@parall/sdk 1.54.0 → 1.55.1

package/src/types.ts

@@ -1,3 +1,10 @@
+import type {
+  Label,
+  LabelCreatedData,
+  LabelDeletedData,
+  LabelUpdatedData,
+} from './task-label-types.js';
+
 // ============================================================
 // Entity Types — mirror server data model
 // ============================================================
@@ -94,6 +101,8 @@ export interface ChatMember {
   pinned: boolean;
   hidden: boolean;
   joined_at: string;
+  /** Org-scoped public title. Omitted by older servers and for former DM peers. */
+  title?: string;
   user?: User;
 }
 
@@ -477,17 +486,64 @@ export interface UpdateAgentInstructionsRequest {
   expected_version: number;
 }
 
-// Team — a named group of org members, referenced in wiki ACLs as `@slug`.
+// Team — a named group of org members, referenced in ACL rosters by its ID.
+export type TeamRole = 'member' | 'manager';
+
 export interface Team {
   id: string;
   org_id: string;
   name: string;
-  slug: string;
+  /** @deprecated Removed since migration 176 — teams have no slug anymore. */
+  slug?: string;
   created_by: string;
   created_at: string;
   updated_at: string;
 }
 
+/**
+ * Display fields a roster listing carries for each member. The server projects
+ * only these columns, so this is deliberately narrower than `User`: no email,
+ * phone, or last_seen_at reaches a roster response.
+ *
+ * `avatar_url` is optional rather than nullable because the server omits the
+ * field when unset.
+ */
+export interface RosterUser {
+  id: string;
+  type: UserType;
+  display_name: string;
+  avatar_url?: string;
+  status: UserStatus;
+}
+
+export interface TeamMember {
+  team_id: string;
+  user_id: string;
+  role: TeamRole;
+  added_by: string;
+  added_at: string;
+  user?: RosterUser;
+}
+
+export interface CreateTeamRequest {
+  name: string;
+  /** @deprecated Accepted and ignored by the server since migration 176. */
+  slug?: string;
+}
+
+export interface UpdateTeamRequest {
+  name: string;
+}
+
+export interface AddTeamMemberRequest {
+  user_id: string;
+  role?: TeamRole;
+}
+
+export interface UpdateTeamMemberRequest {
+  role: TeamRole;
+}
+
 // Invitation
 
 export type InvitationStatus = 'pending' | 'accepted' | 'declined' | 'revoked';
@@ -751,8 +807,23 @@ export interface DeployTemplateRequest {
   /** Hire-time per-agent adjustments (onboarding wizard S2). Keys are the
    *  template's agent keys; omitted agents keep template defaults. */
   agent_overrides?: Record<string, DeployAgentOverride>;
+  /** Explicit onboarding S4 intent. Each ref must be an effective dependency
+   * of this team whose selected_agents restriction was established in S3.
+   * Deploy additively grants only the newly-created Agents that declare it. */
+  dependency_access_refs?: string[];
 }
 
+export interface TemplateDeploymentStatus {
+  deployment_id: string;
+  status: 'queued' | 'deploying' | 'failed';
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+
+export type TemplateDeploymentResult = TemplateDeploymentReport | TemplateDeploymentStatus;
+
 /** Per-agent hire-time override. Substitutes values within the platform-legal
  *  surface; never adds capability. Dependencies may only disable (false)
  *  declared optional deps — required deps and undeclared refs are rejected. */
@@ -957,12 +1028,6 @@ export interface DirectMessageResponse {
   message: Message;
 }
 
-export interface JsonPatchOp {
-  op: 'replace' | 'add';
-  path: string;
-  value: unknown;
-}
-
 export interface CreateAgentRequest {
   display_name: string;
   agent_provider?: string;
@@ -1488,7 +1553,8 @@ export interface Task {
   assignee_id: string | null;
   creator_id: string;
   parent_id: string | null;
-  project_id: string | null;
+  /** Every Task belongs to exactly one Project; immutable after creation. */
+  project_id: string;
   seq_number: number | null;
   identifier: string | null;
   sort_order: number;
@@ -1512,11 +1578,16 @@ export interface Task {
   deleted_at?: string | null;
   /**
    * Per-viewer: whether the requesting user may manage OTHER members' comment
-   * subscriptions for this task (creator / assignee / project lead / org
+   * subscriptions for this task (creator / assignee / project manager / org
    * owner-admin). Populated on single-task GET; undefined elsewhere. Read this to
    * gate subscriber-management UI — do not re-derive the rule client-side.
    */
   can_manage_subscribers?: boolean;
+  /**
+   * Always present on label-aware HTTP/WS responses. Optional here only so
+   * persisted Task rows from older clients can be read during migration.
+   */
+  labels?: Label[];
 }
 
 export interface TaskWatcher {
@@ -1583,13 +1654,20 @@ export interface CreateTaskRequest {
   priority?: TaskPriority;
   assignee_id?: string;
   parent_id?: string;
-  project_id?: string;
+  /**
+   * Required: every Task is created inside a Project (missing → 400
+   * MISSING_FIELDS with `error.details.available_projects`; archived project →
+   * 400 PROJECT_ARCHIVED). A parent task's subtasks must use the parent's
+   * project (400 INVALID_PARENT otherwise). Immutable after creation.
+   */
+  project_id: string;
   source_chat_id?: string;
   sort_order?: number;
   /** Planned start date, YYYY-MM-DD. Must be <= due_date when both are set. */
   planned_start_date?: string;
   /** Planned completion date, YYYY-MM-DD. */
   due_date?: string;
+  label_ids?: string[];
 }
 
 export interface UpdateTaskRequest {
@@ -1599,7 +1677,9 @@ export interface UpdateTaskRequest {
   priority?: TaskPriority;
   assignee_id?: string | null;
   parent_id?: string | null;
-  project_id?: string | null;
+  // project_id is deliberately absent: a Task's Project is immutable after
+  // creation (server answers 400 PROJECT_IMMUTABLE; resubmitting the current
+  // value is an idempotent no-op).
   sort_order?: number;
   /**
    * Ordering intent resolved server-side in the update transaction:
@@ -1616,6 +1696,11 @@ export interface UpdateTaskRequest {
   planned_start_date?: string | null;
   /** Planned completion date, YYYY-MM-DD; explicit null clears it. */
   due_date?: string | null;
+  /**
+   * Full-set replacement: absent leaves labels unchanged; [] or null clears.
+   * Concurrent writers should prefer addTaskLabels/removeTaskLabel.
+   */
+  label_ids?: string[] | null;
   /**
    * Dispatch lane binding (agent senders during a typed dispatch turn).
    * dispatch_lane + dispatch_event_id bind the update to the claimed typed
@@ -1641,36 +1726,157 @@ export interface CreateTaskRelationRequest {
 
 export type ProjectStatus = 'active' | 'paused' | 'completed' | 'archived';
 
+/** Visibility only decides how someone becomes a member (self-join /
+ * request+approval / invite-only); membership rights are identical on every
+ * tier, and reads are always roster-scoped. */
+export type ProjectVisibility = 'public' | 'restricted' | 'private';
+
+/** A role held on a project roster. Managers administer the project; members
+ * only reach it. Org owners and admins are implicit managers everywhere, which
+ * is why a project can never become unmanageable. */
+export type ProjectRole = 'member' | 'manager';
+
 export interface Project {
   id: string;
   org_id: string;
   name: string;
   key: string;
   description: string | null;
-  lead_id: string | null;
   status: ProjectStatus;
+  visibility: ProjectVisibility;
   color: string | null;
   sort_order: number;
   created_at: string;
   updated_at: string;
+  /** The requesting user's own role, computed per request rather than stored.
+   * Absent means they hold no membership (direct or team-derived). */
+  my_role?: ProjectRole;
+  /** True when the requesting user holds their own roster row — the fact
+   * Leave acts on, as opposed to team-derived or org-admin standing. */
+  my_direct_member?: boolean;
+  /**
+   * @deprecated Project authority now comes from the project roster. Retained
+   * only for source compatibility during the pre-GA migration window; current
+   * API responses omit it.
+   */
+  lead_id?: string | null;
+}
+
+/** One join-library row: the minimal metadata a non-member may see about a
+ * discoverable project, plus the caller's own admission state. */
+export interface ProjectLibraryEntry {
+  id: string;
+  name: string;
+  key: string;
+  color?: string | null;
+  visibility: ProjectVisibility;
+  joined: boolean;
+  requested: boolean;
+}
+
+/** One pending join request, as the Collaborators pending tab renders it. */
+export interface ProjectJoinRequest {
+  id: string;
+  requester_id: string;
+  created_at: string;
+  requester?: User;
+}
+
+/** One roster entry. `subject` is a bare user ID or a bare team ID; exactly one
+ * of `user` / `team` is filled in for display, according to which kind it is. */
+export interface ProjectMember {
+  project_id: string;
+  subject: string;
+  role: ProjectRole;
+  added_by?: string;
+  added_at: string;
+  user?: User;
+  team?: Team;
+}
+
+/**
+ * Adds one subject to a project's roster. Create-only: an existing row answers
+ * `409 MEMBER_EXISTS` rather than being mutated — role changes go through the
+ * member role endpoint. A subject naming nobody reachable answers
+ * `400 UNKNOWN_SUBJECT`. Member rows are storable on every tier.
+ */
+export interface AddProjectMemberRequest {
+  /** A bare user ID, or a bare team ID (`team_...`) for a team. */
+  subject: string;
+  /** Defaults to `member` when omitted. */
+  role?: ProjectRole;
+}
+
+/**
+ * Changes one roster entry's role. Demoting the last manager answers
+ * `400 LAST_MANAGER`; a concurrent roster change answers `409 CONFLICT`.
+ */
+export interface UpdateProjectMemberRequest {
+  role: ProjectRole;
 }
 
 export interface CreateProjectRequest {
   name: string;
   key?: string;
   description?: string;
-  lead_id?: string;
+  /** Defaults to `public` when omitted. The creator is always written as the
+   * first manager, which is what naming yourself lead used to mean. */
+  visibility?: ProjectVisibility;
   color?: string;
+  /**
+   * @deprecated Use the project roster after creation. Retained only for
+   * source compatibility; the current API ignores this retired field.
+   */
+  lead_id?: string;
 }
 
 export interface UpdateProjectRequest {
   name?: string;
   key?: string;
   description?: string | null;
-  lead_id?: string | null;
   status?: ProjectStatus;
+  visibility?: ProjectVisibility;
   color?: string | null;
   sort_order?: number;
+  /**
+   * @deprecated Use the project roster. Retained only for source
+   * compatibility; the current API ignores this retired field.
+   */
+  lead_id?: string | null;
+}
+
+export interface ProjectTaskStatusCounts {
+  todo: number;
+  in_progress: number;
+  in_review: number;
+  done: number;
+  canceled: number;
+}
+
+export interface ProjectTaskSummary {
+  project_id: string;
+  status_counts: ProjectTaskStatusCounts;
+  completed_series: number[];
+}
+
+export interface ProjectTaskSummaryResponse {
+  workspace_counts: {
+    all_issues: number;
+    my_issues: number;
+    no_project: number;
+    my_status_counts: ProjectTaskStatusCounts;
+  };
+  projects: ProjectTaskSummary[];
+}
+
+export interface TaskSubtaskSummary {
+  task_id: string;
+  total: number;
+  done: number;
+}
+
+export interface TaskSubtaskSummaryResponse {
+  data: TaskSubtaskSummary[];
 }
 
 // ============================================================
@@ -2507,6 +2713,17 @@ export interface MessageNewData {
   attachments?: Attachment[];
 }
 
+/** @deprecated The `message.patch` event is retired — the server no longer
+ * publishes it (content updates arrive as full-content `message.edit`). Kept
+ * only so existing consumers keep compiling through the deprecation window;
+ * a handler typed with this will never fire. */
+export interface JsonPatchOp {
+  op: 'replace' | 'add';
+  path: string;
+  value: unknown;
+}
+
+/** @deprecated See {@link JsonPatchOp} — `message.patch` is never published. */
 export interface MessagePatchData {
   message_id: string;
   chat_id: string;
@@ -2514,11 +2731,20 @@ export interface MessagePatchData {
   ops: JsonPatchOp[];
 }
 
+/**
+ * Unified message-content-update event: every persisted content write (author
+ * edit, server link-preview write-back) publishes it with the full content and
+ * post-write version. Apply only when `version` is greater than the local one;
+ * the "(edited)" marker keys off `edited_at` alone — a preview write-back
+ * never creates or changes edited state (it carries the pre-existing value,
+ * absent when the message was never author-edited).
+ */
 export interface MessageEditData {
   message_id: string;
   chat_id: string;
   content: MessageContent;
-  edited_at: string;
+  version: number;
+  edited_at?: string;
 }
 
 export interface MessageDeleteData {
@@ -2616,6 +2842,13 @@ export interface OrgMemberRemovedData {
   user_id: string;
 }
 
+/** An org-scoped public member profile changed. */
+export interface OrgMemberProfileUpdatedData {
+  org_id: string;
+  user_id: string;
+  profile_version: number;
+}
+
 // ---- Task Comment & Activity Types ----
 
 export type TaskActivityAction = 'created' | 'field_changed' | 'commented';
@@ -3121,13 +3354,53 @@ export interface SlackChannelsPage {
   next_cursor?: string;
 }
 
-/** WeChat address book (id lists only — the vendor returns no names). */
+/** One WeChat friend resolved with its display name. */
+export interface WechatContactName {
+  wxid: string;
+  nick_name?: string;
+  remark?: string;
+  alias?: string;
+  /** The label the WeChat app would show: remark > nickName > alias > wxid. */
+  display: string;
+}
+
+/** One WeChat saved chatroom with its display name. */
+export interface WechatChatroomEntry {
+  chatroom_id: string;
+  nick_name?: string;
+  remark?: string;
+  display: string;
+}
+
+/**
+ * WeChat address book — the vendor's id-only lists enriched with display
+ * names (getBriefInfo for friends, getChatroomInfo per chatroom). System
+ * ids (weixin/fmessage/medianote) are filtered out.
+ */
 export interface WechatContactsPage {
-  friends: string[];
-  chatrooms: string[];
+  friends: WechatContactName[];
+  chatrooms: WechatChatroomEntry[];
   ghs: string[];
 }
 
+/** The connected WeChat account's identity (getProfile + stored app id). */
+export interface WechatProfileView {
+  wxid: string;
+  alias?: string;
+  nick_name?: string;
+  app_id: string;
+}
+
+/** WeChat connection health: live online probe + identity + offline record. */
+export interface WechatStatusView {
+  online: boolean;
+  wxid: string;
+  alias?: string;
+  nick_name?: string;
+  app_id: string;
+  last_offline_at?: string;
+}
+
 export interface SlackUserInfo {
   id: string;
   name: string;
@@ -3537,6 +3810,7 @@ export interface NotificationAlertData {
 export type WsEventMap = {
   hello: HelloData;
   'message.new': MessageNewData;
+  /** @deprecated Never published anymore — kept so existing `ws.on('message.patch', …)` registrations keep compiling. */
   'message.patch': MessagePatchData;
   'message.edit': MessageEditData;
   'message.delete': MessageDeleteData;
@@ -3554,6 +3828,9 @@ export type WsEventMap = {
   'task.created': TaskCreatedData;
   'task.updated': TaskUpdatedData;
   'task.deleted': TaskDeletedData;
+  'label.created': LabelCreatedData;
+  'label.updated': LabelUpdatedData;
+  'label.deleted': LabelDeletedData;
   'task.assigned': TaskAssignedData;
   'task.comment.created': TaskCommentCreatedData;
   'task.comment.updated': TaskCommentUpdatedData;
@@ -3571,6 +3848,7 @@ export type WsEventMap = {
   'org.join_request.new': OrgJoinRequestNewEventData;
   'org.invite_link.joined': OrgInviteLinkJoinedEventData;
   'org.member.removed': OrgMemberRemovedData;
+  'org.member.profile.updated': OrgMemberProfileUpdatedData;
   'agent_config.update': AgentConfigUpdateData;
   'presence.update': PresenceUpdateData;
   'wiki.changeset.created': WikiChangesetCreatedData;
@@ -4727,6 +5005,54 @@ export interface SetEdgeProfileProxyRequest {
   password?: string;
 }
 
+/**
+ * One normalized cookie in a hosted-profile cookie-seed import — the exact shape
+ * the pod-side `session.cookies.set()` consumes (mirrors the desktop
+ * cookie-import output). Web parses the manager's paste (a raw `Cookie` header +
+ * target domain, or a Cookie-Editor JSON export) into an array of these before
+ * the PUT. Values are write-only; the sanitized status never echoes them.
+ */
+export interface EdgeCookie {
+  url: string;
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  secure: boolean;
+  httpOnly: boolean;
+  /** Unix epoch seconds; null for a session cookie (no persisted expiry). */
+  expirationDate: number | null;
+  sameSite: 'no_restriction' | 'lax' | 'strict' | null;
+}
+
+/**
+ * PUT body for a hosted profile's one-shot cookie seed: the full normalized
+ * cookie array. Injected at the next cold start and consumed once. Clearing is
+ * DELETE, never an empty PUT.
+ */
+export interface SetEdgeCookieSeedRequest {
+  cookies: EdgeCookie[];
+}
+
+/**
+ * Sanitized cookie-seed status (hosted Cloud Profiles) — the GET response and
+ * the PUT/DELETE result. NEVER carries cookie values: only the count and the
+ * distinct target domains are exposed.
+ */
+export interface EdgeCookieSeedStatus {
+  configured: boolean;
+  cookie_count: number;
+  domains: string[];
+  /** Opaque compare-and-swap token for conditional PUT/DELETE (`cookieseed-<version>` ETag). */
+  version: string;
+  /** Authoritative mutation gate; false whenever a non-released lease exists. */
+  can_mutate: boolean;
+  /** Actual lease state blocking a mutation (never inferred from device status). */
+  lease_status?: 'pending' | 'assigned' | 'active' | 'releasing' | 'repair';
+  /** Suggested delay before re-reading authoritative state. */
+  retry_after_seconds?: number | null;
+}
+
 export interface ClipConnection {
   id: string;
   clip_id: string;
@@ -4749,7 +5075,18 @@ export interface ClipConnection {
  * would make `putClipMCPConfig({auth_type: 'oauth'})` type-legal while its
  * declared return type is wrong. Reads use MCPConfigAuthType.
  */
-export type MCPAuthType = 'none' | 'bearer' | 'api_key';
+export type MCPAuthType = 'none' | 'bearer' | 'api_key' | 'basic';
+
+/**
+ * One declared credential input of an `api_key` clip (manifest
+ * `mcp.auth_headers`): the header the value is delivered in and, for
+ * `Authorization`, the `Bearer` scheme prefix. `bearer` remains the legacy
+ * alias for the single `Authorization: Bearer` shape.
+ */
+export interface MCPAuthHeaderSlot {
+  name: string;
+  scheme?: 'Bearer';
+}
 
 /**
  * MCP clip auth modes a config can REPORT. A config authorized through the
@@ -4824,12 +5161,16 @@ export interface MCPToolInfo {
  */
 export type MCPClientMode = 'preregistered' | 'cimd' | 'dcr';
 
+/** Where the OAuth client identity is owned. `platform` references a
+ * deployment App; its shared secret is never copied into the org grant. */
+export type MCPOAuthClientSource = 'embedded' | 'platform';
+
 /**
  * Redacted MCP server config of an MCP clip
  * (`GET /orgs/{orgId}/clip-registry/{clipId}/mcp-config` — the org's DEFAULT
  * connection — or `GET …/mcp-configs/{configId}`). The whole mcp-config
- * family is publisher-org only: cross-org installs get
- * `403 MCP_CROSS_ORG_DISABLED`, reads included. The stored credential NEVER
+ * family also accepts an installed reviewed Official OAuth Clip across orgs;
+ * every other cross-org Clip gets `403 MCP_CROSS_ORG_DISABLED`. The stored credential NEVER
  * appears in any response — `credential_set` is the only credential fact.
  *
  * Multi-connection model: a clip holds one config row (credential slot) PER
@@ -4855,6 +5196,9 @@ export interface MCPConfigResponse {
   /** Present while an oauth config holds a stored client identity
    *  (connected or needs_reauth); absent once disconnected. */
   client_mode?: MCPClientMode;
+  client_source?: MCPOAuthClientSource;
+  /** True only when this grant uses the reviewed platform-owned OAuth App. */
+  official_oauth?: boolean;
   /**
    * Opaque CAS token for If-Match on PUT/DELETE (lost-update protection).
    * Version mismatch answers `409 MCP_CONFIG_STALE`.
@@ -4870,9 +5214,20 @@ export interface MCPConfigResponse {
  * persists nothing.
  */
 export interface MCPConfigPutRequest {
+  /**
+   * Required on the wire, but when the clip's manifest declares the server
+   * an empty string means "use the declaration" — the server fills it in and
+   * refuses a contradicting value. (The Console sends '' for declared clips.)
+   */
   server_url: string;
   auth_type: MCPAuthType;
   credential?: string;
+  /**
+   * Slot-aligned multi-value form: one value per declared `auth_headers`
+   * slot, or `[username, password]` for `basic`. Mutually exclusive with
+   * `credential`.
+   */
+  credentials?: string[];
 }
 
 /**
@@ -4891,6 +5246,8 @@ export interface MCPConfigCreateRequest {
   server_url?: string;
   auth_type: MCPAuthType | 'oauth';
   credential?: string;
+  /** See MCPConfigPutRequest.credentials. */
+  credentials?: string[];
   alias?: string;
   oauth_client?: MCPOAuthClientParams;
 }
@@ -4926,9 +5283,19 @@ export interface MCPConnectionSummary {
   tools_refreshed_at?: string;
   oauth_status?: MCPOAuthStatus;
   client_mode?: MCPClientMode;
+  client_source?: MCPOAuthClientSource;
+  official_oauth?: boolean;
   version: string;
 }
 
+/** Result of the server-orchestrated Official MCP Clip removal. Local rows
+ * are always removed on success; `revoked: false` warns that the provider may
+ * still hold a grant requiring manual cleanup. */
+export interface MCPOfficialClipRemovalResponse {
+  removed: boolean;
+  revoked: boolean;
+}
+
 /**
  * PATCH body of `/clip-connections/{connId}` (MCP connections only, human
  * org-admin JWT): rename the slot and/or promote it to the org default
@@ -4991,13 +5358,33 @@ export interface PublishRegistryClipRequest {
   files: Record<string, string>;
 }
 
+/**
+ * One granted agent's entry under `selected_agents` (ADR-019).
+ *
+ * - `connection_scope: 'all'` — the grant covers every connection of the clip
+ *   (what a legacy `agent_ids` write means). `connection_ids` must be [].
+ * - `connection_scope: 'selected'` — the grant admits only the connections in
+ *   `connection_ids` (non-empty on write; a grant can still READ back with []
+ *   when its granted connections were deleted, and then admits nothing).
+ */
+export interface ClipAgentExecGrant {
+  agent_id: string;
+  connection_scope: 'all' | 'selected';
+  /** Granted connection ids (`ccn_…`) under `selected`, sorted; [] under `all`. */
+  connection_ids: string[];
+}
+
 /**
  * A clip's per-org agent exec access (`GET/PUT /orgs/{orgId}/clips/{clipId}/exec-access`).
  *
  * - `all_agents` (default): every org agent may exec the clip.
- * - `selected_agents`: only the agents in `agent_ids` may exec; an empty list
- *   blocks every agent. Denied agents also stop seeing the clip in
- *   `clips/installed`, and exec answers `403 CLIP_AGENT_NOT_ALLOWED`.
+ * - `selected_agents`: only the agents in `grants` may exec, each through the
+ *   connections its `connection_scope` admits; an empty list blocks every
+ *   agent. Denied agents also stop seeing the clip in `clips/installed`; exec
+ *   answers `403 CLIP_AGENT_NOT_ALLOWED` (no grant at all) or
+ *   `403 CLIP_AGENT_CONNECTION_NOT_ALLOWED` (grant does not cover the named
+ *   connection). Agents must always exec through a connection — a
+ *   connectionless agent exec answers `400 AGENT_CONNECTION_REQUIRED`.
  *
  * Decided by the CALLING org (an installer restricts its own agents, never the
  * publisher's). Humans are never restricted; the PUT is human-only (an agent
@@ -5005,8 +5392,24 @@ export interface PublishRegistryClipRequest {
  */
 export interface ClipAgentExecAccess {
   mode: 'all_agents' | 'selected_agents';
-  /** Granted agent user ids under `selected_agents`; always [] under `all_agents`. */
+  /**
+   * Granted agent user ids under `selected_agents` — the flat projection of
+   * `grants`, kept for older readers; always [] under `all_agents`.
+   */
   agent_ids: string[];
+  /** Per-agent connection scope under `selected_agents`, sorted by agent id. */
+  grants: ClipAgentExecGrant[];
+}
+
+/**
+ * The PUT body for a clip's agent exec access. Two shapes, one semantic
+ * space — pass EITHER `agent_ids` (legacy flat form; every listed agent gets
+ * `connection_scope: 'all'`) OR `grants` (connection-scoped form), never both.
+ */
+export interface ClipAgentExecAccessUpdate {
+  mode: 'all_agents' | 'selected_agents';
+  agent_ids?: string[];
+  grants?: ClipAgentExecGrant[];
 }
 
 /**
@@ -5021,6 +5424,10 @@ export interface ClipAgentExecAccess {
  *   here is refused (`400 HOSTED_CONNECTION_REQUIRED`).
  * - neither: legacy BYOC fallback — resolves only to the caller's OWN online
  *   desktop device, never to a hosted one.
+ *
+ * AGENT principals must always pass `connection` (ADR-019): the device paths
+ * answer `400 AGENT_CONNECTION_REQUIRED`, and a connection outside the agent's
+ * granted scope answers `403 CLIP_AGENT_CONNECTION_NOT_ALLOWED`.
  */
 export interface ExecEdgeClipRequest {
   /**