@buildanagent/sdk 0.1.0-alpha.1 → 0.1.0-alpha.11
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/README.md +424 -5
- package/dist/budget.d.ts +33 -0
- package/dist/budget.js +55 -0
- package/dist/budget.js.map +1 -0
- package/dist/compose.d.ts +26 -0
- package/dist/compose.js +157 -0
- package/dist/compose.js.map +1 -0
- package/dist/errors.d.ts +49 -0
- package/dist/errors.js +57 -0
- package/dist/errors.js.map +1 -0
- package/dist/events.d.ts +168 -0
- package/dist/events.js +32 -0
- package/dist/events.js.map +1 -0
- package/dist/freeze.d.ts +11 -0
- package/dist/freeze.js +42 -0
- package/dist/freeze.js.map +1 -0
- package/dist/hook-checks.d.ts +31 -0
- package/dist/hook-checks.js +130 -0
- package/dist/hook-checks.js.map +1 -0
- package/dist/hook-runner.d.ts +96 -0
- package/dist/hook-runner.js +372 -0
- package/dist/hook-runner.js.map +1 -0
- package/dist/hooks.d.ts +183 -0
- package/dist/hooks.js +2 -0
- package/dist/hooks.js.map +1 -0
- package/dist/index.d.ts +26 -3
- package/dist/index.js +21 -3
- package/dist/index.js.map +1 -1
- package/dist/loop.d.ts +67 -0
- package/dist/loop.js +644 -0
- package/dist/loop.js.map +1 -0
- package/dist/observers.d.ts +31 -0
- package/dist/observers.js +98 -0
- package/dist/observers.js.map +1 -0
- package/dist/otel/attributes.d.ts +43 -0
- package/dist/otel/attributes.js +50 -0
- package/dist/otel/attributes.js.map +1 -0
- package/dist/otel/content.d.ts +17 -0
- package/dist/otel/content.js +48 -0
- package/dist/otel/content.js.map +1 -0
- package/dist/otel/index.d.ts +6 -2
- package/dist/otel/index.js +6 -2
- package/dist/otel/index.js.map +1 -1
- package/dist/otel/observer.d.ts +82 -0
- package/dist/otel/observer.js +300 -0
- package/dist/otel/observer.js.map +1 -0
- package/dist/pauses.d.ts +61 -0
- package/dist/pauses.js +83 -0
- package/dist/pauses.js.map +1 -0
- package/dist/progress.d.ts +34 -0
- package/dist/progress.js +139 -0
- package/dist/progress.js.map +1 -0
- package/dist/result.d.ts +134 -0
- package/dist/result.js +2 -0
- package/dist/result.js.map +1 -0
- package/dist/resume.d.ts +76 -0
- package/dist/resume.js +237 -0
- package/dist/resume.js.map +1 -0
- package/dist/run.d.ts +214 -0
- package/dist/run.js +327 -0
- package/dist/run.js.map +1 -0
- package/dist/steering.d.ts +52 -0
- package/dist/steering.js +104 -0
- package/dist/steering.js.map +1 -0
- package/dist/testing/scripted-model.d.ts +12 -2
- package/dist/testing/scripted-model.js +19 -2
- package/dist/testing/scripted-model.js.map +1 -1
- package/dist/tools/coerce.d.ts +15 -0
- package/dist/tools/coerce.js +93 -0
- package/dist/tools/coerce.js.map +1 -0
- package/dist/tools/define.d.ts +54 -0
- package/dist/tools/define.js +121 -0
- package/dist/tools/define.js.map +1 -0
- package/dist/tools/format-error.d.ts +13 -0
- package/dist/tools/format-error.js +66 -0
- package/dist/tools/format-error.js.map +1 -0
- package/dist/tools/outcome.d.ts +7 -0
- package/dist/tools/outcome.js +30 -0
- package/dist/tools/outcome.js.map +1 -0
- package/dist/tools/pipeline.d.ts +111 -0
- package/dist/tools/pipeline.js +382 -0
- package/dist/tools/pipeline.js.map +1 -0
- package/dist/tools/scheduler.d.ts +33 -0
- package/dist/tools/scheduler.js +51 -0
- package/dist/tools/scheduler.js.map +1 -0
- package/dist/tools/schema.d.ts +20 -0
- package/dist/tools/schema.js +100 -0
- package/dist/tools/schema.js.map +1 -0
- package/dist/tools/types.d.ts +196 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/dist/vendor/agent-safety/bytes.d.ts +17 -0
- package/dist/vendor/agent-safety/bytes.js +59 -0
- package/dist/vendor/agent-safety/bytes.js.map +1 -0
- package/dist/vendor/agent-safety/errors.d.ts +23 -0
- package/dist/vendor/agent-safety/errors.js +22 -0
- package/dist/vendor/agent-safety/errors.js.map +1 -0
- package/dist/vendor/agent-safety/hash.d.ts +16 -0
- package/dist/vendor/agent-safety/hash.js +110 -0
- package/dist/vendor/agent-safety/hash.js.map +1 -0
- package/dist/vendor/agent-safety/outcome.d.ts +88 -0
- package/dist/vendor/agent-safety/outcome.js +140 -0
- package/dist/vendor/agent-safety/outcome.js.map +1 -0
- package/dist/vendor/agent-safety/pending.d.ts +119 -0
- package/dist/vendor/agent-safety/pending.js +122 -0
- package/dist/vendor/agent-safety/pending.js.map +1 -0
- package/dist/vendor/agent-safety/render.d.ts +40 -0
- package/dist/vendor/agent-safety/render.js +92 -0
- package/dist/vendor/agent-safety/render.js.map +1 -0
- package/dist/vendor/agent-safety/signer.d.ts +42 -0
- package/dist/vendor/agent-safety/signer.js +128 -0
- package/dist/vendor/agent-safety/signer.js.map +1 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +8 -0
- package/dist/version.js.map +1 -0
- package/package.json +13 -3
package/dist/loop.js
ADDED
|
@@ -0,0 +1,644 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds
|
|
3
|
+
* (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.
|
|
4
|
+
*
|
|
5
|
+
* Each step runs transform → before → stream → after → tools → stop. Those moments are where the interceptors
|
|
6
|
+
* plug in (D6); a run without interceptors sends the transcript as it stands and keeps each response unchanged.
|
|
7
|
+
* Every outcome is a stop reason, never an exception: only a programmer error, such as a malformed tool result,
|
|
8
|
+
* throws.
|
|
9
|
+
*/
|
|
10
|
+
import { addCost, addUsage, emptyUsage, projectCallCost, } from "@buildanagent/gateway";
|
|
11
|
+
import { checkBudget, unknownPriceError } from "./budget.js";
|
|
12
|
+
import { isSdkError, SdkError } from "./errors.js";
|
|
13
|
+
import { HookFailure, HookRunner } from "./hook-runner.js";
|
|
14
|
+
import { judgeOpenCalls } from "./resume.js";
|
|
15
|
+
import { toWireTool } from "./tools/define.js";
|
|
16
|
+
import { runToolCalls } from "./tools/pipeline.js";
|
|
17
|
+
/**
|
|
18
|
+
* The cost of no model call: an exact zero. Its basis is `provider` because `addCost()` keeps the other cost's basis
|
|
19
|
+
* when it adds a provider cost, so the zero never turns a billed sum into an estimate.
|
|
20
|
+
*/
|
|
21
|
+
const NO_COST = { total: 0, basis: "provider", currency: "USD" };
|
|
22
|
+
/** What changes while a run goes on. */
|
|
23
|
+
class LoopState {
|
|
24
|
+
setup;
|
|
25
|
+
emit;
|
|
26
|
+
messages;
|
|
27
|
+
added;
|
|
28
|
+
drain;
|
|
29
|
+
hooks;
|
|
30
|
+
#wire;
|
|
31
|
+
/** The tools the latest request sent; the tool calls of its response may run only these. */
|
|
32
|
+
active = [];
|
|
33
|
+
steps = 0;
|
|
34
|
+
stepIndex = 0;
|
|
35
|
+
usage = emptyUsage();
|
|
36
|
+
lastUsage;
|
|
37
|
+
cost;
|
|
38
|
+
output;
|
|
39
|
+
/** Set when the run was kept going to deliver a follow-up, so the next step boundary applies the follow-ups too. */
|
|
40
|
+
releaseFollowUps = false;
|
|
41
|
+
/** The signed requests of the calls that gates paused, in model order. */
|
|
42
|
+
pending = [];
|
|
43
|
+
/**
|
|
44
|
+
* The input each pending request signs, by request id. It has no prototype, because an id comes from the host's
|
|
45
|
+
* `idGenerator` and `"__proto__"` must be stored as a key like any other.
|
|
46
|
+
*/
|
|
47
|
+
pendingInputs = Object.create(null);
|
|
48
|
+
constructor(setup, emit, drain) {
|
|
49
|
+
this.setup = setup;
|
|
50
|
+
this.emit = emit;
|
|
51
|
+
this.drain = drain;
|
|
52
|
+
this.messages = [...setup.history, ...setup.input];
|
|
53
|
+
this.added = [...setup.input];
|
|
54
|
+
this.#wire = new Map(setup.tools.map((tool) => [tool, toWireTool(tool)]));
|
|
55
|
+
this.hooks = new HookRunner({
|
|
56
|
+
interceptors: setup.interceptors,
|
|
57
|
+
runId: setup.runId,
|
|
58
|
+
signal: setup.signal,
|
|
59
|
+
clock: setup.clock,
|
|
60
|
+
stepIndex: () => this.stepIndex,
|
|
61
|
+
send: (body) => this.send(body),
|
|
62
|
+
signer: setup.signer,
|
|
63
|
+
nextId: setup.nextId,
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
/** The wire form of each of `tools`, as a request sends them. */
|
|
67
|
+
wireOf(tools) {
|
|
68
|
+
// Every tool of the run was lowered in the constructor, and a request names only the run's tools.
|
|
69
|
+
return tools.map((tool) => this.#wire.get(tool));
|
|
70
|
+
}
|
|
71
|
+
send(body) {
|
|
72
|
+
this.emit(body, this.stepIndex);
|
|
73
|
+
}
|
|
74
|
+
append(message) {
|
|
75
|
+
this.messages.push(message);
|
|
76
|
+
this.added.push(message);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The stream options a request event records: everything but the payload hook, the abort signal and the caps, as the
|
|
81
|
+
* gateway's own request dump leaves them out. An untyped caller may still pass a signal or caps in `modelOptions`.
|
|
82
|
+
*/
|
|
83
|
+
function dumpedOptions(options) {
|
|
84
|
+
const { onPayload: _onPayload, signal: _signal, caps: _caps, ...rest } = options;
|
|
85
|
+
return rest;
|
|
86
|
+
}
|
|
87
|
+
/** Re-emits one model event as a run event, and returns the final message once the terminal event arrives. */
|
|
88
|
+
function forward(state, event) {
|
|
89
|
+
switch (event.type) {
|
|
90
|
+
case "done":
|
|
91
|
+
case "error":
|
|
92
|
+
return event.message;
|
|
93
|
+
case "start":
|
|
94
|
+
return undefined;
|
|
95
|
+
case "retry":
|
|
96
|
+
state.send({ type: "retry", attempt: event.attempt, delayMs: event.delayMs, error: event.error });
|
|
97
|
+
return undefined;
|
|
98
|
+
case "warning":
|
|
99
|
+
state.send({ type: "warning", code: "model_warning", detail: `${event.code}: ${event.message}` });
|
|
100
|
+
return undefined;
|
|
101
|
+
case "text_start":
|
|
102
|
+
case "reasoning_start":
|
|
103
|
+
case "tool_input_start":
|
|
104
|
+
state.send({ type: event.type, index: event.index });
|
|
105
|
+
return undefined;
|
|
106
|
+
case "text_delta":
|
|
107
|
+
case "reasoning_delta":
|
|
108
|
+
case "tool_input_delta":
|
|
109
|
+
state.send({ type: event.type, index: event.index, delta: event.delta });
|
|
110
|
+
return undefined;
|
|
111
|
+
default:
|
|
112
|
+
state.send({ type: event.type, index: event.index, block: event.block });
|
|
113
|
+
return undefined;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
/** The tools a request sends unless `beforeModelCall` names others: the ones whose exposure is `direct`. */
|
|
117
|
+
function directTools(tools) {
|
|
118
|
+
return tools.filter((tool) => (tool.exposure ?? "direct") === "direct");
|
|
119
|
+
}
|
|
120
|
+
/** The tools `names` picks, in definition order whatever order `names` is in. */
|
|
121
|
+
function toolsNamed(tools, names) {
|
|
122
|
+
const unknown = names.filter((name) => !tools.some((tool) => tool.name === name));
|
|
123
|
+
if (unknown.length > 0) {
|
|
124
|
+
throw new SdkError("invalid_hook_result", `activeTools names unknown tools: ${unknown.join(", ")}`);
|
|
125
|
+
}
|
|
126
|
+
return tools.filter((tool) => names.includes(tool.name));
|
|
127
|
+
}
|
|
128
|
+
function patched(state, request, patch) {
|
|
129
|
+
const active = patch.activeTools === undefined ? request.active : toolsNamed(state.setup.tools, patch.activeTools);
|
|
130
|
+
const { system, messages } = request.context;
|
|
131
|
+
return {
|
|
132
|
+
model: patch.model ?? request.model,
|
|
133
|
+
options: patch.options ?? request.options,
|
|
134
|
+
active,
|
|
135
|
+
context: {
|
|
136
|
+
system: patch.system ?? system,
|
|
137
|
+
messages: patch.messages === undefined ? messages : [...patch.messages],
|
|
138
|
+
tools: state.wireOf(active),
|
|
139
|
+
},
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Builds one call's request: the transcript, or the view `transformContext` returns for this call alone, then the
|
|
144
|
+
* changes `beforeModelCall` asks for. The run's own transcript is never replaced by either.
|
|
145
|
+
*/
|
|
146
|
+
async function buildRequest(state) {
|
|
147
|
+
const { model, system, modelOptions, tools } = state.setup;
|
|
148
|
+
const view = await state.hooks.transformContext({
|
|
149
|
+
system,
|
|
150
|
+
messages: state.messages,
|
|
151
|
+
model: model.ref,
|
|
152
|
+
lastUsage: state.lastUsage,
|
|
153
|
+
});
|
|
154
|
+
const active = directTools(tools);
|
|
155
|
+
const context = { system, messages: [...(view ?? state.messages)], tools: state.wireOf(active) };
|
|
156
|
+
const request = { model, context, options: modelOptions, active };
|
|
157
|
+
const patch = await state.hooks.beforeModelCall({ context, options: modelOptions });
|
|
158
|
+
return patch === undefined ? request : patched(state, request, patch);
|
|
159
|
+
}
|
|
160
|
+
/** Streams one request, re-emitting its events, and returns the model's final message. */
|
|
161
|
+
async function streamRequest(state, request) {
|
|
162
|
+
const { model, context, options } = request;
|
|
163
|
+
state.send({ type: "model_call_start", request: { model: model.ref, context, options: dumpedOptions(options) } });
|
|
164
|
+
let message;
|
|
165
|
+
for await (const event of model.stream(context, { ...options, signal: state.setup.signal })) {
|
|
166
|
+
message = forward(state, event) ?? message;
|
|
167
|
+
}
|
|
168
|
+
if (message === undefined) {
|
|
169
|
+
throw new SdkError("invalid_model_stream", "the model's stream ended without a done or error event");
|
|
170
|
+
}
|
|
171
|
+
return message;
|
|
172
|
+
}
|
|
173
|
+
/** Adds a model call's response to the transcript and reports it. */
|
|
174
|
+
function record(state, message) {
|
|
175
|
+
state.append(message);
|
|
176
|
+
state.send({ type: "model_call_end", message });
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* What the transcript holds for a response whose `afterModelCall` failed while the run fails closed: no content, so a
|
|
180
|
+
* check that crashed can't let the response through, but the call's usage and cost, which were billed. Its error stop
|
|
181
|
+
* reason makes the replay pass skip it if the run is continued.
|
|
182
|
+
*/
|
|
183
|
+
function withheld(original) {
|
|
184
|
+
const { model, usage, cost, lastAttemptUsage } = original;
|
|
185
|
+
return {
|
|
186
|
+
role: "assistant",
|
|
187
|
+
content: [],
|
|
188
|
+
model,
|
|
189
|
+
stopReason: "error",
|
|
190
|
+
error: { kind: "fatal", message: "the response was withheld, because its afterModelCall check failed" },
|
|
191
|
+
usage,
|
|
192
|
+
...(lastAttemptUsage === undefined ? {} : { lastAttemptUsage }),
|
|
193
|
+
cost,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The budget check before a call (D9): the outcome that ends the run when the spend so far plus the call's projected
|
|
198
|
+
* cost would pass `budgetUsd`, or `undefined` when the call may go out. It checks the request as it will be sent,
|
|
199
|
+
* after the interceptors have changed it, and projects with the model the request names.
|
|
200
|
+
*/
|
|
201
|
+
function budgetBlock(state, request) {
|
|
202
|
+
const { budgetUsd } = state.setup;
|
|
203
|
+
if (budgetUsd === undefined)
|
|
204
|
+
return undefined;
|
|
205
|
+
const projected = projectCallCost(request.model, request.context, request.options);
|
|
206
|
+
const verdict = checkBudget(budgetUsd, state.cost, projected);
|
|
207
|
+
switch (verdict.kind) {
|
|
208
|
+
case "allow":
|
|
209
|
+
return undefined;
|
|
210
|
+
case "unknown":
|
|
211
|
+
return { stopReason: "error", error: verdict.error };
|
|
212
|
+
case "exceeded":
|
|
213
|
+
return {
|
|
214
|
+
stopReason: "budget",
|
|
215
|
+
reason: verdict.reason,
|
|
216
|
+
budgetUsd,
|
|
217
|
+
spentUsd: verdict.spentUsd,
|
|
218
|
+
projectedUsd: verdict.projectedUsd,
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Makes one model call, streams its events and records the response. The call's usage and cost are the model's own
|
|
224
|
+
* message's, so an `afterModelCall` replacement changes what the run goes on with, never what it is billed. When
|
|
225
|
+
* `afterModelCall` fails and the run fails closed, a withheld stand-in is recorded before the run ends, so the
|
|
226
|
+
* transcript and `model_call_end` still account for the billed call and none of its tool calls run.
|
|
227
|
+
*/
|
|
228
|
+
async function callModel(state) {
|
|
229
|
+
const request = await buildRequest(state);
|
|
230
|
+
const blocked = budgetBlock(state, request);
|
|
231
|
+
if (blocked !== undefined)
|
|
232
|
+
return { blocked };
|
|
233
|
+
state.active = request.active;
|
|
234
|
+
const original = await streamRequest(state, request);
|
|
235
|
+
state.steps += 1;
|
|
236
|
+
state.usage = addUsage(state.usage, original.usage);
|
|
237
|
+
state.lastUsage = original.usage;
|
|
238
|
+
state.cost = state.cost === undefined ? original.cost : addCost(state.cost, original.cost);
|
|
239
|
+
let message;
|
|
240
|
+
try {
|
|
241
|
+
message = await state.hooks.afterModelCall(original);
|
|
242
|
+
}
|
|
243
|
+
catch (error) {
|
|
244
|
+
if (error instanceof HookFailure || (isSdkError(error) && error.code === "invalid_hook_result")) {
|
|
245
|
+
record(state, withheld(original));
|
|
246
|
+
}
|
|
247
|
+
throw error;
|
|
248
|
+
}
|
|
249
|
+
record(state, message);
|
|
250
|
+
return message;
|
|
251
|
+
}
|
|
252
|
+
/** The tool message the model reads for one call. */
|
|
253
|
+
function toolMessage(entry) {
|
|
254
|
+
return {
|
|
255
|
+
role: "tool",
|
|
256
|
+
callId: entry.call.callId,
|
|
257
|
+
content: [...entry.result.content],
|
|
258
|
+
isError: entry.result.isError === true,
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
/** Records one call's result: the tool message the model reads, the output tool's answer and `tool_call_end`. */
|
|
262
|
+
function recordResult(state, entry) {
|
|
263
|
+
const { output } = state.setup;
|
|
264
|
+
state.append(toolMessage(entry));
|
|
265
|
+
if (output !== undefined && entry.call.name === output.name && entry.result.isError !== true) {
|
|
266
|
+
state.output = entry.result.structured;
|
|
267
|
+
}
|
|
268
|
+
const ranWith = "input" in entry ? { input: entry.input } : {};
|
|
269
|
+
state.send({ type: "tool_call_end", callId: entry.call.callId, result: entry.result, ...ranWith });
|
|
270
|
+
}
|
|
271
|
+
/** Holds a signed request for a person: in the run's pending list, by id in its inputs, and as `approval_request`. */
|
|
272
|
+
function holdPause(state, request, input) {
|
|
273
|
+
state.pending.push(request);
|
|
274
|
+
state.pendingInputs[request.id] = input;
|
|
275
|
+
state.send({ type: "approval_request", request, input });
|
|
276
|
+
}
|
|
277
|
+
/** True for a result that asks the user a question, which pauses its call instead of reaching the model. */
|
|
278
|
+
function asksUser(result) {
|
|
279
|
+
return result.pause !== undefined && result.isError !== true;
|
|
280
|
+
}
|
|
281
|
+
/** The pipeline callbacks every tool batch of the run shares. `onResult` holds back a question for `askUser()`. */
|
|
282
|
+
function pipelineOf(state, asks) {
|
|
283
|
+
const { runId, signal, clock, depth, maxDepth } = state.setup;
|
|
284
|
+
return {
|
|
285
|
+
runId,
|
|
286
|
+
signal,
|
|
287
|
+
clock,
|
|
288
|
+
depth,
|
|
289
|
+
maxDepth,
|
|
290
|
+
onStart: (call) => state.send({ type: "tool_call_start", callId: call.callId, tool: call.name, input: call.input }),
|
|
291
|
+
onUpdate: (callId, details) => state.send({ type: "tool_call_update", callId, details }),
|
|
292
|
+
onPause: ({ request, input }) => holdPause(state, request, input),
|
|
293
|
+
onResult: (entry) => {
|
|
294
|
+
if (asksUser(entry.result))
|
|
295
|
+
asks.push(entry);
|
|
296
|
+
else
|
|
297
|
+
recordResult(state, entry);
|
|
298
|
+
},
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Signs a clarification request for each call whose tool asked the user a question, in model order. The call then
|
|
303
|
+
* waits like a paused one, with no result; a question that can't be signed reaches the model as an error result.
|
|
304
|
+
* Returns the batch's results with those error results in place.
|
|
305
|
+
*/
|
|
306
|
+
async function askUser(state, results, asks) {
|
|
307
|
+
const replaced = new Map();
|
|
308
|
+
for (const entry of asks) {
|
|
309
|
+
const question = entry.result.pause?.question;
|
|
310
|
+
const outcome = await state.hooks.clarify(entry.call, entry.ranWith, question);
|
|
311
|
+
if ("paused" in outcome) {
|
|
312
|
+
holdPause(state, outcome.paused, outcome.input);
|
|
313
|
+
}
|
|
314
|
+
else if ("blocked" in outcome) {
|
|
315
|
+
const blocked = { call: entry.call, result: outcome.blocked };
|
|
316
|
+
recordResult(state, blocked);
|
|
317
|
+
replaced.set(entry, blocked);
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
return results.map((entry) => replaced.get(entry) ?? entry);
|
|
321
|
+
}
|
|
322
|
+
/** Runs the response's tool calls as the pipeline schedules them, recording each result in model order. */
|
|
323
|
+
async function runTools(state, message) {
|
|
324
|
+
const asks = [];
|
|
325
|
+
const results = await runToolCalls(message, state.active, {
|
|
326
|
+
...pipelineOf(state, asks),
|
|
327
|
+
...state.hooks.pipelineHooks(),
|
|
328
|
+
});
|
|
329
|
+
return asks.length === 0 ? results : askUser(state, results, asks);
|
|
330
|
+
}
|
|
331
|
+
/**
|
|
332
|
+
* The outcome of a run whose calls wait for a person. Its requests are put in the model's order of their calls, and
|
|
333
|
+
* it ends `awaiting_approval` when any waits for an approval, or `clarification_requested` when all wait for answers.
|
|
334
|
+
*/
|
|
335
|
+
function pausedOutcome(state, message) {
|
|
336
|
+
const order = callOrderOf(message);
|
|
337
|
+
const pending = [...state.pending].sort((a, b) => order.indexOf(a.callId) - order.indexOf(b.callId));
|
|
338
|
+
const approval = pending.some((request) => request.kind === "approval");
|
|
339
|
+
return {
|
|
340
|
+
stopReason: approval ? "awaiting_approval" : "clarification_requested",
|
|
341
|
+
pending,
|
|
342
|
+
pendingInputs: { ...state.pendingInputs },
|
|
343
|
+
};
|
|
344
|
+
}
|
|
345
|
+
/** The failed call's error as the run reports it. A message without one counts as `fatal`. */
|
|
346
|
+
function runErrorOf(message) {
|
|
347
|
+
const error = message.error;
|
|
348
|
+
if (error === undefined)
|
|
349
|
+
return { kind: "fatal", message: "the model call failed without an error description" };
|
|
350
|
+
return { kind: error.kind, message: error.message, ...(error.status === undefined ? {} : { status: error.status }) };
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* The stop check after one step. A pause, including a question for the user, or a finished answer wins over an abort
|
|
354
|
+
* that came too late to change it; otherwise an abort stops the run before the step cap does. A pause wins over a
|
|
355
|
+
* finished answer too, because its call is still waiting. A text answer cut off at the output limit also counts as
|
|
356
|
+
* finished: its message keeps `stopReason: "length"`.
|
|
357
|
+
*/
|
|
358
|
+
function stopCheck(state, message, results) {
|
|
359
|
+
if (message.stopReason === "error")
|
|
360
|
+
return { stopReason: "error", error: runErrorOf(message) };
|
|
361
|
+
if (message.stopReason === "aborted")
|
|
362
|
+
return { stopReason: "aborted" };
|
|
363
|
+
// A paused call is still waiting, so the run can't count as finished, and the pause is signed and stored with the
|
|
364
|
+
// context, so it outlasts an abort that came while the step's other calls ran.
|
|
365
|
+
if (state.pending.length > 0)
|
|
366
|
+
return pausedOutcome(state, message);
|
|
367
|
+
const finished = results.length === 0 || results.some(({ result }) => result.terminate === true && !result.isError);
|
|
368
|
+
if (finished)
|
|
369
|
+
return { stopReason: "done", output: state.output };
|
|
370
|
+
if (state.setup.signal.aborted)
|
|
371
|
+
return { stopReason: "aborted" };
|
|
372
|
+
if (state.steps >= state.setup.maxSteps)
|
|
373
|
+
return { stopReason: "max_steps" };
|
|
374
|
+
return undefined;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* What `shouldStop` changes about the stop check. A finished answer or an error stands whatever the hook says; the
|
|
378
|
+
* hook can end a run that would go on, and can keep going a run the model ended by answering in text, until the
|
|
379
|
+
* step cap.
|
|
380
|
+
*/
|
|
381
|
+
function withVerdict(state, natural, verdict) {
|
|
382
|
+
if (natural !== undefined && verdict.kind !== "continue")
|
|
383
|
+
return natural;
|
|
384
|
+
switch (verdict.kind) {
|
|
385
|
+
case "stop":
|
|
386
|
+
return { stopReason: "stopped", stoppedBy: verdict.stoppedBy };
|
|
387
|
+
case "no_progress":
|
|
388
|
+
return { stopReason: "no_progress", reason: verdict.reason };
|
|
389
|
+
case "continue":
|
|
390
|
+
if (natural === undefined)
|
|
391
|
+
return undefined;
|
|
392
|
+
if (state.steps >= state.setup.maxSteps)
|
|
393
|
+
return { stopReason: "max_steps" };
|
|
394
|
+
state.append({ role: "user", content: verdict.content });
|
|
395
|
+
return undefined;
|
|
396
|
+
default:
|
|
397
|
+
return natural;
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* Applies the queued messages before a model call: every steer, and the follow-ups too once the run was kept going to
|
|
402
|
+
* deliver them. Each becomes a user message and a `steer_applied` event, in the order it was sent, and its receipt
|
|
403
|
+
* resolves with the index of the step about to run.
|
|
404
|
+
*/
|
|
405
|
+
function applySteering(state) {
|
|
406
|
+
const { steering } = state.setup;
|
|
407
|
+
const withFollowUps = state.releaseFollowUps;
|
|
408
|
+
state.releaseFollowUps = false;
|
|
409
|
+
for (const delivery of steering.take(withFollowUps)) {
|
|
410
|
+
// A copy, so a caller who changes a receipt's message cannot change the transcript.
|
|
411
|
+
state.append({ role: "user", content: delivery.message.map((block) => ({ ...block })) });
|
|
412
|
+
state.send({ type: "steer_applied", receipt: delivery.deliver(state.stepIndex) });
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
/**
|
|
416
|
+
* Keeps a run that its model ended by answering going, when a message is waiting and the step cap leaves room for
|
|
417
|
+
* one more call: a steer comes first, and follow-ups wait for the next time the run would end. Any other outcome
|
|
418
|
+
* stands, as does a `stop` or `no_progress` verdict that `withVerdict` folded into `done`, and an abort that came
|
|
419
|
+
* after the answer, which `stopCheck` lets the answer win over. The messages still waiting are rejected when the run
|
|
420
|
+
* ends.
|
|
421
|
+
*/
|
|
422
|
+
function withQueued(state, outcome, verdict) {
|
|
423
|
+
const { steering, maxSteps, signal } = state.setup;
|
|
424
|
+
if (outcome?.stopReason !== "done" || !steering.hasPending() || state.steps >= maxSteps)
|
|
425
|
+
return outcome;
|
|
426
|
+
if (verdict.kind === "stop" || verdict.kind === "no_progress" || signal.aborted)
|
|
427
|
+
return outcome;
|
|
428
|
+
state.releaseFollowUps = !steering.hasSteers();
|
|
429
|
+
return undefined;
|
|
430
|
+
}
|
|
431
|
+
/** The stop check after one step, then the `shouldStop` hook where it may change it. */
|
|
432
|
+
async function decide(state, message, results) {
|
|
433
|
+
const natural = stopCheck(state, message, results);
|
|
434
|
+
const endedByAnswer = natural?.stopReason === "done" && results.length === 0;
|
|
435
|
+
if (natural !== undefined && !endedByAnswer)
|
|
436
|
+
return natural;
|
|
437
|
+
const verdict = await state.hooks.shouldStop({ messages: state.messages, lastMessage: message });
|
|
438
|
+
const judged = await withProgress(state, verdict);
|
|
439
|
+
const outcome = withVerdict(state, natural, judged);
|
|
440
|
+
return endedByAnswer ? withQueued(state, outcome, judged) : outcome;
|
|
441
|
+
}
|
|
442
|
+
/**
|
|
443
|
+
* The caller's verdict, unless the progress policy finds the run stuck. A caller's own stop stands, and a caller's
|
|
444
|
+
* `{ continue }` or failed hook can't keep a stuck run going.
|
|
445
|
+
*/
|
|
446
|
+
async function withProgress(state, verdict) {
|
|
447
|
+
if (verdict.kind === "stop" || verdict.kind === "no_progress" || state.setup.progress === undefined)
|
|
448
|
+
return verdict;
|
|
449
|
+
const reason = await state.setup.progress(state.messages);
|
|
450
|
+
return reason === undefined ? verdict : { kind: "no_progress", reason };
|
|
451
|
+
}
|
|
452
|
+
/** The outcome of a hook that failed while the run fails closed. A failure caused by an abort ends the run aborted. */
|
|
453
|
+
function failedOutcome(state, error) {
|
|
454
|
+
if (!(error instanceof HookFailure))
|
|
455
|
+
throw error;
|
|
456
|
+
if (state.setup.signal.aborted)
|
|
457
|
+
return { stopReason: "aborted" };
|
|
458
|
+
return { stopReason: "error", error: { kind: "hook", message: error.message } };
|
|
459
|
+
}
|
|
460
|
+
async function runStep(state) {
|
|
461
|
+
state.stepIndex = state.steps;
|
|
462
|
+
state.send({ type: "step_start" });
|
|
463
|
+
let outcome;
|
|
464
|
+
try {
|
|
465
|
+
applySteering(state);
|
|
466
|
+
const called = await callModel(state);
|
|
467
|
+
if ("blocked" in called) {
|
|
468
|
+
outcome = called.blocked;
|
|
469
|
+
}
|
|
470
|
+
else {
|
|
471
|
+
const results = await runTools(state, called);
|
|
472
|
+
outcome = await decide(state, called, results);
|
|
473
|
+
}
|
|
474
|
+
}
|
|
475
|
+
catch (error) {
|
|
476
|
+
outcome = failedOutcome(state, error);
|
|
477
|
+
}
|
|
478
|
+
state.send({ type: "step_end", stopCheck: outcome === undefined ? "continue" : "stop" });
|
|
479
|
+
return outcome;
|
|
480
|
+
}
|
|
481
|
+
/**
|
|
482
|
+
* An aborted run's transcript ends with an assistant message whose `stopReason` is `"aborted"`. When tool results end
|
|
483
|
+
* the transcript, because the abort came while tools ran or cut off a response that held tool calls, the loop
|
|
484
|
+
* appends an empty one after them; the replay pass drops it before any request.
|
|
485
|
+
*/
|
|
486
|
+
function closeAborted(state) {
|
|
487
|
+
const last = state.messages.at(-1);
|
|
488
|
+
if (last?.role === "assistant" && last.stopReason === "aborted")
|
|
489
|
+
return;
|
|
490
|
+
state.append({
|
|
491
|
+
role: "assistant",
|
|
492
|
+
content: [],
|
|
493
|
+
model: state.setup.model.ref,
|
|
494
|
+
stopReason: "aborted",
|
|
495
|
+
usage: emptyUsage(),
|
|
496
|
+
cost: { ...NO_COST },
|
|
497
|
+
});
|
|
498
|
+
}
|
|
499
|
+
function resultOf(state, outcome) {
|
|
500
|
+
const pending = outcome.stopReason === "awaiting_approval" || outcome.stopReason === "clarification_requested"
|
|
501
|
+
? { pending: [...outcome.pending], pendingInputs: { ...outcome.pendingInputs } }
|
|
502
|
+
: {};
|
|
503
|
+
const base = {
|
|
504
|
+
messages: state.added,
|
|
505
|
+
context: { system: state.setup.system, messages: state.messages, ...pending },
|
|
506
|
+
usage: state.usage,
|
|
507
|
+
cost: state.cost ?? { ...NO_COST },
|
|
508
|
+
steps: state.steps,
|
|
509
|
+
};
|
|
510
|
+
return { ...base, ...outcome };
|
|
511
|
+
}
|
|
512
|
+
/**
|
|
513
|
+
* Ends the run: the settle event comes once every observer has seen what came before it, and `run_end` after that.
|
|
514
|
+
* An observer's failure while handling `agent_settled` is reported between the two; one while handling `run_end` is
|
|
515
|
+
* dropped, so `run_end` stays the last event. The result is returned only once observers have seen it.
|
|
516
|
+
*/
|
|
517
|
+
async function finish(state, outcome) {
|
|
518
|
+
if (outcome.stopReason === "aborted")
|
|
519
|
+
closeAborted(state);
|
|
520
|
+
if (outcome.stopReason === "max_steps") {
|
|
521
|
+
state.send({ type: "warning", code: "max_steps", detail: `the run reached maxSteps (${state.setup.maxSteps})` });
|
|
522
|
+
}
|
|
523
|
+
if (outcome.stopReason === "error")
|
|
524
|
+
state.send({ type: "error", error: outcome.error });
|
|
525
|
+
await state.drain();
|
|
526
|
+
state.send({ type: "agent_settled" });
|
|
527
|
+
await state.drain();
|
|
528
|
+
const result = resultOf(state, outcome);
|
|
529
|
+
state.send({ type: "run_end", result });
|
|
530
|
+
await state.drain();
|
|
531
|
+
return result;
|
|
532
|
+
}
|
|
533
|
+
/** The synthetic response that holds `calls`, so the pipeline runs them as one batch of the resumed message. */
|
|
534
|
+
function batchOf(message, calls) {
|
|
535
|
+
return { ...message, content: [...calls], stopReason: "tool_calls" };
|
|
536
|
+
}
|
|
537
|
+
/** The call ids of `message`'s tool calls, in model order. */
|
|
538
|
+
function callOrderOf(message) {
|
|
539
|
+
return message.content.flatMap((block) => (block.type === "tool_call" ? [block.callId] : []));
|
|
540
|
+
}
|
|
541
|
+
/**
|
|
542
|
+
* Puts the tool messages `list` gained from `from` on in the model's order of their calls, as a step records them.
|
|
543
|
+
* A resume settles its calls by verdict, so without this a denial could come before an approval the model made first.
|
|
544
|
+
*/
|
|
545
|
+
function inModelOrder(list, from, order) {
|
|
546
|
+
const rank = (entry) => (entry.role === "tool" ? order.indexOf(entry.callId) : order.length);
|
|
547
|
+
const tail = list.splice(from).sort((a, b) => rank(a) - rank(b));
|
|
548
|
+
list.push(...tail);
|
|
549
|
+
}
|
|
550
|
+
/**
|
|
551
|
+
* Acts on the verdicts for a resumed context's waiting calls, before the run's first model call, which none of this
|
|
552
|
+
* counts as, and records their results in the model's order. Returns the paused outcome when any call still waits,
|
|
553
|
+
* and `done` when none does and an approved call's result ends the run, as `terminate` does in a step.
|
|
554
|
+
*/
|
|
555
|
+
async function resume(state, setup) {
|
|
556
|
+
const { message } = setup;
|
|
557
|
+
const from = { messages: state.messages.length, added: state.added.length };
|
|
558
|
+
try {
|
|
559
|
+
return await settle(state, setup);
|
|
560
|
+
}
|
|
561
|
+
finally {
|
|
562
|
+
if (message !== undefined) {
|
|
563
|
+
const order = callOrderOf(message);
|
|
564
|
+
inModelOrder(state.messages, from.messages, order);
|
|
565
|
+
inModelOrder(state.added, from.added, order);
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
}
|
|
569
|
+
/**
|
|
570
|
+
* Verified answers and denials reach the model as results; verified approvals run, without the gate, with the input
|
|
571
|
+
* their requests sign; requests that still wait stay pending; and calls whose checks failed ask again, through the
|
|
572
|
+
* gate but never running.
|
|
573
|
+
*/
|
|
574
|
+
async function settle(state, setup) {
|
|
575
|
+
const { signer } = state.setup;
|
|
576
|
+
state.hooks.reserveRequestIds(setup.open.map((entry) => entry.request.id));
|
|
577
|
+
const verdicts = await judgeOpenCalls(setup, { signer, send: (body) => state.send(body) });
|
|
578
|
+
const of = (kind) => verdicts.filter((verdict) => verdict.kind === kind);
|
|
579
|
+
for (const { call, result } of of("result")) {
|
|
580
|
+
state.send({ type: "tool_call_start", callId: call.callId, tool: call.name, input: call.input });
|
|
581
|
+
recordResult(state, { call, result });
|
|
582
|
+
}
|
|
583
|
+
const asks = [];
|
|
584
|
+
const { message } = setup;
|
|
585
|
+
if (message === undefined)
|
|
586
|
+
return undefined;
|
|
587
|
+
const run = of("run").map((verdict) => verdict.call);
|
|
588
|
+
let ran = [];
|
|
589
|
+
if (run.length > 0) {
|
|
590
|
+
const { after } = state.hooks.pipelineHooks();
|
|
591
|
+
const ctx = { ...pipelineOf(state, asks), approved: true, ...(after === undefined ? {} : { after }) };
|
|
592
|
+
// A verified request names its tool, and the run signed it only for a call to a tool its request had sent.
|
|
593
|
+
const results = await runToolCalls(batchOf(message, run), state.setup.tools, ctx);
|
|
594
|
+
ran = asks.length > 0 ? await askUser(state, results, asks) : results;
|
|
595
|
+
}
|
|
596
|
+
for (const { request, input } of of("wait")) {
|
|
597
|
+
state.pending.push(request);
|
|
598
|
+
state.pendingInputs[request.id] = input;
|
|
599
|
+
}
|
|
600
|
+
const again = of("reissue").map((verdict) => verdict.call);
|
|
601
|
+
if (again.length > 0) {
|
|
602
|
+
const ctx = { ...pipelineOf(state, asks), gate: state.hooks.reissueGate() };
|
|
603
|
+
// Nothing verified these calls, so only the tools a request sends by default may ask again: a stored context
|
|
604
|
+
// can't get a new signed request for a tool the model is never sent.
|
|
605
|
+
await runToolCalls(batchOf(message, again), directTools(state.setup.tools), ctx);
|
|
606
|
+
}
|
|
607
|
+
if (state.pending.length > 0)
|
|
608
|
+
return pausedOutcome(state, message);
|
|
609
|
+
const ends = ran.some(({ result }) => result.terminate === true && !result.isError);
|
|
610
|
+
return ends ? { stopReason: "done", output: state.output } : undefined;
|
|
611
|
+
}
|
|
612
|
+
/** `resume()`, with a hook that failed while the run fails closed ending the run as a step's failure would. */
|
|
613
|
+
async function resumeOrFail(state, setup) {
|
|
614
|
+
try {
|
|
615
|
+
return await resume(state, setup);
|
|
616
|
+
}
|
|
617
|
+
catch (error) {
|
|
618
|
+
return failedOutcome(state, error);
|
|
619
|
+
}
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results
|
|
623
|
+
* already received are in the transcript.
|
|
624
|
+
*/
|
|
625
|
+
export async function runLoop(setup, emit, drain) {
|
|
626
|
+
const state = new LoopState(setup, emit, drain);
|
|
627
|
+
// A budget needs a price to check against, so a model without one is refused before it is called (D4).
|
|
628
|
+
const refused = setup.budgetUsd === undefined ? undefined : unknownPriceError(setup.model);
|
|
629
|
+
let outcome = refused === undefined ? undefined : { stopReason: "error", error: refused };
|
|
630
|
+
try {
|
|
631
|
+
if (outcome === undefined && setup.resume !== undefined)
|
|
632
|
+
outcome = await resumeOrFail(state, setup.resume);
|
|
633
|
+
while (outcome === undefined) {
|
|
634
|
+
outcome = setup.signal.aborted ? { stopReason: "aborted" } : await runStep(state);
|
|
635
|
+
}
|
|
636
|
+
}
|
|
637
|
+
finally {
|
|
638
|
+
// The run has its outcome, or threw for a programmer error, so a message still waiting can no longer reach a
|
|
639
|
+
// model call, and its receipt must not hang.
|
|
640
|
+
setup.steering.close();
|
|
641
|
+
}
|
|
642
|
+
return finish(state, outcome);
|
|
643
|
+
}
|
|
644
|
+
//# sourceMappingURL=loop.js.map
|