@agent-compose/sdk 0.8.3 → 0.8.5

package/src/client.ts

@@ -1,3 +1,4 @@
+import type { ConversationRow, CreateChatInput, ChannelIvyState, ProjectIvyConnection } from "./types/api-conversations.js";
 /**
  * AgentComposeClient — HTTP client for the agent-compose server API.
  *
@@ -32,8 +33,9 @@ import type {
   ConversationsPage, SessionsPage, ConversationDetail, ConversationThread,
   CreateCloudSessionInput, CloudSessionCreated,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
+  BackgroundWorkChildDecl, BackgroundWorkStatus, MachineUpsizeOutcome,
   SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport,
-  SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState,
+  SessionChangePreflight, SessionRebaseReport,
   ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential,
   SendConversationMessageInput, SendConversationMessageResult,
   ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
@@ -53,13 +55,14 @@ import type {
 import type {
   RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions,
   SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
-  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage,
+  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage, FactoryFileConflict, FactoryFileConflictList, ProjectSecretMeta, ProjectSecretList,
   FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultCatalogEntry,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse,
-  DriveRepoLink, CreateDriveRepoLinkInput,
+  DriveRepoLink, CreateDriveRepoLinkInput, CreateNativeRepoInput, CreateNativeRepoResult,
   DriveMountSession, CreateDriveMountSessionInput,
+  ConnectorGrantSummary,
 } from "./types/api-factory.js";
 import type {
   ComplianceSession, RequestComplianceSessionInput, ListComplianceSessionsOptions,
@@ -85,15 +88,17 @@ export type {
 } from "./types/api-runs.js";
 export type {
   TeamMember, Mention, CreateMentionsInput,
+  CreateChatInput, ChannelIvyState, ProjectIvyConnection,
   ConversationMessagePart, ConversationRow, ConversationMessageRow,
   ConversationsPage, SessionsPage, ConversationDetail,
   CreateCloudSessionInput, CloudSessionCreated, ConversationThread,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
+  BackgroundWorkChildDecl, BackgroundWorkStatus, MachineUpsizeOutcome,
   SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion,
   ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument,
   ReviewSuggestionDecision, ReviewSuggestionDecisions,
   SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
-  SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState,
+  SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport,
   ConversationPageContext, SendConversationMessageInput, ConversationTurnState,
   SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
   ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
@@ -115,15 +120,16 @@ export type {
   RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput,
   TemplateRow, TemplateDetail, ListTemplatesOptions,
   FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
-  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage,
+  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage, FactoryFileConflict, FactoryFileConflictList, ProjectSecretMeta, ProjectSecretList,
   PublicFileLinkState,
   FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus, SessionSecretRequestSummary, VaultRequestKind, VaultCatalogEntry,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
-  DriveRepoLink, CreateDriveRepoLinkInput,
+  DriveRepoLink, CreateDriveRepoLinkInput, CreateNativeRepoInput, CreateNativeRepoResult,
   DriveMountSession, CreateDriveMountSessionInput,
+  ConnectorGrantSummary,
 } from "./types/api-factory.js";
 export type {
   ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess,
@@ -770,6 +776,55 @@ export class AgentComposeClient {
     };
   }
 
+  /** Bounded, cursor-paginated conflicts. A session filter is applied in the database. */
+  /** Project secrets (the group tier) — names + metadata, project members only. */
+  listProjectSecrets(projectId: string): Promise<ProjectSecretList> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(projectId)}/secrets`);
+  }
+
+  /** Upsert a project secret. Human credential required (a session toolbelt
+   * key is refused). Values are write-only — never echoed. */
+  upsertProjectSecret(projectId: string, secret: {
+    key: string; value: string;
+    delivery?: "injected" | "brokered"; brokerHost?: string; brokerHeaderName?: string; brokerHeaderScheme?: string;
+  }): Promise<{ key: string; delivery: "injected" | "brokered" }> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
+      method: "POST", body: JSON.stringify(secret),
+    });
+  }
+
+  deleteProjectSecret(projectId: string, key: string): Promise<void> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
+
+  listFactoryFileConflicts(factorySlug: string, opts: { limit?: number; cursor?: string; conversationId?: string } = {}): Promise<FactoryFileConflictList> {
+    const q = new URLSearchParams();
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts.cursor) q.set("cursor", opts.cursor);
+    if (opts.conversationId) q.set("conversationId", opts.conversationId);
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/conflicts?${q}`);
+  }
+
+  async getFactoryFileConflictContent(factorySlug: string, id: string): Promise<Uint8Array> {
+    const bytes = await this.fetch<ArrayBuffer, "arrayBuffer">(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/conflicts/${encodeURIComponent(id)}/content`,
+      { responseType: "arrayBuffer" },
+    );
+    return new Uint8Array(bytes);
+  }
+
+  /** Records a decision about the exact inspected versions. Stale arms refuse. */
+  resolveFactoryFileConflict(factorySlug: string, id: string, decision: {
+    status: "resolved" | "dismissed";
+    settle: "branch" | "main";
+    expectedOursHash: string | null;
+    expectedTheirsHash: string | null;
+  }): Promise<FactoryFileConflict & { settled: "branch" | "main" | "row" }> {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/conflicts/${encodeURIComponent(id)}/resolve`, {
+      method: "POST", body: JSON.stringify(decision),
+    });
+  }
+
   /** Read one file's current content (or a specific revision) as RAW BYTES —
    *  byte-exact for any content type. This is the wire truth; `getFactoryFile`
    *  is a UTF-8 decode over it. Binaries (images, archives) MUST come through
@@ -860,6 +915,17 @@ export class AgentComposeClient {
   // access. Key callers see what their sender scope allows; the server is the
   // sole authority — these are thin typed wrappers.
 
+  /** Create a shared chat, including its own Ivy by default. */
+  createChat(input: CreateChatInput): Promise<ConversationRow> {
+    return this.fetch("/api/v1/conversations", { method: "POST", body: JSON.stringify(input), headers: { "content-type": "application/json" } });
+  }
+  getChannelIvy(id: string): Promise<ChannelIvyState> {
+    return this.fetch(`/api/v1/conversations/${encodeURIComponent(id)}/ivy`);
+  }
+  listProjectIvyConnections(id: string): Promise<{ connections: ProjectIvyConnection[]; canManage: boolean }> {
+    return this.fetch(`/api/v1/projects/${encodeURIComponent(id)}/ivy-connections`);
+  }
+
   /** List conversations the caller can access, newest-activity first.
    *  Cursor-paginated: pass the previous page's `next_cursor`. */
   listConversations(opts?: { cursor?: string }): Promise<ConversationsPage> {
@@ -1095,19 +1161,62 @@ export class AgentComposeClient {
    *  background-work busy lease: while it is live, the between-turns
    *  park/suspend leaves the session's VM running so work the turn left
    *  behind keeps executing. The lease lapses on its own — re-hold to
-   *  extend past `minutes` (server-capped). Write-tier. */
-  holdBackgroundWork(conversationId: string, input?: { minutes?: number }): Promise<BackgroundWorkHeld> {
+   *  extend past `minutes` (server-capped). `children` descriptors
+   *  ({pid, journalPath, label}) register the DETACHED processes the hold
+   *  vouches for, so the platform can verify and reattach them after a
+   *  park (task #63). Write-tier. */
+  holdBackgroundWork(
+    conversationId: string,
+    input?: { minutes?: number; children?: BackgroundWorkChildDecl[] },
+  ): Promise<BackgroundWorkHeld> {
     return this.fetch<BackgroundWorkHeld>(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`,
-      { method: "POST", body: { ...(input?.minutes !== undefined ? { minutes: input.minutes } : {}) } },
+      { method: "POST", body: {
+        ...(input?.minutes !== undefined ? { minutes: input.minutes } : {}),
+        ...(input?.children !== undefined ? { children: input.children } : {}),
+      } },
+    );
+  }
+
+  /** Request ONE machine size up for a cloud session (task #110 — the
+   *  auto-resize policy's agent door). The platform arbitrates: within the
+   *  team's daily cap the upsize is auto-granted (and executes the moment
+   *  no live turn / background work holds the machine — home essentials
+   *  carry over); past the cap it becomes an owner approval card.
+   *  Deliberately not `resize`: the in-sandbox toolbelt key may call THIS,
+   *  because the kill only ever happens under platform policy or human
+   *  approval. Refusals (memory ceiling, template-pinned, ended) arrive as
+   *  HTTP 409s carrying `code`. Write-tier. */
+  requestMachineUpsize(
+    conversationId: string, input?: { reason?: string },
+  ): Promise<MachineUpsizeOutcome> {
+    return this.fetch<MachineUpsizeOutcome>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/machine/request-upsize`,
+      { method: "POST", body: input?.reason ? { reason: input.reason } : {} },
+    );
+  }
+
+  /** The session's background-work status: the lease deadline, the declared
+   *  children, and the owed-report marker a mid-work park leaves behind.
+   *  Read-tier. */
+  getBackgroundWork(conversationId: string): Promise<BackgroundWorkStatus> {
+    return this.fetch<BackgroundWorkStatus>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`,
     );
   }
 
   /** Release the session's background-work lease (the work finished).
-   *  Idempotent — `released` is false when no lease was held. */
-  async releaseBackgroundWork(conversationId: string): Promise<boolean> {
+   *  Idempotent — `released` is false when no lease was held. `pid` scopes
+   *  the release to ONE declared child (what a `--while-pid` holder passes
+   *  when its watched process dies): the child is pruned from the declared
+   *  registry, and the lease clears only when it was the last — a sibling's
+   *  death never erases the other holders' declarations. */
+  async releaseBackgroundWork(
+    conversationId: string, opts?: { pid?: number },
+  ): Promise<boolean> {
+    const pidQuery = opts?.pid !== undefined ? `?pid=${encodeURIComponent(opts.pid)}` : "";
     const body = await this.fetch<{ released: boolean }>(
-      `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`,
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work${pidQuery}`,
       { method: "DELETE" },
     );
     return body.released;
@@ -1214,6 +1323,59 @@ export class AgentComposeClient {
     );
   }
 
+  /** Mint ONE fresh short-lived WIP-push credential for the CALLING
+   *  session's git namespace (`POST /sessions/self/wip-git-credential`,
+   *  git-door slice 2) — the server half of `agentc repos clone` and its
+   *  git credential helper. The token's Push grant is exactly
+   *  `refs/sessions/<sessionId>/`; the door refuses everything else.
+   *  Callable only with a session's own toolbelt credential.
+   *
+   *  Failures: 403 `session_credential_required` | `not_a_session`;
+   *  409 `git_remote_unavailable` (unbranched / legacy plane / fsgw off). */
+  getSessionWipGitCredential(): Promise<ReviewGitCredential & { pushNamespace: string }> {
+    return this.fetch<ReviewGitCredential & { pushNamespace: string }>(
+      "/api/v1/sessions/self/wip-git-credential",
+      { method: "POST" },
+    );
+  }
+
+  /** Mint a short-lived native-git credential for a linked repo's MIRROR
+   *  namespace (`POST /:slug/repo-links/:id/git-credential`, git-door
+   *  slice 4). mode "fetch" (default) reads the mirror — gated on link
+   *  visibility; mode "mirror" pushes real GitHub history through the
+   *  closure-verified door — gated on the repo_link WRITE capability.
+   *  409 `git_remote_unavailable` when no git plane serves the factory. */
+  getRepoLinkGitCredential(linkId: string, opts?: { mode?: "fetch" | "mirror" | "github" | "native"; factorySlug?: string }):
+    Promise<{
+      url: string; username: string; password: string; repoUrl: string;
+      /** Absent in `github` mode (the credential targets github.com, not the platform git plane). */
+      namespace?: string; expiresAt: string; mode: string;
+      /** `github` mode only: the host the credential is for. */
+      host?: string;
+      /** `github` mode only: the token's ceiling — "write" (contents:write,
+       *  push-capable) for viewers with write capability on the link,
+       *  "read" (clone/fetch only) otherwise. */
+      access?: "read" | "write";
+      /** `github` mode only: the GRANTED permission map GitHub echoed at
+       *  mint (e.g. `{contents:"write", pulls:"write"}`). A capability
+       *  missing here (pulls, issues) means the App installation does not
+       *  carry it — the OWNER must widen the installation; retrying can
+       *  never help. */
+      permissions?: Record<string, string>;
+      /** `github` mode only: the INSTALLATION's recorded grant ledger
+       *  (`key:level` strings, probe-synced). A capability present here
+       *  but missing from `permissions` is a platform downscope; missing
+       *  from both layers, an App-installation gap only the owner can
+       *  widen. Empty = not yet recorded (reconnect or next probe). */
+      installationScopes?: string[];
+    }> {
+    const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(
+      `/api/v1/factories/${encodeURIComponent(slug)}/repo-links/${encodeURIComponent(linkId)}/git-credential`,
+      { method: "POST", body: JSON.stringify({ mode: opts?.mode ?? "fetch" }), headers: { "content-type": "application/json" } },
+    );
+  }
+
   /** Approve the session's proposed changes: 3-way merge its branch into
    *  `main`, then continue the session on a fresh branch off post-merge
    *  `main`. Write-tier + human caller. Pass `opts.branch` (the branch you
@@ -1224,9 +1386,14 @@ export class AgentComposeClient {
    *  converged on) a kind='merge' approval routed to the session's
    *  approvers. Discriminate on `object`.
    *
-   *  Failures: 403 `role_read_only` (read-only member) or a plain 403 for
-   *  session toolbelt keys (agents cannot self-approve); 409 `turn_active`
-   *  (a turn is running — retry when idle) | `branch_changed`; 400
+   *  Failures: 403 `role_read_only` (read-only member); 403 `not_own_branch`
+   *  (a session toolbelt key merges ONLY its own bound session's branch —
+   *  the agent self-merge door, owner ruling 2026-08-31); 403 `merge_gated`
+   *  (a gated session's self-merge — a designated approver merges from the
+   *  Changes panel instead, and no card is minted); 409 `turn_active` (a
+   *  turn is running — retry when idle; a session's OWN self-merge is
+   *  exempt) | `branch_changed` | `branch_claimed` (a teammate session
+   *  holds the branch claim — merge after it releases); 400
    *  `no_branch` (session predates branching); 502 `quiesce_failed`
    *  (nothing changed — safe to retry) | `merge_failed` (branch retained,
    *  named in the body) | `rebranch_failed` (merge landed; retry safe). */
@@ -1290,24 +1457,6 @@ export class AgentComposeClient {
     );
   }
 
-  /** Arm/disarm the OPT-IN main-advance auto-rebase reflex for a session
-   *  (default OFF): when armed and the drive's main moves, the platform
-   *  preflights and — only on a provably clean fold (zero conflicts) —
-   *  rebases the session's branch from main headlessly, posting a quiet
-   *  receipt. Trade-off (why default OFF): the agent's view of files it
-   *  did not touch can change mid-task. Human, write-tier act.
-   *
-   *  Failures: 409 `review_session_scratch` | `plane_unsupported`; 403
-   *  (needs a user-bound human caller with write access). */
-  setSessionAutoRebase(
-    conversationId: string, enabled: boolean,
-  ): Promise<SessionAutoRebaseState> {
-    return this.fetch<SessionAutoRebaseState>(
-      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/autorebase`,
-      { method: "POST", body: { enabled } },
-    );
-  }
-
   // ── Conversation membership (ADR-0045) ────────────────────────────────────
   // Channel rosters carry roles (`owner > write > read`). Inviting is a
   // `write` action; removing and re-roling are `owner` (or team admin)
@@ -1497,6 +1646,13 @@ export class AgentComposeClient {
     };
   }
 
+  /** The credential's user role on the active team; null for a creator-less
+   * key or a user with no membership. */
+  async getTeamRole(): Promise<string | null> {
+    const body = await this.fetch<{ role: string | null }>("/api/v1/team/role");
+    return body.role;
+  }
+
   /** List the human members of your team — the people you (or an agent) can
    *  @-flag with `createMentions`. Each row's `userId` is what
    *  `mentionedUserIds` expects. */
@@ -1914,6 +2070,27 @@ export class AgentComposeClient {
     return body.links;
   }
 
+  /** Create a repo whose origin IS Agent Compose (`manage` scope) — no
+   *  GitHub behind it; clone/fetch/push ride the platform git door. 409
+   *  names the missing prerequisite (graph drive, git plane) or an
+   *  overlapping placement. */
+  async createNativeRepo(
+    input: CreateNativeRepoInput, opts?: { factorySlug?: string },
+  ): Promise<CreateNativeRepoResult> {
+    const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch<CreateNativeRepoResult>(
+      `/api/v1/factories/${encodeURIComponent(slug)}/repo-links/native`,
+      { method: "POST", body: input });
+  }
+
+  /** The team's connector grants (metadata only — never tokens). Used by
+   *  `agentc repos link` to default `--grant` when the team holds exactly
+   *  one active GitHub grant. */
+  async listConnectorGrants(): Promise<ConnectorGrantSummary[]> {
+    const body = await this.fetch<{ data: ConnectorGrantSummary[] }>("/api/v1/connectors");
+    return body.data;
+  }
+
   /** Unlink (§6.3: the prefix's files and history stay on the drive). */
   deleteRepoLink(linkId: string, opts?: { factorySlug?: string }): Promise<void> {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
@@ -1986,20 +2163,61 @@ export class AgentComposeClient {
    *  toolbelt credential (the in-sandbox agent's door) or by a session
    *  writer. */
   requestSessionSecrets(
-    conversationId: string, keys: string[], opts?: { reason?: string },
+    conversationId: string, keys: string[],
+    opts?: { reason?: string; setLabel?: string; kind?: VaultRequestKind },
   ): Promise<SessionSecretRequestCreated> {
     return this.fetch(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests`,
-      { method: "POST", body: { keys, ...(opts?.reason ? { reason: opts.reason } : {}) } });
+      { method: "POST", body: {
+        keys,
+        ...(opts?.reason ? { reason: opts.reason } : {}),
+        // Suggested batch name — prefills the vault form's save-as-set label.
+        ...(opts?.setLabel ? { setLabel: opts.setLabel } : {}),
+        // WHAT KIND of credential — the vault page leads with the user's
+        // matching STANDING entries (personal-vault reuse, 2026-08-31).
+        ...(opts?.kind ? { kind: opts.kind } : {}),
+      } });
+  }
+
+  /** The session's STANDING-vault catalog (2026-08-31): entries the vault
+   *  could grant to this session — labels, kinds, field NAMES, last-used.
+   *  Values are write-only and never on this wire. Query it BEFORE asking
+   *  the human for a credential: a matching entry means the ask is a GRANT
+   *  ask naming it, never a blank re-entry form. */
+  getSessionVaultCatalog(conversationId: string): Promise<{ entries: VaultCatalogEntry[]; note?: string }> {
+    return this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/vault-catalog`);
   }
 
   /** Poll a vault link's status (`pending` → `fulfilled`; `expired` when the
-   *  clock ran out). The in-sandbox `agentc secrets request --wait` loop. */
+   *  clock ran out; `cancelled` when the human denied it or the requester
+   *  withdrew it — attribution rides the answer). The in-sandbox
+   *  `agentc secrets request --wait` loop. */
   getSessionSecretRequest(conversationId: string, requestId: string): Promise<SessionSecretRequestStatus> {
     return this.fetch(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests/${encodeURIComponent(requestId)}`);
   }
 
+  /** List a session's OPEN vault requests (pending + unexpired), newest
+   *  first — receipts only (keys, reason, clocks). The cancel verb's
+   *  `--all` enumeration. */
+  async listSessionSecretRequests(conversationId: string): Promise<SessionSecretRequestSummary[]> {
+    const body = await this.fetch<{ requests: SessionSecretRequestSummary[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests`);
+    return body.requests;
+  }
+
+  /** Cancel one vault request (task #111). The requesting agent withdraws
+   *  its own ask (session toolbelt key), or a session writer denies it.
+   *  409 `request_not_pending` when it already settled. */
+  cancelSessionSecretRequest(
+    conversationId: string, requestId: string, opts?: { reason?: string },
+  ): Promise<{ requestId: string; status: "cancelled" }> {
+    return this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests/${encodeURIComponent(requestId)}/cancel`,
+      { method: "POST", body: { ...(opts?.reason ? { reason: opts.reason } : {}) } });
+  }
+
   // ── API keys ───────────────────────────────────────────────────────────────
   // Both endpoints require an admin-scoped key as the bearer token.
 

package/src/directives.ts

@@ -61,7 +61,15 @@ export type CloudDirective =
   /** Interactive question card gated on a named approver — resolution and
    *  the mentions ping are server-authoritative (`display_ask` shape). The
    *  one write-bearing directive (see the module header). */
-  | { kind: "ask"; prompt: string; approver: string; options?: Array<{ id: string; label: string }> };
+  | { kind: "ask"; prompt: string; approver: string; options?: Array<{ id: string; label: string }> }
+  /** Offer the human the desktop takeover door (`request_desktop_takeover`
+   *  shape): the server captures the current screen and posts a card with a
+   *  signed takeover link — "You can take over from here." Grants nothing
+   *  by itself: the link's viewer must still be a signed-in member with
+   *  write access to THIS session (the server re-checks on every resolve).
+   *  ONLY for structurally-human walls (a CAPTCHA, human-only verification)
+   *  or when the user asked to do it themselves. */
+  | { kind: "takeover"; note?: string };
 
 /** `runId` values the run directives accept: a UUID, or the literal
  *  `latest` (resolved server-side against the session's factory, optionally
@@ -85,6 +93,10 @@ export const ASK_DIRECTIVE_OPTION_LABEL_MAX = 60;
 export const ASK_APPROVER_MIN = 3;
 export const ASK_APPROVER_MAX = 320;
 
+/** Takeover-note bound — one line naming what the human must do on the
+ *  screen (mirrors the display-desktop caption cap). */
+export const TAKEOVER_NOTE_MAX_CHARS = 200;
+
 function validDirectivePath(v: unknown): string | null {
   return typeof v === "string" && v.length >= 1 && v.length <= DIRECTIVE_PATH_MAX ? v : null;
 }
@@ -152,6 +164,14 @@ function validDirective(value: unknown): CloudDirective | null {
     }
     return { kind: "ask", prompt, approver, ...(options !== undefined ? { options } : {}) };
   }
+  if (d.kind === "takeover") {
+    const note = d.note;
+    if (note !== undefined
+      && (typeof note !== "string" || note.length < 1 || note.length > TAKEOVER_NOTE_MAX_CHARS)) {
+      return null;
+    }
+    return { kind: "takeover", ...(note !== undefined ? { note } : {}) };
+  }
   return null;
 }