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

package/dist/fingerprint.js

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+/**
+ * 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 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 const MAX_TOOL_DEPTH = 100;
+/** The first message is not `system` or `developer`, or there are no messages. */
+export const NO_INSTRUCTIONS = 'no_instructions';
+/** The leading instruction messages normalise to the empty string. */
+export const EMPTY_INSTRUCTIONS = 'empty_instructions';
+const SHINGLE_TOKENS = 8;
+const DIGEST_BYTES = 16;
+const MAX_PREFIX_SHINGLES = 512;
+const INSTRUCTION_ROLES = new Set(['system', 'developer']);
+// Unicode White_Space. The lookbehind anchors the match at the start of the run, so a long run stays linear.
+const TRAILING_SPACE = /(?<!\p{White_Space})\p{White_Space}+$/u;
+const SPACE_RUN = /\p{White_Space}+/u;
+// "abc "\n  "def", 'abc ' +\n 'def', f"abc "\\\n f"def": concatenation, so the halves join directly.
+const CONCAT_SEAM = /["'`][ \t]*(?:[+\\][ \t]*)?\n[ \t\n]*(?:\+[ \t]*)?[bfruBFRU]{0,2}["'`]/g;
+// "abc",\n  "def" inside an array: elements are joined by a separator at runtime, so a space.
+const ELEMENT_SEAM = /["'`][ \t]*,[ \t]*\n[ \t\n]*[bfruBFRU]{0,2}["'`]/g;
+const WHITESPACE_ESCAPE = /(?<!\\)\\+[ntr]/g;
+const QUOTE_ESCAPE = /(?<!\\)\\+(?=["'`])/g;
+const BACKSLASH_RUN = /\\{2,}/g;
+const QUOTE = /["'`]/g;
+/** A tool definition nested deeper than `MAX_TOOL_DEPTH`. */
+export 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 function normalise(text) {
+    return text
+        .normalize('NFC')
+        .replaceAll('\r\n', '\n')
+        .split('\n')
+        .map((line) => line.replace(TRAILING_SPACE, ''))
+        .join('\n')
+        .replace(TRAILING_SPACE, '');
+}
+/**
+ * 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 function prefixText(messages) {
+    const end = messages.findIndex((message) => !isRecord(message) || !INSTRUCTION_ROLES.has(message.role));
+    const leading = end === -1 ? messages : messages.slice(0, end);
+    if (leading.length === 0) {
+        return null;
+    }
+    return normalise(leading.map((message) => contentText(isRecord(message) ? message.content : undefined)).join('\n\n'));
+}
+/**
+ * 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 function prefixDigest(messages) {
+    return prefixTextDigest(prefixText(messages));
+}
+/**
+ * `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 function prefixTextDigest(text) {
+    if (text === null) {
+        return { digest: null, cause: NO_INSTRUCTIONS };
+    }
+    if (text === '') {
+        return { digest: null, cause: EMPTY_INSTRUCTIONS };
+    }
+    return { digest: sha256(text).toString('hex'), cause: null };
+}
+/**
+ * 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 function toolsetDigest(tools) {
+    if (tools.length === 0) {
+        return null;
+    }
+    const entries = tools.map((tool) => ({ name: toolName(tool), json: canonicalJson(tool, 0) }));
+    entries.sort((a, b) => compareCodeUnits(a.name, b.name) || compareCodeUnits(a.json, b.json));
+    return sha256(entries.map((entry) => entry.json).join('\n')).toString('hex');
+}
+/**
+ * 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 function shingleDigests(text) {
+    return windowDigests(tokens(text), MAX_PREFIX_SHINGLES);
+}
+function contentText(content) {
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return '';
+    }
+    return content
+        .flatMap((part) => (isRecord(part) && part.type === 'text' && typeof part.text === 'string' ? [part.text] : []))
+        .join('\n\n');
+}
+function toolName(tool) {
+    if (!isRecord(tool)) {
+        return '';
+    }
+    if (typeof tool.name === 'string') {
+        return tool.name;
+    }
+    const fn = tool.function;
+    return isRecord(fn) && typeof fn.name === 'string' ? fn.name : '';
+}
+// JSON.stringify already writes numbers as Number::toString, escapes lone surrogates (ES2019) and
+// leaves non-ASCII as is, which is exactly what the Python port reimplements by hand.
+function canonicalJson(value, depth) {
+    if (depth > MAX_TOOL_DEPTH) {
+        throw new ToolDepthExceeded(`tool definition nests deeper than ${String(MAX_TOOL_DEPTH)} levels`);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item, depth + 1)).join(',')}]`;
+    }
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort(compareCodeUnits);
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key], depth + 1)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * 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 function tokens(text) {
+    return normalise(text)
+        .replace(CONCAT_SEAM, '')
+        .replace(ELEMENT_SEAM, ' ')
+        .replace(WHITESPACE_ESCAPE, ' ')
+        .replace(QUOTE_ESCAPE, '')
+        .replace(BACKSLASH_RUN, '\\')
+        .replaceAll('{{', '{')
+        .replaceAll('}}', '}')
+        .replace(QUOTE, '')
+        .split(SPACE_RUN)
+        .filter((token) => token !== '');
+}
+/**
+ * 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 function windowDigests(words, cap) {
+    const digests = new Set();
+    for (let i = 0; i + SHINGLE_TOKENS <= words.length && digests.size < cap; i++) {
+        digests.add(sha256(words.slice(i, i + SHINGLE_TOKENS).join(' ')).subarray(0, DIGEST_BYTES).toString('hex'));
+    }
+    return [...digests];
+}
+// Node's UTF-8 encoder turns a lone surrogate into U+FFFD, which the Python port copies.
+function sha256(text) {
+    return createHash('sha256').update(text, 'utf8').digest();
+}
+function compareCodeUnits(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/gate.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The runtime gate: before an LLM span's first HTTP request leaves the process, ask Agent Watch
+ * whether the agent may make it (plan Q1, Q2, D7). An LLM span is one the processor reports
+ * (`isLlmSpan`), so a refused call is always reported as one; tool, agent and embedding spans
+ * are never gated.
+ *
+ * What it must never do:
+ * 1. Fail the call for any reason but a `block` answer. Every other outcome (slow, down, a status
+ *    that is not 2xx, a body it cannot read, a bug here) lets the call through and is counted as
+ *    a fail-open, reported on the next decision request for the same agent. There is no
+ *    fail-closed path and no switch for one.
+ * 2. Wait longer than `GATE_TIMEOUT_MILLIS`. A held answer costs no request at all, and neither
+ *    does a call after a fail-open: the agent is held at allow for a while (`FAIL_OPEN_HOLD_MILLIS`).
+ * 3. Send content. The request names the agent (the span name), the service, the model and the
+ *    deployment environment, and carries the counts it owes. Nothing from a message, tool or response.
+ *
+ * What it owes travels as one report batch per request (contract v2, AWT-335): the batch has a
+ * `report_id` and is sent again, unchanged, until a request carrying it is answered, so the
+ * platform writes it once however often it is resent. What is counted meanwhile waits for the
+ * next batch.
+ */
+/** The longest a call waits for an answer: the coding edge's `DEFAULT_ENFORCEMENT_TIMEOUT_MS`. */
+export declare const GATE_TIMEOUT_MILLIS = 300;
+/**
+ * How long a decision request may run after the call stopped waiting for it. Not cancelled at the
+ * gate timeout: a far-away gateway answers a cold request in more than 300 ms, and cancelling
+ * would throw the connection away and make every attempt cold. Its late answer is held.
+ */
+export declare const LATE_ANSWER_MILLIS = 5000;
+/** A `hold_ms` above this is held for this long: a stale refusal must not outlive a cap raise by much. */
+export declare const MAX_HOLD_MILLIS = 60000;
+/** How long a fail-open holds an allow: Agent Watch slow, down or failing. */
+export declare const FAIL_OPEN_HOLD_MILLIS = 30000;
+/** How long a 401, 403 or 404 holds an allow: the route is missing or the token lacks the scope. */
+export declare const FAIL_OPEN_AUTH_HOLD_MILLIS = 300000;
+/**
+ * Agents remembered at once; past it the least recently used one with nothing in flight and
+ * nothing owed is forgotten. One that owes reports is kept up to twice this many.
+ */
+export declare const MAX_AGENTS = 1000;
+/** Token endpoints a model call depends on (Vertex on a workload identity): never gated. */
+export declare const TOKEN_HOSTS: ReadonlySet<string>;
+/** Why a call went through without an answer. Values are core's `RuntimeFailOpenReason`. */
+export type FailOpenReason = 'timeout' | 'unreachable' | 'http_status' | 'unreadable' | 'internal';
+/** Who a decision is about. `null` fields are left out of the request. Held per agent and environment. */
+export interface DecisionSubject {
+    readonly agentName: string;
+    readonly serviceName: string | null;
+    readonly model: string | null;
+    readonly deploymentEnvironment: string | null;
+}
+type FetchInput = Parameters<typeof fetch>[0];
+type FetchInit = Parameters<typeof fetch>[1];
+/** Asks the decision route, holds its answers per agent, and gates `fetch` requests made inside LLM spans. */
+export declare class RuntimeGate {
+    private readonly endpoint;
+    private readonly agents;
+    private readonly spans;
+    /**
+     * Point the gate at a decision route.
+     * @param token SDK token scoped `ingest:production`.
+     * @param endpoint Ingest base URL; `v1/enforcement/runtime-decision` is joined onto it.
+     */
+    constructor(token: string, endpoint: string);
+    /**
+     * Whether this agent's next call is refused. Never rejects, and settles within the gate timeout.
+     * @param subject The agent and what is stated about it.
+     * @returns `true` to refuse the call.
+     */
+    check(subject: DecisionSubject): Promise<boolean>;
+    /**
+     * `fetch`, gated: the first request inside an LLM span waits for the span's decision; every
+     * later request in that span gets the same one. Anything else goes straight through.
+     * @param original The `fetch` this one replaced.
+     * @param input As `fetch`.
+     * @param init As `fetch`.
+     * @returns What `original` returns, or a rejection with `AgentWatchRefusal`, or with
+     *   `init.signal`'s reason when it aborts while the decision is awaited.
+     */
+    fetch(original: typeof fetch, input: FetchInput, init?: FetchInit): Promise<Response>;
+    /** Release the sockets. Uninstall it first: a closed gate is never consulted. */
+    close(): void;
+    private agentFor;
+    private evict;
+    private decisionFor;
+    private decide;
+}
+/**
+ * Make `gate` the one `globalThis.fetch` consults, until it is uninstalled. Wraps `fetch` once per
+ * process, however many processors or copies of this package register; the most recent live gate
+ * is the one consulted.
+ * @param gate The gate to consult.
+ */
+export declare function installGate(gate: RuntimeGate): void;
+/**
+ * Stop consulting `gate`; the gate installed before it, if still live, is consulted again. `fetch`
+ * stays wrapped and passes through once no gate is live.
+ * @param gate The gate being shut down.
+ */
+export declare function uninstallGate(gate: RuntimeGate): void;
+/**
+ * The fallback for calls the gate does not see (`node:http`, gRPC, other transports): await it
+ * before the call. Resolves at once when no processor is registered.
+ * @param agentName The agent the call is charged to, as the span would name it.
+ * @returns When the call may go ahead.
+ * @throws {AgentWatchRefusal} When an Agent Watch budget refuses it.
+ */
+export declare function guard(agentName: string): Promise<void>;
+export {};