@swfte/nexus-sdk 0.1.0

package/src/pricing.cjs

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * Exact model cost from real usage — a deliberate mirror of `nexus/integrations/pricing.py`, which
+ * is itself a deliberate mirror of `nexus_devtools/pricing.py`.
+ *
+ * Three copies of one rate card, and the copying is intentional rather than lazy: this SDK ships to
+ * customers under Apache-2.0 with **zero dependencies**, so it cannot import a module from the
+ * proprietary wrapper repo, and a network call to fetch rates on a request path is not a serious
+ * proposal. What keeps the copies honest is a parity check — `scripts/pricing-parity.mjs` loads the
+ * Python implementation and asserts identical dollars across a matrix that includes the cache
+ * split. If the rate card moves in one repo and not the others, that is the thing that fails.
+ *
+ * The property being defended is a product claim, not a rounding preference. "Exact cost" is what
+ * distinguishes this ledger from every observability tool that multiplies total tokens by a blended
+ * $/Mtok — and cache-heavy agent traffic is where that blend is *badly* wrong in both directions:
+ * cache reads are 10× cheaper than fresh input, cache writes 1.25–2× more expensive. A bridge that
+ * folds both into `input_tokens` reports a number the customer can disprove against their invoice,
+ * which is worse than reporting nothing.
+ *
+ * Unpriced models return `null` rather than a guess. A missing cost is a gap somebody can fill; an
+ * invented cost is a gap nobody can see.
+ */
+
+/**
+ * `[matcher substring, input $/Mtok, output $/Mtok]`, ordered most-specific → least, so the first
+ * hit on a normalised id wins. Mirrors `_RATES` in both Python files verbatim.
+ *
+ * The `opus-5` row exists because `opus`'s catch-all was swallowing `claude-opus-5`. It returns
+ * what the catch-all already returned; the row is for parity, and for the day the catch-all's rate
+ * changes and this one should not.
+ */
+const RATES = [
+  ['fable-5', 10.0, 50.0],
+  ['mythos-5', 10.0, 50.0],
+  ['opus-5', 5.0, 25.0],
+  ['opus-4-8', 5.0, 25.0],
+  ['opus-4-7', 5.0, 25.0],
+  ['opus-4-6', 5.0, 25.0],
+  ['opus-4-5', 5.0, 25.0],
+  ['opus-4-1', 15.0, 75.0],
+  ['opus-4-0', 15.0, 75.0],
+  ['opus-4', 15.0, 75.0],
+  ['3-opus', 15.0, 75.0],
+  ['opus', 5.0, 25.0],
+  ['sonnet-5', 3.0, 15.0],
+  ['sonnet-4-6', 3.0, 15.0],
+  ['sonnet-4-5', 3.0, 15.0],
+  ['sonnet-4', 3.0, 15.0],
+  ['3-7-sonnet', 3.0, 15.0],
+  ['3-5-sonnet', 3.0, 15.0],
+  ['sonnet', 3.0, 15.0],
+  ['haiku-4-5', 1.0, 5.0],
+  ['3-5-haiku', 0.80, 4.0],
+  ['3-haiku', 0.25, 1.25],
+  ['haiku', 1.0, 5.0],
+];
+
+const CACHE_WRITE_5M = 1.25;   // × input rate
+const CACHE_WRITE_1H = 2.0;    // × input rate
+const CACHE_READ = 0.10;       // × input rate
+
+/**
+ * `cost_source` values. Provenance is part of the record: a figure derived from our rate card is an
+ * inference and must be legible as one next to a figure the provider itself reported.
+ */
+const SOURCE_USAGE = 'usage';        // computed here from the provider's own token breakdown
+const SOURCE_PROVIDER = 'provider';  // the provider or instrumentation reported dollars directly
+
+/**
+ * Reduce a provider or span model id to its matchable core.
+ *
+ * The peel order is load-bearing because the decorations nest — a Bedrock id carries a regional
+ * prefix, a vendor prefix, a date *and* a model version at once:
+ *
+ *     claude-haiku-4-5-20251001                         → claude-haiku-4-5
+ *     claude-fable-5[1m]                                → claude-fable-5
+ *     us.anthropic.claude-haiku-4-5-v1:0                → claude-haiku-4-5
+ *     bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0 → claude-3-5-sonnet
+ *     vertex_ai/claude-opus-4-8@20260101                → claude-opus-4-8
+ *
+ * Beyond pricing this keeps per-model aggregates whole: a serving route that normalised to a
+ * different string than the same weights reached first-party would split one model across two
+ * buckets and silently under-count every total.
+ */
+function normalize(model) {
+  let m = String(model || '').toLowerCase().trim();
+  m = m.replace(/^[a-z][a-z0-9_-]*\//, '');        // bedrock/ , vertex_ai/ , <vendor>/ prefixes
+  m = m.replace(/^(?:us|eu|apac|global)\./, '');   // Bedrock cross-region inference prefixes
+  m = m.replace(/^anthropic\./, '');
+  m = m.replace(/\[[^\]]*\]/g, '');                // drop [1m] / [200k] context tags
+  m = m.replace(/-v\d+:\d+$/, '');                 // drop Bedrock model-version suffix (-v1:0)
+  m = m.replace(/[@-]\d{8}$/, '');                 // drop dated snapshot suffix
+  m = m.replace(/-fast$/, '');
+  return m;
+}
+
+/** `[input, output]` $/Mtok for a model, or `null` when unpriced. */
+function rates(model) {
+  const norm = normalize(model);
+  for (const [needle, tin, tout] of RATES) {
+    if (norm.includes(needle)) return [tin, tout];
+  }
+  return null;
+}
+
+function num(v) {
+  const n = typeof v === 'number' ? v : parseFloat(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Exact USD for one usage breakdown, or `null` when the model is unpriced. Never throws.
+ *
+ * `usage` uses the transcript's own field names — `input_tokens` (uncached), `output_tokens`,
+ * `cache_read_input_tokens`, and either the split `cache_creation.ephemeral_5m_input_tokens` /
+ * `ephemeral_1h_input_tokens` or the flat `cache_creation_input_tokens` (priced at the 5-minute
+ * rate). See {@link costFromTokens} for the SDK's own camelCase field names.
+ */
+function costFromUsage(model, usage) {
+  const r = rates(model);
+  if (!r) return null;
+  const [tin, tout] = r;
+  try {
+    const u = usage || {};
+    // `cache_creation` is whatever the caller put there. A bridge reading a hostile or half-written
+    // span can hand us a string, and reading a property off one would otherwise fall into the
+    // blanket catch below — turning one malformed field into a null cost for the whole call.
+    // Nothing about the other four numbers is unknowable just because this one is junk.
+    const cc = (u.cache_creation && typeof u.cache_creation === 'object') ? u.cache_creation : {};
+    let w5 = num(cc.ephemeral_5m_input_tokens);
+    const w1 = num(cc.ephemeral_1h_input_tokens);
+    if (!w5 && !w1) w5 = num(u.cache_creation_input_tokens);  // no split → flat, treat as 5m
+
+    const dollars = (
+      num(u.input_tokens) * tin
+      + num(u.output_tokens) * tout
+      + num(u.cache_read_input_tokens) * tin * CACHE_READ
+      + w5 * tin * CACHE_WRITE_5M
+      + w1 * tin * CACHE_WRITE_1H
+    ) / 1000000;
+    // Python rounds to 6 decimal places, and matching it *exactly* matters: a fraction of a cent
+    // that differs between two producers turns "do these agree?" into a floating-point question
+    // rather than a data question.
+    //
+    // `toFixed(6)` rather than the obvious `Math.round(x * 1e6) / 1e6`. The two disagree, and the
+    // difference is not theoretical — it produced 9 mismatches across the parity matrix on the
+    // first run, every one an off-by-one in the sixth decimal place:
+    //
+    //     0.0004125  →  Math.round 0.000413   toFixed 0.000412   (Python: 0.000412)
+    //     0.0000875  →  Math.round 0.000088   toFixed 0.000087   (Python: 0.000087)
+    //
+    // Multiplying by 1e6 first introduces its own representation error and then rounds *that*,
+    // half away from zero. `toFixed` and CPython's `round()` both round the exact binary value of
+    // the double, which is why they agree on every case in the matrix including the ties.
+    return Number(dollars.toFixed(6));
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * The same calculation over the field names this SDK uses on its own `usage()` call and in the AI
+ * bridge, rather than the transcript's snake_case ones.
+ *
+ * A thin adapter on purpose. The rate card and the arithmetic stay in one function that is
+ * diff-able against Python line by line; only the naming differs, and naming is exactly what a
+ * "port" gets wrong quietly. `cacheWriteTokens` maps to the flat `cache_creation_input_tokens` and
+ * is therefore priced at the 5-minute rate — neither the AI SDK nor `run.usage()` exposes the
+ * 5m/1h split, and inventing one would be a guess about a number the customer is billed for.
+ */
+function costFromTokens(model, o) {
+  return costFromUsage(model, {
+    input_tokens: o.inputTokens,
+    output_tokens: o.outputTokens,
+    cache_read_input_tokens: o.cacheReadTokens,
+    cache_creation_input_tokens: o.cacheWriteTokens,
+  });
+}
+
+module.exports = {
+  RATES,
+  SOURCE_USAGE,
+  SOURCE_PROVIDER,
+  normalize,
+  rates,
+  costFromUsage,
+  costFromTokens,
+};

package/src/provenance.cjs

@@ -0,0 +1,304 @@
+'use strict';
+/**
+ * Where the running process thinks it came from — and, for every value, *how we know*.
+ *
+ * Port of `nexus-sdk/src/nexus/provenance.py`. Same detectors, same order, same field names, same
+ * refusals. A developer who has read one should not have to read the other.
+ *
+ * ── Why this file is separate, and why it refuses so much ────────────────────────────────────
+ *
+ * The operate plane exists to draw one chain honestly:
+ *
+ *     repo ──► commit ──► build ──► deployment ──► running version
+ *
+ * and to draw a **break** wherever a link is missing (`docs/ANCHOR-INTEGRATION.md` §5.3). The
+ * break is the product: a dotted segment between "running version" and "deployment" is the
+ * shadow-deploy alarm — *software is running in production that no release accounts for*. That
+ * alarm is only meaningful if the SDK never invents a link.
+ *
+ * So this module has exactly two rules, and they are the two rules that matter most in the whole
+ * SDK:
+ *
+ * 1. **An absent value stays absent.** No `'unknown'`, no `''`, no `'HEAD'`, no zero. A key that
+ *    is not known is not on the wire at all. `contract.base()` drops nulls for the same reason.
+ * 2. **Never guess silently.** Every detected value carries the name of the variable it was read
+ *    from, as `provenance_source: "env:VERCEL_GIT_COMMIT_SHA"`. A value with no recorded source
+ *    is a bug, and `detect()` cannot produce one — source and value are written together.
+ *
+ * Three consequences that are easy to undo by accident, all three copied from the Python module
+ * because each one is a place where a small convenience destroys the central claim:
+ *
+ * * **A partial value is an absent value.** `VERCEL_GIT_REPO_SLUG` is the bare repository name
+ *   (`portal`). Publishing it as `repo` produces something that *looks* like a repo identity,
+ *   joins against nothing in the devtools ledger, and therefore turns a drawn break into a
+ *   drawn-but-wrong link. Half a join key joins to the wrong thing, not to nothing.
+ * * **`repo` never acquires a host we did not read.** Vercel publishes owner, slug and a provider
+ *   *word* (`github`); it does not publish a host. Mapping `github` → `github.com` is right for
+ *   the common case and wrong for every GitHub Enterprise install, and a wrong host silently
+ *   matches nothing. So on Vercel `repo` is `owner/name`; on GitHub Actions, where
+ *   `GITHUB_SERVER_URL` *is* published, it is `host/owner/name`. The consumer parses both forms;
+ *   it cannot detect a fabricated segment.
+ * * **`application` is never inferred.** It is a declaration, not a similarity. The only
+ *   auto-detected source is `app.kubernetes.io/name`, and that qualifies precisely because an
+ *   operator wrote it down — we are relaying a declaration, not noticing a resemblance.
+ *
+ * ── What this module deliberately does not do ────────────────────────────────────────────────
+ *
+ * * **No `git rev-parse`.** Shelling out is synchronous process I/O at init, it reads the
+ *   *filesystem's* commit rather than the *artifact's*, and in a container it usually finds no
+ *   repository at all. A commit read from a working tree that happens to be mounted next to the
+ *   process is a guess wearing a fact's clothes.
+ * * **No talking to a container runtime.** OCI labels live in the image manifest and a process
+ *   cannot read its own image labels without a daemon socket. What it can read is the convention
+ *   of projecting them into the environment at build time, which is what `_oci` does — and if a
+ *   deployment does not do that, the value is absent, which is the correct answer.
+ * * **No normalisation of `env`.** `VERCEL_ENV=production` is passed through as `production`, not
+ *   rewritten to `prod`. Rewriting is an unsourced translation of a value we were told; the
+ *   console's own mapping is a mapping it can see and change.
+ *
+ * The one file read is Kubernetes' downward-API labels projection, exactly as the Python module
+ * does it: bounded to 128 lines, wrapped so a malformed byte from a sidecar cannot be why `init()`
+ * raised, and attempted only at start-up. Nothing here runs on a request path.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Cap on any single value. Provenance values are identifiers; a 4 kB one is a bug or an attack. */
+const MAX = 256;
+
+/**
+ * The fields this module can fill, in the order the console's ribbon reads them. Snake_case
+ * because these are wire keys — `provenance` ships as `{ deployment_id: 'env:…' }`, and a map
+ * whose keys differ between the Python and Node producers would be two vocabularies.
+ */
+const FIELDS = ['application', 'repo', 'commit', 'env', 'version', 'branch', 'deployment_id'];
+
+/** Trim, cap, and treat empty-after-trim as absent. `FOO=` in a base image must not become a value. */
+function clean(v) {
+  if (v === undefined || v === null) return null;
+  const s = String(v).trim();
+  return s === '' ? null : s.slice(0, MAX);
+}
+
+/** First non-empty variable in `names`, and the name that supplied it. */
+function get(env, names) {
+  for (const n of names) {
+    const v = clean(env[n]);
+    if (v !== null) return [v, 'env:' + n];
+  }
+  return [null, null];
+}
+
+/**
+ * Record a value and its source. First writer wins; an absent value writes nothing at all — not a
+ * `null` entry, because a key present with a null value claims we looked and found emptiness,
+ * which is a different fact from not having looked.
+ */
+function put(out, src, field, value, source) {
+  if (value === null || value === undefined || out[field] !== undefined) return;
+  out[field] = value;
+  src[field] = source;
+}
+
+/** A platform answered *part* of a field. Recorded so a customer can be told why the ribbon broke. */
+function partial(state, field) {
+  if (state.incomplete.indexOf(field) === -1) state.incomplete.push(field);
+}
+
+// ---------------------------------------------------------------------------------------------
+// platform detectors — each reads only, and reports what it read
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Vercel build and runtime environment.
+ *
+ * Gated on `VERCEL` / `VERCEL_ENV`: every Vercel runtime sets one of them, and without that gate
+ * the `VERCEL_*` names could be anything a customer happened to export — reading them would be a
+ * guess about which platform we are on.
+ */
+function vercel(env, out, src, state) {
+  if (!clean(env.VERCEL) && !clean(env.VERCEL_ENV)) return;
+
+  const [commit, cs] = get(env, ['VERCEL_GIT_COMMIT_SHA']);
+  put(out, src, 'commit', commit, cs);
+
+  const owner = clean(env.VERCEL_GIT_REPO_OWNER);
+  const slug = clean(env.VERCEL_GIT_REPO_SLUG);
+  if (owner && slug) {
+    // No host. See the module docstring: `VERCEL_GIT_PROVIDER` is a word, not a hostname.
+    put(out, src, 'repo', owner + '/' + slug, 'env:VERCEL_GIT_REPO_OWNER+VERCEL_GIT_REPO_SLUG');
+  } else if (owner || slug) {
+    partial(state, 'repo');
+  }
+
+  const [branch, bs] = get(env, ['VERCEL_GIT_COMMIT_REF']);
+  put(out, src, 'branch', branch, bs);
+
+  const [dep, ds] = get(env, ['VERCEL_DEPLOYMENT_ID']);
+  put(out, src, 'deployment_id', dep, ds);
+
+  // Verbatim: "production" / "preview" / "development". Mapping those onto the console's
+  // prod|staging|dev|preview vocabulary is the consumer's job.
+  const [venv, es] = get(env, ['VERCEL_ENV']);
+  put(out, src, 'env', venv, es);
+}
+
+/** GitHub Actions. The only platform here that publishes its own host. */
+function githubActions(env, out, src, state) {
+  if (!clean(env.GITHUB_ACTIONS)) return;
+
+  const [commit, cs] = get(env, ['GITHUB_SHA']);
+  put(out, src, 'commit', commit, cs);
+
+  const repo = clean(env.GITHUB_REPOSITORY); // "owner/name"
+  if (repo && repo.indexOf('/') !== -1) {
+    const server = clean(env.GITHUB_SERVER_URL);
+    const host = server ? server.split('://').pop().replace(/\/+$/, '') : '';
+    if (host) {
+      put(out, src, 'repo', host + '/' + repo, 'env:GITHUB_SERVER_URL+GITHUB_REPOSITORY');
+    } else {
+      put(out, src, 'repo', repo, 'env:GITHUB_REPOSITORY');
+    }
+  } else if (repo) {
+    partial(state, 'repo');
+  }
+
+  const [branch, bs] = get(env, ['GITHUB_REF_NAME']);
+  put(out, src, 'branch', branch, bs);
+}
+
+/**
+ * The recommended Kubernetes labels, from projected env or from the projected labels file.
+ *
+ * This is the *only* auto-detected source of `application`, and it qualifies because
+ * `app.kubernetes.io/name` is something an operator wrote down.
+ */
+function kubernetes(env, out, src) {
+  const [name, ns] = get(env, ['APP_KUBERNETES_IO_NAME', 'K8S_APP_NAME']);
+  put(out, src, 'application', name, ns);
+  const [ver, vs] = get(env, ['APP_KUBERNETES_IO_VERSION', 'K8S_APP_VERSION']);
+  put(out, src, 'version', ver, vs);
+
+  if (out.application !== undefined && out.version !== undefined) return;
+
+  const dir = clean(env.NEXUS_PODINFO_DIR) || '/etc/podinfo';
+  const where = path.join(dir, 'labels');
+  const labels = readLabels(where);
+  if (!labels) return;
+  put(out, src, 'application', clean(labels['app.kubernetes.io/name']),
+    'file:' + where + '#app.kubernetes.io/name');
+  put(out, src, 'version', clean(labels['app.kubernetes.io/version']),
+    'file:' + where + '#app.kubernetes.io/version');
+}
+
+/**
+ * Parse a downward-API labels projection: one `key="value"` per line.
+ *
+ * Bounded and total. A projected volume that is not mounted is the normal case rather than an
+ * error, and a malformed line is skipped rather than raised on — this runs inside `init()`, and
+ * `init()` throwing because a sidecar wrote a stray byte would be the SDK becoming the outage.
+ */
+function readLabels(file) {
+  try {
+    if (!fs.existsSync(file)) return null;
+    const text = fs.readFileSync(file, 'utf8');
+    const out = {};
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length && i < 128; i += 1) {
+      const line = lines[i].trim();
+      const eq = line.indexOf('=');
+      if (eq === -1) continue;
+      out[line.slice(0, eq).trim()] = line.slice(eq + 1).trim().replace(/^"|"$/g, '').slice(0, MAX);
+    }
+    return out;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** Generic OCI image labels, projected into the environment at build time. */
+function oci(env, out, src) {
+  const [commit, cs] = get(env, [
+    'OCI_IMAGE_REVISION', 'ORG_OPENCONTAINERS_IMAGE_REVISION', 'org.opencontainers.image.revision',
+  ]);
+  put(out, src, 'commit', commit, cs);
+
+  const [source, ss] = get(env, [
+    'OCI_IMAGE_SOURCE', 'ORG_OPENCONTAINERS_IMAGE_SOURCE', 'org.opencontainers.image.source',
+  ]);
+  if (source) {
+    // The label is a URL by convention. Stripping the scheme and a trailing ".git" normalises a
+    // value we were given; it does not infer one we were not.
+    let repo = source.split('://').pop().replace(/\/+$/, '');
+    if (repo.endsWith('.git')) repo = repo.slice(0, -4);
+    put(out, src, 'repo', repo || null, ss);
+  }
+
+  const [ver, vs] = get(env, [
+    'OCI_IMAGE_VERSION', 'ORG_OPENCONTAINERS_IMAGE_VERSION', 'org.opencontainers.image.version',
+  ]);
+  put(out, src, 'version', ver, vs);
+}
+
+const DETECTORS = [vercel, githubActions, kubernetes, oci];
+
+/**
+ * Detect provenance, recording where every value came from.
+ *
+ * @param {Record<string, unknown>} [explicit] values the application passed to `init()`, already
+ *   merged with the `NEXUS_*` variables by the caller — which is why anything present here is
+ *   stamped `explicit`. "The application told us" is a *stronger* claim than "we read it off the
+ *   platform", not a weaker one, so it short-circuits detection for that field.
+ * @param {Record<string, string|undefined>} [env] defaults to `process.env`; injectable so the
+ *   tests can exercise a clean environment without mutating the process.
+ * @returns {{values: Record<string,string>, sources: Record<string,string>, incomplete: string[]}}
+ *   `values` and `sources` always have exactly the same key set — a value can never arrive without
+ *   its source. `incomplete` names fields a platform *nearly* answered, so the SDK can count them
+ *   and a customer whose ribbon has a break can be told which kind of break it is.
+ */
+function detect(explicit, env) {
+  const e = env || process.env;
+  const values = {};
+  const sources = {};
+  const state = { incomplete: [] };
+
+  for (const field of FIELDS) {
+    const given = clean(explicit ? explicit[field] : null);
+    if (given === null) continue;
+    values[field] = given;
+    // ── `env` and `version` take a value but never a source, matching `provenance.py:resolve` ──
+    //
+    // They are unified tags the process already carries, with their own `"unknown"` sentinel, and
+    // they appear in FIELDS only so that a *detected* value can beat that sentinel. Stamping them
+    // `'explicit'` makes the sources map non-empty on every ordinary `init()` — so a console
+    // reading "does this process have provenance?" off a non-empty map sees provenance everywhere
+    // and a break nowhere, which is the one question the ribbon exists to answer.
+    //
+    // The Python SDK reached this first and says so in its own comment. This SDK stamped both and
+    // therefore published a sources map two keys wider than Python's for the same `init()` call.
+    if (field === 'env' || field === 'version') continue;
+    sources[field] = 'explicit';
+  }
+
+  for (const fn of DETECTORS) {
+    // A detector must never be the reason `init()` failed.
+    try { fn(e, values, sources, state); } catch (_) { /* next platform */ }
+  }
+
+  return { values, sources, incomplete: state.incomplete };
+}
+
+/**
+ * The scalar the console's `RunningVersion.provenance_source` expects.
+ *
+ * It is the source of **the commit**, and of nothing else. The commit is the join key into the
+ * commit-anchored devtools ledger; a ribbon printing the source of some *other* field while the
+ * commit is absent would attach a provenance claim to a link that does not exist. Absent when the
+ * commit is absent, which is exactly when the ribbon should draw a break.
+ */
+function primarySource(sources) {
+  return (sources && sources.commit) || null;
+}
+
+module.exports = { detect, primarySource, FIELDS, MAX, readLabels };