@providerkit/agents 0.1.0 → 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-APACHE-2.0 +202 -0
- package/README.md +2108 -52
- 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 +85 -16
- package/dist/delegation.d.ts.map +1 -1
- package/dist/delegation.js +240 -106
- package/dist/delegation.js.map +1 -1
- 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 +14 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -1
- 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 +16 -4
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +2016 -245
- package/dist/run.js.map +1 -1
- package/dist/runs.d.ts +77 -34
- package/dist/runs.d.ts.map +1 -1
- package/dist/runs.js +267 -85
- package/dist/runs.js.map +1 -1
- 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 +57 -8
- package/dist/snapshot.d.ts.map +1 -1
- package/dist/snapshot.js +1206 -109
- package/dist/snapshot.js.map +1 -1
- 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 +62 -6
- package/dist/tree.d.ts.map +1 -1
- package/dist/tree.js +192 -23
- package/dist/tree.js.map +1 -1
- package/dist/types.d.ts +767 -52
- package/dist/types.d.ts.map +1 -1
- 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 +18 -4
- 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/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 +58 -6
- 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 +444 -155
- 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 +51 -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 +2678 -313
- package/src/runs.ts +464 -133
- package/src/schema-to-ts.ts +194 -0
- package/src/session.ts +178 -0
- package/src/snapshot.ts +1595 -124
- package/src/steering.ts +329 -0
- package/src/subagents.ts +1084 -0
- package/src/tool-retry.ts +86 -0
- package/src/tree.ts +223 -27
- package/src/types.ts +711 -52
- package/src/workflow-snapshot.ts +366 -0
- package/src/workflow-types.ts +213 -0
- package/src/workflow.ts +1316 -0
package/src/delegation.ts
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
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";
|
|
1
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";
|
|
2
12
|
import {
|
|
3
|
-
|
|
4
|
-
checkTree,
|
|
13
|
+
agentSnapshot,
|
|
5
14
|
childRunId,
|
|
6
15
|
copyData,
|
|
7
16
|
equalData,
|
|
@@ -9,63 +18,175 @@ import {
|
|
|
9
18
|
isId,
|
|
10
19
|
isRecord,
|
|
11
20
|
} from "./snapshot.ts";
|
|
12
|
-
import {
|
|
21
|
+
import {
|
|
22
|
+
emitEvent,
|
|
23
|
+
fail,
|
|
24
|
+
Halt,
|
|
25
|
+
isLocalStop,
|
|
26
|
+
nodeId,
|
|
27
|
+
untilAbort,
|
|
28
|
+
type ExecutionScope,
|
|
29
|
+
} from "./tree.ts";
|
|
13
30
|
import type {
|
|
14
31
|
Agent,
|
|
32
|
+
AgentConfig,
|
|
33
|
+
AgentInput,
|
|
34
|
+
AgentMessage,
|
|
35
|
+
Answer,
|
|
36
|
+
QuestionAsk,
|
|
15
37
|
ChildEnvelope,
|
|
16
|
-
ChildPathStep,
|
|
17
38
|
DelegationExecution,
|
|
18
39
|
RunOptions,
|
|
40
|
+
RunLimits,
|
|
19
41
|
RunOutcome,
|
|
20
42
|
RunSnapshot,
|
|
43
|
+
ToolRequest,
|
|
21
44
|
ToolResult,
|
|
45
|
+
UserContent,
|
|
22
46
|
} from "./types.ts";
|
|
23
47
|
|
|
24
48
|
/** Internal symbol holds no execution state. Every invocation receives its own scope. */
|
|
25
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
|
+
}
|
|
26
60
|
|
|
27
|
-
export
|
|
28
|
-
|
|
29
|
-
|
|
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];
|
|
30
86
|
}
|
|
31
87
|
|
|
32
88
|
/** @internal */
|
|
33
89
|
export interface AgentRuntime<T> {
|
|
34
|
-
|
|
35
|
-
|
|
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;
|
|
36
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>;
|
|
37
122
|
execute(
|
|
38
123
|
snapshot: RunSnapshot,
|
|
39
124
|
options: RunOptions,
|
|
40
125
|
scope: ExecutionScope,
|
|
41
|
-
|
|
126
|
+
answers?: Readonly<Record<string, unknown>>,
|
|
42
127
|
): Promise<RunOutcome<T>>;
|
|
43
128
|
}
|
|
44
129
|
|
|
45
|
-
export interface ChildHandle<T = unknown> {
|
|
130
|
+
export interface ChildHandle<T = unknown, R extends NodeOutcome<T> = RunOutcome<T>> {
|
|
46
131
|
readonly key: string;
|
|
47
132
|
readonly runId: string;
|
|
48
133
|
/** A started child, not another provider call. Repeated joins reuse the same outcome. */
|
|
49
|
-
join(): Promise<
|
|
134
|
+
join(): Promise<R>;
|
|
50
135
|
}
|
|
51
136
|
|
|
52
|
-
export type Joined<H extends readonly ChildHandle<unknown>[]> = {
|
|
53
|
-
[K in keyof H]: H[K] extends ChildHandle<infer
|
|
137
|
+
export type Joined<H extends readonly ChildHandle<unknown, NodeOutcome>[]> = {
|
|
138
|
+
[K in keyof H]: H[K] extends ChildHandle<unknown, infer R> ? R : never;
|
|
54
139
|
};
|
|
55
140
|
|
|
56
141
|
export interface DelegationContext {
|
|
57
|
-
|
|
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>>;
|
|
58
172
|
/** Settles in caller order, not completion order. No child may outlive this barrier. */
|
|
59
|
-
join<const H extends readonly ChildHandle<unknown>[]>(
|
|
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[];
|
|
60
180
|
}
|
|
61
181
|
|
|
62
182
|
export interface DelegationSpec<I, O> {
|
|
63
183
|
name: string;
|
|
64
184
|
description: string;
|
|
65
185
|
inputSchema: JsonObjectSchema;
|
|
186
|
+
needsApproval?: boolean;
|
|
66
187
|
validate: (raw: unknown) => I;
|
|
67
188
|
/** Fixed allow-list. Agents cannot add tools or specialists at runtime. */
|
|
68
|
-
specialists: readonly
|
|
189
|
+
specialists: readonly Specialist[];
|
|
69
190
|
/** Pure, deterministic coordination only: use child and join for work. This callback
|
|
70
191
|
* can replay after interruption; do not put external effects or mutable host state here. */
|
|
71
192
|
run: (input: I, context: DelegationContext) => Promise<O>;
|
|
@@ -76,13 +197,15 @@ export interface DelegationSpec<I, O> {
|
|
|
76
197
|
export interface Delegation {
|
|
77
198
|
readonly kind: "delegation";
|
|
78
199
|
readonly name: string;
|
|
79
|
-
readonly
|
|
200
|
+
readonly needsApproval: boolean;
|
|
201
|
+
readonly specialists: readonly Specialist[];
|
|
80
202
|
definition(): ToolDefinition;
|
|
81
203
|
/** @internal Errors and suspensions must not go through Tool.invoke's error conversion. */
|
|
82
204
|
execute(raw: unknown, context: DelegationContext): Promise<ToolResult>;
|
|
83
205
|
}
|
|
84
206
|
|
|
85
207
|
export interface SpecialistToolOptions<T> {
|
|
208
|
+
needsApproval?: boolean;
|
|
86
209
|
name: string;
|
|
87
210
|
description: string;
|
|
88
211
|
/** Pure; may run again when replaying coordination. */
|
|
@@ -121,6 +244,7 @@ export function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation {
|
|
|
121
244
|
return Object.freeze({
|
|
122
245
|
kind: "delegation",
|
|
123
246
|
name: spec.name,
|
|
247
|
+
needsApproval: spec.needsApproval ?? false,
|
|
124
248
|
specialists,
|
|
125
249
|
definition: () => copyData(definition),
|
|
126
250
|
async execute(raw: unknown, context: DelegationContext): Promise<ToolResult> {
|
|
@@ -133,13 +257,13 @@ export function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation {
|
|
|
133
257
|
const output = await run(input, context);
|
|
134
258
|
const content = summarize ? summarize(output) : JSON.stringify(output);
|
|
135
259
|
if (typeof content !== "string") throw new TypeError("A delegation summary must be text.");
|
|
136
|
-
return {
|
|
260
|
+
return successfulToolResult({ output, summary: content });
|
|
137
261
|
},
|
|
138
262
|
});
|
|
139
263
|
}
|
|
140
264
|
|
|
141
265
|
export function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOptions<T>): Delegation {
|
|
142
|
-
|
|
266
|
+
const descriptor = defineDelegation({
|
|
143
267
|
...options,
|
|
144
268
|
inputSchema: {
|
|
145
269
|
type: "object",
|
|
@@ -165,6 +289,33 @@ export function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOption
|
|
|
165
289
|
return result.output;
|
|
166
290
|
},
|
|
167
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
|
+
});
|
|
168
319
|
}
|
|
169
320
|
|
|
170
321
|
/** The whole pure coordination barrier lends its parent's slot, not each join.
|
|
@@ -173,146 +324,179 @@ export async function executeDelegation(
|
|
|
173
324
|
descriptor: Delegation,
|
|
174
325
|
journal: DelegationExecution,
|
|
175
326
|
parent: RunSnapshot,
|
|
176
|
-
raw: unknown
|
|
327
|
+
raw: Record<string, unknown>,
|
|
177
328
|
options: RunOptions,
|
|
178
329
|
scope: ExecutionScope,
|
|
179
330
|
signal: AbortSignal,
|
|
180
331
|
active: () => void,
|
|
181
|
-
|
|
332
|
+
requests: RequestJournal,
|
|
182
333
|
): Promise<ToolResult> {
|
|
183
334
|
let open = true;
|
|
184
335
|
const started = new Map<string, Promise<void>>();
|
|
185
|
-
const
|
|
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);
|
|
186
348
|
|
|
187
|
-
function
|
|
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> {
|
|
188
402
|
if (!open)
|
|
189
403
|
throw new Error("This delegation has ended; start children only inside its coordinator.");
|
|
190
404
|
active();
|
|
191
|
-
if (!isId(key)
|
|
192
|
-
throw new TypeError("A child needs a non-empty key and text input.");
|
|
405
|
+
if (!isId(key)) throw new TypeError("A child needs a non-empty key.");
|
|
193
406
|
if (!descriptor.specialists.includes(agent))
|
|
194
407
|
fail(
|
|
195
408
|
"unregistered_specialist",
|
|
196
|
-
"Register this 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.",
|
|
197
421
|
journal.operationId,
|
|
198
422
|
);
|
|
199
|
-
|
|
423
|
+
requested.set(key, identity);
|
|
424
|
+
const runId = childRunId(journal.operationId, key);
|
|
200
425
|
let entry = journal.children.find((saved) => saved.key === key);
|
|
201
426
|
const resume = entry !== undefined;
|
|
202
427
|
if (entry) {
|
|
428
|
+
const saved = entry.snapshot;
|
|
429
|
+
const savedStart =
|
|
430
|
+
saved.kind === "agent" ? { history: saved.history, input: saved.input } : saved.input;
|
|
203
431
|
if (
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
+
)
|
|
207
442
|
)
|
|
208
443
|
fail(
|
|
209
444
|
"child_key_conflict",
|
|
210
|
-
"This child key
|
|
445
|
+
"This child key belongs to another definition or input.",
|
|
211
446
|
journal.operationId,
|
|
212
447
|
);
|
|
213
|
-
} else {
|
|
214
|
-
scope.tree.reserveChild(scope.depth + 1);
|
|
215
|
-
entry = {
|
|
216
|
-
key,
|
|
217
|
-
snapshot: runtime.create(input, childRunId(journal.operationId, key), parent.tree),
|
|
218
|
-
};
|
|
219
|
-
journal.children.push(entry);
|
|
220
448
|
}
|
|
221
|
-
const saved = entry;
|
|
222
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
|
+
}
|
|
223
465
|
const work = async () => {
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
saved
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
try {
|
|
259
|
-
envelope = options.host?.child
|
|
260
|
-
? await untilAbort(
|
|
261
|
-
Promise.resolve(
|
|
262
|
-
options.host.child(
|
|
263
|
-
immutableCopy({
|
|
264
|
-
...saved,
|
|
265
|
-
parentRunId: parent.runId,
|
|
266
|
-
operationId: journal.operationId,
|
|
267
|
-
resume,
|
|
268
|
-
}),
|
|
269
|
-
execute,
|
|
270
|
-
),
|
|
271
|
-
),
|
|
272
|
-
signal,
|
|
273
|
-
)
|
|
274
|
-
: await execute();
|
|
275
|
-
if (execution && !executionSettled)
|
|
276
|
-
fail(
|
|
277
|
-
"invalid_child_host",
|
|
278
|
-
"The child hook returned before its execution settled.",
|
|
279
|
-
journal.operationId,
|
|
280
|
-
);
|
|
281
|
-
} finally {
|
|
282
|
-
hookOpen = false;
|
|
283
|
-
if (execution) await execution;
|
|
284
|
-
}
|
|
285
|
-
if (!isRecord(envelope) || (envelope.reference !== undefined && !isId(envelope.reference)))
|
|
286
|
-
fail(
|
|
287
|
-
"invalid_child_host",
|
|
288
|
-
"The child hook must return a snapshot envelope.",
|
|
289
|
-
journal.operationId,
|
|
290
|
-
);
|
|
291
|
-
const restored = runtime.restore(envelope.snapshot, parent.tree);
|
|
292
|
-
checkChildProgress(saved.snapshot, restored);
|
|
293
|
-
if (restored.state.status === "running")
|
|
294
|
-
fail(
|
|
295
|
-
"invalid_child_host",
|
|
296
|
-
"The child hook returned an unfinished child.",
|
|
297
|
-
journal.operationId,
|
|
298
|
-
);
|
|
299
|
-
// Returning a cached suspended host segment cannot consume an SDK approval.
|
|
300
|
-
if (!execution && childEvidence && restored.state.status === "suspended")
|
|
301
|
-
fail(
|
|
302
|
-
"host_resume_unsupported",
|
|
303
|
-
"The host returned a cached suspension. Resume this child in a new or resumable host segment.",
|
|
304
|
-
journal.operationId,
|
|
305
|
-
);
|
|
306
|
-
const previous = saved.snapshot;
|
|
307
|
-
saved.snapshot = restored;
|
|
308
|
-
try {
|
|
309
|
-
checkTree(scope.tree.root);
|
|
310
|
-
} catch (error) {
|
|
311
|
-
saved.snapshot = previous;
|
|
312
|
-
throw error;
|
|
313
|
-
}
|
|
314
|
-
saved.reference = envelope.reference ?? saved.reference;
|
|
315
|
-
await scope.tree.save();
|
|
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
|
+
);
|
|
316
500
|
};
|
|
317
501
|
const promise = work().catch(async (error: unknown) => {
|
|
318
502
|
let failure = error;
|
|
@@ -321,8 +505,8 @@ export async function executeDelegation(
|
|
|
321
505
|
} catch (stopped) {
|
|
322
506
|
failure = stopped;
|
|
323
507
|
}
|
|
324
|
-
if (
|
|
325
|
-
|
|
508
|
+
if (entry?.snapshot.state.status === "running") {
|
|
509
|
+
entry.snapshot.state =
|
|
326
510
|
failure instanceof Halt
|
|
327
511
|
? failure.state
|
|
328
512
|
: {
|
|
@@ -339,9 +523,11 @@ export async function executeDelegation(
|
|
|
339
523
|
const pending = started.get(key);
|
|
340
524
|
const handle = Object.freeze({
|
|
341
525
|
key,
|
|
342
|
-
runId
|
|
343
|
-
async join(): Promise<
|
|
526
|
+
runId,
|
|
527
|
+
async join(): Promise<NodeOutcome> {
|
|
344
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.");
|
|
345
531
|
return runtime.hydrate(saved.snapshot);
|
|
346
532
|
},
|
|
347
533
|
});
|
|
@@ -349,17 +535,84 @@ export async function executeDelegation(
|
|
|
349
535
|
return handle;
|
|
350
536
|
}
|
|
351
537
|
|
|
352
|
-
function join<const H extends readonly ChildHandle<unknown>[]>(
|
|
353
|
-
|
|
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[]> {
|
|
354
542
|
if (items.some((handle) => !handles.has(handle)))
|
|
355
543
|
throw new TypeError("Join only handles created by this delegation context.");
|
|
356
544
|
return Promise.all(items.map((handle) => handle.join()));
|
|
357
545
|
}
|
|
358
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
|
+
|
|
359
588
|
let result: ToolResult | undefined;
|
|
360
589
|
let failure: { error: unknown } | undefined;
|
|
361
590
|
try {
|
|
362
|
-
result = await untilAbort(
|
|
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
|
+
);
|
|
363
616
|
} catch (error) {
|
|
364
617
|
failure = { error };
|
|
365
618
|
} finally {
|
|
@@ -370,36 +623,72 @@ export async function executeDelegation(
|
|
|
370
623
|
if (started.has(entry.key)) continue;
|
|
371
624
|
const agent = descriptor.specialists.find(
|
|
372
625
|
(agent) =>
|
|
373
|
-
agent.
|
|
626
|
+
agent.kind === entry.snapshot.kind &&
|
|
627
|
+
agent.id === nodeId(entry.snapshot) &&
|
|
628
|
+
agent.version === entry.snapshot.version,
|
|
374
629
|
);
|
|
375
630
|
if (!agent)
|
|
376
631
|
fail("unregistered_specialist", "The saved child is not a registered specialist.");
|
|
377
|
-
|
|
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);
|
|
378
650
|
}
|
|
379
651
|
} catch (error) {
|
|
380
652
|
failure ??= { error };
|
|
381
653
|
}
|
|
382
654
|
open = false;
|
|
383
|
-
const settled = await Promise.allSettled(started.values());
|
|
384
|
-
const rejected =
|
|
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");
|
|
385
662
|
if (rejected?.status === "rejected") failure = { error: rejected.reason };
|
|
386
663
|
}
|
|
387
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
|
+
};
|
|
388
682
|
if (failure && !(failure.error instanceof Halt && failure.error.state.status === "suspended"))
|
|
389
683
|
throw failure.error;
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
path: [
|
|
396
|
-
{ operationId: journal.operationId, key: entry.key, runId: entry.snapshot.runId },
|
|
397
|
-
...state.path,
|
|
398
|
-
],
|
|
399
|
-
});
|
|
400
|
-
}
|
|
401
|
-
}
|
|
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" });
|
|
402
689
|
if (failure) throw failure.error;
|
|
403
690
|
if (!result) throw new Error("The delegation ended without a result.");
|
|
404
691
|
return result;
|
|
405
692
|
}
|
|
693
|
+
|
|
694
|
+
class CancelledQuestion extends Error {}
|