@agent-compose/sdk 0.8.0 → 0.8.1

package/dist/types/protocol.d.ts

@@ -31,6 +31,12 @@ export interface AgentMessageToolUse extends AgentMessageBase {
     toolName: string;
     toolInput: Record<string, unknown>;
     toolUseId: string;
+    /** The spawning subagent call's tool_use id when this call ran INSIDE a
+     *  subagent (claude stream-json stamps `parent_tool_use_id` on every
+     *  sidechain event) — lets renderers nest child activity under the
+     *  Agent/Task call instead of flattening it into the parent transcript.
+     *  Optional and additive: producers without sidechains omit it. */
+    parentToolUseId?: string;
 }
 export interface AgentMessageToolResult extends AgentMessageBase {
     type: "tool_result";
@@ -54,6 +60,8 @@ export interface AgentMessageToolResult extends AgentMessageBase {
         path: string;
         line?: number;
     }[];
+    /** Sidechain attribution, mirroring AgentMessageToolUse.parentToolUseId. */
+    parentToolUseId?: string;
 }
 export interface AgentMessageDone extends AgentMessageBase {
     type: "done";

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

@@ -231,6 +231,14 @@ export interface WorkflowMetadata {
      *  canonical metadata hash (frozen-metadata rule), so existing workflows are
      *  not forced to re-register. */
     environmentBuild?: boolean;
+    /** Whether this workflow's runs need the factory drive. ABSENT ⇒
+     *  `"required"`: on a drive-backed factory the server treats the /factory
+     *  mount as load-bearing — a mount failure FAILS the run instead of
+     *  silently proceeding drive-less. Declare `"none"` for a workflow that
+     *  genuinely never touches /factory: the server skips the mount entirely
+     *  for its runs (the explicit no-drive mode; there is no silent degrade).
+     *  Optional + additive (frozen-metadata rule). */
+    factoryDrive?: "required" | "none";
 }
 /**
  * Pull the server-readable declarations off a `StepWorkflowDefinition`

package/dist/utils/bundler.d.ts

@@ -18,6 +18,19 @@
  * parses or imports user source — it only validates the structured manifest
  * this function returns alongside the bundled bytes, and cross-checks the
  * manifest's `sourceHash` against the source it received.
+ *
+ * Module resolution carries two more layers, because most workflow source is
+ * now written by an AGENT and the bundler's error is the only feedback it
+ * gets (the Workflow Studio's agent authored `import … from "agentc/sdk"`
+ * and prod answered with bun's `Maybe you need to "bun install"?` — advice
+ * nobody could act on inside a sandbox with no package.json):
+ *
+ *   - TOLERATE (`SDK_SPECIFIER_ALIASES` + `sdkAliasPlugin`) — near-miss
+ *     spellings of `@agent-compose/sdk` resolve to the real package, so a
+ *     draft already written with the wrong one builds unedited.
+ *   - SELF-CORRECT (`explainBundleFailure`) — anything that still fails to
+ *     resolve produces an error NAMING the real package, which an agent
+ *     reading its own tool error can fix on the next turn.
  */
 import type { SnapshotConfig } from "../types/workflow.js";
 import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources, DriveMergePolicy } from "../types/workflow-metadata.js";
@@ -108,7 +121,50 @@ export interface BundledWorkflow {
     /** Set by `defineSandboxEnvironment` — marks an environment build so the
      *  server skips the /factory mount for its runs (#13). */
     environmentBuild?: boolean;
+    /** Drive requirement declared via `defineWorkflow({ factoryDrive })`.
+     *  Absent ⇒ `"required"` (a failed /factory mount fails the run);
+     *  `"none"` = explicit no-drive opt-out. */
+    factoryDrive?: "required" | "none";
 }
+/** The one true import specifier for the platform SDK. */
+export declare const SDK_PACKAGE = "@agent-compose/sdk";
+/**
+ * Import specifiers that can only have MEANT `@agent-compose/sdk`, rewritten
+ * to it at bundle time so a draft written with the wrong spelling builds
+ * unedited.
+ *
+ * Every entry carries an `sdk` segment or suffix, so none of them can be a
+ * real third-party package a workflow might legitimately depend on: `a/b`
+ * forms are subpaths of packages that don't exist, and the `*-sdk` forms
+ * name this platform explicitly. Bare `agentc` / `agent-compose` are
+ * deliberately NOT aliased — those are plausible npm package names, and
+ * silently redirecting a real dependency is worse than a clear error.
+ *
+ * Exported for the unit test that pins the table.
+ */
+export declare const SDK_SPECIFIER_ALIASES: readonly string[];
+/** `@agent-compose/sdk` when `specifier` is a known near-miss for it, else
+ *  null. The single authority: the plugin's regex filter is only a fast
+ *  pre-filter, and this decides. */
+export declare function resolveSdkAlias(specifier: string): string | null;
+/**
+ * The SELF-CORRECTING layer. Turns a Bun bundle failure into a message that
+ * names the real fix instead of leaking Bun's internals.
+ *
+ * An unresolved import is almost always one thing: workflow source naming
+ * the platform SDK by a specifier that isn't its package name. Bun answers
+ * that with `Could not resolve: "agentc/sdk". Maybe you need to "bun
+ * install"?` — advice the author cannot act on (there is no package.json to
+ * install into; the drive holds one file). The rewritten message says the
+ * package name, so an agent reading its own tool error can fix the import on
+ * the next turn.
+ *
+ * Non-resolve failures (syntax errors, transform failures) keep their
+ * verbatim diagnostics — those are already actionable.
+ *
+ * Exported for the unit test; `bundleWorkflow` is the supported entrypoint.
+ */
+export declare function explainBundleFailure(err: unknown, label: string): string;
 /**
  * Parse the bundled source and assert the default export is a CallExpression
  * to an identifier named `defineWorkflow` (or to a `.step(...).build()` chain

package/dist/workflow-steps/workflow.d.ts

@@ -72,6 +72,13 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
      *  server skips mounting the shared factory drive for its runs (#13). See
      *  `WorkflowMetadata.environmentBuild`. */
     environmentBuild?: boolean;
+    /** Whether this workflow's runs need the factory drive. Omit (⇒
+     *  `"required"`) for any workflow that reads or writes /factory: a failed
+     *  mount then FAILS the run instead of silently proceeding drive-less.
+     *  Declare `"none"` for a drive-agnostic workflow — the server skips the
+     *  /factory mount entirely for its runs. See
+     *  `WorkflowMetadata.factoryDrive`. */
+    factoryDrive?: "required" | "none";
 }
 export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
 /** Type guard — true when `value` is a `Workflow`. */

package/dist/workflows/invoke-child.d.ts

@@ -1,4 +1,22 @@
 import type { InvokeChild } from "../types/execution-context.js";
+/**
+ * Derive the deterministic per-call `Idempotency-Key` for a `ctx.invokeChild`
+ * dispatch: `invoke-child:<parentRunId>:step<stepIndex>:<childName>:<ordinal>`.
+ *
+ * Replay safety: a replayed step re-runs its body from the top, so the k-th
+ * `invokeChild(name)` call in a step re-derives the SAME key (the per-scope
+ * ordinal counter lives on the active-step state, which resets identically on
+ * every (re-)entry — the `nextPauseOrdinalInActiveStep` pattern). The server's
+ * idempotency window then returns the original child run instead of
+ * double-dispatching. Outside step execution (local dev, tests) there is no
+ * stable coordinate to key on — returns null and the dispatch is unkeyed,
+ * exactly the old behavior.
+ *
+ * Key syntax matches the server's `Idempotency-Key` grammar
+ * (`[A-Za-z0-9_\-:.]{1,255}`): runId is a UUID, step index a number, and
+ * workflow names are kebab-case.
+ */
+export declare function deriveInvokeChildIdempotencyKey(parentRunId: string, childName: string): string | null;
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
  * workflow execution. Provider-backed engines may inject a different

package/dist/workflows/invoke-child.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Replay-safety pin for `ctx.invokeChild` (parity plan P3.3): the
+ * Idempotency-Key a child dispatch carries is DETERMINISTIC per
+ * (parentRunId, stepIndex, childName, call ordinal) — a step body re-run
+ * from the top (pause/resume re-entry, crash-replayed attempt) re-derives
+ * byte-identical keys, so the server's idempotency window collapses the
+ * replayed dispatch into the original child run instead of double-running.
+ */
+export {};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Layr-Labs/agent-compose.git",
+    "url": "git+https://github.com/Chris-Moller/agent-compose.git",
     "directory": "sdk"
   },
   "type": "module",

package/src/agent/agent-loop.ts

@@ -126,6 +126,11 @@ export type AgentLifecycleEvent =
       /** Short runtime self-identifier (`claude`, `openai-desktop`, …).
        *  Drives the per-agent runtime icon on the dashboard. */
       runtimeKind?: string;
+      /** Authored plan-phase this agent belongs to (e.g. dynamic-task's
+       *  `phase.name`). Purely observability: the dashboard groups agents
+       *  under named phases without parsing the label prefix. Optional and
+       *  additive — absent for agents outside a phased plan. */
+      phase?: string;
     }
   | { event: "agent.message"; at: number; agentId: string; label: string; iteration: number; message: AgentMessageSummary }
   | { event: "agent.iteration"; at: number; agentId: string; label: string; iteration: number; status: AgentStatus | null }
@@ -134,6 +139,9 @@ export type AgentLifecycleEvent =
 export interface AgentLoopOpts<TResponse = unknown> {
   agentId?: string;
   label?: string;
+  /** Authored plan-phase name carried onto `agent.spawned` (see
+   *  AgentLifecycleEvent.phase). Optional, observability-only. */
+  phase?: string;
   onAgentLifecycleEvent?: (event: AgentLifecycleEvent) => void;
   onIteration?: (iteration: number, status: AgentStatus | null) => void;
   turnsPerIteration?: number;
@@ -307,6 +315,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
       ...(client.model       != null ? { model:       client.model       } : {}),
       ...(client.kind        != null ? { runtimeKind: client.kind        } : {}),
+      ...(opts.phase         != null ? { phase:       opts.phase         } : {}),
     });
   }
 

package/src/agent/run-agent.ts

@@ -183,6 +183,10 @@ export interface AgentOpts<T = unknown> {
   responseSchema?: z.ZodType<T>;
   /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
   label?: string;
+  /** Authored plan-phase this agent belongs to. Rides `agent.spawned` so the
+   *  dashboard groups agents under named phases. Optional, additive,
+   *  observability-only — it never affects execution. */
+  phase?: string;
   /** Lifecycle event sink from workflow ctx. Emits agent.spawned / iteration / settled. */
   events?: { emit: (event: AgentLifecycleEvent) => void | Promise<void> };
   /** Per-message event callback — wire this to your workflow's event
@@ -349,6 +353,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
     agentId,
     ...(opts.label !== undefined ? { label: opts.label } : {}),
+    ...(opts.phase !== undefined ? { phase: opts.phase } : {}),
     ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
     ...(opts.budget?.maxIterations     !== undefined ? { maxIterations:     opts.budget.maxIterations }     : {}),
     ...(opts.tools                      !== undefined ? { allowedTools:      opts.tools }                    : {}),

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,
@@ -53,6 +54,7 @@ import type {
   SecretOptions, SetSecretResult, SecretListEntry,
   CreateApiKeyInput, ApiKey, ApiKeyCreated, 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,
@@ -108,6 +111,7 @@ export type {
   CreateApiKeyInput, ApiKey, ApiKeyCreated,
   UsageRollupRow, UsageResponse,
   DriveRepoLink, CreateDriveRepoLinkInput,
+  DriveMountSession, CreateDriveMountSessionInput,
 } from "./types/api-factory.js";
 export type {
   ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess,
@@ -296,6 +300,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 +355,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 +393,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 +686,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 +744,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 +767,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 +840,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 +874,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 } : {}),
       },
     });
   }

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;
 }