@providerkit/agents 0.0.0-stage → 0.2.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 +21 -0
- package/LICENSE-APACHE-2.0 +202 -0
- package/README.md +2328 -2
- package/THIRD_PARTY_NOTICES.md +521 -0
- package/dist/a2a/auth.d.ts +10 -0
- package/dist/a2a/auth.d.ts.map +1 -0
- package/dist/a2a/auth.js +52 -0
- package/dist/a2a/auth.js.map +1 -0
- package/dist/a2a/client.d.ts +74 -0
- package/dist/a2a/client.d.ts.map +1 -0
- package/dist/a2a/client.js +601 -0
- package/dist/a2a/client.js.map +1 -0
- package/dist/a2a/index.d.ts +22 -0
- package/dist/a2a/index.d.ts.map +1 -0
- package/dist/a2a/index.js +11 -0
- package/dist/a2a/index.js.map +1 -0
- package/dist/a2a/memory-runs.d.ts +62 -0
- package/dist/a2a/memory-runs.d.ts.map +1 -0
- package/dist/a2a/memory-runs.js +349 -0
- package/dist/a2a/memory-runs.js.map +1 -0
- package/dist/a2a/policy.d.ts +15 -0
- package/dist/a2a/policy.d.ts.map +1 -0
- package/dist/a2a/policy.js +114 -0
- package/dist/a2a/policy.js.map +1 -0
- package/dist/a2a/push.d.ts +34 -0
- package/dist/a2a/push.d.ts.map +1 -0
- package/dist/a2a/push.js +180 -0
- package/dist/a2a/push.js.map +1 -0
- package/dist/a2a/remote.d.ts +155 -0
- package/dist/a2a/remote.d.ts.map +1 -0
- package/dist/a2a/remote.js +1196 -0
- package/dist/a2a/remote.js.map +1 -0
- package/dist/a2a/server.d.ts +110 -0
- package/dist/a2a/server.d.ts.map +1 -0
- package/dist/a2a/server.js +1139 -0
- package/dist/a2a/server.js.map +1 -0
- package/dist/a2a/signing.d.ts +21 -0
- package/dist/a2a/signing.d.ts.map +1 -0
- package/dist/a2a/signing.js +305 -0
- package/dist/a2a/signing.js.map +1 -0
- package/dist/a2a/tasks.d.ts +88 -0
- package/dist/a2a/tasks.d.ts.map +1 -0
- package/dist/a2a/tasks.js +170 -0
- package/dist/a2a/tasks.js.map +1 -0
- package/dist/a2a/wire.d.ts +267 -0
- package/dist/a2a/wire.d.ts.map +1 -0
- package/dist/a2a/wire.js +1202 -0
- package/dist/a2a/wire.js.map +1 -0
- package/dist/background-types.d.ts +76 -0
- package/dist/background-types.d.ts.map +1 -0
- package/dist/background-types.js +2 -0
- package/dist/background-types.js.map +1 -0
- package/dist/child.d.ts +25 -0
- package/dist/child.d.ts.map +1 -0
- package/dist/child.js +129 -0
- package/dist/child.js.map +1 -0
- package/dist/code-driver.d.ts +40 -0
- package/dist/code-driver.d.ts.map +1 -0
- package/dist/code-driver.js +2 -0
- package/dist/code-driver.js.map +1 -0
- package/dist/code-mode.d.ts +3 -0
- package/dist/code-mode.d.ts.map +1 -0
- package/dist/code-mode.js +2 -0
- package/dist/code-mode.js.map +1 -0
- package/dist/code-script.d.ts +3 -0
- package/dist/code-script.d.ts.map +1 -0
- package/dist/code-script.js +149 -0
- package/dist/code-script.js.map +1 -0
- package/dist/code.d.ts +75 -0
- package/dist/code.d.ts.map +1 -0
- package/dist/code.js +326 -0
- package/dist/code.js.map +1 -0
- package/dist/compaction.d.ts +15 -0
- package/dist/compaction.d.ts.map +1 -0
- package/dist/compaction.js +168 -0
- package/dist/compaction.js.map +1 -0
- package/dist/delegation.d.ts +135 -0
- package/dist/delegation.d.ts.map +1 -0
- package/dist/delegation.js +401 -0
- package/dist/delegation.js.map +1 -0
- package/dist/evals/driver.d.ts +10 -0
- package/dist/evals/driver.d.ts.map +1 -0
- package/dist/evals/driver.js +192 -0
- package/dist/evals/driver.js.map +1 -0
- package/dist/evals/journal.d.ts +26 -0
- package/dist/evals/journal.d.ts.map +1 -0
- package/dist/evals/journal.js +483 -0
- package/dist/evals/journal.js.map +1 -0
- package/dist/evals/judge.d.ts +31 -0
- package/dist/evals/judge.d.ts.map +1 -0
- package/dist/evals/judge.js +142 -0
- package/dist/evals/judge.js.map +1 -0
- package/dist/evals/report.d.ts +38 -0
- package/dist/evals/report.d.ts.map +1 -0
- package/dist/evals/report.js +241 -0
- package/dist/evals/report.js.map +1 -0
- package/dist/evals/runner.d.ts +24 -0
- package/dist/evals/runner.d.ts.map +1 -0
- package/dist/evals/runner.js +655 -0
- package/dist/evals/runner.js.map +1 -0
- package/dist/evals/scorers.d.ts +36 -0
- package/dist/evals/scorers.d.ts.map +1 -0
- package/dist/evals/scorers.js +259 -0
- package/dist/evals/scorers.js.map +1 -0
- package/dist/evals/simulation.d.ts +7 -0
- package/dist/evals/simulation.d.ts.map +1 -0
- package/dist/evals/simulation.js +38 -0
- package/dist/evals/simulation.js.map +1 -0
- package/dist/evals/testing.d.ts +36 -0
- package/dist/evals/testing.d.ts.map +1 -0
- package/dist/evals/testing.js +87 -0
- package/dist/evals/testing.js.map +1 -0
- package/dist/evals/trajectory.d.ts +11 -0
- package/dist/evals/trajectory.d.ts.map +1 -0
- package/dist/evals/trajectory.js +180 -0
- package/dist/evals/trajectory.js.map +1 -0
- package/dist/evals/types.d.ts +431 -0
- package/dist/evals/types.d.ts.map +1 -0
- package/dist/evals/types.js +4 -0
- package/dist/evals/types.js.map +1 -0
- package/dist/evals.d.ts +14 -0
- package/dist/evals.d.ts.map +1 -0
- package/dist/evals.js +9 -0
- package/dist/evals.js.map +1 -0
- package/dist/extensions.d.ts +33 -0
- package/dist/extensions.d.ts.map +1 -0
- package/dist/extensions.js +188 -0
- package/dist/extensions.js.map +1 -0
- package/dist/handoff.d.ts +58 -0
- package/dist/handoff.d.ts.map +1 -0
- package/dist/handoff.js +160 -0
- package/dist/handoff.js.map +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -0
- package/dist/input.d.ts +42 -0
- package/dist/input.d.ts.map +1 -0
- package/dist/input.js +266 -0
- package/dist/input.js.map +1 -0
- package/dist/mcp.d.ts +77 -0
- package/dist/mcp.d.ts.map +1 -0
- package/dist/mcp.js +505 -0
- package/dist/mcp.js.map +1 -0
- package/dist/memory-store.d.ts +11 -0
- package/dist/memory-store.d.ts.map +1 -0
- package/dist/memory-store.js +272 -0
- package/dist/memory-store.js.map +1 -0
- package/dist/memory.d.ts +212 -0
- package/dist/memory.d.ts.map +1 -0
- package/dist/memory.js +613 -0
- package/dist/memory.js.map +1 -0
- package/dist/otel.d.ts +74 -0
- package/dist/otel.d.ts.map +1 -0
- package/dist/otel.js +427 -0
- package/dist/otel.js.map +1 -0
- package/dist/progress.d.ts +17 -0
- package/dist/progress.d.ts.map +1 -0
- package/dist/progress.js +193 -0
- package/dist/progress.js.map +1 -0
- package/dist/quickjs.d.ts +19 -0
- package/dist/quickjs.d.ts.map +1 -0
- package/dist/quickjs.js +519 -0
- package/dist/quickjs.js.map +1 -0
- package/dist/recovery.d.ts +10 -0
- package/dist/recovery.d.ts.map +1 -0
- package/dist/recovery.js +62 -0
- package/dist/recovery.js.map +1 -0
- package/dist/request.d.ts +88 -0
- package/dist/request.d.ts.map +1 -0
- package/dist/request.js +422 -0
- package/dist/request.js.map +1 -0
- package/dist/run.d.ts +20 -0
- package/dist/run.d.ts.map +1 -0
- package/dist/run.js +2407 -0
- package/dist/run.js.map +1 -0
- package/dist/runs.d.ts +110 -0
- package/dist/runs.d.ts.map +1 -0
- package/dist/runs.js +438 -0
- package/dist/runs.js.map +1 -0
- package/dist/schema-to-ts.d.ts +4 -0
- package/dist/schema-to-ts.d.ts.map +1 -0
- package/dist/schema-to-ts.js +191 -0
- package/dist/schema-to-ts.js.map +1 -0
- package/dist/session.d.ts +23 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +137 -0
- package/dist/session.js.map +1 -0
- package/dist/snapshot.d.ts +75 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +1607 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/steering.d.ts +75 -0
- package/dist/steering.d.ts.map +1 -0
- package/dist/steering.js +214 -0
- package/dist/steering.js.map +1 -0
- package/dist/subagents.d.ts +141 -0
- package/dist/subagents.d.ts.map +1 -0
- package/dist/subagents.js +746 -0
- package/dist/subagents.js.map +1 -0
- package/dist/tool-retry.d.ts +12 -0
- package/dist/tool-retry.d.ts.map +1 -0
- package/dist/tool-retry.js +53 -0
- package/dist/tool-retry.js.map +1 -0
- package/dist/tree.d.ts +98 -0
- package/dist/tree.d.ts.map +1 -0
- package/dist/tree.js +320 -0
- package/dist/tree.js.map +1 -0
- package/dist/types.d.ts +1007 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/workflow-snapshot.d.ts +8 -0
- package/dist/workflow-snapshot.d.ts.map +1 -0
- package/dist/workflow-snapshot.js +276 -0
- package/dist/workflow-snapshot.js.map +1 -0
- package/dist/workflow-types.d.ts +171 -0
- package/dist/workflow-types.d.ts.map +1 -0
- package/dist/workflow-types.js +2 -0
- package/dist/workflow-types.js.map +1 -0
- package/dist/workflow.d.ts +19 -0
- package/dist/workflow.d.ts.map +1 -0
- package/dist/workflow.js +1053 -0
- package/dist/workflow.js.map +1 -0
- package/examples/a2a-remote.ts +85 -0
- package/examples/a2a-server.ts +100 -0
- package/examples/background.ts +59 -0
- package/examples/basic.ts +44 -0
- package/examples/code-mode.ts +76 -0
- package/examples/conversation.ts +57 -0
- package/examples/evals.ts +79 -0
- package/examples/guardrails.ts +56 -0
- package/examples/handoff.ts +79 -0
- package/examples/memory.ts +44 -0
- package/examples/otel.ts +99 -0
- package/examples/specialists.ts +99 -0
- package/examples/steering.ts +69 -0
- package/examples/structured-handoff.ts +92 -0
- package/examples/subagents.ts +127 -0
- package/examples/workflow.ts +74 -0
- package/package.json +114 -4
- package/src/a2a/auth.ts +62 -0
- package/src/a2a/client.ts +733 -0
- package/src/a2a/index.ts +74 -0
- package/src/a2a/memory-runs.ts +448 -0
- package/src/a2a/policy.ts +148 -0
- package/src/a2a/push.ts +251 -0
- package/src/a2a/remote.ts +1652 -0
- package/src/a2a/server.ts +1390 -0
- package/src/a2a/signing.ts +348 -0
- package/src/a2a/tasks.ts +260 -0
- package/src/a2a/wire.ts +1443 -0
- package/src/background-types.ts +86 -0
- package/src/child.ts +181 -0
- package/src/code-driver.ts +48 -0
- package/src/code-mode.ts +12 -0
- package/src/code-script.ts +149 -0
- package/src/code.ts +424 -0
- package/src/compaction.ts +212 -0
- package/src/delegation.ts +694 -0
- package/src/evals/driver.ts +222 -0
- package/src/evals/journal.ts +605 -0
- package/src/evals/judge.ts +188 -0
- package/src/evals/report.ts +295 -0
- package/src/evals/runner.ts +826 -0
- package/src/evals/scorers.ts +339 -0
- package/src/evals/simulation.ts +46 -0
- package/src/evals/testing.ts +126 -0
- package/src/evals/trajectory.ts +223 -0
- package/src/evals/types.ts +463 -0
- package/src/evals.ts +72 -0
- package/src/extensions.ts +247 -0
- package/src/handoff.ts +214 -0
- package/src/index.ts +62 -0
- package/src/input.ts +319 -0
- package/src/mcp.ts +690 -0
- package/src/memory-store.ts +366 -0
- package/src/memory.ts +893 -0
- package/src/otel.ts +568 -0
- package/src/progress.ts +214 -0
- package/src/quickjs.ts +524 -0
- package/src/recovery.ts +90 -0
- package/src/request.ts +513 -0
- package/src/run.ts +3199 -0
- package/src/runs.ts +696 -0
- package/src/schema-to-ts.ts +194 -0
- package/src/session.ts +178 -0
- package/src/snapshot.ts +2099 -0
- package/src/steering.ts +329 -0
- package/src/subagents.ts +1084 -0
- package/src/tool-retry.ts +86 -0
- package/src/tree.ts +366 -0
- package/src/types.ts +944 -0
- package/src/workflow-snapshot.ts +366 -0
- package/src/workflow-types.ts +213 -0
- package/src/workflow.ts +1316 -0
|
@@ -0,0 +1,694 @@
|
|
|
1
|
+
import type { RemoteAgent, RemoteInput, RemoteOutcome } from "./a2a/remote.ts";
|
|
2
|
+
import type { Workflow, WorkflowOutcome } from "./workflow-types.ts";
|
|
3
|
+
import type { TreeNode } from "./types.ts";
|
|
4
|
+
import { messageOf, type JsonObjectSchema, type ToolDefinition } from "@providerkit/core";
|
|
5
|
+
import { admitChild, startChild, childOptions, prepareChild } from "./child.ts";
|
|
6
|
+
import { RequestJournal } from "./request.ts";
|
|
7
|
+
import { checkMemoryBinding } from "./memory.ts";
|
|
8
|
+
import { isSubagentTool, type SubagentCreation, type SubagentRecord } from "./subagents.ts";
|
|
9
|
+
import { successfulToolResult } from "./extensions.ts";
|
|
10
|
+
import { handoffRef, type Handoff } from "./handoff.ts";
|
|
11
|
+
import { conversationOf, inputOf } from "./input.ts";
|
|
12
|
+
import {
|
|
13
|
+
agentSnapshot,
|
|
14
|
+
childRunId,
|
|
15
|
+
copyData,
|
|
16
|
+
equalData,
|
|
17
|
+
immutableCopy,
|
|
18
|
+
isId,
|
|
19
|
+
isRecord,
|
|
20
|
+
} from "./snapshot.ts";
|
|
21
|
+
import {
|
|
22
|
+
emitEvent,
|
|
23
|
+
fail,
|
|
24
|
+
Halt,
|
|
25
|
+
isLocalStop,
|
|
26
|
+
nodeId,
|
|
27
|
+
untilAbort,
|
|
28
|
+
type ExecutionScope,
|
|
29
|
+
} from "./tree.ts";
|
|
30
|
+
import type {
|
|
31
|
+
Agent,
|
|
32
|
+
AgentConfig,
|
|
33
|
+
AgentInput,
|
|
34
|
+
AgentMessage,
|
|
35
|
+
Answer,
|
|
36
|
+
QuestionAsk,
|
|
37
|
+
ChildEnvelope,
|
|
38
|
+
DelegationExecution,
|
|
39
|
+
RunOptions,
|
|
40
|
+
RunLimits,
|
|
41
|
+
RunOutcome,
|
|
42
|
+
RunSnapshot,
|
|
43
|
+
ToolRequest,
|
|
44
|
+
ToolResult,
|
|
45
|
+
UserContent,
|
|
46
|
+
} from "./types.ts";
|
|
47
|
+
|
|
48
|
+
/** Internal symbol holds no execution state. Every invocation receives its own scope. */
|
|
49
|
+
export const AGENT_RUNTIME = Symbol("agent-runtime");
|
|
50
|
+
/** @internal Only the built-in helper coordinator receives this journaled admission path. */
|
|
51
|
+
export const SUBAGENT_CONTEXT = Symbol("subagent-context");
|
|
52
|
+
|
|
53
|
+
/** @internal What a new run starts from, checked: the history before the new turn, the turn,
|
|
54
|
+
* and the session the history came from. */
|
|
55
|
+
export interface RunStart {
|
|
56
|
+
history: AgentMessage[];
|
|
57
|
+
input: UserContent;
|
|
58
|
+
session?: RunSnapshot["session"];
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export type Specialist = Agent<unknown> | Workflow<unknown, unknown> | RemoteAgent<unknown>;
|
|
62
|
+
export type NodeOutcome<T = unknown> = RunOutcome<T> | WorkflowOutcome<T> | RemoteOutcome<T>;
|
|
63
|
+
export interface NodeRuntime<R extends NodeOutcome = NodeOutcome> {
|
|
64
|
+
restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): TreeNode;
|
|
65
|
+
hydrate(snapshot: TreeNode): R;
|
|
66
|
+
answerRequests(
|
|
67
|
+
snapshot: TreeNode,
|
|
68
|
+
options: RunOptions,
|
|
69
|
+
scope: ExecutionScope,
|
|
70
|
+
answers: Readonly<Record<string, unknown>>,
|
|
71
|
+
signal: AbortSignal,
|
|
72
|
+
): Promise<void>;
|
|
73
|
+
execute(
|
|
74
|
+
snapshot: TreeNode,
|
|
75
|
+
options: RunOptions,
|
|
76
|
+
scope: ExecutionScope,
|
|
77
|
+
answers?: Readonly<Record<string, unknown>>,
|
|
78
|
+
): Promise<R>;
|
|
79
|
+
}
|
|
80
|
+
export function runtimeOf<T>(node: Agent<T>): NodeRuntime<RunOutcome<T>>;
|
|
81
|
+
export function runtimeOf<T>(node: RemoteAgent<T>): NodeRuntime<RemoteOutcome<T>>;
|
|
82
|
+
export function runtimeOf<I, O>(node: Workflow<I, O>): NodeRuntime<WorkflowOutcome<O>>;
|
|
83
|
+
export function runtimeOf(node: Specialist): NodeRuntime;
|
|
84
|
+
export function runtimeOf(node: Specialist): NodeRuntime {
|
|
85
|
+
return node.kind === "agent" ? node[AGENT_RUNTIME].node : node[AGENT_RUNTIME];
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** @internal */
|
|
89
|
+
export interface AgentRuntime<T> {
|
|
90
|
+
readonly node: NodeRuntime<RunOutcome<T>>;
|
|
91
|
+
readonly handoffs: readonly Handoff[];
|
|
92
|
+
readonly tools: NonNullable<AgentConfig["tools"]>;
|
|
93
|
+
readonly enabledTools: readonly string[] | undefined;
|
|
94
|
+
readonly limits: RunLimits;
|
|
95
|
+
/** JSON identity of host configuration. Callbacks need an agent version change. */
|
|
96
|
+
configuration(): Record<string, unknown>;
|
|
97
|
+
/** Recheck current selection without resolving or replacing recorded instructions. */
|
|
98
|
+
checkTools(snapshot: RunSnapshot, options: RunOptions): Promise<void>;
|
|
99
|
+
/** A new root run's snapshot: the input normalized, the session read once and the history
|
|
100
|
+
* prepared, repaired and frozen, before anything is saved. */
|
|
101
|
+
open(input: AgentInput, options: RunOptions, runId: string): Promise<RunSnapshot>;
|
|
102
|
+
/** The history repaired with this agent's tools and the inline bytes checked: the exact form
|
|
103
|
+
* a snapshot stores, so a saved child can be compared with a new request for its key. */
|
|
104
|
+
freeze(start: RunStart): RunStart;
|
|
105
|
+
/** Resolves the run definition once, then creates a snapshot from the repaired history. */
|
|
106
|
+
create(
|
|
107
|
+
start: RunStart,
|
|
108
|
+
runId: string,
|
|
109
|
+
tree?: RunSnapshot["tree"],
|
|
110
|
+
options?: RunOptions,
|
|
111
|
+
subagent?: SubagentCreation,
|
|
112
|
+
): Promise<RunSnapshot>;
|
|
113
|
+
restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): RunSnapshot;
|
|
114
|
+
hydrate(snapshot: RunSnapshot): RunOutcome<T>;
|
|
115
|
+
answerRequests(
|
|
116
|
+
snapshot: RunSnapshot,
|
|
117
|
+
options: RunOptions,
|
|
118
|
+
scope: ExecutionScope,
|
|
119
|
+
answers: Readonly<Record<string, unknown>>,
|
|
120
|
+
signal: AbortSignal,
|
|
121
|
+
): Promise<void>;
|
|
122
|
+
execute(
|
|
123
|
+
snapshot: RunSnapshot,
|
|
124
|
+
options: RunOptions,
|
|
125
|
+
scope: ExecutionScope,
|
|
126
|
+
answers?: Readonly<Record<string, unknown>>,
|
|
127
|
+
): Promise<RunOutcome<T>>;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
export interface ChildHandle<T = unknown, R extends NodeOutcome<T> = RunOutcome<T>> {
|
|
131
|
+
readonly key: string;
|
|
132
|
+
readonly runId: string;
|
|
133
|
+
/** A started child, not another provider call. Repeated joins reuse the same outcome. */
|
|
134
|
+
join(): Promise<R>;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
export type Joined<H extends readonly ChildHandle<unknown, NodeOutcome>[]> = {
|
|
138
|
+
[K in keyof H]: H[K] extends ChildHandle<unknown, infer R> ? R : never;
|
|
139
|
+
};
|
|
140
|
+
|
|
141
|
+
export interface DelegationContext {
|
|
142
|
+
/** @internal Kept off the public barrel. Model-created helpers use the same child journal. */
|
|
143
|
+
readonly [SUBAGENT_CONTEXT]?: {
|
|
144
|
+
parent: RunSnapshot;
|
|
145
|
+
journal: DelegationExecution;
|
|
146
|
+
scope: ExecutionScope;
|
|
147
|
+
request: ToolRequest;
|
|
148
|
+
signal: AbortSignal;
|
|
149
|
+
recheck(agent: Agent<unknown>, snapshot: RunSnapshot): Promise<void>;
|
|
150
|
+
child<T>(
|
|
151
|
+
key: string,
|
|
152
|
+
agent: Agent<T>,
|
|
153
|
+
input: AgentInput,
|
|
154
|
+
subagent: SubagentCreation,
|
|
155
|
+
): ChildHandle<T>;
|
|
156
|
+
};
|
|
157
|
+
/** Pure coordination replays from its start. The saved answer is matched by key and checked
|
|
158
|
+
* by this pure validator, not by a saved JavaScript stack. A rejected form is asked again. */
|
|
159
|
+
ask<T>(question: Omit<QuestionAsk, "type">, validate: (answer: Answer) => T): Promise<T>;
|
|
160
|
+
/** `key` becomes part of the child's run id and of every operation id under it, which
|
|
161
|
+
* progress events carry and a display layer may send to a browser. Key by position or a
|
|
162
|
+
* fixed name ("topic-1"), never by the input. The input is checked like `run`'s, except
|
|
163
|
+
* that provider-owned fields are kept: coordinator code is trusted. A child never gets the
|
|
164
|
+
* parent's session. */
|
|
165
|
+
child<I, O>(key: string, workflow: Workflow<I, O>, input: I): ChildHandle<O, WorkflowOutcome<O>>;
|
|
166
|
+
child<T>(key: string, agent: Agent<T>, input: AgentInput): ChildHandle<T>;
|
|
167
|
+
child<T>(
|
|
168
|
+
key: string,
|
|
169
|
+
agent: RemoteAgent<T>,
|
|
170
|
+
input: RemoteInput,
|
|
171
|
+
): ChildHandle<T, RemoteOutcome<T>>;
|
|
172
|
+
/** Settles in caller order, not completion order. No child may outlive this barrier. */
|
|
173
|
+
join<const H extends readonly ChildHandle<unknown, NodeOutcome>[]>(
|
|
174
|
+
handles: H,
|
|
175
|
+
): Promise<Joined<H>>;
|
|
176
|
+
/** The parent's conversation before this tool call: no system prompt and no unfinished
|
|
177
|
+
* round. Frozen. A child sees none of it unless you forward it, for example
|
|
178
|
+
* `{ messages: [...context.conversation, { role: "user", content: task }] }`. */
|
|
179
|
+
readonly conversation: readonly AgentMessage[];
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export interface DelegationSpec<I, O> {
|
|
183
|
+
name: string;
|
|
184
|
+
description: string;
|
|
185
|
+
inputSchema: JsonObjectSchema;
|
|
186
|
+
needsApproval?: boolean;
|
|
187
|
+
validate: (raw: unknown) => I;
|
|
188
|
+
/** Fixed allow-list. Agents cannot add tools or specialists at runtime. */
|
|
189
|
+
specialists: readonly Specialist[];
|
|
190
|
+
/** Pure, deterministic coordination only: use child and join for work. This callback
|
|
191
|
+
* can replay after interruption; do not put external effects or mutable host state here. */
|
|
192
|
+
run: (input: I, context: DelegationContext) => Promise<O>;
|
|
193
|
+
summarize?: (output: O) => string;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Advertises a core tool definition, but deliberately is not an invokable core Tool. */
|
|
197
|
+
export interface Delegation {
|
|
198
|
+
readonly kind: "delegation";
|
|
199
|
+
readonly name: string;
|
|
200
|
+
readonly needsApproval: boolean;
|
|
201
|
+
readonly specialists: readonly Specialist[];
|
|
202
|
+
definition(): ToolDefinition;
|
|
203
|
+
/** @internal Errors and suspensions must not go through Tool.invoke's error conversion. */
|
|
204
|
+
execute(raw: unknown, context: DelegationContext): Promise<ToolResult>;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
export interface SpecialistToolOptions<T> {
|
|
208
|
+
needsApproval?: boolean;
|
|
209
|
+
name: string;
|
|
210
|
+
description: string;
|
|
211
|
+
/** Pure; may run again when replaying coordination. */
|
|
212
|
+
summarize?: (output: T) => string;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
export function isDelegation(value: { readonly name: string }): value is Delegation {
|
|
216
|
+
return "kind" in value && value.kind === "delegation";
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
export function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation {
|
|
220
|
+
if (
|
|
221
|
+
!isId(spec.name) ||
|
|
222
|
+
!isId(spec.description) ||
|
|
223
|
+
!isRecord(spec.inputSchema) ||
|
|
224
|
+
spec.inputSchema.type !== "object" ||
|
|
225
|
+
typeof spec.validate !== "function" ||
|
|
226
|
+
typeof spec.run !== "function" ||
|
|
227
|
+
(spec.summarize !== undefined && typeof spec.summarize !== "function")
|
|
228
|
+
)
|
|
229
|
+
throw new TypeError(
|
|
230
|
+
"A delegation needs a name, description, object schema, validator and coordinator.",
|
|
231
|
+
);
|
|
232
|
+
const specialists = Object.freeze([...spec.specialists]);
|
|
233
|
+
if (
|
|
234
|
+
specialists.some((agent) => !agent?.[AGENT_RUNTIME]) ||
|
|
235
|
+
new Set(specialists.map((agent) => agent.id)).size !== specialists.length
|
|
236
|
+
)
|
|
237
|
+
throw new TypeError("Register each specialist agent once, with a unique id.");
|
|
238
|
+
const definition = immutableCopy({
|
|
239
|
+
name: spec.name,
|
|
240
|
+
description: spec.description,
|
|
241
|
+
inputSchema: spec.inputSchema,
|
|
242
|
+
});
|
|
243
|
+
const { validate, run, summarize } = spec;
|
|
244
|
+
return Object.freeze({
|
|
245
|
+
kind: "delegation",
|
|
246
|
+
name: spec.name,
|
|
247
|
+
needsApproval: spec.needsApproval ?? false,
|
|
248
|
+
specialists,
|
|
249
|
+
definition: () => copyData(definition),
|
|
250
|
+
async execute(raw: unknown, context: DelegationContext): Promise<ToolResult> {
|
|
251
|
+
let input: I;
|
|
252
|
+
try {
|
|
253
|
+
input = validate(copyData(raw));
|
|
254
|
+
} catch (error) {
|
|
255
|
+
return { ok: false, kind: "invalid_input", content: messageOf(error) };
|
|
256
|
+
}
|
|
257
|
+
const output = await run(input, context);
|
|
258
|
+
const content = summarize ? summarize(output) : JSON.stringify(output);
|
|
259
|
+
if (typeof content !== "string") throw new TypeError("A delegation summary must be text.");
|
|
260
|
+
return successfulToolResult({ output, summary: content });
|
|
261
|
+
},
|
|
262
|
+
});
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOptions<T>): Delegation {
|
|
266
|
+
const descriptor = defineDelegation({
|
|
267
|
+
...options,
|
|
268
|
+
inputSchema: {
|
|
269
|
+
type: "object",
|
|
270
|
+
properties: { input: { type: "string" } },
|
|
271
|
+
required: ["input"],
|
|
272
|
+
additionalProperties: false,
|
|
273
|
+
},
|
|
274
|
+
specialists: [agent],
|
|
275
|
+
validate(raw) {
|
|
276
|
+
if (!isRecord(raw) || !isId(raw.input) || Object.keys(raw).some((key) => key !== "input"))
|
|
277
|
+
throw new TypeError("Pass one non-empty input string to the specialist.");
|
|
278
|
+
return raw.input;
|
|
279
|
+
},
|
|
280
|
+
async run(input, context) {
|
|
281
|
+
const result = await context.child("result", agent, input).join();
|
|
282
|
+
if (result.status !== "completed") {
|
|
283
|
+
// A suspension is lifted with its child path by executeDelegation below.
|
|
284
|
+
const state = result.snapshot.state;
|
|
285
|
+
if (state.status === "running" || state.status === "completed")
|
|
286
|
+
throw new Error("The specialist outcome does not match its snapshot.");
|
|
287
|
+
throw new Halt(state);
|
|
288
|
+
}
|
|
289
|
+
return result.output;
|
|
290
|
+
},
|
|
291
|
+
});
|
|
292
|
+
return specialistFailures(descriptor);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/** Known local failures are tool data. Authority and journal failures still stop the tree. */
|
|
296
|
+
export function specialistFailures(descriptor: Delegation): Delegation {
|
|
297
|
+
return Object.freeze({
|
|
298
|
+
...descriptor,
|
|
299
|
+
async execute(raw: unknown, context: DelegationContext): Promise<ToolResult> {
|
|
300
|
+
try {
|
|
301
|
+
return await descriptor.execute(raw, context);
|
|
302
|
+
} catch (error) {
|
|
303
|
+
if (!(error instanceof Halt) || !isLocalStop(error.state)) throw error;
|
|
304
|
+
const reason =
|
|
305
|
+
error.state.status === "limited"
|
|
306
|
+
? `its ${error.state.limit === "steps" ? "step" : error.state.limit === "elapsedMs" ? "time" : error.state.limit === "outputTokens" ? "output" : error.state.limit === "toolCalls" ? "tool-call" : "model-turn"} limit`
|
|
307
|
+
: error.state.status === "failed" &&
|
|
308
|
+
["memory_missing", "memory_unavailable"].includes(error.state.error.code)
|
|
309
|
+
? "a problem reading saved notes"
|
|
310
|
+
: "a model or result failure";
|
|
311
|
+
return {
|
|
312
|
+
ok: false,
|
|
313
|
+
kind: "failed",
|
|
314
|
+
content: `The specialist could not finish because of ${reason}. Continue with the other results.`,
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
},
|
|
318
|
+
});
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** The whole pure coordination barrier lends its parent's slot, not each join.
|
|
322
|
+
* Overlapping joins therefore cannot reacquire a slot while another join still waits. */
|
|
323
|
+
export async function executeDelegation(
|
|
324
|
+
descriptor: Delegation,
|
|
325
|
+
journal: DelegationExecution,
|
|
326
|
+
parent: RunSnapshot,
|
|
327
|
+
raw: Record<string, unknown>,
|
|
328
|
+
options: RunOptions,
|
|
329
|
+
scope: ExecutionScope,
|
|
330
|
+
signal: AbortSignal,
|
|
331
|
+
active: () => void,
|
|
332
|
+
requests: RequestJournal,
|
|
333
|
+
): Promise<ToolResult> {
|
|
334
|
+
let open = true;
|
|
335
|
+
const started = new Map<string, Promise<void>>();
|
|
336
|
+
const requested = new Map<
|
|
337
|
+
string,
|
|
338
|
+
{ agentId: string; version: string; start: unknown; subagent?: SubagentCreation }
|
|
339
|
+
>();
|
|
340
|
+
// Resolve new child definitions in admission order, without delaying children already
|
|
341
|
+
// running. No half-resolved definition can appear in another child's root checkpoint.
|
|
342
|
+
let admissions = Promise.resolve();
|
|
343
|
+
const handles = new WeakSet<ChildHandle<unknown, NodeOutcome>>();
|
|
344
|
+
// Computed again on a replay from the same settled rounds, so a coordinator that forwards it
|
|
345
|
+
// asks for the same child input and reuses the saved child.
|
|
346
|
+
const conversation = immutableCopy(conversationOf(parent));
|
|
347
|
+
const inherited = childOptions(options);
|
|
348
|
+
|
|
349
|
+
async function recheck(agent: Agent<unknown>, snapshot: RunSnapshot): Promise<void> {
|
|
350
|
+
if (!options.host?.beforeTool)
|
|
351
|
+
fail(
|
|
352
|
+
"subagent_authority_missing",
|
|
353
|
+
"Supply host.beforeTool to authorize helper forks and follow-ups.",
|
|
354
|
+
);
|
|
355
|
+
await agent[AGENT_RUNTIME].checkTools(snapshot, { ...inherited, signal });
|
|
356
|
+
checkMemoryBinding(snapshot, inherited.memory);
|
|
357
|
+
if (inherited.memory) {
|
|
358
|
+
const { store, scope, shared = [] } = inherited.memory;
|
|
359
|
+
try {
|
|
360
|
+
for (const access of [...(scope ? [scope] : []), ...shared]) {
|
|
361
|
+
const current = await untilAbort(
|
|
362
|
+
store.access(immutableCopy(access.scope), { signal }),
|
|
363
|
+
signal,
|
|
364
|
+
);
|
|
365
|
+
if (!equalData(current, access)) throw new Error("Changed memory access");
|
|
366
|
+
}
|
|
367
|
+
} catch {
|
|
368
|
+
signal.throwIfAborted();
|
|
369
|
+
fail(
|
|
370
|
+
"subagent_memory_changed",
|
|
371
|
+
"The helper's memory access changed or could not be checked. Obtain fresh host authorization before starting new work.",
|
|
372
|
+
);
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
await requests.recheck({ ...requests.call, arguments: raw });
|
|
376
|
+
await requests.assertFresh();
|
|
377
|
+
active();
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
function child<T>(
|
|
381
|
+
key: string,
|
|
382
|
+
agent: Agent<T>,
|
|
383
|
+
input: AgentInput,
|
|
384
|
+
subagent?: SubagentCreation,
|
|
385
|
+
): ChildHandle<T>;
|
|
386
|
+
function child<I, O>(
|
|
387
|
+
key: string,
|
|
388
|
+
agent: Workflow<I, O>,
|
|
389
|
+
input: I,
|
|
390
|
+
): ChildHandle<O, WorkflowOutcome<O>>;
|
|
391
|
+
function child<T>(
|
|
392
|
+
key: string,
|
|
393
|
+
agent: RemoteAgent<T>,
|
|
394
|
+
input: RemoteInput,
|
|
395
|
+
): ChildHandle<T, RemoteOutcome<T>>;
|
|
396
|
+
function child(
|
|
397
|
+
key: string,
|
|
398
|
+
agent: Specialist,
|
|
399
|
+
input: unknown,
|
|
400
|
+
subagent?: SubagentCreation,
|
|
401
|
+
): ChildHandle<unknown, NodeOutcome> {
|
|
402
|
+
if (!open)
|
|
403
|
+
throw new Error("This delegation has ended; start children only inside its coordinator.");
|
|
404
|
+
active();
|
|
405
|
+
if (!isId(key)) throw new TypeError("A child needs a non-empty key.");
|
|
406
|
+
if (!descriptor.specialists.includes(agent))
|
|
407
|
+
fail(
|
|
408
|
+
"unregistered_specialist",
|
|
409
|
+
"Register this specialist before starting it.",
|
|
410
|
+
journal.operationId,
|
|
411
|
+
);
|
|
412
|
+
const runtime = runtimeOf(agent);
|
|
413
|
+
const prepared = prepareChild(agent, input, subagent, scope.tree.root);
|
|
414
|
+
const start = prepared.input;
|
|
415
|
+
const identity = { agentId: agent.id, version: agent.version, start, subagent };
|
|
416
|
+
const prior = requested.get(key);
|
|
417
|
+
if (prior && !equalData(prior, identity))
|
|
418
|
+
fail(
|
|
419
|
+
"child_key_conflict",
|
|
420
|
+
"This child key belongs to another definition or input.",
|
|
421
|
+
journal.operationId,
|
|
422
|
+
);
|
|
423
|
+
requested.set(key, identity);
|
|
424
|
+
const runId = childRunId(journal.operationId, key);
|
|
425
|
+
let entry = journal.children.find((saved) => saved.key === key);
|
|
426
|
+
const resume = entry !== undefined;
|
|
427
|
+
if (entry) {
|
|
428
|
+
const saved = entry.snapshot;
|
|
429
|
+
const savedStart =
|
|
430
|
+
saved.kind === "agent" ? { history: saved.history, input: saved.input } : saved.input;
|
|
431
|
+
if (
|
|
432
|
+
saved.kind !== agent.kind ||
|
|
433
|
+
nodeId(saved) !== agent.id ||
|
|
434
|
+
saved.version !== agent.version ||
|
|
435
|
+
!equalData(savedStart, start) ||
|
|
436
|
+
!equalData(
|
|
437
|
+
saved.kind === "agent" && saved.subagent
|
|
438
|
+
? { ...saved.subagent, base: undefined }
|
|
439
|
+
: undefined,
|
|
440
|
+
subagent?.record,
|
|
441
|
+
)
|
|
442
|
+
)
|
|
443
|
+
fail(
|
|
444
|
+
"child_key_conflict",
|
|
445
|
+
"This child key belongs to another definition or input.",
|
|
446
|
+
journal.operationId,
|
|
447
|
+
);
|
|
448
|
+
}
|
|
449
|
+
if (!started.has(key)) {
|
|
450
|
+
let admitted: Promise<ChildEnvelope & { key: string }>;
|
|
451
|
+
if (entry) admitted = Promise.resolve(entry);
|
|
452
|
+
else {
|
|
453
|
+
scope.tree.reserveChild(scope.depth + 1);
|
|
454
|
+
admitted = admissions.then(async () => {
|
|
455
|
+
const snapshot = await prepared.create(runId, parent.tree, { ...inherited, signal });
|
|
456
|
+
active();
|
|
457
|
+
entry = admitChild(journal.children, { key, snapshot }, scope);
|
|
458
|
+
return entry;
|
|
459
|
+
});
|
|
460
|
+
admissions = admitted.then(
|
|
461
|
+
() => {},
|
|
462
|
+
() => {},
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
const work = async () => {
|
|
466
|
+
const saved = await admitted;
|
|
467
|
+
await startChild(
|
|
468
|
+
saved,
|
|
469
|
+
parent,
|
|
470
|
+
journal.operationId,
|
|
471
|
+
runtime,
|
|
472
|
+
inherited,
|
|
473
|
+
scope,
|
|
474
|
+
signal,
|
|
475
|
+
active,
|
|
476
|
+
resume,
|
|
477
|
+
async () => {
|
|
478
|
+
if (
|
|
479
|
+
agent.kind === "agent" &&
|
|
480
|
+
saved.snapshot.kind === "agent" &&
|
|
481
|
+
(saved.snapshot.subagent?.fork || saved.snapshot.subagent?.previousRunId)
|
|
482
|
+
)
|
|
483
|
+
await recheck(agent, saved.snapshot);
|
|
484
|
+
if (journal.kind === "handoff")
|
|
485
|
+
emitEvent(options, {
|
|
486
|
+
type: "handoff",
|
|
487
|
+
runId: parent.runId,
|
|
488
|
+
attemptId: parent.attemptId,
|
|
489
|
+
operationId: journal.operationId,
|
|
490
|
+
childRunId: saved.snapshot.runId,
|
|
491
|
+
from: handoffRef(parent),
|
|
492
|
+
to: journal.target,
|
|
493
|
+
...(journal.note !== undefined ? { note: journal.note } : {}),
|
|
494
|
+
});
|
|
495
|
+
},
|
|
496
|
+
journal.kind === "handoff"
|
|
497
|
+
? (parent.inputs.at(-1)?.content ?? scope.handoffInput ?? parent.input)
|
|
498
|
+
: undefined,
|
|
499
|
+
);
|
|
500
|
+
};
|
|
501
|
+
const promise = work().catch(async (error: unknown) => {
|
|
502
|
+
let failure = error;
|
|
503
|
+
try {
|
|
504
|
+
active();
|
|
505
|
+
} catch (stopped) {
|
|
506
|
+
failure = stopped;
|
|
507
|
+
}
|
|
508
|
+
if (entry?.snapshot.state.status === "running") {
|
|
509
|
+
entry.snapshot.state =
|
|
510
|
+
failure instanceof Halt
|
|
511
|
+
? failure.state
|
|
512
|
+
: {
|
|
513
|
+
status: "failed",
|
|
514
|
+
error: { code: "child_host_failed", message: messageOf(failure) },
|
|
515
|
+
};
|
|
516
|
+
await scope.tree.save();
|
|
517
|
+
}
|
|
518
|
+
throw failure;
|
|
519
|
+
});
|
|
520
|
+
started.set(key, promise);
|
|
521
|
+
void promise.catch(() => {});
|
|
522
|
+
}
|
|
523
|
+
const pending = started.get(key);
|
|
524
|
+
const handle = Object.freeze({
|
|
525
|
+
key,
|
|
526
|
+
runId,
|
|
527
|
+
async join(): Promise<NodeOutcome> {
|
|
528
|
+
await pending;
|
|
529
|
+
const saved = journal.children.find((child) => child.key === key);
|
|
530
|
+
if (!saved) throw new Error("The child ended before its definition resolved.");
|
|
531
|
+
return runtime.hydrate(saved.snapshot);
|
|
532
|
+
},
|
|
533
|
+
});
|
|
534
|
+
handles.add(handle);
|
|
535
|
+
return handle;
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
function join<const H extends readonly ChildHandle<unknown, NodeOutcome>[]>(
|
|
539
|
+
items: H,
|
|
540
|
+
): Promise<Joined<H>>;
|
|
541
|
+
async function join(items: readonly ChildHandle<unknown, NodeOutcome>[]): Promise<NodeOutcome[]> {
|
|
542
|
+
if (items.some((handle) => !handles.has(handle)))
|
|
543
|
+
throw new TypeError("Join only handles created by this delegation context.");
|
|
544
|
+
return Promise.all(items.map((handle) => handle.join()));
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
// Adapted from LangGraph.js (MIT), interrupt.ts: return a saved answer on replay.
|
|
548
|
+
// Keys replace positional matching; validation stays with the trusted coordinator.
|
|
549
|
+
let asks = Promise.resolve();
|
|
550
|
+
const asking: Promise<unknown>[] = [];
|
|
551
|
+
function ask<T>(
|
|
552
|
+
question: Omit<QuestionAsk, "type">,
|
|
553
|
+
validate: (answer: Answer) => T,
|
|
554
|
+
): Promise<T> {
|
|
555
|
+
if (!open) throw new Error("Ask only inside the active coordinator.");
|
|
556
|
+
const work = asks.then(async () => {
|
|
557
|
+
active();
|
|
558
|
+
const record = await requests.ensure({ ...question, type: "question" });
|
|
559
|
+
if (!record.decision) throw new Halt({ status: "suspended" });
|
|
560
|
+
if (record.decision.type === "stop") {
|
|
561
|
+
scope.tree.stop();
|
|
562
|
+
throw new Halt({ status: "cancelled" });
|
|
563
|
+
}
|
|
564
|
+
if (record.decision.type === "cancel") throw new CancelledQuestion();
|
|
565
|
+
if (record.decision.type !== "answer") throw new TypeError("This question needs an answer.");
|
|
566
|
+
await requests.recheck({ ...requests.call, arguments: raw });
|
|
567
|
+
active();
|
|
568
|
+
try {
|
|
569
|
+
return validate(immutableCopy(record.decision.answer));
|
|
570
|
+
} catch (error) {
|
|
571
|
+
record.closed = "invalid";
|
|
572
|
+
await requests.open(
|
|
573
|
+
{ ...question, type: "question" },
|
|
574
|
+
{ code: "invalid_answer", message: messageOf(error) },
|
|
575
|
+
);
|
|
576
|
+
throw new Halt({ status: "suspended" });
|
|
577
|
+
}
|
|
578
|
+
});
|
|
579
|
+
asks = work.then(
|
|
580
|
+
() => {},
|
|
581
|
+
() => {},
|
|
582
|
+
);
|
|
583
|
+
asking.push(work);
|
|
584
|
+
void work.catch(() => {});
|
|
585
|
+
return work;
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
let result: ToolResult | undefined;
|
|
589
|
+
let failure: { error: unknown } | undefined;
|
|
590
|
+
try {
|
|
591
|
+
result = await untilAbort(
|
|
592
|
+
descriptor.execute(
|
|
593
|
+
raw,
|
|
594
|
+
Object.freeze({
|
|
595
|
+
child,
|
|
596
|
+
join,
|
|
597
|
+
ask,
|
|
598
|
+
conversation,
|
|
599
|
+
...(isSubagentTool(descriptor)
|
|
600
|
+
? {
|
|
601
|
+
[SUBAGENT_CONTEXT]: {
|
|
602
|
+
parent,
|
|
603
|
+
journal,
|
|
604
|
+
scope,
|
|
605
|
+
request: { ...requests.call, arguments: raw },
|
|
606
|
+
signal,
|
|
607
|
+
recheck,
|
|
608
|
+
child,
|
|
609
|
+
},
|
|
610
|
+
}
|
|
611
|
+
: {}),
|
|
612
|
+
}),
|
|
613
|
+
),
|
|
614
|
+
signal,
|
|
615
|
+
);
|
|
616
|
+
} catch (error) {
|
|
617
|
+
failure = { error };
|
|
618
|
+
} finally {
|
|
619
|
+
// Even ignored children belong to this parent, including children admitted on an
|
|
620
|
+
// earlier attempt that pure coordination did not revisit this time.
|
|
621
|
+
try {
|
|
622
|
+
for (const entry of journal.children) {
|
|
623
|
+
if (started.has(entry.key)) continue;
|
|
624
|
+
const agent = descriptor.specialists.find(
|
|
625
|
+
(agent) =>
|
|
626
|
+
agent.kind === entry.snapshot.kind &&
|
|
627
|
+
agent.id === nodeId(entry.snapshot) &&
|
|
628
|
+
agent.version === entry.snapshot.version,
|
|
629
|
+
);
|
|
630
|
+
if (!agent)
|
|
631
|
+
fail("unregistered_specialist", "The saved child is not a registered specialist.");
|
|
632
|
+
// A rejected helper definition must not resume saved work through this fallback.
|
|
633
|
+
// Already started children still settle below, as for every delegation.
|
|
634
|
+
if (failure && entry.snapshot.kind === "agent" && entry.snapshot.subagent) continue;
|
|
635
|
+
if (entry.snapshot.kind === "agent" && entry.snapshot.subagent && agent.kind === "agent") {
|
|
636
|
+
const { base, ...record } = entry.snapshot.subagent;
|
|
637
|
+
child(entry.key, agent, inputOf(entry.snapshot), {
|
|
638
|
+
record,
|
|
639
|
+
...(record.previousRunId
|
|
640
|
+
? { source: base }
|
|
641
|
+
: record.policy.self
|
|
642
|
+
? { source: parent.definition }
|
|
643
|
+
: {}),
|
|
644
|
+
});
|
|
645
|
+
} else if (agent.kind === "agent")
|
|
646
|
+
child(entry.key, agent, inputOf(agentSnapshot(entry.snapshot)));
|
|
647
|
+
else if (agent.kind === "remote" && entry.snapshot.kind === "remote")
|
|
648
|
+
child(entry.key, agent, entry.snapshot.input);
|
|
649
|
+
else if (agent.kind === "workflow") child(entry.key, agent, entry.snapshot.input);
|
|
650
|
+
}
|
|
651
|
+
} catch (error) {
|
|
652
|
+
failure ??= { error };
|
|
653
|
+
}
|
|
654
|
+
open = false;
|
|
655
|
+
const settled = await Promise.allSettled([...started.values(), ...asking]);
|
|
656
|
+
const rejected =
|
|
657
|
+
settled.find(
|
|
658
|
+
(item) =>
|
|
659
|
+
item.status === "rejected" &&
|
|
660
|
+
!(item.reason instanceof Halt && item.reason.state.status === "suspended"),
|
|
661
|
+
) ?? settled.find((item) => item.status === "rejected");
|
|
662
|
+
if (rejected?.status === "rejected") failure = { error: rejected.reason };
|
|
663
|
+
}
|
|
664
|
+
active();
|
|
665
|
+
// A coordinator may inspect or ignore outcomes, but cannot waive cancellation, tree limits
|
|
666
|
+
// or broken host/journal contracts. All admitted children have settled at this point.
|
|
667
|
+
for (const { snapshot } of journal.children) {
|
|
668
|
+
const state = snapshot.state;
|
|
669
|
+
if (state.status === "cancelled") scope.tree.stop();
|
|
670
|
+
if (
|
|
671
|
+
(state.status === "cancelled" || state.status === "limited" || state.status === "failed") &&
|
|
672
|
+
!isLocalStop(state)
|
|
673
|
+
)
|
|
674
|
+
throw new Halt(state);
|
|
675
|
+
}
|
|
676
|
+
if (failure?.error instanceof CancelledQuestion)
|
|
677
|
+
return {
|
|
678
|
+
ok: false,
|
|
679
|
+
kind: "cancelled",
|
|
680
|
+
content: "The person cancelled this question. Continue without this action.",
|
|
681
|
+
};
|
|
682
|
+
if (failure && !(failure.error instanceof Halt && failure.error.state.status === "suspended"))
|
|
683
|
+
throw failure.error;
|
|
684
|
+
if (
|
|
685
|
+
journal.children.some((entry) => entry.snapshot.state.status === "suspended") ||
|
|
686
|
+
requests.execution.asks?.some((record) => !record.closed && !record.decision)
|
|
687
|
+
)
|
|
688
|
+
throw new Halt({ status: "suspended" });
|
|
689
|
+
if (failure) throw failure.error;
|
|
690
|
+
if (!result) throw new Error("The delegation ended without a result.");
|
|
691
|
+
return result;
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
class CancelledQuestion extends Error {}
|