@swfte/nexus-sdk 0.1.0

package/src/health.cjs

@@ -0,0 +1,172 @@
+'use strict';
+/**
+ * `service_health` — derived from spans we already have, on the path that already exists.
+ *
+ * A port of `nexus/health.py`. Availability, latency and error rate are what an operator asks for
+ * first, and the tempting way to get them is a new instrumentation ask: a `nexus.request()` wrapper
+ * threaded through every handler. That ask is why most observability adoptions stall, and it is
+ * unnecessary — the SDK already brackets every `action` span and already knows how long each took
+ * and whether it ended in an error. This module reads those spans on their way out and rolls them
+ * up.
+ *
+ * ── What is measured, stated plainly, because the wire key invites a stronger reading ─────────
+ *
+ * `requests` on this event, when the SDK is the producer, is **the number of action spans
+ * observed** — not the number of HTTP requests served. An application that instruments one action
+ * per request makes the two identical; one that instruments three makes them differ by 3×; one that
+ * instruments none emits nothing at all. Which is the reason for the next rule.
+ *
+ * **An empty window emits nothing.** Zero observed spans does not mean zero requests — far more
+ * often it means "this service never calls `run.action`". Writing `requests: 0` there would be a
+ * fabricated zero, and it would read on a console as a measured outage. `heartbeat()` is the honest
+ * version of that statement: a window with a timestamp and no quantities, which says *this process
+ * was alive and nothing was measured*.
+ *
+ * **Percentiles** are exact within the reservoir, which holds the most recent {@link RESERVOIR}
+ * durations of the window. `requests` and `errors` are always true counts. The contract carries no
+ * sample-count field, so the approximation is recorded here rather than on the wire — at the default
+ * 60 s window a service would need to sustain ~136 spans/second before the cap binds at all.
+ *
+ * ── Two things in the Python that deliberately did NOT come across ───────────────────────────
+ *
+ * 1. **The lock.** `HealthRollup` in Python holds a `threading.Lock`, and `roll()` acquires it
+ *    non-blockingly so that a re-entrant shutdown (atexit hook running when SIGTERM arrives) cannot
+ *    deadlock the process against itself. Node has one event loop and no preemption, so a
+ *    synchronous `roll()` cannot be interleaved with `observe()` at all — there is no torn read to
+ *    prevent, and adding a mutex would be porting the shape of a fix rather than its reason.
+ *    Re-entrancy is still guarded, because the shutdown path *is* re-entrant here too: `_rolling`
+ *    below does what the non-blocking acquire did, for the same reason (emitting one window twice
+ *    would double-count it).
+ * 2. **The worker/caller split.** Python aggregates only when its background thread is draining, so
+ *    an explicit `flush()` from the application's thread drains *without* aggregating — which keeps
+ *    "the calling thread never performs I/O, and now also never aggregates" true without a hole.
+ *    Node has no such split: the flush is asynchronous either way, so the fold happens in a promise
+ *    continuation on the loop regardless of who asked. Aggregating on every drain is therefore
+ *    simpler and slightly *more* complete than Python, which silently drops spans drained by an
+ *    explicit flush. Noted in PARITY.md rather than left to be discovered from a count that differs.
+ */
+
+/**
+ * Most recent durations retained per window for the percentile calculation. Bounded because a
+ * window is wall-clock-bounded rather than volume-bounded, and an unbounded array here would be a
+ * memory leak with a traffic spike as its trigger.
+ */
+const RESERVOIR = 8192;
+
+/**
+ * The span type we derive from. One name, in one place: the day `tool_action` is renamed on the
+ * wire, this file must fail loudly rather than silently roll up nothing forever.
+ */
+const SPAN_TYPE = 'tool_action';
+
+/**
+ * Nearest-rank percentile. `null` for an empty sample — never `0`, which is a latency.
+ *
+ * `rank = ceil(q * n)`, the textbook definition, so a p95 is an observation that was actually in
+ * the sample rather than an interpolation between two. An interpolated p99 over twenty requests
+ * invents a latency nobody experienced.
+ */
+function pct(sortedMs, q) {
+  const n = sortedMs.length;
+  if (n === 0) return null;
+  const scaled = q * n;
+  let rank = Math.floor(scaled);
+  if (scaled > rank) rank += 1;
+  rank = Math.max(1, Math.min(n, rank));
+  return Math.round(sortedMs[rank - 1] * 1000) / 1000;
+}
+
+class HealthRollup {
+  constructor(now) {
+    this._now = now;
+    this._durations = [];
+    this._requests = 0;
+    this._errors = 0;
+    this._windowFrom = now();
+    this._lastRoll = Date.now();
+    this._rolling = false;
+  }
+
+  /**
+   * Fold one outgoing batch into the current window. Called on the drain path, over events that
+   * are on their way out anyway, so an action span costs exactly what it cost before this file
+   * existed.
+   */
+  observe(batch) {
+    let seen = 0;
+    let errs = 0;
+    const durations = [];
+    for (const e of batch) {
+      if (!e || e.type !== SPAN_TYPE) continue;
+      seen += 1;
+      // The tiered ladder means the error may present as `error`, `error_preview`, or only as
+      // `error_fingerprint` at `metadata_only`. The fingerprint is the one that survives every
+      // tier, so an error rate must not depend on how much content the operator allows — a
+      // `metadata_only` deployment reporting zero errors would be the worst kind of wrong.
+      if (e.error_fingerprint !== undefined || e.error !== undefined) errs += 1;
+      const d = e.duration_ms;
+      if (typeof d === 'number' && Number.isFinite(d)) durations.push(d);
+    }
+    if (!seen) return;
+    this._requests += seen;
+    this._errors += errs;
+    for (const d of durations) {
+      this._durations.push(d);
+      if (this._durations.length > RESERVOIR) this._durations.shift();
+    }
+  }
+
+  due(intervalMs) {
+    if (!intervalMs || intervalMs <= 0) return false;
+    return (Date.now() - this._lastRoll) >= intervalMs;
+  }
+
+  /**
+   * Close the window and build one `service_health` event, or `null`.
+   *
+   * `emptyWindow` is `heartbeat()`'s path: emit a window even when nothing was in it, so a process
+   * with no request loop can still say it is alive. Every quantity stays absent in that case — the
+   * event carries a timestamp and no numbers, which is precisely the claim.
+   */
+  roll(sessionId, cfg, builders, emptyWindow) {
+    if (this._rolling) return null;      // re-entered during shutdown; already rolling
+    this._rolling = true;
+    let requests;
+    let errors;
+    let samples;
+    let windowFrom;
+    try {
+      requests = this._requests;
+      errors = this._errors;
+      samples = this._durations.slice().sort((a, b) => a - b);
+      windowFrom = this._windowFrom;
+      this._durations = [];
+      this._requests = 0;
+      this._errors = 0;
+      this._windowFrom = this._now();
+      this._lastRoll = Date.now();
+    } finally {
+      this._rolling = false;
+    }
+
+    if (requests === 0 && !emptyWindow) return null;
+    const measured = requests > 0;
+
+    return builders.serviceHealth(sessionId, cfg, {
+      service: cfg.service,
+      appId: cfg.application,
+      env: cfg.env !== 'unknown' ? cfg.env : null,
+      windowFrom,
+      windowTo: this._now(),
+      // A window we watched and saw nothing in is a measured zero; a window we did not watch (a
+      // heartbeat) has no count at all. Two different facts, two renderings.
+      requests: measured ? requests : null,
+      errors: measured ? errors : null,
+      p50Ms: measured ? pct(samples, 0.50) : null,
+      p95Ms: measured ? pct(samples, 0.95) : null,
+      p99Ms: measured ? pct(samples, 0.99) : null,
+    });
+  }
+}
+
+module.exports = { HealthRollup, RESERVOIR, SPAN_TYPE, pct };

package/src/index.cjs

@@ -0,0 +1,53 @@
+'use strict';
+/**
+ * nexus — CommonJS entry.
+ *
+ *   const nexus = require('nexus');
+ *
+ * This is a thin re-export of the same `core.cjs` the ESM entry pulls in, so `import` and
+ * `require` of this package in one process share one client, one session id and one queue.
+ * `test/dual.test.mjs` asserts that; the dual-package hazard is otherwise silent and shows up
+ * downstream as one service reporting as two.
+ */
+const ENABLED = (() => {
+  const v = process.env.NEXUS_ENABLED;
+  if (v === undefined) return true;
+  return !['0', 'false', 'no', 'off'].includes(String(v).trim().toLowerCase());
+})();
+
+const INERT = new Proxy(function () {}, {
+  get(_t, p) { return p === 'then' ? undefined : INERT; },
+  apply() { return INERT; },
+  construct() { return INERT; },
+});
+
+let _core = null;
+function core() {
+  if (_core === null) _core = require('./core.cjs');
+  return _core;
+}
+
+module.exports = {
+  init: (o) => (ENABLED ? core().init(o) : null),
+  agent: (n, o) => (ENABLED ? core().agent(n, o) : INERT),
+  withAgent: (n, o, f) => (ENABLED ? core().withAgent(n, o, f)
+    : Promise.resolve((typeof o === 'function' ? o : f)(INERT))),
+  action: (n, t) => (ENABLED ? core().action(n, t) : INERT),
+  currentRun: () => (ENABLED ? core().currentRun() : null),
+  flush: (d) => (ENABLED ? core().flush(d) : Promise.resolve(true)),
+  shutdown: (d) => (ENABLED ? core().shutdown(d) : Promise.resolve(true)),
+
+  // ── operate plane (ANCHOR-INTEGRATION §6.1–6.4) ──────────────────────────────────────────
+  deployment: (o) => (ENABLED ? core().deployment(o) : false),
+  integration: (n, o) => (ENABLED ? core().integration(n, o) : INERT),
+  withIntegration: (n, o, f) => (ENABLED ? core().withIntegration(n, o, f)
+    : Promise.resolve((typeof o === 'function' ? o : f)(INERT))),
+  expectsData: (n, o) => (ENABLED ? core().expectsData(n, o) : false),
+  heartbeat: () => (ENABLED ? core().heartbeat() : false),
+  setWaitUntil: (f) => { if (ENABLED) core().setWaitUntil(f); },
+  instrumentHandler: (h, o) => (ENABLED ? core().instrumentHandler(h, o) : h),
+  counters: () => (ENABLED ? core().counters() : {}),
+  enabled: () => ENABLED,
+  instrumentation: () => (ENABLED ? core().describeInstrumentation() : 'none'),
+  version: '0.1.0',
+};

package/src/index.js

@@ -0,0 +1,151 @@
+/**
+ * nexus — agent governance as an application dependency. ESM entry.
+ *
+ *   import * as nexus from 'nexus';
+ *   nexus.init({ service: 'support-triage', env: 'prod' });
+ *
+ *   const run = nexus.agent('triage', { goalClass: 'classify' });
+ *   const act = run.action('db.write', 'tickets');
+ *   act.effect({ rows: n }).end();
+ *   run.outcome('resolved', { verifiedBy: 'test' });
+ *   run.end();
+ *
+ * `NEXUS_ENABLED=0` is a true kill switch: no hooks registered, no `Module._load` patch, no exit
+ * handler, no file opened. Every export below short-circuits on `ENABLED`.
+ *
+ * Python's `nexus/__init__.py` goes one step further and defers even the *import* of its core,
+ * because on CPython `import typing` alone costs tens of milliseconds of a Lambda's cold start.
+ * That does not translate and does not need to: `core.cjs` pulls in three builtins that are already
+ * in Node's startup snapshot, and `bundle/measure.mjs` puts the switched-off import at well under a
+ * millisecond. The static import is also the only form a bundler can follow — a
+ * `createRequire(import.meta.url)('./core.cjs')` resolves against the *bundle's* location at
+ * runtime and throws, which would make this package unusable in exactly the deployment shape
+ * SCOPE.md §3 says we have to serve.
+ */
+import core_ from './core.cjs';
+
+const ENABLED = (() => {
+  const v = process.env.NEXUS_ENABLED;
+  if (v === undefined) return true;
+  return !['0', 'false', 'no', 'off'].includes(String(v).trim().toLowerCase());
+})();
+
+function core() { return core_; }
+
+/** Absorbs every use when the SDK is switched off, so host code needs no `if (nexus)` guards. */
+const INERT = new Proxy(function () {}, {
+  get(_t, p) { return p === 'then' ? undefined : INERT; },
+  apply() { return INERT; },
+  construct() { return INERT; },
+});
+
+/**
+ * Declare service identity and arm the SDK. Idempotent — safe to call from both `main()` and a
+ * framework startup hook.
+ * @param {{service?: string, env?: string, version?: string, tier?: 'metadata_only'|'hashed'|'full',
+ *          sink?: string, tags?: Record<string,string>, enabled?: boolean}} [opts]
+ */
+export function init(opts) { return ENABLED ? core().init(opts) : null; }
+
+/**
+ * Open a run: one unit of agent work, with an outcome. Call `run.end()` when it finishes.
+ * @param {string} name
+ * @param {{goalClass?: string}} [opts]
+ */
+export function agent(name, opts) { return ENABLED ? core().agent(name, opts) : INERT; }
+
+/**
+ * Scoped run. Prefer this in async code: the current run propagates across `await` correctly here
+ * and only here (`AsyncLocalStorage`), which the object form returned by `agent()` cannot do.
+ * @template T
+ * @param {string} name
+ * @param {{goalClass?: string}|((run: any) => Promise<T>)} optsOrFn
+ * @param {(run: any) => Promise<T>} [fn]
+ * @returns {Promise<T>}
+ */
+export function withAgent(name, optsOrFn, fn) {
+  if (!ENABLED) {
+    const f = typeof optsOrFn === 'function' ? optsOrFn : fn;
+    return Promise.resolve(f(INERT));
+  }
+  return core().withAgent(name, optsOrFn, fn);
+}
+
+/**
+ * Open an action against the run currently in context. For code several frames below the
+ * `agent()` call that opened the run.
+ * @param {string} name
+ * @param {string} [target]
+ */
+export function action(name, target) { return ENABLED ? core().action(name, target) : INERT; }
+
+/** The run currently in context, or `null`. */
+export function currentRun() { return ENABLED ? core().currentRun() : null; }
+
+/**
+ * Drain the queue within a deadline. Call before a process that is about to stop.
+ *
+ * Asynchronous, because the calling thread never performs I/O — there is no synchronous form to
+ * offer. Switched off, it resolves `true` without touching the core.
+ * @param {number} [deadlineMs]
+ * @returns {Promise<boolean>}
+ */
+export function flush(deadlineMs) { return ENABLED ? core().flush(deadlineMs) : Promise.resolve(true); }
+
+/** Final flush and stop. @param {number} [deadlineMs] @returns {Promise<boolean>} */
+export function shutdown(deadlineMs) {
+  return ENABLED ? core().shutdown(deadlineMs) : Promise.resolve(true);
+}
+
+// ── operate plane (ANCHOR-INTEGRATION §6.1–6.4) ─────────────────────────────────────────────
+
+/** Self-report a deployment. Stamped `detected_by: 'self'`, the weakest claim on the plane. */
+export function deployment(opts) { return ENABLED ? core().deployment(opts) : false; }
+
+/** Open a probe of an outbound dependency. Liveness and freshness stay separate. */
+export function integration(name, opts) { return ENABLED ? core().integration(name, opts) : INERT; }
+
+/** The bracketed form of {@link integration}. Closes on the way out, including on throw. */
+export function withIntegration(name, optsOrFn, fn) {
+  if (!ENABLED) {
+    const f = typeof optsOrFn === 'function' ? optsOrFn : fn;
+    return Promise.resolve(f(INERT));
+  }
+  return core().withIntegration(name, optsOrFn, fn);
+}
+
+/** Declare that data is expected within a window, so its absence can raise an alarm. */
+export function expectsData(name, opts) { return ENABLED ? core().expectsData(name, opts) : false; }
+
+/**
+ * Close the `service_health` window now and emit it, even when nothing was measured.
+ *
+ * The honest form of "this process is alive": a window with a timestamp and no quantities. A
+ * `requests: 0` would be a fabricated zero, and zero observed spans far more often means "this
+ * service never calls `run.action`" than it means an outage.
+ */
+export function heartbeat() { return ENABLED ? core().heartbeat() : false; }
+
+/** Give the SDK the host's `waitUntil` (Vercel), so a flush can outlive the response. */
+export function setWaitUntil(fn) { if (ENABLED) core().setWaitUntil(fn); }
+
+/**
+ * Wrap a serverless handler so the queue drains before the sandbox freezes.
+ *
+ * Without this — or `init({ waitUntil })` — the last buffered events of every invocation are
+ * lost, not delayed. See `src/core.cjs`, the serverless section.
+ */
+export function instrumentHandler(handler, opts) {
+  return ENABLED ? core().instrumentHandler(handler, opts) : handler;
+}
+
+/** The SDK's account of itself: drops, sink failures, contained errors. */
+export function counters() { return ENABLED ? core().counters() : {}; }
+
+/** `true` unless `NEXUS_ENABLED` says otherwise. */
+export function enabled() { return ENABLED; }
+
+/** Which loader armed auto-instrumentation: `esm-hooks`, `cjs-require`, or `none`. */
+export function instrumentation() { return ENABLED ? core().describeInstrumentation() : 'none'; }
+
+export const version = '0.1.0';

package/src/otel/bridge.cjs

@@ -0,0 +1,257 @@
+'use strict';
+/**
+ * Span → nexus event. A port of the emitting half of `nexus/otel/bridge.py`.
+ *
+ * This is what makes `model_response` and `model_thinking` reachable in Node, and it is the only
+ * path by which model-authored text ever leaves this SDK — the AI SDK bridge deliberately emits
+ * none, because before this module existed there was nowhere honest to put it.
+ *
+ * ── What is ported, and what is not ──────────────────────────────────────────────────────────
+ *
+ * Ported: the reader (`semconv.cjs`), the classifier (`classify.cjs`), and one span → its events.
+ *
+ * **Not ported: the logical-call join.** Python's bridge maintains a tree of open spans so that an
+ * instrumentation emitting one span per HTTP *attempt* — a retry, a resend, a streamed reconnect —
+ * is billed once rather than three times, with the losing observations recorded as shape. That is a
+ * whole subsystem (`integrations/billing.py`, span eviction, GC finalizers for abandoned spans) and
+ * porting half of it would be worse than not porting it: a half-built join produces a *plausible*
+ * number, and a plausible wrong bill is harder to catch than an obviously missing one.
+ *
+ * So this bridge is **one span, one observation**. The consequence is named rather than buried:
+ * against an instrumentation that emits a span per retry, token counts and cost are summed across
+ * attempts instead of deduplicated. `attempts` is still read and carried when the instrumentation
+ * reports it, so the over-count is at least visible in the record. PARITY.md §6 states this, and it
+ * is the first thing to build if this bridge is taken further.
+ *
+ * ── Content ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * Upstream redaction is **not trusted**. Every instrumentation in this space has its own
+ * content-capture switch and its own idea of what a secret looks like; some have none. Whether text
+ * may leave this process is our customer's tier decision, so it is re-decided here against the same
+ * ladder every other free-text field passes through. Even `full` is redacted: a tier is a decision
+ * about content, never a waiver on credentials.
+ *
+ * The prompt is read and **emitted nowhere**, matching Python. `SpanFacts.inputText` exists so the
+ * reader is complete and so a future `prompt` event has something to draw on; there is no `prompt`
+ * builder in `nexus_devtools/events.py` that this SDK could emit against, and inventing one is the
+ * mistake this repository has already made once with `data_expectation`.
+ */
+
+const semconv = require('./semconv.cjs');
+const classify = require('./classify.cjs');
+
+/** Which semconv release produced these facts. Rides on the event so a reader can tell which
+ *  vocabulary a row was extracted under — the spec is pre-stable and will move. */
+const SEMCONV_TAG = Object.freeze({
+  genai: semconv.GENAI_SEMCONV_VERSION,
+  stability: semconv.GENAI_SEMCONV_STABILITY,
+});
+
+class Bridge {
+  /**
+   * @param {object} core the SDK core (injected so this module has no cycle back into it)
+   * @param {{strict?: boolean}} [opts]
+   */
+  constructor(core, opts) {
+    this.core = core;
+    this.strict = opts && opts.strict !== undefined ? opts.strict : null;
+    this._stats = { seen: 0, emitted: 0, ignored: 0, unclassified: 0 };
+  }
+
+  /** Statistics for tests and for `counters()`. */
+  stats() { return Object.assign({}, this._stats); }
+
+  reset() { this._stats = { seen: 0, emitted: 0, ignored: 0, unclassified: 0 }; }
+
+  /**
+   * Read one finished span and emit whatever it is worth.
+   *
+   * Never throws. A bridge that raises has put an exception on the host's request path from inside
+   * a span exporter, which is the one place a telemetry failure is guaranteed to be blamed on the
+   * application.
+   */
+  ingest(span) {
+    // Strict mode deliberately bypasses the guard. `guard` exists so a bridge bug cannot reach the
+    // host, which is exactly right in production — but under test the whole point of strict is that
+    // an unclassified span *fails the build*, and a guarded throw is a silently contained one. So
+    // the two modes get the two opposite failure behaviours the classifier's header describes.
+    if (this._strictNow()) return this._ingest(span);
+    return this.core.guard('otel.ingest', () => this._ingest(span), false);
+  }
+
+  _strictNow() {
+    return this.strict === null || this.strict === undefined
+      ? classify.strictDefault()
+      : Boolean(this.strict);
+  }
+
+  _ingest(span) {
+    this._stats.seen += 1;
+    const facts = semconv.normalise(span);
+
+    if (!classify.isOurs(facts)) {
+      // Not a GenAI span at all — an HTTP call, a DB query. Not ours, and silence is correct:
+      // counting every unrelated span in a customer's tracer as "ignored" would make the number
+      // meaningless.
+      this._stats.ignored += 1;
+      return false;
+    }
+
+    let cls;
+    try {
+      cls = classify.classifySpan(facts, this.strict);
+    } catch (err) {
+      // Strict mode. Re-thrown deliberately: under test a new span kind must fail the build.
+      this._stats.unclassified += 1;
+      this.core.incr('bridge_unclassified');
+      throw err;
+    }
+
+    if (cls === null) {
+      // A GenAI span whose kind we do not model. **Dropped, and counted** — never defaulted into
+      // `behavior_trace`, which is the class the product sells as evidence. The counter is what
+      // keeps this a visible coverage gap rather than an invisible one.
+      this._stats.unclassified += 1;
+      this.core.incr('bridge_unclassified');
+      this.core.incr('bridge_unclassified.' + (facts.kind || 'unknown'));
+      return false;
+    }
+
+    const client = this.core.ensureClient();
+    if (!client) return false;
+
+    if (facts.kind === semconv.KIND_LLM) this._emitLlm(client, facts);
+    else this._emitTool(client, facts);
+
+    this._stats.emitted += 1;
+    return true;
+  }
+
+  _emitLlm(client, facts) {
+    const cfg = client.cfg;
+    const run = this.core.currentRun();
+    const runId = run ? run.runId : undefined;
+
+    // Only emit usage when there is usage. A `token_usage` row of zeros for a span that carried no
+    // accounting is a fabricated measurement, and the same fabricated-zero rule that governs
+    // `service_health` governs this.
+    if (semconv.hasUsage(facts) || facts.reportedCostUsd !== null) {
+      const [costUsd, costSource] = this._cost(facts);
+      const ev = this.core.contract.tokenUsage(client.sessionId, cfg, {
+        model: facts.model || 'unknown',
+        provider: facts.provider || undefined,
+        inputTokens: facts.inputTokens || 0,
+        outputTokens: facts.outputTokens || 0,
+        cacheReadTokens: facts.cacheReadTokens === null ? undefined : facts.cacheReadTokens,
+        cacheWriteTokens: this._cacheWriteTotal(facts),
+        costUsd: costUsd === null ? undefined : costUsd,
+        costSource: costSource === null ? undefined : costSource,
+        runId,
+        attempts: facts.attempts === null ? undefined : facts.attempts,
+        instrumentation: 'otel',
+      });
+      // Which vocabulary this was read under, and the 1h cache split the contract has no field for.
+      // Additive on a type the schema declares `additionalProperties: true`, and structure rather
+      // than content — no value from the span reaches it.
+      ev.bridge = Object.assign({ semconv: SEMCONV_TAG }, {
+        vocabulary: facts.vocabulary,
+        cache_write_1h_tokens: facts.cacheWrite1hTokens === null
+          ? undefined : facts.cacheWrite1hTokens,
+      });
+      client.emit(ev);
+    }
+
+    this._emitContent(client, cfg, facts, runId);
+  }
+
+  /**
+   * Model-authored text, re-gated by *our* tier and split by epistemic class.
+   *
+   * The split is the point. A completion is `interaction_narrative` — what the user was told. A
+   * reasoning trace is `rationalisation` — what the model said about its own process. Folding the
+   * second into the first would launder a claim into the record beside the answer it is supposed
+   * to justify.
+   */
+  _emitContent(client, cfg, facts, runId) {
+    const out = this._fragment(facts.outputText, cfg);
+    if (out) {
+      client.emit(this.core.base('model_response', client.sessionId, cfg,
+        classify.classifyPayload(classify.PAYLOAD_OUTPUT), {
+          model: facts.model, provider: facts.provider, prompt_id: runId,
+          answer: out.text !== undefined ? out.text : out.preview,
+          answer_chars: out.chars,
+          answer_fingerprint: out.fingerprint,
+          tokens_est: out.tokens_est,
+          redacted: out.text_redacted || out.preview_redacted || null,
+          truncated: out.preview_truncated || null,
+        }));
+    }
+
+    const think = this._fragment(facts.reasoningText, cfg);
+    if (think) {
+      client.emit(this.core.base('model_thinking', client.sessionId, cfg,
+        classify.classifyPayload(classify.PAYLOAD_REASONING), {
+          model: facts.model, provider: facts.provider, prompt_id: runId,
+          thinking: think.text !== undefined ? think.text : think.preview,
+          thinking_chars: think.chars,
+          thinking_fingerprint: think.fingerprint,
+          redacted: think.text_redacted || think.preview_redacted || null,
+          truncated: think.preview_truncated || null,
+        }));
+    }
+  }
+
+  /** The tier gate, applied on ingest, because upstream redaction is not trusted. */
+  _fragment(text, cfg) {
+    if (!text) return null;
+    return this.core.redactPreview(text, cfg.tier);
+  }
+
+  _emitTool(client, facts) {
+    const run = this.core.currentRun();
+    const runId = run ? run.runId : undefined;
+
+    // `target` is an identifier or nothing — `semconv.identifier` guarantees it, and that is the
+    // reason this call no longer hands the model's own arguments to a text gate. What the
+    // arguments contributed that was worth keeping — how many, named what, of what types — rides
+    // in `effect.arg_shape`, which carries no values at any depth.
+    const effect = { incomplete: false };
+    if (facts.toolArgShape) effect.arg_shape = facts.toolArgShape;
+    if (facts.vocabulary) effect.vocabulary = facts.vocabulary;
+
+    client.emit(this.core.contract.toolAction(client.sessionId, client.cfg, {
+      toolName: facts.toolName || facts.name || 'tool',
+      action: 'invoke',
+      target: facts.toolTarget === null ? undefined : facts.toolTarget,
+      durationMs: facts.durationMs === null ? undefined : facts.durationMs,
+      runId,
+      error: facts.error === null ? undefined : facts.error,
+      effect,
+    }));
+  }
+
+  _cacheWriteTotal(facts) {
+    const total = (facts.cacheWrite5mTokens || 0) + (facts.cacheWrite1hTokens || 0);
+    return total || undefined;
+  }
+
+  /**
+   * Exact dollars for this call, with provenance.
+   *
+   * A cost the provider reported wins: it is evidence. Ours is arithmetic over the provider's own
+   * token breakdown against the pinned rate card, including the cache split — cached input is 10x
+   * cheaper and cache writes 1.25–2x dearer, so a bridge that ignores the split is not imprecise,
+   * it is wrong by multiples on exactly the cache-heavy traffic agents generate. An unpriced model
+   * yields null, never an estimate.
+   */
+  _cost(facts) {
+    if (facts.reportedCostUsd !== null && facts.reportedCostUsd !== undefined) {
+      return [facts.reportedCostUsd, this.core.pricing.SOURCE_PROVIDER];
+    }
+    if (!facts.model || !semconv.hasUsage(facts)) return [null, null];
+    const cost = this.core.pricing.costFromUsage(facts.model, semconv.usageDict(facts));
+    return cost === null ? [null, null] : [cost, this.core.pricing.SOURCE_USAGE];
+  }
+}
+
+module.exports = { Bridge, SEMCONV_TAG };