@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.40.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-lock.mjs

@@ -0,0 +1,202 @@
+// One copy of a service, locked before any side effect (LC-01, DEC-0057): the instance lock and the supervisor marker.
+// Part of the Node service kit (FAA-65, layer L3); the twin of fabric_lock.py. Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { SUPERVISOR_ENV, ServiceError } from './fabric-base.mjs';
+import { atomicWrite, ensurePrivateDir } from './fabric-paths.mjs';
+
+export const EXIT_ALREADY_RUNNING = 75;
+
+export const LOCK_WAIT_SUPERVISED_SECONDS = 300;
+
+export const LOCK_BACKOFF_FIRST_SECONDS = 0.5;
+
+export const LOCK_BACKOFF_MAX_SECONDS = 30;
+
+const O_EXLOCK = 0x20; // BSD/macOS: open(2) takes flock(LOCK_EX); absent from fs.constants
+
+export class AlreadyRunning extends ServiceError {
+  constructor(holderPid, lockPath) {
+    // FAC-SEM-078: a copy that cannot learn the holder's pid says the holder is unknown.
+    super(`Another copy is already running (${holderPid ? `process ${holderPid}` : 'an unknown process'} holds ${lockPath}).`);
+    this.holderPid = holderPid;
+    this.lockPath = lockPath;
+  }
+}
+
+export class InstanceLock {
+  constructor(dataDir) {
+    this.path = path.join(dataDir, 'service.lock');
+    this.fd = null;
+    this.server = null;
+  }
+
+  async acquire() {
+    ensurePrivateDir(path.dirname(this.path));
+    if (process.platform === 'darwin') {
+      const flags = fs.constants.O_RDWR | fs.constants.O_CREAT | O_EXLOCK | fs.constants.O_NONBLOCK;
+      try {
+        this.fd = fs.openSync(this.path, flags, 0o600);
+      } catch (error) {
+        if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
+        throw error;
+      }
+      fs.ftruncateSync(this.fd, 0);
+      fs.writeSync(this.fd, String(process.pid));
+      fs.fsyncSync(this.fd);
+      return this;
+    }
+    // Linux: an abstract unix socket; Windows: a named pipe. Each is exclusive, has no file, and dies
+    // with the process. The Python kit holds the same name beside its file lock (fabric_service.lock_name).
+    const name = lockName(this.path);
+    if (!name) throw new ServiceError(`No instance lock on ${process.platform}: the kit supports macOS, Linux and Windows.`);
+    this.server = net.createServer();
+    await new Promise((resolve, reject) => {
+      // Windows reports a held pipe as EADDRINUSE (access denied) or, when its holder capped the instances, EBUSY.
+      const held = (code) => code === 'EADDRINUSE' || (process.platform === 'win32' && code === 'EBUSY');
+      this.server.once('error', (error) => reject(held(error.code) ? new AlreadyRunning(readPid(this.path), this.path) : error));
+      this.server.listen(name, resolve);
+    });
+    this.server.unref();
+    atomicWrite(this.path, String(process.pid));
+    return this;
+  }
+
+  release() {
+    if (this.fd !== null) fs.closeSync(this.fd);
+    if (this.server) this.server.close();
+    this.fd = null;
+    this.server = null;
+  }
+}
+
+/** The name the lock is held under on Linux (abstract socket) and Windows (named pipe); null on macOS. */
+export function lockName(lockPath, platform = process.platform) {
+  const digest = (text) => crypto.createHash('sha256').update(text).digest('hex').slice(0, 32);
+  if (platform === 'linux') return `\0fabric-service-${digest(path.posix.resolve(lockPath))}`;
+  // Windows paths compare without case: C:\Users and c:\users are one lock.
+  if (platform === 'win32') return `\\\\.\\pipe\\fabric-service-${digest(path.win32.resolve(lockPath).toLowerCase())}`;
+  return null;
+}
+
+function readPid(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8').trim();
+    return /^\d+$/.test(text) ? Number(text) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The managers a supervisor marker may name (DEC-0057): the three systems' supervisors and Project Observatory's node. */
+export const SUPERVISORS = Object.freeze(['launchd', 'systemd', 'task-scheduler', 'node']);
+
+/** The argument form of the marker, for a supervisor whose start carries no environment (a Scheduled Task's action). */
+export const SUPERVISOR_ARG = '--fabric-supervisor';
+
+/**
+ * The marker values an argument vector carries after the executable and before `--`. A bare `--fabric-supervisor`
+ * followed by nothing, by `--` or by another `--…` flag is a marker with an empty value and consumes nothing.
+ */
+export function markerArguments(argv) {
+  const values = [];
+  if (!Array.isArray(argv)) return values;
+  for (let index = 1; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (item === '--') break;
+    if (item === SUPERVISOR_ARG) {
+      const next = argv[index + 1];
+      if (typeof next === 'string' && !next.startsWith('--')) {
+        values.push(next);
+        index += 1;
+      } else {
+        values.push('');
+      }
+    } else if (typeof item === 'string' && item.startsWith(`${SUPERVISOR_ARG}=`)) {
+      values.push(item.slice(SUPERVISOR_ARG.length + 1));
+    }
+  }
+  return values;
+}
+
+/**
+ * How this copy was started (DEC-0057), from `FABRIC_SERVICE_SUPERVISOR=<manager>` and `--fabric-supervisor <manager>` /
+ * `--fabric-supervisor=<manager>` (`env` and `argv` default to this process's; `argv[0]` is the executable or script):
+ * `{kind: 'supervised', manager, forms}` when every marker present names the same manager of SUPERVISORS;
+ * `{kind: 'conflict', values, forms}` when they disagree (an empty or bare argument beside a variable disagrees with it):
+ * the copy exits 75 at once, before it takes the lock; `{kind: 'manual', forms, unreadable?}` with no marker (only an
+ * empty variable counts as none) or one that names no manager. Never inferred from the parent process. The contract's
+ * `supervisorMarker`.
+ */
+export function supervisorMarker({ env = process.env, argv = process.argv.slice(1) } = {}) {
+  const variable = env?.[SUPERVISOR_ENV];
+  const fromEnv = typeof variable === 'string' && variable !== '' ? [variable] : [];
+  const fromArgs = markerArguments(argv);
+  const forms = [...(fromEnv.length ? ['environment'] : []), ...(fromArgs.length ? ['argument'] : [])];
+  const values = [...new Set([...fromEnv, ...fromArgs])];
+  if (values.length > 1) return { kind: 'conflict', values, forms };
+  if (values.length === 0) return { kind: 'manual', forms };
+  return SUPERVISORS.includes(values[0]) ? { kind: 'supervised', manager: values[0], forms } : { kind: 'manual', unreadable: values[0], forms };
+}
+
+/** How long a copy started so may wait for the lock, in seconds: 300 when supervised, else not at all. */
+export const lockWaitBudgetSeconds = (marker) => (marker?.kind === 'supervised' ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
+
+/** The one sentence a copy whose markers disagree exits with, naming the markers present. */
+export function markerConflictMessage(marker) {
+  const shown = marker.values.map((v) => JSON.stringify(v)).join(', ');
+  return marker.forms.length === 2
+    ? `${SUPERVISOR_ENV} and ${SUPERVISOR_ARG} disagree (${shown}); not starting unsupervised.`
+    : `${SUPERVISOR_ARG} is given with different values (${shown}); not starting unsupervised.`;
+}
+
+/** True when a supervisor that restarts on exit started this process and said so with the marker. */
+export const supervised = (start) => supervisorMarker(start).kind === 'supervised';
+
+/** True when launchd started this process from a plist that says so (FABRIC_SERVICE_SUPERVISOR=launchd). */
+export const supervisedByLaunchd = (start) => supervisorMarker(start).manager === 'launchd';
+
+const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));
+
+/**
+ * Take the lock or exit 75 with one sentence naming the holder (DEC-0057, FAC-SEM-078). Markers that
+ * disagree exit 75 before the lock. Started by hand, a held lock exits 75 at once. Under a
+ * supervisor that restarts on exit (launchd's KeepAlive) an immediate exit is a respawn every ThrottleInterval,
+ * forever; so a supervised copy first backs off in-process (0.5 s doubling to 30 s,
+ * LOCK_WAIT_SUPERVISED_SECONDS in all), takes over if the holder leaves, and exits 75 only when
+ * the wait runs out. `waitSeconds` overrides the choice (0 = never wait).
+ */
+export async function holdSingleInstance(dataDir, {
+  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code), env, argv,
+} = {}) {
+  // DEC-0057: markers that disagree exit 75 at once, before the lock, naming them.
+  const marker = supervisorMarker({ ...(env === undefined ? {} : { env }), ...(argv === undefined ? {} : { argv }) });
+  if (marker.kind === 'conflict') {
+    process.stderr.write(`${markerConflictMessage(marker)}\n`);
+    return exit(EXIT_ALREADY_RUNNING);
+  }
+  const wait = waitSeconds ?? lockWaitBudgetSeconds(marker);
+  const deadline = clock() + Math.max(0, wait);
+  let delay = LOCK_BACKOFF_FIRST_SECONDS;
+  let announced = false;
+  for (;;) {
+    try {
+      return await new InstanceLock(dataDir).acquire();
+    } catch (error) {
+      if (!(error instanceof AlreadyRunning)) throw error;
+      const remaining = deadline - clock();
+      if (remaining <= 0) {
+        process.stderr.write(`${error.message}\n`);
+        return exit(EXIT_ALREADY_RUNNING);
+      }
+      if (!announced) {
+        process.stderr.write(`${error.message} Waiting up to ${Math.round(remaining)} s for it to exit.\n`);
+        announced = true;
+      }
+      await sleep(Math.min(delay, remaining));
+      delay = Math.min(delay * 2, LOCK_BACKOFF_MAX_SECONDS);
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-logs.mjs

@@ -0,0 +1,136 @@
+// Logs and stopping (LC-01, LC-12): a rotating log, a capped stdout log, the stop signal and the drain.
+// Part of the Node service kit (FAA-65, layer L3); the twin of fabric_logs.py. Node 20+, no dependency.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DRAIN_SECONDS, ServiceError, nowIso } from './fabric-base.mjs';
+import { ensurePrivateDir } from './fabric-paths.mjs';
+
+export const DRAIN_GRACE_SECONDS = 2;
+
+export const EXIT_HARD_STOP = 70;
+
+// LC-12: logs rotate by size, 5 x 5 MB by default.
+export const LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+export const LOG_BACKUPS = 5;
+
+/**
+ * One structured log: JSON lines rotated by size (5 x 5 MB by default), files 0600 in a 0700
+ * directory. `service.jsonl` -> `.1` ... `.<backups>`; the oldest falls off. Never pass a token,
+ * a cookie, a login code or a request body that may carry one.
+ */
+export class RotatingLog {
+  constructor(file, { maxBytes = LOG_MAX_BYTES, backups = LOG_BACKUPS } = {}) {
+    if (maxBytes < 256 || backups < 1) throw new ServiceError('A rotating log needs maxBytes >= 256 and at least one backup.');
+    this.file = file;
+    this.maxBytes = maxBytes;
+    this.backups = backups;
+  }
+
+  line(record) {
+    let data = Buffer.from(`${JSON.stringify(record)}\n`);
+    if (data.length <= this.maxBytes) return data;
+    const cut = { ...record, truncated: true };
+    let message = String(record.message ?? '');
+    while (message) {
+      message = message.slice(0, Math.floor(message.length / 2));
+      cut.message = message;
+      data = Buffer.from(`${JSON.stringify(cut)}\n`);
+      if (data.length <= this.maxBytes) return data;
+    }
+    return Buffer.from(`${JSON.stringify({ at: record.at, level: record.level, message: '', truncated: true })}\n`);
+  }
+
+  write(level, message, fields = {}) {
+    const data = this.line({ at: nowIso(), level: String(level), message: String(message), ...fields });
+    ensurePrivateDir(path.dirname(this.file));
+    let size = 0;
+    try { size = fs.statSync(this.file).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (size && size + data.length > this.maxBytes) this.rotate();
+    const fd = fs.openSync(this.file, 'a', 0o600);
+    try { fs.writeSync(fd, data); } finally { fs.closeSync(fd); }
+  }
+
+  rotate() {
+    for (let i = this.backups - 1; i > 0; i -= 1) {
+      if (fs.existsSync(`${this.file}.${i}`)) fs.renameSync(`${this.file}.${i}`, `${this.file}.${i + 1}`);
+    }
+    fs.renameSync(this.file, `${this.file}.1`);
+  }
+}
+
+/**
+ * Call once at start: a launchd stdout file over `maxBytes` is copied to `<file>.1` and truncated
+ * in place (launchd holds it open for append, so a rename would leave it writing to the old name).
+ */
+export function capStdoutLog(file, maxBytes = LOG_MAX_BYTES) {
+  let size;
+  try { size = fs.statSync(file).size; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if (size <= maxBytes) return false;
+  fs.copyFileSync(file, `${file}.1`);
+  fs.chmodSync(`${file}.1`, 0o600);
+  fs.truncateSync(file, 0);
+  return true;
+}
+
+export class Stopping extends ServiceError {}
+
+/**
+ * SIGTERM/SIGINT: stop taking new work, drain in-flight work until `deadline` seconds, then hand
+ * over with `onStop(drained)`. A hand-over that never settles is cut by a hard exit
+ * (EXIT_HARD_STOP) `grace` seconds later.
+ *
+ *   const drain = new Drain().install((drained) => server.close(() => process.exit(0)),
+ *     { onStopping: () => log.append('service.stopping', 'info', 'Stopping.') });
+ *   await drain.work(async () => { ... });   // rejects with Stopping once a stop has begun
+ */
+export class Drain {
+  constructor({ deadline = DRAIN_SECONDS, grace = DRAIN_GRACE_SECONDS } = {}) {
+    this.deadline = deadline;
+    this.grace = grace;
+    this.inflight = 0;
+    this.stopping = false;
+    this.waiters = new Set();
+  }
+
+  async work(fn) {
+    if (this.stopping) throw new Stopping('The service is stopping and takes no new work.');
+    this.inflight += 1;
+    try {
+      return await fn();
+    } finally {
+      this.inflight -= 1;
+      if (this.inflight === 0) for (const wake of this.waiters) wake();
+    }
+  }
+
+  /** Refuse new work from now on; false when a stop had already begun. */
+  requestStop() {
+    if (this.stopping) return false;
+    this.stopping = true;
+    return true;
+  }
+
+  /** Resolves true when in-flight work finished inside `timeoutSeconds`, false otherwise. */
+  wait(timeoutSeconds) {
+    if (this.inflight === 0) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const wake = () => { clearTimeout(timer); this.waiters.delete(wake); resolve(true); };
+      const timer = setTimeout(() => { this.waiters.delete(wake); resolve(false); }, timeoutSeconds * 1000);
+      this.waiters.add(wake);
+    });
+  }
+
+  install(onStop, { onStopping, signals = ['SIGTERM', 'SIGINT'] } = {}) {
+    const handler = () => {
+      if (!this.requestStop()) return; // a second signal changes nothing: the hard exit holds the deadline
+      setTimeout(() => process.exit(EXIT_HARD_STOP), (this.deadline + this.grace) * 1000).unref();
+      (async () => {
+        try { await onStopping?.(); } catch (error) { process.stderr.write(`${error?.stack ?? error}\n`); }
+        await onStop(await this.wait(this.deadline));
+      })();
+    };
+    for (const signal of signals) process.on(signal, handler);
+    return this;
+  }
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-openrouter.mjs

@@ -0,0 +1,335 @@
+// OpenRouter chat completions for a service: its own key, a spend ceiling checked before every attempt, a usage receipt
+// for every answered call, and a fallback model of another vendor. The twin of fabric_openrouter.py: the same rules, the
+// same cases (test/fixtures/kit-openrouter-cases.json); the rules are written out in that file's docstring.
+//
+//   const client = new Client({ ceilingUsd: 2, ledger: new JsonlUsageLedger(file), prices: pricesFromCatalog(catalog) });
+//   const answer = await client.chat([{ role: 'user', content: '...' }],
+//     { model: 'deepseek/deepseek-v4.1-flash', fallback: 'qwen/qwen3.8-flash', maxTokens: 800 });
+//   answer.content, answer.receipt.costUsd
+//
+// The key is read from the environment variable `keyEnv` names when a call is made, sent only in the Authorization
+// header, never in an error. Before every attempt the window's spend (ledger receipts of the UTC day or month, plus
+// calls in flight) plus this attempt's worst case (one token per two UTF-8 bytes of the messages as JSON, maxTokens of
+// output, at the model's price) must stay within the ceiling. A 200 records one receipt; stop or tool_calls with
+// content is an answer; error is retried on the model; length, content_filter and empty go to the fallback; 408, 429,
+// 5xx and connection errors are retried within one deadline; 401, 402 and 403 stop at once. Attribution is off unless a
+// setting is given (FAC-SEM-098). Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+
+import * as http from './fabric-http.mjs';
+import { isObject } from './fabric-jsvalue.mjs';
+import * as time from './fabric-time.mjs';
+import { attributionHeaders, makeUsageReceipt } from './fabric-usage.mjs';
+
+export const BASE_URL = 'https://openrouter.ai/api/v1';
+export const ANSWERED = Object.freeze(['stop', 'tool_calls']);
+const STOP_AT_ONCE = { 401: 'auth', 402: 'payment', 403: 'auth' };
+const RESERVED_PARAMS = ['model', 'messages', 'max_tokens', 'max_completion_tokens', 'maxTokens', 'stream', 'usage'];
+// Params that change what a call is billed for (other models, plugins, web search): the ceiling could not bound them.
+const UNBOUNDED_PARAMS = ['models', 'route', 'plugins', 'web_search_options', 'n'];
+
+export class OpenRouterError extends Error {
+  constructor(message, { kind, attempts = [] } = {}) {
+    super(message);
+    this.name = 'OpenRouterError';
+    this.kind = kind; // config, unpriced, ceiling, auth, payment, failed
+    this.attempts = [...attempts];
+  }
+}
+
+export const vendor = (model) => (String(model).includes('/') ? String(model).split('/', 1)[0] : '');
+
+const DECIMAL = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?$/;
+
+// A catalog price (a plain decimal string such as "0.000001", or a number) or null: blank, hex, a list, negative or
+// not finite are null, exactly as fabric_openrouter.py reads them.
+function price(value) {
+  let n;
+  if (typeof value === 'string') n = DECIMAL.test(value) ? Number(value) : Number.NaN;
+  else if (typeof value === 'number') n = value;
+  else return null;
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+const count = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : null); // as fabric_openrouter.py: 0 to 2**53 - 1
+
+// Every message's content is text: a string, null, or parts that are all {type: 'text'}. An image, audio or file part is
+// billed in ways a byte count cannot bound, so the client does not send it.
+function textOnly(messages) {
+  return messages.every((m) => isObject(m) && (m.content === null || m.content === undefined || typeof m.content === 'string'
+    || (Array.isArray(m.content) && m.content.every((p) => isObject(p) && p.type === 'text'))));
+}
+
+// {model: {prompt, completion, request}} in USD per token (per request) from GET /api/v1/models; a model without a
+// readable prompt or completion price is left out, so the client refuses it rather than guessing.
+export function pricesFromCatalog(catalog) {
+  const out = {};
+  const rows = isObject(catalog) && Array.isArray(catalog.data) ? catalog.data : [];
+  for (const row of rows) {
+    if (!isObject(row) || typeof row.id !== 'string') continue;
+    const pricing = isObject(row.pricing) ? row.pricing : {};
+    const prompt = price(pricing.prompt);
+    const completion = price(pricing.completion);
+    if (prompt === null || completion === null) continue;
+    out[row.id] = { prompt, completion, request: price(pricing.request) ?? 0 };
+  }
+  return out;
+}
+
+// One token per two UTF-8 bytes of what is sent as compact JSON: the messages and every param, all billed as input.
+export const promptTokensBound = (value) => Math.ceil(http.jsonBytes(value).length / 2);
+
+function checkAttribution(projectId, taskRunId) {
+  try {
+    makeUsageReceipt('openrouter', 'check', { inputTokens: 0, outputTokens: 0, projectId, taskRunId });
+  } catch (err) {
+    throw new OpenRouterError(err.message, { kind: 'config' });
+  }
+}
+
+export class Client {
+  constructor({ ceilingUsd, ledger, prices, keyEnv = 'OPENROUTER_API_KEY', window = 'day', baseUrl = BASE_URL,
+    attribution = null, projectId, unmeasuredCallUsd = null, deadlineS = 120, retries = 1, env = process.env,
+    transport, sleep, clock = () => performance.now() / 1000, now = () => Date.now() / 1000, rand = Math.random } = {}) {
+    if (typeof ceilingUsd !== 'number' || !Number.isFinite(ceilingUsd) || ceilingUsd < 0) {
+      throw new OpenRouterError('ceilingUsd is a finite number of dollars, 0 or more', { kind: 'config' });
+    }
+    if (!['day', 'month'].includes(window)) throw new OpenRouterError('window is day or month (UTC)', { kind: 'config' });
+    if (!ledger || typeof ledger.record !== 'function' || typeof ledger.receipts !== 'function') {
+      throw new OpenRouterError('ledger has record(receipt) and receipts(), as JsonlUsageLedger', { kind: 'config' });
+    }
+    if (!Number.isInteger(retries) || retries < 0 || retries > 5) {
+      throw new OpenRouterError('retries is an integer from 0 to 5', { kind: 'config' });
+    }
+    http.checkUrl(baseUrl);
+    checkAttribution(projectId, undefined);
+    Object.assign(this, { ceilingUsd, ledger, keyEnv, window, attribution, projectId, unmeasuredCallUsd, deadlineS, retries });
+    this.prices = Object.fromEntries(Object.entries(prices ?? {}).map(([k, v]) => [k, { ...v }]));
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.env = env;
+    this.transport = transport;
+    this.sleep = sleep ?? ((s) => new Promise((resolve) => setTimeout(resolve, s * 1000)));
+    this.clock = clock;
+    this.now = now;
+    this.rand = rand;
+    this.inFlight = 0;
+    this.unmeasuredWorst = new Map(); // `${at} ${model}` of an unmeasured receipt -> that attempt's worst case
+  }
+
+  priced(model) {
+    const p = this.prices[model];
+    if (!isObject(p)) return null;
+    const prompt = price(p.prompt);
+    const completion = price(p.completion);
+    if (prompt === null || completion === null) return null;
+    return { prompt, completion, request: price(p.request) ?? 0 };
+  }
+
+  worstCaseUsd(model, messages, maxTokens, params = {}) {
+    const p = this.priced(model);
+    if (p === null) return null;
+    return promptTokensBound({ ...params, messages }) * p.prompt + maxTokens * p.completion + p.request;
+  }
+
+  inWindow(at, today) {
+    const ms = time.parseRfc3339Ms(at);
+    if (Number.isNaN(ms)) return false;
+    const day = time.utcDay(ms);
+    return this.window === 'day' ? day === today : day.slice(0, 7) === today.slice(0, 7);
+  }
+
+  spentUsd({ unmeasuredUsd = 0 } = {}) {
+    const today = time.utcDay(this.now() * 1000);
+    let total = 0;
+    for (const r of this.ledger.receipts()) {
+      if (!isObject(r) || !this.inWindow(r.at, today)) continue;
+      if (typeof r.costUsd === 'number' && price(r.costUsd) !== null) total += r.costUsd;
+      else total += this.unmeasuredWorst.get(`${r.at} ${r.model}`) ?? unmeasuredUsd; // known here, else unmeasuredUsd
+    }
+    return total;
+  }
+
+  reserve(model, messages, maxTokens, params) {
+    const worst = this.worstCaseUsd(model, messages, maxTokens, params);
+    if (worst === null) {
+      throw new OpenRouterError(`${model} has no price: its spend cannot be bounded, so it is not called`, { kind: 'unpriced' });
+    }
+    const unmeasured = this.unmeasuredCallUsd === null ? worst : Number(this.unmeasuredCallUsd);
+    const spent = this.spentUsd({ unmeasuredUsd: unmeasured }) + this.inFlight;
+    if (spent + worst > this.ceilingUsd) {
+      throw new OpenRouterError(`the ${this.window} ceiling of $${this.ceilingUsd.toFixed(4)} would be passed: spent `
+        + `$${spent.toFixed(4)}, this attempt up to $${worst.toFixed(4)}`, { kind: 'ceiling' });
+    }
+    this.inFlight += worst; // synchronous with the check: no other call can pass between them
+    return worst;
+  }
+
+  release(amount) { this.inFlight = Math.max(0, this.inFlight - amount); }
+
+  receipt(asked, body, taskRunId, worst) {
+    const served = typeof body.model === 'string' && body.model.trim() ? body.model : asked;
+    const usage = isObject(body.usage) ? body.usage : null;
+    const common = { at: time.formatRfc3339(Math.trunc(this.now() * 1000)), route: 'key', projectId: this.projectId, taskRunId };
+    const prompt = usage ? count(usage.prompt_tokens) : null;
+    const completion = usage ? count(usage.completion_tokens) : null;
+    if (prompt === null || completion === null) {
+      const unmeasured = makeUsageReceipt('openrouter', served.slice(0, 128), { inputTokens: 0, outputTokens: 0, tokensMeasured: false, ...common });
+      this.rememberUnmeasured(unmeasured, worst);
+      return unmeasured;
+    }
+    const details = isObject(usage.prompt_tokens_details) ? usage.prompt_tokens_details : {};
+    const cached = count(details.cached_tokens) ?? 0;
+    const written = count(details.cache_write_tokens) ?? 0;
+    let cost = typeof usage.cost === 'number' ? price(usage.cost) : null;
+    let basis = 'provider';
+    if (cost === null) {
+      const p = this.priced(served) ?? this.priced(asked);
+      if (p) { cost = prompt * p.prompt + completion * p.completion; basis = 'price-list'; }
+    }
+    return makeUsageReceipt('openrouter', served.slice(0, 128), {
+      inputTokens: Math.max(0, prompt - cached - written), outputTokens: completion, cacheReadTokens: cached,
+      cacheWriteTokens: written, costUsd: cost, costBasis: cost === null ? undefined : basis, ...common,
+    });
+  }
+
+  // A receipt for an attempt that may have been billed with no usage to read: no tokens, no cost.
+  unmeasured(asked, taskRunId, worst) {
+    const receipt = makeUsageReceipt('openrouter', asked.slice(0, 128), { inputTokens: 0, outputTokens: 0, tokensMeasured: false,
+      at: time.formatRfc3339(Math.trunc(this.now() * 1000)), route: 'key', projectId: this.projectId, taskRunId });
+    this.rememberUnmeasured(receipt, worst);
+    return receipt;
+  }
+
+  rememberUnmeasured(receipt, worst) {
+    const key = `${receipt.at} ${receipt.model}`;
+    this.unmeasuredWorst.set(key, (this.unmeasuredWorst.get(key) ?? 0) + worst);
+  }
+
+  key() {
+    const key = this.env[this.keyEnv] ?? '';
+    if (!key || /[\r\n\0 ]/.test(key)) throw new OpenRouterError(`no usable key in the environment variable ${this.keyEnv}`, { kind: 'config' });
+    return key;
+  }
+
+  headers(key) {
+    const headers = { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' };
+    if (this.attribution !== null) {
+      Object.assign(headers, attributionHeaders(this.attribution, { url: this.baseUrl, originated: true, headers: {} }).headers);
+    }
+    return headers;
+  }
+
+  async chat(messages, { model, fallback, maxTokens, taskRunId, ...params } = {}) {
+    if (!Array.isArray(messages) || messages.length === 0) throw new OpenRouterError('messages is a non-empty list', { kind: 'config' });
+    if (!textOnly(messages)) {
+      throw new OpenRouterError('only text content is sent: an image, audio or file part has a cost the ceiling cannot bound', { kind: 'config' });
+    }
+    if (!vendor(model) || !vendor(fallback) || vendor(model) === vendor(fallback)) {
+      throw new OpenRouterError(`the fallback is a model of another vendor than ${model}`, { kind: 'config' });
+    }
+    if (!Number.isInteger(maxTokens) || maxTokens < 1 || maxTokens > 200_000) {
+      throw new OpenRouterError('maxTokens is an integer from 1 to 200000', { kind: 'config' });
+    }
+    checkAttribution(this.projectId, taskRunId); // before anything is sent: a billed call keeps its receipt
+    const clash = Object.keys(params).filter((k) => RESERVED_PARAMS.includes(k));
+    if (clash.length) throw new OpenRouterError(`the client sets ${clash.sort().join(', ')} itself`, { kind: 'config' });
+    const unbounded = Object.keys(params).filter((k) => UNBOUNDED_PARAMS.includes(k));
+    if (unbounded.length) {
+      throw new OpenRouterError(`${unbounded.sort().join(', ')} change what a call is billed for; the ceiling cannot bound them`, { kind: 'config' });
+    }
+    try {
+      promptTokensBound({ ...params, messages });
+    } catch {
+      throw new OpenRouterError('the request holds a number JSON cannot write (NaN or Infinity)', { kind: 'config' });
+    }
+    const headers = this.headers(this.key());
+    const url = `${this.baseUrl}/chat/completions`;
+    const end = this.clock() + this.deadlineS;
+    const attempts = [];
+    for (const current of [model, fallback]) {
+      const body = { model: current, messages, max_tokens: maxTokens, usage: { include: true }, ...params };
+      for (let tried = 0; tried <= this.retries; tried += 1) {
+        const left = end - this.clock();
+        if (left <= 0) throw new OpenRouterError(`the deadline passed after ${attempts.length} attempts`, { kind: 'failed', attempts });
+        let held;
+        try {
+          held = this.reserve(current, messages, maxTokens, params);
+        } catch (err) {
+          err.attempts = [...attempts];
+          throw err;
+        }
+        let result;
+        try {
+          result = await this.attempt(url, headers, body, left, current, taskRunId, held);
+        } finally {
+          this.release(held);
+        }
+        attempts.push({ model: current, status: result.status, outcome: result.outcome });
+        if (result.answer) return { ...result.answer, attempts };
+        if (Object.values(STOP_AT_ONCE).includes(result.outcome)) {
+          throw new OpenRouterError(`OpenRouter refused the key or the request (${result.status})`, { kind: result.outcome, attempts });
+        }
+        if (!['retry', 'error'].includes(result.outcome) || tried === this.retries) break;
+        const wait = result.wait ?? http.backoffS(tried, { baseS: 0.5, maxS: 8, rand: this.rand() });
+        if (this.clock() + wait >= end) break;
+        await this.sleep(wait);
+      }
+    }
+    throw new OpenRouterError(`no answer from ${model} or ${fallback}`, { kind: 'failed', attempts });
+  }
+
+  async attempt(url, headers, body, left, asked, taskRunId, worst) {
+    let response;
+    try {
+      response = await http.request('POST', url, { headers, body, deadlineS: left, retries: 0, transport: this.transport, clock: this.clock });
+    } catch (err) {
+      if (!(err instanceof http.HttpError)) throw err;
+      if (['timeout', 'connection'].includes(err.kind) || (err.kind === 'too-large' && err.status === 200)) {
+        // may have been billed (a cut connection looks like a refused one from here): counted, never as $0
+        this.ledger.record(this.unmeasured(asked, taskRunId, worst));
+      }
+      return { outcome: ['connection', 'timeout'].includes(err.kind) ? 'retry' : 'refused', status: err.status };
+    }
+    const { status } = response;
+    if (STOP_AT_ONCE[status]) return { outcome: STOP_AT_ONCE[status], status };
+    if (status !== 200) {
+      if (http.RETRY_STATUSES.includes(status)) return { outcome: 'retry', status, wait: http.retryAfterS(response.headers['retry-after'] ?? null) };
+      return { outcome: 'refused', status };
+    }
+    let parsed = null;
+    try { parsed = response.json(); } catch { /* read as no answer below */ }
+    if (!isObject(parsed)) {
+      this.ledger.record(this.unmeasured(asked, taskRunId, worst));
+      return { outcome: 'bad-answer', status };
+    }
+    let receipt;
+    try {
+      receipt = this.receipt(asked, parsed, taskRunId, worst);
+    } catch {
+      this.ledger.record(this.unmeasured(asked, taskRunId, worst)); // a billed answer it cannot read still counts
+      return { outcome: 'bad-answer', status };
+    }
+    this.ledger.record(receipt);
+    const choice = Array.isArray(parsed.choices) && isObject(parsed.choices[0]) ? parsed.choices[0] : {};
+    const message = isObject(choice.message) ? choice.message : {};
+    const finish = choice.finish_reason;
+    const content = typeof message.content === 'string' ? message.content : '';
+    const tools = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+    if (finish === 'error' || isObject(parsed.error)) return { outcome: 'error', status };
+    if (finish === 'length') return { outcome: 'length', status };
+    if (finish === 'content_filter') return { outcome: 'filtered', status };
+    if (!ANSWERED.includes(finish) || !(content.trim() || tools.length)) return { outcome: 'empty', status };
+    return { outcome: 'answered', status, answer: { content, message, model: receipt.model, finishReason: finish, receipt } };
+  }
+}
+
+// Calls, priced spend and unpriced calls over receipts; spentUsd is null when every call is unpriced.
+export function totals(receipts) {
+  let calls = 0;
+  let priced = 0;
+  let spent = 0;
+  for (const r of receipts) {
+    calls += 1;
+    if (typeof r.costUsd === 'number' && price(r.costUsd) !== null) { priced += 1; spent += r.costUsd; }
+  }
+  return { calls, spentUsd: priced ? spent : null, unpricedCalls: calls - priced };
+}