@parall/sdk 1.54.0 → 1.55.1

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { Label, LabelCreatedData, LabelDeletedData, LabelUpdatedData } from './task-label-types.js';
 export type UserType = 'human' | 'agent';
 export type UserStatus = 'active' | 'disabled';
 export interface User {
@@ -79,6 +80,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;
 }
 export interface UpdateChatMemberRequest {
@@ -373,15 +376,55 @@ export interface UpdateAgentInstructionsRequest {
     instructions: string;
     expected_version: number;
 }
+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;
+}
 export type InvitationStatus = 'pending' | 'accepted' | 'declined' | 'revoked';
 export interface OrgInvitation {
     id: string;
@@ -592,7 +635,20 @@ 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. */
@@ -783,11 +839,6 @@ export interface DirectMessageResponse {
     chat: Chat;
     message: Message;
 }
-export interface JsonPatchOp {
-    op: 'replace' | 'add';
-    path: string;
-    value: unknown;
-}
 export interface CreateAgentRequest {
     display_name: string;
     agent_provider?: string;
@@ -1185,7 +1236,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;
@@ -1209,11 +1261,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 {
     task_id: string;
@@ -1272,13 +1329,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 {
     title?: string;
@@ -1287,7 +1351,6 @@ export interface UpdateTaskRequest {
     priority?: TaskPriority;
     assignee_id?: string | null;
     parent_id?: string | null;
-    project_id?: string | null;
     sort_order?: number;
     /**
      * Ordering intent resolved server-side in the update transaction:
@@ -1304,6 +1367,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
@@ -1322,34 +1390,143 @@ export interface CreateTaskRelationRequest {
     relation_type: TaskRelationType;
 }
 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[];
 }
 export type ScheduleSpecType = 'cron' | 'interval' | 'one_shot';
 export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'cancelled';
@@ -2041,17 +2218,36 @@ export interface MessageNewData {
     hints?: MessageHints | null;
     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;
     version: number;
     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 {
     message_id: string;
@@ -2120,6 +2316,12 @@ export interface OrgMemberRemovedData {
     org_id: string;
     user_id: string;
 }
+/** An org-scoped public member profile changed. */
+export interface OrgMemberProfileUpdatedData {
+    org_id: string;
+    user_id: string;
+    profile_version: number;
+}
 export type TaskActivityAction = 'created' | 'field_changed' | 'commented';
 export interface TaskComment {
     id: string;
@@ -2551,12 +2753,48 @@ export interface SlackChannelsPage {
     channels: SlackChannelInfo[];
     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;
@@ -2911,6 +3149,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;
@@ -2930,6 +3169,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;
@@ -2947,6 +3189,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;
@@ -3937,6 +4180,51 @@ export interface SetEdgeProfileProxyRequest {
     username?: string;
     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;
@@ -3958,7 +4246,17 @@ 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
  * OAuth flow reads back as `oauth`, so every reader must handle it even
@@ -4025,12 +4323,15 @@ export interface MCPToolInfo {
  * document, `dcr` = RFC 7591 dynamic registration.
  */
 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
@@ -4056,6 +4357,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`.
@@ -4070,9 +4374,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[];
 }
 /**
  * POST body of `…/clip-registry/{clipId}/mcp-configs` — a NEW connection
@@ -4090,6 +4405,8 @@ export interface MCPConfigCreateRequest {
     server_url?: string;
     auth_type: MCPAuthType | 'oauth';
     credential?: string;
+    /** See MCPConfigPutRequest.credentials. */
+    credentials?: string[];
     alias?: string;
     oauth_client?: MCPOAuthClientParams;
 }
@@ -4123,8 +4440,17 @@ 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
@@ -4183,13 +4509,32 @@ export interface PublishRegistryClipRequest {
     /** filename → UTF-8 content (e.g. `search.js`). */
     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
@@ -4197,8 +4542,23 @@ 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[];
 }
 /**
  * Execute a registry (Edge) clip command on an Edge device
@@ -4212,6 +4572,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 {
     /**