@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/dist/delegation.d.ts
CHANGED
|
@@ -1,40 +1,105 @@
|
|
|
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 { type JsonObjectSchema, type ToolDefinition } from "@providerkit/core";
|
|
5
|
+
import { RequestJournal } from "./request.ts";
|
|
6
|
+
import { type SubagentCreation, type SubagentRecord } from "./subagents.ts";
|
|
7
|
+
import { type Handoff } from "./handoff.ts";
|
|
2
8
|
import { type ExecutionScope } from "./tree.ts";
|
|
3
|
-
import type { Agent,
|
|
9
|
+
import type { Agent, AgentConfig, AgentInput, AgentMessage, Answer, QuestionAsk, DelegationExecution, RunOptions, RunLimits, RunOutcome, RunSnapshot, ToolRequest, ToolResult, UserContent } from "./types.ts";
|
|
4
10
|
/** Internal symbol holds no execution state. Every invocation receives its own scope. */
|
|
5
11
|
export declare const AGENT_RUNTIME: unique symbol;
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
12
|
+
/** @internal Only the built-in helper coordinator receives this journaled admission path. */
|
|
13
|
+
export declare const SUBAGENT_CONTEXT: unique symbol;
|
|
14
|
+
/** @internal What a new run starts from, checked: the history before the new turn, the turn,
|
|
15
|
+
* and the session the history came from. */
|
|
16
|
+
export interface RunStart {
|
|
17
|
+
history: AgentMessage[];
|
|
18
|
+
input: UserContent;
|
|
19
|
+
session?: RunSnapshot["session"];
|
|
9
20
|
}
|
|
21
|
+
export type Specialist = Agent<unknown> | Workflow<unknown, unknown> | RemoteAgent<unknown>;
|
|
22
|
+
export type NodeOutcome<T = unknown> = RunOutcome<T> | WorkflowOutcome<T> | RemoteOutcome<T>;
|
|
23
|
+
export interface NodeRuntime<R extends NodeOutcome = NodeOutcome> {
|
|
24
|
+
restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): TreeNode;
|
|
25
|
+
hydrate(snapshot: TreeNode): R;
|
|
26
|
+
answerRequests(snapshot: TreeNode, options: RunOptions, scope: ExecutionScope, answers: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<void>;
|
|
27
|
+
execute(snapshot: TreeNode, options: RunOptions, scope: ExecutionScope, answers?: Readonly<Record<string, unknown>>): Promise<R>;
|
|
28
|
+
}
|
|
29
|
+
export declare function runtimeOf<T>(node: Agent<T>): NodeRuntime<RunOutcome<T>>;
|
|
30
|
+
export declare function runtimeOf<T>(node: RemoteAgent<T>): NodeRuntime<RemoteOutcome<T>>;
|
|
31
|
+
export declare function runtimeOf<I, O>(node: Workflow<I, O>): NodeRuntime<WorkflowOutcome<O>>;
|
|
32
|
+
export declare function runtimeOf(node: Specialist): NodeRuntime;
|
|
10
33
|
/** @internal */
|
|
11
34
|
export interface AgentRuntime<T> {
|
|
12
|
-
|
|
13
|
-
|
|
35
|
+
readonly node: NodeRuntime<RunOutcome<T>>;
|
|
36
|
+
readonly handoffs: readonly Handoff[];
|
|
37
|
+
readonly tools: NonNullable<AgentConfig["tools"]>;
|
|
38
|
+
readonly enabledTools: readonly string[] | undefined;
|
|
39
|
+
readonly limits: RunLimits;
|
|
40
|
+
/** JSON identity of host configuration. Callbacks need an agent version change. */
|
|
41
|
+
configuration(): Record<string, unknown>;
|
|
42
|
+
/** Recheck current selection without resolving or replacing recorded instructions. */
|
|
43
|
+
checkTools(snapshot: RunSnapshot, options: RunOptions): Promise<void>;
|
|
44
|
+
/** A new root run's snapshot: the input normalized, the session read once and the history
|
|
45
|
+
* prepared, repaired and frozen, before anything is saved. */
|
|
46
|
+
open(input: AgentInput, options: RunOptions, runId: string): Promise<RunSnapshot>;
|
|
47
|
+
/** The history repaired with this agent's tools and the inline bytes checked: the exact form
|
|
48
|
+
* a snapshot stores, so a saved child can be compared with a new request for its key. */
|
|
49
|
+
freeze(start: RunStart): RunStart;
|
|
50
|
+
/** Resolves the run definition once, then creates a snapshot from the repaired history. */
|
|
51
|
+
create(start: RunStart, runId: string, tree?: RunSnapshot["tree"], options?: RunOptions, subagent?: SubagentCreation): Promise<RunSnapshot>;
|
|
52
|
+
restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): RunSnapshot;
|
|
14
53
|
hydrate(snapshot: RunSnapshot): RunOutcome<T>;
|
|
15
|
-
|
|
54
|
+
answerRequests(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, answers: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<void>;
|
|
55
|
+
execute(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, answers?: Readonly<Record<string, unknown>>): Promise<RunOutcome<T>>;
|
|
16
56
|
}
|
|
17
|
-
export interface ChildHandle<T = unknown> {
|
|
57
|
+
export interface ChildHandle<T = unknown, R extends NodeOutcome<T> = RunOutcome<T>> {
|
|
18
58
|
readonly key: string;
|
|
19
59
|
readonly runId: string;
|
|
20
60
|
/** A started child, not another provider call. Repeated joins reuse the same outcome. */
|
|
21
|
-
join(): Promise<
|
|
61
|
+
join(): Promise<R>;
|
|
22
62
|
}
|
|
23
|
-
export type Joined<H extends readonly ChildHandle<unknown>[]> = {
|
|
24
|
-
[K in keyof H]: H[K] extends ChildHandle<infer
|
|
63
|
+
export type Joined<H extends readonly ChildHandle<unknown, NodeOutcome>[]> = {
|
|
64
|
+
[K in keyof H]: H[K] extends ChildHandle<unknown, infer R> ? R : never;
|
|
25
65
|
};
|
|
26
66
|
export interface DelegationContext {
|
|
27
|
-
|
|
67
|
+
/** @internal Kept off the public barrel. Model-created helpers use the same child journal. */
|
|
68
|
+
readonly [SUBAGENT_CONTEXT]?: {
|
|
69
|
+
parent: RunSnapshot;
|
|
70
|
+
journal: DelegationExecution;
|
|
71
|
+
scope: ExecutionScope;
|
|
72
|
+
request: ToolRequest;
|
|
73
|
+
signal: AbortSignal;
|
|
74
|
+
recheck(agent: Agent<unknown>, snapshot: RunSnapshot): Promise<void>;
|
|
75
|
+
child<T>(key: string, agent: Agent<T>, input: AgentInput, subagent: SubagentCreation): ChildHandle<T>;
|
|
76
|
+
};
|
|
77
|
+
/** Pure coordination replays from its start. The saved answer is matched by key and checked
|
|
78
|
+
* by this pure validator, not by a saved JavaScript stack. A rejected form is asked again. */
|
|
79
|
+
ask<T>(question: Omit<QuestionAsk, "type">, validate: (answer: Answer) => T): Promise<T>;
|
|
80
|
+
/** `key` becomes part of the child's run id and of every operation id under it, which
|
|
81
|
+
* progress events carry and a display layer may send to a browser. Key by position or a
|
|
82
|
+
* fixed name ("topic-1"), never by the input. The input is checked like `run`'s, except
|
|
83
|
+
* that provider-owned fields are kept: coordinator code is trusted. A child never gets the
|
|
84
|
+
* parent's session. */
|
|
85
|
+
child<I, O>(key: string, workflow: Workflow<I, O>, input: I): ChildHandle<O, WorkflowOutcome<O>>;
|
|
86
|
+
child<T>(key: string, agent: Agent<T>, input: AgentInput): ChildHandle<T>;
|
|
87
|
+
child<T>(key: string, agent: RemoteAgent<T>, input: RemoteInput): ChildHandle<T, RemoteOutcome<T>>;
|
|
28
88
|
/** 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>>;
|
|
89
|
+
join<const H extends readonly ChildHandle<unknown, NodeOutcome>[]>(handles: H): Promise<Joined<H>>;
|
|
90
|
+
/** The parent's conversation before this tool call: no system prompt and no unfinished
|
|
91
|
+
* round. Frozen. A child sees none of it unless you forward it, for example
|
|
92
|
+
* `{ messages: [...context.conversation, { role: "user", content: task }] }`. */
|
|
93
|
+
readonly conversation: readonly AgentMessage[];
|
|
30
94
|
}
|
|
31
95
|
export interface DelegationSpec<I, O> {
|
|
32
96
|
name: string;
|
|
33
97
|
description: string;
|
|
34
98
|
inputSchema: JsonObjectSchema;
|
|
99
|
+
needsApproval?: boolean;
|
|
35
100
|
validate: (raw: unknown) => I;
|
|
36
101
|
/** Fixed allow-list. Agents cannot add tools or specialists at runtime. */
|
|
37
|
-
specialists: readonly
|
|
102
|
+
specialists: readonly Specialist[];
|
|
38
103
|
/** Pure, deterministic coordination only: use child and join for work. This callback
|
|
39
104
|
* can replay after interruption; do not put external effects or mutable host state here. */
|
|
40
105
|
run: (input: I, context: DelegationContext) => Promise<O>;
|
|
@@ -44,12 +109,14 @@ export interface DelegationSpec<I, O> {
|
|
|
44
109
|
export interface Delegation {
|
|
45
110
|
readonly kind: "delegation";
|
|
46
111
|
readonly name: string;
|
|
47
|
-
readonly
|
|
112
|
+
readonly needsApproval: boolean;
|
|
113
|
+
readonly specialists: readonly Specialist[];
|
|
48
114
|
definition(): ToolDefinition;
|
|
49
115
|
/** @internal Errors and suspensions must not go through Tool.invoke's error conversion. */
|
|
50
116
|
execute(raw: unknown, context: DelegationContext): Promise<ToolResult>;
|
|
51
117
|
}
|
|
52
118
|
export interface SpecialistToolOptions<T> {
|
|
119
|
+
needsApproval?: boolean;
|
|
53
120
|
name: string;
|
|
54
121
|
description: string;
|
|
55
122
|
/** Pure; may run again when replaying coordination. */
|
|
@@ -60,7 +127,9 @@ export declare function isDelegation(value: {
|
|
|
60
127
|
}): value is Delegation;
|
|
61
128
|
export declare function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation;
|
|
62
129
|
export declare function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOptions<T>): Delegation;
|
|
130
|
+
/** Known local failures are tool data. Authority and journal failures still stop the tree. */
|
|
131
|
+
export declare function specialistFailures(descriptor: Delegation): Delegation;
|
|
63
132
|
/** The whole pure coordination barrier lends its parent's slot, not each join.
|
|
64
133
|
* Overlapping joins therefore cannot reacquire a slot while another join still waits. */
|
|
65
|
-
export declare function executeDelegation(descriptor: Delegation, journal: DelegationExecution, parent: RunSnapshot, raw:
|
|
134
|
+
export declare function executeDelegation(descriptor: Delegation, journal: DelegationExecution, parent: RunSnapshot, raw: Record<string, unknown>, options: RunOptions, scope: ExecutionScope, signal: AbortSignal, active: () => void, requests: RequestJournal): Promise<ToolResult>;
|
|
66
135
|
//# sourceMappingURL=delegation.d.ts.map
|
package/dist/delegation.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"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"}
|
package/dist/delegation.js
CHANGED
|
@@ -1,8 +1,20 @@
|
|
|
1
1
|
import { messageOf } from "@providerkit/core";
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { admitChild, startChild, childOptions, prepareChild } from "./child.js";
|
|
3
|
+
import { RequestJournal } from "./request.js";
|
|
4
|
+
import { checkMemoryBinding } from "./memory.js";
|
|
5
|
+
import { isSubagentTool } from "./subagents.js";
|
|
6
|
+
import { successfulToolResult } from "./extensions.js";
|
|
7
|
+
import { handoffRef } from "./handoff.js";
|
|
8
|
+
import { conversationOf, inputOf } from "./input.js";
|
|
9
|
+
import { agentSnapshot, childRunId, copyData, equalData, immutableCopy, isId, isRecord, } from "./snapshot.js";
|
|
10
|
+
import { emitEvent, fail, Halt, isLocalStop, nodeId, untilAbort, } from "./tree.js";
|
|
4
11
|
/** Internal symbol holds no execution state. Every invocation receives its own scope. */
|
|
5
12
|
export const AGENT_RUNTIME = Symbol("agent-runtime");
|
|
13
|
+
/** @internal Only the built-in helper coordinator receives this journaled admission path. */
|
|
14
|
+
export const SUBAGENT_CONTEXT = Symbol("subagent-context");
|
|
15
|
+
export function runtimeOf(node) {
|
|
16
|
+
return node.kind === "agent" ? node[AGENT_RUNTIME].node : node[AGENT_RUNTIME];
|
|
17
|
+
}
|
|
6
18
|
export function isDelegation(value) {
|
|
7
19
|
return "kind" in value && value.kind === "delegation";
|
|
8
20
|
}
|
|
@@ -28,6 +40,7 @@ export function defineDelegation(spec) {
|
|
|
28
40
|
return Object.freeze({
|
|
29
41
|
kind: "delegation",
|
|
30
42
|
name: spec.name,
|
|
43
|
+
needsApproval: spec.needsApproval ?? false,
|
|
31
44
|
specialists,
|
|
32
45
|
definition: () => copyData(definition),
|
|
33
46
|
async execute(raw, context) {
|
|
@@ -42,12 +55,12 @@ export function defineDelegation(spec) {
|
|
|
42
55
|
const content = summarize ? summarize(output) : JSON.stringify(output);
|
|
43
56
|
if (typeof content !== "string")
|
|
44
57
|
throw new TypeError("A delegation summary must be text.");
|
|
45
|
-
return {
|
|
58
|
+
return successfulToolResult({ output, summary: content });
|
|
46
59
|
},
|
|
47
60
|
});
|
|
48
61
|
}
|
|
49
62
|
export function specialistTool(agent, options) {
|
|
50
|
-
|
|
63
|
+
const descriptor = defineDelegation({
|
|
51
64
|
...options,
|
|
52
65
|
inputSchema: {
|
|
53
66
|
type: "object",
|
|
@@ -73,105 +86,137 @@ export function specialistTool(agent, options) {
|
|
|
73
86
|
return result.output;
|
|
74
87
|
},
|
|
75
88
|
});
|
|
89
|
+
return specialistFailures(descriptor);
|
|
90
|
+
}
|
|
91
|
+
/** Known local failures are tool data. Authority and journal failures still stop the tree. */
|
|
92
|
+
export function specialistFailures(descriptor) {
|
|
93
|
+
return Object.freeze({
|
|
94
|
+
...descriptor,
|
|
95
|
+
async execute(raw, context) {
|
|
96
|
+
try {
|
|
97
|
+
return await descriptor.execute(raw, context);
|
|
98
|
+
}
|
|
99
|
+
catch (error) {
|
|
100
|
+
if (!(error instanceof Halt) || !isLocalStop(error.state))
|
|
101
|
+
throw error;
|
|
102
|
+
const reason = error.state.status === "limited"
|
|
103
|
+
? `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`
|
|
104
|
+
: error.state.status === "failed" &&
|
|
105
|
+
["memory_missing", "memory_unavailable"].includes(error.state.error.code)
|
|
106
|
+
? "a problem reading saved notes"
|
|
107
|
+
: "a model or result failure";
|
|
108
|
+
return {
|
|
109
|
+
ok: false,
|
|
110
|
+
kind: "failed",
|
|
111
|
+
content: `The specialist could not finish because of ${reason}. Continue with the other results.`,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
},
|
|
115
|
+
});
|
|
76
116
|
}
|
|
77
117
|
/** The whole pure coordination barrier lends its parent's slot, not each join.
|
|
78
118
|
* 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,
|
|
119
|
+
export async function executeDelegation(descriptor, journal, parent, raw, options, scope, signal, active, requests) {
|
|
80
120
|
let open = true;
|
|
81
121
|
const started = new Map();
|
|
122
|
+
const requested = new Map();
|
|
123
|
+
// Resolve new child definitions in admission order, without delaying children already
|
|
124
|
+
// running. No half-resolved definition can appear in another child's root checkpoint.
|
|
125
|
+
let admissions = Promise.resolve();
|
|
82
126
|
const handles = new WeakSet();
|
|
83
|
-
|
|
127
|
+
// Computed again on a replay from the same settled rounds, so a coordinator that forwards it
|
|
128
|
+
// asks for the same child input and reuses the saved child.
|
|
129
|
+
const conversation = immutableCopy(conversationOf(parent));
|
|
130
|
+
const inherited = childOptions(options);
|
|
131
|
+
async function recheck(agent, snapshot) {
|
|
132
|
+
if (!options.host?.beforeTool)
|
|
133
|
+
fail("subagent_authority_missing", "Supply host.beforeTool to authorize helper forks and follow-ups.");
|
|
134
|
+
await agent[AGENT_RUNTIME].checkTools(snapshot, { ...inherited, signal });
|
|
135
|
+
checkMemoryBinding(snapshot, inherited.memory);
|
|
136
|
+
if (inherited.memory) {
|
|
137
|
+
const { store, scope, shared = [] } = inherited.memory;
|
|
138
|
+
try {
|
|
139
|
+
for (const access of [...(scope ? [scope] : []), ...shared]) {
|
|
140
|
+
const current = await untilAbort(store.access(immutableCopy(access.scope), { signal }), signal);
|
|
141
|
+
if (!equalData(current, access))
|
|
142
|
+
throw new Error("Changed memory access");
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
catch {
|
|
146
|
+
signal.throwIfAborted();
|
|
147
|
+
fail("subagent_memory_changed", "The helper's memory access changed or could not be checked. Obtain fresh host authorization before starting new work.");
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
await requests.recheck({ ...requests.call, arguments: raw });
|
|
151
|
+
await requests.assertFresh();
|
|
152
|
+
active();
|
|
153
|
+
}
|
|
154
|
+
function child(key, agent, input, subagent) {
|
|
84
155
|
if (!open)
|
|
85
156
|
throw new Error("This delegation has ended; start children only inside its coordinator.");
|
|
86
157
|
active();
|
|
87
|
-
if (!isId(key)
|
|
88
|
-
throw new TypeError("A child needs a non-empty key
|
|
158
|
+
if (!isId(key))
|
|
159
|
+
throw new TypeError("A child needs a non-empty key.");
|
|
89
160
|
if (!descriptor.specialists.includes(agent))
|
|
90
|
-
fail("unregistered_specialist", "Register this specialist
|
|
91
|
-
const runtime = agent
|
|
161
|
+
fail("unregistered_specialist", "Register this specialist before starting it.", journal.operationId);
|
|
162
|
+
const runtime = runtimeOf(agent);
|
|
163
|
+
const prepared = prepareChild(agent, input, subagent, scope.tree.root);
|
|
164
|
+
const start = prepared.input;
|
|
165
|
+
const identity = { agentId: agent.id, version: agent.version, start, subagent };
|
|
166
|
+
const prior = requested.get(key);
|
|
167
|
+
if (prior && !equalData(prior, identity))
|
|
168
|
+
fail("child_key_conflict", "This child key belongs to another definition or input.", journal.operationId);
|
|
169
|
+
requested.set(key, identity);
|
|
170
|
+
const runId = childRunId(journal.operationId, key);
|
|
92
171
|
let entry = journal.children.find((saved) => saved.key === key);
|
|
93
172
|
const resume = entry !== undefined;
|
|
94
173
|
if (entry) {
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
};
|
|
106
|
-
journal.children.push(entry);
|
|
174
|
+
const saved = entry.snapshot;
|
|
175
|
+
const savedStart = saved.kind === "agent" ? { history: saved.history, input: saved.input } : saved.input;
|
|
176
|
+
if (saved.kind !== agent.kind ||
|
|
177
|
+
nodeId(saved) !== agent.id ||
|
|
178
|
+
saved.version !== agent.version ||
|
|
179
|
+
!equalData(savedStart, start) ||
|
|
180
|
+
!equalData(saved.kind === "agent" && saved.subagent
|
|
181
|
+
? { ...saved.subagent, base: undefined }
|
|
182
|
+
: undefined, subagent?.record))
|
|
183
|
+
fail("child_key_conflict", "This child key belongs to another definition or input.", journal.operationId);
|
|
107
184
|
}
|
|
108
|
-
const saved = entry;
|
|
109
185
|
if (!started.has(key)) {
|
|
186
|
+
let admitted;
|
|
187
|
+
if (entry)
|
|
188
|
+
admitted = Promise.resolve(entry);
|
|
189
|
+
else {
|
|
190
|
+
scope.tree.reserveChild(scope.depth + 1);
|
|
191
|
+
admitted = admissions.then(async () => {
|
|
192
|
+
const snapshot = await prepared.create(runId, parent.tree, { ...inherited, signal });
|
|
193
|
+
active();
|
|
194
|
+
entry = admitChild(journal.children, { key, snapshot }, scope);
|
|
195
|
+
return entry;
|
|
196
|
+
});
|
|
197
|
+
admissions = admitted.then(() => { }, () => { });
|
|
198
|
+
}
|
|
110
199
|
const work = async () => {
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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,
|
|
200
|
+
const saved = await admitted;
|
|
201
|
+
await startChild(saved, parent, journal.operationId, runtime, inherited, scope, signal, active, resume, async () => {
|
|
202
|
+
if (agent.kind === "agent" &&
|
|
203
|
+
saved.snapshot.kind === "agent" &&
|
|
204
|
+
(saved.snapshot.subagent?.fork || saved.snapshot.subagent?.previousRunId))
|
|
205
|
+
await recheck(agent, saved.snapshot);
|
|
206
|
+
if (journal.kind === "handoff")
|
|
207
|
+
emitEvent(options, {
|
|
208
|
+
type: "handoff",
|
|
209
|
+
runId: parent.runId,
|
|
210
|
+
attemptId: parent.attemptId,
|
|
143
211
|
operationId: journal.operationId,
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
}
|
|
150
|
-
|
|
151
|
-
|
|
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();
|
|
212
|
+
childRunId: saved.snapshot.runId,
|
|
213
|
+
from: handoffRef(parent),
|
|
214
|
+
to: journal.target,
|
|
215
|
+
...(journal.note !== undefined ? { note: journal.note } : {}),
|
|
216
|
+
});
|
|
217
|
+
}, journal.kind === "handoff"
|
|
218
|
+
? (parent.inputs.at(-1)?.content ?? scope.handoffInput ?? parent.input)
|
|
219
|
+
: undefined);
|
|
175
220
|
};
|
|
176
221
|
const promise = work().catch(async (error) => {
|
|
177
222
|
let failure = error;
|
|
@@ -181,8 +226,8 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
|
|
|
181
226
|
catch (stopped) {
|
|
182
227
|
failure = stopped;
|
|
183
228
|
}
|
|
184
|
-
if (
|
|
185
|
-
|
|
229
|
+
if (entry?.snapshot.state.status === "running") {
|
|
230
|
+
entry.snapshot.state =
|
|
186
231
|
failure instanceof Halt
|
|
187
232
|
? failure.state
|
|
188
233
|
: {
|
|
@@ -199,9 +244,12 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
|
|
|
199
244
|
const pending = started.get(key);
|
|
200
245
|
const handle = Object.freeze({
|
|
201
246
|
key,
|
|
202
|
-
runId
|
|
247
|
+
runId,
|
|
203
248
|
async join() {
|
|
204
249
|
await pending;
|
|
250
|
+
const saved = journal.children.find((child) => child.key === key);
|
|
251
|
+
if (!saved)
|
|
252
|
+
throw new Error("The child ended before its definition resolved.");
|
|
205
253
|
return runtime.hydrate(saved.snapshot);
|
|
206
254
|
},
|
|
207
255
|
});
|
|
@@ -213,10 +261,64 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
|
|
|
213
261
|
throw new TypeError("Join only handles created by this delegation context.");
|
|
214
262
|
return Promise.all(items.map((handle) => handle.join()));
|
|
215
263
|
}
|
|
264
|
+
// Adapted from LangGraph.js (MIT), interrupt.ts: return a saved answer on replay.
|
|
265
|
+
// Keys replace positional matching; validation stays with the trusted coordinator.
|
|
266
|
+
let asks = Promise.resolve();
|
|
267
|
+
const asking = [];
|
|
268
|
+
function ask(question, validate) {
|
|
269
|
+
if (!open)
|
|
270
|
+
throw new Error("Ask only inside the active coordinator.");
|
|
271
|
+
const work = asks.then(async () => {
|
|
272
|
+
active();
|
|
273
|
+
const record = await requests.ensure({ ...question, type: "question" });
|
|
274
|
+
if (!record.decision)
|
|
275
|
+
throw new Halt({ status: "suspended" });
|
|
276
|
+
if (record.decision.type === "stop") {
|
|
277
|
+
scope.tree.stop();
|
|
278
|
+
throw new Halt({ status: "cancelled" });
|
|
279
|
+
}
|
|
280
|
+
if (record.decision.type === "cancel")
|
|
281
|
+
throw new CancelledQuestion();
|
|
282
|
+
if (record.decision.type !== "answer")
|
|
283
|
+
throw new TypeError("This question needs an answer.");
|
|
284
|
+
await requests.recheck({ ...requests.call, arguments: raw });
|
|
285
|
+
active();
|
|
286
|
+
try {
|
|
287
|
+
return validate(immutableCopy(record.decision.answer));
|
|
288
|
+
}
|
|
289
|
+
catch (error) {
|
|
290
|
+
record.closed = "invalid";
|
|
291
|
+
await requests.open({ ...question, type: "question" }, { code: "invalid_answer", message: messageOf(error) });
|
|
292
|
+
throw new Halt({ status: "suspended" });
|
|
293
|
+
}
|
|
294
|
+
});
|
|
295
|
+
asks = work.then(() => { }, () => { });
|
|
296
|
+
asking.push(work);
|
|
297
|
+
void work.catch(() => { });
|
|
298
|
+
return work;
|
|
299
|
+
}
|
|
216
300
|
let result;
|
|
217
301
|
let failure;
|
|
218
302
|
try {
|
|
219
|
-
result = await untilAbort(descriptor.execute(raw, Object.freeze({
|
|
303
|
+
result = await untilAbort(descriptor.execute(raw, Object.freeze({
|
|
304
|
+
child,
|
|
305
|
+
join,
|
|
306
|
+
ask,
|
|
307
|
+
conversation,
|
|
308
|
+
...(isSubagentTool(descriptor)
|
|
309
|
+
? {
|
|
310
|
+
[SUBAGENT_CONTEXT]: {
|
|
311
|
+
parent,
|
|
312
|
+
journal,
|
|
313
|
+
scope,
|
|
314
|
+
request: { ...requests.call, arguments: raw },
|
|
315
|
+
signal,
|
|
316
|
+
recheck,
|
|
317
|
+
child,
|
|
318
|
+
},
|
|
319
|
+
}
|
|
320
|
+
: {}),
|
|
321
|
+
})), signal);
|
|
220
322
|
}
|
|
221
323
|
catch (error) {
|
|
222
324
|
failure = { error };
|
|
@@ -228,40 +330,72 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
|
|
|
228
330
|
for (const entry of journal.children) {
|
|
229
331
|
if (started.has(entry.key))
|
|
230
332
|
continue;
|
|
231
|
-
const agent = descriptor.specialists.find((agent) => agent.
|
|
333
|
+
const agent = descriptor.specialists.find((agent) => agent.kind === entry.snapshot.kind &&
|
|
334
|
+
agent.id === nodeId(entry.snapshot) &&
|
|
335
|
+
agent.version === entry.snapshot.version);
|
|
232
336
|
if (!agent)
|
|
233
337
|
fail("unregistered_specialist", "The saved child is not a registered specialist.");
|
|
234
|
-
|
|
338
|
+
// A rejected helper definition must not resume saved work through this fallback.
|
|
339
|
+
// Already started children still settle below, as for every delegation.
|
|
340
|
+
if (failure && entry.snapshot.kind === "agent" && entry.snapshot.subagent)
|
|
341
|
+
continue;
|
|
342
|
+
if (entry.snapshot.kind === "agent" && entry.snapshot.subagent && agent.kind === "agent") {
|
|
343
|
+
const { base, ...record } = entry.snapshot.subagent;
|
|
344
|
+
child(entry.key, agent, inputOf(entry.snapshot), {
|
|
345
|
+
record,
|
|
346
|
+
...(record.previousRunId
|
|
347
|
+
? { source: base }
|
|
348
|
+
: record.policy.self
|
|
349
|
+
? { source: parent.definition }
|
|
350
|
+
: {}),
|
|
351
|
+
});
|
|
352
|
+
}
|
|
353
|
+
else if (agent.kind === "agent")
|
|
354
|
+
child(entry.key, agent, inputOf(agentSnapshot(entry.snapshot)));
|
|
355
|
+
else if (agent.kind === "remote" && entry.snapshot.kind === "remote")
|
|
356
|
+
child(entry.key, agent, entry.snapshot.input);
|
|
357
|
+
else if (agent.kind === "workflow")
|
|
358
|
+
child(entry.key, agent, entry.snapshot.input);
|
|
235
359
|
}
|
|
236
360
|
}
|
|
237
361
|
catch (error) {
|
|
238
362
|
failure ??= { error };
|
|
239
363
|
}
|
|
240
364
|
open = false;
|
|
241
|
-
const settled = await Promise.allSettled(started.values());
|
|
242
|
-
const rejected = settled.find((item) => item.status === "rejected"
|
|
365
|
+
const settled = await Promise.allSettled([...started.values(), ...asking]);
|
|
366
|
+
const rejected = settled.find((item) => item.status === "rejected" &&
|
|
367
|
+
!(item.reason instanceof Halt && item.reason.state.status === "suspended")) ?? settled.find((item) => item.status === "rejected");
|
|
243
368
|
if (rejected?.status === "rejected")
|
|
244
369
|
failure = { error: rejected.reason };
|
|
245
370
|
}
|
|
246
371
|
active();
|
|
372
|
+
// A coordinator may inspect or ignore outcomes, but cannot waive cancellation, tree limits
|
|
373
|
+
// or broken host/journal contracts. All admitted children have settled at this point.
|
|
374
|
+
for (const { snapshot } of journal.children) {
|
|
375
|
+
const state = snapshot.state;
|
|
376
|
+
if (state.status === "cancelled")
|
|
377
|
+
scope.tree.stop();
|
|
378
|
+
if ((state.status === "cancelled" || state.status === "limited" || state.status === "failed") &&
|
|
379
|
+
!isLocalStop(state))
|
|
380
|
+
throw new Halt(state);
|
|
381
|
+
}
|
|
382
|
+
if (failure?.error instanceof CancelledQuestion)
|
|
383
|
+
return {
|
|
384
|
+
ok: false,
|
|
385
|
+
kind: "cancelled",
|
|
386
|
+
content: "The person cancelled this question. Continue without this action.",
|
|
387
|
+
};
|
|
247
388
|
if (failure && !(failure.error instanceof Halt && failure.error.state.status === "suspended"))
|
|
248
389
|
throw failure.error;
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
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
|
-
}
|
|
390
|
+
if (journal.children.some((entry) => entry.snapshot.state.status === "suspended") ||
|
|
391
|
+
requests.execution.asks?.some((record) => !record.closed && !record.decision))
|
|
392
|
+
throw new Halt({ status: "suspended" });
|
|
261
393
|
if (failure)
|
|
262
394
|
throw failure.error;
|
|
263
395
|
if (!result)
|
|
264
396
|
throw new Error("The delegation ended without a result.");
|
|
265
397
|
return result;
|
|
266
398
|
}
|
|
399
|
+
class CancelledQuestion extends Error {
|
|
400
|
+
}
|
|
267
401
|
//# sourceMappingURL=delegation.js.map
|