@agent-compose/sdk 0.8.1 → 0.8.3

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";
@@ -31,11 +31,15 @@ import type {
   TeamMember, Mention, CreateMentionsInput,
   ConversationsPage, SessionsPage, ConversationDetail, ConversationThread,
   CreateCloudSessionInput, CloudSessionCreated,
-  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
-  SessionChangeSet, SessionMergeReport, SessionDiscardReport,
+  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,10 +53,11 @@ 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,
-  CreateApiKeyInput, ApiKey, ApiKeyCreated, UsageResponse,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
   DriveMountSession, CreateDriveMountSessionInput,
 } from "./types/api-factory.js";
@@ -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,
@@ -82,12 +88,17 @@ export type {
   ConversationMessagePart, ConversationRow, ConversationMessageRow,
   ConversationsPage, SessionsPage, ConversationDetail,
   CreateCloudSessionInput, CloudSessionCreated, ConversationThread,
-  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
-  SessionFileChange, SessionChangeSet,
-  SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport,
+  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, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
+  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,
@@ -104,11 +115,12 @@ 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,
-  CreateApiKeyInput, ApiKey, ApiKeyCreated,
+  SecretOptions, SetSecretResult, SecretListEntry, SessionSecretEntry, SessionSecretInput, SessionSecretRequestCreated, SessionSecretRequestStatus,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
   DriveMountSession, CreateDriveMountSessionInput,
@@ -164,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. */
@@ -652,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> {
@@ -744,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)
@@ -755,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" },
@@ -767,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));
   }
@@ -840,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. */
@@ -944,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
@@ -984,6 +1091,28 @@ export class AgentComposeClient {
     return body.closed;
   }
 
+  /** Hold (or extend — the stamp is monotone) a cloud session's
+   *  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> {
+    return this.fetch<BackgroundWorkHeld>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`,
+      { method: "POST", body: { ...(input?.minutes !== undefined ? { minutes: input.minutes } : {}) } },
+    );
+  }
+
+  /** 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> {
+    const body = await this.fetch<{ released: boolean }>(
+      `/api/v1/conversations/${encodeURIComponent(conversationId)}/background-work`,
+      { method: "DELETE" },
+    );
+    return body.released;
+  }
+
   /** Fork a cloud session from HEAD: snapshot the VM + branch the drive + seed
    *  a new conversation from the transcript so far, booting from both. Returns
    *  the child conversation id to switch to. Write-tier; "Branch from here." */
@@ -1006,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" },
     );
   }
 
@@ -1017,6 +1219,11 @@ export class AgentComposeClient {
    *  `main`. Write-tier + human caller. Pass `opts.branch` (the branch you
    *  reviewed) to fail 409 `branch_changed` if it moved since.
    *
+   *  On a merge-GATED session (merge-gate spec) a non-approver's call does
+   *  NOT merge: it answers 202 `SessionMergeGated` — the ask froze into (or
+   *  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
@@ -1026,8 +1233,8 @@ export class AgentComposeClient {
   mergeSessionChanges(
     conversationId: string,
     opts: { branch?: string } = {},
-  ): Promise<SessionMergeReport> {
-    return this.fetch<SessionMergeReport>(
+  ): Promise<SessionMergeReport | SessionMergeGated> {
+    return this.fetch<SessionMergeReport | SessionMergeGated>(
       `/api/v1/conversations/${encodeURIComponent(conversationId)}/changes/merge`,
       { method: "POST", body: opts.branch ? { branch: opts.branch } : {} },
     );
@@ -1048,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)
@@ -1139,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: {} },
     );
@@ -1205,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. */
@@ -1608,17 +1900,18 @@ export class AgentComposeClient {
     return body.links;
   }
 
-  /** Link a drive directory to a GitHub repo + tracked branch (`manage`
-   *  scope). Requires the drive to be graph-authoritative — 409 names the
-   *  promotion prerequisite otherwise. */
+  /** Link a drive directory to a GitHub repo's tracked BRANCHES (`manage`
+   *  scope) — one link row per branch, created in one action. Requires the
+   *  drive to be graph-authoritative — 409 names the promotion
+   *  prerequisite otherwise. */
   async createRepoLink(
     input: CreateDriveRepoLinkInput, opts?: { factorySlug?: string },
-  ): Promise<DriveRepoLink> {
+  ): Promise<DriveRepoLink[]> {
     const slug = opts?.factorySlug ?? DEFAULT_FACTORY;
-    const body = await this.fetch<{ link: DriveRepoLink }>(
+    const body = await this.fetch<{ links: DriveRepoLink[] }>(
       `/api/v1/factories/${encodeURIComponent(slug)}/repo-links`,
       { method: "POST", body: input });
-    return body.link;
+    return body.links;
   }
 
   /** Unlink (§6.3: the prefix's files and history stay on the drive). */
@@ -1655,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.
 
@@ -1668,10 +2013,17 @@ export class AgentComposeClient {
   }
 
   /** List API keys on the caller's team (metadata only — plaintext keys are
-   *  never returned). */
-  async listApiKeys(): Promise<ApiKey[]> {
-    const body = await this.fetch<{ object: "list"; data: ApiKey[]; has_more: boolean }>("/api-keys");
-    return body.data;
+   *  never returned). Bounded + keyset-paginated: pass `cursor` from the
+   *  previous page's `nextCursor` to walk forward. */
+  async listApiKeys(opts?: ListApiKeysOptions): Promise<ApiKeyPage> {
+    const qs = new URLSearchParams();
+    if (opts?.limit  !== undefined) qs.set("limit", String(opts.limit));
+    if (opts?.status !== undefined) qs.set("status", opts.status);
+    if (opts?.cursor !== undefined) qs.set("cursor", opts.cursor);
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    const body = await this.fetch<{ object: "list"; data: ApiKey[]; has_more: boolean; next_cursor: string | null }>(
+      `/api-keys${suffix}`);
+    return { data: body.data, hasMore: body.has_more, nextCursor: body.next_cursor ?? null };
   }
 
   // ── Usage ──────────────────────────────────────────────────────────────────