@relayflows/sdk 2.0.36 → 2.0.37

package/src/decimal-dollars.ts

@@ -0,0 +1,38 @@
+// Exact decimal-dollar arithmetic shared by the journal folds.
+
+/**
+ * Sum two decimal dollar strings exactly, at whatever scale they carry — the
+ * kernel's budget fold (`relayflowd-core/src/state/budget.rs`) aligns every
+ * fractional digit before adding, and it accepts arbitrary precision. Scaling
+ * to a fixed six fractional digits dropped a charge of `0.0000001` to zero, so
+ * `flows status` underreported spend the kernel had totalled exactly.
+ *
+ * A value that is not a decimal number is left out of the sum rather than
+ * counted as zero, and the caller is told by `malformed`.
+ */
+export function addDollars(left: string, right: string): string {
+  const parsed = [left, right].map((value) => /^\d+(?:\.\d+)?$/.test(value) ? value : null);
+  const usable = parsed.filter((value): value is string => value !== null);
+  if (usable.length === 0) return '0';
+  if (usable.length === 1) return normalizeDollars(usable[0]!);
+  const scale = Math.max(...usable.map((value) => (value.split('.')[1] ?? '').length));
+  const scaled = usable.map((value) => {
+    const [whole, fraction = ''] = value.split('.');
+    return BigInt(`${whole}${fraction.padEnd(scale, '0')}`);
+  });
+  return fromScaled(scaled[0]! + scaled[1]!, scale);
+}
+
+/** `12.3400` -> `12.34`, `0.000` -> `0`; the journal's own spelling otherwise. */
+function normalizeDollars(value: string): string {
+  const [whole, fraction = ''] = value.split('.');
+  return fromScaled(BigInt(`${whole}${fraction}`), fraction.length);
+}
+
+function fromScaled(total: bigint, scale: number): string {
+  if (scale === 0) return String(total);
+  const digits = String(total).padStart(scale + 1, '0');
+  const whole = digits.slice(0, digits.length - scale);
+  const fraction = digits.slice(digits.length - scale).replace(/0+$/, '');
+  return fraction.length === 0 ? whole : `${whole}.${fraction}`;
+}

package/src/effect-channel.ts

@@ -4,6 +4,7 @@ import type { JournalClient } from './journal-client.js';
 import type { StepDispatchEvent } from './protocol.js';
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import { withWorkerLease } from './worker-lease.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 import { snapshotJsonValue } from './json-value.js';
 
 /** Structural subset of Agent Relay's messages.dm; credentials stay in the client. */
@@ -93,5 +94,6 @@ export async function completeChannelPost(
         messageId, channel: call.channel, to: call.to, text: call.text },
       started_pins: dispatch.pins, end_pins: dispatch.pins,
       effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }],
+      reported_cost: NO_MODEL_COST,
     });
 }

package/src/helper-instruction.ts

@@ -0,0 +1,2 @@
+/** The instruction prefix a lowered provider helper step carries (`yaml-helpers.ts`). */
+export const HELPER_INSTRUCTION_PREFIX = 'relayflows:helper:v1\n';

package/src/journal-client.ts

@@ -13,7 +13,7 @@ import { EventEmitter } from 'node:events';
 export { walkJournal, JournalReadError, type JournalEvent, type JournalReadFailure } from './journal-reader.js';
 import { randomUUID } from 'node:crypto';
 import { createConnection, type Socket } from 'node:net';
-import type { VerbContract, EventEmitParams, EventSubmitParams } from './protocol.js';
+import type { VerbContract, EventEmitParams, EventSubmitParams, ReportedCost } from './protocol.js';
 import {
   PROTOCOL_VERSION,
   type CompletionReason,
@@ -61,6 +61,8 @@ export class JournalProtocolError extends Error {
 }
 
 export class JournalClient extends EventEmitter {
+  /** Additive request capabilities the daemon advertised at `hello`; none until then. */
+  private features: ReadonlySet<string> = new Set();
   private socket: Socket | null = null;
   /** Why the connection ended, so a later "not connected" names its cause rather than hiding it. */
   private disconnectCause: Error | undefined;
@@ -215,9 +217,11 @@ export class JournalClient extends EventEmitter {
 
   // --- Typed verb methods (gate 1 minimal set, kernel DESIGN.md §5) --------
 
-  /** Handshake; version mismatch is a hard error. */
-  hello(client: string): Promise<VerbContract['hello']['result']> {
-    return this.request('hello', { protocol: PROTOCOL_VERSION, client });
+  /** Handshake; version mismatch is a hard error. Records the daemon's additive features. */
+  async hello(client: string): Promise<VerbContract['hello']['result']> {
+    const result = await this.request('hello', { protocol: PROTOCOL_VERSION, client });
+    this.features = new Set(Array.isArray(result.features) ? result.features.filter(f => typeof f === 'string') : []);
+    return result;
   }
 
   /**
@@ -403,15 +407,20 @@ export class JournalClient extends EventEmitter {
       effects?: EffectRef[];
       trajectory_tail?: unknown;
       human_intervention?: boolean;
+      reported_cost?: ReportedCost;
     } = {},
   ): Promise<VerbContract['step.complete']['result']> {
+    // `reported_cost` is display-only, and a daemon that predates it refuses
+    // unknown completion fields: drop it rather than fail the completion.
+    const { reported_cost: reportedCost, ...rest } = extra;
     return this.request('step.complete', {
       run_id: runId,
       step_id: stepId,
       attempt,
       idempotency_key: idempotencyKey,
       completionReason,
-      ...extra,
+      ...rest,
+      ...(reportedCost !== undefined && this.features.has('reported_cost') ? { reported_cost: reportedCost } : {}),
     }, null).catch(error => {
       if (error instanceof JournalProtocolError) error.verb = 'step.complete';
       throw error;

package/src/llm-worker.ts

@@ -1,4 +1,5 @@
 import { workerSpend } from './worker-spend.js';
+import { reportedCost } from './reported-cost.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
@@ -22,6 +23,7 @@ export class LlmWorker extends EventEmitter {
     private readonly client: JournalClient,
     private readonly workerId: string,
     private readonly capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
+    private readonly environment?: NodeJS.ProcessEnv,
   ) {
     super();
   }
@@ -59,9 +61,11 @@ export class LlmWorker extends EventEmitter {
     const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.prompt === 'string'
-        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm')
+        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm',
+          undefined, undefined, 'direct', undefined, this.environment)
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
+    const cost = reportedCost(completed, effectiveModel);
     let reason: CompletionReason = result.exit_code === 0 ? 'success' : 'worker_error';
     let output: unknown = result.stdout_tail;
     let detail = result.stderr_tail;
@@ -94,6 +98,7 @@ export class LlmWorker extends EventEmitter {
       dispatch.idempotency_key, reason, {
         output,
         ...(usage !== undefined ? { usage } : {}),
+        ...(cost === undefined ? {} : { reported_cost: cost }),
         ...(Object.keys(trajectoryTail).length === 0 ? {} : { trajectory_tail: trajectoryTail }),
       });
   }

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

@@ -15,6 +15,7 @@ export async function attachLocalAgent(
   capacity: number = DEFAULT_LOCAL_AGENT_CAPACITY,
   runRoot?: string,
   declaredStreams: readonly string[] = [],
+  environment?: NodeJS.ProcessEnv,
 ): Promise<{
   stream: string;
   readonly failure: unknown;
@@ -31,7 +32,7 @@ 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,
+    dataDir, onPtyReady, runRoot, environment,
     pins: { workspace: [], streams: [...new Set([stream, ...declaredStreams])]
       .map(stream => ({ stream, read_offset: 0 })) },
   });

package/src/protocol.ts

@@ -79,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 {
@@ -97,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 };
@@ -342,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;
 

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')}`;
+}

package/src/run-state.ts

@@ -10,8 +10,13 @@
 // No I/O, no clock: the caller passes `now_ms`, so a test folds a hand-built
 // journal against a fixed instant and asserts exact elapsed and overdue values.
 
+import { addDollars } from './decimal-dollars.js';
+import { addReportedCost, modelFreeSteps, NO_REPORTED_COST, type ReportedCostTotal } from './reported-cost-total.js';
 import type { JournalEvent } from './journal-reader.js';
 
+export { addDollars } from './decimal-dollars.js';
+export type { ReportedCostTotal } from './reported-cost-total.js';
+
 export type RunStatus = 'running' | 'parked' | 'completed' | 'failed' | 'cancelling' | 'cancelled';
 
 /** `StepState` variant names from state.rs, snake_case. */
@@ -25,6 +30,7 @@ export interface Spend {
   dollars_unmetered: boolean;
 }
 
+
 export interface StepCounts {
   total: number;
   done: number;
@@ -91,6 +97,10 @@ export interface StepView {
   completion_reason: string | null;
   /** Paths the worker journaled for the last attempt, when its output carried them. */
   artifacts: { paths: string[]; journaled: boolean };
+  /** Metered charges of this step's attempts: what counted toward the budget. */
+  spend: Spend;
+  /** Actual cost of this step's attempts. Null until an attempt completes. */
+  reported_cost: ReportedCostTotal | null;
 }
 
 export interface RunView {
@@ -101,6 +111,8 @@ export interface RunView {
   spawned_at_ms: number;
   now_ms: number;
   spend: Spend;
+  /** Actual cost of this run's own attempts; see {@link ReportedCostTotal}. */
+  reported_cost: ReportedCostTotal;
   counts: StepCounts;
   steps: StepView[];
 }
@@ -127,42 +139,6 @@ function text(value: unknown, fallback = ''): string {
   return typeof value === 'string' ? value : fallback;
 }
 
-/**
- * Sum two decimal dollar strings exactly, at whatever scale they carry — the
- * kernel's budget fold (`relayflowd-core/src/state/budget.rs`) aligns every
- * fractional digit before adding, and it accepts arbitrary precision. Scaling
- * to a fixed six fractional digits dropped a charge of `0.0000001` to zero, so
- * `flows status` underreported spend the kernel had totalled exactly.
- *
- * A value that is not a decimal number is left out of the sum rather than
- * counted as zero, and the caller is told by `malformed`.
- */
-export function addDollars(left: string, right: string): string {
-  const parsed = [left, right].map((value) => /^\d+(?:\.\d+)?$/.test(value) ? value : null);
-  const usable = parsed.filter((value): value is string => value !== null);
-  if (usable.length === 0) return '0';
-  if (usable.length === 1) return normalizeDollars(usable[0]!);
-  const scale = Math.max(...usable.map((value) => (value.split('.')[1] ?? '').length));
-  const scaled = usable.map((value) => {
-    const [whole, fraction = ''] = value.split('.');
-    return BigInt(`${whole}${fraction.padEnd(scale, '0')}`);
-  });
-  return fromScaled(scaled[0]! + scaled[1]!, scale);
-}
-
-/** `12.3400` -> `12.34`, `0.000` -> `0`; the journal's own spelling otherwise. */
-function normalizeDollars(value: string): string {
-  const [whole, fraction = ''] = value.split('.');
-  return fromScaled(BigInt(`${whole}${fraction}`), fraction.length);
-}
-
-function fromScaled(total: bigint, scale: number): string {
-  if (scale === 0) return String(total);
-  const digits = String(total).padStart(scale + 1, '0');
-  const whole = digits.slice(0, digits.length - scale);
-  const fraction = digits.slice(digits.length - scale).replace(/0+$/, '');
-  return fraction.length === 0 ? whole : `${whole}.${fraction}`;
-}
 
 /**
  * Reduce `trajectory_tail.transcript` (the digest flows#491 journals) to the
@@ -209,6 +185,7 @@ function addSpend(total: Spend, charge: unknown): Spend {
 
 const ZERO_SPEND: Spend = { tokens_in: 0, tokens_out: 0, dollars: '0', dollars_unmetered: false };
 
+
 interface StepFold {
   view: StepView;
   depends_on: string[];
@@ -221,6 +198,7 @@ function freshStep(id: string, type: string, maxIterations: number | null, depen
       id, type, state: 'pending', attempt: 0, max_iterations: maxIterations,
       started_at_ms: null, elapsed_ms: null, lease: null, backoff_until_ms: null, wait: null,
       last_attempt: null, completion_reason: null, artifacts: { paths: [], journaled: false },
+      spend: ZERO_SPEND, reported_cost: null,
     },
   };
 }
@@ -268,6 +246,8 @@ export function foldRunState(events: readonly JournalEvent[], now_ms: number): R
   // An authored child run carries its parent's totals so ceilings hold across
   // the family (state.rs `prior_spend`); the view reports the same running total.
   let spend = addSpend(ZERO_SPEND, budget['prior_spend']);
+  let reportedCost = NO_REPORTED_COST;
+  const modelFree = modelFreeSteps(first);
   let completion: string | null = null;
   let cancelRequested = false;
 
@@ -297,6 +277,9 @@ export function foldRunState(events: readonly JournalEvent[], now_ms: number): R
         const attempt = event.attempt ?? view.attempt;
         view.attempt = Math.max(view.attempt, attempt);
         spend = addSpend(spend, payload['budget']);
+        view.spend = addSpend(view.spend, payload['budget']);
+        reportedCost = addReportedCost(reportedCost, payload, modelFree.has(view.id));
+        view.reported_cost = addReportedCost(view.reported_cost ?? NO_REPORTED_COST, payload, modelFree.has(view.id));
         const verification = payload['verification'] !== null && typeof payload['verification'] === 'object'
           ? payload['verification'] as Payload : undefined;
         view.last_attempt = {
@@ -362,8 +345,12 @@ export function foldRunState(events: readonly JournalEvent[], now_ms: number): R
         // A new epoch restarts every step (state.rs `apply_epoch`); the
         // summary then restores the ones it carries forward.
         for (const step of steps.values()) {
-          const { id, type, max_iterations } = step.view;
+          const { id, type, max_iterations, spend: stepSpend, reported_cost: stepCost } = step.view;
           step.view = freshStep(id, type, max_iterations, step.depends_on).view;
+          // Rollover keeps the earlier segments' completions in the journal,
+          // and this fold has already read them: what the step cost stays.
+          step.view.spend = stepSpend;
+          step.view.reported_cost = stepCost;
         }
         spend = addSpend(ZERO_SPEND, payload['budget_spent']);
         const done = payload['steps_done'] !== null && typeof payload['steps_done'] === 'object' ? payload['steps_done'] as Payload : {};
@@ -462,6 +449,7 @@ export function foldRunState(events: readonly JournalEvent[], now_ms: number): R
     spawned_at_ms: first.at_ms,
     now_ms,
     spend,
+    reported_cost: reportedCost,
     counts,
     steps: views,
   };

package/src/worker-cli.ts

@@ -91,6 +91,7 @@ export async function runAgentCli(
   cwd?: string,
   transport: AgentTransport = 'direct',
   relayContext?: AgentRelayContext,
+  processEnvironment: NodeJS.ProcessEnv = process.env,
 ): Promise<WorkerCliResult> {
   signal?.throwIfAborted();
   if (signal !== undefined && process.platform === 'win32') {
@@ -134,7 +135,7 @@ export async function runAgentCli(
   if (kind === 'relayflows-wrapper-v1') {
     // The closed allowlist admits no ambient RELAYFLOW_* value; the four
     // discovery names are set from this dispatch, exactly as for a direct spawn.
-    const wrapperEnv = wrapperEnvironment(process.env);
+    const wrapperEnv = wrapperEnvironment(processEnvironment);
     applyStepEnvironment(wrapperEnv, sidechannel);
     return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
@@ -148,7 +149,7 @@ export async function runAgentCli(
     )), effectiveModel);
   }
 
-  const env: NodeJS.ProcessEnv = { ...process.env };
+  const env: NodeJS.ProcessEnv = { ...processEnvironment };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
   // Where this attempt's journal is, so the agent can run `flows status` on

package/src/worker.ts

@@ -1,5 +1,6 @@
 import { communicationInstruction } from './communication/spec.js';
 import { workerSpend } from './worker-spend.js';
+import { reportedCost } from './reported-cost.js';
 import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
 import type { JournalClient } from './journal-client.js';
@@ -31,6 +32,8 @@ export interface AgentWorkerOptions {
    * the root a dispatch is measured against is a value, not an assumption.
    */
   runRoot?: string;
+  /** Environment inherited by provider CLIs, including agent-only secrets. */
+  environment?: NodeJS.ProcessEnv;
 }
 
 /**
@@ -122,7 +125,8 @@ export class AgentWorker extends EventEmitter {
     if (communication) {
       if (!this.options.dataDir) throw new Error('Agent communication requires a worker data directory');
       const { completeCommunicationDispatch } = await import('./communication/worker.js');
-      await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir, this.options.runRoot);
+      await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir,
+        this.options.runRoot, this.options.environment);
       return;
     }
     let humanIntervention = false;
@@ -142,9 +146,11 @@ export class AgentWorker extends EventEmitter {
           }, cwd.directory ?? (spec.transport === 'relay' ? undefined : this.options.runRoot),
             spec.transport === 'relay' ? 'relay' : 'direct',
             { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
-              dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema })
+              dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema },
+            this.options.environment)
           : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
+    const cost = reportedCost(completed, effectiveModel);
     const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
 
     // Output shape: if the CLI's stdout parses as JSON, promote THAT
@@ -195,6 +201,7 @@ export class AgentWorker extends EventEmitter {
         ...(Object.keys(trajectoryTail).length === 0 ? {} : { trajectory_tail: trajectoryTail }),
         ...(humanIntervention ? { human_intervention: true } : {}),
         ...(usage !== undefined ? { usage } : {}),
+        ...(cost === undefined ? {} : { reported_cost: cost }),
         started_pins: dispatch.pins,
         end_pins: dispatch.pins,
       },