@agent-compose/sdk 0.8.0 → 0.8.2

package/src/client.ts

@@ -18,7 +18,8 @@ import type { RunEvent } from "./types/events.js";
 import type { ConversationStreamEvent } from "./types/conversation-stream.js";
 import { normalizeConversationStreamEvent } from "./types/conversation-stream.js";
 import type {
-  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions,
+  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, StreamRunLogsOptions,
+  InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions,
   RunStatus, ResumePauseOptions, ResumePauseResponse, AnswerSteerOptions,
   RequestAgentPauseOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
@@ -30,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,
@@ -51,8 +52,9 @@ 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";
 import type {
   ComplianceSession, RequestComplianceSessionInput, ListComplianceSessionsOptions,
@@ -64,7 +66,8 @@ import type {
 // here so `client.js` stays the single import surface for the client and its
 // shapes (index.ts re-exports from here).
 export type {
-  RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, StreamRunLogsOptions,
+  RunState, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice, StreamRunLogsOptions,
+  InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions,
   RunStatus, ResumePauseActor, ResumePauseSuccess, ResumePausePending, ResumePauseResponse,
   ResumePauseOptions, RequestAgentPauseOptions, AnswerSteerOptions, RequestAgentPauseResponse,
   SendAgentMessageOptions, SendAgentMessageResponse,
@@ -79,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 {
@@ -105,9 +109,10 @@ export type {
   FactoryRow, CreateFactoryInput, UpdateFactoryInput,
   ScheduleRow, CreateScheduleInput,
   SecretOptions, SetSecretResult, SecretListEntry,
-  CreateApiKeyInput, ApiKey, ApiKeyCreated,
+  CreateApiKeyInput, ApiKey, ApiKeyCreated, ListApiKeysOptions, ApiKeyPage,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
+  DriveMountSession, CreateDriveMountSessionInput,
 } from "./types/api-factory.js";
 export type {
   ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess,
@@ -296,6 +301,45 @@ export class AgentComposeClient {
         ...(opts?.size          !== undefined ? { size:          opts.size }          : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
+        ...(opts?.funding       !== undefined ? { funding:       opts.funding }       : {}),
+        ...(opts?.fundingSecret !== undefined ? { fundingSecret: opts.fundingSecret } : {}),
+      },
+    });
+  }
+
+  /** Invoke an INLINE workflow — the exact payload `bundleWorkflow` produced
+   *  plus a `name` — WITHOUT registering it. The server validates it through
+   *  the same core as registration (manifest required + bound to the source
+   *  bytes) but writes no registry row: the run snapshots the source it
+   *  executes, and registration stays the door for named/versioned/scheduled
+   *  workflows. Same parent-child auto-detection and `Idempotency-Key`
+   *  semantics as `invoke()`. Requires the `invoke` scope. */
+  invokeInline(
+    workflow: InlineWorkflowPayload,
+    input?: Record<string, unknown>,
+    opts?: InvokeInlineOptions,
+  ): Promise<InvokeResult> {
+    const parentRunId = opts?.parentRunId === undefined
+      ? detectAmbientParentRunId()
+      : opts.parentRunId;
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const headers: Record<string, string> = {};
+    if (opts?.idempotencyKey) headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/invoke`, {
+      method: "POST",
+      ...(opts?.idempotencyKey ? { headers } : {}),
+      body: {
+        workflow,
+        input,
+        ...(opts?.title         !== undefined ? { title:         opts.title }         : {}),
+        ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
+        ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
+        ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+        ...(opts?.size          !== undefined ? { size:          opts.size }          : {}),
+        ...(parentRunId                       ? { parentRunId }                       : {}),
+        ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
+        ...(opts?.funding       !== undefined ? { funding:       opts.funding }       : {}),
+        ...(opts?.fundingSecret !== undefined ? { fundingSecret: opts.fundingSecret } : {}),
       },
     });
   }
@@ -312,12 +356,33 @@ export class AgentComposeClient {
     input?: Record<string, unknown>,
     opts?: InvokeAndWaitOptions,
   ): Promise<RunStatus<TOutput>> {
-    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
-    const pollMs    = opts?.pollIntervalMs ?? 1000;
     // InvokeAndWaitOptions extends InvokeWorkflowOptions, so we can forward
     // `opts` directly — invoke() picks only the fields it sends, so the
     // extra `timeoutMs` / `pollIntervalMs` never leak into the request body.
     const { id: runId } = await this.invoke(name, input, opts);
+    return this.waitForRun<TOutput>(runId, opts);
+  }
+
+  /** `invokeInline` + block until the run settles — the "call blocks →
+   *  result returns on the same turn" contract for inline sub-workflows. */
+  async invokeInlineAndWait<TOutput = unknown>(
+    workflow: InlineWorkflowPayload,
+    input?: Record<string, unknown>,
+    opts?: InvokeInlineAndWaitOptions,
+  ): Promise<RunStatus<TOutput>> {
+    const { id: runId } = await this.invokeInline(workflow, input, opts);
+    return this.waitForRun<TOutput>(runId, opts);
+  }
+
+  /** Poll one run until it settles (success / failed / abandoned) and return
+   *  its final status. Shared tail of `invokeAndWait` / `invokeInlineAndWait`;
+   *  also useful to re-attach to a run you dispatched fire-and-forget. */
+  async waitForRun<TOutput = unknown>(
+    runId: string,
+    opts?: { timeoutMs?: number; pollIntervalMs?: number },
+  ): Promise<RunStatus<TOutput>> {
+    const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
+    const pollMs    = opts?.pollIntervalMs ?? 1000;
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
       const status = await this.getStatus<TOutput>(runId);
@@ -329,7 +394,7 @@ export class AgentComposeClient {
     // Use AgentComposeError (not plain Error) so catch-blocks handling SDK
     // transport failures also handle timeouts uniformly. HTTP 504 is the
     // closest idiomatic status for "upstream didn't answer in time."
-    throw new AgentComposeError(504, `invokeAndWait: run ${runId} did not settle within ${timeoutMs}ms`);
+    throw new AgentComposeError(504, `waitForRun: run ${runId} did not settle within ${timeoutMs}ms`);
   }
 
   /** List captured snapshots in a factory. */
@@ -622,6 +687,21 @@ export class AgentComposeClient {
     }));
   }
 
+  /** One run artifact's bytes, resolved server-side through the DRIVE INDEX
+   *  (never the run's gone sandbox or branch) — a listed artifact with an
+   *  indexed path is always readable here, including after the run's branch
+   *  is merged/retired. The path is the listing's `path`, sent as a single
+   *  query parameter so slashes / spaces / unicode in agent-derived
+   *  filenames survive verbatim. */
+  async getRunArtifactBytes(runId: string, path: string): Promise<Uint8Array> {
+    const q = new URLSearchParams({ path });
+    const buf = await this.fetch<ArrayBuffer, "arrayBuffer">(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/artifacts/content?${q}`,
+      { responseType: "arrayBuffer" },
+    );
+    return new Uint8Array(buf);
+  }
+
   // ── Factory files ──────────────────────────────────────────────────────────
   // The factory drive: documents surfaced in the dashboard's Files tab.
   // Writes from inside a sandbox automatically carry the run-callback token
@@ -665,13 +745,17 @@ export class AgentComposeClient {
    *  U+FFFD and the original bytes are unrecoverable). */
   async getFactoryFileBytes(
     path: string,
-    opts?: { factorySlug?: string; revision?: number },
+    opts?: { factorySlug?: string; revision?: number; branch?: string },
   ): Promise<Uint8Array> {
     const factorySlug = opts?.factorySlug
       ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
       ?? DEFAULT_FACTORY;
     const q = new URLSearchParams({ path });
     if (opts?.revision !== undefined) q.set("revision", String(opts.revision));
+    // Branch view (read-only): the file AS OF a drive branch — e.g. a cloud
+    // 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);
     const buf = await this.fetch<ArrayBuffer, "arrayBuffer">(
       `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q}`,
       { responseType: "arrayBuffer" },
@@ -684,11 +768,57 @@ export class AgentComposeClient {
    *  text corrupts the bytes irreversibly. */
   async getFactoryFile(
     path: string,
-    opts?: { factorySlug?: string; revision?: number },
+    opts?: { factorySlug?: string; revision?: number; branch?: string },
   ): Promise<string> {
     return new TextDecoder().decode(await this.getFactoryFileBytes(path, opts));
   }
 
+  // ── User drive mounts ──────────────────────────────────────────────────────
+  // `agentc files mount` on a human's own machine: the server forks a user
+  // branch, backs it with a mount session (the review surface), and mints a
+  // user-principal gateway token. Human-held credentials only (sign-in
+  // cookie or a device-flow bridge key) — sandbox session keys are refused.
+
+  /** Create a local drive mount (or re-mint an existing one's token by
+   *  passing its `conversationId`). */
+  async createDriveMountSession(
+    opts?: CreateDriveMountSessionInput & { factorySlug?: string },
+  ): Promise<DriveMountSession> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    return this.fetch<DriveMountSession>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/mount-sessions`,
+      {
+        method: "POST",
+        body: {
+          ...(opts?.conversationId ? { conversationId: opts.conversationId } : {}),
+          ...(opts?.host ? { host: opts.host } : {}),
+        },
+      },
+    );
+  }
+
+  /** Release a local mount's gateway branch mount (clean unmount). The
+   *  branch and its review card survive — this only drops the gateway's
+   *  in-memory mount so the exclusive branch is not pinned. */
+  async releaseDriveMountSession(
+    conversationId: string,
+    opts?: { factorySlug?: string },
+  ): Promise<{ released: boolean }> {
+    const factorySlug = opts?.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    return this.fetch<{ released: boolean }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/files/mount-sessions/${encodeURIComponent(conversationId)}/release`,
+      { method: "POST", body: {} },
+    );
+  }
+
+  // A mount's change set + merge/discard ride the EXISTING session-branch
+  // proposal surface below (`getSessionChanges` / `mergeSessionChanges` /
+  // `discardSessionChanges`) — the mount's `conversationId` is a session.
+
   // ── Conversations ──────────────────────────────────────────────────────────
   // The chat surfaces (channels / solo chats / sessions) the caller can
   // access. Key callers see what their sender scope allows; the server is the
@@ -711,9 +841,12 @@ export class AgentComposeClient {
     return this.fetch<SessionsPage>(`/api/v1/sessions?${q}`);
   }
 
-  /** One conversation with its latest page of messages. */
-  getConversation(id: string): Promise<ConversationDetail> {
-    return this.fetch<ConversationDetail>(`/api/v1/conversations/${encodeURIComponent(id)}`);
+  /** 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. */
+  getConversation(id: string, opts?: { limit?: number }): Promise<ConversationDetail> {
+    const q = opts?.limit !== undefined ? `?limit=${opts.limit}` : "";
+    return this.fetch<ConversationDetail>(`/api/v1/conversations/${encodeURIComponent(id)}${q}`);
   }
 
   /** Provision a CLOUD-native session (ADR-0037 Phase 3b / ADR-0055 §9): a
@@ -742,6 +875,9 @@ export class AgentComposeClient {
         ...(input.sandboxSize ? { sandboxSize: input.sandboxSize } : {}),
         ...(input.networkPolicy !== undefined ? { networkPolicy: input.networkPolicy } : {}),
         ...(input.connectorProfileId !== undefined ? { connectorProfileId: input.connectorProfileId } : {}),
+        ...(input.setupCommand !== undefined ? { setupCommand: input.setupCommand } : {}),
+        ...(input.handoffOrigin !== undefined ? { handoffOrigin: input.handoffOrigin } : {}),
+        ...(input.seedFiles !== undefined ? { seedFiles: input.seedFiles } : {}),
       },
     });
   }
@@ -849,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." */
@@ -882,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
@@ -891,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 } : {} },
     );
@@ -1473,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). */
@@ -1533,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/display.ts

@@ -101,8 +101,32 @@ export const TABLE_MAX_COLUMNS = 12;
 export const TABLE_MAX_ROWS = 100;
 export const TABLE_CELL_MAX_CHARS = 200;
 
-/** Drive-path bound for image markers (mirrors the directive path cap). */
-const IMAGE_PATH_MAX_CHARS = 512;
+/** Drive-path bound for promoted/marker paths (mirrors the directive cap). */
+export const DRIVE_PATH_MAX_CHARS = 512;
+
+/**
+ * Whether a string is a PLAUSIBLE factory-drive path — the gate every
+ * promoted document/image/preview/diff path and document/image marker
+ * passes before it can become a card. A malformed agent command can hand
+ * the promoter shell fragments instead of a path (live failure: a partial
+ * `agentc display document` call promoted the redirect word `2>&1` — and a
+ * bare `/` — into "Showed document" cards whose viewer link was dead), so
+ * anything that reads as a shell operator, flag, or empty reference is not
+ * a path: reject whitespace-only, over-long, flag-shaped (leading `-`),
+ * shell operators / substitution (`|`, `<`, `>`, `;`, backticks, `$(`,
+ * which covers `2>&1`), control characters, backslashes, bare/duplicate
+ * slashes, and `.`/`..` segments (the server rejects those anyway).
+ */
+export function isPlausibleDrivePath(raw: string): boolean {
+  if (raw.trim().length === 0 || raw.length > DRIVE_PATH_MAX_CHARS) return false;
+  if (raw.startsWith("-")) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f\\]/.test(raw)) return false;
+  if (/[|<>;`]|\$\(/.test(raw)) return false;
+  const trimmed = raw.replace(/^\/+|\/+$/g, "");
+  if (trimmed.length === 0) return false; // bare "/" (or only slashes)
+  return trimmed.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
 
 function clampCellString(s: string): string {
   return s.length > TABLE_CELL_MAX_CHARS ? `${s.slice(0, TABLE_CELL_MAX_CHARS - 1)}…` : s;
@@ -288,7 +312,7 @@ export function parseDisplayMarker(line: string): DisplayMarker | null {
     }
     case "document": {
       const path = str("path");
-      if (!path) return null;
+      if (!path || !isPlausibleDrivePath(path)) return null;
       return {
         kind: "document", path,
         ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
@@ -301,7 +325,7 @@ export function parseDisplayMarker(line: string): DisplayMarker | null {
     }
     case "image": {
       const path = str("path");
-      if (!path || path.length > IMAGE_PATH_MAX_CHARS) return null;
+      if (!path || !isPlausibleDrivePath(path)) return null;
       return {
         kind: "image", path,
         ...(str("factorySlug") ? { factorySlug: str("factorySlug") } : {}),
@@ -446,6 +470,11 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
   for (let i = start + 1; i < words.length; i += 1) {
     const w = words[i];
     if (SHELL_STOPPERS.has(w)) break;
+    // A merged-stream redirect (`2>&1`) is tolerated by the control-word
+    // gate above, but it is shell syntax, never an argument — collecting
+    // it turned a truncated `agentc display document 2>&1` into a "Showed
+    // document" card whose path was the redirect itself (live failure).
+    if (/^\d*>&\d+$/.test(w)) continue;
     if (w.startsWith("--")) {
       if (VALUE_FLAGS.has(w) && i + 1 < words.length && !SHELL_STOPPERS.has(words[i + 1])) {
         flags.set(w, words[i + 1]);
@@ -458,6 +487,12 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
   const factorySlug = flags.get("--factory");
   const withSlug = factorySlug ? { factorySlug } : {};
   const uuid = (v: string | undefined): string | null => (v && UUID_RE.test(v) ? v : null);
+  // Path-taking verbs promote only PLAUSIBLE drive paths — a shell
+  // fragment or bare `/` from a malformed command is unparseable-argument
+  // territory (the pair persists raw, the CLI's own error is the agent's
+  // feedback), never a document card.
+  const drivePath = (v: string | undefined): string | null =>
+    (v && isPlausibleDrivePath(v) ? v : null);
 
   if (args[0] === "display") {
     switch (args[1]) {
@@ -469,19 +504,28 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
         const runId = uuid(args[2]);
         return runId ? { verb: "display-changes", runId, ...withSlug } : null;
       }
-      case "document":
-        return args[2] ? { verb: "display-document", path: args[2], ...withSlug } : null;
+      case "document": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-document", path, ...withSlug } : null;
+      }
       case "plan":
         return { verb: "display-plan" };
-      case "image":
-        return args[2] ? { verb: "display-image", path: args[2], ...withSlug } : null;
-      case "preview":
-        return args[2] ? { verb: "display-preview", path: args[2] } : null;
+      case "image": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-image", path, ...withSlug } : null;
+      }
+      case "preview": {
+        const path = drivePath(args[2]);
+        return path ? { verb: "display-preview", path } : null;
+      }
       case "table": {
         const file = flags.get("--file");
         const hasData = flags.has("--data");
         // Exactly one source; both or neither is an unpromotable combination.
-        if (file && !hasData) return { verb: "display-table", source: "file", path: file };
+        if (file && !hasData) {
+          const path = drivePath(file);
+          return path ? { verb: "display-table", source: "file", path } : null;
+        }
         if (hasData && !file) return { verb: "display-table", source: "inline" };
         return null;
       }
@@ -494,9 +538,10 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
       case "diff": {
         const from = flags.get("--from");
         const to = flags.get("--to");
-        if (!args[2] || !from || !to) return null;
+        const path = drivePath(args[2]);
+        if (!path || !from || !to) return null;
         if (!REVISION_SELECTOR_RE.test(from) || !REVISION_SELECTOR_RE.test(to)) return null;
-        return { verb: "display-diff", path: args[2], from, to };
+        return { verb: "display-diff", path, from, to };
       }
       case "ask": {
         const prompt = flags.get("--prompt");
@@ -524,8 +569,9 @@ export function detectAgentcInvocation(command: string): AgentcInvocation | null
     const runId = uuid(args[2]);
     return runId ? { verb: "run-get", runId } : null;
   }
-  if (args[0] === "files" && args[1] === "read" && args[2]) {
-    return { verb: "files-read", path: args[2], ...withSlug };
+  if (args[0] === "files" && args[1] === "read") {
+    const path = drivePath(args[2]);
+    return path ? { verb: "files-read", path, ...withSlug } : null;
   }
   return null;
 }

package/src/index.ts

@@ -113,7 +113,8 @@ export type {
 export { AgentComposeClient } from "./client.js";
 export type {
   RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef,
-  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult,
+  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, FundingChoice,
+  InlineWorkflowPayload, InvokeInlineOptions, InvokeInlineAndWaitOptions,
   ListSnapshotsOptions, TemplateRow, ListTemplatesOptions,
   CreateFactoryInput, UpdateFactoryInput,
   SecretOptions, SetSecretResult, SecretListEntry,
@@ -124,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,
@@ -134,13 +135,17 @@ 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)
   ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
   FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState,
@@ -206,6 +211,10 @@ export {
   BUNDLER_VERSION,
   WorkflowSourceValidationError,
   assertDefaultExportIsDefineWorkflow,
+  SDK_PACKAGE,
+  SDK_SPECIFIER_ALIASES,
+  resolveSdkAlias,
+  explainBundleFailure,
 } from "./utils/bundler.js";
 export type { BundledWorkflow, WorkflowManifest } from "./utils/bundler.js";
 
@@ -232,7 +241,7 @@ export type { GatewayModelId } from "ai";
 // sandbox and stream-parse its JSONL. No heavy npm deps (the CLI lives in the
 // sandbox image), so these are root-exported like claudeRuntime.
 export { createCodexRuntime, codexSpec } from "./runtimes/codex.js";
-export type { CodexRuntimeConfig } from "./runtimes/codex.js";
+export type { CodexRuntimeConfig, CodexReasoningEffort } from "./runtimes/codex.js";
 export { default as codexRuntime } from "./runtimes/codex.js";
 // Reasoning-effort level a CLI runtime turn may carry (claude-code / codex).
 export type { CliReasoningEffort } from "./runtimes/_cli-agent.js";
@@ -255,7 +264,7 @@ export { default as droidRuntime } from "./runtimes/droid.js";
 // adapter) — the cloud-hostable counterpart of `claudeRuntime` (claude.ts,
 // which drives the Agent SDK in the calling process and so can never run a
 // server-driven cloud-session turn).
-export { createClaudeCodeRuntime, claudeCodeSpec, CLAUDE_CODE_ACP_ADAPTER, CLAUDE_CODE_THINKING_TOKENS } from "./runtimes/claude-code.js";
+export { createClaudeCodeRuntime, claudeCodeSpec, CLAUDE_CODE_ACP_ADAPTER, CLAUDE_CODE_EFFORT_LEVELS } from "./runtimes/claude-code.js";
 export type { ClaudeCodeRuntimeConfig } from "./runtimes/claude-code.js";
 export { default as claudeCodeRuntime } from "./runtimes/claude-code.js";
 
@@ -271,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,
@@ -386,6 +398,7 @@ export {
   TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS,
   CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS,
   ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS,
+  DRIVE_PATH_MAX_CHARS, isPlausibleDrivePath,
   serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries,
   clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions,
   detectAgentcInvocation, shellWords, createDisplayPromoter,