@agent-compose/sdk 0.8.0 → 0.8.2

package/dist/sandbox/sizes.d.ts

@@ -1,19 +1,78 @@
 /**
- * Sandbox machine sizes + the E2B template aliases derived from them.
+ * Sandbox machine sizes — THE single source of the size vocabulary.
  *
- * A coarse hardware knob that maps to provider machine specs at create time:
- * Vercel honours it natively via `resources.vcpus`; E2B sizing is baked into
- * the template, so on E2B a size resolves to a pre-built per-size template.
+ * Everything that names a size (the server's `SANDBOX_DEFAULT_SIZE` env enum,
+ * the register/invoke zod schemas, the run + session row types, the CLI's
+ * `--size` flag, the dashboard pickers via `GET /v1/sandbox-sizes`) derives
+ * from `SANDBOX_SIZES` / `SandboxSize` here. Adding a size is a ONE-LINE edit
+ * to `SANDBOX_MACHINES`: the type, the enums, the E2B build matrix and the
+ * pickers all follow. Do NOT re-declare the union inline anywhere.
+ *
+ * A size is a coarse hardware knob that maps to provider machine specs:
+ * Vercel honours it natively via `resources.vcpus`; E2B sizing is BAKED INTO
+ * THE TEMPLATE (e2b 2.30.5 has no create-time cpu/mem knob — `NewSandbox`
+ * carries only `templateID`), so on E2B a size resolves to a pre-built
+ * per-size template.
  */
-/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
- *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
- *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
- *    4vcpu-8gb   =  4 vCPU /  8 GiB
- *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
- *                                     probed live: 16 & 32 vCPU 400 on dev)
- *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
-export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
-/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
+/** Every sandbox hardware SKU, with its real machine spec. Named for the
+ *  machine (vCPU + RAM) rather than abstract t-shirt sizes, so a size can
+ *  never quietly mean something different than it says.
+ *
+ *  RAM is 2048 MB/vCPU everywhere EXCEPT `8vcpu-8gb`, which exists because
+ *  E2B caps a sandbox at 8 vCPU / 8192 MB (e2b.dev/docs/billing: Hobby and
+ *  Pro both "8 vCPU / 8 GB", raised only by arrangement): 8 vCPU at the 2 GB
+ *  rule would need 16 GiB and cannot be built. `8vcpu-8gb` is the CPU ceiling
+ *  at the memory ceiling — the only way to get 8 cores on E2B today, and a
+ *  spec already proven bakeable by the devbox (`E2B_DEVBOX_SPEC`).
+ *
+ *  Adding an entry here automatically: widens `SandboxSize`, widens every
+ *  derived enum, and — if it fits under the E2B caps — adds it to
+ *  `E2B_TEMPLATE_SIZES`, which is what `infra/e2b-template/build.ts` and the
+ *  `sandbox-images` CI job loop over. Two templates get baked per size, so
+ *  the matrix is not free; see that workflow's header. */
+export declare const SANDBOX_MACHINES: {
+    /** 1 vCPU / 2 GiB — the cheap floor. Plenty for a terminal session or a
+     *  shell-shaped agent; tight for a big `bun install` or a browser. */
+    readonly "1vcpu-2gb": {
+        readonly vcpus: 1;
+        readonly memoryMB: 2048;
+    };
+    /** 2 vCPU / 4 GiB — the default (Vercel's own default machine too). */
+    readonly "2vcpu-4gb": {
+        readonly vcpus: 2;
+        readonly memoryMB: 4096;
+    };
+    /** 4 vCPU / 8 GiB — comfortable for builds and multi-tool agent turns. */
+    readonly "4vcpu-8gb": {
+        readonly vcpus: 4;
+        readonly memoryMB: 8192;
+    };
+    /** 8 vCPU / 8 GiB — E2B's per-sandbox CEILING (cores maxed at the memory
+     *  cap). NOT expressible on Vercel, whose RAM follows vCPUs at 2 GB each. */
+    readonly "8vcpu-8gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 8192;
+    };
+    /** 8 vCPU / 16 GiB — Vercel only; exceeds E2B's 8 GiB memory cap. */
+    readonly "8vcpu-16gb": {
+        readonly vcpus: 8;
+        readonly memoryMB: 16384;
+    };
+    /** 32 vCPU / 64 GiB — Vercel Enterprise only; far past every E2B cap. */
+    readonly "32vcpu-64gb": {
+        readonly vcpus: 32;
+        readonly memoryMB: 65536;
+    };
+};
+/** Sandbox hardware SKU. Derived from `SANDBOX_MACHINES` — never re-spelled
+ *  as an inline union. */
+export type SandboxSize = keyof typeof SANDBOX_MACHINES;
+/** The vocabulary as an ordered, smallest-first array — the shape zod
+ *  (`z.enum`), the CLI's `--size` validation, and the wire catalogue want.
+ *  Ordering is the pickers' display order, so keep it ascending. */
+export declare const SANDBOX_SIZES: readonly [SandboxSize, ...SandboxSize[]];
+/** SKU → Vercel vCPU count (Vercel's RAM follows automatically at 2048
+ *  MB/vCPU — which is why `isVercelSupportedSize` exists). */
 export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
 /** SDK fallback size when neither the caller nor the deployment specifies one.
  *  Deliberately conservative — the OPERATIONAL default is the server's
@@ -21,30 +80,61 @@ export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
  *  small matters because Vercel rate-limits creation by vCPUs-per-window
  *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
  *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
- *  workflow rather than inflating the default for everyone. */
+ *  workflow rather than inflating the default for everyone.
+ *
+ *  NOT `1vcpu-2gb`: the floor is an opt-IN for cheap sessions, not a quiet
+ *  downgrade of every existing run's machine. */
 export declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
-/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
- *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
- *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
- *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
- *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
- *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
- *  templates) only once the account's memory limit is raised. The register/
- *  invoke guards reject an unsupported E2B size before it can reach here. */
+/** SESSION default — deliberately one size up from the run default
+ *  (2026-08-13): a session's sandbox carries the full desktop toolbelt
+ *  (VS Code + Chromium + dockerd) plus the KasmVNC encoder at the 60fps
+ *  cap, and that stack swap-thrashes on 4 GiB while the encoder starves on
+ *  2 shared vCPUs. Workflow runs keep DEFAULT_SANDBOX_SIZE — no desktop,
+ *  no toolbelt weight. Sessions bill active time only (parked = storage),
+ *  so the delta applies to active hours, not the fleet. */
+export declare const SESSION_DEFAULT_SANDBOX_SIZE: SandboxSize;
+/** E2B's per-sandbox ceiling on the plans we run (e2b.dev/docs/billing —
+ *  Hobby: "8 vCPU / 8 GB"; Pro: the same, "8+" only by arrangement with
+ *  support). Recorded live too: `Template.build` 400s with "Memory can't be
+ *  higher than 8192 MiB" past the memory cap.
+ *
+ *  These two numbers are the ONLY knob for which sizes get an E2B template —
+ *  raise them after E2B raises the account limit and the build matrix (and
+ *  therefore the session picker) widens on its own. */
+export declare const E2B_MAX_VCPUS = 8;
+export declare const E2B_MAX_MEMORY_MB = 8192;
+/** The E2B sizes we pre-build a template for — DERIVED from the caps, not
+ *  hand-listed, so a new `SANDBOX_MACHINES` entry can never be offered
+ *  without a template or omitted despite fitting. E2B sizing is
+ *  template-baked (no per-create cpu/mem knob), so honouring `resources.size`
+ *  on E2B means ONE pre-built template per size; `infra/e2b-template/build.ts`
+ *  loops exactly this list. The register / invoke / session-spawn / resize
+ *  guards all reject an unsupported E2B size before it can reach a create. */
 export declare const E2B_TEMPLATE_SIZES: readonly SandboxSize[];
-/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
- *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
- *  not — the guards lean on this so the "no E2B equivalent" decision lives in
- *  exactly one place. */
+/** Is `size` one E2B can be built/booted at? False for the sizes past E2B's
+ *  8 vCPU / 8 GiB ceiling (`8vcpu-16gb`, `32vcpu-64gb`) — those run on Vercel.
+ *  The "no E2B equivalent" decision lives in exactly one place: the caps. */
 export declare function isE2bSupportedSize(size: SandboxSize): boolean;
-/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
- *  always 2048 MB/vCPU, matching the size name + Vercel parity
- *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
- *  per-size base + agent-env templates. */
+/** Vercel's fixed memory-per-vCPU ratio. Vercel takes `resources.vcpus` and
+ *  allocates RAM itself at this rate — there is no independent memory knob. */
+export declare const VERCEL_MEMORY_MB_PER_VCPU = 2048;
+/** Is `size` expressible on Vercel? Only when its RAM matches what Vercel
+ *  would allocate for that vCPU count — otherwise asking for it would hand
+ *  the caller a machine that does not match the name (`8vcpu-8gb` would come
+ *  back with 16 GiB). Vercel's own ceiling (32 vCPU, Enterprise) is a plan
+ *  matter, not a shape matter, so it is not encoded here. */
+export declare function isVercelSupportedSize(size: SandboxSize): boolean;
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. Used
+ *  by `infra/e2b-template/build.ts` to stamp the per-size base + agent-env
+ *  templates. Reads the explicit table rather than deriving RAM from vCPUs —
+ *  `8vcpu-8gb` is deliberately off the 2048 MB/vCPU line. */
 export declare function e2bMachineSpec(size: SandboxSize): {
     cpuCount: number;
     memoryMB: number;
 };
+/** Human label for a size — "2 vCPU · 4 GB". The wire catalogue carries it so
+ *  the dashboard never has to parse the id back into numbers. */
+export declare function sandboxSizeLabel(size: SandboxSize): string;
 /** Stable E2B template ALIAS for the platform base at a given size
  *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
  *  multi-account-clean: the same string resolves in any E2B account that built

package/dist/sandbox.d.ts

@@ -14,7 +14,7 @@ export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions,
 export type { SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxNetworkPolicy, } from "./sandbox/network-policy.js";
 export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
 export type { SandboxSize } from "./sandbox/sizes.js";
-export { SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES, isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate, isPlatformE2bTemplateAlias, } from "./sandbox/sizes.js";
+export { 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, } from "./sandbox/sizes.js";
 export { E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION, e2bDevboxTemplateRef, } from "./sandbox/devbox.js";
 export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";

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<{
@@ -157,11 +160,31 @@ export interface ConversationDetail {
         name: string;
         description: string;
     }> | null;
+    /** Where this conversation's UNMERGED work lives: a cloud session writes
+     *  its own private drive branch, and every drive read a client makes for
+     *  THAT factory must carry `?branch=` or it resolves against `main`,
+     *  where session-born files do not exist. Non-null only for a session
+     *  with a drive branch and a resolvable factory; null/absent = main
+     *  only (read loosely — older servers omit it). */
+    sessionDrive?: {
+        factorySlug: string;
+        branch: string;
+    } | null;
     viewerLastReadAt: string | null;
     /** The caller's role in this conversation (ADR-0045) — drives client
      *  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
@@ -226,6 +249,36 @@ export interface CreateCloudSessionInput {
      *  profile ids, or "none" for a bare session. Omitted = the owner's
      *  default profile. */
     connectorProfileId?: string;
+    /** Idempotent dependency-setup command run by every fresh sandbox acquire
+     *  after the drive mounts (`bun install`, `npm ci`, …). Strict charset —
+     *  no shell metacharacters (400). Mutually exclusive with `templateId`
+     *  (a snapshot carries its own installed state). */
+    setupCommand?: string;
+    /** Provenance of a session born by `agentc session import`: where the
+     *  imported local session lived and which harness thread seeded it. */
+    handoffOrigin?: {
+        cwd: string;
+        sourceAcpSessionId: string | null;
+        agentKind: string;
+        mirrorConversationId: string | null;
+    };
+    /** Imported claude memories (session-import spec §memories): guest-home
+     *  seeds re-applied on every fresh acquire. Paths under .claude/ only;
+     *  strict base64; 256KB decoded total (server-capped). */
+    seedFiles?: Array<{
+        path: string;
+        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;
@@ -295,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. */
@@ -326,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. */
@@ -394,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;
@@ -406,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

@@ -89,6 +89,11 @@ export interface RegisterWorkflowInput {
      *  server skips the /factory mount for its runs (#13). See
      *  `WorkflowMetadata.environmentBuild`. */
     environmentBuild?: boolean;
+    /** Drive requirement declared via `defineWorkflow({ factoryDrive })`.
+     *  Omitted ⇒ `"required"` on the server (a failed /factory mount fails
+     *  the run); `"none"` = explicit no-drive opt-out. See
+     *  `WorkflowMetadata.factoryDrive`. */
+    factoryDrive?: "required" | "none";
     /** Factory slug. Defaults to `"default"`. */
     factorySlug?: string;
 }
@@ -181,6 +186,26 @@ export interface FactoryFileWriteResult {
     sizeBytes: number;
     created: boolean;
 }
+/** A minted local-mount grant: the user branch, the signed gateway token, and
+ *  where to dial. The backing `conversationId` is the mount's review surface
+ *  (its branch changes list + merge ride the session-changes routes). */
+export interface DriveMountSession {
+    conversationId: string;
+    branch: string;
+    /** Signed gateway mount token (user principal, exclusive mode). Treat as a
+     *  secret: write it to a 0600 token file, never argv/env of children. */
+    token: string;
+    gatewayWsUrl: string;
+    /** Token expiry, unix seconds — re-mint (same `conversationId`) before it. */
+    expiresAtS: number;
+    diskId: string;
+}
+export interface CreateDriveMountSessionInput {
+    /** Re-mint for an existing mount session (remount / token refresh). */
+    conversationId?: string;
+    /** The mounting machine's hostname — carried in the mount's title. */
+    host?: string;
+}
 /** A factory: a project-level grouping of workflows inside a team. */
 export interface FactoryRow {
     id: string;
@@ -259,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;
@@ -275,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;
@@ -285,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

@@ -9,7 +9,18 @@
 import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
 import type { SnapshotConfig } from "./workflow-metadata.js";
 import type { RunContext } from "./api-scopes.js";
+import type { BundledWorkflow } from "../utils/bundler.js";
 export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
+/** INLINE invoke payload (`POST /factories/:slug/invoke`): everything
+ *  `bundleWorkflow` produced — source, the REQUIRED manifest binding the
+ *  bytes, the workflow plan, and the build fields — plus the name the run
+ *  reports as its workflow. The server runs it through the same
+ *  validate/build core as registration but writes NO registry row: the run
+ *  snapshots the validated source (auditable, replayable) and the name
+ *  stays free for real registrations. */
+export type InlineWorkflowPayload = BundledWorkflow & {
+    name: string;
+};
 export interface InvokeWorkflowOptions {
     /** Per-invocation snapshot config override. `snapshots.bootFrom`
      *  replaces the template's boot source; `snapshots.saveLatest` and
@@ -38,11 +49,45 @@ export interface InvokeWorkflowOptions {
      *  with the same key inside the server's dedup window returns the original
      *  run instead of starting a new one (matches `resumePause`'s pattern). */
     idempotencyKey?: string;
-}
+    /** Who pays for this run's model calls:
+     *
+     *    - `"default"` (Auto) — the initiating human's connected subscription
+     *      when one is enabled for workflows, else platform credits;
+     *    - `"platform"` — always platform credits (metered);
+     *    - `"subscription"` — REQUIRE the initiating human's plan. If it
+     *      cannot be honored the invoke FAILS (412) rather than quietly
+     *      spending credits;
+     *    - `"byok"` — a factory secret named by `fundingSecret`, injected as
+     *      the runtime's raw provider key. Never metered.
+     *
+     *  Omitted → the workflow's own default (its `settings.funding`), else
+     *  Auto. */
+    funding?: FundingChoice;
+    /** `funding: "byok"` only — the FACTORY SECRET NAME whose value funds the
+     *  run. Must be a provider key variable (ANTHROPIC_API_KEY,
+     *  OPENAI_API_KEY, CODEX_API_KEY, OPENROUTER_API_KEY) — that is where the
+     *  sandbox's runtimes read it. The name only; the value never leaves the
+     *  server's secret store. */
+    fundingSecret?: string;
+}
+/** Inference-funding choice for a run — a lane the caller PINS, or
+ *  `"default"` (Auto, the automatic ladder). Mirrors the same vocabulary
+ *  cloud sessions use. */
+export type FundingChoice = "default" | "platform" | "subscription" | "byok";
 export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
     timeoutMs?: number;
     pollIntervalMs?: number;
 }
+/** Options for `invokeInline` — the named-invoke options plus the run-title
+ *  override (an inline run has no registered template to inherit one from). */
+export interface InvokeInlineOptions extends InvokeWorkflowOptions {
+    /** Run title override — defaults to the workflow name. */
+    title?: string;
+}
+export interface InvokeInlineAndWaitOptions extends InvokeInlineOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
 export interface InvokeResult {
     id: string;
 }
@@ -238,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";