@buildanagent/agent-safety 0.0.0-stage → 0.1.0-alpha.28
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 +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +514 -2
- package/dist/agents/index.d.ts +5 -0
- package/dist/agents/index.js +6 -0
- package/dist/agents/index.js.map +1 -0
- package/dist/ai/index.d.ts +10 -0
- package/dist/ai/index.js +11 -0
- package/dist/ai/index.js.map +1 -0
- package/dist/ai/interrupted-write.d.ts +28 -0
- package/dist/ai/interrupted-write.js +52 -0
- package/dist/ai/interrupted-write.js.map +1 -0
- package/dist/ai/settle-denied.d.ts +17 -0
- package/dist/ai/settle-denied.js +25 -0
- package/dist/ai/settle-denied.js.map +1 -0
- package/dist/ai/tool-approval.d.ts +68 -0
- package/dist/ai/tool-approval.js +219 -0
- package/dist/ai/tool-approval.js.map +1 -0
- package/dist/ai/tool-result.d.ts +23 -0
- package/dist/ai/tool-result.js +20 -0
- package/dist/ai/tool-result.js.map +1 -0
- package/dist/byok/default-provider.d.ts +12 -0
- package/dist/byok/default-provider.js +72 -0
- package/dist/byok/default-provider.js.map +1 -0
- package/dist/byok/explicit-provider.d.ts +39 -0
- package/dist/byok/explicit-provider.js +80 -0
- package/dist/byok/explicit-provider.js.map +1 -0
- package/dist/byok/index.d.ts +8 -0
- package/dist/byok/index.js +9 -0
- package/dist/byok/index.js.map +1 -0
- package/dist/bytes.d.ts +17 -0
- package/dist/bytes.js +59 -0
- package/dist/bytes.js.map +1 -0
- package/dist/cost/ai-types.d.ts +26 -0
- package/dist/cost/ai-types.js +2 -0
- package/dist/cost/ai-types.js.map +1 -0
- package/dist/cost/budget-exceeded.d.ts +39 -0
- package/dist/cost/budget-exceeded.js +49 -0
- package/dist/cost/budget-exceeded.js.map +1 -0
- package/dist/cost/cost-guard.d.ts +63 -0
- package/dist/cost/cost-guard.js +278 -0
- package/dist/cost/cost-guard.js.map +1 -0
- package/dist/cost/estimate.d.ts +76 -0
- package/dist/cost/estimate.js +320 -0
- package/dist/cost/estimate.js.map +1 -0
- package/dist/cost/guarded-provider.d.ts +24 -0
- package/dist/cost/guarded-provider.js +19 -0
- package/dist/cost/guarded-provider.js.map +1 -0
- package/dist/cost/index.d.ts +12 -0
- package/dist/cost/index.js +12 -0
- package/dist/cost/index.js.map +1 -0
- package/dist/cost/spend.d.ts +13 -0
- package/dist/cost/spend.js +15 -0
- package/dist/cost/spend.js.map +1 -0
- package/dist/effect-key.d.ts +31 -0
- package/dist/effect-key.js +61 -0
- package/dist/effect-key.js.map +1 -0
- package/dist/effect-store-conformance.d.ts +24 -0
- package/dist/effect-store-conformance.js +140 -0
- package/dist/effect-store-conformance.js.map +1 -0
- package/dist/effect-store.d.ts +71 -0
- package/dist/effect-store.js +38 -0
- package/dist/effect-store.js.map +1 -0
- package/dist/egress.d.ts +74 -0
- package/dist/egress.js +174 -0
- package/dist/egress.js.map +1 -0
- package/dist/errors.d.ts +32 -0
- package/dist/errors.js +26 -0
- package/dist/errors.js.map +1 -0
- package/dist/guarded-write.d.ts +99 -0
- package/dist/guarded-write.js +245 -0
- package/dist/guarded-write.js.map +1 -0
- package/dist/hash.d.ts +24 -0
- package/dist/hash.js +121 -0
- package/dist/hash.js.map +1 -0
- package/dist/index.d.ts +27 -0
- package/dist/index.js +28 -0
- package/dist/index.js.map +1 -0
- package/dist/key-store.d.ts +37 -0
- package/dist/key-store.js +53 -0
- package/dist/key-store.js.map +1 -0
- package/dist/model-routes.d.ts +54 -0
- package/dist/model-routes.js +117 -0
- package/dist/model-routes.js.map +1 -0
- package/dist/model-url.d.ts +39 -0
- package/dist/model-url.js +79 -0
- package/dist/model-url.js.map +1 -0
- package/dist/outcome.d.ts +88 -0
- package/dist/outcome.js +140 -0
- package/dist/outcome.js.map +1 -0
- package/dist/pending-store.d.ts +45 -0
- package/dist/pending-store.js +36 -0
- package/dist/pending-store.js.map +1 -0
- package/dist/pending.d.ts +144 -0
- package/dist/pending.js +161 -0
- package/dist/pending.js.map +1 -0
- package/dist/plan-approval.d.ts +196 -0
- package/dist/plan-approval.js +357 -0
- package/dist/plan-approval.js.map +1 -0
- package/dist/plan-card.d.ts +34 -0
- package/dist/plan-card.js +56 -0
- package/dist/plan-card.js.map +1 -0
- package/dist/plan-ledger-conformance.d.ts +24 -0
- package/dist/plan-ledger-conformance.js +99 -0
- package/dist/plan-ledger-conformance.js.map +1 -0
- package/dist/plan-ledger.d.ts +14 -0
- package/dist/plan-ledger.js +42 -0
- package/dist/plan-ledger.js.map +1 -0
- package/dist/plan-run.d.ts +133 -0
- package/dist/plan-run.js +438 -0
- package/dist/plan-run.js.map +1 -0
- package/dist/render.d.ts +40 -0
- package/dist/render.js +92 -0
- package/dist/render.js.map +1 -0
- package/dist/signer.d.ts +42 -0
- package/dist/signer.js +128 -0
- package/dist/signer.js.map +1 -0
- package/dist/stores/cloudflare.d.ts +34 -0
- package/dist/stores/cloudflare.js +84 -0
- package/dist/stores/cloudflare.js.map +1 -0
- package/dist/stores/dynamodb.d.ts +27 -0
- package/dist/stores/dynamodb.js +139 -0
- package/dist/stores/dynamodb.js.map +1 -0
- package/dist/stores/lost-claim.d.ts +8 -0
- package/dist/stores/lost-claim.js +11 -0
- package/dist/stores/lost-claim.js.map +1 -0
- package/dist/stores/postgres.d.ts +30 -0
- package/dist/stores/postgres.js +79 -0
- package/dist/stores/postgres.js.map +1 -0
- package/dist/test-signer.d.ts +13 -0
- package/dist/test-signer.js +18 -0
- package/dist/test-signer.js.map +1 -0
- package/dist/testing.d.ts +8 -0
- package/dist/testing.js +9 -0
- package/dist/testing.js.map +1 -0
- package/llms.txt +212 -0
- package/package.json +107 -3
|
@@ -0,0 +1,320 @@
|
|
|
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 { emptyUsage, estimateInputTokens, priceUsage, unreportedUsage, } from "@buildanagent/gateway";
|
|
7
|
+
// Only `MODEL` and the usage of an assistant message reach the estimate; the other fields fill the gateway's type.
|
|
8
|
+
const MODEL = { api: "ai-sdk", provider: "ai-sdk", id: "ai-sdk" };
|
|
9
|
+
const NO_COST = { total: null, basis: "unknown", currency: "USD" };
|
|
10
|
+
/** The number of characters a file's data would take in a request, or 0 when the request only points at it. */
|
|
11
|
+
function fileChars(data) {
|
|
12
|
+
if (typeof data !== "object" || data === null)
|
|
13
|
+
return 0;
|
|
14
|
+
const file = data;
|
|
15
|
+
if (file.type === "text" && typeof file.text === "string")
|
|
16
|
+
return file.text.length;
|
|
17
|
+
if (file.type !== "data")
|
|
18
|
+
return 0;
|
|
19
|
+
if (typeof file.data === "string")
|
|
20
|
+
return file.data.length;
|
|
21
|
+
// Raw bytes travel as base64, four characters for every three bytes.
|
|
22
|
+
return file.data instanceof Uint8Array ? Math.ceil(file.data.byteLength / 3) * 4 : 0;
|
|
23
|
+
}
|
|
24
|
+
/** Serialises a part for its character count, with binary data replaced by a marker so it isn't counted twice. */
|
|
25
|
+
function serialise(value) {
|
|
26
|
+
return JSON.stringify(value, (_key, v) => (v instanceof Uint8Array ? `<${v.byteLength} bytes>` : v)) ?? "";
|
|
27
|
+
}
|
|
28
|
+
const IMAGE = { type: "image", mediaType: "", data: "" };
|
|
29
|
+
/** The file a part points at, or `undefined` when the part carries its data or is an image, which counts without a size. */
|
|
30
|
+
function fileRef(data, mediaType, filename) {
|
|
31
|
+
if (typeof data !== "object" || data === null || mediaType.startsWith("image/"))
|
|
32
|
+
return undefined;
|
|
33
|
+
const file = data;
|
|
34
|
+
const named = filename === undefined ? {} : { filename };
|
|
35
|
+
if (file.type === "url")
|
|
36
|
+
return { kind: "url", source: String(file.url), mediaType, ...named };
|
|
37
|
+
if (file.type === "reference")
|
|
38
|
+
return { kind: "reference", source: JSON.stringify(file.reference), mediaType, ...named };
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
// A size past these is no file a provider takes, and counting it would build blocks without end, so it counts as
|
|
42
|
+
// unknown and the call is refused.
|
|
43
|
+
const MAX_BYTES = 2 ** 32;
|
|
44
|
+
const MAX_PAGES = 100_000;
|
|
45
|
+
// Text counts by characters, so a large size becomes blocks that share one string, never one huge string.
|
|
46
|
+
const CHUNK = " ".repeat(2 ** 20);
|
|
47
|
+
/** The blocks that a known size stands for: the base64 characters of its bytes, or one image for each page. */
|
|
48
|
+
function sizedBlocks(size) {
|
|
49
|
+
if ("pages" in size)
|
|
50
|
+
return Array.from({ length: size.pages }, () => IMAGE);
|
|
51
|
+
let chars = Math.ceil(size.bytes / 3) * 4;
|
|
52
|
+
const blocks = [];
|
|
53
|
+
for (; chars >= CHUNK.length; chars -= CHUNK.length)
|
|
54
|
+
blocks.push({ type: "text", text: CHUNK });
|
|
55
|
+
return [...blocks, { type: "text", text: CHUNK.slice(0, chars) }];
|
|
56
|
+
}
|
|
57
|
+
/** A caller's size if it is a usable one, a whole number of bytes or pages within bounds; `undefined` otherwise. */
|
|
58
|
+
function usableSize(size) {
|
|
59
|
+
if (typeof size !== "object" || size === null)
|
|
60
|
+
return undefined;
|
|
61
|
+
const { bytes, pages } = size;
|
|
62
|
+
if (typeof bytes === "number" && pages === undefined && Number.isSafeInteger(bytes)) {
|
|
63
|
+
return bytes >= 0 && bytes <= MAX_BYTES ? { bytes } : undefined;
|
|
64
|
+
}
|
|
65
|
+
if (typeof pages === "number" && bytes === undefined && Number.isSafeInteger(pages)) {
|
|
66
|
+
return pages >= 0 && pages <= MAX_PAGES ? { pages } : undefined;
|
|
67
|
+
}
|
|
68
|
+
return undefined;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* The blocks a file counts as. An image becomes an image block, which the gateway counts at the largest per-image size
|
|
72
|
+
* a provider documents; other files count their data's characters. A file sent by URL or by provider reference has no
|
|
73
|
+
* data here, so it counts by the size `sizes` holds for it, and as one image when none is known; `sizeFiles()`
|
|
74
|
+
* lets a caller refuse such a request first.
|
|
75
|
+
*/
|
|
76
|
+
function fileBlocks(data, mediaType, filename, sizes) {
|
|
77
|
+
const ref = fileRef(data, mediaType, filename);
|
|
78
|
+
const known = ref === undefined ? undefined : sizes.get(sizeKey(ref));
|
|
79
|
+
if (known !== undefined)
|
|
80
|
+
return sizedBlocks(known);
|
|
81
|
+
const chars = fileChars(data);
|
|
82
|
+
if (mediaType.startsWith("image/") || chars === 0)
|
|
83
|
+
return [IMAGE];
|
|
84
|
+
return [{ type: "text", text: " ".repeat(chars) }];
|
|
85
|
+
}
|
|
86
|
+
const sizeKey = (ref) => `${ref.kind}\u0000${ref.mediaType}\u0000${ref.source}`;
|
|
87
|
+
/** The file parts of one message part: itself, or the files in the output a tool returned. */
|
|
88
|
+
function filesIn(part) {
|
|
89
|
+
if (part.type === "file" || part.type === "reasoning-file") {
|
|
90
|
+
return [{ data: part.data, mediaType: part.mediaType, filename: "filename" in part ? part.filename : undefined }];
|
|
91
|
+
}
|
|
92
|
+
if (part.type !== "tool-result" || part.output.type !== "content")
|
|
93
|
+
return [];
|
|
94
|
+
return part.output.value.flatMap((item) => item.type === "file" ? [{ data: item.data, mediaType: item.mediaType, filename: undefined }] : []);
|
|
95
|
+
}
|
|
96
|
+
/** The file parts of a prompt, wherever they sit: in a message, or in the output a tool returned. */
|
|
97
|
+
function fileParts(prompt) {
|
|
98
|
+
return prompt.flatMap((message) => typeof message.content === "string" ? [] : message.content.flatMap(filesIn));
|
|
99
|
+
}
|
|
100
|
+
/** What `sizeOf` says of a file. A `sizeOf` that throws or rejects gives no size, so the call is refused, not failed. */
|
|
101
|
+
async function askSize(sizeOf, ref) {
|
|
102
|
+
try {
|
|
103
|
+
return await sizeOf?.(ref);
|
|
104
|
+
}
|
|
105
|
+
catch {
|
|
106
|
+
return undefined;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
// The sizes a guard remembers, so a tool loop doesn't ask for a file's size on every step.
|
|
110
|
+
const REMEMBERED_SIZES = 256;
|
|
111
|
+
/**
|
|
112
|
+
* What the guard knows of a prompt's files: the sizes `sizeOf` gave for the files it points at by URL or reference,
|
|
113
|
+
* and the first such file with no usable size, which the caller refuses to send under a cap. A size `sizeOf` gave is
|
|
114
|
+
* kept in `remembered`, so it is asked once for each file while the guard remembers it; a file with no size is asked
|
|
115
|
+
* for again on the next call.
|
|
116
|
+
*/
|
|
117
|
+
export async function sizeFiles(prompt, sizeOf, remembered) {
|
|
118
|
+
const sizes = new Map();
|
|
119
|
+
const asked = new Set();
|
|
120
|
+
let unsized;
|
|
121
|
+
for (const { data, mediaType, filename } of fileParts(prompt)) {
|
|
122
|
+
const ref = fileRef(data, mediaType, filename);
|
|
123
|
+
if (ref === undefined || asked.has(sizeKey(ref)))
|
|
124
|
+
continue;
|
|
125
|
+
const key = sizeKey(ref);
|
|
126
|
+
asked.add(key);
|
|
127
|
+
const size = remembered.get(key) ?? usableSize(await askSize(sizeOf, ref));
|
|
128
|
+
if (size === undefined) {
|
|
129
|
+
unsized ??= ref;
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
132
|
+
sizes.set(key, size);
|
|
133
|
+
if (remembered.size >= REMEMBERED_SIZES && !remembered.has(key)) {
|
|
134
|
+
remembered.delete(remembered.keys().next().value);
|
|
135
|
+
}
|
|
136
|
+
remembered.set(key, size);
|
|
137
|
+
}
|
|
138
|
+
return { sizes, unsized };
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* A file's name for a message: its `filename`, else its URL without the query and fragment, which may hold a
|
|
142
|
+
* signature, else the providers its reference names. The full source never reaches an error.
|
|
143
|
+
*/
|
|
144
|
+
export function describeFile(file) {
|
|
145
|
+
if (file.filename !== undefined)
|
|
146
|
+
return file.filename;
|
|
147
|
+
if (file.kind === "reference") {
|
|
148
|
+
try {
|
|
149
|
+
const providers = Object.keys(JSON.parse(file.source));
|
|
150
|
+
return `a provider reference (${providers.join(", ")})`;
|
|
151
|
+
}
|
|
152
|
+
catch {
|
|
153
|
+
return "a provider reference";
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
try {
|
|
157
|
+
const url = new URL(file.source);
|
|
158
|
+
return `${url.origin}${url.pathname}`;
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
return "a file URL";
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* The blocks a tool result counts as. A result whose output is content is counted part by part, so an image a tool
|
|
166
|
+
* returns, such as a screenshot, counts as an image and not as its base64 characters.
|
|
167
|
+
*/
|
|
168
|
+
function toolResultBlocks(part, sizes) {
|
|
169
|
+
const { output, ...rest } = part;
|
|
170
|
+
if (output.type !== "content")
|
|
171
|
+
return [{ type: "text", text: serialise(part) }];
|
|
172
|
+
const header = { type: "text", text: serialise(rest) };
|
|
173
|
+
return [
|
|
174
|
+
header,
|
|
175
|
+
...output.value.flatMap((item) => {
|
|
176
|
+
if (item.type === "text")
|
|
177
|
+
return [{ type: "text", text: item.text }];
|
|
178
|
+
if (item.type === "file")
|
|
179
|
+
return fileBlocks(item.data, item.mediaType, undefined, sizes);
|
|
180
|
+
return [{ type: "text", text: serialise(item) }];
|
|
181
|
+
}),
|
|
182
|
+
];
|
|
183
|
+
}
|
|
184
|
+
/** The gateway blocks one AI SDK part counts as. */
|
|
185
|
+
function blocks(part, sizes) {
|
|
186
|
+
switch (part.type) {
|
|
187
|
+
case "text":
|
|
188
|
+
return [{ type: "text", text: part.text }];
|
|
189
|
+
case "reasoning":
|
|
190
|
+
return [{ type: "reasoning", text: part.text }];
|
|
191
|
+
case "tool-call":
|
|
192
|
+
return [{ type: "tool_call", callId: part.toolCallId, name: part.toolName, input: part.input }];
|
|
193
|
+
case "file":
|
|
194
|
+
case "reasoning-file":
|
|
195
|
+
return fileBlocks(part.data, part.mediaType, "filename" in part ? part.filename : undefined, sizes);
|
|
196
|
+
case "tool-result":
|
|
197
|
+
return toolResultBlocks(part, sizes);
|
|
198
|
+
default:
|
|
199
|
+
return [{ type: "text", text: serialise(part) }];
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
/** The characters of text, reasoning and tool calls in `content`, measured as the gateway's estimate measures them. */
|
|
203
|
+
function contentChars(content) {
|
|
204
|
+
return content.reduce((sum, block) => {
|
|
205
|
+
if (block.type === "text" || block.type === "reasoning")
|
|
206
|
+
return sum + block.text.length;
|
|
207
|
+
if (block.type === "tool_call")
|
|
208
|
+
return sum + block.name.length + JSON.stringify(block.input ?? null).length;
|
|
209
|
+
return sum;
|
|
210
|
+
}, 0);
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* The usage that stands in for an assistant message. When the message holds more than the recorded call returned, it
|
|
214
|
+
* isn't that call's answer as returned, so its output counts at least the message's own character estimate.
|
|
215
|
+
*/
|
|
216
|
+
function standInUsage(content, reported) {
|
|
217
|
+
const { usage } = reported;
|
|
218
|
+
if (contentChars(content) <= reported.responseChars)
|
|
219
|
+
return usage;
|
|
220
|
+
const own = estimateInputTokens({ system: "", tools: [], messages: [{ role: "user", content: [...content] }] });
|
|
221
|
+
return { ...usage, output: Math.max(usage.output, own) };
|
|
222
|
+
}
|
|
223
|
+
function message(prompt, reported, sizes) {
|
|
224
|
+
if (prompt.role === "system")
|
|
225
|
+
return undefined;
|
|
226
|
+
const content = prompt.content.flatMap((part) => blocks(part, sizes));
|
|
227
|
+
switch (prompt.role) {
|
|
228
|
+
case "user":
|
|
229
|
+
return { role: "user", content };
|
|
230
|
+
case "tool":
|
|
231
|
+
return {
|
|
232
|
+
role: "tool",
|
|
233
|
+
callId: "",
|
|
234
|
+
content: content,
|
|
235
|
+
isError: false,
|
|
236
|
+
};
|
|
237
|
+
case "assistant":
|
|
238
|
+
return {
|
|
239
|
+
role: "assistant",
|
|
240
|
+
content,
|
|
241
|
+
model: MODEL,
|
|
242
|
+
stopReason: "stop",
|
|
243
|
+
usage: reported === undefined ? unreportedUsage() : standInUsage(content, reported),
|
|
244
|
+
cost: NO_COST,
|
|
245
|
+
};
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
function wireTool(tool) {
|
|
249
|
+
if (tool.type === "function") {
|
|
250
|
+
return {
|
|
251
|
+
name: tool.name,
|
|
252
|
+
description: tool.description ?? "",
|
|
253
|
+
inputSchema: tool.inputSchema,
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
return { name: tool.name, description: tool.id, inputSchema: tool.args };
|
|
257
|
+
}
|
|
258
|
+
/**
|
|
259
|
+
* The gateway context that one AI SDK request stands for. `reported` names the prompt index of the assistant message
|
|
260
|
+
* a recorded call produced, with that call's usage, so `estimateInputTokens()` counts everything up to that message
|
|
261
|
+
* from the provider's own numbers. `sizes` holds the sizes of the files the prompt points at, from `sizeFiles()`.
|
|
262
|
+
*/
|
|
263
|
+
export function gatewayContext(prompt, tools, reported, sizes) {
|
|
264
|
+
const system = prompt.flatMap((m) => (m.role === "system" ? [m.content] : [])).join("\n");
|
|
265
|
+
const messages = prompt.flatMap((m, i) => message(m, i === reported?.index ? reported : undefined, sizes) ?? []);
|
|
266
|
+
return { system, messages, tools: (tools ?? []).map(wireTool) };
|
|
267
|
+
}
|
|
268
|
+
/** One key per message, equal for two messages only when they are the same, to recognise a prompt a call continues. */
|
|
269
|
+
export function messageKeys(prompt) {
|
|
270
|
+
return prompt.map(serialise);
|
|
271
|
+
}
|
|
272
|
+
/** A key for the tools a request offers, equal for two requests only when they offer the same tools. */
|
|
273
|
+
export function toolsKey(tools) {
|
|
274
|
+
return serialise(tools ?? []);
|
|
275
|
+
}
|
|
276
|
+
/** The characters of text, reasoning and tool calls in a response part, measured as `contentChars()` measures them. */
|
|
277
|
+
export function responsePartChars(part) {
|
|
278
|
+
const p = part;
|
|
279
|
+
if ((p.type === "text" || p.type === "reasoning") && typeof p.text === "string")
|
|
280
|
+
return p.text.length;
|
|
281
|
+
if ((p.type === "text-delta" || p.type === "reasoning-delta") && typeof p.delta === "string")
|
|
282
|
+
return p.delta.length;
|
|
283
|
+
if (p.type === "tool-call" && typeof p.toolName === "string" && typeof p.input === "string") {
|
|
284
|
+
return p.toolName.length + p.input.length;
|
|
285
|
+
}
|
|
286
|
+
return 0;
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* The gateway's usage record for an AI SDK response, or an unreported one when the provider left out the input or
|
|
290
|
+
* output total. A missing breakdown is derived from the totals: uncached input is the input left after cache reads and
|
|
291
|
+
* writes, and every cache write counts as a short-lived one, which `priceResponse()` prices at the dearer lifetime.
|
|
292
|
+
*/
|
|
293
|
+
export function gatewayUsage(usage) {
|
|
294
|
+
const input = usage?.inputTokens;
|
|
295
|
+
const output = usage?.outputTokens;
|
|
296
|
+
if (input?.total === undefined || output?.total === undefined)
|
|
297
|
+
return unreportedUsage(usage ?? null);
|
|
298
|
+
const cacheRead = input.cacheRead ?? 0;
|
|
299
|
+
const cacheWrite = input.cacheWrite ?? 0;
|
|
300
|
+
return {
|
|
301
|
+
...emptyUsage(usage?.raw ?? null),
|
|
302
|
+
uncachedInput: input.noCache ?? Math.max(0, input.total - cacheRead - cacheWrite),
|
|
303
|
+
cacheRead,
|
|
304
|
+
cacheWrite: { "5m": cacheWrite, "1h": 0 },
|
|
305
|
+
output: output.total,
|
|
306
|
+
reasoning: output.reasoning ?? 0,
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* The response's price in USD, or `null` when its usage is unreported. The AI SDK reports cache writes as one count,
|
|
311
|
+
* so they are priced at whichever of the short and long write rates costs more, which errs towards a higher spend.
|
|
312
|
+
*/
|
|
313
|
+
export function priceResponse(usage, entry) {
|
|
314
|
+
const short = priceUsage(usage, entry).total;
|
|
315
|
+
const long = priceUsage({ ...usage, cacheWrite: { "5m": 0, "1h": usage.cacheWrite["5m"] } }, entry).total;
|
|
316
|
+
if (short === null || long === null)
|
|
317
|
+
return null;
|
|
318
|
+
return Math.max(short, long);
|
|
319
|
+
}
|
|
320
|
+
//# sourceMappingURL=estimate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"estimate.js","sourceRoot":"","sources":["../../src/cost/estimate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lowering an AI SDK request to the gateway's transcript, so the guard estimates its input with the gateway's own\n * `estimateInputTokens()`, which counts the previous call's reported tokens and estimates only the messages added since\n * from their characters, the rule the SDK's own loop follows.\n */\nimport {\n type CatalogEntry,\n type ContentBlock,\n type Cost,\n emptyUsage,\n estimateInputTokens,\n type Message,\n type ModelContext,\n priceUsage,\n type Usage,\n unreportedUsage,\n type WireTool,\n} from \"@buildanagent/gateway\";\nimport type { CallTool, ModelUsage, Prompt, PromptMessage } from \"./ai-types.js\";\n\ntype Part = Exclude<PromptMessage[\"content\"], string>[number];\n\n/** A file a request points at, by URL or by provider reference, so the request holds none of its bytes. */\nexport interface FileRef {\n /** The URL, or the provider reference as JSON, such as `{\"openai\":\"file-abc\"}`. */\n readonly source: string;\n readonly kind: \"url\" | \"reference\";\n /** The file's media type, such as `application/pdf`. */\n readonly mediaType: string;\n readonly filename?: string;\n}\n\n/** What the caller knows of a file's size: its bytes, or its pages. */\nexport type FileSize = { readonly bytes: number } | { readonly pages: number };\n\n/** Looks up the size of a file a request points at, or returns `undefined` when it isn't known. */\nexport type FileSizer = (file: FileRef) => FileSize | undefined | Promise<FileSize | undefined>;\n\n// Only `MODEL` and the usage of an assistant message reach the estimate; the other fields fill the gateway's type.\nconst MODEL = { api: \"ai-sdk\", provider: \"ai-sdk\", id: \"ai-sdk\" };\nconst NO_COST: Cost = { total: null, basis: \"unknown\", currency: \"USD\" };\n\n/** The number of characters a file's data would take in a request, or 0 when the request only points at it. */\nfunction fileChars(data: unknown): number {\n if (typeof data !== \"object\" || data === null) return 0;\n const file = data as { type?: string; data?: unknown; text?: unknown };\n if (file.type === \"text\" && typeof file.text === \"string\") return file.text.length;\n if (file.type !== \"data\") return 0;\n if (typeof file.data === \"string\") return file.data.length;\n // Raw bytes travel as base64, four characters for every three bytes.\n return file.data instanceof Uint8Array ? Math.ceil(file.data.byteLength / 3) * 4 : 0;\n}\n\n/** Serialises a part for its character count, with binary data replaced by a marker so it isn't counted twice. */\nfunction serialise(value: unknown): string {\n return JSON.stringify(value, (_key, v: unknown) => (v instanceof Uint8Array ? `<${v.byteLength} bytes>` : v)) ?? \"\";\n}\n\nconst IMAGE: ContentBlock = { type: \"image\", mediaType: \"\", data: \"\" };\n\n/** The file a part points at, or `undefined` when the part carries its data or is an image, which counts without a size. */\nfunction fileRef(data: unknown, mediaType: string, filename: string | undefined): FileRef | undefined {\n if (typeof data !== \"object\" || data === null || mediaType.startsWith(\"image/\")) return undefined;\n const file = data as { type?: string; url?: unknown; reference?: unknown };\n const named = filename === undefined ? {} : { filename };\n if (file.type === \"url\") return { kind: \"url\", source: String(file.url), mediaType, ...named };\n if (file.type === \"reference\")\n return { kind: \"reference\", source: JSON.stringify(file.reference), mediaType, ...named };\n return undefined;\n}\n\n// A size past these is no file a provider takes, and counting it would build blocks without end, so it counts as\n// unknown and the call is refused.\nconst MAX_BYTES = 2 ** 32;\nconst MAX_PAGES = 100_000;\n// Text counts by characters, so a large size becomes blocks that share one string, never one huge string.\nconst CHUNK = \" \".repeat(2 ** 20);\n\n/** The blocks that a known size stands for: the base64 characters of its bytes, or one image for each page. */\nfunction sizedBlocks(size: FileSize): ContentBlock[] {\n if (\"pages\" in size) return Array.from({ length: size.pages }, () => IMAGE);\n let chars = Math.ceil(size.bytes / 3) * 4;\n const blocks: ContentBlock[] = [];\n for (; chars >= CHUNK.length; chars -= CHUNK.length) blocks.push({ type: \"text\", text: CHUNK });\n return [...blocks, { type: \"text\", text: CHUNK.slice(0, chars) }];\n}\n\n/** A caller's size if it is a usable one, a whole number of bytes or pages within bounds; `undefined` otherwise. */\nfunction usableSize(size: unknown): FileSize | undefined {\n if (typeof size !== \"object\" || size === null) return undefined;\n const { bytes, pages } = size as { bytes?: unknown; pages?: unknown };\n if (typeof bytes === \"number\" && pages === undefined && Number.isSafeInteger(bytes)) {\n return bytes >= 0 && bytes <= MAX_BYTES ? { bytes } : undefined;\n }\n if (typeof pages === \"number\" && bytes === undefined && Number.isSafeInteger(pages)) {\n return pages >= 0 && pages <= MAX_PAGES ? { pages } : undefined;\n }\n return undefined;\n}\n\n/**\n * The blocks a file counts as. An image becomes an image block, which the gateway counts at the largest per-image size\n * a provider documents; other files count their data's characters. A file sent by URL or by provider reference has no\n * data here, so it counts by the size `sizes` holds for it, and as one image when none is known; `sizeFiles()`\n * lets a caller refuse such a request first.\n */\nfunction fileBlocks(data: unknown, mediaType: string, filename: string | undefined, sizes: SizeTable): ContentBlock[] {\n const ref = fileRef(data, mediaType, filename);\n const known = ref === undefined ? undefined : sizes.get(sizeKey(ref));\n if (known !== undefined) return sizedBlocks(known);\n const chars = fileChars(data);\n if (mediaType.startsWith(\"image/\") || chars === 0) return [IMAGE];\n return [{ type: \"text\", text: \" \".repeat(chars) }];\n}\n\n/** The sizes found for a request's files, by `sizeKey()`. */\ntype SizeTable = ReadonlyMap<string, FileSize>;\n\nconst sizeKey = (ref: FileRef): string => `${ref.kind}\\u0000${ref.mediaType}\\u0000${ref.source}`;\n\ninterface FilePart {\n readonly data: unknown;\n readonly mediaType: string;\n readonly filename: string | undefined;\n}\n\n/** The file parts of one message part: itself, or the files in the output a tool returned. */\nfunction filesIn(part: Part): FilePart[] {\n if (part.type === \"file\" || part.type === \"reasoning-file\") {\n return [{ data: part.data, mediaType: part.mediaType, filename: \"filename\" in part ? part.filename : undefined }];\n }\n if (part.type !== \"tool-result\" || part.output.type !== \"content\") return [];\n return part.output.value.flatMap((item) =>\n item.type === \"file\" ? [{ data: item.data, mediaType: item.mediaType, filename: undefined }] : [],\n );\n}\n\n/** The file parts of a prompt, wherever they sit: in a message, or in the output a tool returned. */\nfunction fileParts(prompt: Prompt): FilePart[] {\n return prompt.flatMap((message) =>\n typeof message.content === \"string\" ? [] : (message.content as Part[]).flatMap(filesIn),\n );\n}\n\n/** What `sizeOf` says of a file. A `sizeOf` that throws or rejects gives no size, so the call is refused, not failed. */\nasync function askSize(sizeOf: FileSizer | undefined, ref: FileRef): Promise<unknown> {\n try {\n return await sizeOf?.(ref);\n } catch {\n return undefined;\n }\n}\n\n// The sizes a guard remembers, so a tool loop doesn't ask for a file's size on every step.\nconst REMEMBERED_SIZES = 256;\n\n/**\n * What the guard knows of a prompt's files: the sizes `sizeOf` gave for the files it points at by URL or reference,\n * and the first such file with no usable size, which the caller refuses to send under a cap. A size `sizeOf` gave is\n * kept in `remembered`, so it is asked once for each file while the guard remembers it; a file with no size is asked\n * for again on the next call.\n */\nexport async function sizeFiles(\n prompt: Prompt,\n sizeOf: FileSizer | undefined,\n remembered: Map<string, FileSize>,\n): Promise<{ readonly sizes: SizeTable; readonly unsized: FileRef | undefined }> {\n const sizes = new Map<string, FileSize>();\n const asked = new Set<string>();\n let unsized: FileRef | undefined;\n for (const { data, mediaType, filename } of fileParts(prompt)) {\n const ref = fileRef(data, mediaType, filename);\n if (ref === undefined || asked.has(sizeKey(ref))) continue;\n const key = sizeKey(ref);\n asked.add(key);\n const size = remembered.get(key) ?? usableSize(await askSize(sizeOf, ref));\n if (size === undefined) {\n unsized ??= ref;\n continue;\n }\n sizes.set(key, size);\n if (remembered.size >= REMEMBERED_SIZES && !remembered.has(key)) {\n remembered.delete(remembered.keys().next().value as string);\n }\n remembered.set(key, size);\n }\n return { sizes, unsized };\n}\n\n/**\n * A file's name for a message: its `filename`, else its URL without the query and fragment, which may hold a\n * signature, else the providers its reference names. The full source never reaches an error.\n */\nexport function describeFile(file: FileRef): string {\n if (file.filename !== undefined) return file.filename;\n if (file.kind === \"reference\") {\n try {\n const providers = Object.keys(JSON.parse(file.source) as Record<string, unknown>);\n return `a provider reference (${providers.join(\", \")})`;\n } catch {\n return \"a provider reference\";\n }\n }\n try {\n const url = new URL(file.source);\n return `${url.origin}${url.pathname}`;\n } catch {\n return \"a file URL\";\n }\n}\n\ntype ToolResult = Extract<Part, { type: \"tool-result\" }>;\n\n/**\n * The blocks a tool result counts as. A result whose output is content is counted part by part, so an image a tool\n * returns, such as a screenshot, counts as an image and not as its base64 characters.\n */\nfunction toolResultBlocks(part: ToolResult, sizes: SizeTable): ContentBlock[] {\n const { output, ...rest } = part;\n if (output.type !== \"content\") return [{ type: \"text\", text: serialise(part) }];\n const header: ContentBlock = { type: \"text\", text: serialise(rest) };\n return [\n header,\n ...output.value.flatMap((item): ContentBlock[] => {\n if (item.type === \"text\") return [{ type: \"text\", text: item.text }];\n if (item.type === \"file\") return fileBlocks(item.data, item.mediaType, undefined, sizes);\n return [{ type: \"text\", text: serialise(item) }];\n }),\n ];\n}\n\n/** The gateway blocks one AI SDK part counts as. */\nfunction blocks(part: Part, sizes: SizeTable): ContentBlock[] {\n switch (part.type) {\n case \"text\":\n return [{ type: \"text\", text: part.text }];\n case \"reasoning\":\n return [{ type: \"reasoning\", text: part.text }];\n case \"tool-call\":\n return [{ type: \"tool_call\", callId: part.toolCallId, name: part.toolName, input: part.input }];\n case \"file\":\n case \"reasoning-file\":\n return fileBlocks(part.data, part.mediaType, \"filename\" in part ? part.filename : undefined, sizes);\n case \"tool-result\":\n return toolResultBlocks(part, sizes);\n default:\n return [{ type: \"text\", text: serialise(part) }];\n }\n}\n\n/** The characters of text, reasoning and tool calls in `content`, measured as the gateway's estimate measures them. */\nfunction contentChars(content: readonly ContentBlock[]): number {\n return content.reduce((sum, block) => {\n if (block.type === \"text\" || block.type === \"reasoning\") return sum + block.text.length;\n if (block.type === \"tool_call\") return sum + block.name.length + JSON.stringify(block.input ?? null).length;\n return sum;\n }, 0);\n}\n\n/**\n * A recorded call whose answer the prompt continues: the prompt index of that answer, the call's usage, and the\n * characters of text, reasoning and tool calls the call returned.\n */\nexport interface ReportedCall {\n readonly index: number;\n readonly usage: Usage;\n readonly responseChars: number;\n}\n\n/**\n * The usage that stands in for an assistant message. When the message holds more than the recorded call returned, it\n * isn't that call's answer as returned, so its output counts at least the message's own character estimate.\n */\nfunction standInUsage(content: readonly ContentBlock[], reported: ReportedCall): Usage {\n const { usage } = reported;\n if (contentChars(content) <= reported.responseChars) return usage;\n const own = estimateInputTokens({ system: \"\", tools: [], messages: [{ role: \"user\", content: [...content] }] });\n return { ...usage, output: Math.max(usage.output, own) };\n}\n\nfunction message(prompt: PromptMessage, reported: ReportedCall | undefined, sizes: SizeTable): Message | undefined {\n if (prompt.role === \"system\") return undefined;\n const content = prompt.content.flatMap((part) => blocks(part as Part, sizes));\n switch (prompt.role) {\n case \"user\":\n return { role: \"user\", content };\n case \"tool\":\n return {\n role: \"tool\",\n callId: \"\",\n content: content as Extract<Message, { role: \"tool\" }>[\"content\"],\n isError: false,\n };\n case \"assistant\":\n return {\n role: \"assistant\",\n content,\n model: MODEL,\n stopReason: \"stop\",\n usage: reported === undefined ? unreportedUsage() : standInUsage(content, reported),\n cost: NO_COST,\n };\n }\n}\n\nfunction wireTool(tool: CallTool): WireTool {\n if (tool.type === \"function\") {\n return {\n name: tool.name,\n description: tool.description ?? \"\",\n inputSchema: tool.inputSchema as Record<string, unknown>,\n };\n }\n return { name: tool.name, description: tool.id, inputSchema: tool.args };\n}\n\n/**\n * The gateway context that one AI SDK request stands for. `reported` names the prompt index of the assistant message\n * a recorded call produced, with that call's usage, so `estimateInputTokens()` counts everything up to that message\n * from the provider's own numbers. `sizes` holds the sizes of the files the prompt points at, from `sizeFiles()`.\n */\nexport function gatewayContext(\n prompt: Prompt,\n tools: readonly CallTool[] | undefined,\n reported: ReportedCall | undefined,\n sizes: SizeTable,\n): ModelContext {\n const system = prompt.flatMap((m) => (m.role === \"system\" ? [m.content] : [])).join(\"\\n\");\n const messages = prompt.flatMap((m, i) => message(m, i === reported?.index ? reported : undefined, sizes) ?? []);\n return { system, messages, tools: (tools ?? []).map(wireTool) };\n}\n\n/** One key per message, equal for two messages only when they are the same, to recognise a prompt a call continues. */\nexport function messageKeys(prompt: Prompt): string[] {\n return prompt.map(serialise);\n}\n\n/** A key for the tools a request offers, equal for two requests only when they offer the same tools. */\nexport function toolsKey(tools: readonly CallTool[] | undefined): string {\n return serialise(tools ?? []);\n}\n\n/** The characters of text, reasoning and tool calls in a response part, measured as `contentChars()` measures them. */\nexport function responsePartChars(part: { readonly type: string }): number {\n const p = part as { type: string; text?: unknown; delta?: unknown; toolName?: unknown; input?: unknown };\n if ((p.type === \"text\" || p.type === \"reasoning\") && typeof p.text === \"string\") return p.text.length;\n if ((p.type === \"text-delta\" || p.type === \"reasoning-delta\") && typeof p.delta === \"string\") return p.delta.length;\n if (p.type === \"tool-call\" && typeof p.toolName === \"string\" && typeof p.input === \"string\") {\n return p.toolName.length + p.input.length;\n }\n return 0;\n}\n\n/**\n * The gateway's usage record for an AI SDK response, or an unreported one when the provider left out the input or\n * output total. A missing breakdown is derived from the totals: uncached input is the input left after cache reads and\n * writes, and every cache write counts as a short-lived one, which `priceResponse()` prices at the dearer lifetime.\n */\nexport function gatewayUsage(usage: ModelUsage | undefined): Usage {\n const input = usage?.inputTokens;\n const output = usage?.outputTokens;\n if (input?.total === undefined || output?.total === undefined) return unreportedUsage(usage ?? null);\n const cacheRead = input.cacheRead ?? 0;\n const cacheWrite = input.cacheWrite ?? 0;\n return {\n ...emptyUsage(usage?.raw ?? null),\n uncachedInput: input.noCache ?? Math.max(0, input.total - cacheRead - cacheWrite),\n cacheRead,\n cacheWrite: { \"5m\": cacheWrite, \"1h\": 0 },\n output: output.total,\n reasoning: output.reasoning ?? 0,\n };\n}\n\n/**\n * The response's price in USD, or `null` when its usage is unreported. The AI SDK reports cache writes as one count,\n * so they are priced at whichever of the short and long write rates costs more, which errs towards a higher spend.\n */\nexport function priceResponse(usage: Usage, entry: CatalogEntry): number | null {\n const short = priceUsage(usage, entry).total;\n const long = priceUsage({ ...usage, cacheWrite: { \"5m\": 0, \"1h\": usage.cacheWrite[\"5m\"] } }, entry).total;\n if (short === null || long === null) return null;\n return Math.max(short, long);\n}\n"]}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `guardedProvider()` and `guardedModel()`: apply cost guards to every language model of a provider, or to one model.
|
|
3
|
+
* A model that never passes through a guard escapes its cap, so build every model a run uses, the ones `prepareStep`
|
|
4
|
+
* switches to included, from one guarded provider.
|
|
5
|
+
*/
|
|
6
|
+
import { type LanguageModelMiddleware, wrapLanguageModel, wrapProvider } from "ai";
|
|
7
|
+
/** A provider the AI SDK accepts: a `ProviderV4`, `ProviderV3` or `ProviderV2`. */
|
|
8
|
+
export type GuardableProvider = Parameters<typeof wrapProvider>[0]["provider"];
|
|
9
|
+
/** A provider whose language models all run through the guards: a `ProviderV4`. */
|
|
10
|
+
export type GuardedProvider = ReturnType<typeof wrapProvider>;
|
|
11
|
+
/** A language model the AI SDK accepts: a `LanguageModelV4`, `LanguageModelV3` or `LanguageModelV2`. */
|
|
12
|
+
export type GuardableModel = Parameters<typeof wrapLanguageModel>[0]["model"];
|
|
13
|
+
/** A language model wrapped in guards: a `LanguageModelV4`. */
|
|
14
|
+
export type GuardedModel = ReturnType<typeof wrapLanguageModel>;
|
|
15
|
+
type Guards = LanguageModelMiddleware | readonly LanguageModelMiddleware[];
|
|
16
|
+
/**
|
|
17
|
+
* The provider with `guards` around each language model it returns, through the AI SDK's `wrapProvider()`. Pass
|
|
18
|
+
* several guards, such as a per-run and a per-session `costGuard()`, and a call goes out only when every guard allows
|
|
19
|
+
* it. Call its `languageModel(id)` for each model; embedding, image and other models pass through unguarded.
|
|
20
|
+
*/
|
|
21
|
+
export declare function guardedProvider(provider: GuardableProvider, guards: Guards): GuardedProvider;
|
|
22
|
+
/** One model with `guards` around it, through the AI SDK's `wrapLanguageModel()`. */
|
|
23
|
+
export declare function guardedModel(model: GuardableModel, guards: Guards): GuardedModel;
|
|
24
|
+
export {};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `guardedProvider()` and `guardedModel()`: apply cost guards to every language model of a provider, or to one model.
|
|
3
|
+
* A model that never passes through a guard escapes its cap, so build every model a run uses, the ones `prepareStep`
|
|
4
|
+
* switches to included, from one guarded provider.
|
|
5
|
+
*/
|
|
6
|
+
import { wrapLanguageModel, wrapProvider } from "ai";
|
|
7
|
+
/**
|
|
8
|
+
* The provider with `guards` around each language model it returns, through the AI SDK's `wrapProvider()`. Pass
|
|
9
|
+
* several guards, such as a per-run and a per-session `costGuard()`, and a call goes out only when every guard allows
|
|
10
|
+
* it. Call its `languageModel(id)` for each model; embedding, image and other models pass through unguarded.
|
|
11
|
+
*/
|
|
12
|
+
export function guardedProvider(provider, guards) {
|
|
13
|
+
return wrapProvider({ provider, languageModelMiddleware: [guards].flat() });
|
|
14
|
+
}
|
|
15
|
+
/** One model with `guards` around it, through the AI SDK's `wrapLanguageModel()`. */
|
|
16
|
+
export function guardedModel(model, guards) {
|
|
17
|
+
return wrapLanguageModel({ model, middleware: [guards].flat() });
|
|
18
|
+
}
|
|
19
|
+
//# sourceMappingURL=guarded-provider.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"guarded-provider.js","sourceRoot":"","sources":["../../src/cost/guarded-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAgC,iBAAiB,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAanF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAA2B,EAAE,MAAc;IACzE,OAAO,YAAY,CAAC,EAAE,QAAQ,EAAE,uBAAuB,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,KAAqB,EAAE,MAAc;IAChE,OAAO,iBAAiB,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC","sourcesContent":["/**\n * `guardedProvider()` and `guardedModel()`: apply cost guards to every language model of a provider, or to one model.\n * A model that never passes through a guard escapes its cap, so build every model a run uses, the ones `prepareStep`\n * switches to included, from one guarded provider.\n */\nimport { type LanguageModelMiddleware, wrapLanguageModel, wrapProvider } from \"ai\";\n\n/** A provider the AI SDK accepts: a `ProviderV4`, `ProviderV3` or `ProviderV2`. */\nexport type GuardableProvider = Parameters<typeof wrapProvider>[0][\"provider\"];\n/** A provider whose language models all run through the guards: a `ProviderV4`. */\nexport type GuardedProvider = ReturnType<typeof wrapProvider>;\n/** A language model the AI SDK accepts: a `LanguageModelV4`, `LanguageModelV3` or `LanguageModelV2`. */\nexport type GuardableModel = Parameters<typeof wrapLanguageModel>[0][\"model\"];\n/** A language model wrapped in guards: a `LanguageModelV4`. */\nexport type GuardedModel = ReturnType<typeof wrapLanguageModel>;\n\ntype Guards = LanguageModelMiddleware | readonly LanguageModelMiddleware[];\n\n/**\n * The provider with `guards` around each language model it returns, through the AI SDK's `wrapProvider()`. Pass\n * several guards, such as a per-run and a per-session `costGuard()`, and a call goes out only when every guard allows\n * it. Call its `languageModel(id)` for each model; embedding, image and other models pass through unguarded.\n */\nexport function guardedProvider(provider: GuardableProvider, guards: Guards): GuardedProvider {\n return wrapProvider({ provider, languageModelMiddleware: [guards].flat() });\n}\n\n/** One model with `guards` around it, through the AI SDK's `wrapLanguageModel()`. */\nexport function guardedModel(model: GuardableModel, guards: Guards): GuardedModel {\n return wrapLanguageModel({ model, middleware: [guards].flat() });\n}\n"]}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/agent-safety/cost`: a USD cap for the Vercel AI SDK, checked before each model call. `costGuard()` is
|
|
3
|
+
* a language-model middleware that refuses a call with `BudgetExceeded` when the spend so far plus the call's
|
|
4
|
+
* projected cost would pass the cap, and `guardedProvider()` applies it to every model of a provider. The projection
|
|
5
|
+
* is the gateway's, so this cap and the SDK's `budgetUsd` agree. This subpath imports `ai`, an optional peer
|
|
6
|
+
* dependency, and `@buildanagent/gateway`.
|
|
7
|
+
*/
|
|
8
|
+
export { BudgetExceeded, type BudgetRefusalCode, type BudgetRefusalInit, budgetRefusal } from "./budget-exceeded.js";
|
|
9
|
+
export { type CostGuardOptions, costGuard, type GuardedCall } from "./cost-guard.js";
|
|
10
|
+
export type { FileRef, FileSize, FileSizer } from "./estimate.js";
|
|
11
|
+
export { type GuardableModel, type GuardableProvider, type GuardedModel, type GuardedProvider, guardedModel, guardedProvider, } from "./guarded-provider.js";
|
|
12
|
+
export { memorySpend, type Spend } from "./spend.js";
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/agent-safety/cost`: a USD cap for the Vercel AI SDK, checked before each model call. `costGuard()` is
|
|
3
|
+
* a language-model middleware that refuses a call with `BudgetExceeded` when the spend so far plus the call's
|
|
4
|
+
* projected cost would pass the cap, and `guardedProvider()` applies it to every model of a provider. The projection
|
|
5
|
+
* is the gateway's, so this cap and the SDK's `budgetUsd` agree. This subpath imports `ai`, an optional peer
|
|
6
|
+
* dependency, and `@buildanagent/gateway`.
|
|
7
|
+
*/
|
|
8
|
+
export { BudgetExceeded, budgetRefusal } from "./budget-exceeded.js";
|
|
9
|
+
export { costGuard } from "./cost-guard.js";
|
|
10
|
+
export { guardedModel, guardedProvider, } from "./guarded-provider.js";
|
|
11
|
+
export { memorySpend } from "./spend.js";
|
|
12
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cost/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAkD,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrH,OAAO,EAAyB,SAAS,EAAoB,MAAM,iBAAiB,CAAC;AAErF,OAAO,EAKL,YAAY,EACZ,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC","sourcesContent":["/**\n * `@buildanagent/agent-safety/cost`: a USD cap for the Vercel AI SDK, checked before each model call. `costGuard()` is\n * a language-model middleware that refuses a call with `BudgetExceeded` when the spend so far plus the call's\n * projected cost would pass the cap, and `guardedProvider()` applies it to every model of a provider. The projection\n * is the gateway's, so this cap and the SDK's `budgetUsd` agree. This subpath imports `ai`, an optional peer\n * dependency, and `@buildanagent/gateway`.\n */\nexport { BudgetExceeded, type BudgetRefusalCode, type BudgetRefusalInit, budgetRefusal } from \"./budget-exceeded.js\";\nexport { type CostGuardOptions, costGuard, type GuardedCall } from \"./cost-guard.js\";\nexport type { FileRef, FileSize, FileSizer } from \"./estimate.js\";\nexport {\n type GuardableModel,\n type GuardableProvider,\n type GuardedModel,\n type GuardedProvider,\n guardedModel,\n guardedProvider,\n} from \"./guarded-provider.js\";\nexport { memorySpend, type Spend } from \"./spend.js\";\n"]}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `Spend`: where a cost guard keeps what a run or a session has spent. One `Spend` per run caps each run; one that
|
|
3
|
+
* outlives the run, kept in storage every run of a session reads, caps the session.
|
|
4
|
+
*/
|
|
5
|
+
/** The USD a run or session has spent on model calls so far. */
|
|
6
|
+
export interface Spend {
|
|
7
|
+
/** The dollars spent so far. */
|
|
8
|
+
get(): Promise<number>;
|
|
9
|
+
/** Records the cost of one finished call, in dollars. */
|
|
10
|
+
add(usd: number): Promise<void>;
|
|
11
|
+
}
|
|
12
|
+
/** A `Spend` held in memory, starting at `initialUsd`, which lasts as long as the object does. */
|
|
13
|
+
export declare function memorySpend(initialUsd?: number): Spend;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `Spend`: where a cost guard keeps what a run or a session has spent. One `Spend` per run caps each run; one that
|
|
3
|
+
* outlives the run, kept in storage every run of a session reads, caps the session.
|
|
4
|
+
*/
|
|
5
|
+
/** A `Spend` held in memory, starting at `initialUsd`, which lasts as long as the object does. */
|
|
6
|
+
export function memorySpend(initialUsd = 0) {
|
|
7
|
+
let spent = initialUsd;
|
|
8
|
+
return {
|
|
9
|
+
get: async () => spent,
|
|
10
|
+
add: async (usd) => {
|
|
11
|
+
spent += usd;
|
|
12
|
+
},
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
//# sourceMappingURL=spend.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"spend.js","sourceRoot":"","sources":["../../src/cost/spend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,kGAAkG;AAClG,MAAM,UAAU,WAAW,CAAC,UAAU,GAAG,CAAC;IACxC,IAAI,KAAK,GAAG,UAAU,CAAC;IACvB,OAAO;QACL,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK;QACtB,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjB,KAAK,IAAI,GAAG,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `Spend`: where a cost guard keeps what a run or a session has spent. One `Spend` per run caps each run; one that\n * outlives the run, kept in storage every run of a session reads, caps the session.\n */\n\n/** The USD a run or session has spent on model calls so far. */\nexport interface Spend {\n /** The dollars spent so far. */\n get(): Promise<number>;\n /** Records the cost of one finished call, in dollars. */\n add(usd: number): Promise<void>;\n}\n\n/** A `Spend` held in memory, starting at `initialUsd`, which lasts as long as the object does. */\nexport function memorySpend(initialUsd = 0): Spend {\n let spent = initialUsd;\n return {\n get: async () => spent,\n add: async (usd) => {\n spent += usd;\n },\n };\n}\n"]}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** Where a write was asked for: the tenant, the session and branch of the conversation, and the model's tool call. */
|
|
2
|
+
export interface EffectScope {
|
|
3
|
+
/** The tenant the write acts for. One tenant is one user, so a business key never spans two users. */
|
|
4
|
+
readonly tenant: string;
|
|
5
|
+
/** The session the tool call belongs to. */
|
|
6
|
+
readonly session: string;
|
|
7
|
+
/** The branch of the session's tree, so a forked or rewound branch that replays a call id gets its own key. */
|
|
8
|
+
readonly branch: string;
|
|
9
|
+
/** The model's id for this tool call. */
|
|
10
|
+
readonly toolCallId: string;
|
|
11
|
+
}
|
|
12
|
+
/** Throws a `SafetyError`, code `invalid_effect`, unless every scope field and the business key are non-empty text. */
|
|
13
|
+
export declare function checkEffectScope(scope: EffectScope, businessKey?: string): void;
|
|
14
|
+
/**
|
|
15
|
+
* Returns the effect key of a write, as 64 lowercase hex digits.
|
|
16
|
+
*
|
|
17
|
+
* With a business key, the key depends only on the tenant and the business key, so every call for the same business
|
|
18
|
+
* object, from any session, branch or turn, shares one key. Declare a business key for every tool that sends,
|
|
19
|
+
* submits, pays or deletes, such as `email:{threadId}:{draftId}` or `refund:{orderId}`: without one, a regenerated
|
|
20
|
+
* turn carries a fresh call id, gets a fresh key, and can repeat the write. Without a business key, the key depends on
|
|
21
|
+
* all four scope fields.
|
|
22
|
+
*
|
|
23
|
+
* The key is async, because Web Crypto's digest is. It rejects with a `SafetyError`, code `invalid_effect`, for an
|
|
24
|
+
* empty scope field or business key, and with code `invalid_input` for text holding a lone surrogate.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* ```ts
|
|
28
|
+
* const key = await effectKey(scope, `refund:${input.orderId}`);
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare function effectKey(scope: EffectScope, businessKey?: string): Promise<string>;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `effectKey()`: the identity of one write, fixed before the write runs. A tool that declares a business key, such as
|
|
3
|
+
* `refund:{orderId}`, gets one key per tenant and business key, so a regenerated model turn, which carries a fresh
|
|
4
|
+
* tool call id, or a new session maps to the same effect. Without a business key the identity falls back to the tool
|
|
5
|
+
* call: tenant, session, branch and call id, the scope the server rollback report asks for. The owner chose the
|
|
6
|
+
* business key's scope on 2026-11-18: one tenant, which is one user, and never the session (close-sdk-gaps SG3).
|
|
7
|
+
*
|
|
8
|
+
* The key is a hash, not the joined fields, because an external API may cap its length and should never see the
|
|
9
|
+
* business key's own text, which can hold an email address or an order number.
|
|
10
|
+
*/
|
|
11
|
+
import { SafetyError } from "./errors.js";
|
|
12
|
+
import { canonicalInputHash } from "./hash.js";
|
|
13
|
+
// Domain separation, so an effect key never equals the hash of some tool input that happens to hold the same fields.
|
|
14
|
+
const DOMAIN = "buildanagent.effect-key.v1";
|
|
15
|
+
function invalid(message) {
|
|
16
|
+
return new SafetyError("invalid_effect", message);
|
|
17
|
+
}
|
|
18
|
+
function requireField(value, field) {
|
|
19
|
+
if (typeof value !== "string" || value.trim() === "")
|
|
20
|
+
throw invalid(`an effect scope's ${field} must be non-empty`);
|
|
21
|
+
}
|
|
22
|
+
/** Throws a `SafetyError`, code `invalid_effect`, unless every scope field and the business key are non-empty text. */
|
|
23
|
+
export function checkEffectScope(scope, businessKey) {
|
|
24
|
+
if (typeof scope !== "object" || scope === null)
|
|
25
|
+
throw invalid("an effect scope must be an object");
|
|
26
|
+
for (const field of ["tenant", "session", "branch", "toolCallId"])
|
|
27
|
+
requireField(scope[field], field);
|
|
28
|
+
if (businessKey !== undefined && (typeof businessKey !== "string" || businessKey.trim() === "")) {
|
|
29
|
+
throw invalid("a business key must be non-empty when it is set");
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Returns the effect key of a write, as 64 lowercase hex digits.
|
|
34
|
+
*
|
|
35
|
+
* With a business key, the key depends only on the tenant and the business key, so every call for the same business
|
|
36
|
+
* object, from any session, branch or turn, shares one key. Declare a business key for every tool that sends,
|
|
37
|
+
* submits, pays or deletes, such as `email:{threadId}:{draftId}` or `refund:{orderId}`: without one, a regenerated
|
|
38
|
+
* turn carries a fresh call id, gets a fresh key, and can repeat the write. Without a business key, the key depends on
|
|
39
|
+
* all four scope fields.
|
|
40
|
+
*
|
|
41
|
+
* The key is async, because Web Crypto's digest is. It rejects with a `SafetyError`, code `invalid_effect`, for an
|
|
42
|
+
* empty scope field or business key, and with code `invalid_input` for text holding a lone surrogate.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* const key = await effectKey(scope, `refund:${input.orderId}`);
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
export async function effectKey(scope, businessKey) {
|
|
50
|
+
checkEffectScope(scope, businessKey);
|
|
51
|
+
return canonicalInputHash(businessKey === undefined
|
|
52
|
+
? {
|
|
53
|
+
domain: DOMAIN,
|
|
54
|
+
tenant: scope.tenant,
|
|
55
|
+
session: scope.session,
|
|
56
|
+
branch: scope.branch,
|
|
57
|
+
toolCallId: scope.toolCallId,
|
|
58
|
+
}
|
|
59
|
+
: { domain: DOMAIN, tenant: scope.tenant, businessKey });
|
|
60
|
+
}
|
|
61
|
+
//# sourceMappingURL=effect-key.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"effect-key.js","sourceRoot":"","sources":["../src/effect-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAc/C,qHAAqH;AACrH,MAAM,MAAM,GAAG,4BAA4B,CAAC;AAE5C,SAAS,OAAO,CAAC,OAAe;IAC9B,OAAO,IAAI,WAAW,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,KAAa;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,OAAO,CAAC,qBAAqB,KAAK,oBAAoB,CAAC,CAAC;AACtH,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,gBAAgB,CAAC,KAAkB,EAAE,WAAoB;IACvE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,MAAM,OAAO,CAAC,mCAAmC,CAAC,CAAC;IACpG,KAAK,MAAM,KAAK,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,CAAU;QAAE,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9G,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAChG,MAAM,OAAO,CAAC,iDAAiD,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAkB,EAAE,WAAoB;IACtE,gBAAgB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACrC,OAAO,kBAAkB,CACvB,WAAW,KAAK,SAAS;QACvB,CAAC,CAAC;YACE,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B;QACH,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,CAC1D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * `effectKey()`: the identity of one write, fixed before the write runs. A tool that declares a business key, such as\n * `refund:{orderId}`, gets one key per tenant and business key, so a regenerated model turn, which carries a fresh\n * tool call id, or a new session maps to the same effect. Without a business key the identity falls back to the tool\n * call: tenant, session, branch and call id, the scope the server rollback report asks for. The owner chose the\n * business key's scope on 2026-11-18: one tenant, which is one user, and never the session (close-sdk-gaps SG3).\n *\n * The key is a hash, not the joined fields, because an external API may cap its length and should never see the\n * business key's own text, which can hold an email address or an order number.\n */\nimport { SafetyError } from \"./errors.js\";\nimport { canonicalInputHash } from \"./hash.js\";\n\n/** Where a write was asked for: the tenant, the session and branch of the conversation, and the model's tool call. */\nexport interface EffectScope {\n /** The tenant the write acts for. One tenant is one user, so a business key never spans two users. */\n readonly tenant: string;\n /** The session the tool call belongs to. */\n readonly session: string;\n /** The branch of the session's tree, so a forked or rewound branch that replays a call id gets its own key. */\n readonly branch: string;\n /** The model's id for this tool call. */\n readonly toolCallId: string;\n}\n\n// Domain separation, so an effect key never equals the hash of some tool input that happens to hold the same fields.\nconst DOMAIN = \"buildanagent.effect-key.v1\";\n\nfunction invalid(message: string): SafetyError {\n return new SafetyError(\"invalid_effect\", message);\n}\n\nfunction requireField(value: unknown, field: string): void {\n if (typeof value !== \"string\" || value.trim() === \"\") throw invalid(`an effect scope's ${field} must be non-empty`);\n}\n\n/** Throws a `SafetyError`, code `invalid_effect`, unless every scope field and the business key are non-empty text. */\nexport function checkEffectScope(scope: EffectScope, businessKey?: string): void {\n if (typeof scope !== \"object\" || scope === null) throw invalid(\"an effect scope must be an object\");\n for (const field of [\"tenant\", \"session\", \"branch\", \"toolCallId\"] as const) requireField(scope[field], field);\n if (businessKey !== undefined && (typeof businessKey !== \"string\" || businessKey.trim() === \"\")) {\n throw invalid(\"a business key must be non-empty when it is set\");\n }\n}\n\n/**\n * Returns the effect key of a write, as 64 lowercase hex digits.\n *\n * With a business key, the key depends only on the tenant and the business key, so every call for the same business\n * object, from any session, branch or turn, shares one key. Declare a business key for every tool that sends,\n * submits, pays or deletes, such as `email:{threadId}:{draftId}` or `refund:{orderId}`: without one, a regenerated\n * turn carries a fresh call id, gets a fresh key, and can repeat the write. Without a business key, the key depends on\n * all four scope fields.\n *\n * The key is async, because Web Crypto's digest is. It rejects with a `SafetyError`, code `invalid_effect`, for an\n * empty scope field or business key, and with code `invalid_input` for text holding a lone surrogate.\n *\n * @example\n * ```ts\n * const key = await effectKey(scope, `refund:${input.orderId}`);\n * ```\n */\nexport async function effectKey(scope: EffectScope, businessKey?: string): Promise<string> {\n checkEffectScope(scope, businessKey);\n return canonicalInputHash(\n businessKey === undefined\n ? {\n domain: DOMAIN,\n tenant: scope.tenant,\n session: scope.session,\n branch: scope.branch,\n toolCallId: scope.toolCallId,\n }\n : { domain: DOMAIN, tenant: scope.tenant, businessKey },\n );\n}\n"]}
|