@providerkit/agents 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gustavo Salomé
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,273 @@
1
- # Temporary Holding Version
1
+ # @providerkit/agents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An agent calls a model, runs the tools it requests and returns an answer.
4
+ Keep its instructions, provider and tools in one place:
5
+
6
+ ```ts
7
+ const result = await writer.run("Explain why a database index speeds up a search.");
8
+ ```
9
+
10
+ A completed result has `status: "completed"` and an `output` value. Other results say whether the
11
+ run failed, was cancelled, reached a limit or is waiting for approval. Check the status before
12
+ using the output.
13
+
14
+ The API may change before 1.0. This package uses `@providerkit/core` for model calls. Its main
15
+ entry has no database, queue or vendor SDK dependency and sends no traces to an external service.
16
+
17
+ ## Set up an agent
18
+
19
+ Install the agent package and core:
20
+
21
+ ```sh
22
+ bun add @providerkit/agents @providerkit/core
23
+ ```
24
+
25
+ Pass a provider you already configured with core:
26
+
27
+ ```ts
28
+ import { defineAgent } from "@providerkit/agents";
29
+ import type { Provider } from "@providerkit/core";
30
+
31
+ export function createWriter(provider: Provider) {
32
+ return defineAgent({
33
+ id: "writer",
34
+ version: "1",
35
+ instructions: "Explain technical topics in short sentences.",
36
+ provider,
37
+ });
38
+ }
39
+ ```
40
+
41
+ Set up routing, fallback models, provider deadlines and retry policy in core. The agent uses that
42
+ provider as supplied; it does not add another retry loop.
43
+
44
+ Change the agent's version when its instructions, tools or result contract change. A saved run
45
+ from another version is refused rather than resumed under different rules.
46
+
47
+ ## Results and progress
48
+
49
+ ```ts
50
+ const result = await writer.run("Explain database indexes.", {
51
+ signal: controller.signal,
52
+ onEvent(event) {
53
+ if (event.type === "model_chunk") {
54
+ render(event.chunk.content ?? "");
55
+ }
56
+ },
57
+ });
58
+
59
+ if (result.status === "completed") {
60
+ console.log(result.output);
61
+ }
62
+ ```
63
+
64
+ The same reader collects the answer and reports progress. An observer failure does not stop the
65
+ work. Tool results and provider metadata stay in the recorded history.
66
+
67
+ | Status | Meaning |
68
+ | ----------- | -------------------------------------------------------------------------- |
69
+ | `completed` | The answer passed the configured result validator. |
70
+ | `suspended` | A tool needs an approval decision from the host. |
71
+ | `cancelled` | The caller stopped the run. Cancellation does not undo an external action. |
72
+ | `limited` | A turn, tool-call, time or provider output limit stopped the run. |
73
+ | `failed` | Execution could not continue. Read `error.code` and `error.message`. |
74
+
75
+ Reasoning without an answer is not success. A provider's length-limited answer is not accepted as
76
+ a complete result. Increase the provider's output allowance when appropriate rather than blindly
77
+ repeating a paid request.
78
+
79
+ ## Tools and checked output
80
+
81
+ Pass core `Tool` instances in `tools`. Their input validation, timeouts and error outcomes remain
82
+ core's responsibility. Unmarked tools run serially. Parallel tool execution requires both the
83
+ core tool's `isConcurrencySafe` flag and the host's permission to batch it. Tools run in your
84
+ process; this package does not provide a sandbox for untrusted code.
85
+
86
+ For a checked result, supply `output.schema` and `output.validate`. The schema tells the model what
87
+ to submit; the validator checks the actual value. Return the desired TypeScript value or throw a
88
+ message explaining what to correct. The SDK reserves the `submit_result` tool name for this path.
89
+ A validator should be pure: it can run again when a completed result is restored.
90
+
91
+ ## Specialists and parallel work
92
+
93
+ An orchestrator can call another configured agent as a tool:
94
+
95
+ ```ts
96
+ const editor = defineAgent({
97
+ id: "editor",
98
+ version: "1",
99
+ instructions: "Ask the reviewer for feedback, then write the final answer.",
100
+ provider,
101
+ tools: [
102
+ reviewer.asTool({
103
+ name: "review",
104
+ description: "Review a draft and identify changes it needs.",
105
+ }),
106
+ ],
107
+ });
108
+ ```
109
+
110
+ The specialist gets the explicit input sent to it, not the parent's conversation. Its result returns
111
+ to the orchestrator; this is not a conversation handoff. Each agent can use a different core provider.
112
+ `asTool` propagates a specialist's stopped outcome. Use `defineDelegation` when your code needs to
113
+ combine several explicit child outcomes.
114
+
115
+ A delegation declares its fixed `specialists` list, input schema and validator. Inside its `run`
116
+ callback, start children before joining them:
117
+
118
+ ```ts
119
+ const draft = context.child("draft", writer, input);
120
+ const review = context.child("review", reviewer, input);
121
+ const [draftResult, reviewResult] = await context.join([draft, review]);
122
+ ```
123
+
124
+ Children start immediately, subject to the shared limit. Joining returns outcomes in the order you
125
+ requested, not the order they finish. Check their statuses and return only what the parent needs,
126
+ not their full snapshots. A suspended child pauses the parent instead of becoming a success string.
127
+
128
+ Coordination callbacks must be pure: use `child` and `join` for work. The callback can run again
129
+ after an interruption, but completed children are reused. Reusing a child key with different input
130
+ or a different agent is refused. Every admitted child settles before the delegation ends.
131
+
132
+ ## Limits and usage
133
+
134
+ Per-run defaults are 12 model turns, 32 tool calls, 5 minutes and at most 3 approved concurrent
135
+ ordinary tools. Change these through `limits` when configuring an agent.
136
+
137
+ The root's `treeLimits` apply across all descendants:
138
+
139
+ | Setting | Default | Counts |
140
+ | ------------- | ------- | --------------------------------------------------------------------------------- |
141
+ | `maxParallel` | 4 | Active agents, including the root. A parent waiting on children lends its slot. |
142
+ | `maxChildren` | 32 | Children in total, not per parent. |
143
+ | `maxDepth` | 4 | Descendant levels; the root is depth 0. |
144
+ | `modelCalls` | 128 | Calls from agent loops to core. Provider-internal retries can send more requests. |
145
+ | `elapsedMs` | 300000 | Wall time, including queueing and waiting for approval, across attempts. |
146
+
147
+ A child's local limits still apply. Set enough time for a human decision when using approval.
148
+ Resuming does not reset the deadline or give the tree a fresh call budget.
149
+
150
+ `usage` describes the current agent's model calls. `treeUsage` includes registered descendants
151
+ without counting recorded work twice. Only model usage reported by providers is known; an
152
+ interrupted call may have cost more than its last report. Ordinary tools' external service charges
153
+ are not included. Prices and billing stay with the host, and these counters are not an exact
154
+ spending cap. Use SDK delegation rather than calling another model directly inside an ordinary
155
+ tool when that work must share the tree's limits and usage.
156
+
157
+ ## Checkpoints and approval
158
+
159
+ A host can save a run through `host.checkpoint`. The SDK records each model or tool operation before
160
+ starting it and records its result afterward. Saved operation IDs remain stable across attempts.
161
+
162
+ `agent.resume(snapshot, options)` requires a trusted `host.authorizeResume` callback. The host must
163
+ load authoritative state, check its owner and prevent concurrent attempts. Valid JSON is not
164
+ permission to run a tool, and a snapshot sent by a browser is not authoritative state.
165
+
166
+ For tools marked `needsApproval`, the host supplies the actor, resource version and expiry through
167
+ `approvalContext`, authenticates and consumes the decision through `resolveApproval`, and checks
168
+ current access through `beforeTool`. Missing approval policy refuses the action. A saved approval
169
+ flag cannot bypass those checks.
170
+
171
+ A suspended result includes the `path` to the exact child call. Pass it as `approvalPath` when
172
+ resuming a descendant decision. Approving the parent does not approve its children's actions.
173
+
174
+ Completed results can be reused. An operation recorded as running has an unknown outcome after a
175
+ crash, so resume refuses to repeat it automatically. An email, payment or paid model call may have
176
+ finished before its result was saved. Reconcile that outcome or use a receiving service that
177
+ honors an idempotency key; a checkpoint alone cannot make the action happen exactly once.
178
+
179
+ Snapshots include prompts, tool arguments and results. The host owns access, storage and retention.
180
+ Progress events are not a substitute for saved execution state.
181
+
182
+ ## Background runs
183
+
184
+ `@providerkit/agents/runs` binds an agent to `@gusnips/server/runs` 0.19 or later. Install that
185
+ optional peer only when using this entry. Supply your existing run service, durable queue callback
186
+ and trusted policy factory:
187
+
188
+ ```ts
189
+ import { createBackgroundAgent } from "@providerkit/agents/runs";
190
+
191
+ const jobs = createBackgroundAgent({
192
+ agent: writer,
193
+ kind: "writer-v1",
194
+ runs,
195
+ enqueue,
196
+ policy,
197
+ });
198
+
199
+ const { id } = await jobs.start(authenticatedOwner, "Write a release note.");
200
+ const saved = await jobs.wait(authenticatedOwner, id);
201
+ ```
202
+
203
+ The owner must come from your authentication code, not an unchecked request field. Reads,
204
+ observation, waiting, cancellation and resume all require it. A worker calls
205
+ `runs.drive(id, jobs.handlers)`. Run `runs.sweep` on boot and periodically to queue unfinished work,
206
+ and call `runs.drain` before shutting down. See [the background example](examples/background.ts)
207
+ for these connections. A stored job without a worker and recovery sweep does not run itself.
208
+
209
+ `start` saves the input before returning an ID. If queueing fails, `BackgroundEnqueueError.id`
210
+ identifies the saved run. Requeue that ID or let the sweep find it; do not create another run.
211
+
212
+ `read` and `wait` return two statuses. `saved.status` describes the host worker run;
213
+ `saved.outcome?.status` describes the agent. A successful worker run can contain a suspended or
214
+ failed agent outcome. Read the latter before treating the answer as complete.
215
+
216
+ Pass an observer signal to `observe` or `wait` to stop listening. That does not cancel the work.
217
+ `cancel(owner, id)` cancels the whole run tree. Children execute in-process under their root's
218
+ lease; they are not independently owned distributed jobs.
219
+
220
+ ### Background approval policy
221
+
222
+ The required `policy` factory receives the authoritative owner and host run ID. It provides the
223
+ same resume and tool checks described above, plus `claimContinuation`. Keep these rules in trusted
224
+ server code:
225
+
226
+ - `authorizeResume` checks stored state and ownership on every attempt.
227
+ - `approvalContext` identifies the actor, resource version and decision expiry.
228
+ - `claimContinuation` authenticates submitted evidence and atomically reserves the exact pending
229
+ decision for one continuation and one host run. Repeating that same claim during recovery must
230
+ succeed; a different claim or host run must fail.
231
+ - `resolveApproval` returns the decision only for that claim. `beforeTool` checks current access
232
+ and resource version again immediately before the action.
233
+
234
+ Return database handles or other worker-only tool values through `policy.context`. They are not
235
+ serialized. Do not put secrets or handles in a saved snapshot.
236
+
237
+ `resume(owner, id, decisionEvidence)` saves a new host run with the same logical agent history.
238
+ It queues evidence, not permission. The worker claims it under its lease after the row exists;
239
+ read or wait on the returned ID to learn whether the decision was accepted. Completed child work
240
+ is retained, and old evidence cannot approve a later tool call. The host must store approval claims
241
+ durably; an in-memory boolean is not sufficient.
242
+
243
+ This binding stores token-usage receipts, not money. It does not call the run service's additive
244
+ `spend()` method or claim atomic billing with checkpoints. Account for recorded operations using
245
+ stable IDs in your own billing system.
246
+
247
+ ## Development
248
+
249
+ From the repository root, run `bun install` and `bun run build`. Then, from `agents/`:
250
+
251
+ ```sh
252
+ bun run lint
253
+ bun run typecheck
254
+ bunx vitest run test/lifecycle.test.ts
255
+ bunx vitest run test/delegation.test.ts
256
+ bun examples/basic.ts
257
+ bun examples/specialists.ts
258
+ ```
259
+
260
+ These checks and examples use fake providers and tools. They do not call a live model or any app.
261
+ The basic example runs a model/tool round. The specialist example runs a manager with two children
262
+ and returns their notes in order. Neither needs an API key.
263
+
264
+ The background integration file needs a disposable local PostgreSQL database named
265
+ `providerkit_agents`. It creates and drops its own schema and starts worker processes that it
266
+ kills deliberately to check recovery. It refuses non-loopback database URLs:
267
+
268
+ ```sh
269
+ AGENTS_TEST_DATABASE_URL=postgresql://postgres@127.0.0.1:5432/providerkit_agents \
270
+ bunx vitest run test/runs.test.ts
271
+ ```
272
+
273
+ Use a throwaway database, not an app database. These checks never call a live model.
@@ -0,0 +1,66 @@
1
+ import { type JsonObjectSchema, type ToolDefinition } from "@providerkit/core";
2
+ import { type ExecutionScope } from "./tree.ts";
3
+ import type { Agent, ChildPathStep, DelegationExecution, RunOptions, RunOutcome, RunSnapshot, ToolResult } from "./types.ts";
4
+ /** Internal symbol holds no execution state. Every invocation receives its own scope. */
5
+ export declare const AGENT_RUNTIME: unique symbol;
6
+ export interface ApprovalEvidence {
7
+ path: readonly ChildPathStep[];
8
+ decision: unknown;
9
+ }
10
+ /** @internal */
11
+ export interface AgentRuntime<T> {
12
+ create(input: string, runId: string, tree?: RunSnapshot["tree"]): RunSnapshot;
13
+ restore(raw: unknown, tree?: RunSnapshot["tree"]): RunSnapshot;
14
+ hydrate(snapshot: RunSnapshot): RunOutcome<T>;
15
+ execute(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, evidence?: ApprovalEvidence): Promise<RunOutcome<T>>;
16
+ }
17
+ export interface ChildHandle<T = unknown> {
18
+ readonly key: string;
19
+ readonly runId: string;
20
+ /** A started child, not another provider call. Repeated joins reuse the same outcome. */
21
+ join(): Promise<RunOutcome<T>>;
22
+ }
23
+ export type Joined<H extends readonly ChildHandle<unknown>[]> = {
24
+ [K in keyof H]: H[K] extends ChildHandle<infer T> ? RunOutcome<T> : never;
25
+ };
26
+ export interface DelegationContext {
27
+ child<T>(key: string, agent: Agent<T>, input: string): ChildHandle<T>;
28
+ /** Settles in caller order, not completion order. No child may outlive this barrier. */
29
+ join<const H extends readonly ChildHandle<unknown>[]>(handles: H): Promise<Joined<H>>;
30
+ }
31
+ export interface DelegationSpec<I, O> {
32
+ name: string;
33
+ description: string;
34
+ inputSchema: JsonObjectSchema;
35
+ validate: (raw: unknown) => I;
36
+ /** Fixed allow-list. Agents cannot add tools or specialists at runtime. */
37
+ specialists: readonly Agent<unknown>[];
38
+ /** Pure, deterministic coordination only: use child and join for work. This callback
39
+ * can replay after interruption; do not put external effects or mutable host state here. */
40
+ run: (input: I, context: DelegationContext) => Promise<O>;
41
+ summarize?: (output: O) => string;
42
+ }
43
+ /** Advertises a core tool definition, but deliberately is not an invokable core Tool. */
44
+ export interface Delegation {
45
+ readonly kind: "delegation";
46
+ readonly name: string;
47
+ readonly specialists: readonly Agent<unknown>[];
48
+ definition(): ToolDefinition;
49
+ /** @internal Errors and suspensions must not go through Tool.invoke's error conversion. */
50
+ execute(raw: unknown, context: DelegationContext): Promise<ToolResult>;
51
+ }
52
+ export interface SpecialistToolOptions<T> {
53
+ name: string;
54
+ description: string;
55
+ /** Pure; may run again when replaying coordination. */
56
+ summarize?: (output: T) => string;
57
+ }
58
+ export declare function isDelegation(value: {
59
+ readonly name: string;
60
+ }): value is Delegation;
61
+ export declare function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation;
62
+ export declare function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOptions<T>): Delegation;
63
+ /** The whole pure coordination barrier lends its parent's slot, not each join.
64
+ * Overlapping joins therefore cannot reacquire a slot while another join still waits. */
65
+ export declare function executeDelegation(descriptor: Delegation, journal: DelegationExecution, parent: RunSnapshot, raw: unknown, options: RunOptions, scope: ExecutionScope, signal: AbortSignal, active: () => void, evidence?: ApprovalEvidence): Promise<ToolResult>;
66
+ //# sourceMappingURL=delegation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,267 @@
1
+ import { messageOf } from "@providerkit/core";
2
+ import { checkChildProgress, checkTree, childRunId, copyData, equalData, immutableCopy, isId, isRecord, } from "./snapshot.js";
3
+ import { fail, Halt, untilAbort } from "./tree.js";
4
+ /** Internal symbol holds no execution state. Every invocation receives its own scope. */
5
+ export const AGENT_RUNTIME = Symbol("agent-runtime");
6
+ export function isDelegation(value) {
7
+ return "kind" in value && value.kind === "delegation";
8
+ }
9
+ export function defineDelegation(spec) {
10
+ if (!isId(spec.name) ||
11
+ !isId(spec.description) ||
12
+ !isRecord(spec.inputSchema) ||
13
+ spec.inputSchema.type !== "object" ||
14
+ typeof spec.validate !== "function" ||
15
+ typeof spec.run !== "function" ||
16
+ (spec.summarize !== undefined && typeof spec.summarize !== "function"))
17
+ throw new TypeError("A delegation needs a name, description, object schema, validator and coordinator.");
18
+ const specialists = Object.freeze([...spec.specialists]);
19
+ if (specialists.some((agent) => !agent?.[AGENT_RUNTIME]) ||
20
+ new Set(specialists.map((agent) => agent.id)).size !== specialists.length)
21
+ throw new TypeError("Register each specialist agent once, with a unique id.");
22
+ const definition = immutableCopy({
23
+ name: spec.name,
24
+ description: spec.description,
25
+ inputSchema: spec.inputSchema,
26
+ });
27
+ const { validate, run, summarize } = spec;
28
+ return Object.freeze({
29
+ kind: "delegation",
30
+ name: spec.name,
31
+ specialists,
32
+ definition: () => copyData(definition),
33
+ async execute(raw, context) {
34
+ let input;
35
+ try {
36
+ input = validate(copyData(raw));
37
+ }
38
+ catch (error) {
39
+ return { ok: false, kind: "invalid_input", content: messageOf(error) };
40
+ }
41
+ const output = await run(input, context);
42
+ const content = summarize ? summarize(output) : JSON.stringify(output);
43
+ if (typeof content !== "string")
44
+ throw new TypeError("A delegation summary must be text.");
45
+ return { ok: true, content };
46
+ },
47
+ });
48
+ }
49
+ export function specialistTool(agent, options) {
50
+ return defineDelegation({
51
+ ...options,
52
+ inputSchema: {
53
+ type: "object",
54
+ properties: { input: { type: "string" } },
55
+ required: ["input"],
56
+ additionalProperties: false,
57
+ },
58
+ specialists: [agent],
59
+ validate(raw) {
60
+ if (!isRecord(raw) || !isId(raw.input) || Object.keys(raw).some((key) => key !== "input"))
61
+ throw new TypeError("Pass one non-empty input string to the specialist.");
62
+ return raw.input;
63
+ },
64
+ async run(input, context) {
65
+ const result = await context.child("result", agent, input).join();
66
+ if (result.status !== "completed") {
67
+ // A suspension is lifted with its child path by executeDelegation below.
68
+ const state = result.snapshot.state;
69
+ if (state.status === "running" || state.status === "completed")
70
+ throw new Error("The specialist outcome does not match its snapshot.");
71
+ throw new Halt(state);
72
+ }
73
+ return result.output;
74
+ },
75
+ });
76
+ }
77
+ /** The whole pure coordination barrier lends its parent's slot, not each join.
78
+ * Overlapping joins therefore cannot reacquire a slot while another join still waits. */
79
+ export async function executeDelegation(descriptor, journal, parent, raw, options, scope, signal, active, evidence) {
80
+ let open = true;
81
+ const started = new Map();
82
+ const handles = new WeakSet();
83
+ function child(key, agent, input) {
84
+ if (!open)
85
+ throw new Error("This delegation has ended; start children only inside its coordinator.");
86
+ active();
87
+ if (!isId(key) || !isId(input))
88
+ throw new TypeError("A child needs a non-empty key and text input.");
89
+ if (!descriptor.specialists.includes(agent))
90
+ fail("unregistered_specialist", "Register this specialist in the delegation before starting it.", journal.operationId);
91
+ const runtime = agent[AGENT_RUNTIME];
92
+ let entry = journal.children.find((saved) => saved.key === key);
93
+ const resume = entry !== undefined;
94
+ if (entry) {
95
+ if (entry.snapshot.agentId !== agent.id ||
96
+ entry.snapshot.version !== agent.version ||
97
+ entry.snapshot.input !== input)
98
+ fail("child_key_conflict", "This child key already belongs to another agent, version or input.", journal.operationId);
99
+ }
100
+ else {
101
+ scope.tree.reserveChild(scope.depth + 1);
102
+ entry = {
103
+ key,
104
+ snapshot: runtime.create(input, childRunId(journal.operationId, key), parent.tree),
105
+ };
106
+ journal.children.push(entry);
107
+ }
108
+ const saved = entry;
109
+ if (!started.has(key)) {
110
+ const work = async () => {
111
+ if (saved.snapshot.state.status !== "running" &&
112
+ saved.snapshot.state.status !== "suspended")
113
+ return;
114
+ await scope.tree.save();
115
+ active();
116
+ const step = { operationId: journal.operationId, key, runId: saved.snapshot.runId };
117
+ const childEvidence = evidence && equalData(evidence.path[0], step)
118
+ ? { path: evidence.path.slice(1), decision: evidence.decision }
119
+ : undefined;
120
+ let execution;
121
+ let hookOpen = true;
122
+ let executionSettled = false;
123
+ const execute = () => {
124
+ if (!hookOpen || execution)
125
+ throw new Error("A host child may execute once, before its hook returns.");
126
+ execution = (async () => {
127
+ if (resume)
128
+ saved.snapshot.attemptId = crypto.randomUUID();
129
+ const result = await runtime.execute(saved.snapshot, { ...options, signal }, { tree: scope.tree, depth: scope.depth + 1 }, childEvidence);
130
+ executionSettled = true;
131
+ return { snapshot: result.snapshot };
132
+ })();
133
+ // A hook that throws or forgets to await cannot leave an unhandled child promise.
134
+ void execution.catch(() => { });
135
+ return execution;
136
+ };
137
+ let envelope;
138
+ try {
139
+ envelope = options.host?.child
140
+ ? await untilAbort(Promise.resolve(options.host.child(immutableCopy({
141
+ ...saved,
142
+ parentRunId: parent.runId,
143
+ operationId: journal.operationId,
144
+ resume,
145
+ }), execute)), signal)
146
+ : await execute();
147
+ if (execution && !executionSettled)
148
+ fail("invalid_child_host", "The child hook returned before its execution settled.", journal.operationId);
149
+ }
150
+ finally {
151
+ hookOpen = false;
152
+ if (execution)
153
+ await execution;
154
+ }
155
+ if (!isRecord(envelope) || (envelope.reference !== undefined && !isId(envelope.reference)))
156
+ fail("invalid_child_host", "The child hook must return a snapshot envelope.", journal.operationId);
157
+ const restored = runtime.restore(envelope.snapshot, parent.tree);
158
+ checkChildProgress(saved.snapshot, restored);
159
+ if (restored.state.status === "running")
160
+ fail("invalid_child_host", "The child hook returned an unfinished child.", journal.operationId);
161
+ // Returning a cached suspended host segment cannot consume an SDK approval.
162
+ if (!execution && childEvidence && restored.state.status === "suspended")
163
+ fail("host_resume_unsupported", "The host returned a cached suspension. Resume this child in a new or resumable host segment.", journal.operationId);
164
+ const previous = saved.snapshot;
165
+ saved.snapshot = restored;
166
+ try {
167
+ checkTree(scope.tree.root);
168
+ }
169
+ catch (error) {
170
+ saved.snapshot = previous;
171
+ throw error;
172
+ }
173
+ saved.reference = envelope.reference ?? saved.reference;
174
+ await scope.tree.save();
175
+ };
176
+ const promise = work().catch(async (error) => {
177
+ let failure = error;
178
+ try {
179
+ active();
180
+ }
181
+ catch (stopped) {
182
+ failure = stopped;
183
+ }
184
+ if (saved.snapshot.state.status === "running") {
185
+ saved.snapshot.state =
186
+ failure instanceof Halt
187
+ ? failure.state
188
+ : {
189
+ status: "failed",
190
+ error: { code: "child_host_failed", message: messageOf(failure) },
191
+ };
192
+ await scope.tree.save();
193
+ }
194
+ throw failure;
195
+ });
196
+ started.set(key, promise);
197
+ void promise.catch(() => { });
198
+ }
199
+ const pending = started.get(key);
200
+ const handle = Object.freeze({
201
+ key,
202
+ runId: saved.snapshot.runId,
203
+ async join() {
204
+ await pending;
205
+ return runtime.hydrate(saved.snapshot);
206
+ },
207
+ });
208
+ handles.add(handle);
209
+ return handle;
210
+ }
211
+ async function join(items) {
212
+ if (items.some((handle) => !handles.has(handle)))
213
+ throw new TypeError("Join only handles created by this delegation context.");
214
+ return Promise.all(items.map((handle) => handle.join()));
215
+ }
216
+ let result;
217
+ let failure;
218
+ try {
219
+ result = await untilAbort(descriptor.execute(raw, Object.freeze({ child, join })), signal);
220
+ }
221
+ catch (error) {
222
+ failure = { error };
223
+ }
224
+ finally {
225
+ // Even ignored children belong to this parent, including children admitted on an
226
+ // earlier attempt that pure coordination did not revisit this time.
227
+ try {
228
+ for (const entry of journal.children) {
229
+ if (started.has(entry.key))
230
+ continue;
231
+ const agent = descriptor.specialists.find((agent) => agent.id === entry.snapshot.agentId && agent.version === entry.snapshot.version);
232
+ if (!agent)
233
+ fail("unregistered_specialist", "The saved child is not a registered specialist.");
234
+ child(entry.key, agent, entry.snapshot.input);
235
+ }
236
+ }
237
+ catch (error) {
238
+ failure ??= { error };
239
+ }
240
+ open = false;
241
+ const settled = await Promise.allSettled(started.values());
242
+ const rejected = settled.find((item) => item.status === "rejected");
243
+ if (rejected?.status === "rejected")
244
+ failure = { error: rejected.reason };
245
+ }
246
+ active();
247
+ if (failure && !(failure.error instanceof Halt && failure.error.state.status === "suspended"))
248
+ throw failure.error;
249
+ for (const entry of journal.children) {
250
+ const state = entry.snapshot.state;
251
+ if (state.status === "suspended") {
252
+ throw new Halt({
253
+ ...state,
254
+ path: [
255
+ { operationId: journal.operationId, key: entry.key, runId: entry.snapshot.runId },
256
+ ...state.path,
257
+ ],
258
+ });
259
+ }
260
+ }
261
+ if (failure)
262
+ throw failure.error;
263
+ if (!result)
264
+ throw new Error("The delegation ended without a result.");
265
+ return result;
266
+ }
267
+ //# sourceMappingURL=delegation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"delegation.js","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"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"}