@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.
- package/dist/agent/__tests__/run-agent-liveness.test.d.ts +17 -0
- package/dist/agent/agent-context.d.ts +67 -0
- package/dist/agent/agent-loop.d.ts +23 -12
- package/dist/agent/local-pause-request.d.ts +49 -0
- package/dist/agent/local-pause-request.test.d.ts +1 -0
- package/dist/agent/steer-control.d.ts +22 -6
- package/dist/client.d.ts +76 -2
- package/dist/index.d.ts +10 -5
- package/dist/index.js +2409 -1457
- package/dist/pause/checkpoint.d.ts +27 -10
- package/dist/pause/manager.d.ts +1 -0
- package/dist/pause/pause-core.d.ts +23 -0
- package/dist/pause/state-dir.d.ts +1 -1
- package/dist/pause/wrappers.d.ts +7 -11
- package/dist/processors/builtins.d.ts +20 -1
- package/dist/processors/index.d.ts +1 -1
- package/dist/processors/processor.d.ts +13 -0
- package/dist/runtimes/_acp-client.d.ts +140 -0
- package/dist/runtimes/_cli-agent.d.ts +155 -3
- package/dist/runtimes/amp.d.ts +2 -2
- package/dist/runtimes/cli-agent-acp-live.test.d.ts +30 -0
- package/dist/runtimes/cli-agent.test.d.ts +22 -6
- package/dist/runtimes/codex.d.ts +7 -2
- package/dist/runtimes/openai-desktop.js +2394 -1457
- package/dist/runtimes/vercel.js +389 -2
- package/dist/sandbox.d.ts +132 -14
- package/dist/step-invocation/types.d.ts +1 -1
- package/dist/types/__tests__/environment-build-flag.test.d.ts +1 -0
- package/dist/types/__tests__/workflow-metadata-provider.test.d.ts +1 -0
- package/dist/types/execution-context.d.ts +1 -11
- package/dist/types/protocol.d.ts +32 -1
- package/dist/types/runtime.d.ts +7 -0
- package/dist/types/sandbox-environment.d.ts +6 -1
- package/dist/types/sandbox.d.ts +41 -6
- package/dist/types/workflow-metadata.d.ts +47 -6
- package/dist/types/workflow.d.ts +27 -4
- package/dist/utils/bundler.d.ts +7 -1
- package/dist/workflow-steps/observability.d.ts +28 -2
- package/dist/workflow-steps/types.d.ts +11 -7
- package/dist/workflow-steps/workflow.d.ts +5 -1
- package/package.json +3 -2
- package/src/agent/agent-context.ts +220 -0
- package/src/agent/agent-loop.ts +90 -22
- package/src/agent/local-pause-request.ts +90 -0
- package/src/agent/run-agent.ts +43 -3
- package/src/agent/steer-control.ts +21 -7
- package/src/client.ts +123 -2
- package/src/index.ts +16 -4
- package/src/pause/checkpoint.ts +33 -14
- package/src/pause/manager.ts +2 -2
- package/src/pause/pause-core.ts +35 -0
- package/src/pause/state-dir.ts +2 -2
- package/src/pause/wrappers.ts +7 -21
- package/src/processors/builtins.ts +44 -1
- package/src/processors/index.ts +1 -0
- package/src/processors/processor.ts +13 -0
- package/src/runtimes/_acp-client.ts +516 -0
- package/src/runtimes/_cli-agent.ts +418 -3
- package/src/runtimes/claude.ts +27 -3
- package/src/runtimes/codex.ts +21 -1
- package/src/runtimes/vercel.ts +4 -1
- package/src/sandbox.ts +429 -67
- package/src/step-invocation/types.ts +1 -1
- package/src/types/execution-context.ts +1 -11
- package/src/types/protocol.ts +27 -1
- package/src/types/runtime.ts +7 -0
- package/src/types/sandbox-environment.ts +12 -1
- package/src/types/sandbox.ts +40 -6
- package/src/types/workflow-metadata.ts +51 -6
- package/src/types/workflow.ts +27 -6
- package/src/utils/bundler.ts +9 -1
- package/src/workflow-steps/observability.ts +51 -5
- package/src/workflow-steps/runner.ts +9 -5
- package/src/workflow-steps/types.ts +11 -7
- package/src/workflow-steps/workflow.ts +5 -1
- package/src/workflows/invoke-child.ts +7 -1
package/dist/types/protocol.d.ts
CHANGED
|
@@ -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
|
-
|
|
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;
|
package/dist/types/runtime.d.ts
CHANGED
|
@@ -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
|
package/dist/types/sandbox.d.ts
CHANGED
|
@@ -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
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
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).
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
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
|
package/dist/types/workflow.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
45
|
-
*
|
|
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
|
package/dist/utils/bundler.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
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
|
-
*
|
|
46
|
-
*
|
|
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.
|
|
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": "
|
|
70
|
+
"e2b": "2.30.5",
|
|
70
71
|
"ofetch": "^1.5.1",
|
|
71
72
|
"openai": "^6.33.0",
|
|
72
73
|
"p-retry": "^6.2.0",
|