@agent-compose/sdk 0.8.1 → 0.8.2

package/dist/types/api-conversations.d.ts

@@ -101,6 +101,9 @@ export interface ConversationMessageRow {
     reactions: Record<string, string[]>;
     replyCount: number;
     lastReplyAt: string | null;
+    /** When the author last edited the content; null/absent = never edited
+     *  (absent on older servers). */
+    editedAt?: string | null;
     createdAt: string;
     /** Thread-root facepile (≤3) — present only on roots with replies. */
     replyAuthors?: Array<{
@@ -172,6 +175,16 @@ export interface ConversationDetail {
      *  affordances only; the server remains the authority on every action.
      *  Public channels report implicit `write` for non-member teammates. */
     viewerRole: ConversationMemberRole;
+    /** Provenance when `viewerRole` is DERIVED rather than held: the project
+     *  (ADR-0045 read floor) or attached channel (ADR-0057) the viewer
+     *  follows this conversation through. Null/absent for real members —
+     *  clients use it to explain read-only honestly ("You follow this
+     *  session through <project>…"). Absent on older servers. */
+    viewerRoleVia?: {
+        kind: "project" | "channel";
+        id: string;
+        name: string | null;
+    } | null;
     /** SSE replay watermark: the conversation's highest durable stream-event
      *  id at hydrate time — everything at or below it is already folded into
      *  `messages`. Seed the stream's first `Last-Event-ID` from it instead of
@@ -257,6 +270,15 @@ export interface CreateCloudSessionInput {
         contentB64: string;
         mode: "write" | "append";
     }>;
+    /** DIFF REVIEW spawn: the conversation whose proposed changes this
+     *  session is born to review. Server-resolved: on a graph-plane drive
+     *  the new session's branch is minted as a FORK of the reviewed branch
+     *  (its working dir IS the proposal, `.review/` comparison materials
+     *  included); on the legacy plane the spawn degrades to an ordinary
+     *  session. Requires a human caller and a chat session on the reviewed
+     *  session's factory; 409 `review_of_review` when the target is itself
+     *  a review session. */
+    reviewOfConversationId?: string;
 }
 export interface CloudSessionCreated {
     conversation: ConversationRow;
@@ -326,6 +348,14 @@ export interface SessionForked {
     /** The new child conversation to switch to. */
     conversationId: string;
 }
+/** Result of holding a session's background-work busy lease
+ *  (`POST /conversations/:id/background-work`). While the lease is live the
+ *  between-turns park/suspend leaves the session's VM running; it lapses on
+ *  its own — re-hold to extend. */
+export interface BackgroundWorkHeld {
+    /** ISO timestamp the lease now runs to. */
+    leaseUntil: string;
+}
 /** One changed file on a session's drive branch relative to `main`. */
 export interface SessionFileChange {
     /** Factory-relative path. */
@@ -357,6 +387,131 @@ export interface SessionChangeSet {
     truncated: boolean;
     /** Open `factory_file_conflicts` rows from this session's prior merges. */
     openConflicts: number;
+    /** MERGE GATE (merge-gate spec, additive — absent on older servers):
+     *  null = ungated. Present: whether THIS caller's merge lands directly
+     *  (`canMerge` — an owner or named approver) or stages a kind='merge'
+     *  approval instead (`mergeSessionChanges` answers 202
+     *  `SessionMergeGated`), plus the resolved approver set. */
+    mergeGate?: {
+        enabled: true;
+        canMerge: boolean;
+        approvers: Array<{
+            userId: string;
+            label: string | null;
+        }>;
+    } | null;
+    /** The OPEN kind='merge' approval already waiting on this session's
+     *  branch, if any (additive — absent on older servers). */
+    pendingApprovalId?: string | null;
+    /** DIFF REVIEW (additive — absent on older servers): notes written back
+     *  by a spawned review session, whether they predate the served diff
+     *  (`reviewStale` — the changed-file signature no longer matches), the
+     *  bound review session's conversation + whether it is still live, and
+     *  whether the deployment offers reviews at all (`reviewEnabled`; false
+     *  hides the affordance). Reviews are USER-TRIGGERED only — binding
+     *  rides `POST /conversations/:id/changes/review`, and notes arrive
+     *  through the review session's own gated write-back. */
+    reviewNotes?: string | null;
+    reviewStale?: boolean;
+    reviewEnabled?: boolean;
+    reviewSessionConversationId?: string | null;
+    reviewSessionActive?: boolean;
+    /** STRUCTURED review suggestions beside the notes (additive — absent on
+     *  older servers): individually actionable {id, path, title, rationale,
+     *  patch} entries the review session wrote back, status-stamped
+     *  `"proposed"` by the server (`"accepted"`/`"rejected"` are reserved for
+     *  the human decision pass). */
+    reviewSuggestions?: ReviewSuggestion[];
+    /** THE REVIEWER MARKER (additive — absent on older servers): non-null ⇒
+     *  THIS session was born to review that conversation's diff. Its own
+     *  branch is a fork of the reviewed branch and can never merge
+     *  (`mergeable` false, merge 409s `fork_branch_unmergeable`), and it is
+     *  refused as a review target (409 `review_of_review`). */
+    reviewOfConversationId?: string | null;
+}
+/** One STRUCTURED, individually actionable suggestion a review session
+ *  wrote back beside its notes (`SessionChangeSet.reviewSuggestions`). */
+export interface ReviewSuggestion {
+    /** Reviewer-minted stable id — survives full-replace re-posts. */
+    id: string;
+    /** The changed file the suggestion targets (always in the change set —
+     *  the writeback refuses paths outside it). */
+    path: string;
+    title: string;
+    rationale: string;
+    /** Unified-diff hunk targeting the PROPOSED side of `path`. */
+    patch: string;
+    /** Server-stamped `"proposed"` at writeback; the HUMAN decision routes
+     *  (`POST …/changes/suggestions/:suggestionId/decide` / `…/decide-all`)
+     *  are the only writers of the rest — `"accepted"` (the patch landed on
+     *  the session branch), `"rejected"`, or `"stale"` (an accept found the
+     *  file drifted since review; nothing was written). */
+    status: "proposed" | "accepted" | "rejected" | "stale";
+}
+/** `POST /conversations/:id/changes/suggestions/:suggestionId/decide` —
+ *  the post-call truth for that suggestion (an accept that found drift
+ *  answers `"stale"`; repeats on a settled row are no-ops). */
+export interface ReviewSuggestionDecision {
+    object: "review_suggestion_decision";
+    conversationId: string;
+    id: string;
+    status: ReviewSuggestion["status"];
+}
+/** `POST /conversations/:id/changes/suggestions/decide-all` — every stored
+ *  suggestion's post-call status (only `"proposed"` rows flip). */
+export interface ReviewSuggestionDecisions {
+    object: "review_suggestion_decisions";
+    conversationId: string;
+    results: Array<{
+        id: string;
+        status: ReviewSuggestion["status"];
+    }>;
+}
+/** `GET /conversations/:id/changes/stats` — the changes chip's aggregate
+ *  +added/−removed line counts, cached server-side per (base, theirsHead).
+ *  `unavailable` = no cheap head anchors (legacy plane, unbranched) — the
+ *  chip degrades to its file count, never fake zeros. */
+export type SessionChangeStats = {
+    object: "session_change_stats";
+    conversationId: string;
+    state: "unavailable";
+} | {
+    object: "session_change_stats";
+    conversationId: string;
+    state: "ok";
+    additions: number;
+    deletions: number;
+    files: number;
+    /** True when the count is partial (list truncated / file cap). */
+    truncated: boolean;
+    base: string;
+    theirsHead: string;
+};
+/** `POST /conversations/:id/changes/review` — binds a just-spawned review
+ *  session to the reviewed session and stamps the diff signature the
+ *  review covers. */
+export interface SessionDiffReviewBound {
+    object: "session_diff_review";
+    conversationId: string;
+    reviewSessionConversationId: string;
+    reviewDiffSignature: string;
+}
+/** 202 from `POST /conversations/:id/changes/merge` on a merge-GATED
+ *  session when the caller is not an approver: nothing merged — the ask
+ *  froze into (`approval_required`) or converged on (`approval_pending`) a
+ *  kind='merge' approval routed to the approvers. */
+export interface SessionMergeGated {
+    object: "session_merge_gated";
+    conversationId: string;
+    code: "approval_required" | "approval_pending";
+    approvalId: string;
+    branch?: string;
+    changeCount?: number;
+    openConflicts?: number;
+    approvers: Array<{
+        userId: string;
+        label: string | null;
+    }>;
 }
 /** Per-file accounting of one session branch merge — the merge core's
  *  honest report, returned verbatim. */
@@ -425,6 +580,14 @@ export interface SendConversationMessageInput {
  *  streaming; `queued` = a turn is already in flight — the message is owed
  *  work and a coalesced follow-up turn will answer it. NOT an error. */
 export type ConversationTurnState = "none" | "started" | "queued";
+/** One @-mentioned user the server DROPPED as a non-member — the mention
+ *  ping went to nobody, and the response says so instead of staying
+ *  silent. `name` is the label the sender's own text carried for the
+ *  mention (picked in the typeahead — no new information). */
+export interface UnnotifiedMention {
+    userId: string;
+    name: string;
+}
 export interface SendConversationMessageResult {
     /** The persisted user message's id. */
     messageId: string;
@@ -437,6 +600,10 @@ export interface SendConversationMessageResult {
      *  each runs its own turn in its own conversation. Absent on older
      *  servers and non-channel sends. */
     relayedSessionIds?: string[];
+    /** Mentioned users whose ping was dropped by the member filter (a
+     *  private channel pings members only; a DM pings only the pair) —
+     *  present only when non-empty. Absent on older servers. */
+    unnotifiedMentions?: UnnotifiedMention[];
 }
 /** Response of the presence heartbeat (ADR-0037 §6): a fresh agent-liveness
  *  snapshot + the roster TTL. The attach roster itself is NOT returned —

package/dist/types/api-factory.d.ts

@@ -284,6 +284,25 @@ export interface ApiKey {
 export interface ApiKeyCreated extends ApiKey {
     key: string;
 }
+/** Options for `GET /api-keys` — the list is bounded and keyset-paginated
+ *  (every run step / session boot mints a key row, so "all keys ever" is
+ *  unbounded by construction). */
+export interface ListApiKeysOptions {
+    /** Page size, 1–200 (server default 100). */
+    limit?: number;
+    /** `active` = unrevoked + unexpired only; `all` (default) includes
+     *  revoked/expired history. */
+    status?: "active" | "all";
+    /** Opaque cursor from a previous page's `nextCursor`. */
+    cursor?: string;
+}
+/** One page of `GET /api-keys`. */
+export interface ApiKeyPage {
+    data: ApiKey[];
+    hasMore: boolean;
+    /** Pass as `cursor` to fetch the next page; null on the last page. */
+    nextCursor: string | null;
+}
 /** Single rollup row from `GET /api/v1/usage`. */
 export interface UsageRollupRow {
     eventType: string;
@@ -300,7 +319,10 @@ export interface UsageResponse {
     to: string | null;
 }
 /** One drive-directory ⇄ GitHub-repo link (`/factories/:slug/repo-links`).
- *  The webhook secret ref is operator plumbing and never on the wire. */
+ *  Multi-branch model: ONE link row per (repo, branch); sibling branches
+ *  of a repo occupy sibling `base@<branch>` placements. The webhook secret
+ *  ref is operator plumbing and never on the wire — `webhookConfigured` /
+ *  `webhookVerifiedAt` carry the honest connect status instead. */
 export interface DriveRepoLink {
     id: string;
     factoryId: string;
@@ -310,25 +332,55 @@ export interface DriveRepoLink {
     provider: string;
     /** "org/repo". */
     repoFullName: string;
-    /** The GitHub branch drive `main` syncs with. */
+    /** The GitHub branch this link's placement syncs with. */
     trackedBranch: string;
     connectorGrantId: string | null;
     /** v1 links are always 'write' (the round trip is the feature). */
     access: "read" | "write";
+    /** A webhook secret exists for this link (registration done). NOT proof
+     *  of delivery — that is `webhookVerifiedAt`. */
+    webhookConfigured: boolean;
+    /** When a signed GitHub delivery last PROVED the webhook delivers; null
+     *  = unproven (the link syncs by poll). */
+    webhookVerifiedAt: string | null;
+    /** Two-way sync: drive edits under the prefix push back to the tracked
+     *  branch. ON by default for new links. */
+    pushOutEnabled: boolean;
+    /** Follow-all mode (stamped identically on every sibling link of one
+     *  repo): pushes to NEW branches auto-link them; GitHub branch deletes
+     *  auto-unlink. False = explicit selection. */
+    followAllBranches: boolean;
+    /** Branches follow-all could NOT link (with the reason) — stamped on
+     *  the repo's PRIMARY link row only; empty everywhere else. */
+    autoLinkSkips: Array<{
+        branch: string;
+        reason: string;
+        at: string;
+    }>;
     lastSyncedGitSha: string | null;
     lastSyncedAcgCommit: string | null;
-    syncState: "idle" | "syncing" | "diverged" | "reauth_required";
-    visibility: "team" | "restricted";
+    syncState: "idle" | "syncing" | "pushing" | "error" | "conflict" | "diverged" | "reauth_required";
+    /** Human-readable detail when syncState is 'error' or 'conflict'. */
+    syncError: string | null;
     createdBy: string | null;
     lastSyncedAt: string | null;
     createdAt: string;
 }
 /** Input for `POST /factories/:slug/repo-links`. Requires the drive to be
- *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise. */
+ *  graph-authoritative (ADR-0058 Phase 4 promoted) — 409 otherwise.
+ *  Exactly ONE of `followAllBranches` / `trackedBranches`:
+ *  `followAllBranches: true` (the default connect mode) links EVERY
+ *  branch — default branch primary at the plain `dirPrefix` — and keeps
+ *  following live (new branches auto-link on push, deleted branches
+ *  auto-unlink; capped at 100 branches). Explicit `trackedBranches`:
+ *  index 0 is the PRIMARY and keeps the plain placement; every additional
+ *  branch lands at the sibling `dirPrefix@<sanitized-branch>` placement. */
 export interface CreateDriveRepoLinkInput {
     dirPrefix: string;
     repoFullName: string;
-    trackedBranch: string;
+    trackedBranches?: string[];
+    followAllBranches?: boolean;
     connectorGrantId: string;
-    visibility?: "team" | "restricted";
+    /** Two-way sync ("push-out") — defaults to TRUE for new links. */
+    pushOut?: boolean;
 }

package/dist/types/api-runs.d.ts

@@ -283,7 +283,8 @@ export interface ListRunsOptions {
     factorySlug?: string;
     /** Substring match on the registered workflow name (`metadata._workflow`). */
     workflow?: string;
-    /** Substring match across title / task title / branch / run id. */
+    /** Substring match across title / task title / branch — or an exact run
+     *  id (full UUID). */
     search?: string;
     outcome?: string;
     sort?: "newest" | "oldest" | "fastest" | "slowest";

package/dist/types/workflow-metadata.d.ts

@@ -146,11 +146,12 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-    /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
-     *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
-     *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
-     *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
-     *  ignores this. */
+    /** Machine hardware SKU. The vocabulary is `SANDBOX_SIZES` in
+     *  `sandbox/sizes.ts` — the single source; do not restate it here or
+     *  anywhere else. Maps to provider specs at create time: Vercel takes the
+     *  vCPU count and allocates RAM at 2048 MB/vCPU; E2B has no create-time
+     *  cpu/mem knob at all, so the size selects a PRE-BUILT per-size template
+     *  (`E2B_TEMPLATE_SIZES`). Omit → `DEFAULT_SANDBOX_SIZE`. */
     size?: SandboxSize;
     /** Sandbox provider this workflow's runs execute on — `"vercel"` or
      *  `"e2b"`. Optional and additive: omit and the run resolves to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/agent/agent-context.ts

@@ -173,38 +173,49 @@ there is nothing to type, paste, or screenshot a credential from.
 
 ## Recording a demo — the desktop, captured to a video the human can play
 
-"Record a demo of you using X" is a normal ask, and this machine does it:
-start a screen recording, drive the app with \`xdotool\` exactly as in Computer
-Use, stop the recording, and report the file. (For a LIVE view no recording is
-needed — the session header's **Desktop** button already streams this display
-to any teammate watching; a recording is the durable, replayable artifact.
-Both modes exist; say so when it matters.)
+"Record a demo of you using X" is a normal ask, and this machine does it.
+(For a LIVE view no recording is needed — the session header's **Desktop**
+button already streams this display to any teammate watching; a recording is
+the durable, replayable artifact. Both modes exist; say so when it matters.)
 
-**ffmpeg is NOT pre-installed** — install it first, once per machine:
+**Use \`ac-record\` — the platform recorder is already on PATH** (cloud
+sessions; \`command -v ac-record\` to confirm on older machines):
 
-    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+    ac-record start     # begins capturing the desktop (display :0)
+    # ... drive the app with xdotool, screenshotting as you go ...
+    ac-record stop      # finishes + saves to recordings/ in your workspace
+    ac-record status    # one JSON line: {"recording":true,...}
+
+It records the whole display (with desktop audio when the machine has a
+PulseAudio monitor), enforces sane caps (5 min / 200 MB — start a fresh
+recording per scene rather than one long take), keeps the file playable even
+if the machine dies mid-take, and \`stop\` prints the saved path — the file
+lands ON THE DRIVE in \`recordings/\`, visible in Files and playable in the
+dashboard. A human watching the Desktop pane sees the recording indicator
+while you record.
 
-(drop \`sudo\` if you are already root). Then the whole recipe:
+If \`ac-record\` is missing (older machine), record by hand.
+**ffmpeg IS pre-installed** on platform images (\`command -v ffmpeg\`; only
+if absent: \`sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\`):
 
     DISPLAY=:0 ffmpeg -f x11grab \\
       -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
       -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
       demo.webm &
     FFMPEG_PID=$!
-    # ... drive the app with xdotool, screenshotting as you go ...
+    # ... drive the app with xdotool ...
     kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
 
-The gotchas, each one earned:
+The hand-rolled gotchas, each one earned:
 - **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
   file on SIGINT; a hard kill truncates the encode mid-write.
-- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
-  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
-  playable up to the last written frame and plays natively in the browser.
-  MP4's only edge is compatibility with some external players — transcode
-  afterwards if you truly need it, never record straight to it.
+- **Record WebM (matroska-family), not plain MP4** — mp4 writes its moov atom
+  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm
+  stays playable up to the last written frame and plays natively in the
+  browser. (\`ac-record\` sidesteps this with fragmented mp4.)
 - **\`-video_size\` must match the real screen** — x11grab does not default to
   it; read the geometry from \`xdotool getdisplaygeometry\` as above.
-- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+- **10–15 fps is right for a screen demo** — small files, legible UI motion;
   this is not video production.
 - **Write to the drive, not /tmp** — the recording must land in your working
   directory to persist and show up in Files; a file in /tmp dies with the

package/src/client.ts

@@ -31,8 +31,8 @@ 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,
   SendConversationMessageInput, SendConversationMessageResult,
   ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
   ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
@@ -52,7 +52,7 @@ import type {
   FactoryRow, CreateFactoryInput, UpdateFactoryInput,
   ScheduleRow, CreateScheduleInput,
   SecretOptions, SetSecretResult, SecretListEntry,
-  CreateApiKeyInput, ApiKey, ApiKeyCreated, UsageResponse,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
   DriveMountSession, CreateDriveMountSessionInput,
 } from "./types/api-factory.js";
@@ -82,11 +82,12 @@ 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,
+  ReviewSuggestionDecision, ReviewSuggestionDecisions,
+  SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
   ConversationPageContext, SendConversationMessageInput, ConversationTurnState,
-  SendConversationMessageResult, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
+  SendConversationMessageResult, UnnotifiedMention, ConversationPresenceSnapshot, AgentListRow, StreamConversationOptions,
   ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
 } from "./types/api-conversations.js";
 export type {
@@ -108,7 +109,7 @@ export type {
   FactoryRow, CreateFactoryInput, UpdateFactoryInput,
   ScheduleRow, CreateScheduleInput,
   SecretOptions, SetSecretResult, SecretListEntry,
-  CreateApiKeyInput, ApiKey, ApiKeyCreated,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
   DriveMountSession, CreateDriveMountSessionInput,
@@ -984,6 +985,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." */
@@ -1017,6 +1040,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 +1054,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 } : {} },
     );
@@ -1608,17 +1636,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). */
@@ -1668,10 +1697,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 ──────────────────────────────────────────────────────────────────

package/src/index.ts

@@ -125,7 +125,7 @@ export type {
   RunListEntry, ListRunsOptions, RunDetail,
   FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse,
   RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
-  ApiKey, ApiKeyCreated,
+  ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   CancelRunResponse,
   RequestAgentPauseOptions, RequestAgentPauseResponse,
@@ -135,13 +135,15 @@ export type {
   ConversationMessagePart, ConversationRow, ConversationMessageRow,
   ConversationsPage, ConversationDetail, ConversationThread,
   ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult,
+  UnnotifiedMention,
   ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
   CreateCloudSessionInput, CloudSessionCreated,
   // Cloud-session developer surface (ADR-0052)
-  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
+  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked, BackgroundWorkHeld,
   // Session branch proposals (ADR-0053)
-  SessionFileChange, SessionChangeSet,
-  SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport,
+  SessionFileChange, SessionChangeSet, SessionChangeStats, SessionDiffReviewBound, ReviewSuggestion,
+  ReviewSuggestionDecision, ReviewSuggestionDecisions,
+  SessionMergeReportDetail, SessionMergeReport, SessionMergeGated, SessionDiscardReport,
   // User drive mounts (`agentc files mount` on a human's own machine)
   DriveMountSession, CreateDriveMountSessionInput,
   // Channel-attached sessions (ADR-0057)
@@ -278,8 +280,11 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves,
   makeSandboxProvider, makeDesktopSandboxProvider,
   parseSseExecStream, AGENT_COMPOSE_TAG,
-  SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES,
-  isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
+  SANDBOX_SIZES, SANDBOX_MACHINES, SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, SESSION_DEFAULT_SANDBOX_SIZE,
+  E2B_TEMPLATE_SIZES, E2B_MAX_VCPUS, E2B_MAX_MEMORY_MB,
+  VERCEL_MEMORY_MB_PER_VCPU,
+  isE2bSupportedSize, isVercelSupportedSize, sandboxSizeLabel,
+  e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
   isPlatformE2bTemplateAlias,
   // ADR-0038 "Computer" — the per-member persistent desktop machine template.
   E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION,