@agent-watch-ai/otel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentWatch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# @agent-watch-ai/otel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Your production LLM spend in Agent Watch, hashed in your own process, and over-budget calls refused before they leave it.**
+
+One line beside your OpenTelemetry setup. Prompt text, tool definitions and arguments, and model
+responses never leave the process — only digests, token counts and ids do. Your own processors and
+exporters keep receiving everything, unchanged. The Node twin of the Python `agent-watch-otel`: the
+same span produces the same payload in both.
+
+```sh
+npm install @agent-watch-ai/otel
+```
+
+```ts
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { AgentWatchSpanProcessor } from '@agent-watch-ai/otel';
+
+const provider = new NodeTracerProvider({
+  spanProcessors: [yourProcessor, new AgentWatchSpanProcessor()] // beside yours
+});
+```
+
+The token is an Agent Watch SDK token scoped `ingest:production`. `token` and `endpoint` come from
+the options or from `AGENT_WATCH_TOKEN` and `AGENT_WATCH_ENDPOINT`. `OTEL_*` is never read: it
+belongs to your exporter.
+
+---
+
+## What it sends
+
+Finished spans whose `openinference.span.kind` is `LLM`, and nothing else. Per call:
+
+| Sent | Not sent |
+|---|---|
+| sha256 of the system/developer prefix, and its 8-token window digests | the prompt |
+| sha256 of the tool definitions | the tool definitions, and every tool argument |
+| model, provider, token counts (input, output, cache read/write, reasoning) | the response |
+| span id, trace id, span name, end time | anything the span carries that is not in this table |
+| `service.name` and `service.version` from the OTel resource | |
+
+Before a model call, the gate sends a decision request (see "Refusing over-budget calls"). It
+carries the span name, `service.name`, the model and the deployment environment, plus counts of
+local refusals and fail-opens. Never prompt text, tool definitions or responses.
+
+Digests are computed in `onEnd`, inside your `span.end()`, before anything is queued. The queue
+holds hashes.
+
+## What it does to your application
+
+- **`onEnd` never touches the network.** It hashes and enqueues. Requests start from an unref'd
+  timer, one batch of at most 100 calls at a time (under 2 MB of JSON per request).
+- **Its own request is invisible to your instrumentation.** The POST is sent with OpenTelemetry
+  tracing suppressed, so HTTP instrumentation neither traces it nor injects trace headers.
+- **`onEnd` never throws, and nothing it starts rejects unhandled.** A bug here costs you a cost
+  record, never a request, and never an `unhandledRejection` crash.
+- **The queue is bounded.** When Agent Watch is unreachable or slow, calls are dropped and counted
+  rather than buffered without limit inside your process. A queued call is at most about 18 KB
+  (512 shingle digests), so the default `maxQueue` of 512 holds at most about 9 MB of payload.
+- **It never holds your process open.** Its timer and its request's socket are unref'd: a process
+  whose own work is done exits without waiting on a slow ingest. `shutdown()` is bounded by
+  `shutdownMillis` however many times it is called; a request still in flight when the budget
+  runs out is aborted. While you await `forceFlush()` or `shutdown()` the request is held open
+  (each bounded by its timeout), so a short job that ends with `await provider.forceFlush()`
+  delivers its last batch before it exits.
+- **The token never crosses a network in clear.** The endpoint must be `https`; plain `http` is
+  accepted only on loopback (`localhost`, `127.0.0.0/8`, `::1`) and anything else throws at
+  construction.
+
+```ts
+processor.stats();
+// { sent: 412, droppedQueueFull: 0, droppedSendFailed: 3, droppedNoModel: 0, droppedError: 0 }
+```
+
+A call with no `llm.model_name` and no `llm.model` is counted under `droppedNoModel` rather than
+sent under a guessed model. Failed batches are dropped, not retried. Warnings go to the
+OpenTelemetry `diag` logger, so they appear only if you configured one.
+
+## Refusing over-budget calls
+
+When a feature's production budget is spent, the agent's next model call is refused before it
+leaves your process. Registering the processor wraps `globalThis.fetch`. The first request made
+inside an LLM span (`openinference.span.kind = LLM`, the spans this processor reports) asks Agent
+Watch about the agent the span names. Tool, agent and embedding spans, and spans that only set
+`gen_ai.operation.name`, are never gated. A refused call fails with:
+
+```
+AgentWatchRefusal: An Agent Watch budget refused this call.
+```
+
+It names no cap, amount, feature or policy, and `retryable` is `false`: a retry gets the same
+answer from the held decision, with no request to Agent Watch or to the provider. Provider SDKs
+that wrap transport errors (OpenAI, Anthropic) raise their own connection error with the refusal
+as its `cause`, and may retry with their own backoff first. Test for it with `isAgentWatchRefusal`:
+
+```ts
+import { isAgentWatchRefusal } from '@agent-watch-ai/otel';
+
+try {
+  await client.chat.completions.create(request);
+} catch (err) {
+  if (isAgentWatchRefusal(err)) return budgetSpentAnswer();
+  throw err;
+}
+```
+
+**The cost.** Answers are held per agent and deployment environment for as long as Agent Watch
+says (at most 60 s); a held answer adds no request. A fresh one waits at most 300 ms, with one
+request per agent in flight at a time: concurrent calls for the same agent wait on that one
+request. While it waits, the decision request keeps the process alive, so a script whose only
+work is that model call still makes it. A request still unanswered at 300 ms is not cancelled:
+the call goes ahead as a fail-open, the request runs on in the background (at most 5 s, never
+holding the process open), and its answer is held for the agent's next calls. So a gateway far
+away, slower than 300 ms on a cold connection, still gets to refuse. An abort of the call's
+`signal` (in `init`, or on a `Request` passed in) while it waits rejects at once with the abort
+reason.
+
+**Register the processor before you create provider clients.** The gate sees only requests made
+through `globalThis.fetch` as it is after the processor is constructed. A client that keeps its
+own reference to `fetch`, taken when the client was created, bypasses the gate if it was created
+first: construct `AgentWatchSpanProcessor` in your tracing setup, before any module creates an
+OpenAI or Anthropic client. SDK versions that do not use the global `fetch` at all (OpenAI's v4
+SDK on Node defaults to `node-fetch`) are never gated that way: pass `fetch: globalThis.fetch` in
+the client options, or await `guard(agentName)` before each call. Such calls are not counted as
+fail-opens either, since the gate never saw them.
+
+**Which agent.** The agent is the span name. OpenInference's OpenAI instrumentation names every
+span `ChatCompletion`, so all such calls are one agent unless you name the span yourself (wrap the
+call in a span named for the agent, or rename it).
+
+**Fail-open, always.** If Agent Watch is slow, unreachable, answers anything but 2xx, or answers
+something it cannot read, the call goes ahead, and the fail-open is reported on the next decision
+request for that agent. What is owed travels as one batch with a `report_id`, resent unchanged
+until a request carrying it is answered, so Agent Watch records it once. After a fail-open the agent is allowed without asking for 30 s, or for
+5 minutes after a 401, 403 or 404 (the route is missing or the token lacks the scope); each call
+let through meanwhile is counted as a fail-open too. There is no fail-closed mode and no switch
+for one. Nothing inside the
+package reaches your application as anything but the refusal.
+
+**What passes ungated.** Requests outside an LLM span; requests to `metadata.google.internal`,
+`oauth2.googleapis.com` and `sts.googleapis.com`, so a workload-identity token fetch is never
+refused; and the package's own requests. A refused call is still reported, with `refused: true`,
+and counts no spend.
+
+**Known limit: sampled-out spans are never gated.** A span your sampler drops carries no name or
+attributes, so a call inside it goes ahead unjudged and is not counted anywhere. Keep LLM spans
+sampled (a parent-based sampler that always records LLM spans, or sample everything) wherever you
+rely on the gate.
+
+**Other transports.** `node:http`, gRPC and other HTTP clients are not intercepted. Await
+`guard(agentName)` before such a call; it throws `AgentWatchRefusal` when refused, and resolves at
+once when no processor is registered. It states the agent and the deployment environment from
+`OTEL_RESOURCE_ATTRIBUTES`; with neither environment key set there, it is judged as production.
+
+**Dev and CI.** Set the resource attribute `deployment.environment.name` (or the older
+`deployment.environment`, read when the first is unset) to anything but `production` or `prod`
+and calls are allowed without judging; unset, they are judged as production.
+
+## Options
+
+| Option | Default | What it is |
+|---|---|---|
+| `token` | `$AGENT_WATCH_TOKEN` | SDK token scoped `ingest:production` |
+| `endpoint` | `$AGENT_WATCH_ENDPOINT` | Ingest base URL; the route `v1/runtime/calls` is joined onto it |
+| `instanceId` | the resource's `service.name` | This deployment's name, as you know it |
+| `maxQueue` | 512 | Calls held while the sender is behind; a positive integer |
+| `flushMillis` | 5000 | How long a partial batch waits, in (0, 2^31-1] |
+| `timeoutMillis` | 10000 | Network timeout for one POST |
+| `shutdownMillis` | 3000 | The whole budget `shutdown()` may spend, across every call |
+
+A missing token or endpoint throws at construction — on your startup path, where a
+misconfiguration is visible — never later from `onEnd`. Any other invalid number falls back to
+its default rather than throwing.
+
+## Requirements
+
+Node 20.19+ or 22.12+, with `@opentelemetry/api` 1.9+ and `@opentelemetry/sdk-trace-base` 1.x or
+2.x (types only) as peer dependencies. The package is ESM only; those Node versions load it from
+CommonJS too, through `require()` of ES modules, so there is no second CommonJS build to keep in
+step. No other dependency, by policy: this code runs inside your application.
+
+## Development
+
+```sh
+npm ci                     # at the repository root: TypeScript, vitest and ESLint come from there
+cd node/agent-watch-otel && npm ci
+npm run typecheck && npm run lint && npm test
+npx vitest run tests/fingerprint-vectors.test.ts tests/call-vectors.test.ts tests/gate-conformance.test.ts   # parity with Python
+```
+
+`conformance/runtime/gate-cases.json` is the gate's behaviour (gateway answers in, outcomes out),
+replayed by `tests/gate-conformance.test.ts` and by the Python package.
+
+Both parity files live in `conformance/runtime/` at the repository root and are read in place by
+this package and the Python one. `fingerprint-vectors.json` is a byte copy of core's golden
+fingerprint vectors (scheme 1); `call-vectors.json` is generated from the Python `build_call` by
+`generate_call_vectors.py`. Neither is edited to make a test pass.
+
+`scripts/system-check.mjs` posts one real span to a running ingestion gateway and prints its verdict.
+
+## Licence
+
+MIT.

package/dist/call.d.ts

@@ -0,0 +1,51 @@
+import type { Attributes, AttributeValue } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+/**
+ * One finished LLM span in, one `runtime.call` out: digests, token counts, ids and timestamps.
+ *
+ * The confidentiality boundary of the package. Prompt text, tool definitions and responses are
+ * read here, hashed here and left here; nothing returned holds a message body. A port of
+ * `python/agent-watch-otel/agent_watch_otel/call.py`, held to it by `conformance/runtime/call-vectors.json`.
+ */
+/** The platform enum member for a customer-run span processor (AWT-70). */
+export declare const PLATFORM = "otel_processor";
+/** What `buildCall` reads from a span: a subset of the SDK's `ReadableSpan`. */
+export type CallSpan = Pick<ReadableSpan, 'name' | 'attributes' | 'endTime' | 'spanContext'> & {
+    readonly resource?: {
+        readonly attributes: Attributes;
+    };
+};
+/** The `runtime.call` payload. Strict on the gateway: no key outside this shape is ever sent. */
+export type RuntimeCall = Readonly<Record<string, string | number | boolean | readonly string[]>>;
+/** Set to `true` by the runtime gate on a span whose call it refused. */
+export declare const REFUSED_ATTRIBUTE = "agent_watch.refused";
+/**
+ * Whether the processor reports this span.
+ * @param span Any finished span.
+ * @returns `true` when its OpenInference kind is `LLM`.
+ */
+export declare function isLlmSpan(span: Pick<ReadableSpan, 'attributes'>): boolean;
+/**
+ * Turn a finished LLM span into the `runtime.call` the ingest route accepts.
+ * @param span A finished span whose OpenInference kind is `LLM`.
+ * @param instanceId The tenant's name for this deployment; empty falls back to `service.name`.
+ * @returns The payload, or `null` when the span names no model: unpriceable spend is counted as
+ *   dropped rather than sent under a guess. A refused call has no spend, so it is sent as model `unknown`.
+ * @throws Only on a bug; the processor counts it as `dropped_error`.
+ */
+export declare function buildCall(span: CallSpan, instanceId: string): RuntimeCall | null;
+/**
+ * The resource's `service.name`, unless it is the SDK's `unknown_service[:<process>]` placeholder,
+ * which would put a fictional service on the connection page.
+ * @param value The resource attribute.
+ * @returns The storable name, or `null`.
+ */
+export declare function reportedService(value: AttributeValue | undefined): string | null;
+/**
+ * Trimmed, length-capped, and free of anything the gateway would refuse. One bad code point in
+ * one span name is a 400 for the whole batch, which would cost every other call in it.
+ * @param value Any attribute value; anything but a string reads as absent.
+ * @param limit The contract's maximum length for this field, in UTF-16 units.
+ * @returns The storable text, or `null` when nothing is left of it.
+ */
+export declare function storable(value: unknown, limit: number): string | null;

package/dist/call.js

@@ -0,0 +1,289 @@
+import { EMPTY_INSTRUCTIONS, NO_INSTRUCTIONS, ToolDepthExceeded, prefixText, prefixTextDigest, shingleDigests, toolsetDigest } from './fingerprint.js';
+/**
+ * One finished LLM span in, one `runtime.call` out: digests, token counts, ids and timestamps.
+ *
+ * The confidentiality boundary of the package. Prompt text, tool definitions and responses are
+ * read here, hashed here and left here; nothing returned holds a message body. A port of
+ * `python/agent-watch-otel/agent_watch_otel/call.py`, held to it by `conformance/runtime/call-vectors.json`.
+ */
+/** The platform enum member for a customer-run span processor (AWT-70). */
+export const PLATFORM = 'otel_processor';
+/** Set to `true` by the runtime gate on a span whose call it refused. */
+export const REFUSED_ATTRIBUTE = 'agent_watch.refused';
+const SPAN_KIND = 'openinference.span.kind';
+const LLM_KIND = 'LLM';
+// The model a refused call is reported under when its span names none: the contract requires one.
+const UNKNOWN_MODEL = 'unknown';
+const AGENT_NAME_MAX = 200;
+const ID_MAX = 200;
+const TOKEN_MAX = 1_000_000_000;
+const INPUT_HIDDEN = 'input_hidden';
+const TOOLS_UNPARSED = 'tools_unparsed';
+const GEN_AI_TOOLS = 'gen_ai.tool.definitions';
+const MESSAGE_ROLE = /^llm\.input_messages\.(\d+)\.message\.role$/;
+const MESSAGE_PART = /^llm\.input_messages\.(\d+)\.message\.contents\.(\d+)\.message_content\.type$/;
+const INSTRUCTION_ROLES = new Set(['system', 'developer']);
+const TOOL_SCHEMA = /^llm\.tools\.(\d+)\.tool\.json_schema$/;
+// Control, unassigned and surrogate code points: Postgres cannot store them or the contract refuses them.
+const UNSTORABLE = /[\p{Cc}\p{Cn}\p{Cs}]/gu;
+// Python's str.strip(): Unicode White_Space plus U+001C..U+001F. Not String.prototype.trim, which
+// also strips U+FEFF and would send a different agent name than the Python package for one span.
+// Tested one UTF-16 unit at a time from each end, never as an anchored `[...]+$` regex: that
+// one retries the run from every position and goes quadratic on a long run of spaces, inside
+// the customer's span.end(). Every such character is in the BMP, so a unit scan is exact.
+// eslint-disable-next-line no-control-regex -- U+001C..U+001F are exactly what Python's strip() adds.
+const EDGE_SPACE = /^[\p{White_Space}\x1c-\x1f]$/u;
+/**
+ * Whether the processor reports this span.
+ * @param span Any finished span.
+ * @returns `true` when its OpenInference kind is `LLM`.
+ */
+export function isLlmSpan(span) {
+    return span.attributes[SPAN_KIND] === LLM_KIND;
+}
+/**
+ * Turn a finished LLM span into the `runtime.call` the ingest route accepts.
+ * @param span A finished span whose OpenInference kind is `LLM`.
+ * @param instanceId The tenant's name for this deployment; empty falls back to `service.name`.
+ * @returns The payload, or `null` when the span names no model: unpriceable spend is counted as
+ *   dropped rather than sent under a guess. A refused call has no spend, so it is sent as model `unknown`.
+ * @throws Only on a bug; the processor counts it as `dropped_error`.
+ */
+export function buildCall(span, instanceId) {
+    const attributes = span.attributes;
+    const refused = attributes[REFUSED_ATTRIBUTE] === true;
+    const model = storable(firstString(attributes, 'llm.model_name', 'llm.model', 'gen_ai.request.model'), ID_MAX) ?? (refused ? UNKNOWN_MODEL : null);
+    if (model === null) {
+        return null;
+    }
+    const resource = span.resource?.attributes ?? {};
+    const serviceName = reportedService(resource['service.name']);
+    const context = span.spanContext();
+    return {
+        type: 'runtime.call',
+        platform: PLATFORM,
+        instance_id: storable(instanceId, ID_MAX) ?? serviceName ?? PLATFORM,
+        external_id: context.spanId,
+        occurred_at: isoInstant(span.endTime),
+        agent_name: storable(span.name, AGENT_NAME_MAX) ?? 'unnamed',
+        trace_id: context.traceId,
+        provider: storable(firstString(attributes, 'llm.provider', 'llm.system'), ID_MAX) ?? 'unknown',
+        model,
+        input_tokens: tokenCount(attributes['llm.token_count.prompt']) ?? 0,
+        output_tokens: tokenCount(attributes['llm.token_count.completion']) ?? 0,
+        ...present('cache_read_tokens', tokenCount(attributes['llm.token_count.prompt_details.cache_read'])),
+        ...present('cache_write_tokens', tokenCount(attributes['llm.token_count.prompt_details.cache_write'])),
+        ...present('reasoning_tokens', tokenCount(attributes['llm.token_count.completion_details.reasoning'])),
+        ...present('service_name', serviceName),
+        ...present('service_version', storable(resource['service.version'], ID_MAX)),
+        ...fingerprintFields(attributes),
+        // The gate refused this call before it reached a provider: a call, but no spend (AWT-336).
+        // Last, so every call the gate let through keeps the shared vectors' key order.
+        ...(refused ? { refused: true } : {})
+    };
+}
+// The contract allows a prefix digest beside tools_unparsed, never a digest beside its own
+// absence cause, so the prefix's cause wins when there is one.
+function fingerprintFields(attributes) {
+    const messages = leadingInstructions(attributes);
+    const { tools, parsed } = toolDefinitions(attributes);
+    const toolset = parsed ? boundedToolset(tools) : null;
+    const toolsetField = present('toolset_sha256', toolset);
+    // Masked input does not mask the tools: half a fingerprint beats none.
+    if (messages === null) {
+        return { ...toolsetField, uncovered_cause: INPUT_HIDDEN };
+    }
+    const text = prefixText(messages);
+    const prefix = prefixTextDigest(text);
+    const shingles = prefix.digest === null || text === null ? [] : shingleDigests(text);
+    const prefixCause = prefix.cause === NO_INSTRUCTIONS || prefix.cause === EMPTY_INSTRUCTIONS ? prefix.cause : null;
+    const toolsCause = !parsed || (tools.length > 0 && toolset === null) ? TOOLS_UNPARSED : null;
+    return {
+        ...toolsetField,
+        ...present('prefix_sha256', prefix.digest),
+        // Omitted rather than sent empty: a prompt under eight tokens has no windows.
+        ...(shingles.length > 0 ? { prefix_shingles_sha256: shingles } : {}),
+        ...present('uncovered_cause', prefixCause ?? toolsCause)
+    };
+}
+// An over-deep definition is reported as unparsed rather than hashed, exactly as in Python.
+function boundedToolset(tools) {
+    try {
+        return toolsetDigest(tools);
+    }
+    catch (error) {
+        if (error instanceof ToolDepthExceeded) {
+            return null;
+        }
+        throw error;
+    }
+}
+// One pass over the attributes, bucketed by message index. `null` when there are no messages
+// at all; otherwise the messages in order up to and including the first that is not an
+// instruction. Content is built only for the ones `prefixText` reads: the leading run.
+function leadingInstructions(attributes) {
+    const byIndex = new Map();
+    const bucket = (index) => {
+        let message = byIndex.get(index);
+        if (message === undefined) {
+            message = { role: undefined, parts: [] };
+            byIndex.set(index, message);
+        }
+        return message;
+    };
+    const roles = new Set();
+    for (const [key, value] of Object.entries(attributes)) {
+        const role = MESSAGE_ROLE.exec(key);
+        if (role !== null) {
+            const index = Number(role[1]);
+            bucket(index).role = value;
+            roles.add(index);
+            continue;
+        }
+        const part = MESSAGE_PART.exec(key);
+        if (part !== null && value === 'text') {
+            bucket(Number(part[1])).parts.push([Number(part[2]), key]);
+        }
+    }
+    if (roles.size === 0) {
+        return null;
+    }
+    const leading = [];
+    for (const index of [...roles].sort((a, b) => a - b)) {
+        const message = byIndex.get(index);
+        const role = message?.role;
+        if (!INSTRUCTION_ROLES.has(role)) {
+            // Its content is never read: `prefixText` stops at the first message that is not an instruction.
+            leading.push({ role, content: undefined });
+            break;
+        }
+        leading.push({ role, content: messageContent(attributes, index, message?.parts ?? []) });
+    }
+    return leading;
+}
+// The flat string, else the message's `contents.N` text parts in order.
+function messageContent(attributes, index, parts) {
+    const flat = attributes[`llm.input_messages.${String(index)}.message.content`];
+    if (typeof flat === 'string') {
+        return flat;
+    }
+    const texts = [];
+    for (const [part, typeKey] of parts) {
+        const text = attributes[`${typeKey.slice(0, -'type'.length)}text`];
+        if (typeof text === 'string') {
+            texts.push([part, { type: 'text', text }]);
+        }
+    }
+    return texts.sort((a, b) => a[0] - b[0]).map(([, part]) => part);
+}
+// `llm.tools.N.tool.json_schema` first; Phoenix leaves `gen_ai.tool.definitions` unconverted, so
+// that is read too. `parsed: false` means tools were there in a shape nothing parsed, which is
+// not the same as no tools.
+function toolDefinitions(attributes) {
+    const indexed = [];
+    for (const [key, value] of Object.entries(attributes)) {
+        const match = TOOL_SCHEMA.exec(key);
+        if (match !== null && typeof value === 'string') {
+            indexed.push([Number(match[1]), value]);
+        }
+    }
+    if (indexed.length > 0) {
+        const loaded = indexed.sort((a, b) => a[0] - b[0]).map(([, schema]) => parseJson(schema));
+        return { tools: loaded.filter((tool) => tool !== null), parsed: loaded.every((tool) => tool !== null) };
+    }
+    const raw = attributes[GEN_AI_TOOLS];
+    if (typeof raw !== 'string') {
+        return { tools: [], parsed: true };
+    }
+    const parsed = parseJson(raw);
+    if (parsed === null) {
+        return { tools: [], parsed: false };
+    }
+    return { tools: Array.isArray(parsed) ? parsed : [parsed], parsed: true };
+}
+// `null` for anything that is not JSON, and for the JSON literal `null`, as Python's `None` is both.
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function firstString(attributes, ...keys) {
+    for (const key of keys) {
+        const value = attributes[key];
+        if (typeof value === 'string' && trimEdges(value) !== '') {
+            return value;
+        }
+    }
+    return null;
+}
+// A count clamped into the contract's range. Non-finite reads as absent: Python's int() raises
+// there and the call is dropped, and sending zero is the better of the two answers.
+function tokenCount(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return Math.max(0, Math.min(TOKEN_MAX, Math.trunc(value)));
+}
+/**
+ * The resource's `service.name`, unless it is the SDK's `unknown_service[:<process>]` placeholder,
+ * which would put a fictional service on the connection page.
+ * @param value The resource attribute.
+ * @returns The storable name, or `null`.
+ */
+export function reportedService(value) {
+    const name = storable(value, ID_MAX);
+    return name === null || name.split(':')[0] === 'unknown_service' ? null : name;
+}
+/**
+ * Trimmed, length-capped, and free of anything the gateway would refuse. One bad code point in
+ * one span name is a 400 for the whole batch, which would cost every other call in it.
+ * @param value Any attribute value; anything but a string reads as absent.
+ * @param limit The contract's maximum length for this field, in UTF-16 units.
+ * @returns The storable text, or `null` when nothing is left of it.
+ */
+export function storable(value, limit) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const kept = trimEdges(capUtf16(trimEdges(value.replace(UNSTORABLE, '')), limit));
+    return kept === '' ? null : kept;
+}
+// Python's str.strip(), linear in the length however long the runs of space are.
+function trimEdges(text) {
+    let start = 0;
+    let end = text.length;
+    while (start < end && EDGE_SPACE.test(text.charAt(start))) {
+        start++;
+    }
+    while (end > start && EDGE_SPACE.test(text.charAt(end - 1))) {
+        end--;
+    }
+    return start === 0 && end === text.length ? text : text.slice(start, end);
+}
+// String.length is already UTF-16 units, which is what zod's .max() counts. Whole code points are
+// copied, so a surrogate pair is never split.
+function capUtf16(text, limit) {
+    if (text.length <= limit) {
+        return text;
+    }
+    let kept = '';
+    for (const char of text) {
+        if (kept.length + char.length > limit) {
+            break;
+        }
+        kept += char;
+    }
+    return kept;
+}
+// An ISO-8601 instant with an explicit offset, millisecond precision, truncated not rounded: the
+// same text Python's isoformat(timespec="milliseconds") writes.
+function isoInstant([seconds, nanos]) {
+    return `${new Date(seconds * 1000 + Math.floor(nanos / 1_000_000)).toISOString().slice(0, 23)}+00:00`;
+}
+// The schema refuses null, so an optional field is either set or absent.
+function present(key, value) {
+    return value === null ? {} : { [key]: value };
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A Node port of `@agent-watch/fingerprint` scheme 1, digest for digest with the Python port.
+ *
+ * Copied from agent-watch-core `packages/fingerprint/src/fingerprint.ts` at 207ba472, the commit
+ * `conformance/runtime/fingerprint-vectors.json` was cut from, with one addition: the
+ * `MAX_TOOL_DEPTH` bound the Python port states, so an over-deep tool definition is refused at
+ * the same depth in both ports instead of at whatever depth the stack runs out.
+ */
+/** Names the rules in the shared vectors. Digests from different schemes never compare. */
+export declare const FINGERPRINT_SCHEME = "agent-watch-fingerprint/1";
+/** How deep a tool definition may nest before canonical JSON refuses it. Python holds the same number. */
+export declare const MAX_TOOL_DEPTH = 100;
+/** The first message is not `system` or `developer`, or there are no messages. */
+export declare const NO_INSTRUCTIONS = "no_instructions";
+/** The leading instruction messages normalise to the empty string. */
+export declare const EMPTY_INSTRUCTIONS = "empty_instructions";
+export type PrefixCause = typeof NO_INSTRUCTIONS | typeof EMPTY_INSTRUCTIONS;
+export type PrefixDigest = {
+    readonly digest: string;
+    readonly cause: null;
+} | {
+    readonly digest: null;
+    readonly cause: PrefixCause;
+};
+/** A tool definition nested deeper than `MAX_TOOL_DEPTH`. */
+export declare class ToolDepthExceeded extends RangeError {
+}
+/**
+ * NFC, CRLF to LF, trailing whitespace off every line and off the end. Never lowercases.
+ * @param text Prompt or source text as the platform stored it.
+ * @returns The text every digest here is taken over.
+ */
+export declare function normalise(text: string): string;
+/**
+ * The normalised leading `system`/`developer` run, joined by a blank line. Producers shingle
+ * exactly this text; any other join changes the shingles.
+ * @param messages Messages in order, in whatever shape the platform stored them.
+ * @returns The prefix text, or `null` when the first message is not an instruction.
+ */
+export declare function prefixText(messages: readonly unknown[]): string | null;
+/**
+ * sha256 hex of `prefixText`, or the reason there is none.
+ * @param messages Messages in order.
+ * @returns The digest with a `null` cause, or a `null` digest with its cause.
+ */
+export declare function prefixDigest(messages: readonly unknown[]): PrefixDigest;
+/**
+ * `prefixDigest` from text `prefixText` already returned, so a caller that also shingles it
+ * builds the text once.
+ * @param text `prefixText`'s output.
+ * @returns The digest with a `null` cause, or a `null` digest with its cause.
+ */
+export declare function prefixTextDigest(text: string | null): PrefixDigest;
+/**
+ * sha256 hex of the tool definitions as canonical JSON, sorted by (name, JSON) and newline-joined.
+ * @param tools Tool definitions as parsed JSON, OpenAI (`function.name`) or Anthropic (`name`) shape.
+ * @returns 64 hex characters, or `null` when there are no tools.
+ * @throws {ToolDepthExceeded} A definition nests past `MAX_TOOL_DEPTH`.
+ */
+export declare function toolsetDigest(tools: readonly unknown[]): string | null;
+/**
+ * 16-byte hex digests of every 8-token window, deduplicated in order, at most 512.
+ * @param text Prompt text, normally `prefixText`'s output.
+ * @returns Up to 512 digests of 32 hex characters each.
+ */
+export declare function shingleDigests(text: string): string[];
+/**
+ * The words a window is taken over. Exported for the source-file runner in the tests.
+ * @param text Prompt or source text.
+ * @returns Its tokens in order.
+ */
+export declare function tokens(text: string): string[];
+/**
+ * 16-byte hex digests of every 8-token window, deduplicated in order.
+ * @param words `tokens`' output.
+ * @param cap At most this many digests.
+ * @returns The digests.
+ */
+export declare function windowDigests(words: readonly string[], cap: number): string[];