@buildanagent/gateway 0.0.0-stage → 0.1.0-alpha.1
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 +305 -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 +27 -0
- package/dist/adapters/anthropic/failure.js +53 -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 +38 -0
- package/dist/adapters/anthropic/response.js +237 -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 +32 -0
- package/dist/adapters/openai-chat/failure.js +40 -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 +22 -0
- package/dist/adapters/openai-chat/usage.js +25 -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 +98 -0
- package/dist/adapters/wire.js +187 -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 +44 -0
- package/dist/cost.js +132 -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 +33 -0
- package/dist/retry.js +219 -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 +143 -0
- package/dist/types.js +6 -0
- package/dist/types.js.map +1 -0
- package/dist/usage.d.ts +16 -0
- package/dist/usage.js +31 -0
- package/dist/usage.js.map +1 -0
- package/package.json +50 -3
package/dist/classify.js
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// Quota and billing errors are final even when the status is 429, because waiting does not refill a budget. Only
|
|
2
|
+
// explicit billing codes and phrases count: a rate-limit message that merely mentions "quota" stays retryable.
|
|
3
|
+
// Anthropic's `enforced_spend_limit_reached` is a 429 for a monthly tier threshold (Messages API reference, Errors,
|
|
4
|
+
// https://platform.claude.com/docs/en/api/messages/create, as of November 2026), so waiting does not clear it.
|
|
5
|
+
// OpenAI's billing 429s carry a code that names the cause, and "retrying billing, spend, or quota errors won't restore
|
|
6
|
+
// API access" (Error codes, https://developers.openai.com/api/docs/guides/error-codes, as of November 2026).
|
|
7
|
+
const QUOTA = /insufficient_quota|exceeded your current quota|credit balance is too low|billing_hard_limit|enforced_spend_limit_reached|credit_balance_exhausted|(organization|project)_spend_limit_exceeded|organization_usage_limit_exceeded/i;
|
|
8
|
+
// A per-minute "request too large" 429 is a rate limit, not a full context, so only context phrases count here.
|
|
9
|
+
const OVERFLOW = /context[ _-]?(length|window)|prompt is too long|maximum context/i;
|
|
10
|
+
// Other 5xx statuses, such as 501 and 505, are permanent.
|
|
11
|
+
const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504, 529]);
|
|
12
|
+
/**
|
|
13
|
+
* Returns the error kind for a failed request. A request that got no response is `retryable`, because it failed in
|
|
14
|
+
* transit; a response whose status the gateway doesn't know is `fatal`, so nothing is retried by accident.
|
|
15
|
+
*/
|
|
16
|
+
export function classifyError(failure) {
|
|
17
|
+
const text = `${failure.code ?? ""} ${failure.message ?? ""}`;
|
|
18
|
+
if (failure.status === 402 || QUOTA.test(text))
|
|
19
|
+
return "quota";
|
|
20
|
+
if (failure.status === 413 || OVERFLOW.test(text))
|
|
21
|
+
return "overflow";
|
|
22
|
+
// No status means the request failed in transit (a reset connection or DNS failure), which is safe to retry.
|
|
23
|
+
if (failure.status === undefined)
|
|
24
|
+
return "retryable";
|
|
25
|
+
if (RETRYABLE_STATUSES.has(failure.status))
|
|
26
|
+
return "retryable";
|
|
27
|
+
return "fatal";
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* True for the errors a `fetch` throws when a request gets no response, or when its body breaks off: undici names a
|
|
31
|
+
* failed request "fetch failed" and a body cut short "terminated". Any other throw is a bug or a guard, so the
|
|
32
|
+
* gateway never retries it.
|
|
33
|
+
*/
|
|
34
|
+
export function isTransportFailure(thrown) {
|
|
35
|
+
return thrown instanceof TypeError && /fetch|network|socket|connect|terminated/i.test(thrown.message);
|
|
36
|
+
}
|
|
37
|
+
//# sourceMappingURL=classify.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"classify.js","sourceRoot":"","sources":["../src/classify.ts"],"names":[],"mappings":"AAiBA,iHAAiH;AACjH,+GAA+G;AAC/G,oHAAoH;AACpH,+GAA+G;AAC/G,uHAAuH;AACvH,6GAA6G;AAC7G,MAAM,KAAK,GACT,kOAAkO,CAAC;AACrO,gHAAgH;AAChH,MAAM,QAAQ,GAAG,kEAAkE,CAAC;AACpF,0DAA0D;AAC1D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAElF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;IAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IACrE,6GAA6G;IAC7G,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IACrD,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,WAAW,CAAC;IAC/D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe;IAChD,OAAO,MAAM,YAAY,SAAS,IAAI,0CAA0C,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACxG,CAAC","sourcesContent":["/**\n * `classifyError()`: sorts a failed request into the four error kinds the gateway and the loop act on (SDK decision 4;\n * agent-SDK guide §2). Adapters call it with the HTTP status and the provider's error code or message.\n */\nimport type { AssistantMessage } from \"./types.js\";\n\n/** How a failed call is handled: retried, compacted, stopped for billing, or stopped. */\nexport type ErrorKind = NonNullable<AssistantMessage[\"error\"]>[\"kind\"];\n\n/** What an adapter knows about one failed request. A request that never got a response has no `status`. */\nexport interface FailedRequest {\n status?: number;\n /** The provider's error code or type, for example `\"insufficient_quota\"`. */\n code?: string;\n message?: string;\n}\n\n// Quota and billing errors are final even when the status is 429, because waiting does not refill a budget. Only\n// explicit billing codes and phrases count: a rate-limit message that merely mentions \"quota\" stays retryable.\n// Anthropic's `enforced_spend_limit_reached` is a 429 for a monthly tier threshold (Messages API reference, Errors,\n// https://platform.claude.com/docs/en/api/messages/create, as of November 2026), so waiting does not clear it.\n// OpenAI's billing 429s carry a code that names the cause, and \"retrying billing, spend, or quota errors won't restore\n// API access\" (Error codes, https://developers.openai.com/api/docs/guides/error-codes, as of November 2026).\nconst QUOTA =\n /insufficient_quota|exceeded your current quota|credit balance is too low|billing_hard_limit|enforced_spend_limit_reached|credit_balance_exhausted|(organization|project)_spend_limit_exceeded|organization_usage_limit_exceeded/i;\n// A per-minute \"request too large\" 429 is a rate limit, not a full context, so only context phrases count here.\nconst OVERFLOW = /context[ _-]?(length|window)|prompt is too long|maximum context/i;\n// Other 5xx statuses, such as 501 and 505, are permanent.\nconst RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504, 529]);\n\n/**\n * Returns the error kind for a failed request. A request that got no response is `retryable`, because it failed in\n * transit; a response whose status the gateway doesn't know is `fatal`, so nothing is retried by accident.\n */\nexport function classifyError(failure: FailedRequest): ErrorKind {\n const text = `${failure.code ?? \"\"} ${failure.message ?? \"\"}`;\n if (failure.status === 402 || QUOTA.test(text)) return \"quota\";\n if (failure.status === 413 || OVERFLOW.test(text)) return \"overflow\";\n // No status means the request failed in transit (a reset connection or DNS failure), which is safe to retry.\n if (failure.status === undefined) return \"retryable\";\n if (RETRYABLE_STATUSES.has(failure.status)) return \"retryable\";\n return \"fatal\";\n}\n\n/**\n * True for the errors a `fetch` throws when a request gets no response, or when its body breaks off: undici names a\n * failed request \"fetch failed\" and a body cut short \"terminated\". Any other throw is a bug or a guard, so the\n * gateway never retries it.\n */\nexport function isTransportFailure(thrown: unknown): boolean {\n return thrown instanceof TypeError && /fetch|network|socket|connect|terminated/i.test(thrown.message);\n}\n"]}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** `complete()`: folds a model stream into its final message (SDK plan §3.2). */
|
|
2
|
+
import type { GatewayEvent } from "./runtime-types.js";
|
|
3
|
+
import type { AssistantMessage } from "./types.js";
|
|
4
|
+
/**
|
|
5
|
+
* Reads the stream to its terminal event and returns that event's message. An `error` terminal is returned, not
|
|
6
|
+
* thrown: its message carries `stopReason` `"error"` or `"aborted"`, the partial content and the usage so far. A stream
|
|
7
|
+
* that ends without a terminal event breaks the stream rule, so that case throws. `retry` events are skipped.
|
|
8
|
+
*/
|
|
9
|
+
export declare function complete(events: AsyncIterable<GatewayEvent>): Promise<AssistantMessage>;
|
package/dist/complete.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reads the stream to its terminal event and returns that event's message. An `error` terminal is returned, not
|
|
3
|
+
* thrown: its message carries `stopReason` `"error"` or `"aborted"`, the partial content and the usage so far. A stream
|
|
4
|
+
* that ends without a terminal event breaks the stream rule, so that case throws. `retry` events are skipped.
|
|
5
|
+
*/
|
|
6
|
+
export async function complete(events) {
|
|
7
|
+
for await (const event of events) {
|
|
8
|
+
if (event.type === "done" || event.type === "error")
|
|
9
|
+
return event.message;
|
|
10
|
+
}
|
|
11
|
+
throw new Error("the model stream ended without a done or error event");
|
|
12
|
+
}
|
|
13
|
+
//# sourceMappingURL=complete.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"complete.js","sourceRoot":"","sources":["../src/complete.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAmC;IAChE,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IAC5E,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;AAC1E,CAAC","sourcesContent":["/** `complete()`: folds a model stream into its final message (SDK plan §3.2). */\nimport type { GatewayEvent } from \"./runtime-types.js\";\nimport type { AssistantMessage } from \"./types.js\";\n\n/**\n * Reads the stream to its terminal event and returns that event's message. An `error` terminal is returned, not\n * thrown: its message carries `stopReason` `\"error\"` or `\"aborted\"`, the partial content and the usage so far. A stream\n * that ends without a terminal event breaks the stream rule, so that case throws. `retry` events are skipped.\n */\nexport async function complete(events: AsyncIterable<GatewayEvent>): Promise<AssistantMessage> {\n for await (const event of events) {\n if (event.type === \"done\" || event.type === \"error\") return event.message;\n }\n throw new Error(\"the model stream ended without a done or error event\");\n}\n"]}
|
package/dist/cost.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pricing usage against the catalog, and projecting a call's cost before it is sent (D3, D4, D9; ADR 0043).
|
|
3
|
+
*
|
|
4
|
+
* Separate token classes (D3) mean the fold multiplies each class by its own rate with no conversion. A provider's
|
|
5
|
+
* billed total wins over the catalog, and a model the catalog lacks, or a response whose usage the provider didn't
|
|
6
|
+
* report, has an unknown price, never a guessed zero.
|
|
7
|
+
*/
|
|
8
|
+
import type { CatalogEntry } from "./catalog.js";
|
|
9
|
+
import type { Model, ModelCallOptions } from "./runtime-types.js";
|
|
10
|
+
import type { AssistantMessage, Cost, ModelContext, Usage } from "./types.js";
|
|
11
|
+
/**
|
|
12
|
+
* Prices one response's usage with a catalog entry. Each token class is multiplied by its rate in the tier that the
|
|
13
|
+
* response's total input selects. Without an entry, or for usage marked `unreported`, the result is
|
|
14
|
+
* `{ total: null, basis: "unknown" }`.
|
|
15
|
+
*/
|
|
16
|
+
export declare function priceUsage(usage: Usage, entry: CatalogEntry | undefined): Cost;
|
|
17
|
+
/** The message's cost: the provider's billed total when the adapter reported one, else `price(usage)`. */
|
|
18
|
+
export declare function foldCost(message: AssistantMessage, price: (usage: Usage) => Cost): Cost;
|
|
19
|
+
/** The token counts a projection prices: the input to send and the most output the call may produce. */
|
|
20
|
+
export interface ProjectedTokens {
|
|
21
|
+
readonly inputTokens: number;
|
|
22
|
+
readonly maxOutputTokens: number;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The most one call can cost: every input token at the highest input rate in the tier the input selects (the
|
|
26
|
+
* uncached rate or either cache-write rate, whichever costs most), plus `maxOutputTokens` at the output rate. Without
|
|
27
|
+
* an entry, the result is `{ total: null, basis: "unknown" }`.
|
|
28
|
+
*/
|
|
29
|
+
export declare function projectCost(tokens: ProjectedTokens, entry: CatalogEntry | undefined): Cost;
|
|
30
|
+
/**
|
|
31
|
+
* Estimates the input tokens of sending `context`. When an earlier assistant message reports its usage, the estimate
|
|
32
|
+
* is that request's total input and output plus a character-based estimate of the messages after it; otherwise every
|
|
33
|
+
* part of the context is estimated from its characters. A retried call counts only its last attempt, through
|
|
34
|
+
* `lastAttemptUsage`, because its summed `usage` would count the same prompt once per attempt. The reported usage
|
|
35
|
+
* stands in for the system prompt and tools, so the estimate assumes they are unchanged since that request: if you
|
|
36
|
+
* grow them, the growth is not counted. Otherwise the estimate errs high, so a budget check errs towards stopping.
|
|
37
|
+
*/
|
|
38
|
+
export declare function estimateInputTokens(context: ModelContext): number;
|
|
39
|
+
/**
|
|
40
|
+
* The most the next call can cost, priced as `projectCost()` prices it: over `estimateInputTokens(context)` and the
|
|
41
|
+
* call's `maxOutputTokens`, or the model's own output limit when the options leave it out. Priced with the model's catalog
|
|
42
|
+
* entry, so a model the catalog lacks projects `{ total: null, basis: "unknown" }`.
|
|
43
|
+
*/
|
|
44
|
+
export declare function projectCallCost(model: Model, context: ModelContext, options?: ModelCallOptions): Cost;
|
package/dist/cost.js
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import { emptyUsage, totalInput } from "./usage.js";
|
|
2
|
+
const PER_MILLION = 1_000_000;
|
|
3
|
+
/** The cost of a model the catalog doesn't list, or of usage the provider didn't report. */
|
|
4
|
+
const UNKNOWN_COST = { total: null, basis: "unknown", currency: "USD" };
|
|
5
|
+
/** The first tier whose limit covers `inputTokens`; the catalog check guarantees the last tier has no limit. */
|
|
6
|
+
function tierFor(rates, inputTokens) {
|
|
7
|
+
return rates.find((tier) => tier.upToInputTokens === null || inputTokens <= tier.upToInputTokens);
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Prices one response's usage with a catalog entry. Each token class is multiplied by its rate in the tier that the
|
|
11
|
+
* response's total input selects. Without an entry, or for usage marked `unreported`, the result is
|
|
12
|
+
* `{ total: null, basis: "unknown" }`.
|
|
13
|
+
*/
|
|
14
|
+
export function priceUsage(usage, entry) {
|
|
15
|
+
// Zero counts the provider never reported are not a price of zero, and a budget must not treat them as one.
|
|
16
|
+
if (usage.unreported)
|
|
17
|
+
return { ...UNKNOWN_COST };
|
|
18
|
+
const tier = entry ? tierFor(entry.rates, totalInput(usage)) : undefined;
|
|
19
|
+
if (entry === undefined || tier === undefined)
|
|
20
|
+
return { ...UNKNOWN_COST };
|
|
21
|
+
const total = (usage.uncachedInput * tier.uncachedInput +
|
|
22
|
+
usage.cacheRead * tier.cacheRead +
|
|
23
|
+
usage.cacheWrite["5m"] * tier.cacheWrite["5m"] +
|
|
24
|
+
usage.cacheWrite["1h"] * tier.cacheWrite["1h"] +
|
|
25
|
+
usage.output * tier.output) /
|
|
26
|
+
PER_MILLION;
|
|
27
|
+
return { total, basis: "catalog", currency: "USD", catalogAsOf: entry.asOf };
|
|
28
|
+
}
|
|
29
|
+
/** The message's cost: the provider's billed total when the adapter reported one, else `price(usage)`. */
|
|
30
|
+
export function foldCost(message, price) {
|
|
31
|
+
if (message.cost.basis === "provider" && message.cost.total !== null)
|
|
32
|
+
return message.cost;
|
|
33
|
+
return price(message.usage);
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The most one call can cost: every input token at the highest input rate in the tier the input selects (the
|
|
37
|
+
* uncached rate or either cache-write rate, whichever costs most), plus `maxOutputTokens` at the output rate. Without
|
|
38
|
+
* an entry, the result is `{ total: null, basis: "unknown" }`.
|
|
39
|
+
*/
|
|
40
|
+
export function projectCost(tokens, entry) {
|
|
41
|
+
return projectWith(tokens, (usage) => priceUsage(usage, entry));
|
|
42
|
+
}
|
|
43
|
+
// Every input token is put in one class at a time and the dearest result wins. The tier depends only on total input,
|
|
44
|
+
// which is the same in each candidate, so this prices the input at the tier's highest input rate without reading the
|
|
45
|
+
// rates themselves; `Model.price()` keeps its catalog entry private.
|
|
46
|
+
function projectWith(tokens, price) {
|
|
47
|
+
const base = { ...emptyUsage(), output: tokens.maxOutputTokens };
|
|
48
|
+
const n = tokens.inputTokens;
|
|
49
|
+
const candidates = [
|
|
50
|
+
price({ ...base, uncachedInput: n }),
|
|
51
|
+
price({ ...base, cacheWrite: { "5m": n, "1h": 0 } }),
|
|
52
|
+
price({ ...base, cacheWrite: { "5m": 0, "1h": n } }),
|
|
53
|
+
];
|
|
54
|
+
return candidates.reduce((most, cost) => ((cost.total ?? -1) > (most.total ?? -1) ? cost : most));
|
|
55
|
+
}
|
|
56
|
+
// Anthropic's models overview puts 1M tokens at roughly 2.5M Unicode characters on its current tokenizer, as of
|
|
57
|
+
// November 2026. Other tokenizers fit more characters in a token, so this rate errs towards a higher estimate.
|
|
58
|
+
const CHARS_PER_TOKEN = 2.5;
|
|
59
|
+
// The largest per-image cost a first provider documents: Anthropic's high-resolution limit of 4,784 visual tokens
|
|
60
|
+
// (vision docs, as of November 2026). Counting an image's base64 data instead would overstate it a hundredfold.
|
|
61
|
+
const TOKENS_PER_IMAGE = 4784;
|
|
62
|
+
function blockChars(block) {
|
|
63
|
+
switch (block.type) {
|
|
64
|
+
case "text":
|
|
65
|
+
case "reasoning":
|
|
66
|
+
return block.text.length;
|
|
67
|
+
case "tool_call":
|
|
68
|
+
return block.name.length + JSON.stringify(block.input ?? null).length;
|
|
69
|
+
case "image":
|
|
70
|
+
return 0;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
function messageEstimate(message) {
|
|
74
|
+
const blocks = message.content;
|
|
75
|
+
const chars = blocks.reduce((sum, block) => sum + blockChars(block), 0);
|
|
76
|
+
const images = blocks.filter((block) => block.type === "image").length;
|
|
77
|
+
return chars / CHARS_PER_TOKEN + images * TOKENS_PER_IMAGE;
|
|
78
|
+
}
|
|
79
|
+
function promptEstimate(context) {
|
|
80
|
+
const tools = context.tools.reduce((sum, tool) => sum + tool.name.length + tool.description.length + JSON.stringify(tool.inputSchema).length, 0);
|
|
81
|
+
return (context.system.length + tools) / CHARS_PER_TOKEN;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* One request's usage: a retried call's `usage` sums every attempt, so its last attempt's usage alone gives the size
|
|
85
|
+
* of the request that produced the message.
|
|
86
|
+
*/
|
|
87
|
+
function requestUsage(message) {
|
|
88
|
+
return message.lastAttemptUsage ?? message.usage;
|
|
89
|
+
}
|
|
90
|
+
/** The index of the last assistant message whose request reports any input, or -1 when there is none. */
|
|
91
|
+
function lastReportedCall(messages) {
|
|
92
|
+
return messages.findLastIndex((m) => {
|
|
93
|
+
if (m.role !== "assistant")
|
|
94
|
+
return false;
|
|
95
|
+
const usage = requestUsage(m);
|
|
96
|
+
// Unreported counts may miss the output, so the estimate falls back to characters, which errs high.
|
|
97
|
+
return !usage.unreported && totalInput(usage) > 0;
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Estimates the input tokens of sending `context`. When an earlier assistant message reports its usage, the estimate
|
|
102
|
+
* is that request's total input and output plus a character-based estimate of the messages after it; otherwise every
|
|
103
|
+
* part of the context is estimated from its characters. A retried call counts only its last attempt, through
|
|
104
|
+
* `lastAttemptUsage`, because its summed `usage` would count the same prompt once per attempt. The reported usage
|
|
105
|
+
* stands in for the system prompt and tools, so the estimate assumes they are unchanged since that request: if you
|
|
106
|
+
* grow them, the growth is not counted. Otherwise the estimate errs high, so a budget check errs towards stopping.
|
|
107
|
+
*/
|
|
108
|
+
export function estimateInputTokens(context) {
|
|
109
|
+
const last = lastReportedCall(context.messages);
|
|
110
|
+
const previous = context.messages[last];
|
|
111
|
+
if (previous?.role !== "assistant") {
|
|
112
|
+
const messages = context.messages.reduce((sum, m) => sum + messageEstimate(m), 0);
|
|
113
|
+
return Math.ceil(promptEstimate(context) + messages);
|
|
114
|
+
}
|
|
115
|
+
// The reported output stands in for the assistant message's own content, which the next call sends as input.
|
|
116
|
+
const added = context.messages.slice(last + 1).reduce((sum, m) => sum + messageEstimate(m), 0);
|
|
117
|
+
const usage = requestUsage(previous);
|
|
118
|
+
return Math.ceil(totalInput(usage) + usage.output + added);
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* The most the next call can cost, priced as `projectCost()` prices it: over `estimateInputTokens(context)` and the
|
|
122
|
+
* call's `maxOutputTokens`, or the model's own output limit when the options leave it out. Priced with the model's catalog
|
|
123
|
+
* entry, so a model the catalog lacks projects `{ total: null, basis: "unknown" }`.
|
|
124
|
+
*/
|
|
125
|
+
export function projectCallCost(model, context, options = {}) {
|
|
126
|
+
const tokens = {
|
|
127
|
+
inputTokens: estimateInputTokens(context),
|
|
128
|
+
maxOutputTokens: options.maxOutputTokens ?? model.caps.maxOutputTokens,
|
|
129
|
+
};
|
|
130
|
+
return projectWith(tokens, (usage) => model.price(usage));
|
|
131
|
+
}
|
|
132
|
+
//# sourceMappingURL=cost.js.map
|
package/dist/cost.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pricing usage against the catalog, and projecting a call's cost before it is sent (D3, D4, D9; ADR 0043).\n *\n * Separate token classes (D3) mean the fold multiplies each class by its own rate with no conversion. A provider's\n * billed total wins over the catalog, and a model the catalog lacks, or a response whose usage the provider didn't\n * report, has an unknown price, never a guessed zero.\n */\nimport type { CatalogEntry, RateTier } from \"./catalog.js\";\nimport type { Model, ModelCallOptions } from \"./runtime-types.js\";\nimport type { AssistantMessage, ContentBlock, Cost, Message, ModelContext, Usage } from \"./types.js\";\nimport { emptyUsage, totalInput } from \"./usage.js\";\n\nconst PER_MILLION = 1_000_000;\n\n/** The cost of a model the catalog doesn't list, or of usage the provider didn't report. */\nconst UNKNOWN_COST: Cost = { total: null, basis: \"unknown\", currency: \"USD\" };\n\n/** The first tier whose limit covers `inputTokens`; the catalog check guarantees the last tier has no limit. */\nfunction tierFor(rates: readonly RateTier[], inputTokens: number): RateTier | undefined {\n return rates.find((tier) => tier.upToInputTokens === null || inputTokens <= tier.upToInputTokens);\n}\n\n/**\n * Prices one response's usage with a catalog entry. Each token class is multiplied by its rate in the tier that the\n * response's total input selects. Without an entry, or for usage marked `unreported`, the result is\n * `{ total: null, basis: \"unknown\" }`.\n */\nexport function priceUsage(usage: Usage, entry: CatalogEntry | undefined): Cost {\n // Zero counts the provider never reported are not a price of zero, and a budget must not treat them as one.\n if (usage.unreported) return { ...UNKNOWN_COST };\n const tier = entry ? tierFor(entry.rates, totalInput(usage)) : undefined;\n if (entry === undefined || tier === undefined) return { ...UNKNOWN_COST };\n const total =\n (usage.uncachedInput * tier.uncachedInput +\n usage.cacheRead * tier.cacheRead +\n usage.cacheWrite[\"5m\"] * tier.cacheWrite[\"5m\"] +\n usage.cacheWrite[\"1h\"] * tier.cacheWrite[\"1h\"] +\n usage.output * tier.output) /\n PER_MILLION;\n return { total, basis: \"catalog\", currency: \"USD\", catalogAsOf: entry.asOf };\n}\n\n/** The message's cost: the provider's billed total when the adapter reported one, else `price(usage)`. */\nexport function foldCost(message: AssistantMessage, price: (usage: Usage) => Cost): Cost {\n if (message.cost.basis === \"provider\" && message.cost.total !== null) return message.cost;\n return price(message.usage);\n}\n\n/** The token counts a projection prices: the input to send and the most output the call may produce. */\nexport interface ProjectedTokens {\n readonly inputTokens: number;\n readonly maxOutputTokens: number;\n}\n\n/**\n * The most one call can cost: every input token at the highest input rate in the tier the input selects (the\n * uncached rate or either cache-write rate, whichever costs most), plus `maxOutputTokens` at the output rate. Without\n * an entry, the result is `{ total: null, basis: \"unknown\" }`.\n */\nexport function projectCost(tokens: ProjectedTokens, entry: CatalogEntry | undefined): Cost {\n return projectWith(tokens, (usage) => priceUsage(usage, entry));\n}\n\n// Every input token is put in one class at a time and the dearest result wins. The tier depends only on total input,\n// which is the same in each candidate, so this prices the input at the tier's highest input rate without reading the\n// rates themselves; `Model.price()` keeps its catalog entry private.\nfunction projectWith(tokens: ProjectedTokens, price: (usage: Usage) => Cost): Cost {\n const base = { ...emptyUsage(), output: tokens.maxOutputTokens };\n const n = tokens.inputTokens;\n const candidates = [\n price({ ...base, uncachedInput: n }),\n price({ ...base, cacheWrite: { \"5m\": n, \"1h\": 0 } }),\n price({ ...base, cacheWrite: { \"5m\": 0, \"1h\": n } }),\n ];\n return candidates.reduce((most, cost) => ((cost.total ?? -1) > (most.total ?? -1) ? cost : most));\n}\n\n// Anthropic's models overview puts 1M tokens at roughly 2.5M Unicode characters on its current tokenizer, as of\n// November 2026. Other tokenizers fit more characters in a token, so this rate errs towards a higher estimate.\nconst CHARS_PER_TOKEN = 2.5;\n// The largest per-image cost a first provider documents: Anthropic's high-resolution limit of 4,784 visual tokens\n// (vision docs, as of November 2026). Counting an image's base64 data instead would overstate it a hundredfold.\nconst TOKENS_PER_IMAGE = 4784;\n\nfunction blockChars(block: ContentBlock): number {\n switch (block.type) {\n case \"text\":\n case \"reasoning\":\n return block.text.length;\n case \"tool_call\":\n return block.name.length + JSON.stringify(block.input ?? null).length;\n case \"image\":\n return 0;\n }\n}\n\nfunction messageEstimate(message: Message): number {\n const blocks: readonly ContentBlock[] = message.content;\n const chars = blocks.reduce((sum, block) => sum + blockChars(block), 0);\n const images = blocks.filter((block) => block.type === \"image\").length;\n return chars / CHARS_PER_TOKEN + images * TOKENS_PER_IMAGE;\n}\n\nfunction promptEstimate(context: ModelContext): number {\n const tools = context.tools.reduce(\n (sum, tool) => sum + tool.name.length + tool.description.length + JSON.stringify(tool.inputSchema).length,\n 0,\n );\n return (context.system.length + tools) / CHARS_PER_TOKEN;\n}\n\n/**\n * One request's usage: a retried call's `usage` sums every attempt, so its last attempt's usage alone gives the size\n * of the request that produced the message.\n */\nfunction requestUsage(message: AssistantMessage): Usage {\n return message.lastAttemptUsage ?? message.usage;\n}\n\n/** The index of the last assistant message whose request reports any input, or -1 when there is none. */\nfunction lastReportedCall(messages: readonly Message[]): number {\n return messages.findLastIndex((m) => {\n if (m.role !== \"assistant\") return false;\n const usage = requestUsage(m);\n // Unreported counts may miss the output, so the estimate falls back to characters, which errs high.\n return !usage.unreported && totalInput(usage) > 0;\n });\n}\n\n/**\n * Estimates the input tokens of sending `context`. When an earlier assistant message reports its usage, the estimate\n * is that request's total input and output plus a character-based estimate of the messages after it; otherwise every\n * part of the context is estimated from its characters. A retried call counts only its last attempt, through\n * `lastAttemptUsage`, because its summed `usage` would count the same prompt once per attempt. The reported usage\n * stands in for the system prompt and tools, so the estimate assumes they are unchanged since that request: if you\n * grow them, the growth is not counted. Otherwise the estimate errs high, so a budget check errs towards stopping.\n */\nexport function estimateInputTokens(context: ModelContext): number {\n const last = lastReportedCall(context.messages);\n const previous = context.messages[last];\n if (previous?.role !== \"assistant\") {\n const messages = context.messages.reduce((sum, m) => sum + messageEstimate(m), 0);\n return Math.ceil(promptEstimate(context) + messages);\n }\n // The reported output stands in for the assistant message's own content, which the next call sends as input.\n const added = context.messages.slice(last + 1).reduce((sum, m) => sum + messageEstimate(m), 0);\n const usage = requestUsage(previous);\n return Math.ceil(totalInput(usage) + usage.output + added);\n}\n\n/**\n * The most the next call can cost, priced as `projectCost()` prices it: over `estimateInputTokens(context)` and the\n * call's `maxOutputTokens`, or the model's own output limit when the options leave it out. Priced with the model's catalog\n * entry, so a model the catalog lacks projects `{ total: null, basis: \"unknown\" }`.\n */\nexport function projectCallCost(model: Model, context: ModelContext, options: ModelCallOptions = {}): Cost {\n const tokens = {\n inputTokens: estimateInputTokens(context),\n maxOutputTokens: options.maxOutputTokens ?? model.caps.maxOutputTokens,\n };\n return projectWith(tokens, (usage) => model.price(usage));\n}\n"]}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { CreateModelOptions, Model } from "./runtime-types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Creates a model from an adapter object and a model id. Every call through it is retried, wrapped in middleware
|
|
4
|
+
* and dumped the same way, whatever the adapter. Throws a `GatewayError` for bad options, including a malformed
|
|
5
|
+
* `catalog` (code `invalid_catalog`).
|
|
6
|
+
*/
|
|
7
|
+
export declare function createModel(options: CreateModelOptions): Model;
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `createModel()`: binds an adapter to one model id and wraps it in the gateway's shared behaviour (SDK plan §3.2;
|
|
3
|
+
* SDK decisions 4, 13). The order, outside in: middleware, then retries, then the request dump, then the adapter.
|
|
4
|
+
*/
|
|
5
|
+
import { defaultCatalog, findCatalogEntry, parseCatalog } from "./catalog.js";
|
|
6
|
+
import { complete } from "./complete.js";
|
|
7
|
+
import { priceUsage } from "./cost.js";
|
|
8
|
+
import { GatewayError } from "./errors.js";
|
|
9
|
+
import { transformParams, wrapStream } from "./middleware.js";
|
|
10
|
+
import { startAttempt } from "./request-dump.js";
|
|
11
|
+
import { abortableSleep, withRetries } from "./retry.js";
|
|
12
|
+
const DEFAULT_RETRIES = 2;
|
|
13
|
+
const DEFAULT_INITIAL_DELAY_MS = 2000;
|
|
14
|
+
function assertAdapter(adapter) {
|
|
15
|
+
const candidate = adapter;
|
|
16
|
+
if (typeof candidate !== "object" || candidate === null || typeof candidate.stream !== "function") {
|
|
17
|
+
// A string here is usually a bare model id; the gateway never resolves one to a provider.
|
|
18
|
+
throw new GatewayError("invalid_options", "createModel() needs an adapter object, such as anthropic({ apiKey }).");
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
function nonNegativeInteger(name, value, fallback) {
|
|
22
|
+
if (value === undefined)
|
|
23
|
+
return fallback;
|
|
24
|
+
if (!Number.isInteger(value) || value < 0) {
|
|
25
|
+
throw new GatewayError("invalid_options", `createModel(): ${name} must be a non-negative integer, got ${value}`);
|
|
26
|
+
}
|
|
27
|
+
return value;
|
|
28
|
+
}
|
|
29
|
+
/** The catalog entry's limits, with the adapter's defaults for anything the entry leaves out. */
|
|
30
|
+
function resolveCaps(adapter, id, entry) {
|
|
31
|
+
const defaults = adapter.defaultCaps;
|
|
32
|
+
if (entry) {
|
|
33
|
+
return {
|
|
34
|
+
contextWindow: entry.contextWindow,
|
|
35
|
+
maxOutputTokens: entry.maxOutputTokens,
|
|
36
|
+
// Without a record either way, assume no support: sending an image or reasoning option a model rejects fails.
|
|
37
|
+
images: entry.images ?? defaults?.images ?? false,
|
|
38
|
+
reasoning: entry.reasoning ?? defaults?.reasoning ?? false,
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
if (defaults)
|
|
42
|
+
return { ...defaults };
|
|
43
|
+
throw new GatewayError("missing_caps", `createModel(): ${adapter.provider}/${id} is not in the catalog and the adapter has no default caps`);
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Creates a model from an adapter object and a model id. Every call through it is retried, wrapped in middleware
|
|
47
|
+
* and dumped the same way, whatever the adapter. Throws a `GatewayError` for bad options, including a malformed
|
|
48
|
+
* `catalog` (code `invalid_catalog`).
|
|
49
|
+
*/
|
|
50
|
+
export function createModel(options) {
|
|
51
|
+
const { adapter, id } = options;
|
|
52
|
+
assertAdapter(adapter);
|
|
53
|
+
const ref = { api: adapter.api, provider: adapter.provider, id };
|
|
54
|
+
// A caller's catalog is checked like a JSON one: pricing relies on ascending tiers, an open last tier and
|
|
55
|
+
// finite, non-negative rates, and a typed object can still break them.
|
|
56
|
+
const catalog = options.catalog === undefined ? defaultCatalog : parseCatalog(options.catalog);
|
|
57
|
+
const entry = findCatalogEntry(catalog, adapter.provider, id);
|
|
58
|
+
const caps = resolveCaps(adapter, id, entry);
|
|
59
|
+
const price = (usage) => priceUsage(usage, entry);
|
|
60
|
+
const middleware = [...(options.middleware ?? [])];
|
|
61
|
+
const settings = {
|
|
62
|
+
retries: nonNegativeInteger("retries", options.retries, DEFAULT_RETRIES),
|
|
63
|
+
initialDelayMs: nonNegativeInteger("initialRetryDelayMs", options.initialRetryDelayMs, DEFAULT_INITIAL_DELAY_MS),
|
|
64
|
+
sleep: options.sleep ?? abortableSleep,
|
|
65
|
+
price,
|
|
66
|
+
};
|
|
67
|
+
const onRequest = options.onRequest?.bind(options);
|
|
68
|
+
async function* stream(context, streamOptions = {}) {
|
|
69
|
+
const params = await transformParams(middleware, { context, options: streamOptions });
|
|
70
|
+
const request = { adapter, ref, context: params.context, options: params.options, caps, onRequest };
|
|
71
|
+
yield* wrapStream(middleware, params, () => withRetries((n) => startAttempt(request, n), ref, params.options.signal, settings));
|
|
72
|
+
}
|
|
73
|
+
return {
|
|
74
|
+
ref,
|
|
75
|
+
caps,
|
|
76
|
+
stream,
|
|
77
|
+
complete: (context, streamOptions) => complete(stream(context, streamOptions)),
|
|
78
|
+
price,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
//# sourceMappingURL=create-model.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"create-model.js","sourceRoot":"","sources":["../src/create-model.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `createModel()`: binds an adapter to one model id and wraps it in the gateway's shared behaviour (SDK plan §3.2;\n * SDK decisions 4, 13). The order, outside in: middleware, then retries, then the request dump, then the adapter.\n */\nimport { type CatalogEntry, defaultCatalog, findCatalogEntry, parseCatalog } from \"./catalog.js\";\nimport { complete } from \"./complete.js\";\nimport { priceUsage } from \"./cost.js\";\nimport { GatewayError } from \"./errors.js\";\nimport { transformParams, wrapStream } from \"./middleware.js\";\nimport { startAttempt } from \"./request-dump.js\";\nimport { abortableSleep, type RetrySettings, withRetries } from \"./retry.js\";\nimport type { CreateModelOptions, GatewayEvent, Model, ModelCallOptions } from \"./runtime-types.js\";\nimport type { ModelAdapter } from \"./spec.js\";\nimport type { ModelCaps, ModelContext, Usage } from \"./types.js\";\n\nconst DEFAULT_RETRIES = 2;\nconst DEFAULT_INITIAL_DELAY_MS = 2000;\n\nfunction assertAdapter(adapter: unknown): asserts adapter is ModelAdapter {\n const candidate = adapter as Partial<ModelAdapter> | null;\n if (typeof candidate !== \"object\" || candidate === null || typeof candidate.stream !== \"function\") {\n // A string here is usually a bare model id; the gateway never resolves one to a provider.\n throw new GatewayError(\"invalid_options\", \"createModel() needs an adapter object, such as anthropic({ apiKey }).\");\n }\n}\n\nfunction nonNegativeInteger(name: string, value: number | undefined, fallback: number): number {\n if (value === undefined) return fallback;\n if (!Number.isInteger(value) || value < 0) {\n throw new GatewayError(\"invalid_options\", `createModel(): ${name} must be a non-negative integer, got ${value}`);\n }\n return value;\n}\n\n/** The catalog entry's limits, with the adapter's defaults for anything the entry leaves out. */\nfunction resolveCaps(adapter: ModelAdapter, id: string, entry: CatalogEntry | undefined): ModelCaps {\n const defaults = adapter.defaultCaps;\n if (entry) {\n return {\n contextWindow: entry.contextWindow,\n maxOutputTokens: entry.maxOutputTokens,\n // Without a record either way, assume no support: sending an image or reasoning option a model rejects fails.\n images: entry.images ?? defaults?.images ?? false,\n reasoning: entry.reasoning ?? defaults?.reasoning ?? false,\n };\n }\n if (defaults) return { ...defaults };\n throw new GatewayError(\n \"missing_caps\",\n `createModel(): ${adapter.provider}/${id} is not in the catalog and the adapter has no default caps`,\n );\n}\n\n/**\n * Creates a model from an adapter object and a model id. Every call through it is retried, wrapped in middleware\n * and dumped the same way, whatever the adapter. Throws a `GatewayError` for bad options, including a malformed\n * `catalog` (code `invalid_catalog`).\n */\nexport function createModel(options: CreateModelOptions): Model {\n const { adapter, id } = options;\n assertAdapter(adapter);\n const ref = { api: adapter.api, provider: adapter.provider, id };\n // A caller's catalog is checked like a JSON one: pricing relies on ascending tiers, an open last tier and\n // finite, non-negative rates, and a typed object can still break them.\n const catalog = options.catalog === undefined ? defaultCatalog : parseCatalog(options.catalog);\n const entry = findCatalogEntry(catalog, adapter.provider, id);\n const caps = resolveCaps(adapter, id, entry);\n const price = (usage: Usage) => priceUsage(usage, entry);\n const middleware = [...(options.middleware ?? [])];\n const settings: RetrySettings = {\n retries: nonNegativeInteger(\"retries\", options.retries, DEFAULT_RETRIES),\n initialDelayMs: nonNegativeInteger(\"initialRetryDelayMs\", options.initialRetryDelayMs, DEFAULT_INITIAL_DELAY_MS),\n sleep: options.sleep ?? abortableSleep,\n price,\n };\n const onRequest = options.onRequest?.bind(options);\n\n async function* stream(context: ModelContext, streamOptions: ModelCallOptions = {}): AsyncGenerator<GatewayEvent> {\n const params = await transformParams(middleware, { context, options: streamOptions });\n const request = { adapter, ref, context: params.context, options: params.options, caps, onRequest };\n yield* wrapStream(middleware, params, () =>\n withRetries((n) => startAttempt(request, n), ref, params.options.signal, settings),\n );\n }\n\n return {\n ref,\n caps,\n stream,\n complete: (context, streamOptions) => complete(stream(context, streamOptions)),\n price,\n };\n}\n"]}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `GatewayError`: the gateway's error for programmer errors, such as a missing key, invalid options, a malformed
|
|
3
|
+
* catalog, a tool name outside the canonical rule, or a request a mock transport's script did not expect.
|
|
4
|
+
*/
|
|
5
|
+
/** Why a `GatewayError` was thrown. */
|
|
6
|
+
export type GatewayErrorCode = "missing_api_key" | "missing_caps" | "invalid_options" | "invalid_catalog" | "invalid_tool_name" | "unexpected_request";
|
|
7
|
+
/**
|
|
8
|
+
* Thrown for a mistake in how the gateway is called. A failed model call is never thrown: it ends its stream with an
|
|
9
|
+
* `error` event instead.
|
|
10
|
+
*/
|
|
11
|
+
export declare class GatewayError extends Error {
|
|
12
|
+
readonly name = "GatewayError";
|
|
13
|
+
readonly code: GatewayErrorCode;
|
|
14
|
+
constructor(code: GatewayErrorCode, message: string, options?: ErrorOptions);
|
|
15
|
+
}
|
|
16
|
+
/** True for a `GatewayError`, including one from another copy of the package. */
|
|
17
|
+
export declare function isGatewayError(error: unknown): error is GatewayError;
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `GatewayError`: the gateway's error for programmer errors, such as a missing key, invalid options, a malformed
|
|
3
|
+
* catalog, a tool name outside the canonical rule, or a request a mock transport's script did not expect.
|
|
4
|
+
*/
|
|
5
|
+
// A registered symbol, so the guard still works when two copies of the package are bundled.
|
|
6
|
+
const GATEWAY_ERROR = Symbol.for("buildanagent.gateway.GatewayError");
|
|
7
|
+
/**
|
|
8
|
+
* Thrown for a mistake in how the gateway is called. A failed model call is never thrown: it ends its stream with an
|
|
9
|
+
* `error` event instead.
|
|
10
|
+
*/
|
|
11
|
+
export class GatewayError extends Error {
|
|
12
|
+
name = "GatewayError";
|
|
13
|
+
code;
|
|
14
|
+
constructor(code, message, options) {
|
|
15
|
+
super(message, options);
|
|
16
|
+
this.code = code;
|
|
17
|
+
Object.defineProperty(this, GATEWAY_ERROR, { value: true });
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
/** True for a `GatewayError`, including one from another copy of the package. */
|
|
21
|
+
export function isGatewayError(error) {
|
|
22
|
+
return typeof error === "object" && error !== null && error[GATEWAY_ERROR] === true;
|
|
23
|
+
}
|
|
24
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,4FAA4F;AAC5F,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAEtE;;;GAGG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACnB,IAAI,GAAG,cAAc,CAAC;IAC/B,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe,EAAE,OAAsB;QACzE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;AACnH,CAAC","sourcesContent":["/**\n * `GatewayError`: the gateway's error for programmer errors, such as a missing key, invalid options, a malformed\n * catalog, a tool name outside the canonical rule, or a request a mock transport's script did not expect.\n */\n\n/** Why a `GatewayError` was thrown. */\nexport type GatewayErrorCode =\n | \"missing_api_key\"\n | \"missing_caps\"\n | \"invalid_options\"\n | \"invalid_catalog\"\n | \"invalid_tool_name\"\n | \"unexpected_request\";\n\n// A registered symbol, so the guard still works when two copies of the package are bundled.\nconst GATEWAY_ERROR = Symbol.for(\"buildanagent.gateway.GatewayError\");\n\n/**\n * Thrown for a mistake in how the gateway is called. A failed model call is never thrown: it ends its stream with an\n * `error` event instead.\n */\nexport class GatewayError extends Error {\n override readonly name = \"GatewayError\";\n readonly code: GatewayErrorCode;\n\n constructor(code: GatewayErrorCode, message: string, options?: ErrorOptions) {\n super(message, options);\n this.code = code;\n Object.defineProperty(this, GATEWAY_ERROR, { value: true });\n }\n}\n\n/** True for a `GatewayError`, including one from another copy of the package. */\nexport function isGatewayError(error: unknown): error is GatewayError {\n return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[GATEWAY_ERROR] === true;\n}\n"]}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/gateway`: the model gateway's transcript, model spec, stream rule, runtime, price catalog and
|
|
3
|
+
* helpers.
|
|
4
|
+
*/
|
|
5
|
+
export { type CatalogEntry, type CatalogSources, defaultCatalog, findCatalogEntry, type PriceCatalog, parseCatalog, type RateTier, staleCatalogEntries, } from "./catalog.js";
|
|
6
|
+
export { classifyError, type ErrorKind, type FailedRequest } from "./classify.js";
|
|
7
|
+
export { complete } from "./complete.js";
|
|
8
|
+
export { estimateInputTokens, type ProjectedTokens, priceUsage, projectCallCost, projectCost } from "./cost.js";
|
|
9
|
+
export { createModel } from "./create-model.js";
|
|
10
|
+
export { GatewayError, type GatewayErrorCode, isGatewayError } from "./errors.js";
|
|
11
|
+
export { assertCanonicalName, CANONICAL_TOOL_NAME, createToolNameMap, isCanonicalName, TOOL_NAME_RULES, type ToolNameMap, type ToolNameRule, } from "./names.js";
|
|
12
|
+
export { type ResolvedProviderConfig, resolveProviderConfig } from "./provider-config.js";
|
|
13
|
+
export { assertModelRequestAllowed, isMockTransport, ModelRequestsDisabledError, modelRequestsAreAllowed, } from "./request-policy.js";
|
|
14
|
+
export type { CreateModelOptions, DumpedOptions, GatewayEvent, MiddlewareParams, Model, ModelCallOptions, ModelMiddleware, ProviderConfig, RequestDump, Sleep, Transport, } from "./runtime-types.js";
|
|
15
|
+
export type { ModelAdapter, ModelEvent, StreamOptions } from "./spec.js";
|
|
16
|
+
export { assertStreamContract, StreamContractError } from "./stream-contract.js";
|
|
17
|
+
export { transformMessages } from "./transform-messages.js";
|
|
18
|
+
export type { AssistantMessage, ContentBlock, Cost, Message, ModelCaps, ModelContent, ModelContext, ModelErrorCode, ModelRef, OpaqueToken, Usage, WireTool, } from "./types.js";
|
|
19
|
+
export { addUsage, emptyUsage, totalInput, unreportedUsage } from "./usage.js";
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/gateway`: the model gateway's transcript, model spec, stream rule, runtime, price catalog and
|
|
3
|
+
* helpers.
|
|
4
|
+
*/
|
|
5
|
+
export { defaultCatalog, findCatalogEntry, parseCatalog, staleCatalogEntries, } from "./catalog.js";
|
|
6
|
+
export { classifyError } from "./classify.js";
|
|
7
|
+
export { complete } from "./complete.js";
|
|
8
|
+
export { estimateInputTokens, priceUsage, projectCallCost, projectCost } from "./cost.js";
|
|
9
|
+
export { createModel } from "./create-model.js";
|
|
10
|
+
export { GatewayError, isGatewayError } from "./errors.js";
|
|
11
|
+
export { assertCanonicalName, CANONICAL_TOOL_NAME, createToolNameMap, isCanonicalName, TOOL_NAME_RULES, } from "./names.js";
|
|
12
|
+
export { resolveProviderConfig } from "./provider-config.js";
|
|
13
|
+
export { assertModelRequestAllowed, isMockTransport, ModelRequestsDisabledError, modelRequestsAreAllowed, } from "./request-policy.js";
|
|
14
|
+
export { assertStreamContract, StreamContractError } from "./stream-contract.js";
|
|
15
|
+
export { transformMessages } from "./transform-messages.js";
|
|
16
|
+
export { addUsage, emptyUsage, totalInput, unreportedUsage } from "./usage.js";
|
|
17
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAGL,cAAc,EACd,gBAAgB,EAEhB,YAAY,EAEZ,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAsC,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAwB,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAChH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAyB,cAAc,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAGhB,MAAM,YAAY,CAAC;AACpB,OAAO,EAA+B,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAe7B,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAe5D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC","sourcesContent":["/**\n * `@buildanagent/gateway`: the model gateway's transcript, model spec, stream rule, runtime, price catalog and\n * helpers.\n */\nexport {\n type CatalogEntry,\n type CatalogSources,\n defaultCatalog,\n findCatalogEntry,\n type PriceCatalog,\n parseCatalog,\n type RateTier,\n staleCatalogEntries,\n} from \"./catalog.js\";\nexport { classifyError, type ErrorKind, type FailedRequest } from \"./classify.js\";\nexport { complete } from \"./complete.js\";\nexport { estimateInputTokens, type ProjectedTokens, priceUsage, projectCallCost, projectCost } from \"./cost.js\";\nexport { createModel } from \"./create-model.js\";\nexport { GatewayError, type GatewayErrorCode, isGatewayError } from \"./errors.js\";\nexport {\n assertCanonicalName,\n CANONICAL_TOOL_NAME,\n createToolNameMap,\n isCanonicalName,\n TOOL_NAME_RULES,\n type ToolNameMap,\n type ToolNameRule,\n} from \"./names.js\";\nexport { type ResolvedProviderConfig, resolveProviderConfig } from \"./provider-config.js\";\nexport {\n assertModelRequestAllowed,\n isMockTransport,\n ModelRequestsDisabledError,\n modelRequestsAreAllowed,\n} from \"./request-policy.js\";\nexport type {\n CreateModelOptions,\n DumpedOptions,\n GatewayEvent,\n MiddlewareParams,\n Model,\n ModelCallOptions,\n ModelMiddleware,\n ProviderConfig,\n RequestDump,\n Sleep,\n Transport,\n} from \"./runtime-types.js\";\nexport type { ModelAdapter, ModelEvent, StreamOptions } from \"./spec.js\";\nexport { assertStreamContract, StreamContractError } from \"./stream-contract.js\";\nexport { transformMessages } from \"./transform-messages.js\";\nexport type {\n AssistantMessage,\n ContentBlock,\n Cost,\n Message,\n ModelCaps,\n ModelContent,\n ModelContext,\n ModelErrorCode,\n ModelRef,\n OpaqueToken,\n Usage,\n WireTool,\n} from \"./types.js\";\nexport { addUsage, emptyUsage, totalInput, unreportedUsage } from \"./usage.js\";\n"]}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Middleware composition: the first middleware is outermost (SDK plan §3.2).
|
|
3
|
+
*
|
|
4
|
+
* `transformParams` runs first to last, each seeing the previous one's result. `wrapStream` nests the same way, so the
|
|
5
|
+
* first middleware's wrapper sees every event the inner ones pass on, retries included.
|
|
6
|
+
*/
|
|
7
|
+
import type { GatewayEvent, MiddlewareParams, ModelMiddleware } from "./runtime-types.js";
|
|
8
|
+
/** Applies each middleware's `transformParams` in order. */
|
|
9
|
+
export declare function transformParams(middleware: readonly ModelMiddleware[], params: MiddlewareParams): Promise<MiddlewareParams>;
|
|
10
|
+
/** Nests each middleware's `wrapStream` around `inner`, first outermost, and starts the outermost one. */
|
|
11
|
+
export declare function wrapStream(middleware: readonly ModelMiddleware[], params: MiddlewareParams, inner: () => AsyncIterable<GatewayEvent>): AsyncIterable<GatewayEvent>;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/** Applies each middleware's `transformParams` in order. */
|
|
2
|
+
export async function transformParams(middleware, params) {
|
|
3
|
+
let current = params;
|
|
4
|
+
for (const m of middleware) {
|
|
5
|
+
if (m.transformParams)
|
|
6
|
+
current = await m.transformParams(current);
|
|
7
|
+
}
|
|
8
|
+
return current;
|
|
9
|
+
}
|
|
10
|
+
/** Nests each middleware's `wrapStream` around `inner`, first outermost, and starts the outermost one. */
|
|
11
|
+
export function wrapStream(middleware, params, inner) {
|
|
12
|
+
let next = inner;
|
|
13
|
+
for (const m of [...middleware].reverse()) {
|
|
14
|
+
const wrap = m.wrapStream?.bind(m);
|
|
15
|
+
if (!wrap)
|
|
16
|
+
continue;
|
|
17
|
+
const below = next;
|
|
18
|
+
next = () => wrap({ next: below, context: params.context, options: params.options });
|
|
19
|
+
}
|
|
20
|
+
return next();
|
|
21
|
+
}
|
|
22
|
+
//# sourceMappingURL=middleware.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAQA,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAsC,EACtC,MAAwB;IAExB,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,eAAe;YAAE,OAAO,GAAG,MAAM,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,UAAU,CACxB,UAAsC,EACtC,MAAwB,EACxB,KAAwC;IAExC,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC;QACnB,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Middleware composition: the first middleware is outermost (SDK plan §3.2).\n *\n * `transformParams` runs first to last, each seeing the previous one's result. `wrapStream` nests the same way, so the\n * first middleware's wrapper sees every event the inner ones pass on, retries included.\n */\nimport type { GatewayEvent, MiddlewareParams, ModelMiddleware } from \"./runtime-types.js\";\n\n/** Applies each middleware's `transformParams` in order. */\nexport async function transformParams(\n middleware: readonly ModelMiddleware[],\n params: MiddlewareParams,\n): Promise<MiddlewareParams> {\n let current = params;\n for (const m of middleware) {\n if (m.transformParams) current = await m.transformParams(current);\n }\n return current;\n}\n\n/** Nests each middleware's `wrapStream` around `inner`, first outermost, and starts the outermost one. */\nexport function wrapStream(\n middleware: readonly ModelMiddleware[],\n params: MiddlewareParams,\n inner: () => AsyncIterable<GatewayEvent>,\n): AsyncIterable<GatewayEvent> {\n let next = inner;\n for (const m of [...middleware].reverse()) {\n const wrap = m.wrapStream?.bind(m);\n if (!wrap) continue;\n const below = next;\n next = () => wrap({ next: below, context: params.context, options: params.options });\n }\n return next();\n}\n"]}
|
package/dist/names.d.ts
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The canonical tool-name rule: 1 to 64 ASCII letters, digits, underscores or hyphens. It is the strictest
|
|
3
|
+
* intersection of the first providers' rules, so a canonical name reaches either of them unchanged.
|
|
4
|
+
*/
|
|
5
|
+
export declare const CANONICAL_TOOL_NAME: RegExp;
|
|
6
|
+
/** True when `name` meets the canonical tool-name rule. */
|
|
7
|
+
export declare function isCanonicalName(name: string): boolean;
|
|
8
|
+
/**
|
|
9
|
+
* Throws a `GatewayError` with code `invalid_tool_name` unless `name` meets the canonical rule, 1 to 64 characters
|
|
10
|
+
* from `A-Z`, `a-z`, `0-9`, `_` and `-`. Namespaced names such as `mcp__<server>__<tool>` follow the same rule.
|
|
11
|
+
*/
|
|
12
|
+
export declare function assertCanonicalName(name: string): void;
|
|
13
|
+
/** One wire protocol's rule for tool names, copied from the provider's API reference. */
|
|
14
|
+
export interface ToolNameRule {
|
|
15
|
+
/** The wire protocol the rule belongs to, such as `"anthropic-messages"`. */
|
|
16
|
+
readonly api: string;
|
|
17
|
+
/** The allowed characters, as the body of a regular-expression character class, such as `"A-Za-z0-9_-"`. */
|
|
18
|
+
readonly characters: string;
|
|
19
|
+
/** The longest name the protocol accepts, in characters. */
|
|
20
|
+
readonly maxLength: number;
|
|
21
|
+
/** The API reference page the rule was copied from. */
|
|
22
|
+
readonly source: string;
|
|
23
|
+
/** The date the rule was checked against `source`, as `YYYY-MM-DD`. */
|
|
24
|
+
readonly checkedOn: string;
|
|
25
|
+
}
|
|
26
|
+
/** The tool-name rules of the two first wire protocols, Anthropic Messages and OpenAI Chat Completions. Frozen. */
|
|
27
|
+
export declare const TOOL_NAME_RULES: {
|
|
28
|
+
readonly anthropicMessages: ToolNameRule;
|
|
29
|
+
readonly openaiChat: ToolNameRule;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* A run's map between canonical tool names and one protocol's wire names. `sanitize()` gives the wire name for a
|
|
33
|
+
* tool, and `restore()` turns a wire name the model sent back into the tool's name.
|
|
34
|
+
*
|
|
35
|
+
* No two wire names are equal or differ only in case, because neither first provider says whether tool names are
|
|
36
|
+
* case-sensitive. Of the names passed to `createToolNameMap()` up front, one that meets the rule keeps itself
|
|
37
|
+
* unless it differs only in case from a name that sorts before it. Their wire names depend only on the set of
|
|
38
|
+
* names, not on its order or on the order of `sanitize()` calls. A name that `sanitize()` first sees later keeps
|
|
39
|
+
* itself if it meets the rule and no issued wire name matches it, ignoring case. Otherwise it gets a salted hash
|
|
40
|
+
* suffix: a hash of the name and an attempt counter. Every name keeps its first wire name for the life of the map,
|
|
41
|
+
* because that wire name may already have been sent.
|
|
42
|
+
*/
|
|
43
|
+
export interface ToolNameMap {
|
|
44
|
+
/**
|
|
45
|
+
* The wire name for `name`. A name that meets the rule comes back unchanged unless an issued wire name matches it,
|
|
46
|
+
* ignoring case. Any other name has its disallowed characters replaced by `_`, is cut to fit, and ends in `_` and
|
|
47
|
+
* an 8-digit hex hash. The map first hashes the name alone. If that wire name is taken, it salts the hash with an
|
|
48
|
+
* attempt counter, counting up until the wire name is free, so two names never share a wire name. One map always
|
|
49
|
+
* gives one name the same wire name.
|
|
50
|
+
*/
|
|
51
|
+
sanitize(name: string): string;
|
|
52
|
+
/**
|
|
53
|
+
* The name that the map turned into `wireName`, or `undefined` when the map never issued `wireName`. A tool name
|
|
54
|
+
* the model invented therefore never resolves to a tool, even when it equals a tool's name before sanitising.
|
|
55
|
+
*/
|
|
56
|
+
restore(wireName: string): string | undefined;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* FNV-1a over UTF-16 code units, as 8 hex digits: synchronous and portable, so sanitising needs neither Web Crypto
|
|
60
|
+
* nor a Promise. Internal to the gateway; adapters also use it to fingerprint a conversation.
|
|
61
|
+
*/
|
|
62
|
+
export declare function fnv1a(text: string): string;
|
|
63
|
+
/**
|
|
64
|
+
* Creates the map between canonical names and the wire names of the protocol that `rule` describes. Pass the run's
|
|
65
|
+
* tool names as `names`, so their wire names do not depend on the order the tools are registered or sanitised in.
|
|
66
|
+
* Keep one map for a whole run, so every request sends the same wire names and the prompt cache stays valid.
|
|
67
|
+
*
|
|
68
|
+
* Throws a `GatewayError` with code `invalid_options` when the rule is too short to hold a hash suffix, its
|
|
69
|
+
* characters are not a plain character-class body, or they exclude `_` or a hex digit. In `characters`, a `-` must
|
|
70
|
+
* be the first or last character or join two digits, two lowercase letters or two uppercase letters.
|
|
71
|
+
*/
|
|
72
|
+
export declare function createToolNameMap(rule: ToolNameRule, names?: Iterable<string>): ToolNameMap;
|