@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
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
import { isAsk } from "./request.ts";
|
|
2
|
+
import {
|
|
3
|
+
copyData,
|
|
4
|
+
equalData,
|
|
5
|
+
isId,
|
|
6
|
+
isRecord,
|
|
7
|
+
isAskRecord,
|
|
8
|
+
isState,
|
|
9
|
+
isTreeInfo,
|
|
10
|
+
isTreeNode,
|
|
11
|
+
childRunId,
|
|
12
|
+
checkChildProgress,
|
|
13
|
+
} from "./snapshot.ts";
|
|
14
|
+
import type {
|
|
15
|
+
WorkflowLimits,
|
|
16
|
+
WorkflowSnapshot,
|
|
17
|
+
StepExecution,
|
|
18
|
+
StepAttempt,
|
|
19
|
+
StepError,
|
|
20
|
+
} from "./workflow-types.ts";
|
|
21
|
+
|
|
22
|
+
export function readWorkflowLimits(value: Partial<WorkflowLimits> = {}): WorkflowLimits {
|
|
23
|
+
const limits = { steps: 100, parallelSteps: 4, inlineWaitMs: 0, resultBytes: 262_144, ...value };
|
|
24
|
+
if (!isWorkflowLimits(limits))
|
|
25
|
+
throw new TypeError("Workflow limits must be bounded whole numbers; inlineWaitMs may be zero.");
|
|
26
|
+
return limits;
|
|
27
|
+
}
|
|
28
|
+
function integer(value: unknown, min = 1): value is number {
|
|
29
|
+
return (
|
|
30
|
+
typeof value === "number" &&
|
|
31
|
+
Number.isSafeInteger(value) &&
|
|
32
|
+
value >= min &&
|
|
33
|
+
value <= 2_147_483_647
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
function isWorkflowLimits(raw: unknown): raw is WorkflowLimits {
|
|
37
|
+
return (
|
|
38
|
+
isRecord(raw) &&
|
|
39
|
+
integer(raw.steps) &&
|
|
40
|
+
raw.steps <= 10_000 &&
|
|
41
|
+
integer(raw.parallelSteps) &&
|
|
42
|
+
raw.parallelSteps <= 1_024 &&
|
|
43
|
+
integer(raw.inlineWaitMs, 0) &&
|
|
44
|
+
integer(raw.resultBytes)
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
export function stepId(runId: string, key: string): string {
|
|
48
|
+
return `${runId}/step/${encodeURIComponent(key)}`;
|
|
49
|
+
}
|
|
50
|
+
export function stepData<T>(value: T, bytes: number): T {
|
|
51
|
+
copyData(value);
|
|
52
|
+
// JSON round-trip makes first execution and database replay return the same representation.
|
|
53
|
+
const text = JSON.stringify(value);
|
|
54
|
+
if (text === undefined || new TextEncoder().encode(text).byteLength > bytes)
|
|
55
|
+
throw new TypeError("Workflow input and results must be JSON within limits.resultBytes.");
|
|
56
|
+
return JSON.parse(text);
|
|
57
|
+
}
|
|
58
|
+
function isError(value: unknown): value is StepError {
|
|
59
|
+
return (
|
|
60
|
+
isRecord(value) &&
|
|
61
|
+
["failed", "timeout", "denied", "cancelled"].includes(String(value.reason)) &&
|
|
62
|
+
typeof value.name === "string" &&
|
|
63
|
+
typeof value.message === "string"
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
function isAttempt(value: unknown): value is StepAttempt {
|
|
67
|
+
return (
|
|
68
|
+
isRecord(value) &&
|
|
69
|
+
isId(value.attemptId) &&
|
|
70
|
+
["running", "completed", "failed", "interrupted", "not_run"].includes(String(value.status)) &&
|
|
71
|
+
(value.error === undefined || isError(value.error)) &&
|
|
72
|
+
(value.reconciliation === undefined || isId(value.reconciliation))
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
function isStep(raw: unknown): raw is StepExecution {
|
|
76
|
+
return (
|
|
77
|
+
isRecord(raw) &&
|
|
78
|
+
isId(raw.id) &&
|
|
79
|
+
isId(raw.key) &&
|
|
80
|
+
raw.key.length <= 256 &&
|
|
81
|
+
["step", "agent", "remote", "workflow", "ask", "sleep"].includes(String(raw.kind)) &&
|
|
82
|
+
["pending", "running", "waiting", "retrying", "completed", "failed"].includes(
|
|
83
|
+
String(raw.status),
|
|
84
|
+
) &&
|
|
85
|
+
isRecord(raw.definition) &&
|
|
86
|
+
Array.isArray(raw.attempts) &&
|
|
87
|
+
raw.attempts.every(isAttempt) &&
|
|
88
|
+
(raw.error === undefined || isError(raw.error)) &&
|
|
89
|
+
(raw.wakeAt === undefined ||
|
|
90
|
+
(typeof raw.wakeAt === "number" && Number.isSafeInteger(raw.wakeAt) && raw.wakeAt > 0)) &&
|
|
91
|
+
Array.isArray(raw.children) &&
|
|
92
|
+
raw.children.every(
|
|
93
|
+
(child) =>
|
|
94
|
+
isRecord(child) &&
|
|
95
|
+
isId(child.key) &&
|
|
96
|
+
(child.reference === undefined || isId(child.reference)) &&
|
|
97
|
+
isTreeNode(child.snapshot),
|
|
98
|
+
) &&
|
|
99
|
+
(raw.reconciliations === undefined ||
|
|
100
|
+
(isRecord(raw.reconciliations) && Object.values(raw.reconciliations).every(isId))) &&
|
|
101
|
+
(raw.asks === undefined || (Array.isArray(raw.asks) && raw.asks.every(isAskRecord)))
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
export function isWorkflowSnapshot(raw: unknown): raw is WorkflowSnapshot {
|
|
105
|
+
return (
|
|
106
|
+
isRecord(raw) &&
|
|
107
|
+
raw.kind === "workflow" &&
|
|
108
|
+
raw.format === 3 &&
|
|
109
|
+
[raw.workflowId, raw.version, raw.runId, raw.attemptId].every(isId) &&
|
|
110
|
+
typeof raw.startedAt === "number" &&
|
|
111
|
+
Number.isSafeInteger(raw.startedAt) &&
|
|
112
|
+
raw.startedAt > 0 &&
|
|
113
|
+
isRecord(raw.definition) &&
|
|
114
|
+
isWorkflowLimits(raw.limits) &&
|
|
115
|
+
Array.isArray(raw.steps) &&
|
|
116
|
+
raw.steps.every(isStep) &&
|
|
117
|
+
isTreeInfo(raw.tree) &&
|
|
118
|
+
isState(raw.state)
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
export function checkWorkflowSnapshot(node: WorkflowSnapshot): void {
|
|
122
|
+
stepData(node.input, node.limits.resultBytes);
|
|
123
|
+
if (
|
|
124
|
+
node.steps.length > node.limits.steps ||
|
|
125
|
+
new Set(node.steps.map((step) => step.key)).size !== node.steps.length
|
|
126
|
+
)
|
|
127
|
+
throw new TypeError("Duplicate workflow keys or exceeded step limit.");
|
|
128
|
+
for (const step of node.steps) {
|
|
129
|
+
if (step.id !== stepId(node.runId, step.key))
|
|
130
|
+
throw new TypeError("Invalid workflow step identity.");
|
|
131
|
+
stepData(step.definition, node.limits.resultBytes);
|
|
132
|
+
const retryPolicy = step.definition.retry;
|
|
133
|
+
if (
|
|
134
|
+
retryPolicy !== undefined &&
|
|
135
|
+
retryPolicy !== null &&
|
|
136
|
+
(!isRecord(retryPolicy) ||
|
|
137
|
+
!integer(retryPolicy.maxAttempts) ||
|
|
138
|
+
retryPolicy.maxAttempts > 100 ||
|
|
139
|
+
!["read-only", "reconcile"].includes(String(retryPolicy.replay)))
|
|
140
|
+
)
|
|
141
|
+
throw new TypeError("Invalid workflow retry policy.");
|
|
142
|
+
if (
|
|
143
|
+
step.kind === "step" &&
|
|
144
|
+
(!integer(step.definition.timeoutMs) ||
|
|
145
|
+
typeof step.definition.needsApproval !== "boolean" ||
|
|
146
|
+
(step.definition.needsApproval && retryPolicy))
|
|
147
|
+
)
|
|
148
|
+
throw new TypeError("Invalid host step policy.");
|
|
149
|
+
if (
|
|
150
|
+
step.kind === "ask" &&
|
|
151
|
+
(!isAsk(step.definition.question) ||
|
|
152
|
+
step.definition.question.type !== "question" ||
|
|
153
|
+
step.definition.question.key !== step.key)
|
|
154
|
+
)
|
|
155
|
+
throw new TypeError("Invalid workflow question.");
|
|
156
|
+
if (
|
|
157
|
+
step.kind === "sleep" &&
|
|
158
|
+
(!integer(step.definition.ms, 0) || (step.status === "completed" && step.result !== null))
|
|
159
|
+
)
|
|
160
|
+
throw new TypeError("Invalid saved sleep.");
|
|
161
|
+
if (step.status === "completed") stepData(step.result, node.limits.resultBytes);
|
|
162
|
+
if (step.status === "failed" && !step.error)
|
|
163
|
+
throw new TypeError("A failed step needs its saved error.");
|
|
164
|
+
if (new Set(step.attempts.map((attempt) => attempt.attemptId)).size !== step.attempts.length)
|
|
165
|
+
throw new TypeError("Duplicate workflow attempt.");
|
|
166
|
+
if (step.kind === "step") {
|
|
167
|
+
if (
|
|
168
|
+
step.children.length ||
|
|
169
|
+
step.attempts.some(
|
|
170
|
+
(attempt, index) => attempt.status === "running" && index !== step.attempts.length - 1,
|
|
171
|
+
)
|
|
172
|
+
)
|
|
173
|
+
throw new TypeError("Invalid effect attempt history.");
|
|
174
|
+
const retry = step.definition.retry;
|
|
175
|
+
const max = isRecord(retry) && integer(retry.maxAttempts) ? retry.maxAttempts : 1;
|
|
176
|
+
const effects = step.attempts.filter((attempt) => attempt.status !== "not_run");
|
|
177
|
+
if (
|
|
178
|
+
step.attempts.length > 100 ||
|
|
179
|
+
effects.length > max ||
|
|
180
|
+
(effects.length > 1 &&
|
|
181
|
+
(!isRecord(retry) ||
|
|
182
|
+
!["read-only", "reconcile"].includes(String(retry.replay)) ||
|
|
183
|
+
step.asks?.length))
|
|
184
|
+
)
|
|
185
|
+
throw new TypeError("Effect attempts exceed their repeatability policy.");
|
|
186
|
+
if (
|
|
187
|
+
isRecord(retry) &&
|
|
188
|
+
retry.replay === "reconcile" &&
|
|
189
|
+
effects.slice(0, -1).some((attempt) => !isId(attempt.reconciliation))
|
|
190
|
+
)
|
|
191
|
+
throw new TypeError("A write was retried without reconciliation.");
|
|
192
|
+
if (step.status === "running" && step.attempts.at(-1)?.status !== "running")
|
|
193
|
+
throw new TypeError("A running effect needs an attempt marker.");
|
|
194
|
+
if (step.status === "completed" && step.attempts.at(-1)?.status !== "completed")
|
|
195
|
+
throw new TypeError("A completed effect needs a receipt.");
|
|
196
|
+
} else if (step.attempts.length) throw new TypeError("Only host effects have effect attempts.");
|
|
197
|
+
if (
|
|
198
|
+
step.kind !== "agent" &&
|
|
199
|
+
step.kind !== "workflow" &&
|
|
200
|
+
step.kind !== "remote" &&
|
|
201
|
+
step.children.length
|
|
202
|
+
)
|
|
203
|
+
throw new TypeError("This step cannot own a child.");
|
|
204
|
+
if (step.kind === "agent" || step.kind === "workflow" || step.kind === "remote") {
|
|
205
|
+
const retry = step.definition.retry;
|
|
206
|
+
if (step.kind === "remote" && retry)
|
|
207
|
+
throw new TypeError("Remote children cannot be retried.");
|
|
208
|
+
const max = isRecord(retry) && integer(retry.maxAttempts) ? retry.maxAttempts : 1;
|
|
209
|
+
if (
|
|
210
|
+
step.children.length > max ||
|
|
211
|
+
step.children.some(
|
|
212
|
+
(child, index) =>
|
|
213
|
+
child.key !== String(index + 1) ||
|
|
214
|
+
child.snapshot.kind !== step.kind ||
|
|
215
|
+
(index < step.children.length - 1 && child.snapshot.state.status !== "failed"),
|
|
216
|
+
)
|
|
217
|
+
)
|
|
218
|
+
throw new TypeError("Invalid workflow child attempts.");
|
|
219
|
+
if (
|
|
220
|
+
step.children.length > 1 &&
|
|
221
|
+
(!isRecord(retry) || !["read-only", "reconcile"].includes(String(retry.replay)))
|
|
222
|
+
)
|
|
223
|
+
throw new TypeError("A child retry needs repeatability policy.");
|
|
224
|
+
if (
|
|
225
|
+
isRecord(retry) &&
|
|
226
|
+
retry.replay === "reconcile" &&
|
|
227
|
+
step.children
|
|
228
|
+
.slice(0, -1)
|
|
229
|
+
.some((child) => !isId(step.reconciliations?.[child.snapshot.runId]))
|
|
230
|
+
)
|
|
231
|
+
throw new TypeError("A child retry is missing reconciliation.");
|
|
232
|
+
if (
|
|
233
|
+
step.status === "completed" &&
|
|
234
|
+
(!step.children.length ||
|
|
235
|
+
!equalData(step.result, { childRunId: step.children.at(-1)?.snapshot.runId }))
|
|
236
|
+
)
|
|
237
|
+
throw new TypeError("A completed child step needs its exact child receipt.");
|
|
238
|
+
}
|
|
239
|
+
if (
|
|
240
|
+
step.kind === "sleep" &&
|
|
241
|
+
step.status !== "pending" &&
|
|
242
|
+
step.status !== "completed" &&
|
|
243
|
+
step.wakeAt === undefined
|
|
244
|
+
)
|
|
245
|
+
throw new TypeError("A sleeping step needs a wake time.");
|
|
246
|
+
const openKeys = new Set<string>();
|
|
247
|
+
for (const [index, record] of (step.asks ?? []).entries()) {
|
|
248
|
+
const request = record.request;
|
|
249
|
+
if (!record.closed) {
|
|
250
|
+
if (openKeys.has(request.ask.type))
|
|
251
|
+
throw new TypeError("A workflow step has duplicate open requests.");
|
|
252
|
+
openKeys.add(request.ask.type);
|
|
253
|
+
}
|
|
254
|
+
if (
|
|
255
|
+
(step.kind === "ask" && !equalData(request.ask, step.definition.question)) ||
|
|
256
|
+
(step.kind !== "ask" &&
|
|
257
|
+
(step.kind !== "step" ||
|
|
258
|
+
request.ask.type !== "approval" ||
|
|
259
|
+
step.definition.needsApproval !== true))
|
|
260
|
+
)
|
|
261
|
+
throw new TypeError("The request kind does not match its workflow step.");
|
|
262
|
+
if (
|
|
263
|
+
!request.step ||
|
|
264
|
+
request.call ||
|
|
265
|
+
request.id !== `${step.id}/ask/${index + 1}` ||
|
|
266
|
+
request.step.operationId !== step.id ||
|
|
267
|
+
request.step.runId !== node.runId ||
|
|
268
|
+
request.step.workflowId !== node.workflowId ||
|
|
269
|
+
request.step.version !== node.version ||
|
|
270
|
+
request.step.key !== step.key ||
|
|
271
|
+
request.step.kind !== step.kind ||
|
|
272
|
+
!equalData(request.step.input, step.definition.input) ||
|
|
273
|
+
request.createdAt < node.startedAt ||
|
|
274
|
+
request.ask.type === "client"
|
|
275
|
+
)
|
|
276
|
+
throw new TypeError("The request does not belong to this workflow step.");
|
|
277
|
+
if (
|
|
278
|
+
(step.status === "completed" || step.status === "failed") &&
|
|
279
|
+
!record.closed &&
|
|
280
|
+
!record.decision
|
|
281
|
+
)
|
|
282
|
+
throw new TypeError("A settled step cannot have an unanswered request.");
|
|
283
|
+
}
|
|
284
|
+
if (
|
|
285
|
+
step.kind === "ask" &&
|
|
286
|
+
step.status === "completed" &&
|
|
287
|
+
!step.asks?.some(
|
|
288
|
+
(record) =>
|
|
289
|
+
!record.closed &&
|
|
290
|
+
record.decision?.type === "answer" &&
|
|
291
|
+
equalData(record.decision.answer, step.result),
|
|
292
|
+
)
|
|
293
|
+
)
|
|
294
|
+
throw new TypeError("The completed question differs from its saved answer.");
|
|
295
|
+
for (const child of step.children) {
|
|
296
|
+
if (
|
|
297
|
+
child.snapshot.runId !== childRunId(step.id, child.key) ||
|
|
298
|
+
child.snapshot.startedAt < node.startedAt
|
|
299
|
+
)
|
|
300
|
+
throw new TypeError("Invalid workflow child identity.");
|
|
301
|
+
if (
|
|
302
|
+
step.status === "completed" &&
|
|
303
|
+
["running", "suspended"].includes(child.snapshot.state.status)
|
|
304
|
+
)
|
|
305
|
+
throw new TypeError("A settled step cannot own unfinished work.");
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
if (
|
|
309
|
+
node.state.status === "completed" &&
|
|
310
|
+
node.steps.some((step) => step.status !== "completed" && step.status !== "failed")
|
|
311
|
+
)
|
|
312
|
+
throw new TypeError("A completed workflow has unfinished steps.");
|
|
313
|
+
if (
|
|
314
|
+
node.state.status === "suspended" &&
|
|
315
|
+
!node.steps.some((step) => step.status === "waiting" || step.status === "retrying")
|
|
316
|
+
)
|
|
317
|
+
throw new TypeError("A suspended workflow needs a waiting step.");
|
|
318
|
+
}
|
|
319
|
+
export function checkWorkflowProgress(previous: WorkflowSnapshot, next: WorkflowSnapshot): void {
|
|
320
|
+
if (previous.steps.length > next.steps.length)
|
|
321
|
+
throw new TypeError("The host dropped workflow steps.");
|
|
322
|
+
for (const [index, step] of previous.steps.entries()) {
|
|
323
|
+
const saved = next.steps[index];
|
|
324
|
+
if (
|
|
325
|
+
!saved ||
|
|
326
|
+
step.id !== saved.id ||
|
|
327
|
+
step.kind !== saved.kind ||
|
|
328
|
+
step.key !== saved.key ||
|
|
329
|
+
!equalData(step.definition, saved.definition) ||
|
|
330
|
+
((step.status === "completed" || step.status === "failed") && !equalData(step, saved))
|
|
331
|
+
)
|
|
332
|
+
throw new TypeError("The host changed a recorded workflow step.");
|
|
333
|
+
for (const [runId, receipt] of Object.entries(step.reconciliations ?? {}))
|
|
334
|
+
if (saved.reconciliations?.[runId] !== receipt)
|
|
335
|
+
throw new TypeError("The host dropped child reconciliation evidence.");
|
|
336
|
+
if (step.wakeAt !== undefined && step.kind === "sleep" && step.wakeAt !== saved.wakeAt)
|
|
337
|
+
throw new TypeError("The host changed a wake time.");
|
|
338
|
+
for (const [i, attempt] of step.attempts.entries()) {
|
|
339
|
+
const after = saved.attempts[i];
|
|
340
|
+
if (
|
|
341
|
+
!after ||
|
|
342
|
+
attempt.attemptId !== after.attemptId ||
|
|
343
|
+
(attempt.reconciliation !== undefined && attempt.reconciliation !== after.reconciliation) ||
|
|
344
|
+
(attempt.status !== "running" &&
|
|
345
|
+
!equalData({ ...attempt, reconciliation: after.reconciliation }, after))
|
|
346
|
+
)
|
|
347
|
+
throw new TypeError("The host erased or replaced a step attempt.");
|
|
348
|
+
}
|
|
349
|
+
for (const [i, ask] of (step.asks ?? []).entries()) {
|
|
350
|
+
const after = saved.asks?.[i];
|
|
351
|
+
if (
|
|
352
|
+
!after ||
|
|
353
|
+
!equalData(ask.request, after.request) ||
|
|
354
|
+
(ask.decision && !equalData(ask.decision, after.decision)) ||
|
|
355
|
+
(ask.closed && ask.closed !== after.closed)
|
|
356
|
+
)
|
|
357
|
+
throw new TypeError("The host changed a workflow request.");
|
|
358
|
+
}
|
|
359
|
+
for (const [i, child] of step.children.entries()) {
|
|
360
|
+
const after = saved.children[i];
|
|
361
|
+
if (!after || child.key !== after.key)
|
|
362
|
+
throw new TypeError("The host dropped a workflow child.");
|
|
363
|
+
checkChildProgress(child.snapshot, after.snapshot);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
}
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
import type { RemoteAgent, RemoteInput, RemoteOutcome } from "./a2a/remote.ts";
|
|
2
|
+
import type { TokenUsage, ToolContext } from "@providerkit/core";
|
|
3
|
+
import type {
|
|
4
|
+
AGENT_RUNTIME,
|
|
5
|
+
Delegation,
|
|
6
|
+
NodeRuntime,
|
|
7
|
+
NodeOutcome,
|
|
8
|
+
SpecialistToolOptions,
|
|
9
|
+
} from "./delegation.ts";
|
|
10
|
+
import type {
|
|
11
|
+
Agent,
|
|
12
|
+
AgentInput,
|
|
13
|
+
Answer,
|
|
14
|
+
AskRecord,
|
|
15
|
+
ChildEnvelope,
|
|
16
|
+
PendingRequest,
|
|
17
|
+
RequestProblem,
|
|
18
|
+
QuestionAsk,
|
|
19
|
+
ResultSchema,
|
|
20
|
+
ResumeOptions,
|
|
21
|
+
RunOptions,
|
|
22
|
+
RunOutcome,
|
|
23
|
+
RunSnapshot,
|
|
24
|
+
RunState,
|
|
25
|
+
TreeLimits,
|
|
26
|
+
} from "./types.ts";
|
|
27
|
+
|
|
28
|
+
export type StepKind = "step" | "agent" | "remote" | "workflow" | "ask" | "sleep";
|
|
29
|
+
export interface StepError {
|
|
30
|
+
reason: "failed" | "timeout" | "denied" | "cancelled";
|
|
31
|
+
name: string;
|
|
32
|
+
message: string;
|
|
33
|
+
}
|
|
34
|
+
export interface WorkflowLimits {
|
|
35
|
+
steps: number;
|
|
36
|
+
parallelSteps: number;
|
|
37
|
+
/** Zero (default) always returns control for a future wake. */
|
|
38
|
+
inlineWaitMs: number;
|
|
39
|
+
resultBytes: number;
|
|
40
|
+
}
|
|
41
|
+
export interface StepRequest {
|
|
42
|
+
workflowId: string;
|
|
43
|
+
version: string;
|
|
44
|
+
runId: string;
|
|
45
|
+
attemptId: string;
|
|
46
|
+
operationId: string;
|
|
47
|
+
key: string;
|
|
48
|
+
kind: StepKind;
|
|
49
|
+
input?: unknown;
|
|
50
|
+
}
|
|
51
|
+
export interface StepAttempt {
|
|
52
|
+
attemptId: string;
|
|
53
|
+
status: "running" | "completed" | "failed" | "interrupted" | "not_run";
|
|
54
|
+
error?: StepError;
|
|
55
|
+
reconciliation?: string;
|
|
56
|
+
}
|
|
57
|
+
export interface StepExecution {
|
|
58
|
+
id: string;
|
|
59
|
+
key: string;
|
|
60
|
+
kind: StepKind;
|
|
61
|
+
/** JSON identity: input, target definition and effect/retry policy. */
|
|
62
|
+
definition: Record<string, unknown>;
|
|
63
|
+
status: "pending" | "running" | "waiting" | "retrying" | "completed" | "failed";
|
|
64
|
+
attempts: StepAttempt[];
|
|
65
|
+
result?: unknown;
|
|
66
|
+
error?: StepError;
|
|
67
|
+
wakeAt?: number;
|
|
68
|
+
children: (ChildEnvelope & { key: string })[];
|
|
69
|
+
asks?: AskRecord[];
|
|
70
|
+
/** Authoritative not-run evidence for whole-child retries, keyed by child run id. */
|
|
71
|
+
reconciliations?: Record<string, string>;
|
|
72
|
+
}
|
|
73
|
+
export interface ChildRetry {
|
|
74
|
+
maxAttempts: number;
|
|
75
|
+
/** Host assertion that the whole child is read-only, or host reconciliation of all its effects. */
|
|
76
|
+
replay: "read-only" | "reconcile";
|
|
77
|
+
retryOn?: (outcome: NodeOutcome) => boolean;
|
|
78
|
+
}
|
|
79
|
+
export interface WorkflowSnapshot {
|
|
80
|
+
format: 3;
|
|
81
|
+
kind: "workflow";
|
|
82
|
+
workflowId: string;
|
|
83
|
+
version: string;
|
|
84
|
+
runId: string;
|
|
85
|
+
attemptId: string;
|
|
86
|
+
startedAt: number;
|
|
87
|
+
input: unknown;
|
|
88
|
+
definition: Record<string, unknown>;
|
|
89
|
+
limits: WorkflowLimits;
|
|
90
|
+
steps: StepExecution[];
|
|
91
|
+
tree: RunSnapshot["tree"];
|
|
92
|
+
state: RunState;
|
|
93
|
+
}
|
|
94
|
+
export type WorkflowRunOptions = Pick<
|
|
95
|
+
RunOptions,
|
|
96
|
+
| "runId"
|
|
97
|
+
| "signal"
|
|
98
|
+
| "context"
|
|
99
|
+
| "memory"
|
|
100
|
+
| "host"
|
|
101
|
+
| "onEvent"
|
|
102
|
+
| "onLifecycle"
|
|
103
|
+
| "bindModelProvider"
|
|
104
|
+
>;
|
|
105
|
+
export type WorkflowResumeOptions = Omit<ResumeOptions, "session">;
|
|
106
|
+
export type WorkflowOutcome<O = unknown> = {
|
|
107
|
+
runId: string;
|
|
108
|
+
attemptId: string;
|
|
109
|
+
treeUsage: TokenUsage;
|
|
110
|
+
steps: StepReceipt[];
|
|
111
|
+
snapshot: WorkflowSnapshot;
|
|
112
|
+
} & (
|
|
113
|
+
| Exclude<RunState, { status: "running" | "completed" | "suspended" }>
|
|
114
|
+
| { status: "completed"; output: O }
|
|
115
|
+
| {
|
|
116
|
+
status: "suspended";
|
|
117
|
+
requests: (PendingRequest & { problem?: RequestProblem })[];
|
|
118
|
+
wakeAt?: number;
|
|
119
|
+
}
|
|
120
|
+
);
|
|
121
|
+
export interface StepReceipt {
|
|
122
|
+
id: string;
|
|
123
|
+
key: string;
|
|
124
|
+
kind: StepKind;
|
|
125
|
+
status: StepExecution["status"];
|
|
126
|
+
attempts: StepAttempt[];
|
|
127
|
+
}
|
|
128
|
+
export interface WorkflowRuntime<O> extends NodeRuntime<WorkflowOutcome<O>> {
|
|
129
|
+
open(input: unknown, options: RunOptions, runId: string): Promise<WorkflowSnapshot>;
|
|
130
|
+
create(
|
|
131
|
+
input: unknown,
|
|
132
|
+
runId: string,
|
|
133
|
+
tree?: RunSnapshot["tree"],
|
|
134
|
+
options?: RunOptions,
|
|
135
|
+
): Promise<WorkflowSnapshot>;
|
|
136
|
+
restore(raw: unknown, tree?: RunSnapshot["tree"]): WorkflowSnapshot;
|
|
137
|
+
configuration(): Record<string, unknown>;
|
|
138
|
+
replay(snapshot: WorkflowSnapshot): Promise<void>;
|
|
139
|
+
}
|
|
140
|
+
export interface Workflow<I = unknown, O = unknown> {
|
|
141
|
+
readonly kind: "workflow";
|
|
142
|
+
readonly id: string;
|
|
143
|
+
readonly version: string;
|
|
144
|
+
run(input: I, options?: WorkflowRunOptions): Promise<WorkflowOutcome<O>>;
|
|
145
|
+
resume(snapshot: unknown, options: WorkflowResumeOptions): Promise<WorkflowOutcome<O>>;
|
|
146
|
+
asTool(options: SpecialistToolOptions<O>): Delegation;
|
|
147
|
+
readonly [AGENT_RUNTIME]: WorkflowRuntime<O>;
|
|
148
|
+
}
|
|
149
|
+
export interface WorkflowSpec<I, O> {
|
|
150
|
+
id: string;
|
|
151
|
+
/** Change when coordination, callback implementations or result meaning changes. */
|
|
152
|
+
version: string;
|
|
153
|
+
input: ResultSchema<I>;
|
|
154
|
+
output?: ResultSchema<O>;
|
|
155
|
+
agents?: readonly (Agent<unknown> | RemoteAgent<unknown>)[];
|
|
156
|
+
workflows?: readonly Workflow<unknown, unknown>[];
|
|
157
|
+
limits?: Partial<WorkflowLimits>;
|
|
158
|
+
treeLimits?: Partial<TreeLimits>;
|
|
159
|
+
/** Pure coordination only. Put every effect and nondeterministic read in a step. */
|
|
160
|
+
run(input: I, context: WorkflowContext): Promise<O>;
|
|
161
|
+
}
|
|
162
|
+
export interface StepOptions<T, I> {
|
|
163
|
+
input?: I;
|
|
164
|
+
/** Pure. Rechecked on replay. Without it T must itself be plain JSON. */
|
|
165
|
+
validate?: (value: unknown) => T;
|
|
166
|
+
timeoutMs?: number;
|
|
167
|
+
/** No retries by default. A read-only assertion or authoritative reconciliation is required. */
|
|
168
|
+
retry?: {
|
|
169
|
+
maxAttempts: number;
|
|
170
|
+
replay: "read-only" | "reconcile";
|
|
171
|
+
baseDelayMs?: number;
|
|
172
|
+
maxDelayMs?: number;
|
|
173
|
+
retryOn?: (error: StepError, attempt: number) => boolean;
|
|
174
|
+
};
|
|
175
|
+
needsApproval?: boolean;
|
|
176
|
+
/** Required before accepting an approval's edited input. */
|
|
177
|
+
validateInput?: (raw: unknown) => I;
|
|
178
|
+
}
|
|
179
|
+
export interface StepRun<I = undefined> {
|
|
180
|
+
readonly key: string;
|
|
181
|
+
readonly attempt: number;
|
|
182
|
+
/** Stable identity, not proof that the receiver deduplicates writes. */
|
|
183
|
+
readonly idempotencyKey: string;
|
|
184
|
+
readonly signal: AbortSignal;
|
|
185
|
+
readonly input: I;
|
|
186
|
+
readonly context: Readonly<ToolContext>;
|
|
187
|
+
report(data: unknown): void;
|
|
188
|
+
}
|
|
189
|
+
export interface WorkflowContext {
|
|
190
|
+
readonly runId: string;
|
|
191
|
+
readonly context: Readonly<ToolContext>;
|
|
192
|
+
step<T, I = undefined>(
|
|
193
|
+
key: string,
|
|
194
|
+
fn: (run: StepRun<I>) => T | Promise<T>,
|
|
195
|
+
options?: StepOptions<T, I>,
|
|
196
|
+
): Promise<T>;
|
|
197
|
+
agent<T>(
|
|
198
|
+
key: string,
|
|
199
|
+
agent: Agent<T>,
|
|
200
|
+
input: AgentInput,
|
|
201
|
+
options?: { retry?: ChildRetry },
|
|
202
|
+
): Promise<RunOutcome<T>>;
|
|
203
|
+
/** Remote sends cannot be retried as a new child. Resume their recorded task instead. */
|
|
204
|
+
agent<T>(key: string, agent: RemoteAgent<T>, input: RemoteInput): Promise<RemoteOutcome<T>>;
|
|
205
|
+
workflow<I, O>(
|
|
206
|
+
key: string,
|
|
207
|
+
workflow: Workflow<I, O>,
|
|
208
|
+
input: I,
|
|
209
|
+
options?: { retry?: ChildRetry },
|
|
210
|
+
): Promise<WorkflowOutcome<O>>;
|
|
211
|
+
ask<T>(question: Omit<QuestionAsk, "type">, validate: (answer: Answer) => T): Promise<T>;
|
|
212
|
+
sleep(key: string, ms: number): Promise<void>;
|
|
213
|
+
}
|