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

package/dist/gate.js

@@ -0,0 +1,498 @@
+import { randomUUID } from 'node:crypto';
+import { trace } from '@opentelemetry/api';
+import { REFUSED_ATTRIBUTE, isLlmSpan, reportedService, storable } from './call.js';
+import { BodyTooLarge, Endpoint } from './post.js';
+import { AgentWatchRefusal } from './refusal.js';
+/**
+ * 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 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 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 const MAX_HOLD_MILLIS = 60_000;
+/** How long a fail-open holds an allow: Agent Watch slow, down or failing. */
+export const FAIL_OPEN_HOLD_MILLIS = 30_000;
+/** How long a 401, 403 or 404 holds an allow: the route is missing or the token lacks the scope. */
+export const FAIL_OPEN_AUTH_HOLD_MILLIS = 300_000;
+/**
+ * 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 const MAX_AGENTS = 1000;
+/** Token endpoints a model call depends on (Vertex on a workload identity): never gated. */
+export const TOKEN_HOSTS = new Set(['metadata.google.internal', 'oauth2.googleapis.com', 'sts.googleapis.com']);
+const DECISION_PATH = 'v1/enforcement/runtime-decision';
+const ID_MAX = 200;
+const MAX_AGENTS_OWING = 2 * MAX_AGENTS;
+const AUTH_STATUSES = new Set([401, 403, 404]);
+// An answer is two short fields; anything longer is not one.
+const MAX_ANSWER_BYTES = 4096;
+// The contract's ceiling on a reported count.
+const REPORT_COUNT_MAX = 1_000_000_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+class AnswerError extends Error {
+    reason;
+    holdMillis;
+    late;
+    // `late`: on a timeout, the request still running, whose answer may yet be held.
+    constructor(reason, holdMillis = FAIL_OPEN_HOLD_MILLIS, late) {
+        super(reason);
+        this.reason = reason;
+        this.holdMillis = holdMillis;
+        this.late = late;
+    }
+}
+// A count, clamped to the contract's ceiling.
+function cap(count) {
+    return Math.min(REPORT_COUNT_MAX, count);
+}
+// One report batch: refusals answered here without asking, the feature they were answered from,
+// and fail-opens per reason. Its id is drawn once, so a resent batch carries the same one.
+class Reports {
+    id = randomUUID();
+    refused = 0;
+    featureId = null;
+    failOpens = new Map();
+    get empty() {
+        return this.refused === 0 && this.failOpens.size === 0;
+    }
+    // Refusals from blocks on different features never share a batch in practice (a batch is sent
+    // before the next answer); if they ever did, they are reported on no feature rather than a wrong one.
+    refuse(featureId) {
+        this.featureId = this.refused === 0 || this.featureId === featureId ? featureId : null;
+        this.refused = cap(this.refused + 1);
+    }
+    failOpen(reason) {
+        const at = new Date().toISOString();
+        const prior = this.failOpens.get(reason);
+        // `last_at` never precedes `first_at` (a 400) when the wall clock steps back.
+        this.failOpens.set(reason, prior === undefined
+            ? { count: 1, first_at: at, last_at: at }
+            : { count: cap(prior.count + 1), first_at: prior.first_at, last_at: at < prior.first_at ? prior.first_at : at });
+    }
+    fields() {
+        if (this.empty) {
+            return {};
+        }
+        const failOpens = [...this.failOpens].map(([reason, report]) => ({ reason, ...report }));
+        return {
+            report_id: this.id,
+            ...(this.refused > 0 ? { refused_since_last: this.refused } : {}),
+            ...(this.refused > 0 && this.featureId !== null ? { refused_feature_id: this.featureId } : {}),
+            ...(failOpens.length > 0 ? { fail_opens: failOpens } : {})
+        };
+    }
+}
+// One agent's held answer, its single request in flight, and what it owes. A hold set by a
+// fail-open allows, and counts each call it lets through as one more fail-open.
+class AgentGate {
+    answer;
+    held = null;
+    flight = null;
+    // The batch sent and not yet answered, resent as it is until it is.
+    sending = null;
+    // What is counted meanwhile: the next batch.
+    reports = new Reports();
+    // Bumped per request, so a late answer never overrides a newer one.
+    asked = 0;
+    constructor(answer) {
+        this.answer = answer;
+    }
+    // Whether forgetting it would lose a request in flight or reports owed.
+    get busy() {
+        return this.flight !== null;
+    }
+    get owes() {
+        return this.sending !== null || !this.reports.empty;
+    }
+    // `true` refuses the call. Never rejects.
+    async check(subject) {
+        try {
+            const held = this.held;
+            if (held !== null && held.until > Date.now()) {
+                if (held.failOpen !== undefined) {
+                    this.reports.failOpen(held.failOpen);
+                    return false;
+                }
+                return this.answeredHere(held.decision, held.featureId);
+            }
+            const joining = this.flight !== null;
+            this.flight ??= this.ask(subject).finally(() => {
+                this.flight = null;
+            });
+            const outcome = await this.flight;
+            if ('failOpen' in outcome) {
+                this.reports.failOpen(outcome.failOpen);
+                return false;
+            }
+            // The call that asked is the one the platform answered; the ones that waited on it are
+            // answered here, and a refusal among them is reported like a held one.
+            return joining ? this.answeredHere(outcome.decision, outcome.featureId) : outcome.decision === 'block';
+        }
+        catch {
+            this.reports.failOpen('internal');
+            return false;
+        }
+    }
+    answeredHere(decision, featureId) {
+        if (decision === 'block') {
+            this.reports.refuse(featureId);
+        }
+        return decision === 'block';
+    }
+    async ask(subject) {
+        if (this.sending === null && !this.reports.empty) {
+            this.sending = this.reports;
+            this.reports = new Reports();
+        }
+        const sent = this.sending;
+        const generation = ++this.asked;
+        try {
+            const answer = await this.answer(JSON.stringify({ ...subjectFields(subject), ...sent?.fields() }));
+            this.answered(answer, sent, generation);
+            return { decision: answer.decision, featureId: answer.featureId };
+        }
+        catch (error) {
+            const failed = error instanceof AnswerError ? error : new AnswerError('internal');
+            // Maybe not recorded, so `sending` stays and is resent with its report_id once the hold runs out.
+            this.held = { decision: 'allow', until: Date.now() + failed.holdMillis, featureId: null, failOpen: failed.reason };
+            // Still on the wire after a timeout: its answer replaces the fail-open hold, and a failure
+            // holds as that failure would have (a late 401 is an auth hold, not a timeout one).
+            failed.late?.then((answer) => this.answered(answer, sent, generation), (late) => {
+                if (this.asked === generation && late instanceof AnswerError) {
+                    this.held = { decision: 'allow', until: Date.now() + late.holdMillis, featureId: null, failOpen: late.reason };
+                }
+            });
+            return { failOpen: failed.reason };
+        }
+    }
+    // Answered, so recorded: the next batch is the one counted meanwhile. A late answer never
+    // overrides a newer request's hold.
+    answered(answer, sent, generation) {
+        if (this.sending === sent) {
+            this.sending = null;
+        }
+        if (this.asked === generation) {
+            this.held = answer.holdMillis > 0
+                ? { decision: answer.decision, until: Date.now() + Math.min(answer.holdMillis, MAX_HOLD_MILLIS), featureId: answer.featureId }
+                : null;
+        }
+    }
+}
+/** Asks the decision route, holds its answers per agent, and gates `fetch` requests made inside LLM spans. */
+export class RuntimeGate {
+    endpoint;
+    // Least recently used first.
+    agents = new Map();
+    spans = new WeakMap();
+    /**
+     * 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, endpoint) {
+        this.endpoint = new Endpoint(token, endpoint, DECISION_PATH);
+    }
+    /**
+     * 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) {
+        return this.agentFor(subject).check(subject);
+    }
+    /**
+     * `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, input, init) {
+        let refused;
+        try {
+            refused = this.decisionFor(input);
+        }
+        catch {
+            refused = null;
+        }
+        if (refused === null) {
+            return original(input, init);
+        }
+        return unlessAborted(refused, init?.signal ?? requestSignal(input)).then((isRefused) => {
+            if (isRefused) {
+                throw new AgentWatchRefusal();
+            }
+            return original(input, init);
+        });
+    }
+    /** Release the sockets. Uninstall it first: a closed gate is never consulted. */
+    close() {
+        this.endpoint.destroy();
+    }
+    agentFor(subject) {
+        const key = JSON.stringify([subject.agentName, subject.deploymentEnvironment]);
+        const known = this.agents.get(key);
+        if (known !== undefined) {
+            this.agents.delete(key);
+            this.agents.set(key, known);
+            return known;
+        }
+        this.evict();
+        const created = new AgentGate((body) => this.decide(body));
+        // Full of agents that are all in flight or owing: this one is asked about but not
+        // remembered, so the map stays bounded whatever the application fans out.
+        if (this.agents.size < MAX_AGENTS_OWING) {
+            this.agents.set(key, created);
+        }
+        return created;
+    }
+    // Forget the least recently used agent with nothing in flight and nothing owed; past
+    // MAX_AGENTS_OWING, the least recently used one that owes. Never one with a request in flight.
+    evict() {
+        if (this.agents.size < MAX_AGENTS) {
+            return;
+        }
+        let owing = null;
+        for (const [key, agent] of this.agents) {
+            if (agent.busy) {
+                continue;
+            }
+            if (!agent.owes) {
+                this.agents.delete(key);
+                return;
+            }
+            owing ??= key;
+        }
+        if (owing !== null && this.agents.size >= MAX_AGENTS_OWING) {
+            this.agents.delete(owing);
+        }
+    }
+    // The span's decision, or `null` when this request is not gated. The span is checked before
+    // the URL: the URL is parsed once per gated span, not on every request the application makes.
+    decisionFor(input) {
+        const span = trace.getActiveSpan();
+        if (span === undefined) {
+            return null;
+        }
+        const known = this.spans.get(span);
+        if (known !== undefined) {
+            // A token request in a refused span still goes through.
+            return known.then((refused) => refused && !isTokenRequest(input));
+        }
+        // The SDK's span carries its attributes, name and resource; the API's interface does not.
+        // A sampled-out span (NonRecordingSpan) carries none, so it is never gated.
+        const { attributes, name, resource } = span;
+        if (attributes === undefined || !isLlmSpan({ attributes }) || isTokenRequest(input)) {
+            return null;
+        }
+        const stated = resource?.attributes ?? {};
+        const decided = this.check({
+            agentName: storable(name, ID_MAX) ?? 'unnamed',
+            serviceName: reportedService(stated['service.name']),
+            model: storable(attributes['llm.model_name'], ID_MAX) ?? storable(attributes['llm.model'], ID_MAX) ?? storable(attributes['gen_ai.request.model'], ID_MAX),
+            deploymentEnvironment: environmentOf(stated)
+        }).then((refused) => {
+            if (refused) {
+                markRefused(span);
+            }
+            return refused;
+        });
+        this.spans.set(span, decided);
+        return decided;
+    }
+    // Settles within the gate timeout, with the fail-open reason on failure. The socket and the
+    // timer are ref'd while a caller awaits it: a process with nothing else to do must not exit
+    // before the model call it is waiting to make. Past the timeout the request runs on, unref'd
+    // and capped at LATE_ANSWER_MILLIS, and the timeout carries it as `late`.
+    decide(body) {
+        let timer;
+        const waiting = new AbortController();
+        const capped = new AbortController();
+        const cap = setTimeout(() => capped.abort(), LATE_ANSWER_MILLIS).unref();
+        const answered = this.endpoint.postJson(body, { signal: capped.signal, maxBytes: MAX_ANSWER_BYTES, holdProcess: waiting.signal }).then(readPosted, (error) => {
+            throw new AnswerError(error instanceof BodyTooLarge ? 'unreadable' : 'unreachable');
+        }).finally(() => clearTimeout(cap));
+        const timedOut = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                waiting.abort();
+                reject(new AnswerError('timeout', FAIL_OPEN_HOLD_MILLIS, answered));
+            }, GATE_TIMEOUT_MILLIS);
+        });
+        return Promise.race([answered, timedOut]).finally(() => clearTimeout(timer));
+    }
+}
+const SLOT = Symbol.for('agent-watch.otel.fetch-gate');
+function liveGate() {
+    return globalThis[SLOT]?.at(-1);
+}
+/**
+ * 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 function installGate(gate) {
+    const host = globalThis;
+    if (host[SLOT] === undefined) {
+        const original = host.fetch;
+        host[SLOT] = [];
+        if (typeof original === 'function') {
+            host.fetch = function fetch(input, init) {
+                const live = liveGate();
+                return live === undefined ? original(input, init) : live.fetch(original, input, init);
+            };
+        }
+    }
+    host[SLOT].push(gate);
+}
+/**
+ * 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 function uninstallGate(gate) {
+    const gates = globalThis[SLOT];
+    const index = gates?.lastIndexOf(gate) ?? -1;
+    if (index >= 0) {
+        gates?.splice(index, 1);
+    }
+}
+/**
+ * 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 async function guard(agentName) {
+    const gate = liveGate();
+    if (gate === undefined) {
+        return;
+    }
+    const refused = await gate.check({
+        agentName: storable(agentName, ID_MAX) ?? 'unnamed',
+        serviceName: null,
+        model: null,
+        deploymentEnvironment: environmentOf(resourceFromEnvironment())
+    });
+    if (refused) {
+        throw new AgentWatchRefusal();
+    }
+}
+// `init.signal` aborting while the decision is awaited rejects at once with its reason, as
+// `fetch` itself would.
+function unlessAborted(pending, signal) {
+    if (signal === undefined || signal === null) {
+        return pending;
+    }
+    if (signal.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        void pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+// A `Request` carries its own signal; `init.signal` overrides it, as in `fetch`.
+function requestSignal(input) {
+    return typeof Request !== 'undefined' && input instanceof Request ? input.signal : undefined;
+}
+function readPosted(posted) {
+    if (posted.status < 200 || posted.status > 299) {
+        throw new AnswerError('http_status', AUTH_STATUSES.has(posted.status) ? FAIL_OPEN_AUTH_HOLD_MILLIS : FAIL_OPEN_HOLD_MILLIS);
+    }
+    const answer = readAnswer(posted.text);
+    if (answer === null) {
+        throw new AnswerError('unreadable');
+    }
+    return answer;
+}
+// `deployment.environment.name` (semantic conventions 1.27+), then the older `deployment.environment`.
+function environmentOf(attributes) {
+    return storable(attributes['deployment.environment.name'], ID_MAX) ?? storable(attributes['deployment.environment'], ID_MAX);
+}
+// OTEL_RESOURCE_ATTRIBUTES (`key=value,key=value`, values percent-encoded): what a resource
+// detector would read, for `guard`, which has no span.
+function resourceFromEnvironment() {
+    const attributes = {};
+    for (const pair of (process.env.OTEL_RESOURCE_ATTRIBUTES ?? '').split(',')) {
+        const separator = pair.indexOf('=');
+        if (separator > 0) {
+            try {
+                attributes[pair.slice(0, separator).trim()] = decodeURIComponent(pair.slice(separator + 1).trim());
+            }
+            catch {
+                // A value that is not percent-encoded properly is left out, as the SDK's detector does.
+            }
+        }
+    }
+    return attributes;
+}
+function subjectFields(subject) {
+    return {
+        agent_name: subject.agentName,
+        ...(subject.serviceName === null ? {} : { service_name: subject.serviceName }),
+        ...(subject.model === null ? {} : { model: subject.model }),
+        ...(subject.deploymentEnvironment === null ? {} : { deployment_environment: subject.deploymentEnvironment })
+    };
+}
+function readAnswer(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return null;
+    }
+    const { decision, hold_ms: hold, feature_id: featureId } = parsed;
+    if ((decision !== 'allow' && decision !== 'block') || typeof hold !== 'number' || !Number.isFinite(hold) || hold < 0) {
+        return null;
+    }
+    // Not a uuid, it is not echoed: the platform would drop it anyway.
+    return { decision, holdMillis: hold, featureId: decision === 'block' && typeof featureId === 'string' && UUID.test(featureId) ? featureId : null };
+}
+// A URL that does not parse is not a token request; `fetch` itself rejects it.
+function isTokenRequest(input) {
+    const href = typeof input === 'string' || 'href' in input ? String(input) : input.url;
+    return URL.canParse(href) && TOKEN_HOSTS.has(new URL(href).hostname);
+}
+// The processor reads it back in `buildCall`: a refused call is reported as one, with no spend.
+function markRefused(span) {
+    try {
+        span.setAttribute(REFUSED_ATTRIBUTE, true);
+    }
+    catch {
+        // A span that cannot take it is still refused.
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AgentWatchSpanProcessor, BATCH_MAX_CALLS, type AgentWatchSpanProcessorOptions, type ProcessorStats } from './processor.js';
+export { PLATFORM, buildCall, isLlmSpan, type CallSpan, type RuntimeCall } from './call.js';
+export { FINGERPRINT_SCHEME, MAX_TOOL_DEPTH } from './fingerprint.js';
+export { AgentWatchRefusal, REFUSAL_MESSAGE, isAgentWatchRefusal } from './refusal.js';
+export { GATE_TIMEOUT_MILLIS, guard } from './gate.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+// @agent-watch-ai/otel: production LLM spend from an OpenTelemetry span processor, as digests only.
+//
+//   provider = new NodeTracerProvider({ spanProcessors: [yours, new AgentWatchSpanProcessor()] });
+//
+// The customer's own processors keep receiving every span exactly as before.
+export { AgentWatchSpanProcessor, BATCH_MAX_CALLS } from './processor.js';
+export { PLATFORM, buildCall, isLlmSpan } from './call.js';
+export { FINGERPRINT_SCHEME, MAX_TOOL_DEPTH } from './fingerprint.js';
+export { AgentWatchRefusal, REFUSAL_MESSAGE, isAgentWatchRefusal } from './refusal.js';
+export { GATE_TIMEOUT_MILLIS, guard } from './gate.js';

package/dist/post.d.ts

@@ -0,0 +1,54 @@
+/** What came back: the status, and the body when it was read. */
+export interface Posted {
+    readonly status: number;
+    readonly text: string;
+}
+/** Per-request options. */
+export interface PostOptions {
+    /** Aborts the request. */
+    readonly signal?: AbortSignal;
+    /** Read a 2xx body up to this many bytes (more rejects with `BodyTooLarge`); 0 reads none. */
+    readonly maxBytes?: number;
+    /**
+     * Keep the process alive while the request is in flight: a caller is awaiting it. A signal
+     * holds it until the request settles or the signal aborts (the caller stopped waiting).
+     */
+    readonly holdProcess?: boolean | AbortSignal;
+}
+/** A 2xx body longer than `maxBytes`. */
+export declare class BodyTooLarge extends Error {
+}
+/** One Agent Watch route, with the token and the agent its requests use. */
+export declare class Endpoint {
+    private readonly token;
+    private readonly url;
+    private readonly agent;
+    private readonly sockets;
+    private held;
+    /**
+     * Join the route onto the base URL and give it its own agent.
+     * @throws {Error} Plain http to anything but loopback.
+     * @param token SDK token, sent as a bearer token.
+     * @param base Ingest base URL.
+     * @param path The route, joined onto `base`.
+     */
+    constructor(token: string, base: string, path: string);
+    /**
+     * POST `body` as JSON. Resolves with any status, a redirect included (never followed: it would
+     * carry the token elsewhere); rejects on a network error, an abort or an oversized body.
+     * @param body The JSON text.
+     * @param options See `PostOptions`.
+     * @returns The status, and the body when `maxBytes` asked for it and the status is 2xx.
+     */
+    postJson(body: string, options?: PostOptions): Promise<Posted>;
+    /**
+     * Keep the process alive for this endpoint's requests while `work` runs: awaiting a promise
+     * does not keep Node's loop alive, so a short job awaiting delivery would otherwise exit first.
+     * Bounded by whatever bounds `work`.
+     * @param work What the caller awaits.
+     * @returns `work`'s result.
+     */
+    heldWhile<T>(work: () => Promise<T>): Promise<T>;
+    /** Release the sockets. */
+    destroy(): void;
+}