@relayflows/sdk 2.0.35 → 2.0.37

package/src/local-agent-environment.ts

@@ -0,0 +1,92 @@
+import { closeSync, readSync } from 'node:fs';
+
+/**
+ * Inherited descriptor carrying environment values that only local agent/LLM
+ * subprocesses may receive. The flows process consumes and closes it before
+ * loading authored code, so that code cannot inherit or read the credentials.
+ */
+export const LOCAL_AGENT_ENV_FD = 'FLOWS_LOCAL_AGENT_ENV_FD';
+
+const MAX_BYTES = 64 * 1024;
+const AGENT_CREDENTIAL_NAMES = new Set([
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_BASE_URL',
+  'OPENAI_API_KEY',
+  'OPENAI_BASE_URL',
+]);
+
+export function localAgentEnvironment(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv | undefined {
+  const environment = { ...base };
+  const rawFd = environment[LOCAL_AGENT_ENV_FD];
+  delete environment[LOCAL_AGENT_ENV_FD];
+  // Without the descriptor, provider launches keep their historical live
+  // process.env behavior instead of freezing an early snapshot.
+  if (rawFd === undefined) return undefined;
+  // Every later child — especially the authored runtime — inherits process.env.
+  // Remove the capability marker before any authored module can be imported.
+  if (base === process.env) delete process.env[LOCAL_AGENT_ENV_FD];
+
+  if (!/^[0-9]+$/.test(rawFd)) throw new Error(`${LOCAL_AGENT_ENV_FD} must name an inherited file descriptor`);
+  const fd = Number(rawFd);
+  if (!Number.isSafeInteger(fd) || fd < 3 || fd > 255) {
+    throw new Error(`${LOCAL_AGENT_ENV_FD} must name an inherited file descriptor`);
+  }
+
+  const chunks: Buffer[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const chunk = Buffer.allocUnsafe(Math.min(8 * 1024, MAX_BYTES + 1 - bytes));
+      const read = readSync(fd, chunk, 0, chunk.length, null);
+      if (read === 0) break;
+      bytes += read;
+      if (bytes > MAX_BYTES) throw new Error('local agent environment payload exceeds 64 KiB');
+      chunks.push(chunk.subarray(0, read));
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'local agent environment payload exceeds 64 KiB') throw error;
+    throw new Error('local agent environment payload could not be read');
+  } finally {
+    try { closeSync(fd); } catch { /* The descriptor is unusable either way. */ }
+  }
+
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8')); }
+  catch { throw new Error('local agent environment payload is not valid JSON'); }
+  if (!plainObject(parsed)) throw new Error('local agent environment payload must be an object of strings');
+  const agentEnvironment: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!AGENT_CREDENTIAL_NAMES.has(key) || typeof value !== 'string' || value.includes('\0')) {
+      throw new Error('local agent environment payload must be an object of valid environment strings');
+    }
+    if (key !== LOCAL_AGENT_ENV_FD) agentEnvironment[key] = value;
+  }
+  return { ...environment, ...agentEnvironment };
+}
+
+/** Reduce a composed provider environment to the credential overlay that is
+ * safe to serialize across the authored Node runtime boundary. */
+export function localAgentCredentialEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries([...AGENT_CREDENTIAL_NAMES]
+    .flatMap(key => environment[key] === undefined ? [] : [[key, environment[key]!]]));
+}
+
+/** Validate the parent-to-authored-runtime handoff without touching a descriptor. */
+export function validatedLocalAgentEnvironment(value: unknown): NodeJS.ProcessEnv | undefined {
+  if (value === undefined) return undefined;
+  if (!plainObject(value)) throw new Error('local agent environment payload must be an object of strings');
+  const environment: NodeJS.ProcessEnv = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!AGENT_CREDENTIAL_NAMES.has(key) || typeof entry !== 'string' || entry.includes('\0')) {
+      throw new Error('local agent environment payload must be an object of valid environment strings');
+    }
+    environment[key] = entry;
+  }
+  return environment;
+}
+
+function plainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}

package/src/local-agent.ts

@@ -2,6 +2,8 @@ import { onWorkerFailure } from './worker-lease.js';
 import { randomUUID } from 'node:crypto';
 import type { JournalClient } from './journal-client.js';
 import { AgentWorker } from './worker.js';
+import type { KernelRunSpec } from './spec.js';
+import { communicationInstruction } from './communication/spec.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 
 /** A local worker for stream-only steps; no workspace recovery is claimed. */
@@ -12,13 +14,17 @@ export async function attachLocalAgent(
   requestedStream?: string,
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
   runRoot?: string,
+  declaredStreams: readonly string[] = [],
+  environment?: NodeJS.ProcessEnv,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
   close(): Promise<void>;
 }> {
-  // A fresh, unconsumed stream has offset zero. The executor declares exactly
-  // this stream on its agent steps. No worktree revision is invented.
+  // This worker has consumed no messages: its read offsets are zero, including
+  // named declarative streams. The kernel retains ownership of dispatch pins
+  // and rejects a resume whose required offsets this worker does not hold.
+  // No worktree revision is invented.
   const stream = requestedStream ?? `local-agent-${randomUUID()}`;
   const worker = new AgentWorker(client, {
     workerId: stream,
@@ -26,8 +32,9 @@ export async function attachLocalAgent(
     // second parking behind the first. Authored bodies size their admission to
     // this same number (worker-slots.ts), so they never ask for more.
     capacity,
-    dataDir, onPtyReady, runRoot,
-    pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
+    dataDir, onPtyReady, runRoot, environment,
+    pins: { workspace: [], streams: [...new Set([stream, ...declaredStreams])]
+      .map(stream => ({ stream, read_offset: 0 })) },
   });
   let failure: unknown;
   // The cause travels with the close, so the flow's next request names it.
@@ -41,3 +48,11 @@ export async function attachLocalAgent(
     },
   };
 }
+
+/** Conversation workers own their streams and registration; do not steal their dispatches. */
+export function declaredLocalAgentStreams(spec: KernelRunSpec): string[] {
+  return [...new Set(spec.steps.flatMap(step =>
+    step.type === 'agent' && !communicationInstruction(step.instruction)
+      ? step.surfaces?.streams?.map(({ stream }) => stream) ?? []
+      : []))];
+}

package/src/preflight.ts

@@ -52,6 +52,12 @@ export interface CliProbeResult {
    * unauthenticated CLI.
    */
   authFailureDetail?: string;
+  /** Exit code of a FAILED model-scoped readiness probe. */
+  modelExitCode?: number | null;
+  /** Cause the adapter read from a failed readiness probe's output, if any. */
+  modelFailure?: import('./adapters/base.js').ModelProbeFailure;
+  /** Redacted output of a FAILED model-scoped readiness probe. */
+  modelFailureDetail?: string;
 }
 
 export type CliProbeFailureDetail =
@@ -603,17 +609,47 @@ function probeResolvedCli(
       message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}`,
     });
   } else if (resolution.model !== undefined && result.modelAvailable !== true) {
-    diagnostics.push({
-      severity: 'refusal',
-      kind: 'model_unavailable',
-      stepId: resolution.stepId,
-      cli: resolution.cli,
-      model: resolution.model,
-      message: describeEffectiveModel(resolution.stepId, resolution.model, resolution.cli, resolution.modelSource)
-        + `, but its model-scoped "${result.modelCommand ?? `${resolution.cli} auth status`}" probe exited non-zero;`
-        + ` verify the model name and this credential's access.`,
-    });
+    diagnostics.push(modelProbeRefusal(resolution as CliResolution & { model: string }, result));
+  }
+}
+
+// Only a probe whose output says the model is unknown (or the adapter gave no
+// output to read) is told to check the model name. An outdated CLI and a
+// usage-limited credential name a different remedy, and "verify the model
+// name" sends the author after a typo that is not there.
+function modelProbeRefusal(
+  resolution: CliResolution & { model: string },
+  result: CliProbeResult,
+): PreflightDiagnostic {
+  const { stepId, cli, model } = resolution;
+  const effective = describeEffectiveModel(stepId, model, cli, resolution.modelSource);
+  const command = `"${result.modelCommand ?? `${cli} auth status`}"`;
+  const exit = result.modelExitCode === undefined || result.modelExitCode === null ? '' : ` (exit ${result.modelExitCode})`;
+  const reported = result.modelFailureDetail === undefined ? '' : ` It reported: ${result.modelFailureDetail}`;
+  const base = { severity: 'refusal' as const, stepId, cli, model };
+  const cause = result.modelFailure?.cause;
+  if (cause === 'cli_outdated') {
+    const required = result.modelFailure?.requiredVersion;
+    return { ...base, kind: 'cli_outdated',
+      message: `${effective}, but this "${cli}" is too old to use that model`
+        + (required === undefined ? '' : `; version ${required} or newer is required`)
+        + `. Upgrade the CLI in the environment that runs this flow; the model name is not the problem.${reported}` };
+  }
+  if (cause === 'provider_usage_limited') {
+    return { ...base, kind: 'provider_usage_limited',
+      message: `${effective}, but the provider refused the model-scoped ${command} probe${exit} because this credential`
+        + ` has reached a usage or rate limit. Retry after the limit resets or use a credential with capacity;`
+        + ` the model name is not the problem.${reported}` };
   }
+  // A probe that printed nothing is judged on its exit code alone, which is
+  // how a wrapper refuses a model it cannot serve.
+  const unknownModel = cause === 'model_unknown' || result.modelFailureDetail === undefined;
+  return { ...base, kind: 'model_unavailable',
+    message: `${effective}, but its model-scoped ${command} probe exited non-zero${exit}`
+      + (unknownModel
+        ? `; verify the model name and this credential's access.`
+        : ` for a reason Relayflows does not recognise.`)
+      + reported };
 }
 
 function probeFailedMessage(

package/src/protocol.ts

@@ -53,8 +53,16 @@ export type Verb =
   | 'effect.confirm'
   | 'step.complete'
   | 'step.wait'
+  | 'subscription.park'
   | 'event.emit'
   | 'event.submit'
+  | 'subscription.open'
+  | 'subscription.activate'
+  | 'subscription.deliver'
+  | 'subscription.inspect'
+  | 'subscription.fence_overflow'
+  | 'subscription.next'
+  | 'subscription.close'
   | 'channel.append'
   | 'channel.receive'
   | 'channel.ack'
@@ -71,6 +79,11 @@ export interface HelloParams {
 export interface HelloResult {
   protocol: 0;
   server: string;
+  /**
+   * Additive request capabilities within protocol 0. Absent from daemons that
+   * predate it, which then accept none of the optional fields it gates.
+   */
+  features?: string[];
 }
 
 export interface StepSpend {
@@ -89,6 +102,21 @@ export interface StepSpend {
  * `dollars_unmetered: true` and no dollar amount, so unknown cost is never
  * journaled as a measured $0. See `workerSpend` for the full contract.
  */
+/**
+ * A step attempt's actual cost (`reported-cost.ts`), journaled beside the
+ * metered `usage` as `reported_cost`. Display only: the kernel never charges it
+ * against `maxDollars`.
+ */
+export interface ReportedCost {
+  /** Non-negative decimal string, six places. */
+  dollars: string;
+  /**
+   * `cli`: the CLI's own reported total. `priced`: estimated from full token
+   * usage. `no_model`: an internal effect worker completed the step; $0.
+   */
+  source: 'cli' | 'priced' | 'no_model';
+}
+
 export type StepUsage =
   | { tokens_in: number; tokens_out: number; dollars: string; dollars_unmetered?: never }
   | { tokens_in: number; tokens_out: number; dollars_unmetered: true; dollars?: never };
@@ -334,6 +362,8 @@ export interface StepCompleteParams {
   effects?: EffectRef[];
   /** `inspect` evidence for the next attempt. Rejected over 16 KiB of JSON. */
   trajectory_tail?: unknown;
+  /** Display-only actual cost; never charged to the budget. */
+  reported_cost?: ReportedCost;
 }
 export type StepCompleteResult = RunOutcome;
 
@@ -362,6 +392,10 @@ export interface EventEmitParams {
   run_id: string;
   event_key: string;
   payload: unknown;
+  /** Provider delivery id for body activities. Required by Cloud; optional for legacy exact waits. */
+  delivery_id?: string;
+  /** Provider actor identity, used by the local router adapter for self filtering. */
+  actor?: string;
 }
 export interface EventEmitResult {
   matched: number;
@@ -388,6 +422,111 @@ export interface EventSubmitResult {
   run?: unknown;
 }
 
+/** Body-level activity open; the server acknowledges only after its fenced binding is durable. */
+export interface SubscriptionOpenParams {
+  run_id: string;
+  subscription_id: string;
+  event_types: string[];
+  pattern?: Record<string, unknown>;
+  settle_ms: number;
+  idle_ms: number;
+  deadline_ms: number;
+  include_self: boolean;
+}
+export type SubscriptionOpenResult =
+  | {
+    /** Immutable snapshot from the durable `subscription.prepared` entry. */
+    state: 'prepared';
+    subscription_id: string;
+    event_types: string[];
+    pattern?: Record<string, unknown>;
+    stream: string;
+    settle_ms: number;
+    idle_ms: number;
+    deadline_at_ms: number;
+    include_self: boolean;
+  }
+  | {
+    state: 'active';
+    subscription_id: string;
+    stream: string;
+    deadline_at_ms: number;
+  };
+
+/** Cloud supplies this receipt only after it has durably fenced its binding. */
+export interface SubscriptionActivateParams {
+  run_id: string;
+  subscription_id: string;
+  ingress_offset: number;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionActivateResult {
+  state: 'active';
+  subscription_id: string;
+  stream: string;
+  deadline_at_ms: number;
+}
+
+/** Targeted Cloud ingress; receipt must equal the journaled activation receipt. */
+export interface SubscriptionDeliverParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+  delivery_id: string;
+  frame: unknown;
+}
+export interface SubscriptionDeliverResult {
+  /** False for an idempotent duplicate or a frame that closes on overflow. */
+  appended: boolean;
+  reason?: 'duplicate' | 'overflow';
+}
+
+/** Read-only projection of the kernel's durable subscription records. */
+export interface SubscriptionSnapshot {
+  subscriptionId: string;
+  state: 'prepared' | 'active' | 'closed';
+  completionReason?: 'closed' | 'run_completed' | 'canceled' | 'deadline' | 'overflow';
+  routerBinding?: Record<string, unknown>;
+  ingressOffset?: number;
+  unreadFrames: number;
+  unreadBytes: number;
+  settleMs: number;
+  idleAtMs?: number;
+  deadlineAtMs: number;
+}
+export interface SubscriptionInspectParams { run_id: string }
+export interface SubscriptionInspectResult { subscriptions: SubscriptionSnapshot[] }
+export interface SubscriptionFenceOverflowParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionFenceOverflowResult { fenced: true }
+
+export interface SubscriptionNextParams {
+  run_id: string;
+  subscription_id: string;
+  /** Internal durable receipt for the prior normal wake, supplied with the next pull. */
+  acknowledge_wait_id?: string;
+  /** Body call ordinal: replay this pull's durable wake across process restarts. */
+  sequence?: number;
+}
+export type SubscriptionNextResult =
+  | { kind: 'suspended'; subscription_id: string; stream: string; deadline_at_ms: number }
+  | { kind: 'events'; events: unknown[]; offset: number; acknowledge_wait_id?: string }
+  | { kind: 'idle'; acknowledge_wait_id?: string }
+  | { kind: 'deadline'; pending: { from: number; to: number } | null }
+  | { kind: 'overflow'; retained: number; bytes: number; from: number };
+
+export interface SubscriptionCloseParams {
+  run_id: string;
+  subscription_id: string;
+  completion_reason: 'closed' | 'run_completed' | 'canceled';
+}
+export interface SubscriptionCloseResult {
+  closed: string;
+}
+
 export interface StreamAppendParams {
   run_id: string;
   stream: string;
@@ -441,8 +580,20 @@ export interface VerbContract {
   'effect.confirm': { params: EffectConfirmParams; result: EffectConfirmResult };
   'step.complete': { params: StepCompleteParams; result: StepCompleteResult };
   'step.wait': { params: StepWaitParams; result: StepWaitResult };
+  'subscription.park': {
+    params: { run_id: string; step_id: string; attempt: number; idempotency_key: string;
+      subscription_id: string; phase: 'activation' | 'event_wait' };
+    result: RunOutcome;
+  };
   'event.emit': { params: EventEmitParams; result: EventEmitResult };
   'event.submit': { params: EventSubmitParams; result: EventSubmitResult };
+  'subscription.open': { params: SubscriptionOpenParams; result: SubscriptionOpenResult };
+  'subscription.activate': { params: SubscriptionActivateParams; result: SubscriptionActivateResult };
+  'subscription.deliver': { params: SubscriptionDeliverParams; result: SubscriptionDeliverResult };
+  'subscription.inspect': { params: SubscriptionInspectParams; result: SubscriptionInspectResult };
+  'subscription.fence_overflow': { params: SubscriptionFenceOverflowParams; result: SubscriptionFenceOverflowResult };
+  'subscription.next': { params: SubscriptionNextParams; result: SubscriptionNextResult };
+  'subscription.close': { params: SubscriptionCloseParams; result: SubscriptionCloseResult };
   'stream.append': { params: StreamAppendParams; result: StreamAppendResult };
   'stream.read': { params: StreamReadParams; result: StreamReadResult };
   'journal.read': { params: JournalReadParams; result: JournalReadResult };

package/src/reported-cost-total.ts

@@ -0,0 +1,82 @@
+// The display-only actual-cost fold beside run-state's metered spend.
+// Nothing here is enforcement: the kernel charges `budget`, never `reported_cost`.
+
+import { declaresAuthoredRoot } from './authored-verdict.js';
+import { addDollars } from './decimal-dollars.js';
+import { HELPER_INSTRUCTION_PREFIX } from './helper-instruction.js';
+import type { JournalEvent } from './journal-reader.js';
+
+type Payload = Record<string, unknown>;
+
+/**
+ * What steps actually cost, summed from each attempt's journaled
+ * `reported_cost` (the CLI's own total, or a full-usage estimate). Display
+ * only: the kernel charges `spend` against `maxDollars`, never this. `complete`
+ * is false when some completed model attempt reported no cost (e.g. Codex, or
+ * an older runtime), so `dollars` is then a lower bound. Segment rollover keeps
+ * earlier completions in the journal, so an epoch summary does not lose any.
+ */
+export interface ReportedCostTotal {
+  /** Decimal string. */
+  dollars: string;
+  complete: boolean;
+  /** Where the summed figures came from; `mixed` when attempts differ. */
+  source: 'cli' | 'priced' | 'mixed' | null;
+}
+
+/**
+ * Steps known to run no model, read from the spawned spec. Deliberately
+ * narrow: a crash-recovered or cancelled model attempt journals a default zero
+ * budget although the model ran, so metering nothing proves nothing. A step
+ * not listed here that reports no cost stays unknown, and the total reads as a
+ * lower bound rather than a false complete figure.
+ * - a deterministic step runs a command;
+ * - a provider helper (`relayflows:helper:v1`) performs a relayfile write;
+ * - the authored root runs the flow body, whose model calls are child runs with
+ *   journals of their own. Only a spec carrying the authored-root discriminator
+ *   counts: an ordinary flow may name a step `authored-root`.
+ * A memoized reuse is free too, per completion (`reused_from`): the source run
+ * paid for the model.
+ */
+export function modelFreeSteps(spawned: JournalEvent): Set<string> {
+  const payload = spawned.payload !== null && typeof spawned.payload === 'object' ? spawned.payload as Payload : {};
+  const spec = payload['spec'] !== null && typeof payload['spec'] === 'object' ? payload['spec'] as Payload : {};
+  const steps = Array.isArray(spec['steps']) ? spec['steps'] as unknown[] : [];
+  const authoredRoot = declaresAuthoredRoot(spawned);
+  const free = new Set<string>();
+  for (const entry of steps) {
+    const step = entry !== null && typeof entry === 'object' ? entry as Payload : {};
+    if (typeof step['id'] !== 'string') continue;
+    const helper = step['type'] === 'agent' && typeof step['instruction'] === 'string'
+      && step['instruction'].startsWith(HELPER_INSTRUCTION_PREFIX);
+    if (step['type'] === 'deterministic' || helper || (authoredRoot && step['id'] === 'authored-root')) free.add(step['id']);
+  }
+  return free;
+}
+
+export const NO_REPORTED_COST: ReportedCostTotal = { dollars: '0', complete: true, source: null };
+
+
+/**
+ * Add one completed attempt's journaled `reported_cost` to a total. A model
+ * attempt without one (older runtime, Codex, unpriced) leaves the sum unchanged
+ * and marks it incomplete rather than counting an unknown cost as zero.
+ */
+export function addReportedCost(total: ReportedCostTotal, completion: Payload, modelFree: boolean): ReportedCostTotal {
+  const charge = completion['reported_cost'];
+  const cost = charge !== null && typeof charge === 'object' && !Array.isArray(charge) ? charge as Payload : null;
+  const reused = completion['reused_from'] !== undefined && completion['reused_from'] !== null;
+  if (cost === null && (modelFree || reused)) return total;
+  const dollars = cost === null ? null : cost['dollars'];
+  const source = cost === null ? null : cost['source'];
+  // An internal effect worker ran no model: a known $0 that names no cost source.
+  if (source === 'no_model') return total;
+  if (typeof dollars !== 'string' || !/^\d+(?:\.\d+)?$/.test(dollars) || (source !== 'cli' && source !== 'priced')) {
+    return { ...total, complete: false };
+  }
+  return {
+    dollars: addDollars(total.dollars, dollars),
+    complete: total.complete,
+    source: total.source === null || total.source === source ? source : 'mixed',
+  };
+}

package/src/reported-cost.ts

@@ -0,0 +1,51 @@
+import { MODEL_PRICING } from './model-pricing.js';
+import type { ReportedCost } from './protocol.js';
+import type { WorkerCliResult } from './worker-cli.js';
+
+/**
+ * What a step attempt actually cost, for display. Never enforcement.
+ *
+ * The metered `usage` (`workerSpend`) is what the kernel charges against
+ * `maxDollars`, and it prices only plain input and output tokens. That
+ * undercounts cache-heavy agents badly. This is the real figure a reader wants
+ * to see, and it rides beside the metered charge as `reported_cost`: the kernel
+ * journals it and never folds it into the budget. Changing which charges count
+ * toward a cap is a separate decision, and this module takes no part in it.
+ *
+ * Sources, in order:
+ * - `cli`: the CLI's own reported total (Claude `total_cost_usd`);
+ * - `priced`: an estimate from the digest's full token usage at the frozen
+ *   `MODEL_PRICING` rates, with cache writes at 1.25x and cache reads at 0.1x
+ *   the input rate (Codex's input total already includes its cached tokens, so
+ *   they are split out, not added). Only for a model that already has a price.
+ * Otherwise undefined: an unknown cost is left unknown, never shown as $0.
+ */
+export function reportedCost(result: WorkerCliResult, model: string | undefined): ReportedCost | undefined {
+  const digest = result.transcript?.result;
+  const cli = digest?.total_cost_usd;
+  if (typeof cli === 'number' && Number.isFinite(cli) && cli >= 0) {
+    return { dollars: microDollars(BigInt(Math.round(cli * 1_000_000))), source: 'cli' };
+  }
+  const usage = digest?.usage;
+  const priceModel = digest?.model ?? model;
+  if (usage === undefined || priceModel === undefined || !Object.hasOwn(MODEL_PRICING, priceModel)) return undefined;
+  const counts = [usage.input, usage.output, usage.cache_read, usage.cache_creation].map(n => n ?? 0);
+  if (!counts.every(n => Number.isSafeInteger(n) && n >= 0)) return undefined;
+  const [reportedInput, output, cacheRead, cacheCreation] = counts.map(BigInt) as [bigint, bigint, bigint, bigint];
+  // Claude reports cache tokens beside `input_tokens`; Codex's `input_tokens`
+  // already includes its `cached_input_tokens`. Charge each token once.
+  const input = digest?.provider === 'codex'
+    ? (reportedInput > cacheRead ? reportedInput - cacheRead : 0n) : reportedInput;
+  const price = MODEL_PRICING[priceModel]!;
+  const inRate = BigInt(price.input);
+  const micro = input * inRate + output * BigInt(price.output)
+    + (cacheCreation * inRate * 125n) / 100n + (cacheRead * inRate * 10n) / 100n;
+  return { dollars: microDollars(micro), source: 'priced' };
+}
+
+/** What an internal effect worker (provider helper, plugin, MCP) reports: no model ran. */
+export const NO_MODEL_COST: ReportedCost = Object.freeze({ dollars: '0.000000', source: 'no_model' });
+
+function microDollars(micro: bigint): string {
+  return `${micro / 1_000_000n}.${String(micro % 1_000_000n).padStart(6, '0')}`;
+}