@agent-compose/sdk 0.8.0 → 0.8.2

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

package/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

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

package/src/workflow-steps/workflow.ts

@@ -77,6 +77,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 function createStepWorkflow<TInput, TOutput>(

package/src/workflows/invoke-child.ts

@@ -1,6 +1,32 @@
 import { AgentComposeClient } from "../client.js";
+import { getActiveStep, nextPauseOrdinalInActiveStep } from "../active-step.js";
 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 function deriveInvokeChildIdempotencyKey(parentRunId: string, childName: string): string | null {
+  const step = getActiveStep();
+  if (!step) return null;
+  const ordinal = nextPauseOrdinalInActiveStep(`invoke-child:${childName}`);
+  if (ordinal === null) return null;
+  return `invoke-child:${parentRunId}:step${step.stepIndex}:${childName}:${ordinal}`;
+}
+
 /**
  * Build the public-API child workflow invoker used by legacy and sandboxed
  * workflow execution. Provider-backed engines may inject a different
@@ -21,15 +47,25 @@ export function buildInvokeChild(
     childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
-  return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
-    ...childOpts,
-    parentRunId: runId,
-    // The runner sets `AGENT_COMPOSE_FACTORY` (the run's factory slug — see
-    // activities.ts loadRunnerEnvs). Default the child to it so it lands in the
-    // SAME factory as the parent — the per-run API key is factory-scoped, so a
-    // child dispatched into another factory 403s. (Was reading the never-set
-    // `AGENT_COMPOSE_FACTORY_SLUG`, silently falling back to "default".)
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug
-      ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
-  });
+  return (name, input, childOpts) => {
+    // Replay-safe dispatch: derive a deterministic per-step key so a step
+    // re-entered after pause/resume (or a crash-replayed attempt) dedupes to
+    // the original child run instead of double-dispatching. An explicit
+    // caller-supplied key wins.
+    const idempotencyKey = childOpts?.idempotencyKey
+      ?? deriveInvokeChildIdempotencyKey(runId, name)
+      ?? undefined;
+    return getChildClient().invokeAndWait(name, input, {
+      ...childOpts,
+      ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
+      parentRunId: runId,
+      // The runner sets `AGENT_COMPOSE_FACTORY` (the run's factory slug — see
+      // activities.ts loadRunnerEnvs). Default the child to it so it lands in the
+      // SAME factory as the parent — the per-run API key is factory-scoped, so a
+      // child dispatched into another factory 403s. (Was reading the never-set
+      // `AGENT_COMPOSE_FACTORY_SLUG`, silently falling back to "default".)
+      factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug
+        ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
+    });
+  };
 }