@buildanagent/agent-safety 0.0.0-stage → 0.1.0-alpha.29

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.
Files changed (138) hide show
  1. package/LICENSE +54 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +514 -2
  5. package/dist/agents/index.d.ts +5 -0
  6. package/dist/agents/index.js +6 -0
  7. package/dist/agents/index.js.map +1 -0
  8. package/dist/ai/index.d.ts +10 -0
  9. package/dist/ai/index.js +11 -0
  10. package/dist/ai/index.js.map +1 -0
  11. package/dist/ai/interrupted-write.d.ts +28 -0
  12. package/dist/ai/interrupted-write.js +52 -0
  13. package/dist/ai/interrupted-write.js.map +1 -0
  14. package/dist/ai/settle-denied.d.ts +17 -0
  15. package/dist/ai/settle-denied.js +25 -0
  16. package/dist/ai/settle-denied.js.map +1 -0
  17. package/dist/ai/tool-approval.d.ts +68 -0
  18. package/dist/ai/tool-approval.js +219 -0
  19. package/dist/ai/tool-approval.js.map +1 -0
  20. package/dist/ai/tool-result.d.ts +23 -0
  21. package/dist/ai/tool-result.js +20 -0
  22. package/dist/ai/tool-result.js.map +1 -0
  23. package/dist/byok/default-provider.d.ts +12 -0
  24. package/dist/byok/default-provider.js +72 -0
  25. package/dist/byok/default-provider.js.map +1 -0
  26. package/dist/byok/explicit-provider.d.ts +39 -0
  27. package/dist/byok/explicit-provider.js +80 -0
  28. package/dist/byok/explicit-provider.js.map +1 -0
  29. package/dist/byok/index.d.ts +8 -0
  30. package/dist/byok/index.js +9 -0
  31. package/dist/byok/index.js.map +1 -0
  32. package/dist/bytes.d.ts +17 -0
  33. package/dist/bytes.js +59 -0
  34. package/dist/bytes.js.map +1 -0
  35. package/dist/cost/ai-types.d.ts +26 -0
  36. package/dist/cost/ai-types.js +2 -0
  37. package/dist/cost/ai-types.js.map +1 -0
  38. package/dist/cost/budget-exceeded.d.ts +39 -0
  39. package/dist/cost/budget-exceeded.js +49 -0
  40. package/dist/cost/budget-exceeded.js.map +1 -0
  41. package/dist/cost/cost-guard.d.ts +63 -0
  42. package/dist/cost/cost-guard.js +278 -0
  43. package/dist/cost/cost-guard.js.map +1 -0
  44. package/dist/cost/estimate.d.ts +76 -0
  45. package/dist/cost/estimate.js +320 -0
  46. package/dist/cost/estimate.js.map +1 -0
  47. package/dist/cost/guarded-provider.d.ts +24 -0
  48. package/dist/cost/guarded-provider.js +19 -0
  49. package/dist/cost/guarded-provider.js.map +1 -0
  50. package/dist/cost/index.d.ts +12 -0
  51. package/dist/cost/index.js +12 -0
  52. package/dist/cost/index.js.map +1 -0
  53. package/dist/cost/spend.d.ts +13 -0
  54. package/dist/cost/spend.js +15 -0
  55. package/dist/cost/spend.js.map +1 -0
  56. package/dist/effect-key.d.ts +31 -0
  57. package/dist/effect-key.js +61 -0
  58. package/dist/effect-key.js.map +1 -0
  59. package/dist/effect-store-conformance.d.ts +24 -0
  60. package/dist/effect-store-conformance.js +140 -0
  61. package/dist/effect-store-conformance.js.map +1 -0
  62. package/dist/effect-store.d.ts +71 -0
  63. package/dist/effect-store.js +38 -0
  64. package/dist/effect-store.js.map +1 -0
  65. package/dist/egress.d.ts +74 -0
  66. package/dist/egress.js +174 -0
  67. package/dist/egress.js.map +1 -0
  68. package/dist/errors.d.ts +32 -0
  69. package/dist/errors.js +26 -0
  70. package/dist/errors.js.map +1 -0
  71. package/dist/guarded-write.d.ts +99 -0
  72. package/dist/guarded-write.js +245 -0
  73. package/dist/guarded-write.js.map +1 -0
  74. package/dist/hash.d.ts +24 -0
  75. package/dist/hash.js +121 -0
  76. package/dist/hash.js.map +1 -0
  77. package/dist/index.d.ts +27 -0
  78. package/dist/index.js +28 -0
  79. package/dist/index.js.map +1 -0
  80. package/dist/key-store.d.ts +37 -0
  81. package/dist/key-store.js +53 -0
  82. package/dist/key-store.js.map +1 -0
  83. package/dist/model-routes.d.ts +54 -0
  84. package/dist/model-routes.js +117 -0
  85. package/dist/model-routes.js.map +1 -0
  86. package/dist/model-url.d.ts +39 -0
  87. package/dist/model-url.js +79 -0
  88. package/dist/model-url.js.map +1 -0
  89. package/dist/outcome.d.ts +88 -0
  90. package/dist/outcome.js +140 -0
  91. package/dist/outcome.js.map +1 -0
  92. package/dist/pending-store.d.ts +45 -0
  93. package/dist/pending-store.js +36 -0
  94. package/dist/pending-store.js.map +1 -0
  95. package/dist/pending.d.ts +144 -0
  96. package/dist/pending.js +161 -0
  97. package/dist/pending.js.map +1 -0
  98. package/dist/plan-approval.d.ts +196 -0
  99. package/dist/plan-approval.js +357 -0
  100. package/dist/plan-approval.js.map +1 -0
  101. package/dist/plan-card.d.ts +34 -0
  102. package/dist/plan-card.js +56 -0
  103. package/dist/plan-card.js.map +1 -0
  104. package/dist/plan-ledger-conformance.d.ts +24 -0
  105. package/dist/plan-ledger-conformance.js +99 -0
  106. package/dist/plan-ledger-conformance.js.map +1 -0
  107. package/dist/plan-ledger.d.ts +14 -0
  108. package/dist/plan-ledger.js +42 -0
  109. package/dist/plan-ledger.js.map +1 -0
  110. package/dist/plan-run.d.ts +133 -0
  111. package/dist/plan-run.js +438 -0
  112. package/dist/plan-run.js.map +1 -0
  113. package/dist/render.d.ts +40 -0
  114. package/dist/render.js +92 -0
  115. package/dist/render.js.map +1 -0
  116. package/dist/signer.d.ts +42 -0
  117. package/dist/signer.js +128 -0
  118. package/dist/signer.js.map +1 -0
  119. package/dist/stores/cloudflare.d.ts +34 -0
  120. package/dist/stores/cloudflare.js +84 -0
  121. package/dist/stores/cloudflare.js.map +1 -0
  122. package/dist/stores/dynamodb.d.ts +27 -0
  123. package/dist/stores/dynamodb.js +139 -0
  124. package/dist/stores/dynamodb.js.map +1 -0
  125. package/dist/stores/lost-claim.d.ts +8 -0
  126. package/dist/stores/lost-claim.js +11 -0
  127. package/dist/stores/lost-claim.js.map +1 -0
  128. package/dist/stores/postgres.d.ts +30 -0
  129. package/dist/stores/postgres.js +79 -0
  130. package/dist/stores/postgres.js.map +1 -0
  131. package/dist/test-signer.d.ts +13 -0
  132. package/dist/test-signer.js +18 -0
  133. package/dist/test-signer.js.map +1 -0
  134. package/dist/testing.d.ts +8 -0
  135. package/dist/testing.js +9 -0
  136. package/dist/testing.js.map +1 -0
  137. package/llms.txt +212 -0
  138. package/package.json +107 -3
@@ -0,0 +1,278 @@
1
+ /**
2
+ * `costGuard()`: an AI SDK language-model middleware that refuses a call before it is sent when the spend so far plus
3
+ * the call's projected cost would pass a USD cap, the rule our SDK's loop applies too. In `ai` 7.0.162 each
4
+ * step and each retry calls the step model's `doGenerate` or `doStream`, so a wrapped model's middleware sees every
5
+ * provider request. The projection is the gateway's `projectCost()` over the gateway's `estimateInputTokens()`, the
6
+ * formula the SDK's loop uses, so both caps agree on what a call can cost.
7
+ */
8
+ import { defaultCatalog, estimateInputTokens, findCatalogEntry, projectCost, } from "@buildanagent/gateway";
9
+ import { SafetyError } from "../errors.js";
10
+ import { BudgetExceeded } from "./budget-exceeded.js";
11
+ import { describeFile, gatewayContext, gatewayUsage, messageKeys, priceResponse, responsePartChars, sizeFiles, toolsKey, } from "./estimate.js";
12
+ // Enough finished calls to recognise the one a step continues while a few calls run side by side.
13
+ const RECENT_CALLS = 8;
14
+ function checkOptions(options) {
15
+ const { capUsd, maxOutputTokens } = options;
16
+ if (typeof capUsd !== "number" || !Number.isFinite(capUsd) || capUsd < 0) {
17
+ throw new SafetyError("invalid_budget", `capUsd must be a finite number of dollars, 0 or more, got ${String(capUsd)}`);
18
+ }
19
+ if (maxOutputTokens !== undefined && (!Number.isInteger(maxOutputTokens) || maxOutputTokens <= 0)) {
20
+ throw new SafetyError("invalid_budget", `maxOutputTokens must be a positive integer, got ${String(maxOutputTokens)}`);
21
+ }
22
+ }
23
+ /** A dollar amount for a message, to six significant digits, so float noise doesn't reach the text. */
24
+ function dollars(usd) {
25
+ if (!Number.isFinite(usd))
26
+ return `$${String(usd)}`;
27
+ // Fixed notation, never `1e-7`; the trimmed zeros leave `$0.4` rather than `$0.40000000`.
28
+ const fixed = usd.toFixed(8);
29
+ return `$${fixed.includes(".") ? fixed.replace(/0+$/, "").replace(/\.$/, "") : fixed}`;
30
+ }
31
+ /** The catalog provider a model's AI SDK provider name stands for: `anthropic.messages` is `anthropic`. */
32
+ function catalogProvider(model) {
33
+ return model.provider.split(".")[0] ?? model.provider;
34
+ }
35
+ /**
36
+ * The guard's state for one cap. It holds the projections of calls in flight, so calls that run at the same time
37
+ * through one guard share the cap instead of each checking it against the same spend.
38
+ */
39
+ class Ledger {
40
+ reservedUsd = 0;
41
+ // The dollars this guard has added to the spend, so a read that raced an `add()` still counts it.
42
+ addedUsd = 0;
43
+ unknown;
44
+ recent = [];
45
+ fileSizes = new Map();
46
+ options;
47
+ constructor(options) {
48
+ this.options = options;
49
+ }
50
+ refuse(code, model, message, spentUsd, projectedUsd) {
51
+ throw new BudgetExceeded({
52
+ code,
53
+ message,
54
+ capUsd: this.options.capUsd,
55
+ spentUsd,
56
+ projectedUsd,
57
+ provider: model.provider,
58
+ modelId: model.modelId,
59
+ });
60
+ }
61
+ /**
62
+ * Reads the spend, and returns a function that gives the spend so far plus what calls in flight may cost. Call that
63
+ * function in the same synchronous step that reserves, so no other call's reservation slips in between. A call that
64
+ * settles while `get()` runs has already given back its reservation, and a store need not show its `add()` to a read
65
+ * that started first, so what this guard added meanwhile counts too; a read that did see the add then counts it
66
+ * twice, which errs towards refusing.
67
+ */
68
+ async readSpend(model) {
69
+ const added = this.addedUsd;
70
+ const stored = await this.options.spend.get();
71
+ if (typeof stored !== "number" || !Number.isFinite(stored) || stored < 0) {
72
+ const message = `the Spend returned ${String(stored)}, not a number of dollars, so the USD cap can't be checked`;
73
+ this.refuse("unknown_price", model, message, Number.NaN, null);
74
+ }
75
+ return () => stored + this.reservedUsd + (this.addedUsd - added);
76
+ }
77
+ /** The prompt index and usage of the latest finished call that this request continues, if any. */
78
+ reported(model, prompt, tools, roles) {
79
+ for (const call of this.recent.toReversed()) {
80
+ // Another model counts tokens with another tokenizer, and new tools add input the usage doesn't hold.
81
+ const continues = call.model === model &&
82
+ call.tools === tools &&
83
+ call.prompt.length < prompt.length &&
84
+ roles[call.prompt.length]?.role === "assistant" &&
85
+ call.prompt.every((key, i) => key === prompt[i]);
86
+ if (continues)
87
+ return { index: call.prompt.length, usage: call.usage, responseChars: call.responseChars };
88
+ }
89
+ return undefined;
90
+ }
91
+ /** Projects the call and reserves its projection against the cap, or throws `BudgetExceeded`. */
92
+ async admit(model, params) {
93
+ const { capUsd, catalog = defaultCatalog } = this.options;
94
+ const id = `${model.provider}/${model.modelId}`;
95
+ const entry = findCatalogEntry(catalog, catalogProvider(model), model.modelId);
96
+ if (entry === undefined) {
97
+ const message = `the price of ${id} is unknown, so a call under a USD cap can't be checked; add the model to the catalog`;
98
+ this.refuse("unknown_price", model, message, (await this.readSpend(model))(), null);
99
+ }
100
+ const prompt = messageKeys(params.prompt);
101
+ const tools = toolsKey(params.tools);
102
+ const continued = this.reported(id, prompt, tools, params.prompt);
103
+ // A call that continues a recorded one is priced from its usage up to that answer, so only the files after it need a size.
104
+ const { sizes, unsized } = await sizeFiles(params.prompt.slice(continued?.index ?? 0), this.options.fileSize, this.fileSizes);
105
+ if (unsized !== undefined) {
106
+ const message = `${id} was not called: the request points at ${describeFile(unsized)} (${unsized.mediaType}) by ${unsized.kind} and its size is unknown or out of range, so a call under a USD cap can't be checked; set fileSize on costGuard() to size it`;
107
+ this.refuse("unknown_price", model, message, (await this.readSpend(model))(), null);
108
+ }
109
+ const context = gatewayContext(params.prompt, params.tools, continued, sizes);
110
+ const tokens = {
111
+ inputTokens: estimateInputTokens(context),
112
+ maxOutputTokens: params.maxOutputTokens ?? entry.maxOutputTokens,
113
+ };
114
+ const projectedUsd = projectCost(tokens, entry).total;
115
+ const spentNow = await this.readSpend(model);
116
+ // Everything from here to the reservation runs in one step, so a call admitted meanwhile is seen.
117
+ const spent = spentNow();
118
+ if (this.unknown !== undefined)
119
+ this.refuse("unknown_price", model, this.unknown, spent, projectedUsd);
120
+ if (projectedUsd === null) {
121
+ const message = `the catalog has no rate for ${id} at ${tokens.inputTokens} input tokens, so a call under a USD cap can't be checked`;
122
+ this.refuse("unknown_price", model, message, spent, null);
123
+ }
124
+ if (spent + projectedUsd > capUsd) {
125
+ const message = `${id} was not called: ${dollars(spent)} is spent or in flight and the call can cost up to ${dollars(projectedUsd)}, which passes the cap of ${dollars(capUsd)}`;
126
+ this.refuse("budget_exceeded", model, message, spent, projectedUsd);
127
+ }
128
+ this.reservedUsd += projectedUsd;
129
+ return { model, entry, prompt, tools, projectedUsd };
130
+ }
131
+ /** Gives back a call's reservation when the provider rejected it with an error, which leaves no usage to price. */
132
+ release(call) {
133
+ this.reservedUsd -= call.projectedUsd;
134
+ }
135
+ /**
136
+ * Records a call's cost and gives back its reservation. A response that reported no usage, or usage the catalog
137
+ * can't price, is charged its projection and stops the guard. An interrupted call is charged its projection, the most
138
+ * it could have cost, and the guard carries on. If the `Spend` fails to record the cost, the guard stops too.
139
+ */
140
+ async settle(call, outcome) {
141
+ const { provider, modelId } = call.model;
142
+ let costUsd = null;
143
+ if (outcome.kind === "finished") {
144
+ const usage = gatewayUsage(outcome.usage);
145
+ costUsd = usage.unreported ? null : priceResponse(usage, call.entry);
146
+ if (costUsd === null) {
147
+ this.unknown = usage.unreported
148
+ ? `a call to ${provider}/${modelId} reported no usage, so the spend is unknown and the USD cap can't be checked`
149
+ : `the catalog can't price the usage a call to ${provider}/${modelId} reported, so the USD cap can't be checked`;
150
+ }
151
+ else {
152
+ const { prompt, tools } = call;
153
+ this.recent.push({
154
+ model: `${provider}/${modelId}`,
155
+ prompt,
156
+ tools,
157
+ usage,
158
+ responseChars: outcome.responseChars,
159
+ });
160
+ if (this.recent.length > RECENT_CALLS)
161
+ this.recent.shift();
162
+ }
163
+ }
164
+ const charged = costUsd ?? call.projectedUsd;
165
+ try {
166
+ await this.options.spend.add(charged);
167
+ this.addedUsd += charged;
168
+ }
169
+ catch (error) {
170
+ this.unknown = `the Spend failed to record what a call to ${provider}/${modelId} cost, so the spend is unknown and the USD cap can't be checked`;
171
+ throw error;
172
+ }
173
+ finally {
174
+ this.reservedUsd -= call.projectedUsd;
175
+ }
176
+ this.options.onCallCost?.({ provider, modelId, projectedUsd: call.projectedUsd, costUsd });
177
+ }
178
+ /**
179
+ * Settles a call that threw before it returned a response. One its abort signal stopped may have been billed for
180
+ * what the provider generated before it stopped, so it is charged its projection. Any other error, and a signal that
181
+ * was already aborted when the request was sent, is a request the provider never billed, which gives the
182
+ * reservation back. The caller sees the call's own error either way.
183
+ */
184
+ async failed(call, params, abortedBeforeSend) {
185
+ if (abortedBeforeSend || params.abortSignal?.aborted !== true) {
186
+ this.release(call);
187
+ return;
188
+ }
189
+ // A failed add has already stopped the guard; the abort is the error worth reporting.
190
+ await this.settle(call, { kind: "interrupted" }).catch(() => undefined);
191
+ }
192
+ }
193
+ /** The characters of text, reasoning and tool calls in a generated response. */
194
+ function generatedChars(content) {
195
+ return content.reduce((sum, part) => sum + responsePartChars(part), 0);
196
+ }
197
+ /**
198
+ * Passes a stream through unchanged and settles the call once: with the `finish` part's usage when the stream ends, or
199
+ * as interrupted when it is cancelled or errors before its `finish` part.
200
+ */
201
+ function settledStream(stream, settle) {
202
+ let usage;
203
+ let finished = false;
204
+ let errored = false;
205
+ let responseChars = 0;
206
+ let settled;
207
+ const once = (outcome) => {
208
+ settled ??= settle(outcome);
209
+ return settled;
210
+ };
211
+ // A stream that reported an error and never finished is a provider fault, not a response without usage: charge its
212
+ // projection and carry on, as for a cancelled stream.
213
+ const ended = () => errored && !finished ? { kind: "interrupted" } : { kind: "finished", usage, responseChars };
214
+ return stream.pipeThrough(new TransformStream({
215
+ transform(part, controller) {
216
+ responseChars += responsePartChars(part);
217
+ if (part.type === "finish") {
218
+ usage = part.usage;
219
+ finished = true;
220
+ }
221
+ if (part.type === "error")
222
+ errored = true;
223
+ controller.enqueue(part);
224
+ },
225
+ flush: () => once(ended()),
226
+ cancel: () => once(finished ? ended() : { kind: "interrupted" }),
227
+ }));
228
+ }
229
+ /**
230
+ * A language-model middleware that caps what calls through it may spend. Before each call it estimates the input
231
+ * tokens from the request, prices them and the call's output limit with the gateway's `projectCost()`, and throws
232
+ * `BudgetExceeded` without calling the provider if the spend so far plus that projection would pass `capUsd`. A model
233
+ * the catalog has no price for is refused before its first call, code `unknown_price`. After each call it adds the
234
+ * cost of the usage the response reported, read from a stream's `finish` part. A streamed call holds its projection
235
+ * against the cap until its stream ends or is cancelled, so read the stream to its end or cancel it. Wrap a whole
236
+ * provider with `guardedProvider()`, so a model `prepareStep` picks from it is capped too.
237
+ */
238
+ export function costGuard(options) {
239
+ checkOptions(options);
240
+ const ledger = new Ledger(options);
241
+ const { maxOutputTokens } = options;
242
+ return {
243
+ specificationVersion: "v4",
244
+ transformParams: async ({ params }) => maxOutputTokens === undefined || params.maxOutputTokens !== undefined ? params : { ...params, maxOutputTokens },
245
+ wrapGenerate: async ({ doGenerate, params, model }) => {
246
+ const call = await ledger.admit(model, params);
247
+ let result;
248
+ const abortedBeforeSend = params.abortSignal?.aborted === true;
249
+ try {
250
+ result = await doGenerate();
251
+ }
252
+ catch (error) {
253
+ await ledger.failed(call, params, abortedBeforeSend);
254
+ throw error;
255
+ }
256
+ await ledger.settle(call, {
257
+ kind: "finished",
258
+ usage: result.usage,
259
+ responseChars: generatedChars(result.content),
260
+ });
261
+ return result;
262
+ },
263
+ wrapStream: async ({ doStream, params, model }) => {
264
+ const call = await ledger.admit(model, params);
265
+ let result;
266
+ const abortedBeforeSend = params.abortSignal?.aborted === true;
267
+ try {
268
+ result = await doStream();
269
+ }
270
+ catch (error) {
271
+ await ledger.failed(call, params, abortedBeforeSend);
272
+ throw error;
273
+ }
274
+ return { ...result, stream: settledStream(result.stream, (outcome) => ledger.settle(call, outcome)) };
275
+ },
276
+ };
277
+ }
278
+ //# sourceMappingURL=cost-guard.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cost-guard.js","sourceRoot":"","sources":["../../src/cost/cost-guard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `costGuard()`: an AI SDK language-model middleware that refuses a call before it is sent when the spend so far plus\n * the call's projected cost would pass a USD cap, the rule our SDK's loop applies too. In `ai` 7.0.162 each\n * step and each retry calls the step model's `doGenerate` or `doStream`, so a wrapped model's middleware sees every\n * provider request. The projection is the gateway's `projectCost()` over the gateway's `estimateInputTokens()`, the\n * formula the SDK's loop uses, so both caps agree on what a call can cost.\n */\nimport {\n type CatalogEntry,\n defaultCatalog,\n estimateInputTokens,\n findCatalogEntry,\n type PriceCatalog,\n projectCost,\n type Usage,\n} from \"@buildanagent/gateway\";\nimport type { LanguageModelMiddleware } from \"ai\";\nimport { SafetyError } from \"../errors.js\";\nimport type { CallOptions, InnerModel, ModelUsage, Prompt, StreamPart } from \"./ai-types.js\";\nimport { BudgetExceeded, type BudgetRefusalCode } from \"./budget-exceeded.js\";\nimport {\n describeFile,\n type FileSize,\n type FileSizer,\n gatewayContext,\n gatewayUsage,\n messageKeys,\n priceResponse,\n type ReportedCall,\n responsePartChars,\n sizeFiles,\n toolsKey,\n} from \"./estimate.js\";\n\nimport type { Spend } from \"./spend.js\";\n\n/** One call the guard let through, reported once its cost is known. */\nexport interface GuardedCall {\n /** The model's `provider`, as the AI SDK names it, such as `anthropic.messages`. */\n readonly provider: string;\n readonly modelId: string;\n /** The most the call could cost, which the guard checked against the cap before sending it. */\n readonly projectedUsd: number;\n /**\n * What the call cost, priced from the usage its response reported, or `null` when the response reported none or the\n * call was interrupted before it did. The guard then adds `projectedUsd` to the spend instead. After a response\n * without usage it also refuses every later call with `unknown_price`; after an interrupted call it carries on.\n */\n readonly costUsd: number | null;\n}\n\n/** Options for `costGuard()`. */\nexport interface CostGuardOptions {\n /** The most the run or session may spend, in USD: a finite number, 0 or more. */\n readonly capUsd: number;\n /** Where the spend is kept. A fresh `memorySpend()` caps one run; a `Spend` the whole session shares caps the session. */\n readonly spend: Spend;\n /** The price catalog to read rates from. Defaults to the gateway's `defaultCatalog`. */\n readonly catalog?: PriceCatalog;\n /**\n * The output limit the guard sets on a call that sets none, and prices that call at. Left out, such a call is\n * priced at the catalog's output limit for the model and sent unchanged.\n */\n readonly maxOutputTokens?: number;\n /**\n * The size of a file a request points at by URL or by provider reference, which holds none of its bytes: `{ bytes }`\n * or `{ pages }`, or `undefined` when you don't know it. Bytes count as the base64 characters of the file, and each\n * page as one image; the text a provider reads from a page isn't counted, so give bytes when you have them. A usable\n * size is a whole number, up to 2 ** 32 bytes or 100,000 pages. The guard remembers each size it was given, so a\n * tool loop asks once for each file.\n *\n * A file that is not an image and has no usable size, one whose `fileSize` throws included, is refused with\n * `unknown_price`, because the guard can't tell what it costs. An image needs no size, because it counts at the\n * largest per-image size a provider documents.\n */\n readonly fileSize?: FileSizer;\n /** Called after each call the guard let through, once its cost is known. */\n readonly onCallCost?: (call: GuardedCall) => void;\n}\n\n/** A call the guard admitted: what it projected and what it holds against the cap until the call settles. */\ninterface Admitted {\n readonly model: InnerModel;\n readonly entry: CatalogEntry;\n readonly prompt: readonly string[];\n readonly tools: string;\n readonly projectedUsd: number;\n}\n\n/** A finished call whose prompt a later call may continue. */\ninterface Recorded {\n readonly model: string;\n readonly prompt: readonly string[];\n readonly tools: string;\n readonly usage: Usage;\n readonly responseChars: number;\n}\n\n/** How an admitted call ended. */\ntype Outcome =\n /** The response ended, with the usage it reported, if any, and the characters it returned. */\n | { readonly kind: \"finished\"; readonly usage: ModelUsage | undefined; readonly responseChars: number }\n /** The call was aborted, or its stream cancelled or broken, before the response reported its usage. */\n | { readonly kind: \"interrupted\" };\n\n// Enough finished calls to recognise the one a step continues while a few calls run side by side.\nconst RECENT_CALLS = 8;\n\nfunction checkOptions(options: CostGuardOptions): void {\n const { capUsd, maxOutputTokens } = options;\n if (typeof capUsd !== \"number\" || !Number.isFinite(capUsd) || capUsd < 0) {\n throw new SafetyError(\n \"invalid_budget\",\n `capUsd must be a finite number of dollars, 0 or more, got ${String(capUsd)}`,\n );\n }\n if (maxOutputTokens !== undefined && (!Number.isInteger(maxOutputTokens) || maxOutputTokens <= 0)) {\n throw new SafetyError(\n \"invalid_budget\",\n `maxOutputTokens must be a positive integer, got ${String(maxOutputTokens)}`,\n );\n }\n}\n\n/** A dollar amount for a message, to six significant digits, so float noise doesn't reach the text. */\nfunction dollars(usd: number): string {\n if (!Number.isFinite(usd)) return `$${String(usd)}`;\n // Fixed notation, never `1e-7`; the trimmed zeros leave `$0.4` rather than `$0.40000000`.\n const fixed = usd.toFixed(8);\n return `$${fixed.includes(\".\") ? fixed.replace(/0+$/, \"\").replace(/\\.$/, \"\") : fixed}`;\n}\n\n/** The catalog provider a model's AI SDK provider name stands for: `anthropic.messages` is `anthropic`. */\nfunction catalogProvider(model: InnerModel): string {\n return model.provider.split(\".\")[0] ?? model.provider;\n}\n\n/**\n * The guard's state for one cap. It holds the projections of calls in flight, so calls that run at the same time\n * through one guard share the cap instead of each checking it against the same spend.\n */\nclass Ledger {\n private reservedUsd = 0;\n // The dollars this guard has added to the spend, so a read that raced an `add()` still counts it.\n private addedUsd = 0;\n private unknown: string | undefined;\n private readonly recent: Recorded[] = [];\n private readonly fileSizes = new Map<string, FileSize>();\n private readonly options: CostGuardOptions;\n\n constructor(options: CostGuardOptions) {\n this.options = options;\n }\n\n private refuse(\n code: BudgetRefusalCode,\n model: InnerModel,\n message: string,\n spentUsd: number,\n projectedUsd: number | null,\n ): never {\n throw new BudgetExceeded({\n code,\n message,\n capUsd: this.options.capUsd,\n spentUsd,\n projectedUsd,\n provider: model.provider,\n modelId: model.modelId,\n });\n }\n\n /**\n * Reads the spend, and returns a function that gives the spend so far plus what calls in flight may cost. Call that\n * function in the same synchronous step that reserves, so no other call's reservation slips in between. A call that\n * settles while `get()` runs has already given back its reservation, and a store need not show its `add()` to a read\n * that started first, so what this guard added meanwhile counts too; a read that did see the add then counts it\n * twice, which errs towards refusing.\n */\n private async readSpend(model: InnerModel): Promise<() => number> {\n const added = this.addedUsd;\n const stored: unknown = await this.options.spend.get();\n if (typeof stored !== \"number\" || !Number.isFinite(stored) || stored < 0) {\n const message = `the Spend returned ${String(stored)}, not a number of dollars, so the USD cap can't be checked`;\n this.refuse(\"unknown_price\", model, message, Number.NaN, null);\n }\n return () => stored + this.reservedUsd + (this.addedUsd - added);\n }\n\n /** The prompt index and usage of the latest finished call that this request continues, if any. */\n private reported(model: string, prompt: readonly string[], tools: string, roles: Prompt): ReportedCall | undefined {\n for (const call of this.recent.toReversed()) {\n // Another model counts tokens with another tokenizer, and new tools add input the usage doesn't hold.\n const continues =\n call.model === model &&\n call.tools === tools &&\n call.prompt.length < prompt.length &&\n roles[call.prompt.length]?.role === \"assistant\" &&\n call.prompt.every((key, i) => key === prompt[i]);\n if (continues) return { index: call.prompt.length, usage: call.usage, responseChars: call.responseChars };\n }\n return undefined;\n }\n\n /** Projects the call and reserves its projection against the cap, or throws `BudgetExceeded`. */\n async admit(model: InnerModel, params: CallOptions): Promise<Admitted> {\n const { capUsd, catalog = defaultCatalog } = this.options;\n const id = `${model.provider}/${model.modelId}`;\n const entry = findCatalogEntry(catalog, catalogProvider(model), model.modelId);\n if (entry === undefined) {\n const message = `the price of ${id} is unknown, so a call under a USD cap can't be checked; add the model to the catalog`;\n this.refuse(\"unknown_price\", model, message, (await this.readSpend(model))(), null);\n }\n const prompt = messageKeys(params.prompt);\n const tools = toolsKey(params.tools);\n const continued = this.reported(id, prompt, tools, params.prompt);\n // A call that continues a recorded one is priced from its usage up to that answer, so only the files after it need a size.\n const { sizes, unsized } = await sizeFiles(\n params.prompt.slice(continued?.index ?? 0),\n this.options.fileSize,\n this.fileSizes,\n );\n if (unsized !== undefined) {\n const message = `${id} was not called: the request points at ${describeFile(unsized)} (${unsized.mediaType}) by ${unsized.kind} and its size is unknown or out of range, so a call under a USD cap can't be checked; set fileSize on costGuard() to size it`;\n this.refuse(\"unknown_price\", model, message, (await this.readSpend(model))(), null);\n }\n const context = gatewayContext(params.prompt, params.tools, continued, sizes);\n const tokens = {\n inputTokens: estimateInputTokens(context),\n maxOutputTokens: params.maxOutputTokens ?? entry.maxOutputTokens,\n };\n const projectedUsd = projectCost(tokens, entry).total;\n const spentNow = await this.readSpend(model);\n // Everything from here to the reservation runs in one step, so a call admitted meanwhile is seen.\n const spent = spentNow();\n if (this.unknown !== undefined) this.refuse(\"unknown_price\", model, this.unknown, spent, projectedUsd);\n if (projectedUsd === null) {\n const message = `the catalog has no rate for ${id} at ${tokens.inputTokens} input tokens, so a call under a USD cap can't be checked`;\n this.refuse(\"unknown_price\", model, message, spent, null);\n }\n if (spent + projectedUsd > capUsd) {\n const message = `${id} was not called: ${dollars(spent)} is spent or in flight and the call can cost up to ${dollars(projectedUsd)}, which passes the cap of ${dollars(capUsd)}`;\n this.refuse(\"budget_exceeded\", model, message, spent, projectedUsd);\n }\n this.reservedUsd += projectedUsd;\n return { model, entry, prompt, tools, projectedUsd };\n }\n\n /** Gives back a call's reservation when the provider rejected it with an error, which leaves no usage to price. */\n private release(call: Admitted): void {\n this.reservedUsd -= call.projectedUsd;\n }\n\n /**\n * Records a call's cost and gives back its reservation. A response that reported no usage, or usage the catalog\n * can't price, is charged its projection and stops the guard. An interrupted call is charged its projection, the most\n * it could have cost, and the guard carries on. If the `Spend` fails to record the cost, the guard stops too.\n */\n async settle(call: Admitted, outcome: Outcome): Promise<void> {\n const { provider, modelId } = call.model;\n let costUsd: number | null = null;\n if (outcome.kind === \"finished\") {\n const usage = gatewayUsage(outcome.usage);\n costUsd = usage.unreported ? null : priceResponse(usage, call.entry);\n if (costUsd === null) {\n this.unknown = usage.unreported\n ? `a call to ${provider}/${modelId} reported no usage, so the spend is unknown and the USD cap can't be checked`\n : `the catalog can't price the usage a call to ${provider}/${modelId} reported, so the USD cap can't be checked`;\n } else {\n const { prompt, tools } = call;\n this.recent.push({\n model: `${provider}/${modelId}`,\n prompt,\n tools,\n usage,\n responseChars: outcome.responseChars,\n });\n if (this.recent.length > RECENT_CALLS) this.recent.shift();\n }\n }\n const charged = costUsd ?? call.projectedUsd;\n try {\n await this.options.spend.add(charged);\n this.addedUsd += charged;\n } catch (error) {\n this.unknown = `the Spend failed to record what a call to ${provider}/${modelId} cost, so the spend is unknown and the USD cap can't be checked`;\n throw error;\n } finally {\n this.reservedUsd -= call.projectedUsd;\n }\n this.options.onCallCost?.({ provider, modelId, projectedUsd: call.projectedUsd, costUsd });\n }\n\n /**\n * Settles a call that threw before it returned a response. One its abort signal stopped may have been billed for\n * what the provider generated before it stopped, so it is charged its projection. Any other error, and a signal that\n * was already aborted when the request was sent, is a request the provider never billed, which gives the\n * reservation back. The caller sees the call's own error either way.\n */\n async failed(call: Admitted, params: CallOptions, abortedBeforeSend: boolean): Promise<void> {\n if (abortedBeforeSend || params.abortSignal?.aborted !== true) {\n this.release(call);\n return;\n }\n // A failed add has already stopped the guard; the abort is the error worth reporting.\n await this.settle(call, { kind: \"interrupted\" }).catch(() => undefined);\n }\n}\n\n/** The characters of text, reasoning and tool calls in a generated response. */\nfunction generatedChars(content: readonly { readonly type: string }[]): number {\n return content.reduce((sum, part) => sum + responsePartChars(part), 0);\n}\n\n/**\n * Passes a stream through unchanged and settles the call once: with the `finish` part's usage when the stream ends, or\n * as interrupted when it is cancelled or errors before its `finish` part.\n */\nfunction settledStream(\n stream: ReadableStream<StreamPart>,\n settle: (outcome: Outcome) => Promise<void>,\n): ReadableStream<StreamPart> {\n let usage: ModelUsage | undefined;\n let finished = false;\n let errored = false;\n let responseChars = 0;\n let settled: Promise<void> | undefined;\n const once = (outcome: Outcome) => {\n settled ??= settle(outcome);\n return settled;\n };\n // A stream that reported an error and never finished is a provider fault, not a response without usage: charge its\n // projection and carry on, as for a cancelled stream.\n const ended = (): Outcome =>\n errored && !finished ? { kind: \"interrupted\" } : { kind: \"finished\", usage, responseChars };\n return stream.pipeThrough(\n new TransformStream<StreamPart, StreamPart>({\n transform(part, controller) {\n responseChars += responsePartChars(part);\n if (part.type === \"finish\") {\n usage = part.usage;\n finished = true;\n }\n if (part.type === \"error\") errored = true;\n controller.enqueue(part);\n },\n flush: () => once(ended()),\n cancel: () => once(finished ? ended() : { kind: \"interrupted\" }),\n }),\n );\n}\n\n/**\n * A language-model middleware that caps what calls through it may spend. Before each call it estimates the input\n * tokens from the request, prices them and the call's output limit with the gateway's `projectCost()`, and throws\n * `BudgetExceeded` without calling the provider if the spend so far plus that projection would pass `capUsd`. A model\n * the catalog has no price for is refused before its first call, code `unknown_price`. After each call it adds the\n * cost of the usage the response reported, read from a stream's `finish` part. A streamed call holds its projection\n * against the cap until its stream ends or is cancelled, so read the stream to its end or cancel it. Wrap a whole\n * provider with `guardedProvider()`, so a model `prepareStep` picks from it is capped too.\n */\nexport function costGuard(options: CostGuardOptions): LanguageModelMiddleware {\n checkOptions(options);\n const ledger = new Ledger(options);\n const { maxOutputTokens } = options;\n return {\n specificationVersion: \"v4\",\n transformParams: async ({ params }) =>\n maxOutputTokens === undefined || params.maxOutputTokens !== undefined ? params : { ...params, maxOutputTokens },\n wrapGenerate: async ({ doGenerate, params, model }) => {\n const call = await ledger.admit(model, params);\n let result: Awaited<ReturnType<typeof doGenerate>>;\n const abortedBeforeSend = params.abortSignal?.aborted === true;\n try {\n result = await doGenerate();\n } catch (error) {\n await ledger.failed(call, params, abortedBeforeSend);\n throw error;\n }\n await ledger.settle(call, {\n kind: \"finished\",\n usage: result.usage,\n responseChars: generatedChars(result.content),\n });\n return result;\n },\n wrapStream: async ({ doStream, params, model }) => {\n const call = await ledger.admit(model, params);\n let result: Awaited<ReturnType<typeof doStream>>;\n const abortedBeforeSend = params.abortSignal?.aborted === true;\n try {\n result = await doStream();\n } catch (error) {\n await ledger.failed(call, params, abortedBeforeSend);\n throw error;\n }\n return { ...result, stream: settledStream(result.stream, (outcome) => ledger.settle(call, outcome)) };\n },\n };\n}\n"]}
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Lowering an AI SDK request to the gateway's transcript, so the guard estimates its input with the gateway's own
3
+ * `estimateInputTokens()`, which counts the previous call's reported tokens and estimates only the messages added since
4
+ * from their characters, the rule the SDK's own loop follows.
5
+ */
6
+ import { type CatalogEntry, type ModelContext, type Usage } from "@buildanagent/gateway";
7
+ import type { CallTool, ModelUsage, Prompt } from "./ai-types.js";
8
+ /** A file a request points at, by URL or by provider reference, so the request holds none of its bytes. */
9
+ export interface FileRef {
10
+ /** The URL, or the provider reference as JSON, such as `{"openai":"file-abc"}`. */
11
+ readonly source: string;
12
+ readonly kind: "url" | "reference";
13
+ /** The file's media type, such as `application/pdf`. */
14
+ readonly mediaType: string;
15
+ readonly filename?: string;
16
+ }
17
+ /** What the caller knows of a file's size: its bytes, or its pages. */
18
+ export type FileSize = {
19
+ readonly bytes: number;
20
+ } | {
21
+ readonly pages: number;
22
+ };
23
+ /** Looks up the size of a file a request points at, or returns `undefined` when it isn't known. */
24
+ export type FileSizer = (file: FileRef) => FileSize | undefined | Promise<FileSize | undefined>;
25
+ /** The sizes found for a request's files, by `sizeKey()`. */
26
+ type SizeTable = ReadonlyMap<string, FileSize>;
27
+ /**
28
+ * What the guard knows of a prompt's files: the sizes `sizeOf` gave for the files it points at by URL or reference,
29
+ * and the first such file with no usable size, which the caller refuses to send under a cap. A size `sizeOf` gave is
30
+ * kept in `remembered`, so it is asked once for each file while the guard remembers it; a file with no size is asked
31
+ * for again on the next call.
32
+ */
33
+ export declare function sizeFiles(prompt: Prompt, sizeOf: FileSizer | undefined, remembered: Map<string, FileSize>): Promise<{
34
+ readonly sizes: SizeTable;
35
+ readonly unsized: FileRef | undefined;
36
+ }>;
37
+ /**
38
+ * A file's name for a message: its `filename`, else its URL without the query and fragment, which may hold a
39
+ * signature, else the providers its reference names. The full source never reaches an error.
40
+ */
41
+ export declare function describeFile(file: FileRef): string;
42
+ /**
43
+ * A recorded call whose answer the prompt continues: the prompt index of that answer, the call's usage, and the
44
+ * characters of text, reasoning and tool calls the call returned.
45
+ */
46
+ export interface ReportedCall {
47
+ readonly index: number;
48
+ readonly usage: Usage;
49
+ readonly responseChars: number;
50
+ }
51
+ /**
52
+ * The gateway context that one AI SDK request stands for. `reported` names the prompt index of the assistant message
53
+ * a recorded call produced, with that call's usage, so `estimateInputTokens()` counts everything up to that message
54
+ * from the provider's own numbers. `sizes` holds the sizes of the files the prompt points at, from `sizeFiles()`.
55
+ */
56
+ export declare function gatewayContext(prompt: Prompt, tools: readonly CallTool[] | undefined, reported: ReportedCall | undefined, sizes: SizeTable): ModelContext;
57
+ /** One key per message, equal for two messages only when they are the same, to recognise a prompt a call continues. */
58
+ export declare function messageKeys(prompt: Prompt): string[];
59
+ /** A key for the tools a request offers, equal for two requests only when they offer the same tools. */
60
+ export declare function toolsKey(tools: readonly CallTool[] | undefined): string;
61
+ /** The characters of text, reasoning and tool calls in a response part, measured as `contentChars()` measures them. */
62
+ export declare function responsePartChars(part: {
63
+ readonly type: string;
64
+ }): number;
65
+ /**
66
+ * The gateway's usage record for an AI SDK response, or an unreported one when the provider left out the input or
67
+ * output total. A missing breakdown is derived from the totals: uncached input is the input left after cache reads and
68
+ * writes, and every cache write counts as a short-lived one, which `priceResponse()` prices at the dearer lifetime.
69
+ */
70
+ export declare function gatewayUsage(usage: ModelUsage | undefined): Usage;
71
+ /**
72
+ * The response's price in USD, or `null` when its usage is unreported. The AI SDK reports cache writes as one count,
73
+ * so they are priced at whichever of the short and long write rates costs more, which errs towards a higher spend.
74
+ */
75
+ export declare function priceResponse(usage: Usage, entry: CatalogEntry): number | null;
76
+ export {};