@relayflows/sdk 2.0.36 → 2.0.38

package/src/mcp-stdio.ts

@@ -13,8 +13,9 @@ export class McpStdioTransport implements Transport {
   onmessage?: Transport['onmessage'];
   private child?: ChildProcessWithoutNullStreams;
   private stopTree?: ChildStop;
+  private childClosed = false;
   private readonly buffer = new ReadBuffer({ maxBufferSize: 1_048_576 });
-  private closed?: Promise<void>;
+  private stopped?: Promise<void>;
   private closing?: Promise<void>;
   constructor(private readonly config: Extract<McpServerConfig, { command: string }>) {}
 
@@ -23,11 +24,24 @@ export class McpStdioTransport implements Transport {
     for (const name of this.config.env ?? []) {
       if (process.env[name] !== undefined) env[name] = process.env[name];
     }
+    const ownsGroup = process.platform !== 'win32';
     const child = this.child = spawn(this.config.command, this.config.args ?? [], {
-      env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+      env, stdio: ['pipe', 'pipe', 'pipe'], detached: ownsGroup,
+    });
+    let resolveStopped!: () => void;
+    let rejectStopped!: (error: Error) => void;
+    this.stopped = new Promise<void>((resolve, reject) => {
+      resolveStopped = resolve;
+      rejectStopped = reject;
+    });
+    this.stopTree = childStop(child, ownsGroup, undefined, error => {
+      if (error === undefined) resolveStopped();
+      else rejectStopped(error);
+    });
+    child.once('close', () => {
+      this.childClosed = true;
+      this.stopTree?.maySettleOnChildExit();
     });
-    this.stopTree = childStop(child, process.platform !== 'win32');
-    this.closed = new Promise(resolve => child.once('close', () => resolve()));
     child.stderr.resume();
     child.stdout.on('data', (chunk: Buffer) => {
       if (this.closing) return;
@@ -63,22 +77,22 @@ export class McpStdioTransport implements Transport {
     if (!child) return;
     child.stdin.end();
     this.stopTree!.terminate();
-    // A direct-child close is insufficient: wrappers can leave descendants
-    // alive with either inherited pipes or completely detached stdio.
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const deadline = new Promise<void>(resolve => { timer = setTimeout(resolve, 1000); });
-    await Promise.race([this.closed, deadline]);
-    if (!this.stopTree!.maySettleOnChildExit()) await deadline;
-    clearTimeout(timer);
-    if (child.exitCode === null && child.signalCode === null && child.pid !== undefined) {
-      const exited = new Promise<void>(resolve => child.once('exit', () => resolve()));
-      this.stopTree!.kill();
-      await exited;
+    // `close()` may be called after the direct child already emitted close and
+    // resolved `stopped`. Refund the just-armed escalation in that case before
+    // awaiting the already-settled promise; otherwise its referenced timer can
+    // fire later against a captured, potentially reused process-group id.
+    if (this.childClosed) this.stopTree!.maySettleOnChildExit();
+    try {
+      // A direct-child close is insufficient: wrappers can leave descendants
+      // alive with either inherited pipes or completely detached stdio. The
+      // shared stop owns the bound and rejects when group death is unprovable.
+      await this.stopped;
+    } finally {
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      this.buffer.clear();
+      this.onclose?.();
     }
-    child.stdin.destroy();
-    child.stdout.destroy();
-    child.stderr.destroy();
-    this.buffer.clear();
-    this.onclose?.();
   }
 }

package/src/preflight.ts

@@ -35,6 +35,8 @@ export interface CliResolution {
 export interface CliProbeResult {
   exists: boolean;
   authenticated: boolean | 'unverified';
+  /** Absolute executable selected once for both this probe and later dispatch. */
+  executable?: string;
   /** False when a custom executable did not identify as a wrapper adapter. */
   supported?: boolean;
   /** Exact declared model passed the CLI's model-scoped readiness probe. */

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 };
@@ -233,6 +253,8 @@ export interface StepDispatchEvent {
   lease_id: string;
   idempotency_key: string;
   pins: Pins;
+  /** Remaining lease duration at dispatch; `lease_deadline_ms` stays absolute. */
+  lease_ttl_ms?: number;
   /**
    * The `wake_context` payload from the run's `subscription.matched`
    * journal entry — carries the triggering event and any epoch summary
@@ -271,6 +293,13 @@ export interface StepHeartbeatParams {
 }
 export interface StepHeartbeatResult {
   lease_deadline_ms: number;
+  /**
+   * The renewed lease as a duration on the daemon's clock. Absent from older
+   * daemons; a worker that has it times the lease on its own monotonic clock
+   * instead of comparing the absolute deadline with a wall clock that may
+   * disagree with the daemon's.
+   */
+  lease_ttl_ms?: number;
 }
 
 /** completionReason mirrors kernel DESIGN.md §1.3. */
@@ -342,6 +371,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/resolved-cli-identity.ts

@@ -0,0 +1,42 @@
+import type {
+  FlowSpec,
+  KernelAgentStep,
+  KernelLlmStep,
+  KernelStepCommon,
+  KernelStepSpec,
+} from './spec.js';
+
+interface ResolvedCliIdentityField {
+  /** Host-proved authored identity used to select the adapter for canonical CLI bytes. */
+  cli_identity?: string;
+}
+
+export type ResolvedKernelStepCommon = KernelStepCommon & ResolvedCliIdentityField;
+export type ResolvedKernelAgentStep = KernelAgentStep & ResolvedCliIdentityField;
+export type ResolvedKernelLlmStep = KernelLlmStep & ResolvedCliIdentityField;
+export type ResolvedKernelStepSpec = KernelStepSpec & ResolvedCliIdentityField;
+
+/**
+ * Host-proved CLI identities are deliberately out-of-band from the authoring
+ * schema. A flow cannot claim that a canonical `cli.js` target is Claude; only
+ * the successful preflight that resolved the authored `claude` declaration
+ * can attach that identity before kernel lowering.
+ */
+const IDENTITIES = new WeakMap<object, ReadonlyMap<string, string>>();
+
+export function resolvedCliIdentities(value: unknown): ReadonlyMap<string, string> | undefined {
+  return typeof value === 'object' && value !== null ? IDENTITIES.get(value) : undefined;
+}
+
+export function rememberResolvedCliIdentities<T extends FlowSpec>(
+  flow: T,
+  identities: ReadonlyMap<string, string>,
+): T {
+  IDENTITIES.set(flow, new Map(identities));
+  return flow;
+}
+
+export function inheritResolvedCliIdentities<T extends FlowSpec>(source: unknown, flow: T): T {
+  const identities = resolvedCliIdentities(source);
+  return identities === undefined ? flow : rememberResolvedCliIdentities(flow, identities);
+}

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,
   };