@parall/sdk 1.55.0 → 1.55.2

package/dist/project-task-client.js

@@ -114,4 +114,60 @@ export class ProjectTaskClient {
     async deleteProject(orgId, projectId) {
         return this.request('DELETE', ENDPOINTS.PROJECT(orgId, projectId));
     }
+    /** Roster with display info; readable by anyone who can read the project. */
+    async getProjectMembers(orgId, projectId) {
+        const res = await this.request('GET', ENDPOINTS.PROJECT_MEMBERS(orgId, projectId));
+        return res.data;
+    }
+    /**
+     * User IDs who may read the project — the assignee-eligibility set. Every
+     * tier answers the roster expansion (direct, team-reached, org
+     * owners/admins); visibility only shapes admission, never reach.
+     */
+    async getProjectReaders(orgId, projectId) {
+        const res = await this.request('GET', ENDPOINTS.PROJECT_READERS(orgId, projectId));
+        return res.data;
+    }
+    /** The join library: every discoverable project (public + restricted, plus
+     * private for org owners/admins) with the caller's admission state. */
+    async getProjectLibrary(orgId) {
+        const res = await this.request('GET', ENDPOINTS.PROJECT_LIBRARY(orgId));
+        return res.data;
+    }
+    /** Public-tier self-admission: writes the caller's own member row.
+     * Other tiers answer `404 PROJECT_NOT_FOUND`; a duplicate answers
+     * `409 MEMBER_EXISTS`. */
+    async joinProject(orgId, projectId) {
+        return this.request('POST', ENDPOINTS.PROJECT_JOIN(orgId, projectId));
+    }
+    /** Restricted-tier admission petition. A pending duplicate answers
+     * `409 REQUEST_EXISTS`; membership answers `409 MEMBER_EXISTS`. */
+    async createProjectJoinRequest(orgId, projectId) {
+        return this.request('POST', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+    }
+    /** Pending petitions for one project — manager standing required. */
+    async listProjectJoinRequests(orgId, projectId) {
+        const res = await this.request('GET', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+        return res.data;
+    }
+    /** Withdraws the caller's own pending petition. */
+    async cancelProjectJoinRequest(orgId, projectId) {
+        return this.request('DELETE', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+    }
+    /**
+     * Adds one subject (user ID or team ID) to the roster. Manager-only,
+     * create-only: an existing row answers `409 MEMBER_EXISTS` — change roles
+     * through updateProjectMember instead.
+     */
+    async addProjectMember(orgId, projectId, req) {
+        return this.request('POST', ENDPOINTS.PROJECT_MEMBERS(orgId, projectId), req);
+    }
+    /** Sets one roster entry's role. Demoting the last manager answers `400 LAST_MANAGER`. */
+    async updateProjectMember(orgId, projectId, subject, req) {
+        return this.request('PATCH', ENDPOINTS.PROJECT_MEMBER(orgId, projectId, subject), req);
+    }
+    /** Removes one roster entry. Removing the last manager answers `400 LAST_MANAGER`. */
+    async removeProjectMember(orgId, projectId, subject) {
+        return this.request('DELETE', ENDPOINTS.PROJECT_MEMBER(orgId, projectId, subject));
+    }
 }

package/dist/subject.d.ts

@@ -2,11 +2,10 @@
 export type SubjectKind = 'wildcard' | 'user' | 'team';
 export interface ParsedSubject {
     kind: SubjectKind;
-    /** Empty for wildcard, user ID for user, and slug without `@` for team. */
+    /** Empty for wildcard, user ID for user, and the full team ID for team. */
     value: string;
 }
-export declare function isValidTeamSlug(slug: string): boolean;
-export declare function formatTeamSubject(slug: string): string;
+export declare function isTeamSubject(token: string): boolean;
 export declare function parseSubjectToken(token: string): ParsedSubject;
 /**
  * Maximum distinct team references one ACL row may carry. Mirrors
@@ -14,12 +13,10 @@ export declare function parseSubjectToken(token: string): ParsedSubject;
  */
 export declare const MAX_TEAM_SUBJECTS_PER_WRITE = 200;
 /**
- * Returns unique team slugs in first-seen order for batched write validation.
- *
- * Syntactically invalid slugs are included rather than skipped, matching the
- * server's `subject.TeamSlugs`: a mistyped `@Finance` must reach the existence
- * check and be reported missing, so the write fails with a legible error
- * instead of storing a token that matches nobody.
+ * Returns unique team IDs in first-seen order for batched write validation.
+ * An ID that names no team comes back from the server's existence check
+ * reported missing, so the write fails with a legible error instead of
+ * storing a token that matches nobody.
  */
-export declare function teamSlugsFromSubjects(subjects: readonly string[]): string[];
+export declare function teamIdsFromSubjects(subjects: readonly string[]): string[];
 //# sourceMappingURL=subject.d.ts.map

package/dist/subject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../src/subject.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAe9D;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAW3E"}
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../src/subject.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAW9D;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CASzE"}

package/dist/subject.js

@@ -1,28 +1,24 @@
 /** Shared ACL subject token helpers for clients that edit permission rosters. */
-const TEAM_SLUG = /^[a-z0-9][a-z0-9-]*$/;
-export function isValidTeamSlug(slug) {
-    return TEAM_SLUG.test(slug);
-}
-export function formatTeamSubject(slug) {
-    if (!isValidTeamSlug(slug)) {
-        throw new Error(`Invalid team slug: ${slug}`);
-    }
-    return `@${slug}`;
+/**
+ * Team subjects are stored as bare team IDs (`team_...`), mirroring the
+ * server's `pkg/subject`: the ID prefix is what makes a token a team
+ * reference, so no marker syntax exists and a rename never invalidates a
+ * stored reference.
+ */
+const TEAM_ID_PREFIX = 'team_';
+export function isTeamSubject(token) {
+    return token.startsWith(TEAM_ID_PREFIX);
 }
 export function parseSubjectToken(token) {
     if (token === '*') {
         return { kind: 'wildcard', value: '' };
     }
-    if (token.startsWith('@')) {
-        const slug = token.slice(1);
-        if (!isValidTeamSlug(slug)) {
-            throw new Error(`Invalid team subject: ${token}`);
-        }
-        return { kind: 'team', value: slug };
-    }
     if (!token) {
         throw new Error('Subject token is empty');
     }
+    if (isTeamSubject(token)) {
+        return { kind: 'team', value: token };
+    }
     return { kind: 'user', value: token };
 }
 /**
@@ -31,24 +27,19 @@ export function parseSubjectToken(token) {
  */
 export const MAX_TEAM_SUBJECTS_PER_WRITE = 200;
 /**
- * Returns unique team slugs in first-seen order for batched write validation.
- *
- * Syntactically invalid slugs are included rather than skipped, matching the
- * server's `subject.TeamSlugs`: a mistyped `@Finance` must reach the existence
- * check and be reported missing, so the write fails with a legible error
- * instead of storing a token that matches nobody.
+ * Returns unique team IDs in first-seen order for batched write validation.
+ * An ID that names no team comes back from the server's existence check
+ * reported missing, so the write fails with a legible error instead of
+ * storing a token that matches nobody.
  */
-export function teamSlugsFromSubjects(subjects) {
+export function teamIdsFromSubjects(subjects) {
     const seen = new Set();
-    const slugs = [];
+    const ids = [];
     for (const token of subjects) {
-        if (!token.startsWith('@'))
-            continue;
-        const slug = token.slice(1);
-        if (!slug || seen.has(slug))
+        if (!isTeamSubject(token) || seen.has(token))
             continue;
-        seen.add(slug);
-        slugs.push(slug);
+        seen.add(token);
+        ids.push(token);
     }
-    return slugs;
+    return ids;
 }

package/dist/types.d.ts

@@ -381,7 +381,8 @@ 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;
@@ -411,12 +412,11 @@ export interface TeamMember {
 }
 export interface CreateTeamRequest {
     name: string;
-    slug: string;
+    /** @deprecated Accepted and ignored by the server since migration 176. */
+    slug?: string;
 }
 export interface UpdateTeamRequest {
     name: string;
-    /** Team slugs are immutable because wiki ACL rows store them as @slug. */
-    slug?: never;
 }
 export interface AddTeamMemberRequest {
     user_id: string;
@@ -839,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;
@@ -1241,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;
@@ -1265,7 +1261,7 @@ 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.
      */
@@ -1333,7 +1329,13 @@ 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. */
@@ -1349,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:
@@ -1389,34 +1390,114 @@ 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;
@@ -2137,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;
@@ -3049,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;
@@ -3220,6 +3321,8 @@ export interface ResolvedRef {
     message_type?: string;
     created_at?: string;
     attachments?: Attachment[];
+    quoted_text?: string;
+    quote_from_edited?: boolean;
     range_messages?: Array<{
         id: string;
         sender_id: string;
@@ -4079,6 +4182,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;
@@ -4100,7 +4248,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
@@ -4218,9 +4376,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
@@ -4238,6 +4407,8 @@ export interface MCPConfigCreateRequest {
     server_url?: string;
     auth_type: MCPAuthType | 'oauth';
     credential?: string;
+    /** See MCPConfigPutRequest.credentials. */
+    credentials?: string[];
     alias?: string;
     oauth_client?: MCPOAuthClientParams;
 }
@@ -4340,13 +4511,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
@@ -4354,8 +4544,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
@@ -4369,6 +4574,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 {
     /**