feat(server): expand controls list with attachments

models/src/agent_control_models/__init__.py

@@ -84,6 +84,7 @@
     AgentRef,
     AgentSummary,
     ConflictMode,
+    ControlAttachments,
     ControlSummary,
     ControlVersionSummary,
     CreateControlBindingRequest,
@@ -107,9 +108,11 @@
     PatchControlBindingResponse,
     PatchControlRequest,
     PatchControlResponse,
+    PolicyRef,
     RenderControlTemplateRequest,
     RenderControlTemplateResponse,
     StepKey,
+    TargetAttachmentRef,
     UpsertControlBindingRequest,
     UpsertControlBindingResponse,
     ValidateControlDataRequest,
@@ -177,6 +180,7 @@
     "AgentRef",
     "AgentSummary",
     "ConflictMode",
+    "ControlAttachments",
     "ControlVersionSummary",
     "ControlSummary",
     "CreateControlBindingRequest",
@@ -200,9 +204,11 @@
     "PatchControlBindingResponse",
     "PatchControlRequest",
     "PatchControlResponse",
+    "PolicyRef",
     "RenderControlTemplateRequest",
     "RenderControlTemplateResponse",
     "StepKey",
+    "TargetAttachmentRef",
     "UpsertControlBindingRequest",
     "UpsertControlBindingResponse",
     "ValidateControlDataRequest",

models/src/agent_control_models/server.py

@@ -514,6 +514,38 @@ class AgentRef(BaseModel):
     agent_name: str = Field(..., description="Agent name")
 
 
+class PolicyRef(BaseModel):
+    """Reference to a policy attached to a control."""
+
+    policy_id: int = Field(..., description="Policy ID")
+
+
+class TargetAttachmentRef(BaseModel):
+    """Reference to a target binding attached to a control."""
+
+    binding_id: int = Field(..., description="Control binding ID")
+    target_type: str = Field(..., description="Opaque target kind")
+    target_id: str = Field(..., description="Opaque target identifier")
+    enabled: bool = Field(..., description="Whether this target binding is enabled")
+
+
+class ControlAttachments(BaseModel):
+    """Attachments for a listed control."""
+
+    agents: list[AgentRef] = Field(
+        default_factory=list,
+        description="Direct agent associations for this control",
+    )
+    policies: list[PolicyRef] = Field(
+        default_factory=list,
+        description="Policy associations for this control",
+    )
+    targets: list[TargetAttachmentRef] = Field(
+        default_factory=list,
+        description="Target bindings for this control",
+    )
+
+
 class ControlSummary(BaseModel):
     """Summary of a control for list responses."""
 
@@ -542,6 +574,13 @@ class ControlSummary(BaseModel):
     used_by_agents_count: int = Field(
         0, description="Number of unique agents using this control"
     )
+    attachments: ControlAttachments | None = Field(
+        None,
+        description=(
+            "Expanded attachment details. Present when list controls is called "
+            "with include_attachments=true."
+        ),
+    )
 
 
 class ListControlsResponse(BaseModel):
@@ -759,4 +798,3 @@ class DeleteControlBindingByKeyResponse(BaseModel):
             "binding existed."
         ),
     )
-

sdks/typescript/src/generated/funcs/controls-list.ts

@@ -45,6 +45,8 @@ import { Result } from "../types/fp.js";
  *     stage: Optional filter by stage ('pre' or 'post')
  *     execution: Optional filter by execution ('server' or 'sdk')
  *     tag: Optional filter by tag
+ *     include_attachments: Whether to include attachment details for listed controls
+ *     attachment_target_type: Optional target binding type filter for attachments
  *     db: Database session (injected)
  *
  * Returns:
@@ -119,9 +121,11 @@ async function $do(
   const path = pathToFunc("/api/v1/controls")();
 
   const query = encodeFormQuery({
+    "attachment_target_type": payload?.attachment_target_type,
     "cursor": payload?.cursor,
     "enabled": payload?.enabled,
     "execution": payload?.execution,
+    "include_attachments": payload?.include_attachments,
     "limit": payload?.limit,
     "name": payload?.name,
     "stage": payload?.stage,

sdks/typescript/src/generated/models/control-attachments.ts

@@ -0,0 +1,53 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import * as types from "../types/primitives.js";
+import { AgentRef, AgentRef$inboundSchema } from "./agent-ref.js";
+import { SDKValidationError } from "./errors/sdk-validation-error.js";
+import { PolicyRef, PolicyRef$inboundSchema } from "./policy-ref.js";
+import {
+  TargetAttachmentRef,
+  TargetAttachmentRef$inboundSchema,
+} from "./target-attachment-ref.js";
+
+/**
+ * Attachments for a listed control.
+ */
+export type ControlAttachments = {
+  /**
+   * Direct agent associations for this control
+   */
+  agents?: Array<AgentRef> | undefined;
+  /**
+   * Policy associations for this control
+   */
+  policies?: Array<PolicyRef> | undefined;
+  /**
+   * Target bindings for this control
+   */
+  targets?: Array<TargetAttachmentRef> | undefined;
+};
+
+/** @internal */
+export const ControlAttachments$inboundSchema: z.ZodMiniType<
+  ControlAttachments,
+  unknown
+> = z.object({
+  agents: types.optional(z.array(AgentRef$inboundSchema)),
+  policies: types.optional(z.array(PolicyRef$inboundSchema)),
+  targets: types.optional(z.array(TargetAttachmentRef$inboundSchema)),
+});
+
+export function controlAttachmentsFromJSON(
+  jsonString: string,
+): SafeParseResult<ControlAttachments, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => ControlAttachments$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'ControlAttachments' from JSON`,
+  );
+}

sdks/typescript/src/generated/models/control-summary.ts

@@ -8,12 +8,20 @@ import { safeParse } from "../lib/schemas.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import * as types from "../types/primitives.js";
 import { AgentRef, AgentRef$inboundSchema } from "./agent-ref.js";
+import {
+  ControlAttachments,
+  ControlAttachments$inboundSchema,
+} from "./control-attachments.js";
 import { SDKValidationError } from "./errors/sdk-validation-error.js";
 
 /**
  * Summary of a control for list responses.
  */
 export type ControlSummary = {
+  /**
+   * Expanded attachment details. Present when list controls is called with include_attachments=true.
+   */
+  attachments?: ControlAttachments | null | undefined;
   /**
    * Control description
    */
@@ -70,6 +78,7 @@ export const ControlSummary$inboundSchema: z.ZodMiniType<
   unknown
 > = z.pipe(
   z.object({
+    attachments: z.optional(z.nullable(ControlAttachments$inboundSchema)),
     description: z.optional(z.nullable(types.string())),
     enabled: z._default(types.boolean(), true),
     execution: z.optional(z.nullable(types.string())),

sdks/typescript/src/generated/models/index.ts

@@ -17,6 +17,7 @@ export * from "./condition-node-output.js";
 export * from "./config-response.js";
 export * from "./conflict-mode.js";
 export * from "./control-action.js";
+export * from "./control-attachments.js";
 export * from "./control-definition-input.js";
 export * from "./control-definition-output.js";
 export * from "./control-execution-event.js";
@@ -77,6 +78,7 @@ export * from "./patch-control-binding-request.js";
 export * from "./patch-control-binding-response.js";
 export * from "./patch-control-request.js";
 export * from "./patch-control-response.js";
+export * from "./policy-ref.js";
 export * from "./regex-template-parameter.js";
 export * from "./remove-agent-control-response.js";
 export * from "./render-control-template-request.js";
@@ -95,6 +97,7 @@ export * from "./step-schema.js";
 export * from "./step.js";
 export * from "./string-list-template-parameter.js";
 export * from "./string-template-parameter.js";
+export * from "./target-attachment-ref.js";
 export * from "./template-control-input.js";
 export * from "./template-definition-input.js";
 export * from "./template-definition-output.js";

sdks/typescript/src/generated/models/operations/list-controls-api-v1-controls-get.ts

@@ -39,6 +39,14 @@ export type ListControlsApiV1ControlsGetRequest = {
    * Filter by tag
    */
   tag?: string | null | undefined;
+  /**
+   * When true, include direct agent associations, policy associations, and target bindings for each listed control.
+   */
+  includeAttachments?: boolean | undefined;
+  /**
+   * Optional target_type filter applied to expanded target bindings. Only used when include_attachments=true.
+   */
+  attachmentTargetType?: string | null | undefined;
 };
 
 /** @internal */
@@ -52,6 +60,8 @@ export type ListControlsApiV1ControlsGetRequest$Outbound = {
   stage?: string | null | undefined;
   execution?: string | null | undefined;
   tag?: string | null | undefined;
+  include_attachments: boolean;
+  attachment_target_type?: string | null | undefined;
 };
 
 /** @internal */
@@ -69,11 +79,15 @@ export const ListControlsApiV1ControlsGetRequest$outboundSchema: z.ZodMiniType<
     stage: z.optional(z.nullable(z.string())),
     execution: z.optional(z.nullable(z.string())),
     tag: z.optional(z.nullable(z.string())),
+    includeAttachments: z._default(z.boolean(), false),
+    attachmentTargetType: z.optional(z.nullable(z.string())),
   }),
   z.transform((v) => {
     return remap$(v, {
       templateBacked: "template_backed",
       stepType: "step_type",
+      includeAttachments: "include_attachments",
+      attachmentTargetType: "attachment_target_type",
     });
   }),
 );

sdks/typescript/src/generated/models/policy-ref.ts

@@ -0,0 +1,43 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { remap as remap$ } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import * as types from "../types/primitives.js";
+import { SDKValidationError } from "./errors/sdk-validation-error.js";
+
+/**
+ * Reference to a policy attached to a control.
+ */
+export type PolicyRef = {
+  /**
+   * Policy ID
+   */
+  policyId: number;
+};
+
+/** @internal */
+export const PolicyRef$inboundSchema: z.ZodMiniType<PolicyRef, unknown> = z
+  .pipe(
+    z.object({
+      policy_id: types.number(),
+    }),
+    z.transform((v) => {
+      return remap$(v, {
+        "policy_id": "policyId",
+      });
+    }),
+  );
+
+export function policyRefFromJSON(
+  jsonString: string,
+): SafeParseResult<PolicyRef, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => PolicyRef$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'PolicyRef' from JSON`,
+  );
+}

sdks/typescript/src/generated/models/target-attachment-ref.ts

@@ -0,0 +1,62 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v4-mini";
+import { remap as remap$ } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { Result as SafeParseResult } from "../types/fp.js";
+import * as types from "../types/primitives.js";
+import { SDKValidationError } from "./errors/sdk-validation-error.js";
+
+/**
+ * Reference to a target binding attached to a control.
+ */
+export type TargetAttachmentRef = {
+  /**
+   * Control binding ID
+   */
+  bindingId: number;
+  /**
+   * Whether this target binding is enabled
+   */
+  enabled: boolean;
+  /**
+   * Opaque target identifier
+   */
+  targetId: string;
+  /**
+   * Opaque target kind
+   */
+  targetType: string;
+};
+
+/** @internal */
+export const TargetAttachmentRef$inboundSchema: z.ZodMiniType<
+  TargetAttachmentRef,
+  unknown
+> = z.pipe(
+  z.object({
+    binding_id: types.number(),
+    enabled: types.boolean(),
+    target_id: types.string(),
+    target_type: types.string(),
+  }),
+  z.transform((v) => {
+    return remap$(v, {
+      "binding_id": "bindingId",
+      "target_id": "targetId",
+      "target_type": "targetType",
+    });
+  }),
+);
+
+export function targetAttachmentRefFromJSON(
+  jsonString: string,
+): SafeParseResult<TargetAttachmentRef, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => TargetAttachmentRef$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'TargetAttachmentRef' from JSON`,
+  );
+}

sdks/typescript/src/generated/sdk/controls.ts

@@ -55,6 +55,8 @@ export class Controls extends ClientSDK {
    *     stage: Optional filter by stage ('pre' or 'post')
    *     execution: Optional filter by execution ('server' or 'sdk')
    *     tag: Optional filter by tag
+   *     include_attachments: Whether to include attachment details for listed controls
+   *     attachment_target_type: Optional target binding type filter for attachments
    *     db: Database session (injected)
    *
    * Returns: