@swfte/nexus-sdk 0.1.0

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@swfte/nexus-sdk",
+  "version": "0.1.0",
+  "description": "Embedded agent observability for Node services \u2014 zero dependencies, bundler-proof.",
+  "license": "Apache-2.0",
+  "author": "Swfte AI",
+  "homepage": "https://github.com/SwfteAI/nexus-sdk-node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SwfteAI/nexus-sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SwfteAI/nexus-sdk-node/issues"
+  },
+  "keywords": [
+    "observability",
+    "agents",
+    "llm",
+    "telemetry",
+    "tracing",
+    "ai-sdk",
+    "vercel"
+  ],
+  "type": "module",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./ai": {
+      "types": "./ai.d.ts",
+      "import": "./src/ai.js",
+      "require": "./src/ai.cjs"
+    },
+    "./package.json": "./package.json",
+    "./otel": {
+      "types": "./otel.d.ts",
+      "import": "./src/otel/index.js",
+      "require": "./src/otel/index.cjs"
+    },
+    "./policy": {
+      "types": "./policy.d.ts",
+      "require": "./src/policy/index.cjs",
+      "import": "./src/policy/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "ai.d.ts",
+    "index.d.ts",
+    "otel.d.ts",
+    "policy.d.ts",
+    "src/ai.cjs",
+    "src/ai.js",
+    "src/core.cjs",
+    "src/health.cjs",
+    "src/index.cjs",
+    "src/index.js",
+    "src/otel/bridge.cjs",
+    "src/otel/classify.cjs",
+    "src/otel/index.cjs",
+    "src/otel/index.js",
+    "src/otel/semconv.cjs",
+    "src/policy/engine.cjs",
+    "src/policy/envelope.cjs",
+    "src/policy/index.cjs",
+    "src/policy/rules.cjs",
+    "src/pricing.cjs",
+    "src/provenance.cjs",
+    "src/redact.cjs"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "bundle": "node bundle/build.mjs",
+    "measure": "node bundle/measure.mjs",
+    "typecheck": "npx --yes --package typescript@5.6.3 tsc --noEmit --strict --module nodenext --moduleResolution nodenext --target es2022 test/types-check.mts",
+    "guard": "node scripts/npm-guard.cjs",
+    "parity": "node scripts/redact-parity.mjs && node scripts/pricing-parity.mjs && node scripts/policy-parity.mjs && node conformance/run.mjs",
+    "probe:ai": "cd fixtures/vercel && npm install --no-audit --no-fund && node bridge-check.mjs && node inspect.mjs",
+    "prepublishOnly": "npm test && npm run typecheck && npm run guard",
+    "conformance": "node conformance/run.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/policy.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `@swfte/nexus-sdk/policy` — the enforcement seam.
+ *
+ * Every agent-observability tool observes. The differentiator is that this one can refuse.
+ *
+ * ── Which call sites are genuinely gated ─────────────────────────────────────────────────────
+ *
+ * **Importing this module gates `run.action(...)`.** That is the only gated call site in this SDK,
+ * and it is the only one that *can* be: enforcement needs a decision taken before the effect, which
+ * needs a call site you own.
+ *
+ * **These are NOT gated, and cannot be:**
+ *
+ * - **The Vercel AI SDK seam (`@swfte/nexus-sdk/ai`).** Its callbacks return `void` — there is no
+ *   channel to refuse on, and a throw from `onToolExecutionStart` neither stops the tool nor
+ *   reaches your code. There is deliberately no policy hook there and there will not be one: a hook
+ *   that appears to work and silently does not is worse than no hook. **If your application runs
+ *   tool calls through the AI SDK, they cannot be gated in-process** — now or in a later release.
+ * - **The OpenTelemetry bridge (`@swfte/nexus-sdk/otel`).** A span is read after the fact; by the
+ *   time it exists the call has happened.
+ * - **`run.usage()`, `act.effect()`, `integration()`, `deployment()`.** All of these record
+ *   something that already occurred.
+ *
+ * So enforcement in Node means the explicit API, a gateway in front of your provider, or nothing.
+ * Worth knowing before you design around it rather than after.
+ *
+ * ── What throws ──────────────────────────────────────────────────────────────────────────────
+ *
+ * `Denied` is the single exception this SDK will ever put in your stack trace, and you opted into
+ * it twice: the rule carried `enforce: true` and the call site did not decline. **With no policy
+ * installed — the default — nothing here can throw**, so adding the import changes no behaviour
+ * until a signed envelope arrives.
+ */
+
+/** How a decision was reached. Read it before trusting `denied`. */
+export type DecisionSource =
+  /** A rule matched. */
+  | 'policy'
+  /** Policy is installed and no rule matched. */
+  | 'no-match'
+  /** No verified policy is installed. Allows, unless `failClosed`. */
+  | 'no-policy'
+  /** The envelope is stale and the rule was not `enforce`-marked, so it became advice. */
+  | 'stale-advisory'
+  /** Evaluation exceeded its latency budget. **Always allows.** */
+  | 'budget-exceeded'
+  /** A `require_approval` rule with no approver channel; resolved to the rule's `on_timeout`. */
+  | 'approval-unavailable'
+  /** A bug inside policy evaluation. **Always allows**, and raises an integrity alert. */
+  | 'error';
+
+export interface Decision {
+  action: 'allow' | 'deny';
+  /** True only when this decision actually stopped something. */
+  enforced: boolean;
+  /** `action === 'deny' && enforced`. The only thing that makes `check`/`gate` throw. */
+  readonly denied: boolean;
+  ruleId: string | null;
+  reason: string;
+  source: DecisionSource;
+  /** The envelope is past its hard-stale window. `enforce`-marked rules still enforce. */
+  stale: boolean;
+  timedOut: boolean;
+  latencyMs: number;
+}
+
+export interface DecideOptions {
+  /**
+   * `false` forces advise mode for this call site regardless of rule markings — the dry-run switch.
+   *
+   * A call site can **decline** to enforce; it can never **promote**. An unmarked rule stays
+   * advisory however this is set, because a mode that could be inferred from context is a mode
+   * somebody will infer wrongly at 3am.
+   */
+  enforce?: boolean;
+  /** Lower the latency budget for this decision. Cannot go below the operator's floor. */
+  budgetMs?: number;
+}
+
+export interface InstallResult {
+  installed: boolean;
+  /** Why it was refused — a specific string, never a generic failure. */
+  problem: string | null;
+  state: 'fresh' | 'soft-stale' | 'hard-stale' | 'expired' | null;
+  rules: number;
+  /** `[index, why]` per rule that would not parse. **A quarantined `enforce` rule is an
+   *  enforcement gap**, so this is reported rather than merely counted. */
+  quarantined: Array<[number, string]>;
+}
+
+export interface PolicySettings {
+  enforcementEnabled?: boolean;
+  /** Deny when no verified policy is installed. **Opt-in**, and the only place in this module
+   *  where being unable to reach something produces a denial. */
+  failClosed?: boolean;
+  decisionBudgetMs?: number;
+  pubkeyHex?: string | null;
+}
+
+/** The one exception this SDK raises. Carries the decision that produced it. */
+export class Denied extends Error {
+  readonly decision: Decision;
+}
+
+/**
+ * Verify and install a signed policy envelope.
+ *
+ * Failure is *no policy*, which **allows** — never a denial. A control plane that pushed a bad
+ * envelope must not take your service down as the punishment, and a failed install leaves the
+ * previous good policy in place.
+ */
+export function install(envelope: unknown, pubkeyHex?: string | null): InstallResult;
+
+/** Adjust settings at runtime. */
+export function configure(patch: PolicySettings): PolicySettings;
+
+/** Evaluate a subject. **Never throws.** */
+export function decide(kind: string, subject: Record<string, unknown>,
+  opts?: DecideOptions): Decision;
+
+/** Decide, and throw {@link Denied} if an enforcing rule refuses. */
+export function check(kind: string, subject: Record<string, unknown>,
+  opts?: DecideOptions): Decision;
+
+/**
+ * Guard a function. **Decides first, then calls it.**
+ *
+ * On a denial the body never executes. A denial raised after the write already went out is not
+ * enforcement, it is journalism.
+ */
+export function gate<T>(kind: string, subject: Record<string, unknown>,
+  fn: (decision: Decision) => T, opts?: DecideOptions): T;
+
+/** Engine counters: evaluations, denials, budget overruns, alerts by kind. */
+export function counters(): Record<string, number>;
+
+/** Every integrity alert this process has raised, with its count and window. */
+export function alerts(): Array<{ kind: string; count: number; firstSeen: number; lastSeen: number }>;
+
+/** Forget the installed policy, the counters and the alerts. Chiefly for tests. */
+export function reset(): void;

package/src/ai.cjs

@@ -0,0 +1,334 @@
+'use strict';
+/**
+ * The Vercel AI SDK bridge — the one capture path in Node that a bundler cannot take away.
+ *
+ * ── Why this exists at all ───────────────────────────────────────────────────────────────────
+ *
+ * Module-hook auto-instrumentation intercepts an *import*. A bundler inlines the provider's source
+ * into the application's own file, so by the time the artifact runs there is no import left to
+ * intercept and no module boundary for a hook to sit on. That is not a degraded mode, it is a dead
+ * end: `SCOPE.md` §3 measures it, and `test/bundled.test.mjs` asserts it. Since Next.js bundles
+ * server code by default, the deployment shape most likely to be running an agent in Node is
+ * exactly the shape module hooks cannot reach.
+ *
+ * `registerTelemetry()` is a *runtime registration*. The application calls it, at startup, with an
+ * object of callbacks. Nothing about the module graph is involved, so nothing a bundler does can
+ * erase it — verified rather than argued: `fixtures/vercel/bundle-check.mjs` bundles the probe with
+ * esbuild and counts the same six callbacks firing.
+ *
+ * ── What this bridge deliberately cannot do ──────────────────────────────────────────────────
+ *
+ * **It cannot deny.** `onToolExecutionStart` fires before a tool's `execute`, which looks like an
+ * enforcement point and is not one. The callback type is `(event) => PromiseLike<void> | void`:
+ * there is no return channel by which an integration could refuse, and a thrown error does not
+ * propagate — measured, not assumed. `fixtures/vercel/enforce.mjs` throws from that callback and
+ * the tool still runs (`tool-executions=1`) with the throw swallowed entirely.
+ *
+ * So this module is observe-only, by the seam's type signature rather than by our choice. In Node,
+ * enforcement comes from the explicit API — `run.action(...)`, where the customer owns the call
+ * site and a decision can be taken before the effect — or it does not come at all. Nothing in this
+ * file accepts a policy, a gate, or a `block` callback, because offering one would be a lie that
+ * only shows up in production.
+ *
+ * ── Content ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * This bridge used to emit **metadata only, at every tier** — never a tool input, never a tool
+ * output, not even at `tier: 'full'`. That was not caution for its own sake: the AI SDK hands these
+ * callbacks fully-formed message arrays and tool payloads, arbitrary customer data in bulk
+ * including whatever a RAG step just pulled out of a database, and gating it correctly needed a
+ * redaction pass this SDK did not have. A half-written redactor is worse than none, because its
+ * output *looks* scrubbed.
+ *
+ * `src/redact.cjs` is that pass now — ported from `nexus/redact.py` and checked against it over a
+ * shared corpus by `scripts/redact-parity.mjs`. So the restriction is lifted as far as the redactor
+ * honestly reaches, and no further:
+ *
+ * - **Tool inputs and outputs are emitted**, through `scrubMapping`, on the ordinary tier ladder.
+ *   They are structured values, which is exactly the shape that pass was built for: a key called
+ *   `api_key` is masked by name whatever its type, a number under an unrecognised key is masked
+ *   below `full`, and the walk is bounded in width and depth so a paged tool result cannot turn
+ *   scrubbing into the slow part of the request.
+ * - **Prompt and completion text are still not emitted.** Not because the redactor could not scrub
+ *   them, but because there is nowhere honest to put them: the events carrying model text are
+ *   `prompt`, `model_response` and `model_thinking`, and in the Python SDK those come from the OTel
+ *   bridge, which this SDK does not have yet. Inventing a home for the text here would repeat the
+ *   `data_expectation` mistake — a producer emitting ahead of the artifact.
+ *
+ * The honest summary: **structured tool data rides the tier ladder; model text does not appear at
+ * all.** `test/ai.test.mjs` asserts both halves, including a canary run that drives marked secrets
+ * through every callback at `tier: 'full'` and searches the whole emitted corpus.
+ *
+ * ── Usage ───────────────────────────────────────────────────────────────────────────────────
+ *
+ *     import { registerTelemetry } from 'ai';
+ *     import * as nexus from '@swfte/nexus-sdk';
+ *     import { telemetry } from '@swfte/nexus-sdk/ai';
+ *
+ *     nexus.init({ service: 'support-triage', env: 'prod' });
+ *     registerTelemetry(telemetry());
+ *
+ * Note the direction: the customer imports `ai`, not us. This package has no dependency on `ai`,
+ * no peer dependency, and no version range to conflict with theirs — we hand them a plain object
+ * of callbacks and they pass it to a function they already had. That also means this file cannot
+ * break when `ai` changes its exports; it can only be wrong about a *field name*, which is what
+ * `FIELD_MAP` below and the recorded fixture exist to pin.
+ */
+
+const core = require('./core.cjs');
+
+/** Stamped on every event this bridge produces, so its coverage is separable in the ledger. */
+const MODE = 'ai-sdk';
+
+/**
+ * Where each number is read from on `ai@7`, recorded because it is the part most likely to move.
+ *
+ * These are not the names the AI SDK's own documentation suggests, and two of them are not the
+ * names this repository's own spike fixtures used. Measured against `ai@7.0.58` with
+ * `fixtures/vercel/inspect.mjs`:
+ *
+ *     usage own keys: ["inputTokens","inputTokenDetails","outputTokens",
+ *                      "outputTokenDetails","totalTokens","raw"]
+ *     usage.inputTokenDetails: { noCacheTokens, cacheReadTokens, cacheWriteTokens }
+ *     performance: { responseTimeMs, effectiveOutputTokensPerSecond, ... }
+ *
+ * The traps, both of which produced silently-empty output before being measured:
+ *
+ *   - the cache split is `usage.inputTokenDetails.cacheReadTokens`, NOT `usage.cachedInputTokens`;
+ *   - the duration is `performance.responseTimeMs`, NOT `performance.durationMs`.
+ *
+ * `fixtures/vercel/enforce.mjs` reads both of the wrong ones. It still "worked" — printed a line,
+ * exited zero — with every token field silently absent, because `JSON.stringify` drops `undefined`
+ * keys. That is the exact failure this bridge has to not have, and it is why the reader below is
+ * written to try the nested shape first and fall back, and why `test/ai.test.mjs` asserts on
+ * numbers rather than on the call happening.
+ */
+const FIELD_MAP = Object.freeze({
+  model: 'event.modelId',
+  provider: 'event.provider',
+  inputTokens: 'event.usage.inputTokens',
+  outputTokens: 'event.usage.outputTokens',
+  cacheReadTokens: 'event.usage.inputTokenDetails.cacheReadTokens',
+  cacheWriteTokens: 'event.usage.inputTokenDetails.cacheWriteTokens',
+  durationMs: 'event.performance.responseTimeMs',
+  toolName: 'event.toolCall.toolName',
+  toolDurationMs: 'event.toolExecutionMs',
+});
+
+/**
+ * The tool's actual return value, out of the AI SDK's wrapper around it.
+ *
+ * `onToolExecutionEnd` reports `toolOutput` as `{ type: 'tool-result', toolCallId, toolName, input,
+ * output, dynamic }` — the result plus a copy of the metadata already on the event. Emitting the
+ * wrapper would duplicate `toolName` and `input` inside `effect.output` and bury the actual value
+ * one level deeper than a reader expects, so the payload is unwrapped here.
+ *
+ * Defensive about the shape because it is version-dependent: an older or newer `ai` that hands back
+ * the bare result rather than the envelope still works.
+ */
+function outputOf(toolOutput) {
+  if (!toolOutput || typeof toolOutput !== 'object') return toolOutput;
+  return 'output' in toolOutput ? toolOutput.output : toolOutput;
+}
+
+/**
+ * The `effect` payload for one tool execution, or `null` when nothing may be recorded.
+ *
+ * Keys are assigned rather than declared, so a suppressed half leaves no key behind at all. See the
+ * call site for why `{ input: undefined }` is not good enough.
+ */
+function toolEffect(call, event) {
+  const effect = {};
+  if (event.recordInputs !== false && call.input !== undefined) effect.input = call.input;
+  if (event.recordOutputs !== false && event.toolOutput !== undefined) {
+    effect.output = outputOf(event.toolOutput);
+  }
+  return Object.keys(effect).length ? effect : null;
+}
+
+/** A finite non-negative number, or `undefined`. Never `NaN`, never a string that looked numeric. */
+function num(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return undefined;
+  return v;
+}
+
+/**
+ * Read a token count that may be flat or nested.
+ *
+ * `ai@7.0.58` reports `usage.inputTokens` as a plain number and puts the cache split in a sibling
+ * `inputTokenDetails`. Earlier LanguageModelV3 drafts nested it as `{ total, cacheRead, ... }`, and
+ * `fixtures/vercel/inspect.mjs` still feeds a mock in that shape. Accepting both costs three lines
+ * and means a minor bump of `ai` that moves back or forth does not silently zero the billing
+ * numbers — which, given `input_tokens: o.inputTokens | 0` in the contract layer, would surface
+ * downstream as a real model call that cost nothing rather than as an error.
+ */
+function tokens(v) {
+  if (v && typeof v === 'object') return num(v.total);
+  return num(v);
+}
+
+function detail(usage, flatKey, nestedParent, nestedKey) {
+  if (!usage) return undefined;
+  const flat = usage[nestedParent];
+  if (flat && typeof flat === 'object') {
+    const n = num(flat[nestedKey]);
+    if (n !== undefined) return n;
+  }
+  // The nested-usage shape carries the split inside the token object itself.
+  const t = usage[flatKey];
+  if (t && typeof t === 'object') return num(t[nestedKey.replace(/Tokens$/, '')]);
+  return undefined;
+}
+
+/**
+ * Build the telemetry integration object.
+ *
+ * Hand the result to the AI SDK's `registerTelemetry`. Every callback is individually guarded: a
+ * bug in this bridge must not surface inside the customer's `generateText` call, and the AI SDK's
+ * own error handling — which swallows throws from these callbacks, as `enforce.mjs` shows — would
+ * hide it rather than report it, so containing it here is the only way it gets counted at all.
+ *
+ * @param {{ runs?: boolean, toolActions?: boolean }} [opts]
+ *   `runs` (default `false`) opens a nexus run per top-level AI SDK operation when the application
+ *   is not already inside one. Off by default because double-counting is worse than under-counting:
+ *   an application that already wraps its handler in `nexus.withAgent` would otherwise report two
+ *   runs for one unit of work, and no downstream query can tell those apart afterwards.
+ *   `toolActions` (default `true`) emits a `tool_action` per tool execution.
+ */
+function telemetry(opts) {
+  const o = opts || {};
+  const wantRuns = o.runs === true;
+  const wantToolActions = o.toolActions !== false;
+
+  // Recorded now, not lazily: `instrumentation()` must report `ai-sdk` from the moment the
+  // integration is built, because the value's whole job is answering "is anything actually
+  // capturing?" for a customer looking at an empty dashboard. Deferring it until the first model
+  // call would make the honest answer arrive only after the thing it was needed to explain.
+  core.noteInstrumentation(MODE);
+
+  /** Runs this bridge opened itself, keyed by the AI SDK's own call id, so `onEnd` can close them. */
+  const ownRuns = new Map();
+
+  const guarded = (name, fn) => (event) => {
+    core.guard('ai.' + name, () => fn(event || {}));
+  };
+
+  const integration = {
+    onStart: guarded('onStart', (e) => {
+      if (!wantRuns) return;
+      if (core.currentRun()) return;            // the application already owns a run; do not nest
+      const id = e.callId || e.operationId;
+      if (!id || ownRuns.has(id)) return;
+      const run = core.agent(String(e.functionId || e.operationId || 'ai'), {
+        goalClass: e.operationId ? String(e.operationId) : undefined,
+      });
+      ownRuns.set(id, run);
+    }),
+
+    onLanguageModelCallEnd: guarded('onLanguageModelCallEnd', (e) => {
+      const client = core.ensureClient();
+      if (!client) return;
+      const usage = e.usage || {};
+      const run = core.currentRun() || ownRuns.get(e.callId) || null;
+
+      client.emit(core.contract.tokenUsage(client.sessionId, client.cfg, {
+        model: e.modelId ? String(e.modelId) : 'unknown',
+        provider: e.provider ? String(e.provider) : undefined,
+        inputTokens: tokens(usage.inputTokens),
+        outputTokens: tokens(usage.outputTokens),
+        cacheReadTokens: detail(usage, 'inputTokens', 'inputTokenDetails', 'cacheReadTokens'),
+        cacheWriteTokens: detail(usage, 'inputTokens', 'inputTokenDetails', 'cacheWriteTokens'),
+        // NOTE: `performance.responseTimeMs` is available here and is deliberately NOT emitted.
+        // `token_usage` has no `duration_ms` in `contract/events.v1.json`, and adding an
+        // undeclared field to a type two producers already write into is the precise mechanism by
+        // which a shared ledger stops being trustworthy (SCOPE.md §7, D4). Model-call latency
+        // arrives when the contract grows a field for it, not before. Passing it into
+        // `contract.tokenUsage` today would not even reach the wire — the function does not read
+        // it — which is the worse failure: a line of code that looks like coverage and is not.
+        // `run_id` when the application is inside a nexus run, absent when it is not. Absent is
+        // correct and is not a defect: a model call made outside any run genuinely has no run to
+        // belong to, and inventing a synthetic parent would put a run in the ledger that no
+        // application ever started.
+        runId: run ? run.runId : undefined,
+        instrumentation: MODE,
+      }));
+    }),
+
+    onToolExecutionEnd: guarded('onToolExecutionEnd', (e) => {
+      if (!wantToolActions) return;
+      const client = core.ensureClient();
+      if (!client) return;
+      const call = e.toolCall || {};
+      const run = core.currentRun() || ownRuns.get(e.callId) || null;
+
+      client.emit(core.contract.toolAction(client.sessionId, client.cfg, {
+        toolName: call.toolName ? String(call.toolName) : 'unknown',
+        action: 'invoke',
+        // No `target`: the AI SDK has no notion of one, and deriving it from the tool input would
+        // put customer data on the wire through a field whose tier gate assumes a short identifier.
+        //
+        // `effect` is the right home for it instead, and it now carries the tool's input and
+        // output. `contract.toolAction` puts this through `scrubMapping`, so the tier ladder and
+        // the key-name rules apply exactly as they do to an `effect()` the application wrote by
+        // hand — a tool argument called `api_key` is masked by name, a number under an unrecognised
+        // key is masked below `full`, and the walk is bounded in width and depth.
+        //
+        // Wrapped in `input`/`output` rather than spread, so a tool argument called `rows` cannot
+        // collide with a field the contract may grow later, and so a reader can tell what the
+        // agent asked for from what it got back.
+        // The AI SDK's own per-call privacy flags are honoured on top of our tier. An application
+        // that told `ai` not to record inputs has already expressed an intent, and a telemetry SDK
+        // that overrides it because its own tier happens to be permissive has substituted its
+        // judgement for the caller's.
+        //
+        // Built by assignment rather than as a literal with `undefined` values: `{ input:
+        // undefined }` still HAS the key, so `'input' in effect` stays true and `scrubMapping`
+        // writes it back out as `null`. A reader then cannot tell "the application suppressed this"
+        // from "the tool was called with no arguments" — which is the same absent-versus-empty
+        // distinction the tier ladder is careful about everywhere else.
+        effect: toolEffect(call, e),
+        durationMs: num(e.toolExecutionMs),
+        // Always false from this path, and the constant is the honest value rather than a
+        // placeholder: this seam cannot deny, so an action reaching it has already executed.
+        // A `blocked: true` could only ever come from the explicit API.
+        blocked: false,
+        runId: run ? run.runId : undefined,
+      }));
+    }),
+
+    onEnd: guarded('onEnd', (e) => {
+      const id = e.callId || e.operationId;
+      const run = id ? ownRuns.get(id) : null;
+      if (!run) return;
+      ownRuns.delete(id);
+      run.end();
+    }),
+  };
+
+  return integration;
+}
+
+/**
+ * Convenience wrapper: hand it the AI SDK's own `registerTelemetry` and it registers for you.
+ *
+ *     import { registerTelemetry } from 'ai';
+ *     register(registerTelemetry);
+ *
+ * Exists because `registerTelemetry(telemetry())` reads like it might have an argument order to get
+ * wrong. Returns whether registration happened, so a startup path can log its own state; a
+ * non-function argument is a no-op rather than a throw, because a telemetry SDK that crashes an
+ * application's boot over its own optional integration has failed at its one job.
+ *
+ * @param {(integration: object) => unknown} registerTelemetry
+ */
+function register(registerTelemetry, opts) {
+  return core.guard('ai.register', () => {
+    if (typeof registerTelemetry !== 'function') {
+      core.incr('ai_register_not_a_function');
+      return false;
+    }
+    registerTelemetry(telemetry(opts));
+    return true;
+  }, false);
+}
+
+module.exports = { telemetry, register, MODE, FIELD_MAP };

package/src/ai.js

@@ -0,0 +1,39 @@
+/**
+ * `@swfte/nexus-sdk/ai` — ESM entry for the Vercel AI SDK bridge.
+ *
+ *     import { registerTelemetry } from 'ai';
+ *     import * as nexus from '@swfte/nexus-sdk';
+ *     import { telemetry } from '@swfte/nexus-sdk/ai';
+ *
+ *     nexus.init({ service: 'support-triage', env: 'prod' });
+ *     registerTelemetry(telemetry());
+ *
+ * A facade over `./ai.cjs`, for the same reason `src/index.js` is a facade over `src/core.cjs`: the
+ * state has to live in exactly one module instance or a process that reaches this package through
+ * both `import` and `require` gets two clients, two session ids and two queues. CJS is the format
+ * both loaders share, so the implementation lives there and this file re-exports it.
+ *
+ * Unlike the main entry there is no `NEXUS_ENABLED` short-circuit here, and it is not an omission:
+ * `telemetry()` builds a plain object of callbacks that each consult the core, and the core is
+ * already switched off at that point — `ensureClient()` returns `null` and every callback becomes
+ * a cheap no-op. Adding a second gate would buy nothing and would give a reader two places to
+ * check when the answer to "is it off?" has to be unambiguous.
+ */
+import bridge from './ai.cjs';
+
+/**
+ * Build the telemetry integration to hand to the AI SDK's `registerTelemetry`.
+ *
+ * Observe-only. The seam cannot deny — a throw from `onToolExecutionStart` does not stop the tool
+ * and does not reach the application. See the header of `src/ai.cjs` for the measurement.
+ */
+export const telemetry = bridge.telemetry;
+
+/** Convenience: `register(registerTelemetry)` instead of `registerTelemetry(telemetry())`. */
+export const register = bridge.register;
+
+/** The value `instrumentation()` reports once this bridge is built: `"ai-sdk"`. */
+export const MODE = bridge.MODE;
+
+/** Where each number is read from on the AI SDK's events. Exported for diagnostics and tests. */
+export const FIELD_MAP = bridge.FIELD_MAP;