@agent-compose/sdk 0.8.0 → 0.8.2

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

@@ -146,11 +146,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
@@ -231,6 +232,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.2",
   "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-context.ts

@@ -173,38 +173,49 @@ there is nothing to type, paste, or screenshot a credential from.
 
 ## Recording a demo — the desktop, captured to a video the human can play
 
-"Record a demo of you using X" is a normal ask, and this machine does it:
-start a screen recording, drive the app with \`xdotool\` exactly as in Computer
-Use, stop the recording, and report the file. (For a LIVE view no recording is
-needed — the session header's **Desktop** button already streams this display
-to any teammate watching; a recording is the durable, replayable artifact.
-Both modes exist; say so when it matters.)
+"Record a demo of you using X" is a normal ask, and this machine does it.
+(For a LIVE view no recording is needed — the session header's **Desktop**
+button already streams this display to any teammate watching; a recording is
+the durable, replayable artifact. Both modes exist; say so when it matters.)
 
-**ffmpeg is NOT pre-installed** — install it first, once per machine:
+**Use \`ac-record\` — the platform recorder is already on PATH** (cloud
+sessions; \`command -v ac-record\` to confirm on older machines):
 
-    sudo apt-get update -q && sudo apt-get install -y -q ffmpeg
+    ac-record start     # begins capturing the desktop (display :0)
+    # ... drive the app with xdotool, screenshotting as you go ...
+    ac-record stop      # finishes + saves to recordings/ in your workspace
+    ac-record status    # one JSON line: {"recording":true,...}
+
+It records the whole display (with desktop audio when the machine has a
+PulseAudio monitor), enforces sane caps (5 min / 200 MB — start a fresh
+recording per scene rather than one long take), keeps the file playable even
+if the machine dies mid-take, and \`stop\` prints the saved path — the file
+lands ON THE DRIVE in \`recordings/\`, visible in Files and playable in the
+dashboard. A human watching the Desktop pane sees the recording indicator
+while you record.
 
-(drop \`sudo\` if you are already root). Then the whole recipe:
+If \`ac-record\` is missing (older machine), record by hand.
+**ffmpeg IS pre-installed** on platform images (\`command -v ffmpeg\`; only
+if absent: \`sudo apt-get update -q && sudo apt-get install -y -q ffmpeg\`):
 
     DISPLAY=:0 ffmpeg -f x11grab \\
       -video_size "$(DISPLAY=:0 xdotool getdisplaygeometry | tr ' ' x)" \\
       -framerate 10 -i :0 -c:v libvpx -b:v 1M -deadline realtime -cpu-used 8 \\
       demo.webm &
     FFMPEG_PID=$!
-    # ... drive the app with xdotool, screenshotting as you go ...
+    # ... drive the app with xdotool ...
     kill -INT "$FFMPEG_PID" && wait "$FFMPEG_PID"
 
-The gotchas, each one earned:
+The hand-rolled gotchas, each one earned:
 - **Stop with SIGINT (\`kill -INT\`), never SIGKILL** — ffmpeg finalizes the
   file on SIGINT; a hard kill truncates the encode mid-write.
-- **Record WebM (matroska-family), not MP4** — mp4 writes its moov atom at the
-  END, so a killed or crashed encode leaves an UNPLAYABLE file; webm stays
-  playable up to the last written frame and plays natively in the browser.
-  MP4's only edge is compatibility with some external players — transcode
-  afterwards if you truly need it, never record straight to it.
+- **Record WebM (matroska-family), not plain MP4** — mp4 writes its moov atom
+  at the END, so a killed or crashed encode leaves an UNPLAYABLE file; webm
+  stays playable up to the last written frame and plays natively in the
+  browser. (\`ac-record\` sidesteps this with fragmented mp4.)
 - **\`-video_size\` must match the real screen** — x11grab does not default to
   it; read the geometry from \`xdotool getdisplaygeometry\` as above.
-- **10–12 fps is right for a screen demo** — small files, legible UI motion;
+- **10–15 fps is right for a screen demo** — small files, legible UI motion;
   this is not video production.
 - **Write to the drive, not /tmp** — the recording must land in your working
   directory to persist and show up in Files; a file in /tmp dies with the

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 }                    : {}),