@buildanagent/sdk 0.1.0-alpha.3 → 0.1.0-alpha.5

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.
Files changed (50) hide show
  1. package/README.md +76 -6
  2. package/dist/compose.d.ts +22 -0
  3. package/dist/compose.js +137 -0
  4. package/dist/compose.js.map +1 -0
  5. package/dist/errors.d.ts +12 -7
  6. package/dist/errors.js +11 -6
  7. package/dist/errors.js.map +1 -1
  8. package/dist/events.d.ts +22 -2
  9. package/dist/events.js +2 -0
  10. package/dist/events.js.map +1 -1
  11. package/dist/freeze.d.ts +11 -0
  12. package/dist/freeze.js +42 -0
  13. package/dist/freeze.js.map +1 -0
  14. package/dist/hook-checks.d.ts +31 -0
  15. package/dist/hook-checks.js +113 -0
  16. package/dist/hook-checks.js.map +1 -0
  17. package/dist/hook-runner.d.ts +60 -0
  18. package/dist/hook-runner.js +169 -0
  19. package/dist/hook-runner.js.map +1 -0
  20. package/dist/hooks.d.ts +177 -0
  21. package/dist/hooks.js +2 -0
  22. package/dist/hooks.js.map +1 -0
  23. package/dist/index.d.ts +7 -4
  24. package/dist/index.js +4 -2
  25. package/dist/index.js.map +1 -1
  26. package/dist/loop.d.ts +18 -8
  27. package/dist/loop.js +191 -29
  28. package/dist/loop.js.map +1 -1
  29. package/dist/observers.d.ts +31 -0
  30. package/dist/observers.js +98 -0
  31. package/dist/observers.js.map +1 -0
  32. package/dist/result.d.ts +11 -5
  33. package/dist/result.js.map +1 -1
  34. package/dist/run.d.ts +34 -4
  35. package/dist/run.js +84 -7
  36. package/dist/run.js.map +1 -1
  37. package/dist/tools/define.d.ts +3 -2
  38. package/dist/tools/define.js +10 -2
  39. package/dist/tools/define.js.map +1 -1
  40. package/dist/tools/format-error.js +1 -0
  41. package/dist/tools/format-error.js.map +1 -1
  42. package/dist/tools/pipeline.d.ts +40 -7
  43. package/dist/tools/pipeline.js +196 -37
  44. package/dist/tools/pipeline.js.map +1 -1
  45. package/dist/tools/scheduler.d.ts +33 -0
  46. package/dist/tools/scheduler.js +51 -0
  47. package/dist/tools/scheduler.js.map +1 -0
  48. package/dist/tools/types.d.ts +41 -5
  49. package/dist/tools/types.js.map +1 -1
  50. package/package.json +2 -2
package/dist/index.d.ts CHANGED
@@ -1,14 +1,17 @@
1
1
  /**
2
2
  * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the loop (`run()`,
3
- * `continueRun()`, `runOrThrow()`), its events and results, and the tools: their definitions, schemas, results and
4
- * write outcomes. Hooks, signed pauses and budgets are planned in the SDK plan §3.3.
3
+ * `continueRun()`, `runOrThrow()`), its events and results, the tools (their definitions, schemas, results and write
4
+ * outcomes) and the hooks: six interceptors that can change a run and observers that only watch it. Signed pauses and
5
+ * budgets are planned in the SDK plan §3.3.
5
6
  */
7
+ export { composeInterceptors } from "./compose.js";
6
8
  export { isSdkError, RunStoppedError, SdkError, type SdkErrorCode } from "./errors.js";
7
9
  export { AGENT_EVENT_TYPES, type AgentEvent, type AgentEventBody, type EventBase, type ModelCallRequest, type WarningCode, } from "./events.js";
8
- export type { Context, DoneResult, EndedResult, ErrorResult, ResultBase, RunError, RunResult, StoppedResult, UnfinishedResult, } from "./result.js";
10
+ export type { CallOptions, ContextEvent, GateDecision, HookEventBase, Interceptors, MaybePromise, ModelCallEvent, ModelCallPatch, ModelResultEvent, Observer, OrNothing, StepEvent, StopDecision, ToolCallEvent, ToolResultEvent, ToolResultPatch, } from "./hooks.js";
11
+ export type { Context, DoneResult, EndedResult, ErrorResult, NoProgressResult, ResultBase, RunError, RunResult, StoppedResult, UnfinishedResult, } from "./result.js";
9
12
  export { continueRun, type Run, type RunInput, type RunOptions, run, runOrThrow } from "./run.js";
10
13
  export { type ClarificationToolOptions, clarificationTool, defineTool, type OutputToolOptions, outputTool, } from "./tools/define.js";
11
- export type { JsonSchema, SchemaIssue, ToolContext, ToolDefinition, ToolEffect, ToolExposure, ToolFailure, ToolResult, ToolSchema, } from "./tools/types.js";
14
+ export type { JsonSchema, SchemaIssue, ToolAnnotations, ToolContext, ToolDefinition, ToolEffect, ToolExecutionMode, ToolExposure, ToolFailure, ToolResult, ToolSchema, } from "./tools/types.js";
12
15
  export type { WriteOutcome } from "./vendor/agent-safety/outcome.js";
13
16
  /** The package's name, `@buildanagent/sdk`. */
14
17
  export declare const SDK_PACKAGE = "@buildanagent/sdk";
package/dist/index.js CHANGED
@@ -1,8 +1,10 @@
1
1
  /**
2
2
  * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the loop (`run()`,
3
- * `continueRun()`, `runOrThrow()`), its events and results, and the tools: their definitions, schemas, results and
4
- * write outcomes. Hooks, signed pauses and budgets are planned in the SDK plan §3.3.
3
+ * `continueRun()`, `runOrThrow()`), its events and results, the tools (their definitions, schemas, results and write
4
+ * outcomes) and the hooks: six interceptors that can change a run and observers that only watch it. Signed pauses and
5
+ * budgets are planned in the SDK plan §3.3.
5
6
  */
7
+ export { composeInterceptors } from "./compose.js";
6
8
  export { isSdkError, RunStoppedError, SdkError } from "./errors.js";
7
9
  export { AGENT_EVENT_TYPES, } from "./events.js";
8
10
  export { continueRun, run, runOrThrow } from "./run.js";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAqB,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,iBAAiB,GAMlB,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,WAAW,EAA4C,GAAG,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,EAEL,iBAAiB,EACjB,UAAU,EAEV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAc3B,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC","sourcesContent":["/**\n * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the loop (`run()`,\n * `continueRun()`, `runOrThrow()`), its events and results, and the tools: their definitions, schemas, results and\n * write outcomes. Hooks, signed pauses and budgets are planned in the SDK plan §3.3.\n */\nexport { isSdkError, RunStoppedError, SdkError, type SdkErrorCode } from \"./errors.js\";\nexport {\n AGENT_EVENT_TYPES,\n type AgentEvent,\n type AgentEventBody,\n type EventBase,\n type ModelCallRequest,\n type WarningCode,\n} from \"./events.js\";\nexport type {\n Context,\n DoneResult,\n EndedResult,\n ErrorResult,\n ResultBase,\n RunError,\n RunResult,\n StoppedResult,\n UnfinishedResult,\n} from \"./result.js\";\nexport { continueRun, type Run, type RunInput, type RunOptions, run, runOrThrow } from \"./run.js\";\nexport {\n type ClarificationToolOptions,\n clarificationTool,\n defineTool,\n type OutputToolOptions,\n outputTool,\n} from \"./tools/define.js\";\nexport type {\n JsonSchema,\n SchemaIssue,\n ToolContext,\n ToolDefinition,\n ToolEffect,\n ToolExposure,\n ToolFailure,\n ToolResult,\n ToolSchema,\n} from \"./tools/types.js\";\nexport type { WriteOutcome } from \"./vendor/agent-safety/outcome.js\";\n\n/** The package's name, `@buildanagent/sdk`. */\nexport const SDK_PACKAGE = \"@buildanagent/sdk\";\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAqB,MAAM,aAAa,CAAC;AACvF,OAAO,EACL,iBAAiB,GAMlB,MAAM,aAAa,CAAC;AA+BrB,OAAO,EAAE,WAAW,EAA4C,GAAG,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAClG,OAAO,EAEL,iBAAiB,EACjB,UAAU,EAEV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAgB3B,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC","sourcesContent":["/**\n * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the loop (`run()`,\n * `continueRun()`, `runOrThrow()`), its events and results, the tools (their definitions, schemas, results and write\n * outcomes) and the hooks: six interceptors that can change a run and observers that only watch it. Signed pauses and\n * budgets are planned in the SDK plan §3.3.\n */\nexport { composeInterceptors } from \"./compose.js\";\nexport { isSdkError, RunStoppedError, SdkError, type SdkErrorCode } from \"./errors.js\";\nexport {\n AGENT_EVENT_TYPES,\n type AgentEvent,\n type AgentEventBody,\n type EventBase,\n type ModelCallRequest,\n type WarningCode,\n} from \"./events.js\";\nexport type {\n CallOptions,\n ContextEvent,\n GateDecision,\n HookEventBase,\n Interceptors,\n MaybePromise,\n ModelCallEvent,\n ModelCallPatch,\n ModelResultEvent,\n Observer,\n OrNothing,\n StepEvent,\n StopDecision,\n ToolCallEvent,\n ToolResultEvent,\n ToolResultPatch,\n} from \"./hooks.js\";\nexport type {\n Context,\n DoneResult,\n EndedResult,\n ErrorResult,\n NoProgressResult,\n ResultBase,\n RunError,\n RunResult,\n StoppedResult,\n UnfinishedResult,\n} from \"./result.js\";\nexport { continueRun, type Run, type RunInput, type RunOptions, run, runOrThrow } from \"./run.js\";\nexport {\n type ClarificationToolOptions,\n clarificationTool,\n defineTool,\n type OutputToolOptions,\n outputTool,\n} from \"./tools/define.js\";\nexport type {\n JsonSchema,\n SchemaIssue,\n ToolAnnotations,\n ToolContext,\n ToolDefinition,\n ToolEffect,\n ToolExecutionMode,\n ToolExposure,\n ToolFailure,\n ToolResult,\n ToolSchema,\n} from \"./tools/types.js\";\nexport type { WriteOutcome } from \"./vendor/agent-safety/outcome.js\";\n\n/** The package's name, `@buildanagent/sdk`. */\nexport const SDK_PACKAGE = \"@buildanagent/sdk\";\n"]}
package/dist/loop.d.ts CHANGED
@@ -2,13 +2,14 @@
2
2
  * The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds
3
3
  * (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.
4
4
  *
5
- * Each step runs transform → before → stream → after → tools → stop. The transform, before and after moments are
6
- * where the interceptors plug in (D6); until they exist the request is the transcript as it stands and the response
7
- * is kept unchanged. Every outcome is a stop reason, never an exception: only a programmer error, such as a malformed
8
- * tool result, throws.
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
9
  */
10
- import { type Message, type Model, type ModelCallOptions } from "@buildanagent/gateway";
10
+ import { type Message, type Model } from "@buildanagent/gateway";
11
11
  import type { AgentEventBody } from "./events.js";
12
+ import type { CallOptions, Interceptors } from "./hooks.js";
12
13
  import type { RunResult } from "./result.js";
13
14
  import type { Clock } from "./testing/determinism.js";
14
15
  import { type AnyTool } from "./tools/pipeline.js";
@@ -21,18 +22,27 @@ export interface LoopSetup {
21
22
  readonly history: readonly Message[];
22
23
  /** The messages the run starts by adding, such as the user's input. */
23
24
  readonly input: readonly Message[];
24
- /** The tools the model is sent, in definition order; only these can run. */
25
+ /**
26
+ * Every tool the run knows, in definition order. A request sends the ones whose exposure is `direct`, or the ones
27
+ * `activeTools` names, and only the tools a request sent can run.
28
+ */
25
29
  readonly tools: readonly AnyTool[];
26
30
  readonly output: AnyTool | undefined;
27
31
  readonly maxSteps: number;
28
- readonly modelOptions: Omit<ModelCallOptions, "signal">;
32
+ readonly modelOptions: CallOptions;
33
+ readonly interceptors: Interceptors;
29
34
  readonly signal: AbortSignal;
30
35
  readonly clock: Clock;
31
36
  }
32
37
  /** Sends one event; the run adds the `EventBase` fields. */
33
38
  export type Emit = (body: AgentEventBody, stepIndex: number) => void;
39
+ /**
40
+ * Resolves once every observer has handled the events sent so far. The loop calls it only once it has its outcome,
41
+ * and the run treats the first call as the point after which an abort no longer counts.
42
+ */
43
+ export type Drain = () => Promise<void>;
34
44
  /**
35
45
  * Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results
36
46
  * already received are in the transcript.
37
47
  */
38
- export declare function runLoop(setup: LoopSetup, emit: Emit): Promise<RunResult>;
48
+ export declare function runLoop(setup: LoopSetup, emit: Emit, drain: Drain): Promise<RunResult>;
package/dist/loop.js CHANGED
@@ -2,13 +2,14 @@
2
2
  * The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds
3
3
  * (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.
4
4
  *
5
- * Each step runs transform → before → stream → after → tools → stop. The transform, before and after moments are
6
- * where the interceptors plug in (D6); until they exist the request is the transcript as it stands and the response
7
- * is kept unchanged. Every outcome is a stop reason, never an exception: only a programmer error, such as a malformed
8
- * tool result, throws.
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
9
  */
10
10
  import { addCost, addUsage, emptyUsage, } from "@buildanagent/gateway";
11
- import { SdkError } from "./errors.js";
11
+ import { isSdkError, SdkError } from "./errors.js";
12
+ import { HookFailure, HookRunner } from "./hook-runner.js";
12
13
  import { toWireTool } from "./tools/define.js";
13
14
  import { runToolCalls } from "./tools/pipeline.js";
14
15
  /** The `stoppedBy` of a run that a clarification tool stopped. */
@@ -27,18 +28,37 @@ class LoopState {
27
28
  emit;
28
29
  messages;
29
30
  added;
30
- wireTools;
31
+ drain;
32
+ hooks;
33
+ #wire;
34
+ /** The tools the latest request sent; the tool calls of its response may run only these. */
35
+ active = [];
31
36
  steps = 0;
32
37
  stepIndex = 0;
33
38
  usage = emptyUsage();
39
+ lastUsage;
34
40
  cost;
35
41
  output;
36
- constructor(setup, emit) {
42
+ constructor(setup, emit, drain) {
37
43
  this.setup = setup;
38
44
  this.emit = emit;
45
+ this.drain = drain;
39
46
  this.messages = [...setup.history, ...setup.input];
40
47
  this.added = [...setup.input];
41
- this.wireTools = setup.tools.map(toWireTool);
48
+ this.#wire = new Map(setup.tools.map((tool) => [tool, toWireTool(tool)]));
49
+ this.hooks = new HookRunner({
50
+ interceptors: setup.interceptors,
51
+ runId: setup.runId,
52
+ signal: setup.signal,
53
+ clock: setup.clock,
54
+ stepIndex: () => this.stepIndex,
55
+ send: (body) => this.send(body),
56
+ });
57
+ }
58
+ /** The wire form of each of `tools`, as a request sends them. */
59
+ wireOf(tools) {
60
+ // Every tool of the run was lowered in the constructor, and a request names only the run's tools.
61
+ return tools.map((tool) => this.#wire.get(tool));
42
62
  }
43
63
  send(body) {
44
64
  this.emit(body, this.stepIndex);
@@ -85,26 +105,111 @@ function forward(state, event) {
85
105
  return undefined;
86
106
  }
87
107
  }
88
- /** Makes one model call, streams its events and records the response. */
89
- async function callModel(state) {
90
- const { model, system, modelOptions, signal } = state.setup;
91
- const context = { system, messages: [...state.messages], tools: state.wireTools };
92
- state.send({
93
- type: "model_call_start",
94
- request: { model: model.ref, context, options: dumpedOptions(modelOptions) },
108
+ /** The tools a request sends unless `beforeModelCall` names others: the ones whose exposure is `direct`. */
109
+ function directTools(tools) {
110
+ return tools.filter((tool) => (tool.exposure ?? "direct") === "direct");
111
+ }
112
+ /** The tools `names` picks, in definition order whatever order `names` is in. */
113
+ function toolsNamed(tools, names) {
114
+ const unknown = names.filter((name) => !tools.some((tool) => tool.name === name));
115
+ if (unknown.length > 0) {
116
+ throw new SdkError("invalid_hook_result", `activeTools names unknown tools: ${unknown.join(", ")}`);
117
+ }
118
+ return tools.filter((tool) => names.includes(tool.name));
119
+ }
120
+ function patched(state, request, patch) {
121
+ const active = patch.activeTools === undefined ? request.active : toolsNamed(state.setup.tools, patch.activeTools);
122
+ const { system, messages } = request.context;
123
+ return {
124
+ model: patch.model ?? request.model,
125
+ options: patch.options ?? request.options,
126
+ active,
127
+ context: {
128
+ system: patch.system ?? system,
129
+ messages: patch.messages === undefined ? messages : [...patch.messages],
130
+ tools: state.wireOf(active),
131
+ },
132
+ };
133
+ }
134
+ /**
135
+ * Builds one call's request: the transcript, or the view `transformContext` returns for this call alone, then the
136
+ * changes `beforeModelCall` asks for. The run's own transcript is never replaced by either.
137
+ */
138
+ async function buildRequest(state) {
139
+ const { model, system, modelOptions, tools } = state.setup;
140
+ const view = await state.hooks.transformContext({
141
+ system,
142
+ messages: state.messages,
143
+ model: model.ref,
144
+ lastUsage: state.lastUsage,
95
145
  });
146
+ const active = directTools(tools);
147
+ const context = { system, messages: [...(view ?? state.messages)], tools: state.wireOf(active) };
148
+ const request = { model, context, options: modelOptions, active };
149
+ const patch = await state.hooks.beforeModelCall({ context, options: modelOptions });
150
+ return patch === undefined ? request : patched(state, request, patch);
151
+ }
152
+ /** Streams one request, re-emitting its events, and returns the model's final message. */
153
+ async function streamRequest(state, request) {
154
+ const { model, context, options } = request;
155
+ state.send({ type: "model_call_start", request: { model: model.ref, context, options: dumpedOptions(options) } });
96
156
  let message;
97
- for await (const event of model.stream(context, { ...modelOptions, signal })) {
157
+ for await (const event of model.stream(context, { ...options, signal: state.setup.signal })) {
98
158
  message = forward(state, event) ?? message;
99
159
  }
100
160
  if (message === undefined) {
101
161
  throw new SdkError("invalid_model_stream", "the model's stream ended without a done or error event");
102
162
  }
103
- state.steps += 1;
104
- state.usage = addUsage(state.usage, message.usage);
105
- state.cost = state.cost === undefined ? message.cost : addCost(state.cost, message.cost);
163
+ return message;
164
+ }
165
+ /** Adds a model call's response to the transcript and reports it. */
166
+ function record(state, message) {
106
167
  state.append(message);
107
168
  state.send({ type: "model_call_end", message });
169
+ }
170
+ /**
171
+ * What the transcript holds for a response whose `afterModelCall` failed while the run fails closed: no content, so a
172
+ * check that crashed can't let the response through, but the call's usage and cost, which were billed. Its error stop
173
+ * reason makes the replay pass skip it if the run is continued.
174
+ */
175
+ function withheld(original) {
176
+ const { model, usage, cost, lastAttemptUsage } = original;
177
+ return {
178
+ role: "assistant",
179
+ content: [],
180
+ model,
181
+ stopReason: "error",
182
+ error: { kind: "fatal", message: "the response was withheld, because its afterModelCall check failed" },
183
+ usage,
184
+ ...(lastAttemptUsage === undefined ? {} : { lastAttemptUsage }),
185
+ cost,
186
+ };
187
+ }
188
+ /**
189
+ * Makes one model call, streams its events and records the response. The call's usage and cost are the model's own
190
+ * message's, so an `afterModelCall` replacement changes what the run goes on with, never what it is billed. When
191
+ * `afterModelCall` fails and the run fails closed, a withheld stand-in is recorded before the run ends, so the
192
+ * transcript and `model_call_end` still account for the billed call and none of its tool calls run.
193
+ */
194
+ async function callModel(state) {
195
+ const request = await buildRequest(state);
196
+ state.active = request.active;
197
+ const original = await streamRequest(state, request);
198
+ state.steps += 1;
199
+ state.usage = addUsage(state.usage, original.usage);
200
+ state.lastUsage = original.usage;
201
+ state.cost = state.cost === undefined ? original.cost : addCost(state.cost, original.cost);
202
+ let message;
203
+ try {
204
+ message = await state.hooks.afterModelCall(original);
205
+ }
206
+ catch (error) {
207
+ if (error instanceof HookFailure || (isSdkError(error) && error.code === "invalid_hook_result")) {
208
+ record(state, withheld(original));
209
+ }
210
+ throw error;
211
+ }
212
+ record(state, message);
108
213
  return message;
109
214
  }
110
215
  /** The tool message the model reads for one call. */
@@ -116,15 +221,16 @@ function toolMessage(entry) {
116
221
  isError: entry.result.isError === true,
117
222
  };
118
223
  }
119
- /** Runs the response's tool calls one at a time, recording each result as soon as it arrives. */
224
+ /** Runs the response's tool calls as the pipeline schedules them, recording each result in model order. */
120
225
  async function runTools(state, message) {
121
- const { runId, signal, clock, tools, output } = state.setup;
122
- return runToolCalls(message, tools, {
226
+ const { runId, signal, clock, output } = state.setup;
227
+ return runToolCalls(message, state.active, {
123
228
  runId,
124
229
  signal,
125
230
  clock,
126
231
  depth: TOP_LEVEL_DEPTH,
127
232
  maxDepth: DEFAULT_MAX_DEPTH,
233
+ ...state.hooks.pipelineHooks(),
128
234
  onStart: (call) => state.send({ type: "tool_call_start", callId: call.callId, tool: call.name, input: call.input }),
129
235
  onUpdate: (callId, details) => state.send({ type: "tool_call_update", callId, details }),
130
236
  onResult: (entry) => {
@@ -132,7 +238,8 @@ async function runTools(state, message) {
132
238
  if (output !== undefined && entry.call.name === output.name && entry.result.isError !== true) {
133
239
  state.output = entry.result.structured;
134
240
  }
135
- state.send({ type: "tool_call_end", callId: entry.call.callId, result: entry.result });
241
+ const ranWith = "input" in entry ? { input: entry.input } : {};
242
+ state.send({ type: "tool_call_end", callId: entry.call.callId, result: entry.result, ...ranWith });
136
243
  },
137
244
  });
138
245
  }
@@ -167,12 +274,59 @@ function stopCheck(state, message, results) {
167
274
  return { stopReason: "max_steps" };
168
275
  return undefined;
169
276
  }
277
+ /**
278
+ * What `shouldStop` changes about the stop check. A finished answer or an error stands whatever the hook says; the
279
+ * hook can end a run that would go on, and can keep going a run the model ended by answering in text, until the
280
+ * step cap.
281
+ */
282
+ function withVerdict(state, natural, verdict) {
283
+ if (natural !== undefined && verdict.kind !== "continue")
284
+ return natural;
285
+ switch (verdict.kind) {
286
+ case "stop":
287
+ return { stopReason: "stopped", stoppedBy: verdict.stoppedBy };
288
+ case "no_progress":
289
+ return { stopReason: "no_progress", reason: verdict.reason };
290
+ case "continue":
291
+ if (natural === undefined)
292
+ return undefined;
293
+ if (state.steps >= state.setup.maxSteps)
294
+ return { stopReason: "max_steps" };
295
+ state.append({ role: "user", content: verdict.content });
296
+ return undefined;
297
+ default:
298
+ return natural;
299
+ }
300
+ }
301
+ /** The stop check after one step, then the `shouldStop` hook where it may change it. */
302
+ async function decide(state, message, results) {
303
+ const natural = stopCheck(state, message, results);
304
+ const endedByAnswer = natural?.stopReason === "done" && results.length === 0;
305
+ if (natural !== undefined && !endedByAnswer)
306
+ return natural;
307
+ const verdict = await state.hooks.shouldStop({ messages: state.messages, lastMessage: message });
308
+ return withVerdict(state, natural, verdict);
309
+ }
310
+ /** The outcome of a hook that failed while the run fails closed. A failure caused by an abort ends the run aborted. */
311
+ function failedOutcome(state, error) {
312
+ if (!(error instanceof HookFailure))
313
+ throw error;
314
+ if (state.setup.signal.aborted)
315
+ return { stopReason: "aborted" };
316
+ return { stopReason: "error", error: { kind: "hook", message: error.message } };
317
+ }
170
318
  async function runStep(state) {
171
319
  state.stepIndex = state.steps;
172
320
  state.send({ type: "step_start" });
173
- const message = await callModel(state);
174
- const results = await runTools(state, message);
175
- const outcome = stopCheck(state, message, results);
321
+ let outcome;
322
+ try {
323
+ const message = await callModel(state);
324
+ const results = await runTools(state, message);
325
+ outcome = await decide(state, message, results);
326
+ }
327
+ catch (error) {
328
+ outcome = failedOutcome(state, error);
329
+ }
176
330
  state.send({ type: "step_end", stopCheck: outcome === undefined ? "continue" : "stop" });
177
331
  return outcome;
178
332
  }
@@ -204,7 +358,12 @@ function resultOf(state, outcome) {
204
358
  };
205
359
  return { ...base, ...outcome };
206
360
  }
207
- function finish(state, outcome) {
361
+ /**
362
+ * Ends the run: the settle event comes once every observer has seen what came before it, and `run_end` after that.
363
+ * An observer's failure while handling `agent_settled` is reported between the two; one while handling `run_end` is
364
+ * dropped, so `run_end` stays the last event. The result is returned only once observers have seen it.
365
+ */
366
+ async function finish(state, outcome) {
208
367
  if (outcome.stopReason === "aborted")
209
368
  closeAborted(state);
210
369
  if (outcome.stopReason === "max_steps") {
@@ -212,17 +371,20 @@ function finish(state, outcome) {
212
371
  }
213
372
  if (outcome.stopReason === "error")
214
373
  state.send({ type: "error", error: outcome.error });
374
+ await state.drain();
215
375
  state.send({ type: "agent_settled" });
376
+ await state.drain();
216
377
  const result = resultOf(state, outcome);
217
378
  state.send({ type: "run_end", result });
379
+ await state.drain();
218
380
  return result;
219
381
  }
220
382
  /**
221
383
  * Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results
222
384
  * already received are in the transcript.
223
385
  */
224
- export async function runLoop(setup, emit) {
225
- const state = new LoopState(setup, emit);
386
+ export async function runLoop(setup, emit, drain) {
387
+ const state = new LoopState(setup, emit, drain);
226
388
  let outcome;
227
389
  while (outcome === undefined) {
228
390
  outcome = setup.signal.aborted ? { stopReason: "aborted" } : await runStep(state);
package/dist/loop.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds\n * (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.\n *\n * Each step runs transform → before → stream → after → tools → stop. The transform, before and after moments are\n * where the interceptors plug in (D6); until they exist the request is the transcript as it stands and the response\n * is kept unchanged. Every outcome is a stop reason, never an exception: only a programmer error, such as a malformed\n * tool result, throws.\n */\nimport {\n type AssistantMessage,\n addCost,\n addUsage,\n type Cost,\n type DumpedOptions,\n emptyUsage,\n type GatewayEvent,\n type Message,\n type Model,\n type ModelCallOptions,\n type ModelContext,\n type StreamOptions,\n type Usage,\n type WireTool,\n} from \"@buildanagent/gateway\";\nimport { SdkError } from \"./errors.js\";\nimport type { AgentEventBody } from \"./events.js\";\nimport type { RunError, RunResult } from \"./result.js\";\nimport type { Clock } from \"./testing/determinism.js\";\nimport { toWireTool } from \"./tools/define.js\";\nimport { type AnyTool, runToolCalls, type ToolCallResult } from \"./tools/pipeline.js\";\nimport type { ToolCall } from \"./tools/types.js\";\n\n/** The `stoppedBy` of a run that a clarification tool stopped. */\nconst CLARIFICATION = \"clarification\";\n\n// The depth cap's defaults (D11). Nested runs pass their own depth once the depth cap is configurable.\nconst TOP_LEVEL_DEPTH = 0;\nconst DEFAULT_MAX_DEPTH = 2;\n\n/**\n * The cost of no model call: an exact zero. Its basis is `provider` because `addCost()` keeps the other cost's basis\n * when it adds a provider cost, so the zero never turns a billed sum into an estimate.\n */\nconst NO_COST: Cost = { total: 0, basis: \"provider\", currency: \"USD\" };\n\n/** Everything one run needs, fixed when it starts. */\nexport interface LoopSetup {\n readonly runId: string;\n readonly model: Model;\n readonly system: string;\n /** The conversation before this run's own messages. */\n readonly history: readonly Message[];\n /** The messages the run starts by adding, such as the user's input. */\n readonly input: readonly Message[];\n /** The tools the model is sent, in definition order; only these can run. */\n readonly tools: readonly AnyTool[];\n readonly output: AnyTool | undefined;\n readonly maxSteps: number;\n readonly modelOptions: Omit<ModelCallOptions, \"signal\">;\n readonly signal: AbortSignal;\n readonly clock: Clock;\n}\n\n/** Sends one event; the run adds the `EventBase` fields. */\nexport type Emit = (body: AgentEventBody, stepIndex: number) => void;\n\n/** How a run ended, before its usage, cost and messages are attached. */\ntype Outcome =\n | { readonly stopReason: \"done\"; readonly output: unknown }\n | { readonly stopReason: \"max_steps\" | \"aborted\" }\n | { readonly stopReason: \"error\"; readonly error: RunError }\n | { readonly stopReason: \"stopped\"; readonly stoppedBy: string };\n\n/** What changes while a run goes on. */\nclass LoopState {\n readonly setup: LoopSetup;\n readonly emit: Emit;\n readonly messages: Message[];\n readonly added: Message[];\n readonly wireTools: WireTool[];\n steps = 0;\n stepIndex = 0;\n usage: Usage = emptyUsage();\n cost: Cost | undefined;\n output: unknown;\n\n constructor(setup: LoopSetup, emit: Emit) {\n this.setup = setup;\n this.emit = emit;\n this.messages = [...setup.history, ...setup.input];\n this.added = [...setup.input];\n this.wireTools = setup.tools.map(toWireTool);\n }\n\n send(body: AgentEventBody): void {\n this.emit(body, this.stepIndex);\n }\n\n append(message: Message): void {\n this.messages.push(message);\n this.added.push(message);\n }\n}\n\n/**\n * The stream options a request event records: everything but the payload hook, the abort signal and the caps, as the\n * gateway's own request dump leaves them out. An untyped caller may still pass a signal or caps in `modelOptions`.\n */\nfunction dumpedOptions(options: Omit<ModelCallOptions, \"signal\">): DumpedOptions {\n const { onPayload: _onPayload, signal: _signal, caps: _caps, ...rest } = options as StreamOptions;\n return rest;\n}\n\n/** Re-emits one model event as a run event, and returns the final message once the terminal event arrives. */\nfunction forward(state: LoopState, event: GatewayEvent): AssistantMessage | undefined {\n switch (event.type) {\n case \"done\":\n case \"error\":\n return event.message;\n case \"start\":\n return undefined;\n case \"retry\":\n state.send({ type: \"retry\", attempt: event.attempt, delayMs: event.delayMs, error: event.error });\n return undefined;\n case \"warning\":\n state.send({ type: \"warning\", code: \"model_warning\", detail: `${event.code}: ${event.message}` });\n return undefined;\n case \"text_start\":\n case \"reasoning_start\":\n case \"tool_input_start\":\n state.send({ type: event.type, index: event.index });\n return undefined;\n case \"text_delta\":\n case \"reasoning_delta\":\n case \"tool_input_delta\":\n state.send({ type: event.type, index: event.index, delta: event.delta });\n return undefined;\n default:\n state.send({ type: event.type, index: event.index, block: event.block });\n return undefined;\n }\n}\n\n/** Makes one model call, streams its events and records the response. */\nasync function callModel(state: LoopState): Promise<AssistantMessage> {\n const { model, system, modelOptions, signal } = state.setup;\n const context: ModelContext = { system, messages: [...state.messages], tools: state.wireTools };\n state.send({\n type: \"model_call_start\",\n request: { model: model.ref, context, options: dumpedOptions(modelOptions) },\n });\n let message: AssistantMessage | undefined;\n for await (const event of model.stream(context, { ...modelOptions, signal })) {\n message = forward(state, event) ?? message;\n }\n if (message === undefined) {\n throw new SdkError(\"invalid_model_stream\", \"the model's stream ended without a done or error event\");\n }\n state.steps += 1;\n state.usage = addUsage(state.usage, message.usage);\n state.cost = state.cost === undefined ? message.cost : addCost(state.cost, message.cost);\n state.append(message);\n state.send({ type: \"model_call_end\", message });\n return message;\n}\n\n/** The tool message the model reads for one call. */\nfunction toolMessage(entry: ToolCallResult): Message {\n return {\n role: \"tool\",\n callId: entry.call.callId,\n content: [...entry.result.content],\n isError: entry.result.isError === true,\n };\n}\n\n/** Runs the response's tool calls one at a time, recording each result as soon as it arrives. */\nasync function runTools(state: LoopState, message: AssistantMessage): Promise<readonly ToolCallResult[]> {\n const { runId, signal, clock, tools, output } = state.setup;\n return runToolCalls(message, tools, {\n runId,\n signal,\n clock,\n depth: TOP_LEVEL_DEPTH,\n maxDepth: DEFAULT_MAX_DEPTH,\n onStart: (call: ToolCall) =>\n state.send({ type: \"tool_call_start\", callId: call.callId, tool: call.name, input: call.input }),\n onUpdate: (callId, details) => state.send({ type: \"tool_call_update\", callId, details }),\n onResult: (entry) => {\n state.append(toolMessage(entry));\n if (output !== undefined && entry.call.name === output.name && entry.result.isError !== true) {\n state.output = entry.result.structured;\n }\n state.send({ type: \"tool_call_end\", callId: entry.call.callId, result: entry.result });\n },\n });\n}\n\n/** The failed call's error as the run reports it. A message without one counts as `fatal`. */\nfunction runErrorOf(message: AssistantMessage): RunError {\n const error = message.error;\n if (error === undefined) return { kind: \"fatal\", message: \"the model call failed without an error description\" };\n return { kind: error.kind, message: error.message, ...(error.status === undefined ? {} : { status: error.status }) };\n}\n\n/**\n * The stop check after one step. A finished answer, or a question for the user, wins over an abort that came too late\n * to change it; otherwise an abort stops the run before the step cap does. A text answer cut off at the output limit\n * also counts as finished: its message keeps `stopReason: \"length\"`.\n */\nfunction stopCheck(\n state: LoopState,\n message: AssistantMessage,\n results: readonly ToolCallResult[],\n): Outcome | undefined {\n if (message.stopReason === \"error\") return { stopReason: \"error\", error: runErrorOf(message) };\n if (message.stopReason === \"aborted\") return { stopReason: \"aborted\" };\n const finished = results.length === 0 || results.some(({ result }) => result.terminate === true && !result.isError);\n if (finished) return { stopReason: \"done\", output: state.output };\n // Until runs can pause for an answer, a clarification question stops the run, so the model never goes on as if the\n // user had been asked and answered.\n if (results.some(({ result }) => result.pause !== undefined && !result.isError)) {\n return { stopReason: \"stopped\", stoppedBy: CLARIFICATION };\n }\n if (state.setup.signal.aborted) return { stopReason: \"aborted\" };\n if (state.steps >= state.setup.maxSteps) return { stopReason: \"max_steps\" };\n return undefined;\n}\n\nasync function runStep(state: LoopState): Promise<Outcome | undefined> {\n state.stepIndex = state.steps;\n state.send({ type: \"step_start\" });\n const message = await callModel(state);\n const results = await runTools(state, message);\n const outcome = stopCheck(state, message, results);\n state.send({ type: \"step_end\", stopCheck: outcome === undefined ? \"continue\" : \"stop\" });\n return outcome;\n}\n\n/**\n * An aborted run's transcript ends with an assistant message whose `stopReason` is `\"aborted\"`. When tool results end\n * the transcript, because the abort came while tools ran or cut off a response that held tool calls, the loop\n * appends an empty one after them; the replay pass drops it before any request.\n */\nfunction closeAborted(state: LoopState): void {\n const last = state.messages.at(-1);\n if (last?.role === \"assistant\" && last.stopReason === \"aborted\") return;\n state.append({\n role: \"assistant\",\n content: [],\n model: state.setup.model.ref,\n stopReason: \"aborted\",\n usage: emptyUsage(),\n cost: { ...NO_COST },\n });\n}\n\nfunction resultOf(state: LoopState, outcome: Outcome): RunResult {\n const base = {\n messages: state.added,\n context: { system: state.setup.system, messages: state.messages },\n usage: state.usage,\n cost: state.cost ?? { ...NO_COST },\n steps: state.steps,\n };\n return { ...base, ...outcome } as RunResult;\n}\n\nfunction finish(state: LoopState, outcome: Outcome): RunResult {\n if (outcome.stopReason === \"aborted\") closeAborted(state);\n if (outcome.stopReason === \"max_steps\") {\n state.send({ type: \"warning\", code: \"max_steps\", detail: `the run reached maxSteps (${state.setup.maxSteps})` });\n }\n if (outcome.stopReason === \"error\") state.send({ type: \"error\", error: outcome.error });\n state.send({ type: \"agent_settled\" });\n const result = resultOf(state, outcome);\n state.send({ type: \"run_end\", result });\n return result;\n}\n\n/**\n * Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results\n * already received are in the transcript.\n */\nexport async function runLoop(setup: LoopSetup, emit: Emit): Promise<RunResult> {\n const state = new LoopState(setup, emit);\n let outcome: Outcome | undefined;\n while (outcome === undefined) {\n outcome = setup.signal.aborted ? { stopReason: \"aborted\" } : await runStep(state);\n }\n return finish(state, outcome);\n}\n"]}
1
+ {"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds\n * (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.\n *\n * Each step runs transform → before → stream → after → tools → stop. Those moments are where the interceptors\n * plug in (D6); a run without interceptors sends the transcript as it stands and keeps each response unchanged.\n * Every outcome is a stop reason, never an exception: only a programmer error, such as a malformed tool result,\n * throws.\n */\nimport {\n type AssistantMessage,\n addCost,\n addUsage,\n type Cost,\n type DumpedOptions,\n emptyUsage,\n type GatewayEvent,\n type Message,\n type Model,\n type ModelContext,\n type StreamOptions,\n type Usage,\n type WireTool,\n} from \"@buildanagent/gateway\";\nimport { isSdkError, SdkError } from \"./errors.js\";\nimport type { AgentEventBody } from \"./events.js\";\nimport type { StopVerdict } from \"./hook-checks.js\";\nimport { HookFailure, HookRunner } from \"./hook-runner.js\";\nimport type { CallOptions, Interceptors, ModelCallPatch } from \"./hooks.js\";\nimport type { RunError, RunResult } from \"./result.js\";\nimport type { Clock } from \"./testing/determinism.js\";\nimport { toWireTool } from \"./tools/define.js\";\nimport { type AnyTool, runToolCalls, type ToolCallResult } from \"./tools/pipeline.js\";\nimport type { ToolCall } from \"./tools/types.js\";\n\n/** The `stoppedBy` of a run that a clarification tool stopped. */\nconst CLARIFICATION = \"clarification\";\n\n// The depth cap's defaults (D11). Nested runs pass their own depth once the depth cap is configurable.\nconst TOP_LEVEL_DEPTH = 0;\nconst DEFAULT_MAX_DEPTH = 2;\n\n/**\n * The cost of no model call: an exact zero. Its basis is `provider` because `addCost()` keeps the other cost's basis\n * when it adds a provider cost, so the zero never turns a billed sum into an estimate.\n */\nconst NO_COST: Cost = { total: 0, basis: \"provider\", currency: \"USD\" };\n\n/** Everything one run needs, fixed when it starts. */\nexport interface LoopSetup {\n readonly runId: string;\n readonly model: Model;\n readonly system: string;\n /** The conversation before this run's own messages. */\n readonly history: readonly Message[];\n /** The messages the run starts by adding, such as the user's input. */\n readonly input: readonly Message[];\n /**\n * Every tool the run knows, in definition order. A request sends the ones whose exposure is `direct`, or the ones\n * `activeTools` names, and only the tools a request sent can run.\n */\n readonly tools: readonly AnyTool[];\n readonly output: AnyTool | undefined;\n readonly maxSteps: number;\n readonly modelOptions: CallOptions;\n readonly interceptors: Interceptors;\n readonly signal: AbortSignal;\n readonly clock: Clock;\n}\n\n/** Sends one event; the run adds the `EventBase` fields. */\nexport type Emit = (body: AgentEventBody, stepIndex: number) => void;\n\n/**\n * Resolves once every observer has handled the events sent so far. The loop calls it only once it has its outcome,\n * and the run treats the first call as the point after which an abort no longer counts.\n */\nexport type Drain = () => Promise<void>;\n\n/** How a run ended, before its usage, cost and messages are attached. */\ntype Outcome =\n | { readonly stopReason: \"done\"; readonly output: unknown }\n | { readonly stopReason: \"max_steps\" | \"aborted\" }\n | { readonly stopReason: \"error\"; readonly error: RunError }\n | { readonly stopReason: \"stopped\"; readonly stoppedBy: string }\n | { readonly stopReason: \"no_progress\"; readonly reason: string };\n\n/** What changes while a run goes on. */\nclass LoopState {\n readonly setup: LoopSetup;\n readonly emit: Emit;\n readonly messages: Message[];\n readonly added: Message[];\n readonly drain: Drain;\n readonly hooks: HookRunner;\n readonly #wire: ReadonlyMap<AnyTool, WireTool>;\n /** The tools the latest request sent; the tool calls of its response may run only these. */\n active: readonly AnyTool[] = [];\n steps = 0;\n stepIndex = 0;\n usage: Usage = emptyUsage();\n lastUsage: Usage | undefined;\n cost: Cost | undefined;\n output: unknown;\n\n constructor(setup: LoopSetup, emit: Emit, drain: Drain) {\n this.setup = setup;\n this.emit = emit;\n this.drain = drain;\n this.messages = [...setup.history, ...setup.input];\n this.added = [...setup.input];\n this.#wire = new Map(setup.tools.map((tool) => [tool, toWireTool(tool)]));\n this.hooks = new HookRunner({\n interceptors: setup.interceptors,\n runId: setup.runId,\n signal: setup.signal,\n clock: setup.clock,\n stepIndex: () => this.stepIndex,\n send: (body) => this.send(body),\n });\n }\n\n /** The wire form of each of `tools`, as a request sends them. */\n wireOf(tools: readonly AnyTool[]): WireTool[] {\n // Every tool of the run was lowered in the constructor, and a request names only the run's tools.\n return tools.map((tool) => this.#wire.get(tool) as WireTool);\n }\n\n send(body: AgentEventBody): void {\n this.emit(body, this.stepIndex);\n }\n\n append(message: Message): void {\n this.messages.push(message);\n this.added.push(message);\n }\n}\n\n/**\n * The stream options a request event records: everything but the payload hook, the abort signal and the caps, as the\n * gateway's own request dump leaves them out. An untyped caller may still pass a signal or caps in `modelOptions`.\n */\nfunction dumpedOptions(options: CallOptions): DumpedOptions {\n const { onPayload: _onPayload, signal: _signal, caps: _caps, ...rest } = options as StreamOptions;\n return rest;\n}\n\n/** Re-emits one model event as a run event, and returns the final message once the terminal event arrives. */\nfunction forward(state: LoopState, event: GatewayEvent): AssistantMessage | undefined {\n switch (event.type) {\n case \"done\":\n case \"error\":\n return event.message;\n case \"start\":\n return undefined;\n case \"retry\":\n state.send({ type: \"retry\", attempt: event.attempt, delayMs: event.delayMs, error: event.error });\n return undefined;\n case \"warning\":\n state.send({ type: \"warning\", code: \"model_warning\", detail: `${event.code}: ${event.message}` });\n return undefined;\n case \"text_start\":\n case \"reasoning_start\":\n case \"tool_input_start\":\n state.send({ type: event.type, index: event.index });\n return undefined;\n case \"text_delta\":\n case \"reasoning_delta\":\n case \"tool_input_delta\":\n state.send({ type: event.type, index: event.index, delta: event.delta });\n return undefined;\n default:\n state.send({ type: event.type, index: event.index, block: event.block });\n return undefined;\n }\n}\n\n/** One model call as it will be sent, after `transformContext` and `beforeModelCall`. */\ninterface Request {\n readonly model: Model;\n readonly context: ModelContext;\n readonly options: CallOptions;\n readonly active: readonly AnyTool[];\n}\n\n/** The tools a request sends unless `beforeModelCall` names others: the ones whose exposure is `direct`. */\nfunction directTools(tools: readonly AnyTool[]): AnyTool[] {\n return tools.filter((tool) => (tool.exposure ?? \"direct\") === \"direct\");\n}\n\n/** The tools `names` picks, in definition order whatever order `names` is in. */\nfunction toolsNamed(tools: readonly AnyTool[], names: readonly string[]): AnyTool[] {\n const unknown = names.filter((name) => !tools.some((tool) => tool.name === name));\n if (unknown.length > 0) {\n throw new SdkError(\"invalid_hook_result\", `activeTools names unknown tools: ${unknown.join(\", \")}`);\n }\n return tools.filter((tool) => names.includes(tool.name));\n}\n\nfunction patched(state: LoopState, request: Request, patch: ModelCallPatch): Request {\n const active = patch.activeTools === undefined ? request.active : toolsNamed(state.setup.tools, patch.activeTools);\n const { system, messages } = request.context;\n return {\n model: patch.model ?? request.model,\n options: patch.options ?? request.options,\n active,\n context: {\n system: patch.system ?? system,\n messages: patch.messages === undefined ? messages : [...patch.messages],\n tools: state.wireOf(active),\n },\n };\n}\n\n/**\n * Builds one call's request: the transcript, or the view `transformContext` returns for this call alone, then the\n * changes `beforeModelCall` asks for. The run's own transcript is never replaced by either.\n */\nasync function buildRequest(state: LoopState): Promise<Request> {\n const { model, system, modelOptions, tools } = state.setup;\n const view = await state.hooks.transformContext({\n system,\n messages: state.messages,\n model: model.ref,\n lastUsage: state.lastUsage,\n });\n const active = directTools(tools);\n const context = { system, messages: [...(view ?? state.messages)], tools: state.wireOf(active) };\n const request: Request = { model, context, options: modelOptions, active };\n const patch = await state.hooks.beforeModelCall({ context, options: modelOptions });\n return patch === undefined ? request : patched(state, request, patch);\n}\n\n/** Streams one request, re-emitting its events, and returns the model's final message. */\nasync function streamRequest(state: LoopState, request: Request): Promise<AssistantMessage> {\n const { model, context, options } = request;\n state.send({ type: \"model_call_start\", request: { model: model.ref, context, options: dumpedOptions(options) } });\n let message: AssistantMessage | undefined;\n for await (const event of model.stream(context, { ...options, signal: state.setup.signal })) {\n message = forward(state, event) ?? message;\n }\n if (message === undefined) {\n throw new SdkError(\"invalid_model_stream\", \"the model's stream ended without a done or error event\");\n }\n return message;\n}\n\n/** Adds a model call's response to the transcript and reports it. */\nfunction record(state: LoopState, message: AssistantMessage): void {\n state.append(message);\n state.send({ type: \"model_call_end\", message });\n}\n\n/**\n * What the transcript holds for a response whose `afterModelCall` failed while the run fails closed: no content, so a\n * check that crashed can't let the response through, but the call's usage and cost, which were billed. Its error stop\n * reason makes the replay pass skip it if the run is continued.\n */\nfunction withheld(original: AssistantMessage): AssistantMessage {\n const { model, usage, cost, lastAttemptUsage } = original;\n return {\n role: \"assistant\",\n content: [],\n model,\n stopReason: \"error\",\n error: { kind: \"fatal\", message: \"the response was withheld, because its afterModelCall check failed\" },\n usage,\n ...(lastAttemptUsage === undefined ? {} : { lastAttemptUsage }),\n cost,\n };\n}\n\n/**\n * Makes one model call, streams its events and records the response. The call's usage and cost are the model's own\n * message's, so an `afterModelCall` replacement changes what the run goes on with, never what it is billed. When\n * `afterModelCall` fails and the run fails closed, a withheld stand-in is recorded before the run ends, so the\n * transcript and `model_call_end` still account for the billed call and none of its tool calls run.\n */\nasync function callModel(state: LoopState): Promise<AssistantMessage> {\n const request = await buildRequest(state);\n state.active = request.active;\n const original = await streamRequest(state, request);\n state.steps += 1;\n state.usage = addUsage(state.usage, original.usage);\n state.lastUsage = original.usage;\n state.cost = state.cost === undefined ? original.cost : addCost(state.cost, original.cost);\n let message: AssistantMessage;\n try {\n message = await state.hooks.afterModelCall(original);\n } catch (error) {\n if (error instanceof HookFailure || (isSdkError(error) && error.code === \"invalid_hook_result\")) {\n record(state, withheld(original));\n }\n throw error;\n }\n record(state, message);\n return message;\n}\n\n/** The tool message the model reads for one call. */\nfunction toolMessage(entry: ToolCallResult): Message {\n return {\n role: \"tool\",\n callId: entry.call.callId,\n content: [...entry.result.content],\n isError: entry.result.isError === true,\n };\n}\n\n/** Runs the response's tool calls as the pipeline schedules them, recording each result in model order. */\nasync function runTools(state: LoopState, message: AssistantMessage): Promise<readonly ToolCallResult[]> {\n const { runId, signal, clock, output } = state.setup;\n return runToolCalls(message, state.active, {\n runId,\n signal,\n clock,\n depth: TOP_LEVEL_DEPTH,\n maxDepth: DEFAULT_MAX_DEPTH,\n ...state.hooks.pipelineHooks(),\n onStart: (call: ToolCall) =>\n state.send({ type: \"tool_call_start\", callId: call.callId, tool: call.name, input: call.input }),\n onUpdate: (callId, details) => state.send({ type: \"tool_call_update\", callId, details }),\n onResult: (entry) => {\n state.append(toolMessage(entry));\n if (output !== undefined && entry.call.name === output.name && entry.result.isError !== true) {\n state.output = entry.result.structured;\n }\n const ranWith = \"input\" in entry ? { input: entry.input } : {};\n state.send({ type: \"tool_call_end\", callId: entry.call.callId, result: entry.result, ...ranWith });\n },\n });\n}\n\n/** The failed call's error as the run reports it. A message without one counts as `fatal`. */\nfunction runErrorOf(message: AssistantMessage): RunError {\n const error = message.error;\n if (error === undefined) return { kind: \"fatal\", message: \"the model call failed without an error description\" };\n return { kind: error.kind, message: error.message, ...(error.status === undefined ? {} : { status: error.status }) };\n}\n\n/**\n * The stop check after one step. A finished answer, or a question for the user, wins over an abort that came too late\n * to change it; otherwise an abort stops the run before the step cap does. A text answer cut off at the output limit\n * also counts as finished: its message keeps `stopReason: \"length\"`.\n */\nfunction stopCheck(\n state: LoopState,\n message: AssistantMessage,\n results: readonly ToolCallResult[],\n): Outcome | undefined {\n if (message.stopReason === \"error\") return { stopReason: \"error\", error: runErrorOf(message) };\n if (message.stopReason === \"aborted\") return { stopReason: \"aborted\" };\n const finished = results.length === 0 || results.some(({ result }) => result.terminate === true && !result.isError);\n if (finished) return { stopReason: \"done\", output: state.output };\n // Until runs can pause for an answer, a clarification question stops the run, so the model never goes on as if the\n // user had been asked and answered.\n if (results.some(({ result }) => result.pause !== undefined && !result.isError)) {\n return { stopReason: \"stopped\", stoppedBy: CLARIFICATION };\n }\n if (state.setup.signal.aborted) return { stopReason: \"aborted\" };\n if (state.steps >= state.setup.maxSteps) return { stopReason: \"max_steps\" };\n return undefined;\n}\n\n/**\n * What `shouldStop` changes about the stop check. A finished answer or an error stands whatever the hook says; the\n * hook can end a run that would go on, and can keep going a run the model ended by answering in text, until the\n * step cap.\n */\nfunction withVerdict(state: LoopState, natural: Outcome | undefined, verdict: StopVerdict): Outcome | undefined {\n if (natural !== undefined && verdict.kind !== \"continue\") return natural;\n switch (verdict.kind) {\n case \"stop\":\n return { stopReason: \"stopped\", stoppedBy: verdict.stoppedBy };\n case \"no_progress\":\n return { stopReason: \"no_progress\", reason: verdict.reason };\n case \"continue\":\n if (natural === undefined) return undefined;\n if (state.steps >= state.setup.maxSteps) return { stopReason: \"max_steps\" };\n state.append({ role: \"user\", content: verdict.content });\n return undefined;\n default:\n return natural;\n }\n}\n\n/** The stop check after one step, then the `shouldStop` hook where it may change it. */\nasync function decide(\n state: LoopState,\n message: AssistantMessage,\n results: readonly ToolCallResult[],\n): Promise<Outcome | undefined> {\n const natural = stopCheck(state, message, results);\n const endedByAnswer = natural?.stopReason === \"done\" && results.length === 0;\n if (natural !== undefined && !endedByAnswer) return natural;\n const verdict = await state.hooks.shouldStop({ messages: state.messages, lastMessage: message });\n return withVerdict(state, natural, verdict);\n}\n\n/** The outcome of a hook that failed while the run fails closed. A failure caused by an abort ends the run aborted. */\nfunction failedOutcome(state: LoopState, error: unknown): Outcome {\n if (!(error instanceof HookFailure)) throw error;\n if (state.setup.signal.aborted) return { stopReason: \"aborted\" };\n return { stopReason: \"error\", error: { kind: \"hook\", message: error.message } };\n}\n\nasync function runStep(state: LoopState): Promise<Outcome | undefined> {\n state.stepIndex = state.steps;\n state.send({ type: \"step_start\" });\n let outcome: Outcome | undefined;\n try {\n const message = await callModel(state);\n const results = await runTools(state, message);\n outcome = await decide(state, message, results);\n } catch (error) {\n outcome = failedOutcome(state, error);\n }\n state.send({ type: \"step_end\", stopCheck: outcome === undefined ? \"continue\" : \"stop\" });\n return outcome;\n}\n\n/**\n * An aborted run's transcript ends with an assistant message whose `stopReason` is `\"aborted\"`. When tool results end\n * the transcript, because the abort came while tools ran or cut off a response that held tool calls, the loop\n * appends an empty one after them; the replay pass drops it before any request.\n */\nfunction closeAborted(state: LoopState): void {\n const last = state.messages.at(-1);\n if (last?.role === \"assistant\" && last.stopReason === \"aborted\") return;\n state.append({\n role: \"assistant\",\n content: [],\n model: state.setup.model.ref,\n stopReason: \"aborted\",\n usage: emptyUsage(),\n cost: { ...NO_COST },\n });\n}\n\nfunction resultOf(state: LoopState, outcome: Outcome): RunResult {\n const base = {\n messages: state.added,\n context: { system: state.setup.system, messages: state.messages },\n usage: state.usage,\n cost: state.cost ?? { ...NO_COST },\n steps: state.steps,\n };\n return { ...base, ...outcome } as RunResult;\n}\n\n/**\n * Ends the run: the settle event comes once every observer has seen what came before it, and `run_end` after that.\n * An observer's failure while handling `agent_settled` is reported between the two; one while handling `run_end` is\n * dropped, so `run_end` stays the last event. The result is returned only once observers have seen it.\n */\nasync function finish(state: LoopState, outcome: Outcome): Promise<RunResult> {\n if (outcome.stopReason === \"aborted\") closeAborted(state);\n if (outcome.stopReason === \"max_steps\") {\n state.send({ type: \"warning\", code: \"max_steps\", detail: `the run reached maxSteps (${state.setup.maxSteps})` });\n }\n if (outcome.stopReason === \"error\") state.send({ type: \"error\", error: outcome.error });\n await state.drain();\n state.send({ type: \"agent_settled\" });\n await state.drain();\n const result = resultOf(state, outcome);\n state.send({ type: \"run_end\", result });\n await state.drain();\n return result;\n}\n\n/**\n * Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results\n * already received are in the transcript.\n */\nexport async function runLoop(setup: LoopSetup, emit: Emit, drain: Drain): Promise<RunResult> {\n const state = new LoopState(setup, emit, drain);\n let outcome: Outcome | undefined;\n while (outcome === undefined) {\n outcome = setup.signal.aborted ? { stopReason: \"aborted\" } : await runStep(state);\n }\n return finish(state, outcome);\n}\n"]}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The observer channel: delivers each event to every subscriber, in order, without ever letting a subscriber change
3
+ * or break the run. Each subscriber has its own queue, so a slow one delays only itself, and the run waits for the
4
+ * queues to empty only where it must, before `agent_settled` and before the run ends, and then only for a bounded
5
+ * time.
6
+ */
7
+ import type { AgentEvent } from "./events.js";
8
+ import type { Observer } from "./hooks.js";
9
+ /** The hook name a `hook_error` event gives for a failed observer. */
10
+ export declare const OBSERVER_HOOK = "observer";
11
+ /** What a failed observer turns into: the run reports it as a `hook_error` event. */
12
+ export type ReportFailure = (hook: string, error: unknown) => void;
13
+ /** Delivers events to observers. `deliver` and `flush` never throw and never reject. */
14
+ export declare class ObserverBus {
15
+ #private;
16
+ /** `timeoutMs` bounds how long `flush` waits for an observer before it drops it. */
17
+ constructor(report: ReportFailure, timeoutMs: number);
18
+ /** Starts delivering later events to `observer`, and returns the function that stops it. */
19
+ add(observer: Observer): () => void;
20
+ /**
21
+ * Queues `event` for every subscriber. They all get one frozen copy, so an observer can neither change the event
22
+ * the run and its iterators hold nor any message or result inside it.
23
+ */
24
+ deliver(event: AgentEvent): void;
25
+ /**
26
+ * Resolves once every subscriber has handled every event delivered so far, including events its failures add. A
27
+ * subscriber that has not caught up within the timeout is dropped and reported, so an observer whose promise never
28
+ * settles can't hold the run open.
29
+ */
30
+ flush(): Promise<void>;
31
+ }