@buildanagent/sdk 0.1.0-alpha.4 → 0.1.0-alpha.6
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 +115 -7
- package/dist/budget.d.ts +33 -0
- package/dist/budget.js +55 -0
- package/dist/budget.js.map +1 -0
- package/dist/compose.d.ts +22 -0
- package/dist/compose.js +137 -0
- package/dist/compose.js.map +1 -0
- package/dist/errors.d.ts +7 -2
- package/dist/errors.js +6 -1
- 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 +10 -4
- package/dist/index.js +9 -3
- package/dist/index.js.map +1 -1
- package/dist/loop.d.ts +26 -8
- package/dist/loop.js +241 -35
- 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/progress.d.ts +34 -0
- package/dist/progress.js +139 -0
- package/dist/progress.js.map +1 -0
- package/dist/result.d.ts +28 -5
- package/dist/result.js.map +1 -1
- package/dist/run.d.ts +69 -5
- package/dist/run.js +125 -7
- package/dist/run.js.map +1 -1
- package/dist/tools/define.d.ts +3 -3
- package/dist/tools/define.js +6 -3
- package/dist/tools/define.js.map +1 -1
- package/dist/tools/pipeline.d.ts +29 -7
- package/dist/tools/pipeline.js +48 -14
- package/dist/tools/pipeline.js.map +1 -1
- package/dist/tools/types.d.ts +10 -2
- package/dist/tools/types.js.map +1 -1
- package/dist/vendor/agent-safety/hash.d.ts +16 -0
- package/dist/vendor/agent-safety/hash.js +109 -0
- package/dist/vendor/agent-safety/hash.js.map +1 -0
- package/package.json +2 -2
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observers.js","sourceRoot":"","sources":["../src/observers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The observer channel: delivers each event to every subscriber, in order, without ever letting a subscriber change\n * or break the run. Each subscriber has its own queue, so a slow one delays only itself, and the run waits for the\n * queues to empty only where it must, before `agent_settled` and before the run ends, and then only for a bounded\n * time.\n */\nimport type { AgentEvent } from \"./events.js\";\nimport { frozenCopy } from \"./freeze.js\";\nimport type { Observer } from \"./hooks.js\";\n\n/** The hook name a `hook_error` event gives for a failed observer. */\nexport const OBSERVER_HOOK = \"observer\";\n\ninterface Subscription {\n readonly observer: Observer;\n active: boolean;\n tail: Promise<void>;\n /** The events queued for it and not yet handled. */\n pending: number;\n /** The type of the event it is handling, for the report when it is dropped. */\n current: AgentEvent[\"type\"] | undefined;\n}\n\n/** What a failed observer turns into: the run reports it as a `hook_error` event. */\nexport type ReportFailure = (hook: string, error: unknown) => void;\n\n/** Delivers events to observers. `deliver` and `flush` never throw and never reject. */\nexport class ObserverBus {\n readonly #subscriptions = new Set<Subscription>();\n readonly #report: ReportFailure;\n readonly #timeoutMs: number;\n\n /** `timeoutMs` bounds how long `flush` waits for an observer before it drops it. */\n constructor(report: ReportFailure, timeoutMs: number) {\n this.#report = report;\n this.#timeoutMs = timeoutMs;\n }\n\n /** Starts delivering later events to `observer`, and returns the function that stops it. */\n add(observer: Observer): () => void {\n const subscription: Subscription = {\n observer,\n active: true,\n tail: Promise.resolve(),\n pending: 0,\n current: undefined,\n };\n this.#subscriptions.add(subscription);\n return () => this.#remove(subscription);\n }\n\n /**\n * Queues `event` for every subscriber. They all get one frozen copy, so an observer can neither change the event\n * the run and its iterators hold nor any message or result inside it.\n */\n deliver(event: AgentEvent): void {\n if (this.#subscriptions.size === 0) return;\n const frozen = frozenCopy(event);\n for (const subscription of this.#subscriptions) {\n subscription.pending += 1;\n subscription.tail = subscription.tail.then(() => this.#call(subscription, frozen));\n }\n }\n\n /**\n * Resolves once every subscriber has handled every event delivered so far, including events its failures add. A\n * subscriber that has not caught up within the timeout is dropped and reported, so an observer whose promise never\n * settles can't hold the run open.\n */\n async flush(): Promise<void> {\n let timer: ReturnType<typeof setTimeout> | undefined;\n const expired = new Promise<\"expired\">((resolve) => {\n timer = setTimeout(() => resolve(\"expired\"), this.#timeoutMs);\n });\n try {\n let tails: Promise<void>[];\n do {\n tails = [...this.#subscriptions].map((subscription) => subscription.tail);\n const outcome = await Promise.race([Promise.all(tails), expired]);\n if (outcome === \"expired\") {\n this.#dropLagging();\n return;\n }\n } while ([...this.#subscriptions].some((subscription, index) => subscription.tail !== tails[index]));\n } finally {\n clearTimeout(timer);\n }\n }\n\n #dropLagging(): void {\n const lagging = [...this.#subscriptions].filter((subscription) => subscription.pending > 0);\n for (const subscription of lagging) this.#remove(subscription);\n for (const subscription of lagging) {\n const what = subscription.current === undefined ? \"its events\" : `a ${subscription.current} event`;\n this.#report(\n OBSERVER_HOOK,\n new Error(`an observer did not handle ${what} within ${this.#timeoutMs} ms, so it was removed`),\n );\n }\n }\n\n #remove(subscription: Subscription): void {\n subscription.active = false;\n this.#subscriptions.delete(subscription);\n }\n\n async #call(subscription: Subscription, event: AgentEvent): Promise<void> {\n try {\n // An unsubscribe call stops events that are queued but not yet handled, too.\n if (!subscription.active) return;\n subscription.current = event.type;\n await subscription.observer(event);\n } catch (error) {\n // A failure while handling `hook_error` or `run_end` is dropped: reporting the first would loop for ever, and\n // nothing may follow the second.\n if (subscription.active && event.type !== \"hook_error\" && event.type !== \"run_end\") {\n this.#report(OBSERVER_HOOK, error);\n }\n } finally {\n subscription.pending -= 1;\n subscription.current = undefined;\n }\n }\n}\n"]}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The default progress policy (D11): it ends a run with `no_progress` when the model keeps making the same failing
|
|
3
|
+
* call. Two rules fire it:
|
|
4
|
+
*
|
|
5
|
+
* - **Identical failures.** The latest calls are one tool with one canonical input hash, each returned an error, and
|
|
6
|
+
* there are `maxIdenticalFailures` of them in a row (3 by default).
|
|
7
|
+
* - **One key.** A tool's `progressKey()` gave `maxSameKeyCalls` calls (5 by default) the same key and none of them
|
|
8
|
+
* succeeded. A successful call with that key starts its count again; calls with other keys don't.
|
|
9
|
+
*
|
|
10
|
+
* The policy reads the transcript, so it holds no state a `continueRun()` would have to restore, and it counts only
|
|
11
|
+
* the calls the run itself made. The loop runs it after the caller's `shouldStop`, outside the hook runner, so a
|
|
12
|
+
* caller's hook that throws can't switch it off.
|
|
13
|
+
*/
|
|
14
|
+
import type { Message } from "@buildanagent/gateway";
|
|
15
|
+
import type { AnyTool } from "./tools/pipeline.js";
|
|
16
|
+
/** The thresholds of the default progress policy. Pass `progress: false` to `run()` to turn the policy off. */
|
|
17
|
+
export interface ProgressPolicy {
|
|
18
|
+
/** How many identical failing calls in a row end the run. Default 3. */
|
|
19
|
+
readonly maxIdenticalFailures?: number;
|
|
20
|
+
/** How many calls with one `progressKey` and no success between them end the run. Default 5. */
|
|
21
|
+
readonly maxSameKeyCalls?: number;
|
|
22
|
+
}
|
|
23
|
+
/** The defaults, provisional until recorded runs retune them. The object is frozen, so no caller can change them. */
|
|
24
|
+
export declare const DEFAULT_PROGRESS: Readonly<Required<ProgressPolicy>>;
|
|
25
|
+
/** Checks a `progress` option and fills in its defaults. */
|
|
26
|
+
export declare function resolveProgress(progress: ProgressPolicy | false | undefined): Required<ProgressPolicy> | undefined;
|
|
27
|
+
/** The progress check the loop runs after each step: the reason the run is stuck, or `undefined`. */
|
|
28
|
+
export type ProgressCheck = (messages: readonly Message[]) => Promise<string | undefined>;
|
|
29
|
+
/**
|
|
30
|
+
* The default progress policy as a check over the transcript. `skip` is how many messages came before this run's
|
|
31
|
+
* own, so a run continued from a context that ended in a loop is not stopped by the old calls. The transcript only
|
|
32
|
+
* grows, so each call's hash and key are worked out once and kept by its place in it.
|
|
33
|
+
*/
|
|
34
|
+
export declare function progressCheck(tools: readonly AnyTool[], policy: Required<ProgressPolicy>, skip: number): ProgressCheck;
|
package/dist/progress.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { SdkError } from "./errors.js";
|
|
2
|
+
import { canonicalInputHash } from "./vendor/agent-safety/hash.js";
|
|
3
|
+
/** The defaults, provisional until recorded runs retune them. The object is frozen, so no caller can change them. */
|
|
4
|
+
export const DEFAULT_PROGRESS = Object.freeze({
|
|
5
|
+
maxIdenticalFailures: 3,
|
|
6
|
+
maxSameKeyCalls: 5,
|
|
7
|
+
});
|
|
8
|
+
/** Checks a `progress` option and fills in its defaults. */
|
|
9
|
+
export function resolveProgress(progress) {
|
|
10
|
+
if (progress === false)
|
|
11
|
+
return undefined;
|
|
12
|
+
const policy = { ...DEFAULT_PROGRESS, ...definedFields(progress ?? {}) };
|
|
13
|
+
for (const [name, value] of Object.entries(policy)) {
|
|
14
|
+
if (!Number.isInteger(value) || value < 1) {
|
|
15
|
+
throw new SdkError("invalid_run_options", `progress.${name} must be a positive integer, got ${String(value)}`);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
return policy;
|
|
19
|
+
}
|
|
20
|
+
function definedFields(policy) {
|
|
21
|
+
return Object.fromEntries(Object.entries(policy).filter(([, value]) => value !== undefined));
|
|
22
|
+
}
|
|
23
|
+
function keyOf(tool, input) {
|
|
24
|
+
if (tool?.progressKey === undefined)
|
|
25
|
+
return undefined;
|
|
26
|
+
try {
|
|
27
|
+
const key = tool.progressKey(input);
|
|
28
|
+
return typeof key === "string" ? key : undefined;
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
// A key function that can't read the model's input leaves the call unkeyed, so only the identical-failure rule
|
|
32
|
+
// sees it.
|
|
33
|
+
return undefined;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
/** The hash of a call's input, or a value no other call shares when the input has no canonical form. */
|
|
37
|
+
async function hashOf(position, input) {
|
|
38
|
+
try {
|
|
39
|
+
return await canonicalInputHash(input);
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
return `unhashable:${position}`;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
/** The calls of one assistant message, each named by its place in the transcript. */
|
|
46
|
+
function callsOf(message, turn) {
|
|
47
|
+
const calls = [];
|
|
48
|
+
message.content.forEach((block, at) => {
|
|
49
|
+
if (block.type === "tool_call")
|
|
50
|
+
calls.push({ call: block, position: `${turn}:${at}`, turn });
|
|
51
|
+
});
|
|
52
|
+
return calls;
|
|
53
|
+
}
|
|
54
|
+
/** The unanswered call with `callId` in the newest turn, the first such call within it. */
|
|
55
|
+
function callFor(calls, callId) {
|
|
56
|
+
let best;
|
|
57
|
+
for (const pending of calls) {
|
|
58
|
+
if (pending.failed !== undefined || pending.call.callId !== callId)
|
|
59
|
+
continue;
|
|
60
|
+
if (best === undefined || pending.turn > best.turn)
|
|
61
|
+
best = pending;
|
|
62
|
+
}
|
|
63
|
+
return best;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The tool calls in `messages` that have a result, in the order the model made them. Call ids need not be unique:
|
|
67
|
+
* a provider may repeat one or send none, so a result goes to the unanswered call with its id in the newest turn,
|
|
68
|
+
* the first such call within it, the order the gateway pairs them in.
|
|
69
|
+
*/
|
|
70
|
+
function resolvedCalls(messages) {
|
|
71
|
+
const calls = [];
|
|
72
|
+
messages.forEach((message, index) => {
|
|
73
|
+
if (message.role === "assistant")
|
|
74
|
+
calls.push(...callsOf(message, index));
|
|
75
|
+
if (message.role !== "tool")
|
|
76
|
+
return;
|
|
77
|
+
const pending = callFor(calls, message.callId);
|
|
78
|
+
if (pending !== undefined)
|
|
79
|
+
pending.failed = message.isError === true;
|
|
80
|
+
});
|
|
81
|
+
return calls.filter((pending) => pending.failed !== undefined);
|
|
82
|
+
}
|
|
83
|
+
/** The calls in `messages` that have a result, each with its input hash, key and outcome. */
|
|
84
|
+
async function attemptsOf(messages, tools, facts) {
|
|
85
|
+
const attempts = [];
|
|
86
|
+
for (const { call, position, failed } of resolvedCalls(messages)) {
|
|
87
|
+
let known = facts.get(position);
|
|
88
|
+
if (known === undefined) {
|
|
89
|
+
known = { hash: hashOf(position, call.input), key: keyOf(tools.get(call.name), call.input) };
|
|
90
|
+
facts.set(position, known);
|
|
91
|
+
}
|
|
92
|
+
attempts.push({ tool: call.name, hash: await known.hash, key: known.key, failed: failed === true });
|
|
93
|
+
}
|
|
94
|
+
return attempts;
|
|
95
|
+
}
|
|
96
|
+
/** The reason when the latest calls are `limit` identical failures, or `undefined`. */
|
|
97
|
+
function identicalFailures(attempts, limit) {
|
|
98
|
+
const last = attempts.at(-1);
|
|
99
|
+
if (last === undefined || !last.failed)
|
|
100
|
+
return undefined;
|
|
101
|
+
let streak = 0;
|
|
102
|
+
for (let i = attempts.length - 1; i >= 0; i--) {
|
|
103
|
+
const attempt = attempts[i];
|
|
104
|
+
if (attempt === undefined || !attempt.failed || attempt.tool !== last.tool || attempt.hash !== last.hash)
|
|
105
|
+
break;
|
|
106
|
+
streak += 1;
|
|
107
|
+
}
|
|
108
|
+
if (streak < limit)
|
|
109
|
+
return undefined;
|
|
110
|
+
return `the model made ${streak} identical failing calls to ${last.tool} in a row`;
|
|
111
|
+
}
|
|
112
|
+
/** The reason when some key has `limit` calls and no success since its first, or `undefined`. */
|
|
113
|
+
function repeatedKey(attempts, limit) {
|
|
114
|
+
const counts = new Map();
|
|
115
|
+
for (const { tool, key, failed } of attempts) {
|
|
116
|
+
if (key === undefined)
|
|
117
|
+
continue;
|
|
118
|
+
const id = JSON.stringify([tool, key]);
|
|
119
|
+
const count = failed ? (counts.get(id) ?? 0) + 1 : 0;
|
|
120
|
+
counts.set(id, count);
|
|
121
|
+
if (count >= limit)
|
|
122
|
+
return `the model called ${tool} ${count} times with the key ${JSON.stringify(key)} and none succeeded`;
|
|
123
|
+
}
|
|
124
|
+
return undefined;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The default progress policy as a check over the transcript. `skip` is how many messages came before this run's
|
|
128
|
+
* own, so a run continued from a context that ended in a loop is not stopped by the old calls. The transcript only
|
|
129
|
+
* grows, so each call's hash and key are worked out once and kept by its place in it.
|
|
130
|
+
*/
|
|
131
|
+
export function progressCheck(tools, policy, skip) {
|
|
132
|
+
const byName = new Map(tools.map((tool) => [tool.name, tool]));
|
|
133
|
+
const facts = new Map();
|
|
134
|
+
return async (messages) => {
|
|
135
|
+
const attempts = await attemptsOf(messages.slice(skip), byName, facts);
|
|
136
|
+
return identicalFailures(attempts, policy.maxIdenticalFailures) ?? repeatedKey(attempts, policy.maxSameKeyCalls);
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
//# sourceMappingURL=progress.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The default progress policy (D11): it ends a run with `no_progress` when the model keeps making the same failing\n * call. Two rules fire it:\n *\n * - **Identical failures.** The latest calls are one tool with one canonical input hash, each returned an error, and\n * there are `maxIdenticalFailures` of them in a row (3 by default).\n * - **One key.** A tool's `progressKey()` gave `maxSameKeyCalls` calls (5 by default) the same key and none of them\n * succeeded. A successful call with that key starts its count again; calls with other keys don't.\n *\n * The policy reads the transcript, so it holds no state a `continueRun()` would have to restore, and it counts only\n * the calls the run itself made. The loop runs it after the caller's `shouldStop`, outside the hook runner, so a\n * caller's hook that throws can't switch it off.\n */\nimport type { AssistantMessage, Message } from \"@buildanagent/gateway\";\nimport { SdkError } from \"./errors.js\";\nimport type { AnyTool } from \"./tools/pipeline.js\";\nimport type { ToolCall } from \"./tools/types.js\";\nimport { canonicalInputHash } from \"./vendor/agent-safety/hash.js\";\n\n/** The thresholds of the default progress policy. Pass `progress: false` to `run()` to turn the policy off. */\nexport interface ProgressPolicy {\n /** How many identical failing calls in a row end the run. Default 3. */\n readonly maxIdenticalFailures?: number;\n /** How many calls with one `progressKey` and no success between them end the run. Default 5. */\n readonly maxSameKeyCalls?: number;\n}\n\n/** The defaults, provisional until recorded runs retune them. The object is frozen, so no caller can change them. */\nexport const DEFAULT_PROGRESS: Readonly<Required<ProgressPolicy>> = Object.freeze({\n maxIdenticalFailures: 3,\n maxSameKeyCalls: 5,\n});\n\n/** Checks a `progress` option and fills in its defaults. */\nexport function resolveProgress(progress: ProgressPolicy | false | undefined): Required<ProgressPolicy> | undefined {\n if (progress === false) return undefined;\n const policy = { ...DEFAULT_PROGRESS, ...definedFields(progress ?? {}) };\n for (const [name, value] of Object.entries(policy)) {\n if (!Number.isInteger(value) || value < 1) {\n throw new SdkError(\"invalid_run_options\", `progress.${name} must be a positive integer, got ${String(value)}`);\n }\n }\n return policy;\n}\n\nfunction definedFields(policy: ProgressPolicy): ProgressPolicy {\n return Object.fromEntries(Object.entries(policy).filter(([, value]) => value !== undefined));\n}\n\n/** One tool call of the run, with the result it got. */\ninterface Attempt {\n readonly tool: string;\n readonly hash: string;\n readonly key: string | undefined;\n readonly failed: boolean;\n}\n\n/** What the policy works out once for each call: its input hash and its key. */\ninterface CallFacts {\n readonly hash: Promise<string>;\n readonly key: string | undefined;\n}\n\nfunction keyOf(tool: AnyTool | undefined, input: unknown): string | undefined {\n if (tool?.progressKey === undefined) return undefined;\n try {\n const key: unknown = tool.progressKey(input);\n return typeof key === \"string\" ? key : undefined;\n } catch {\n // A key function that can't read the model's input leaves the call unkeyed, so only the identical-failure rule\n // sees it.\n return undefined;\n }\n}\n\n/** The hash of a call's input, or a value no other call shares when the input has no canonical form. */\nasync function hashOf(position: string, input: unknown): Promise<string> {\n try {\n return await canonicalInputHash(input);\n } catch {\n return `unhashable:${position}`;\n }\n}\n\n/** A call waiting for its result, named by its place in the transcript. */\ninterface Pending {\n readonly call: ToolCall;\n readonly position: string;\n readonly turn: number;\n failed?: boolean;\n}\n\n/** The calls of one assistant message, each named by its place in the transcript. */\nfunction callsOf(message: AssistantMessage, turn: number): Pending[] {\n const calls: Pending[] = [];\n message.content.forEach((block, at) => {\n if (block.type === \"tool_call\") calls.push({ call: block, position: `${turn}:${at}`, turn });\n });\n return calls;\n}\n\n/** The unanswered call with `callId` in the newest turn, the first such call within it. */\nfunction callFor(calls: readonly Pending[], callId: string): Pending | undefined {\n let best: Pending | undefined;\n for (const pending of calls) {\n if (pending.failed !== undefined || pending.call.callId !== callId) continue;\n if (best === undefined || pending.turn > best.turn) best = pending;\n }\n return best;\n}\n\n/**\n * The tool calls in `messages` that have a result, in the order the model made them. Call ids need not be unique:\n * a provider may repeat one or send none, so a result goes to the unanswered call with its id in the newest turn,\n * the first such call within it, the order the gateway pairs them in.\n */\nfunction resolvedCalls(messages: readonly Message[]): Pending[] {\n const calls: Pending[] = [];\n messages.forEach((message, index) => {\n if (message.role === \"assistant\") calls.push(...callsOf(message, index));\n if (message.role !== \"tool\") return;\n const pending = callFor(calls, message.callId);\n if (pending !== undefined) pending.failed = message.isError === true;\n });\n return calls.filter((pending) => pending.failed !== undefined);\n}\n\n/** The calls in `messages` that have a result, each with its input hash, key and outcome. */\nasync function attemptsOf(\n messages: readonly Message[],\n tools: ReadonlyMap<string, AnyTool>,\n facts: Map<string, CallFacts>,\n): Promise<Attempt[]> {\n const attempts: Attempt[] = [];\n for (const { call, position, failed } of resolvedCalls(messages)) {\n let known = facts.get(position);\n if (known === undefined) {\n known = { hash: hashOf(position, call.input), key: keyOf(tools.get(call.name), call.input) };\n facts.set(position, known);\n }\n attempts.push({ tool: call.name, hash: await known.hash, key: known.key, failed: failed === true });\n }\n return attempts;\n}\n\n/** The reason when the latest calls are `limit` identical failures, or `undefined`. */\nfunction identicalFailures(attempts: readonly Attempt[], limit: number): string | undefined {\n const last = attempts.at(-1);\n if (last === undefined || !last.failed) return undefined;\n let streak = 0;\n for (let i = attempts.length - 1; i >= 0; i--) {\n const attempt = attempts[i];\n if (attempt === undefined || !attempt.failed || attempt.tool !== last.tool || attempt.hash !== last.hash) break;\n streak += 1;\n }\n if (streak < limit) return undefined;\n return `the model made ${streak} identical failing calls to ${last.tool} in a row`;\n}\n\n/** The reason when some key has `limit` calls and no success since its first, or `undefined`. */\nfunction repeatedKey(attempts: readonly Attempt[], limit: number): string | undefined {\n const counts = new Map<string, number>();\n for (const { tool, key, failed } of attempts) {\n if (key === undefined) continue;\n const id = JSON.stringify([tool, key]);\n const count = failed ? (counts.get(id) ?? 0) + 1 : 0;\n counts.set(id, count);\n if (count >= limit)\n return `the model called ${tool} ${count} times with the key ${JSON.stringify(key)} and none succeeded`;\n }\n return undefined;\n}\n\n/** The progress check the loop runs after each step: the reason the run is stuck, or `undefined`. */\nexport type ProgressCheck = (messages: readonly Message[]) => Promise<string | undefined>;\n\n/**\n * The default progress policy as a check over the transcript. `skip` is how many messages came before this run's\n * own, so a run continued from a context that ended in a loop is not stopped by the old calls. The transcript only\n * grows, so each call's hash and key are worked out once and kept by its place in it.\n */\nexport function progressCheck(\n tools: readonly AnyTool[],\n policy: Required<ProgressPolicy>,\n skip: number,\n): ProgressCheck {\n const byName = new Map(tools.map((tool) => [tool.name, tool]));\n const facts = new Map<string, CallFacts>();\n return async (messages) => {\n const attempts = await attemptsOf(messages.slice(skip), byName, facts);\n return identicalFailures(attempts, policy.maxIdenticalFailures) ?? repeatedKey(attempts, policy.maxSameKeyCalls);\n };\n}\n"]}
|
package/dist/result.d.ts
CHANGED
|
@@ -17,9 +17,10 @@ export interface RunError {
|
|
|
17
17
|
/**
|
|
18
18
|
* `overflow`: the request was larger than the model's context window. `quota`: the account is out of quota or
|
|
19
19
|
* credit. `retryable`: a temporary failure that outlasted the model's retries. `fatal`: any other failure, such as a
|
|
20
|
-
* rejected request.
|
|
20
|
+
* rejected request. `hook`: an interceptor threw while the run fails closed, and `message` says which one.
|
|
21
|
+
* `unknown_price`: the run has a `budgetUsd`, but a price it needs is unknown, so it can't check the spend.
|
|
21
22
|
*/
|
|
22
|
-
readonly kind: NonNullable<AssistantMessage["error"]>["kind"];
|
|
23
|
+
readonly kind: NonNullable<AssistantMessage["error"]>["kind"] | "hook" | "unknown_price";
|
|
23
24
|
readonly message: string;
|
|
24
25
|
/** The provider's HTTP status, when the failure came with one. */
|
|
25
26
|
readonly status?: number;
|
|
@@ -57,14 +58,36 @@ export interface DoneResult<S> extends ResultBase {
|
|
|
57
58
|
export interface EndedResult extends ResultBase {
|
|
58
59
|
readonly stopReason: "max_steps" | "aborted";
|
|
59
60
|
}
|
|
60
|
-
/**
|
|
61
|
+
/**
|
|
62
|
+
* A run that stopped making progress. The default progress policy ends a run this way after 3 identical failing tool
|
|
63
|
+
* calls in a row, or after 5 failing calls to a tool with one `progressKey`; pass `progress` to `run()` to change the
|
|
64
|
+
* thresholds, or `progress: false` to turn the policy off. A `shouldStop` hook that returns `{ stop: "no_progress" }`
|
|
65
|
+
* ends a run this way too. `reason` says which rule or hook fired.
|
|
66
|
+
*/
|
|
67
|
+
export interface NoProgressResult extends ResultBase {
|
|
68
|
+
readonly stopReason: "no_progress";
|
|
69
|
+
readonly reason: string;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* A run that ended before a model call because that call could have taken the spend past `budgetUsd`. `spentUsd` is
|
|
73
|
+
* what the run's earlier calls cost, and `projectedUsd` the most the refused call could have cost.
|
|
74
|
+
*/
|
|
75
|
+
export interface BudgetResult extends ResultBase {
|
|
76
|
+
readonly stopReason: "budget";
|
|
77
|
+
readonly reason: string;
|
|
78
|
+
readonly budgetUsd: number;
|
|
79
|
+
readonly spentUsd: number;
|
|
80
|
+
readonly projectedUsd: number;
|
|
81
|
+
}
|
|
82
|
+
/** A run that ended because a model call failed, or because an interceptor failed while the run fails closed. */
|
|
61
83
|
export interface ErrorResult extends ResultBase {
|
|
62
84
|
readonly stopReason: "error";
|
|
63
85
|
readonly error: RunError;
|
|
64
86
|
}
|
|
65
87
|
/**
|
|
66
88
|
* A run that stopped before it finished, for a reason `stoppedBy` names. `clarification`: a tool from
|
|
67
|
-
* `clarificationTool()` asked the user a question.
|
|
89
|
+
* `clarificationTool()` asked the user a question. Any other value is the `reason` a `shouldStop` hook gave, or
|
|
90
|
+
* `"hook"` when it returned `true`. To go on, add the answer to `context` as a user message and pass the
|
|
68
91
|
* context to `continueRun()`.
|
|
69
92
|
*/
|
|
70
93
|
export interface StoppedResult extends ResultBase {
|
|
@@ -72,6 +95,6 @@ export interface StoppedResult extends ResultBase {
|
|
|
72
95
|
readonly stoppedBy: string;
|
|
73
96
|
}
|
|
74
97
|
/** What a run returns. Check `stopReason` before you read the fields of one variant. */
|
|
75
|
-
export type RunResult<S = unknown> = DoneResult<S> | EndedResult | ErrorResult | StoppedResult;
|
|
98
|
+
export type RunResult<S = unknown> = DoneResult<S> | BudgetResult | EndedResult | ErrorResult | NoProgressResult | StoppedResult;
|
|
76
99
|
/** Every run result except `done`, which `runOrThrow()` turns into a `RunStoppedError`. */
|
|
77
100
|
export type UnfinishedResult = Exclude<RunResult, DoneResult<unknown>>;
|
package/dist/result.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * What a run returns: a union discriminated by `stopReason`, in which only the `done` variant carries `output`, so\n * code that reads the output without checking the stop reason fails to compile (D10). Every variant carries the\n * usage, the cost and a context the run can continue from.\n */\nimport type { AssistantMessage, Cost, Message, Usage } from \"@buildanagent/gateway\";\n\n/**\n * A run's conversation as plain JSON: the system prompt and every message so far. Store it anywhere and pass it to\n * `continueRun()` to go on from where the run stopped.\n */\nexport interface Context {\n readonly system: string;\n readonly messages: readonly Message[];\n}\n\n/** Why a model call failed, copied from the failed message's `error`. */\nexport interface RunError {\n /**\n * `overflow`: the request was larger than the model's context window. `quota`: the account is out of quota or\n * credit. `retryable`: a temporary failure that outlasted the model's retries. `fatal`: any other failure, such as a\n * rejected request.\n */\n readonly kind: NonNullable<AssistantMessage[\"error\"]>[\"kind\"];\n readonly message: string;\n /** The provider's HTTP status, when the failure came with one. */\n readonly status?: number;\n}\n\n/** The fields every run result carries. */\nexport interface ResultBase {\n /** The messages this run added: the input, if any, then every response and tool result, in order. */\n readonly messages: readonly Message[];\n /** The whole conversation, earlier history included, ready for `continueRun()`. */\n readonly context: Context;\n /** The tokens of every model call, summed. */\n readonly usage: Usage;\n /**\n * The cost of every model call, summed. It is unknown if any call's cost is. A run that made no call costs an exact\n * 0 with basis `provider`, so adding it to another cost keeps that cost's basis.\n */\n readonly cost: Cost;\n /** How many model calls the run made. */\n readonly steps: number;\n}\n\n/**\n * A run that finished: the model answered without calling a tool, or an output tool accepted its answer. `output` is\n * the accepted answer, and `undefined` when the run has no output tool, the model answered in text, or another tool\n * ended the run with `terminate: true`. A text\n * answer cut off at the output limit also ends `done`; its message's `stopReason` is then `\"length\"`.\n */\nexport interface DoneResult<S> extends ResultBase {\n readonly stopReason: \"done\";\n readonly output: S | undefined;\n}\n\n/**\n * A run that ended before it finished. `max_steps`: it made `maxSteps` model calls and the model still wanted to\n * continue. `aborted`: it was aborted.\n */\nexport interface EndedResult extends ResultBase {\n readonly stopReason: \"max_steps\" | \"aborted\";\n}\n\n/** A run that ended because a model call failed. */\nexport interface ErrorResult extends ResultBase {\n readonly stopReason: \"error\";\n readonly error: RunError;\n}\n\n/**\n * A run that stopped before it finished, for a reason `stoppedBy` names. `clarification`: a tool from\n * `clarificationTool()` asked the user a question. To go on, add the answer to `context` as a user message and pass the\n * context to `continueRun()`.\n */\nexport interface StoppedResult extends ResultBase {\n readonly stopReason: \"stopped\";\n readonly stoppedBy: string;\n}\n\n/** What a run returns. Check `stopReason` before you read the fields of one variant. */\nexport type RunResult<S = unknown>
|
|
1
|
+
{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * What a run returns: a union discriminated by `stopReason`, in which only the `done` variant carries `output`, so\n * code that reads the output without checking the stop reason fails to compile (D10). Every variant carries the\n * usage, the cost and a context the run can continue from.\n */\nimport type { AssistantMessage, Cost, Message, Usage } from \"@buildanagent/gateway\";\n\n/**\n * A run's conversation as plain JSON: the system prompt and every message so far. Store it anywhere and pass it to\n * `continueRun()` to go on from where the run stopped.\n */\nexport interface Context {\n readonly system: string;\n readonly messages: readonly Message[];\n}\n\n/** Why a model call failed, copied from the failed message's `error`. */\nexport interface RunError {\n /**\n * `overflow`: the request was larger than the model's context window. `quota`: the account is out of quota or\n * credit. `retryable`: a temporary failure that outlasted the model's retries. `fatal`: any other failure, such as a\n * rejected request. `hook`: an interceptor threw while the run fails closed, and `message` says which one.\n * `unknown_price`: the run has a `budgetUsd`, but a price it needs is unknown, so it can't check the spend.\n */\n readonly kind: NonNullable<AssistantMessage[\"error\"]>[\"kind\"] | \"hook\" | \"unknown_price\";\n readonly message: string;\n /** The provider's HTTP status, when the failure came with one. */\n readonly status?: number;\n}\n\n/** The fields every run result carries. */\nexport interface ResultBase {\n /** The messages this run added: the input, if any, then every response and tool result, in order. */\n readonly messages: readonly Message[];\n /** The whole conversation, earlier history included, ready for `continueRun()`. */\n readonly context: Context;\n /** The tokens of every model call, summed. */\n readonly usage: Usage;\n /**\n * The cost of every model call, summed. It is unknown if any call's cost is. A run that made no call costs an exact\n * 0 with basis `provider`, so adding it to another cost keeps that cost's basis.\n */\n readonly cost: Cost;\n /** How many model calls the run made. */\n readonly steps: number;\n}\n\n/**\n * A run that finished: the model answered without calling a tool, or an output tool accepted its answer. `output` is\n * the accepted answer, and `undefined` when the run has no output tool, the model answered in text, or another tool\n * ended the run with `terminate: true`. A text\n * answer cut off at the output limit also ends `done`; its message's `stopReason` is then `\"length\"`.\n */\nexport interface DoneResult<S> extends ResultBase {\n readonly stopReason: \"done\";\n readonly output: S | undefined;\n}\n\n/**\n * A run that ended before it finished. `max_steps`: it made `maxSteps` model calls and the model still wanted to\n * continue. `aborted`: it was aborted.\n */\nexport interface EndedResult extends ResultBase {\n readonly stopReason: \"max_steps\" | \"aborted\";\n}\n\n/**\n * A run that stopped making progress. The default progress policy ends a run this way after 3 identical failing tool\n * calls in a row, or after 5 failing calls to a tool with one `progressKey`; pass `progress` to `run()` to change the\n * thresholds, or `progress: false` to turn the policy off. A `shouldStop` hook that returns `{ stop: \"no_progress\" }`\n * ends a run this way too. `reason` says which rule or hook fired.\n */\nexport interface NoProgressResult extends ResultBase {\n readonly stopReason: \"no_progress\";\n readonly reason: string;\n}\n\n/**\n * A run that ended before a model call because that call could have taken the spend past `budgetUsd`. `spentUsd` is\n * what the run's earlier calls cost, and `projectedUsd` the most the refused call could have cost.\n */\nexport interface BudgetResult extends ResultBase {\n readonly stopReason: \"budget\";\n readonly reason: string;\n readonly budgetUsd: number;\n readonly spentUsd: number;\n readonly projectedUsd: number;\n}\n\n/** A run that ended because a model call failed, or because an interceptor failed while the run fails closed. */\nexport interface ErrorResult extends ResultBase {\n readonly stopReason: \"error\";\n readonly error: RunError;\n}\n\n/**\n * A run that stopped before it finished, for a reason `stoppedBy` names. `clarification`: a tool from\n * `clarificationTool()` asked the user a question. Any other value is the `reason` a `shouldStop` hook gave, or\n * `\"hook\"` when it returned `true`. To go on, add the answer to `context` as a user message and pass the\n * context to `continueRun()`.\n */\nexport interface StoppedResult extends ResultBase {\n readonly stopReason: \"stopped\";\n readonly stoppedBy: string;\n}\n\n/** What a run returns. Check `stopReason` before you read the fields of one variant. */\nexport type RunResult<S = unknown> =\n | DoneResult<S>\n | BudgetResult\n | EndedResult\n | ErrorResult\n | NoProgressResult\n | StoppedResult;\n\n/** Every run result except `done`, which `runOrThrow()` turns into a `RunStoppedError`. */\nexport type UnfinishedResult = Exclude<RunResult, DoneResult<unknown>>;\n"]}
|
package/dist/run.d.ts
CHANGED
|
@@ -3,16 +3,21 @@
|
|
|
3
3
|
* its events to anyone who iterates it and settles `result` with the same run's outcome, so the streaming and the
|
|
4
4
|
* non-streaming caller drive one loop.
|
|
5
5
|
*/
|
|
6
|
-
import type { ContentBlock, Message, Model
|
|
6
|
+
import type { ContentBlock, Message, Model } from "@buildanagent/gateway";
|
|
7
7
|
import type { AgentEvent } from "./events.js";
|
|
8
|
+
import type { CallOptions, Interceptors, Observer } from "./hooks.js";
|
|
9
|
+
import { type ProgressPolicy } from "./progress.js";
|
|
8
10
|
import type { Context, DoneResult, RunResult } from "./result.js";
|
|
9
11
|
import type { Clock } from "./testing/determinism.js";
|
|
10
|
-
import type { ToolDefinition } from "./tools/types.js";
|
|
12
|
+
import type { ToolContext, ToolDefinition } from "./tools/types.js";
|
|
11
13
|
/** The options `run()` and `continueRun()` share. */
|
|
12
14
|
export interface RunOptions<S = unknown> {
|
|
13
15
|
/** The model, from `createModel()`. */
|
|
14
16
|
readonly model: Model;
|
|
15
|
-
/**
|
|
17
|
+
/**
|
|
18
|
+
* The tools the model may call. Tools whose `exposure` is `deferred` or `hidden` are not sent unless a
|
|
19
|
+
* `beforeModelCall` interceptor names them in `activeTools`.
|
|
20
|
+
*/
|
|
16
21
|
readonly tools?: readonly ToolDefinition<unknown, unknown>[];
|
|
17
22
|
/**
|
|
18
23
|
* A tool from `outputTool()` whose input is the final answer. It is sent with the other tools; once the model calls
|
|
@@ -24,10 +29,52 @@ export interface RunOptions<S = unknown> {
|
|
|
24
29
|
* ends with `stopReason: "max_steps"` and emits a `warning` event with `code: "max_steps"`.
|
|
25
30
|
*/
|
|
26
31
|
readonly maxSteps?: number;
|
|
32
|
+
/**
|
|
33
|
+
* The most the run's model calls may cost, in USD. Before each call the run projects its cost with
|
|
34
|
+
* `projectCallCost()` and, if the spend so far plus that projection would pass the cap, ends with
|
|
35
|
+
* `stopReason: "budget"` without making the call. The cap counts the calls this run makes, not the cost of the
|
|
36
|
+
* history a `continueRun()` starts from. A budgeted run on a model whose price is unknown ends `error` with
|
|
37
|
+
* `error.kind: "unknown_price"` before its first call, because it could not tell what it spent. Without it, a run
|
|
38
|
+
* has no cap.
|
|
39
|
+
*/
|
|
40
|
+
readonly budgetUsd?: number;
|
|
41
|
+
/**
|
|
42
|
+
* The default progress policy: the run ends `no_progress` after 3 identical failing tool calls in a row, or after 5
|
|
43
|
+
* calls to a tool with one `progressKey` and no success between them. It runs after your own `shouldStop`, whose
|
|
44
|
+
* `{ continue }` can't keep a stuck run going. Pass numbers to change either threshold, or `false` to turn the
|
|
45
|
+
* policy off.
|
|
46
|
+
*/
|
|
47
|
+
readonly progress?: ProgressPolicy | false;
|
|
48
|
+
/**
|
|
49
|
+
* How deeply this run is nested inside other agents' tool calls. Default 0. A tool that starts a run of its own
|
|
50
|
+
* passes `depth: ctx.depth + 1` and `maxDepth: ctx.maxDepth`; `run()` throws an `SdkError` with code
|
|
51
|
+
* `max_depth_exceeded` when `depth` is above `maxDepth`, which the tool's caller reads as an error result.
|
|
52
|
+
*/
|
|
53
|
+
readonly depth?: number;
|
|
54
|
+
/** The deepest nesting allowed, which tools read as `ctx.maxDepth`. Default 2. */
|
|
55
|
+
readonly maxDepth?: number;
|
|
27
56
|
/** Aborts the run, like `run.abort()`. */
|
|
28
57
|
readonly signal?: AbortSignal;
|
|
29
58
|
/** Options for every model call, such as `maxOutputTokens`. The run passes its own abort signal. */
|
|
30
|
-
readonly modelOptions?:
|
|
59
|
+
readonly modelOptions?: CallOptions;
|
|
60
|
+
/**
|
|
61
|
+
* The interceptors: hooks that can change the run at six moments. A run takes one object; join several with
|
|
62
|
+
* `composeInterceptors()`. See `Interceptors` for the order and for what a failing hook does.
|
|
63
|
+
*/
|
|
64
|
+
readonly interceptors?: Interceptors;
|
|
65
|
+
/**
|
|
66
|
+
* Observers, which receive every event from `run_start` on and can't change the run. Each observer sees the events in
|
|
67
|
+
* order and waits for its own promises, but observers don't wait for each other. An observer that throws becomes a
|
|
68
|
+
* `hook_error` event. The run waits for every observer to handle the last event before it settles, for at most
|
|
69
|
+
* `observerTimeoutMs` each time it waits; an observer that hasn't caught up by then is removed and reported as a
|
|
70
|
+
* `hook_error`.
|
|
71
|
+
*/
|
|
72
|
+
readonly observers?: readonly Observer[];
|
|
73
|
+
/**
|
|
74
|
+
* The longest the run waits for its observers each time it waits for them: before `agent_settled`, before
|
|
75
|
+
* `run_end` and before it settles. A number from 1 to 2147483647; the default is 10000. It bounds an observer whose promise never settles.
|
|
76
|
+
*/
|
|
77
|
+
readonly observerTimeoutMs?: number;
|
|
31
78
|
/** Stamps each event's `timestamp`, and is passed to tools. Defaults to the system clock. */
|
|
32
79
|
readonly clock?: Clock;
|
|
33
80
|
/** Makes the run's id. Defaults to `crypto.randomUUID()`. */
|
|
@@ -54,10 +101,27 @@ export interface Run<S = unknown> extends AsyncIterable<AgentEvent> {
|
|
|
54
101
|
readonly result: Promise<RunResult<S>>;
|
|
55
102
|
/**
|
|
56
103
|
* Stops the run. A model call in flight ends, a running tool sees its `signal` fire, and calls that haven't started
|
|
57
|
-
* get an error result instead. The run then ends with `stopReason: "aborted"`. Does nothing once the run has
|
|
104
|
+
* get an error result instead. The run then ends with `stopReason: "aborted"`. Does nothing once the run has its
|
|
105
|
+
* outcome and is ending, which is before `agent_settled`.
|
|
58
106
|
*/
|
|
59
107
|
abort(reason?: string): void;
|
|
108
|
+
/**
|
|
109
|
+
* Adds an observer that receives the events from now on, in order, and returns the function that removes it. An
|
|
110
|
+
* event that was queued for it but not yet handled is dropped when you remove it. Add it right after `run()` to
|
|
111
|
+
* see every event but `run_start`, which `run()` emits before it returns; to see that one too, pass the observer
|
|
112
|
+
* in the `observers` option.
|
|
113
|
+
*/
|
|
114
|
+
on(observer: Observer): () => void;
|
|
60
115
|
}
|
|
116
|
+
/**
|
|
117
|
+
* The `depth` and `maxDepth` options for a run that a tool starts: one level deeper than the tool's own run, under
|
|
118
|
+
* the same cap. Spread it into the nested `run()`; the nested run throws `max_depth_exceeded` when the tool was
|
|
119
|
+
* already at `maxDepth`.
|
|
120
|
+
*/
|
|
121
|
+
export declare function nestedRunDepth(ctx: Pick<ToolContext, "depth" | "maxDepth">): {
|
|
122
|
+
depth: number;
|
|
123
|
+
maxDepth: number;
|
|
124
|
+
};
|
|
61
125
|
/**
|
|
62
126
|
* Starts a run: the model answers `input`, runs the tools it asks for, and goes on until it answers without a tool
|
|
63
127
|
* call, an output tool accepts its answer, or a stop reason ends the run early. Throws an `SdkError` at once for an
|
package/dist/run.js
CHANGED
|
@@ -1,11 +1,53 @@
|
|
|
1
|
+
import { checkBudgetOption } from "./budget.js";
|
|
1
2
|
import { RunStoppedError, SdkError } from "./errors.js";
|
|
2
3
|
import { runLoop } from "./loop.js";
|
|
4
|
+
import { ObserverBus } from "./observers.js";
|
|
5
|
+
import { progressCheck, resolveProgress } from "./progress.js";
|
|
3
6
|
import { preparedSchemaOf } from "./tools/define.js";
|
|
4
7
|
import { SDK_VERSION } from "./version.js";
|
|
5
8
|
/** The step cap's default, counted in model calls. */
|
|
6
9
|
const DEFAULT_MAX_STEPS = 20;
|
|
10
|
+
/** The depth cap's default (D11): a top-level run, its subagents and their subagents may run, and no deeper. */
|
|
11
|
+
const DEFAULT_MAX_DEPTH = 2;
|
|
12
|
+
/** How long the run waits, by default, for an observer to catch up before it drops it. */
|
|
13
|
+
const DEFAULT_OBSERVER_TIMEOUT_MS = 10_000;
|
|
14
|
+
/** The longest delay `setTimeout` accepts; a larger one fires at once on Node and workerd alike. */
|
|
15
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
7
16
|
const systemClock = { now: () => new Date().toISOString() };
|
|
8
17
|
const randomIds = () => globalThis.crypto.randomUUID();
|
|
18
|
+
function messageOf(error) {
|
|
19
|
+
return error instanceof Error ? error.message : String(error);
|
|
20
|
+
}
|
|
21
|
+
function checkObserver(observer) {
|
|
22
|
+
if (typeof observer !== "function") {
|
|
23
|
+
throw new SdkError("invalid_run_options", `an observer must be a function, got ${typeof observer}`);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
const HOOK_NAMES = [
|
|
27
|
+
"transformContext",
|
|
28
|
+
"beforeModelCall",
|
|
29
|
+
"afterModelCall",
|
|
30
|
+
"beforeToolCall",
|
|
31
|
+
"afterToolCall",
|
|
32
|
+
"shouldStop",
|
|
33
|
+
];
|
|
34
|
+
/** Checks the interceptors option once, so a misspelt or mistyped hook fails at `run()` and not mid-run. */
|
|
35
|
+
function checkInterceptors(interceptors) {
|
|
36
|
+
if (typeof interceptors !== "object" || interceptors === null) {
|
|
37
|
+
throw new SdkError("invalid_run_options", "interceptors must be an object of hooks");
|
|
38
|
+
}
|
|
39
|
+
for (const name of HOOK_NAMES) {
|
|
40
|
+
const hook = interceptors[name];
|
|
41
|
+
if (hook !== undefined && typeof hook !== "function") {
|
|
42
|
+
throw new SdkError("invalid_run_options", `interceptors.${name} must be a function, got ${typeof hook}`);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
const { onFailure } = interceptors;
|
|
46
|
+
if (onFailure !== undefined && onFailure !== "fail_closed" && onFailure !== "continue") {
|
|
47
|
+
throw new SdkError("invalid_run_options", `interceptors.onFailure must be "fail_closed" or "continue"`);
|
|
48
|
+
}
|
|
49
|
+
return interceptors;
|
|
50
|
+
}
|
|
9
51
|
function reasonOf(reason) {
|
|
10
52
|
if (typeof reason === "string")
|
|
11
53
|
return reason;
|
|
@@ -17,13 +59,25 @@ class RunHandle {
|
|
|
17
59
|
#events = [];
|
|
18
60
|
#controller = new AbortController();
|
|
19
61
|
#clock;
|
|
62
|
+
#bus;
|
|
20
63
|
#waiters = [];
|
|
21
64
|
#ended = false;
|
|
65
|
+
/** Set once the loop has its outcome and starts to end the run, so `abort()` no longer does anything. */
|
|
66
|
+
#settled = false;
|
|
67
|
+
/** Set by `run_end`: nothing may follow it, so a late observer report is dropped. */
|
|
68
|
+
#closed = false;
|
|
22
69
|
#failure;
|
|
23
70
|
#stepIndex = 0;
|
|
24
|
-
constructor(setup, signal) {
|
|
71
|
+
constructor(setup, signal, watch) {
|
|
25
72
|
this.id = setup.runId;
|
|
26
73
|
this.#clock = setup.clock;
|
|
74
|
+
this.#bus = new ObserverBus((hook, error) => {
|
|
75
|
+
if (!this.#closed)
|
|
76
|
+
this.#push({ type: "hook_error", hook, error: messageOf(error) }, this.#stepIndex);
|
|
77
|
+
}, watch.timeoutMs);
|
|
78
|
+
const { observers } = watch;
|
|
79
|
+
for (const observer of observers)
|
|
80
|
+
this.#bus.add(observer);
|
|
27
81
|
const emit = (body, stepIndex) => this.#push(body, stepIndex);
|
|
28
82
|
const { model } = setup;
|
|
29
83
|
const versions = { sdkVersion: SDK_VERSION, specVersion: "v1", defaultsHash: "", capabilities: [] };
|
|
@@ -33,7 +87,15 @@ class RunHandle {
|
|
|
33
87
|
forwardAbort();
|
|
34
88
|
else
|
|
35
89
|
signal?.addEventListener("abort", forwardAbort, { once: true });
|
|
36
|
-
|
|
90
|
+
// The loop starts after this turn, so an observer added with `run.on()` straight after `run()` sees every event
|
|
91
|
+
// after `run_start`, and a `run.abort()` straight after it stops the run before its first model call.
|
|
92
|
+
// The loop drains the observers only once it has its outcome (`finish()`), so the first drain is also where an
|
|
93
|
+
// abort stops mattering: it could no longer change the outcome, only add an `abort` event after it.
|
|
94
|
+
const drain = () => {
|
|
95
|
+
this.#settled = true;
|
|
96
|
+
return this.#bus.flush();
|
|
97
|
+
};
|
|
98
|
+
const loop = Promise.resolve().then(() => runLoop({ ...setup, signal: this.#controller.signal }, emit, drain));
|
|
37
99
|
// The loop's result type is `RunResult<unknown>`; only the output tool, whose type is `S`, fills `output`.
|
|
38
100
|
this.result = loop;
|
|
39
101
|
// Handling the rejection here also keeps a caller who only iterates from an unhandled rejection: iteration
|
|
@@ -41,11 +103,15 @@ class RunHandle {
|
|
|
41
103
|
loop.then(() => this.#end(signal, forwardAbort, undefined), (error) => this.#end(signal, forwardAbort, { error }));
|
|
42
104
|
}
|
|
43
105
|
abort(reason) {
|
|
44
|
-
if (this.#ended || this.#controller.signal.aborted)
|
|
106
|
+
if (this.#settled || this.#ended || this.#controller.signal.aborted)
|
|
45
107
|
return;
|
|
46
108
|
this.#push(reason === undefined ? { type: "abort" } : { type: "abort", reason }, this.#stepIndex);
|
|
47
109
|
this.#controller.abort(reason);
|
|
48
110
|
}
|
|
111
|
+
on(observer) {
|
|
112
|
+
checkObserver(observer);
|
|
113
|
+
return this.#bus.add(observer);
|
|
114
|
+
}
|
|
49
115
|
[Symbol.asyncIterator]() {
|
|
50
116
|
let cursor = 0;
|
|
51
117
|
return {
|
|
@@ -66,8 +132,12 @@ class RunHandle {
|
|
|
66
132
|
}
|
|
67
133
|
#push(body, stepIndex) {
|
|
68
134
|
this.#stepIndex = stepIndex;
|
|
135
|
+
if (body.type === "run_end")
|
|
136
|
+
this.#closed = true;
|
|
69
137
|
const base = { runId: this.id, seq: this.#events.length, stepIndex, timestamp: this.#clock.now() };
|
|
70
|
-
|
|
138
|
+
const event = { ...base, ...body };
|
|
139
|
+
this.#events.push(event);
|
|
140
|
+
this.#bus.deliver(event);
|
|
71
141
|
this.#wake();
|
|
72
142
|
}
|
|
73
143
|
#end(signal, forwardAbort, failure) {
|
|
@@ -107,6 +177,36 @@ function toolsOf(options) {
|
|
|
107
177
|
}
|
|
108
178
|
return tools;
|
|
109
179
|
}
|
|
180
|
+
function isCount(value) {
|
|
181
|
+
return typeof value === "number" && Number.isInteger(value) && value >= 0;
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* The `depth` and `maxDepth` options for a run that a tool starts: one level deeper than the tool's own run, under
|
|
185
|
+
* the same cap. Spread it into the nested `run()`; the nested run throws `max_depth_exceeded` when the tool was
|
|
186
|
+
* already at `maxDepth`.
|
|
187
|
+
*/
|
|
188
|
+
export function nestedRunDepth(ctx) {
|
|
189
|
+
return { depth: ctx.depth + 1, maxDepth: ctx.maxDepth };
|
|
190
|
+
}
|
|
191
|
+
/** Checks `depth` and `maxDepth`, and refuses a run nested deeper than the cap allows (D11). */
|
|
192
|
+
function depthsOf(options) {
|
|
193
|
+
const { depth = 0, maxDepth = DEFAULT_MAX_DEPTH } = options;
|
|
194
|
+
if (!isCount(depth) || !isCount(maxDepth)) {
|
|
195
|
+
throw new SdkError("invalid_run_options", `depth and maxDepth must be whole numbers, 0 or more, got ${String(depth)} and ${String(maxDepth)}`);
|
|
196
|
+
}
|
|
197
|
+
if (depth > maxDepth) {
|
|
198
|
+
throw new SdkError("max_depth_exceeded", `a run at depth ${depth} is deeper than maxDepth ${maxDepth} allows`);
|
|
199
|
+
}
|
|
200
|
+
return { depth, maxDepth };
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* The default progress policy for this run, or `undefined` when `progress: false` turns it off. `skip` is the number
|
|
204
|
+
* of messages before the run's own.
|
|
205
|
+
*/
|
|
206
|
+
function progressOf(options, tools, skip) {
|
|
207
|
+
const policy = resolveProgress(options.progress);
|
|
208
|
+
return policy === undefined ? undefined : progressCheck(tools, policy, skip);
|
|
209
|
+
}
|
|
110
210
|
function setupOf(options, context, input) {
|
|
111
211
|
if (!isModel(options.model)) {
|
|
112
212
|
throw new SdkError("invalid_run_options", "the model must come from createModel(), such as createModel({ adapter, id })");
|
|
@@ -115,7 +215,10 @@ function setupOf(options, context, input) {
|
|
|
115
215
|
if (!Number.isInteger(maxSteps) || maxSteps < 1) {
|
|
116
216
|
throw new SdkError("invalid_run_options", `maxSteps must be a positive integer, got ${maxSteps}`);
|
|
117
217
|
}
|
|
218
|
+
const budgetUsd = checkBudgetOption(options.budgetUsd);
|
|
118
219
|
const tools = toolsOf(options);
|
|
220
|
+
const { depth, maxDepth } = depthsOf(options);
|
|
221
|
+
const progress = progressOf(options, tools, context.messages.length + input.length);
|
|
119
222
|
if (options.output !== undefined && (options.output.exposure ?? "direct") !== "direct") {
|
|
120
223
|
throw new SdkError("invalid_run_options", `the output tool "${options.output.name}" must be sent to the model, so its exposure must be "direct"`);
|
|
121
224
|
}
|
|
@@ -125,13 +228,28 @@ function setupOf(options, context, input) {
|
|
|
125
228
|
system: context.system,
|
|
126
229
|
history: context.messages,
|
|
127
230
|
input,
|
|
128
|
-
tools
|
|
231
|
+
tools,
|
|
129
232
|
output: options.output,
|
|
130
233
|
maxSteps,
|
|
234
|
+
...(budgetUsd === undefined ? {} : { budgetUsd }),
|
|
235
|
+
depth,
|
|
236
|
+
maxDepth,
|
|
131
237
|
modelOptions: options.modelOptions ?? {},
|
|
238
|
+
interceptors: checkInterceptors(options.interceptors ?? {}),
|
|
239
|
+
...(progress === undefined ? {} : { progress }),
|
|
132
240
|
clock: options.clock ?? systemClock,
|
|
133
241
|
};
|
|
134
242
|
}
|
|
243
|
+
function observersOf(options) {
|
|
244
|
+
const observers = options.observers ?? [];
|
|
245
|
+
for (const observer of observers)
|
|
246
|
+
checkObserver(observer);
|
|
247
|
+
const timeoutMs = options.observerTimeoutMs ?? DEFAULT_OBSERVER_TIMEOUT_MS;
|
|
248
|
+
if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_MS) {
|
|
249
|
+
throw new SdkError("invalid_run_options", `observerTimeoutMs must be a number from 1 to ${MAX_TIMER_MS}, got ${timeoutMs}`);
|
|
250
|
+
}
|
|
251
|
+
return { observers, timeoutMs };
|
|
252
|
+
}
|
|
135
253
|
/**
|
|
136
254
|
* Starts a run: the model answers `input`, runs the tools it asks for, and goes on until it answers without a tool
|
|
137
255
|
* call, an output tool accepts its answer, or a stop reason ends the run early. Throws an `SdkError` at once for an
|
|
@@ -142,7 +260,7 @@ export function run(options) {
|
|
|
142
260
|
const content = typeof options.input === "string" ? [{ type: "text", text: options.input }] : options.input;
|
|
143
261
|
const input = { role: "user", content: [...content] };
|
|
144
262
|
const setup = setupOf(options, { system: options.system, messages: options.history ?? [] }, [input]);
|
|
145
|
-
return new RunHandle(setup, options.signal);
|
|
263
|
+
return new RunHandle(setup, options.signal, observersOf(options));
|
|
146
264
|
}
|
|
147
265
|
/**
|
|
148
266
|
* Goes on with a conversation from a result's `context`, or one you rebuilt from your own store. It runs like
|
|
@@ -150,7 +268,7 @@ export function run(options) {
|
|
|
150
268
|
* is sent as it stands, so add a user message to one that ends with the model's answer, such as a `done` result's.
|
|
151
269
|
*/
|
|
152
270
|
export function continueRun(context, options) {
|
|
153
|
-
return new RunHandle(setupOf(options, context, []), options.signal);
|
|
271
|
+
return new RunHandle(setupOf(options, context, []), options.signal, observersOf(options));
|
|
154
272
|
}
|
|
155
273
|
/**
|
|
156
274
|
* Awaits a run and returns its result if it ended `done`. Any other stop reason throws a `RunStoppedError` that
|