@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/run.js
CHANGED
|
@@ -1,44 +1,42 @@
|
|
|
1
|
-
import { EMPTY_USAGE,
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
1
|
+
import { EMPTY_USAGE, ProviderError, ToolRegistry, collectTurn, createGate, defineTool, messageOf, parseToolArgs, } from "@providerkit/core";
|
|
2
|
+
import { bindMemoryTool, checkMemoryBinding, isMemoryTool, memoryPolicy, memoryScopes, MEMORY_TOOL_NAMES, readMemoryBinding, recallMemory, withMemoryRecall, } from "./memory.js";
|
|
3
|
+
import { allModels, compactionDefinition, compactionId, compactionPlan, modelConversation, } from "./compaction.js";
|
|
4
|
+
import { bindSubagentTool, checkSubagentChildren, subagentInstructions, subagentLimits, } from "./subagents.js";
|
|
5
|
+
import { isCodeTool, programJson, programReceipt, programReply, textBytes, } from "./code.js";
|
|
6
|
+
import { checkRetryTool, readToolRetryPolicy, retryBudget, toolAttempts } from "./tool-retry.js";
|
|
7
|
+
import { GuardChecks, GUARDED_CHUNK_LIMIT, guardDefinition, guardedChunk, jsonBytes, observeLifecycle, refuseGuardedReplay, requireGuardVerdicts, successfulToolResult, toolResultOf, } from "./extensions.js";
|
|
8
|
+
import { AGENT_RUNTIME, executeDelegation, isDelegation, specialistTool, runtimeOf, } from "./delegation.js";
|
|
9
|
+
import { checkHandoffTargets, handoffDelegation, handoffNote, handoffRecord, handoffRef, isHandoff, } from "./handoff.js";
|
|
10
|
+
import { RequestJournal, isClientTool, isInputRequired, requestHash, } from "./request.js";
|
|
11
|
+
import { acknowledgeInputs, acceptInputs, inputReceipts } from "./steering.js";
|
|
12
|
+
import { modelsUsage, readRecoveryPolicy, recoveryToolHash, requireRecovery } from "./recovery.js";
|
|
13
|
+
import { readInput, readStored, repairConversation, requestOf } from "./input.js";
|
|
14
|
+
import { ExecutionTree, Halt, authorizeTree, emitEvent, fail, treeUsage, nodeId, wakeAt, openRequests, readAnswers, requestRecords, stopRequests, untilAbort, } from "./tree.js";
|
|
15
|
+
import { checkOptions, agentSnapshot, completeArguments, copyData, equalData, finalToolResult, finalHandoffResult, immutableCopy, inlineBytes, isBase64, isEnabledTools, isId, isNames, isRecord, isRevision, isUsage, jsonArguments, modelId, recordCodeTools, readLimits, readModelSettings, readTreeLimits, readSnapshot, readTurn, snapshotInlineBytes, toolId, } from "./snapshot.js";
|
|
5
16
|
/** Reserved for the output contract supplied to defineAgent. */
|
|
6
17
|
export const RESULT_TOOL_NAME = "submit_result";
|
|
7
|
-
function
|
|
8
|
-
const history = [
|
|
9
|
-
{ role: "system", content: instructions },
|
|
10
|
-
{ role: "user", content: snapshot.input },
|
|
11
|
-
];
|
|
12
|
-
for (const model of snapshot.models) {
|
|
13
|
-
// Never give a provider half a tool round. The journal retains unfinished work.
|
|
14
|
-
if (model.status !== "completed" || model.tools.some((tool) => tool.status !== "completed"))
|
|
15
|
-
break;
|
|
16
|
-
history.push(model.turn.message);
|
|
17
|
-
for (const [index, tool] of model.tools.entries()) {
|
|
18
|
-
const call = model.turn.message.toolCalls?.[index];
|
|
19
|
-
if (call && tool.status === "completed") {
|
|
20
|
-
history.push({
|
|
21
|
-
role: "tool",
|
|
22
|
-
toolCallId: call.id,
|
|
23
|
-
name: call.name,
|
|
24
|
-
content: tool.result.content,
|
|
25
|
-
});
|
|
26
|
-
}
|
|
27
|
-
}
|
|
28
|
-
}
|
|
29
|
-
return copyData(history);
|
|
30
|
-
}
|
|
31
|
-
function recordOf(snapshot, instructions) {
|
|
18
|
+
function recordOf(snapshot) {
|
|
32
19
|
const saved = copyData(snapshot);
|
|
33
20
|
const receipts = [];
|
|
34
|
-
|
|
35
|
-
for (const model of saved
|
|
36
|
-
|
|
21
|
+
const usage = modelsUsage(allModels(saved));
|
|
22
|
+
for (const model of allModels(saved)) {
|
|
23
|
+
for (const attempt of model.interrupted)
|
|
24
|
+
receipts.push({
|
|
25
|
+
kind: "model",
|
|
26
|
+
id: model.id,
|
|
27
|
+
...attempt,
|
|
28
|
+
status: "interrupted",
|
|
29
|
+
billing: "unknown",
|
|
30
|
+
});
|
|
37
31
|
receipts.push({
|
|
38
32
|
kind: "model",
|
|
33
|
+
...(saved.compactions.some((entry) => entry.id === model.id)
|
|
34
|
+
? { purpose: "compaction" }
|
|
35
|
+
: {}),
|
|
39
36
|
id: model.id,
|
|
40
37
|
attemptId: model.attemptId,
|
|
41
38
|
status: model.status,
|
|
39
|
+
billing: model.billing,
|
|
42
40
|
usage: model.usage,
|
|
43
41
|
...(model.status === "completed" && model.turn.source ? { source: model.turn.source } : {}),
|
|
44
42
|
});
|
|
@@ -46,12 +44,51 @@ function recordOf(snapshot, instructions) {
|
|
|
46
44
|
continue;
|
|
47
45
|
for (const [index, tool] of model.tools.entries()) {
|
|
48
46
|
const call = model.turn.message.toolCalls?.[index];
|
|
49
|
-
if (!call
|
|
47
|
+
if (!call)
|
|
48
|
+
continue;
|
|
49
|
+
for (const attempt of tool.interrupted)
|
|
50
|
+
receipts.push({
|
|
51
|
+
kind: "tool",
|
|
52
|
+
id: tool.id,
|
|
53
|
+
callId: call.id,
|
|
54
|
+
...attempt,
|
|
55
|
+
status: "interrupted",
|
|
56
|
+
});
|
|
57
|
+
for (const attempt of tool.retries)
|
|
58
|
+
receipts.push({
|
|
59
|
+
kind: "tool",
|
|
60
|
+
id: tool.id,
|
|
61
|
+
callId: call.id,
|
|
62
|
+
attemptId: attempt.attemptId,
|
|
63
|
+
result: attempt.result,
|
|
64
|
+
status: "completed",
|
|
65
|
+
});
|
|
66
|
+
for (const inner of tool.calls ?? []) {
|
|
67
|
+
for (const attempt of inner.retries)
|
|
68
|
+
receipts.push({
|
|
69
|
+
kind: "tool",
|
|
70
|
+
id: inner.id,
|
|
71
|
+
parentOperationId: tool.id,
|
|
72
|
+
callId: inner.id,
|
|
73
|
+
attemptId: attempt.attemptId,
|
|
74
|
+
status: "completed",
|
|
75
|
+
result: attempt.result,
|
|
76
|
+
});
|
|
77
|
+
if (inner.status !== "pending")
|
|
78
|
+
receipts.push({
|
|
79
|
+
kind: "tool",
|
|
80
|
+
id: inner.id,
|
|
81
|
+
parentOperationId: tool.id,
|
|
82
|
+
callId: inner.id,
|
|
83
|
+
attemptId: inner.attemptId,
|
|
84
|
+
status: inner.status,
|
|
85
|
+
...(inner.status === "completed" ? { result: inner.result } : {}),
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
if (tool.status === "pending")
|
|
50
89
|
continue;
|
|
51
90
|
receipts.push({
|
|
52
|
-
kind: saved.delegations.
|
|
53
|
-
? "delegation"
|
|
54
|
-
: "tool",
|
|
91
|
+
kind: saved.delegations.find((journal) => journal.operationId === tool.id)?.kind ?? "tool",
|
|
55
92
|
id: tool.id,
|
|
56
93
|
callId: call.id,
|
|
57
94
|
attemptId: tool.attemptId,
|
|
@@ -60,25 +97,51 @@ function recordOf(snapshot, instructions) {
|
|
|
60
97
|
});
|
|
61
98
|
}
|
|
62
99
|
}
|
|
100
|
+
// A root run replaces this with what its append did. Read from a snapshot alone, whether the
|
|
101
|
+
// session has the turn is not known.
|
|
102
|
+
const session = saved.session && {
|
|
103
|
+
id: saved.session.id,
|
|
104
|
+
status: "pending",
|
|
105
|
+
};
|
|
63
106
|
return {
|
|
64
107
|
runId: saved.runId,
|
|
65
108
|
attemptId: saved.attemptId,
|
|
66
109
|
usage,
|
|
67
110
|
treeUsage: treeUsage(saved),
|
|
68
111
|
receipts,
|
|
69
|
-
|
|
112
|
+
inputs: inputReceipts(saved),
|
|
113
|
+
...handoffRecord(saved),
|
|
70
114
|
snapshot: saved,
|
|
115
|
+
...(session ? { session } : {}),
|
|
71
116
|
};
|
|
72
117
|
}
|
|
73
118
|
export function defineAgent(definition) {
|
|
74
119
|
const { id, version, instructions, provider } = definition;
|
|
75
120
|
if (!isId(id) ||
|
|
76
121
|
!isId(version) ||
|
|
77
|
-
typeof instructions !== "string" ||
|
|
122
|
+
(typeof instructions !== "string" && typeof instructions !== "function") ||
|
|
78
123
|
!provider ||
|
|
79
124
|
typeof provider.createStream !== "function") {
|
|
80
125
|
throw new TypeError("An agent needs an id, version, instructions and provider.");
|
|
81
126
|
}
|
|
127
|
+
const settings = readModelSettings(definition.modelSettings);
|
|
128
|
+
const memory = memoryPolicy(definition.memory);
|
|
129
|
+
const compaction = compactionDefinition(definition.compaction);
|
|
130
|
+
const summarizer = definition.compaction?.summarize?.provider;
|
|
131
|
+
const toolRetries = readToolRetryPolicy(definition.toolRetries);
|
|
132
|
+
const guardPolicy = guardDefinition(definition.guardrails);
|
|
133
|
+
const guardrails = definition.guardrails && Object.freeze({ ...definition.guardrails });
|
|
134
|
+
const onLifecycle = definition.onLifecycle;
|
|
135
|
+
if (onLifecycle !== undefined && typeof onLifecycle !== "function")
|
|
136
|
+
throw new TypeError("onLifecycle must be a function.");
|
|
137
|
+
const recovery = readRecoveryPolicy(definition.recovery);
|
|
138
|
+
if (recovery && (!isId(provider.id) || !isId(provider.model)))
|
|
139
|
+
throw new TypeError("A recovery profile needs a stable provider id and model.");
|
|
140
|
+
if (definition.enabledTools !== undefined && !isEnabledTools(definition.enabledTools))
|
|
141
|
+
throw new TypeError("enabledTools must be an allow-list or a function returning one.");
|
|
142
|
+
const enabledTools = Array.isArray(definition.enabledTools)
|
|
143
|
+
? [...definition.enabledTools]
|
|
144
|
+
: definition.enabledTools;
|
|
82
145
|
const limits = readLimits(definition.limits);
|
|
83
146
|
const treeLimits = readTreeLimits(definition.treeLimits);
|
|
84
147
|
const output = definition.output && {
|
|
@@ -91,13 +154,40 @@ export function defineAgent(definition) {
|
|
|
91
154
|
typeof output.validate !== "function")) {
|
|
92
155
|
throw new TypeError("An output contract needs an object schema and a runtime validator.");
|
|
93
156
|
}
|
|
94
|
-
const
|
|
157
|
+
const registeredTools = [...(definition.tools ?? [])];
|
|
158
|
+
const codeTools = new Map(registeredTools.filter(isCodeTool).map((tool) => [tool.name, tool]));
|
|
159
|
+
// Keep capability identity for helper grants; approval/dispatch use the bound tools below.
|
|
160
|
+
const capabilities = new Map(registeredTools.map((tool) => [tool.name, tool]));
|
|
161
|
+
for (const code of codeTools.values())
|
|
162
|
+
for (const tool of code.tools) {
|
|
163
|
+
if (capabilities.has(tool.name) && capabilities.get(tool.name) !== tool)
|
|
164
|
+
throw new TypeError(`The name ${tool.name} must refer to the same tool object directly and in every code binding.`);
|
|
165
|
+
capabilities.set(tool.name, tool);
|
|
166
|
+
}
|
|
167
|
+
const needsMemory = !!memory || [...capabilities.values()].some(isMemoryTool);
|
|
168
|
+
if ([...capabilities.values()].some((tool) => MEMORY_TOOL_NAMES.includes(tool.name) && !isMemoryTool(tool)))
|
|
169
|
+
throw new TypeError("memory_search, memory_save and memory_forget are reserved. Register tools from memoryTools().");
|
|
170
|
+
const tools = registeredTools.map((tool) => isDelegation(tool) ? bindSubagentTool(tool, () => agent) : tool);
|
|
95
171
|
if (new Set(tools.map((tool) => tool.name)).size !== tools.length ||
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
(!isDelegation(tool) && tool.isTerminal))) {
|
|
99
|
-
throw new TypeError(`Use unique tool names and the output contract for terminal results. ${RESULT_TOOL_NAME} is reserved.`);
|
|
172
|
+
[...capabilities.values()].some((tool) => !isId(tool.name) || tool.name === RESULT_TOOL_NAME)) {
|
|
173
|
+
throw new TypeError(`Use unique tool names. ${RESULT_TOOL_NAME} is reserved for the output contract.`);
|
|
100
174
|
}
|
|
175
|
+
if (definition.stopAtTools !== undefined && !isNames(definition.stopAtTools))
|
|
176
|
+
throw new TypeError("stopAtTools must be a list of unique tool names.");
|
|
177
|
+
const stopAtTools = [...(definition.stopAtTools ?? [])];
|
|
178
|
+
for (const name of stopAtTools) {
|
|
179
|
+
const tool = tools.find((tool) => tool.name === name);
|
|
180
|
+
if (!tool || isDelegation(tool) || isHandoff(tool) || isClientTool(tool) || isCodeTool(tool))
|
|
181
|
+
throw new TypeError("stopAtTools must name ordinary tools registered on this agent.");
|
|
182
|
+
}
|
|
183
|
+
for (const tool of tools)
|
|
184
|
+
if (!isDelegation(tool) &&
|
|
185
|
+
!isHandoff(tool) &&
|
|
186
|
+
!isClientTool(tool) &&
|
|
187
|
+
!isCodeTool(tool) &&
|
|
188
|
+
tool.isTerminal &&
|
|
189
|
+
!stopAtTools.includes(tool.name))
|
|
190
|
+
stopAtTools.push(tool.name);
|
|
101
191
|
if (output) {
|
|
102
192
|
tools.push(defineTool({
|
|
103
193
|
name: RESULT_TOOL_NAME,
|
|
@@ -110,17 +200,279 @@ export function defineAgent(definition) {
|
|
|
110
200
|
isReadOnly: true,
|
|
111
201
|
}));
|
|
112
202
|
}
|
|
113
|
-
|
|
203
|
+
if ([...codeTools.values()].some((code) => code.tools.some((tool) => stopAtTools.includes(tool.name))))
|
|
204
|
+
throw new TypeError("Stopping tools must stay direct, outside code mode.");
|
|
205
|
+
const registry = new ToolRegistry([...new Set([...tools, ...capabilities.values()])].filter((tool) => !isDelegation(tool) && !isHandoff(tool) && !isClientTool(tool) && !isCodeTool(tool)));
|
|
206
|
+
for (const name of recovery?.readOnlyTools ?? [])
|
|
207
|
+
if ((!registry.get(name)?.isReadOnly && !codeTools.has(name)) || name === RESULT_TOOL_NAME)
|
|
208
|
+
throw new TypeError("Recovery readOnlyTools must name ordinary isReadOnly tools registered on this agent.");
|
|
209
|
+
for (const [name, policy] of Object.entries(toolRetries?.tools ?? {})) {
|
|
210
|
+
const tool = registry.get(name);
|
|
211
|
+
if (!tool ||
|
|
212
|
+
tool.isTerminal ||
|
|
213
|
+
tool.needsApproval ||
|
|
214
|
+
stopAtTools.includes(name) ||
|
|
215
|
+
(policy.replay === "read-only" && !tool.isReadOnly))
|
|
216
|
+
throw new TypeError("toolRetries must name ordinary non-stopping tools without required approval. Read-only retries need isReadOnly.");
|
|
217
|
+
}
|
|
114
218
|
const delegations = new Map(tools.filter(isDelegation).map((tool) => [tool.name, tool]));
|
|
219
|
+
const handoffs = new Map(tools.filter(isHandoff).map((tool) => [tool.name, tool]));
|
|
220
|
+
function descriptorFor(name, snapshot, operationId) {
|
|
221
|
+
const handoff = handoffs.get(name);
|
|
222
|
+
if (!handoff)
|
|
223
|
+
return delegations.get(name);
|
|
224
|
+
const journal = snapshot.delegations.find((entry) => entry.operationId === operationId);
|
|
225
|
+
if (!journal || journal.kind !== "handoff")
|
|
226
|
+
return undefined;
|
|
227
|
+
if (!equalData(journal.target, handoffRef(handoff.target())))
|
|
228
|
+
throw new TypeError("The saved handoff target or version changed. Restore the registered target.");
|
|
229
|
+
return handoffDelegation(handoff, snapshot, journal);
|
|
230
|
+
}
|
|
231
|
+
const clients = new Map(tools.filter(isClientTool).map((tool) => [tool.name, tool]));
|
|
232
|
+
const names = [...new Set([...capabilities.keys(), ...tools.map((tool) => tool.name)])];
|
|
233
|
+
const directNames = tools.map((tool) => tool.name);
|
|
234
|
+
const definitionsFor = (enabled) => tools
|
|
235
|
+
.filter((tool) => enabled.includes(tool.name))
|
|
236
|
+
.map((tool) => (isCodeTool(tool) ? tool.definition(enabled) : tool.definition()));
|
|
237
|
+
async function toolHash(name) {
|
|
238
|
+
const code = codeTools.get(name);
|
|
239
|
+
if (code)
|
|
240
|
+
return requestHash({
|
|
241
|
+
definition: code.definition(),
|
|
242
|
+
limits: code.limits,
|
|
243
|
+
tools: await Promise.all(code.tools.map(recoveryToolHash)),
|
|
244
|
+
});
|
|
245
|
+
const tool = registry.get(name);
|
|
246
|
+
if (!tool)
|
|
247
|
+
throw new TypeError("Missing recovery tool.");
|
|
248
|
+
return recoveryToolHash(tool);
|
|
249
|
+
}
|
|
250
|
+
function checkNames(value) {
|
|
251
|
+
if (!isNames(value) || value.some((name) => !names.includes(name)))
|
|
252
|
+
throw new TypeError("enabledTools must name each registered tool at most once.");
|
|
253
|
+
return [...value];
|
|
254
|
+
}
|
|
255
|
+
if (Array.isArray(enabledTools))
|
|
256
|
+
checkNames(enabledTools);
|
|
257
|
+
// Adapted from OpenAI Agents JS (MIT), agent.ts and tool.ts. Unlike its per-turn
|
|
258
|
+
// callbacks, these resolve once: a restarted worker must see the same prompt and tools.
|
|
259
|
+
async function resolveDefinition(start, options, runId, source) {
|
|
260
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
261
|
+
const run = Object.freeze({
|
|
262
|
+
agentId: id,
|
|
263
|
+
version,
|
|
264
|
+
runId,
|
|
265
|
+
...immutableCopy({ history: start.history, input: start.input }),
|
|
266
|
+
context: Object.freeze({ ...options.context }),
|
|
267
|
+
signal,
|
|
268
|
+
});
|
|
269
|
+
const text = source
|
|
270
|
+
? source.instructions
|
|
271
|
+
: typeof instructions === "function"
|
|
272
|
+
? await untilAbort(Promise.resolve(instructions(run)), signal)
|
|
273
|
+
: instructions;
|
|
274
|
+
if (typeof text !== "string")
|
|
275
|
+
throw new TypeError("instructions must return a string.");
|
|
276
|
+
async function select(selection) {
|
|
277
|
+
return selection === undefined
|
|
278
|
+
? [...names]
|
|
279
|
+
: checkNames(typeof selection === "function"
|
|
280
|
+
? await untilAbort(Promise.resolve(selection(run)), signal)
|
|
281
|
+
: selection);
|
|
282
|
+
}
|
|
283
|
+
const allowed = source ? source.enabledTools : await select(enabledTools);
|
|
284
|
+
const selected = options.enabledTools === undefined ? allowed : await select(options.enabledTools);
|
|
285
|
+
if (selected.some((name) => name !== RESULT_TOOL_NAME && !allowed.includes(name)))
|
|
286
|
+
throw new TypeError("Run enabledTools may narrow the agent's tools, not enable a disabled tool.");
|
|
287
|
+
// The definition's order is part of the provider's cached prefix, not the allow-list's.
|
|
288
|
+
const enabled = names.filter((name) => selected.includes(name) || (output && name === RESULT_TOOL_NAME));
|
|
289
|
+
// Ported from PydanticAI (MIT), settings.py, merge_model_settings: the run wins.
|
|
290
|
+
// Provider defaults remain in core; passing only set values preserves that first layer.
|
|
291
|
+
const { onActivity: _onActivity, onRateLimit: _onRateLimit, ...modelSettings } = {
|
|
292
|
+
...(source ? source.modelSettings : settings),
|
|
293
|
+
...readModelSettings(options.modelSettings),
|
|
294
|
+
};
|
|
295
|
+
const choice = modelSettings.toolChoice;
|
|
296
|
+
if (output && choice === "none")
|
|
297
|
+
throw new TypeError("toolChoice none disables submit_result, which a checked-output run needs to finish.");
|
|
298
|
+
if ((choice === "required" && enabled.length === 0) ||
|
|
299
|
+
(typeof choice === "object" && !enabled.includes(choice.name)))
|
|
300
|
+
throw new TypeError("toolChoice must name an enabled tool; required needs at least one.");
|
|
301
|
+
const toolHashes = Object.fromEntries(await Promise.all((recovery?.readOnlyTools ?? []).map(async (name) => {
|
|
302
|
+
return [name, await toolHash(name)];
|
|
303
|
+
})));
|
|
304
|
+
const retryHashes = Object.fromEntries(await Promise.all(Object.keys(toolRetries?.tools ?? {}).map(async (name) => {
|
|
305
|
+
const tool = registry.get(name);
|
|
306
|
+
if (!tool)
|
|
307
|
+
throw new TypeError("Missing retry tool.");
|
|
308
|
+
return [name, await recoveryToolHash(tool)];
|
|
309
|
+
})));
|
|
310
|
+
return {
|
|
311
|
+
instructions: text,
|
|
312
|
+
...(memory ? { memory: copyData(memory) } : {}),
|
|
313
|
+
modelSettings,
|
|
314
|
+
enabledTools: enabled,
|
|
315
|
+
stopAtTools: [...stopAtTools],
|
|
316
|
+
...(codeTools.size ? { codeTools: recordCodeTools(codeTools) } : {}),
|
|
317
|
+
guardrails: copyData(guardPolicy),
|
|
318
|
+
compaction: copyData(compaction),
|
|
319
|
+
toolRetries: toolRetries ? { policy: copyData(toolRetries), toolHashes: retryHashes } : null,
|
|
320
|
+
recovery: recovery
|
|
321
|
+
? {
|
|
322
|
+
policy: copyData(recovery),
|
|
323
|
+
provider: { id: provider.id, model: provider.model },
|
|
324
|
+
toolHashes,
|
|
325
|
+
modelToolsHash: await requestHash(definitionsFor(enabled)),
|
|
326
|
+
}
|
|
327
|
+
: null,
|
|
328
|
+
};
|
|
329
|
+
}
|
|
115
330
|
function validateResult(candidate) {
|
|
331
|
+
// copyData permits absent optional values, but a result must survive a JSON checkpoint.
|
|
332
|
+
if (candidate === undefined)
|
|
333
|
+
throw new TypeError("The result must be a JSON value. Return null instead of undefined.");
|
|
116
334
|
if (output)
|
|
117
335
|
return output.validate(copyData(candidate));
|
|
118
336
|
if (typeof candidate !== "string" || !candidate.trim())
|
|
119
337
|
throw new TypeError("The model returned no answer.");
|
|
120
338
|
return candidate;
|
|
121
339
|
}
|
|
122
|
-
|
|
340
|
+
// Adapted from OpenAI Agents JS (MIT), result.ts: the active agent processes its own
|
|
341
|
+
// final output. Follow our saved child instead of casting it to the source's output type.
|
|
342
|
+
function completedOutput(snapshot) {
|
|
343
|
+
if (snapshot.state.status !== "completed")
|
|
344
|
+
throw new TypeError("The run has no completed result.");
|
|
345
|
+
const last = snapshot.models.at(-1);
|
|
346
|
+
const transfer = last?.status === "completed" && finalHandoffResult(snapshot, last);
|
|
347
|
+
if (!transfer)
|
|
348
|
+
return validateResult(snapshot.state.candidate);
|
|
349
|
+
const name = last.turn.message.toolCalls?.[0]?.name;
|
|
350
|
+
const target = name && handoffs.get(name)?.target();
|
|
351
|
+
if (!target || !equalData(handoffRef(target), handoffRef(transfer.child)))
|
|
352
|
+
throw new TypeError("The completed handoff does not match its registered target.");
|
|
353
|
+
const result = target[AGENT_RUNTIME].hydrate(transfer.child);
|
|
354
|
+
if (result.status !== "completed")
|
|
355
|
+
throw new TypeError("The handoff target has no completed result.");
|
|
356
|
+
return result.output;
|
|
357
|
+
}
|
|
358
|
+
function requestFor(snapshot, model, index) {
|
|
359
|
+
const call = model.turn.message.toolCalls?.[index];
|
|
360
|
+
const tool = model.tools[index];
|
|
361
|
+
if (!call || !tool)
|
|
362
|
+
fail("invalid_journal", "The tool call is missing from its journal.");
|
|
363
|
+
return {
|
|
364
|
+
agentId: id,
|
|
365
|
+
version,
|
|
366
|
+
runId: snapshot.runId,
|
|
367
|
+
attemptId: tool.status === "running" || tool.status === "completed"
|
|
368
|
+
? tool.attemptId
|
|
369
|
+
: tool.retries.length
|
|
370
|
+
? `${snapshot.attemptId}/tool-attempt/${tool.retries.length + tool.interrupted.length + 1}`
|
|
371
|
+
: snapshot.attemptId,
|
|
372
|
+
operationId: tool.id,
|
|
373
|
+
...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
|
|
374
|
+
call,
|
|
375
|
+
arguments: codeTools.has(call.name)
|
|
376
|
+
? (jsonArguments(call.arguments) ?? {})
|
|
377
|
+
: parseToolArgs(call.arguments),
|
|
378
|
+
};
|
|
379
|
+
}
|
|
380
|
+
async function needsApproval(call, options, signal) {
|
|
381
|
+
if (call.call.name === RESULT_TOOL_NAME)
|
|
382
|
+
return false;
|
|
383
|
+
const tool = tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
|
|
384
|
+
return (tool?.needsApproval === true ||
|
|
385
|
+
(await untilAbort(Promise.resolve(options.host?.needsApproval?.(immutableCopy(call))), signal)) === true);
|
|
386
|
+
}
|
|
387
|
+
function journalFor(snapshot, model, index, options, scope, signal, effectiveCall) {
|
|
388
|
+
const call = requestFor(snapshot, model, index);
|
|
389
|
+
const execution = model.tools[index];
|
|
390
|
+
if (!execution)
|
|
391
|
+
throw new TypeError("Missing tool journal.");
|
|
392
|
+
return requestsFor(call, execution, options, scope, signal, effectiveCall);
|
|
393
|
+
}
|
|
394
|
+
function requestsFor(call, execution, options, scope, signal, effectiveCall) {
|
|
395
|
+
const tool = tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
|
|
396
|
+
return new RequestJournal(execution, effectiveCall ?? call, options, scope, signal,
|
|
397
|
+
// The policy hash follows the original model call even when dispatch arguments were edited.
|
|
398
|
+
async () => requestHash({
|
|
399
|
+
definition: tool?.definition() ?? null,
|
|
400
|
+
needsApproval: await needsApproval(call, options, signal),
|
|
401
|
+
kind: tool && isHandoff(tool)
|
|
402
|
+
? "handoff"
|
|
403
|
+
: tool && isDelegation(tool)
|
|
404
|
+
? "delegation"
|
|
405
|
+
: tool && isClientTool(tool)
|
|
406
|
+
? "client"
|
|
407
|
+
: "tool",
|
|
408
|
+
...(tool && isHandoff(tool) ? { target: handoffRef(tool.target()) } : {}),
|
|
409
|
+
...(tool && isClientTool(tool) ? { resultSchema: tool.resultSchema } : {}),
|
|
410
|
+
}), (decision) => {
|
|
411
|
+
if (decision.type === "result") {
|
|
412
|
+
const client = clients.get(call.call.name);
|
|
413
|
+
if (!client)
|
|
414
|
+
throw new TypeError("This call is not a registered client tool.");
|
|
415
|
+
client.result(decision.value);
|
|
416
|
+
}
|
|
417
|
+
}, !!guardrails?.toolOutput);
|
|
418
|
+
}
|
|
419
|
+
// Intake is a tree-wide pre-effect barrier. A saved child receives its decisions in its
|
|
420
|
+
// snapshot before the host may reuse a segment. No browser-supplied route is consulted.
|
|
421
|
+
async function answerRequests(snapshot, options, scope, answers, signal) {
|
|
422
|
+
if (snapshot.state.status !== "running" && snapshot.state.status !== "suspended")
|
|
423
|
+
return;
|
|
424
|
+
signal.throwIfAborted();
|
|
425
|
+
for (const model of snapshot.models) {
|
|
426
|
+
if (model.status !== "completed")
|
|
427
|
+
continue;
|
|
428
|
+
for (const [index, execution] of model.tools.entries()) {
|
|
429
|
+
if (execution.status === "completed")
|
|
430
|
+
continue;
|
|
431
|
+
const journal = journalFor(snapshot, model, index, options, scope, signal);
|
|
432
|
+
for (const record of [...(execution.asks ?? [])]) {
|
|
433
|
+
if (record.closed)
|
|
434
|
+
continue;
|
|
435
|
+
scope.tree.active();
|
|
436
|
+
signal.throwIfAborted();
|
|
437
|
+
if (!record.decision && Object.hasOwn(answers, record.request.id))
|
|
438
|
+
await journal.resolve(record, answers[record.request.id]);
|
|
439
|
+
else
|
|
440
|
+
await journal.refresh(record);
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
for (const entry of snapshot.delegations) {
|
|
445
|
+
const model = snapshot.models.find((model) => model.status === "completed" && model.tools.some((tool) => tool.id === entry.operationId));
|
|
446
|
+
const position = model?.status === "completed"
|
|
447
|
+
? model.tools.findIndex((tool) => tool.id === entry.operationId)
|
|
448
|
+
: -1;
|
|
449
|
+
const name = model?.status === "completed" ? model.turn.message.toolCalls?.[position]?.name : undefined;
|
|
450
|
+
const descriptor = name && descriptorFor(name, snapshot, entry.operationId);
|
|
451
|
+
if (!descriptor)
|
|
452
|
+
continue;
|
|
453
|
+
for (const child of entry.children) {
|
|
454
|
+
if (child.snapshot.state.status !== "running" &&
|
|
455
|
+
child.snapshot.state.status !== "suspended")
|
|
456
|
+
continue;
|
|
457
|
+
const specialist = descriptor.specialists.find((agent) => agent.kind === child.snapshot.kind &&
|
|
458
|
+
agent.id === nodeId(child.snapshot) &&
|
|
459
|
+
agent.version === child.snapshot.version);
|
|
460
|
+
if (!specialist)
|
|
461
|
+
throw new TypeError("Unregistered specialist.");
|
|
462
|
+
await runtimeOf(specialist).answerRequests(child.snapshot, options, {
|
|
463
|
+
tree: scope.tree,
|
|
464
|
+
depth: scope.depth + 1,
|
|
465
|
+
path: [
|
|
466
|
+
...scope.path,
|
|
467
|
+
{ operationId: entry.operationId, key: child.key, runId: child.snapshot.runId },
|
|
468
|
+
],
|
|
469
|
+
}, answers, signal);
|
|
470
|
+
}
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
async function execute(snapshot, options, scope, answers) {
|
|
123
474
|
const host = options.host;
|
|
475
|
+
const limits = snapshot.limits;
|
|
124
476
|
const deadline = snapshot.startedAt + limits.elapsedMs;
|
|
125
477
|
const timeout = new AbortController();
|
|
126
478
|
const signal = AbortSignal.any([
|
|
@@ -130,8 +482,8 @@ export function defineAgent(definition) {
|
|
|
130
482
|
]);
|
|
131
483
|
const timer = setTimeout(() => timeout.abort(new Error("The run reached its time limit.")), Math.max(0, deadline - Date.now()));
|
|
132
484
|
let release = () => { };
|
|
133
|
-
let approved;
|
|
134
485
|
let completed;
|
|
486
|
+
let started = false;
|
|
135
487
|
function active() {
|
|
136
488
|
scope.tree.active();
|
|
137
489
|
if (options.signal?.aborted)
|
|
@@ -140,47 +492,303 @@ export function defineAgent(definition) {
|
|
|
140
492
|
throw new Halt({ status: "limited", limit: "elapsedMs" });
|
|
141
493
|
}
|
|
142
494
|
function emit(event) {
|
|
495
|
+
emitEvent(options, event);
|
|
496
|
+
}
|
|
497
|
+
const save = () => scope.tree.save();
|
|
498
|
+
const callbackContext = Object.freeze({
|
|
499
|
+
agentId: id,
|
|
500
|
+
version,
|
|
501
|
+
runId: snapshot.runId,
|
|
502
|
+
attemptId: snapshot.attemptId,
|
|
503
|
+
context: Object.freeze({ ...options.context }),
|
|
504
|
+
signal,
|
|
505
|
+
});
|
|
506
|
+
const observe = (event, callSignal = signal) => observeLifecycle([onLifecycle, options.onLifecycle], event, callSignal === signal ? callbackContext : { ...callbackContext, signal: callSignal });
|
|
507
|
+
const guards = new GuardChecks(snapshot, guardrails, callbackContext, save, active);
|
|
508
|
+
function slotFor(model, index) {
|
|
509
|
+
return {
|
|
510
|
+
model,
|
|
511
|
+
get() {
|
|
512
|
+
const execution = model.tools[index];
|
|
513
|
+
if (!execution)
|
|
514
|
+
fail("invalid_journal", "The tool call is missing from its journal.");
|
|
515
|
+
return execution;
|
|
516
|
+
},
|
|
517
|
+
set(execution) {
|
|
518
|
+
model.tools[index] = execution;
|
|
519
|
+
},
|
|
520
|
+
request: () => requestFor(snapshot, model, index),
|
|
521
|
+
};
|
|
522
|
+
}
|
|
523
|
+
function invocationActive(slot) {
|
|
524
|
+
active();
|
|
525
|
+
slot.inner?.signal.throwIfAborted();
|
|
526
|
+
}
|
|
527
|
+
function toolChecks(callSignal) {
|
|
528
|
+
return callSignal === signal
|
|
529
|
+
? guards
|
|
530
|
+
: new GuardChecks(snapshot, guardrails, { ...callbackContext, signal: callSignal }, save, () => {
|
|
531
|
+
active();
|
|
532
|
+
callSignal.throwIfAborted();
|
|
533
|
+
});
|
|
534
|
+
}
|
|
535
|
+
async function beforeTool(request, callSignal = signal) {
|
|
536
|
+
await toolChecks(callSignal).check("toolInput", request.operationId, request.attemptId, request);
|
|
537
|
+
active();
|
|
538
|
+
callSignal.throwIfAborted();
|
|
539
|
+
await observe({ type: "tool_start", request }, callSignal);
|
|
540
|
+
active();
|
|
541
|
+
callSignal.throwIfAborted();
|
|
542
|
+
}
|
|
543
|
+
async function withToolError(request, work, callSignal = signal) {
|
|
143
544
|
try {
|
|
144
|
-
|
|
545
|
+
await work();
|
|
145
546
|
}
|
|
146
|
-
catch {
|
|
147
|
-
|
|
547
|
+
catch (error) {
|
|
548
|
+
await observe({ type: "tool_error", request }, callSignal);
|
|
549
|
+
throw error;
|
|
550
|
+
}
|
|
551
|
+
}
|
|
552
|
+
function restart(kind, operationId, previousAttemptId, attemptId = snapshot.attemptId) {
|
|
553
|
+
// Adapted from Vercel AI SDK (Apache-2.0), workflow/do-stream-step.ts: reset the
|
|
554
|
+
// current display before replacement output. Unlike reset-step, identity stays explicit.
|
|
555
|
+
emit({
|
|
556
|
+
type: "operation_restart",
|
|
557
|
+
kind,
|
|
558
|
+
runId: snapshot.runId,
|
|
559
|
+
operationId,
|
|
560
|
+
previousAttemptId,
|
|
561
|
+
attemptId,
|
|
562
|
+
});
|
|
563
|
+
}
|
|
564
|
+
async function checkToolRecovery(model, index, previous) {
|
|
565
|
+
const execution = model.tools[index];
|
|
566
|
+
if (!execution)
|
|
567
|
+
fail("invalid_journal", "The tool call is missing from its journal.");
|
|
568
|
+
const request = requestFor(snapshot, model, index);
|
|
569
|
+
const tool = registry.get(request.call.name);
|
|
570
|
+
const recorded = snapshot.definition.recovery;
|
|
571
|
+
const budget = retryBudget(snapshot.definition.toolRetries, request.call.name);
|
|
572
|
+
if (budget && previous + 1 >= budget.maxAttempts)
|
|
573
|
+
fail("tool_retry_exhausted", "This call reached its tool attempt limit. Reconcile the saved attempts with the host.", execution.id);
|
|
574
|
+
requireRecovery(!!tool?.isReadOnly &&
|
|
575
|
+
recorded?.policy.readOnlyTools?.includes(request.call.name) === true &&
|
|
576
|
+
!execution.asks?.length &&
|
|
577
|
+
!!host?.beforeTool, previous, recorded, execution.id);
|
|
578
|
+
if (!tool || (await recoveryToolHash(tool)) !== recorded?.toolHashes[tool.name])
|
|
579
|
+
fail("recovery_definition_changed", "The interrupted tool's definition changed. Reconcile it with the host before continuing.", execution.id);
|
|
580
|
+
active();
|
|
581
|
+
}
|
|
582
|
+
async function recoverTools(model) {
|
|
583
|
+
for (const [index, execution] of model.tools.entries()) {
|
|
584
|
+
if (execution.status !== "running")
|
|
585
|
+
continue;
|
|
586
|
+
const code = codeTools.get(model.turn.message.toolCalls?.[index]?.name ?? "");
|
|
587
|
+
if (code) {
|
|
588
|
+
const calls = execution.calls ?? [];
|
|
589
|
+
const unknown = calls.find((call) => call.status === "running" && !registry.get(call.name)?.isReadOnly);
|
|
590
|
+
if (unknown)
|
|
591
|
+
fail("interrupted_operation", "This inner call started but has no saved result. Reconcile its effect with the host; the program will not replay it.", unknown.id);
|
|
592
|
+
refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
|
|
593
|
+
const restartable = calls.every((call) => registry.get(call.name)?.isReadOnly && !call.asks?.length) &&
|
|
594
|
+
!execution.asks?.length &&
|
|
595
|
+
snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) &&
|
|
596
|
+
!!host?.beforeTool &&
|
|
597
|
+
toolAttempts(execution) < (snapshot.definition.recovery?.policy.maxAttempts ?? 0);
|
|
598
|
+
for (const [position, call] of calls.entries()) {
|
|
599
|
+
if (call.status === "completed")
|
|
600
|
+
continue;
|
|
601
|
+
calls[position] = {
|
|
602
|
+
...call,
|
|
603
|
+
status: "completed",
|
|
604
|
+
result: {
|
|
605
|
+
ok: false,
|
|
606
|
+
kind: "interrupted",
|
|
607
|
+
content: call.started
|
|
608
|
+
? "This read stopped before its result was saved. It changed nothing."
|
|
609
|
+
: "This call did not start. It changed nothing.",
|
|
610
|
+
},
|
|
611
|
+
};
|
|
612
|
+
}
|
|
613
|
+
if (restartable) {
|
|
614
|
+
if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
|
|
615
|
+
fail("recovery_definition_changed", "The code tool's bindings or limits changed. Restore the saved definition before restarting.", execution.id);
|
|
616
|
+
model.tools[index] = {
|
|
617
|
+
id: execution.id,
|
|
618
|
+
status: "pending",
|
|
619
|
+
previousAttemptId: execution.attemptId,
|
|
620
|
+
interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
|
|
621
|
+
retries: execution.retries,
|
|
622
|
+
calls,
|
|
623
|
+
};
|
|
624
|
+
await save();
|
|
625
|
+
}
|
|
626
|
+
else
|
|
627
|
+
await finishTool(model, index, requestFor(snapshot, model, index), code.close(calls));
|
|
628
|
+
continue;
|
|
629
|
+
}
|
|
630
|
+
refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
|
|
631
|
+
await checkToolRecovery(model, index, execution.interrupted.length + execution.retries.length);
|
|
632
|
+
model.tools[index] = {
|
|
633
|
+
id: execution.id,
|
|
634
|
+
status: "pending",
|
|
635
|
+
previousAttemptId: execution.attemptId,
|
|
636
|
+
retries: execution.retries,
|
|
637
|
+
interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
|
|
638
|
+
};
|
|
148
639
|
}
|
|
149
640
|
}
|
|
150
|
-
const save = () => scope.tree.save();
|
|
151
641
|
function usedTools() {
|
|
152
642
|
return snapshot.models.reduce((count, model) => count +
|
|
153
643
|
(model.status === "completed"
|
|
154
|
-
? model.tools.
|
|
644
|
+
? model.tools.reduce((total, tool) => total +
|
|
645
|
+
toolAttempts(tool) +
|
|
646
|
+
(tool.calls ?? []).reduce((innerTotal, call) => innerTotal + 1 + call.retries.length, 0), 0)
|
|
155
647
|
: 0), 0);
|
|
156
648
|
}
|
|
157
|
-
function
|
|
158
|
-
const
|
|
159
|
-
const
|
|
160
|
-
if (!
|
|
161
|
-
fail("invalid_journal", "
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
649
|
+
async function checkToolRetry(slot) {
|
|
650
|
+
const execution = slot.get();
|
|
651
|
+
const recorded = snapshot.definition.toolRetries;
|
|
652
|
+
if (!recorded)
|
|
653
|
+
fail("invalid_journal", "Missing tool retry policy.");
|
|
654
|
+
const request = slot.request();
|
|
655
|
+
await checkRetryTool(registry.get(request.call.name), recorded, execution);
|
|
656
|
+
if (!host?.beforeTool ||
|
|
657
|
+
(await needsApproval(request, options, slot.inner?.signal ?? signal)))
|
|
658
|
+
fail("tool_retry_unsafe", "A retry needs current host authorization and cannot reuse or open an approval.", execution.id);
|
|
659
|
+
invocationActive(slot);
|
|
660
|
+
}
|
|
661
|
+
async function retryTool(slot) {
|
|
662
|
+
const execution = slot.get();
|
|
663
|
+
if (execution.status !== "completed" ||
|
|
664
|
+
execution.result.ok ||
|
|
665
|
+
execution.asks?.length ||
|
|
666
|
+
!["failed", "timeout"].includes(execution.result.kind))
|
|
667
|
+
return false;
|
|
668
|
+
const request = slot.request();
|
|
669
|
+
const policy = retryBudget(snapshot.definition.toolRetries, request.call.name);
|
|
670
|
+
const recoveryCeiling = execution.interrupted.length
|
|
671
|
+
? snapshot.definition.recovery?.policy.maxAttempts
|
|
672
|
+
: undefined;
|
|
673
|
+
if (!policy ||
|
|
674
|
+
toolAttempts(execution) >=
|
|
675
|
+
Math.min(policy.maxAttempts, recoveryCeiling ?? policy.maxAttempts))
|
|
676
|
+
return false;
|
|
677
|
+
invocationActive(slot);
|
|
678
|
+
if (slot.inner && slot.inner.callsLeft() <= 0)
|
|
679
|
+
return false;
|
|
680
|
+
if (usedTools() >= limits.toolCalls) {
|
|
681
|
+
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
682
|
+
}
|
|
683
|
+
await checkToolRetry(slot);
|
|
684
|
+
let reconciliation;
|
|
685
|
+
if (policy.replay === "reconcile") {
|
|
686
|
+
const reconcile = host?.reconcileToolRetry;
|
|
687
|
+
if (!reconcile)
|
|
688
|
+
fail("tool_retry_unsafe", "This failed call needs host reconciliation before it can be repeated.", execution.id);
|
|
689
|
+
const verdict = await untilAbort(Promise.resolve(reconcile(immutableCopy({ request, result: execution.result }), callbackContext)), slot.inner?.signal ?? signal);
|
|
690
|
+
invocationActive(slot);
|
|
691
|
+
if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
|
|
692
|
+
fail("tool_retry_unsafe", "The host could not confirm that the failed call did not run. Reconcile its effect before continuing.", execution.id);
|
|
693
|
+
reconciliation = verdict.receipt;
|
|
694
|
+
}
|
|
695
|
+
// Guest calls can reserve the remaining budget while host reconciliation is awaited.
|
|
696
|
+
invocationActive(slot);
|
|
697
|
+
if (slot.inner && slot.inner.callsLeft() <= 0)
|
|
698
|
+
return false;
|
|
699
|
+
slot.set({
|
|
700
|
+
id: execution.id,
|
|
701
|
+
status: "pending",
|
|
702
|
+
previousAttemptId: execution.attemptId,
|
|
703
|
+
interrupted: execution.interrupted,
|
|
704
|
+
retries: [
|
|
705
|
+
...execution.retries,
|
|
706
|
+
{
|
|
707
|
+
attemptId: execution.attemptId,
|
|
708
|
+
arguments: copyData(request.arguments),
|
|
709
|
+
result: execution.result,
|
|
710
|
+
...(reconciliation ? { reconciliation } : {}),
|
|
711
|
+
},
|
|
712
|
+
],
|
|
713
|
+
});
|
|
714
|
+
// Retain the failure and reconciliation before reserving another attempt.
|
|
715
|
+
await save();
|
|
716
|
+
return true;
|
|
171
717
|
}
|
|
172
718
|
async function finishTool(model, index, request, result) {
|
|
173
|
-
model
|
|
719
|
+
return finishExecution(slotFor(model, index), request, result);
|
|
720
|
+
}
|
|
721
|
+
async function finishExecution(slot, request, result) {
|
|
722
|
+
if (!result.ok && (result.kind === "cancelled" || result.kind === "denied")) {
|
|
723
|
+
for (const record of slot.get().asks ?? [])
|
|
724
|
+
if (!record.decision && !record.closed)
|
|
725
|
+
record.closed = "stopped";
|
|
726
|
+
// A cancelled coordination call cannot leave suspended children under a completed
|
|
727
|
+
// tool receipt. Already settled children and their usage remain untouched.
|
|
728
|
+
const delegation = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
|
|
729
|
+
for (const child of delegation?.children ?? [])
|
|
730
|
+
stopRequests(child.snapshot);
|
|
731
|
+
// Once a target was admitted, it owns this conversation. Denying a renewed transfer
|
|
732
|
+
// stops that conversation; it cannot buy a new source turn after target effects.
|
|
733
|
+
if (delegation?.kind === "handoff" && delegation.children.length > 0)
|
|
734
|
+
snapshot.state = { status: "cancelled" };
|
|
735
|
+
}
|
|
736
|
+
const edited = slot
|
|
737
|
+
.get()
|
|
738
|
+
.asks?.some((record) => !record.closed &&
|
|
739
|
+
record.decision?.type === "approve" &&
|
|
740
|
+
record.decision.arguments !== undefined);
|
|
741
|
+
if (edited && !codeTools.has(request.call.name))
|
|
742
|
+
result = {
|
|
743
|
+
...result,
|
|
744
|
+
content: `${result.content}\nThe reviewer replaced the tool arguments before this call.`,
|
|
745
|
+
};
|
|
746
|
+
const callSignal = slot.inner?.signal ?? signal;
|
|
747
|
+
const checks = toolChecks(callSignal);
|
|
748
|
+
await observe({ type: "tool_end", request, result }, callSignal);
|
|
749
|
+
invocationActive(slot);
|
|
750
|
+
if (guardPolicy?.stages.includes("toolOutput") &&
|
|
751
|
+
jsonBytes(result) > guardPolicy.maxOutputBytes)
|
|
752
|
+
await checks.overflow("toolOutput", request.operationId, request.attemptId);
|
|
753
|
+
await checks.check("toolOutput", request.operationId, request.attemptId, {
|
|
754
|
+
request,
|
|
755
|
+
result,
|
|
756
|
+
});
|
|
757
|
+
invocationActive(slot);
|
|
758
|
+
// Check after callbacks: another concurrent result may have consumed the remaining bytes.
|
|
759
|
+
if (result.ok &&
|
|
760
|
+
result.images &&
|
|
761
|
+
snapshotInlineBytes(snapshot) +
|
|
762
|
+
inlineBytes([
|
|
763
|
+
{
|
|
764
|
+
role: "tool",
|
|
765
|
+
name: request.call.name,
|
|
766
|
+
toolCallId: request.call.id,
|
|
767
|
+
content: result.content,
|
|
768
|
+
images: result.images,
|
|
769
|
+
},
|
|
770
|
+
], "") >
|
|
771
|
+
limits.inlineBytes)
|
|
772
|
+
fail("tool_media_limit", "Tool images exceed this run's inline byte limit. Return fewer or smaller images before starting new work.", request.operationId);
|
|
773
|
+
if (slot.inner)
|
|
774
|
+
result = slot.inner.record(result);
|
|
775
|
+
const previous = slot.get();
|
|
776
|
+
slot.set({
|
|
777
|
+
interrupted: previous.interrupted,
|
|
778
|
+
retries: previous.retries,
|
|
779
|
+
asks: previous.asks,
|
|
780
|
+
calls: previous.calls,
|
|
174
781
|
id: request.operationId,
|
|
175
|
-
attemptId:
|
|
782
|
+
attemptId: request.attemptId,
|
|
176
783
|
status: "completed",
|
|
177
784
|
result,
|
|
178
|
-
};
|
|
785
|
+
});
|
|
179
786
|
await save();
|
|
180
787
|
emit({ type: "tool_result", request, result });
|
|
181
788
|
}
|
|
182
|
-
async function runTool(
|
|
183
|
-
|
|
789
|
+
async function runTool(slot, request, tool, parallel) {
|
|
790
|
+
invocationActive(slot);
|
|
791
|
+
const callSignal = slot.inner?.signal ?? signal;
|
|
184
792
|
let result;
|
|
185
793
|
if (!tool) {
|
|
186
794
|
result = {
|
|
@@ -196,59 +804,512 @@ export function defineAgent(definition) {
|
|
|
196
804
|
content: "Tool arguments must be one complete JSON object. Send the full object again.",
|
|
197
805
|
};
|
|
198
806
|
}
|
|
199
|
-
else if (tool.isTerminal && model
|
|
807
|
+
else if (tool.isTerminal && slot.model?.tools.length !== 1) {
|
|
200
808
|
result = {
|
|
201
809
|
ok: false,
|
|
202
810
|
kind: "invalid_input",
|
|
203
|
-
content: `Call ${
|
|
811
|
+
content: `Call ${tool.name} alone, after the other tool results arrive.`,
|
|
204
812
|
};
|
|
205
813
|
}
|
|
206
814
|
else {
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
815
|
+
// The barrier can return on abort before its callback unwinds. Retain that callback
|
|
816
|
+
// so a program cannot finish while a late guard or tool can still write a receipt.
|
|
817
|
+
let dispatch;
|
|
818
|
+
async function invoke() {
|
|
819
|
+
invocationActive(slot);
|
|
820
|
+
const journal = requestsFor(slot.request(), slot.get(), options, scope, callSignal);
|
|
821
|
+
try {
|
|
822
|
+
await beforeTool(request, callSignal);
|
|
823
|
+
if (slot.get().retries.length)
|
|
824
|
+
await checkToolRetry(slot);
|
|
825
|
+
await journal.recheck(request);
|
|
826
|
+
invocationActive(slot);
|
|
827
|
+
if (slot.inner) {
|
|
828
|
+
slot.inner.start();
|
|
829
|
+
if (!tool?.isReadOnly)
|
|
830
|
+
await save();
|
|
831
|
+
invocationActive(slot);
|
|
832
|
+
await journal.recheck(request);
|
|
833
|
+
invocationActive(slot);
|
|
834
|
+
}
|
|
835
|
+
emit({ type: "tool_start", request });
|
|
836
|
+
invocationActive(slot);
|
|
837
|
+
// Observers and checkpoints can expire an approval or revoke ownership.
|
|
838
|
+
// Reauthorize after them, with no further callback before the actual invocation.
|
|
839
|
+
await journal.recheck(request);
|
|
840
|
+
await journal.assertFresh();
|
|
841
|
+
invocationActive(slot);
|
|
215
842
|
}
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
843
|
+
catch (error) {
|
|
844
|
+
if (!slot.inner && error instanceof Halt && error.state.status === "suspended")
|
|
845
|
+
slot.set({
|
|
846
|
+
id: request.operationId,
|
|
847
|
+
status: "pending",
|
|
848
|
+
interrupted: slot.get().interrupted,
|
|
849
|
+
retries: slot.get().retries,
|
|
850
|
+
asks: slot.get().asks,
|
|
851
|
+
});
|
|
852
|
+
throw error;
|
|
853
|
+
}
|
|
854
|
+
const records = slot.get().asks ?? [];
|
|
855
|
+
const answers = Object.fromEntries(records
|
|
856
|
+
.filter((record) => !record.closed &&
|
|
857
|
+
record.request.ask.type === "question" &&
|
|
858
|
+
record.decision?.type === "answer")
|
|
859
|
+
.map((record) => [
|
|
860
|
+
record.request.ask.type === "question" ? record.request.ask.key : "",
|
|
861
|
+
record.decision?.type === "answer" ? record.decision.answer : undefined,
|
|
862
|
+
]));
|
|
863
|
+
const decision = [...records]
|
|
864
|
+
.reverse()
|
|
865
|
+
.find((record) => !record.closed && record.decision)?.decision;
|
|
866
|
+
if (!tool)
|
|
867
|
+
throw new TypeError("Missing dispatched tool.");
|
|
868
|
+
return untilAbort(bindMemoryTool(tool, options.memory, snapshot, request).invoke(copyData(request.arguments), {
|
|
225
869
|
...options.context,
|
|
870
|
+
answers: immutableCopy(answers),
|
|
871
|
+
decision: immutableCopy(decision),
|
|
226
872
|
runId: snapshot.runId,
|
|
227
|
-
attemptId:
|
|
873
|
+
attemptId: request.attemptId,
|
|
228
874
|
operationId: request.operationId,
|
|
875
|
+
parentOperationId: request.parentOperationId,
|
|
229
876
|
callId: request.call.id,
|
|
230
|
-
signal,
|
|
877
|
+
signal: callSignal,
|
|
878
|
+
}), callSignal);
|
|
879
|
+
}
|
|
880
|
+
let outcome;
|
|
881
|
+
try {
|
|
882
|
+
outcome = await scope.tree.invokeTool(parallel, callSignal, () => {
|
|
883
|
+
dispatch = invoke();
|
|
884
|
+
return dispatch;
|
|
231
885
|
});
|
|
232
|
-
}
|
|
233
|
-
|
|
886
|
+
}
|
|
887
|
+
catch (error) {
|
|
888
|
+
if (slot.inner && dispatch)
|
|
889
|
+
await dispatch.catch(() => { });
|
|
890
|
+
throw error;
|
|
891
|
+
}
|
|
892
|
+
// Run/tree stops never buy another model turn. Program-only abort is settled below.
|
|
234
893
|
if (!outcome.ok)
|
|
235
894
|
active();
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
895
|
+
if (!outcome.ok &&
|
|
896
|
+
isMemoryTool(tool) &&
|
|
897
|
+
outcome.cause instanceof Error &&
|
|
898
|
+
outcome.cause.name === "MemoryScopeError")
|
|
899
|
+
fail("memory_scope_violation", "Memory returned another scope's data. Fix the store before continuing.", request.operationId);
|
|
900
|
+
if (!outcome.ok && outcome.kind === "failed" && isInputRequired(outcome.cause)) {
|
|
901
|
+
if (slot.inner) {
|
|
902
|
+
result = {
|
|
903
|
+
ok: false,
|
|
904
|
+
kind: "denied",
|
|
905
|
+
content: `This call needs a person's answer, and code cannot wait for one.${directNames.includes(tool.name) ? ` Call ${tool.name} directly.` : " Ask the host to provide a direct tool."}`,
|
|
906
|
+
};
|
|
907
|
+
await finishExecution(slot, request, result);
|
|
908
|
+
return;
|
|
909
|
+
}
|
|
910
|
+
if (slot.get().retries.length)
|
|
911
|
+
fail("tool_retry_unsafe", "A retried call requested input. Reconcile it with the host; retries cannot create request replay paths.", request.operationId);
|
|
912
|
+
slot.set({
|
|
913
|
+
id: request.operationId,
|
|
914
|
+
status: "pending",
|
|
915
|
+
asks: slot.get().asks,
|
|
916
|
+
retries: slot.get().retries,
|
|
917
|
+
interrupted: slot.get().interrupted,
|
|
918
|
+
});
|
|
919
|
+
const journal = requestsFor(request, slot.get(), options, scope, signal);
|
|
920
|
+
const previous = journal.latest(outcome.cause.ask);
|
|
921
|
+
if (previous?.decision)
|
|
922
|
+
previous.closed = "invalid";
|
|
923
|
+
await journal.open(outcome.cause.ask, outcome.cause.problem
|
|
924
|
+
? { code: "invalid_answer", message: outcome.cause.problem }
|
|
925
|
+
: undefined);
|
|
926
|
+
return;
|
|
927
|
+
}
|
|
928
|
+
try {
|
|
929
|
+
if (slot.inner && outcome.ok) {
|
|
930
|
+
try {
|
|
931
|
+
if (outcome.output !== undefined)
|
|
932
|
+
programJson(outcome.output);
|
|
933
|
+
result = { ok: true, content: outcome.summary, output: outcome.output };
|
|
934
|
+
}
|
|
935
|
+
catch {
|
|
936
|
+
slot.inner.outputError =
|
|
937
|
+
"The call ran but returned a non-JSON value. Check its effect before calling it again.";
|
|
938
|
+
result = { ok: true, content: slot.inner.outputError };
|
|
939
|
+
}
|
|
940
|
+
}
|
|
941
|
+
else
|
|
942
|
+
result =
|
|
943
|
+
tool.name === RESULT_TOOL_NAME && outcome.ok
|
|
944
|
+
? { ok: true, content: outcome.summary }
|
|
945
|
+
: toolResultOf(outcome);
|
|
946
|
+
}
|
|
947
|
+
catch {
|
|
948
|
+
fail("invalid_tool_output", "The tool returned unsavable data or unsupported content. Return JSON or core text/image parts.", request.operationId);
|
|
949
|
+
}
|
|
950
|
+
if (outcome.ok && tool.name === RESULT_TOOL_NAME && result.ok)
|
|
951
|
+
result.final = { candidate: copyData(request.arguments) };
|
|
952
|
+
if (outcome.ok && snapshot.definition.stopAtTools.includes(tool.name)) {
|
|
953
|
+
try {
|
|
954
|
+
const candidate = output ? copyData(outcome.output) : outcome.summary;
|
|
955
|
+
validateResult(candidate);
|
|
956
|
+
result = { ...result, ok: true, final: { candidate } };
|
|
957
|
+
}
|
|
958
|
+
catch (error) {
|
|
959
|
+
result = {
|
|
960
|
+
ok: false,
|
|
961
|
+
kind: "invalid_output",
|
|
962
|
+
content: `The tool result did not pass the output check: ${messageOf(error)}`,
|
|
963
|
+
};
|
|
964
|
+
}
|
|
965
|
+
}
|
|
239
966
|
}
|
|
240
|
-
await
|
|
967
|
+
await finishExecution(slot, request, result);
|
|
968
|
+
active();
|
|
969
|
+
}
|
|
970
|
+
function canParallel(request, tool, execution) {
|
|
971
|
+
return (!guardrails?.toolInput &&
|
|
972
|
+
!guardrails?.toolOutput &&
|
|
973
|
+
!retryBudget(snapshot.definition.toolRetries, request.call.name) &&
|
|
974
|
+
tool?.isConcurrencySafe === true &&
|
|
975
|
+
snapshot.definition.enabledTools.includes(tool.name) &&
|
|
976
|
+
(request.parentOperationId !== undefined || directNames.includes(tool.name)) &&
|
|
977
|
+
!tool.needsApproval &&
|
|
978
|
+
!host?.needsApproval &&
|
|
979
|
+
!execution.asks?.length &&
|
|
980
|
+
!tool.isTerminal &&
|
|
981
|
+
host?.canRunConcurrently?.(immutableCopy(request)) === true);
|
|
982
|
+
}
|
|
983
|
+
async function runProgram(model, index, request, code) {
|
|
984
|
+
const slot = slotFor(model, index);
|
|
985
|
+
const previous = slot.get();
|
|
986
|
+
if (previous.interrupted.length) {
|
|
987
|
+
requireRecovery(snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) === true &&
|
|
988
|
+
!!host?.beforeTool &&
|
|
989
|
+
!previous.asks?.length &&
|
|
990
|
+
(previous.calls ?? []).every((call) => call.status === "completed" &&
|
|
991
|
+
registry.get(call.name)?.isReadOnly &&
|
|
992
|
+
!call.asks?.length), previous.interrupted.length - 1, snapshot.definition.recovery, previous.id);
|
|
993
|
+
if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
|
|
994
|
+
fail("recovery_definition_changed", "The code bindings changed. Restore the saved definition before restarting.", previous.id);
|
|
995
|
+
}
|
|
996
|
+
const calls = previous.calls ?? [];
|
|
997
|
+
slot.set({
|
|
998
|
+
id: request.operationId,
|
|
999
|
+
attemptId: request.attemptId,
|
|
1000
|
+
status: "running",
|
|
1001
|
+
calls,
|
|
1002
|
+
asks: previous.asks,
|
|
1003
|
+
interrupted: previous.interrupted,
|
|
1004
|
+
retries: previous.retries,
|
|
1005
|
+
});
|
|
1006
|
+
await save();
|
|
1007
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
1008
|
+
try {
|
|
1009
|
+
await beforeTool(request);
|
|
1010
|
+
await requests.recheck(request);
|
|
1011
|
+
active();
|
|
1012
|
+
if (previous.status === "pending" && previous.previousAttemptId)
|
|
1013
|
+
restart("tool", request.operationId, previous.previousAttemptId, request.attemptId);
|
|
1014
|
+
emit({ type: "tool_start", request });
|
|
1015
|
+
await requests.recheck(request);
|
|
1016
|
+
await requests.assertFresh();
|
|
1017
|
+
active();
|
|
1018
|
+
}
|
|
1019
|
+
catch (error) {
|
|
1020
|
+
if (error instanceof Halt && error.state.status === "suspended")
|
|
1021
|
+
slot.set({ ...previous, asks: slot.get().asks });
|
|
1022
|
+
throw error;
|
|
1023
|
+
}
|
|
1024
|
+
const end = new AbortController();
|
|
1025
|
+
const programSignal = AbortSignal.any([signal, end.signal]);
|
|
1026
|
+
const programDeadline = Math.min(Date.now() + code.limits.timeoutMs, deadline, snapshot.tree.startedAt + snapshot.tree.limits.elapsedMs);
|
|
1027
|
+
const timer = setTimeout(() => end.abort(new Error("The program reached its time limit.")), Math.max(0, programDeadline - Date.now()));
|
|
1028
|
+
const enabled = code.tools.filter((tool) => snapshot.definition.enabledTools.includes(tool.name));
|
|
1029
|
+
const gate = createGate(limits.parallelTools);
|
|
1030
|
+
const jobs = [];
|
|
1031
|
+
let barrier = Promise.resolve();
|
|
1032
|
+
let settled = Promise.resolve();
|
|
1033
|
+
let fatal;
|
|
1034
|
+
let closed = false;
|
|
1035
|
+
const reject = (kind, message) => JSON.stringify({ ok: false, error: { kind, message } });
|
|
1036
|
+
const stopped = (call) => ({
|
|
1037
|
+
ok: false,
|
|
1038
|
+
kind: "aborted",
|
|
1039
|
+
content: call.started
|
|
1040
|
+
? "The program stopped. This call may have partly run. Check its effect before repeating it."
|
|
1041
|
+
: "The program stopped before this call started. It did not run.",
|
|
1042
|
+
});
|
|
1043
|
+
const count = () => calls
|
|
1044
|
+
.filter((call) => call.programAttemptId === request.attemptId)
|
|
1045
|
+
.reduce((total, call) => total + 1 + call.retries.length, 0);
|
|
1046
|
+
const bridge = {
|
|
1047
|
+
tools: enabled,
|
|
1048
|
+
signal: programSignal,
|
|
1049
|
+
deadline: programDeadline,
|
|
1050
|
+
calls,
|
|
1051
|
+
toolCallsLeft: () => Math.max(0, Math.min(code.limits.calls - count(), limits.toolCalls - usedTools() - 1)),
|
|
1052
|
+
call(name, input) {
|
|
1053
|
+
if (closed || programSignal.aborted)
|
|
1054
|
+
return Promise.resolve(reject("aborted", "The program has finished. No more calls can start."));
|
|
1055
|
+
const tool = enabled.find((tool) => tool.name === name);
|
|
1056
|
+
if (!tool)
|
|
1057
|
+
return Promise.resolve(reject("disabled_tool", "This tool is not bound and enabled for this program."));
|
|
1058
|
+
if (tool.needsApproval || tool.isTerminal)
|
|
1059
|
+
return Promise.resolve(reject("denied", "This control tool must be called directly, outside code."));
|
|
1060
|
+
const arguments_ = typeof input === "string" && textBytes(input) <= code.limits.callInputBytes
|
|
1061
|
+
? jsonArguments(input)
|
|
1062
|
+
: undefined;
|
|
1063
|
+
if (!arguments_)
|
|
1064
|
+
return Promise.resolve(reject("invalid_input", `Pass one JSON object within ${code.limits.callInputBytes} bytes.`));
|
|
1065
|
+
if (bridge.toolCallsLeft() === 0)
|
|
1066
|
+
return Promise.resolve(reject("denied", "The program has no tool calls left. Return what you have; the final direct call is reserved."));
|
|
1067
|
+
// Admission and budget reservation are synchronous. Promise.all cannot overspend.
|
|
1068
|
+
const position = calls.length;
|
|
1069
|
+
const operationId = `${request.operationId}/call/${position + 1}`;
|
|
1070
|
+
let call = {
|
|
1071
|
+
id: operationId,
|
|
1072
|
+
attemptId: request.attemptId,
|
|
1073
|
+
programAttemptId: request.attemptId,
|
|
1074
|
+
name,
|
|
1075
|
+
arguments: arguments_,
|
|
1076
|
+
status: "pending",
|
|
1077
|
+
started: false,
|
|
1078
|
+
interrupted: [],
|
|
1079
|
+
retries: [],
|
|
1080
|
+
};
|
|
1081
|
+
calls.push(call);
|
|
1082
|
+
let reply = reject("aborted", "The call did not finish.");
|
|
1083
|
+
const inner = {
|
|
1084
|
+
get: () => call,
|
|
1085
|
+
set(execution) {
|
|
1086
|
+
if (execution.status === "delegating" || execution.calls !== undefined)
|
|
1087
|
+
throw new TypeError("A program may only call ordinary tools.");
|
|
1088
|
+
call = {
|
|
1089
|
+
...execution,
|
|
1090
|
+
name,
|
|
1091
|
+
arguments: arguments_,
|
|
1092
|
+
programAttemptId: request.attemptId,
|
|
1093
|
+
attemptId: execution.status === "pending"
|
|
1094
|
+
? `${request.attemptId}/call/${position + 1}/attempt/${execution.retries.length + 1}`
|
|
1095
|
+
: execution.attemptId,
|
|
1096
|
+
started: call.started,
|
|
1097
|
+
bytes: execution.status === "pending" ? undefined : call.bytes,
|
|
1098
|
+
};
|
|
1099
|
+
calls[position] = call;
|
|
1100
|
+
},
|
|
1101
|
+
request: () => ({
|
|
1102
|
+
agentId: id,
|
|
1103
|
+
version,
|
|
1104
|
+
runId: snapshot.runId,
|
|
1105
|
+
attemptId: call.status === "pending" && call.retries.length
|
|
1106
|
+
? `${request.attemptId}/call/${position + 1}/attempt/${call.retries.length + 1}`
|
|
1107
|
+
: call.attemptId,
|
|
1108
|
+
operationId,
|
|
1109
|
+
parentOperationId: request.operationId,
|
|
1110
|
+
...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
|
|
1111
|
+
call: { id: operationId, name, arguments: input },
|
|
1112
|
+
arguments: copyData(arguments_),
|
|
1113
|
+
}),
|
|
1114
|
+
inner: {
|
|
1115
|
+
signal: programSignal,
|
|
1116
|
+
code,
|
|
1117
|
+
callsLeft: () => bridge.toolCallsLeft(),
|
|
1118
|
+
start() {
|
|
1119
|
+
call = {
|
|
1120
|
+
id: call.id,
|
|
1121
|
+
name,
|
|
1122
|
+
arguments: arguments_,
|
|
1123
|
+
programAttemptId: request.attemptId,
|
|
1124
|
+
interrupted: call.interrupted,
|
|
1125
|
+
retries: call.retries,
|
|
1126
|
+
asks: call.asks,
|
|
1127
|
+
status: "running",
|
|
1128
|
+
attemptId: inner.request().attemptId,
|
|
1129
|
+
started: true,
|
|
1130
|
+
};
|
|
1131
|
+
calls[position] = call;
|
|
1132
|
+
},
|
|
1133
|
+
record(result) {
|
|
1134
|
+
const receipt = programReceipt(result);
|
|
1135
|
+
call.bytes = receipt.bytes;
|
|
1136
|
+
reply = inner.inner?.outputError
|
|
1137
|
+
? reject("invalid_output", inner.inner.outputError)
|
|
1138
|
+
: programReply(result, code.limits.callOutputBytes);
|
|
1139
|
+
return receipt.result;
|
|
1140
|
+
},
|
|
1141
|
+
},
|
|
1142
|
+
};
|
|
1143
|
+
let concurrent = false;
|
|
1144
|
+
const work = (async () => {
|
|
1145
|
+
let releaseCall = () => { };
|
|
1146
|
+
try {
|
|
1147
|
+
// Synchronous admission is host work too: a throw must settle its pending call.
|
|
1148
|
+
concurrent = canParallel(inner.request(), tool, call);
|
|
1149
|
+
await (concurrent ? barrier : settled);
|
|
1150
|
+
releaseCall = await gate.acquire(programSignal);
|
|
1151
|
+
do {
|
|
1152
|
+
invocationActive(inner);
|
|
1153
|
+
let effective = inner.request();
|
|
1154
|
+
const journal = requestsFor(effective, call, options, scope, programSignal);
|
|
1155
|
+
if (await needsApproval(effective, options, programSignal)) {
|
|
1156
|
+
let refusal;
|
|
1157
|
+
if (!host?.prepareRequest || !host.beforeTool)
|
|
1158
|
+
refusal = {
|
|
1159
|
+
ok: false,
|
|
1160
|
+
kind: "denied",
|
|
1161
|
+
content: "This call needs a person's approval, and code cannot wait for one.",
|
|
1162
|
+
};
|
|
1163
|
+
else {
|
|
1164
|
+
const record = await journal.ensure({ type: "approval" });
|
|
1165
|
+
const decision = record.decision;
|
|
1166
|
+
if (decision?.type === "approve") {
|
|
1167
|
+
if (decision.arguments !== undefined)
|
|
1168
|
+
effective = { ...effective, arguments: copyData(decision.arguments) };
|
|
1169
|
+
}
|
|
1170
|
+
else {
|
|
1171
|
+
if (!record.decision)
|
|
1172
|
+
record.closed = "stopped";
|
|
1173
|
+
refusal = {
|
|
1174
|
+
ok: false,
|
|
1175
|
+
kind: decision?.type === "cancel" ? "cancelled" : "denied",
|
|
1176
|
+
content: decision?.type === "deny"
|
|
1177
|
+
? (decision.message ?? "The person denied this call.")
|
|
1178
|
+
: "This call needs a person's approval, and code cannot wait for one.",
|
|
1179
|
+
};
|
|
1180
|
+
}
|
|
1181
|
+
}
|
|
1182
|
+
if (refusal) {
|
|
1183
|
+
if (directNames.includes(name))
|
|
1184
|
+
refusal.content += ` Call ${name} directly.`;
|
|
1185
|
+
await finishExecution(inner, effective, refusal);
|
|
1186
|
+
break;
|
|
1187
|
+
}
|
|
1188
|
+
}
|
|
1189
|
+
if (textBytes(programJson(effective.arguments)) > code.limits.callInputBytes) {
|
|
1190
|
+
await finishExecution(inner, effective, {
|
|
1191
|
+
ok: false,
|
|
1192
|
+
kind: "invalid_input",
|
|
1193
|
+
content: `The approved arguments exceed ${code.limits.callInputBytes} bytes. Send less data.`,
|
|
1194
|
+
});
|
|
1195
|
+
break;
|
|
1196
|
+
}
|
|
1197
|
+
if (call.status === "pending" && call.previousAttemptId) {
|
|
1198
|
+
emit({
|
|
1199
|
+
type: "operation_restart",
|
|
1200
|
+
kind: "tool",
|
|
1201
|
+
runId: snapshot.runId,
|
|
1202
|
+
operationId,
|
|
1203
|
+
parentOperationId: request.operationId,
|
|
1204
|
+
previousAttemptId: call.previousAttemptId,
|
|
1205
|
+
attemptId: effective.attemptId,
|
|
1206
|
+
});
|
|
1207
|
+
}
|
|
1208
|
+
await withToolError(effective, () => runTool(inner, effective, tool, concurrent), programSignal);
|
|
1209
|
+
if (count() >= code.limits.calls || programSignal.aborted)
|
|
1210
|
+
break;
|
|
1211
|
+
} while (await retryTool(inner));
|
|
1212
|
+
return reply;
|
|
1213
|
+
}
|
|
1214
|
+
catch (error) {
|
|
1215
|
+
// A host/guard/checkpoint error stops the run, not merely one guest call.
|
|
1216
|
+
if (!programSignal.aborted &&
|
|
1217
|
+
!(error instanceof Halt && error.state.status === "suspended")) {
|
|
1218
|
+
fatal ??= error;
|
|
1219
|
+
end.abort(error);
|
|
1220
|
+
}
|
|
1221
|
+
for (const ask of call.asks ?? [])
|
|
1222
|
+
if (!ask.closed && !ask.decision)
|
|
1223
|
+
ask.closed = "stopped";
|
|
1224
|
+
if (!programSignal.aborted &&
|
|
1225
|
+
error instanceof Halt &&
|
|
1226
|
+
error.state.status === "suspended") {
|
|
1227
|
+
const result = {
|
|
1228
|
+
ok: false,
|
|
1229
|
+
kind: "denied",
|
|
1230
|
+
content: "The approval expired. Code cannot wait for a new decision. Call this tool directly.",
|
|
1231
|
+
};
|
|
1232
|
+
await finishExecution(inner, inner.request(), result);
|
|
1233
|
+
return programReply(result, code.limits.callOutputBytes);
|
|
1234
|
+
}
|
|
1235
|
+
if (inner.get().status !== "completed") {
|
|
1236
|
+
const result = stopped(call);
|
|
1237
|
+
inner.set({
|
|
1238
|
+
id: operationId,
|
|
1239
|
+
attemptId: call.attemptId,
|
|
1240
|
+
status: "completed",
|
|
1241
|
+
interrupted: call.interrupted,
|
|
1242
|
+
retries: call.retries,
|
|
1243
|
+
asks: call.asks,
|
|
1244
|
+
result: programReceipt(result).result,
|
|
1245
|
+
});
|
|
1246
|
+
await save();
|
|
1247
|
+
if (!guardPolicy?.stages.includes("toolOutput"))
|
|
1248
|
+
emit({ type: "tool_result", request: inner.request(), result });
|
|
1249
|
+
}
|
|
1250
|
+
return reject("aborted", "The call stopped. Check its saved receipt before repeating it.");
|
|
1251
|
+
}
|
|
1252
|
+
finally {
|
|
1253
|
+
releaseCall();
|
|
1254
|
+
}
|
|
1255
|
+
})();
|
|
1256
|
+
const done = work.then(() => { }, () => { });
|
|
1257
|
+
settled = Promise.all([settled, done]).then(() => { });
|
|
1258
|
+
if (!concurrent)
|
|
1259
|
+
barrier = settled;
|
|
1260
|
+
jobs.push(work);
|
|
1261
|
+
return work.catch((error) => {
|
|
1262
|
+
fatal ??= error;
|
|
1263
|
+
end.abort(error);
|
|
1264
|
+
return reject("aborted", "The host could not record the call. Stop and reconcile its effect.");
|
|
1265
|
+
});
|
|
1266
|
+
},
|
|
1267
|
+
async settle() {
|
|
1268
|
+
closed = true;
|
|
1269
|
+
end.abort(new Error("The program has finished."));
|
|
1270
|
+
await Promise.allSettled(jobs);
|
|
1271
|
+
clearTimeout(timer);
|
|
1272
|
+
if (fatal)
|
|
1273
|
+
throw fatal;
|
|
1274
|
+
// A deadline may interrupt a guard after an effect returned. Never turn its
|
|
1275
|
+
// unfinished verdict into a successful program or buy another model turn.
|
|
1276
|
+
requireGuardVerdicts(snapshot);
|
|
1277
|
+
},
|
|
1278
|
+
};
|
|
1279
|
+
const outcome = await code.execute(completeArguments(request.call.arguments) ? request.arguments : undefined, bridge);
|
|
1280
|
+
await finishTool(model, index, request, outcome.result);
|
|
241
1281
|
active();
|
|
242
1282
|
}
|
|
243
1283
|
async function runDelegation(model, index, request, descriptor) {
|
|
244
1284
|
let journal = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
|
|
245
1285
|
if (!journal) {
|
|
246
|
-
journal = { operationId: request.operationId, children: [] };
|
|
1286
|
+
journal = { kind: "delegation", operationId: request.operationId, children: [] };
|
|
247
1287
|
snapshot.delegations.push(journal);
|
|
248
1288
|
}
|
|
1289
|
+
if (journal.kind === "handoff") {
|
|
1290
|
+
try {
|
|
1291
|
+
const note = handoffNote(request.arguments);
|
|
1292
|
+
if (journal.children.length > 0 && note !== journal.note)
|
|
1293
|
+
throw new TypeError("The transfer note changed after the target started.");
|
|
1294
|
+
journal.note = note;
|
|
1295
|
+
}
|
|
1296
|
+
catch (error) {
|
|
1297
|
+
if (journal.children.length > 0)
|
|
1298
|
+
fail("handoff_input_changed", "The target already started. Its transfer arguments cannot change. Reconcile the saved run before starting different work.", request.operationId);
|
|
1299
|
+
await finishTool(model, index, request, {
|
|
1300
|
+
ok: false,
|
|
1301
|
+
kind: "invalid_input",
|
|
1302
|
+
content: messageOf(error),
|
|
1303
|
+
});
|
|
1304
|
+
return;
|
|
1305
|
+
}
|
|
1306
|
+
}
|
|
249
1307
|
model.tools[index] = {
|
|
1308
|
+
interrupted: model.tools[index]?.interrupted ?? [],
|
|
1309
|
+
retries: model.tools[index]?.retries ?? [],
|
|
1310
|
+
asks: model.tools[index]?.asks,
|
|
250
1311
|
id: request.operationId,
|
|
251
|
-
attemptId:
|
|
1312
|
+
attemptId: request.attemptId,
|
|
252
1313
|
status: "delegating",
|
|
253
1314
|
};
|
|
254
1315
|
await save();
|
|
@@ -261,16 +1322,22 @@ export function defineAgent(definition) {
|
|
|
261
1322
|
});
|
|
262
1323
|
return;
|
|
263
1324
|
}
|
|
264
|
-
|
|
1325
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
1326
|
+
refuseGuardedReplay(snapshot, request.operationId);
|
|
1327
|
+
await beforeTool(request);
|
|
1328
|
+
await requests.recheck(request);
|
|
265
1329
|
active();
|
|
266
1330
|
emit({ type: "tool_start", request });
|
|
267
1331
|
active();
|
|
1332
|
+
await requests.recheck(request);
|
|
1333
|
+
await requests.assertFresh();
|
|
1334
|
+
active();
|
|
268
1335
|
// Coordination is pure and is the only place children can start. Lend once
|
|
269
1336
|
// for this entire barrier, including ignored children and overlapping joins.
|
|
270
1337
|
release();
|
|
271
1338
|
let result;
|
|
272
1339
|
try {
|
|
273
|
-
result = await executeDelegation(descriptor, journal, snapshot, request.arguments, options, scope, signal, active,
|
|
1340
|
+
result = await executeDelegation(descriptor, journal, snapshot, request.arguments, options, scope, signal, active, requests);
|
|
274
1341
|
}
|
|
275
1342
|
finally {
|
|
276
1343
|
release = await scope.tree.gate.acquire(signal);
|
|
@@ -278,6 +1345,76 @@ export function defineAgent(definition) {
|
|
|
278
1345
|
active();
|
|
279
1346
|
await finishTool(model, index, request, result);
|
|
280
1347
|
}
|
|
1348
|
+
async function openApprovals(model, from) {
|
|
1349
|
+
for (let index = from; index < model.tools.length; index++) {
|
|
1350
|
+
const execution = model.tools[index];
|
|
1351
|
+
if (!execution || execution.status === "completed")
|
|
1352
|
+
continue;
|
|
1353
|
+
if (usedTools() >= limits.toolCalls && !execution.asks?.length)
|
|
1354
|
+
break;
|
|
1355
|
+
const request = requestFor(snapshot, model, index);
|
|
1356
|
+
const tool = tools.find((tool) => tool.name === request.call.name);
|
|
1357
|
+
if (!tool ||
|
|
1358
|
+
request.call.name === RESULT_TOOL_NAME ||
|
|
1359
|
+
!snapshot.definition.enabledTools.includes(tool.name) ||
|
|
1360
|
+
snapshot.definition.modelSettings.toolChoice === "none" ||
|
|
1361
|
+
!completeArguments(request.call.arguments) ||
|
|
1362
|
+
(isHandoff(tool) && model.tools.length !== 1) ||
|
|
1363
|
+
(!isDelegation(tool) &&
|
|
1364
|
+
!isHandoff(tool) &&
|
|
1365
|
+
!isClientTool(tool) &&
|
|
1366
|
+
!isCodeTool(tool) &&
|
|
1367
|
+
tool.isTerminal &&
|
|
1368
|
+
model.tools.length !== 1))
|
|
1369
|
+
continue;
|
|
1370
|
+
if (await needsApproval(request, options, signal))
|
|
1371
|
+
await journalFor(snapshot, model, index, options, scope, signal).ensure({
|
|
1372
|
+
type: "approval",
|
|
1373
|
+
});
|
|
1374
|
+
}
|
|
1375
|
+
}
|
|
1376
|
+
async function runClient(model, index, request, client) {
|
|
1377
|
+
try {
|
|
1378
|
+
if (!completeArguments(request.call.arguments))
|
|
1379
|
+
throw new TypeError("Send one complete JSON object.");
|
|
1380
|
+
client.validateArguments(request.arguments);
|
|
1381
|
+
}
|
|
1382
|
+
catch (error) {
|
|
1383
|
+
await finishTool(model, index, request, {
|
|
1384
|
+
ok: false,
|
|
1385
|
+
kind: "invalid_input",
|
|
1386
|
+
content: messageOf(error),
|
|
1387
|
+
});
|
|
1388
|
+
return;
|
|
1389
|
+
}
|
|
1390
|
+
if (!host?.beforeTool)
|
|
1391
|
+
fail("request_host_missing", "Provide host.beforeTool before dispatching a client tool.");
|
|
1392
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal, request);
|
|
1393
|
+
refuseGuardedReplay(snapshot, request.operationId);
|
|
1394
|
+
await beforeTool(request);
|
|
1395
|
+
await requests.recheck(request);
|
|
1396
|
+
const record = await requests.ensure({ type: "client", resultSchema: client.resultSchema });
|
|
1397
|
+
if (!record.decision)
|
|
1398
|
+
return;
|
|
1399
|
+
if (record.decision.type === "stop") {
|
|
1400
|
+
scope.tree.stop();
|
|
1401
|
+
throw new Halt({ status: "cancelled" });
|
|
1402
|
+
}
|
|
1403
|
+
if (record.decision.type === "cancel") {
|
|
1404
|
+
await finishTool(model, index, request, {
|
|
1405
|
+
ok: false,
|
|
1406
|
+
kind: "cancelled",
|
|
1407
|
+
content: "The person cancelled this client request. This does not undo an action already taken.",
|
|
1408
|
+
});
|
|
1409
|
+
return;
|
|
1410
|
+
}
|
|
1411
|
+
if (record.decision.type !== "result")
|
|
1412
|
+
throw new TypeError("A client request needs a result.");
|
|
1413
|
+
await requests.recheck(request);
|
|
1414
|
+
active();
|
|
1415
|
+
const result = client.result(record.decision.value);
|
|
1416
|
+
await finishTool(model, index, request, successfulToolResult(result));
|
|
1417
|
+
}
|
|
281
1418
|
async function handleTurn(model) {
|
|
282
1419
|
active();
|
|
283
1420
|
const { message, finishReason } = model.turn;
|
|
@@ -296,99 +1433,432 @@ export function defineAgent(definition) {
|
|
|
296
1433
|
snapshot.state = { status: "completed", candidate: message.content };
|
|
297
1434
|
return;
|
|
298
1435
|
}
|
|
1436
|
+
// The one extra call at the local turn limit has no tools, even if a provider ignores
|
|
1437
|
+
// toolChoice. Never execute calls it returns. The shared tree limit remains a hard cap.
|
|
1438
|
+
if (snapshot.models.indexOf(model) >= limits.turns)
|
|
1439
|
+
throw new Halt({ status: "limited", limit: "turns" });
|
|
299
1440
|
for (let index = 0; index < calls.length;) {
|
|
300
|
-
if (model.tools[index]?.status === "completed"
|
|
1441
|
+
if (model.tools[index]?.status === "completed" &&
|
|
1442
|
+
!(await retryTool(slotFor(model, index)))) {
|
|
301
1443
|
index++;
|
|
302
1444
|
continue;
|
|
303
1445
|
}
|
|
304
1446
|
active();
|
|
305
1447
|
const capacity = limits.toolCalls - usedTools();
|
|
306
|
-
if (capacity <= 0 &&
|
|
1448
|
+
if (capacity <= 0 &&
|
|
1449
|
+
model.tools[index]?.status === "pending" &&
|
|
1450
|
+
!model.tools[index]?.asks?.length)
|
|
307
1451
|
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
1452
|
+
let request = requestFor(snapshot, model, index);
|
|
1453
|
+
if (model.tools[index]?.retries.length)
|
|
1454
|
+
await checkToolRetry(slotFor(model, index));
|
|
1455
|
+
if (!directNames.includes(request.call.name) ||
|
|
1456
|
+
!snapshot.definition.enabledTools.includes(request.call.name) ||
|
|
1457
|
+
snapshot.definition.modelSettings.toolChoice === "none") {
|
|
1458
|
+
await finishTool(model, index, request, {
|
|
1459
|
+
ok: false,
|
|
1460
|
+
kind: names.includes(request.call.name) ? "disabled_tool" : "unknown_tool",
|
|
1461
|
+
content: "This tool is not available in this run. Choose one of the provided tools.",
|
|
1462
|
+
});
|
|
312
1463
|
index++;
|
|
313
1464
|
continue;
|
|
314
1465
|
}
|
|
1466
|
+
const handoff = handoffs.get(request.call.name);
|
|
1467
|
+
if (handoff &&
|
|
1468
|
+
!snapshot.delegations.some((entry) => entry.operationId === request.operationId)) {
|
|
1469
|
+
let target;
|
|
1470
|
+
let note;
|
|
1471
|
+
try {
|
|
1472
|
+
if (calls.length !== 1)
|
|
1473
|
+
throw new TypeError(`Call ${handoff.name} alone, after the other tool results arrive.`);
|
|
1474
|
+
if (!completeArguments(request.call.arguments))
|
|
1475
|
+
throw new TypeError("Tool arguments must be one complete JSON object. Send the full object again.");
|
|
1476
|
+
note = handoffNote(request.arguments);
|
|
1477
|
+
target = handoff.target();
|
|
1478
|
+
if (target.id === id)
|
|
1479
|
+
throw new TypeError("This agent already owns the conversation. Choose a different target.");
|
|
1480
|
+
checkHandoffTargets(agent);
|
|
1481
|
+
}
|
|
1482
|
+
catch (error) {
|
|
1483
|
+
await finishTool(model, index, request, {
|
|
1484
|
+
ok: false,
|
|
1485
|
+
kind: "invalid_input",
|
|
1486
|
+
content: messageOf(error),
|
|
1487
|
+
});
|
|
1488
|
+
index++;
|
|
1489
|
+
continue;
|
|
1490
|
+
}
|
|
1491
|
+
// Pin identity before asking for permission. A resumed lazy reference cannot turn
|
|
1492
|
+
// an approval for one target into a transfer to another.
|
|
1493
|
+
snapshot.delegations.push({
|
|
1494
|
+
kind: "handoff",
|
|
1495
|
+
operationId: request.operationId,
|
|
1496
|
+
target: handoffRef(target),
|
|
1497
|
+
...(note !== undefined ? { note } : {}),
|
|
1498
|
+
children: [],
|
|
1499
|
+
});
|
|
1500
|
+
model.tools[index] = {
|
|
1501
|
+
id: request.operationId,
|
|
1502
|
+
status: "delegating",
|
|
1503
|
+
attemptId: snapshot.attemptId,
|
|
1504
|
+
interrupted: [],
|
|
1505
|
+
retries: [],
|
|
1506
|
+
};
|
|
1507
|
+
await save();
|
|
1508
|
+
active();
|
|
1509
|
+
}
|
|
1510
|
+
const descriptor = descriptorFor(request.call.name, snapshot, request.operationId);
|
|
315
1511
|
const tool = registry.get(request.call.name);
|
|
316
|
-
|
|
1512
|
+
const client = clients.get(request.call.name);
|
|
1513
|
+
const code = codeTools.get(request.call.name);
|
|
1514
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
1515
|
+
if ((tool || descriptor || client || code) &&
|
|
317
1516
|
completeArguments(request.call.arguments) &&
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
1517
|
+
(!tool?.isTerminal || model.tools.length === 1) &&
|
|
1518
|
+
(await needsApproval(request, options, signal)))
|
|
1519
|
+
await requests.ensure({ type: "approval" });
|
|
1520
|
+
const records = model.tools[index]?.asks ?? [];
|
|
1521
|
+
if (records.some((record) => !record.closed && record.decision?.type === "stop")) {
|
|
1522
|
+
scope.tree.stop();
|
|
1523
|
+
throw new Halt({ status: "cancelled" });
|
|
1524
|
+
}
|
|
1525
|
+
const decline = records.find((record) => !record.closed &&
|
|
1526
|
+
(record.decision?.type === "deny" || record.decision?.type === "cancel"));
|
|
1527
|
+
if (decline?.decision) {
|
|
1528
|
+
await finishTool(model, index, request, decline.decision.type === "deny"
|
|
1529
|
+
? {
|
|
1530
|
+
ok: false,
|
|
1531
|
+
kind: "denied",
|
|
1532
|
+
content: decline.decision.message ??
|
|
1533
|
+
"The person denied this call. Continue without this action.",
|
|
1534
|
+
}
|
|
1535
|
+
: {
|
|
1536
|
+
ok: false,
|
|
1537
|
+
kind: "cancelled",
|
|
1538
|
+
content: "The person cancelled this request. Continue without this action.",
|
|
1539
|
+
});
|
|
1540
|
+
index++;
|
|
1541
|
+
continue;
|
|
1542
|
+
}
|
|
1543
|
+
if (records.some((record) => !record.closed && !record.decision)) {
|
|
1544
|
+
await openApprovals(model, index + 1);
|
|
1545
|
+
snapshot.state = { status: "suspended" };
|
|
330
1546
|
return;
|
|
331
1547
|
}
|
|
332
|
-
const
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
1548
|
+
const approval = requests.latest({ type: "approval" })?.decision;
|
|
1549
|
+
if (approval?.type === "approve" && approval.arguments !== undefined)
|
|
1550
|
+
request = { ...request, arguments: copyData(approval.arguments) };
|
|
1551
|
+
if (code) {
|
|
1552
|
+
await withToolError(request, () => runProgram(model, index, request, code));
|
|
1553
|
+
index++;
|
|
1554
|
+
continue;
|
|
1555
|
+
}
|
|
1556
|
+
if (descriptor) {
|
|
1557
|
+
await withToolError(request, () => runDelegation(model, index, request, descriptor));
|
|
1558
|
+
index++;
|
|
1559
|
+
continue;
|
|
1560
|
+
}
|
|
1561
|
+
if (client) {
|
|
1562
|
+
await withToolError(request, () => runClient(model, index, request, client));
|
|
1563
|
+
if (model.tools[index]?.status !== "completed") {
|
|
1564
|
+
await openApprovals(model, index + 1);
|
|
1565
|
+
snapshot.state = { status: "suspended" };
|
|
1566
|
+
return;
|
|
1567
|
+
}
|
|
1568
|
+
index++;
|
|
1569
|
+
continue;
|
|
1570
|
+
}
|
|
1571
|
+
const execution = model.tools[index];
|
|
1572
|
+
const batch = [
|
|
1573
|
+
{
|
|
1574
|
+
index,
|
|
1575
|
+
request,
|
|
1576
|
+
tool,
|
|
1577
|
+
previousAttemptId: execution?.status === "pending" ? execution.previousAttemptId : undefined,
|
|
1578
|
+
},
|
|
1579
|
+
];
|
|
1580
|
+
const parallel = (request, tool) => canParallel(request, tool, slotFor(model, model.tools.findIndex((entry) => entry.id === request.operationId)).get());
|
|
337
1581
|
const concurrent = parallel(request, tool);
|
|
338
1582
|
if (concurrent) {
|
|
339
1583
|
for (let next = index + 1; next < calls.length && batch.length < Math.min(limits.parallelTools, capacity); next++) {
|
|
340
|
-
|
|
1584
|
+
const execution = model.tools[next];
|
|
1585
|
+
if (execution?.status !== "pending")
|
|
341
1586
|
break;
|
|
342
|
-
const nextRequest = requestFor(model, next);
|
|
1587
|
+
const nextRequest = requestFor(snapshot, model, next);
|
|
343
1588
|
const nextTool = registry.get(nextRequest.call.name);
|
|
344
1589
|
if (!parallel(nextRequest, nextTool))
|
|
345
1590
|
break;
|
|
346
|
-
batch.push({
|
|
1591
|
+
batch.push({
|
|
1592
|
+
index: next,
|
|
1593
|
+
request: nextRequest,
|
|
1594
|
+
tool: nextTool,
|
|
1595
|
+
previousAttemptId: execution.previousAttemptId,
|
|
1596
|
+
});
|
|
347
1597
|
}
|
|
348
1598
|
}
|
|
1599
|
+
// A checkpoint can capture the pending retry while another child saves. Check its
|
|
1600
|
+
// identity again before admission, even if this worker did not perform the reset.
|
|
1601
|
+
for (const job of batch) {
|
|
1602
|
+
const execution = model.tools[job.index];
|
|
1603
|
+
if (execution?.interrupted.length && !execution.asks?.length)
|
|
1604
|
+
await checkToolRecovery(model, job.index, execution.interrupted.length + execution.retries.length - 1);
|
|
1605
|
+
}
|
|
349
1606
|
active();
|
|
350
1607
|
// Reserve the whole admitted batch before any invocation, including its tool-call budget.
|
|
351
1608
|
for (const job of batch)
|
|
352
1609
|
model.tools[job.index] = {
|
|
1610
|
+
interrupted: model.tools[job.index]?.interrupted ?? [],
|
|
1611
|
+
retries: model.tools[job.index]?.retries ?? [],
|
|
1612
|
+
asks: model.tools[job.index]?.asks,
|
|
353
1613
|
id: job.request.operationId,
|
|
354
|
-
attemptId:
|
|
1614
|
+
attemptId: job.request.attemptId,
|
|
355
1615
|
status: "running",
|
|
356
1616
|
};
|
|
357
1617
|
await save();
|
|
358
|
-
const settled = await Promise.allSettled(batch.map((job) =>
|
|
1618
|
+
const settled = await Promise.allSettled(batch.map((job) => {
|
|
1619
|
+
// Retry and recovery histories can interleave. Use the predecessor saved when
|
|
1620
|
+
// this replacement was scheduled, not the tail of either history alone.
|
|
1621
|
+
if (job.previousAttemptId)
|
|
1622
|
+
restart("tool", job.request.operationId, job.previousAttemptId, job.request.attemptId);
|
|
1623
|
+
return withToolError(job.request, () => runTool(slotFor(model, job.index), job.request, job.tool, concurrent));
|
|
1624
|
+
}));
|
|
359
1625
|
const rejected = settled.find((result) => result.status === "rejected");
|
|
360
1626
|
if (rejected?.status === "rejected")
|
|
361
1627
|
throw rejected.reason;
|
|
362
|
-
|
|
363
|
-
|
|
1628
|
+
if (batch.some((job) => model.tools[job.index]?.status === "pending")) {
|
|
1629
|
+
if (batch.some((job) => model.tools[job.index]?.asks?.some((record) => !record.closed && !record.decision))) {
|
|
1630
|
+
await openApprovals(model, index + batch.length);
|
|
1631
|
+
snapshot.state = { status: "suspended" };
|
|
1632
|
+
return;
|
|
1633
|
+
}
|
|
1634
|
+
continue;
|
|
1635
|
+
}
|
|
1636
|
+
// Retrying tools run serially. Revisit their settled failure through the same
|
|
1637
|
+
// admission path; ordinary batches advance as before.
|
|
1638
|
+
if (!retryBudget(snapshot.definition.toolRetries, request.call.name))
|
|
1639
|
+
index += batch.length;
|
|
1640
|
+
}
|
|
1641
|
+
// Adapted from OpenAI Agents JS (MIT), runner/toolExecution.ts: settle this batch,
|
|
1642
|
+
// then select the first stopping tool in model order, not completion order.
|
|
1643
|
+
const final = finalHandoffResult(snapshot, model) ??
|
|
1644
|
+
finalToolResult(model, snapshot.definition.stopAtTools, output ? RESULT_TOOL_NAME : undefined);
|
|
1645
|
+
if (final)
|
|
1646
|
+
snapshot.state = { status: "completed", candidate: final.candidate };
|
|
1647
|
+
}
|
|
1648
|
+
// One load per media id per attempt. The bytes live only in the requests built from it,
|
|
1649
|
+
// never in the journal, the outcome or an event. The per-run cache of pending loads is
|
|
1650
|
+
// adapted from TanStack AI (MIT), packages/ai-harness/src/media.ts.
|
|
1651
|
+
const media = new Map();
|
|
1652
|
+
function loadMedia(ref) {
|
|
1653
|
+
let loaded = media.get(ref.id);
|
|
1654
|
+
if (!loaded) {
|
|
1655
|
+
loaded = readMedia(ref);
|
|
1656
|
+
media.set(ref.id, loaded);
|
|
364
1657
|
}
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
1658
|
+
return loaded;
|
|
1659
|
+
}
|
|
1660
|
+
async function readMedia(ref) {
|
|
1661
|
+
const load = host?.loadMedia;
|
|
1662
|
+
if (!load)
|
|
1663
|
+
fail("media_unavailable", "This run has media references. Provide host.loadMedia to read their bytes.");
|
|
1664
|
+
let data;
|
|
1665
|
+
try {
|
|
1666
|
+
data = await untilAbort(Promise.resolve(load(immutableCopy(ref), { runId: snapshot.runId, signal })), signal);
|
|
1667
|
+
}
|
|
1668
|
+
catch {
|
|
1669
|
+
active();
|
|
1670
|
+
// Loader errors can quote credentials from a header or request. Never persist them.
|
|
1671
|
+
fail("media_unavailable", "The media could not be loaded. Check file access before trying again.");
|
|
372
1672
|
}
|
|
1673
|
+
if (!isBase64(data))
|
|
1674
|
+
fail("media_unavailable", `host.loadMedia returned no base64 bytes for media ${ref.id}. Return the bytes as padded base64 text.`);
|
|
1675
|
+
return data;
|
|
373
1676
|
}
|
|
374
|
-
async function
|
|
1677
|
+
async function compact() {
|
|
1678
|
+
const last = snapshot.compactions.at(-1);
|
|
1679
|
+
if (last?.status === "running")
|
|
1680
|
+
fail("interrupted_compaction", "The summary has no saved result and may have been billed. Reconcile it with the host before continuing.", last.id);
|
|
1681
|
+
const plan = compactionPlan(snapshot);
|
|
1682
|
+
if (!plan)
|
|
1683
|
+
return;
|
|
1684
|
+
const { removed, ...position } = plan;
|
|
1685
|
+
const index = snapshot.compactions.length;
|
|
1686
|
+
const entry = {
|
|
1687
|
+
id: compactionId(snapshot.runId, index),
|
|
1688
|
+
beforeModel: snapshot.models.length,
|
|
1689
|
+
...position,
|
|
1690
|
+
status: "running",
|
|
1691
|
+
};
|
|
1692
|
+
const summary = snapshot.definition.compaction?.summarize;
|
|
1693
|
+
if (!summary) {
|
|
1694
|
+
snapshot.compactions.push({
|
|
1695
|
+
...entry,
|
|
1696
|
+
status: "completed",
|
|
1697
|
+
summary: "Earlier messages were omitted. No summary was generated.",
|
|
1698
|
+
});
|
|
1699
|
+
await save();
|
|
1700
|
+
return;
|
|
1701
|
+
}
|
|
1702
|
+
if (!summarizer)
|
|
1703
|
+
fail("invalid_journal", "The recorded summary provider is missing.");
|
|
1704
|
+
// A separate receipt freezes this cut before any paid work. A crash, even before
|
|
1705
|
+
// dispatch, fails closed instead of silently purchasing the same summary twice.
|
|
1706
|
+
snapshot.compactions.push(entry);
|
|
1707
|
+
await save();
|
|
375
1708
|
active();
|
|
376
|
-
|
|
1709
|
+
const messages = await requestOf(summary.instructions, removed, loadMedia);
|
|
1710
|
+
await callModel(entry.id, {
|
|
1711
|
+
messages,
|
|
1712
|
+
tools: [],
|
|
1713
|
+
settings: {
|
|
1714
|
+
maxTokens: summary.maxTokens,
|
|
1715
|
+
maxAttempts: 1,
|
|
1716
|
+
toolChoice: "none",
|
|
1717
|
+
hostedTools: [],
|
|
1718
|
+
},
|
|
1719
|
+
}, summarizer, (model) => {
|
|
1720
|
+
if (model.status === "completed") {
|
|
1721
|
+
if (model.turn.finishReason !== "stop" ||
|
|
1722
|
+
!model.turn.message.content.trim() ||
|
|
1723
|
+
model.tools.length ||
|
|
1724
|
+
model.turn.message.hostedCalls?.length ||
|
|
1725
|
+
model.turn.message.hostedItems)
|
|
1726
|
+
fail("invalid_compaction", "The summary must be complete text without tool calls. Check the summary provider before starting new work.", entry.id);
|
|
1727
|
+
snapshot.compactions[index] = {
|
|
1728
|
+
...entry,
|
|
1729
|
+
model,
|
|
1730
|
+
status: "completed",
|
|
1731
|
+
summary: model.turn.message.content,
|
|
1732
|
+
};
|
|
1733
|
+
}
|
|
1734
|
+
else
|
|
1735
|
+
entry.model = model;
|
|
1736
|
+
}, undefined, true);
|
|
1737
|
+
}
|
|
1738
|
+
async function nextTurn(previous) {
|
|
1739
|
+
active();
|
|
1740
|
+
// Hosted actions may run before any local tool call appears. Their explicit presence
|
|
1741
|
+
// overrides a profile's inference-only claim when an interrupted call is recovered.
|
|
1742
|
+
if (previous) {
|
|
1743
|
+
refuseGuardedReplay(snapshot, previous.id);
|
|
1744
|
+
requireRecovery(snapshot.definition.recovery?.policy.inferenceOnly === true &&
|
|
1745
|
+
!snapshot.definition.modelSettings.hostedTools?.length, previous.interrupted.length, snapshot.definition.recovery, previous.id);
|
|
1746
|
+
}
|
|
1747
|
+
const position = previous ? snapshot.models.indexOf(previous) : snapshot.models.length;
|
|
1748
|
+
const selected = definitionsFor(snapshot.definition.enabledTools);
|
|
1749
|
+
if (previous &&
|
|
1750
|
+
(await requestHash(selected)) !== snapshot.definition.recovery?.modelToolsHash)
|
|
1751
|
+
fail("recovery_definition_changed", "The interrupted model call's tool definitions changed. Restore the same definitions or reconcile the run.", previous.id);
|
|
1752
|
+
// Ported from Microsoft Agent Framework (MIT), _tools.py: after the iteration
|
|
1753
|
+
// allowance, ask once for a tool-free answer. Checked output needs submit_result,
|
|
1754
|
+
// so that mode retains the hard local turn cap instead of buying an unusable call.
|
|
1755
|
+
const finalTurn = position === limits.turns;
|
|
1756
|
+
if (position > limits.turns || (finalTurn && output))
|
|
377
1757
|
throw new Halt({ status: "limited", limit: "turns" });
|
|
1758
|
+
// A steer never changes the input of an already admitted call, including safe replay.
|
|
1759
|
+
// Check capacity before polling so a spent budget leaves delivery queued in the host.
|
|
1760
|
+
scope.tree.reserveModel();
|
|
1761
|
+
if (!previous) {
|
|
1762
|
+
await acceptInputs(snapshot, scope, options, signal);
|
|
1763
|
+
await compact();
|
|
1764
|
+
}
|
|
1765
|
+
active();
|
|
1766
|
+
// Media is read before the receipt below exists, so a missing loader or file fails the
|
|
1767
|
+
// run with no model operation left running and nothing to reconcile.
|
|
1768
|
+
const request = await requestOf(snapshot.definition.instructions, withMemoryRecall(snapshot, modelConversation(snapshot)), loadMedia);
|
|
1769
|
+
active();
|
|
1770
|
+
const modelSettings = copyData(snapshot.definition.modelSettings);
|
|
1771
|
+
// Ported from OpenAI Agents JS (MIT), runner/modelSettings.ts, maybeResetToolChoice.
|
|
1772
|
+
// Derive usage from the journal so resume cannot force the first tool a second time.
|
|
1773
|
+
const choice = modelSettings.toolChoice;
|
|
1774
|
+
if ((choice === "required" || typeof choice === "object") &&
|
|
1775
|
+
snapshot.models.some((model) => model.status === "completed" && model.tools.length > 0))
|
|
1776
|
+
modelSettings.toolChoice = "auto";
|
|
1777
|
+
if (finalTurn)
|
|
1778
|
+
modelSettings.toolChoice = "none";
|
|
1779
|
+
const operationId = modelId(snapshot.runId, position);
|
|
1780
|
+
const modelInput = {
|
|
1781
|
+
messages: request,
|
|
1782
|
+
tools: finalTurn ? [] : copyData(selected),
|
|
1783
|
+
settings: modelSettings,
|
|
1784
|
+
};
|
|
1785
|
+
const done = await callModel(operationId, modelInput, provider, (model) => {
|
|
1786
|
+
snapshot.models[position] = model;
|
|
1787
|
+
}, previous);
|
|
1788
|
+
for (const receipt of inputReceipts(snapshot).filter((receipt) => receipt.modelId === done.id))
|
|
1789
|
+
emit({ type: "input", receipt });
|
|
1790
|
+
await acknowledgeInputs(snapshot, options, signal);
|
|
1791
|
+
return done;
|
|
1792
|
+
}
|
|
1793
|
+
// Both ordinary turns and explicit summaries use the same admission, guards, usage
|
|
1794
|
+
// checkpoints and collection path. Summaries stay private and never dispatch tools.
|
|
1795
|
+
async function callModel(operationId, modelInput, selectedProvider, record, previous, summary = false) {
|
|
1796
|
+
const { messages: request, settings: modelSettings } = modelInput;
|
|
1797
|
+
await guards.check("modelInput", operationId, snapshot.attemptId, modelInput);
|
|
1798
|
+
await observe({
|
|
1799
|
+
type: "model_start",
|
|
1800
|
+
operationId,
|
|
1801
|
+
attemptId: snapshot.attemptId,
|
|
1802
|
+
input: modelInput,
|
|
1803
|
+
});
|
|
1804
|
+
active();
|
|
1805
|
+
// The tree check and the receipt stay together, with no await between them, so two
|
|
1806
|
+
// children racing for the tree's last model call cannot both take it.
|
|
378
1807
|
scope.tree.reserveModel();
|
|
379
1808
|
const model = {
|
|
380
|
-
id:
|
|
1809
|
+
id: operationId,
|
|
381
1810
|
attemptId: snapshot.attemptId,
|
|
382
1811
|
status: "running",
|
|
1812
|
+
billing: "unknown",
|
|
383
1813
|
usage: { ...EMPTY_USAGE },
|
|
1814
|
+
interrupted: previous
|
|
1815
|
+
? [
|
|
1816
|
+
...previous.interrupted,
|
|
1817
|
+
{ attemptId: previous.attemptId, usage: copyData(previous.usage) },
|
|
1818
|
+
]
|
|
1819
|
+
: [],
|
|
384
1820
|
};
|
|
385
|
-
|
|
1821
|
+
record(model);
|
|
386
1822
|
await save();
|
|
1823
|
+
if (previous)
|
|
1824
|
+
restart("model", model.id, previous.attemptId);
|
|
387
1825
|
active();
|
|
1826
|
+
let reportedUsage = false;
|
|
1827
|
+
let bufferedChunks = 0;
|
|
1828
|
+
let bufferedBytes = 0;
|
|
1829
|
+
const guarded = !!guardrails?.modelOutput;
|
|
388
1830
|
async function* observed() {
|
|
389
|
-
|
|
1831
|
+
let dispatchProvider = selectedProvider;
|
|
1832
|
+
if (options.bindModelProvider) {
|
|
1833
|
+
try {
|
|
1834
|
+
const bound = options.bindModelProvider(selectedProvider, Object.freeze({
|
|
1835
|
+
run: callbackContext,
|
|
1836
|
+
operationId: model.id,
|
|
1837
|
+
operationAttemptId: model.attemptId,
|
|
1838
|
+
purpose: summary ? "compaction" : "turn",
|
|
1839
|
+
}));
|
|
1840
|
+
if (bound && typeof bound.createStream === "function")
|
|
1841
|
+
dispatchProvider = bound;
|
|
1842
|
+
}
|
|
1843
|
+
catch {
|
|
1844
|
+
// Instrumentation can fail before dispatch. Never catch/replay the provider call.
|
|
1845
|
+
}
|
|
1846
|
+
}
|
|
1847
|
+
active();
|
|
1848
|
+
const stream = dispatchProvider.createStream(request, modelInput.tools, {
|
|
1849
|
+
...modelSettings,
|
|
1850
|
+
...(settings.onActivity ? { onActivity: settings.onActivity } : {}),
|
|
1851
|
+
...(settings.onRateLimit ? { onRateLimit: settings.onRateLimit } : {}),
|
|
1852
|
+
...(options.modelSettings?.onActivity
|
|
1853
|
+
? { onActivity: options.modelSettings.onActivity }
|
|
1854
|
+
: {}),
|
|
1855
|
+
...(options.modelSettings?.onRateLimit
|
|
1856
|
+
? { onRateLimit: options.modelSettings.onRateLimit }
|
|
1857
|
+
: {}),
|
|
390
1858
|
signal,
|
|
391
|
-
sessionId:
|
|
1859
|
+
sessionId: summary
|
|
1860
|
+
? operationId
|
|
1861
|
+
: (snapshot.subagent?.identity.originRunId ?? snapshot.runId),
|
|
392
1862
|
});
|
|
393
1863
|
for await (const chunk of stream) {
|
|
394
1864
|
active();
|
|
@@ -396,92 +1866,143 @@ export function defineAgent(definition) {
|
|
|
396
1866
|
if (!isUsage(chunk.usage))
|
|
397
1867
|
fail("invalid_usage", "The provider returned invalid token usage.", model.id);
|
|
398
1868
|
model.usage = copyData(chunk.usage);
|
|
1869
|
+
reportedUsage = true;
|
|
1870
|
+
// Preserve measurements before another pull can hang or the worker can disappear.
|
|
1871
|
+
// This saves usage, not partial text, and does not claim final billing is known.
|
|
1872
|
+
await save();
|
|
1873
|
+
active();
|
|
1874
|
+
}
|
|
1875
|
+
if (guarded) {
|
|
1876
|
+
// Bound collection before yielding. Only the checked assembled turn is published.
|
|
1877
|
+
// All fields count, including reasoning, signatures, tool args and hosted payloads.
|
|
1878
|
+
bufferedBytes += jsonBytes(chunk);
|
|
1879
|
+
bufferedChunks++;
|
|
1880
|
+
if (bufferedBytes > (guardPolicy?.maxOutputBytes ?? 0) ||
|
|
1881
|
+
bufferedChunks > GUARDED_CHUNK_LIMIT)
|
|
1882
|
+
await guards.overflow("modelOutput", model.id);
|
|
1883
|
+
}
|
|
1884
|
+
else if (!summary) {
|
|
1885
|
+
emit({
|
|
1886
|
+
type: "model_chunk",
|
|
1887
|
+
runId: snapshot.runId,
|
|
1888
|
+
attemptId: snapshot.attemptId,
|
|
1889
|
+
operationId: model.id,
|
|
1890
|
+
chunk,
|
|
1891
|
+
});
|
|
399
1892
|
}
|
|
400
|
-
emit({
|
|
401
|
-
type: "model_chunk",
|
|
402
|
-
runId: snapshot.runId,
|
|
403
|
-
attemptId: snapshot.attemptId,
|
|
404
|
-
operationId: model.id,
|
|
405
|
-
chunk,
|
|
406
|
-
});
|
|
407
1893
|
active();
|
|
408
1894
|
yield chunk;
|
|
409
1895
|
}
|
|
410
1896
|
}
|
|
411
|
-
|
|
1897
|
+
let collected;
|
|
1898
|
+
try {
|
|
1899
|
+
collected = await untilAbort(collectTurn(observed()), signal);
|
|
1900
|
+
}
|
|
1901
|
+
catch (error) {
|
|
1902
|
+
await observe({ type: "model_error", operationId: model.id, attemptId: model.attemptId });
|
|
1903
|
+
active();
|
|
1904
|
+
// Only core's classified provider failures are local model failures. Host/checkpoint
|
|
1905
|
+
// errors and unclassified programming errors must not become benign tool strings.
|
|
1906
|
+
if (!(error instanceof ProviderError)) {
|
|
1907
|
+
if (guarded && !(error instanceof Halt))
|
|
1908
|
+
fail("guarded_model_failed", "The guarded model call failed before its output could be checked. Inspect the provider on the server before starting new work.", model.id);
|
|
1909
|
+
throw error;
|
|
1910
|
+
}
|
|
1911
|
+
if (error.kind === "aborted") {
|
|
1912
|
+
scope.tree.stop();
|
|
1913
|
+
throw new Halt({ status: "cancelled" });
|
|
1914
|
+
}
|
|
1915
|
+
fail("model_failed", guarded
|
|
1916
|
+
? `The model call failed (${error.kind}). Check the provider before starting new work.`
|
|
1917
|
+
: `The model call failed (${error.kind}): ${error.message}`, model.id);
|
|
1918
|
+
}
|
|
1919
|
+
let turn;
|
|
1920
|
+
try {
|
|
1921
|
+
turn = readTurn(collected);
|
|
1922
|
+
}
|
|
1923
|
+
catch (error) {
|
|
1924
|
+
fail("invalid_model_output", guarded
|
|
1925
|
+
? "The provider returned an invalid guarded turn. Check the provider before starting new work."
|
|
1926
|
+
: messageOf(error), model.id);
|
|
1927
|
+
}
|
|
1928
|
+
await observe({ type: "model_end", operationId: model.id, attemptId: model.attemptId, turn });
|
|
1929
|
+
active();
|
|
1930
|
+
await guards.check("modelOutput", model.id, model.attemptId, turn);
|
|
1931
|
+
active();
|
|
412
1932
|
const done = {
|
|
413
1933
|
...model,
|
|
414
1934
|
status: "completed",
|
|
1935
|
+
billing: reportedUsage ? "reported" : "unknown",
|
|
415
1936
|
usage: turn.usage,
|
|
416
1937
|
turn,
|
|
417
1938
|
tools: (turn.message.toolCalls ?? []).map((_call, index) => ({
|
|
418
1939
|
id: toolId(model.id, index),
|
|
419
1940
|
status: "pending",
|
|
1941
|
+
interrupted: [],
|
|
1942
|
+
retries: [],
|
|
420
1943
|
})),
|
|
421
1944
|
};
|
|
422
|
-
|
|
1945
|
+
record(done);
|
|
423
1946
|
await save();
|
|
1947
|
+
if (guarded && !summary) {
|
|
1948
|
+
active();
|
|
1949
|
+
emit({
|
|
1950
|
+
type: "model_chunk",
|
|
1951
|
+
runId: snapshot.runId,
|
|
1952
|
+
attemptId: model.attemptId,
|
|
1953
|
+
operationId: model.id,
|
|
1954
|
+
chunk: guardedChunk(turn),
|
|
1955
|
+
});
|
|
1956
|
+
}
|
|
424
1957
|
return done;
|
|
425
1958
|
}
|
|
426
1959
|
try {
|
|
1960
|
+
// Repair a lost acknowledgement from the saved journal without rereading its payload.
|
|
1961
|
+
// Terminal snapshots synchronize too; this never starts a follow-up model call.
|
|
1962
|
+
if (scope.depth === 0)
|
|
1963
|
+
await acknowledgeInputs(snapshot, options, signal);
|
|
1964
|
+
if (scope.depth === 0 && answers) {
|
|
1965
|
+
await answerRequests(snapshot, options, scope, answers, signal);
|
|
1966
|
+
if ([...requestRecords(snapshot)].some(({ record }) => !record.closed && record.decision?.type === "stop"))
|
|
1967
|
+
scope.tree.stop();
|
|
1968
|
+
await save();
|
|
1969
|
+
}
|
|
427
1970
|
if (snapshot.state.status === "running" || snapshot.state.status === "suspended") {
|
|
428
1971
|
release = await scope.tree.gate.acquire(signal);
|
|
429
1972
|
active();
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
if (
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
fail("invalid_approval", "The pending approval does not belong to an approval-required tool.");
|
|
448
|
-
if (!host?.resolveApproval || !host.beforeTool)
|
|
449
|
-
fail("approval_host_missing", "Provide host.resolveApproval and host.beforeTool to authenticate a decision and recheck access.");
|
|
1973
|
+
requireGuardVerdicts(snapshot);
|
|
1974
|
+
started = true;
|
|
1975
|
+
await observe({ type: "run_start" });
|
|
1976
|
+
active();
|
|
1977
|
+
const last = snapshot.models.at(-1);
|
|
1978
|
+
snapshot.state = { status: "running" };
|
|
1979
|
+
checkMemoryBinding(snapshot, options.memory);
|
|
1980
|
+
if (needsMemory && !options.memory)
|
|
1981
|
+
fail("memory_missing", "Supply authenticated memory access before starting this agent.");
|
|
1982
|
+
if (!options.memory?.scope &&
|
|
1983
|
+
[...capabilities.values()].some((tool) => isMemoryTool(tool) &&
|
|
1984
|
+
!tool.isReadOnly &&
|
|
1985
|
+
snapshot.definition.enabledTools.includes(tool.name)))
|
|
1986
|
+
fail("memory_missing", "Memory writes need an authenticated person's writable scope. Disable save and forget for shared-only access.");
|
|
1987
|
+
if (memory && options.memory && !snapshot.recall) {
|
|
1988
|
+
snapshot.recall = await recallMemory(snapshot, options.memory, signal, scope.handoffInput);
|
|
1989
|
+
// No model sees recall until the existing progress/checkpoint barrier confirms it.
|
|
450
1990
|
await save();
|
|
451
1991
|
active();
|
|
452
|
-
const answer = await untilAbort(Promise.resolve(host.resolveApproval(immutableCopy(approval), immutableCopy(evidence.decision))), signal);
|
|
453
|
-
active();
|
|
454
|
-
if (answer !== "pending") {
|
|
455
|
-
if (answer !== "approved" && answer !== "denied")
|
|
456
|
-
fail("invalid_approval_decision", "The host must return approved, denied or pending.");
|
|
457
|
-
snapshot.state = { status: "running" };
|
|
458
|
-
if (answer === "approved")
|
|
459
|
-
approved = approval;
|
|
460
|
-
else {
|
|
461
|
-
const model = snapshot.models.at(-1);
|
|
462
|
-
if (model?.status !== "completed")
|
|
463
|
-
fail("invalid_journal", "The pending tool turn is missing.");
|
|
464
|
-
const index = model.tools.findIndex((tool) => tool.id === approval.request.operationId);
|
|
465
|
-
if (usedTools() >= limits.toolCalls)
|
|
466
|
-
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
467
|
-
await finishTool(model, index, requestFor(model, index), {
|
|
468
|
-
ok: false,
|
|
469
|
-
kind: "denied",
|
|
470
|
-
content: "The host denied this tool call. Continue without this action.",
|
|
471
|
-
});
|
|
472
|
-
}
|
|
473
|
-
}
|
|
474
1992
|
}
|
|
475
|
-
if (snapshot.
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
1993
|
+
if (snapshot.recall?.status === "failed" && memory?.onError === "fail")
|
|
1994
|
+
fail("memory_unavailable", "Memory could not be read. Check the store before starting a new run.");
|
|
1995
|
+
if (last?.status === "running")
|
|
1996
|
+
await handleTurn(await nextTurn(last));
|
|
1997
|
+
else if (last?.status === "completed") {
|
|
1998
|
+
await recoverTools(last);
|
|
1999
|
+
await handleTurn(last);
|
|
481
2000
|
}
|
|
2001
|
+
while (snapshot.state.status === "running")
|
|
2002
|
+
await handleTurn(await nextTurn());
|
|
482
2003
|
}
|
|
483
2004
|
if (snapshot.state.status === "completed")
|
|
484
|
-
completed = { output:
|
|
2005
|
+
completed = { output: completedOutput(snapshot) };
|
|
485
2006
|
await save();
|
|
486
2007
|
}
|
|
487
2008
|
catch (error) {
|
|
@@ -514,6 +2035,8 @@ export function defineAgent(definition) {
|
|
|
514
2035
|
}
|
|
515
2036
|
finally {
|
|
516
2037
|
release();
|
|
2038
|
+
if (started)
|
|
2039
|
+
await observe({ type: "run_end", state: snapshot.state });
|
|
517
2040
|
clearTimeout(timer);
|
|
518
2041
|
}
|
|
519
2042
|
emit({
|
|
@@ -522,36 +2045,229 @@ export function defineAgent(definition) {
|
|
|
522
2045
|
attemptId: snapshot.attemptId,
|
|
523
2046
|
state: snapshot.state,
|
|
524
2047
|
});
|
|
525
|
-
|
|
2048
|
+
// Includes the final state event, before a child host receipt or session append can land.
|
|
2049
|
+
await host?.progress?.flush();
|
|
2050
|
+
const record = recordOf(snapshot);
|
|
526
2051
|
const state = snapshot.state;
|
|
527
2052
|
if (state.status === "completed") {
|
|
528
2053
|
if (!completed)
|
|
529
2054
|
throw new Error("The agent completed without validating its result.");
|
|
530
2055
|
return { ...record, status: "completed", output: completed.output };
|
|
531
2056
|
}
|
|
532
|
-
return
|
|
2057
|
+
return state.status === "suspended"
|
|
2058
|
+
? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
|
|
2059
|
+
: { ...record, ...state };
|
|
2060
|
+
}
|
|
2061
|
+
function checkInline(start) {
|
|
2062
|
+
const bytes = inlineBytes(start.history, start.input);
|
|
2063
|
+
if (bytes > limits.inlineBytes)
|
|
2064
|
+
throw new TypeError(`The inline images and files come to ${bytes} bytes, and this agent accepts ${limits.inlineBytes}. Send large files as media references, or raise limits.inlineBytes.`);
|
|
2065
|
+
}
|
|
2066
|
+
function freeze(start) {
|
|
2067
|
+
// Once, here: adapters repair every request again, and repair is idempotent, so the
|
|
2068
|
+
// bytes a provider caches never change between turns or across a resume.
|
|
2069
|
+
const history = repairConversation(start.history, (name) => (registry.get(name) ?? codeTools.get(name))?.isReadOnly === true);
|
|
2070
|
+
checkInline({ history, input: start.input });
|
|
2071
|
+
return { ...start, history };
|
|
2072
|
+
}
|
|
2073
|
+
async function create(start, runId, tree, options = {}, subagent) {
|
|
2074
|
+
const frozen = freeze(start);
|
|
2075
|
+
const spec = subagent?.record.spec;
|
|
2076
|
+
const resolved = await resolveDefinition(frozen, spec
|
|
2077
|
+
? {
|
|
2078
|
+
...options,
|
|
2079
|
+
enabledTools: spec.tools,
|
|
2080
|
+
modelSettings: subagent.record.policy.models[spec.model ?? ""]?.settings,
|
|
2081
|
+
}
|
|
2082
|
+
: options, runId, subagent?.source);
|
|
2083
|
+
const record = subagent
|
|
2084
|
+
? { ...copyData(subagent.record), base: copyData(resolved) }
|
|
2085
|
+
: undefined;
|
|
2086
|
+
if (subagent?.record.previousRunId && !equalData(resolved, subagent.source))
|
|
2087
|
+
throw new TypeError("The helper's admitted definition changed. Restore its original configuration before continuing.");
|
|
2088
|
+
if (spec)
|
|
2089
|
+
resolved.instructions = subagentInstructions(resolved.instructions, spec.instructions);
|
|
2090
|
+
const childLimits = spec ? subagentLimits(limits, spec.limits) : limits;
|
|
2091
|
+
if (inlineBytes(frozen.history, frozen.input) > childLimits.inlineBytes)
|
|
2092
|
+
throw new TypeError("The helper input exceeds its admitted inline byte limit.");
|
|
2093
|
+
const { history, input, session } = frozen;
|
|
2094
|
+
const startedAt = Date.now();
|
|
2095
|
+
return {
|
|
2096
|
+
kind: "agent",
|
|
2097
|
+
format: 3,
|
|
2098
|
+
agentId: id,
|
|
2099
|
+
version,
|
|
2100
|
+
runId,
|
|
2101
|
+
attemptId: crypto.randomUUID(),
|
|
2102
|
+
startedAt,
|
|
2103
|
+
definition: resolved,
|
|
2104
|
+
...(record ? { subagent: record } : {}),
|
|
2105
|
+
history: copyData(history),
|
|
2106
|
+
input: copyData(input),
|
|
2107
|
+
inputs: [],
|
|
2108
|
+
guards: [],
|
|
2109
|
+
compactions: [],
|
|
2110
|
+
...(session ? { session: copyData(session) } : {}),
|
|
2111
|
+
limits: copyData(childLimits),
|
|
2112
|
+
models: [],
|
|
2113
|
+
delegations: [],
|
|
2114
|
+
state: { status: "running" },
|
|
2115
|
+
tree: tree
|
|
2116
|
+
? copyData(tree)
|
|
2117
|
+
: {
|
|
2118
|
+
runId,
|
|
2119
|
+
startedAt,
|
|
2120
|
+
limits: copyData(treeLimits),
|
|
2121
|
+
...(options.memory ? { memory: memoryScopes(options.memory) } : {}),
|
|
2122
|
+
},
|
|
2123
|
+
};
|
|
533
2124
|
}
|
|
534
2125
|
const runtime = {
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
2126
|
+
node: {
|
|
2127
|
+
restore: (raw, tree, subagent) => runtime.restore(raw, tree, subagent),
|
|
2128
|
+
hydrate: (node) => runtime.hydrate(agentSnapshot(node)),
|
|
2129
|
+
answerRequests: (node, options, scope, answers, signal) => answerRequests(agentSnapshot(node), options, scope, answers, signal),
|
|
2130
|
+
execute: (node, options, scope, answers) => execute(agentSnapshot(node), options, scope, answers),
|
|
2131
|
+
},
|
|
2132
|
+
handoffs: [...handoffs.values()],
|
|
2133
|
+
tools: Object.freeze([...capabilities.values()]),
|
|
2134
|
+
enabledTools: Array.isArray(enabledTools) ? Object.freeze([...enabledTools]) : undefined,
|
|
2135
|
+
limits: immutableCopy(limits),
|
|
2136
|
+
async checkTools(snapshot, options) {
|
|
2137
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
2138
|
+
const current = checkNames(typeof enabledTools === "function"
|
|
2139
|
+
? await untilAbort(Promise.resolve(enabledTools(Object.freeze({
|
|
2140
|
+
agentId: id,
|
|
2141
|
+
version,
|
|
2142
|
+
runId: snapshot.runId,
|
|
2143
|
+
...immutableCopy({ history: snapshot.history, input: snapshot.input }),
|
|
2144
|
+
context: Object.freeze({ ...options.context }),
|
|
2145
|
+
signal,
|
|
2146
|
+
}))), signal)
|
|
2147
|
+
: (enabledTools ?? names));
|
|
2148
|
+
if (snapshot.definition.enabledTools.some((name) => name !== RESULT_TOOL_NAME && !current.includes(name)))
|
|
2149
|
+
fail("subagent_grant_changed", "The host revoked a helper capability. Obtain fresh authorization before starting different work.");
|
|
2150
|
+
},
|
|
2151
|
+
configuration() {
|
|
2152
|
+
const { onActivity: _activity, onRateLimit: _rateLimit, ...modelSettings } = settings;
|
|
2153
|
+
return immutableCopy({
|
|
2154
|
+
id,
|
|
541
2155
|
version,
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
limits
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
2156
|
+
provider: { id: provider.id, model: provider.model },
|
|
2157
|
+
instructions: typeof instructions === "string" ? instructions : null,
|
|
2158
|
+
enabledTools: Array.isArray(enabledTools) ? enabledTools : null,
|
|
2159
|
+
modelSettings,
|
|
2160
|
+
limits,
|
|
2161
|
+
output: output?.schema ?? null,
|
|
2162
|
+
stopAtTools,
|
|
2163
|
+
recovery,
|
|
2164
|
+
guardrails: guardPolicy,
|
|
2165
|
+
compaction,
|
|
2166
|
+
toolRetries,
|
|
2167
|
+
...(memory ? { memory } : {}),
|
|
2168
|
+
tools: tools.map((tool) => ({
|
|
2169
|
+
definition: tool.definition(),
|
|
2170
|
+
needsApproval: tool.needsApproval === true,
|
|
2171
|
+
...(isDelegation(tool)
|
|
2172
|
+
? {
|
|
2173
|
+
kind: "delegation",
|
|
2174
|
+
specialists: tool.specialists.map(({ id, version }) => ({ id, version })),
|
|
2175
|
+
}
|
|
2176
|
+
: isHandoff(tool)
|
|
2177
|
+
? { kind: "handoff", target: handoffRef(tool.target()) }
|
|
2178
|
+
: isCodeTool(tool)
|
|
2179
|
+
? {
|
|
2180
|
+
kind: "code",
|
|
2181
|
+
limits: tool.limits,
|
|
2182
|
+
bindings: tool.tools.map((bound) => ({
|
|
2183
|
+
definition: bound.definition(),
|
|
2184
|
+
outputSchema: bound.outputSchema,
|
|
2185
|
+
isReadOnly: bound.isReadOnly,
|
|
2186
|
+
needsApproval: bound.needsApproval,
|
|
2187
|
+
isConcurrencySafe: bound.isConcurrencySafe,
|
|
2188
|
+
timeoutMs: bound.timeoutMs,
|
|
2189
|
+
})),
|
|
2190
|
+
}
|
|
2191
|
+
: isClientTool(tool)
|
|
2192
|
+
? { kind: "client", resultSchema: tool.resultSchema }
|
|
2193
|
+
: {
|
|
2194
|
+
kind: "tool",
|
|
2195
|
+
isReadOnly: tool.isReadOnly === true,
|
|
2196
|
+
isConcurrencySafe: tool.isConcurrencySafe === true,
|
|
2197
|
+
isTerminal: tool.isTerminal === true,
|
|
2198
|
+
}),
|
|
2199
|
+
})),
|
|
2200
|
+
});
|
|
552
2201
|
},
|
|
553
|
-
|
|
554
|
-
|
|
2202
|
+
execute,
|
|
2203
|
+
answerRequests,
|
|
2204
|
+
freeze,
|
|
2205
|
+
create,
|
|
2206
|
+
async open(input, options, runId) {
|
|
2207
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
2208
|
+
if (needsMemory && !options.memory)
|
|
2209
|
+
throw new TypeError("This agent needs authenticated memory access in RunOptions.memory.");
|
|
2210
|
+
// Everything before the snapshot exists runs outside the journal: a paid summarizer in
|
|
2211
|
+
// prepareHistory can run again if the process dies before the first checkpoint.
|
|
2212
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
2213
|
+
const session = options.session;
|
|
2214
|
+
let start;
|
|
2215
|
+
if (session) {
|
|
2216
|
+
if (isRecord(input) && "messages" in input)
|
|
2217
|
+
throw new TypeError("With a session, pass only the new turn. The session holds the history.");
|
|
2218
|
+
// Checked before the load, so a turn that would be refused costs no read.
|
|
2219
|
+
const turn = readInput(input, "caller").input;
|
|
2220
|
+
checkInline({ history: [], input: turn });
|
|
2221
|
+
const loaded = await untilAbort(Promise.resolve(session.load({
|
|
2222
|
+
...(options.historyLimit !== undefined ? { limit: options.historyLimit } : {}),
|
|
2223
|
+
signal,
|
|
2224
|
+
})), signal);
|
|
2225
|
+
if (!isRecord(loaded) || !isRevision(loaded.revision))
|
|
2226
|
+
throw new TypeError("session.load must return { messages, revision }.");
|
|
2227
|
+
start = {
|
|
2228
|
+
history: readStored(loaded.messages, "session.load"),
|
|
2229
|
+
input: turn,
|
|
2230
|
+
session: { id: session.id, revision: loaded.revision },
|
|
2231
|
+
};
|
|
2232
|
+
}
|
|
2233
|
+
else {
|
|
2234
|
+
if (options.historyLimit !== undefined)
|
|
2235
|
+
throw new TypeError("historyLimit applies to a session. Trim the messages you pass in yourself.");
|
|
2236
|
+
start = readInput(input, "caller");
|
|
2237
|
+
}
|
|
2238
|
+
if (options.prepareHistory) {
|
|
2239
|
+
const prepared = await untilAbort(Promise.resolve(options.prepareHistory(copyData(start.history))), signal);
|
|
2240
|
+
start = { ...start, history: readStored(prepared, "prepareHistory") };
|
|
2241
|
+
}
|
|
2242
|
+
return create(start, runId, undefined, options);
|
|
2243
|
+
},
|
|
2244
|
+
restore(raw, tree, subagent) {
|
|
2245
|
+
if (isRecord(raw) && (!equalData(raw.subagent, subagent) || (subagent && !tree)))
|
|
2246
|
+
throw new TypeError("Restore a model-created helper through its owning creation tool.");
|
|
2247
|
+
const snapshot = readSnapshot(raw, id, version, subagent ? subagentLimits(limits, subagent.spec.limits) : limits, output ? RESULT_TOOL_NAME : undefined, codeTools);
|
|
2248
|
+
checkNames(snapshot.definition.enabledTools);
|
|
2249
|
+
if (!equalData(snapshot.definition.memory, memory))
|
|
2250
|
+
throw new TypeError("Restore the same memory recall policy before resuming.");
|
|
2251
|
+
if (!equalData(snapshot.definition.compaction, compaction) ||
|
|
2252
|
+
!equalData(snapshot.definition.toolRetries?.policy ?? null, toolRetries))
|
|
2253
|
+
throw new TypeError("The recorded compaction or tool retry policy changed. Restore the same definition before resuming.");
|
|
2254
|
+
if (!equalData(snapshot.definition.guardrails, guardPolicy))
|
|
2255
|
+
throw new TypeError("The recorded guard policy changed. Restore the same guard identity, stages and limits.");
|
|
2256
|
+
if (!equalData(snapshot.definition.recovery?.policy ?? null, recovery) ||
|
|
2257
|
+
(snapshot.definition.recovery &&
|
|
2258
|
+
!equalData(snapshot.definition.recovery.provider, {
|
|
2259
|
+
id: provider.id,
|
|
2260
|
+
model: provider.model,
|
|
2261
|
+
})))
|
|
2262
|
+
throw new TypeError("The recorded recovery policy or provider identity changed. Restore the same profile or reconcile the run.");
|
|
2263
|
+
if (!equalData(snapshot.definition.stopAtTools, stopAtTools) ||
|
|
2264
|
+
(output && !snapshot.definition.enabledTools.includes(RESULT_TOOL_NAME)))
|
|
2265
|
+
throw new TypeError("The recorded tool behavior does not match this agent version.");
|
|
2266
|
+
const choice = snapshot.definition.modelSettings.toolChoice;
|
|
2267
|
+
if ((output && choice === "none") ||
|
|
2268
|
+
(choice === "required" && snapshot.definition.enabledTools.length === 0) ||
|
|
2269
|
+
(typeof choice === "object" && !snapshot.definition.enabledTools.includes(choice.name)))
|
|
2270
|
+
throw new TypeError("The recorded tool choice does not name an enabled tool.");
|
|
555
2271
|
if (tree
|
|
556
2272
|
? !equalData(snapshot.tree, tree)
|
|
557
2273
|
: snapshot.tree.runId !== snapshot.runId || !equalData(snapshot.tree.limits, treeLimits))
|
|
@@ -561,7 +2277,10 @@ export function defineAgent(definition) {
|
|
|
561
2277
|
continue;
|
|
562
2278
|
for (const [index, tool] of model.tools.entries()) {
|
|
563
2279
|
const call = model.turn.message.toolCalls?.[index];
|
|
564
|
-
const descriptor = call &&
|
|
2280
|
+
const descriptor = call &&
|
|
2281
|
+
snapshot.definition.enabledTools.includes(call.name) &&
|
|
2282
|
+
snapshot.definition.modelSettings.toolChoice !== "none" &&
|
|
2283
|
+
descriptorFor(call.name, snapshot, tool.id);
|
|
565
2284
|
const journal = snapshot.delegations.find((entry) => entry.operationId === tool.id);
|
|
566
2285
|
if (descriptor && tool.status !== "pending") {
|
|
567
2286
|
if (!journal || tool.status === "running")
|
|
@@ -571,38 +2290,92 @@ export function defineAgent(definition) {
|
|
|
571
2290
|
throw new TypeError("The saved delegation is not in this agent definition.");
|
|
572
2291
|
if (!journal || !descriptor)
|
|
573
2292
|
continue;
|
|
2293
|
+
if (journal.kind !== (call && handoffs.has(call.name) ? "handoff" : "delegation"))
|
|
2294
|
+
throw new TypeError("The saved delegation kind does not match its registered tool.");
|
|
2295
|
+
if (journal.kind === "handoff")
|
|
2296
|
+
checkHandoffTargets(agent);
|
|
2297
|
+
checkSubagentChildren(descriptor, snapshot, journal);
|
|
574
2298
|
for (const entry of journal.children) {
|
|
575
|
-
const agent = descriptor.specialists.find((agent) => agent.
|
|
2299
|
+
const agent = descriptor.specialists.find((agent) => agent.kind === entry.snapshot.kind &&
|
|
2300
|
+
agent.id === nodeId(entry.snapshot) &&
|
|
2301
|
+
agent.version === entry.snapshot.version);
|
|
576
2302
|
if (!agent)
|
|
577
2303
|
throw new TypeError("The saved child is not a registered specialist version.");
|
|
578
|
-
entry.snapshot = agent
|
|
2304
|
+
entry.snapshot = runtimeOf(agent).restore(entry.snapshot, snapshot.tree, entry.snapshot.kind === "agent" ? entry.snapshot.subagent : undefined);
|
|
579
2305
|
}
|
|
580
2306
|
}
|
|
581
2307
|
}
|
|
582
2308
|
if (snapshot.state.status === "completed")
|
|
583
|
-
|
|
2309
|
+
completedOutput(snapshot);
|
|
584
2310
|
return snapshot;
|
|
585
2311
|
},
|
|
586
2312
|
hydrate(snapshot) {
|
|
587
|
-
const record = recordOf(snapshot
|
|
2313
|
+
const record = recordOf(snapshot);
|
|
588
2314
|
const state = record.snapshot.state;
|
|
589
2315
|
if (state.status === "running")
|
|
590
2316
|
throw new Error("A child has not settled yet.");
|
|
591
2317
|
return state.status === "completed"
|
|
592
|
-
? { ...record, status: "completed", output:
|
|
593
|
-
:
|
|
2318
|
+
? { ...record, status: "completed", output: completedOutput(record.snapshot) }
|
|
2319
|
+
: state.status === "suspended"
|
|
2320
|
+
? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
|
|
2321
|
+
: { ...record, ...state };
|
|
594
2322
|
},
|
|
595
2323
|
};
|
|
596
|
-
|
|
2324
|
+
/** Once per root, after its final checkpoint. Never changes the run's own status. */
|
|
2325
|
+
async function appendTurn(outcome, options, tree) {
|
|
2326
|
+
const ref = outcome.snapshot.session;
|
|
2327
|
+
if (!ref)
|
|
2328
|
+
return undefined;
|
|
2329
|
+
const session = options.session;
|
|
2330
|
+
// A waiting run has no settled turn yet. After a failed checkpoint the host's journal is
|
|
2331
|
+
// behind this outcome: resuming what it saved settles again and appends then.
|
|
2332
|
+
if (!session || outcome.status === "suspended" || tree.checkpointFailed)
|
|
2333
|
+
return { id: ref.id, status: "pending" };
|
|
2334
|
+
// A Stop ends the run, not the record of it: the turn the person sent is still saved.
|
|
2335
|
+
const signal = options.signal && !options.signal.aborted ? options.signal : new AbortController().signal;
|
|
2336
|
+
try {
|
|
2337
|
+
const saved = await untilAbort(Promise.resolve(session.append(immutableCopy({
|
|
2338
|
+
runId: outcome.runId,
|
|
2339
|
+
after: ref.revision,
|
|
2340
|
+
messages: outcome.newMessages,
|
|
2341
|
+
}), { signal })), signal);
|
|
2342
|
+
if (!isRecord(saved) || !isId(saved.revision))
|
|
2343
|
+
throw new TypeError("session.append returned no revision.");
|
|
2344
|
+
return { id: ref.id, status: "saved", revision: saved.revision };
|
|
2345
|
+
}
|
|
2346
|
+
catch (error) {
|
|
2347
|
+
// By name, not instanceof: a store built against another copy of this package throws
|
|
2348
|
+
// its own SessionConflictError class.
|
|
2349
|
+
const conflict = error instanceof Error && error.name === "SessionConflictError";
|
|
2350
|
+
return {
|
|
2351
|
+
id: ref.id,
|
|
2352
|
+
status: "unsaved",
|
|
2353
|
+
error: conflict
|
|
2354
|
+
? {
|
|
2355
|
+
code: "session_conflict",
|
|
2356
|
+
message: "The conversation changed after this run loaded it. Load it again before you continue it.",
|
|
2357
|
+
}
|
|
2358
|
+
: {
|
|
2359
|
+
code: "session_failed",
|
|
2360
|
+
message: `The session did not save this turn: ${messageOf(error)}`,
|
|
2361
|
+
},
|
|
2362
|
+
};
|
|
2363
|
+
}
|
|
2364
|
+
}
|
|
2365
|
+
async function root(snapshot, options, answers) {
|
|
597
2366
|
const tree = new ExecutionTree(snapshot, options);
|
|
2367
|
+
let outcome;
|
|
598
2368
|
try {
|
|
599
|
-
|
|
2369
|
+
outcome = await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
|
|
600
2370
|
}
|
|
601
2371
|
finally {
|
|
602
2372
|
tree.close();
|
|
603
2373
|
}
|
|
2374
|
+
const session = await appendTurn(outcome, options, tree);
|
|
2375
|
+
return session ? { ...outcome, session } : outcome;
|
|
604
2376
|
}
|
|
605
2377
|
const agent = {
|
|
2378
|
+
kind: "agent",
|
|
606
2379
|
id,
|
|
607
2380
|
version,
|
|
608
2381
|
[AGENT_RUNTIME]: runtime,
|
|
@@ -610,25 +2383,23 @@ export function defineAgent(definition) {
|
|
|
610
2383
|
return specialistTool(agent, options);
|
|
611
2384
|
},
|
|
612
2385
|
async run(input, options = {}) {
|
|
613
|
-
if (!isId(input))
|
|
614
|
-
throw new TypeError("Give the agent a non-empty text input.");
|
|
615
2386
|
checkOptions(options);
|
|
616
|
-
|
|
2387
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
2388
|
+
return root(await runtime.open(input, options, options.runId ?? crypto.randomUUID()), options);
|
|
617
2389
|
},
|
|
618
2390
|
async resume(raw, options) {
|
|
619
|
-
checkOptions(options);
|
|
2391
|
+
checkOptions(options, "resume");
|
|
2392
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
620
2393
|
const snapshot = runtime.restore(raw);
|
|
621
|
-
|
|
622
|
-
if (options.
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
evidence = copyData({ path: snapshot.state.path, decision: options.decision });
|
|
628
|
-
}
|
|
2394
|
+
checkMemoryBinding(snapshot, options.memory);
|
|
2395
|
+
if (options.session && options.session.id !== snapshot.session?.id)
|
|
2396
|
+
throw new TypeError(snapshot.session
|
|
2397
|
+
? "This run belongs to another session."
|
|
2398
|
+
: "This run has no session. Resume it without one.");
|
|
2399
|
+
const answers = readAnswers(snapshot, options.answers ?? {});
|
|
629
2400
|
await authorizeTree(snapshot, options.host);
|
|
630
2401
|
snapshot.attemptId = crypto.randomUUID();
|
|
631
|
-
return root(snapshot, options,
|
|
2402
|
+
return root(snapshot, options, answers);
|
|
632
2403
|
},
|
|
633
2404
|
};
|
|
634
2405
|
return Object.freeze(agent);
|