@agent-compose/sdk 0.8.0 → 0.8.1

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,
@@ -141,6 +142,8 @@ export type {
   // Session branch proposals (ADR-0053)
   SessionFileChange, SessionChangeSet,
   SessionMergeReportDetail, SessionMergeReport, 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 +209,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 +239,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 +262,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";
 
@@ -386,6 +393,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,

package/src/runtimes/_cli-agent.ts

@@ -119,13 +119,15 @@ async function withHandshakeTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
   }
 }
 
-/** Reasoning-effort level a CLI turn may carry (T2 session effort). The
- *  per-CLI mapping lives in each spec's `buildCommand` — Claude Code takes a
- *  thinking-token budget via `MAX_THINKING_TOKENS`, codex takes
- *  `-c model_reasoning_effort=<level>`. Specs without a real knob
- *  (opencode/droid/cursor) never receive one: the server hides + rejects
- *  effort for those runtimes. */
-export type CliReasoningEffort = "low" | "medium" | "high";
+/** Reasoning-effort level a CLI turn may carry (T2 session effort) — the
+ *  UNION of what the effort-capable CLIs accept. The per-CLI mapping lives in
+ *  each spec's `buildCommand` — Claude Code takes its own `--effort` flag
+ *  (all five levels), codex takes `-c model_reasoning_effort=<level>`
+ *  (low|medium|high|xhigh — no "max"; the spec clamps it). Specs without a
+ *  real knob (opencode/droid/cursor) never receive one: the server hides +
+ *  rejects effort for those runtimes, and rejects levels a runtime lacks
+ *  (sessionEffortLockError). */
+export type CliReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
 
 /** Per-CLI behaviour. The base owns the lifecycle (init/done/error) and the
  *  transport (spawn + JSONL parse); a spec owns the CLI-specific bits. */

package/src/runtimes/claude-code.ts

@@ -72,13 +72,15 @@ function toolResultText(content: unknown): string {
   return content == null ? "" : JSON.stringify(content) ?? "";
 }
 
-/** Extended-thinking token budget per effort level — Claude Code's real knob
- *  is the `MAX_THINKING_TOKENS` env var (its documented settings env), set
- *  per invocation below. Values mirror the platform turn loop's
- *  `EFFORT_BUDGET_TOKENS` (server model-client) so "high" means the same
- *  thing in a channel and in a claude-code session. */
-export const CLAUDE_CODE_THINKING_TOKENS: Record<CliReasoningEffort, number> =
-  { low: 2_048, medium: 8_192, high: 16_384 };
+/** Claude Code's real reasoning knob is its own `--effort <level>` flag
+ *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
+ *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the
+ *  flag verbatim; the CLI itself downgrades a level the selected model lacks
+ *  (its documented behaviour, e.g. xhigh → high off Opus). The old
+ *  `MAX_THINKING_TOKENS` env mapping is gone: the CLI deprecated it (treated
+ *  as on/off on current models) and it could never express xhigh/max. */
+export const CLAUDE_CODE_EFFORT_LEVELS: readonly CliReasoningEffort[] =
+  ["low", "medium", "high", "xhigh", "max"];
 
 export const claudeCodeSpec: CliAgentSpec = {
   kind: "claude-code",
@@ -115,17 +117,25 @@ export const claudeCodeSpec: CliAgentSpec = {
       // root-user refusal (the E2B agent-env user is root).
       "--dangerously-skip-permissions",
       ...(model ? [`--model ${shellQuote(model)}`] : []),
+      // Reasoning effort is the CLI's own flag; the value comes from the
+      // closed CliReasoningEffort set, so it is shell-safe unquoted.
+      ...(effort ? [`--effort ${effort}`] : []),
       ...(sessionId ? [`--resume ${shellQuote(sessionId)}`] : []),
     ].join(" ");
-    // Reasoning effort rides as the CLI's own thinking-budget env, same
-    // per-invocation idiom as IS_SANDBOX (never persisted into settings).
-    const thinking = effort ? `MAX_THINKING_TOKENS=${CLAUDE_CODE_THINKING_TOKENS[effort]} ` : "";
-    return `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}${thinking}IS_SANDBOX=1 claude ${flags} < ${shellQuote(promptPath)}`;
+    return `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}IS_SANDBOX=1 claude ${flags} < ${shellQuote(promptPath)}`;
   },
   // Every stream-json event carries the session id; the init event is first.
   extractSessionId: (p) => (typeof p.session_id === "string" ? p.session_id : undefined),
   mapEvent: (p): AgentMessage[] => {
     const ts = now();
+    // Sidechain attribution: stream-json stamps `parent_tool_use_id` on
+    // every event emitted INSIDE a subagent (the spawning Agent/Task call's
+    // tool_use id; null at top level). Forwarded on tool_use/tool_result so
+    // renderers can nest child activity under the spawning call instead of
+    // flattening it into the parent transcript unattributed.
+    const parent = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0
+      ? { parentToolUseId: p.parent_tool_use_id }
+      : {};
     switch (p.type) {
       // Assistant API message: content blocks → text / thinking / tool_use.
       case "assistant": {
@@ -141,7 +151,7 @@ export const claudeCodeSpec: CliAgentSpec = {
           if (b.type === "tool_use") {
             return [{
               type: "tool_use", toolName: String(b.name ?? "tool"),
-              toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts,
+              toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), ...parent, timestamp: ts,
             }];
           }
           return [];
@@ -155,7 +165,7 @@ export const claudeCodeSpec: CliAgentSpec = {
           b.type === "tool_result"
             ? [{
                 type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
-                output: toolResultText(b.content), isError: b.is_error === true, timestamp: ts,
+                output: toolResultText(b.content), isError: b.is_error === true, ...parent, timestamp: ts,
               }]
             : []);
       }
@@ -234,8 +244,8 @@ export const claudeCodeSpec: CliAgentSpec = {
 export interface ClaudeCodeRuntimeConfig {
   /** Claude model id (`--model`). Omit to use the CLI's configured default. */
   model?: string;
-  /** Extended-thinking effort (`MAX_THINKING_TOKENS`). Omit for the CLI's
-   *  default behaviour (no forced budget). */
+  /** Reasoning effort (`--effort <level>`; the CLI accepts all five levels).
+   *  Omit for the CLI's default behaviour. */
   effort?: CliReasoningEffort;
 }
 

package/src/runtimes/codex.ts

@@ -88,9 +88,13 @@ export const codexSpec: CliAgentSpec = {
       "--dangerously-bypass-approvals-and-sandbox",
       ...(model ? ["-m", shellQuote(model)] : []),
       // codex's own reasoning knob — a config override, valid values
-      // low|medium|high (plus "minimal", unused here). The value comes from
+      // none|minimal|low|medium|high|xhigh (codex docs; xhigh is the
+      // codex-max-tier deep-reasoning level). There is NO "max" in codex's
+      // vocabulary: the server rejects it for codex sessions
+      // (sessionEffortLockError), and this clamp to xhigh is the type-level
+      // backstop for a caller that bypasses that gate. The value comes from
       // the closed CliReasoningEffort set, so it is shell-safe unquoted.
-      ...(effort ? ["-c", `model_reasoning_effort=${effort}`] : []),
+      ...(effort ? ["-c", `model_reasoning_effort=${effort === "max" ? "xhigh" : effort}`] : []),
       ...(cwd ? ["-C", shellQuote(cwd)] : []),
     ].join(" ");
     // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
@@ -171,12 +175,16 @@ export const codexSpec: CliAgentSpec = {
   },
 };
 
+/** The effort levels codex actually has (`model_reasoning_effort`):
+ *  low|medium|high|xhigh — no "max" (that level is Claude Code's alone). */
+export type CodexReasoningEffort = Exclude<CliReasoningEffort, "max">;
+
 export interface CodexRuntimeConfig {
   /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
   model?: string;
   /** Reasoning effort (`-c model_reasoning_effort=<level>`). Omit to use the
    *  codex CLI's configured default. */
-  effort?: CliReasoningEffort;
+  effort?: CodexReasoningEffort;
 }
 
 export function createCodexRuntime(config: CodexRuntimeConfig = {}) {

package/src/types/api-conversations.ts

@@ -155,6 +155,13 @@ export interface ConversationDetail {
    *  in drivers. Null/absent when never reported (platform agents, older
    *  daemons/servers). */
   sessionCommands?: Array<{ 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.
@@ -226,6 +233,24 @@ export interface CreateCloudSessionInput {
    *  profile ids, or "none" for a bare session. Omitted = the owner's
    *  default profile. */
   connectorProfileId?: string;
+  // ── Session import (session-import spec) ────────────────────────────────
+  /** 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" }>;
 }
 
 export interface CloudSessionCreated {

package/src/types/api-factory.ts

@@ -95,6 +95,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;
 }
@@ -194,6 +199,33 @@ export interface FactoryFileWriteResult {
   created: boolean;
 }
 
+// ── User drive mounts (`agentc files mount` on a human's own machine) ────────
+
+/** 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 mount's change set + merge ride the existing session-branch proposal
+// types in `api-conversations.ts` (`SessionChangeSet`, `SessionMergeReport`).
+
 /** A factory: a project-level grouping of workflows inside a team. */
 export interface FactoryRow {
   id:          string;

package/src/types/api-runs.ts

@@ -10,9 +10,19 @@
 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
@@ -41,13 +51,50 @@ 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;
 }

package/src/types/protocol.ts

@@ -37,6 +37,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 {
@@ -54,6 +60,8 @@ export interface AgentMessageToolResult extends AgentMessageBase {
   /** File locations touched by the tool call (ACP `locations` field), enabling
    *  "follow-along" UI. Optional and additive (WS-C / ADR-0020 Q3). */
   locations?: { path: string; line?: number }[];
+  /** Sidechain attribution, mirroring AgentMessageToolUse.parentToolUseId. */
+  parentToolUseId?: string;
 }
 
 export interface AgentMessageDone extends AgentMessageBase {

package/src/types/workflow-metadata.ts

@@ -241,6 +241,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";
 }
 
 /**
@@ -274,6 +282,7 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   if (source.connectorOperation !== undefined) out.connectorOperation = Object.freeze({ ...source.connectorOperation });
   if (source.invokePolicy       !== undefined) out.invokePolicy       = freezeMetadataValue(source.invokePolicy);
   if (source.environmentBuild   !== undefined) out.environmentBuild   = source.environmentBuild;
+  if (source.factoryDrive       !== undefined) out.factoryDrive       = source.factoryDrive;
   return Object.freeze(out);
 }
 

package/src/utils/bundler.ts

@@ -18,9 +18,23 @@
  * 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 { createHash } from "node:crypto";
+import { dirname } from "node:path";
 import { parse as babelParse } from "@babel/parser";
 import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
@@ -121,11 +135,191 @@ 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 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 const SDK_SPECIFIER_ALIASES: readonly string[] = [
+  "agentc/sdk",
+  "@agentc/sdk",
+  "agentc-sdk",
+  "agent-compose/sdk",
+  "agentcompose/sdk",
+  "@agentcompose/sdk",
+  "agent-compose-sdk",
+];
+
+const SDK_ALIAS_SET = new Set(SDK_SPECIFIER_ALIASES);
+
+/** `@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 function resolveSdkAlias(specifier: string): string | null {
+  return SDK_ALIAS_SET.has(specifier) ? SDK_PACKAGE : null;
+}
+
+/** Minimal shape of the Bun surface this module drives. Accessed via
+ *  globalThis so the SDK keeps no compile-time dependency on @types/bun. */
+interface BunBuildLog { message: string; name?: string; specifier?: string }
+interface BunSurface {
+  build(opts: {
+    entrypoints: string[]; format: string; target: string;
+    plugins?: { name: string; setup(build: BunPluginBuild): void }[];
+  }): Promise<{ success: boolean; outputs: { text(): Promise<string> }[]; logs: BunBuildLog[] }>;
+  resolveSync(specifier: string, parent: string): string;
+}
+interface BunPluginBuild {
+  onResolve(
+    constraints: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string; importer?: string; resolveDir?: string }) => { path: string } | undefined,
+  ): void;
+}
+
+/** Anchored regex over the alias table — the plugin filter. Specifiers are
+ *  literal package names, but escape anyway so a future entry with a `.`
+ *  or `+` can't widen the filter. */
+function aliasFilter(): RegExp {
+  const alternation = SDK_SPECIFIER_ALIASES
+    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("|");
+  return new RegExp(`^(?:${alternation})$`);
+}
+
+/**
+ * The TOLERATE layer: a Bun resolve plugin that maps every known near-miss
+ * specifier onto the real SDK. Resolution goes through Bun's own resolver
+ * from the importing file's directory, so the alias lands on exactly the
+ * `@agent-compose/sdk` the build would have used had the source spelled it
+ * correctly. When the real SDK can't be resolved either, the plugin declines
+ * and Bun's failure flows into `explainBundleFailure` below.
+ */
+function sdkAliasPlugin(bun: BunSurface): { name: string; setup(build: BunPluginBuild): void } {
+  return {
+    name: "agent-compose-sdk-alias",
+    setup(build) {
+      build.onResolve({ filter: aliasFilter() }, (args) => {
+        const target = resolveSdkAlias(args.path);
+        if (!target) return undefined;
+        // `importer` is the importing FILE, `resolveDir` already a directory.
+        const from = args.importer ? dirname(args.importer) : args.resolveDir;
+        try {
+          return { path: bun.resolveSync(target, from && from.length > 0 ? from : process.cwd()) };
+        } catch {
+          return undefined;
+        }
+      });
+    },
+  };
+}
+
+/** The unresolved specifier a Bun diagnostic is about, or null when it isn't
+ *  a resolve failure. `ResolveMessage` carries it as a field; parsing the
+ *  message text is the fallback. */
+function readUnresolvedSpecifier(diag: unknown): string | null {
+  if (!diag || typeof diag !== "object") return null;
+  const d = diag as { specifier?: unknown; message?: unknown };
+  if (typeof d.specifier === "string" && d.specifier.length > 0) return d.specifier;
+  const message = typeof d.message === "string" ? d.message : "";
+  const m = /Could not resolve:?\s*"([^"]+)"/.exec(message);
+  return m ? m[1] : null;
+}
+
+/** Flatten a bundler failure into the diagnostics it actually carries.
+ *  Bun reports through two channels and both land here: a THROWN
+ *  `AggregateError("Bundle failed")` whose real messages hide in `.errors`,
+ *  and a returned `logs` array on `success: false`. */
+function flattenDiagnostics(failure: unknown): unknown[] {
+  const out: unknown[] = [];
+  const seen = new Set<unknown>();
+  const walk = (node: unknown, depth: number): void => {
+    if (!node || depth > 4 || seen.has(node)) return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+      for (const sub of node) walk(sub, depth + 1);
+      return;
+    }
+    out.push(node);
+    if (typeof node === "object") {
+      const n = node as { errors?: unknown; cause?: unknown };
+      if (Array.isArray(n.errors)) for (const sub of n.errors) walk(sub, depth + 1);
+      if (n.cause) walk(n.cause, depth + 1);
+    }
+  };
+  walk(failure, 0);
+  return out;
+}
+
+function diagnosticText(diag: unknown): string {
+  if (diag instanceof Error) return diag.message || String(diag);
+  if (diag && typeof diag === "object" && typeof (diag as { message?: unknown }).message === "string") {
+    return (diag as { message: string }).message;
+  }
+  return String(diag);
+}
+
+/**
+ * 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 function explainBundleFailure(err: unknown, label: string): string {
+  const diagnostics = flattenDiagnostics(err);
+  const unresolved: string[] = [];
+  for (const diag of diagnostics) {
+    const specifier = readUnresolvedSpecifier(diag);
+    if (specifier && !unresolved.includes(specifier)) unresolved.push(specifier);
+  }
+
+  if (unresolved.length > 0) {
+    const quoted = unresolved.map((s) => `"${s}"`).join(", ");
+    return (
+      `Could not resolve ${quoted} — workflow source imports the platform SDK as "${SDK_PACKAGE}". ` +
+      `Fix the import specifier in ${label}; anything that is genuinely a third-party ` +
+      `package must be installed where the source is bundled.`
+    );
+  }
+
+  const detail = diagnostics
+    .map(diagnosticText)
+    .filter((t) => t.length > 0 && t !== "Bundle failed")
+    .join("\n");
+  return `Failed to bundle ${label}:\n${detail || "the bundler reported no diagnostics"}`;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
   // Use globalThis to access Bun without a compile-time dependency on @types/bun.
-  const bun = globalThis as unknown as { Bun?: { build(opts: { entrypoints: string[]; format: string; target: string }): Promise<{ success: boolean; outputs: { text(): Promise<string> }[]; logs: { message: string }[] }> } };
+  const bun = globalThis as unknown as { Bun?: BunSurface };
   if (!bun.Bun?.build) throw new Error("bundleWorkflow requires the Bun runtime (Bun.build)");
   // target: "node" — the bundle runs inside the Vercel sandbox under Node 22+.
   //
@@ -141,9 +335,24 @@ async function bundle(path: string, label: string): Promise<string> {
   // Pure-ESM workflows (e.g. only importing `@agent-compose/sdk`) bundled
   // identically under either target — that's why this bug stayed hidden
   // until the first workflow that pulled CJS deps got dispatched.
-  const result = await bun.Bun.build({ entrypoints: [path], format: "esm", target: "node" });
+  //
+  // The alias plugin rewrites known near-miss SDK specifiers before Bun's
+  // resolver sees them; whatever still fails to resolve comes back through
+  // `explainBundleFailure` naming the real package instead of Bun's
+  // "Maybe you need to `bun install`?".
+  let result: Awaited<ReturnType<BunSurface["build"]>>;
+  try {
+    result = await bun.Bun.build({
+      entrypoints: [path], format: "esm", target: "node",
+      plugins: [sdkAliasPlugin(bun.Bun)],
+    });
+  } catch (err) {
+    // Modern Bun.build THROWS AggregateError("Bundle failed") on a resolve
+    // or transform error rather than returning `success: false`.
+    throw new WorkflowSourceValidationError(explainBundleFailure(err, label));
+  }
   if (!result.success) {
-    throw new Error(`Failed to bundle ${label}:\n${result.logs.map((l) => l.message).join("\n")}`);
+    throw new WorkflowSourceValidationError(explainBundleFailure(result.logs, label));
   }
   return result.outputs[0].text();
 }
@@ -371,6 +580,7 @@ export async function bundleWorkflow(
     ...(metadata.connectorOperation  !== undefined ? { connectorOperation:  metadata.connectorOperation }  : {}),
     ...(metadata.invokePolicy        !== undefined ? { invokePolicy:        metadata.invokePolicy }        : {}),
     ...(metadata.environmentBuild    !== undefined ? { environmentBuild:    metadata.environmentBuild }    : {}),
+    ...(metadata.factoryDrive        !== undefined ? { factoryDrive:        metadata.factoryDrive }        : {}),
   };
 }