@buildanagent/sdk 0.1.0-alpha.2 → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md 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 tool definitions and the testing export. You can define your tools and their rules now; the loop that calls the model and runs them comes next, with hooks, approvals and budgets.
5
+ As of November 2026 the package holds the loop, tool definitions and the testing export. Hooks, approvals and budgets come next.
6
6
 
7
7
  ## Install the alpha with `pnpm add @buildanagent/sdk@alpha`
8
8
 
@@ -16,6 +16,74 @@ Both packages always share one version, and the SDK depends on that exact versio
16
16
 
17
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
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 never sent to the model, and a call to it 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, and `fatal` otherwise.
46
+ - **`aborted`**: you aborted the run.
47
+ - **`stopped`**: a tool from `clarificationTool()` asked the user a question, and `result.stoppedBy` is `"clarification"`.
48
+
49
+ `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.
50
+
51
+ 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.
52
+
53
+ ### `runOrThrow()` turns an unfinished run into an exception
54
+
55
+ 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:
56
+
57
+ ```ts
58
+ const result = await runOrThrow(run({ model, system, input }));
59
+ ```
60
+
61
+ ### Continue a conversation with `continueRun()`
62
+
63
+ `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 and the messages. A run that stopped at `max_steps` continues with the model reading its last tool results. 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.
64
+
65
+ ### Abort a run with `run.abort()` or a signal
66
+
67
+ `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.
68
+
69
+ 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.
70
+
71
+ ## A run streams one closed set of events
72
+
73
+ 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.
74
+
75
+ 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:
76
+
77
+ - **`run_start`** comes first, with the SDK's version, the spec version and the model.
78
+ - **`step_start`** and **`step_end`** wrap one model call and its tool calls; `step_end.stopCheck` says whether the run goes on.
79
+ - **`model_call_start`** carries the request, and **`model_call_end`** the final message.
80
+ - **`tool_call_start`**, **`tool_call_update`** and **`tool_call_end`** follow each tool call; `tool_call_end.result` is what the model reads.
81
+ - **`retry`** reports a failed request the gateway is retrying, and **`warning`** reports a reached cap or a model warning.
82
+ - **`error`** and **`abort`** report a failed call and an abort request.
83
+ - **`agent_settled`** fires once nothing is running any more, retries and tools included. **`run_end`** follows it and carries the result.
84
+
85
+ `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.
86
+
19
87
  ## Define a tool with `defineTool()`
20
88
 
21
89
  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:
@@ -89,23 +157,37 @@ The model reads the outcome first, as a sentence and as JSON, and then your cont
89
157
 
90
158
  ## End the run with `outputTool()`, or ask with `clarificationTool()`
91
159
 
92
- `outputTool({ name, schema })` turns the run's final answer into a tool call. A call whose input passes the schema ends the run, and the validated answer is the result's `structured` value. A call that fails the schema returns the issues to the model, which can correct its answer and call again.
160
+ `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.
161
+
162
+ `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 ends with `stopReason: "stopped"` and `stoppedBy: "clarification"`, and the question is the call's input in `result.messages`. To go on, add the user's answer to `result.context` as a user message and pass the context to `continueRun()`.
163
+
164
+ ## A step's tool calls run in parallel
165
+
166
+ 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:
167
+
168
+ - **`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.
169
+ - **`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.
170
+ - **`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.
93
171
 
94
- `clarificationTool()` gives the model a tool named `ask_user` that takes one `question`. Its result carries the question as a pause, so the run can wait for the user's answer. Pass `{ name }` to call it something else.
172
+ 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.
95
173
 
96
174
  ## `SdkError` marks a mistake in your code
97
175
 
98
176
  The SDK throws only for programmer errors, never for a failure the model caused. `isSdkError(error)` recognises the error, and its `code` says why:
99
177
 
100
- - **`invalid_tool_definition`**: a tool's name, description or schema is unusable, or two tools share a name.
101
- - **`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`.
178
+ - **`invalid_tool_definition`**: a tool's name, description, schema, exposure, `executionMode` or `resourceKey` is unusable, or two tools share a name.
179
+ - **`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.
180
+ - **`invalid_run_options`**: `run()` or `continueRun()` got a model that isn't from `createModel()`, a `maxSteps` that isn't a positive integer, or an output tool whose `exposure` isn't `"direct"`.
181
+ - **`invalid_model_stream`**: a model's stream ended without a final message, which only a broken adapter does.
182
+ - **`run_stopped`**: the error is a `RunStoppedError` from `runOrThrow()`.
183
+ - **`unexpected_model_call`**: the error is an `UnexpectedModelCallError` from `ScriptedModel`.
102
184
 
103
185
  ## Test against a strict scripted model
104
186
 
105
187
  `ScriptedModel` plays back the responses you script, one per model call. It fails loudly when your test's expectations drift:
106
188
 
107
- - **Too many calls throw.** A call past the last scripted step throws `UnexpectedModelCallError`.
108
- - **Unused steps fail.** `assertComplete()` throws if any step was never called; call it when the test ends.
189
+ - **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.
190
+ - **`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.
109
191
  - **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.
110
192
  - **Streams look real.** Text, reasoning and tool-call input arrive in small pieces (4 characters by default), and an abort is checked between pieces.
111
193
 
@@ -127,7 +209,7 @@ A step is either a fixed response or a function that builds one from the request
127
209
 
128
210
  ## Tests give the same result every run
129
211
 
130
- 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.
212
+ 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.
131
213
 
132
214
  Start each test file with `import "@buildanagent/gateway/testing/setup"`, which keeps the test offline.
133
215
 
package/dist/errors.d.ts CHANGED
@@ -1,19 +1,40 @@
1
1
  /**
2
2
  * `SdkError`: the SDK's error for programmer errors, such as a tool definition that breaks the name rule or a tool
3
3
  * that returns something other than a tool result. A failure the model caused, such as invalid tool input, is never
4
- * thrown: the tool pipeline returns it to the model as an error result.
4
+ * thrown: the tool pipeline returns it to the model as an error result. Two subclasses keep their own names:
5
+ * `RunStoppedError`, which `runOrThrow()` throws for a run that did not finish, and the testing export's
6
+ * `UnexpectedModelCallError`.
5
7
  */
8
+ import type { Context, UnfinishedResult } from "./result.js";
6
9
  /** Why an `SdkError` was thrown. */
7
- export type SdkErrorCode = "invalid_tool_definition" | "invalid_tool_result";
10
+ export type SdkErrorCode = "invalid_tool_definition" | "invalid_tool_result" | "invalid_run_options" | "invalid_model_stream" | "run_stopped" | "unexpected_model_call";
8
11
  /**
9
- * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description or schema
10
- * is unusable, or two tools share a name. `invalid_tool_result`: a tool's `execute` returned a malformed result or
11
- * write outcome.
12
+ * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description, schema,
13
+ * exposure, `executionMode` or `resourceKey` is unusable, or two tools share a name. `invalid_tool_result`: a tool's
14
+ * `execute` returned a malformed result or write outcome. `invalid_run_options`: `run()` or `continueRun()` got an
15
+ * option it can't use, such as a model that isn't from `createModel()`. `invalid_model_stream`: a model's stream ended
16
+ * without a final message. `run_stopped`: `runOrThrow()` was given a run that did not finish (a `RunStoppedError`).
17
+ * `unexpected_model_call`: a `ScriptedModel` was called more times than its script allows (an
18
+ * `UnexpectedModelCallError`).
12
19
  */
13
20
  export declare class SdkError extends Error {
14
- readonly name = "SdkError";
21
+ readonly name: string;
15
22
  readonly code: SdkErrorCode;
16
23
  constructor(code: SdkErrorCode, message: string, options?: ErrorOptions);
17
24
  }
18
25
  /** True for an `SdkError`, including one from another copy of the package. */
19
26
  export declare function isSdkError(error: unknown): error is SdkError;
27
+ /**
28
+ * Thrown by `runOrThrow()` for a run that ended any way other than `done`, such as one that reached `maxSteps`. It
29
+ * carries the whole result, and the context to continue from. It is an `SdkError` with code `run_stopped`.
30
+ */
31
+ export declare class RunStoppedError extends SdkError {
32
+ readonly name = "RunStoppedError";
33
+ readonly stopReason: UnfinishedResult["stopReason"];
34
+ readonly result: UnfinishedResult;
35
+ /** The conversation so far, ready for `continueRun()`. */
36
+ readonly context: Context;
37
+ constructor(result: UnfinishedResult);
38
+ /** True for a `RunStoppedError`, including one from another copy of the package. Use it in place of `instanceof`. */
39
+ static isInstance(error: unknown): error is RunStoppedError;
40
+ }
package/dist/errors.js CHANGED
@@ -1,14 +1,13 @@
1
- /**
2
- * `SdkError`: the SDK's error for programmer errors, such as a tool definition that breaks the name rule or a tool
3
- * that returns something other than a tool result. A failure the model caused, such as invalid tool input, is never
4
- * thrown: the tool pipeline returns it to the model as an error result.
5
- */
6
1
  // A registered symbol, so the guard still works when two copies of the package are bundled.
7
2
  const SDK_ERROR = Symbol.for("buildanagent.sdk.SdkError");
8
3
  /**
9
- * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description or schema
10
- * is unusable, or two tools share a name. `invalid_tool_result`: a tool's `execute` returned a malformed result or
11
- * write outcome.
4
+ * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description, schema,
5
+ * exposure, `executionMode` or `resourceKey` is unusable, or two tools share a name. `invalid_tool_result`: a tool's
6
+ * `execute` returned a malformed result or write outcome. `invalid_run_options`: `run()` or `continueRun()` got an
7
+ * option it can't use, such as a model that isn't from `createModel()`. `invalid_model_stream`: a model's stream ended
8
+ * without a final message. `run_stopped`: `runOrThrow()` was given a run that did not finish (a `RunStoppedError`).
9
+ * `unexpected_model_call`: a `ScriptedModel` was called more times than its script allows (an
10
+ * `UnexpectedModelCallError`).
12
11
  */
13
12
  export class SdkError extends Error {
14
13
  name = "SdkError";
@@ -23,4 +22,27 @@ export class SdkError extends Error {
23
22
  export function isSdkError(error) {
24
23
  return typeof error === "object" && error !== null && error[SDK_ERROR] === true;
25
24
  }
25
+ const RUN_STOPPED_ERROR = Symbol.for("buildanagent.sdk.RunStoppedError");
26
+ /**
27
+ * Thrown by `runOrThrow()` for a run that ended any way other than `done`, such as one that reached `maxSteps`. It
28
+ * carries the whole result, and the context to continue from. It is an `SdkError` with code `run_stopped`.
29
+ */
30
+ export class RunStoppedError extends SdkError {
31
+ name = "RunStoppedError";
32
+ stopReason;
33
+ result;
34
+ /** The conversation so far, ready for `continueRun()`. */
35
+ context;
36
+ constructor(result) {
37
+ super("run_stopped", `the run stopped with "${result.stopReason}" after ${result.steps} model calls`);
38
+ this.stopReason = result.stopReason;
39
+ this.result = result;
40
+ this.context = result.context;
41
+ Object.defineProperty(this, RUN_STOPPED_ERROR, { value: true });
42
+ }
43
+ /** True for a `RunStoppedError`, including one from another copy of the package. Use it in place of `instanceof`. */
44
+ static isInstance(error) {
45
+ return (typeof error === "object" && error !== null && error[RUN_STOPPED_ERROR] === true);
46
+ }
47
+ }
26
48
  //# sourceMappingURL=errors.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,4FAA4F;AAC5F,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACf,IAAI,GAAG,UAAU,CAAC;IAC3B,IAAI,CAAe;IAE5B,YAAY,IAAkB,EAAE,OAAe,EAAE,OAAsB;QACrE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AAC/G,CAAC","sourcesContent":["/**\n * `SdkError`: the SDK's error for programmer errors, such as a tool definition that breaks the name rule or a tool\n * that returns something other than a tool result. A failure the model caused, such as invalid tool input, is never\n * thrown: the tool pipeline returns it to the model as an error result.\n */\n\n/** Why an `SdkError` was thrown. */\nexport type SdkErrorCode = \"invalid_tool_definition\" | \"invalid_tool_result\";\n\n// A registered symbol, so the guard still works when two copies of the package are bundled.\nconst SDK_ERROR = Symbol.for(\"buildanagent.sdk.SdkError\");\n\n/**\n * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description or schema\n * is unusable, or two tools share a name. `invalid_tool_result`: a tool's `execute` returned a malformed result or\n * write outcome.\n */\nexport class SdkError extends Error {\n override readonly name = \"SdkError\";\n readonly code: SdkErrorCode;\n\n constructor(code: SdkErrorCode, message: string, options?: ErrorOptions) {\n super(message, options);\n this.code = code;\n Object.defineProperty(this, SDK_ERROR, { value: true });\n }\n}\n\n/** True for an `SdkError`, including one from another copy of the package. */\nexport function isSdkError(error: unknown): error is SdkError {\n return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[SDK_ERROR] === true;\n}\n"]}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAkBA,4FAA4F;AAC5F,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACf,IAAI,GAAW,UAAU,CAAC;IACnC,IAAI,CAAe;IAE5B,YAAY,IAAkB,EAAE,OAAe,EAAE,OAAsB;QACrE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;AAC/G,CAAC;AAED,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAEzE;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACzB,IAAI,GAAG,iBAAiB,CAAC;IAClC,UAAU,CAAiC;IAC3C,MAAM,CAAmB;IAClC,0DAA0D;IACjD,OAAO,CAAU;IAE1B,YAAY,MAAwB;QAClC,KAAK,CAAC,aAAa,EAAE,yBAAyB,MAAM,CAAC,UAAU,WAAW,MAAM,CAAC,KAAK,cAAc,CAAC,CAAC;QACtG,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAED,qHAAqH;IACrH,MAAM,CAAC,UAAU,CAAC,KAAc;QAC9B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAC9G,CAAC;IACJ,CAAC;CACF","sourcesContent":["/**\n * `SdkError`: the SDK's error for programmer errors, such as a tool definition that breaks the name rule or a tool\n * that returns something other than a tool result. A failure the model caused, such as invalid tool input, is never\n * thrown: the tool pipeline returns it to the model as an error result. Two subclasses keep their own names:\n * `RunStoppedError`, which `runOrThrow()` throws for a run that did not finish, and the testing export's\n * `UnexpectedModelCallError`.\n */\nimport type { Context, UnfinishedResult } from \"./result.js\";\n\n/** Why an `SdkError` was thrown. */\nexport type SdkErrorCode =\n | \"invalid_tool_definition\"\n | \"invalid_tool_result\"\n | \"invalid_run_options\"\n | \"invalid_model_stream\"\n | \"run_stopped\"\n | \"unexpected_model_call\";\n\n// A registered symbol, so the guard still works when two copies of the package are bundled.\nconst SDK_ERROR = Symbol.for(\"buildanagent.sdk.SdkError\");\n\n/**\n * Thrown for a mistake in how the SDK is called. `invalid_tool_definition`: a tool's name, description, schema,\n * exposure, `executionMode` or `resourceKey` is unusable, or two tools share a name. `invalid_tool_result`: a tool's\n * `execute` returned a malformed result or write outcome. `invalid_run_options`: `run()` or `continueRun()` got an\n * option it can't use, such as a model that isn't from `createModel()`. `invalid_model_stream`: a model's stream ended\n * without a final message. `run_stopped`: `runOrThrow()` was given a run that did not finish (a `RunStoppedError`).\n * `unexpected_model_call`: a `ScriptedModel` was called more times than its script allows (an\n * `UnexpectedModelCallError`).\n */\nexport class SdkError extends Error {\n override readonly name: string = \"SdkError\";\n readonly code: SdkErrorCode;\n\n constructor(code: SdkErrorCode, message: string, options?: ErrorOptions) {\n super(message, options);\n this.code = code;\n Object.defineProperty(this, SDK_ERROR, { value: true });\n }\n}\n\n/** True for an `SdkError`, including one from another copy of the package. */\nexport function isSdkError(error: unknown): error is SdkError {\n return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[SDK_ERROR] === true;\n}\n\nconst RUN_STOPPED_ERROR = Symbol.for(\"buildanagent.sdk.RunStoppedError\");\n\n/**\n * Thrown by `runOrThrow()` for a run that ended any way other than `done`, such as one that reached `maxSteps`. It\n * carries the whole result, and the context to continue from. It is an `SdkError` with code `run_stopped`.\n */\nexport class RunStoppedError extends SdkError {\n override readonly name = \"RunStoppedError\";\n readonly stopReason: UnfinishedResult[\"stopReason\"];\n readonly result: UnfinishedResult;\n /** The conversation so far, ready for `continueRun()`. */\n readonly context: Context;\n\n constructor(result: UnfinishedResult) {\n super(\"run_stopped\", `the run stopped with \"${result.stopReason}\" after ${result.steps} model calls`);\n this.stopReason = result.stopReason;\n this.result = result;\n this.context = result.context;\n Object.defineProperty(this, RUN_STOPPED_ERROR, { value: true });\n }\n\n /** True for a `RunStoppedError`, including one from another copy of the package. Use it in place of `instanceof`. */\n static isInstance(error: unknown): error is RunStoppedError {\n return (\n typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[RUN_STOPPED_ERROR] === true\n );\n }\n}\n"]}
@@ -0,0 +1,104 @@
1
+ /**
2
+ * The events a run streams: one closed union in two layers (agent-SDK guide §5). The delta layer streams each content
3
+ * block by its index; the item layer's end events (`model_call_end`, `tool_call_end`, `run_end`) carry the
4
+ * authoritative item, which a session log stores. `AGENT_EVENT_TYPES` lists the union at run time, so a test can
5
+ * check that the loop emits no type the union does not declare.
6
+ */
7
+ import type { AssistantMessage, ContentBlock, DumpedOptions, ModelContext, ModelRef } from "@buildanagent/gateway";
8
+ import type { RunError, RunResult } from "./result.js";
9
+ import type { ToolResult } from "./tools/types.js";
10
+ /** The fields every event carries. `seq` counts the run's events from 0; `stepIndex` counts its model calls from 0. */
11
+ export interface EventBase {
12
+ readonly runId: string;
13
+ readonly seq: number;
14
+ readonly stepIndex: number;
15
+ /** When the event was emitted, from the run's clock, in ISO 8601. */
16
+ readonly timestamp: string;
17
+ }
18
+ /** One model call's request as the loop sends it: the model, the context and the options. */
19
+ export interface ModelCallRequest {
20
+ readonly model: ModelRef;
21
+ readonly context: ModelContext;
22
+ readonly options: DumpedOptions;
23
+ }
24
+ /**
25
+ * Why a `warning` event fired. `max_steps`: the run reached `maxSteps` and stopped. `model_warning`: the model call
26
+ * reported something that did not stop it, such as an option the provider would reject and the adapter dropped.
27
+ */
28
+ export type WarningCode = "max_steps" | "model_warning";
29
+ /** The body of each event, without the fields of `EventBase`. */
30
+ export type AgentEventBody = {
31
+ readonly type: "run_start";
32
+ readonly sdkVersion: string;
33
+ readonly specVersion: "v1";
34
+ /** Reserved for a hash of the run's defaults; empty for now. */
35
+ readonly defaultsHash: string;
36
+ /** Reserved for the SDK's capability names; empty for now. */
37
+ readonly capabilities: readonly string[];
38
+ readonly model: ModelRef;
39
+ } | {
40
+ readonly type: "run_end";
41
+ readonly result: RunResult;
42
+ }
43
+ /** Fires once nothing is running any more, retries and tools included; `run_end` follows it. */
44
+ | {
45
+ readonly type: "agent_settled";
46
+ } | {
47
+ readonly type: "step_start";
48
+ } | {
49
+ readonly type: "step_end";
50
+ readonly stopCheck: "continue" | "stop";
51
+ } | {
52
+ readonly type: "model_call_start";
53
+ readonly request: ModelCallRequest;
54
+ } | {
55
+ readonly type: "model_call_end";
56
+ readonly message: AssistantMessage;
57
+ } | {
58
+ readonly type: "text_start" | "reasoning_start" | "tool_input_start";
59
+ readonly index: number;
60
+ } | {
61
+ readonly type: "text_delta" | "reasoning_delta" | "tool_input_delta";
62
+ readonly index: number;
63
+ readonly delta: string;
64
+ } | {
65
+ readonly type: "text_end" | "reasoning_end" | "tool_input_end";
66
+ readonly index: number;
67
+ readonly block: ContentBlock;
68
+ } | {
69
+ readonly type: "tool_call_start";
70
+ readonly callId: string;
71
+ readonly tool: string;
72
+ readonly input: unknown;
73
+ } | {
74
+ readonly type: "tool_call_update";
75
+ readonly callId: string;
76
+ readonly details: unknown;
77
+ }
78
+ /** `result` is what the model reads for the call. */
79
+ | {
80
+ readonly type: "tool_call_end";
81
+ readonly callId: string;
82
+ readonly result: ToolResult;
83
+ }
84
+ /** The model is retrying a failed request; `attempt` is 1 for the first retry. */
85
+ | {
86
+ readonly type: "retry";
87
+ readonly attempt: number;
88
+ readonly delayMs: number;
89
+ readonly error: string;
90
+ } | {
91
+ readonly type: "warning";
92
+ readonly code: WarningCode;
93
+ readonly detail: string;
94
+ } | {
95
+ readonly type: "error";
96
+ readonly error: RunError;
97
+ } | {
98
+ readonly type: "abort";
99
+ readonly reason?: string;
100
+ };
101
+ /** One event of a run. Switch on `type`: the union is closed, so a `switch` over it can be exhaustive. */
102
+ export type AgentEvent = EventBase & AgentEventBody;
103
+ /** Every `AgentEvent` type. A run emits no type this list lacks. */
104
+ export declare const AGENT_EVENT_TYPES: readonly ["run_start", "step_start", "model_call_start", "retry", "text_start", "text_delta", "text_end", "reasoning_start", "reasoning_delta", "reasoning_end", "tool_input_start", "tool_input_delta", "tool_input_end", "warning", "model_call_end", "tool_call_start", "tool_call_update", "tool_call_end", "step_end", "error", "abort", "agent_settled", "run_end"];
package/dist/events.js ADDED
@@ -0,0 +1,27 @@
1
+ /** Every `AgentEvent` type. A run emits no type this list lacks. */
2
+ export const AGENT_EVENT_TYPES = Object.freeze([
3
+ "run_start",
4
+ "step_start",
5
+ "model_call_start",
6
+ "retry",
7
+ "text_start",
8
+ "text_delta",
9
+ "text_end",
10
+ "reasoning_start",
11
+ "reasoning_delta",
12
+ "reasoning_end",
13
+ "tool_input_start",
14
+ "tool_input_delta",
15
+ "tool_input_end",
16
+ "warning",
17
+ "model_call_end",
18
+ "tool_call_start",
19
+ "tool_call_update",
20
+ "tool_call_end",
21
+ "step_end",
22
+ "error",
23
+ "abort",
24
+ "agent_settled",
25
+ "run_end",
26
+ ]);
27
+ //# sourceMappingURL=events.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AA2EA,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7C,WAAW;IACX,YAAY;IACZ,kBAAkB;IAClB,OAAO;IACP,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,iBAAiB;IACjB,iBAAiB;IACjB,eAAe;IACf,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;IAChB,SAAS;IACT,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,eAAe;IACf,UAAU;IACV,OAAO;IACP,OAAO;IACP,eAAe;IACf,SAAS;CACuC,CAAC,CAAC","sourcesContent":["/**\n * The events a run streams: one closed union in two layers (agent-SDK guide §5). The delta layer streams each content\n * block by its index; the item layer's end events (`model_call_end`, `tool_call_end`, `run_end`) carry the\n * authoritative item, which a session log stores. `AGENT_EVENT_TYPES` lists the union at run time, so a test can\n * check that the loop emits no type the union does not declare.\n */\nimport type { AssistantMessage, ContentBlock, DumpedOptions, ModelContext, ModelRef } from \"@buildanagent/gateway\";\nimport type { RunError, RunResult } from \"./result.js\";\nimport type { ToolResult } from \"./tools/types.js\";\n\n/** The fields every event carries. `seq` counts the run's events from 0; `stepIndex` counts its model calls from 0. */\nexport interface EventBase {\n readonly runId: string;\n readonly seq: number;\n readonly stepIndex: number;\n /** When the event was emitted, from the run's clock, in ISO 8601. */\n readonly timestamp: string;\n}\n\n/** One model call's request as the loop sends it: the model, the context and the options. */\nexport interface ModelCallRequest {\n readonly model: ModelRef;\n readonly context: ModelContext;\n readonly options: DumpedOptions;\n}\n\n/**\n * Why a `warning` event fired. `max_steps`: the run reached `maxSteps` and stopped. `model_warning`: the model call\n * reported something that did not stop it, such as an option the provider would reject and the adapter dropped.\n */\nexport type WarningCode = \"max_steps\" | \"model_warning\";\n\n/** The body of each event, without the fields of `EventBase`. */\nexport type AgentEventBody =\n | {\n readonly type: \"run_start\";\n readonly sdkVersion: string;\n readonly specVersion: \"v1\";\n /** Reserved for a hash of the run's defaults; empty for now. */\n readonly defaultsHash: string;\n /** Reserved for the SDK's capability names; empty for now. */\n readonly capabilities: readonly string[];\n readonly model: ModelRef;\n }\n | { readonly type: \"run_end\"; readonly result: RunResult }\n /** Fires once nothing is running any more, retries and tools included; `run_end` follows it. */\n | { readonly type: \"agent_settled\" }\n | { readonly type: \"step_start\" }\n | { readonly type: \"step_end\"; readonly stopCheck: \"continue\" | \"stop\" }\n | { readonly type: \"model_call_start\"; readonly request: ModelCallRequest }\n | { readonly type: \"model_call_end\"; readonly message: AssistantMessage }\n | { readonly type: \"text_start\" | \"reasoning_start\" | \"tool_input_start\"; readonly index: number }\n | {\n readonly type: \"text_delta\" | \"reasoning_delta\" | \"tool_input_delta\";\n readonly index: number;\n readonly delta: string;\n }\n | {\n readonly type: \"text_end\" | \"reasoning_end\" | \"tool_input_end\";\n readonly index: number;\n readonly block: ContentBlock;\n }\n | { readonly type: \"tool_call_start\"; readonly callId: string; readonly tool: string; readonly input: unknown }\n | { readonly type: \"tool_call_update\"; readonly callId: string; readonly details: unknown }\n /** `result` is what the model reads for the call. */\n | { readonly type: \"tool_call_end\"; readonly callId: string; readonly result: ToolResult }\n /** The model is retrying a failed request; `attempt` is 1 for the first retry. */\n | { readonly type: \"retry\"; readonly attempt: number; readonly delayMs: number; readonly error: string }\n | { readonly type: \"warning\"; readonly code: WarningCode; readonly detail: string }\n | { readonly type: \"error\"; readonly error: RunError }\n | { readonly type: \"abort\"; readonly reason?: string };\n\n/** One event of a run. Switch on `type`: the union is closed, so a `switch` over it can be exhaustive. */\nexport type AgentEvent = EventBase & AgentEventBody;\n\n/** Every `AgentEvent` type. A run emits no type this list lacks. */\nexport const AGENT_EVENT_TYPES = Object.freeze([\n \"run_start\",\n \"step_start\",\n \"model_call_start\",\n \"retry\",\n \"text_start\",\n \"text_delta\",\n \"text_end\",\n \"reasoning_start\",\n \"reasoning_delta\",\n \"reasoning_end\",\n \"tool_input_start\",\n \"tool_input_delta\",\n \"tool_input_end\",\n \"warning\",\n \"model_call_end\",\n \"tool_call_start\",\n \"tool_call_update\",\n \"tool_call_end\",\n \"step_end\",\n \"error\",\n \"abort\",\n \"agent_settled\",\n \"run_end\",\n] as const satisfies readonly AgentEvent[\"type\"][]);\n"]}
package/dist/index.d.ts CHANGED
@@ -1,10 +1,14 @@
1
1
  /**
2
- * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the tools: their definitions,
3
- * schemas, results and write outcomes. The loop, hooks, signed pauses and budgets are planned in the SDK plan §3.3.
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.
4
5
  */
5
- export { isSdkError, SdkError, type SdkErrorCode } from "./errors.js";
6
+ export { isSdkError, RunStoppedError, SdkError, type SdkErrorCode } from "./errors.js";
7
+ 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";
9
+ export { continueRun, type Run, type RunInput, type RunOptions, run, runOrThrow } from "./run.js";
6
10
  export { type ClarificationToolOptions, clarificationTool, defineTool, type OutputToolOptions, outputTool, } from "./tools/define.js";
7
- export type { JsonSchema, SchemaIssue, ToolContext, ToolDefinition, ToolEffect, ToolFailure, ToolResult, ToolSchema, } from "./tools/types.js";
11
+ export type { JsonSchema, SchemaIssue, ToolAnnotations, ToolContext, ToolDefinition, ToolEffect, ToolExecutionMode, ToolExposure, ToolFailure, ToolResult, ToolSchema, } from "./tools/types.js";
8
12
  export type { WriteOutcome } from "./vendor/agent-safety/outcome.js";
9
13
  /** The package's name, `@buildanagent/sdk`. */
10
14
  export declare const SDK_PACKAGE = "@buildanagent/sdk";
package/dist/index.js CHANGED
@@ -1,8 +1,11 @@
1
1
  /**
2
- * `@buildanagent/sdk`: the agent loop over `@buildanagent/gateway`. This entry holds the tools: their definitions,
3
- * schemas, results and write outcomes. The loop, hooks, signed pauses and budgets are planned in the SDK plan §3.3.
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.
4
5
  */
5
- export { isSdkError, SdkError } from "./errors.js";
6
+ export { isSdkError, RunStoppedError, SdkError } from "./errors.js";
7
+ export { AGENT_EVENT_TYPES, } from "./events.js";
8
+ export { continueRun, run, runOrThrow } from "./run.js";
6
9
  export { clarificationTool, defineTool, outputTool, } from "./tools/define.js";
7
10
  /** The package's name, `@buildanagent/sdk`. */
8
11
  export const SDK_PACKAGE = "@buildanagent/sdk";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAqB,MAAM,aAAa,CAAC;AACtE,OAAO,EAEL,iBAAiB,EACjB,UAAU,EAEV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAa3B,+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 tools: their definitions,\n * schemas, results and write outcomes. The loop, hooks, signed pauses and budgets are planned in the SDK plan §3.3.\n */\nexport { isSdkError, SdkError, type SdkErrorCode } from \"./errors.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 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;;;;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;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, 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 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 ADDED
@@ -0,0 +1,38 @@
1
+ /**
2
+ * The step loop: one model call, then the tool calls it asked for, then the stop check, until a stop reason holds
3
+ * (agent-SDK guide §3). The non-streaming result is built from the same run, so there is one loop for both modes.
4
+ *
5
+ * Each step runs transform → before → stream → after → tools → stop. 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.
9
+ */
10
+ import { type Message, type Model, type ModelCallOptions } from "@buildanagent/gateway";
11
+ import type { AgentEventBody } from "./events.js";
12
+ import type { RunResult } from "./result.js";
13
+ import type { Clock } from "./testing/determinism.js";
14
+ import { type AnyTool } from "./tools/pipeline.js";
15
+ /** Everything one run needs, fixed when it starts. */
16
+ export interface LoopSetup {
17
+ readonly runId: string;
18
+ readonly model: Model;
19
+ readonly system: string;
20
+ /** The conversation before this run's own messages. */
21
+ readonly history: readonly Message[];
22
+ /** The messages the run starts by adding, such as the user's input. */
23
+ readonly input: readonly Message[];
24
+ /** The tools the model is sent, in definition order; only these can run. */
25
+ readonly tools: readonly AnyTool[];
26
+ readonly output: AnyTool | undefined;
27
+ readonly maxSteps: number;
28
+ readonly modelOptions: Omit<ModelCallOptions, "signal">;
29
+ readonly signal: AbortSignal;
30
+ readonly clock: Clock;
31
+ }
32
+ /** Sends one event; the run adds the `EventBase` fields. */
33
+ export type Emit = (body: AgentEventBody, stepIndex: number) => void;
34
+ /**
35
+ * Runs the loop to a stop reason and returns the result. It throws only for a programmer error, after the results
36
+ * already received are in the transcript.
37
+ */
38
+ export declare function runLoop(setup: LoopSetup, emit: Emit): Promise<RunResult>;