@earendil-works/pi-ai 1.3.0 → 1.5.0

package/dist/telemetry.d.ts

@@ -0,0 +1,288 @@
+import { type TelemetrySpan } from "@earendil-works/pi-telemetry";
+import type { LazyStreamObserver } from "./api/lazy.ts";
+import type { Api, Model } from "./types.ts";
+/** Pi-owned request metadata, bounded error status, events, and low-cardinality metrics. */
+export declare const AI_TELEMETRY_SCHEMA: {
+    readonly version: 1;
+    readonly spans: {
+        readonly "pi.ai.request": {
+            readonly description: "One logical model request, including authentication and provider setup.";
+            readonly parents: {
+                readonly kind: "any";
+            };
+            readonly startAttributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly api: {
+                    readonly type: "string";
+                    readonly description: "API identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+                readonly reasoning: {
+                    readonly type: "string";
+                    readonly description: "Scalar requested reasoning level.";
+                    readonly required: false;
+                };
+            };
+            readonly endAttributes: {
+                readonly stop: {
+                    readonly type: "string";
+                    readonly description: "Normalized stop reason.";
+                    readonly values: readonly ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"];
+                };
+                readonly "usage.input": {
+                    readonly type: "number";
+                    readonly description: "Uncached input tokens.";
+                };
+                readonly "usage.output": {
+                    readonly type: "number";
+                    readonly description: "Output tokens.";
+                };
+                readonly "usage.cache_read": {
+                    readonly type: "number";
+                    readonly description: "Cache-read tokens.";
+                };
+                readonly "usage.cache_write": {
+                    readonly type: "number";
+                    readonly description: "Cache-write tokens.";
+                };
+                readonly "cost.total": {
+                    readonly type: "number";
+                    readonly description: "Total request cost in USD.";
+                };
+                readonly "response.id": {
+                    readonly type: "string";
+                    readonly description: "Provider response identifier.";
+                    readonly cardinality: "high";
+                };
+            };
+            readonly events: {
+                readonly "pi.ai.first_chunk": {
+                    readonly description: "First normalized stream event delivered.";
+                    readonly attributes: {};
+                };
+                readonly "pi.ai.block": {
+                    readonly description: "A completed content block; content is never recorded.";
+                    readonly attributes: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly description: "Block kind.";
+                            readonly values: readonly ["text", "thinking", "tool_call"];
+                            readonly required: true;
+                        };
+                        readonly index: {
+                            readonly type: "number";
+                            readonly description: "Content block index.";
+                            readonly required: true;
+                        };
+                        readonly chars: {
+                            readonly type: "number";
+                            readonly description: "UTF-16 character count.";
+                            readonly required: true;
+                        };
+                        readonly tool: {
+                            readonly type: "string";
+                            readonly description: "Tool name, for tool-call blocks only.";
+                            readonly required: false;
+                        };
+                    };
+                };
+            };
+            readonly status: {
+                readonly default: "ok";
+                readonly errorWhen: "Stop reason is error: provider_error with at most 500 error-message characters. Aborted stays ok.";
+            };
+        };
+        readonly "pi.ai.poll": {
+            readonly parents: {
+                readonly kind: "any";
+            };
+            readonly startAttributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly api: {
+                    readonly type: "string";
+                    readonly description: "API identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+                readonly reasoning: {
+                    readonly type: "string";
+                    readonly description: "Scalar requested reasoning level.";
+                    readonly required: false;
+                };
+            };
+            readonly endAttributes: {
+                readonly stop: {
+                    readonly type: "string";
+                    readonly description: "Normalized stop reason.";
+                    readonly values: readonly ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"];
+                };
+                readonly "usage.input": {
+                    readonly type: "number";
+                    readonly description: "Uncached input tokens.";
+                };
+                readonly "usage.output": {
+                    readonly type: "number";
+                    readonly description: "Output tokens.";
+                };
+                readonly "usage.cache_read": {
+                    readonly type: "number";
+                    readonly description: "Cache-read tokens.";
+                };
+                readonly "usage.cache_write": {
+                    readonly type: "number";
+                    readonly description: "Cache-write tokens.";
+                };
+                readonly "cost.total": {
+                    readonly type: "number";
+                    readonly description: "Total request cost in USD.";
+                };
+                readonly "response.id": {
+                    readonly type: "string";
+                    readonly description: "Provider response identifier.";
+                    readonly cardinality: "high";
+                };
+            };
+            readonly events: {
+                readonly "pi.ai.first_chunk": {
+                    readonly description: "First normalized stream event delivered.";
+                    readonly attributes: {};
+                };
+                readonly "pi.ai.block": {
+                    readonly description: "A completed content block; content is never recorded.";
+                    readonly attributes: {
+                        readonly type: {
+                            readonly type: "string";
+                            readonly description: "Block kind.";
+                            readonly values: readonly ["text", "thinking", "tool_call"];
+                            readonly required: true;
+                        };
+                        readonly index: {
+                            readonly type: "number";
+                            readonly description: "Content block index.";
+                            readonly required: true;
+                        };
+                        readonly chars: {
+                            readonly type: "number";
+                            readonly description: "UTF-16 character count.";
+                            readonly required: true;
+                        };
+                        readonly tool: {
+                            readonly type: "string";
+                            readonly description: "Tool name, for tool-call blocks only.";
+                            readonly required: false;
+                        };
+                    };
+                };
+            };
+            readonly status: {
+                readonly default: "ok";
+                readonly errorWhen: "Stop reason is error: provider_error with at most 500 error-message characters. Aborted stays ok.";
+            };
+            readonly description: "One deferred-response poll, not the deferred request's lifetime.";
+        };
+    };
+    readonly metrics: {
+        readonly "pi.ai.request.duration": {
+            readonly kind: "histogram";
+            readonly description: "Logical request or poll duration.";
+            readonly unit: "ms";
+            readonly attributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+                readonly stop: {
+                    readonly type: "string";
+                    readonly description: "Normalized stop reason.";
+                    readonly values: readonly ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"];
+                    readonly required: true;
+                };
+            };
+        };
+        readonly "pi.ai.first_chunk.duration": {
+            readonly kind: "histogram";
+            readonly description: "Time to the first normalized stream event.";
+            readonly unit: "ms";
+            readonly attributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+            };
+        };
+        readonly "pi.ai.tokens": {
+            readonly kind: "counter";
+            readonly description: "Reported model token usage; pending and deferred polls are excluded.";
+            readonly unit: "token";
+            readonly attributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+                readonly kind: {
+                    readonly type: "string";
+                    readonly description: "Token usage category.";
+                    readonly values: readonly ["input", "output", "cache_read", "cache_write"];
+                    readonly required: true;
+                };
+            };
+        };
+        readonly "pi.ai.cost": {
+            readonly kind: "counter";
+            readonly description: "Reported model cost; pending and deferred polls are excluded.";
+            readonly unit: "USD";
+            readonly attributes: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly description: "Provider identifier.";
+                    readonly required: true;
+                };
+                readonly model: {
+                    readonly type: "string";
+                    readonly description: "Requested model identifier.";
+                    readonly required: true;
+                };
+            };
+        };
+    };
+};
+export declare function observeModelRequest(requestedModel: Model<Api>, options: {
+    telemetry?: TelemetrySpan;
+    reasoning?: unknown;
+} | undefined, poll: boolean): LazyStreamObserver;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.js

@@ -0,0 +1,192 @@
+import { createTypedMetrics, createTypedSpanStarter, defineTelemetrySchema, NOOP_TELEMETRY_CONTEXT, NOOP_TELEMETRY_METRICS, } from "@earendil-works/pi-telemetry";
+import { ownedSlice } from "./utils/text.js";
+const provider = { type: "string", description: "Provider identifier.", required: true };
+const model = { type: "string", description: "Requested model identifier.", required: true };
+const stop = {
+    type: "string",
+    description: "Normalized stop reason.",
+    values: ["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"],
+};
+const request = {
+    description: "One logical model request, including authentication and provider setup.",
+    parents: { kind: "any" },
+    startAttributes: {
+        provider,
+        api: { type: "string", description: "API identifier.", required: true },
+        model,
+        reasoning: { type: "string", description: "Scalar requested reasoning level.", required: false },
+    },
+    endAttributes: {
+        stop,
+        "usage.input": { type: "number", description: "Uncached input tokens." },
+        "usage.output": { type: "number", description: "Output tokens." },
+        "usage.cache_read": { type: "number", description: "Cache-read tokens." },
+        "usage.cache_write": { type: "number", description: "Cache-write tokens." },
+        "cost.total": { type: "number", description: "Total request cost in USD." },
+        "response.id": { type: "string", description: "Provider response identifier.", cardinality: "high" },
+    },
+    events: {
+        "pi.ai.first_chunk": { description: "First normalized stream event delivered.", attributes: {} },
+        "pi.ai.block": {
+            description: "A completed content block; content is never recorded.",
+            attributes: {
+                type: {
+                    type: "string",
+                    description: "Block kind.",
+                    values: ["text", "thinking", "tool_call"],
+                    required: true,
+                },
+                index: { type: "number", description: "Content block index.", required: true },
+                chars: { type: "number", description: "UTF-16 character count.", required: true },
+                tool: { type: "string", description: "Tool name, for tool-call blocks only.", required: false },
+            },
+        },
+    },
+    status: {
+        default: "ok",
+        errorWhen: "Stop reason is error: provider_error with at most 500 error-message characters. Aborted stays ok.",
+    },
+};
+/** Pi-owned request metadata, bounded error status, events, and low-cardinality metrics. */
+export const AI_TELEMETRY_SCHEMA = defineTelemetrySchema({
+    version: 1,
+    spans: {
+        "pi.ai.request": request,
+        "pi.ai.poll": { ...request, description: "One deferred-response poll, not the deferred request's lifetime." },
+    },
+    metrics: {
+        "pi.ai.request.duration": {
+            kind: "histogram",
+            description: "Logical request or poll duration.",
+            unit: "ms",
+            attributes: { provider, model, stop: { ...stop, required: true } },
+        },
+        "pi.ai.first_chunk.duration": {
+            kind: "histogram",
+            description: "Time to the first normalized stream event.",
+            unit: "ms",
+            attributes: { provider, model },
+        },
+        "pi.ai.tokens": {
+            kind: "counter",
+            description: "Reported model token usage; pending and deferred polls are excluded.",
+            unit: "token",
+            attributes: {
+                provider,
+                model,
+                kind: {
+                    type: "string",
+                    description: "Token usage category.",
+                    values: ["input", "output", "cache_read", "cache_write"],
+                    required: true,
+                },
+            },
+        },
+        "pi.ai.cost": {
+            kind: "counter",
+            description: "Reported model cost; pending and deferred polls are excluded.",
+            unit: "USD",
+            attributes: { provider, model },
+        },
+    },
+});
+function createInstruments(adapter) {
+    const metrics = createTypedMetrics(adapter, [AI_TELEMETRY_SCHEMA]);
+    return {
+        requestDuration: metrics.histogram("pi.ai.request.duration"),
+        firstChunkDuration: metrics.histogram("pi.ai.first_chunk.duration"),
+        tokens: metrics.counter("pi.ai.tokens"),
+        cost: metrics.counter("pi.ai.cost"),
+    };
+}
+const instrumentCache = new WeakMap();
+export function observeModelRequest(requestedModel, options, poll) {
+    const started = performance.now();
+    const attributes = { provider: requestedModel.provider, model: requestedModel.id };
+    const adapter = options?.telemetry?.metrics ?? NOOP_TELEMETRY_METRICS;
+    let instruments = instrumentCache.get(adapter);
+    if (!instruments) {
+        instruments = createInstruments(adapter);
+        instrumentCache.set(adapter, instruments);
+    }
+    const { requestDuration, firstChunkDuration, tokens, cost } = instruments;
+    let span;
+    let finish;
+    let first = true;
+    const toolChars = new Map();
+    const finished = new Promise((resolve) => {
+        finish = resolve;
+    });
+    const run = (activeSpan) => {
+        span = activeSpan;
+        return finished;
+    };
+    const startAttributes = {
+        ...attributes,
+        api: requestedModel.api,
+        ...(typeof options?.reasoning === "string" ? { reasoning: options.reasoning } : {}),
+    };
+    const start = createTypedSpanStarter(options?.telemetry ?? NOOP_TELEMETRY_CONTEXT, [AI_TELEMETRY_SCHEMA]);
+    if (poll)
+        void start("pi.ai.poll", startAttributes, run);
+    else
+        void start("pi.ai.request", startAttributes, run);
+    return {
+        onEvent(event) {
+            if (first) {
+                first = false;
+                span.addEvent("pi.ai.first_chunk");
+                firstChunkDuration.record(performance.now() - started, attributes, span);
+            }
+            if (event.type === "toolcall_delta") {
+                toolChars.set(event.contentIndex, (toolChars.get(event.contentIndex) ?? 0) + event.delta.length);
+            }
+            else if (event.type === "text_end" || event.type === "thinking_end") {
+                span.addEvent("pi.ai.block", {
+                    type: event.type === "text_end" ? "text" : "thinking",
+                    index: event.contentIndex,
+                    chars: event.content.length,
+                });
+            }
+            else if (event.type === "toolcall_end") {
+                const chars = toolChars.get(event.contentIndex) ?? 0;
+                toolChars.delete(event.contentIndex);
+                span.addEvent("pi.ai.block", {
+                    type: "tool_call",
+                    index: event.contentIndex,
+                    chars,
+                    tool: event.toolCall.name,
+                });
+            }
+        },
+        onResult(message) {
+            if (message) {
+                span.setAttributes({
+                    stop: message.stopReason,
+                    "usage.input": message.usage.input,
+                    "usage.output": message.usage.output,
+                    "usage.cache_read": message.usage.cacheRead,
+                    "usage.cache_write": message.usage.cacheWrite,
+                    "cost.total": message.usage.cost.total,
+                    "response.id": message.responseId,
+                });
+                if (message.stopReason === "error") {
+                    span.setStatus({
+                        status: "error",
+                        error: { name: "provider_error", message: ownedSlice(message.errorMessage ?? "", 0, 500) },
+                    });
+                }
+                requestDuration.record(performance.now() - started, { ...attributes, stop: message.stopReason }, span);
+                if (!poll || (message.stopReason !== "pending" && message.stopReason !== "deferred")) {
+                    tokens.add(message.usage.input, { ...attributes, kind: "input" });
+                    tokens.add(message.usage.output, { ...attributes, kind: "output" });
+                    tokens.add(message.usage.cacheRead, { ...attributes, kind: "cache_read" });
+                    tokens.add(message.usage.cacheWrite, { ...attributes, kind: "cache_write" });
+                    cost.add(message.usage.cost.total, attributes);
+                }
+            }
+            finish();
+        },
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tcreateTypedMetrics,\n\tcreateTypedSpanStarter,\n\tdefineTelemetrySchema,\n\tNOOP_TELEMETRY_CONTEXT,\n\tNOOP_TELEMETRY_METRICS,\n\ttype SchemaTelemetrySpan,\n\ttype TelemetryMetrics,\n\ttype TelemetrySpan,\n} from \"@earendil-works/pi-telemetry\";\nimport type { LazyStreamObserver } from \"./api/lazy.ts\";\nimport type { Api, Model } from \"./types.ts\";\nimport { ownedSlice } from \"./utils/text.ts\";\n\nconst provider = { type: \"string\", description: \"Provider identifier.\", required: true } as const;\nconst model = { type: \"string\", description: \"Requested model identifier.\", required: true } as const;\nconst stop = {\n\ttype: \"string\",\n\tdescription: \"Normalized stop reason.\",\n\tvalues: [\"pending\", \"stop\", \"length\", \"toolUse\", \"error\", \"aborted\", \"deferred\"],\n} as const;\nconst request = {\n\tdescription: \"One logical model request, including authentication and provider setup.\",\n\tparents: { kind: \"any\" },\n\tstartAttributes: {\n\t\tprovider,\n\t\tapi: { type: \"string\", description: \"API identifier.\", required: true },\n\t\tmodel,\n\t\treasoning: { type: \"string\", description: \"Scalar requested reasoning level.\", required: false },\n\t},\n\tendAttributes: {\n\t\tstop,\n\t\t\"usage.input\": { type: \"number\", description: \"Uncached input tokens.\" },\n\t\t\"usage.output\": { type: \"number\", description: \"Output tokens.\" },\n\t\t\"usage.cache_read\": { type: \"number\", description: \"Cache-read tokens.\" },\n\t\t\"usage.cache_write\": { type: \"number\", description: \"Cache-write tokens.\" },\n\t\t\"cost.total\": { type: \"number\", description: \"Total request cost in USD.\" },\n\t\t\"response.id\": { type: \"string\", description: \"Provider response identifier.\", cardinality: \"high\" },\n\t},\n\tevents: {\n\t\t\"pi.ai.first_chunk\": { description: \"First normalized stream event delivered.\", attributes: {} },\n\t\t\"pi.ai.block\": {\n\t\t\tdescription: \"A completed content block; content is never recorded.\",\n\t\t\tattributes: {\n\t\t\t\ttype: {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescription: \"Block kind.\",\n\t\t\t\t\tvalues: [\"text\", \"thinking\", \"tool_call\"],\n\t\t\t\t\trequired: true,\n\t\t\t\t},\n\t\t\t\tindex: { type: \"number\", description: \"Content block index.\", required: true },\n\t\t\t\tchars: { type: \"number\", description: \"UTF-16 character count.\", required: true },\n\t\t\t\ttool: { type: \"string\", description: \"Tool name, for tool-call blocks only.\", required: false },\n\t\t\t},\n\t\t},\n\t},\n\tstatus: {\n\t\tdefault: \"ok\",\n\t\terrorWhen: \"Stop reason is error: provider_error with at most 500 error-message characters. Aborted stays ok.\",\n\t},\n} as const;\n\n/** Pi-owned request metadata, bounded error status, events, and low-cardinality metrics. */\nexport const AI_TELEMETRY_SCHEMA = defineTelemetrySchema({\n\tversion: 1,\n\tspans: {\n\t\t\"pi.ai.request\": request,\n\t\t\"pi.ai.poll\": { ...request, description: \"One deferred-response poll, not the deferred request's lifetime.\" },\n\t},\n\tmetrics: {\n\t\t\"pi.ai.request.duration\": {\n\t\t\tkind: \"histogram\",\n\t\t\tdescription: \"Logical request or poll duration.\",\n\t\t\tunit: \"ms\",\n\t\t\tattributes: { provider, model, stop: { ...stop, required: true } },\n\t\t},\n\t\t\"pi.ai.first_chunk.duration\": {\n\t\t\tkind: \"histogram\",\n\t\t\tdescription: \"Time to the first normalized stream event.\",\n\t\t\tunit: \"ms\",\n\t\t\tattributes: { provider, model },\n\t\t},\n\t\t\"pi.ai.tokens\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"Reported model token usage; pending and deferred polls are excluded.\",\n\t\t\tunit: \"token\",\n\t\t\tattributes: {\n\t\t\t\tprovider,\n\t\t\t\tmodel,\n\t\t\t\tkind: {\n\t\t\t\t\ttype: \"string\",\n\t\t\t\t\tdescription: \"Token usage category.\",\n\t\t\t\t\tvalues: [\"input\", \"output\", \"cache_read\", \"cache_write\"],\n\t\t\t\t\trequired: true,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t\t\"pi.ai.cost\": {\n\t\t\tkind: \"counter\",\n\t\t\tdescription: \"Reported model cost; pending and deferred polls are excluded.\",\n\t\t\tunit: \"USD\",\n\t\t\tattributes: { provider, model },\n\t\t},\n\t},\n});\n\ntype RequestSpan = SchemaTelemetrySpan<typeof AI_TELEMETRY_SCHEMA, \"pi.ai.request\">;\n\nfunction createInstruments(adapter: TelemetryMetrics) {\n\tconst metrics = createTypedMetrics(adapter, [AI_TELEMETRY_SCHEMA]);\n\treturn {\n\t\trequestDuration: metrics.histogram(\"pi.ai.request.duration\"),\n\t\tfirstChunkDuration: metrics.histogram(\"pi.ai.first_chunk.duration\"),\n\t\ttokens: metrics.counter(\"pi.ai.tokens\"),\n\t\tcost: metrics.counter(\"pi.ai.cost\"),\n\t};\n}\n\nconst instrumentCache = new WeakMap<TelemetryMetrics, ReturnType<typeof createInstruments>>();\n\nexport function observeModelRequest(\n\trequestedModel: Model<Api>,\n\toptions: { telemetry?: TelemetrySpan; reasoning?: unknown } | undefined,\n\tpoll: boolean,\n): LazyStreamObserver {\n\tconst started = performance.now();\n\tconst attributes = { provider: requestedModel.provider, model: requestedModel.id };\n\tconst adapter = options?.telemetry?.metrics ?? NOOP_TELEMETRY_METRICS;\n\tlet instruments = instrumentCache.get(adapter);\n\tif (!instruments) {\n\t\tinstruments = createInstruments(adapter);\n\t\tinstrumentCache.set(adapter, instruments);\n\t}\n\tconst { requestDuration, firstChunkDuration, tokens, cost } = instruments;\n\tlet span!: RequestSpan;\n\tlet finish!: () => void;\n\tlet first = true;\n\tconst toolChars = new Map<number, number>();\n\tconst finished = new Promise<void>((resolve) => {\n\t\tfinish = resolve;\n\t});\n\tconst run = (activeSpan: RequestSpan): Promise<void> => {\n\t\tspan = activeSpan;\n\t\treturn finished;\n\t};\n\tconst startAttributes = {\n\t\t...attributes,\n\t\tapi: requestedModel.api,\n\t\t...(typeof options?.reasoning === \"string\" ? { reasoning: options.reasoning } : {}),\n\t};\n\tconst start = createTypedSpanStarter(options?.telemetry ?? NOOP_TELEMETRY_CONTEXT, [AI_TELEMETRY_SCHEMA]);\n\tif (poll) void start(\"pi.ai.poll\", startAttributes, run);\n\telse void start(\"pi.ai.request\", startAttributes, run);\n\n\treturn {\n\t\tonEvent(event) {\n\t\t\tif (first) {\n\t\t\t\tfirst = false;\n\t\t\t\tspan.addEvent(\"pi.ai.first_chunk\");\n\t\t\t\tfirstChunkDuration.record(performance.now() - started, attributes, span);\n\t\t\t}\n\t\t\tif (event.type === \"toolcall_delta\") {\n\t\t\t\ttoolChars.set(event.contentIndex, (toolChars.get(event.contentIndex) ?? 0) + event.delta.length);\n\t\t\t} else if (event.type === \"text_end\" || event.type === \"thinking_end\") {\n\t\t\t\tspan.addEvent(\"pi.ai.block\", {\n\t\t\t\t\ttype: event.type === \"text_end\" ? \"text\" : \"thinking\",\n\t\t\t\t\tindex: event.contentIndex,\n\t\t\t\t\tchars: event.content.length,\n\t\t\t\t});\n\t\t\t} else if (event.type === \"toolcall_end\") {\n\t\t\t\tconst chars = toolChars.get(event.contentIndex) ?? 0;\n\t\t\t\ttoolChars.delete(event.contentIndex);\n\t\t\t\tspan.addEvent(\"pi.ai.block\", {\n\t\t\t\t\ttype: \"tool_call\",\n\t\t\t\t\tindex: event.contentIndex,\n\t\t\t\t\tchars,\n\t\t\t\t\ttool: event.toolCall.name,\n\t\t\t\t});\n\t\t\t}\n\t\t},\n\t\tonResult(message) {\n\t\t\tif (message) {\n\t\t\t\tspan.setAttributes({\n\t\t\t\t\tstop: message.stopReason,\n\t\t\t\t\t\"usage.input\": message.usage.input,\n\t\t\t\t\t\"usage.output\": message.usage.output,\n\t\t\t\t\t\"usage.cache_read\": message.usage.cacheRead,\n\t\t\t\t\t\"usage.cache_write\": message.usage.cacheWrite,\n\t\t\t\t\t\"cost.total\": message.usage.cost.total,\n\t\t\t\t\t\"response.id\": message.responseId,\n\t\t\t\t});\n\t\t\t\tif (message.stopReason === \"error\") {\n\t\t\t\t\tspan.setStatus({\n\t\t\t\t\t\tstatus: \"error\",\n\t\t\t\t\t\terror: { name: \"provider_error\", message: ownedSlice(message.errorMessage ?? \"\", 0, 500) },\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\trequestDuration.record(performance.now() - started, { ...attributes, stop: message.stopReason }, span);\n\t\t\t\tif (!poll || (message.stopReason !== \"pending\" && message.stopReason !== \"deferred\")) {\n\t\t\t\t\ttokens.add(message.usage.input, { ...attributes, kind: \"input\" });\n\t\t\t\t\ttokens.add(message.usage.output, { ...attributes, kind: \"output\" });\n\t\t\t\t\ttokens.add(message.usage.cacheRead, { ...attributes, kind: \"cache_read\" });\n\t\t\t\t\ttokens.add(message.usage.cacheWrite, { ...attributes, kind: \"cache_write\" });\n\t\t\t\t\tcost.add(message.usage.cost.total, attributes);\n\t\t\t\t}\n\t\t\t}\n\t\t\tfinish();\n\t\t},\n\t};\n}\n"]}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { TelemetryContext } from "@earendil-works/pi-telemetry";
+import type { TelemetrySpan } from "@earendil-works/pi-telemetry";
 import type { AnthropicOptions } from "./api/anthropic-messages.ts";
 import type { AzureOpenAIResponsesOptions } from "./api/azure-openai-responses.ts";
 import type { BedrockOptions } from "./api/bedrock-converse-stream.ts";
@@ -9,11 +9,12 @@ import type { OpenAICodexResponsesOptions } from "./api/openai-codex-responses.t
 import type { OpenAICompletionsOptions } from "./api/openai-completions.ts";
 import type { OpenAIResponsesOptions } from "./api/openai-responses.ts";
 import type { PiMessagesOptions } from "./api/pi-messages.ts";
-import type { AnthropicMessagesCompat, BedrockCompat, MistralConversationsCompat, OpenAICompletionsCompat, OpenAIResponsesCompat } from "./providers/compat-schema.ts";
+import type { AnthropicMessagesCompat, BedrockCompat, MistralConversationsCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, SystemOneCompat } from "./providers/compat-schema.ts";
 import type { CacheRetention, ModelCost, ModelInputLimits, ModelInputModality, ModelPromptCache, ModelThinkingLevel, ThinkingLevel, ThinkingLevelMap } from "./providers/model-schema.ts";
 import type { AssistantMessageDiagnostic } from "./utils/diagnostics.ts";
 import type { AssistantMessageEventStream } from "./utils/event-stream.ts";
-export type { AnthropicAllowedFallbackModel, AnthropicMessagesCompat, BedrockCompat, ChatTemplateKwargValue, MistralConversationsCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, OpenRouterRouting, SessionAffinityFormat, ThinkingTokenBudgetField, VercelGatewayRouting, } from "./providers/compat-schema.ts";
+import type { ClientIdentity } from "./utils/identity.ts";
+export type { AnthropicAllowedFallbackModel, AnthropicMessagesCompat, BedrockCompat, ChatTemplateKwargValue, MistralConversationsCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, OpenRouterRouting, SessionAffinityFormat, SystemOneCompat, ThinkingTokenBudgetField, VercelGatewayRouting, } from "./providers/compat-schema.ts";
 export type { CacheRetention, ModelCost, ModelCostRates, ModelCostTier, ModelImageInputLimits, ModelImageResizeOptions, ModelInputLimits, ModelInputModality, ModelPromptCache, ModelThinkingLevel, ThinkingLevel, ThinkingLevelMap, } from "./providers/model-schema.ts";
 export type { AssistantMessageEventStream } from "./utils/event-stream.ts";
 export type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
@@ -46,8 +47,8 @@ export interface ProviderResponse {
 /** Authentication, HTTP transport, and lifecycle callbacks shared by provider requests. */
 export interface ProviderRequestOptions<TModel = Model<Api>> {
     signal?: AbortSignal;
-    /** Explicit parent context for telemetry produced by this logical request. */
-    telemetryContext?: TelemetryContext;
+    /** Explicit parent span for telemetry produced by this logical request. */
+    telemetry?: TelemetrySpan;
     apiKey?: string;
     /**
      * Optional fetch implementation for provider HTTP requests.
@@ -79,6 +80,11 @@ export interface ProviderRequestOptions<TModel = Model<Api>> {
      * A null value suppresses a provider/API default header with the same name.
      */
     headers?: ProviderHeaders;
+    /**
+     * How the request identifies the calling app: `User-Agent` and provider attribution headers.
+     * Absent fields use pi-ai's defaults: a detailed `User-Agent` and no attribution.
+     */
+    identity?: ClientIdentity;
     /**
      * HTTP request timeout in milliseconds for providers/SDKs that support it.
      * For example, OpenAI and Anthropic SDK clients default to 10 minutes.
@@ -291,11 +297,18 @@ export interface Usage {
     reasoning?: number;
     totalTokens: number;
     cost: {
+        /** Catalog-derived input cost. */
         input: number;
+        /** Catalog-derived output cost. */
         output: number;
+        /** Catalog-derived cache-read cost. */
         cacheRead: number;
+        /** Catalog-derived cache-write cost. */
         cacheWrite: number;
+        /** Best available total: provider-reported billed cost when supported, otherwise the catalog estimate. */
         total: number;
+        /** True when `total` is the billed cost reported by the provider. False when it is a catalog estimate; absent also means false. */
+        totalFromProvider?: boolean;
     };
 }
 export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
@@ -501,7 +514,6 @@ export interface ClassifierResult {
     errorMessage?: string;
     timestamp: number;
 }
-import type { TSchema } from "typebox";
 /** OpenAI grammar variants for constrained sampling. */
 export type GrammarFormat = "openai_lark" | "openai_regex";
 export type GrammarVariants = Partial<Record<GrammarFormat, string>>;
@@ -519,7 +531,11 @@ export type ConstrainedSamplingConfig = {
     type: "grammar";
     variants: GrammarVariants;
 };
-export interface Tool<TParameters extends TSchema = TSchema> {
+/**
+ * A tool the model may call. `parameters` is the JSON Schema of its arguments: pi-schema's builders (which also type
+ * the arguments, see `Static` in `@earendil-works/pi-schema`), TypeBox schemas, or any JSON Schema object.
+ */
+export interface Tool<TParameters extends object = object> {
     name: string;
     description: string;
     parameters: TParameters;
@@ -668,6 +684,8 @@ export interface ImageModel<TApi extends ImageApi> extends BaseModel<TApi> {
 export interface ClassifierModel<TApi extends ClassifierApi> extends BaseModel<TApi> {
     type: "classifier";
     contextWindow: number;
+    /** Compatibility overrides for System One APIs. If not set, auto-detected from provider, baseUrl, and id. */
+    compat?: TApi extends "typesafe-system-one" | "cloudflare-workers-ai-system-one" ? SystemOneCompat : never;
 }
 /** Model shape for each model type. */
 export interface ModelTypeMap {