@providerkit/agents 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE-APACHE-2.0 +202 -0
- package/README.md +2108 -52
- package/THIRD_PARTY_NOTICES.md +521 -0
- package/dist/a2a/auth.d.ts +10 -0
- package/dist/a2a/auth.d.ts.map +1 -0
- package/dist/a2a/auth.js +52 -0
- package/dist/a2a/auth.js.map +1 -0
- package/dist/a2a/client.d.ts +74 -0
- package/dist/a2a/client.d.ts.map +1 -0
- package/dist/a2a/client.js +601 -0
- package/dist/a2a/client.js.map +1 -0
- package/dist/a2a/index.d.ts +22 -0
- package/dist/a2a/index.d.ts.map +1 -0
- package/dist/a2a/index.js +11 -0
- package/dist/a2a/index.js.map +1 -0
- package/dist/a2a/memory-runs.d.ts +62 -0
- package/dist/a2a/memory-runs.d.ts.map +1 -0
- package/dist/a2a/memory-runs.js +349 -0
- package/dist/a2a/memory-runs.js.map +1 -0
- package/dist/a2a/policy.d.ts +15 -0
- package/dist/a2a/policy.d.ts.map +1 -0
- package/dist/a2a/policy.js +114 -0
- package/dist/a2a/policy.js.map +1 -0
- package/dist/a2a/push.d.ts +34 -0
- package/dist/a2a/push.d.ts.map +1 -0
- package/dist/a2a/push.js +180 -0
- package/dist/a2a/push.js.map +1 -0
- package/dist/a2a/remote.d.ts +155 -0
- package/dist/a2a/remote.d.ts.map +1 -0
- package/dist/a2a/remote.js +1196 -0
- package/dist/a2a/remote.js.map +1 -0
- package/dist/a2a/server.d.ts +110 -0
- package/dist/a2a/server.d.ts.map +1 -0
- package/dist/a2a/server.js +1139 -0
- package/dist/a2a/server.js.map +1 -0
- package/dist/a2a/signing.d.ts +21 -0
- package/dist/a2a/signing.d.ts.map +1 -0
- package/dist/a2a/signing.js +305 -0
- package/dist/a2a/signing.js.map +1 -0
- package/dist/a2a/tasks.d.ts +88 -0
- package/dist/a2a/tasks.d.ts.map +1 -0
- package/dist/a2a/tasks.js +170 -0
- package/dist/a2a/tasks.js.map +1 -0
- package/dist/a2a/wire.d.ts +267 -0
- package/dist/a2a/wire.d.ts.map +1 -0
- package/dist/a2a/wire.js +1202 -0
- package/dist/a2a/wire.js.map +1 -0
- package/dist/background-types.d.ts +76 -0
- package/dist/background-types.d.ts.map +1 -0
- package/dist/background-types.js +2 -0
- package/dist/background-types.js.map +1 -0
- package/dist/child.d.ts +25 -0
- package/dist/child.d.ts.map +1 -0
- package/dist/child.js +129 -0
- package/dist/child.js.map +1 -0
- package/dist/code-driver.d.ts +40 -0
- package/dist/code-driver.d.ts.map +1 -0
- package/dist/code-driver.js +2 -0
- package/dist/code-driver.js.map +1 -0
- package/dist/code-mode.d.ts +3 -0
- package/dist/code-mode.d.ts.map +1 -0
- package/dist/code-mode.js +2 -0
- package/dist/code-mode.js.map +1 -0
- package/dist/code-script.d.ts +3 -0
- package/dist/code-script.d.ts.map +1 -0
- package/dist/code-script.js +149 -0
- package/dist/code-script.js.map +1 -0
- package/dist/code.d.ts +75 -0
- package/dist/code.d.ts.map +1 -0
- package/dist/code.js +326 -0
- package/dist/code.js.map +1 -0
- package/dist/compaction.d.ts +15 -0
- package/dist/compaction.d.ts.map +1 -0
- package/dist/compaction.js +168 -0
- package/dist/compaction.js.map +1 -0
- package/dist/delegation.d.ts +85 -16
- package/dist/delegation.d.ts.map +1 -1
- package/dist/delegation.js +240 -106
- package/dist/delegation.js.map +1 -1
- package/dist/evals/driver.d.ts +10 -0
- package/dist/evals/driver.d.ts.map +1 -0
- package/dist/evals/driver.js +192 -0
- package/dist/evals/driver.js.map +1 -0
- package/dist/evals/journal.d.ts +26 -0
- package/dist/evals/journal.d.ts.map +1 -0
- package/dist/evals/journal.js +483 -0
- package/dist/evals/journal.js.map +1 -0
- package/dist/evals/judge.d.ts +31 -0
- package/dist/evals/judge.d.ts.map +1 -0
- package/dist/evals/judge.js +142 -0
- package/dist/evals/judge.js.map +1 -0
- package/dist/evals/report.d.ts +38 -0
- package/dist/evals/report.d.ts.map +1 -0
- package/dist/evals/report.js +241 -0
- package/dist/evals/report.js.map +1 -0
- package/dist/evals/runner.d.ts +24 -0
- package/dist/evals/runner.d.ts.map +1 -0
- package/dist/evals/runner.js +655 -0
- package/dist/evals/runner.js.map +1 -0
- package/dist/evals/scorers.d.ts +36 -0
- package/dist/evals/scorers.d.ts.map +1 -0
- package/dist/evals/scorers.js +259 -0
- package/dist/evals/scorers.js.map +1 -0
- package/dist/evals/simulation.d.ts +7 -0
- package/dist/evals/simulation.d.ts.map +1 -0
- package/dist/evals/simulation.js +38 -0
- package/dist/evals/simulation.js.map +1 -0
- package/dist/evals/testing.d.ts +36 -0
- package/dist/evals/testing.d.ts.map +1 -0
- package/dist/evals/testing.js +87 -0
- package/dist/evals/testing.js.map +1 -0
- package/dist/evals/trajectory.d.ts +11 -0
- package/dist/evals/trajectory.d.ts.map +1 -0
- package/dist/evals/trajectory.js +180 -0
- package/dist/evals/trajectory.js.map +1 -0
- package/dist/evals/types.d.ts +431 -0
- package/dist/evals/types.d.ts.map +1 -0
- package/dist/evals/types.js +4 -0
- package/dist/evals/types.js.map +1 -0
- package/dist/evals.d.ts +14 -0
- package/dist/evals.d.ts.map +1 -0
- package/dist/evals.js +9 -0
- package/dist/evals.js.map +1 -0
- package/dist/extensions.d.ts +33 -0
- package/dist/extensions.d.ts.map +1 -0
- package/dist/extensions.js +188 -0
- package/dist/extensions.js.map +1 -0
- package/dist/handoff.d.ts +58 -0
- package/dist/handoff.d.ts.map +1 -0
- package/dist/handoff.js +160 -0
- package/dist/handoff.js.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -1
- package/dist/input.d.ts +42 -0
- package/dist/input.d.ts.map +1 -0
- package/dist/input.js +266 -0
- package/dist/input.js.map +1 -0
- package/dist/mcp.d.ts +77 -0
- package/dist/mcp.d.ts.map +1 -0
- package/dist/mcp.js +505 -0
- package/dist/mcp.js.map +1 -0
- package/dist/memory-store.d.ts +11 -0
- package/dist/memory-store.d.ts.map +1 -0
- package/dist/memory-store.js +272 -0
- package/dist/memory-store.js.map +1 -0
- package/dist/memory.d.ts +212 -0
- package/dist/memory.d.ts.map +1 -0
- package/dist/memory.js +613 -0
- package/dist/memory.js.map +1 -0
- package/dist/otel.d.ts +74 -0
- package/dist/otel.d.ts.map +1 -0
- package/dist/otel.js +427 -0
- package/dist/otel.js.map +1 -0
- package/dist/progress.d.ts +17 -0
- package/dist/progress.d.ts.map +1 -0
- package/dist/progress.js +193 -0
- package/dist/progress.js.map +1 -0
- package/dist/quickjs.d.ts +19 -0
- package/dist/quickjs.d.ts.map +1 -0
- package/dist/quickjs.js +519 -0
- package/dist/quickjs.js.map +1 -0
- package/dist/recovery.d.ts +10 -0
- package/dist/recovery.d.ts.map +1 -0
- package/dist/recovery.js +62 -0
- package/dist/recovery.js.map +1 -0
- package/dist/request.d.ts +88 -0
- package/dist/request.d.ts.map +1 -0
- package/dist/request.js +422 -0
- package/dist/request.js.map +1 -0
- package/dist/run.d.ts +16 -4
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +2016 -245
- package/dist/run.js.map +1 -1
- package/dist/runs.d.ts +77 -34
- package/dist/runs.d.ts.map +1 -1
- package/dist/runs.js +267 -85
- package/dist/runs.js.map +1 -1
- package/dist/schema-to-ts.d.ts +4 -0
- package/dist/schema-to-ts.d.ts.map +1 -0
- package/dist/schema-to-ts.js +191 -0
- package/dist/schema-to-ts.js.map +1 -0
- package/dist/session.d.ts +23 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +137 -0
- package/dist/session.js.map +1 -0
- package/dist/snapshot.d.ts +57 -8
- package/dist/snapshot.d.ts.map +1 -1
- package/dist/snapshot.js +1206 -109
- package/dist/snapshot.js.map +1 -1
- package/dist/steering.d.ts +75 -0
- package/dist/steering.d.ts.map +1 -0
- package/dist/steering.js +214 -0
- package/dist/steering.js.map +1 -0
- package/dist/subagents.d.ts +141 -0
- package/dist/subagents.d.ts.map +1 -0
- package/dist/subagents.js +746 -0
- package/dist/subagents.js.map +1 -0
- package/dist/tool-retry.d.ts +12 -0
- package/dist/tool-retry.d.ts.map +1 -0
- package/dist/tool-retry.js +53 -0
- package/dist/tool-retry.js.map +1 -0
- package/dist/tree.d.ts +62 -6
- package/dist/tree.d.ts.map +1 -1
- package/dist/tree.js +192 -23
- package/dist/tree.js.map +1 -1
- package/dist/types.d.ts +767 -52
- package/dist/types.d.ts.map +1 -1
- package/dist/workflow-snapshot.d.ts +8 -0
- package/dist/workflow-snapshot.d.ts.map +1 -0
- package/dist/workflow-snapshot.js +276 -0
- package/dist/workflow-snapshot.js.map +1 -0
- package/dist/workflow-types.d.ts +171 -0
- package/dist/workflow-types.d.ts.map +1 -0
- package/dist/workflow-types.js +2 -0
- package/dist/workflow-types.js.map +1 -0
- package/dist/workflow.d.ts +19 -0
- package/dist/workflow.d.ts.map +1 -0
- package/dist/workflow.js +1053 -0
- package/dist/workflow.js.map +1 -0
- package/examples/a2a-remote.ts +85 -0
- package/examples/a2a-server.ts +100 -0
- package/examples/background.ts +18 -4
- package/examples/code-mode.ts +76 -0
- package/examples/conversation.ts +57 -0
- package/examples/evals.ts +79 -0
- package/examples/guardrails.ts +56 -0
- package/examples/handoff.ts +79 -0
- package/examples/memory.ts +44 -0
- package/examples/otel.ts +99 -0
- package/examples/steering.ts +69 -0
- package/examples/structured-handoff.ts +92 -0
- package/examples/subagents.ts +127 -0
- package/examples/workflow.ts +74 -0
- package/package.json +58 -6
- package/src/a2a/auth.ts +62 -0
- package/src/a2a/client.ts +733 -0
- package/src/a2a/index.ts +74 -0
- package/src/a2a/memory-runs.ts +448 -0
- package/src/a2a/policy.ts +148 -0
- package/src/a2a/push.ts +251 -0
- package/src/a2a/remote.ts +1652 -0
- package/src/a2a/server.ts +1390 -0
- package/src/a2a/signing.ts +348 -0
- package/src/a2a/tasks.ts +260 -0
- package/src/a2a/wire.ts +1443 -0
- package/src/background-types.ts +86 -0
- package/src/child.ts +181 -0
- package/src/code-driver.ts +48 -0
- package/src/code-mode.ts +12 -0
- package/src/code-script.ts +149 -0
- package/src/code.ts +424 -0
- package/src/compaction.ts +212 -0
- package/src/delegation.ts +444 -155
- package/src/evals/driver.ts +222 -0
- package/src/evals/journal.ts +605 -0
- package/src/evals/judge.ts +188 -0
- package/src/evals/report.ts +295 -0
- package/src/evals/runner.ts +826 -0
- package/src/evals/scorers.ts +339 -0
- package/src/evals/simulation.ts +46 -0
- package/src/evals/testing.ts +126 -0
- package/src/evals/trajectory.ts +223 -0
- package/src/evals/types.ts +463 -0
- package/src/evals.ts +72 -0
- package/src/extensions.ts +247 -0
- package/src/handoff.ts +214 -0
- package/src/index.ts +51 -0
- package/src/input.ts +319 -0
- package/src/mcp.ts +690 -0
- package/src/memory-store.ts +366 -0
- package/src/memory.ts +893 -0
- package/src/otel.ts +568 -0
- package/src/progress.ts +214 -0
- package/src/quickjs.ts +524 -0
- package/src/recovery.ts +90 -0
- package/src/request.ts +513 -0
- package/src/run.ts +2678 -313
- package/src/runs.ts +464 -133
- package/src/schema-to-ts.ts +194 -0
- package/src/session.ts +178 -0
- package/src/snapshot.ts +1595 -124
- package/src/steering.ts +329 -0
- package/src/subagents.ts +1084 -0
- package/src/tool-retry.ts +86 -0
- package/src/tree.ts +223 -27
- package/src/types.ts +711 -52
- package/src/workflow-snapshot.ts +366 -0
- package/src/workflow-types.ts +213 -0
- package/src/workflow.ts +1316 -0
package/src/run.ts
CHANGED
|
@@ -1,48 +1,133 @@
|
|
|
1
1
|
import {
|
|
2
2
|
EMPTY_USAGE,
|
|
3
|
+
ProviderError,
|
|
3
4
|
ToolRegistry,
|
|
4
|
-
addUsage,
|
|
5
5
|
collectTurn,
|
|
6
|
+
createGate,
|
|
6
7
|
defineTool,
|
|
7
8
|
messageOf,
|
|
8
9
|
parseToolArgs,
|
|
9
|
-
type
|
|
10
|
+
type Provider,
|
|
10
11
|
type ProviderChunk,
|
|
11
12
|
type Tool,
|
|
12
13
|
} from "@providerkit/core";
|
|
14
|
+
import {
|
|
15
|
+
bindMemoryTool,
|
|
16
|
+
checkMemoryBinding,
|
|
17
|
+
isMemoryTool,
|
|
18
|
+
memoryPolicy,
|
|
19
|
+
memoryScopes,
|
|
20
|
+
MEMORY_TOOL_NAMES,
|
|
21
|
+
readMemoryBinding,
|
|
22
|
+
recallMemory,
|
|
23
|
+
withMemoryRecall,
|
|
24
|
+
} from "./memory.ts";
|
|
25
|
+
import {
|
|
26
|
+
allModels,
|
|
27
|
+
compactionDefinition,
|
|
28
|
+
compactionId,
|
|
29
|
+
compactionPlan,
|
|
30
|
+
modelConversation,
|
|
31
|
+
} from "./compaction.ts";
|
|
32
|
+
import {
|
|
33
|
+
bindSubagentTool,
|
|
34
|
+
checkSubagentChildren,
|
|
35
|
+
subagentInstructions,
|
|
36
|
+
subagentLimits,
|
|
37
|
+
type SubagentCreation,
|
|
38
|
+
} from "./subagents.ts";
|
|
39
|
+
import {
|
|
40
|
+
isCodeTool,
|
|
41
|
+
programJson,
|
|
42
|
+
programReceipt,
|
|
43
|
+
programReply,
|
|
44
|
+
textBytes,
|
|
45
|
+
type CodeTool,
|
|
46
|
+
} from "./code.ts";
|
|
47
|
+
import { checkRetryTool, readToolRetryPolicy, retryBudget, toolAttempts } from "./tool-retry.ts";
|
|
48
|
+
import {
|
|
49
|
+
GuardChecks,
|
|
50
|
+
GUARDED_CHUNK_LIMIT,
|
|
51
|
+
guardDefinition,
|
|
52
|
+
guardedChunk,
|
|
53
|
+
jsonBytes,
|
|
54
|
+
observeLifecycle,
|
|
55
|
+
refuseGuardedReplay,
|
|
56
|
+
requireGuardVerdicts,
|
|
57
|
+
successfulToolResult,
|
|
58
|
+
toolResultOf,
|
|
59
|
+
} from "./extensions.ts";
|
|
13
60
|
import {
|
|
14
61
|
AGENT_RUNTIME,
|
|
15
62
|
executeDelegation,
|
|
16
63
|
isDelegation,
|
|
17
64
|
specialistTool,
|
|
65
|
+
runtimeOf,
|
|
18
66
|
type AgentRuntime,
|
|
19
|
-
type ApprovalEvidence,
|
|
20
67
|
type Delegation,
|
|
68
|
+
type RunStart,
|
|
21
69
|
} from "./delegation.ts";
|
|
70
|
+
import {
|
|
71
|
+
checkHandoffTargets,
|
|
72
|
+
handoffDelegation,
|
|
73
|
+
handoffNote,
|
|
74
|
+
handoffRecord,
|
|
75
|
+
handoffRef,
|
|
76
|
+
isHandoff,
|
|
77
|
+
type Handoff,
|
|
78
|
+
} from "./handoff.ts";
|
|
79
|
+
import {
|
|
80
|
+
RequestJournal,
|
|
81
|
+
isClientTool,
|
|
82
|
+
isInputRequired,
|
|
83
|
+
requestHash,
|
|
84
|
+
type ClientTool,
|
|
85
|
+
} from "./request.ts";
|
|
86
|
+
import { acknowledgeInputs, acceptInputs, inputReceipts } from "./steering.ts";
|
|
87
|
+
import { modelsUsage, readRecoveryPolicy, recoveryToolHash, requireRecovery } from "./recovery.ts";
|
|
88
|
+
import { readInput, readStored, repairConversation, requestOf } from "./input.ts";
|
|
22
89
|
import {
|
|
23
90
|
ExecutionTree,
|
|
24
91
|
Halt,
|
|
25
92
|
authorizeTree,
|
|
93
|
+
emitEvent,
|
|
26
94
|
fail,
|
|
27
95
|
treeUsage,
|
|
96
|
+
nodeId,
|
|
97
|
+
wakeAt,
|
|
98
|
+
openRequests,
|
|
99
|
+
readAnswers,
|
|
100
|
+
requestRecords,
|
|
101
|
+
stopRequests,
|
|
28
102
|
untilAbort,
|
|
29
103
|
type ExecutionScope,
|
|
30
104
|
} from "./tree.ts";
|
|
31
105
|
import {
|
|
32
106
|
checkOptions,
|
|
107
|
+
agentSnapshot,
|
|
33
108
|
completeArguments,
|
|
34
109
|
copyData,
|
|
35
110
|
equalData,
|
|
111
|
+
finalToolResult,
|
|
112
|
+
finalHandoffResult,
|
|
36
113
|
immutableCopy,
|
|
114
|
+
inlineBytes,
|
|
115
|
+
isBase64,
|
|
116
|
+
isEnabledTools,
|
|
37
117
|
isId,
|
|
118
|
+
isNames,
|
|
38
119
|
isRecord,
|
|
39
|
-
|
|
120
|
+
isRevision,
|
|
40
121
|
isUsage,
|
|
122
|
+
jsonArguments,
|
|
41
123
|
modelId,
|
|
124
|
+
recordCodeTools,
|
|
42
125
|
readLimits,
|
|
126
|
+
readModelSettings,
|
|
43
127
|
readTreeLimits,
|
|
44
128
|
readSnapshot,
|
|
45
129
|
readTurn,
|
|
130
|
+
snapshotInlineBytes,
|
|
46
131
|
toolId,
|
|
47
132
|
} from "./snapshot.ts";
|
|
48
133
|
import type {
|
|
@@ -50,13 +135,23 @@ import type {
|
|
|
50
135
|
AgentConfig,
|
|
51
136
|
AgentDefinition,
|
|
52
137
|
AgentEvent,
|
|
138
|
+
CompactionExecution,
|
|
139
|
+
EnabledTools,
|
|
140
|
+
LifecycleContext,
|
|
141
|
+
LifecycleEvent,
|
|
142
|
+
ModelInput,
|
|
143
|
+
MediaRef,
|
|
53
144
|
ModelExecution,
|
|
54
145
|
OperationReceipt,
|
|
55
|
-
|
|
146
|
+
ProgramCall,
|
|
147
|
+
ToolExecution,
|
|
56
148
|
ResultSchema,
|
|
149
|
+
RunContext,
|
|
150
|
+
RunDefinition,
|
|
57
151
|
RunOptions,
|
|
58
152
|
RunOutcome,
|
|
59
153
|
RunSnapshot,
|
|
154
|
+
SessionStatus,
|
|
60
155
|
ToolRequest,
|
|
61
156
|
ToolResult,
|
|
62
157
|
} from "./types.ts";
|
|
@@ -66,53 +161,93 @@ export const RESULT_TOOL_NAME = "submit_result";
|
|
|
66
161
|
|
|
67
162
|
type CompletedModel = Extract<ModelExecution, { status: "completed" }>;
|
|
68
163
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
role: "tool",
|
|
84
|
-
toolCallId: call.id,
|
|
85
|
-
name: call.name,
|
|
86
|
-
content: tool.result.content,
|
|
87
|
-
});
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
return copyData(history);
|
|
164
|
+
/** The same dispatcher writes either a model tool slot or an inner program call. */
|
|
165
|
+
interface ToolSlot {
|
|
166
|
+
get(): ToolExecution;
|
|
167
|
+
set(execution: ToolExecution): void;
|
|
168
|
+
request(): ToolRequest;
|
|
169
|
+
model?: CompletedModel;
|
|
170
|
+
inner?: {
|
|
171
|
+
signal: AbortSignal;
|
|
172
|
+
code: CodeTool;
|
|
173
|
+
start(): void;
|
|
174
|
+
record(result: ToolResult): ToolResult;
|
|
175
|
+
callsLeft(): number;
|
|
176
|
+
outputError?: string;
|
|
177
|
+
};
|
|
92
178
|
}
|
|
93
179
|
|
|
94
|
-
function recordOf(snapshot: RunSnapshot
|
|
180
|
+
function recordOf(snapshot: RunSnapshot) {
|
|
95
181
|
const saved = copyData(snapshot);
|
|
96
182
|
const receipts: OperationReceipt[] = [];
|
|
97
|
-
|
|
98
|
-
for (const model of saved
|
|
99
|
-
|
|
183
|
+
const usage = modelsUsage(allModels(saved));
|
|
184
|
+
for (const model of allModels(saved)) {
|
|
185
|
+
for (const attempt of model.interrupted)
|
|
186
|
+
receipts.push({
|
|
187
|
+
kind: "model",
|
|
188
|
+
id: model.id,
|
|
189
|
+
...attempt,
|
|
190
|
+
status: "interrupted",
|
|
191
|
+
billing: "unknown",
|
|
192
|
+
});
|
|
100
193
|
receipts.push({
|
|
101
194
|
kind: "model",
|
|
195
|
+
...(saved.compactions.some((entry) => entry.id === model.id)
|
|
196
|
+
? { purpose: "compaction" as const }
|
|
197
|
+
: {}),
|
|
102
198
|
id: model.id,
|
|
103
199
|
attemptId: model.attemptId,
|
|
104
200
|
status: model.status,
|
|
201
|
+
billing: model.billing,
|
|
105
202
|
usage: model.usage,
|
|
106
203
|
...(model.status === "completed" && model.turn.source ? { source: model.turn.source } : {}),
|
|
107
204
|
});
|
|
108
205
|
if (model.status !== "completed") continue;
|
|
109
206
|
for (const [index, tool] of model.tools.entries()) {
|
|
110
207
|
const call = model.turn.message.toolCalls?.[index];
|
|
111
|
-
if (!call
|
|
208
|
+
if (!call) continue;
|
|
209
|
+
for (const attempt of tool.interrupted)
|
|
210
|
+
receipts.push({
|
|
211
|
+
kind: "tool",
|
|
212
|
+
id: tool.id,
|
|
213
|
+
callId: call.id,
|
|
214
|
+
...attempt,
|
|
215
|
+
status: "interrupted",
|
|
216
|
+
});
|
|
217
|
+
for (const attempt of tool.retries)
|
|
218
|
+
receipts.push({
|
|
219
|
+
kind: "tool",
|
|
220
|
+
id: tool.id,
|
|
221
|
+
callId: call.id,
|
|
222
|
+
attemptId: attempt.attemptId,
|
|
223
|
+
result: attempt.result,
|
|
224
|
+
status: "completed",
|
|
225
|
+
});
|
|
226
|
+
for (const inner of tool.calls ?? []) {
|
|
227
|
+
for (const attempt of inner.retries)
|
|
228
|
+
receipts.push({
|
|
229
|
+
kind: "tool",
|
|
230
|
+
id: inner.id,
|
|
231
|
+
parentOperationId: tool.id,
|
|
232
|
+
callId: inner.id,
|
|
233
|
+
attemptId: attempt.attemptId,
|
|
234
|
+
status: "completed",
|
|
235
|
+
result: attempt.result,
|
|
236
|
+
});
|
|
237
|
+
if (inner.status !== "pending")
|
|
238
|
+
receipts.push({
|
|
239
|
+
kind: "tool",
|
|
240
|
+
id: inner.id,
|
|
241
|
+
parentOperationId: tool.id,
|
|
242
|
+
callId: inner.id,
|
|
243
|
+
attemptId: inner.attemptId,
|
|
244
|
+
status: inner.status,
|
|
245
|
+
...(inner.status === "completed" ? { result: inner.result } : {}),
|
|
246
|
+
});
|
|
247
|
+
}
|
|
248
|
+
if (tool.status === "pending") continue;
|
|
112
249
|
receipts.push({
|
|
113
|
-
kind: saved.delegations.
|
|
114
|
-
? "delegation"
|
|
115
|
-
: "tool",
|
|
250
|
+
kind: saved.delegations.find((journal) => journal.operationId === tool.id)?.kind ?? "tool",
|
|
116
251
|
id: tool.id,
|
|
117
252
|
callId: call.id,
|
|
118
253
|
attemptId: tool.attemptId,
|
|
@@ -121,30 +256,71 @@ function recordOf(snapshot: RunSnapshot, instructions: string) {
|
|
|
121
256
|
});
|
|
122
257
|
}
|
|
123
258
|
}
|
|
259
|
+
// A root run replaces this with what its append did. Read from a snapshot alone, whether the
|
|
260
|
+
// session has the turn is not known.
|
|
261
|
+
const session: SessionStatus | undefined = saved.session && {
|
|
262
|
+
id: saved.session.id,
|
|
263
|
+
status: "pending",
|
|
264
|
+
};
|
|
124
265
|
return {
|
|
125
266
|
runId: saved.runId,
|
|
126
267
|
attemptId: saved.attemptId,
|
|
127
268
|
usage,
|
|
128
269
|
treeUsage: treeUsage(saved),
|
|
129
270
|
receipts,
|
|
130
|
-
|
|
271
|
+
inputs: inputReceipts(saved),
|
|
272
|
+
...handoffRecord(saved),
|
|
131
273
|
snapshot: saved,
|
|
274
|
+
...(session ? { session } : {}),
|
|
132
275
|
};
|
|
133
276
|
}
|
|
134
277
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
278
|
+
// Adapted from OpenAI Agents JS (MIT), agent.ts: infer every registered handoff's output.
|
|
279
|
+
// Ordinary tools contribute nothing; each runtime still validates only its own contract.
|
|
280
|
+
type RegisteredTools = NonNullable<AgentConfig["tools"]>;
|
|
281
|
+
type HandoffOutput<Tool> = Tool extends Handoff<infer Output> ? Output : never;
|
|
282
|
+
type ConfigWithTools<Tools extends RegisteredTools> = Omit<AgentConfig, "tools"> & {
|
|
283
|
+
tools?: Tools;
|
|
284
|
+
};
|
|
285
|
+
|
|
286
|
+
export function defineAgent<T, const Tools extends RegisteredTools = []>(
|
|
287
|
+
definition: ConfigWithTools<Tools> & { output: ResultSchema<T> },
|
|
288
|
+
): Agent<T | HandoffOutput<Tools[number]>>;
|
|
289
|
+
export function defineAgent<const Tools extends RegisteredTools = []>(
|
|
290
|
+
definition: ConfigWithTools<Tools> & { output?: undefined },
|
|
291
|
+
): Agent<string | HandoffOutput<Tools[number]>>;
|
|
292
|
+
export function defineAgent<T, const Tools extends RegisteredTools = []>(
|
|
293
|
+
definition: ConfigWithTools<Tools> & { output?: ResultSchema<T> },
|
|
294
|
+
): Agent<T | string | HandoffOutput<Tools[number]>>;
|
|
295
|
+
export function defineAgent<T, H>(definition: AgentDefinition<T, H>): Agent<T | string | H> {
|
|
138
296
|
const { id, version, instructions, provider } = definition;
|
|
139
297
|
if (
|
|
140
298
|
!isId(id) ||
|
|
141
299
|
!isId(version) ||
|
|
142
|
-
typeof instructions !== "string" ||
|
|
300
|
+
(typeof instructions !== "string" && typeof instructions !== "function") ||
|
|
143
301
|
!provider ||
|
|
144
302
|
typeof provider.createStream !== "function"
|
|
145
303
|
) {
|
|
146
304
|
throw new TypeError("An agent needs an id, version, instructions and provider.");
|
|
147
305
|
}
|
|
306
|
+
const settings = readModelSettings(definition.modelSettings);
|
|
307
|
+
const memory = memoryPolicy(definition.memory);
|
|
308
|
+
const compaction = compactionDefinition(definition.compaction);
|
|
309
|
+
const summarizer = definition.compaction?.summarize?.provider;
|
|
310
|
+
const toolRetries = readToolRetryPolicy(definition.toolRetries);
|
|
311
|
+
const guardPolicy = guardDefinition(definition.guardrails);
|
|
312
|
+
const guardrails = definition.guardrails && Object.freeze({ ...definition.guardrails });
|
|
313
|
+
const onLifecycle = definition.onLifecycle;
|
|
314
|
+
if (onLifecycle !== undefined && typeof onLifecycle !== "function")
|
|
315
|
+
throw new TypeError("onLifecycle must be a function.");
|
|
316
|
+
const recovery = readRecoveryPolicy(definition.recovery);
|
|
317
|
+
if (recovery && (!isId(provider.id) || !isId(provider.model)))
|
|
318
|
+
throw new TypeError("A recovery profile needs a stable provider id and model.");
|
|
319
|
+
if (definition.enabledTools !== undefined && !isEnabledTools(definition.enabledTools))
|
|
320
|
+
throw new TypeError("enabledTools must be an allow-list or a function returning one.");
|
|
321
|
+
const enabledTools = Array.isArray(definition.enabledTools)
|
|
322
|
+
? [...definition.enabledTools]
|
|
323
|
+
: definition.enabledTools;
|
|
148
324
|
const limits = readLimits(definition.limits);
|
|
149
325
|
const treeLimits = readTreeLimits(definition.treeLimits);
|
|
150
326
|
const output = definition.output && {
|
|
@@ -159,20 +335,56 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
159
335
|
) {
|
|
160
336
|
throw new TypeError("An output contract needs an object schema and a runtime validator.");
|
|
161
337
|
}
|
|
162
|
-
const
|
|
338
|
+
const registeredTools = [...(definition.tools ?? [])];
|
|
339
|
+
const codeTools = new Map(registeredTools.filter(isCodeTool).map((tool) => [tool.name, tool]));
|
|
340
|
+
// Keep capability identity for helper grants; approval/dispatch use the bound tools below.
|
|
341
|
+
const capabilities = new Map(registeredTools.map((tool) => [tool.name, tool]));
|
|
342
|
+
for (const code of codeTools.values())
|
|
343
|
+
for (const tool of code.tools) {
|
|
344
|
+
if (capabilities.has(tool.name) && capabilities.get(tool.name) !== tool)
|
|
345
|
+
throw new TypeError(
|
|
346
|
+
`The name ${tool.name} must refer to the same tool object directly and in every code binding.`,
|
|
347
|
+
);
|
|
348
|
+
capabilities.set(tool.name, tool);
|
|
349
|
+
}
|
|
350
|
+
const needsMemory = !!memory || [...capabilities.values()].some(isMemoryTool);
|
|
163
351
|
if (
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
(tool) =>
|
|
167
|
-
!isId(tool.name) ||
|
|
168
|
-
tool.name === RESULT_TOOL_NAME ||
|
|
169
|
-
(!isDelegation(tool) && tool.isTerminal),
|
|
352
|
+
[...capabilities.values()].some(
|
|
353
|
+
(tool) => MEMORY_TOOL_NAMES.includes(tool.name) && !isMemoryTool(tool),
|
|
170
354
|
)
|
|
355
|
+
)
|
|
356
|
+
throw new TypeError(
|
|
357
|
+
"memory_search, memory_save and memory_forget are reserved. Register tools from memoryTools().",
|
|
358
|
+
);
|
|
359
|
+
const tools = registeredTools.map((tool) =>
|
|
360
|
+
isDelegation(tool) ? bindSubagentTool(tool, () => agent) : tool,
|
|
361
|
+
);
|
|
362
|
+
if (
|
|
363
|
+
new Set(tools.map((tool) => tool.name)).size !== tools.length ||
|
|
364
|
+
[...capabilities.values()].some((tool) => !isId(tool.name) || tool.name === RESULT_TOOL_NAME)
|
|
171
365
|
) {
|
|
172
366
|
throw new TypeError(
|
|
173
|
-
`Use unique tool names
|
|
367
|
+
`Use unique tool names. ${RESULT_TOOL_NAME} is reserved for the output contract.`,
|
|
174
368
|
);
|
|
175
369
|
}
|
|
370
|
+
if (definition.stopAtTools !== undefined && !isNames(definition.stopAtTools))
|
|
371
|
+
throw new TypeError("stopAtTools must be a list of unique tool names.");
|
|
372
|
+
const stopAtTools = [...(definition.stopAtTools ?? [])];
|
|
373
|
+
for (const name of stopAtTools) {
|
|
374
|
+
const tool = tools.find((tool) => tool.name === name);
|
|
375
|
+
if (!tool || isDelegation(tool) || isHandoff(tool) || isClientTool(tool) || isCodeTool(tool))
|
|
376
|
+
throw new TypeError("stopAtTools must name ordinary tools registered on this agent.");
|
|
377
|
+
}
|
|
378
|
+
for (const tool of tools)
|
|
379
|
+
if (
|
|
380
|
+
!isDelegation(tool) &&
|
|
381
|
+
!isHandoff(tool) &&
|
|
382
|
+
!isClientTool(tool) &&
|
|
383
|
+
!isCodeTool(tool) &&
|
|
384
|
+
tool.isTerminal &&
|
|
385
|
+
!stopAtTools.includes(tool.name)
|
|
386
|
+
)
|
|
387
|
+
stopAtTools.push(tool.name);
|
|
176
388
|
if (output) {
|
|
177
389
|
tools.push(
|
|
178
390
|
defineTool({
|
|
@@ -188,23 +400,384 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
188
400
|
}),
|
|
189
401
|
);
|
|
190
402
|
}
|
|
191
|
-
|
|
403
|
+
if (
|
|
404
|
+
[...codeTools.values()].some((code) =>
|
|
405
|
+
code.tools.some((tool) => stopAtTools.includes(tool.name)),
|
|
406
|
+
)
|
|
407
|
+
)
|
|
408
|
+
throw new TypeError("Stopping tools must stay direct, outside code mode.");
|
|
409
|
+
const registry = new ToolRegistry(
|
|
410
|
+
[...new Set([...tools, ...capabilities.values()])].filter(
|
|
411
|
+
(tool): tool is Tool =>
|
|
412
|
+
!isDelegation(tool) && !isHandoff(tool) && !isClientTool(tool) && !isCodeTool(tool),
|
|
413
|
+
),
|
|
414
|
+
);
|
|
415
|
+
for (const name of recovery?.readOnlyTools ?? [])
|
|
416
|
+
if ((!registry.get(name)?.isReadOnly && !codeTools.has(name)) || name === RESULT_TOOL_NAME)
|
|
417
|
+
throw new TypeError(
|
|
418
|
+
"Recovery readOnlyTools must name ordinary isReadOnly tools registered on this agent.",
|
|
419
|
+
);
|
|
420
|
+
for (const [name, policy] of Object.entries(toolRetries?.tools ?? {})) {
|
|
421
|
+
const tool = registry.get(name);
|
|
422
|
+
if (
|
|
423
|
+
!tool ||
|
|
424
|
+
tool.isTerminal ||
|
|
425
|
+
tool.needsApproval ||
|
|
426
|
+
stopAtTools.includes(name) ||
|
|
427
|
+
(policy.replay === "read-only" && !tool.isReadOnly)
|
|
428
|
+
)
|
|
429
|
+
throw new TypeError(
|
|
430
|
+
"toolRetries must name ordinary non-stopping tools without required approval. Read-only retries need isReadOnly.",
|
|
431
|
+
);
|
|
432
|
+
}
|
|
192
433
|
const delegations = new Map(tools.filter(isDelegation).map((tool) => [tool.name, tool]));
|
|
434
|
+
const handoffs = new Map(tools.filter(isHandoff<H>).map((tool) => [tool.name, tool]));
|
|
435
|
+
|
|
436
|
+
function descriptorFor(
|
|
437
|
+
name: string,
|
|
438
|
+
snapshot: RunSnapshot,
|
|
439
|
+
operationId: string,
|
|
440
|
+
): Delegation | undefined {
|
|
441
|
+
const handoff = handoffs.get(name);
|
|
442
|
+
if (!handoff) return delegations.get(name);
|
|
443
|
+
const journal = snapshot.delegations.find((entry) => entry.operationId === operationId);
|
|
444
|
+
if (!journal || journal.kind !== "handoff") return undefined;
|
|
445
|
+
if (!equalData(journal.target, handoffRef(handoff.target())))
|
|
446
|
+
throw new TypeError(
|
|
447
|
+
"The saved handoff target or version changed. Restore the registered target.",
|
|
448
|
+
);
|
|
449
|
+
return handoffDelegation(handoff, snapshot, journal);
|
|
450
|
+
}
|
|
451
|
+
const clients = new Map(tools.filter(isClientTool).map((tool) => [tool.name, tool]));
|
|
452
|
+
const names = [...new Set([...capabilities.keys(), ...tools.map((tool) => tool.name)])];
|
|
453
|
+
const directNames = tools.map((tool) => tool.name);
|
|
454
|
+
const definitionsFor = (enabled: readonly string[]) =>
|
|
455
|
+
tools
|
|
456
|
+
.filter((tool) => enabled.includes(tool.name))
|
|
457
|
+
.map((tool) => (isCodeTool(tool) ? tool.definition(enabled) : tool.definition()));
|
|
458
|
+
async function toolHash(name: string): Promise<string> {
|
|
459
|
+
const code = codeTools.get(name);
|
|
460
|
+
if (code)
|
|
461
|
+
return requestHash({
|
|
462
|
+
definition: code.definition(),
|
|
463
|
+
limits: code.limits,
|
|
464
|
+
tools: await Promise.all(code.tools.map(recoveryToolHash)),
|
|
465
|
+
});
|
|
466
|
+
const tool = registry.get(name);
|
|
467
|
+
if (!tool) throw new TypeError("Missing recovery tool.");
|
|
468
|
+
return recoveryToolHash(tool);
|
|
469
|
+
}
|
|
470
|
+
function checkNames(value: unknown): string[] {
|
|
471
|
+
if (!isNames(value) || value.some((name) => !names.includes(name)))
|
|
472
|
+
throw new TypeError("enabledTools must name each registered tool at most once.");
|
|
473
|
+
return [...value];
|
|
474
|
+
}
|
|
475
|
+
if (Array.isArray(enabledTools)) checkNames(enabledTools);
|
|
476
|
+
|
|
477
|
+
// Adapted from OpenAI Agents JS (MIT), agent.ts and tool.ts. Unlike its per-turn
|
|
478
|
+
// callbacks, these resolve once: a restarted worker must see the same prompt and tools.
|
|
479
|
+
async function resolveDefinition(
|
|
480
|
+
start: RunStart,
|
|
481
|
+
options: RunOptions,
|
|
482
|
+
runId: string,
|
|
483
|
+
source?: RunDefinition,
|
|
484
|
+
): Promise<RunDefinition> {
|
|
485
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
486
|
+
const run: RunContext = Object.freeze({
|
|
487
|
+
agentId: id,
|
|
488
|
+
version,
|
|
489
|
+
runId,
|
|
490
|
+
...immutableCopy({ history: start.history, input: start.input }),
|
|
491
|
+
context: Object.freeze({ ...options.context }),
|
|
492
|
+
signal,
|
|
493
|
+
});
|
|
494
|
+
const text: unknown = source
|
|
495
|
+
? source.instructions
|
|
496
|
+
: typeof instructions === "function"
|
|
497
|
+
? await untilAbort(Promise.resolve(instructions(run)), signal)
|
|
498
|
+
: instructions;
|
|
499
|
+
if (typeof text !== "string") throw new TypeError("instructions must return a string.");
|
|
500
|
+
async function select(selection: EnabledTools | undefined): Promise<string[]> {
|
|
501
|
+
return selection === undefined
|
|
502
|
+
? [...names]
|
|
503
|
+
: checkNames(
|
|
504
|
+
typeof selection === "function"
|
|
505
|
+
? await untilAbort(Promise.resolve(selection(run)), signal)
|
|
506
|
+
: selection,
|
|
507
|
+
);
|
|
508
|
+
}
|
|
509
|
+
const allowed = source ? source.enabledTools : await select(enabledTools);
|
|
510
|
+
const selected =
|
|
511
|
+
options.enabledTools === undefined ? allowed : await select(options.enabledTools);
|
|
512
|
+
if (selected.some((name) => name !== RESULT_TOOL_NAME && !allowed.includes(name)))
|
|
513
|
+
throw new TypeError(
|
|
514
|
+
"Run enabledTools may narrow the agent's tools, not enable a disabled tool.",
|
|
515
|
+
);
|
|
516
|
+
// The definition's order is part of the provider's cached prefix, not the allow-list's.
|
|
517
|
+
const enabled = names.filter(
|
|
518
|
+
(name) => selected.includes(name) || (output && name === RESULT_TOOL_NAME),
|
|
519
|
+
);
|
|
520
|
+
// Ported from PydanticAI (MIT), settings.py, merge_model_settings: the run wins.
|
|
521
|
+
// Provider defaults remain in core; passing only set values preserves that first layer.
|
|
522
|
+
const {
|
|
523
|
+
onActivity: _onActivity,
|
|
524
|
+
onRateLimit: _onRateLimit,
|
|
525
|
+
...modelSettings
|
|
526
|
+
} = {
|
|
527
|
+
...(source ? source.modelSettings : settings),
|
|
528
|
+
...readModelSettings(options.modelSettings),
|
|
529
|
+
};
|
|
530
|
+
const choice = modelSettings.toolChoice;
|
|
531
|
+
if (output && choice === "none")
|
|
532
|
+
throw new TypeError(
|
|
533
|
+
"toolChoice none disables submit_result, which a checked-output run needs to finish.",
|
|
534
|
+
);
|
|
535
|
+
if (
|
|
536
|
+
(choice === "required" && enabled.length === 0) ||
|
|
537
|
+
(typeof choice === "object" && !enabled.includes(choice.name))
|
|
538
|
+
)
|
|
539
|
+
throw new TypeError("toolChoice must name an enabled tool; required needs at least one.");
|
|
540
|
+
const toolHashes = Object.fromEntries(
|
|
541
|
+
await Promise.all(
|
|
542
|
+
(recovery?.readOnlyTools ?? []).map(async (name) => {
|
|
543
|
+
return [name, await toolHash(name)] as const;
|
|
544
|
+
}),
|
|
545
|
+
),
|
|
546
|
+
);
|
|
547
|
+
const retryHashes = Object.fromEntries(
|
|
548
|
+
await Promise.all(
|
|
549
|
+
Object.keys(toolRetries?.tools ?? {}).map(async (name) => {
|
|
550
|
+
const tool = registry.get(name);
|
|
551
|
+
if (!tool) throw new TypeError("Missing retry tool.");
|
|
552
|
+
return [name, await recoveryToolHash(tool)] as const;
|
|
553
|
+
}),
|
|
554
|
+
),
|
|
555
|
+
);
|
|
556
|
+
return {
|
|
557
|
+
instructions: text,
|
|
558
|
+
...(memory ? { memory: copyData(memory) } : {}),
|
|
559
|
+
modelSettings,
|
|
560
|
+
enabledTools: enabled,
|
|
561
|
+
stopAtTools: [...stopAtTools],
|
|
562
|
+
...(codeTools.size ? { codeTools: recordCodeTools(codeTools) } : {}),
|
|
563
|
+
guardrails: copyData(guardPolicy),
|
|
564
|
+
compaction: copyData(compaction),
|
|
565
|
+
toolRetries: toolRetries ? { policy: copyData(toolRetries), toolHashes: retryHashes } : null,
|
|
566
|
+
recovery: recovery
|
|
567
|
+
? {
|
|
568
|
+
policy: copyData(recovery),
|
|
569
|
+
provider: { id: provider.id, model: provider.model },
|
|
570
|
+
toolHashes,
|
|
571
|
+
modelToolsHash: await requestHash(definitionsFor(enabled)),
|
|
572
|
+
}
|
|
573
|
+
: null,
|
|
574
|
+
};
|
|
575
|
+
}
|
|
193
576
|
|
|
194
577
|
function validateResult(candidate: unknown): T | string {
|
|
578
|
+
// copyData permits absent optional values, but a result must survive a JSON checkpoint.
|
|
579
|
+
if (candidate === undefined)
|
|
580
|
+
throw new TypeError("The result must be a JSON value. Return null instead of undefined.");
|
|
195
581
|
if (output) return output.validate(copyData(candidate));
|
|
196
582
|
if (typeof candidate !== "string" || !candidate.trim())
|
|
197
583
|
throw new TypeError("The model returned no answer.");
|
|
198
584
|
return candidate;
|
|
199
585
|
}
|
|
200
586
|
|
|
587
|
+
// Adapted from OpenAI Agents JS (MIT), result.ts: the active agent processes its own
|
|
588
|
+
// final output. Follow our saved child instead of casting it to the source's output type.
|
|
589
|
+
function completedOutput(snapshot: RunSnapshot): T | string | H {
|
|
590
|
+
if (snapshot.state.status !== "completed")
|
|
591
|
+
throw new TypeError("The run has no completed result.");
|
|
592
|
+
const last = snapshot.models.at(-1);
|
|
593
|
+
const transfer = last?.status === "completed" && finalHandoffResult(snapshot, last);
|
|
594
|
+
if (!transfer) return validateResult(snapshot.state.candidate);
|
|
595
|
+
const name = last.turn.message.toolCalls?.[0]?.name;
|
|
596
|
+
const target = name && handoffs.get(name)?.target();
|
|
597
|
+
if (!target || !equalData(handoffRef(target), handoffRef(transfer.child)))
|
|
598
|
+
throw new TypeError("The completed handoff does not match its registered target.");
|
|
599
|
+
const result = target[AGENT_RUNTIME].hydrate(transfer.child);
|
|
600
|
+
if (result.status !== "completed")
|
|
601
|
+
throw new TypeError("The handoff target has no completed result.");
|
|
602
|
+
return result.output;
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
function requestFor(snapshot: RunSnapshot, model: CompletedModel, index: number): ToolRequest {
|
|
606
|
+
const call = model.turn.message.toolCalls?.[index];
|
|
607
|
+
const tool = model.tools[index];
|
|
608
|
+
if (!call || !tool) fail("invalid_journal", "The tool call is missing from its journal.");
|
|
609
|
+
return {
|
|
610
|
+
agentId: id,
|
|
611
|
+
version,
|
|
612
|
+
runId: snapshot.runId,
|
|
613
|
+
attemptId:
|
|
614
|
+
tool.status === "running" || tool.status === "completed"
|
|
615
|
+
? tool.attemptId
|
|
616
|
+
: tool.retries.length
|
|
617
|
+
? `${snapshot.attemptId}/tool-attempt/${tool.retries.length + tool.interrupted.length + 1}`
|
|
618
|
+
: snapshot.attemptId,
|
|
619
|
+
operationId: tool.id,
|
|
620
|
+
...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
|
|
621
|
+
call,
|
|
622
|
+
arguments: codeTools.has(call.name)
|
|
623
|
+
? (jsonArguments(call.arguments) ?? {})
|
|
624
|
+
: parseToolArgs(call.arguments),
|
|
625
|
+
};
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
async function needsApproval(
|
|
629
|
+
call: ToolRequest,
|
|
630
|
+
options: RunOptions,
|
|
631
|
+
signal: AbortSignal,
|
|
632
|
+
): Promise<boolean> {
|
|
633
|
+
if (call.call.name === RESULT_TOOL_NAME) return false;
|
|
634
|
+
const tool =
|
|
635
|
+
tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
|
|
636
|
+
return (
|
|
637
|
+
tool?.needsApproval === true ||
|
|
638
|
+
(await untilAbort(
|
|
639
|
+
Promise.resolve(options.host?.needsApproval?.(immutableCopy(call))),
|
|
640
|
+
signal,
|
|
641
|
+
)) === true
|
|
642
|
+
);
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
function journalFor(
|
|
646
|
+
snapshot: RunSnapshot,
|
|
647
|
+
model: CompletedModel,
|
|
648
|
+
index: number,
|
|
649
|
+
options: RunOptions,
|
|
650
|
+
scope: ExecutionScope,
|
|
651
|
+
signal: AbortSignal,
|
|
652
|
+
effectiveCall?: ToolRequest,
|
|
653
|
+
): RequestJournal {
|
|
654
|
+
const call = requestFor(snapshot, model, index);
|
|
655
|
+
const execution = model.tools[index];
|
|
656
|
+
if (!execution) throw new TypeError("Missing tool journal.");
|
|
657
|
+
return requestsFor(call, execution, options, scope, signal, effectiveCall);
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
function requestsFor(
|
|
661
|
+
call: ToolRequest,
|
|
662
|
+
execution: ToolExecution,
|
|
663
|
+
options: RunOptions,
|
|
664
|
+
scope: ExecutionScope,
|
|
665
|
+
signal: AbortSignal,
|
|
666
|
+
effectiveCall?: ToolRequest,
|
|
667
|
+
): RequestJournal {
|
|
668
|
+
const tool =
|
|
669
|
+
tools.find((tool) => tool.name === call.call.name) ?? capabilities.get(call.call.name);
|
|
670
|
+
return new RequestJournal(
|
|
671
|
+
execution,
|
|
672
|
+
effectiveCall ?? call,
|
|
673
|
+
options,
|
|
674
|
+
scope,
|
|
675
|
+
signal,
|
|
676
|
+
// The policy hash follows the original model call even when dispatch arguments were edited.
|
|
677
|
+
async () =>
|
|
678
|
+
requestHash({
|
|
679
|
+
definition: tool?.definition() ?? null,
|
|
680
|
+
needsApproval: await needsApproval(call, options, signal),
|
|
681
|
+
kind:
|
|
682
|
+
tool && isHandoff(tool)
|
|
683
|
+
? "handoff"
|
|
684
|
+
: tool && isDelegation(tool)
|
|
685
|
+
? "delegation"
|
|
686
|
+
: tool && isClientTool(tool)
|
|
687
|
+
? "client"
|
|
688
|
+
: "tool",
|
|
689
|
+
...(tool && isHandoff(tool) ? { target: handoffRef(tool.target()) } : {}),
|
|
690
|
+
...(tool && isClientTool(tool) ? { resultSchema: tool.resultSchema } : {}),
|
|
691
|
+
}),
|
|
692
|
+
(decision) => {
|
|
693
|
+
if (decision.type === "result") {
|
|
694
|
+
const client = clients.get(call.call.name);
|
|
695
|
+
if (!client) throw new TypeError("This call is not a registered client tool.");
|
|
696
|
+
client.result(decision.value);
|
|
697
|
+
}
|
|
698
|
+
},
|
|
699
|
+
!!guardrails?.toolOutput,
|
|
700
|
+
);
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
// Intake is a tree-wide pre-effect barrier. A saved child receives its decisions in its
|
|
704
|
+
// snapshot before the host may reuse a segment. No browser-supplied route is consulted.
|
|
705
|
+
async function answerRequests(
|
|
706
|
+
snapshot: RunSnapshot,
|
|
707
|
+
options: RunOptions,
|
|
708
|
+
scope: ExecutionScope,
|
|
709
|
+
answers: Readonly<Record<string, unknown>>,
|
|
710
|
+
signal: AbortSignal,
|
|
711
|
+
): Promise<void> {
|
|
712
|
+
if (snapshot.state.status !== "running" && snapshot.state.status !== "suspended") return;
|
|
713
|
+
signal.throwIfAborted();
|
|
714
|
+
for (const model of snapshot.models) {
|
|
715
|
+
if (model.status !== "completed") continue;
|
|
716
|
+
for (const [index, execution] of model.tools.entries()) {
|
|
717
|
+
if (execution.status === "completed") continue;
|
|
718
|
+
const journal = journalFor(snapshot, model, index, options, scope, signal);
|
|
719
|
+
for (const record of [...(execution.asks ?? [])]) {
|
|
720
|
+
if (record.closed) continue;
|
|
721
|
+
scope.tree.active();
|
|
722
|
+
signal.throwIfAborted();
|
|
723
|
+
if (!record.decision && Object.hasOwn(answers, record.request.id))
|
|
724
|
+
await journal.resolve(record, answers[record.request.id]);
|
|
725
|
+
else await journal.refresh(record);
|
|
726
|
+
}
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
for (const entry of snapshot.delegations) {
|
|
730
|
+
const model = snapshot.models.find(
|
|
731
|
+
(model) =>
|
|
732
|
+
model.status === "completed" && model.tools.some((tool) => tool.id === entry.operationId),
|
|
733
|
+
);
|
|
734
|
+
const position =
|
|
735
|
+
model?.status === "completed"
|
|
736
|
+
? model.tools.findIndex((tool) => tool.id === entry.operationId)
|
|
737
|
+
: -1;
|
|
738
|
+
const name =
|
|
739
|
+
model?.status === "completed" ? model.turn.message.toolCalls?.[position]?.name : undefined;
|
|
740
|
+
const descriptor = name && descriptorFor(name, snapshot, entry.operationId);
|
|
741
|
+
if (!descriptor) continue;
|
|
742
|
+
for (const child of entry.children) {
|
|
743
|
+
if (
|
|
744
|
+
child.snapshot.state.status !== "running" &&
|
|
745
|
+
child.snapshot.state.status !== "suspended"
|
|
746
|
+
)
|
|
747
|
+
continue;
|
|
748
|
+
const specialist = descriptor.specialists.find(
|
|
749
|
+
(agent) =>
|
|
750
|
+
agent.kind === child.snapshot.kind &&
|
|
751
|
+
agent.id === nodeId(child.snapshot) &&
|
|
752
|
+
agent.version === child.snapshot.version,
|
|
753
|
+
);
|
|
754
|
+
if (!specialist) throw new TypeError("Unregistered specialist.");
|
|
755
|
+
await runtimeOf(specialist).answerRequests(
|
|
756
|
+
child.snapshot,
|
|
757
|
+
options,
|
|
758
|
+
{
|
|
759
|
+
tree: scope.tree,
|
|
760
|
+
depth: scope.depth + 1,
|
|
761
|
+
path: [
|
|
762
|
+
...scope.path,
|
|
763
|
+
{ operationId: entry.operationId, key: child.key, runId: child.snapshot.runId },
|
|
764
|
+
],
|
|
765
|
+
},
|
|
766
|
+
answers,
|
|
767
|
+
signal,
|
|
768
|
+
);
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
}
|
|
772
|
+
|
|
201
773
|
async function execute(
|
|
202
774
|
snapshot: RunSnapshot,
|
|
203
775
|
options: RunOptions,
|
|
204
776
|
scope: ExecutionScope,
|
|
205
|
-
|
|
206
|
-
): Promise<RunOutcome<T | string>> {
|
|
777
|
+
answers?: Readonly<Record<string, unknown>>,
|
|
778
|
+
): Promise<RunOutcome<T | string | H>> {
|
|
207
779
|
const host = options.host;
|
|
780
|
+
const limits = snapshot.limits;
|
|
208
781
|
const deadline = snapshot.startedAt + limits.elapsedMs;
|
|
209
782
|
const timeout = new AbortController();
|
|
210
783
|
const signal = AbortSignal.any([
|
|
@@ -217,8 +790,8 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
217
790
|
Math.max(0, deadline - Date.now()),
|
|
218
791
|
);
|
|
219
792
|
let release = () => {};
|
|
220
|
-
let
|
|
221
|
-
let
|
|
793
|
+
let completed: { output: T | string | H } | undefined;
|
|
794
|
+
let started = false;
|
|
222
795
|
|
|
223
796
|
function active(): void {
|
|
224
797
|
scope.tree.active();
|
|
@@ -228,39 +801,322 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
228
801
|
}
|
|
229
802
|
|
|
230
803
|
function emit(event: AgentEvent): void {
|
|
804
|
+
emitEvent(options, event);
|
|
805
|
+
}
|
|
806
|
+
|
|
807
|
+
const save = () => scope.tree.save();
|
|
808
|
+
const callbackContext: LifecycleContext = Object.freeze({
|
|
809
|
+
agentId: id,
|
|
810
|
+
version,
|
|
811
|
+
runId: snapshot.runId,
|
|
812
|
+
attemptId: snapshot.attemptId,
|
|
813
|
+
context: Object.freeze({ ...options.context }),
|
|
814
|
+
signal,
|
|
815
|
+
});
|
|
816
|
+
const observe = (event: LifecycleEvent, callSignal = signal) =>
|
|
817
|
+
observeLifecycle(
|
|
818
|
+
[onLifecycle, options.onLifecycle],
|
|
819
|
+
event,
|
|
820
|
+
callSignal === signal ? callbackContext : { ...callbackContext, signal: callSignal },
|
|
821
|
+
);
|
|
822
|
+
const guards = new GuardChecks(snapshot, guardrails, callbackContext, save, active);
|
|
823
|
+
|
|
824
|
+
function slotFor(model: CompletedModel, index: number): ToolSlot {
|
|
825
|
+
return {
|
|
826
|
+
model,
|
|
827
|
+
get() {
|
|
828
|
+
const execution = model.tools[index];
|
|
829
|
+
if (!execution) fail("invalid_journal", "The tool call is missing from its journal.");
|
|
830
|
+
return execution;
|
|
831
|
+
},
|
|
832
|
+
set(execution) {
|
|
833
|
+
model.tools[index] = execution;
|
|
834
|
+
},
|
|
835
|
+
request: () => requestFor(snapshot, model, index),
|
|
836
|
+
};
|
|
837
|
+
}
|
|
838
|
+
|
|
839
|
+
function invocationActive(slot: ToolSlot): void {
|
|
840
|
+
active();
|
|
841
|
+
slot.inner?.signal.throwIfAborted();
|
|
842
|
+
}
|
|
843
|
+
|
|
844
|
+
function toolChecks(callSignal: AbortSignal): GuardChecks {
|
|
845
|
+
return callSignal === signal
|
|
846
|
+
? guards
|
|
847
|
+
: new GuardChecks(
|
|
848
|
+
snapshot,
|
|
849
|
+
guardrails,
|
|
850
|
+
{ ...callbackContext, signal: callSignal },
|
|
851
|
+
save,
|
|
852
|
+
() => {
|
|
853
|
+
active();
|
|
854
|
+
callSignal.throwIfAborted();
|
|
855
|
+
},
|
|
856
|
+
);
|
|
857
|
+
}
|
|
858
|
+
|
|
859
|
+
async function beforeTool(request: ToolRequest, callSignal = signal): Promise<void> {
|
|
860
|
+
await toolChecks(callSignal).check(
|
|
861
|
+
"toolInput",
|
|
862
|
+
request.operationId,
|
|
863
|
+
request.attemptId,
|
|
864
|
+
request,
|
|
865
|
+
);
|
|
866
|
+
active();
|
|
867
|
+
callSignal.throwIfAborted();
|
|
868
|
+
await observe({ type: "tool_start", request }, callSignal);
|
|
869
|
+
active();
|
|
870
|
+
callSignal.throwIfAborted();
|
|
871
|
+
}
|
|
872
|
+
|
|
873
|
+
async function withToolError(
|
|
874
|
+
request: ToolRequest,
|
|
875
|
+
work: () => Promise<void>,
|
|
876
|
+
callSignal = signal,
|
|
877
|
+
): Promise<void> {
|
|
231
878
|
try {
|
|
232
|
-
|
|
233
|
-
} catch {
|
|
234
|
-
|
|
879
|
+
await work();
|
|
880
|
+
} catch (error) {
|
|
881
|
+
await observe({ type: "tool_error", request }, callSignal);
|
|
882
|
+
throw error;
|
|
235
883
|
}
|
|
236
884
|
}
|
|
237
885
|
|
|
238
|
-
|
|
886
|
+
function restart(
|
|
887
|
+
kind: "model" | "tool",
|
|
888
|
+
operationId: string,
|
|
889
|
+
previousAttemptId: string,
|
|
890
|
+
attemptId = snapshot.attemptId,
|
|
891
|
+
): void {
|
|
892
|
+
// Adapted from Vercel AI SDK (Apache-2.0), workflow/do-stream-step.ts: reset the
|
|
893
|
+
// current display before replacement output. Unlike reset-step, identity stays explicit.
|
|
894
|
+
emit({
|
|
895
|
+
type: "operation_restart",
|
|
896
|
+
kind,
|
|
897
|
+
runId: snapshot.runId,
|
|
898
|
+
operationId,
|
|
899
|
+
previousAttemptId,
|
|
900
|
+
attemptId,
|
|
901
|
+
});
|
|
902
|
+
}
|
|
903
|
+
|
|
904
|
+
async function checkToolRecovery(
|
|
905
|
+
model: CompletedModel,
|
|
906
|
+
index: number,
|
|
907
|
+
previous: number,
|
|
908
|
+
): Promise<void> {
|
|
909
|
+
const execution = model.tools[index];
|
|
910
|
+
if (!execution) fail("invalid_journal", "The tool call is missing from its journal.");
|
|
911
|
+
const request = requestFor(snapshot, model, index);
|
|
912
|
+
const tool = registry.get(request.call.name);
|
|
913
|
+
const recorded = snapshot.definition.recovery;
|
|
914
|
+
const budget = retryBudget(snapshot.definition.toolRetries, request.call.name);
|
|
915
|
+
if (budget && previous + 1 >= budget.maxAttempts)
|
|
916
|
+
fail(
|
|
917
|
+
"tool_retry_exhausted",
|
|
918
|
+
"This call reached its tool attempt limit. Reconcile the saved attempts with the host.",
|
|
919
|
+
execution.id,
|
|
920
|
+
);
|
|
921
|
+
requireRecovery(
|
|
922
|
+
!!tool?.isReadOnly &&
|
|
923
|
+
recorded?.policy.readOnlyTools?.includes(request.call.name) === true &&
|
|
924
|
+
!execution.asks?.length &&
|
|
925
|
+
!!host?.beforeTool,
|
|
926
|
+
previous,
|
|
927
|
+
recorded,
|
|
928
|
+
execution.id,
|
|
929
|
+
);
|
|
930
|
+
if (!tool || (await recoveryToolHash(tool)) !== recorded?.toolHashes[tool.name])
|
|
931
|
+
fail(
|
|
932
|
+
"recovery_definition_changed",
|
|
933
|
+
"The interrupted tool's definition changed. Reconcile it with the host before continuing.",
|
|
934
|
+
execution.id,
|
|
935
|
+
);
|
|
936
|
+
active();
|
|
937
|
+
}
|
|
938
|
+
|
|
939
|
+
async function recoverTools(model: CompletedModel): Promise<void> {
|
|
940
|
+
for (const [index, execution] of model.tools.entries()) {
|
|
941
|
+
if (execution.status !== "running") continue;
|
|
942
|
+
const code = codeTools.get(model.turn.message.toolCalls?.[index]?.name ?? "");
|
|
943
|
+
if (code) {
|
|
944
|
+
const calls = execution.calls ?? [];
|
|
945
|
+
const unknown = calls.find(
|
|
946
|
+
(call) => call.status === "running" && !registry.get(call.name)?.isReadOnly,
|
|
947
|
+
);
|
|
948
|
+
if (unknown)
|
|
949
|
+
fail(
|
|
950
|
+
"interrupted_operation",
|
|
951
|
+
"This inner call started but has no saved result. Reconcile its effect with the host; the program will not replay it.",
|
|
952
|
+
unknown.id,
|
|
953
|
+
);
|
|
954
|
+
refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
|
|
955
|
+
const restartable =
|
|
956
|
+
calls.every((call) => registry.get(call.name)?.isReadOnly && !call.asks?.length) &&
|
|
957
|
+
!execution.asks?.length &&
|
|
958
|
+
snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) &&
|
|
959
|
+
!!host?.beforeTool &&
|
|
960
|
+
toolAttempts(execution) < (snapshot.definition.recovery?.policy.maxAttempts ?? 0);
|
|
961
|
+
for (const [position, call] of calls.entries()) {
|
|
962
|
+
if (call.status === "completed") continue;
|
|
963
|
+
calls[position] = {
|
|
964
|
+
...call,
|
|
965
|
+
status: "completed",
|
|
966
|
+
result: {
|
|
967
|
+
ok: false,
|
|
968
|
+
kind: "interrupted",
|
|
969
|
+
content: call.started
|
|
970
|
+
? "This read stopped before its result was saved. It changed nothing."
|
|
971
|
+
: "This call did not start. It changed nothing.",
|
|
972
|
+
},
|
|
973
|
+
};
|
|
974
|
+
}
|
|
975
|
+
if (restartable) {
|
|
976
|
+
if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
|
|
977
|
+
fail(
|
|
978
|
+
"recovery_definition_changed",
|
|
979
|
+
"The code tool's bindings or limits changed. Restore the saved definition before restarting.",
|
|
980
|
+
execution.id,
|
|
981
|
+
);
|
|
982
|
+
model.tools[index] = {
|
|
983
|
+
id: execution.id,
|
|
984
|
+
status: "pending",
|
|
985
|
+
previousAttemptId: execution.attemptId,
|
|
986
|
+
interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
|
|
987
|
+
retries: execution.retries,
|
|
988
|
+
calls,
|
|
989
|
+
};
|
|
990
|
+
await save();
|
|
991
|
+
} else
|
|
992
|
+
await finishTool(model, index, requestFor(snapshot, model, index), code.close(calls));
|
|
993
|
+
continue;
|
|
994
|
+
}
|
|
995
|
+
refuseGuardedReplay(snapshot, execution.id, execution.attemptId);
|
|
996
|
+
await checkToolRecovery(
|
|
997
|
+
model,
|
|
998
|
+
index,
|
|
999
|
+
execution.interrupted.length + execution.retries.length,
|
|
1000
|
+
);
|
|
1001
|
+
model.tools[index] = {
|
|
1002
|
+
id: execution.id,
|
|
1003
|
+
status: "pending",
|
|
1004
|
+
previousAttemptId: execution.attemptId,
|
|
1005
|
+
retries: execution.retries,
|
|
1006
|
+
interrupted: [...execution.interrupted, { attemptId: execution.attemptId }],
|
|
1007
|
+
};
|
|
1008
|
+
}
|
|
1009
|
+
}
|
|
239
1010
|
|
|
240
1011
|
function usedTools(): number {
|
|
241
1012
|
return snapshot.models.reduce(
|
|
242
1013
|
(count, model) =>
|
|
243
1014
|
count +
|
|
244
1015
|
(model.status === "completed"
|
|
245
|
-
? model.tools.
|
|
1016
|
+
? model.tools.reduce(
|
|
1017
|
+
(total, tool) =>
|
|
1018
|
+
total +
|
|
1019
|
+
toolAttempts(tool) +
|
|
1020
|
+
(tool.calls ?? []).reduce(
|
|
1021
|
+
(innerTotal, call) => innerTotal + 1 + call.retries.length,
|
|
1022
|
+
0,
|
|
1023
|
+
),
|
|
1024
|
+
0,
|
|
1025
|
+
)
|
|
246
1026
|
: 0),
|
|
247
1027
|
0,
|
|
248
1028
|
);
|
|
249
1029
|
}
|
|
250
1030
|
|
|
251
|
-
function
|
|
252
|
-
const
|
|
253
|
-
const
|
|
254
|
-
if (!
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
1031
|
+
async function checkToolRetry(slot: ToolSlot): Promise<void> {
|
|
1032
|
+
const execution = slot.get();
|
|
1033
|
+
const recorded = snapshot.definition.toolRetries;
|
|
1034
|
+
if (!recorded) fail("invalid_journal", "Missing tool retry policy.");
|
|
1035
|
+
const request = slot.request();
|
|
1036
|
+
await checkRetryTool(registry.get(request.call.name), recorded, execution);
|
|
1037
|
+
if (
|
|
1038
|
+
!host?.beforeTool ||
|
|
1039
|
+
(await needsApproval(request, options, slot.inner?.signal ?? signal))
|
|
1040
|
+
)
|
|
1041
|
+
fail(
|
|
1042
|
+
"tool_retry_unsafe",
|
|
1043
|
+
"A retry needs current host authorization and cannot reuse or open an approval.",
|
|
1044
|
+
execution.id,
|
|
1045
|
+
);
|
|
1046
|
+
invocationActive(slot);
|
|
1047
|
+
}
|
|
1048
|
+
|
|
1049
|
+
async function retryTool(slot: ToolSlot): Promise<boolean> {
|
|
1050
|
+
const execution = slot.get();
|
|
1051
|
+
if (
|
|
1052
|
+
execution.status !== "completed" ||
|
|
1053
|
+
execution.result.ok ||
|
|
1054
|
+
execution.asks?.length ||
|
|
1055
|
+
!["failed", "timeout"].includes(execution.result.kind)
|
|
1056
|
+
)
|
|
1057
|
+
return false;
|
|
1058
|
+
const request = slot.request();
|
|
1059
|
+
const policy = retryBudget(snapshot.definition.toolRetries, request.call.name);
|
|
1060
|
+
const recoveryCeiling = execution.interrupted.length
|
|
1061
|
+
? snapshot.definition.recovery?.policy.maxAttempts
|
|
1062
|
+
: undefined;
|
|
1063
|
+
if (
|
|
1064
|
+
!policy ||
|
|
1065
|
+
toolAttempts(execution) >=
|
|
1066
|
+
Math.min(policy.maxAttempts, recoveryCeiling ?? policy.maxAttempts)
|
|
1067
|
+
)
|
|
1068
|
+
return false;
|
|
1069
|
+
invocationActive(slot);
|
|
1070
|
+
if (slot.inner && slot.inner.callsLeft() <= 0) return false;
|
|
1071
|
+
if (usedTools() >= limits.toolCalls) {
|
|
1072
|
+
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
1073
|
+
}
|
|
1074
|
+
await checkToolRetry(slot);
|
|
1075
|
+
let reconciliation: string | undefined;
|
|
1076
|
+
if (policy.replay === "reconcile") {
|
|
1077
|
+
const reconcile = host?.reconcileToolRetry;
|
|
1078
|
+
if (!reconcile)
|
|
1079
|
+
fail(
|
|
1080
|
+
"tool_retry_unsafe",
|
|
1081
|
+
"This failed call needs host reconciliation before it can be repeated.",
|
|
1082
|
+
execution.id,
|
|
1083
|
+
);
|
|
1084
|
+
const verdict = await untilAbort(
|
|
1085
|
+
Promise.resolve(
|
|
1086
|
+
reconcile(immutableCopy({ request, result: execution.result }), callbackContext),
|
|
1087
|
+
),
|
|
1088
|
+
slot.inner?.signal ?? signal,
|
|
1089
|
+
);
|
|
1090
|
+
invocationActive(slot);
|
|
1091
|
+
if (verdict?.outcome !== "not_run" || !isId(verdict.receipt))
|
|
1092
|
+
fail(
|
|
1093
|
+
"tool_retry_unsafe",
|
|
1094
|
+
"The host could not confirm that the failed call did not run. Reconcile its effect before continuing.",
|
|
1095
|
+
execution.id,
|
|
1096
|
+
);
|
|
1097
|
+
reconciliation = verdict.receipt;
|
|
1098
|
+
}
|
|
1099
|
+
// Guest calls can reserve the remaining budget while host reconciliation is awaited.
|
|
1100
|
+
invocationActive(slot);
|
|
1101
|
+
if (slot.inner && slot.inner.callsLeft() <= 0) return false;
|
|
1102
|
+
slot.set({
|
|
1103
|
+
id: execution.id,
|
|
1104
|
+
status: "pending",
|
|
1105
|
+
previousAttemptId: execution.attemptId,
|
|
1106
|
+
interrupted: execution.interrupted,
|
|
1107
|
+
retries: [
|
|
1108
|
+
...execution.retries,
|
|
1109
|
+
{
|
|
1110
|
+
attemptId: execution.attemptId,
|
|
1111
|
+
arguments: copyData(request.arguments),
|
|
1112
|
+
result: execution.result,
|
|
1113
|
+
...(reconciliation ? { reconciliation } : {}),
|
|
1114
|
+
},
|
|
1115
|
+
],
|
|
1116
|
+
});
|
|
1117
|
+
// Retain the failure and reconciliation before reserving another attempt.
|
|
1118
|
+
await save();
|
|
1119
|
+
return true;
|
|
264
1120
|
}
|
|
265
1121
|
|
|
266
1122
|
async function finishTool(
|
|
@@ -269,24 +1125,103 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
269
1125
|
request: ToolRequest,
|
|
270
1126
|
result: ToolResult,
|
|
271
1127
|
): Promise<void> {
|
|
272
|
-
model
|
|
1128
|
+
return finishExecution(slotFor(model, index), request, result);
|
|
1129
|
+
}
|
|
1130
|
+
|
|
1131
|
+
async function finishExecution(
|
|
1132
|
+
slot: ToolSlot,
|
|
1133
|
+
request: ToolRequest,
|
|
1134
|
+
result: ToolResult,
|
|
1135
|
+
): Promise<void> {
|
|
1136
|
+
if (!result.ok && (result.kind === "cancelled" || result.kind === "denied")) {
|
|
1137
|
+
for (const record of slot.get().asks ?? [])
|
|
1138
|
+
if (!record.decision && !record.closed) record.closed = "stopped";
|
|
1139
|
+
// A cancelled coordination call cannot leave suspended children under a completed
|
|
1140
|
+
// tool receipt. Already settled children and their usage remain untouched.
|
|
1141
|
+
const delegation = snapshot.delegations.find(
|
|
1142
|
+
(entry) => entry.operationId === request.operationId,
|
|
1143
|
+
);
|
|
1144
|
+
for (const child of delegation?.children ?? []) stopRequests(child.snapshot);
|
|
1145
|
+
// Once a target was admitted, it owns this conversation. Denying a renewed transfer
|
|
1146
|
+
// stops that conversation; it cannot buy a new source turn after target effects.
|
|
1147
|
+
if (delegation?.kind === "handoff" && delegation.children.length > 0)
|
|
1148
|
+
snapshot.state = { status: "cancelled" };
|
|
1149
|
+
}
|
|
1150
|
+
const edited = slot
|
|
1151
|
+
.get()
|
|
1152
|
+
.asks?.some(
|
|
1153
|
+
(record) =>
|
|
1154
|
+
!record.closed &&
|
|
1155
|
+
record.decision?.type === "approve" &&
|
|
1156
|
+
record.decision.arguments !== undefined,
|
|
1157
|
+
);
|
|
1158
|
+
if (edited && !codeTools.has(request.call.name))
|
|
1159
|
+
result = {
|
|
1160
|
+
...result,
|
|
1161
|
+
content: `${result.content}\nThe reviewer replaced the tool arguments before this call.`,
|
|
1162
|
+
};
|
|
1163
|
+
const callSignal = slot.inner?.signal ?? signal;
|
|
1164
|
+
const checks = toolChecks(callSignal);
|
|
1165
|
+
await observe({ type: "tool_end", request, result }, callSignal);
|
|
1166
|
+
invocationActive(slot);
|
|
1167
|
+
if (
|
|
1168
|
+
guardPolicy?.stages.includes("toolOutput") &&
|
|
1169
|
+
jsonBytes(result) > guardPolicy.maxOutputBytes
|
|
1170
|
+
)
|
|
1171
|
+
await checks.overflow("toolOutput", request.operationId, request.attemptId);
|
|
1172
|
+
await checks.check("toolOutput", request.operationId, request.attemptId, {
|
|
1173
|
+
request,
|
|
1174
|
+
result,
|
|
1175
|
+
});
|
|
1176
|
+
invocationActive(slot);
|
|
1177
|
+
// Check after callbacks: another concurrent result may have consumed the remaining bytes.
|
|
1178
|
+
if (
|
|
1179
|
+
result.ok &&
|
|
1180
|
+
result.images &&
|
|
1181
|
+
snapshotInlineBytes(snapshot) +
|
|
1182
|
+
inlineBytes(
|
|
1183
|
+
[
|
|
1184
|
+
{
|
|
1185
|
+
role: "tool",
|
|
1186
|
+
name: request.call.name,
|
|
1187
|
+
toolCallId: request.call.id,
|
|
1188
|
+
content: result.content,
|
|
1189
|
+
images: result.images,
|
|
1190
|
+
},
|
|
1191
|
+
],
|
|
1192
|
+
"",
|
|
1193
|
+
) >
|
|
1194
|
+
limits.inlineBytes
|
|
1195
|
+
)
|
|
1196
|
+
fail(
|
|
1197
|
+
"tool_media_limit",
|
|
1198
|
+
"Tool images exceed this run's inline byte limit. Return fewer or smaller images before starting new work.",
|
|
1199
|
+
request.operationId,
|
|
1200
|
+
);
|
|
1201
|
+
if (slot.inner) result = slot.inner.record(result);
|
|
1202
|
+
const previous = slot.get();
|
|
1203
|
+
slot.set({
|
|
1204
|
+
interrupted: previous.interrupted,
|
|
1205
|
+
retries: previous.retries,
|
|
1206
|
+
asks: previous.asks,
|
|
1207
|
+
calls: previous.calls,
|
|
273
1208
|
id: request.operationId,
|
|
274
|
-
attemptId:
|
|
1209
|
+
attemptId: request.attemptId,
|
|
275
1210
|
status: "completed",
|
|
276
1211
|
result,
|
|
277
|
-
};
|
|
1212
|
+
});
|
|
278
1213
|
await save();
|
|
279
1214
|
emit({ type: "tool_result", request, result });
|
|
280
1215
|
}
|
|
281
1216
|
|
|
282
1217
|
async function runTool(
|
|
283
|
-
|
|
284
|
-
index: number,
|
|
1218
|
+
slot: ToolSlot,
|
|
285
1219
|
request: ToolRequest,
|
|
286
1220
|
tool: Tool | undefined,
|
|
287
1221
|
parallel: boolean,
|
|
288
1222
|
): Promise<void> {
|
|
289
|
-
|
|
1223
|
+
invocationActive(slot);
|
|
1224
|
+
const callSignal = slot.inner?.signal ?? signal;
|
|
290
1225
|
let result: ToolResult;
|
|
291
1226
|
if (!tool) {
|
|
292
1227
|
result = {
|
|
@@ -300,75 +1235,603 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
300
1235
|
kind: "invalid_input",
|
|
301
1236
|
content: "Tool arguments must be one complete JSON object. Send the full object again.",
|
|
302
1237
|
};
|
|
303
|
-
} else if (tool.isTerminal && model
|
|
1238
|
+
} else if (tool.isTerminal && slot.model?.tools.length !== 1) {
|
|
304
1239
|
result = {
|
|
305
1240
|
ok: false,
|
|
306
1241
|
kind: "invalid_input",
|
|
307
|
-
content: `Call ${
|
|
1242
|
+
content: `Call ${tool.name} alone, after the other tool results arrive.`,
|
|
308
1243
|
};
|
|
309
1244
|
} else {
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
);
|
|
320
|
-
|
|
321
|
-
if (
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
);
|
|
1245
|
+
// The barrier can return on abort before its callback unwinds. Retain that callback
|
|
1246
|
+
// so a program cannot finish while a late guard or tool can still write a receipt.
|
|
1247
|
+
let dispatch: Promise<Awaited<ReturnType<Tool["invoke"]>>> | undefined;
|
|
1248
|
+
async function invoke() {
|
|
1249
|
+
invocationActive(slot);
|
|
1250
|
+
const journal = requestsFor(slot.request(), slot.get(), options, scope, callSignal);
|
|
1251
|
+
try {
|
|
1252
|
+
await beforeTool(request, callSignal);
|
|
1253
|
+
if (slot.get().retries.length) await checkToolRetry(slot);
|
|
1254
|
+
await journal.recheck(request);
|
|
1255
|
+
invocationActive(slot);
|
|
1256
|
+
if (slot.inner) {
|
|
1257
|
+
slot.inner.start();
|
|
1258
|
+
if (!tool?.isReadOnly) await save();
|
|
1259
|
+
invocationActive(slot);
|
|
1260
|
+
await journal.recheck(request);
|
|
1261
|
+
invocationActive(slot);
|
|
1262
|
+
}
|
|
1263
|
+
emit({ type: "tool_start", request });
|
|
1264
|
+
invocationActive(slot);
|
|
1265
|
+
// Observers and checkpoints can expire an approval or revoke ownership.
|
|
1266
|
+
// Reauthorize after them, with no further callback before the actual invocation.
|
|
1267
|
+
await journal.recheck(request);
|
|
1268
|
+
await journal.assertFresh();
|
|
1269
|
+
invocationActive(slot);
|
|
1270
|
+
} catch (error) {
|
|
1271
|
+
if (!slot.inner && error instanceof Halt && error.state.status === "suspended")
|
|
1272
|
+
slot.set({
|
|
1273
|
+
id: request.operationId,
|
|
1274
|
+
status: "pending",
|
|
1275
|
+
interrupted: slot.get().interrupted,
|
|
1276
|
+
retries: slot.get().retries,
|
|
1277
|
+
asks: slot.get().asks,
|
|
1278
|
+
});
|
|
1279
|
+
throw error;
|
|
327
1280
|
}
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
1281
|
+
const records = slot.get().asks ?? [];
|
|
1282
|
+
const answers = Object.fromEntries(
|
|
1283
|
+
records
|
|
1284
|
+
.filter(
|
|
1285
|
+
(record) =>
|
|
1286
|
+
!record.closed &&
|
|
1287
|
+
record.request.ask.type === "question" &&
|
|
1288
|
+
record.decision?.type === "answer",
|
|
1289
|
+
)
|
|
1290
|
+
.map((record) => [
|
|
1291
|
+
record.request.ask.type === "question" ? record.request.ask.key : "",
|
|
1292
|
+
record.decision?.type === "answer" ? record.decision.answer : undefined,
|
|
1293
|
+
]),
|
|
332
1294
|
);
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
1295
|
+
const decision = [...records]
|
|
1296
|
+
.reverse()
|
|
1297
|
+
.find((record) => !record.closed && record.decision)?.decision;
|
|
1298
|
+
if (!tool) throw new TypeError("Missing dispatched tool.");
|
|
1299
|
+
return untilAbort(
|
|
1300
|
+
bindMemoryTool(tool, options.memory, snapshot, request).invoke(
|
|
1301
|
+
copyData(request.arguments),
|
|
1302
|
+
{
|
|
1303
|
+
...options.context,
|
|
1304
|
+
answers: immutableCopy(answers),
|
|
1305
|
+
decision: immutableCopy(decision),
|
|
1306
|
+
runId: snapshot.runId,
|
|
1307
|
+
attemptId: request.attemptId,
|
|
1308
|
+
operationId: request.operationId,
|
|
1309
|
+
parentOperationId: request.parentOperationId,
|
|
1310
|
+
callId: request.call.id,
|
|
1311
|
+
signal: callSignal,
|
|
1312
|
+
},
|
|
1313
|
+
),
|
|
1314
|
+
callSignal,
|
|
1315
|
+
);
|
|
1316
|
+
}
|
|
1317
|
+
let outcome;
|
|
1318
|
+
try {
|
|
1319
|
+
outcome = await scope.tree.invokeTool(parallel, callSignal, () => {
|
|
1320
|
+
dispatch = invoke();
|
|
1321
|
+
return dispatch;
|
|
346
1322
|
});
|
|
347
|
-
})
|
|
348
|
-
|
|
1323
|
+
} catch (error) {
|
|
1324
|
+
if (slot.inner && dispatch) await dispatch.catch(() => {});
|
|
1325
|
+
throw error;
|
|
1326
|
+
}
|
|
1327
|
+
// Run/tree stops never buy another model turn. Program-only abort is settled below.
|
|
349
1328
|
if (!outcome.ok) active();
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
1329
|
+
if (
|
|
1330
|
+
!outcome.ok &&
|
|
1331
|
+
isMemoryTool(tool) &&
|
|
1332
|
+
outcome.cause instanceof Error &&
|
|
1333
|
+
outcome.cause.name === "MemoryScopeError"
|
|
1334
|
+
)
|
|
1335
|
+
fail(
|
|
1336
|
+
"memory_scope_violation",
|
|
1337
|
+
"Memory returned another scope's data. Fix the store before continuing.",
|
|
1338
|
+
request.operationId,
|
|
1339
|
+
);
|
|
1340
|
+
if (!outcome.ok && outcome.kind === "failed" && isInputRequired(outcome.cause)) {
|
|
1341
|
+
if (slot.inner) {
|
|
1342
|
+
result = {
|
|
1343
|
+
ok: false,
|
|
1344
|
+
kind: "denied",
|
|
1345
|
+
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."}`,
|
|
1346
|
+
};
|
|
1347
|
+
await finishExecution(slot, request, result);
|
|
1348
|
+
return;
|
|
1349
|
+
}
|
|
1350
|
+
if (slot.get().retries.length)
|
|
1351
|
+
fail(
|
|
1352
|
+
"tool_retry_unsafe",
|
|
1353
|
+
"A retried call requested input. Reconcile it with the host; retries cannot create request replay paths.",
|
|
1354
|
+
request.operationId,
|
|
1355
|
+
);
|
|
1356
|
+
slot.set({
|
|
1357
|
+
id: request.operationId,
|
|
1358
|
+
status: "pending",
|
|
1359
|
+
asks: slot.get().asks,
|
|
1360
|
+
retries: slot.get().retries,
|
|
1361
|
+
interrupted: slot.get().interrupted,
|
|
1362
|
+
});
|
|
1363
|
+
const journal = requestsFor(request, slot.get(), options, scope, signal);
|
|
1364
|
+
const previous = journal.latest(outcome.cause.ask);
|
|
1365
|
+
if (previous?.decision) previous.closed = "invalid";
|
|
1366
|
+
await journal.open(
|
|
1367
|
+
outcome.cause.ask,
|
|
1368
|
+
outcome.cause.problem
|
|
1369
|
+
? { code: "invalid_answer", message: outcome.cause.problem }
|
|
1370
|
+
: undefined,
|
|
1371
|
+
);
|
|
1372
|
+
return;
|
|
1373
|
+
}
|
|
1374
|
+
try {
|
|
1375
|
+
if (slot.inner && outcome.ok) {
|
|
1376
|
+
try {
|
|
1377
|
+
if (outcome.output !== undefined) programJson(outcome.output);
|
|
1378
|
+
result = { ok: true, content: outcome.summary, output: outcome.output };
|
|
1379
|
+
} catch {
|
|
1380
|
+
slot.inner.outputError =
|
|
1381
|
+
"The call ran but returned a non-JSON value. Check its effect before calling it again.";
|
|
1382
|
+
result = { ok: true, content: slot.inner.outputError };
|
|
1383
|
+
}
|
|
1384
|
+
} else
|
|
1385
|
+
result =
|
|
1386
|
+
tool.name === RESULT_TOOL_NAME && outcome.ok
|
|
1387
|
+
? { ok: true, content: outcome.summary }
|
|
1388
|
+
: toolResultOf(outcome);
|
|
1389
|
+
} catch {
|
|
1390
|
+
fail(
|
|
1391
|
+
"invalid_tool_output",
|
|
1392
|
+
"The tool returned unsavable data or unsupported content. Return JSON or core text/image parts.",
|
|
1393
|
+
request.operationId,
|
|
1394
|
+
);
|
|
1395
|
+
}
|
|
1396
|
+
if (outcome.ok && tool.name === RESULT_TOOL_NAME && result.ok)
|
|
1397
|
+
result.final = { candidate: copyData(request.arguments) };
|
|
1398
|
+
if (outcome.ok && snapshot.definition.stopAtTools.includes(tool.name)) {
|
|
1399
|
+
try {
|
|
1400
|
+
const candidate = output ? copyData(outcome.output) : outcome.summary;
|
|
1401
|
+
validateResult(candidate);
|
|
1402
|
+
result = { ...result, ok: true, final: { candidate } };
|
|
1403
|
+
} catch (error) {
|
|
1404
|
+
result = {
|
|
1405
|
+
ok: false,
|
|
1406
|
+
kind: "invalid_output",
|
|
1407
|
+
content: `The tool result did not pass the output check: ${messageOf(error)}`,
|
|
1408
|
+
};
|
|
1409
|
+
}
|
|
1410
|
+
}
|
|
353
1411
|
}
|
|
354
|
-
await
|
|
1412
|
+
await finishExecution(slot, request, result);
|
|
355
1413
|
active();
|
|
356
1414
|
}
|
|
357
1415
|
|
|
358
|
-
|
|
1416
|
+
function canParallel(
|
|
1417
|
+
request: ToolRequest,
|
|
1418
|
+
tool: Tool | undefined,
|
|
1419
|
+
execution: ToolExecution,
|
|
1420
|
+
): boolean {
|
|
1421
|
+
return (
|
|
1422
|
+
!guardrails?.toolInput &&
|
|
1423
|
+
!guardrails?.toolOutput &&
|
|
1424
|
+
!retryBudget(snapshot.definition.toolRetries, request.call.name) &&
|
|
1425
|
+
tool?.isConcurrencySafe === true &&
|
|
1426
|
+
snapshot.definition.enabledTools.includes(tool.name) &&
|
|
1427
|
+
(request.parentOperationId !== undefined || directNames.includes(tool.name)) &&
|
|
1428
|
+
!tool.needsApproval &&
|
|
1429
|
+
!host?.needsApproval &&
|
|
1430
|
+
!execution.asks?.length &&
|
|
1431
|
+
!tool.isTerminal &&
|
|
1432
|
+
host?.canRunConcurrently?.(immutableCopy(request)) === true
|
|
1433
|
+
);
|
|
1434
|
+
}
|
|
1435
|
+
|
|
1436
|
+
async function runProgram(
|
|
359
1437
|
model: CompletedModel,
|
|
360
1438
|
index: number,
|
|
361
1439
|
request: ToolRequest,
|
|
362
|
-
|
|
1440
|
+
code: CodeTool,
|
|
1441
|
+
): Promise<void> {
|
|
1442
|
+
const slot = slotFor(model, index);
|
|
1443
|
+
const previous = slot.get();
|
|
1444
|
+
if (previous.interrupted.length) {
|
|
1445
|
+
requireRecovery(
|
|
1446
|
+
snapshot.definition.recovery?.policy.readOnlyTools?.includes(code.name) === true &&
|
|
1447
|
+
!!host?.beforeTool &&
|
|
1448
|
+
!previous.asks?.length &&
|
|
1449
|
+
(previous.calls ?? []).every(
|
|
1450
|
+
(call) =>
|
|
1451
|
+
call.status === "completed" &&
|
|
1452
|
+
registry.get(call.name)?.isReadOnly &&
|
|
1453
|
+
!call.asks?.length,
|
|
1454
|
+
),
|
|
1455
|
+
previous.interrupted.length - 1,
|
|
1456
|
+
snapshot.definition.recovery,
|
|
1457
|
+
previous.id,
|
|
1458
|
+
);
|
|
1459
|
+
if ((await toolHash(code.name)) !== snapshot.definition.recovery?.toolHashes[code.name])
|
|
1460
|
+
fail(
|
|
1461
|
+
"recovery_definition_changed",
|
|
1462
|
+
"The code bindings changed. Restore the saved definition before restarting.",
|
|
1463
|
+
previous.id,
|
|
1464
|
+
);
|
|
1465
|
+
}
|
|
1466
|
+
const calls = previous.calls ?? [];
|
|
1467
|
+
slot.set({
|
|
1468
|
+
id: request.operationId,
|
|
1469
|
+
attemptId: request.attemptId,
|
|
1470
|
+
status: "running",
|
|
1471
|
+
calls,
|
|
1472
|
+
asks: previous.asks,
|
|
1473
|
+
interrupted: previous.interrupted,
|
|
1474
|
+
retries: previous.retries,
|
|
1475
|
+
});
|
|
1476
|
+
await save();
|
|
1477
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
1478
|
+
try {
|
|
1479
|
+
await beforeTool(request);
|
|
1480
|
+
await requests.recheck(request);
|
|
1481
|
+
active();
|
|
1482
|
+
if (previous.status === "pending" && previous.previousAttemptId)
|
|
1483
|
+
restart("tool", request.operationId, previous.previousAttemptId, request.attemptId);
|
|
1484
|
+
emit({ type: "tool_start", request });
|
|
1485
|
+
await requests.recheck(request);
|
|
1486
|
+
await requests.assertFresh();
|
|
1487
|
+
active();
|
|
1488
|
+
} catch (error) {
|
|
1489
|
+
if (error instanceof Halt && error.state.status === "suspended")
|
|
1490
|
+
slot.set({ ...previous, asks: slot.get().asks });
|
|
1491
|
+
throw error;
|
|
1492
|
+
}
|
|
1493
|
+
const end = new AbortController();
|
|
1494
|
+
const programSignal = AbortSignal.any([signal, end.signal]);
|
|
1495
|
+
const programDeadline = Math.min(
|
|
1496
|
+
Date.now() + code.limits.timeoutMs,
|
|
1497
|
+
deadline,
|
|
1498
|
+
snapshot.tree.startedAt + snapshot.tree.limits.elapsedMs,
|
|
1499
|
+
);
|
|
1500
|
+
const timer = setTimeout(
|
|
1501
|
+
() => end.abort(new Error("The program reached its time limit.")),
|
|
1502
|
+
Math.max(0, programDeadline - Date.now()),
|
|
1503
|
+
);
|
|
1504
|
+
const enabled = code.tools.filter((tool) =>
|
|
1505
|
+
snapshot.definition.enabledTools.includes(tool.name),
|
|
1506
|
+
);
|
|
1507
|
+
const gate = createGate(limits.parallelTools);
|
|
1508
|
+
const jobs: Promise<string>[] = [];
|
|
1509
|
+
let barrier = Promise.resolve();
|
|
1510
|
+
let settled = Promise.resolve();
|
|
1511
|
+
let fatal: unknown;
|
|
1512
|
+
let closed = false;
|
|
1513
|
+
const reject = (kind: string, message: string) =>
|
|
1514
|
+
JSON.stringify({ ok: false, error: { kind, message } });
|
|
1515
|
+
const stopped = (call: ProgramCall): ToolResult => ({
|
|
1516
|
+
ok: false,
|
|
1517
|
+
kind: "aborted",
|
|
1518
|
+
content: call.started
|
|
1519
|
+
? "The program stopped. This call may have partly run. Check its effect before repeating it."
|
|
1520
|
+
: "The program stopped before this call started. It did not run.",
|
|
1521
|
+
});
|
|
1522
|
+
const count = () =>
|
|
1523
|
+
calls
|
|
1524
|
+
.filter((call) => call.programAttemptId === request.attemptId)
|
|
1525
|
+
.reduce((total, call) => total + 1 + call.retries.length, 0);
|
|
1526
|
+
const bridge = {
|
|
1527
|
+
tools: enabled,
|
|
1528
|
+
signal: programSignal,
|
|
1529
|
+
deadline: programDeadline,
|
|
1530
|
+
calls,
|
|
1531
|
+
toolCallsLeft: () =>
|
|
1532
|
+
Math.max(0, Math.min(code.limits.calls - count(), limits.toolCalls - usedTools() - 1)),
|
|
1533
|
+
call(name: string, input: string): Promise<string> {
|
|
1534
|
+
if (closed || programSignal.aborted)
|
|
1535
|
+
return Promise.resolve(
|
|
1536
|
+
reject("aborted", "The program has finished. No more calls can start."),
|
|
1537
|
+
);
|
|
1538
|
+
const tool = enabled.find((tool) => tool.name === name);
|
|
1539
|
+
if (!tool)
|
|
1540
|
+
return Promise.resolve(
|
|
1541
|
+
reject("disabled_tool", "This tool is not bound and enabled for this program."),
|
|
1542
|
+
);
|
|
1543
|
+
if (tool.needsApproval || tool.isTerminal)
|
|
1544
|
+
return Promise.resolve(
|
|
1545
|
+
reject("denied", "This control tool must be called directly, outside code."),
|
|
1546
|
+
);
|
|
1547
|
+
const arguments_ =
|
|
1548
|
+
typeof input === "string" && textBytes(input) <= code.limits.callInputBytes
|
|
1549
|
+
? jsonArguments(input)
|
|
1550
|
+
: undefined;
|
|
1551
|
+
if (!arguments_)
|
|
1552
|
+
return Promise.resolve(
|
|
1553
|
+
reject(
|
|
1554
|
+
"invalid_input",
|
|
1555
|
+
`Pass one JSON object within ${code.limits.callInputBytes} bytes.`,
|
|
1556
|
+
),
|
|
1557
|
+
);
|
|
1558
|
+
if (bridge.toolCallsLeft() === 0)
|
|
1559
|
+
return Promise.resolve(
|
|
1560
|
+
reject(
|
|
1561
|
+
"denied",
|
|
1562
|
+
"The program has no tool calls left. Return what you have; the final direct call is reserved.",
|
|
1563
|
+
),
|
|
1564
|
+
);
|
|
1565
|
+
// Admission and budget reservation are synchronous. Promise.all cannot overspend.
|
|
1566
|
+
const position = calls.length;
|
|
1567
|
+
const operationId = `${request.operationId}/call/${position + 1}`;
|
|
1568
|
+
let call: ProgramCall = {
|
|
1569
|
+
id: operationId,
|
|
1570
|
+
attemptId: request.attemptId,
|
|
1571
|
+
programAttemptId: request.attemptId,
|
|
1572
|
+
name,
|
|
1573
|
+
arguments: arguments_,
|
|
1574
|
+
status: "pending",
|
|
1575
|
+
started: false,
|
|
1576
|
+
interrupted: [],
|
|
1577
|
+
retries: [],
|
|
1578
|
+
};
|
|
1579
|
+
calls.push(call);
|
|
1580
|
+
let reply = reject("aborted", "The call did not finish.");
|
|
1581
|
+
const inner: ToolSlot = {
|
|
1582
|
+
get: () => call,
|
|
1583
|
+
set(execution) {
|
|
1584
|
+
if (execution.status === "delegating" || execution.calls !== undefined)
|
|
1585
|
+
throw new TypeError("A program may only call ordinary tools.");
|
|
1586
|
+
call = {
|
|
1587
|
+
...execution,
|
|
1588
|
+
name,
|
|
1589
|
+
arguments: arguments_,
|
|
1590
|
+
programAttemptId: request.attemptId,
|
|
1591
|
+
attemptId:
|
|
1592
|
+
execution.status === "pending"
|
|
1593
|
+
? `${request.attemptId}/call/${position + 1}/attempt/${execution.retries.length + 1}`
|
|
1594
|
+
: execution.attemptId,
|
|
1595
|
+
started: call.started,
|
|
1596
|
+
bytes: execution.status === "pending" ? undefined : call.bytes,
|
|
1597
|
+
};
|
|
1598
|
+
calls[position] = call;
|
|
1599
|
+
},
|
|
1600
|
+
request: () => ({
|
|
1601
|
+
agentId: id,
|
|
1602
|
+
version,
|
|
1603
|
+
runId: snapshot.runId,
|
|
1604
|
+
attemptId:
|
|
1605
|
+
call.status === "pending" && call.retries.length
|
|
1606
|
+
? `${request.attemptId}/call/${position + 1}/attempt/${call.retries.length + 1}`
|
|
1607
|
+
: call.attemptId,
|
|
1608
|
+
operationId,
|
|
1609
|
+
parentOperationId: request.operationId,
|
|
1610
|
+
...(snapshot.subagent ? { subagent: snapshot.subagent.spec.name } : {}),
|
|
1611
|
+
call: { id: operationId, name, arguments: input },
|
|
1612
|
+
arguments: copyData(arguments_),
|
|
1613
|
+
}),
|
|
1614
|
+
inner: {
|
|
1615
|
+
signal: programSignal,
|
|
1616
|
+
code,
|
|
1617
|
+
callsLeft: () => bridge.toolCallsLeft(),
|
|
1618
|
+
start() {
|
|
1619
|
+
call = {
|
|
1620
|
+
id: call.id,
|
|
1621
|
+
name,
|
|
1622
|
+
arguments: arguments_,
|
|
1623
|
+
programAttemptId: request.attemptId,
|
|
1624
|
+
interrupted: call.interrupted,
|
|
1625
|
+
retries: call.retries,
|
|
1626
|
+
asks: call.asks,
|
|
1627
|
+
status: "running",
|
|
1628
|
+
attemptId: inner.request().attemptId,
|
|
1629
|
+
started: true,
|
|
1630
|
+
};
|
|
1631
|
+
calls[position] = call;
|
|
1632
|
+
},
|
|
1633
|
+
record(result) {
|
|
1634
|
+
const receipt = programReceipt(result);
|
|
1635
|
+
call.bytes = receipt.bytes;
|
|
1636
|
+
reply = inner.inner?.outputError
|
|
1637
|
+
? reject("invalid_output", inner.inner.outputError)
|
|
1638
|
+
: programReply(result, code.limits.callOutputBytes);
|
|
1639
|
+
return receipt.result;
|
|
1640
|
+
},
|
|
1641
|
+
},
|
|
1642
|
+
};
|
|
1643
|
+
let concurrent = false;
|
|
1644
|
+
const work = (async () => {
|
|
1645
|
+
let releaseCall = () => {};
|
|
1646
|
+
try {
|
|
1647
|
+
// Synchronous admission is host work too: a throw must settle its pending call.
|
|
1648
|
+
concurrent = canParallel(inner.request(), tool, call);
|
|
1649
|
+
await (concurrent ? barrier : settled);
|
|
1650
|
+
releaseCall = await gate.acquire(programSignal);
|
|
1651
|
+
do {
|
|
1652
|
+
invocationActive(inner);
|
|
1653
|
+
let effective = inner.request();
|
|
1654
|
+
const journal = requestsFor(effective, call, options, scope, programSignal);
|
|
1655
|
+
if (await needsApproval(effective, options, programSignal)) {
|
|
1656
|
+
let refusal: ToolResult | undefined;
|
|
1657
|
+
if (!host?.prepareRequest || !host.beforeTool)
|
|
1658
|
+
refusal = {
|
|
1659
|
+
ok: false,
|
|
1660
|
+
kind: "denied",
|
|
1661
|
+
content: "This call needs a person's approval, and code cannot wait for one.",
|
|
1662
|
+
};
|
|
1663
|
+
else {
|
|
1664
|
+
const record = await journal.ensure({ type: "approval" });
|
|
1665
|
+
const decision = record.decision;
|
|
1666
|
+
if (decision?.type === "approve") {
|
|
1667
|
+
if (decision.arguments !== undefined)
|
|
1668
|
+
effective = { ...effective, arguments: copyData(decision.arguments) };
|
|
1669
|
+
} else {
|
|
1670
|
+
if (!record.decision) record.closed = "stopped";
|
|
1671
|
+
refusal = {
|
|
1672
|
+
ok: false,
|
|
1673
|
+
kind: decision?.type === "cancel" ? "cancelled" : "denied",
|
|
1674
|
+
content:
|
|
1675
|
+
decision?.type === "deny"
|
|
1676
|
+
? (decision.message ?? "The person denied this call.")
|
|
1677
|
+
: "This call needs a person's approval, and code cannot wait for one.",
|
|
1678
|
+
};
|
|
1679
|
+
}
|
|
1680
|
+
}
|
|
1681
|
+
if (refusal) {
|
|
1682
|
+
if (directNames.includes(name)) refusal.content += ` Call ${name} directly.`;
|
|
1683
|
+
await finishExecution(inner, effective, refusal);
|
|
1684
|
+
break;
|
|
1685
|
+
}
|
|
1686
|
+
}
|
|
1687
|
+
if (textBytes(programJson(effective.arguments)) > code.limits.callInputBytes) {
|
|
1688
|
+
await finishExecution(inner, effective, {
|
|
1689
|
+
ok: false,
|
|
1690
|
+
kind: "invalid_input",
|
|
1691
|
+
content: `The approved arguments exceed ${code.limits.callInputBytes} bytes. Send less data.`,
|
|
1692
|
+
});
|
|
1693
|
+
break;
|
|
1694
|
+
}
|
|
1695
|
+
if (call.status === "pending" && call.previousAttemptId) {
|
|
1696
|
+
emit({
|
|
1697
|
+
type: "operation_restart",
|
|
1698
|
+
kind: "tool",
|
|
1699
|
+
runId: snapshot.runId,
|
|
1700
|
+
operationId,
|
|
1701
|
+
parentOperationId: request.operationId,
|
|
1702
|
+
previousAttemptId: call.previousAttemptId,
|
|
1703
|
+
attemptId: effective.attemptId,
|
|
1704
|
+
});
|
|
1705
|
+
}
|
|
1706
|
+
await withToolError(
|
|
1707
|
+
effective,
|
|
1708
|
+
() => runTool(inner, effective, tool, concurrent),
|
|
1709
|
+
programSignal,
|
|
1710
|
+
);
|
|
1711
|
+
if (count() >= code.limits.calls || programSignal.aborted) break;
|
|
1712
|
+
} while (await retryTool(inner));
|
|
1713
|
+
return reply;
|
|
1714
|
+
} catch (error) {
|
|
1715
|
+
// A host/guard/checkpoint error stops the run, not merely one guest call.
|
|
1716
|
+
if (
|
|
1717
|
+
!programSignal.aborted &&
|
|
1718
|
+
!(error instanceof Halt && error.state.status === "suspended")
|
|
1719
|
+
) {
|
|
1720
|
+
fatal ??= error;
|
|
1721
|
+
end.abort(error);
|
|
1722
|
+
}
|
|
1723
|
+
for (const ask of call.asks ?? [])
|
|
1724
|
+
if (!ask.closed && !ask.decision) ask.closed = "stopped";
|
|
1725
|
+
if (
|
|
1726
|
+
!programSignal.aborted &&
|
|
1727
|
+
error instanceof Halt &&
|
|
1728
|
+
error.state.status === "suspended"
|
|
1729
|
+
) {
|
|
1730
|
+
const result: ToolResult = {
|
|
1731
|
+
ok: false,
|
|
1732
|
+
kind: "denied",
|
|
1733
|
+
content:
|
|
1734
|
+
"The approval expired. Code cannot wait for a new decision. Call this tool directly.",
|
|
1735
|
+
};
|
|
1736
|
+
await finishExecution(inner, inner.request(), result);
|
|
1737
|
+
return programReply(result, code.limits.callOutputBytes);
|
|
1738
|
+
}
|
|
1739
|
+
if (inner.get().status !== "completed") {
|
|
1740
|
+
const result = stopped(call);
|
|
1741
|
+
inner.set({
|
|
1742
|
+
id: operationId,
|
|
1743
|
+
attemptId: call.attemptId,
|
|
1744
|
+
status: "completed",
|
|
1745
|
+
interrupted: call.interrupted,
|
|
1746
|
+
retries: call.retries,
|
|
1747
|
+
asks: call.asks,
|
|
1748
|
+
result: programReceipt(result).result,
|
|
1749
|
+
});
|
|
1750
|
+
await save();
|
|
1751
|
+
if (!guardPolicy?.stages.includes("toolOutput"))
|
|
1752
|
+
emit({ type: "tool_result", request: inner.request(), result });
|
|
1753
|
+
}
|
|
1754
|
+
return reject(
|
|
1755
|
+
"aborted",
|
|
1756
|
+
"The call stopped. Check its saved receipt before repeating it.",
|
|
1757
|
+
);
|
|
1758
|
+
} finally {
|
|
1759
|
+
releaseCall();
|
|
1760
|
+
}
|
|
1761
|
+
})();
|
|
1762
|
+
const done = work.then(
|
|
1763
|
+
() => {},
|
|
1764
|
+
() => {},
|
|
1765
|
+
);
|
|
1766
|
+
settled = Promise.all([settled, done]).then(() => {});
|
|
1767
|
+
if (!concurrent) barrier = settled;
|
|
1768
|
+
jobs.push(work);
|
|
1769
|
+
return work.catch((error) => {
|
|
1770
|
+
fatal ??= error;
|
|
1771
|
+
end.abort(error);
|
|
1772
|
+
return reject(
|
|
1773
|
+
"aborted",
|
|
1774
|
+
"The host could not record the call. Stop and reconcile its effect.",
|
|
1775
|
+
);
|
|
1776
|
+
});
|
|
1777
|
+
},
|
|
1778
|
+
async settle() {
|
|
1779
|
+
closed = true;
|
|
1780
|
+
end.abort(new Error("The program has finished."));
|
|
1781
|
+
await Promise.allSettled(jobs);
|
|
1782
|
+
clearTimeout(timer);
|
|
1783
|
+
if (fatal) throw fatal;
|
|
1784
|
+
// A deadline may interrupt a guard after an effect returned. Never turn its
|
|
1785
|
+
// unfinished verdict into a successful program or buy another model turn.
|
|
1786
|
+
requireGuardVerdicts(snapshot);
|
|
1787
|
+
},
|
|
1788
|
+
};
|
|
1789
|
+
const outcome = await code.execute(
|
|
1790
|
+
completeArguments(request.call.arguments) ? request.arguments : undefined,
|
|
1791
|
+
bridge,
|
|
1792
|
+
);
|
|
1793
|
+
await finishTool(model, index, request, outcome.result);
|
|
1794
|
+
active();
|
|
1795
|
+
}
|
|
1796
|
+
|
|
1797
|
+
async function runDelegation(
|
|
1798
|
+
model: CompletedModel,
|
|
1799
|
+
index: number,
|
|
1800
|
+
request: ToolRequest,
|
|
1801
|
+
descriptor: Delegation,
|
|
363
1802
|
): Promise<void> {
|
|
364
1803
|
let journal = snapshot.delegations.find((entry) => entry.operationId === request.operationId);
|
|
365
1804
|
if (!journal) {
|
|
366
|
-
journal = { operationId: request.operationId, children: [] };
|
|
1805
|
+
journal = { kind: "delegation", operationId: request.operationId, children: [] };
|
|
367
1806
|
snapshot.delegations.push(journal);
|
|
368
1807
|
}
|
|
1808
|
+
if (journal.kind === "handoff") {
|
|
1809
|
+
try {
|
|
1810
|
+
const note = handoffNote(request.arguments);
|
|
1811
|
+
if (journal.children.length > 0 && note !== journal.note)
|
|
1812
|
+
throw new TypeError("The transfer note changed after the target started.");
|
|
1813
|
+
journal.note = note;
|
|
1814
|
+
} catch (error) {
|
|
1815
|
+
if (journal.children.length > 0)
|
|
1816
|
+
fail(
|
|
1817
|
+
"handoff_input_changed",
|
|
1818
|
+
"The target already started. Its transfer arguments cannot change. Reconcile the saved run before starting different work.",
|
|
1819
|
+
request.operationId,
|
|
1820
|
+
);
|
|
1821
|
+
await finishTool(model, index, request, {
|
|
1822
|
+
ok: false,
|
|
1823
|
+
kind: "invalid_input",
|
|
1824
|
+
content: messageOf(error),
|
|
1825
|
+
});
|
|
1826
|
+
return;
|
|
1827
|
+
}
|
|
1828
|
+
}
|
|
369
1829
|
model.tools[index] = {
|
|
1830
|
+
interrupted: model.tools[index]?.interrupted ?? [],
|
|
1831
|
+
retries: model.tools[index]?.retries ?? [],
|
|
1832
|
+
asks: model.tools[index]?.asks,
|
|
370
1833
|
id: request.operationId,
|
|
371
|
-
attemptId:
|
|
1834
|
+
attemptId: request.attemptId,
|
|
372
1835
|
status: "delegating",
|
|
373
1836
|
};
|
|
374
1837
|
await save();
|
|
@@ -381,10 +1844,16 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
381
1844
|
});
|
|
382
1845
|
return;
|
|
383
1846
|
}
|
|
384
|
-
|
|
1847
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
1848
|
+
refuseGuardedReplay(snapshot, request.operationId);
|
|
1849
|
+
await beforeTool(request);
|
|
1850
|
+
await requests.recheck(request);
|
|
385
1851
|
active();
|
|
386
1852
|
emit({ type: "tool_start", request });
|
|
387
1853
|
active();
|
|
1854
|
+
await requests.recheck(request);
|
|
1855
|
+
await requests.assertFresh();
|
|
1856
|
+
active();
|
|
388
1857
|
// Coordination is pure and is the only place children can start. Lend once
|
|
389
1858
|
// for this entire barrier, including ignored children and overlapping joins.
|
|
390
1859
|
release();
|
|
@@ -399,7 +1868,7 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
399
1868
|
scope,
|
|
400
1869
|
signal,
|
|
401
1870
|
active,
|
|
402
|
-
|
|
1871
|
+
requests,
|
|
403
1872
|
);
|
|
404
1873
|
} finally {
|
|
405
1874
|
release = await scope.tree.gate.acquire(signal);
|
|
@@ -408,6 +1877,82 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
408
1877
|
await finishTool(model, index, request, result);
|
|
409
1878
|
}
|
|
410
1879
|
|
|
1880
|
+
async function openApprovals(model: CompletedModel, from: number): Promise<void> {
|
|
1881
|
+
for (let index = from; index < model.tools.length; index++) {
|
|
1882
|
+
const execution = model.tools[index];
|
|
1883
|
+
if (!execution || execution.status === "completed") continue;
|
|
1884
|
+
if (usedTools() >= limits.toolCalls && !execution.asks?.length) break;
|
|
1885
|
+
const request = requestFor(snapshot, model, index);
|
|
1886
|
+
const tool = tools.find((tool) => tool.name === request.call.name);
|
|
1887
|
+
if (
|
|
1888
|
+
!tool ||
|
|
1889
|
+
request.call.name === RESULT_TOOL_NAME ||
|
|
1890
|
+
!snapshot.definition.enabledTools.includes(tool.name) ||
|
|
1891
|
+
snapshot.definition.modelSettings.toolChoice === "none" ||
|
|
1892
|
+
!completeArguments(request.call.arguments) ||
|
|
1893
|
+
(isHandoff(tool) && model.tools.length !== 1) ||
|
|
1894
|
+
(!isDelegation(tool) &&
|
|
1895
|
+
!isHandoff(tool) &&
|
|
1896
|
+
!isClientTool(tool) &&
|
|
1897
|
+
!isCodeTool(tool) &&
|
|
1898
|
+
tool.isTerminal &&
|
|
1899
|
+
model.tools.length !== 1)
|
|
1900
|
+
)
|
|
1901
|
+
continue;
|
|
1902
|
+
if (await needsApproval(request, options, signal))
|
|
1903
|
+
await journalFor(snapshot, model, index, options, scope, signal).ensure({
|
|
1904
|
+
type: "approval",
|
|
1905
|
+
});
|
|
1906
|
+
}
|
|
1907
|
+
}
|
|
1908
|
+
|
|
1909
|
+
async function runClient(
|
|
1910
|
+
model: CompletedModel,
|
|
1911
|
+
index: number,
|
|
1912
|
+
request: ToolRequest,
|
|
1913
|
+
client: ClientTool,
|
|
1914
|
+
): Promise<void> {
|
|
1915
|
+
try {
|
|
1916
|
+
if (!completeArguments(request.call.arguments))
|
|
1917
|
+
throw new TypeError("Send one complete JSON object.");
|
|
1918
|
+
client.validateArguments(request.arguments);
|
|
1919
|
+
} catch (error) {
|
|
1920
|
+
await finishTool(model, index, request, {
|
|
1921
|
+
ok: false,
|
|
1922
|
+
kind: "invalid_input",
|
|
1923
|
+
content: messageOf(error),
|
|
1924
|
+
});
|
|
1925
|
+
return;
|
|
1926
|
+
}
|
|
1927
|
+
if (!host?.beforeTool)
|
|
1928
|
+
fail("request_host_missing", "Provide host.beforeTool before dispatching a client tool.");
|
|
1929
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal, request);
|
|
1930
|
+
refuseGuardedReplay(snapshot, request.operationId);
|
|
1931
|
+
await beforeTool(request);
|
|
1932
|
+
await requests.recheck(request);
|
|
1933
|
+
const record = await requests.ensure({ type: "client", resultSchema: client.resultSchema });
|
|
1934
|
+
if (!record.decision) return;
|
|
1935
|
+
if (record.decision.type === "stop") {
|
|
1936
|
+
scope.tree.stop();
|
|
1937
|
+
throw new Halt({ status: "cancelled" });
|
|
1938
|
+
}
|
|
1939
|
+
if (record.decision.type === "cancel") {
|
|
1940
|
+
await finishTool(model, index, request, {
|
|
1941
|
+
ok: false,
|
|
1942
|
+
kind: "cancelled",
|
|
1943
|
+
content:
|
|
1944
|
+
"The person cancelled this client request. This does not undo an action already taken.",
|
|
1945
|
+
});
|
|
1946
|
+
return;
|
|
1947
|
+
}
|
|
1948
|
+
if (record.decision.type !== "result")
|
|
1949
|
+
throw new TypeError("A client request needs a result.");
|
|
1950
|
+
await requests.recheck(request);
|
|
1951
|
+
active();
|
|
1952
|
+
const result = client.result(record.decision.value);
|
|
1953
|
+
await finishTool(model, index, request, successfulToolResult(result));
|
|
1954
|
+
}
|
|
1955
|
+
|
|
411
1956
|
async function handleTurn(model: CompletedModel): Promise<void> {
|
|
412
1957
|
active();
|
|
413
1958
|
const { message, finishReason } = model.turn;
|
|
@@ -442,58 +1987,185 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
442
1987
|
return;
|
|
443
1988
|
}
|
|
444
1989
|
|
|
1990
|
+
// The one extra call at the local turn limit has no tools, even if a provider ignores
|
|
1991
|
+
// toolChoice. Never execute calls it returns. The shared tree limit remains a hard cap.
|
|
1992
|
+
if (snapshot.models.indexOf(model) >= limits.turns)
|
|
1993
|
+
throw new Halt({ status: "limited", limit: "turns" });
|
|
1994
|
+
|
|
445
1995
|
for (let index = 0; index < calls.length;) {
|
|
446
|
-
if (
|
|
1996
|
+
if (
|
|
1997
|
+
model.tools[index]?.status === "completed" &&
|
|
1998
|
+
!(await retryTool(slotFor(model, index)))
|
|
1999
|
+
) {
|
|
447
2000
|
index++;
|
|
448
2001
|
continue;
|
|
449
2002
|
}
|
|
450
2003
|
active();
|
|
451
2004
|
const capacity = limits.toolCalls - usedTools();
|
|
452
|
-
if (
|
|
2005
|
+
if (
|
|
2006
|
+
capacity <= 0 &&
|
|
2007
|
+
model.tools[index]?.status === "pending" &&
|
|
2008
|
+
!model.tools[index]?.asks?.length
|
|
2009
|
+
)
|
|
453
2010
|
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
if (
|
|
457
|
-
|
|
2011
|
+
let request = requestFor(snapshot, model, index);
|
|
2012
|
+
if (model.tools[index]?.retries.length) await checkToolRetry(slotFor(model, index));
|
|
2013
|
+
if (
|
|
2014
|
+
!directNames.includes(request.call.name) ||
|
|
2015
|
+
!snapshot.definition.enabledTools.includes(request.call.name) ||
|
|
2016
|
+
snapshot.definition.modelSettings.toolChoice === "none"
|
|
2017
|
+
) {
|
|
2018
|
+
await finishTool(model, index, request, {
|
|
2019
|
+
ok: false,
|
|
2020
|
+
kind: names.includes(request.call.name) ? "disabled_tool" : "unknown_tool",
|
|
2021
|
+
content: "This tool is not available in this run. Choose one of the provided tools.",
|
|
2022
|
+
});
|
|
458
2023
|
index++;
|
|
459
2024
|
continue;
|
|
460
2025
|
}
|
|
2026
|
+
const handoff = handoffs.get(request.call.name);
|
|
2027
|
+
if (
|
|
2028
|
+
handoff &&
|
|
2029
|
+
!snapshot.delegations.some((entry) => entry.operationId === request.operationId)
|
|
2030
|
+
) {
|
|
2031
|
+
let target;
|
|
2032
|
+
let note;
|
|
2033
|
+
try {
|
|
2034
|
+
if (calls.length !== 1)
|
|
2035
|
+
throw new TypeError(
|
|
2036
|
+
`Call ${handoff.name} alone, after the other tool results arrive.`,
|
|
2037
|
+
);
|
|
2038
|
+
if (!completeArguments(request.call.arguments))
|
|
2039
|
+
throw new TypeError(
|
|
2040
|
+
"Tool arguments must be one complete JSON object. Send the full object again.",
|
|
2041
|
+
);
|
|
2042
|
+
note = handoffNote(request.arguments);
|
|
2043
|
+
target = handoff.target();
|
|
2044
|
+
if (target.id === id)
|
|
2045
|
+
throw new TypeError(
|
|
2046
|
+
"This agent already owns the conversation. Choose a different target.",
|
|
2047
|
+
);
|
|
2048
|
+
checkHandoffTargets(agent);
|
|
2049
|
+
} catch (error) {
|
|
2050
|
+
await finishTool(model, index, request, {
|
|
2051
|
+
ok: false,
|
|
2052
|
+
kind: "invalid_input",
|
|
2053
|
+
content: messageOf(error),
|
|
2054
|
+
});
|
|
2055
|
+
index++;
|
|
2056
|
+
continue;
|
|
2057
|
+
}
|
|
2058
|
+
// Pin identity before asking for permission. A resumed lazy reference cannot turn
|
|
2059
|
+
// an approval for one target into a transfer to another.
|
|
2060
|
+
snapshot.delegations.push({
|
|
2061
|
+
kind: "handoff",
|
|
2062
|
+
operationId: request.operationId,
|
|
2063
|
+
target: handoffRef(target),
|
|
2064
|
+
...(note !== undefined ? { note } : {}),
|
|
2065
|
+
children: [],
|
|
2066
|
+
});
|
|
2067
|
+
model.tools[index] = {
|
|
2068
|
+
id: request.operationId,
|
|
2069
|
+
status: "delegating",
|
|
2070
|
+
attemptId: snapshot.attemptId,
|
|
2071
|
+
interrupted: [],
|
|
2072
|
+
retries: [],
|
|
2073
|
+
};
|
|
2074
|
+
await save();
|
|
2075
|
+
active();
|
|
2076
|
+
}
|
|
2077
|
+
const descriptor = descriptorFor(request.call.name, snapshot, request.operationId);
|
|
461
2078
|
const tool = registry.get(request.call.name);
|
|
2079
|
+
const client = clients.get(request.call.name);
|
|
2080
|
+
const code = codeTools.get(request.call.name);
|
|
2081
|
+
const requests = journalFor(snapshot, model, index, options, scope, signal);
|
|
462
2082
|
if (
|
|
463
|
-
tool
|
|
2083
|
+
(tool || descriptor || client || code) &&
|
|
464
2084
|
completeArguments(request.call.arguments) &&
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
2085
|
+
(!tool?.isTerminal || model.tools.length === 1) &&
|
|
2086
|
+
(await needsApproval(request, options, signal))
|
|
2087
|
+
)
|
|
2088
|
+
await requests.ensure({ type: "approval" });
|
|
2089
|
+
const records = model.tools[index]?.asks ?? [];
|
|
2090
|
+
if (records.some((record) => !record.closed && record.decision?.type === "stop")) {
|
|
2091
|
+
scope.tree.stop();
|
|
2092
|
+
throw new Halt({ status: "cancelled" });
|
|
2093
|
+
}
|
|
2094
|
+
const decline = records.find(
|
|
2095
|
+
(record) =>
|
|
2096
|
+
!record.closed &&
|
|
2097
|
+
(record.decision?.type === "deny" || record.decision?.type === "cancel"),
|
|
2098
|
+
);
|
|
2099
|
+
if (decline?.decision) {
|
|
2100
|
+
await finishTool(
|
|
2101
|
+
model,
|
|
2102
|
+
index,
|
|
2103
|
+
request,
|
|
2104
|
+
decline.decision.type === "deny"
|
|
2105
|
+
? {
|
|
2106
|
+
ok: false,
|
|
2107
|
+
kind: "denied",
|
|
2108
|
+
content:
|
|
2109
|
+
decline.decision.message ??
|
|
2110
|
+
"The person denied this call. Continue without this action.",
|
|
2111
|
+
}
|
|
2112
|
+
: {
|
|
2113
|
+
ok: false,
|
|
2114
|
+
kind: "cancelled",
|
|
2115
|
+
content: "The person cancelled this request. Continue without this action.",
|
|
2116
|
+
},
|
|
475
2117
|
);
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
);
|
|
483
|
-
snapshot.state = {
|
|
484
|
-
status: "suspended",
|
|
485
|
-
approval: { request: copyData(request), scope },
|
|
486
|
-
path: [],
|
|
487
|
-
};
|
|
2118
|
+
index++;
|
|
2119
|
+
continue;
|
|
2120
|
+
}
|
|
2121
|
+
if (records.some((record) => !record.closed && !record.decision)) {
|
|
2122
|
+
await openApprovals(model, index + 1);
|
|
2123
|
+
snapshot.state = { status: "suspended" };
|
|
488
2124
|
return;
|
|
489
2125
|
}
|
|
2126
|
+
const approval = requests.latest({ type: "approval" })?.decision;
|
|
2127
|
+
if (approval?.type === "approve" && approval.arguments !== undefined)
|
|
2128
|
+
request = { ...request, arguments: copyData(approval.arguments) };
|
|
2129
|
+
if (code) {
|
|
2130
|
+
await withToolError(request, () => runProgram(model, index, request, code));
|
|
2131
|
+
index++;
|
|
2132
|
+
continue;
|
|
2133
|
+
}
|
|
2134
|
+
if (descriptor) {
|
|
2135
|
+
await withToolError(request, () => runDelegation(model, index, request, descriptor));
|
|
2136
|
+
index++;
|
|
2137
|
+
continue;
|
|
2138
|
+
}
|
|
2139
|
+
if (client) {
|
|
2140
|
+
await withToolError(request, () => runClient(model, index, request, client));
|
|
2141
|
+
if (model.tools[index]?.status !== "completed") {
|
|
2142
|
+
await openApprovals(model, index + 1);
|
|
2143
|
+
snapshot.state = { status: "suspended" };
|
|
2144
|
+
return;
|
|
2145
|
+
}
|
|
2146
|
+
index++;
|
|
2147
|
+
continue;
|
|
2148
|
+
}
|
|
490
2149
|
|
|
491
|
-
const
|
|
2150
|
+
const execution = model.tools[index];
|
|
2151
|
+
const batch = [
|
|
2152
|
+
{
|
|
2153
|
+
index,
|
|
2154
|
+
request,
|
|
2155
|
+
tool,
|
|
2156
|
+
previousAttemptId:
|
|
2157
|
+
execution?.status === "pending" ? execution.previousAttemptId : undefined,
|
|
2158
|
+
},
|
|
2159
|
+
];
|
|
492
2160
|
const parallel = (request: ToolRequest, tool?: Tool) =>
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
2161
|
+
canParallel(
|
|
2162
|
+
request,
|
|
2163
|
+
tool,
|
|
2164
|
+
slotFor(
|
|
2165
|
+
model,
|
|
2166
|
+
model.tools.findIndex((entry) => entry.id === request.operationId),
|
|
2167
|
+
).get(),
|
|
2168
|
+
);
|
|
497
2169
|
const concurrent = parallel(request, tool);
|
|
498
2170
|
if (concurrent) {
|
|
499
2171
|
for (
|
|
@@ -501,180 +2173,534 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
501
2173
|
next < calls.length && batch.length < Math.min(limits.parallelTools, capacity);
|
|
502
2174
|
next++
|
|
503
2175
|
) {
|
|
504
|
-
|
|
505
|
-
|
|
2176
|
+
const execution = model.tools[next];
|
|
2177
|
+
if (execution?.status !== "pending") break;
|
|
2178
|
+
const nextRequest = requestFor(snapshot, model, next);
|
|
506
2179
|
const nextTool = registry.get(nextRequest.call.name);
|
|
507
2180
|
if (!parallel(nextRequest, nextTool)) break;
|
|
508
|
-
batch.push({
|
|
2181
|
+
batch.push({
|
|
2182
|
+
index: next,
|
|
2183
|
+
request: nextRequest,
|
|
2184
|
+
tool: nextTool,
|
|
2185
|
+
previousAttemptId: execution.previousAttemptId,
|
|
2186
|
+
});
|
|
509
2187
|
}
|
|
510
2188
|
}
|
|
2189
|
+
// A checkpoint can capture the pending retry while another child saves. Check its
|
|
2190
|
+
// identity again before admission, even if this worker did not perform the reset.
|
|
2191
|
+
for (const job of batch) {
|
|
2192
|
+
const execution = model.tools[job.index];
|
|
2193
|
+
if (execution?.interrupted.length && !execution.asks?.length)
|
|
2194
|
+
await checkToolRecovery(
|
|
2195
|
+
model,
|
|
2196
|
+
job.index,
|
|
2197
|
+
execution.interrupted.length + execution.retries.length - 1,
|
|
2198
|
+
);
|
|
2199
|
+
}
|
|
511
2200
|
active();
|
|
512
2201
|
// Reserve the whole admitted batch before any invocation, including its tool-call budget.
|
|
513
2202
|
for (const job of batch)
|
|
514
2203
|
model.tools[job.index] = {
|
|
2204
|
+
interrupted: model.tools[job.index]?.interrupted ?? [],
|
|
2205
|
+
retries: model.tools[job.index]?.retries ?? [],
|
|
2206
|
+
asks: model.tools[job.index]?.asks,
|
|
515
2207
|
id: job.request.operationId,
|
|
516
|
-
attemptId:
|
|
2208
|
+
attemptId: job.request.attemptId,
|
|
517
2209
|
status: "running",
|
|
518
2210
|
};
|
|
519
2211
|
await save();
|
|
520
2212
|
const settled = await Promise.allSettled(
|
|
521
|
-
batch.map((job) =>
|
|
2213
|
+
batch.map((job) => {
|
|
2214
|
+
// Retry and recovery histories can interleave. Use the predecessor saved when
|
|
2215
|
+
// this replacement was scheduled, not the tail of either history alone.
|
|
2216
|
+
if (job.previousAttemptId)
|
|
2217
|
+
restart(
|
|
2218
|
+
"tool",
|
|
2219
|
+
job.request.operationId,
|
|
2220
|
+
job.previousAttemptId,
|
|
2221
|
+
job.request.attemptId,
|
|
2222
|
+
);
|
|
2223
|
+
return withToolError(job.request, () =>
|
|
2224
|
+
runTool(slotFor(model, job.index), job.request, job.tool, concurrent),
|
|
2225
|
+
);
|
|
2226
|
+
}),
|
|
522
2227
|
);
|
|
523
2228
|
const rejected = settled.find((result) => result.status === "rejected");
|
|
524
2229
|
if (rejected?.status === "rejected") throw rejected.reason;
|
|
525
|
-
|
|
526
|
-
|
|
2230
|
+
if (batch.some((job) => model.tools[job.index]?.status === "pending")) {
|
|
2231
|
+
if (
|
|
2232
|
+
batch.some((job) =>
|
|
2233
|
+
model.tools[job.index]?.asks?.some((record) => !record.closed && !record.decision),
|
|
2234
|
+
)
|
|
2235
|
+
) {
|
|
2236
|
+
await openApprovals(model, index + batch.length);
|
|
2237
|
+
snapshot.state = { status: "suspended" };
|
|
2238
|
+
return;
|
|
2239
|
+
}
|
|
2240
|
+
continue;
|
|
2241
|
+
}
|
|
2242
|
+
// Retrying tools run serially. Revisit their settled failure through the same
|
|
2243
|
+
// admission path; ordinary batches advance as before.
|
|
2244
|
+
if (!retryBudget(snapshot.definition.toolRetries, request.call.name)) index += batch.length;
|
|
527
2245
|
}
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
2246
|
+
// Adapted from OpenAI Agents JS (MIT), runner/toolExecution.ts: settle this batch,
|
|
2247
|
+
// then select the first stopping tool in model order, not completion order.
|
|
2248
|
+
const final =
|
|
2249
|
+
finalHandoffResult(snapshot, model) ??
|
|
2250
|
+
finalToolResult(
|
|
2251
|
+
model,
|
|
2252
|
+
snapshot.definition.stopAtTools,
|
|
2253
|
+
output ? RESULT_TOOL_NAME : undefined,
|
|
2254
|
+
);
|
|
2255
|
+
if (final) snapshot.state = { status: "completed", candidate: final.candidate };
|
|
2256
|
+
}
|
|
2257
|
+
|
|
2258
|
+
// One load per media id per attempt. The bytes live only in the requests built from it,
|
|
2259
|
+
// never in the journal, the outcome or an event. The per-run cache of pending loads is
|
|
2260
|
+
// adapted from TanStack AI (MIT), packages/ai-harness/src/media.ts.
|
|
2261
|
+
const media = new Map<string, Promise<string>>();
|
|
2262
|
+
function loadMedia(ref: MediaRef): Promise<string> {
|
|
2263
|
+
let loaded = media.get(ref.id);
|
|
2264
|
+
if (!loaded) {
|
|
2265
|
+
loaded = readMedia(ref);
|
|
2266
|
+
media.set(ref.id, loaded);
|
|
2267
|
+
}
|
|
2268
|
+
return loaded;
|
|
2269
|
+
}
|
|
2270
|
+
async function readMedia(ref: MediaRef): Promise<string> {
|
|
2271
|
+
const load = host?.loadMedia;
|
|
2272
|
+
if (!load)
|
|
2273
|
+
fail(
|
|
2274
|
+
"media_unavailable",
|
|
2275
|
+
"This run has media references. Provide host.loadMedia to read their bytes.",
|
|
2276
|
+
);
|
|
2277
|
+
let data: unknown;
|
|
2278
|
+
try {
|
|
2279
|
+
data = await untilAbort(
|
|
2280
|
+
Promise.resolve(load(immutableCopy(ref), { runId: snapshot.runId, signal })),
|
|
2281
|
+
signal,
|
|
2282
|
+
);
|
|
2283
|
+
} catch {
|
|
2284
|
+
active();
|
|
2285
|
+
// Loader errors can quote credentials from a header or request. Never persist them.
|
|
2286
|
+
fail(
|
|
2287
|
+
"media_unavailable",
|
|
2288
|
+
"The media could not be loaded. Check file access before trying again.",
|
|
2289
|
+
);
|
|
537
2290
|
}
|
|
2291
|
+
if (!isBase64(data))
|
|
2292
|
+
fail(
|
|
2293
|
+
"media_unavailable",
|
|
2294
|
+
`host.loadMedia returned no base64 bytes for media ${ref.id}. Return the bytes as padded base64 text.`,
|
|
2295
|
+
);
|
|
2296
|
+
return data;
|
|
538
2297
|
}
|
|
539
2298
|
|
|
540
|
-
async function
|
|
2299
|
+
async function compact(): Promise<void> {
|
|
2300
|
+
const last = snapshot.compactions.at(-1);
|
|
2301
|
+
if (last?.status === "running")
|
|
2302
|
+
fail(
|
|
2303
|
+
"interrupted_compaction",
|
|
2304
|
+
"The summary has no saved result and may have been billed. Reconcile it with the host before continuing.",
|
|
2305
|
+
last.id,
|
|
2306
|
+
);
|
|
2307
|
+
const plan = compactionPlan(snapshot);
|
|
2308
|
+
if (!plan) return;
|
|
2309
|
+
const { removed, ...position } = plan;
|
|
2310
|
+
const index = snapshot.compactions.length;
|
|
2311
|
+
const entry: CompactionExecution = {
|
|
2312
|
+
id: compactionId(snapshot.runId, index),
|
|
2313
|
+
beforeModel: snapshot.models.length,
|
|
2314
|
+
...position,
|
|
2315
|
+
status: "running",
|
|
2316
|
+
};
|
|
2317
|
+
const summary = snapshot.definition.compaction?.summarize;
|
|
2318
|
+
if (!summary) {
|
|
2319
|
+
snapshot.compactions.push({
|
|
2320
|
+
...entry,
|
|
2321
|
+
status: "completed",
|
|
2322
|
+
summary: "Earlier messages were omitted. No summary was generated.",
|
|
2323
|
+
});
|
|
2324
|
+
await save();
|
|
2325
|
+
return;
|
|
2326
|
+
}
|
|
2327
|
+
if (!summarizer) fail("invalid_journal", "The recorded summary provider is missing.");
|
|
2328
|
+
// A separate receipt freezes this cut before any paid work. A crash, even before
|
|
2329
|
+
// dispatch, fails closed instead of silently purchasing the same summary twice.
|
|
2330
|
+
snapshot.compactions.push(entry);
|
|
2331
|
+
await save();
|
|
541
2332
|
active();
|
|
542
|
-
|
|
2333
|
+
const messages = await requestOf(summary.instructions, removed, loadMedia);
|
|
2334
|
+
await callModel(
|
|
2335
|
+
entry.id,
|
|
2336
|
+
{
|
|
2337
|
+
messages,
|
|
2338
|
+
tools: [],
|
|
2339
|
+
settings: {
|
|
2340
|
+
maxTokens: summary.maxTokens,
|
|
2341
|
+
maxAttempts: 1,
|
|
2342
|
+
toolChoice: "none",
|
|
2343
|
+
hostedTools: [],
|
|
2344
|
+
},
|
|
2345
|
+
},
|
|
2346
|
+
summarizer,
|
|
2347
|
+
(model) => {
|
|
2348
|
+
if (model.status === "completed") {
|
|
2349
|
+
if (
|
|
2350
|
+
model.turn.finishReason !== "stop" ||
|
|
2351
|
+
!model.turn.message.content.trim() ||
|
|
2352
|
+
model.tools.length ||
|
|
2353
|
+
model.turn.message.hostedCalls?.length ||
|
|
2354
|
+
model.turn.message.hostedItems
|
|
2355
|
+
)
|
|
2356
|
+
fail(
|
|
2357
|
+
"invalid_compaction",
|
|
2358
|
+
"The summary must be complete text without tool calls. Check the summary provider before starting new work.",
|
|
2359
|
+
entry.id,
|
|
2360
|
+
);
|
|
2361
|
+
snapshot.compactions[index] = {
|
|
2362
|
+
...entry,
|
|
2363
|
+
model,
|
|
2364
|
+
status: "completed",
|
|
2365
|
+
summary: model.turn.message.content,
|
|
2366
|
+
};
|
|
2367
|
+
} else entry.model = model;
|
|
2368
|
+
},
|
|
2369
|
+
undefined,
|
|
2370
|
+
true,
|
|
2371
|
+
);
|
|
2372
|
+
}
|
|
2373
|
+
|
|
2374
|
+
async function nextTurn(
|
|
2375
|
+
previous?: Extract<ModelExecution, { status: "running" }>,
|
|
2376
|
+
): Promise<CompletedModel> {
|
|
2377
|
+
active();
|
|
2378
|
+
// Hosted actions may run before any local tool call appears. Their explicit presence
|
|
2379
|
+
// overrides a profile's inference-only claim when an interrupted call is recovered.
|
|
2380
|
+
if (previous) {
|
|
2381
|
+
refuseGuardedReplay(snapshot, previous.id);
|
|
2382
|
+
requireRecovery(
|
|
2383
|
+
snapshot.definition.recovery?.policy.inferenceOnly === true &&
|
|
2384
|
+
!snapshot.definition.modelSettings.hostedTools?.length,
|
|
2385
|
+
previous.interrupted.length,
|
|
2386
|
+
snapshot.definition.recovery,
|
|
2387
|
+
previous.id,
|
|
2388
|
+
);
|
|
2389
|
+
}
|
|
2390
|
+
const position = previous ? snapshot.models.indexOf(previous) : snapshot.models.length;
|
|
2391
|
+
const selected = definitionsFor(snapshot.definition.enabledTools);
|
|
2392
|
+
if (
|
|
2393
|
+
previous &&
|
|
2394
|
+
(await requestHash(selected)) !== snapshot.definition.recovery?.modelToolsHash
|
|
2395
|
+
)
|
|
2396
|
+
fail(
|
|
2397
|
+
"recovery_definition_changed",
|
|
2398
|
+
"The interrupted model call's tool definitions changed. Restore the same definitions or reconcile the run.",
|
|
2399
|
+
previous.id,
|
|
2400
|
+
);
|
|
2401
|
+
// Ported from Microsoft Agent Framework (MIT), _tools.py: after the iteration
|
|
2402
|
+
// allowance, ask once for a tool-free answer. Checked output needs submit_result,
|
|
2403
|
+
// so that mode retains the hard local turn cap instead of buying an unusable call.
|
|
2404
|
+
const finalTurn = position === limits.turns;
|
|
2405
|
+
if (position > limits.turns || (finalTurn && output))
|
|
543
2406
|
throw new Halt({ status: "limited", limit: "turns" });
|
|
2407
|
+
// A steer never changes the input of an already admitted call, including safe replay.
|
|
2408
|
+
// Check capacity before polling so a spent budget leaves delivery queued in the host.
|
|
2409
|
+
scope.tree.reserveModel();
|
|
2410
|
+
if (!previous) {
|
|
2411
|
+
await acceptInputs(snapshot, scope, options, signal);
|
|
2412
|
+
await compact();
|
|
2413
|
+
}
|
|
2414
|
+
active();
|
|
2415
|
+
// Media is read before the receipt below exists, so a missing loader or file fails the
|
|
2416
|
+
// run with no model operation left running and nothing to reconcile.
|
|
2417
|
+
const request = await requestOf(
|
|
2418
|
+
snapshot.definition.instructions,
|
|
2419
|
+
withMemoryRecall(snapshot, modelConversation(snapshot)),
|
|
2420
|
+
loadMedia,
|
|
2421
|
+
);
|
|
2422
|
+
active();
|
|
2423
|
+
const modelSettings = copyData(snapshot.definition.modelSettings);
|
|
2424
|
+
// Ported from OpenAI Agents JS (MIT), runner/modelSettings.ts, maybeResetToolChoice.
|
|
2425
|
+
// Derive usage from the journal so resume cannot force the first tool a second time.
|
|
2426
|
+
const choice = modelSettings.toolChoice;
|
|
2427
|
+
if (
|
|
2428
|
+
(choice === "required" || typeof choice === "object") &&
|
|
2429
|
+
snapshot.models.some((model) => model.status === "completed" && model.tools.length > 0)
|
|
2430
|
+
)
|
|
2431
|
+
modelSettings.toolChoice = "auto";
|
|
2432
|
+
if (finalTurn) modelSettings.toolChoice = "none";
|
|
2433
|
+
const operationId = modelId(snapshot.runId, position);
|
|
2434
|
+
const modelInput: ModelInput = {
|
|
2435
|
+
messages: request,
|
|
2436
|
+
tools: finalTurn ? [] : copyData(selected),
|
|
2437
|
+
settings: modelSettings,
|
|
2438
|
+
};
|
|
2439
|
+
const done = await callModel(
|
|
2440
|
+
operationId,
|
|
2441
|
+
modelInput,
|
|
2442
|
+
provider,
|
|
2443
|
+
(model) => {
|
|
2444
|
+
snapshot.models[position] = model;
|
|
2445
|
+
},
|
|
2446
|
+
previous,
|
|
2447
|
+
);
|
|
2448
|
+
for (const receipt of inputReceipts(snapshot).filter(
|
|
2449
|
+
(receipt) => receipt.modelId === done.id,
|
|
2450
|
+
))
|
|
2451
|
+
emit({ type: "input", receipt });
|
|
2452
|
+
await acknowledgeInputs(snapshot, options, signal);
|
|
2453
|
+
return done;
|
|
2454
|
+
}
|
|
2455
|
+
|
|
2456
|
+
// Both ordinary turns and explicit summaries use the same admission, guards, usage
|
|
2457
|
+
// checkpoints and collection path. Summaries stay private and never dispatch tools.
|
|
2458
|
+
async function callModel(
|
|
2459
|
+
operationId: string,
|
|
2460
|
+
modelInput: ModelInput,
|
|
2461
|
+
selectedProvider: Provider,
|
|
2462
|
+
record: (model: ModelExecution) => void,
|
|
2463
|
+
previous?: Extract<ModelExecution, { status: "running" }>,
|
|
2464
|
+
summary = false,
|
|
2465
|
+
): Promise<CompletedModel> {
|
|
2466
|
+
const { messages: request, settings: modelSettings } = modelInput;
|
|
2467
|
+
await guards.check("modelInput", operationId, snapshot.attemptId, modelInput);
|
|
2468
|
+
await observe({
|
|
2469
|
+
type: "model_start",
|
|
2470
|
+
operationId,
|
|
2471
|
+
attemptId: snapshot.attemptId,
|
|
2472
|
+
input: modelInput,
|
|
2473
|
+
});
|
|
2474
|
+
active();
|
|
2475
|
+
// The tree check and the receipt stay together, with no await between them, so two
|
|
2476
|
+
// children racing for the tree's last model call cannot both take it.
|
|
544
2477
|
scope.tree.reserveModel();
|
|
545
2478
|
const model: ModelExecution = {
|
|
546
|
-
id:
|
|
2479
|
+
id: operationId,
|
|
547
2480
|
attemptId: snapshot.attemptId,
|
|
548
2481
|
status: "running",
|
|
2482
|
+
billing: "unknown",
|
|
549
2483
|
usage: { ...EMPTY_USAGE },
|
|
2484
|
+
interrupted: previous
|
|
2485
|
+
? [
|
|
2486
|
+
...previous.interrupted,
|
|
2487
|
+
{ attemptId: previous.attemptId, usage: copyData(previous.usage) },
|
|
2488
|
+
]
|
|
2489
|
+
: [],
|
|
550
2490
|
};
|
|
551
|
-
|
|
2491
|
+
record(model);
|
|
552
2492
|
await save();
|
|
2493
|
+
if (previous) restart("model", model.id, previous.attemptId);
|
|
553
2494
|
active();
|
|
2495
|
+
let reportedUsage = false;
|
|
2496
|
+
let bufferedChunks = 0;
|
|
2497
|
+
let bufferedBytes = 0;
|
|
2498
|
+
const guarded = !!guardrails?.modelOutput;
|
|
554
2499
|
async function* observed(): AsyncIterable<ProviderChunk> {
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
2500
|
+
let dispatchProvider = selectedProvider;
|
|
2501
|
+
if (options.bindModelProvider) {
|
|
2502
|
+
try {
|
|
2503
|
+
const bound = options.bindModelProvider(
|
|
2504
|
+
selectedProvider,
|
|
2505
|
+
Object.freeze({
|
|
2506
|
+
run: callbackContext,
|
|
2507
|
+
operationId: model.id,
|
|
2508
|
+
operationAttemptId: model.attemptId,
|
|
2509
|
+
purpose: summary ? "compaction" : "turn",
|
|
2510
|
+
}),
|
|
2511
|
+
);
|
|
2512
|
+
if (bound && typeof bound.createStream === "function") dispatchProvider = bound;
|
|
2513
|
+
} catch {
|
|
2514
|
+
// Instrumentation can fail before dispatch. Never catch/replay the provider call.
|
|
2515
|
+
}
|
|
2516
|
+
}
|
|
2517
|
+
active();
|
|
2518
|
+
const stream = dispatchProvider.createStream(request, modelInput.tools, {
|
|
2519
|
+
...modelSettings,
|
|
2520
|
+
...(settings.onActivity ? { onActivity: settings.onActivity } : {}),
|
|
2521
|
+
...(settings.onRateLimit ? { onRateLimit: settings.onRateLimit } : {}),
|
|
2522
|
+
...(options.modelSettings?.onActivity
|
|
2523
|
+
? { onActivity: options.modelSettings.onActivity }
|
|
2524
|
+
: {}),
|
|
2525
|
+
...(options.modelSettings?.onRateLimit
|
|
2526
|
+
? { onRateLimit: options.modelSettings.onRateLimit }
|
|
2527
|
+
: {}),
|
|
2528
|
+
signal,
|
|
2529
|
+
sessionId: summary
|
|
2530
|
+
? operationId
|
|
2531
|
+
: (snapshot.subagent?.identity.originRunId ?? snapshot.runId),
|
|
2532
|
+
});
|
|
563
2533
|
for await (const chunk of stream) {
|
|
564
2534
|
active();
|
|
565
2535
|
if (chunk.usage) {
|
|
566
2536
|
if (!isUsage(chunk.usage))
|
|
567
2537
|
fail("invalid_usage", "The provider returned invalid token usage.", model.id);
|
|
568
2538
|
model.usage = copyData(chunk.usage);
|
|
2539
|
+
reportedUsage = true;
|
|
2540
|
+
// Preserve measurements before another pull can hang or the worker can disappear.
|
|
2541
|
+
// This saves usage, not partial text, and does not claim final billing is known.
|
|
2542
|
+
await save();
|
|
2543
|
+
active();
|
|
2544
|
+
}
|
|
2545
|
+
if (guarded) {
|
|
2546
|
+
// Bound collection before yielding. Only the checked assembled turn is published.
|
|
2547
|
+
// All fields count, including reasoning, signatures, tool args and hosted payloads.
|
|
2548
|
+
bufferedBytes += jsonBytes(chunk);
|
|
2549
|
+
bufferedChunks++;
|
|
2550
|
+
if (
|
|
2551
|
+
bufferedBytes > (guardPolicy?.maxOutputBytes ?? 0) ||
|
|
2552
|
+
bufferedChunks > GUARDED_CHUNK_LIMIT
|
|
2553
|
+
)
|
|
2554
|
+
await guards.overflow("modelOutput", model.id);
|
|
2555
|
+
} else if (!summary) {
|
|
2556
|
+
emit({
|
|
2557
|
+
type: "model_chunk",
|
|
2558
|
+
runId: snapshot.runId,
|
|
2559
|
+
attemptId: snapshot.attemptId,
|
|
2560
|
+
operationId: model.id,
|
|
2561
|
+
chunk,
|
|
2562
|
+
});
|
|
569
2563
|
}
|
|
570
|
-
emit({
|
|
571
|
-
type: "model_chunk",
|
|
572
|
-
runId: snapshot.runId,
|
|
573
|
-
attemptId: snapshot.attemptId,
|
|
574
|
-
operationId: model.id,
|
|
575
|
-
chunk,
|
|
576
|
-
});
|
|
577
2564
|
active();
|
|
578
2565
|
yield chunk;
|
|
579
2566
|
}
|
|
580
2567
|
}
|
|
581
|
-
|
|
2568
|
+
let collected;
|
|
2569
|
+
try {
|
|
2570
|
+
collected = await untilAbort(collectTurn(observed()), signal);
|
|
2571
|
+
} catch (error) {
|
|
2572
|
+
await observe({ type: "model_error", operationId: model.id, attemptId: model.attemptId });
|
|
2573
|
+
active();
|
|
2574
|
+
// Only core's classified provider failures are local model failures. Host/checkpoint
|
|
2575
|
+
// errors and unclassified programming errors must not become benign tool strings.
|
|
2576
|
+
if (!(error instanceof ProviderError)) {
|
|
2577
|
+
if (guarded && !(error instanceof Halt))
|
|
2578
|
+
fail(
|
|
2579
|
+
"guarded_model_failed",
|
|
2580
|
+
"The guarded model call failed before its output could be checked. Inspect the provider on the server before starting new work.",
|
|
2581
|
+
model.id,
|
|
2582
|
+
);
|
|
2583
|
+
throw error;
|
|
2584
|
+
}
|
|
2585
|
+
if (error.kind === "aborted") {
|
|
2586
|
+
scope.tree.stop();
|
|
2587
|
+
throw new Halt({ status: "cancelled" });
|
|
2588
|
+
}
|
|
2589
|
+
fail(
|
|
2590
|
+
"model_failed",
|
|
2591
|
+
guarded
|
|
2592
|
+
? `The model call failed (${error.kind}). Check the provider before starting new work.`
|
|
2593
|
+
: `The model call failed (${error.kind}): ${error.message}`,
|
|
2594
|
+
model.id,
|
|
2595
|
+
);
|
|
2596
|
+
}
|
|
2597
|
+
let turn;
|
|
2598
|
+
try {
|
|
2599
|
+
turn = readTurn(collected);
|
|
2600
|
+
} catch (error) {
|
|
2601
|
+
fail(
|
|
2602
|
+
"invalid_model_output",
|
|
2603
|
+
guarded
|
|
2604
|
+
? "The provider returned an invalid guarded turn. Check the provider before starting new work."
|
|
2605
|
+
: messageOf(error),
|
|
2606
|
+
model.id,
|
|
2607
|
+
);
|
|
2608
|
+
}
|
|
2609
|
+
await observe({ type: "model_end", operationId: model.id, attemptId: model.attemptId, turn });
|
|
2610
|
+
active();
|
|
2611
|
+
await guards.check("modelOutput", model.id, model.attemptId, turn);
|
|
2612
|
+
active();
|
|
582
2613
|
const done: CompletedModel = {
|
|
583
2614
|
...model,
|
|
584
2615
|
status: "completed",
|
|
2616
|
+
billing: reportedUsage ? "reported" : "unknown",
|
|
585
2617
|
usage: turn.usage,
|
|
586
2618
|
turn,
|
|
587
2619
|
tools: (turn.message.toolCalls ?? []).map((_call, index) => ({
|
|
588
2620
|
id: toolId(model.id, index),
|
|
589
2621
|
status: "pending",
|
|
2622
|
+
interrupted: [],
|
|
2623
|
+
retries: [],
|
|
590
2624
|
})),
|
|
591
2625
|
};
|
|
592
|
-
|
|
2626
|
+
record(done);
|
|
593
2627
|
await save();
|
|
2628
|
+
if (guarded && !summary) {
|
|
2629
|
+
active();
|
|
2630
|
+
emit({
|
|
2631
|
+
type: "model_chunk",
|
|
2632
|
+
runId: snapshot.runId,
|
|
2633
|
+
attemptId: model.attemptId,
|
|
2634
|
+
operationId: model.id,
|
|
2635
|
+
chunk: guardedChunk(turn),
|
|
2636
|
+
});
|
|
2637
|
+
}
|
|
594
2638
|
return done;
|
|
595
2639
|
}
|
|
596
2640
|
|
|
597
2641
|
try {
|
|
2642
|
+
// Repair a lost acknowledgement from the saved journal without rereading its payload.
|
|
2643
|
+
// Terminal snapshots synchronize too; this never starts a follow-up model call.
|
|
2644
|
+
if (scope.depth === 0) await acknowledgeInputs(snapshot, options, signal);
|
|
2645
|
+
if (scope.depth === 0 && answers) {
|
|
2646
|
+
await answerRequests(snapshot, options, scope, answers, signal);
|
|
2647
|
+
if (
|
|
2648
|
+
[...requestRecords(snapshot)].some(
|
|
2649
|
+
({ record }) => !record.closed && record.decision?.type === "stop",
|
|
2650
|
+
)
|
|
2651
|
+
)
|
|
2652
|
+
scope.tree.stop();
|
|
2653
|
+
await save();
|
|
2654
|
+
}
|
|
598
2655
|
if (snapshot.state.status === "running" || snapshot.state.status === "suspended") {
|
|
599
2656
|
release = await scope.tree.gate.acquire(signal);
|
|
600
2657
|
active();
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
fail(
|
|
628
|
-
"invalid_approval",
|
|
629
|
-
"The pending approval does not belong to an approval-required tool.",
|
|
630
|
-
);
|
|
631
|
-
if (!host?.resolveApproval || !host.beforeTool)
|
|
632
|
-
fail(
|
|
633
|
-
"approval_host_missing",
|
|
634
|
-
"Provide host.resolveApproval and host.beforeTool to authenticate a decision and recheck access.",
|
|
635
|
-
);
|
|
636
|
-
await save();
|
|
637
|
-
active();
|
|
638
|
-
const answer = await untilAbort(
|
|
639
|
-
Promise.resolve(
|
|
640
|
-
host.resolveApproval(immutableCopy(approval), immutableCopy(evidence.decision)),
|
|
641
|
-
),
|
|
2658
|
+
requireGuardVerdicts(snapshot);
|
|
2659
|
+
started = true;
|
|
2660
|
+
await observe({ type: "run_start" });
|
|
2661
|
+
active();
|
|
2662
|
+
const last = snapshot.models.at(-1);
|
|
2663
|
+
snapshot.state = { status: "running" };
|
|
2664
|
+
checkMemoryBinding(snapshot, options.memory);
|
|
2665
|
+
if (needsMemory && !options.memory)
|
|
2666
|
+
fail("memory_missing", "Supply authenticated memory access before starting this agent.");
|
|
2667
|
+
if (
|
|
2668
|
+
!options.memory?.scope &&
|
|
2669
|
+
[...capabilities.values()].some(
|
|
2670
|
+
(tool) =>
|
|
2671
|
+
isMemoryTool(tool) &&
|
|
2672
|
+
!tool.isReadOnly &&
|
|
2673
|
+
snapshot.definition.enabledTools.includes(tool.name),
|
|
2674
|
+
)
|
|
2675
|
+
)
|
|
2676
|
+
fail(
|
|
2677
|
+
"memory_missing",
|
|
2678
|
+
"Memory writes need an authenticated person's writable scope. Disable save and forget for shared-only access.",
|
|
2679
|
+
);
|
|
2680
|
+
if (memory && options.memory && !snapshot.recall) {
|
|
2681
|
+
snapshot.recall = await recallMemory(
|
|
2682
|
+
snapshot,
|
|
2683
|
+
options.memory,
|
|
642
2684
|
signal,
|
|
2685
|
+
scope.handoffInput,
|
|
643
2686
|
);
|
|
2687
|
+
// No model sees recall until the existing progress/checkpoint barrier confirms it.
|
|
2688
|
+
await save();
|
|
644
2689
|
active();
|
|
645
|
-
if (answer !== "pending") {
|
|
646
|
-
if (answer !== "approved" && answer !== "denied")
|
|
647
|
-
fail(
|
|
648
|
-
"invalid_approval_decision",
|
|
649
|
-
"The host must return approved, denied or pending.",
|
|
650
|
-
);
|
|
651
|
-
snapshot.state = { status: "running" };
|
|
652
|
-
if (answer === "approved") approved = approval;
|
|
653
|
-
else {
|
|
654
|
-
const model = snapshot.models.at(-1);
|
|
655
|
-
if (model?.status !== "completed")
|
|
656
|
-
fail("invalid_journal", "The pending tool turn is missing.");
|
|
657
|
-
const index = model.tools.findIndex(
|
|
658
|
-
(tool) => tool.id === approval.request.operationId,
|
|
659
|
-
);
|
|
660
|
-
if (usedTools() >= limits.toolCalls)
|
|
661
|
-
throw new Halt({ status: "limited", limit: "toolCalls" });
|
|
662
|
-
await finishTool(model, index, requestFor(model, index), {
|
|
663
|
-
ok: false,
|
|
664
|
-
kind: "denied",
|
|
665
|
-
content: "The host denied this tool call. Continue without this action.",
|
|
666
|
-
});
|
|
667
|
-
}
|
|
668
|
-
}
|
|
669
2690
|
}
|
|
670
|
-
if (snapshot.
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
2691
|
+
if (snapshot.recall?.status === "failed" && memory?.onError === "fail")
|
|
2692
|
+
fail(
|
|
2693
|
+
"memory_unavailable",
|
|
2694
|
+
"Memory could not be read. Check the store before starting a new run.",
|
|
2695
|
+
);
|
|
2696
|
+
if (last?.status === "running") await handleTurn(await nextTurn(last));
|
|
2697
|
+
else if (last?.status === "completed") {
|
|
2698
|
+
await recoverTools(last);
|
|
2699
|
+
await handleTurn(last);
|
|
674
2700
|
}
|
|
2701
|
+
while (snapshot.state.status === "running") await handleTurn(await nextTurn());
|
|
675
2702
|
}
|
|
676
|
-
if (snapshot.state.status === "completed")
|
|
677
|
-
completed = { output: validateResult(snapshot.state.candidate) };
|
|
2703
|
+
if (snapshot.state.status === "completed") completed = { output: completedOutput(snapshot) };
|
|
678
2704
|
await save();
|
|
679
2705
|
} catch (error) {
|
|
680
2706
|
let failure = error;
|
|
@@ -703,6 +2729,7 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
703
2729
|
}
|
|
704
2730
|
} finally {
|
|
705
2731
|
release();
|
|
2732
|
+
if (started) await observe({ type: "run_end", state: snapshot.state });
|
|
706
2733
|
clearTimeout(timer);
|
|
707
2734
|
}
|
|
708
2735
|
emit({
|
|
@@ -711,42 +2738,300 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
711
2738
|
attemptId: snapshot.attemptId,
|
|
712
2739
|
state: snapshot.state,
|
|
713
2740
|
});
|
|
714
|
-
|
|
2741
|
+
// Includes the final state event, before a child host receipt or session append can land.
|
|
2742
|
+
await host?.progress?.flush();
|
|
2743
|
+
const record = recordOf(snapshot);
|
|
715
2744
|
const state = snapshot.state;
|
|
716
2745
|
if (state.status === "completed") {
|
|
717
2746
|
if (!completed) throw new Error("The agent completed without validating its result.");
|
|
718
2747
|
return { ...record, status: "completed", output: completed.output };
|
|
719
2748
|
}
|
|
720
|
-
return
|
|
2749
|
+
return state.status === "suspended"
|
|
2750
|
+
? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
|
|
2751
|
+
: { ...record, ...state };
|
|
721
2752
|
}
|
|
722
2753
|
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
2754
|
+
function checkInline(start: Pick<RunStart, "history" | "input">): void {
|
|
2755
|
+
const bytes = inlineBytes(start.history, start.input);
|
|
2756
|
+
if (bytes > limits.inlineBytes)
|
|
2757
|
+
throw new TypeError(
|
|
2758
|
+
`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.`,
|
|
2759
|
+
);
|
|
2760
|
+
}
|
|
2761
|
+
|
|
2762
|
+
function freeze(start: RunStart): RunStart {
|
|
2763
|
+
// Once, here: adapters repair every request again, and repair is idempotent, so the
|
|
2764
|
+
// bytes a provider caches never change between turns or across a resume.
|
|
2765
|
+
const history = repairConversation(
|
|
2766
|
+
start.history,
|
|
2767
|
+
(name) => (registry.get(name) ?? codeTools.get(name))?.isReadOnly === true,
|
|
2768
|
+
);
|
|
2769
|
+
checkInline({ history, input: start.input });
|
|
2770
|
+
return { ...start, history };
|
|
2771
|
+
}
|
|
2772
|
+
|
|
2773
|
+
async function create(
|
|
2774
|
+
start: RunStart,
|
|
2775
|
+
runId: string,
|
|
2776
|
+
tree?: RunSnapshot["tree"],
|
|
2777
|
+
options: RunOptions = {},
|
|
2778
|
+
subagent?: SubagentCreation,
|
|
2779
|
+
): Promise<RunSnapshot> {
|
|
2780
|
+
const frozen = freeze(start);
|
|
2781
|
+
const spec = subagent?.record.spec;
|
|
2782
|
+
const resolved = await resolveDefinition(
|
|
2783
|
+
frozen,
|
|
2784
|
+
spec
|
|
2785
|
+
? {
|
|
2786
|
+
...options,
|
|
2787
|
+
enabledTools: spec.tools,
|
|
2788
|
+
modelSettings: subagent.record.policy.models[spec.model ?? ""]?.settings,
|
|
2789
|
+
}
|
|
2790
|
+
: options,
|
|
2791
|
+
runId,
|
|
2792
|
+
subagent?.source,
|
|
2793
|
+
);
|
|
2794
|
+
const record = subagent
|
|
2795
|
+
? { ...copyData(subagent.record), base: copyData(resolved) }
|
|
2796
|
+
: undefined;
|
|
2797
|
+
if (subagent?.record.previousRunId && !equalData(resolved, subagent.source))
|
|
2798
|
+
throw new TypeError(
|
|
2799
|
+
"The helper's admitted definition changed. Restore its original configuration before continuing.",
|
|
2800
|
+
);
|
|
2801
|
+
if (spec)
|
|
2802
|
+
resolved.instructions = subagentInstructions(resolved.instructions, spec.instructions);
|
|
2803
|
+
const childLimits = spec ? subagentLimits(limits, spec.limits) : limits;
|
|
2804
|
+
if (inlineBytes(frozen.history, frozen.input) > childLimits.inlineBytes)
|
|
2805
|
+
throw new TypeError("The helper input exceeds its admitted inline byte limit.");
|
|
2806
|
+
const { history, input, session } = frozen;
|
|
2807
|
+
const startedAt = Date.now();
|
|
2808
|
+
return {
|
|
2809
|
+
kind: "agent",
|
|
2810
|
+
format: 3,
|
|
2811
|
+
agentId: id,
|
|
2812
|
+
version,
|
|
2813
|
+
runId,
|
|
2814
|
+
attemptId: crypto.randomUUID(),
|
|
2815
|
+
startedAt,
|
|
2816
|
+
definition: resolved,
|
|
2817
|
+
...(record ? { subagent: record } : {}),
|
|
2818
|
+
history: copyData(history),
|
|
2819
|
+
input: copyData(input),
|
|
2820
|
+
inputs: [],
|
|
2821
|
+
guards: [],
|
|
2822
|
+
compactions: [],
|
|
2823
|
+
...(session ? { session: copyData(session) } : {}),
|
|
2824
|
+
limits: copyData(childLimits),
|
|
2825
|
+
models: [],
|
|
2826
|
+
delegations: [],
|
|
2827
|
+
state: { status: "running" },
|
|
2828
|
+
tree: tree
|
|
2829
|
+
? copyData(tree)
|
|
2830
|
+
: {
|
|
2831
|
+
runId,
|
|
2832
|
+
startedAt,
|
|
2833
|
+
limits: copyData(treeLimits),
|
|
2834
|
+
...(options.memory ? { memory: memoryScopes(options.memory) } : {}),
|
|
2835
|
+
},
|
|
2836
|
+
};
|
|
2837
|
+
}
|
|
2838
|
+
|
|
2839
|
+
const runtime: AgentRuntime<T | string | H> = {
|
|
2840
|
+
node: {
|
|
2841
|
+
restore: (raw, tree, subagent) => runtime.restore(raw, tree, subagent),
|
|
2842
|
+
hydrate: (node) => runtime.hydrate(agentSnapshot(node)),
|
|
2843
|
+
answerRequests: (node, options, scope, answers, signal) =>
|
|
2844
|
+
answerRequests(agentSnapshot(node), options, scope, answers, signal),
|
|
2845
|
+
execute: (node, options, scope, answers) =>
|
|
2846
|
+
execute(agentSnapshot(node), options, scope, answers),
|
|
2847
|
+
},
|
|
2848
|
+
handoffs: [...handoffs.values()],
|
|
2849
|
+
tools: Object.freeze([...capabilities.values()]),
|
|
2850
|
+
enabledTools: Array.isArray(enabledTools) ? Object.freeze([...enabledTools]) : undefined,
|
|
2851
|
+
limits: immutableCopy(limits),
|
|
2852
|
+
async checkTools(snapshot, options) {
|
|
2853
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
2854
|
+
const current = checkNames(
|
|
2855
|
+
typeof enabledTools === "function"
|
|
2856
|
+
? await untilAbort(
|
|
2857
|
+
Promise.resolve(
|
|
2858
|
+
enabledTools(
|
|
2859
|
+
Object.freeze({
|
|
2860
|
+
agentId: id,
|
|
2861
|
+
version,
|
|
2862
|
+
runId: snapshot.runId,
|
|
2863
|
+
...immutableCopy({ history: snapshot.history, input: snapshot.input }),
|
|
2864
|
+
context: Object.freeze({ ...options.context }),
|
|
2865
|
+
signal,
|
|
2866
|
+
}),
|
|
2867
|
+
),
|
|
2868
|
+
),
|
|
2869
|
+
signal,
|
|
2870
|
+
)
|
|
2871
|
+
: (enabledTools ?? names),
|
|
2872
|
+
);
|
|
2873
|
+
if (
|
|
2874
|
+
snapshot.definition.enabledTools.some(
|
|
2875
|
+
(name) => name !== RESULT_TOOL_NAME && !current.includes(name),
|
|
2876
|
+
)
|
|
2877
|
+
)
|
|
2878
|
+
fail(
|
|
2879
|
+
"subagent_grant_changed",
|
|
2880
|
+
"The host revoked a helper capability. Obtain fresh authorization before starting different work.",
|
|
2881
|
+
);
|
|
2882
|
+
},
|
|
2883
|
+
configuration() {
|
|
2884
|
+
const { onActivity: _activity, onRateLimit: _rateLimit, ...modelSettings } = settings;
|
|
2885
|
+
return immutableCopy({
|
|
2886
|
+
id,
|
|
730
2887
|
version,
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
limits
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
2888
|
+
provider: { id: provider.id, model: provider.model },
|
|
2889
|
+
instructions: typeof instructions === "string" ? instructions : null,
|
|
2890
|
+
enabledTools: Array.isArray(enabledTools) ? enabledTools : null,
|
|
2891
|
+
modelSettings,
|
|
2892
|
+
limits,
|
|
2893
|
+
output: output?.schema ?? null,
|
|
2894
|
+
stopAtTools,
|
|
2895
|
+
recovery,
|
|
2896
|
+
guardrails: guardPolicy,
|
|
2897
|
+
compaction,
|
|
2898
|
+
toolRetries,
|
|
2899
|
+
...(memory ? { memory } : {}),
|
|
2900
|
+
tools: tools.map((tool) => ({
|
|
2901
|
+
definition: tool.definition(),
|
|
2902
|
+
needsApproval: tool.needsApproval === true,
|
|
2903
|
+
...(isDelegation(tool)
|
|
2904
|
+
? {
|
|
2905
|
+
kind: "delegation",
|
|
2906
|
+
specialists: tool.specialists.map(({ id, version }) => ({ id, version })),
|
|
2907
|
+
}
|
|
2908
|
+
: isHandoff(tool)
|
|
2909
|
+
? { kind: "handoff", target: handoffRef(tool.target()) }
|
|
2910
|
+
: isCodeTool(tool)
|
|
2911
|
+
? {
|
|
2912
|
+
kind: "code",
|
|
2913
|
+
limits: tool.limits,
|
|
2914
|
+
bindings: tool.tools.map((bound) => ({
|
|
2915
|
+
definition: bound.definition(),
|
|
2916
|
+
outputSchema: bound.outputSchema,
|
|
2917
|
+
isReadOnly: bound.isReadOnly,
|
|
2918
|
+
needsApproval: bound.needsApproval,
|
|
2919
|
+
isConcurrencySafe: bound.isConcurrencySafe,
|
|
2920
|
+
timeoutMs: bound.timeoutMs,
|
|
2921
|
+
})),
|
|
2922
|
+
}
|
|
2923
|
+
: isClientTool(tool)
|
|
2924
|
+
? { kind: "client", resultSchema: tool.resultSchema }
|
|
2925
|
+
: {
|
|
2926
|
+
kind: "tool",
|
|
2927
|
+
isReadOnly: tool.isReadOnly === true,
|
|
2928
|
+
isConcurrencySafe: tool.isConcurrencySafe === true,
|
|
2929
|
+
isTerminal: tool.isTerminal === true,
|
|
2930
|
+
}),
|
|
2931
|
+
})),
|
|
2932
|
+
});
|
|
741
2933
|
},
|
|
742
|
-
|
|
2934
|
+
execute,
|
|
2935
|
+
answerRequests,
|
|
2936
|
+
freeze,
|
|
2937
|
+
create,
|
|
2938
|
+
async open(input, options, runId) {
|
|
2939
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
2940
|
+
if (needsMemory && !options.memory)
|
|
2941
|
+
throw new TypeError("This agent needs authenticated memory access in RunOptions.memory.");
|
|
2942
|
+
// Everything before the snapshot exists runs outside the journal: a paid summarizer in
|
|
2943
|
+
// prepareHistory can run again if the process dies before the first checkpoint.
|
|
2944
|
+
const signal = options.signal ?? new AbortController().signal;
|
|
2945
|
+
const session = options.session;
|
|
2946
|
+
let start: RunStart;
|
|
2947
|
+
if (session) {
|
|
2948
|
+
if (isRecord(input) && "messages" in input)
|
|
2949
|
+
throw new TypeError(
|
|
2950
|
+
"With a session, pass only the new turn. The session holds the history.",
|
|
2951
|
+
);
|
|
2952
|
+
// Checked before the load, so a turn that would be refused costs no read.
|
|
2953
|
+
const turn = readInput(input, "caller").input;
|
|
2954
|
+
checkInline({ history: [], input: turn });
|
|
2955
|
+
const loaded: unknown = await untilAbort(
|
|
2956
|
+
Promise.resolve(
|
|
2957
|
+
session.load({
|
|
2958
|
+
...(options.historyLimit !== undefined ? { limit: options.historyLimit } : {}),
|
|
2959
|
+
signal,
|
|
2960
|
+
}),
|
|
2961
|
+
),
|
|
2962
|
+
signal,
|
|
2963
|
+
);
|
|
2964
|
+
if (!isRecord(loaded) || !isRevision(loaded.revision))
|
|
2965
|
+
throw new TypeError("session.load must return { messages, revision }.");
|
|
2966
|
+
start = {
|
|
2967
|
+
history: readStored(loaded.messages, "session.load"),
|
|
2968
|
+
input: turn,
|
|
2969
|
+
session: { id: session.id, revision: loaded.revision },
|
|
2970
|
+
};
|
|
2971
|
+
} else {
|
|
2972
|
+
if (options.historyLimit !== undefined)
|
|
2973
|
+
throw new TypeError(
|
|
2974
|
+
"historyLimit applies to a session. Trim the messages you pass in yourself.",
|
|
2975
|
+
);
|
|
2976
|
+
start = readInput(input, "caller");
|
|
2977
|
+
}
|
|
2978
|
+
if (options.prepareHistory) {
|
|
2979
|
+
const prepared: unknown = await untilAbort(
|
|
2980
|
+
Promise.resolve(options.prepareHistory(copyData(start.history))),
|
|
2981
|
+
signal,
|
|
2982
|
+
);
|
|
2983
|
+
start = { ...start, history: readStored(prepared, "prepareHistory") };
|
|
2984
|
+
}
|
|
2985
|
+
return create(start, runId, undefined, options);
|
|
2986
|
+
},
|
|
2987
|
+
restore(raw, tree, subagent) {
|
|
2988
|
+
if (isRecord(raw) && (!equalData(raw.subagent, subagent) || (subagent && !tree)))
|
|
2989
|
+
throw new TypeError("Restore a model-created helper through its owning creation tool.");
|
|
743
2990
|
const snapshot = readSnapshot(
|
|
744
2991
|
raw,
|
|
745
2992
|
id,
|
|
746
2993
|
version,
|
|
747
|
-
limits,
|
|
2994
|
+
subagent ? subagentLimits(limits, subagent.spec.limits) : limits,
|
|
748
2995
|
output ? RESULT_TOOL_NAME : undefined,
|
|
2996
|
+
codeTools,
|
|
749
2997
|
);
|
|
2998
|
+
checkNames(snapshot.definition.enabledTools);
|
|
2999
|
+
if (!equalData(snapshot.definition.memory, memory))
|
|
3000
|
+
throw new TypeError("Restore the same memory recall policy before resuming.");
|
|
3001
|
+
if (
|
|
3002
|
+
!equalData(snapshot.definition.compaction, compaction) ||
|
|
3003
|
+
!equalData(snapshot.definition.toolRetries?.policy ?? null, toolRetries)
|
|
3004
|
+
)
|
|
3005
|
+
throw new TypeError(
|
|
3006
|
+
"The recorded compaction or tool retry policy changed. Restore the same definition before resuming.",
|
|
3007
|
+
);
|
|
3008
|
+
if (!equalData(snapshot.definition.guardrails, guardPolicy))
|
|
3009
|
+
throw new TypeError(
|
|
3010
|
+
"The recorded guard policy changed. Restore the same guard identity, stages and limits.",
|
|
3011
|
+
);
|
|
3012
|
+
if (
|
|
3013
|
+
!equalData(snapshot.definition.recovery?.policy ?? null, recovery) ||
|
|
3014
|
+
(snapshot.definition.recovery &&
|
|
3015
|
+
!equalData(snapshot.definition.recovery.provider, {
|
|
3016
|
+
id: provider.id,
|
|
3017
|
+
model: provider.model,
|
|
3018
|
+
}))
|
|
3019
|
+
)
|
|
3020
|
+
throw new TypeError(
|
|
3021
|
+
"The recorded recovery policy or provider identity changed. Restore the same profile or reconcile the run.",
|
|
3022
|
+
);
|
|
3023
|
+
if (
|
|
3024
|
+
!equalData(snapshot.definition.stopAtTools, stopAtTools) ||
|
|
3025
|
+
(output && !snapshot.definition.enabledTools.includes(RESULT_TOOL_NAME))
|
|
3026
|
+
)
|
|
3027
|
+
throw new TypeError("The recorded tool behavior does not match this agent version.");
|
|
3028
|
+
const choice = snapshot.definition.modelSettings.toolChoice;
|
|
3029
|
+
if (
|
|
3030
|
+
(output && choice === "none") ||
|
|
3031
|
+
(choice === "required" && snapshot.definition.enabledTools.length === 0) ||
|
|
3032
|
+
(typeof choice === "object" && !snapshot.definition.enabledTools.includes(choice.name))
|
|
3033
|
+
)
|
|
3034
|
+
throw new TypeError("The recorded tool choice does not name an enabled tool.");
|
|
750
3035
|
if (
|
|
751
3036
|
tree
|
|
752
3037
|
? !equalData(snapshot.tree, tree)
|
|
@@ -757,7 +3042,11 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
757
3042
|
if (model.status !== "completed") continue;
|
|
758
3043
|
for (const [index, tool] of model.tools.entries()) {
|
|
759
3044
|
const call = model.turn.message.toolCalls?.[index];
|
|
760
|
-
const descriptor =
|
|
3045
|
+
const descriptor =
|
|
3046
|
+
call &&
|
|
3047
|
+
snapshot.definition.enabledTools.includes(call.name) &&
|
|
3048
|
+
snapshot.definition.modelSettings.toolChoice !== "none" &&
|
|
3049
|
+
descriptorFor(call.name, snapshot, tool.id);
|
|
761
3050
|
const journal = snapshot.delegations.find((entry) => entry.operationId === tool.id);
|
|
762
3051
|
if (descriptor && tool.status !== "pending") {
|
|
763
3052
|
if (!journal || tool.status === "running")
|
|
@@ -767,40 +3056,114 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
767
3056
|
} else if (journal)
|
|
768
3057
|
throw new TypeError("The saved delegation is not in this agent definition.");
|
|
769
3058
|
if (!journal || !descriptor) continue;
|
|
3059
|
+
if (journal.kind !== (call && handoffs.has(call.name) ? "handoff" : "delegation"))
|
|
3060
|
+
throw new TypeError("The saved delegation kind does not match its registered tool.");
|
|
3061
|
+
if (journal.kind === "handoff") checkHandoffTargets(agent);
|
|
3062
|
+
checkSubagentChildren(descriptor, snapshot, journal);
|
|
770
3063
|
for (const entry of journal.children) {
|
|
771
3064
|
const agent = descriptor.specialists.find(
|
|
772
3065
|
(agent) =>
|
|
773
|
-
agent.
|
|
3066
|
+
agent.kind === entry.snapshot.kind &&
|
|
3067
|
+
agent.id === nodeId(entry.snapshot) &&
|
|
3068
|
+
agent.version === entry.snapshot.version,
|
|
774
3069
|
);
|
|
775
3070
|
if (!agent)
|
|
776
3071
|
throw new TypeError("The saved child is not a registered specialist version.");
|
|
777
|
-
entry.snapshot = agent
|
|
3072
|
+
entry.snapshot = runtimeOf(agent).restore(
|
|
3073
|
+
entry.snapshot,
|
|
3074
|
+
snapshot.tree,
|
|
3075
|
+
entry.snapshot.kind === "agent" ? entry.snapshot.subagent : undefined,
|
|
3076
|
+
);
|
|
778
3077
|
}
|
|
779
3078
|
}
|
|
780
3079
|
}
|
|
781
|
-
if (snapshot.state.status === "completed")
|
|
3080
|
+
if (snapshot.state.status === "completed") completedOutput(snapshot);
|
|
782
3081
|
return snapshot;
|
|
783
3082
|
},
|
|
784
3083
|
hydrate(snapshot) {
|
|
785
|
-
const record = recordOf(snapshot
|
|
3084
|
+
const record = recordOf(snapshot);
|
|
786
3085
|
const state = record.snapshot.state;
|
|
787
3086
|
if (state.status === "running") throw new Error("A child has not settled yet.");
|
|
788
3087
|
return state.status === "completed"
|
|
789
|
-
? { ...record, status: "completed", output:
|
|
790
|
-
:
|
|
3088
|
+
? { ...record, status: "completed", output: completedOutput(record.snapshot) }
|
|
3089
|
+
: state.status === "suspended"
|
|
3090
|
+
? { ...record, ...state, requests: openRequests(snapshot), wakeAt: wakeAt(snapshot) }
|
|
3091
|
+
: { ...record, ...state };
|
|
791
3092
|
},
|
|
792
3093
|
};
|
|
793
3094
|
|
|
794
|
-
|
|
3095
|
+
/** Once per root, after its final checkpoint. Never changes the run's own status. */
|
|
3096
|
+
async function appendTurn(
|
|
3097
|
+
outcome: RunOutcome<T | string | H>,
|
|
3098
|
+
options: RunOptions,
|
|
3099
|
+
tree: ExecutionTree,
|
|
3100
|
+
): Promise<SessionStatus | undefined> {
|
|
3101
|
+
const ref = outcome.snapshot.session;
|
|
3102
|
+
if (!ref) return undefined;
|
|
3103
|
+
const session = options.session;
|
|
3104
|
+
// A waiting run has no settled turn yet. After a failed checkpoint the host's journal is
|
|
3105
|
+
// behind this outcome: resuming what it saved settles again and appends then.
|
|
3106
|
+
if (!session || outcome.status === "suspended" || tree.checkpointFailed)
|
|
3107
|
+
return { id: ref.id, status: "pending" };
|
|
3108
|
+
// A Stop ends the run, not the record of it: the turn the person sent is still saved.
|
|
3109
|
+
const signal =
|
|
3110
|
+
options.signal && !options.signal.aborted ? options.signal : new AbortController().signal;
|
|
3111
|
+
try {
|
|
3112
|
+
const saved: unknown = await untilAbort(
|
|
3113
|
+
Promise.resolve(
|
|
3114
|
+
session.append(
|
|
3115
|
+
immutableCopy({
|
|
3116
|
+
runId: outcome.runId,
|
|
3117
|
+
after: ref.revision,
|
|
3118
|
+
messages: outcome.newMessages,
|
|
3119
|
+
}),
|
|
3120
|
+
{ signal },
|
|
3121
|
+
),
|
|
3122
|
+
),
|
|
3123
|
+
signal,
|
|
3124
|
+
);
|
|
3125
|
+
if (!isRecord(saved) || !isId(saved.revision))
|
|
3126
|
+
throw new TypeError("session.append returned no revision.");
|
|
3127
|
+
return { id: ref.id, status: "saved", revision: saved.revision };
|
|
3128
|
+
} catch (error) {
|
|
3129
|
+
// By name, not instanceof: a store built against another copy of this package throws
|
|
3130
|
+
// its own SessionConflictError class.
|
|
3131
|
+
const conflict = error instanceof Error && error.name === "SessionConflictError";
|
|
3132
|
+
return {
|
|
3133
|
+
id: ref.id,
|
|
3134
|
+
status: "unsaved",
|
|
3135
|
+
error: conflict
|
|
3136
|
+
? {
|
|
3137
|
+
code: "session_conflict",
|
|
3138
|
+
message:
|
|
3139
|
+
"The conversation changed after this run loaded it. Load it again before you continue it.",
|
|
3140
|
+
}
|
|
3141
|
+
: {
|
|
3142
|
+
code: "session_failed",
|
|
3143
|
+
message: `The session did not save this turn: ${messageOf(error)}`,
|
|
3144
|
+
},
|
|
3145
|
+
};
|
|
3146
|
+
}
|
|
3147
|
+
}
|
|
3148
|
+
|
|
3149
|
+
async function root(
|
|
3150
|
+
snapshot: RunSnapshot,
|
|
3151
|
+
options: RunOptions,
|
|
3152
|
+
answers?: Readonly<Record<string, unknown>>,
|
|
3153
|
+
) {
|
|
795
3154
|
const tree = new ExecutionTree(snapshot, options);
|
|
3155
|
+
let outcome: RunOutcome<T | string | H>;
|
|
796
3156
|
try {
|
|
797
|
-
|
|
3157
|
+
outcome = await execute(snapshot, options, { tree, depth: 0, path: [] }, answers);
|
|
798
3158
|
} finally {
|
|
799
3159
|
tree.close();
|
|
800
3160
|
}
|
|
3161
|
+
const session = await appendTurn(outcome, options, tree);
|
|
3162
|
+
return session ? { ...outcome, session } : outcome;
|
|
801
3163
|
}
|
|
802
3164
|
|
|
803
|
-
const agent: Agent<T | string> = {
|
|
3165
|
+
const agent: Agent<T | string | H> = {
|
|
3166
|
+
kind: "agent",
|
|
804
3167
|
id,
|
|
805
3168
|
version,
|
|
806
3169
|
[AGENT_RUNTIME]: runtime,
|
|
@@ -808,26 +3171,28 @@ export function defineAgent<T>(definition: AgentDefinition<T>): Agent<T | string
|
|
|
808
3171
|
return specialistTool(agent, options);
|
|
809
3172
|
},
|
|
810
3173
|
async run(input, options = {}) {
|
|
811
|
-
if (!isId(input)) throw new TypeError("Give the agent a non-empty text input.");
|
|
812
3174
|
checkOptions(options);
|
|
813
|
-
|
|
3175
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
3176
|
+
return root(
|
|
3177
|
+
await runtime.open(input, options, options.runId ?? crypto.randomUUID()),
|
|
3178
|
+
options,
|
|
3179
|
+
);
|
|
814
3180
|
},
|
|
815
3181
|
async resume(raw, options) {
|
|
816
|
-
checkOptions(options);
|
|
3182
|
+
checkOptions(options, "resume");
|
|
3183
|
+
options = { ...options, memory: readMemoryBinding(options.memory) };
|
|
817
3184
|
const snapshot = runtime.restore(raw);
|
|
818
|
-
|
|
819
|
-
if (options.
|
|
820
|
-
|
|
821
|
-
snapshot.
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
evidence = copyData({ path: snapshot.state.path, decision: options.decision });
|
|
827
|
-
}
|
|
3185
|
+
checkMemoryBinding(snapshot, options.memory);
|
|
3186
|
+
if (options.session && options.session.id !== snapshot.session?.id)
|
|
3187
|
+
throw new TypeError(
|
|
3188
|
+
snapshot.session
|
|
3189
|
+
? "This run belongs to another session."
|
|
3190
|
+
: "This run has no session. Resume it without one.",
|
|
3191
|
+
);
|
|
3192
|
+
const answers = readAnswers(snapshot, options.answers ?? {});
|
|
828
3193
|
await authorizeTree(snapshot, options.host);
|
|
829
3194
|
snapshot.attemptId = crypto.randomUUID();
|
|
830
|
-
return root(snapshot, options,
|
|
3195
|
+
return root(snapshot, options, answers);
|
|
831
3196
|
},
|
|
832
3197
|
};
|
|
833
3198
|
return Object.freeze(agent);
|