@parall/sdk 1.55.0 → 1.55.2

package/src/constants.ts

@@ -604,6 +604,18 @@ export const ENDPOINTS = {
   PROJECTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects`,
   PROJECT_TASK_SUMMARY: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects/task-summary`,
   PROJECT: (orgId: string, projectId: string) => `${API_BASE}/orgs/${orgId}/projects/${projectId}`,
+  PROJECT_MEMBERS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/members`,
+  PROJECT_READERS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/readers`,
+  PROJECT_LIBRARY: (orgId: string) => `${API_BASE}/orgs/${orgId}/projects/library`,
+  PROJECT_JOIN: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/join`,
+  PROJECT_JOIN_REQUESTS: (orgId: string, projectId: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/join-requests`,
+  // subject is a bare user ID or a bare team ID; both are path-segment safe.
+  PROJECT_MEMBER: (orgId: string, projectId: string, subject: string) =>
+    `${API_BASE}/orgs/${orgId}/projects/${projectId}/members/${subject}`,
 
   // Schedules (org-scoped, platform time trigger primitive)
   SCHEDULES: (orgId: string) => `${API_BASE}/orgs/${orgId}/schedules`,
@@ -925,6 +937,10 @@ export const ENDPOINTS = {
   // Per-profile egress proxy (hosted Cloud Profiles; manager-only, human-only).
   ORG_EDGE_PROFILE_PROXY: (orgId: string, edgeId: string, profileName: string) =>
     `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles/${encodeURIComponent(profileName)}/proxy`,
+  // Per-profile one-shot cookie seed (hosted Cloud Profiles; manager-only,
+  // human-only, idle-only). Injected at the next cold start, then consumed.
+  ORG_EDGE_PROFILE_COOKIES: (orgId: string, edgeId: string, profileName: string) =>
+    `/api/v1/orgs/${orgId}/edge/${edgeId}/profiles/${encodeURIComponent(profileName)}/cookies`,
   ORG_EDGE_EXEC: (orgId: string) => `/api/v1/orgs/${orgId}/edge/exec`,
   // Cloud Edge live viewer command (V1b) — api-server, gated on cap:edge-viewer.
   // Same request/reply shape as the v2 browser-profile viewer, on the v3 edge
@@ -1020,6 +1036,7 @@ export const WS_EVENTS = {
   PONG: 'pong',
   WATCHING: 'watching',
   MESSAGE_NEW: 'message.new',
+  /** @deprecated `message.patch` is retired and never published; kept for compile compatibility. */
   MESSAGE_PATCH: 'message.patch',
   MESSAGE_EDIT: 'message.edit',
   MESSAGE_DELETE: 'message.delete',

package/src/project-task-client.ts

@@ -1,11 +1,16 @@
 import { ENDPOINTS } from './constants.js';
 import type {
+  AddProjectMemberRequest,
+  Approval,
   CreateProjectRequest,
   CreateTaskCommentRequest,
   CreateTaskRelationRequest,
   CreateTaskRequest,
   PaginatedResponse,
   Project,
+  ProjectJoinRequest,
+  ProjectLibraryEntry,
+  ProjectMember,
   ProjectTaskSummaryResponse,
   Task,
   TaskActivity,
@@ -15,6 +20,7 @@ import type {
   TaskSubtaskSummaryResponse,
   TaskWatcher,
   ThreadWatcher,
+  UpdateProjectMemberRequest,
   UpdateProjectRequest,
   UpdateTaskCommentRequest,
   UpdateTaskRequest,
@@ -246,4 +252,91 @@ export abstract class ProjectTaskClient {
   async deleteProject(orgId: string, projectId: string): Promise<void> {
     return this.request('DELETE', ENDPOINTS.PROJECT(orgId, projectId));
   }
+
+  /** Roster with display info; readable by anyone who can read the project. */
+  async getProjectMembers(orgId: string, projectId: string): Promise<ProjectMember[]> {
+    const res = await this.request<{ data: ProjectMember[] }>(
+      '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: string, projectId: string): Promise<string[]> {
+    const res = await this.request<{ data: string[] }>(
+      '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: string): Promise<ProjectLibraryEntry[]> {
+    const res = await this.request<{ data: ProjectLibraryEntry[] }>(
+      '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: string, projectId: string): Promise<ProjectMember> {
+    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: string, projectId: string): Promise<Approval> {
+    return this.request('POST', ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId));
+  }
+
+  /** Pending petitions for one project — manager standing required. */
+  async listProjectJoinRequests(orgId: string, projectId: string): Promise<ProjectJoinRequest[]> {
+    const res = await this.request<{ data: ProjectJoinRequest[] }>(
+      'GET',
+      ENDPOINTS.PROJECT_JOIN_REQUESTS(orgId, projectId),
+    );
+    return res.data;
+  }
+
+  /** Withdraws the caller's own pending petition. */
+  async cancelProjectJoinRequest(orgId: string, projectId: string): Promise<void> {
+    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: string,
+    projectId: string,
+    req: AddProjectMemberRequest,
+  ): Promise<ProjectMember> {
+    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: string,
+    projectId: string,
+    subject: string,
+    req: UpdateProjectMemberRequest,
+  ): Promise<ProjectMember> {
+    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: string, projectId: string, subject: string): Promise<void> {
+    return this.request('DELETE', ENDPOINTS.PROJECT_MEMBER(orgId, projectId, subject));
+  }
 }

package/src/subject.ts

@@ -4,37 +4,32 @@ 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;
 }
 
-const TEAM_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * 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 isValidTeamSlug(slug: string): boolean {
-  return TEAM_SLUG.test(slug);
-}
-
-export function formatTeamSubject(slug: string): string {
-  if (!isValidTeamSlug(slug)) {
-    throw new Error(`Invalid team slug: ${slug}`);
-  }
-  return `@${slug}`;
+export function isTeamSubject(token: string): boolean {
+  return token.startsWith(TEAM_ID_PREFIX);
 }
 
 export function parseSubjectToken(token: string): ParsedSubject {
   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 };
 }
 
@@ -45,22 +40,18 @@ export function parseSubjectToken(token: string): ParsedSubject {
 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: readonly string[]): string[] {
+export function teamIdsFromSubjects(subjects: readonly string[]): string[] {
   const seen = new Set<string>();
-  const slugs: string[] = [];
+  const ids: string[] = [];
   for (const token of subjects) {
-    if (!token.startsWith('@')) continue;
-    const slug = token.slice(1);
-    if (!slug || seen.has(slug)) continue;
-    seen.add(slug);
-    slugs.push(slug);
+    if (!isTeamSubject(token) || seen.has(token)) continue;
+    seen.add(token);
+    ids.push(token);
   }
-  return slugs;
+  return ids;
 }

package/src/types.ts

@@ -486,14 +486,15 @@ 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;
@@ -526,13 +527,12 @@ 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 {
@@ -1028,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;
@@ -1559,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;
@@ -1583,7 +1578,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.
    */
@@ -1659,7 +1654,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. */
@@ -1676,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:
@@ -1723,36 +1726,123 @@ 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 {
@@ -2623,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;
@@ -2630,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 {
@@ -3700,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;
@@ -3898,6 +4009,14 @@ export interface ResolvedRef {
   created_at?: string;
   attachments?: Attachment[];
 
+  // Partial-quote fields (msg_ refs with a ?v= + #t= anchor): the exact text
+  // sliced from the body that was live at the anchor's content version.
+  // quote_from_edited marks that the body was edited after the quote was
+  // taken. Absent on bounds/validity failure — degrade to the whole-message
+  // reference.
+  quoted_text?: string;
+  quote_from_edited?: boolean;
+
   // Range fields (cht_ + range anchor)
   range_messages?: Array<{
     id: string;
@@ -4894,6 +5013,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;
@@ -4916,7 +5083,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
@@ -5044,9 +5222,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[];
 }
 
 /**
@@ -5065,6 +5254,8 @@ export interface MCPConfigCreateRequest {
   server_url?: string;
   auth_type: MCPAuthType | 'oauth';
   credential?: string;
+  /** See MCPConfigPutRequest.credentials. */
+  credentials?: string[];
   alias?: string;
   oauth_client?: MCPOAuthClientParams;
 }
@@ -5175,13 +5366,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
@@ -5189,8 +5400,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[];
 }
 
 /**
@@ -5205,6 +5432,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 {
   /**