@buildanagent/gateway 0.0.0-stage → 0.1.0-alpha.0
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/LICENSE +52 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +299 -2
- package/dist/adapters/anthropic/adapter.d.ts +25 -0
- package/dist/adapters/anthropic/adapter.js +183 -0
- package/dist/adapters/anthropic/adapter.js.map +1 -0
- package/dist/adapters/anthropic/failure.d.ts +20 -0
- package/dist/adapters/anthropic/failure.js +46 -0
- package/dist/adapters/anthropic/failure.js.map +1 -0
- package/dist/adapters/anthropic/index.d.ts +3 -0
- package/dist/adapters/anthropic/index.js +3 -0
- package/dist/adapters/anthropic/index.js.map +1 -0
- package/dist/adapters/anthropic/request.d.ts +53 -0
- package/dist/adapters/anthropic/request.js +250 -0
- package/dist/adapters/anthropic/request.js.map +1 -0
- package/dist/adapters/anthropic/response.d.ts +31 -0
- package/dist/adapters/anthropic/response.js +212 -0
- package/dist/adapters/anthropic/response.js.map +1 -0
- package/dist/adapters/anthropic/usage.d.ts +26 -0
- package/dist/adapters/anthropic/usage.js +39 -0
- package/dist/adapters/anthropic/usage.js.map +1 -0
- package/dist/adapters/openai-chat/adapter.d.ts +18 -0
- package/dist/adapters/openai-chat/adapter.js +86 -0
- package/dist/adapters/openai-chat/adapter.js.map +1 -0
- package/dist/adapters/openai-chat/compat.d.ts +58 -0
- package/dist/adapters/openai-chat/compat.js +19 -0
- package/dist/adapters/openai-chat/compat.js.map +1 -0
- package/dist/adapters/openai-chat/failure.d.ts +25 -0
- package/dist/adapters/openai-chat/failure.js +33 -0
- package/dist/adapters/openai-chat/failure.js.map +1 -0
- package/dist/adapters/openai-chat/index.d.ts +4 -0
- package/dist/adapters/openai-chat/index.js +3 -0
- package/dist/adapters/openai-chat/index.js.map +1 -0
- package/dist/adapters/openai-chat/request.d.ts +47 -0
- package/dist/adapters/openai-chat/request.js +227 -0
- package/dist/adapters/openai-chat/request.js.map +1 -0
- package/dist/adapters/openai-chat/response.d.ts +22 -0
- package/dist/adapters/openai-chat/response.js +203 -0
- package/dist/adapters/openai-chat/response.js.map +1 -0
- package/dist/adapters/openai-chat/usage.d.ts +19 -0
- package/dist/adapters/openai-chat/usage.js +22 -0
- package/dist/adapters/openai-chat/usage.js.map +1 -0
- package/dist/adapters/strict-schema.d.ts +67 -0
- package/dist/adapters/strict-schema.js +269 -0
- package/dist/adapters/strict-schema.js.map +1 -0
- package/dist/adapters/wire.d.ts +77 -0
- package/dist/adapters/wire.js +137 -0
- package/dist/adapters/wire.js.map +1 -0
- package/dist/catalog.d.ts +65 -0
- package/dist/catalog.js +145 -0
- package/dist/catalog.js.map +1 -0
- package/dist/catalog.json +120 -0
- package/dist/classify.d.ts +25 -0
- package/dist/classify.js +37 -0
- package/dist/classify.js.map +1 -0
- package/dist/complete.d.ts +9 -0
- package/dist/complete.js +13 -0
- package/dist/complete.js.map +1 -0
- package/dist/cost.d.ts +42 -0
- package/dist/cost.js +122 -0
- package/dist/cost.js.map +1 -0
- package/dist/create-model.d.ts +7 -0
- package/dist/create-model.js +81 -0
- package/dist/create-model.js.map +1 -0
- package/dist/errors.d.ts +17 -0
- package/dist/errors.js +24 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/middleware.d.ts +11 -0
- package/dist/middleware.js +22 -0
- package/dist/middleware.js.map +1 -0
- package/dist/names.d.ts +72 -0
- package/dist/names.js +175 -0
- package/dist/names.js.map +1 -0
- package/dist/provider-config.d.ts +15 -0
- package/dist/provider-config.js +23 -0
- package/dist/provider-config.js.map +1 -0
- package/dist/request-dump.d.ts +28 -0
- package/dist/request-dump.js +52 -0
- package/dist/request-dump.js.map +1 -0
- package/dist/request-policy.d.ts +18 -0
- package/dist/request-policy.js +27 -0
- package/dist/request-policy.js.map +1 -0
- package/dist/retry.d.ts +30 -0
- package/dist/retry.js +191 -0
- package/dist/retry.js.map +1 -0
- package/dist/runtime-types.d.ts +112 -0
- package/dist/runtime-types.js +2 -0
- package/dist/runtime-types.js.map +1 -0
- package/dist/spec.d.ts +67 -0
- package/dist/spec.js +2 -0
- package/dist/spec.js.map +1 -0
- package/dist/sse.d.ts +15 -0
- package/dist/sse.js +73 -0
- package/dist/sse.js.map +1 -0
- package/dist/stream-contract.d.ts +23 -0
- package/dist/stream-contract.js +101 -0
- package/dist/stream-contract.js.map +1 -0
- package/dist/testing/guards.d.ts +16 -0
- package/dist/testing/guards.js +48 -0
- package/dist/testing/guards.js.map +1 -0
- package/dist/testing/index.d.ts +12 -0
- package/dist/testing/index.js +13 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/mock-transport.d.ts +49 -0
- package/dist/testing/mock-transport.js +101 -0
- package/dist/testing/mock-transport.js.map +1 -0
- package/dist/testing/random.d.ts +3 -0
- package/dist/testing/random.js +13 -0
- package/dist/testing/random.js.map +1 -0
- package/dist/testing/setup.d.ts +1 -0
- package/dist/testing/setup.js +12 -0
- package/dist/testing/setup.js.map +1 -0
- package/dist/transform-messages.d.ts +32 -0
- package/dist/transform-messages.js +291 -0
- package/dist/transform-messages.js.map +1 -0
- package/dist/types.d.ts +130 -0
- package/dist/types.js +6 -0
- package/dist/types.js.map +1 -0
- package/dist/usage.d.ts +8 -0
- package/dist/usage.js +20 -0
- package/dist/usage.js.map +1 -0
- package/package.json +50 -3
package/dist/retry.js
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTTP retries before any output (SDK decision 4; agent-SDK guide §2).
|
|
3
|
+
*
|
|
4
|
+
* - Only an `error` terminal of kind `retryable` that arrives before any content is retried. Once a block event has
|
|
5
|
+
* been streamed, a retry would replay output the caller has already seen, so the failure is final.
|
|
6
|
+
* - The backoff is exponential (2 s, then 4 s by default, as Vercel's AI SDK) and ends early when the signal aborts.
|
|
7
|
+
* - The caller sees one `start`, then one `retry` event per retry, then the last attempt's events. The final message
|
|
8
|
+
* counts the usage and cost of every attempt, because the provider bills failed attempts too. Each attempt is
|
|
9
|
+
* priced on its own before the sum, because a tiered rate depends on that request's input alone (D4).
|
|
10
|
+
* - A stream that throws is treated like one that ends with an `error` event, so the caller always gets a terminal.
|
|
11
|
+
* - A warning an earlier attempt already streamed, with the same code and message, is not streamed again, because a
|
|
12
|
+
* retry sends the same request and an adapter warns about it each time.
|
|
13
|
+
* - Each wait is capped at 60 s. The provider's retry-after hint isn't used yet: adapters see the response headers,
|
|
14
|
+
* and no event carries a hint to the gateway.
|
|
15
|
+
*/
|
|
16
|
+
import { classifyError, isTransportFailure } from "./classify.js";
|
|
17
|
+
import { foldCost } from "./cost.js";
|
|
18
|
+
import { addUsage, emptyUsage } from "./usage.js";
|
|
19
|
+
const BACKOFF_FACTOR = 2;
|
|
20
|
+
const MAX_RETRY_DELAY_MS = 60_000;
|
|
21
|
+
const UNKNOWN_COST = { total: null, basis: "unknown", currency: "USD" };
|
|
22
|
+
/**
|
|
23
|
+
* Adds a carried cost to an attempt's. The sum is unknown if either part is, a catalog estimate if either part is one,
|
|
24
|
+
* and a provider bill only when both parts are. `undefined` means no attempt is carried yet.
|
|
25
|
+
*/
|
|
26
|
+
function addCost(a, b) {
|
|
27
|
+
if (a === undefined)
|
|
28
|
+
return b;
|
|
29
|
+
if (a.total === null || b.total === null || a.basis === "unknown" || b.basis === "unknown") {
|
|
30
|
+
return { ...UNKNOWN_COST };
|
|
31
|
+
}
|
|
32
|
+
const total = a.total + b.total;
|
|
33
|
+
if (a.basis === "provider" && b.basis === "provider")
|
|
34
|
+
return { total, basis: "provider", currency: "USD" };
|
|
35
|
+
const catalogAsOf = b.catalogAsOf ?? a.catalogAsOf;
|
|
36
|
+
return { total, basis: "catalog", currency: "USD", ...(catalogAsOf === undefined ? {} : { catalogAsOf }) };
|
|
37
|
+
}
|
|
38
|
+
/** The default `Sleep`: a timer that resolves early, without rejecting, when the signal aborts. */
|
|
39
|
+
export const abortableSleep = (ms, signal) => new Promise((resolve) => {
|
|
40
|
+
if (signal?.aborted) {
|
|
41
|
+
resolve();
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
const onAbort = () => {
|
|
45
|
+
clearTimeout(timer);
|
|
46
|
+
resolve();
|
|
47
|
+
};
|
|
48
|
+
const timer = setTimeout(() => {
|
|
49
|
+
signal?.removeEventListener("abort", onAbort);
|
|
50
|
+
resolve();
|
|
51
|
+
}, ms);
|
|
52
|
+
signal?.addEventListener("abort", onAbort, { once: true });
|
|
53
|
+
});
|
|
54
|
+
/** True for a warning an earlier attempt streamed; any other warning is recorded as this attempt's. */
|
|
55
|
+
function isRepeatedWarning(event, call, output) {
|
|
56
|
+
if (event.type !== "warning")
|
|
57
|
+
return false;
|
|
58
|
+
const key = JSON.stringify([event.code, event.message]);
|
|
59
|
+
if (call.warned.has(key))
|
|
60
|
+
return true;
|
|
61
|
+
output.warned.add(key);
|
|
62
|
+
return false;
|
|
63
|
+
}
|
|
64
|
+
function isBlockEvent(event) {
|
|
65
|
+
return event.type !== "start" && event.type !== "warning" && event.type !== "done" && event.type !== "error";
|
|
66
|
+
}
|
|
67
|
+
/** The final message: this attempt's usage and `cost`, with the failed attempts' usage and cost added. */
|
|
68
|
+
function withCarried(message, call, cost) {
|
|
69
|
+
const summed = { ...message, usage: addUsage(call.carried, message.usage), cost: addCost(call.carriedCost, cost) };
|
|
70
|
+
// The projection needs one request's size, which a sum over several attempts overstates.
|
|
71
|
+
return call.carriedCost === undefined ? summed : { ...summed, lastAttemptUsage: message.usage };
|
|
72
|
+
}
|
|
73
|
+
/** A terminal event with the failed attempts added; any other event unchanged. The adapter's usage is priced here. */
|
|
74
|
+
function withCarriedUsage(event, call) {
|
|
75
|
+
if (event.type !== "done" && event.type !== "error")
|
|
76
|
+
return event;
|
|
77
|
+
return { ...event, message: withCarried(event.message, call, foldCost(event.message, call.price)) };
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The message for an adapter whose stream threw instead of ending with an `error` event. Its usage is zero, because
|
|
81
|
+
* nothing reported any, but its cost is unknown, not zero: the request may have reached the provider and been billed.
|
|
82
|
+
*/
|
|
83
|
+
function thrownFailure(thrown, call) {
|
|
84
|
+
const base = {
|
|
85
|
+
role: "assistant",
|
|
86
|
+
content: [],
|
|
87
|
+
model: call.ref,
|
|
88
|
+
usage: emptyUsage(),
|
|
89
|
+
cost: { ...UNKNOWN_COST },
|
|
90
|
+
};
|
|
91
|
+
if (call.signal?.aborted)
|
|
92
|
+
return { ...base, stopReason: "aborted" };
|
|
93
|
+
const name = thrown instanceof Error ? thrown.name : "Error";
|
|
94
|
+
const message = `${name}: ${thrown instanceof Error ? thrown.message : String(thrown)}`;
|
|
95
|
+
// Only a failed fetch is a transport failure worth retrying; any other throw is a bug or a guard, so it is final.
|
|
96
|
+
const kind = isTransportFailure(thrown) ? classifyError({ message }) : "fatal";
|
|
97
|
+
return { ...base, stopReason: "error", error: { kind, message } };
|
|
98
|
+
}
|
|
99
|
+
/** Forwards an attempt's events until it ends or fails retryably before any output. */
|
|
100
|
+
async function* forwardEvents(events, call, mayRetry, output) {
|
|
101
|
+
for await (const event of events) {
|
|
102
|
+
if (event.type === "start") {
|
|
103
|
+
if (call.started)
|
|
104
|
+
continue;
|
|
105
|
+
call.started = true;
|
|
106
|
+
}
|
|
107
|
+
if (isRepeatedWarning(event, call, output))
|
|
108
|
+
continue;
|
|
109
|
+
if (event.type === "error" && mayRetry && !output.seen && event.message.error?.kind === "retryable") {
|
|
110
|
+
return { retry: true, failure: event.message, cost: foldCost(event.message, call.price) };
|
|
111
|
+
}
|
|
112
|
+
if (isBlockEvent(event))
|
|
113
|
+
output.seen = true;
|
|
114
|
+
yield withCarriedUsage(event, call);
|
|
115
|
+
}
|
|
116
|
+
return { retry: false };
|
|
117
|
+
}
|
|
118
|
+
/** Runs one attempt, keeping only the first attempt's `start`, and holds back a retryable failure. */
|
|
119
|
+
async function* runAttempt(events, call, mayRetry) {
|
|
120
|
+
const output = { seen: false, warned: new Set() };
|
|
121
|
+
let failure;
|
|
122
|
+
try {
|
|
123
|
+
return yield* forwardEvents(events, call, mayRetry, output);
|
|
124
|
+
}
|
|
125
|
+
catch (thrown) {
|
|
126
|
+
// A thrown stream is a failure like any other: it ends in an `error` terminal and may be retried.
|
|
127
|
+
failure = thrownFailure(thrown, call);
|
|
128
|
+
}
|
|
129
|
+
finally {
|
|
130
|
+
for (const key of output.warned)
|
|
131
|
+
call.warned.add(key);
|
|
132
|
+
}
|
|
133
|
+
// The failure's unknown cost is final: pricing its zero usage would claim a known zero.
|
|
134
|
+
if (mayRetry && !output.seen && failure.error?.kind === "retryable") {
|
|
135
|
+
return { retry: true, failure, cost: failure.cost };
|
|
136
|
+
}
|
|
137
|
+
if (!call.started) {
|
|
138
|
+
call.started = true;
|
|
139
|
+
yield { type: "start" };
|
|
140
|
+
}
|
|
141
|
+
yield { type: "error", message: withCarried(failure, call, failure.cost) };
|
|
142
|
+
return { retry: false };
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The terminal for a call aborted between attempts. It keeps every failed attempt's usage and drops the error.
|
|
146
|
+
* `call.carried` already includes `failure`, so `lastAttemptUsage` is set only when `retried` says earlier attempts
|
|
147
|
+
* were carried too, as `withCarried` does.
|
|
148
|
+
*/
|
|
149
|
+
function abortedTerminal(failure, call, cost, retried) {
|
|
150
|
+
const { error: _error, ...rest } = failure;
|
|
151
|
+
const message = { ...rest, stopReason: "aborted", usage: call.carried, cost };
|
|
152
|
+
return { type: "error", message: retried ? { ...message, lastAttemptUsage: failure.usage } : message };
|
|
153
|
+
}
|
|
154
|
+
/** Runs `attempt(1)`, then retries per `settings`. `attempt(n)` must start a fresh request each time it is called. */
|
|
155
|
+
export async function* withRetries(attempt, ref, signal, settings) {
|
|
156
|
+
const call = {
|
|
157
|
+
ref,
|
|
158
|
+
signal,
|
|
159
|
+
price: settings.price,
|
|
160
|
+
started: false,
|
|
161
|
+
carried: emptyUsage(),
|
|
162
|
+
carriedCost: undefined,
|
|
163
|
+
warned: new Set(),
|
|
164
|
+
};
|
|
165
|
+
for (let n = 1;; n += 1) {
|
|
166
|
+
const outcome = yield* runAttempt(attempt(n), call, n <= settings.retries);
|
|
167
|
+
if (!outcome.retry)
|
|
168
|
+
return;
|
|
169
|
+
call.carried = addUsage(call.carried, outcome.failure.usage);
|
|
170
|
+
const carriedCost = addCost(call.carriedCost, outcome.cost);
|
|
171
|
+
call.carriedCost = carriedCost;
|
|
172
|
+
// The stream rule puts `start` first, so a failure that arrived without one still gets it before the retry.
|
|
173
|
+
if (!call.started) {
|
|
174
|
+
call.started = true;
|
|
175
|
+
yield { type: "start" };
|
|
176
|
+
}
|
|
177
|
+
if (signal?.aborted) {
|
|
178
|
+
yield abortedTerminal(outcome.failure, call, carriedCost, n > 1);
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
// The cap keeps a long retry count from waiting hours, or overflowing setTimeout's 32-bit delay.
|
|
182
|
+
const delayMs = Math.min(settings.initialDelayMs * BACKOFF_FACTOR ** (n - 1), MAX_RETRY_DELAY_MS);
|
|
183
|
+
yield { type: "retry", attempt: n, delayMs, error: outcome.failure.error?.message ?? "retryable error" };
|
|
184
|
+
await settings.sleep(delayMs, signal);
|
|
185
|
+
if (signal?.aborted) {
|
|
186
|
+
yield abortedTerminal(outcome.failure, call, carriedCost, n > 1);
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
//# sourceMappingURL=retry.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP retries before any output (SDK decision 4; agent-SDK guide §2).\n *\n * - Only an `error` terminal of kind `retryable` that arrives before any content is retried. Once a block event has\n * been streamed, a retry would replay output the caller has already seen, so the failure is final.\n * - The backoff is exponential (2 s, then 4 s by default, as Vercel's AI SDK) and ends early when the signal aborts.\n * - The caller sees one `start`, then one `retry` event per retry, then the last attempt's events. The final message\n * counts the usage and cost of every attempt, because the provider bills failed attempts too. Each attempt is\n * priced on its own before the sum, because a tiered rate depends on that request's input alone (D4).\n * - A stream that throws is treated like one that ends with an `error` event, so the caller always gets a terminal.\n * - A warning an earlier attempt already streamed, with the same code and message, is not streamed again, because a\n * retry sends the same request and an adapter warns about it each time.\n * - Each wait is capped at 60 s. The provider's retry-after hint isn't used yet: adapters see the response headers,\n * and no event carries a hint to the gateway.\n */\n\nimport { classifyError, isTransportFailure } from \"./classify.js\";\nimport { foldCost } from \"./cost.js\";\nimport type { GatewayEvent, Sleep } from \"./runtime-types.js\";\nimport type { ModelEvent } from \"./spec.js\";\nimport type { AssistantMessage, Cost, ModelRef, Usage } from \"./types.js\";\nimport { addUsage, emptyUsage } from \"./usage.js\";\n\n/** How many times to retry, how long to wait, and how. */\nexport interface RetrySettings {\n readonly retries: number;\n readonly initialDelayMs: number;\n readonly sleep: Sleep;\n /** Prices one attempt's usage; a provider-billed total skips it. */\n readonly price: (usage: Usage) => Cost;\n}\n\nconst BACKOFF_FACTOR = 2;\nconst MAX_RETRY_DELAY_MS = 60_000;\nconst UNKNOWN_COST: Cost = { total: null, basis: \"unknown\", currency: \"USD\" };\n\n/**\n * Adds a carried cost to an attempt's. The sum is unknown if either part is, a catalog estimate if either part is one,\n * and a provider bill only when both parts are. `undefined` means no attempt is carried yet.\n */\nfunction addCost(a: Cost | undefined, b: Cost): Cost {\n if (a === undefined) return b;\n if (a.total === null || b.total === null || a.basis === \"unknown\" || b.basis === \"unknown\") {\n return { ...UNKNOWN_COST };\n }\n const total = a.total + b.total;\n if (a.basis === \"provider\" && b.basis === \"provider\") return { total, basis: \"provider\", currency: \"USD\" };\n const catalogAsOf = b.catalogAsOf ?? a.catalogAsOf;\n return { total, basis: \"catalog\", currency: \"USD\", ...(catalogAsOf === undefined ? {} : { catalogAsOf }) };\n}\n\n/** The default `Sleep`: a timer that resolves early, without rejecting, when the signal aborts. */\nexport const abortableSleep: Sleep = (ms, signal) =>\n new Promise((resolve) => {\n if (signal?.aborted) {\n resolve();\n return;\n }\n const onAbort = (): void => {\n clearTimeout(timer);\n resolve();\n };\n const timer = setTimeout(() => {\n signal?.removeEventListener(\"abort\", onAbort);\n resolve();\n }, ms);\n signal?.addEventListener(\"abort\", onAbort, { once: true });\n });\n\n/**\n * How one attempt ended: it ran to its end, or it failed before any output and may be retried. A retryable failure\n * carries its own cost, already priced.\n */\ntype AttemptOutcome =\n | { readonly retry: false }\n | { readonly retry: true; readonly failure: AssistantMessage; readonly cost: Cost };\n\n/** One call's state across its attempts. */\ninterface CallState {\n readonly ref: ModelRef;\n readonly signal: AbortSignal | undefined;\n readonly price: (usage: Usage) => Cost;\n started: boolean;\n /** The usage of the failed attempts so far; the final message adds it, because the provider billed them too. */\n carried: Usage;\n /** The cost of the failed attempts so far, added the same way; `undefined` until an attempt has failed. */\n carriedCost: Cost | undefined;\n /** The code and message of each warning the earlier attempts streamed. */\n readonly warned: Set<string>;\n}\n\n/** One attempt's progress: whether content has reached the caller, and the warnings it streamed. */\ninterface AttemptProgress {\n seen: boolean;\n readonly warned: Set<string>;\n}\n\n/** True for a warning an earlier attempt streamed; any other warning is recorded as this attempt's. */\nfunction isRepeatedWarning(event: ModelEvent, call: CallState, output: AttemptProgress): boolean {\n if (event.type !== \"warning\") return false;\n const key = JSON.stringify([event.code, event.message]);\n if (call.warned.has(key)) return true;\n output.warned.add(key);\n return false;\n}\n\nfunction isBlockEvent(event: ModelEvent): boolean {\n return event.type !== \"start\" && event.type !== \"warning\" && event.type !== \"done\" && event.type !== \"error\";\n}\n\n/** The final message: this attempt's usage and `cost`, with the failed attempts' usage and cost added. */\nfunction withCarried(message: AssistantMessage, call: CallState, cost: Cost): AssistantMessage {\n const summed = { ...message, usage: addUsage(call.carried, message.usage), cost: addCost(call.carriedCost, cost) };\n // The projection needs one request's size, which a sum over several attempts overstates.\n return call.carriedCost === undefined ? summed : { ...summed, lastAttemptUsage: message.usage };\n}\n\n/** A terminal event with the failed attempts added; any other event unchanged. The adapter's usage is priced here. */\nfunction withCarriedUsage(event: GatewayEvent, call: CallState): GatewayEvent {\n if (event.type !== \"done\" && event.type !== \"error\") return event;\n return { ...event, message: withCarried(event.message, call, foldCost(event.message, call.price)) };\n}\n\n/**\n * The message for an adapter whose stream threw instead of ending with an `error` event. Its usage is zero, because\n * nothing reported any, but its cost is unknown, not zero: the request may have reached the provider and been billed.\n */\nfunction thrownFailure(thrown: unknown, call: CallState): AssistantMessage {\n const base = {\n role: \"assistant\" as const,\n content: [],\n model: call.ref,\n usage: emptyUsage(),\n cost: { ...UNKNOWN_COST },\n };\n if (call.signal?.aborted) return { ...base, stopReason: \"aborted\" };\n const name = thrown instanceof Error ? thrown.name : \"Error\";\n const message = `${name}: ${thrown instanceof Error ? thrown.message : String(thrown)}`;\n // Only a failed fetch is a transport failure worth retrying; any other throw is a bug or a guard, so it is final.\n const kind = isTransportFailure(thrown) ? classifyError({ message }) : \"fatal\";\n return { ...base, stopReason: \"error\", error: { kind, message } };\n}\n\n/** Forwards an attempt's events until it ends or fails retryably before any output. */\nasync function* forwardEvents(\n events: AsyncIterable<ModelEvent>,\n call: CallState,\n mayRetry: boolean,\n output: AttemptProgress,\n): AsyncGenerator<GatewayEvent, AttemptOutcome> {\n for await (const event of events) {\n if (event.type === \"start\") {\n if (call.started) continue;\n call.started = true;\n }\n if (isRepeatedWarning(event, call, output)) continue;\n if (event.type === \"error\" && mayRetry && !output.seen && event.message.error?.kind === \"retryable\") {\n return { retry: true, failure: event.message, cost: foldCost(event.message, call.price) };\n }\n if (isBlockEvent(event)) output.seen = true;\n yield withCarriedUsage(event, call);\n }\n return { retry: false };\n}\n\n/** Runs one attempt, keeping only the first attempt's `start`, and holds back a retryable failure. */\nasync function* runAttempt(\n events: AsyncIterable<ModelEvent>,\n call: CallState,\n mayRetry: boolean,\n): AsyncGenerator<GatewayEvent, AttemptOutcome> {\n const output: AttemptProgress = { seen: false, warned: new Set() };\n let failure: AssistantMessage;\n try {\n return yield* forwardEvents(events, call, mayRetry, output);\n } catch (thrown) {\n // A thrown stream is a failure like any other: it ends in an `error` terminal and may be retried.\n failure = thrownFailure(thrown, call);\n } finally {\n for (const key of output.warned) call.warned.add(key);\n }\n // The failure's unknown cost is final: pricing its zero usage would claim a known zero.\n if (mayRetry && !output.seen && failure.error?.kind === \"retryable\") {\n return { retry: true, failure, cost: failure.cost };\n }\n if (!call.started) {\n call.started = true;\n yield { type: \"start\" };\n }\n yield { type: \"error\", message: withCarried(failure, call, failure.cost) };\n return { retry: false };\n}\n\n/**\n * The terminal for a call aborted between attempts. It keeps every failed attempt's usage and drops the error.\n * `call.carried` already includes `failure`, so `lastAttemptUsage` is set only when `retried` says earlier attempts\n * were carried too, as `withCarried` does.\n */\nfunction abortedTerminal(failure: AssistantMessage, call: CallState, cost: Cost, retried: boolean): GatewayEvent {\n const { error: _error, ...rest } = failure;\n const message = { ...rest, stopReason: \"aborted\" as const, usage: call.carried, cost };\n return { type: \"error\", message: retried ? { ...message, lastAttemptUsage: failure.usage } : message };\n}\n\n/** Runs `attempt(1)`, then retries per `settings`. `attempt(n)` must start a fresh request each time it is called. */\nexport async function* withRetries(\n attempt: (n: number) => AsyncIterable<ModelEvent>,\n ref: ModelRef,\n signal: AbortSignal | undefined,\n settings: RetrySettings,\n): AsyncGenerator<GatewayEvent> {\n const call: CallState = {\n ref,\n signal,\n price: settings.price,\n started: false,\n carried: emptyUsage(),\n carriedCost: undefined,\n warned: new Set(),\n };\n for (let n = 1; ; n += 1) {\n const outcome = yield* runAttempt(attempt(n), call, n <= settings.retries);\n if (!outcome.retry) return;\n call.carried = addUsage(call.carried, outcome.failure.usage);\n const carriedCost = addCost(call.carriedCost, outcome.cost);\n call.carriedCost = carriedCost;\n // The stream rule puts `start` first, so a failure that arrived without one still gets it before the retry.\n if (!call.started) {\n call.started = true;\n yield { type: \"start\" };\n }\n if (signal?.aborted) {\n yield abortedTerminal(outcome.failure, call, carriedCost, n > 1);\n return;\n }\n // The cap keeps a long retry count from waiting hours, or overflowing setTimeout's 32-bit delay.\n const delayMs = Math.min(settings.initialDelayMs * BACKOFF_FACTOR ** (n - 1), MAX_RETRY_DELAY_MS);\n yield { type: \"retry\", attempt: n, delayMs, error: outcome.failure.error?.message ?? \"retryable error\" };\n await settings.sleep(delayMs, signal);\n if (signal?.aborted) {\n yield abortedTerminal(outcome.failure, call, carriedCost, n > 1);\n return;\n }\n }\n}\n"]}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/** Gateway runtime types (SDK plan §3.2; SDK decisions 4, 13). */
|
|
2
|
+
import type { PriceCatalog } from "./catalog.js";
|
|
3
|
+
import type { ModelAdapter, ModelEvent, StreamOptions } from "./spec.js";
|
|
4
|
+
import type { AssistantMessage, Cost, ModelCaps, ModelContext, ModelRef, Usage } from "./types.js";
|
|
5
|
+
/** How an adapter sends HTTP. Defaults to `globalThis.fetch`. */
|
|
6
|
+
export type Transport = (request: Request) => Promise<Response>;
|
|
7
|
+
/**
|
|
8
|
+
* What an adapter factory takes. The key is always passed in: the gateway never reads one from the environment and
|
|
9
|
+
* never falls back to another credential.
|
|
10
|
+
*/
|
|
11
|
+
export interface ProviderConfig {
|
|
12
|
+
/** The provider API key. An empty or missing key fails before any request is sent. */
|
|
13
|
+
apiKey: string;
|
|
14
|
+
/** Overrides the provider's default endpoint, for a proxy or a mock server. */
|
|
15
|
+
baseURL?: string;
|
|
16
|
+
/** Sends the HTTP requests. Defaults to `globalThis.fetch`. */
|
|
17
|
+
transport?: Transport;
|
|
18
|
+
/** Extra headers sent with every request. */
|
|
19
|
+
headers?: Record<string, string>;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The events `Model.stream()` yields: the adapter's events plus one `retry` event before each retry. Retry events come
|
|
23
|
+
* after `start` and before any content, because the gateway never retries once output has been streamed.
|
|
24
|
+
*/
|
|
25
|
+
export type GatewayEvent = ModelEvent | {
|
|
26
|
+
type: "retry";
|
|
27
|
+
/** 1 for the first retry, 2 for the second, and so on. */
|
|
28
|
+
attempt: number;
|
|
29
|
+
/** How long the gateway waits before the next attempt. */
|
|
30
|
+
delayMs: number;
|
|
31
|
+
/** The failed attempt's error message. */
|
|
32
|
+
error: string;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* The options of one call through a `Model`: the adapter's `StreamOptions` without `caps`, which `createModel()` sets
|
|
36
|
+
* itself from the caps it resolved.
|
|
37
|
+
*/
|
|
38
|
+
export type ModelCallOptions = Omit<StreamOptions, "caps">;
|
|
39
|
+
/** The stream options a request dump records: everything except the abort signal and the payload hook. */
|
|
40
|
+
export type DumpedOptions = Omit<StreamOptions, "signal" | "onPayload" | "caps">;
|
|
41
|
+
/** The full request of one HTTP request of an attempt, as `onRequest` receives it. */
|
|
42
|
+
export interface RequestDump {
|
|
43
|
+
/** 1 for the first attempt, 2 for the first retry, and so on. */
|
|
44
|
+
readonly attempt: number;
|
|
45
|
+
readonly model: ModelRef;
|
|
46
|
+
readonly context: ModelContext;
|
|
47
|
+
readonly options: DumpedOptions;
|
|
48
|
+
/** The wire body after `onPayload`, or `undefined` for an adapter that sends no wire body, such as a test model. */
|
|
49
|
+
readonly body: unknown;
|
|
50
|
+
}
|
|
51
|
+
/** The request a middleware may rewrite: the context and the stream options. */
|
|
52
|
+
export interface MiddlewareParams {
|
|
53
|
+
context: ModelContext;
|
|
54
|
+
options: ModelCallOptions;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Shared behaviour around every model call. In `createModel({ middleware: [a, b] })`, `a` is outermost: `a`'s
|
|
58
|
+
* `transformParams` runs before `b`'s, and `a`'s `wrapStream` wraps `b`'s. Both run once per call, outside the
|
|
59
|
+
* retries, so `next()` yields any `retry` events.
|
|
60
|
+
*/
|
|
61
|
+
export interface ModelMiddleware {
|
|
62
|
+
/** Rewrites the request before it is sent. */
|
|
63
|
+
transformParams?(params: MiddlewareParams): MiddlewareParams | Promise<MiddlewareParams>;
|
|
64
|
+
/** Wraps the event stream; call `next()` to run the inner middleware and the model. */
|
|
65
|
+
wrapStream?(e: {
|
|
66
|
+
next: () => AsyncIterable<GatewayEvent>;
|
|
67
|
+
context: ModelContext;
|
|
68
|
+
options: ModelCallOptions;
|
|
69
|
+
}): AsyncIterable<GatewayEvent>;
|
|
70
|
+
}
|
|
71
|
+
/** Waits `ms` milliseconds, or less if `signal` aborts first. It must resolve, not reject, on abort. */
|
|
72
|
+
export type Sleep = (ms: number, signal: AbortSignal | undefined) => Promise<void>;
|
|
73
|
+
/** What `createModel()` takes. The adapter is an object: a bare model id string is a type error. */
|
|
74
|
+
export interface CreateModelOptions {
|
|
75
|
+
adapter: ModelAdapter;
|
|
76
|
+
/** The provider's model id. */
|
|
77
|
+
id: string;
|
|
78
|
+
/** HTTP retries before any output. Default 2. Only `retryable` errors are retried. */
|
|
79
|
+
retries?: number;
|
|
80
|
+
/** Delay before the first retry in milliseconds. Default 2000; each later retry waits twice as long. */
|
|
81
|
+
initialRetryDelayMs?: number;
|
|
82
|
+
/** First is outermost. */
|
|
83
|
+
middleware?: readonly ModelMiddleware[];
|
|
84
|
+
/**
|
|
85
|
+
* Where `caps` and prices come from. Defaults to the catalog that ships with the gateway; a catalog you pass
|
|
86
|
+
* replaces it. A model missing from it gets the adapter's default caps and an unknown price. It is checked like
|
|
87
|
+
* `parseCatalog()`, so a malformed catalog throws a `GatewayError` with code `invalid_catalog`.
|
|
88
|
+
*/
|
|
89
|
+
catalog?: PriceCatalog;
|
|
90
|
+
/** Receives the full request before each attempt is sent. */
|
|
91
|
+
onRequest?(dump: RequestDump): void;
|
|
92
|
+
/** Waits between retries. Defaults to an abortable timer; tests pass a fake to skip the wait. */
|
|
93
|
+
sleep?: Sleep;
|
|
94
|
+
}
|
|
95
|
+
/** A model bound to one adapter and id, with the gateway's retries, middleware and request dump around it. */
|
|
96
|
+
export interface Model {
|
|
97
|
+
readonly ref: ModelRef;
|
|
98
|
+
/** The context window and output limit, from the catalog or the adapter's defaults. */
|
|
99
|
+
readonly caps: ModelCaps;
|
|
100
|
+
/** Streams one call. A failed call ends with an `error` event; only a middleware that throws makes this throw. */
|
|
101
|
+
stream(context: ModelContext, options?: ModelCallOptions): AsyncIterable<GatewayEvent>;
|
|
102
|
+
/** Reads `stream()` to its end and returns the final message, including a failed call's message. */
|
|
103
|
+
complete(context: ModelContext, options?: ModelCallOptions): Promise<AssistantMessage>;
|
|
104
|
+
/**
|
|
105
|
+
* Prices one request's usage with the model's catalog entry, choosing the rate tier by that request's input. A
|
|
106
|
+
* model the catalog lacks gets `{ total: null, basis: "unknown" }`. To re-price a retried call, price each request
|
|
107
|
+
* apart, such as `message.lastAttemptUsage ?? message.usage` for the last one: its summed `usage` could select the
|
|
108
|
+
* wrong tier. You rarely need to, because `message.cost` already covers every attempt, priced this way unless the
|
|
109
|
+
* provider reported a billed total.
|
|
110
|
+
*/
|
|
111
|
+
price(usage: Usage): Cost;
|
|
112
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"runtime-types.js","sourceRoot":"","sources":["../src/runtime-types.ts"],"names":[],"mappings":"","sourcesContent":["/** Gateway runtime types (SDK plan §3.2; SDK decisions 4, 13). */\nimport type { PriceCatalog } from \"./catalog.js\";\nimport type { ModelAdapter, ModelEvent, StreamOptions } from \"./spec.js\";\nimport type { AssistantMessage, Cost, ModelCaps, ModelContext, ModelRef, Usage } from \"./types.js\";\n\n/** How an adapter sends HTTP. Defaults to `globalThis.fetch`. */\nexport type Transport = (request: Request) => Promise<Response>;\n\n/**\n * What an adapter factory takes. The key is always passed in: the gateway never reads one from the environment and\n * never falls back to another credential.\n */\nexport interface ProviderConfig {\n /** The provider API key. An empty or missing key fails before any request is sent. */\n apiKey: string;\n /** Overrides the provider's default endpoint, for a proxy or a mock server. */\n baseURL?: string;\n /** Sends the HTTP requests. Defaults to `globalThis.fetch`. */\n transport?: Transport;\n /** Extra headers sent with every request. */\n headers?: Record<string, string>;\n}\n\n/**\n * The events `Model.stream()` yields: the adapter's events plus one `retry` event before each retry. Retry events come\n * after `start` and before any content, because the gateway never retries once output has been streamed.\n */\nexport type GatewayEvent =\n | ModelEvent\n | {\n type: \"retry\";\n /** 1 for the first retry, 2 for the second, and so on. */\n attempt: number;\n /** How long the gateway waits before the next attempt. */\n delayMs: number;\n /** The failed attempt's error message. */\n error: string;\n };\n\n/**\n * The options of one call through a `Model`: the adapter's `StreamOptions` without `caps`, which `createModel()` sets\n * itself from the caps it resolved.\n */\nexport type ModelCallOptions = Omit<StreamOptions, \"caps\">;\n\n/** The stream options a request dump records: everything except the abort signal and the payload hook. */\nexport type DumpedOptions = Omit<StreamOptions, \"signal\" | \"onPayload\" | \"caps\">;\n\n/** The full request of one HTTP request of an attempt, as `onRequest` receives it. */\nexport interface RequestDump {\n /** 1 for the first attempt, 2 for the first retry, and so on. */\n readonly attempt: number;\n readonly model: ModelRef;\n readonly context: ModelContext;\n readonly options: DumpedOptions;\n /** The wire body after `onPayload`, or `undefined` for an adapter that sends no wire body, such as a test model. */\n readonly body: unknown;\n}\n\n/** The request a middleware may rewrite: the context and the stream options. */\nexport interface MiddlewareParams {\n context: ModelContext;\n options: ModelCallOptions;\n}\n\n/**\n * Shared behaviour around every model call. In `createModel({ middleware: [a, b] })`, `a` is outermost: `a`'s\n * `transformParams` runs before `b`'s, and `a`'s `wrapStream` wraps `b`'s. Both run once per call, outside the\n * retries, so `next()` yields any `retry` events.\n */\nexport interface ModelMiddleware {\n /** Rewrites the request before it is sent. */\n transformParams?(params: MiddlewareParams): MiddlewareParams | Promise<MiddlewareParams>;\n /** Wraps the event stream; call `next()` to run the inner middleware and the model. */\n wrapStream?(e: {\n next: () => AsyncIterable<GatewayEvent>;\n context: ModelContext;\n options: ModelCallOptions;\n }): AsyncIterable<GatewayEvent>;\n}\n\n/** Waits `ms` milliseconds, or less if `signal` aborts first. It must resolve, not reject, on abort. */\nexport type Sleep = (ms: number, signal: AbortSignal | undefined) => Promise<void>;\n\n/** What `createModel()` takes. The adapter is an object: a bare model id string is a type error. */\nexport interface CreateModelOptions {\n adapter: ModelAdapter;\n /** The provider's model id. */\n id: string;\n /** HTTP retries before any output. Default 2. Only `retryable` errors are retried. */\n retries?: number;\n /** Delay before the first retry in milliseconds. Default 2000; each later retry waits twice as long. */\n initialRetryDelayMs?: number;\n /** First is outermost. */\n middleware?: readonly ModelMiddleware[];\n /**\n * Where `caps` and prices come from. Defaults to the catalog that ships with the gateway; a catalog you pass\n * replaces it. A model missing from it gets the adapter's default caps and an unknown price. It is checked like\n * `parseCatalog()`, so a malformed catalog throws a `GatewayError` with code `invalid_catalog`.\n */\n catalog?: PriceCatalog;\n /** Receives the full request before each attempt is sent. */\n onRequest?(dump: RequestDump): void;\n /** Waits between retries. Defaults to an abortable timer; tests pass a fake to skip the wait. */\n sleep?: Sleep;\n}\n\n/** A model bound to one adapter and id, with the gateway's retries, middleware and request dump around it. */\nexport interface Model {\n readonly ref: ModelRef;\n /** The context window and output limit, from the catalog or the adapter's defaults. */\n readonly caps: ModelCaps;\n /** Streams one call. A failed call ends with an `error` event; only a middleware that throws makes this throw. */\n stream(context: ModelContext, options?: ModelCallOptions): AsyncIterable<GatewayEvent>;\n /** Reads `stream()` to its end and returns the final message, including a failed call's message. */\n complete(context: ModelContext, options?: ModelCallOptions): Promise<AssistantMessage>;\n /**\n * Prices one request's usage with the model's catalog entry, choosing the rate tier by that request's input. A\n * model the catalog lacks gets `{ total: null, basis: \"unknown\" }`. To re-price a retried call, price each request\n * apart, such as `message.lastAttemptUsage ?? message.usage` for the last one: its summed `usage` could select the\n * wrong tier. You rarely need to, because `message.cost` already covers every attempt, priced this way unless the\n * provider reported a billed total.\n */\n price(usage: Usage): Cost;\n}\n"]}
|
package/dist/spec.d.ts
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** The single-method model spec every provider adapter implements (SDK plan §3.2; SDK decision 1). */
|
|
2
|
+
import type { AssistantMessage, ContentBlock, ModelCaps, ModelContext, ModelRef } from "./types.js";
|
|
3
|
+
/** The events one model call streams. Exactly one terminal event, `done` or `error`, ends every stream. */
|
|
4
|
+
export type ModelEvent = {
|
|
5
|
+
type: "start";
|
|
6
|
+
} | {
|
|
7
|
+
type: "text_start" | "reasoning_start" | "tool_input_start";
|
|
8
|
+
index: number;
|
|
9
|
+
} | {
|
|
10
|
+
type: "text_delta" | "reasoning_delta" | "tool_input_delta";
|
|
11
|
+
index: number;
|
|
12
|
+
delta: string;
|
|
13
|
+
} | {
|
|
14
|
+
type: "text_end" | "reasoning_end" | "tool_input_end";
|
|
15
|
+
index: number;
|
|
16
|
+
block: ContentBlock;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Something the caller should know that does not stop the call, such as an option the provider would reject and
|
|
20
|
+
* the adapter dropped. `code` names the case in snake_case; `message` explains it. A warning is not output, so a
|
|
21
|
+
* call can still be retried after one.
|
|
22
|
+
*/
|
|
23
|
+
| {
|
|
24
|
+
type: "warning";
|
|
25
|
+
code: string;
|
|
26
|
+
message: string;
|
|
27
|
+
} | {
|
|
28
|
+
type: "done";
|
|
29
|
+
message: AssistantMessage;
|
|
30
|
+
}
|
|
31
|
+
/** The message's `stopReason` is `"error"` or `"aborted"`; it carries any partial content and usage. */
|
|
32
|
+
| {
|
|
33
|
+
type: "error";
|
|
34
|
+
message: AssistantMessage;
|
|
35
|
+
};
|
|
36
|
+
export interface StreamOptions {
|
|
37
|
+
signal?: AbortSignal;
|
|
38
|
+
maxOutputTokens?: number;
|
|
39
|
+
temperature?: number;
|
|
40
|
+
/** One portable caching policy that each adapter maps to its provider's controls. */
|
|
41
|
+
cacheRetention?: "none" | "short" | "long";
|
|
42
|
+
/** Escape hatch only. */
|
|
43
|
+
providerOptions?: Record<string, unknown>;
|
|
44
|
+
/**
|
|
45
|
+
* The model's caps. `createModel()` sets them on every call to the caps it resolved, from its catalog or the
|
|
46
|
+
* adapter's `defaultCaps`, after middleware has run, so a `Model`'s options (`ModelCallOptions`) leave them out and
|
|
47
|
+
* any `caps` a caller or middleware passes anyway is replaced. An adapter called directly without them uses its
|
|
48
|
+
* `defaultCaps`.
|
|
49
|
+
*/
|
|
50
|
+
caps?: ModelCaps;
|
|
51
|
+
/**
|
|
52
|
+
* Inspect or replace the request body before it is sent. Return the body to send, or `undefined` to send it
|
|
53
|
+
* unchanged. An adapter calls it once per HTTP request, just before sending, so an adapter that sends a second
|
|
54
|
+
* request within one attempt calls it twice.
|
|
55
|
+
*/
|
|
56
|
+
onPayload?(body: unknown): unknown;
|
|
57
|
+
}
|
|
58
|
+
export interface ModelAdapter {
|
|
59
|
+
readonly specificationVersion: "v1";
|
|
60
|
+
/** Wire protocol, for example `"anthropic-messages"`. */
|
|
61
|
+
readonly api: string;
|
|
62
|
+
/** Vendor and catalog entry. */
|
|
63
|
+
readonly provider: string;
|
|
64
|
+
/** Caps for a model the catalog does not list. Without them, `createModel()` needs a catalog entry. */
|
|
65
|
+
readonly defaultCaps?: ModelCaps;
|
|
66
|
+
stream(model: ModelRef, context: ModelContext, options: StreamOptions): AsyncIterable<ModelEvent>;
|
|
67
|
+
}
|
package/dist/spec.js
ADDED
package/dist/spec.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"","sourcesContent":["/** The single-method model spec every provider adapter implements (SDK plan §3.2; SDK decision 1). */\nimport type { AssistantMessage, ContentBlock, ModelCaps, ModelContext, ModelRef } from \"./types.js\";\n\n/** The events one model call streams. Exactly one terminal event, `done` or `error`, ends every stream. */\nexport type ModelEvent =\n | { type: \"start\" }\n | { type: \"text_start\" | \"reasoning_start\" | \"tool_input_start\"; index: number }\n | { type: \"text_delta\" | \"reasoning_delta\" | \"tool_input_delta\"; index: number; delta: string }\n | { type: \"text_end\" | \"reasoning_end\" | \"tool_input_end\"; index: number; block: ContentBlock }\n /**\n * Something the caller should know that does not stop the call, such as an option the provider would reject and\n * the adapter dropped. `code` names the case in snake_case; `message` explains it. A warning is not output, so a\n * call can still be retried after one.\n */\n | { type: \"warning\"; code: string; message: string }\n | { type: \"done\"; message: AssistantMessage }\n /** The message's `stopReason` is `\"error\"` or `\"aborted\"`; it carries any partial content and usage. */\n | { type: \"error\"; message: AssistantMessage };\n\nexport interface StreamOptions {\n signal?: AbortSignal;\n maxOutputTokens?: number;\n temperature?: number;\n /** One portable caching policy that each adapter maps to its provider's controls. */\n cacheRetention?: \"none\" | \"short\" | \"long\";\n /** Escape hatch only. */\n providerOptions?: Record<string, unknown>;\n /**\n * The model's caps. `createModel()` sets them on every call to the caps it resolved, from its catalog or the\n * adapter's `defaultCaps`, after middleware has run, so a `Model`'s options (`ModelCallOptions`) leave them out and\n * any `caps` a caller or middleware passes anyway is replaced. An adapter called directly without them uses its\n * `defaultCaps`.\n */\n caps?: ModelCaps;\n /**\n * Inspect or replace the request body before it is sent. Return the body to send, or `undefined` to send it\n * unchanged. An adapter calls it once per HTTP request, just before sending, so an adapter that sends a second\n * request within one attempt calls it twice.\n */\n onPayload?(body: unknown): unknown;\n}\n\nexport interface ModelAdapter {\n readonly specificationVersion: \"v1\";\n /** Wire protocol, for example `\"anthropic-messages\"`. */\n readonly api: string;\n /** Vendor and catalog entry. */\n readonly provider: string;\n /** Caps for a model the catalog does not list. Without them, `createModel()` needs a catalog entry. */\n readonly defaultCaps?: ModelCaps;\n stream(model: ModelRef, context: ModelContext, options: StreamOptions): AsyncIterable<ModelEvent>;\n}\n"]}
|
package/dist/sse.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A server-sent events decoder over a byte stream, shared by the wire adapters. It follows the WHATWG event-stream
|
|
3
|
+
* format: lines end in CRLF, LF or CR, a blank line dispatches an event, a line starting with `:` is a comment, and
|
|
4
|
+
* an event left incomplete when the stream ends is discarded.
|
|
5
|
+
*/
|
|
6
|
+
/** One dispatched server-sent event. `event` is `"message"` when the event named none. */
|
|
7
|
+
export interface ServerSentEvent {
|
|
8
|
+
readonly event: string;
|
|
9
|
+
readonly data: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Reads `body` to its end and yields each server-sent event as it completes. Chunk boundaries may fall anywhere,
|
|
13
|
+
* inside a multi-byte character or between a CR and its LF. Breaking out of the loop cancels the body.
|
|
14
|
+
*/
|
|
15
|
+
export declare function readServerSentEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent>;
|
package/dist/sse.js
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A server-sent events decoder over a byte stream, shared by the wire adapters. It follows the WHATWG event-stream
|
|
3
|
+
* format: lines end in CRLF, LF or CR, a blank line dispatches an event, a line starting with `:` is a comment, and
|
|
4
|
+
* an event left incomplete when the stream ends is discarded.
|
|
5
|
+
*/
|
|
6
|
+
const LINE_END = /\r\n|\n|\r/;
|
|
7
|
+
/** Applies one line to the pending event, and returns the event when the line is the blank line that ends it. */
|
|
8
|
+
function applyLine(line, pending) {
|
|
9
|
+
if (line === "") {
|
|
10
|
+
const dispatched = pending.data.length > 0 ? { event: pending.event || "message", data: pending.data.join("\n") } : undefined;
|
|
11
|
+
pending.event = "";
|
|
12
|
+
pending.data = [];
|
|
13
|
+
return dispatched;
|
|
14
|
+
}
|
|
15
|
+
if (line.startsWith(":"))
|
|
16
|
+
return undefined;
|
|
17
|
+
const colon = line.indexOf(":");
|
|
18
|
+
const field = colon === -1 ? line : line.slice(0, colon);
|
|
19
|
+
let value = colon === -1 ? "" : line.slice(colon + 1);
|
|
20
|
+
if (value.startsWith(" "))
|
|
21
|
+
value = value.slice(1);
|
|
22
|
+
if (field === "event")
|
|
23
|
+
pending.event = value;
|
|
24
|
+
else if (field === "data")
|
|
25
|
+
pending.data.push(value);
|
|
26
|
+
return undefined;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Splits the complete lines off `buffer`. A trailing CR is held back until the next chunk or the end of the stream,
|
|
30
|
+
* because it may be the first half of a CRLF split across two chunks.
|
|
31
|
+
*/
|
|
32
|
+
function takeLines(buffer, final) {
|
|
33
|
+
const lines = [];
|
|
34
|
+
let rest = buffer;
|
|
35
|
+
for (let match = LINE_END.exec(rest); match !== null; match = LINE_END.exec(rest)) {
|
|
36
|
+
if (match[0] === "\r" && match.index === rest.length - 1 && !final)
|
|
37
|
+
break;
|
|
38
|
+
lines.push(rest.slice(0, match.index));
|
|
39
|
+
rest = rest.slice(match.index + match[0].length);
|
|
40
|
+
}
|
|
41
|
+
return { lines, rest };
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Reads `body` to its end and yields each server-sent event as it completes. Chunk boundaries may fall anywhere,
|
|
45
|
+
* inside a multi-byte character or between a CR and its LF. Breaking out of the loop cancels the body.
|
|
46
|
+
*/
|
|
47
|
+
export async function* readServerSentEvents(body) {
|
|
48
|
+
const reader = body.getReader();
|
|
49
|
+
const decoder = new TextDecoder();
|
|
50
|
+
const pending = { event: "", data: [] };
|
|
51
|
+
let buffer = "";
|
|
52
|
+
let finished = false;
|
|
53
|
+
try {
|
|
54
|
+
while (!finished) {
|
|
55
|
+
const { done, value } = await reader.read();
|
|
56
|
+
finished = done;
|
|
57
|
+
buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
|
|
58
|
+
const { lines, rest } = takeLines(buffer, done);
|
|
59
|
+
buffer = rest;
|
|
60
|
+
for (const line of lines) {
|
|
61
|
+
const event = applyLine(line, pending);
|
|
62
|
+
if (event)
|
|
63
|
+
yield event;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
finally {
|
|
68
|
+
if (!finished)
|
|
69
|
+
await reader.cancel().catch(() => undefined);
|
|
70
|
+
reader.releaseLock();
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
//# sourceMappingURL=sse.js.map
|
package/dist/sse.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sse.js","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A server-sent events decoder over a byte stream, shared by the wire adapters. It follows the WHATWG event-stream\n * format: lines end in CRLF, LF or CR, a blank line dispatches an event, a line starting with `:` is a comment, and\n * an event left incomplete when the stream ends is discarded.\n */\n\n/** One dispatched server-sent event. `event` is `\"message\"` when the event named none. */\nexport interface ServerSentEvent {\n readonly event: string;\n readonly data: string;\n}\n\nconst LINE_END = /\\r\\n|\\n|\\r/;\n\ninterface PendingEvent {\n event: string;\n data: string[];\n}\n\n/** Applies one line to the pending event, and returns the event when the line is the blank line that ends it. */\nfunction applyLine(line: string, pending: PendingEvent): ServerSentEvent | undefined {\n if (line === \"\") {\n const dispatched =\n pending.data.length > 0 ? { event: pending.event || \"message\", data: pending.data.join(\"\\n\") } : undefined;\n pending.event = \"\";\n pending.data = [];\n return dispatched;\n }\n if (line.startsWith(\":\")) return undefined;\n const colon = line.indexOf(\":\");\n const field = colon === -1 ? line : line.slice(0, colon);\n let value = colon === -1 ? \"\" : line.slice(colon + 1);\n if (value.startsWith(\" \")) value = value.slice(1);\n if (field === \"event\") pending.event = value;\n else if (field === \"data\") pending.data.push(value);\n return undefined;\n}\n\n/**\n * Splits the complete lines off `buffer`. A trailing CR is held back until the next chunk or the end of the stream,\n * because it may be the first half of a CRLF split across two chunks.\n */\nfunction takeLines(buffer: string, final: boolean): { lines: string[]; rest: string } {\n const lines: string[] = [];\n let rest = buffer;\n for (let match = LINE_END.exec(rest); match !== null; match = LINE_END.exec(rest)) {\n if (match[0] === \"\\r\" && match.index === rest.length - 1 && !final) break;\n lines.push(rest.slice(0, match.index));\n rest = rest.slice(match.index + match[0].length);\n }\n return { lines, rest };\n}\n\n/**\n * Reads `body` to its end and yields each server-sent event as it completes. Chunk boundaries may fall anywhere,\n * inside a multi-byte character or between a CR and its LF. Breaking out of the loop cancels the body.\n */\nexport async function* readServerSentEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {\n const reader = body.getReader();\n const decoder = new TextDecoder();\n const pending: PendingEvent = { event: \"\", data: [] };\n let buffer = \"\";\n let finished = false;\n try {\n while (!finished) {\n const { done, value } = await reader.read();\n finished = done;\n buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });\n const { lines, rest } = takeLines(buffer, done);\n buffer = rest;\n for (const line of lines) {\n const event = applyLine(line, pending);\n if (event) yield event;\n }\n }\n } finally {\n if (!finished) await reader.cancel().catch(() => undefined);\n reader.releaseLock();\n }\n}\n"]}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `assertStreamContract()`: checks the stream rule every adapter and test model must follow (SDK plan §3.2).
|
|
3
|
+
*
|
|
4
|
+
* 1. `start` comes first, once.
|
|
5
|
+
* 2. Each content index goes `*_start` → `*_delta`* → `*_end`, with one kind (text, reasoning or tool input) per index.
|
|
6
|
+
* 3. Exactly one terminal event, `done` or `error`, ends the stream, and nothing follows it.
|
|
7
|
+
* 4. An `error` terminal's message has `stopReason` `"error"` or `"aborted"`; a `done` terminal's has neither, and
|
|
8
|
+
* every block it started has ended.
|
|
9
|
+
* 5. A gateway `retry` event comes after `start` and before any block event, because output is never retried.
|
|
10
|
+
* 6. A `warning` may come anywhere between `start` and the terminal event. It is not output, so a retry may follow it.
|
|
11
|
+
*/
|
|
12
|
+
import type { GatewayEvent } from "./runtime-types.js";
|
|
13
|
+
export declare class StreamContractError extends Error {
|
|
14
|
+
readonly name = "StreamContractError";
|
|
15
|
+
/** Position of the offending event in the stream, or the stream length when the stream ended early. */
|
|
16
|
+
readonly position: number;
|
|
17
|
+
constructor(message: string, position: number);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Consumes the stream, throws `StreamContractError` at the first violation, and returns every event it read. It
|
|
21
|
+
* checks an adapter's stream and a `Model.stream()` with its `retry` events alike.
|
|
22
|
+
*/
|
|
23
|
+
export declare function assertStreamContract<E extends GatewayEvent>(events: AsyncIterable<E>): Promise<E[]>;
|