@agent-compose/sdk 0.5.7 → 0.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/dist/agent/__tests__/run-agent-liveness.test.d.ts +17 -0
  2. package/dist/agent/agent-context.d.ts +67 -0
  3. package/dist/agent/agent-loop.d.ts +23 -12
  4. package/dist/agent/local-pause-request.d.ts +49 -0
  5. package/dist/agent/local-pause-request.test.d.ts +1 -0
  6. package/dist/agent/steer-control.d.ts +22 -6
  7. package/dist/client.d.ts +76 -2
  8. package/dist/index.d.ts +10 -5
  9. package/dist/index.js +2409 -1457
  10. package/dist/pause/checkpoint.d.ts +27 -10
  11. package/dist/pause/manager.d.ts +1 -0
  12. package/dist/pause/pause-core.d.ts +23 -0
  13. package/dist/pause/state-dir.d.ts +1 -1
  14. package/dist/pause/wrappers.d.ts +7 -11
  15. package/dist/processors/builtins.d.ts +20 -1
  16. package/dist/processors/index.d.ts +1 -1
  17. package/dist/processors/processor.d.ts +13 -0
  18. package/dist/runtimes/_acp-client.d.ts +140 -0
  19. package/dist/runtimes/_cli-agent.d.ts +155 -3
  20. package/dist/runtimes/amp.d.ts +2 -2
  21. package/dist/runtimes/cli-agent-acp-live.test.d.ts +30 -0
  22. package/dist/runtimes/cli-agent.test.d.ts +22 -6
  23. package/dist/runtimes/codex.d.ts +7 -2
  24. package/dist/runtimes/openai-desktop.js +2394 -1457
  25. package/dist/runtimes/vercel.js +389 -2
  26. package/dist/sandbox.d.ts +132 -14
  27. package/dist/step-invocation/types.d.ts +1 -1
  28. package/dist/types/__tests__/environment-build-flag.test.d.ts +1 -0
  29. package/dist/types/__tests__/workflow-metadata-provider.test.d.ts +1 -0
  30. package/dist/types/execution-context.d.ts +1 -11
  31. package/dist/types/protocol.d.ts +32 -1
  32. package/dist/types/runtime.d.ts +7 -0
  33. package/dist/types/sandbox-environment.d.ts +6 -1
  34. package/dist/types/sandbox.d.ts +41 -6
  35. package/dist/types/workflow-metadata.d.ts +47 -6
  36. package/dist/types/workflow.d.ts +27 -4
  37. package/dist/utils/bundler.d.ts +7 -1
  38. package/dist/workflow-steps/observability.d.ts +28 -2
  39. package/dist/workflow-steps/types.d.ts +11 -7
  40. package/dist/workflow-steps/workflow.d.ts +5 -1
  41. package/package.json +3 -2
  42. package/src/agent/agent-context.ts +220 -0
  43. package/src/agent/agent-loop.ts +90 -22
  44. package/src/agent/local-pause-request.ts +90 -0
  45. package/src/agent/run-agent.ts +43 -3
  46. package/src/agent/steer-control.ts +21 -7
  47. package/src/client.ts +123 -2
  48. package/src/index.ts +16 -4
  49. package/src/pause/checkpoint.ts +33 -14
  50. package/src/pause/manager.ts +2 -2
  51. package/src/pause/pause-core.ts +35 -0
  52. package/src/pause/state-dir.ts +2 -2
  53. package/src/pause/wrappers.ts +7 -21
  54. package/src/processors/builtins.ts +44 -1
  55. package/src/processors/index.ts +1 -0
  56. package/src/processors/processor.ts +13 -0
  57. package/src/runtimes/_acp-client.ts +516 -0
  58. package/src/runtimes/_cli-agent.ts +418 -3
  59. package/src/runtimes/claude.ts +27 -3
  60. package/src/runtimes/codex.ts +21 -1
  61. package/src/runtimes/vercel.ts +4 -1
  62. package/src/sandbox.ts +429 -67
  63. package/src/step-invocation/types.ts +1 -1
  64. package/src/types/execution-context.ts +1 -11
  65. package/src/types/protocol.ts +27 -1
  66. package/src/types/runtime.ts +7 -0
  67. package/src/types/sandbox-environment.ts +12 -1
  68. package/src/types/sandbox.ts +40 -6
  69. package/src/types/workflow-metadata.ts +51 -6
  70. package/src/types/workflow.ts +27 -6
  71. package/src/utils/bundler.ts +9 -1
  72. package/src/workflow-steps/observability.ts +51 -5
  73. package/src/workflow-steps/runner.ts +9 -5
  74. package/src/workflow-steps/types.ts +11 -7
  75. package/src/workflow-steps/workflow.ts +5 -1
  76. package/src/workflows/invoke-child.ts +7 -1
@@ -27,6 +27,23 @@ export interface AgentMessageToolResult extends AgentMessageBase {
27
27
  toolUseId: string;
28
28
  output: string;
29
29
  isError: boolean;
30
+ /** Structured file diffs produced by the tool call, carried alongside the
31
+ * rendered `output` so a richer renderer can use the structure without
32
+ * re-plumbing the normaliser. Sourced from ACP `tool_call`/`tool_call_update`
33
+ * `diff` content blocks (WS-C / ADR-0020 Q3). Optional and additive:
34
+ * existing producers (claude / vercel / legacy JSONL) omit it. `oldText` is
35
+ * null for a newly created file. */
36
+ diffs?: {
37
+ path: string;
38
+ oldText: string | null;
39
+ newText: string;
40
+ }[];
41
+ /** File locations touched by the tool call (ACP `locations` field), enabling
42
+ * "follow-along" UI. Optional and additive (WS-C / ADR-0020 Q3). */
43
+ locations?: {
44
+ path: string;
45
+ line?: number;
46
+ }[];
30
47
  }
31
48
  export interface AgentMessageDone extends AgentMessageBase {
32
49
  type: "done";
@@ -45,7 +62,21 @@ export interface AgentMessageUsage extends AgentMessageBase {
45
62
  durationMs: number;
46
63
  numTurns: number;
47
64
  }
48
- export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage;
65
+ /** Structured execution plan emitted by an agent (ACP `plan` session update,
66
+ * WS-C / ADR-0020 Q2). Each `plan` notification REPLACES the whole plan — the
67
+ * normaliser emits one `AgentMessagePlan` per notification carrying the entire
68
+ * `entries` array, and downstream treats the latest as authoritative. This is
69
+ * NOT an `AgentStatus` and does not feed self-pause; it is observability only.
70
+ * Additive 9th kind: existing producers never emit it. */
71
+ export interface AgentMessagePlan extends AgentMessageBase {
72
+ type: "plan";
73
+ entries: {
74
+ content: string;
75
+ priority: "high" | "medium" | "low";
76
+ status: "pending" | "in_progress" | "completed";
77
+ }[];
78
+ }
79
+ export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessagePlan;
49
80
  /** Status block the agent emits to signal iteration completion or blockers. */
50
81
  export interface AgentStatus {
51
82
  summary: string;
@@ -4,6 +4,7 @@
4
4
  import type { SandboxProvider } from "./sandbox.js";
5
5
  import type { AgentMessage } from "./protocol.js";
6
6
  import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
7
+ import type { BoundaryPauseFn } from "../pause/pause-core.js";
7
8
  import type { RequestContext } from "../request-context/request-context.js";
8
9
  /** Configuration for a single MCP server. */
9
10
  export interface McpServerConfig {
@@ -28,6 +29,12 @@ export interface RuntimeOptions {
28
29
  /** Agent id and label for processor context / adapter logs. */
29
30
  agentId?: string;
30
31
  iteration?: number;
32
+ /** The run's pause boundary, threaded from the agent loop so a runtime-driven
33
+ * pre-tool gate (e.g. the ACP `session/request_permission` path through
34
+ * `gateToolCall`) can raise a human-approval `ctx.pause`. The runtime binds it
35
+ * to the current `{ agentId, iteration }` when it builds a ProcessorContext.
36
+ * Absent ⇒ a processor pause throws (no boundary; see `boundProcessorPause`). */
37
+ pause?: BoundaryPauseFn;
31
38
  /** Optional JSON schema for runtimes with native structured-output support. */
32
39
  outputFormat?: {
33
40
  type: "json_schema";
@@ -35,7 +35,7 @@
35
35
  */
36
36
  import type { SandboxProvider } from "./sandbox.js";
37
37
  import type { Workflow } from "../workflow-steps/types.js";
38
- import type { SnapshotConfig } from "./workflow-metadata.js";
38
+ import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
39
39
  export interface SandboxEnvironmentDefinition {
40
40
  name: string;
41
41
  description?: string;
@@ -45,6 +45,11 @@ export interface SandboxEnvironmentDefinition {
45
45
  * useful — an env with no snapshot can't be referenced as a
46
46
  * `bootFrom` on another workflow). */
47
47
  snapshots?: SnapshotConfig;
48
+ /** Which substrate to build this environment on (and any sizing).
49
+ * An env image is provider-specific — a snapshot captured on E2B
50
+ * can't boot on Vercel and vice-versa — so building the E2B base/
51
+ * agent-env requires `resources: { provider: "e2b" }`. */
52
+ resources?: SandboxResources;
48
53
  }
49
54
  /** Sugar over `defineWorkflow` for setup-only workflows that exist to
50
55
  * capture a snapshot. The workflow takes no meaningful input and returns
@@ -21,6 +21,36 @@ export interface SandboxCommandResult {
21
21
  stdout: string;
22
22
  stderr: string;
23
23
  }
24
+ /** A spawned long-lived command with a writable stdin and readable stdout,
25
+ * exposed as byte web-streams. Unlike `commands.run` (which buffers to
26
+ * completion and exposes stdout only via an `onStdout` callback), a duplex
27
+ * handle keeps the process alive and lets the caller WRITE to its stdin —
28
+ * the half `commands.run` cannot provide. It is the transport the ACP client
29
+ * (`AcpClientPeer` over `ndJsonStream`) needs: the agent CLI reads JSON-RPC
30
+ * request frames on stdin and answers on stdout.
31
+ *
32
+ * Only `makeLocalSandboxProvider` implements it. The runner runs IN the
33
+ * sandbox VM and spawns CLIs via the local provider (a plain `child_process`
34
+ * pipe), so a duplex stdin works identically on Vercel/E2B/local. The
35
+ * vercel/e2b providers are the SERVER→sandbox view and never spawn the in-VM
36
+ * CLI, so they leave `spawnDuplex` undefined and callers fall back cleanly. */
37
+ export interface SandboxDuplexProcess {
38
+ /** Subprocess stdin. JSON-RPC request frames are written here. */
39
+ stdin: WritableStream<Uint8Array>;
40
+ /** Subprocess stdout. JSON-RPC response/notification frames arrive here. */
41
+ stdout: ReadableStream<Uint8Array>;
42
+ /** Resolves when the subprocess exits, carrying the captured stderr tail. */
43
+ exited: Promise<{
44
+ exitCode: number;
45
+ stderr: string;
46
+ }>;
47
+ /** Force-terminate the subprocess. */
48
+ kill(): void;
49
+ }
50
+ export interface SandboxSpawnDuplexOptions {
51
+ cwd?: string;
52
+ envs?: Record<string, string>;
53
+ }
24
54
  /**
25
55
  * A sandbox provider implements the RAW provider operations only. It does NOT
26
56
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -43,6 +73,11 @@ export interface SandboxProvider {
43
73
  cwd?: string;
44
74
  commands: {
45
75
  run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
76
+ /** Spawn a long-lived command with a real duplex stdin/stdout. OPTIONAL —
77
+ * implemented only by `makeLocalSandboxProvider` (the in-VM `child_process`
78
+ * view). The vercel/e2b providers (server→sandbox) leave it undefined; an
79
+ * ACP caller that finds it absent falls back to the JSONL transport. */
80
+ spawnDuplex?(cmd: string, opts?: SandboxSpawnDuplexOptions): SandboxDuplexProcess;
46
81
  };
47
82
  files: {
48
83
  write(path: string, content: string): Promise<void>;
@@ -60,12 +95,12 @@ export interface SandboxProvider {
60
95
  snapshotId: string;
61
96
  sizeBytes?: number;
62
97
  }>;
63
- /** Replace the live sandbox's egress policy in place. Vercel implements
64
- * it via `sandbox.update({ networkPolicy })` (2.x) so the server can
65
- * push a freshly resolved policy — with re-minted connector access
66
- * tokens — before each step instead of relying on the policy baked at
67
- * create. Providers whose enforcement lives inside the VM (E2B
68
- * iron-proxy) leave it undefined. */
98
+ /** Replace the live sandbox's egress policy in place — so the server can
99
+ * push a freshly resolved policy (with re-minted connector access tokens)
100
+ * before each step instead of relying on the policy baked at create.
101
+ * Vercel implements it via `sandbox.update({ networkPolicy })` (2.x); E2B
102
+ * via its native `sandbox.updateNetwork(...)`. Providers without a live
103
+ * network-update primitive leave it undefined. */
69
104
  updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
70
105
  }
71
106
  /** Stateless provider-level snapshot deletion — no live sandbox needed,
@@ -8,8 +8,13 @@
8
8
  * Keep this module free of value imports from `types/workflow.ts` or
9
9
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
10
10
  */
11
- import type { SandboxNetworkPolicy } from "../sandbox.js";
11
+ import type { SandboxNetworkPolicy, SandboxSize, SandboxProviderName } from "../sandbox.js";
12
12
  import type { Processor } from "../processors/processor.js";
13
+ /** The sandbox providers selectable per-workflow. A narrowing of
14
+ * `SandboxProviderName` to the two substrates that execute step workloads —
15
+ * `e2b-desktop` (registry-only, never a workflow's runtime) is deliberately
16
+ * excluded so a workflow can only ask for a substrate that actually runs steps. */
17
+ export type WorkflowSandboxProvider = Extract<SandboxProviderName, "vercel" | "e2b">;
13
18
  /**
14
19
  * Workflow-level metadata read by the server at registration. Lives on
15
20
  * every `Workflow` as `workflow.metadata`, regardless of which form of
@@ -75,11 +80,14 @@ export interface IOSchema {
75
80
  /** Alias kept for backwards source-compatibility with the original
76
81
  * output-only release. New code should prefer `IOSchema`. */
77
82
  export type OutputSchema = IOSchema;
78
- /** Per-connector HTTP request matcher (Tier-2 capability narrowing). The
79
- * iron-proxy / firewall consults these when deciding whether to attach the
80
- * brokered Authorization header to an outbound request. A request to the
81
- * connector host whose method is not in `methods`, or whose path matches no
82
- * entry in `pathPrefixes`, is refused (403) and the token is WITHHELD. */
83
+ /** Per-connector HTTP request matcher (Tier-2 capability narrowing). Vercel's
84
+ * firewall consults these when deciding whether to attach the brokered
85
+ * Authorization header to an outbound request: a request to the connector
86
+ * host whose method is not in `methods`, or whose path matches no entry in
87
+ * `pathPrefixes`, goes out WITHOUT the token. NOT enforced on E2B — its
88
+ * native rules carry only a header transform, no method/path matcher, so the
89
+ * token rides every request to an allowed connector host there (the host
90
+ * allowlist still confines which hosts are reachable). See `toE2bNetwork`. */
83
91
  export interface ConnectorRequestRules {
84
92
  /** Allowed HTTP methods (upper-case). Omit = any method (subject to
85
93
  * `access`). */
@@ -134,6 +142,24 @@ export interface InvokePolicy {
134
142
  apiKeys?: string[];
135
143
  workflows?: string[];
136
144
  }
145
+ /** Sandbox machine resources for a workflow's runs. A coarse size knob
146
+ * today; kept as its own object so finer controls (disk, gpu, …) can be
147
+ * added later without reshaping `WorkflowMetadata`. */
148
+ export interface SandboxResources {
149
+ /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
150
+ * (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
151
+ * provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
152
+ * per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
153
+ * ignores this. */
154
+ size?: SandboxSize;
155
+ /** Sandbox provider this workflow's runs execute on — `"vercel"` or
156
+ * `"e2b"`. Optional and additive: omit and the run resolves to the
157
+ * platform default (`vercel`). Set explicitly to pin a workflow to a
158
+ * substrate regardless of the deployment default. Snapshot formats are
159
+ * provider-specific, so the resolved provider is stamped on the run row
160
+ * at first dispatch and reused across pause/resume/replay. */
161
+ provider?: WorkflowSandboxProvider;
162
+ }
137
163
  export interface WorkflowMetadata {
138
164
  /** One-line, human-readable description of what the workflow does.
139
165
  * Surfaced on the dashboard template tile + run page header. Authors
@@ -154,6 +180,9 @@ export interface WorkflowMetadata {
154
180
  outputSchema?: IOSchema;
155
181
  /** All snapshot config — boot source + capture mode. */
156
182
  snapshots?: SnapshotConfig;
183
+ /** Sandbox machine resources — size + provider. Optional; omit → smallest
184
+ * SKU on the platform-default provider (`vercel`). */
185
+ resources?: SandboxResources;
157
186
  processors?: readonly Processor[];
158
187
  /** Connector requirements — providers whose APIs this workflow calls.
159
188
  * Dispatch resolves an authorized grant per provider and injects a
@@ -165,6 +194,18 @@ export interface WorkflowMetadata {
165
194
  /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
166
195
  * See `InvokePolicy`. */
167
196
  invokePolicy?: InvokePolicy;
197
+ /** Set by `defineSandboxEnvironment` to mark this workflow as an ENVIRONMENT
198
+ * BUILD — a setup-only workflow whose job is to leave its VM configured and
199
+ * snapshot it (base-env / agent-env). Environment builds build a platform
200
+ * IMAGE and never use the shared factory drive, so the server SKIPS mounting
201
+ * /factory for them: a live Archil mount baked into the captured snapshot
202
+ * fails the NEXT boot's re-mount ("an older Archil process is still running
203
+ * for this mountpoint"), degrading /factory for every workflow booting from
204
+ * that snapshot. Absent on ordinary workflows — which mount /factory exactly
205
+ * as before. Optional + additive: an ABSENT flag contributes nothing to the
206
+ * canonical metadata hash (frozen-metadata rule), so existing workflows are
207
+ * not forced to re-register. */
208
+ environmentBuild?: boolean;
168
209
  }
169
210
  /**
170
211
  * Pull the server-readable declarations off a source object (run-form
@@ -27,8 +27,8 @@ export type { WorkflowMetadata } from "./workflow-metadata.js";
27
27
  export interface AgentEventSink {
28
28
  emit(event: AgentLifecycleEvent): void | Promise<void>;
29
29
  }
30
- import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
31
- export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema };
30
+ import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
31
+ export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources };
32
32
  /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
33
33
  * can type per-invoke budget overrides they pass as workflow input. */
34
34
  export interface AgentBudget {
@@ -41,9 +41,16 @@ export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<str
41
41
  /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
42
42
  setMetadata: (data: Record<string, unknown>) => Promise<void>;
43
43
  /**
44
- * Wrap a named step for observability. Emits step_started / step_completed /
45
- * step_failed lifecycle events with duration. Use for long phases you want
44
+ * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
45
+ * the sandbox state-dir; on a pause-resume re-entry the recorded value is
46
+ * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
47
+ * emits substep_started / substep_completed / substep_failed lifecycle
48
+ * events with duration — use for long phases you want both durable and
46
49
  * visible on the run's timeline (setup, external API calls, submit).
50
+ *
51
+ * Names must be unique within a step body (they key the memoise file).
52
+ * A body that pauses is never memoised — the resume re-runs it. For
53
+ * cross-process side effects (DB writes, emails) use `invokeChild`.
47
54
  */
48
55
  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
49
56
  /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
@@ -100,6 +107,15 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
100
107
  * `invoke({ snapshots })` overrides this default.
101
108
  */
102
109
  snapshots?: SnapshotConfig;
110
+ /**
111
+ * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
112
+ * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
113
+ * (`vercel` | `e2b`). `size` maps to provider machine specs at create
114
+ * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
115
+ * ignores it. Optional; omit → smallest SKU on the default provider.
116
+ * Per-invocation `invoke({ size })` overrides the size.
117
+ */
118
+ resources?: SandboxResources;
103
119
  /**
104
120
  * Outbound network policy for the runner sandbox.
105
121
  * Use "*": [] to allow all traffic while still injecting headers for specific domains.
@@ -171,6 +187,13 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
171
187
  * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
172
188
  */
173
189
  invokePolicy?: InvokePolicy;
190
+ /**
191
+ * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
192
+ * Marks the workflow as an environment build (base-env / agent-env) so the
193
+ * server skips mounting the shared factory drive for its runs (#13). See
194
+ * `WorkflowMetadata.environmentBuild`.
195
+ */
196
+ environmentBuild?: boolean;
174
197
  }
175
198
  /**
176
199
  * Declare a workflow. Two forms; both return a `Workflow` whose
@@ -20,7 +20,7 @@
20
20
  * manifest's `sourceHash` against the source it received.
21
21
  */
22
22
  import type { SnapshotConfig } from "../types/workflow.js";
23
- import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "../types/workflow-metadata.js";
23
+ import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "../types/workflow-metadata.js";
24
24
  import type { SandboxNetworkPolicy } from "../sandbox.js";
25
25
  import { type WorkflowPlan } from "../types/workflow-plan.js";
26
26
  /** Bumped when the manifest contract changes in a way the server should
@@ -84,6 +84,9 @@ export interface BundledWorkflow {
84
84
  /** Snapshot config from the workflow definition — `bootFrom` (where to
85
85
  * restore at run start), `save`, `retain`. */
86
86
  snapshots?: SnapshotConfig;
87
+ /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
88
+ * SKU (`size`) and `provider` (`vercel` | `e2b`). */
89
+ resources?: SandboxResources;
87
90
  workflowPlan: WorkflowPlan;
88
91
  /** Compact JSON-Schema-shaped description of the workflow's input
89
92
  * type. Extracted from the workflow's declared `input` zod schema
@@ -98,6 +101,9 @@ export interface BundledWorkflow {
98
101
  /** Tier-1 invoke ACL — who may dispatch this connector-brokering
99
102
  * workflow (`defineWorkflow({ invokePolicy })`). */
100
103
  invokePolicy?: InvokePolicy;
104
+ /** Set by `defineSandboxEnvironment` — marks an environment build so the
105
+ * server skips the /factory mount for its runs (#13). */
106
+ environmentBuild?: boolean;
101
107
  }
102
108
  /**
103
109
  * Parse the bundled source and assert the default export is a CallExpression
@@ -31,13 +31,19 @@
31
31
  import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
32
32
  import type { AgentEventSink } from "../types/workflow.js";
33
33
  import type { LiveAgentEventEmitter } from "./run-callback.js";
34
+ import type { ScopedMemoize } from "../pause/checkpoint.js";
34
35
  /** One named sub-step (from `ctx.step("name", async () => ...)`).
35
- * Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
36
+ * Becomes a `workflow_substep_*` lifecycle event on the run timeline.
37
+ *
38
+ * `restored` is the durable-step resume case (ADR-0012): the body did NOT
39
+ * re-run — its memoised result was read from the state-dir checkpoint a
40
+ * prior subprocess wrote. Always `durationMs: 0` (no work happened this
41
+ * pass) and never carries `error`. */
36
42
  export interface SubStepEvent {
37
43
  name: string;
38
44
  startedAt: number;
39
45
  durationMs: number;
40
- status: "completed" | "failed";
46
+ status: "completed" | "failed" | "restored";
41
47
  /** Present when status="failed" — the user error's message. */
42
48
  error?: string;
43
49
  }
@@ -64,14 +70,34 @@ export declare class StepObservabilityCollector {
64
70
  private events;
65
71
  private subSteps;
66
72
  private readonly liveEmitter?;
73
+ /** State-dir memoise bound to this step's `step<idx>` scope. Present in
74
+ * the sandbox runner (durable `ctx.step`); absent in-process so unit
75
+ * tests record observability without touching disk. */
76
+ private readonly memoize?;
77
+ /** Sub-step names already used in THIS step body. A durable `ctx.step`
78
+ * memoises by name, so a reused name would alias two distinct bodies
79
+ * onto one checkpoint file — guarded by throwing on reuse (ADR-0012). */
80
+ private readonly usedStepNames;
67
81
  /** Seqs of events the server confirmed via the live route. */
68
82
  private readonly ackedSeqs;
69
83
  /** Promises for in-flight live emits — awaited at snapshot time. */
70
84
  private readonly inFlight;
71
85
  constructor(opts?: {
72
86
  liveEmitter?: LiveAgentEventEmitter;
87
+ memoize?: ScopedMemoize;
73
88
  });
74
89
  readonly setMetadata: (data: Record<string, unknown>) => Promise<void>;
90
+ /**
91
+ * Durable named sub-step (ADR-0012). The body's result is memoised to the
92
+ * state-dir checkpoint keyed `step<idx>.<name>`; on a pause-resume re-entry
93
+ * the value is read from disk and `fn` is NOT re-run (recorded as a
94
+ * duration-0 `"restored"` sub-step). A body that PAUSES (PauseSignal)
95
+ * propagates BEFORE any memoise write — partial work is never stored, so
96
+ * the resume re-runs it.
97
+ *
98
+ * When no memoise store is wired (in-process tests), the body always runs
99
+ * and is recorded as a normal timed `"completed"` / `"failed"` sub-step.
100
+ */
75
101
  readonly step: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
76
102
  readonly agentEvents: AgentEventSink;
77
103
  /** Wait for in-flight live emits to settle (or timeout) so the
@@ -36,14 +36,18 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
36
36
  */
37
37
  setMetadata(data: Record<string, unknown>): Promise<void>;
38
38
  /**
39
- * Wrap a named sub-step for observability. Emits
40
- * `workflow_substep_started` / `workflow_substep_completed` /
41
- * `workflow_substep_failed` lifecycle events on the run timeline with
42
- * the measured `durationMs`. Use for long sub-phases inside one step
43
- * (setup, external API call, submit).
39
+ * Durable named sub-step (ADR-0012). Runs `fn` once and memoises its
40
+ * result to the state-dir checkpoint keyed `step<idx>.<name>`; on a
41
+ * pause-resume re-entry the value is read from disk and `fn` is NOT
42
+ * re-run. Emits `workflow_substep_started` /
43
+ * `workflow_substep_completed` / `workflow_substep_failed` lifecycle
44
+ * events on the run timeline with the measured `durationMs` — a restored
45
+ * sub-step reports `durationMs: 0` and status `"restored"`.
44
46
  *
45
- * The block runs even if observability flushing fails — instrumentation
46
- * never breaks the workflow.
47
+ * Names must be unique within one step body — they key the memoise file,
48
+ * so a reused name throws. A body that pauses (PauseSignal) is never
49
+ * memoised: the resume re-enters and re-runs it. For cross-process side
50
+ * effects (DB writes, emails) use `invokeChild`, not `step`.
47
51
  */
48
52
  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
49
53
  /**
@@ -20,7 +20,7 @@
20
20
  */
21
21
  import type { z } from "zod";
22
22
  import type { Step, Workflow } from "./types.js";
23
- import type { SnapshotConfig } from "../types/workflow-metadata.js";
23
+ import type { SnapshotConfig, SandboxResources } from "../types/workflow-metadata.js";
24
24
  import type { SandboxNetworkPolicy } from "../sandbox.js";
25
25
  import type { Processor } from "../processors/processor.js";
26
26
  export interface WorkflowBuilder<TInput, TCurrent> {
@@ -46,6 +46,10 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
46
46
  networkPolicy?: SandboxNetworkPolicy;
47
47
  placeholders?: Record<string, string>;
48
48
  snapshots?: SnapshotConfig;
49
+ /** Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string)
50
+ * and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
51
+ * sizing is template-defined. Omit → smallest SKU on the default provider. */
52
+ resources?: SandboxResources;
49
53
  processors?: readonly Processor[];
50
54
  }
51
55
  export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-compose/sdk",
3
- "version": "0.5.7",
3
+ "version": "0.5.9",
4
4
  "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -60,13 +60,14 @@
60
60
  "vitest": "^3.0.0"
61
61
  },
62
62
  "dependencies": {
63
+ "@agentclientprotocol/sdk": "0.29.0",
63
64
  "@anthropic-ai/claude-agent-sdk": "^0.2.129",
64
65
  "@babel/parser": "^7.29.3",
65
66
  "@babel/types": "^7.29.0",
66
67
  "@e2b/desktop": "^1.1.2",
67
68
  "@vercel/sandbox": "^2.2.0",
68
69
  "ai": "^6.0.175",
69
- "e2b": "^2.3.0",
70
+ "e2b": "2.30.5",
70
71
  "ofetch": "^1.5.1",
71
72
  "openai": "^6.33.0",
72
73
  "p-retry": "^6.2.0",