@agent-compose/sdk 0.8.2 → 0.8.4

package/src/client.ts

@@ -23,7 +23,7 @@ import type {
   RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions,
   RequestAgentPauseOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
-  RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, EventRow, ReportEventInput,
+  RunDetail, RunListEntry, ListRunsOptions, TimelineEvent, RunFundingResponse, RunStepUsageResponse, EventRow, ReportEventInput,
   ListEventsOptions, ListEventsResult, RunArtifactRow, RunLogLine, ListRunLogsOptions,
   CancelRunResponse, ListSnapshotsOptions, SnapshotListResponse, SnapshotListEntry, RunSnapshotEntry,
 } from "./types/api-runs.js";
@@ -33,9 +33,13 @@ import type {
   CreateCloudSessionInput, CloudSessionCreated,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   SessionChangeSet, SessionMergeGated, SessionMergeReport, SessionDiscardReport,
+  SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState,
+  ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential,
   SendConversationMessageInput, SendConversationMessageResult,
   ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  SessionDirectMessageSent, BranchClaimGranted, BranchClaimsReleased, BranchClaimState,
   ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
+  SessionPerfHistoryPage,
 } from "./types/api-conversations.js";
 import type {
   ConversationMemberRole, ConversationMember, ArtifactScope,
@@ -49,9 +53,10 @@ import type {
 import type {
   RegisterResult, RegisterWorkflowInput, TemplateRow, TemplateDetail, ListTemplatesOptions,
   SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
-  FactoryRow, CreateFactoryInput, UpdateFactoryInput,
+  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage,
+  FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
   DriveMountSession, CreateDriveMountSessionInput,
@@ -73,6 +78,7 @@ export type {
   SendAgentMessageOptions, SendAgentMessageResponse,
   RunDetail, RunListEntry, ListRunsOptions, TimelineEvent,
   FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse,
+  RunStepUsage, RunStepUsageResponse,
   EventSubjectType, EventRow, RunArtifactRow, ReportEventInput, ListEventsOptions, ListEventsResult,
   RunLogLine, ListRunLogsOptions, CancelRunResponse,
   ListSnapshotsOptions, SnapshotListEntry, SnapshotListResponse, RunSnapshotEntry,
@@ -84,11 +90,15 @@ export type {
   CreateCloudSessionInput, CloudSessionCreated, ConversationThread,
   SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion,
+  ReviewSuggestionInput, ReviewNotesPublished, ReviewGitCredential, SessionReviewDocument,
   ReviewSuggestionDecision, ReviewSuggestionDecisions,
   SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
+  SessionPreflightFileRow, SessionChangePreflight, SessionRebaseReport, SessionAutoRebaseState,
   ConversationPageContext, SendConversationMessageInput, ConversationTurnState,
   SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
   ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  SessionDirectMessageSent, BranchClaimInfo, BranchClaimGranted, BranchClaimsReleased, BranchClaimState,
+  SessionPerfBucket, SessionPerfHistoryPage,
 } from "./types/api-conversations.js";
 export type {
   ConversationMemberRole, ConversationMember,
@@ -105,10 +115,11 @@ export type {
   RegisterResult, RegisteredRuntime, RuntimeSourceInput, TemplateSourceRef, RegisterWorkflowInput,
   TemplateRow, TemplateDetail, ListTemplatesOptions,
   FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, FactoryFileWriteResult,
+  FactoryFileListRow, ListFactoryFilesOptions, FactoryFileListPage,
   PublicFileLinkState,
-  FactoryRow, CreateFactoryInput, UpdateFactoryInput,
+  FactoryRow, CreateFactoryInput, UpdateFactoryInput, FactoryPerfSummary,
   ScheduleRow, CreateScheduleInput,
-  SecretOptions, SetSecretResult, SecretListEntry,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
@@ -165,6 +176,17 @@ interface FactoryFileWriteWire {
   created: boolean;
 }
 
+/** `GET /factories/:slug/files` — the rows are camelCase on the wire
+ *  already; only the envelope is snake_case. `at` appears exactly when the
+ *  request carried `?at=`. */
+interface FactoryFileListWire {
+  object: "list";
+  data: FactoryFileListRow[];
+  has_more: boolean;
+  next_cursor: string | null;
+  at?: { head: string; committed_at: string | null };
+}
+
 export interface AgentComposeClientOptions {
   /** Your team's API key — minted from the dashboard or `agentc keys create`.
    *  Required. Resolved from `process.env.AGENT_COMPOSE_API_KEY` when omitted. */
@@ -653,6 +675,16 @@ export class AgentComposeClient {
     );
   }
 
+  /** Attested platform tokens attributed to each of a run's steps, derived
+   * server-side from the spend ledger by step time window. Empty `steps` is
+   * an honest answer (legacy run, or funded outside the platform lane —
+   * that money is never metered). */
+  async getRunStepUsage(runId: string): Promise<RunStepUsageResponse> {
+    return this.fetch<RunStepUsageResponse>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/step-usage`,
+    );
+  }
+
   /** Report a durable event against a run. Events are late-binding facts
    * like quality.accepted, defect.regression, or intervention.override. */
   async reportEvent(runId: string, input: ReportEventInput): Promise<EventRow> {
@@ -745,7 +777,7 @@ export class AgentComposeClient {
    *  U+FFFD and the original bytes are unrecoverable). */
   async getFactoryFileBytes(
     path: string,
-    opts?: { factorySlug?: string; revision?: number; branch?: string },
+    opts?: { factorySlug?: string; revision?: number; branch?: string; at?: string },
   ): Promise<Uint8Array> {
     const factorySlug = opts?.factorySlug
       ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
@@ -756,6 +788,10 @@ export class AgentComposeClient {
     // session's own `session-<uuid>` branch, where its unmerged work lives.
     // Mutually exclusive with `revision` (the server rejects the combination).
     if (opts?.branch !== undefined) q.set("branch", opts.branch);
+    // Browse-at-head (read-only): the file AS OF a retained 64-hex commit of
+    // the MAIN drive. A garbage-collected/unknown head answers 410
+    // `at_unavailable`.
+    if (opts?.at !== undefined) q.set("at", opts.at);
     const buf = await this.fetch<ArrayBuffer, "arrayBuffer">(
       `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q}`,
       { responseType: "arrayBuffer" },
@@ -768,7 +804,7 @@ export class AgentComposeClient {
    *  text corrupts the bytes irreversibly. */
   async getFactoryFile(
     path: string,
-    opts?: { factorySlug?: string; revision?: number; branch?: string },
+    opts?: { factorySlug?: string; revision?: number; branch?: string; at?: string },
   ): Promise<string> {
     return new TextDecoder().decode(await this.getFactoryFileBytes(path, opts));
   }
@@ -841,6 +877,31 @@ export class AgentComposeClient {
     return this.fetch<SessionsPage>(`/api/v1/sessions?${q}`);
   }
 
+  /** A session's sandbox perf HISTORY — 15-minute rollup buckets
+   *  (CPU/mem/disk percentiles, load, saturation seconds), newest first.
+   *  Member-gated like the session itself. Cursor-paginated. */
+  getSessionPerfHistory(
+    conversationId: string, opts?: { limit?: number; cursor?: string },
+  ): Promise<SessionPerfHistoryPage> {
+    const q = new URLSearchParams();
+    if (opts?.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    return this.fetch<SessionPerfHistoryPage>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/perf-history${q.toString() ? `?${q}` : ""}`);
+  }
+
+  /** Team-level sandbox perf aggregates over a window (default trailing
+   *  24h, max 30 days). Aggregate-only — no per-session identifiers. */
+  getFactoryPerfSummary(
+    factorySlug: string, opts?: { from?: string; to?: string },
+  ): Promise<FactoryPerfSummary> {
+    const q = new URLSearchParams();
+    if (opts?.from) q.set("from", opts.from);
+    if (opts?.to) q.set("to", opts.to);
+    return this.fetch<FactoryPerfSummary>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/perf-summary${q.toString() ? `?${q}` : ""}`);
+  }
+
   /** One conversation with its latest page of messages. `limit` bounds the
    *  page (newest N) — metadata-only consumers (e.g. resolving the
    *  session's drive branch) pass 1 instead of pulling the full hydrate. */
@@ -945,6 +1006,51 @@ export class AgentComposeClient {
     );
   }
 
+  /** Message ANOTHER session's conversation AS the calling session
+   *  (`agentc session message @alias`). Session toolbelt credential ONLY —
+   *  the sender resolves from the key. `target` is an @alias (team-scoped)
+   *  or a conversation uuid. Unlike a channel post this WAKES the target's
+   *  turn machinery; the response's `turn` verdict says whether it started,
+   *  queued behind a live turn, or was parked by the agent-to-agent
+   *  exchange damper. Unknown alias → 404 with `candidates`. */
+  sendSessionMessage(input: { target: string; text: string }): Promise<SessionDirectMessageSent> {
+    return this.fetch<SessionDirectMessageSent>("/api/v1/session-messages", {
+      method: "POST", body: input,
+    });
+  }
+
+  /** Claim ANOTHER session's drive branch for the calling session
+   *  (`agentc branch claim @alias`) — transfers the branch's one-writer
+   *  authority: the target's own writes refuse honestly until release, and
+   *  the response carries the mount token the CLI uses to FUSE-mount the
+   *  branch in-guest. Session toolbelt credential only; same-owner sessions
+   *  only (cross-user claims refuse with the gap stated); refuses while the
+   *  target is mid-turn (409 `mid_turn`) or already claimed
+   *  (409 `already_claimed`). */
+  claimSessionBranch(input: { target: string; reason?: string }): Promise<BranchClaimGranted> {
+    return this.fetch<BranchClaimGranted>("/api/v1/session-branch-claims", {
+      method: "POST", body: { target: input.target, ...(input.reason ? { reason: input.reason } : {}) },
+    });
+  }
+
+  /** Release branch claims HELD by the calling session (`agentc branch
+   *  release [@alias]`). `target` narrows to one claim; omitted releases
+   *  them all. Idempotent — an empty `released` list means nothing was
+   *  held. */
+  releaseSessionBranchClaims(input: { target?: string } = {}): Promise<BranchClaimsReleased> {
+    return this.fetch<BranchClaimsReleased>("/api/v1/session-branch-claims/release", {
+      method: "POST", body: { ...(input.target ? { target: input.target } : {}) },
+    });
+  }
+
+  /** One session's branch-claim state: the live claim ON its branch (null =
+   *  writable there) and the claims it HOLDS (`agentc branch status`, the
+   *  dashboard's Changes-panel badge). Any viewer with access. */
+  getSessionBranchClaimState(conversationId: string): Promise<BranchClaimState> {
+    return this.fetch<BranchClaimState>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/branch-claim`);
+  }
+
   // ── Cloud-session developer surface (ADR-0052) ────────────────────────────
 
   /** Open a dev preview on a cloud session: expose a port a dev server is
@@ -1029,9 +1135,82 @@ export class AgentComposeClient {
    *  writes `main` directly. The list reflects the branch's last flush and
    *  is advisory; a merge re-verifies against fresh state. 404 = not found
    *  or not a member (uniform). */
-  getSessionChanges(conversationId: string): Promise<SessionChangeSet> {
+  getSessionChanges(
+    conversationId: string,
+    opts: { after?: string; limit?: number } = {},
+  ): Promise<SessionChangeSet> {
+    // Graph-plane pagination (additive): `after` = the previous page's
+    // `nextAfter` cursor; `limit` 1..1000. Older servers ignore both.
+    const q = new URLSearchParams();
+    if (opts.after !== undefined) q.set("after", opts.after);
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    const tail = q.toString();
     return this.fetch<SessionChangeSet>(
-      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes`,
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes${tail ? `?${tail}` : ""}`,
+    );
+  }
+
+  /** One proposed file's RAW BYTES from a session's change set
+   *  (`GET /conversations/:id/changes/content`) — the review surface's
+   *  per-file read, also the in-sandbox `agentc review file` door.
+   *  `side: "base"` serves the PRE-change side (graph plane; the legacy
+   *  plane ignores it and always serves the proposed side). 404 = missing
+   *  path or no access (uniform, no existence oracle). */
+  async getSessionChangeContent(
+    conversationId: string, path: string, opts: { side?: "base" } = {},
+  ): Promise<Uint8Array> {
+    const q = new URLSearchParams({ path });
+    if (opts.side !== undefined) q.set("side", opts.side);
+    const buf = await this.fetch<ArrayBuffer, "arrayBuffer">(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/content?${q}`,
+      { responseType: "arrayBuffer" },
+    );
+    return new Uint8Array(buf);
+  }
+
+  /** Publish a diff review's WHOLE document — prose notes plus structured
+   *  suggestions, FULL REPLACE on every call (`POST
+   *  /conversations/:id/review-notes`; `agentc review publish`). Callable
+   *  ONLY with the bound review session's own toolbelt credential — any
+   *  other key (another session, a human cookie, a plain API key) refuses
+   *  403. `conversationId` is the REVIEWED session's conversation (in a
+   *  review sandbox: `AGENT_COMPOSE_REVIEW_OF_CONVERSATION_ID`).
+   *
+   *  Failures: 403 `session_credential_required` | `not_review_session` |
+   *  `review_superseded` (a newer review replaced this one); 400
+   *  `suggestion_path_not_in_change_set` (naming the offenders); 409
+   *  `review_disabled`. */
+  publishReviewNotes(
+    conversationId: string,
+    input: { notes: string; suggestions?: ReviewSuggestionInput[] },
+  ): Promise<ReviewNotesPublished> {
+    return this.fetch<ReviewNotesPublished>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/review-notes`,
+      {
+        method: "POST",
+        body: {
+          notes: input.notes,
+          ...(input.suggestions !== undefined ? { suggestions: input.suggestions } : {}),
+        },
+      },
+    );
+  }
+
+  /** Mint ONE fresh short-lived credential for the review git remote
+   *  (`POST /conversations/:id/review-git-credential`) — the server half
+   *  of the review sandbox's git credential helper (`agentc review
+   *  git-credential`), which calls this per git operation so the remote's
+   *  credential can never expire mid-review. Callable only with a review
+   *  session's own toolbelt credential; `conversationId` is the REVIEWED
+   *  session's conversation (`AGENT_COMPOSE_REVIEW_OF_CONVERSATION_ID`).
+   *
+   *  Failures: 403 `session_credential_required` | `not_review_session`;
+   *  409 `review_disabled` | `git_remote_unavailable` (legacy plane — read
+   *  the proposal through `getSessionChanges` instead). */
+  getReviewGitCredential(conversationId: string): Promise<ReviewGitCredential> {
+    return this.fetch<ReviewGitCredential>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/review-git-credential`,
+      { method: "POST" },
     );
   }
 
@@ -1076,6 +1255,59 @@ export class AgentComposeClient {
     );
   }
 
+  /** The conflict PREFLIGHT: which of the session's changed files would
+   *  conflict with main if merged right now — the real merge's own per-file
+   *  classification, report-only (no writes, no locks). Read-tier.
+   *  Discriminate on `state`: `pending` means a cold compute is still
+   *  running — poll again to collect it; `unavailable` = no cheap anchors
+   *  (legacy plane / unbranched) — degrade honestly. */
+  getSessionChangePreflight(conversationId: string): Promise<SessionChangePreflight> {
+    return this.fetch<SessionChangePreflight>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/preflight`,
+    );
+  }
+
+  /** Rebase the session's branch ON main — fold main's current state
+   *  into the session's workspace (the reverse merge; main is never
+   *  touched). Conflicting files KEEP the session's version: each is
+   *  recorded as a conflict row and the session is told in-conversation to
+   *  reconcile. Write-tier — a session's own toolbelt key may rebase its
+   *  OWN branch (unlike merge/discard, which need a human). Pass
+   *  `opts.branch` to fail 409 `branch_changed` if it rotated since review.
+   *
+   *  Failures: 409 `plane_unsupported` (legacy drive plane) |
+   *  `review_session_scratch` | `branch_moved` (the branch advanced
+   *  mid-rebase — retry) | `turn_active` | `decision_in_progress` |
+   *  `freshen_failed` / `merge_retry` (mount mid-handoff — retry); 400
+   *  `no_branch`; 502 `rebase_failed` (nothing changed — retry-safe). */
+  rebaseSessionChanges(
+    conversationId: string,
+    opts: { branch?: string } = {},
+  ): Promise<SessionRebaseReport> {
+    return this.fetch<SessionRebaseReport>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/rebase`,
+      { method: "POST", body: opts.branch ? { branch: opts.branch } : {} },
+    );
+  }
+
+  /** 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)
@@ -1167,10 +1399,15 @@ export class AgentComposeClient {
    *  scoped, not surface-scoped: any member can cancel, whichever surface
    *  started the turn. The canceled turn closes with a terminal error part
    *  (it is never re-run); a message sent after it stays queued and is
-   *  answered next. `canceled: false` = nothing was in flight. Requires
+   *  answered next. `canceled: false` = nothing was in flight. `owed`
+   *  reports the queued-backlog kick: 'dispatched' = a turn answering the
+   *  queue was started by this call; 'held' = a live release loop owns the
+   *  backlog; 'none' = nothing queued (absent on older servers). Requires
    *  the `invoke` scope. */
-  cancelConversationTurn(conversationId: string): Promise<{ canceled: boolean }> {
-    return this.fetch<{ canceled: boolean }>(
+  cancelConversationTurn(
+    conversationId: string,
+  ): Promise<{ canceled: boolean; owed?: "dispatched" | "held" | "none" }> {
+    return this.fetch<{ canceled: boolean; owed?: "dispatched" | "held" | "none" }>(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/cancel-turn`,
       { method: "POST", body: {} },
     );
@@ -1233,6 +1470,33 @@ export class AgentComposeClient {
     );
   }
 
+  /** List a factory drive's files — a flat recursive listing, cursor-
+   *  paginated by path. The live index by default; pass `at` (a retained
+   *  64-hex commit) to browse the MAIN drive as of that head — read-only
+   *  time travel, with `branch` + `at` pinning a graph branch instead. A
+   *  garbage-collected/unknown head throws 410 `at_unavailable`. */
+  async listFactoryFiles(opts?: ListFactoryFilesOptions): Promise<FactoryFileListPage> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const q = new URLSearchParams();
+    if (opts?.prefix) q.set("prefix", opts.prefix);
+    if (opts?.cursor) q.set("cursor", opts.cursor);
+    if (opts?.limit != null) q.set("limit", String(opts.limit));
+    if (opts?.branch !== undefined) q.set("branch", opts.branch);
+    if (opts?.at !== undefined) q.set("at", opts.at);
+    const qs = q.toString();
+    const wire = await this.fetch<FactoryFileListWire>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files${qs ? `?${qs}` : ""}`,
+    );
+    return {
+      data:       wire.data,
+      hasMore:    wire.has_more,
+      nextCursor: wire.next_cursor,
+      at:         wire.at ? { head: wire.at.head, committedAt: wire.at.committed_at } : null,
+    };
+  }
+
   /** 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. */
@@ -1684,6 +1948,58 @@ export class AgentComposeClient {
     return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
   }
 
+  // ── Session secrets ─────────────────────────────────────────────────────────
+  // Per-session env for a cloud session's sandbox, keyed by the session's
+  // CONVERSATION id. Values are write-only (set/rotate/delete — never read
+  // back); each secret has an OWNER (the user who set it) and only the owner
+  // or a team admin may replace/remove it. `source: "factory"` entries attach
+  // a factory secret BY NAME instead of carrying a value. Changes apply from
+  // the session's next turn.
+
+  /** List a session's secrets (names + metadata only — values are never returned). */
+  async listSessionSecrets(conversationId: string): Promise<SessionSecretEntry[]> {
+    const body = await this.fetch<{ secrets: SessionSecretEntry[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets`);
+    return body.secrets;
+  }
+
+  /** Set session secrets (bulk-friendly): value entries and/or `source:
+   *  "factory"` attachments-by-name. Returns the keys that were set. */
+  async setSessionSecrets(conversationId: string, secrets: SessionSecretInput[]): Promise<string[]> {
+    const body = await this.fetch<{ set: string[] }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets`,
+      { method: "POST", body: { secrets } });
+    return body.set;
+  }
+
+  /** Delete one session secret (owner or team admin). */
+  deleteSessionSecret(conversationId: string, key: string): Promise<void> {
+    return this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secrets/${encodeURIComponent(key)}`,
+      { method: "DELETE" });
+  }
+
+  /** Mint a VAULT LINK for this session — a short-lived, single-use page
+   *  where a session writer types the named credentials straight into the
+   *  session's secret store (they never transit the chat). Posts a card
+   *  into the session conversation; callable with the session's own
+   *  toolbelt credential (the in-sandbox agent's door) or by a session
+   *  writer. */
+  requestSessionSecrets(
+    conversationId: string, keys: string[], opts?: { reason?: string },
+  ): Promise<SessionSecretRequestCreated> {
+    return this.fetch(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/secret-requests`,
+      { method: "POST", body: { keys, ...(opts?.reason ? { reason: opts.reason } : {}) } });
+  }
+
+  /** Poll a vault link's status (`pending` → `fulfilled`; `expired` when the
+   *  clock ran out). 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)}`);
+  }
+
   // ── API keys ───────────────────────────────────────────────────────────────
   // Both endpoints require an admin-scoped key as the bearer token.
 

package/src/display.ts

@@ -70,7 +70,11 @@ export type DisplayMarker =
   | { kind: "image"; path: string; factorySlug?: string }
   | { kind: "table"; columns: DisplayTableColumn[]; rows: Array<Record<string, DisplayTableCell>>; truncated: boolean }
   | { kind: "chart"; chartKind: DisplayChartKind; series: DisplayChartSeries[]; xLabel?: string; yLabel?: string }
-  | { kind: "ask"; askId: string; prompt: string; options?: DisplayAskOption[]; freeText: boolean };
+  | { kind: "ask"; askId: string; prompt: string; options?: DisplayAskOption[]; freeText: boolean }
+  /** A desktop snapshot (`agentc display desktop`): the CLI captured the
+   *  session VM's screen to `path` on the session's drive branch. The card
+   *  renders the snapshot + an "Open desktop" door to the live surface. */
+  | { kind: "desktop"; path: string; factorySlug?: string; capturedAt?: string; note?: string };
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -273,6 +277,9 @@ export function clampAskOptions(raw: unknown): DisplayAskOption[] {
   return options;
 }
 
+/** Desktop-snapshot note bound — one caption line on the card. */
+export const DESKTOP_NOTE_MAX_CHARS = 200;
+
 /** One-line JSON marker — exactly what `agentc display` prints. */
 export function serializeDisplayMarker(marker: DisplayMarker): string {
   return JSON.stringify({ [DISPLAY_MARKER_KEY]: DISPLAY_MARKER_VERSION, ...marker });
@@ -350,6 +357,21 @@ export function parseDisplayMarker(line: string): DisplayMarker | null {
         ...(yLabel !== undefined ? { yLabel } : {}),
       };
     }
+    case "desktop": {
+      const path = str("path");
+      if (!path || !isPlausibleDrivePath(path)) return null;
+      // capturedAt must parse as a real instant — a garbage stamp is
+      // dropped rather than rendered as "Invalid Date" on the card.
+      const capturedAt = str("capturedAt");
+      const capturedOk = capturedAt !== undefined && Number.isFinite(Date.parse(capturedAt));
+      const note = str("note");
+      return {
+        kind: "desktop", path,
+        ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
+        ...(capturedOk ? { capturedAt } : {}),
+        ...(note !== undefined ? { note: note.slice(0, DESKTOP_NOTE_MAX_CHARS) } : {}),
+      };
+    }
     case "ask": {
       const askId = str("askId");
       const rawPrompt = str("prompt");
@@ -384,6 +406,9 @@ export type AgentcInvocation =
   | { verb: "display-document"; path: string; factorySlug?: string }
   | { verb: "display-plan" }
   | { verb: "display-image"; path: string; factorySlug?: string }
+  /** `agentc display desktop` — the CLI captures the screen itself, so the
+   *  call has no positional path; the marker in the result names the file. */
+  | { verb: "display-desktop" }
   /** Directive verb — detection only arms the tool_call promotion; the
    *  result keeps its raw output so the directive marker reaches the cloud
    *  executor. Same for table `source:"file"`, diff, and ask-with-approver. */
@@ -432,6 +457,7 @@ const VALUE_FLAGS = new Set([
   "--factory", "--input", "--entries", "--url", "--api-key", "--limit",
   "--thread", "--content-type", "--file", "--out", "--revision", "--ended-at",
   "--data", "--kind", "--from", "--to", "--prompt", "--options", "--approver",
+  "--note",
 ]);
 
 /** Detect a known agentc invocation inside a shell command string. Returns
@@ -514,6 +540,8 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
         const path = drivePath(args[2]);
         return path ? { verb: "display-image", path, ...withSlug } : null;
       }
+      case "desktop":
+        return { verb: "display-desktop" };
       case "preview": {
         const path = drivePath(args[2]);
         return path ? { verb: "display-preview", path } : null;
@@ -700,6 +728,8 @@ export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): Display
           return call("display_plan", {});
         case "display-image":
           return call("display_image", { path: invocation.path, ...factoryRef(invocation.factorySlug) });
+        case "display-desktop":
+          return call("display_desktop", {});
         case "display-preview":
           return call("display_preview", { path: invocation.path, ...factoryRef(undefined) });
         case "display-table":
@@ -789,6 +819,19 @@ export function createDisplayPromoter(ctx: DisplayPromoterContext = {}): Display
             ...factoryRef(m?.factorySlug ?? inv.factorySlug),
           })];
         }
+        case "display-desktop": {
+          // No marker → the capture failed before it could name a file —
+          // keep the raw output (the CLI's own error is the feedback);
+          // a desktop card without a snapshot would lie.
+          const marker = findDisplayMarker(text);
+          if (marker?.kind !== "desktop") return [result(msg.output)];
+          return [result({
+            path: marker.path,
+            ...factoryRef(marker.factorySlug),
+            capturedAt: marker.capturedAt ?? null,
+            note: marker.note ?? null,
+          })];
+        }
         case "display-table": {
           // File-sourced tables are a DIRECTIVE: keep the raw output so the
           // marker inside it reaches the cloud executor (the real card pair).