@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/workflow.js
ADDED
|
@@ -0,0 +1,1053 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Keyed JSON replay adapted from TanStack AI and Microsoft Agent Framework (MIT).
|
|
3
|
+
* Retry exclusions adapted from LangGraph.js (MIT).
|
|
4
|
+
* Child replay and suspension adapted from Google ADK JS:
|
|
5
|
+
* Copyright 2026 Google LLC. SPDX-License-Identifier: Apache-2.0
|
|
6
|
+
* Changes: explicit keys, fail-closed effects, existing SDK requests, leases and tree budgets.
|
|
7
|
+
* See THIRD_PARTY_NOTICES.md for source paths and licenses.
|
|
8
|
+
*/
|
|
9
|
+
import { backoffMs, createGate, isTransient, messageOf, ProviderError, sleep, } from "@providerkit/core";
|
|
10
|
+
import { AGENT_RUNTIME, defineDelegation, specialistFailures, runtimeOf, } from "./delegation.js";
|
|
11
|
+
import { admitChild, startChild, childOptions, prepareChild } from "./child.js";
|
|
12
|
+
import { checkMemoryBinding, memoryScopes, readMemoryBinding } from "./memory.js";
|
|
13
|
+
import { RequestJournal, isAsk, requestHash } from "./request.js";
|
|
14
|
+
import { checkOptions, childRunId, copyData, equalData, immutableCopy, isId, isRecord, readTreeLimits, readWorkflowSnapshot, } from "./snapshot.js";
|
|
15
|
+
import { readWorkflowLimits, stepData, stepId } from "./workflow-snapshot.js";
|
|
16
|
+
import { authorizeTree, emitEvent, ExecutionTree, fail, Halt, isLocalStop, nodeId, openRequests, readAnswers, requestRecords, snapshots, treeUsage, untilAbort, wakeAt, } from "./tree.js";
|
|
17
|
+
export class StepFailedError extends Error {
|
|
18
|
+
key;
|
|
19
|
+
error;
|
|
20
|
+
reason;
|
|
21
|
+
constructor(key, error) {
|
|
22
|
+
super(error.message);
|
|
23
|
+
this.key = key;
|
|
24
|
+
this.error = error;
|
|
25
|
+
this.name = "StepFailedError";
|
|
26
|
+
this.reason = error.reason;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
class Pause extends Error {
|
|
30
|
+
}
|
|
31
|
+
const pause = new Pause();
|
|
32
|
+
function workflowNode(node) {
|
|
33
|
+
if (node.kind !== "workflow")
|
|
34
|
+
throw new TypeError("Expected a workflow node.");
|
|
35
|
+
return node;
|
|
36
|
+
}
|
|
37
|
+
function retryable(error) {
|
|
38
|
+
if (error instanceof ProviderError)
|
|
39
|
+
return isTransient(error.kind) && error.shouldRetry !== false;
|
|
40
|
+
if (!isRecord(error))
|
|
41
|
+
return true;
|
|
42
|
+
if (error.name === "AbortError" ||
|
|
43
|
+
error.code === "ECONNABORTED" ||
|
|
44
|
+
(typeof error.message === "string" && /^(Cancel|AbortError)/.test(error.message)))
|
|
45
|
+
return false;
|
|
46
|
+
const status = isRecord(error.response) ? error.response.status : error.status;
|
|
47
|
+
if ([400, 401, 402, 403, 404, 405, 406, 407, 409].includes(Number(status)))
|
|
48
|
+
return false;
|
|
49
|
+
return (error.code !== "insufficient_quota" &&
|
|
50
|
+
!(isRecord(error.error) && error.error.code === "insufficient_quota"));
|
|
51
|
+
}
|
|
52
|
+
function errorOf(error, reason = "failed") {
|
|
53
|
+
return { reason, name: error instanceof Error ? error.name : "Error", message: messageOf(error) };
|
|
54
|
+
}
|
|
55
|
+
function stepPolicy(options) {
|
|
56
|
+
const timeoutMs = options.timeoutMs ?? 60_000;
|
|
57
|
+
const retry = options.retry;
|
|
58
|
+
if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
|
|
59
|
+
throw new TypeError("timeoutMs must be a positive whole number that fits a timer.");
|
|
60
|
+
if (retry &&
|
|
61
|
+
(!Number.isSafeInteger(retry.maxAttempts) ||
|
|
62
|
+
retry.maxAttempts < 1 ||
|
|
63
|
+
retry.maxAttempts > 100 ||
|
|
64
|
+
!["read-only", "reconcile"].includes(retry.replay) ||
|
|
65
|
+
[retry.baseDelayMs ?? 1_000, retry.maxDelayMs ?? 30_000].some((ms) => !Number.isSafeInteger(ms) || ms < 0 || ms > 2_147_483_647)))
|
|
66
|
+
throw new TypeError("Retries need a bounded attempt count and read-only or reconcile policy.");
|
|
67
|
+
if (options.needsApproval && retry)
|
|
68
|
+
throw new TypeError("Approval-gated effects cannot retry an old decision.");
|
|
69
|
+
return {
|
|
70
|
+
input: options.input,
|
|
71
|
+
timeoutMs,
|
|
72
|
+
needsApproval: options.needsApproval === true,
|
|
73
|
+
validate: !!options.validate,
|
|
74
|
+
validateInput: !!options.validateInput,
|
|
75
|
+
retry: retry
|
|
76
|
+
? {
|
|
77
|
+
maxAttempts: retry.maxAttempts,
|
|
78
|
+
replay: retry.replay,
|
|
79
|
+
baseDelayMs: retry.baseDelayMs ?? 1_000,
|
|
80
|
+
maxDelayMs: retry.maxDelayMs ?? 30_000,
|
|
81
|
+
retryOn: !!retry.retryOn,
|
|
82
|
+
}
|
|
83
|
+
: null,
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
export function defineWorkflow(spec) {
|
|
87
|
+
if (!isId(spec.id) ||
|
|
88
|
+
!isId(spec.version) ||
|
|
89
|
+
typeof spec.run !== "function" ||
|
|
90
|
+
!isRecord(spec.input?.schema) ||
|
|
91
|
+
spec.input.schema.type !== "object" ||
|
|
92
|
+
typeof spec.input.validate !== "function" ||
|
|
93
|
+
(spec.output &&
|
|
94
|
+
(!isRecord(spec.output.schema) ||
|
|
95
|
+
spec.output.schema.type !== "object" ||
|
|
96
|
+
typeof spec.output.validate !== "function")))
|
|
97
|
+
throw new TypeError("A workflow needs an id, version, input schema, validator and async function.");
|
|
98
|
+
const { id, version, run } = spec;
|
|
99
|
+
const input = { schema: immutableCopy(spec.input.schema), validate: spec.input.validate };
|
|
100
|
+
const output = spec.output && {
|
|
101
|
+
schema: immutableCopy(spec.output.schema),
|
|
102
|
+
validate: spec.output.validate,
|
|
103
|
+
};
|
|
104
|
+
const limits = readWorkflowLimits(spec.limits);
|
|
105
|
+
const treeLimits = readTreeLimits(spec.treeLimits);
|
|
106
|
+
const agents = [...(spec.agents ?? [])];
|
|
107
|
+
const workflows = [...(spec.workflows ?? [])];
|
|
108
|
+
const specialists = [...agents, ...workflows];
|
|
109
|
+
if (specialists.some((node) => !node?.[AGENT_RUNTIME]) ||
|
|
110
|
+
new Set(specialists.map((node) => node.id)).size !== specialists.length)
|
|
111
|
+
throw new TypeError("Register each workflow or agent once, with a unique id.");
|
|
112
|
+
const definition = immutableCopy({
|
|
113
|
+
input: input.schema,
|
|
114
|
+
output: output?.schema ?? null,
|
|
115
|
+
specialists: specialists.map((node) => ({
|
|
116
|
+
kind: node.kind,
|
|
117
|
+
id: node.id,
|
|
118
|
+
version: node.version,
|
|
119
|
+
definition: node[AGENT_RUNTIME].configuration(),
|
|
120
|
+
})),
|
|
121
|
+
});
|
|
122
|
+
const data = (value) => stepData(value, limits.resultBytes);
|
|
123
|
+
function validateOutput(value) {
|
|
124
|
+
// The unvalidated contract promises O is JSON. Validated contracts may rebuild application values.
|
|
125
|
+
return output ? output.validate(copyData(value)) : copyData(value);
|
|
126
|
+
}
|
|
127
|
+
function target(step) {
|
|
128
|
+
const node = specialists.find((node) => node.id === step.definition.targetId &&
|
|
129
|
+
node.version === step.definition.version &&
|
|
130
|
+
node.kind === step.kind);
|
|
131
|
+
if (!node)
|
|
132
|
+
throw new TypeError("Restore the registered workflow specialist version.");
|
|
133
|
+
return node;
|
|
134
|
+
}
|
|
135
|
+
function request(snapshot, step) {
|
|
136
|
+
return {
|
|
137
|
+
workflowId: id,
|
|
138
|
+
version,
|
|
139
|
+
runId: snapshot.runId,
|
|
140
|
+
attemptId: step.attempts.at(-1)?.attemptId ?? snapshot.attemptId,
|
|
141
|
+
operationId: step.id,
|
|
142
|
+
key: step.key,
|
|
143
|
+
kind: step.kind,
|
|
144
|
+
input: step.definition.input,
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
function journal(snapshot, step, options, scope, signal) {
|
|
148
|
+
return new RequestJournal(step, request(snapshot, step), options, scope, signal, () => requestHash({ workflowId: id, version, kind: step.kind, definition: step.definition }));
|
|
149
|
+
}
|
|
150
|
+
async function answerRequests(node, options, scope, answers, signal) {
|
|
151
|
+
const snapshot = workflowNode(node);
|
|
152
|
+
if (!["running", "suspended"].includes(snapshot.state.status))
|
|
153
|
+
return;
|
|
154
|
+
for (const step of snapshot.steps) {
|
|
155
|
+
if (step.status === "completed" || step.status === "failed")
|
|
156
|
+
continue;
|
|
157
|
+
const requests = journal(snapshot, step, options, scope, signal);
|
|
158
|
+
for (const record of [...(step.asks ?? [])]) {
|
|
159
|
+
scope.tree.active();
|
|
160
|
+
signal.throwIfAborted();
|
|
161
|
+
if (record.closed)
|
|
162
|
+
continue;
|
|
163
|
+
if (!record.decision && Object.hasOwn(answers, record.request.id))
|
|
164
|
+
await requests.resolve(record, answers[record.request.id]);
|
|
165
|
+
else
|
|
166
|
+
await requests.refresh(record);
|
|
167
|
+
}
|
|
168
|
+
for (const child of step.children)
|
|
169
|
+
await runtimeOf(target(step)).answerRequests(child.snapshot, childOptions(options), {
|
|
170
|
+
tree: scope.tree,
|
|
171
|
+
depth: scope.depth + 1,
|
|
172
|
+
path: [
|
|
173
|
+
...scope.path,
|
|
174
|
+
{ operationId: step.id, key: child.key, runId: child.snapshot.runId },
|
|
175
|
+
],
|
|
176
|
+
}, answers, signal);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
/** Replay coordination is also a preflight: no host callback, new admission or effect here. */
|
|
180
|
+
async function coordinate(snapshot, options, scope, replay, strictReplay = false, matched) {
|
|
181
|
+
const controller = new AbortController();
|
|
182
|
+
const signal = AbortSignal.any([
|
|
183
|
+
scope.tree.signal,
|
|
184
|
+
controller.signal,
|
|
185
|
+
...(options.signal ? [options.signal] : []),
|
|
186
|
+
]);
|
|
187
|
+
const gate = createGate(limits.parallelSteps);
|
|
188
|
+
const recorded = [...snapshot.steps];
|
|
189
|
+
const visited = new Set();
|
|
190
|
+
const work = [];
|
|
191
|
+
let accepting = true;
|
|
192
|
+
let paused = false;
|
|
193
|
+
let frontier = false;
|
|
194
|
+
let fatal;
|
|
195
|
+
const hostContext = Object.freeze({ ...options.context });
|
|
196
|
+
const emit = (opts, event) => {
|
|
197
|
+
try {
|
|
198
|
+
emitEvent(opts, event);
|
|
199
|
+
}
|
|
200
|
+
catch {
|
|
201
|
+
fail("progress_failed", "Workflow progress could not be stored. Reconcile saved state before continuing.");
|
|
202
|
+
}
|
|
203
|
+
};
|
|
204
|
+
function active() {
|
|
205
|
+
if (!strictReplay)
|
|
206
|
+
scope.tree.active();
|
|
207
|
+
if (options.signal?.aborted)
|
|
208
|
+
throw new Halt({ status: "cancelled" });
|
|
209
|
+
if (fatal)
|
|
210
|
+
throw fatal;
|
|
211
|
+
signal.throwIfAborted();
|
|
212
|
+
}
|
|
213
|
+
function stop(error) {
|
|
214
|
+
if (error === pause || (error instanceof Halt && error.state.status === "suspended")) {
|
|
215
|
+
paused = true;
|
|
216
|
+
return;
|
|
217
|
+
}
|
|
218
|
+
if (error instanceof Halt || !(error instanceof StepFailedError)) {
|
|
219
|
+
fatal ??= error;
|
|
220
|
+
controller.abort(error);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
function admit(key, kind, identity, execute) {
|
|
224
|
+
let entry;
|
|
225
|
+
try {
|
|
226
|
+
active();
|
|
227
|
+
if (!accepting)
|
|
228
|
+
fail("workflow_closed", "Start steps only inside the active workflow function.");
|
|
229
|
+
if (!isId(key) || key.length > 256)
|
|
230
|
+
fail("invalid_step_key", "Use a nonempty step key of at most 256 characters.");
|
|
231
|
+
if (visited.has(key))
|
|
232
|
+
fail("duplicate_step_key", "Use a different key for each step in one workflow attempt.");
|
|
233
|
+
visited.add(key);
|
|
234
|
+
const saved = snapshot.steps.find((step) => step.key === key);
|
|
235
|
+
identity = data(identity);
|
|
236
|
+
if (saved && (saved.kind !== kind || !equalData(saved.definition, identity)))
|
|
237
|
+
fail("nondeterministic_step", "A recorded step changed kind, input or definition. Restore its workflow version.", saved.id);
|
|
238
|
+
if (!replay && paused)
|
|
239
|
+
throw pause;
|
|
240
|
+
if (!saved) {
|
|
241
|
+
if (replay) {
|
|
242
|
+
if (strictReplay || snapshot.state.status === "completed")
|
|
243
|
+
fail("nondeterministic_workflow", "Replay reached an unrecorded step.");
|
|
244
|
+
frontier = true;
|
|
245
|
+
throw pause;
|
|
246
|
+
}
|
|
247
|
+
if (snapshot.steps.length >= limits.steps)
|
|
248
|
+
throw new Halt({ status: "limited", limit: "steps" });
|
|
249
|
+
// ponytail: bounded whole-root checkpoints. A patch journal is the upgrade for large workflows.
|
|
250
|
+
entry = {
|
|
251
|
+
id: stepId(snapshot.runId, key),
|
|
252
|
+
key,
|
|
253
|
+
kind,
|
|
254
|
+
definition: identity,
|
|
255
|
+
status: "pending",
|
|
256
|
+
attempts: [],
|
|
257
|
+
children: [],
|
|
258
|
+
};
|
|
259
|
+
snapshot.steps.push(entry);
|
|
260
|
+
}
|
|
261
|
+
else
|
|
262
|
+
entry = saved;
|
|
263
|
+
}
|
|
264
|
+
catch (error) {
|
|
265
|
+
stop(error);
|
|
266
|
+
const rejected = Promise.reject(error);
|
|
267
|
+
void rejected.catch(() => { });
|
|
268
|
+
work.push(rejected);
|
|
269
|
+
return rejected;
|
|
270
|
+
}
|
|
271
|
+
// Defer dispatch one microtask: duplicate synchronous admissions fail before any effect.
|
|
272
|
+
const pending = Promise.resolve()
|
|
273
|
+
.then(async () => {
|
|
274
|
+
active();
|
|
275
|
+
if (entry.status === "failed")
|
|
276
|
+
throw new StepFailedError(key, entry.error ?? errorOf("Step failed."));
|
|
277
|
+
if (!replay && entry.kind !== "step" && entry.status !== "completed")
|
|
278
|
+
emit(options, {
|
|
279
|
+
type: "step_start",
|
|
280
|
+
runId: snapshot.runId,
|
|
281
|
+
attemptId: snapshot.attemptId,
|
|
282
|
+
operationId: entry.id,
|
|
283
|
+
key,
|
|
284
|
+
kind: entry.kind,
|
|
285
|
+
attempt: Math.max(1, entry.children.length),
|
|
286
|
+
});
|
|
287
|
+
return execute(entry);
|
|
288
|
+
})
|
|
289
|
+
.catch((error) => {
|
|
290
|
+
if (!replay &&
|
|
291
|
+
entry.status !== "retrying" &&
|
|
292
|
+
(error === pause || (error instanceof Halt && error.state.status === "suspended")))
|
|
293
|
+
entry.status = "waiting";
|
|
294
|
+
// Only callback failures saved as StepFailedError are local. A request, host,
|
|
295
|
+
// progress or journal error must not become recoverable specialist feedback.
|
|
296
|
+
const failure = error === pause || error instanceof Halt || error instanceof StepFailedError
|
|
297
|
+
? error
|
|
298
|
+
: new Halt({
|
|
299
|
+
status: "failed",
|
|
300
|
+
error: {
|
|
301
|
+
code: "workflow_operation_failed",
|
|
302
|
+
message: "A workflow host operation failed. Reconcile stored state before continuing.",
|
|
303
|
+
operationId: entry.id,
|
|
304
|
+
},
|
|
305
|
+
});
|
|
306
|
+
stop(failure);
|
|
307
|
+
throw failure;
|
|
308
|
+
});
|
|
309
|
+
work.push(pending);
|
|
310
|
+
void pending.catch(() => { });
|
|
311
|
+
return pending;
|
|
312
|
+
}
|
|
313
|
+
async function beforeEffect(step, current = request(snapshot, step)) {
|
|
314
|
+
active();
|
|
315
|
+
// Replay already matched cached sibling chains. Their live microtask order is not drift.
|
|
316
|
+
if (recorded.some((saved) => !visited.has(saved.key) && !matched?.has(saved.key)))
|
|
317
|
+
fail("nondeterministic_workflow", "Replay must reach every recorded step before starting more effects.", step.id);
|
|
318
|
+
const requests = journal(snapshot, step, options, scope, signal);
|
|
319
|
+
try {
|
|
320
|
+
await requests.recheck(current);
|
|
321
|
+
}
|
|
322
|
+
catch (error) {
|
|
323
|
+
if (error instanceof Halt)
|
|
324
|
+
throw error;
|
|
325
|
+
fail("step_authorization_failed", "The host could not authorize this workflow step. Check current ownership and lease before continuing.", step.id);
|
|
326
|
+
}
|
|
327
|
+
active();
|
|
328
|
+
await requests.assertFresh();
|
|
329
|
+
}
|
|
330
|
+
async function finish(step, result) {
|
|
331
|
+
step.result = data(result);
|
|
332
|
+
step.status = "completed";
|
|
333
|
+
await scope.tree.save();
|
|
334
|
+
active();
|
|
335
|
+
emit(options, {
|
|
336
|
+
type: "step_result",
|
|
337
|
+
runId: snapshot.runId,
|
|
338
|
+
attemptId: step.attempts.at(-1)?.attemptId ?? snapshot.attemptId,
|
|
339
|
+
operationId: step.id,
|
|
340
|
+
key: step.key,
|
|
341
|
+
kind: step.kind,
|
|
342
|
+
status: "completed",
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
async function failed(step, error) {
|
|
346
|
+
step.error = copyData(error);
|
|
347
|
+
step.status = "failed";
|
|
348
|
+
for (const record of step.asks ?? [])
|
|
349
|
+
if (!record.closed && !record.decision)
|
|
350
|
+
record.closed = "stopped";
|
|
351
|
+
await scope.tree.save();
|
|
352
|
+
emit(options, {
|
|
353
|
+
type: "step_result",
|
|
354
|
+
runId: snapshot.runId,
|
|
355
|
+
attemptId: step.attempts.at(-1)?.attemptId ?? snapshot.attemptId,
|
|
356
|
+
operationId: step.id,
|
|
357
|
+
key: step.key,
|
|
358
|
+
kind: step.kind,
|
|
359
|
+
status: "failed",
|
|
360
|
+
error,
|
|
361
|
+
});
|
|
362
|
+
throw new StepFailedError(step.key, error);
|
|
363
|
+
}
|
|
364
|
+
async function wait(step) {
|
|
365
|
+
active();
|
|
366
|
+
const at = step.wakeAt;
|
|
367
|
+
if (at === undefined)
|
|
368
|
+
throw new TypeError("Missing saved wake time.");
|
|
369
|
+
if (at >= snapshot.tree.startedAt + snapshot.tree.limits.elapsedMs)
|
|
370
|
+
throw new Halt({ status: "limited", limit: "treeElapsedMs" });
|
|
371
|
+
const remaining = at - Date.now();
|
|
372
|
+
if (remaining > 0) {
|
|
373
|
+
if (replay || remaining > limits.inlineWaitMs)
|
|
374
|
+
throw pause;
|
|
375
|
+
await sleep(remaining, signal);
|
|
376
|
+
}
|
|
377
|
+
active();
|
|
378
|
+
}
|
|
379
|
+
async function repeat(step, attempt, policy) {
|
|
380
|
+
if (step.asks?.length ||
|
|
381
|
+
step.attempts.filter((item) => item.status !== "not_run").length >= policy.maxAttempts)
|
|
382
|
+
fail("step_retry_unsafe", "This step cannot repeat an answered or exhausted attempt. Reconcile it with the host.", step.id);
|
|
383
|
+
await beforeEffect(step);
|
|
384
|
+
if (policy.replay === "reconcile" && !attempt.reconciliation) {
|
|
385
|
+
const verdict = await untilAbort(Promise.resolve(options.host?.reconcileStep?.(immutableCopy(request(snapshot, step)), immutableCopy(attempt), signal)), signal);
|
|
386
|
+
active();
|
|
387
|
+
if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
|
|
388
|
+
fail("step_retry_unsafe", "The host could not prove this attempt did not run and cannot still complete. Reconcile its result.", step.id);
|
|
389
|
+
attempt.reconciliation = verdict.receipt;
|
|
390
|
+
}
|
|
391
|
+
if (attempt.status === "running")
|
|
392
|
+
attempt.status = "interrupted";
|
|
393
|
+
step.status = "retrying";
|
|
394
|
+
step.wakeAt ??=
|
|
395
|
+
Date.now() +
|
|
396
|
+
backoffMs(step.attempts.length - 1, policy.baseDelayMs ?? 1_000, policy.maxDelayMs ?? 30_000);
|
|
397
|
+
await scope.tree.save();
|
|
398
|
+
await wait(step);
|
|
399
|
+
}
|
|
400
|
+
function step(key, fn, opts = {}) {
|
|
401
|
+
opts = { ...opts, input: copyData(opts.input), retry: opts.retry && { ...opts.retry } };
|
|
402
|
+
const policy = stepPolicy(opts);
|
|
403
|
+
const validate = (value) => {
|
|
404
|
+
try {
|
|
405
|
+
return opts.validate ? opts.validate(copyData(value)) : copyData(value);
|
|
406
|
+
}
|
|
407
|
+
catch {
|
|
408
|
+
fail("invalid_step_result", "A saved step result no longer passes its validator. Restore its original contract.", stepId(snapshot.runId, key));
|
|
409
|
+
}
|
|
410
|
+
};
|
|
411
|
+
return admit(key, "step", policy, async (entry) => {
|
|
412
|
+
if (entry.status === "completed")
|
|
413
|
+
return validate(entry.result);
|
|
414
|
+
if (replay)
|
|
415
|
+
throw pause;
|
|
416
|
+
const release = await gate.acquire(signal);
|
|
417
|
+
try {
|
|
418
|
+
let effective = copyData(opts.input);
|
|
419
|
+
const requests = journal(snapshot, entry, options, scope, signal);
|
|
420
|
+
if (opts.needsApproval) {
|
|
421
|
+
entry.status = "waiting";
|
|
422
|
+
const record = await requests.ensure({ type: "approval" });
|
|
423
|
+
if (!record.decision)
|
|
424
|
+
throw pause;
|
|
425
|
+
const decision = record.decision;
|
|
426
|
+
if (decision.type === "stop") {
|
|
427
|
+
scope.tree.stop();
|
|
428
|
+
throw new Halt({ status: "cancelled" });
|
|
429
|
+
}
|
|
430
|
+
if (decision.type === "deny" || decision.type === "cancel")
|
|
431
|
+
return failed(entry, {
|
|
432
|
+
reason: decision.type === "deny" ? "denied" : "cancelled",
|
|
433
|
+
name: "Decision",
|
|
434
|
+
message: decision.type === "deny"
|
|
435
|
+
? (decision.message ?? "This step was denied.")
|
|
436
|
+
: "This step was cancelled.",
|
|
437
|
+
});
|
|
438
|
+
if (decision.type !== "approve")
|
|
439
|
+
throw new TypeError("This step needs an approval.");
|
|
440
|
+
if (decision.arguments !== undefined) {
|
|
441
|
+
if (!opts.validateInput)
|
|
442
|
+
fail("invalid_step_input", "Supply validateInput before allowing edited step input.", entry.id);
|
|
443
|
+
effective = opts.validateInput(copyData(decision.arguments));
|
|
444
|
+
}
|
|
445
|
+
}
|
|
446
|
+
for (;;) {
|
|
447
|
+
active();
|
|
448
|
+
if (entry.attempts.length >= 100)
|
|
449
|
+
throw new Halt({ status: "limited", limit: "steps" });
|
|
450
|
+
const previous = entry.attempts.at(-1);
|
|
451
|
+
if (previous && (previous.status === "running" || entry.status === "retrying")) {
|
|
452
|
+
if (!opts.retry)
|
|
453
|
+
fail("interrupted_operation", "This step has an unknown outcome. Reconcile it before starting different work.", entry.id);
|
|
454
|
+
await repeat(entry, previous, opts.retry);
|
|
455
|
+
}
|
|
456
|
+
await beforeEffect(entry, { ...request(snapshot, entry), input: effective });
|
|
457
|
+
entry.status = "running";
|
|
458
|
+
delete entry.wakeAt;
|
|
459
|
+
const attempt = {
|
|
460
|
+
attemptId: `${snapshot.attemptId}/step-attempt/${entry.attempts.length + 1}`,
|
|
461
|
+
status: "running",
|
|
462
|
+
};
|
|
463
|
+
entry.attempts.push(attempt);
|
|
464
|
+
await scope.tree.save();
|
|
465
|
+
active();
|
|
466
|
+
// Progress observers cannot waive the last ownership or expiry check.
|
|
467
|
+
emit(options, {
|
|
468
|
+
type: "step_start",
|
|
469
|
+
runId: snapshot.runId,
|
|
470
|
+
attemptId: attempt.attemptId,
|
|
471
|
+
operationId: entry.id,
|
|
472
|
+
key,
|
|
473
|
+
kind: "step",
|
|
474
|
+
attempt: entry.attempts.length,
|
|
475
|
+
});
|
|
476
|
+
// A slow checkpoint can outlive the owner's lease or the approval's expiry.
|
|
477
|
+
try {
|
|
478
|
+
await requests.recheck({ ...request(snapshot, entry), input: effective });
|
|
479
|
+
await requests.assertFresh();
|
|
480
|
+
active();
|
|
481
|
+
}
|
|
482
|
+
catch (error) {
|
|
483
|
+
attempt.status = "not_run";
|
|
484
|
+
entry.status = "waiting";
|
|
485
|
+
if (error instanceof Halt)
|
|
486
|
+
throw error;
|
|
487
|
+
fail("step_authorization_failed", "The host refused current access before dispatch. Reconcile ownership before continuing.", entry.id);
|
|
488
|
+
}
|
|
489
|
+
const timeout = new AbortController();
|
|
490
|
+
const attemptSignal = AbortSignal.any([signal, timeout.signal]);
|
|
491
|
+
const timer = setTimeout(() => timeout.abort(new Error("The workflow step timed out.")), opts.timeoutMs ?? 60_000);
|
|
492
|
+
let value;
|
|
493
|
+
let thrown;
|
|
494
|
+
try {
|
|
495
|
+
value = await untilAbort(Promise.resolve(fn(Object.freeze({
|
|
496
|
+
key,
|
|
497
|
+
attempt: entry.attempts.length,
|
|
498
|
+
idempotencyKey: entry.id,
|
|
499
|
+
input: immutableCopy(effective),
|
|
500
|
+
context: hostContext,
|
|
501
|
+
signal: attemptSignal,
|
|
502
|
+
report(value) {
|
|
503
|
+
active();
|
|
504
|
+
attemptSignal.throwIfAborted();
|
|
505
|
+
if (attempt.status !== "running")
|
|
506
|
+
throw new Error("The step already settled.");
|
|
507
|
+
emit(options, {
|
|
508
|
+
type: "step_progress",
|
|
509
|
+
runId: snapshot.runId,
|
|
510
|
+
attemptId: attempt.attemptId,
|
|
511
|
+
operationId: entry.id,
|
|
512
|
+
key,
|
|
513
|
+
data: data(value),
|
|
514
|
+
});
|
|
515
|
+
},
|
|
516
|
+
}))), attemptSignal);
|
|
517
|
+
}
|
|
518
|
+
catch (error) {
|
|
519
|
+
thrown = { error };
|
|
520
|
+
}
|
|
521
|
+
finally {
|
|
522
|
+
clearTimeout(timer);
|
|
523
|
+
}
|
|
524
|
+
active();
|
|
525
|
+
let invalidResult = false;
|
|
526
|
+
if (!thrown) {
|
|
527
|
+
try {
|
|
528
|
+
value = data(value);
|
|
529
|
+
opts.validate?.(copyData(value));
|
|
530
|
+
}
|
|
531
|
+
catch (error) {
|
|
532
|
+
invalidResult = true;
|
|
533
|
+
thrown = { error };
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
if (!thrown) {
|
|
537
|
+
attempt.status = "completed";
|
|
538
|
+
await finish(entry, value);
|
|
539
|
+
return validate(entry.result);
|
|
540
|
+
}
|
|
541
|
+
if (thrown.error instanceof Halt)
|
|
542
|
+
throw thrown.error;
|
|
543
|
+
const error = errorOf(thrown.error, timeout.signal.aborted ? "timeout" : "failed");
|
|
544
|
+
attempt.status = "failed";
|
|
545
|
+
attempt.error = error;
|
|
546
|
+
entry.error = error;
|
|
547
|
+
if (!invalidResult &&
|
|
548
|
+
opts.retry &&
|
|
549
|
+
entry.attempts.filter((item) => item.status !== "not_run").length <
|
|
550
|
+
opts.retry.maxAttempts &&
|
|
551
|
+
!entry.asks?.length &&
|
|
552
|
+
(opts.retry.retryOn
|
|
553
|
+
? opts.retry.retryOn(immutableCopy(error), entry.attempts.length)
|
|
554
|
+
: retryable(thrown.error))) {
|
|
555
|
+
entry.status = "retrying";
|
|
556
|
+
entry.wakeAt =
|
|
557
|
+
Date.now() +
|
|
558
|
+
backoffMs(entry.attempts.length - 1, opts.retry.baseDelayMs ?? 1_000, opts.retry.maxDelayMs ?? 30_000);
|
|
559
|
+
await scope.tree.save();
|
|
560
|
+
emit(options, {
|
|
561
|
+
type: "step_result",
|
|
562
|
+
runId: snapshot.runId,
|
|
563
|
+
attemptId: attempt.attemptId,
|
|
564
|
+
operationId: entry.id,
|
|
565
|
+
key,
|
|
566
|
+
kind: "step",
|
|
567
|
+
status: "retrying",
|
|
568
|
+
error,
|
|
569
|
+
});
|
|
570
|
+
continue;
|
|
571
|
+
}
|
|
572
|
+
return failed(entry, error);
|
|
573
|
+
}
|
|
574
|
+
}
|
|
575
|
+
finally {
|
|
576
|
+
release();
|
|
577
|
+
}
|
|
578
|
+
});
|
|
579
|
+
}
|
|
580
|
+
function ask(question, validate) {
|
|
581
|
+
const ask = { ...question, type: "question" };
|
|
582
|
+
if (!isAsk(ask))
|
|
583
|
+
throw new TypeError("Provide a valid question with a stable key.");
|
|
584
|
+
return admit(question.key, "ask", { question: ask }, async (entry) => {
|
|
585
|
+
if (entry.status === "completed") {
|
|
586
|
+
try {
|
|
587
|
+
return validate(copyData(entry.result));
|
|
588
|
+
}
|
|
589
|
+
catch {
|
|
590
|
+
fail("invalid_step_result", "A recorded answer no longer passes validation.", entry.id);
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
const requests = journal(snapshot, entry, options, scope, signal);
|
|
594
|
+
const record = replay
|
|
595
|
+
? requests.latest(ask)
|
|
596
|
+
: await (async () => {
|
|
597
|
+
entry.status = "waiting";
|
|
598
|
+
return requests.ensure(ask);
|
|
599
|
+
})();
|
|
600
|
+
if (!record?.decision)
|
|
601
|
+
throw pause;
|
|
602
|
+
const decision = record.decision;
|
|
603
|
+
if (decision.type === "stop") {
|
|
604
|
+
if (!replay)
|
|
605
|
+
scope.tree.stop();
|
|
606
|
+
throw new Halt({ status: "cancelled" });
|
|
607
|
+
}
|
|
608
|
+
if (decision.type === "cancel") {
|
|
609
|
+
const error = {
|
|
610
|
+
reason: "cancelled",
|
|
611
|
+
name: "Decision",
|
|
612
|
+
message: "This question was cancelled.",
|
|
613
|
+
};
|
|
614
|
+
if (replay)
|
|
615
|
+
throw new StepFailedError(entry.key, error);
|
|
616
|
+
return failed(entry, error);
|
|
617
|
+
}
|
|
618
|
+
if (decision.type !== "answer")
|
|
619
|
+
throw new TypeError("This question needs an answer.");
|
|
620
|
+
if (!replay)
|
|
621
|
+
await beforeEffect(entry);
|
|
622
|
+
let value;
|
|
623
|
+
try {
|
|
624
|
+
value = validate(copyData(decision.answer));
|
|
625
|
+
}
|
|
626
|
+
catch (error) {
|
|
627
|
+
if (!replay) {
|
|
628
|
+
record.closed = "invalid";
|
|
629
|
+
await requests.open(ask, { code: "invalid_answer", message: messageOf(error) });
|
|
630
|
+
}
|
|
631
|
+
throw pause;
|
|
632
|
+
}
|
|
633
|
+
if (!replay)
|
|
634
|
+
await finish(entry, decision.answer);
|
|
635
|
+
return value;
|
|
636
|
+
});
|
|
637
|
+
}
|
|
638
|
+
function child(key, node, value, childPolicy = {}) {
|
|
639
|
+
const runtime = runtimeOf(node);
|
|
640
|
+
if (!specialists.includes(node))
|
|
641
|
+
fail("unregistered_specialist", "Register this child in the workflow definition.");
|
|
642
|
+
const retry = childPolicy.retry && { ...childPolicy.retry };
|
|
643
|
+
if (retry &&
|
|
644
|
+
(!Number.isSafeInteger(retry.maxAttempts) ||
|
|
645
|
+
retry.maxAttempts < 1 ||
|
|
646
|
+
retry.maxAttempts > 100 ||
|
|
647
|
+
!["read-only", "reconcile"].includes(retry.replay)))
|
|
648
|
+
throw new TypeError("Child retries need bounded attempts and an explicit repeatability policy.");
|
|
649
|
+
if (retry && node.kind === "remote")
|
|
650
|
+
throw new TypeError("Remote messages cannot be replayed by child retries. Resume the saved task.");
|
|
651
|
+
const prepared = prepareChild(node, value, undefined, scope.tree.root);
|
|
652
|
+
const normalized = prepared.input;
|
|
653
|
+
return admit(key, node.kind, {
|
|
654
|
+
targetId: node.id,
|
|
655
|
+
version: node.version,
|
|
656
|
+
input: normalized,
|
|
657
|
+
configuration: node[AGENT_RUNTIME].configuration(),
|
|
658
|
+
retry: retry
|
|
659
|
+
? { maxAttempts: retry.maxAttempts, replay: retry.replay, retryOn: !!retry.retryOn }
|
|
660
|
+
: null,
|
|
661
|
+
}, async (entry) => {
|
|
662
|
+
let saved = entry.children.at(-1);
|
|
663
|
+
if (replay) {
|
|
664
|
+
if (!saved || entry.status !== "completed")
|
|
665
|
+
throw pause;
|
|
666
|
+
return runtime.hydrate(saved.snapshot);
|
|
667
|
+
}
|
|
668
|
+
while (entry.status !== "completed") {
|
|
669
|
+
await beforeEffect(entry);
|
|
670
|
+
const resume = !!saved;
|
|
671
|
+
if (!saved) {
|
|
672
|
+
scope.tree.reserveChild(scope.depth + 1);
|
|
673
|
+
const childKey = String(entry.children.length + 1);
|
|
674
|
+
const runId = childRunId(entry.id, childKey);
|
|
675
|
+
const created = await prepared.create(runId, snapshot.tree, childOptions(options));
|
|
676
|
+
active();
|
|
677
|
+
saved = admitChild(entry.children, { key: childKey, snapshot: created }, scope);
|
|
678
|
+
}
|
|
679
|
+
entry.status = "running";
|
|
680
|
+
try {
|
|
681
|
+
await startChild(saved, snapshot, entry.id, {
|
|
682
|
+
...runtime,
|
|
683
|
+
async execute(childSnapshot, inherited, childScope, answers) {
|
|
684
|
+
// startChild saved admission and notified observers. Check current authority now.
|
|
685
|
+
await beforeEffect(entry);
|
|
686
|
+
return runtime.execute(childSnapshot, inherited, childScope, answers);
|
|
687
|
+
},
|
|
688
|
+
}, childOptions(options), scope, signal, active, resume);
|
|
689
|
+
}
|
|
690
|
+
catch (error) {
|
|
691
|
+
if (error instanceof Halt)
|
|
692
|
+
throw error;
|
|
693
|
+
active();
|
|
694
|
+
fail("child_host_failed", "The child host failed or changed its journal. Reconcile stored state before continuing.", entry.id);
|
|
695
|
+
}
|
|
696
|
+
const state = saved.snapshot.state;
|
|
697
|
+
if (state.status === "suspended") {
|
|
698
|
+
entry.status = "waiting";
|
|
699
|
+
await scope.tree.save();
|
|
700
|
+
throw pause;
|
|
701
|
+
}
|
|
702
|
+
if (state.status === "cancelled") {
|
|
703
|
+
scope.tree.stop();
|
|
704
|
+
throw new Halt(state);
|
|
705
|
+
}
|
|
706
|
+
if ((state.status === "limited" || state.status === "failed") && !isLocalStop(state))
|
|
707
|
+
throw new Halt(state);
|
|
708
|
+
const result = runtime.hydrate(saved.snapshot);
|
|
709
|
+
if (state.status === "failed" &&
|
|
710
|
+
state.error.code !== "content_filtered" &&
|
|
711
|
+
retry &&
|
|
712
|
+
entry.children.length < retry.maxAttempts &&
|
|
713
|
+
result.snapshot.kind !== "remote" &&
|
|
714
|
+
(retry.retryOn?.(result) ?? true)) {
|
|
715
|
+
if ([...requestRecords(saved.snapshot)].length ||
|
|
716
|
+
[...snapshots(saved.snapshot)].some((node) => node.kind === "remote" ||
|
|
717
|
+
(node.kind === "agent" && node.definition.modelSettings.hostedTools?.length)))
|
|
718
|
+
fail("step_retry_unsafe", "A child with requests or hosted effects cannot restart under workflow retry policy.", entry.id);
|
|
719
|
+
if (retry.replay === "reconcile" && !entry.reconciliations?.[saved.snapshot.runId]) {
|
|
720
|
+
const verdict = await untilAbort(Promise.resolve(options.host?.reconcileStep?.(immutableCopy(request(snapshot, entry)), { attemptId: saved.snapshot.attemptId }, signal)), signal);
|
|
721
|
+
active();
|
|
722
|
+
if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
|
|
723
|
+
fail("step_retry_unsafe", "The host must reconcile every child effect before restarting it.", entry.id);
|
|
724
|
+
(entry.reconciliations ??= {})[saved.snapshot.runId] = verdict.receipt;
|
|
725
|
+
}
|
|
726
|
+
entry.status = "retrying";
|
|
727
|
+
await scope.tree.save();
|
|
728
|
+
saved = undefined;
|
|
729
|
+
continue;
|
|
730
|
+
}
|
|
731
|
+
await finish(entry, { childRunId: saved.snapshot.runId });
|
|
732
|
+
}
|
|
733
|
+
if (!saved)
|
|
734
|
+
throw new TypeError("Missing completed child.");
|
|
735
|
+
return runtime.hydrate(saved.snapshot);
|
|
736
|
+
});
|
|
737
|
+
}
|
|
738
|
+
const ctx = Object.freeze({
|
|
739
|
+
runId: snapshot.runId,
|
|
740
|
+
context: hostContext,
|
|
741
|
+
step,
|
|
742
|
+
ask,
|
|
743
|
+
agent: child,
|
|
744
|
+
workflow: child,
|
|
745
|
+
sleep(key, ms) {
|
|
746
|
+
if (!Number.isSafeInteger(ms) || ms < 0 || ms > 2_147_483_647)
|
|
747
|
+
throw new TypeError("Sleep needs a nonnegative whole number that fits a timer.");
|
|
748
|
+
return admit(key, "sleep", { ms }, async (entry) => {
|
|
749
|
+
if (entry.status === "completed")
|
|
750
|
+
return;
|
|
751
|
+
if (replay)
|
|
752
|
+
throw pause;
|
|
753
|
+
if (entry.wakeAt === undefined) {
|
|
754
|
+
entry.wakeAt = Date.now() + ms;
|
|
755
|
+
entry.status = "waiting";
|
|
756
|
+
await scope.tree.save();
|
|
757
|
+
}
|
|
758
|
+
await wait(entry);
|
|
759
|
+
await finish(entry, null);
|
|
760
|
+
});
|
|
761
|
+
},
|
|
762
|
+
});
|
|
763
|
+
let candidate;
|
|
764
|
+
let failure;
|
|
765
|
+
try {
|
|
766
|
+
candidate = await untilAbort(run(input.validate(immutableCopy(snapshot.input)), ctx), signal);
|
|
767
|
+
}
|
|
768
|
+
catch (error) {
|
|
769
|
+
failure = { error };
|
|
770
|
+
if (error instanceof Halt)
|
|
771
|
+
stop(error);
|
|
772
|
+
}
|
|
773
|
+
finally {
|
|
774
|
+
accepting = false;
|
|
775
|
+
// A rejected Promise.all or an ignored call must not orphan a sibling effect.
|
|
776
|
+
await Promise.allSettled(work);
|
|
777
|
+
}
|
|
778
|
+
active();
|
|
779
|
+
if (fatal)
|
|
780
|
+
throw fatal;
|
|
781
|
+
if (frontier && recorded.some((entry) => !visited.has(entry.key)))
|
|
782
|
+
fail("nondeterministic_workflow", "Replay reached new work without reaching every recorded step.");
|
|
783
|
+
if (paused)
|
|
784
|
+
return { visited, paused: true };
|
|
785
|
+
if (failure)
|
|
786
|
+
throw failure.error;
|
|
787
|
+
if (recorded.some((entry) => !visited.has(entry.key)))
|
|
788
|
+
fail("nondeterministic_workflow", "The workflow returned without reaching every recorded step.");
|
|
789
|
+
candidate = data(candidate);
|
|
790
|
+
validateOutput(candidate);
|
|
791
|
+
if (replay &&
|
|
792
|
+
snapshot.state.status === "completed" &&
|
|
793
|
+
!equalData(snapshot.state.candidate, candidate))
|
|
794
|
+
fail("nondeterministic_workflow", "Replay returned a different result for the same journal.");
|
|
795
|
+
return { candidate, visited, paused: false };
|
|
796
|
+
}
|
|
797
|
+
function hydrate(node) {
|
|
798
|
+
const snapshot = workflowNode(copyData(node));
|
|
799
|
+
const state = snapshot.state;
|
|
800
|
+
if (state.status === "running")
|
|
801
|
+
throw new TypeError("The workflow has not settled.");
|
|
802
|
+
const record = {
|
|
803
|
+
runId: snapshot.runId,
|
|
804
|
+
attemptId: snapshot.attemptId,
|
|
805
|
+
treeUsage: treeUsage(snapshot),
|
|
806
|
+
steps: snapshot.steps.map(({ id, key, kind, status, attempts }) => ({
|
|
807
|
+
id,
|
|
808
|
+
key,
|
|
809
|
+
kind,
|
|
810
|
+
status,
|
|
811
|
+
attempts,
|
|
812
|
+
})),
|
|
813
|
+
snapshot,
|
|
814
|
+
};
|
|
815
|
+
return state.status === "completed"
|
|
816
|
+
? { ...record, status: "completed", output: validateOutput(state.candidate) }
|
|
817
|
+
: state.status === "suspended"
|
|
818
|
+
? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
|
|
819
|
+
: { ...record, ...state };
|
|
820
|
+
}
|
|
821
|
+
async function execute(node, options, scope, answers) {
|
|
822
|
+
const snapshot = workflowNode(node);
|
|
823
|
+
if (!["running", "suspended"].includes(snapshot.state.status))
|
|
824
|
+
return hydrate(snapshot);
|
|
825
|
+
const signal = AbortSignal.any([
|
|
826
|
+
scope.tree.signal,
|
|
827
|
+
...(options.signal ? [options.signal] : []),
|
|
828
|
+
]);
|
|
829
|
+
try {
|
|
830
|
+
emitEvent(options, {
|
|
831
|
+
type: "execution_start",
|
|
832
|
+
kind: "workflow",
|
|
833
|
+
nodeId: id,
|
|
834
|
+
version,
|
|
835
|
+
runId: snapshot.runId,
|
|
836
|
+
attemptId: snapshot.attemptId,
|
|
837
|
+
});
|
|
838
|
+
scope.tree.active();
|
|
839
|
+
checkMemoryBinding(snapshot, options.memory);
|
|
840
|
+
// Refuse unknown writes before any coordination callback or sibling effect.
|
|
841
|
+
for (const step of snapshot.steps)
|
|
842
|
+
if (step.kind === "step" &&
|
|
843
|
+
step.status === "running" &&
|
|
844
|
+
(!isRecord(step.definition.retry) || step.asks?.length))
|
|
845
|
+
fail("interrupted_operation", "A workflow effect has no saved result. Reconcile its outcome with the host.", step.id);
|
|
846
|
+
await coordinate(snapshot, {}, scope, true);
|
|
847
|
+
if (scope.depth === 0 && answers) {
|
|
848
|
+
try {
|
|
849
|
+
await answerRequests(snapshot, options, scope, answers, signal);
|
|
850
|
+
}
|
|
851
|
+
catch (error) {
|
|
852
|
+
if (error instanceof Halt)
|
|
853
|
+
throw error;
|
|
854
|
+
fail("request_failed", "The host could not authenticate the workflow answers. Check access before continuing.");
|
|
855
|
+
}
|
|
856
|
+
}
|
|
857
|
+
const preflight = await coordinate(snapshot, {}, scope, true);
|
|
858
|
+
snapshot.state = { status: "running" };
|
|
859
|
+
await scope.tree.save();
|
|
860
|
+
const result = await coordinate(snapshot, options, scope, false, false, preflight.visited);
|
|
861
|
+
snapshot.state = result.paused
|
|
862
|
+
? { status: "suspended" }
|
|
863
|
+
: { status: "completed", candidate: result.candidate };
|
|
864
|
+
}
|
|
865
|
+
catch (error) {
|
|
866
|
+
let failure = error;
|
|
867
|
+
try {
|
|
868
|
+
scope.tree.active();
|
|
869
|
+
signal.throwIfAborted();
|
|
870
|
+
}
|
|
871
|
+
catch (stopped) {
|
|
872
|
+
failure = stopped instanceof Halt ? stopped : new Halt({ status: "cancelled" });
|
|
873
|
+
}
|
|
874
|
+
snapshot.state =
|
|
875
|
+
failure instanceof Halt
|
|
876
|
+
? failure.state
|
|
877
|
+
: {
|
|
878
|
+
status: "failed",
|
|
879
|
+
error: {
|
|
880
|
+
code: failure instanceof StepFailedError ? "step_failed" : "workflow_failed",
|
|
881
|
+
message: messageOf(failure),
|
|
882
|
+
},
|
|
883
|
+
};
|
|
884
|
+
}
|
|
885
|
+
try {
|
|
886
|
+
await scope.tree.save();
|
|
887
|
+
}
|
|
888
|
+
catch (error) {
|
|
889
|
+
snapshot.state =
|
|
890
|
+
error instanceof Halt
|
|
891
|
+
? error.state
|
|
892
|
+
: { status: "failed", error: { code: "checkpoint_failed", message: messageOf(error) } };
|
|
893
|
+
}
|
|
894
|
+
emitEvent(options, {
|
|
895
|
+
type: "state",
|
|
896
|
+
runId: snapshot.runId,
|
|
897
|
+
attemptId: snapshot.attemptId,
|
|
898
|
+
state: snapshot.state,
|
|
899
|
+
});
|
|
900
|
+
await options.host?.progress?.flush();
|
|
901
|
+
return hydrate(snapshot);
|
|
902
|
+
}
|
|
903
|
+
async function create(value, runId, tree, options = {}) {
|
|
904
|
+
const frozen = data(value);
|
|
905
|
+
input.validate(immutableCopy(frozen));
|
|
906
|
+
const startedAt = Date.now();
|
|
907
|
+
return {
|
|
908
|
+
kind: "workflow",
|
|
909
|
+
format: 3,
|
|
910
|
+
workflowId: id,
|
|
911
|
+
version,
|
|
912
|
+
runId,
|
|
913
|
+
attemptId: crypto.randomUUID(),
|
|
914
|
+
startedAt,
|
|
915
|
+
input: frozen,
|
|
916
|
+
definition: copyData(definition),
|
|
917
|
+
limits: copyData(limits),
|
|
918
|
+
steps: [],
|
|
919
|
+
state: { status: "running" },
|
|
920
|
+
tree: tree
|
|
921
|
+
? copyData(tree)
|
|
922
|
+
: {
|
|
923
|
+
runId,
|
|
924
|
+
startedAt,
|
|
925
|
+
limits: copyData(treeLimits),
|
|
926
|
+
...(options.memory ? { memory: memoryScopes(options.memory) } : {}),
|
|
927
|
+
},
|
|
928
|
+
};
|
|
929
|
+
}
|
|
930
|
+
const runtime = {
|
|
931
|
+
create,
|
|
932
|
+
execute,
|
|
933
|
+
hydrate,
|
|
934
|
+
answerRequests,
|
|
935
|
+
configuration: () => copyData({ id, version, limits, ...definition }),
|
|
936
|
+
async open(value, options, runId) {
|
|
937
|
+
checkWorkflowOptions(options);
|
|
938
|
+
return create(value, runId, undefined, options);
|
|
939
|
+
},
|
|
940
|
+
restore(raw, tree) {
|
|
941
|
+
const snapshot = readWorkflowSnapshot(raw);
|
|
942
|
+
if (snapshot.workflowId !== id ||
|
|
943
|
+
snapshot.version !== version ||
|
|
944
|
+
!equalData(snapshot.definition, definition) ||
|
|
945
|
+
!equalData(snapshot.limits, limits))
|
|
946
|
+
throw new TypeError("The workflow definition, version or limits changed. Restore the original version.");
|
|
947
|
+
if (tree
|
|
948
|
+
? !equalData(snapshot.tree, tree)
|
|
949
|
+
: snapshot.tree.runId !== snapshot.runId || !equalData(snapshot.tree.limits, treeLimits))
|
|
950
|
+
throw new TypeError("The workflow belongs to another tree.");
|
|
951
|
+
input.validate(immutableCopy(snapshot.input));
|
|
952
|
+
for (const step of snapshot.steps)
|
|
953
|
+
for (const child of step.children) {
|
|
954
|
+
const specialist = target(step);
|
|
955
|
+
if (child.snapshot.kind !== specialist.kind || nodeId(child.snapshot) !== specialist.id)
|
|
956
|
+
throw new TypeError("The saved child identity changed.");
|
|
957
|
+
child.snapshot = runtimeOf(specialist).restore(child.snapshot, snapshot.tree);
|
|
958
|
+
const recordedInput = child.snapshot.kind === "agent"
|
|
959
|
+
? { history: child.snapshot.history, input: child.snapshot.input }
|
|
960
|
+
: child.snapshot.input;
|
|
961
|
+
if (!equalData(recordedInput, step.definition.input) ||
|
|
962
|
+
!equalData(step.definition.configuration, specialist[AGENT_RUNTIME].configuration()))
|
|
963
|
+
throw new TypeError("The workflow child input or configuration changed.");
|
|
964
|
+
}
|
|
965
|
+
if (snapshot.state.status === "completed")
|
|
966
|
+
validateOutput(snapshot.state.candidate);
|
|
967
|
+
return snapshot;
|
|
968
|
+
},
|
|
969
|
+
async replay(snapshot) {
|
|
970
|
+
const tree = new ExecutionTree(snapshot, {});
|
|
971
|
+
try {
|
|
972
|
+
await coordinate(snapshot, {}, { tree, depth: 0, path: [] }, true, true);
|
|
973
|
+
}
|
|
974
|
+
finally {
|
|
975
|
+
tree.close();
|
|
976
|
+
}
|
|
977
|
+
},
|
|
978
|
+
};
|
|
979
|
+
async function root(snapshot, options, answers) {
|
|
980
|
+
const tree = new ExecutionTree(snapshot, options);
|
|
981
|
+
try {
|
|
982
|
+
return await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
|
|
983
|
+
}
|
|
984
|
+
finally {
|
|
985
|
+
tree.close();
|
|
986
|
+
}
|
|
987
|
+
}
|
|
988
|
+
const workflow = Object.freeze({
|
|
989
|
+
kind: "workflow",
|
|
990
|
+
id,
|
|
991
|
+
version,
|
|
992
|
+
[AGENT_RUNTIME]: runtime,
|
|
993
|
+
async run(value, options = {}) {
|
|
994
|
+
checkWorkflowOptions(options);
|
|
995
|
+
const prepared = { ...options, memory: readMemoryBinding(options.memory) };
|
|
996
|
+
return root(await runtime.open(value, prepared, options.runId ?? crypto.randomUUID()), prepared);
|
|
997
|
+
},
|
|
998
|
+
async resume(raw, options) {
|
|
999
|
+
checkWorkflowOptions(options, true);
|
|
1000
|
+
const snapshot = runtime.restore(raw);
|
|
1001
|
+
const prepared = { ...options, memory: readMemoryBinding(options.memory) };
|
|
1002
|
+
checkMemoryBinding(snapshot, prepared.memory);
|
|
1003
|
+
const answers = readAnswers(snapshot, options.answers ?? {});
|
|
1004
|
+
await authorizeTree(snapshot, options.host);
|
|
1005
|
+
snapshot.attemptId = crypto.randomUUID();
|
|
1006
|
+
return root(snapshot, prepared, answers);
|
|
1007
|
+
},
|
|
1008
|
+
asTool(options) {
|
|
1009
|
+
return specialistFailures(defineDelegation({
|
|
1010
|
+
...options,
|
|
1011
|
+
inputSchema: input.schema,
|
|
1012
|
+
validate: input.validate,
|
|
1013
|
+
specialists: [workflow],
|
|
1014
|
+
async run(value, ctx) {
|
|
1015
|
+
const result = await ctx.child("result", workflow, value).join();
|
|
1016
|
+
if (result.status !== "completed") {
|
|
1017
|
+
const state = result.snapshot.state;
|
|
1018
|
+
if (state.status === "running" || state.status === "completed")
|
|
1019
|
+
throw new TypeError("Invalid workflow outcome.");
|
|
1020
|
+
throw new Halt(state);
|
|
1021
|
+
}
|
|
1022
|
+
return result.output;
|
|
1023
|
+
},
|
|
1024
|
+
}));
|
|
1025
|
+
},
|
|
1026
|
+
});
|
|
1027
|
+
return workflow;
|
|
1028
|
+
}
|
|
1029
|
+
function checkWorkflowOptions(options, resume = false) {
|
|
1030
|
+
checkOptions(options, resume ? "resume" : "run");
|
|
1031
|
+
if (options.session ||
|
|
1032
|
+
options.historyLimit !== undefined ||
|
|
1033
|
+
options.prepareHistory ||
|
|
1034
|
+
options.modelSettings ||
|
|
1035
|
+
options.enabledTools)
|
|
1036
|
+
throw new TypeError("Workflows use typed input, not sessions, model settings or tool selection. Configure those on their agents.");
|
|
1037
|
+
}
|
|
1038
|
+
export async function checkReplay(workflow, raw) {
|
|
1039
|
+
try {
|
|
1040
|
+
const runtime = workflow[AGENT_RUNTIME];
|
|
1041
|
+
await runtime.replay(runtime.restore(raw));
|
|
1042
|
+
return { ok: true };
|
|
1043
|
+
}
|
|
1044
|
+
catch (error) {
|
|
1045
|
+
return {
|
|
1046
|
+
ok: false,
|
|
1047
|
+
error: error instanceof Halt && error.state.status === "failed"
|
|
1048
|
+
? error.state.error
|
|
1049
|
+
: { code: "invalid_replay", message: messageOf(error) },
|
|
1050
|
+
};
|
|
1051
|
+
}
|
|
1052
|
+
}
|
|
1053
|
+
//# sourceMappingURL=workflow.js.map
|