@buildanagent/sdk 0.1.0-alpha.1 → 0.1.0-alpha.10

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 (116) hide show
  1. package/README.md +424 -5
  2. package/dist/budget.d.ts +33 -0
  3. package/dist/budget.js +55 -0
  4. package/dist/budget.js.map +1 -0
  5. package/dist/compose.d.ts +26 -0
  6. package/dist/compose.js +157 -0
  7. package/dist/compose.js.map +1 -0
  8. package/dist/errors.d.ts +49 -0
  9. package/dist/errors.js +57 -0
  10. package/dist/errors.js.map +1 -0
  11. package/dist/events.d.ts +168 -0
  12. package/dist/events.js +32 -0
  13. package/dist/events.js.map +1 -0
  14. package/dist/freeze.d.ts +11 -0
  15. package/dist/freeze.js +42 -0
  16. package/dist/freeze.js.map +1 -0
  17. package/dist/hook-checks.d.ts +31 -0
  18. package/dist/hook-checks.js +130 -0
  19. package/dist/hook-checks.js.map +1 -0
  20. package/dist/hook-runner.d.ts +96 -0
  21. package/dist/hook-runner.js +372 -0
  22. package/dist/hook-runner.js.map +1 -0
  23. package/dist/hooks.d.ts +183 -0
  24. package/dist/hooks.js +2 -0
  25. package/dist/hooks.js.map +1 -0
  26. package/dist/index.d.ts +26 -3
  27. package/dist/index.js +21 -3
  28. package/dist/index.js.map +1 -1
  29. package/dist/loop.d.ts +67 -0
  30. package/dist/loop.js +644 -0
  31. package/dist/loop.js.map +1 -0
  32. package/dist/observers.d.ts +31 -0
  33. package/dist/observers.js +98 -0
  34. package/dist/observers.js.map +1 -0
  35. package/dist/otel/attributes.d.ts +43 -0
  36. package/dist/otel/attributes.js +50 -0
  37. package/dist/otel/attributes.js.map +1 -0
  38. package/dist/otel/content.d.ts +17 -0
  39. package/dist/otel/content.js +48 -0
  40. package/dist/otel/content.js.map +1 -0
  41. package/dist/otel/index.d.ts +6 -2
  42. package/dist/otel/index.js +6 -2
  43. package/dist/otel/index.js.map +1 -1
  44. package/dist/otel/observer.d.ts +82 -0
  45. package/dist/otel/observer.js +300 -0
  46. package/dist/otel/observer.js.map +1 -0
  47. package/dist/pauses.d.ts +61 -0
  48. package/dist/pauses.js +83 -0
  49. package/dist/pauses.js.map +1 -0
  50. package/dist/progress.d.ts +34 -0
  51. package/dist/progress.js +139 -0
  52. package/dist/progress.js.map +1 -0
  53. package/dist/result.d.ts +134 -0
  54. package/dist/result.js +2 -0
  55. package/dist/result.js.map +1 -0
  56. package/dist/resume.d.ts +76 -0
  57. package/dist/resume.js +237 -0
  58. package/dist/resume.js.map +1 -0
  59. package/dist/run.d.ts +214 -0
  60. package/dist/run.js +327 -0
  61. package/dist/run.js.map +1 -0
  62. package/dist/steering.d.ts +52 -0
  63. package/dist/steering.js +104 -0
  64. package/dist/steering.js.map +1 -0
  65. package/dist/testing/scripted-model.d.ts +12 -2
  66. package/dist/testing/scripted-model.js +19 -2
  67. package/dist/testing/scripted-model.js.map +1 -1
  68. package/dist/tools/coerce.d.ts +15 -0
  69. package/dist/tools/coerce.js +93 -0
  70. package/dist/tools/coerce.js.map +1 -0
  71. package/dist/tools/define.d.ts +54 -0
  72. package/dist/tools/define.js +121 -0
  73. package/dist/tools/define.js.map +1 -0
  74. package/dist/tools/format-error.d.ts +13 -0
  75. package/dist/tools/format-error.js +66 -0
  76. package/dist/tools/format-error.js.map +1 -0
  77. package/dist/tools/outcome.d.ts +7 -0
  78. package/dist/tools/outcome.js +30 -0
  79. package/dist/tools/outcome.js.map +1 -0
  80. package/dist/tools/pipeline.d.ts +111 -0
  81. package/dist/tools/pipeline.js +382 -0
  82. package/dist/tools/pipeline.js.map +1 -0
  83. package/dist/tools/scheduler.d.ts +33 -0
  84. package/dist/tools/scheduler.js +51 -0
  85. package/dist/tools/scheduler.js.map +1 -0
  86. package/dist/tools/schema.d.ts +20 -0
  87. package/dist/tools/schema.js +100 -0
  88. package/dist/tools/schema.js.map +1 -0
  89. package/dist/tools/types.d.ts +196 -0
  90. package/dist/tools/types.js +2 -0
  91. package/dist/tools/types.js.map +1 -0
  92. package/dist/vendor/agent-safety/bytes.d.ts +17 -0
  93. package/dist/vendor/agent-safety/bytes.js +59 -0
  94. package/dist/vendor/agent-safety/bytes.js.map +1 -0
  95. package/dist/vendor/agent-safety/errors.d.ts +22 -0
  96. package/dist/vendor/agent-safety/errors.js +22 -0
  97. package/dist/vendor/agent-safety/errors.js.map +1 -0
  98. package/dist/vendor/agent-safety/hash.d.ts +16 -0
  99. package/dist/vendor/agent-safety/hash.js +110 -0
  100. package/dist/vendor/agent-safety/hash.js.map +1 -0
  101. package/dist/vendor/agent-safety/outcome.d.ts +88 -0
  102. package/dist/vendor/agent-safety/outcome.js +140 -0
  103. package/dist/vendor/agent-safety/outcome.js.map +1 -0
  104. package/dist/vendor/agent-safety/pending.d.ts +119 -0
  105. package/dist/vendor/agent-safety/pending.js +122 -0
  106. package/dist/vendor/agent-safety/pending.js.map +1 -0
  107. package/dist/vendor/agent-safety/render.d.ts +40 -0
  108. package/dist/vendor/agent-safety/render.js +92 -0
  109. package/dist/vendor/agent-safety/render.js.map +1 -0
  110. package/dist/vendor/agent-safety/signer.d.ts +42 -0
  111. package/dist/vendor/agent-safety/signer.js +128 -0
  112. package/dist/vendor/agent-safety/signer.js.map +1 -0
  113. package/dist/version.d.ts +2 -0
  114. package/dist/version.js +8 -0
  115. package/dist/version.js.map +1 -0
  116. package/package.json +13 -3
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  The SDK runs your agent's loop over [`@buildanagent/gateway`](../gateway/README.md): it calls the model, runs the tools the model asks for, and stops when the work is done. Its testing export lets you test that agent offline against a scripted model, with no API key.
4
4
 
5
- As of November 2026 the package holds only the testing export. The loop, tools, hooks, approvals and budgets are next.
5
+ As of November 2026 the package holds the loop, tool definitions, hooks, signed pauses for approval and the testing export. Resuming a pause comes next.
6
6
 
7
7
  ## Install the alpha with `pnpm add @buildanagent/sdk@alpha`
8
8
 
@@ -12,14 +12,433 @@ Every release is an alpha until the first stable one, and npm serves the alphas
12
12
  pnpm add @buildanagent/sdk@alpha @buildanagent/gateway@alpha
13
13
  ```
14
14
 
15
- Both packages always share one version, and the SDK depends on that exact version of the gateway. Name the tag: a plain `pnpm add @buildanagent/sdk` installs `0.0.0-bootstrap.0`, a deprecated placeholder, because `latest` stays on it until the first stable release. The package needs Node 22 or later.
15
+ Both packages always share one version, and the SDK depends on that exact version of the gateway. Name the tag: a plain `pnpm add @buildanagent/sdk` installs `0.0.0-bootstrap.0`, a deprecated placeholder, because `latest` stays on it until the first stable release. The package needs Node 22.19 or later, the oldest Node its validator, pi-schema 1.5.2, supports.
16
+
17
+ Don't start Node with `--conditions=source` in a project that installs the SDK. Its validator, pi-schema 1.5.2, maps that condition to a source file its package doesn't ship, so the SDK's root entry fails to load under it ([validator check](docs/validator-check.md)).
18
+
19
+ ## Run an agent with `run()`
20
+
21
+ `run()` starts the loop. It sends your system prompt and the user's message to the model, runs each tool the model calls, and sends the results back. It goes on until the model answers without calling a tool. This agent answers questions about orders with the `lookup_order` tool from the next section, and prints the answer as it streams:
22
+
23
+ ```ts
24
+ const started = run({
25
+ model,
26
+ system: SYSTEM_PROMPT,
27
+ input: question,
28
+ tools: [lookupOrderTool(findOrder)],
29
+ maxSteps: MAX_STEPS,
30
+ });
31
+ for await (const event of started) {
32
+ if (event.type === "text_delta") write(event.delta);
33
+ }
34
+ const result = await started.result;
35
+ ```
36
+
37
+ `model` comes from `createModel()` in the gateway, and a bare model id is a type error. A tool whose `exposure` is `"deferred"` or `"hidden"` is sent to the model only when a `beforeModelCall` interceptor names it in `activeTools`, and a call to a tool the request didn't send gets the unknown-tool error.
38
+
39
+ ### Every run ends with a stop reason
40
+
41
+ A failed model call or a failing tool never makes a run throw. The run ends with a result whose `stopReason` says why:
42
+
43
+ - **`done`**: the model answered without calling a tool, or an output tool accepted its answer. A text answer cut off at `maxOutputTokens` also ends `done`, so check whether the last message's `stopReason` is `"length"` before you show it as complete.
44
+ - **`max_steps`**: the run made `maxSteps` model calls, 20 by default, and the model still wanted to go on. The run also emits a `warning` event with `code: "max_steps"`, so a cap that cut a run short shows up in your logs.
45
+ - **`error`**: a model call failed. `result.error` copies the failure's `kind`, `message` and HTTP `status`. Its `kind` is `overflow` for a request too large for the model's window, `quota` for an account out of credit, `retryable` for a temporary failure that outlasted the gateway's retries, `hook` for an interceptor that threw while the run fails closed, `unknown_price` for a budgeted run that can't price a call, and `fatal` otherwise.
46
+ - **`aborted`**: you aborted the run.
47
+ - **`stopped`**: a `shouldStop` hook ended the run, and `result.stoppedBy` is the reason it gave.
48
+ - **`no_progress`**: the default progress policy found the model repeating a failing call, or a `shouldStop` hook ended the run with `{ stop: "no_progress", reason }`. `result.reason` says why.
49
+ - **`budget`**: the next call could have taken the run past `budgetUsd`, so the run ended without making it. `result.spentUsd`, `result.projectedUsd` and `result.budgetUsd` give the numbers.
50
+ - **`awaiting_approval`**: a `beforeToolCall` gate returned `ask`, so the call waits for a person. `result.pending` holds one signed request for each waiting call, as [the pause section](#a-gate-that-asks-ends-the-run-with-a-signed-pending-request) explains.
51
+ - **`clarification_requested`**: a tool from `clarificationTool()` asked the user a question, and no call waits for an approval. `result.pending` holds a signed request of kind `clarification` for each question, as [the clarification section](#end-the-run-with-outputtool-or-ask-with-clarificationtool) explains.
52
+
53
+ `maxSteps` counts model calls, so an output call that fails its schema spends one of them. The tool calls of the last allowed response still run, so every call in the transcript has a result, except a paused call, which waits for a person.
54
+
55
+ Only the `done` result carries `output`. TypeScript rejects `result.output` until you have checked `result.stopReason === "done"`, so an unfinished run can't pass for a finished one. Every result carries `usage` and `cost`, summed over the run's model calls, and `steps`, the number of calls. `result.messages` holds the messages this run added. `result.context` holds the whole conversation, ready to continue.
56
+
57
+ ### `runOrThrow()` turns an unfinished run into an exception
58
+
59
+ If you would rather catch an exception than check the stop reason, `runOrThrow(run)` returns the `done` result and throws a `RunStoppedError` for any other. The error carries the `result` and the `context` to continue from. `RunStoppedError.isInstance(error)` recognises it, even across two copies of the package:
60
+
61
+ ```ts
62
+ const result = await runOrThrow(run({ model, system, input }));
63
+ ```
64
+
65
+ ### Continue a conversation with `continueRun()`
66
+
67
+ `continueRun(context, options)` goes on from a context: a previous result's `context`, or one you rebuilt from your own store. A context is plain JSON holding the system prompt, the messages and, for a paused run, `pending` and `pendingInputs`. A run that stopped at `max_steps` continues with the model reading its last tool results. A context whose last response ended in an error asks the model again, because the gateway leaves that response out of the request. A `done` context ends with the model's answer, so add a user message to it before you continue, or pass the messages as `history` to `run()` with the new input. A paused context resumes with `resolutions`, as [the resume section](#resume-a-pause-with-continuerun-and-a-resolution-for-each-request) explains.
68
+
69
+ ### Abort a run with `run.abort()` or a signal
70
+
71
+ `run.abort(reason)` stops a run, and so does the `signal` option. A model call in flight ends, and a running tool sees its `ctx.signal` fire. The run waits for that tool to return, so pass the signal on to your own I/O. Calls that haven't started get an error result instead of running.
72
+
73
+ An aborted run's transcript stays well formed: every tool call has a result, and the last message is an assistant message with `stopReason: "aborted"`. When tool results would end the transcript, because the abort came while tools ran or cut off a response that held tool calls, the loop appends an empty aborted message after them. Each gateway adapter drops it before the next request, so the transcript can be sent again as it is.
74
+
75
+ ## Three guards stop a runaway run
76
+
77
+ A run that loops or overspends costs real money, so the SDK ships three guards. Each is an option of `run()` and `continueRun()`, and the table gives its default (the budget has none).
78
+
79
+ | Guard | Default | Change it with |
80
+ | --- | --- | --- |
81
+ | USD budget | none | `budgetUsd: 5` |
82
+ | Progress policy | 3 identical failing calls, or 5 calls on one `progressKey` | `progress: { maxIdenticalFailures, maxSameKeyCalls }`, or `progress: false` |
83
+ | Depth cap | `maxDepth` 2 | `depth` and `maxDepth` |
84
+
85
+ These numbers are provisional. Recorded runs will retune them.
86
+
87
+ ### `budgetUsd` checks the cost before each call
88
+
89
+ Before every model call, the run projects the most that call can cost and compares the spend so far plus that projection with `budgetUsd`. If the call could pass the cap, the run ends with `stopReason: "budget"` and never sends it. The projection comes from the gateway's `projectCallCost()`: the previous call's reported input, plus a character-based estimate of the messages added since, at the model's input rate, plus the call's `maxOutputTokens` (or the model's own limit) at its output rate. The SDK re-exports the function, so code that calls `Model.complete()` outside the loop projects with the same formula.
90
+
91
+ Because the projection assumes the model may use its whole output allowance, the run stops early rather than late.
92
+
93
+ On the SDK's scripted 30-step run, with caps placed just above the spend after `k` calls, the pre-emptive check overshot the cap by $0 on every cap and sent 9.3 calls on average. A check that runs after each response overshot by $0.0105 on average, almost the whole call that crossed the cap. The cost of the early stop is cap left unspent: $0.054 on average in that run, set by how far `maxOutputTokens` sits above the output the model actually writes. Lower `maxOutputTokens` in `modelOptions` to tighten the projection.
94
+
95
+ The cap counts the calls the run itself makes. A `continueRun()` does not count the cost of the context it starts from.
96
+
97
+ A run with a budget needs a price for every call. If the model's price is unknown, the run ends `error` with `error.kind: "unknown_price"` before its first call, and so does a run whose earlier call came back with an unknown cost. Add the model to a catalog you pass to `createModel()`, or drop the budget.
98
+
99
+ ### The progress policy ends a run that repeats a failing call
100
+
101
+ The policy reads the run's transcript after each step, after your own `shouldStop` hook. It ends the run `no_progress` in two cases:
102
+
103
+ - **Identical failures.** The latest three tool calls name one tool, carry one input, and each returned an error. Inputs compare by `canonicalInputHash()`, so `{a, b}` and `{b, a}` are the same input. A successful call, or a call to another tool, breaks the streak.
104
+ - **One key.** A tool declares `progressKey(input)`, such as a file path plus a line, and five calls to it return that key with no success between them. A success with that key starts the count again, and calls with other keys do not affect it. The inputs may differ, which is how it catches a model that keeps rewording a failing edit. The function receives the input exactly as the model sent it, so it must cope with any shape; a key that throws or isn't a string leaves that call out of the count.
105
+
106
+ Your own `shouldStop` runs first and its stop wins, but neither its `{ continue }` nor a throw under `onFailure: "continue"` can keep a stuck run going. Pass `progress: { maxIdenticalFailures: 2 }` to tighten a threshold, or `progress: false` to turn the policy off. A `continueRun()` counts only the calls it makes, so you can continue a run that ended `no_progress` after you change what the model sees.
107
+
108
+ ### `depth` and `maxDepth` stop a tree of agents
109
+
110
+ Every tool receives `ctx.depth` (0 for a top-level run) and `ctx.maxDepth` (2 by default). A tool that starts its own agent passes the next level down with `nestedRunDepth(ctx)`:
111
+
112
+ ```ts
113
+ async execute(input, ctx) {
114
+ const child = run({ model, system, input: input.task, signal: ctx.signal, budgetUsd: 0.5, ...nestedRunDepth(ctx) });
115
+ return { content: [{ type: "text", text: (await child.result).stopReason }] };
116
+ }
117
+ ```
118
+
119
+ Pass `signal: ctx.signal` so the child stops when the parent's call is aborted. The parent's `budgetUsd` counts only the parent's own model calls, so give each child a budget of its own. A tool running at `depth === maxDepth` that starts a child run this way makes `run()` throw `max_depth_exceeded`. Since the throw happens inside `execute`, the model reads it as an error result and can answer without the sub-agent.
120
+
121
+ ## Steer a running agent with `run.steer()`, or queue a follow-up with `run.followUp()`
122
+
123
+ Both methods queue a user message and return a promise for a `DeliveryReceipt`. The loop applies queued messages only at a step boundary, so a model call or tool batch that is running is never cut. A steer is applied before the run's next model call: a steer sent while a batch of tool calls runs waits for the whole batch, and the model reads it after the tool results.
124
+
125
+ ```ts
126
+ const started = run({ model, system, input, tools });
127
+ const receipt = await started.steer("Use order 2 instead.");
128
+ console.log(receipt.stepIndex); // the step whose model call is the first to read the message
129
+ ```
130
+
131
+ A follow-up waits until the run would otherwise end. When the model answers without a tool call and a message is waiting, the run adds the waiting messages and makes one more model call, so a follow-up sent before the run ends extends it by one step. A waiting steer goes first, and follow-ups wait for the next time the run would end. The extra call counts against `maxSteps`: a run already at the cap ends as it would have.
132
+
133
+ A receipt resolves once its message is in the transcript. It holds an `id` that is unique within the run, the `kind` (`"steer"` or `"follow_up"`), the `message` as content blocks and the `stepIndex`, the step at whose start the run added the message. That step's model call is the first to read it, unless the run ends before the call, which a budget stop or a failed hook can cause. The run also emits one `steer_applied` event for each message, carrying the same receipt. A message is a string that isn't blank, or a non-empty list of text and image blocks whose text isn't blank. The run applies messages in the order they were sent.
134
+
135
+ The promise rejects with an `SdkError` whose code is `undelivered_message` when the run ends before it applies the message. That happens in four cases:
136
+
137
+ - You call after the run has its outcome.
138
+ - An abort, or any stop reason other than a text answer, ends the run.
139
+ - A `shouldStop` hook or the progress policy ends a run that answered in text.
140
+ - The run ends by calling its output tool.
141
+
142
+ The promise rejects with `invalid_run_options` for a blank message or a block that isn't text or an image. A promise you never await is safe to drop: a rejection nobody reads does not raise an unhandled rejection.
143
+
144
+ ## A run streams one closed set of events
145
+
146
+ Iterating a run yields its events. Each iteration starts from the run's first event, so you can start iterating at any time, even after the run has ended. Every event carries the run's `runId`, a `seq` that counts events from 0, a `stepIndex` that counts model calls from 0, and a `timestamp` from the run's clock.
147
+
148
+ The events come in two layers. The delta layer streams each content block by its index, for a user interface: `text_start`, `text_delta` and `text_end`, and the same three for `reasoning` and `tool_input`. The item layer carries the finished pieces for a log:
149
+
150
+ - **`run_start`** comes first, with the SDK's version, the spec version and the model.
151
+ - **`step_start`** and **`step_end`** wrap one model call and its tool calls; `step_end.stopCheck` says whether the run goes on.
152
+ - **`model_call_start`** carries the request, and **`model_call_end`** the final message.
153
+ - **`tool_call_start`**, **`tool_call_update`** and **`tool_call_end`** follow each tool call; `tool_call_end.result` is what the model reads. When a `beforeToolCall` gate replaced the model's input, `tool_call_end.input` holds the input the call got instead.
154
+ - **`context_transformed`** reports the message counts before and after `transformContext` for one model call.
155
+ - **`steer_applied`** reports a queued steer or follow-up that entered the transcript, with its receipt.
156
+ - **`approval_request`** reports a call that waits for a person, with its signed `request` and the `input` that request signs: a call a gate paused, or a tool's question. That call gets no `tool_call_end`. In a resumed run, **`resolution_rejected`** reports a request or resolution that failed its check, with the cause.
157
+ - **`hook_error`** reports an interceptor or an observer that threw, with the hook's name and the message. It also reports a pause that could not be signed, with `hook: "signer"`.
158
+ - **`retry`** reports a failed request the gateway is retrying, and **`warning`** reports a reached cap or a model warning.
159
+ - **`error`** and **`abort`** report a failed call and an abort request.
160
+ - **`agent_settled`** fires once nothing is running any more, retries and tools included. **`run_end`** follows it and carries the result.
161
+
162
+ `AGENT_EVENT_TYPES` lists every type at run time, and a run emits no other. The union is closed, so a `switch` over `event.type` can be exhaustive.
163
+
164
+ ## Hooks change a run at six moments, and observers only watch
165
+
166
+ A hook is a function that takes one event object. Interceptors can change, block or replace something; observers can only watch. Pass interceptors as one object in the `interceptors` option, and observers in `observers` or through `run.on()`.
167
+
168
+ ### A step calls the interceptors in one fixed order
169
+
170
+ Each model call goes through the same moments, and each interceptor owns one of them:
171
+
172
+ 1. **`transformContext`** returns the messages to send for this call. Use it to mask old tool output or summarise a long conversation. The view reaches that one request. The next call's event, `result.messages` and `result.context` all keep the full history, and each call emits a `context_transformed` event.
173
+ 2. **`beforeModelCall`** returns a patch for the request: a `system` prompt, `messages`, `options`, another `model`, or `activeTools`. A patch lasts for that call only.
174
+ 3. The model call runs.
175
+ 4. **`afterModelCall`** returns `{ message }` to replace the response. The transcript, `model_call_end` and the tool calls that run all use the replacement, while usage and cost stay the model's own.
176
+ 5. For each tool call, **`beforeToolCall`** decides whether it runs, and **`afterToolCall`** edits the result.
177
+ 6. **`shouldStop`** decides whether the run ends.
178
+
179
+ Every event carries `runId`, `stepIndex`, `signal` and `timestamp`, and the two tool hooks add `callId`. Pass `signal` on to any I/O your hook does. The event's data is frozen, so a hook that tries to change it throws a `TypeError`. Return a replacement instead.
180
+
181
+ `activeTools` lists the tools to send, and only those. A tool whose `exposure` is `"deferred"` or `"hidden"` is sent when you name it, so a tool-search step can reveal a tool for the next request. Tools always go out in definition order, whatever order your list has, and a name that matches no tool throws `invalid_hook_result`. A call to a tool the request did not send gets the unknown-tool error.
182
+
183
+ ### A gate decides each tool call
184
+
185
+ `beforeToolCall` returns `{ decision: "allow" }`, `{ decision: "deny", reason }` or `{ decision: "ask" }`. An `allow` may carry a new `input`, which must pass the tool's schema. A `deny` reaches the model as an error result that states the reason, so the model never sees a silent block. An `ask` pauses the call: the run ends `awaiting_approval` with a signed pending request, as the next section explains.
186
+
187
+ The run asks about one call at a time, in the order the model sent them, and no call of the step starts until every gate has answered. Without a `beforeToolCall`, every registered tool is allowed. A gate must return a decision: returning nothing throws `invalid_hook_result`, so a forgotten `return` can't pass for permission.
188
+
189
+ `afterToolCall` returns a patch of `content`, `details`, `structured`, `isError` or `terminate`. The patched result is what the model reads and what `tool_call_end` reports. It runs for calls that executed, a tool that threw included, and not for calls that never ran, such as an unknown tool, invalid input or a denied call. To change a write's `outcome`, replace `content` instead.
190
+
191
+ ### `shouldStop` ends a run, or keeps it going
192
+
193
+ It returns `true` or `{ stop: "hook", reason }` to end the run `stopped`, with the reason as `stoppedBy` (`"hook"` for `true`). It returns `{ stop: "no_progress", reason }` to end it `no_progress`. It returns `{ continue: "text or blocks" }` to keep going a run whose model answered in text, with your content added as a user message. If the step called tools, the run goes on anyway and the content is not added. At the step cap the run ends `max_steps` instead. `false` leaves the decision to the run. A run that has already finished, failed, been aborted or asked a question keeps that outcome.
194
+
195
+ ### A throwing interceptor fails closed
196
+
197
+ By default a hook that throws stops the unsafe thing, and the run emits a `hook_error` event:
198
+
199
+ - A failed `beforeToolCall` denies the call.
200
+ - A failed `afterToolCall` withholds the result, so a redaction that crashed can't leak the original. The stand-in tells the model the tool ran and keeps a write's outcome, so the model does not retry a write that was applied.
201
+ - A failed `transformContext`, `beforeModelCall`, `afterModelCall` or `shouldStop` ends the run with `stopReason: "error"` and `error.kind: "hook"`. If the run was aborted, it ends `aborted` instead. When `afterModelCall` fails, the transcript and `model_call_end` hold an empty stand-in with `stopReason: "error"` and the call's usage and cost, so the response is withheld but the billed call is still on record.
202
+
203
+ Set `onFailure: "continue"` to skip a failed hook and go on as if it had returned nothing. A hook that returns the wrong shape is a different case: it is a bug in your code, so the run's `result` rejects with `invalid_hook_result` whatever `onFailure` says.
204
+
205
+ ### `composeInterceptors()` joins several objects
206
+
207
+ A run takes one `Interceptors` object, so `composeInterceptors(a, b)` joins a context policy, a permission check and an audit. For a moment that several define, the hooks run in the order given. `transformContext` passes the messages through each hook in turn. `beforeModelCall` merges the patches, a later field replacing an earlier one. `afterModelCall` and `afterToolCall` chain, each hook seeing the result so far. For gates the strictest answer wins: the first `deny` ends the check, an `ask` beats an `allow`, and an input one gate replaces is the input the next gate sees. For `shouldStop` the first stop wins, then the first continue. Each hook's return value is checked as if it ran alone, so a gate that returns nothing throws `invalid_hook_result` even when another gate allows the call. The joined `onFailure` is `"continue"` only when every object sets it to `"continue"`; an object that leaves it unset counts as `"fail_closed"`.
208
+
209
+ ### Observers watch without changing anything
210
+
211
+ An observer is `(event) => void | Promise<void>`. Each one sees every event in order, and waits for its own promise before it gets the next. Observers don't wait for each other, so one slow observer delays only itself. The `observers` option sees events from `run_start`. `run.on(observer)` returns a function that removes it, and drops events still queued for it. Call it right after `run()` to see every event but `run_start`.
212
+
213
+ An observer that throws or rejects becomes a `hook_error` event with `hook: "observer"`, and never changes the run. The one exception is an observer that fails while handling `run_end`: nothing may follow that event, so the failure is dropped.
214
+
215
+ The run waits for observers to handle `agent_settled` and `run_end` before it settles, for at most `observerTimeoutMs` each time, a number from 1 to 2147483647 that defaults to 10000. An observer that hasn't caught up by then is removed and reported as a `hook_error`, so an observer whose promise never settles can't hold the run open. Each observer gets a frozen copy of the event, so it can't change the run's own data.
216
+
217
+ ## A gate that asks ends the run with a signed pending request
218
+
219
+ When a `beforeToolCall` gate returns `{ decision: "ask", reason, policyVersion }`, the run doesn't run that call, and doesn't block on a callback either. It signs a pending request for the call, finishes the step's other calls, and ends with `stopReason: "awaiting_approval"`. Store the request with the context, show it to a person with the input it signs, and pass the answer to `continueRun()`, which checks it against the signature before the call runs:
220
+
221
+ ```ts
222
+ const result = await run({ model, system, input, tools, interceptors: { beforeToolCall: gate }, signer }).result;
223
+ if (result.stopReason === "awaiting_approval") {
224
+ await store.save(result.context); // result.context.pending holds the same requests as result.pending
225
+ }
226
+ ```
227
+
228
+ Each request is a `SignedPendingRequest`. Its signature covers six fields: the request's `id`, its `kind`, the `callId`, the `tool`, the `inputHash` and the `policyVersion`. The input hash is `canonicalInputHash()` of the input the call would run with once approved, so a stored pause whose call, tool or input changed no longer verifies. That input is the model's after coercion, `repair` and any gate's replacement, so it can differ from the call's arguments in the transcript; the request stores only its hash, and `result.context.pendingInputs` and the `approval_request` event hold the input itself, by request id. Show the approver that input, not the model's arguments.
229
+
230
+ A gate's `ask` may carry its own `input`, which must pass the tool's schema, and `composeInterceptors()` passes an earlier gate's replacement on that way when a later gate asks, so the pause signs the input the earlier gate chose.
231
+
232
+ `reason` and `createdAt` are shown to people and are not signed, so never let them decide anything. `keyId` names the key that signed.
233
+
234
+ A paused call has no result in the transcript, so the context ends with the model's call still open. The step's other calls run or are denied as usual, and every call a gate paused gets its own request, in model order. A pause wins over an output tool that answered in the same step, because its call is still waiting. The run emits `approval_request` with the request and its input once every call of the step has been gated and before any of them runs. The call gets no `tool_call_end`, and the OpenTelemetry observer ends its tool span without an error. The event is advisory. A later call in the step can still fail the run with a programmer error, which ends it `error` with no `pending`, so build an approval queue from `result.pending`, not from the events.
235
+
236
+ ### Resume a pause with `continueRun()` and a resolution for each request
237
+
238
+ A person answers each request with a `Resolution`: `{ requestId, decision: "allow" | "deny", reason?, by? }` for an approval, or `{ requestId, answer, by? }` for a question. Pass the answers to `continueRun()` with the stored context, in this process or another one that holds the same key ring:
239
+
240
+ ```ts
241
+ const context = await store.load(id); // plain JSON, with pending and pendingInputs
242
+ const next = continueRun(context, { model, tools, signer, resolutions: [{ requestId, decision: "allow", by: "ana" }] });
243
+ ```
244
+
245
+ Before its first model call, the run checks every waiting call's stored request with its `signer`. The check verifies the signature under the request's `keyId`, then the call id and tool against the transcript's call, then the input in `context.pendingInputs` against the signed hash, and last that the resolution fits the request's kind. Each waiting call then goes one of four ways:
246
+
247
+ - **A verified `allow`** runs the call once, with the input its request signs, never the transcript's arguments. `beforeToolCall` isn't asked again, and `afterToolCall` still runs.
248
+ - **A verified `deny`** gives the model an error result with the reason, and a verified `answer` reaches the model as the call's result.
249
+ - **A request no resolution names** still waits. When any call still waits, the run ends paused again without a model call, so you can answer one call at a time.
250
+ - **A request or resolution that fails a check** runs nothing. The run emits `resolution_rejected` with the cause, such as `signature_invalid`, `input_changed`, `resolution_mismatch` or `replayed`, and the call asks again. Your gate is asked as for a new call, and the call pauses with a new request even when the gate allows it. The new request is always an approval, because a request that failed its check can't be trusted to say it was a question. A question that fails therefore comes back as an approval request for the asking tool, and once allowed, the tool runs and asks again. Only a tool the model is sent by default can ask again; a call to any other tool gets the unknown-tool error result instead. A resolution that names no request in the context is reported as `unknown_request`, and its request still waits.
251
+
252
+ Settling the requests is not a step, so `steps` and `maxSteps` count only the model calls the resumed run makes. The results are recorded in the order the model made the calls. When no call still waits and an approved call's result sets `terminate`, such as the output tool's, the run ends `done` without a model call. Pass `recheck` to run current policy just before an approved call runs. It gets copies of the request and its input, so editing them changes nothing, and resolves to `"allow"`, or to `{ deny: reason }`, which gives the model an error result instead. A `recheck` that throws or returns anything else denies the call. Without `recheck`, a verified approval runs, so check policy before you resolve.
253
+
254
+ `continueRun()` refuses a context it can't resume safely. It throws `invalid_run_options` for a context whose last assistant message has a call with no result and no pending request, because that call's pause record was lost, and silently answering it would hide the loss. It also throws for a pending request whose call doesn't wait in the context, and for malformed `pending`, `pendingInputs` or `resolutions`. Store `pending` and `pendingInputs` with the messages.
255
+
256
+ A request is meant to be answered once, but the SDK can't see your other processes, so single use is your store's job. Mark a request used, atomically, before you call `continueRun()` with its answer, and refuse a second resume of the same stored context there. Within one call, two resolutions for one request are refused as `replayed`.
257
+
258
+ ### `blockingApprovals()` answers inside the run, where the person waits with the process
259
+
260
+ Where the run and the person share a process, such as a terminal, `blockingApprovals(handler)` answers approvals without ending the run. Join it with your gate:
261
+
262
+ ```ts
263
+ const interceptors = composeInterceptors(gate, blockingApprovals(async (request, { input }) => askInTerminal(request, input)));
264
+ ```
265
+
266
+ When a gate asks, the run signs the request and emits `approval_request` before it calls the handler, so a crash while it waits still leaves a signed record to resume from. The handler returns a `Resolution` for that request, which the run checks against the request like a resumed one. An `allow` runs the call, and a `deny` gives the model an error result. An answer that names another request, an answer of the wrong kind, a handler that throws and an abort while the run waits each deny the call, and all but the abort emit a `hook_error` with `hook: "blockingApprovals"`. `composeInterceptors()` joins at most one `blockingApprovals()` object.
267
+
268
+ ### Pass `hmacSigner()` wherever a pause may resume in another process
269
+
270
+ The run signs with its `signer` option. The default, `ephemeralSigner()`, holds a random key that lives only in this process. On a serverless host an isolate or function can be recycled between the pause and the answer, and another process rejects the signature as one from an unknown key. The default signer is also shared by every run in the process, and the signed fields name no run or tenant, so a host that serves several tenants in one process stores each tenant's requests apart and passes a signer of its own. Pass `hmacSigner({ keys, current })` over a key ring you keep there:
271
+
272
+ ```ts
273
+ const signer = hmacSigner({ keys: { "2026-11": key2611, "2026-12": key2612 }, current: "2026-12" });
274
+ ```
275
+
276
+ `hmacSigner()` signs with the key `current` names and verifies with any key in `keys`, each 32 bytes or more. To rotate, add a new key and make it current, and keep the old key in the ring until no stored pause names it. A request whose `keyId` isn't in the ring fails verification. Keys stay inside non-extractable Web Crypto keys: no error, event, result or span holds a key's bytes.
277
+
278
+ A pause that can't be signed is never written unsigned. If the signer throws, the call is blocked with an error result, and a `hook_error` with `hook: "signer"` names the cause without the signer's own message. A request id from `idGenerator` that repeats the run's id or an earlier request's is replaced by a random UUID, so a generator that always returns one id still pauses every call.
279
+
280
+ ### Sign a pause outside a run with `createPendingRequest()`
281
+
282
+ Code that makes a tool call itself, rather than through the model, can build the same record:
283
+
284
+ ```ts
285
+ const request = await createPendingRequest({ kind: "approval", callId, tool: "refund", input, reason }, signer);
286
+ ```
287
+
288
+ `createPendingRequest()` signs through the same code path as the loop, so for the same fields, id and signer the two requests are identical byte for byte. Its optional third argument takes `generateId` and `now`, which default to `crypto.randomUUID()` and the current time. It rejects with `invalid_run_options` for a `kind` other than `"approval"` or a signer that isn't an `ApprovalSigner`.
289
+
290
+ ### The signers and the record belong to the safety package
291
+
292
+ `ApprovalSigner`, `ephemeralSigner()`, `hmacSigner()`, `canonicalInputHash()`, `SignedPendingRequest`, `Resolution`, `Recheck`, `RejectionCause` and `SignPendingOptions` are `@buildanagent/agent-safety`'s, re-exported unchanged. So are `SafetyError` and `isSafetyError()`, because `hmacSigner()` throws a `SafetyError` with code `invalid_key_ring` for an unusable ring, and `createPendingRequest()` rejects with one, code `invalid_pending` or `invalid_input`, for a blank field or an input with no canonical JSON form.
293
+
294
+ Until the safety package is published, the SDK carries byte-identical copies of its files, and a test fails if they drift. One consequence follows from the copies: in a process that loads both packages, each has its own ephemeral signer, so a pause signed by one's default doesn't verify with the other's.
295
+
296
+ ## Export a run as OpenTelemetry spans with `otelObserver()`
297
+
298
+ `otelObserver()` turns a run's events into spans that follow the OpenTelemetry GenAI conventions, and it sends them only to the tracer you pass. Import it from `@buildanagent/sdk/otel` and add it to `observers`. Pass it in `observers`, not to `run.on()` later: an observer added late misses `run_start` and records nothing for that run.
299
+
300
+ ```ts
301
+ import { otelObserver } from "@buildanagent/sdk/otel";
302
+ import { context, type Span, trace } from "@opentelemetry/api";
303
+
304
+ const telemetry = otelObserver({
305
+ tracer: trace.getTracer("my-agent"),
306
+ agentName: "triage",
307
+ childContext: (parent) => trace.setSpan(context.active(), parent as Span),
308
+ forceFlush: () => provider.forceFlush(),
309
+ });
310
+ const started = run({ model, system, input, observers: [telemetry] });
311
+ ```
312
+
313
+ A run produces one `invoke_agent` span, one `chat` span for each model call and one `execute_tool` span for each tool call. The model and tool spans are children of the run's span. Each span starts and ends at the timestamps of its events, so a run on a fixed clock gives the same span times every time.
314
+
315
+ The observer imports nothing from OpenTelemetry. `tracer` needs only a `startSpan(name, options, context)` method, which an OpenTelemetry `Tracer` has, and `@opentelemetry/api` stays your own dependency. Two options carry the trace context explicitly, so nothing depends on an ambient `AsyncLocalStorage`, which some runtimes lack:
316
+
317
+ - **`parentContext`** is the context the run's span starts in, such as the one for an incoming request. Left out, the tracer decides, and an OpenTelemetry tracer uses the active context. Every run an observer serves starts in the same `parentContext`, so when it belongs to one request, create one observer per request.
318
+ - **`childContext(parent)`** is required. It builds the context for a model or tool span from the run's span, which makes those spans its children in the same trace. The observer can't build a context itself, because that takes `@opentelemetry/api`.
319
+
320
+ Each `chat` span records `gen_ai.usage.input_tokens` as `totalInput(usage)`, so cached tokens count in it, and `gen_ai.usage.output_tokens` as `usage.output`, which includes reasoning. It adds the cache read, cache write and reasoning counts when they are above zero. A call whose provider reported no usage gets no token attributes, because zeros would read as a measurement. The run's span carries the sums over all calls. A failed model call, a tool that returns `isError` and a run that ends in `error` set the span's status and `error.type`.
321
+
322
+ Spans hold no content unless you ask. With `captureContent: true`, the `chat` spans also record `gen_ai.system_instructions`, `gen_ai.input.messages` and `gen_ai.output.messages`, and the tool spans record `gen_ai.tool.call.arguments` and `gen_ai.tool.call.result`, all as JSON strings in the conventions' message format. The arguments are the ones the tool ran with, so a `beforeToolCall` gate's replacement wins over the model's input. Image bytes are never recorded. An error's message can quote a prompt or an argument, so it becomes the span's status description only when content is on; with content off, a failed span gets its error status and `error.type` alone. Prompts and tool results can hold secrets and personal data, so turn content on only for a backend you trust with them.
323
+
324
+ `telemetry.flush()` calls your `forceFlush`. On Cloudflare Workers, pass it to `ctx.waitUntil()` so spans survive the end of the request. An observer that throws, a tracer included, becomes a `hook_error` event and never changes the run, like any observer.
325
+
326
+ A run's `result` rejects for a programmer error, such as a tool that returns a malformed result. That run sends no `run_end`, so its spans stay open. Call `telemetry.endRun(started.id, error)` in your `catch` to end them as failed and let the observer forget the run.
327
+
328
+ One limit applies to nested runs. A run that a tool starts is another run to the observer, so its span starts in `parentContext` and is not a child of the calling tool's span, because events carry no parent run id.
329
+
330
+ The names come from one constants file. `GEN_AI_ATTRIBUTES` holds every attribute name the observer writes, and `SEMCONV_GENAI_COMMIT` (`"d28355d"`) names the commit of `open-telemetry/semantic-conventions-genai` they follow. The conventions are at Development stability as of November 2026, so a rename upstream changes only that file. Your tests can import the same constants.
331
+
332
+ ## Define a tool with `defineTool()`
333
+
334
+ A tool is a name, a description the model reads, an input schema and an `execute` function. This tool looks up an order in your own store:
335
+
336
+ ```ts
337
+ export function lookupOrderTool(findOrder: FindOrder) {
338
+ return defineTool({
339
+ name: "lookup_order",
340
+ description: "Look up an order by its number and return its status.",
341
+ inputSchema: z.object({ order: z.number().int().positive() }),
342
+ async execute({ order }) {
343
+ const found = await findOrder(order);
344
+ if (found === undefined) return { content: [{ type: "text", text: `No order ${order} exists.` }], isError: true };
345
+ return { content: [{ type: "text", text: `Order ${order} is ${found.status}.` }], structured: found };
346
+ },
347
+ });
348
+ }
349
+ ```
350
+
351
+ The input schema is either a Standard Schema or a raw JSON Schema object. A Standard Schema is a schema from a library that can also describe itself as JSON Schema: Zod 4.2 or later, ArkType, or Valibot through `toStandardJsonSchema()` from `@valibot/to-json-schema`. A raw schema follows draft 2020-12, or draft 7 when its `$schema` names draft 7. Raw schemas check `format` keywords such as `email` and `date`.
352
+
353
+ `execute` receives the validated input and returns a tool result with three channels:
354
+
355
+ - **`content`** is the text and images the model reads.
356
+ - **`details`** is for your logs and user interface; the model never sees it.
357
+ - **`structured`** is typed data for your code, such as the order above.
358
+
359
+ `defineTool()` checks the tool once, when you call it. A name outside the tool-name rule, 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`, throws an `SdkError`. So does a schema that does not compile.
360
+
361
+ ## A failed call becomes an error the model can fix
362
+
363
+ Every tool call runs the same steps in order: find the tool by name, coerce the arguments, validate them, give `repair` one chance, then run `execute`. A failure the model caused, at any step, returns an error result to the model and throws nothing. When the model sends `"forty-two"` as the order number, it reads this:
364
+
365
+ ```text
366
+ The arguments for tool "lookup_order" are invalid:
367
+ - /order: Invalid input: expected number, received string
368
+ Received arguments: {"order":"forty-two"}
369
+ Do not substitute a mock, a placeholder or invented data for this tool's result. Fix the call, try another approach, or tell the user what failed.
370
+ ```
371
+
372
+ Each failing field appears as its JSON Pointer path, so the model knows exactly what to fix. The last line is there because agents have been seen to answer a failed tool by inventing a result. Three options on the tool and one flag on your own result change what happens:
373
+
374
+ - **`repair`** receives invalid input and its issues, and returns fixed input to validate again, or `undefined` to report the failure.
375
+ - **`formatError`** builds the model's content for a failed call in place of the default text.
376
+ - **`redactErrors: true`** shows the model a fixed line when `execute` throws, and keeps the thrown message in the result's `details`. Use it when error messages may hold secrets, such as connection strings.
377
+ - **`isError: true`** on your own result marks a failure you report yourself, such as an order that doesn't exist.
378
+
379
+ The model also sees an error for a tool name that doesn't exist, with the list of real ones. A response that stopped at its output limit runs none of its tool calls, because their arguments may be cut short; the model is asked to send each call again. A response that ended in an error or was aborted runs none of its calls either, and once the run is cancelled no further call starts.
380
+
381
+ ## Arguments are coerced by three rules
382
+
383
+ Models sometimes send a number as a string. Before validation, the SDK converts these values, and nothing else:
384
+
385
+ 1. A string holding JSON becomes the object or array it encodes, where the schema expects an object or an array.
386
+ 2. A string holding a decimal number becomes that number, where the schema expects a number, or an integer when the number is whole. A whole number beyond 2^53 stays a string, because JavaScript would round it to a different number.
387
+ 3. The string `"true"` or `"false"` becomes a boolean, where the schema expects a boolean.
388
+
389
+ The rules reach nested values through `properties` and `items`, and only where the schema names a single type. A value that already has the expected type is never changed.
390
+
391
+ ## Report what a write did with an outcome
392
+
393
+ A tool that changes the world, such as a refund, declares `effect: { kind: "write" }`. A tool without it counts as read-only, so it is safe to run again after a crash. The optional `businessKey` names the real-world operation, such as `refund:42`, so a retry is recognised as the same refund.
394
+
395
+ Such a tool returns an `outcome` beside its content. An outcome says which of five things happened: `applied`, `not_applied`, `compensated`, `partial` or `unknown`. It also says what the model should do next and whether a retry is safe. This refund tool reports a declined refund:
396
+
397
+ ```ts
398
+ return { ...base, kind: "not_applied", retry: "never", applied: [], reason: reply.code, next };
399
+ ```
400
+
401
+ The model reads the outcome first, as a sentence and as JSON, and then your content. For the declined refund the sentence begins "The refund_create call did not take effect, and nothing changed." Every kind except `applied` marks the result as an error. An outcome that breaks a rule, such as a retry its kind doesn't allow, throws an `SdkError`.
402
+
403
+ ## End the run with `outputTool()`, or ask with `clarificationTool()`
404
+
405
+ `outputTool({ name, schema })` turns the run's final answer into a tool call. Pass it to `run()` as `output`. A call whose input passes the schema ends the run `done`, and the validated answer is `result.output`. A call that fails the schema returns the issues to the model, which can correct its answer and call again. If the model answers in text instead, or another tool returns `terminate: true`, the run still ends `done`, with `result.output` undefined. The output tool must keep the default `exposure`, because the model has to be sent it.
406
+
407
+ `clarificationTool()` gives the model a tool named `ask_user` that takes one `question`. Pass `{ name }` to call it something else. Once the model calls it, the run signs a pending request of kind `clarification` with the question in `question`, emits `approval_request`, and ends with `stopReason: "clarification_requested"` once the step's other calls have their results. The asking call has no result yet. Pass the user's answer to `continueRun()` as `{ requestId, answer }`, and the model reads the answer as that call's result. Any tool whose result carries `pause: { kind: "clarification", question }` pauses the same way. When a gate also paused a call in the same step, the run ends `awaiting_approval`, with both requests in `pending` in the model's order.
408
+
409
+ ## A step's tool calls run in parallel
410
+
411
+ When the model asks for several tools in one response, the run checks them one at a time, in the order the model sent them, and then starts them all together. Results are added to the transcript in the model's order, whichever call finishes first, and a result is added as soon as every result before it is in. Three settings on a tool change the schedule:
412
+
413
+ - **`executionMode: "sequential"`** makes every call in that step run one at a time, in the model's order. Use it for a tool that depends on the calls around it. One call to a sequential tool is enough: its whole step runs in sequence, including calls to other tools, even when that call itself fails validation.
414
+ - **`resourceKey(input)`** returns a string that names what a call touches, such as a file path. Calls in one step with the same key never run at the same time, even when they come from different tools, and they run in the model's order. Calls with different keys, or no key, still run together.
415
+ - **`readOnlyHint`**, set in `annotations`, says that a tool changes nothing. It affects scheduling only when the tool is also `firstParty: true` and declares no `effect`. A read-only call doesn't wait for other read-only calls that share its key, though it still waits for a write before it, and a write waits for the reads before it. A tool from an MCP server stays `firstParty: false`, so its hint is ignored: the hint is a claim by whoever runs the server.
416
+
417
+ Every tool gets a `ctx.signal` that fires when the run is aborted. It also fires when a sibling call in the same step throws a programmer error, an `SdkError` such as a malformed result, because the run stops there. A call still waiting for its key never starts after the signal fires and gets an error result instead. The run waits for the other calls to return, passes on their results in the model's order (calls after the failing one that had already run included), and then throws, so pass the signal on to your own I/O. A sibling's error result, one the model can read and answer, such as invalid input or a tool that threw, cancels nothing.
418
+
419
+ ## `SdkError` marks a mistake in your code
420
+
421
+ The SDK throws only for programmer errors, never for a failure the model caused. `isSdkError(error)` recognises the error, and its `code` says why:
422
+
423
+ - **`invalid_tool_definition`**: a tool's name, description, schema, exposure, `executionMode`, `resourceKey` or `progressKey` is unusable, or two tools share a name.
424
+ - **`invalid_tool_result`**: `execute` returned something other than a tool result, or an invalid outcome. A text block needs a string `text`, and an image block a string `mediaType` and `data`. The run's `result` rejects with this error, and iterating the run throws it after the last event.
425
+ - **`invalid_run_options`**: `run()` or `continueRun()` got a model that isn't from `createModel()`, a `maxSteps` that isn't a positive integer, an output tool whose `exposure` isn't `"direct"`, a `budgetUsd` that isn't a non-negative number, a `progress` threshold that isn't a positive integer, or a `depth` or `maxDepth` that isn't a whole number. `continueRun()` also throws it for a context it can't resume, such as one whose waiting call lost its pending request.
426
+ - **`max_depth_exceeded`**: a tool started a run nested deeper than `maxDepth` allows.
427
+ - **`undelivered_message`**: `steer()` or `followUp()` rejects with it when the run ended before it could apply the message.
428
+ - **`invalid_model_stream`**: a model's stream ended without a final message, which only a broken adapter does.
429
+ Hooks add two `SdkError` codes:
430
+
431
+ - **`invalid_hook_result`**: an interceptor returned something its type forbids, such as a gate that returned no decision, an `activeTools` list that names no tool, or a replacement input that fails the tool's schema. The run's `result` rejects with this error.
432
+ - **`hook_failed`**: an interceptor threw while the run fails closed. The run catches it and reports a `hook` error result, so it never reaches your code.
433
+ - **`run_stopped`**: the error is a `RunStoppedError` from `runOrThrow()`.
434
+ - **`unexpected_model_call`**: the error is an `UnexpectedModelCallError` from `ScriptedModel`.
16
435
 
17
436
  ## Test against a strict scripted model
18
437
 
19
438
  `ScriptedModel` plays back the responses you script, one per model call. It fails loudly when your test's expectations drift:
20
439
 
21
- - **Too many calls throw.** A call past the last scripted step throws `UnexpectedModelCallError`.
22
- - **Unused steps fail.** `assertComplete()` throws if any step was never called; call it when the test ends.
440
+ - **Too many calls throw.** A call past the last scripted step throws `UnexpectedModelCallError`, an `SdkError` with code `unexpected_model_call`. Behind `createModel()`, the gateway turns that throw into a failed call, so a run ends `error` instead of throwing.
441
+ - **`assertComplete()` catches both drifts.** It throws if any step was never called, or if a call came after the last step. Call it when the test ends, so an over-run fails the test even when the run swallowed it.
23
442
  - **Requests are snapshots.** `calls` holds a frozen copy of each request, taken when the call was made, so later changes to your conversation never show up in it.
24
443
  - **Streams look real.** Text, reasoning and tool-call input arrive in small pieces (4 characters by default), and an abort is checked between pieces.
25
444
 
@@ -41,7 +460,7 @@ A step is either a fixed response or a function that builds one from the request
41
460
 
42
461
  ## Tests give the same result every run
43
462
 
44
- Nothing in the testing export reads the system clock or `Math.random()`. `fixedClock(start, stepMs)` returns a clock that advances by a fixed step, and `sequentialIds(prefix)` returns `prefix-1`, `prefix-2` and so on. For random numbers you can repeat, import `seededRandom(seed)` from `@buildanagent/gateway/testing`. The same script with the same clock and ids streams the same events every time.
463
+ Nothing in the testing export reads the system clock or `Math.random()`. `fixedClock(start, stepMs)` returns a clock that advances by a fixed step, and `sequentialIds(prefix)` returns `prefix-1`, `prefix-2` and so on. Pass them to `run()` as `clock` and `idGenerator`. For random numbers you can repeat, import `seededRandom(seed)` from `@buildanagent/gateway/testing`. The same script with the same clock and ids streams the same events every time, timestamps and run id included.
45
464
 
46
465
  Start each test file with `import "@buildanagent/gateway/testing/setup"`, which keeps the test offline.
47
466
 
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The USD budget (D9): the loop projects each call's cost before it sends the call, and ends the run `budget` when
3
+ * the spend so far plus that projection would pass the cap. The projection is the gateway's `projectCallCost()`, the
4
+ * same formula a caller uses outside the loop, so the loop's check and a caller's agree.
5
+ */
6
+ import { type Cost, type Model } from "@buildanagent/gateway";
7
+ import type { RunError } from "./result.js";
8
+ /** What a budget check decides before one call. */
9
+ export type BudgetVerdict = {
10
+ readonly kind: "allow";
11
+ } | {
12
+ readonly kind: "exceeded";
13
+ readonly reason: string;
14
+ readonly spentUsd: number;
15
+ readonly projectedUsd: number;
16
+ } | {
17
+ readonly kind: "unknown";
18
+ readonly error: RunError;
19
+ };
20
+ /** Checks the `budgetUsd` option: a finite number of dollars that isn't negative. */
21
+ export declare function checkBudgetOption(budgetUsd: unknown): number | undefined;
22
+ /**
23
+ * The refusal a budgeted run starts with when its model has no price, or `undefined` when the price is known. A
24
+ * budget can't be enforced against a price that is not there, and pricing the calls at zero would let the run spend
25
+ * without bound (D4).
26
+ */
27
+ export declare function unknownPriceError(model: Model): RunError | undefined;
28
+ /**
29
+ * Decides whether the next call may go out. `spent` is what the run's earlier calls cost, and `projected` is what
30
+ * `projectCallCost()` says the next call can cost at most. A cost that is unknown ends the run with `unknown_price`
31
+ * and never counts as zero.
32
+ */
33
+ export declare function checkBudget(budgetUsd: number, spent: Cost | undefined, projected: Cost): BudgetVerdict;
package/dist/budget.js ADDED
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The USD budget (D9): the loop projects each call's cost before it sends the call, and ends the run `budget` when
3
+ * the spend so far plus that projection would pass the cap. The projection is the gateway's `projectCallCost()`, the
4
+ * same formula a caller uses outside the loop, so the loop's check and a caller's agree.
5
+ */
6
+ import { emptyUsage } from "@buildanagent/gateway";
7
+ import { SdkError } from "./errors.js";
8
+ /** Checks the `budgetUsd` option: a finite number of dollars that isn't negative. */
9
+ export function checkBudgetOption(budgetUsd) {
10
+ if (budgetUsd === undefined)
11
+ return undefined;
12
+ if (typeof budgetUsd !== "number" || !Number.isFinite(budgetUsd) || budgetUsd < 0) {
13
+ throw new SdkError("invalid_run_options", `budgetUsd must be a finite number of dollars, 0 or more, got ${String(budgetUsd)}`);
14
+ }
15
+ return budgetUsd;
16
+ }
17
+ /**
18
+ * The refusal a budgeted run starts with when its model has no price, or `undefined` when the price is known. A
19
+ * budget can't be enforced against a price that is not there, and pricing the calls at zero would let the run spend
20
+ * without bound (D4).
21
+ */
22
+ export function unknownPriceError(model) {
23
+ const probe = model.price({ ...emptyUsage(), uncachedInput: 1 });
24
+ if (probe.total !== null)
25
+ return undefined;
26
+ const { provider, id } = model.ref;
27
+ return {
28
+ kind: "unknown_price",
29
+ message: `the price of ${provider}/${id} is unknown, so a run with a budgetUsd can't check its spend; add the model to a catalog or drop the budget`,
30
+ };
31
+ }
32
+ function unknownCost(what) {
33
+ return { kind: "unknown_price", message: `${what} unknown, so the budget can't be checked` };
34
+ }
35
+ /**
36
+ * Decides whether the next call may go out. `spent` is what the run's earlier calls cost, and `projected` is what
37
+ * `projectCallCost()` says the next call can cost at most. A cost that is unknown ends the run with `unknown_price`
38
+ * and never counts as zero.
39
+ */
40
+ export function checkBudget(budgetUsd, spent, projected) {
41
+ if (spent?.total === null)
42
+ return { kind: "unknown", error: unknownCost("an earlier call's cost is") };
43
+ if (projected.total === null)
44
+ return { kind: "unknown", error: unknownCost("the next call's projected cost is") };
45
+ const spentUsd = spent?.total ?? 0;
46
+ if (spentUsd + projected.total <= budgetUsd)
47
+ return { kind: "allow" };
48
+ const reason = `the run has spent ${dollars(spentUsd)} and the next call can cost up to ${dollars(projected.total)}, which passes the budget of ${dollars(budgetUsd)}`;
49
+ return { kind: "exceeded", reason, spentUsd, projectedUsd: projected.total };
50
+ }
51
+ /** A dollar amount for a message, to six significant digits, so a float sum doesn't print as $0.054000000000000006. */
52
+ function dollars(usd) {
53
+ return `$${Number(usd.toPrecision(6))}`;
54
+ }
55
+ //# sourceMappingURL=budget.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAa,UAAU,EAAc,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AASvC,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,SAAkB;IAClD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,QAAQ,CAChB,qBAAqB,EACrB,gEAAgE,MAAM,CAAC,SAAS,CAAC,EAAE,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAY;IAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,UAAU,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC;IACjE,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC;IACnC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,gBAAgB,QAAQ,IAAI,EAAE,6GAA6G;KACrJ,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,IAAI,0CAA0C,EAAE,CAAC;AAC/F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,KAAuB,EAAE,SAAe;IACrF,IAAI,KAAK,EAAE,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,2BAA2B,CAAC,EAAE,CAAC;IACvG,IAAI,SAAS,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,mCAAmC,CAAC,EAAE,CAAC;IAClH,MAAM,QAAQ,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,GAAG,SAAS,CAAC,KAAK,IAAI,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACtE,MAAM,MAAM,GAAG,qBAAqB,OAAO,CAAC,QAAQ,CAAC,qCAAqC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,gCAAgC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;IACvK,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;AAC/E,CAAC;AAED,uHAAuH;AACvH,SAAS,OAAO,CAAC,GAAW;IAC1B,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC1C,CAAC","sourcesContent":["/**\n * The USD budget (D9): the loop projects each call's cost before it sends the call, and ends the run `budget` when\n * the spend so far plus that projection would pass the cap. The projection is the gateway's `projectCallCost()`, the\n * same formula a caller uses outside the loop, so the loop's check and a caller's agree.\n */\nimport { type Cost, emptyUsage, type Model } from \"@buildanagent/gateway\";\nimport { SdkError } from \"./errors.js\";\nimport type { RunError } from \"./result.js\";\n\n/** What a budget check decides before one call. */\nexport type BudgetVerdict =\n | { readonly kind: \"allow\" }\n | { readonly kind: \"exceeded\"; readonly reason: string; readonly spentUsd: number; readonly projectedUsd: number }\n | { readonly kind: \"unknown\"; readonly error: RunError };\n\n/** Checks the `budgetUsd` option: a finite number of dollars that isn't negative. */\nexport function checkBudgetOption(budgetUsd: unknown): number | undefined {\n if (budgetUsd === undefined) return undefined;\n if (typeof budgetUsd !== \"number\" || !Number.isFinite(budgetUsd) || budgetUsd < 0) {\n throw new SdkError(\n \"invalid_run_options\",\n `budgetUsd must be a finite number of dollars, 0 or more, got ${String(budgetUsd)}`,\n );\n }\n return budgetUsd;\n}\n\n/**\n * The refusal a budgeted run starts with when its model has no price, or `undefined` when the price is known. A\n * budget can't be enforced against a price that is not there, and pricing the calls at zero would let the run spend\n * without bound (D4).\n */\nexport function unknownPriceError(model: Model): RunError | undefined {\n const probe = model.price({ ...emptyUsage(), uncachedInput: 1 });\n if (probe.total !== null) return undefined;\n const { provider, id } = model.ref;\n return {\n kind: \"unknown_price\",\n message: `the price of ${provider}/${id} is unknown, so a run with a budgetUsd can't check its spend; add the model to a catalog or drop the budget`,\n };\n}\n\nfunction unknownCost(what: string): RunError {\n return { kind: \"unknown_price\", message: `${what} unknown, so the budget can't be checked` };\n}\n\n/**\n * Decides whether the next call may go out. `spent` is what the run's earlier calls cost, and `projected` is what\n * `projectCallCost()` says the next call can cost at most. A cost that is unknown ends the run with `unknown_price`\n * and never counts as zero.\n */\nexport function checkBudget(budgetUsd: number, spent: Cost | undefined, projected: Cost): BudgetVerdict {\n if (spent?.total === null) return { kind: \"unknown\", error: unknownCost(\"an earlier call's cost is\") };\n if (projected.total === null) return { kind: \"unknown\", error: unknownCost(\"the next call's projected cost is\") };\n const spentUsd = spent?.total ?? 0;\n if (spentUsd + projected.total <= budgetUsd) return { kind: \"allow\" };\n const reason = `the run has spent ${dollars(spentUsd)} and the next call can cost up to ${dollars(projected.total)}, which passes the budget of ${dollars(budgetUsd)}`;\n return { kind: \"exceeded\", reason, spentUsd, projectedUsd: projected.total };\n}\n\n/** A dollar amount for a message, to six significant digits, so a float sum doesn't print as $0.054000000000000006. */\nfunction dollars(usd: number): string {\n return `$${Number(usd.toPrecision(6))}`;\n}\n"]}
@@ -0,0 +1,26 @@
1
+ import type { Interceptors } from "./hooks.js";
2
+ /**
3
+ * Joins interceptor objects into one. For a moment that several objects define, the hooks run in the order given,
4
+ * and the result is:
5
+ *
6
+ * - `transformContext`: the messages pass through each hook in turn.
7
+ * - `beforeModelCall`: the patches are merged in order, a later field replacing an earlier one, and each hook sees
8
+ * the system prompt, messages and options the earlier ones set. A field left `undefined` keeps the earlier value.
9
+ * - `afterModelCall`: each hook sees the message the one before returned.
10
+ * - `beforeToolCall`: the strictest decision wins. The first `deny` ends the check, an `ask` beats `allow`, and an
11
+ * input one gate replaces is the input the next gate sees. When a gate asks, the `ask` carries the last
12
+ * replacement, so the pending request is signed over the input the call would run with.
13
+ * - `afterToolCall`: the patches are applied in order, each hook seeing the result so far.
14
+ * - `shouldStop`: the first `stop` wins; failing that, the first `continue`.
15
+ *
16
+ * Each hook's return value is checked as if the hook ran alone, so a wrong shape, such as a gate that returns nothing,
17
+ * throws an `SdkError` with code `invalid_hook_result` whatever the other hooks return. A hook that throws fails the
18
+ * moment it belongs to, because the joined hook is one function. The joined `onFailure` is
19
+ * `"continue"` only when every object sets it to `"continue"`; an object that leaves it unset counts as
20
+ * `"fail_closed"`. One lenient object therefore never loosens the others, and a join of a gate with a lenient audit
21
+ * hook fails closed. Set `"continue"` on all of them, and the gate then fails open too.
22
+ *
23
+ * An object from `blockingApprovals()` passes its handler on to the joined object. Joining two of them throws an
24
+ * `SdkError` with code `invalid_run_options`, because a request can have only one answer.
25
+ */
26
+ export declare function composeInterceptors(...sets: readonly Interceptors[]): Interceptors;