@buildanagent/sdk 0.1.0-alpha.3 → 0.1.0-alpha.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -6
- package/dist/compose.d.ts +22 -0
- package/dist/compose.js +137 -0
- package/dist/compose.js.map +1 -0
- package/dist/errors.d.ts +12 -7
- package/dist/errors.js +11 -6
- package/dist/errors.js.map +1 -1
- package/dist/events.d.ts +22 -2
- package/dist/events.js +2 -0
- package/dist/events.js.map +1 -1
- package/dist/freeze.d.ts +11 -0
- package/dist/freeze.js +42 -0
- package/dist/freeze.js.map +1 -0
- package/dist/hook-checks.d.ts +31 -0
- package/dist/hook-checks.js +113 -0
- package/dist/hook-checks.js.map +1 -0
- package/dist/hook-runner.d.ts +60 -0
- package/dist/hook-runner.js +169 -0
- package/dist/hook-runner.js.map +1 -0
- package/dist/hooks.d.ts +177 -0
- package/dist/hooks.js +2 -0
- package/dist/hooks.js.map +1 -0
- package/dist/index.d.ts +7 -4
- package/dist/index.js +4 -2
- package/dist/index.js.map +1 -1
- package/dist/loop.d.ts +18 -8
- package/dist/loop.js +191 -29
- package/dist/loop.js.map +1 -1
- package/dist/observers.d.ts +31 -0
- package/dist/observers.js +98 -0
- package/dist/observers.js.map +1 -0
- package/dist/result.d.ts +11 -5
- package/dist/result.js.map +1 -1
- package/dist/run.d.ts +34 -4
- package/dist/run.js +84 -7
- package/dist/run.js.map +1 -1
- package/dist/tools/define.d.ts +3 -2
- package/dist/tools/define.js +10 -2
- package/dist/tools/define.js.map +1 -1
- package/dist/tools/format-error.js +1 -0
- package/dist/tools/format-error.js.map +1 -1
- package/dist/tools/pipeline.d.ts +40 -7
- package/dist/tools/pipeline.js +196 -37
- package/dist/tools/pipeline.js.map +1 -1
- package/dist/tools/scheduler.d.ts +33 -0
- package/dist/tools/scheduler.js +51 -0
- package/dist/tools/scheduler.js.map +1 -0
- package/dist/tools/types.d.ts +41 -5
- package/dist/tools/types.js.map +1 -1
- package/package.json +2 -2
package/dist/tools/types.d.ts
CHANGED
|
@@ -36,7 +36,7 @@ interface FailureBase {
|
|
|
36
36
|
* `redactErrors`, `message` is a fixed line and the thrown message is only in the result's `details`. `truncated`:
|
|
37
37
|
* the response was cut off at the output limit, so the call was not run. `not_run`: the call was not run because the
|
|
38
38
|
* response ended in an error (`response_error`) or was aborted (`response_aborted`), or the run was cancelled before
|
|
39
|
-
* the call started (`run_aborted`).
|
|
39
|
+
* the call started (`run_aborted`), or a sibling call in the same step threw a programmer error (`sibling_failed`).
|
|
40
40
|
*/
|
|
41
41
|
export type ToolFailure = (FailureBase & {
|
|
42
42
|
readonly kind: "unknown_tool";
|
|
@@ -52,7 +52,7 @@ export type ToolFailure = (FailureBase & {
|
|
|
52
52
|
readonly kind: "truncated";
|
|
53
53
|
}) | (FailureBase & {
|
|
54
54
|
readonly kind: "not_run";
|
|
55
|
-
readonly reason: "response_error" | "response_aborted" | "run_aborted";
|
|
55
|
+
readonly reason: "response_error" | "response_aborted" | "run_aborted" | "sibling_failed";
|
|
56
56
|
});
|
|
57
57
|
/**
|
|
58
58
|
* Declares that a tool changes the world, such as sending an email. A tool without `effect` counts as read-only, so
|
|
@@ -63,13 +63,29 @@ export interface ToolEffect<I> {
|
|
|
63
63
|
readonly kind: "write";
|
|
64
64
|
businessKey?(input: I): string;
|
|
65
65
|
}
|
|
66
|
+
/**
|
|
67
|
+
* What a tool says about itself, using the names of the Model Context Protocol's tool annotations. A hint comes from
|
|
68
|
+
* whoever wrote the tool, so the scheduler trusts it only for a tool marked `firstParty`.
|
|
69
|
+
*/
|
|
70
|
+
export interface ToolAnnotations {
|
|
71
|
+
/**
|
|
72
|
+
* The tool changes nothing. With `firstParty`, its calls that share a `resourceKey` run together, unless the tool
|
|
73
|
+
* also declares an `effect`, which wins.
|
|
74
|
+
*/
|
|
75
|
+
readonly readOnlyHint?: boolean;
|
|
76
|
+
}
|
|
77
|
+
/** How a tool's calls are scheduled within one step: `parallel` (the default) or `sequential`. */
|
|
78
|
+
export type ToolExecutionMode = "parallel" | "sequential";
|
|
66
79
|
/** Whether a tool is sent to the model: `direct`, `deferred` or `hidden`. */
|
|
67
80
|
export type ToolExposure = "direct" | "deferred" | "hidden";
|
|
68
81
|
/** What a tool's `execute` receives besides its input. */
|
|
69
82
|
export interface ToolContext {
|
|
70
83
|
readonly runId: string;
|
|
71
84
|
readonly callId: string;
|
|
72
|
-
/**
|
|
85
|
+
/**
|
|
86
|
+
* Fires when the run is aborted, and when a sibling call in the same step throws a programmer error, because the
|
|
87
|
+
* step is then abandoned. A sibling's error result, which the model reads and answers, never fires it.
|
|
88
|
+
*/
|
|
73
89
|
readonly signal: AbortSignal;
|
|
74
90
|
/** How deeply this run is nested inside other agents' tool calls; 0 for a top-level run. */
|
|
75
91
|
readonly depth: number;
|
|
@@ -118,12 +134,32 @@ export interface ToolDefinition<I = unknown, S = unknown> {
|
|
|
118
134
|
readonly inputSchema: ToolSchema<I>;
|
|
119
135
|
/**
|
|
120
136
|
* Whether the model is sent this tool. `direct` (the default) sends it with every model call. A `deferred` or
|
|
121
|
-
* `hidden` tool is left out of every request
|
|
122
|
-
* result.
|
|
137
|
+
* `hidden` tool is left out of every request unless a `beforeModelCall` interceptor names it in `activeTools`, and
|
|
138
|
+
* a call the model makes to a tool that request didn't send gets the unknown-tool error result.
|
|
123
139
|
*/
|
|
124
140
|
readonly exposure?: ToolExposure;
|
|
125
141
|
/** Marks a tool that changes the world. A tool without it counts as read-only. */
|
|
126
142
|
readonly effect?: ToolEffect<I>;
|
|
143
|
+
/**
|
|
144
|
+
* How this tool's calls are scheduled. A step's calls start together by default. A tool that sets `sequential`
|
|
145
|
+
* makes every call of its step run one at a time, in the order the model sent them, because it may depend on the
|
|
146
|
+
* calls around it.
|
|
147
|
+
*/
|
|
148
|
+
readonly executionMode?: ToolExecutionMode;
|
|
149
|
+
/**
|
|
150
|
+
* Names the resource a call touches, such as a file path. Calls in one step that return the same key never run at
|
|
151
|
+
* the same time, in any tool, and run in model order; calls with different keys run together. It must be
|
|
152
|
+
* deterministic and return a string, and it receives the validated input.
|
|
153
|
+
*/
|
|
154
|
+
resourceKey?(input: I): string;
|
|
155
|
+
/** Hints about the tool, such as `readOnlyHint`. They affect scheduling only when `firstParty` is true. */
|
|
156
|
+
readonly annotations?: ToolAnnotations;
|
|
157
|
+
/**
|
|
158
|
+
* True for a tool you wrote, false (the default) for one that came from a server you don't control, such as an MCP
|
|
159
|
+
* tool. Only a first-party tool's `readOnlyHint` changes how its calls are scheduled: read-only calls that share a
|
|
160
|
+
* `resourceKey` run together, and wait only for the writers before them. A tool with an `effect` is never read-only.
|
|
161
|
+
*/
|
|
162
|
+
readonly firstParty?: boolean;
|
|
127
163
|
/**
|
|
128
164
|
* Called once when the input fails its schema, with the coerced input and the issues. Return fixed input to
|
|
129
165
|
* validate again, or `undefined` to report the failure to the model.
|
package/dist/tools/types.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The tool types: what a tool declares, what its `execute` receives and returns, and the failures the pipeline\n * reports to the model (SDK plan §3.3; agent-SDK guide §4).\n */\nimport type { ContentBlock, ModelContent } from \"@buildanagent/gateway\";\nimport type { StandardJSONSchemaV1, StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { Clock } from \"../testing/determinism.js\";\nimport type { WriteOutcome } from \"../vendor/agent-safety/outcome.js\";\n\n/** A JSON Schema object, draft 2020-12 or draft 7, such as `{ type: \"object\", properties: { … } }`. */\nexport type JsonSchema = Readonly<Record<string, unknown>>;\n\n/**\n * A tool's input schema: a Standard Schema that can also describe itself as JSON Schema (Zod 4.2 or later, ArkType,\n * or Valibot through `toStandardJsonSchema()` from `@valibot/to-json-schema`), or a raw JSON Schema object. A raw schema whose `$schema` names draft 7 is checked as draft 7, and\n * any other as draft 2020-12.\n */\nexport type ToolSchema<I> = (StandardSchemaV1<unknown, I> & StandardJSONSchemaV1<unknown, I>) | JsonSchema;\n\n/**\n * One reason a tool input failed its schema. `path` is a JSON Pointer, such as `/items/0/sku`, or `\"\"` for the whole\n * input.\n */\nexport interface SchemaIssue {\n readonly path: string;\n readonly message: string;\n /** The JSON Schema keyword that failed, such as `required`, when the validator reports one. */\n readonly keyword?: string;\n}\n\n/** The fields every tool failure carries. `input` is the arguments the model sent. */\ninterface FailureBase {\n readonly tool: string;\n readonly callId: string;\n readonly input: unknown;\n}\n\n/**\n * A failed tool call, as the error formatter receives it. `unknown_tool`: the model named a tool that doesn't exist.\n * `invalid_input`: the arguments failed the schema, even after repair. `execution_error`: `execute` threw; with\n * `redactErrors`, `message` is a fixed line and the thrown message is only in the result's `details`. `truncated`:\n * the response was cut off at the output limit, so the call was not run. `not_run`: the call was not run because the\n * response ended in an error (`response_error`) or was aborted (`response_aborted`), or the run was cancelled before\n * the call started (`run_aborted`).\n */\nexport type ToolFailure =\n | (FailureBase & { readonly kind: \"unknown_tool\"; readonly availableTools: readonly string[] })\n | (FailureBase & { readonly kind: \"invalid_input\"; readonly issues: readonly SchemaIssue[] })\n | (FailureBase & { readonly kind: \"execution_error\"; readonly message: string; readonly redacted: boolean })\n | (FailureBase & { readonly kind: \"truncated\" })\n | (FailureBase & {\n readonly kind: \"not_run\";\n readonly reason: \"response_error\" | \"response_aborted\" | \"run_aborted\";\n });\n\n/**\n * Declares that a tool changes the world, such as sending an email. A tool without `effect` counts as read-only, so\n * a run that crashes mid-call may safely run it again. `businessKey` names the real-world operation, such as\n * `refund:<order id>`, so the same write is recognised across retries and sessions.\n */\nexport interface ToolEffect<I> {\n readonly kind: \"write\";\n businessKey?(input: I): string;\n}\n\n/** Whether a tool is sent to the model: `direct`, `deferred` or `hidden`. */\nexport type ToolExposure = \"direct\" | \"deferred\" | \"hidden\";\n\n/** What a tool's `execute` receives besides its input. */\nexport interface ToolContext {\n readonly runId: string;\n readonly callId: string;\n
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The tool types: what a tool declares, what its `execute` receives and returns, and the failures the pipeline\n * reports to the model (SDK plan §3.3; agent-SDK guide §4).\n */\nimport type { ContentBlock, ModelContent } from \"@buildanagent/gateway\";\nimport type { StandardJSONSchemaV1, StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { Clock } from \"../testing/determinism.js\";\nimport type { WriteOutcome } from \"../vendor/agent-safety/outcome.js\";\n\n/** A JSON Schema object, draft 2020-12 or draft 7, such as `{ type: \"object\", properties: { … } }`. */\nexport type JsonSchema = Readonly<Record<string, unknown>>;\n\n/**\n * A tool's input schema: a Standard Schema that can also describe itself as JSON Schema (Zod 4.2 or later, ArkType,\n * or Valibot through `toStandardJsonSchema()` from `@valibot/to-json-schema`), or a raw JSON Schema object. A raw schema whose `$schema` names draft 7 is checked as draft 7, and\n * any other as draft 2020-12.\n */\nexport type ToolSchema<I> = (StandardSchemaV1<unknown, I> & StandardJSONSchemaV1<unknown, I>) | JsonSchema;\n\n/**\n * One reason a tool input failed its schema. `path` is a JSON Pointer, such as `/items/0/sku`, or `\"\"` for the whole\n * input.\n */\nexport interface SchemaIssue {\n readonly path: string;\n readonly message: string;\n /** The JSON Schema keyword that failed, such as `required`, when the validator reports one. */\n readonly keyword?: string;\n}\n\n/** The fields every tool failure carries. `input` is the arguments the model sent. */\ninterface FailureBase {\n readonly tool: string;\n readonly callId: string;\n readonly input: unknown;\n}\n\n/**\n * A failed tool call, as the error formatter receives it. `unknown_tool`: the model named a tool that doesn't exist.\n * `invalid_input`: the arguments failed the schema, even after repair. `execution_error`: `execute` threw; with\n * `redactErrors`, `message` is a fixed line and the thrown message is only in the result's `details`. `truncated`:\n * the response was cut off at the output limit, so the call was not run. `not_run`: the call was not run because the\n * response ended in an error (`response_error`) or was aborted (`response_aborted`), or the run was cancelled before\n * the call started (`run_aborted`), or a sibling call in the same step threw a programmer error (`sibling_failed`).\n */\nexport type ToolFailure =\n | (FailureBase & { readonly kind: \"unknown_tool\"; readonly availableTools: readonly string[] })\n | (FailureBase & { readonly kind: \"invalid_input\"; readonly issues: readonly SchemaIssue[] })\n | (FailureBase & { readonly kind: \"execution_error\"; readonly message: string; readonly redacted: boolean })\n | (FailureBase & { readonly kind: \"truncated\" })\n | (FailureBase & {\n readonly kind: \"not_run\";\n readonly reason: \"response_error\" | \"response_aborted\" | \"run_aborted\" | \"sibling_failed\";\n });\n\n/**\n * Declares that a tool changes the world, such as sending an email. A tool without `effect` counts as read-only, so\n * a run that crashes mid-call may safely run it again. `businessKey` names the real-world operation, such as\n * `refund:<order id>`, so the same write is recognised across retries and sessions.\n */\nexport interface ToolEffect<I> {\n readonly kind: \"write\";\n businessKey?(input: I): string;\n}\n\n/**\n * What a tool says about itself, using the names of the Model Context Protocol's tool annotations. A hint comes from\n * whoever wrote the tool, so the scheduler trusts it only for a tool marked `firstParty`.\n */\nexport interface ToolAnnotations {\n /**\n * The tool changes nothing. With `firstParty`, its calls that share a `resourceKey` run together, unless the tool\n * also declares an `effect`, which wins.\n */\n readonly readOnlyHint?: boolean;\n}\n\n/** How a tool's calls are scheduled within one step: `parallel` (the default) or `sequential`. */\nexport type ToolExecutionMode = \"parallel\" | \"sequential\";\n\n/** Whether a tool is sent to the model: `direct`, `deferred` or `hidden`. */\nexport type ToolExposure = \"direct\" | \"deferred\" | \"hidden\";\n\n/** What a tool's `execute` receives besides its input. */\nexport interface ToolContext {\n readonly runId: string;\n readonly callId: string;\n /**\n * Fires when the run is aborted, and when a sibling call in the same step throws a programmer error, because the\n * step is then abandoned. A sibling's error result, which the model reads and answers, never fires it.\n */\n readonly signal: AbortSignal;\n /** How deeply this run is nested inside other agents' tool calls; 0 for a top-level run. */\n readonly depth: number;\n /** The deepest nesting allowed; a tool that starts another agent refuses at this depth. */\n readonly maxDepth: number;\n readonly clock: Clock;\n /** Reports progress for a user interface, such as rows processed so far. The model never sees it. */\n update(details: unknown): void;\n}\n\n/**\n * What a tool returns. `content` is what the model reads, `details` is for logs and user interfaces, and\n * `structured` is typed data for your code; only `content` reaches the model. `isError` marks a failure for the model.\n * `terminate` asks the run to end after this step. `pause` asks the user a question. `outcome` reports what a write\n * did: any kind except `applied` sets `isError`, and the model reads the outcome's sentence and fields before\n * `content`.\n */\nexport interface ToolResult<S = unknown> {\n readonly content: readonly ModelContent[];\n readonly details?: unknown;\n readonly structured?: S;\n readonly isError?: boolean;\n readonly terminate?: boolean;\n readonly pause?: { readonly kind: \"clarification\"; readonly question: string };\n readonly outcome?: WriteOutcome;\n}\n\n/**\n * A tool the model can call. `I` is the input `execute` receives after validation, and `S` the type of `structured`.\n *\n * Every call runs the same steps: the name is resolved, the input is coerced and validated, `repair` gets one chance\n * to fix invalid input, then `execute` runs. A failure the model caused, such as an unknown tool, invalid input or\n * a throwing `execute`, returns an error result to the model. A result that isn't a list of text and image blocks,\n * or that carries an invalid write outcome, throws an `SdkError` with code `invalid_tool_result`.\n */\nexport interface ToolDefinition<I = unknown, S = unknown> {\n /** 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`. */\n readonly name: string;\n readonly description: string;\n /**\n * `function` (the default) runs in your process. The other kinds are for tools that a provider defines or runs:\n * `dynamic` tools have a schema known only at run time, such as one from an MCP server.\n */\n readonly kind?: \"function\" | \"dynamic\" | \"provider-local\" | \"provider-executed\";\n readonly inputSchema: ToolSchema<I>;\n /**\n * Whether the model is sent this tool. `direct` (the default) sends it with every model call. A `deferred` or\n * `hidden` tool is left out of every request unless a `beforeModelCall` interceptor names it in `activeTools`, and\n * a call the model makes to a tool that request didn't send gets the unknown-tool error result.\n */\n readonly exposure?: ToolExposure;\n /** Marks a tool that changes the world. A tool without it counts as read-only. */\n readonly effect?: ToolEffect<I>;\n /**\n * How this tool's calls are scheduled. A step's calls start together by default. A tool that sets `sequential`\n * makes every call of its step run one at a time, in the order the model sent them, because it may depend on the\n * calls around it.\n */\n readonly executionMode?: ToolExecutionMode;\n /**\n * Names the resource a call touches, such as a file path. Calls in one step that return the same key never run at\n * the same time, in any tool, and run in model order; calls with different keys run together. It must be\n * deterministic and return a string, and it receives the validated input.\n */\n resourceKey?(input: I): string;\n /** Hints about the tool, such as `readOnlyHint`. They affect scheduling only when `firstParty` is true. */\n readonly annotations?: ToolAnnotations;\n /**\n * True for a tool you wrote, false (the default) for one that came from a server you don't control, such as an MCP\n * tool. Only a first-party tool's `readOnlyHint` changes how its calls are scheduled: read-only calls that share a\n * `resourceKey` run together, and wait only for the writers before them. A tool with an `effect` is never read-only.\n */\n readonly firstParty?: boolean;\n /**\n * Called once when the input fails its schema, with the coerced input and the issues. Return fixed input to\n * validate again, or `undefined` to report the failure to the model.\n */\n repair?(e: { readonly input: unknown; readonly issues: readonly SchemaIssue[] }): Promise<unknown>;\n /**\n * Builds the content the model reads for a failed call, in place of the default text, which lists the issues and\n * the received arguments and tells the model not to substitute invented data. It runs synchronously; if it throws\n * or returns anything but a list of text and image blocks, the model reads the default text instead.\n */\n formatError?(failure: ToolFailure): readonly ModelContent[];\n /**\n * When true, an error thrown by `execute` reaches the model as a fixed line, and its message goes only to the\n * result's `details`. Default false.\n */\n readonly redactErrors?: boolean;\n execute(input: I, ctx: ToolContext): Promise<ToolResult<S>>;\n}\n\n/** A tool call block from an assistant message. */\nexport type ToolCall = Extract<ContentBlock, { type: \"tool_call\" }>;\n"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@buildanagent/sdk",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.5",
|
|
4
4
|
"description": "The buildanagent SDK: the agent loop, tools, hooks, signed pauses and budgets over the gateway.",
|
|
5
5
|
"license": "Apache-2.0 OR MIT",
|
|
6
6
|
"repository": {
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"dependencies": {
|
|
38
38
|
"@earendil-works/pi-schema": "1.5.2",
|
|
39
39
|
"@standard-schema/spec": "1.1.0",
|
|
40
|
-
"@buildanagent/gateway": "0.1.0-alpha.
|
|
40
|
+
"@buildanagent/gateway": "0.1.0-alpha.5"
|
|
41
41
|
},
|
|
42
42
|
"devDependencies": {
|
|
43
43
|
"@cfworker/json-schema": "4.1.6",
|