@relayflows/sdk 2.0.12 → 2.0.13

package/src/spec.ts

@@ -452,9 +452,31 @@ export interface KernelAgentStep extends KernelStepCommon {
 
 export type KernelStepSpec = KernelDeterministicStep | KernelLlmStep | KernelAgentStep;
 
+/**
+ * Accounting carried into a run that continues an earlier one. The authored
+ * executor lowers each step to its own kernel run and sends the previous run's
+ * totals here. It mirrors the kernel's `PriorSpend` field for field, so the
+ * handoff cannot quietly narrow what a carried budget can express.
+ */
+export interface KernelPriorSpend {
+  tokens_in: number;
+  tokens_out: number;
+  /** Metered dollars only; a lower bound when `dollars_unmetered` is set. */
+  dollars: string;
+  wallclock_ms: number;
+  day?: number;
+  /**
+   * At least one carried charge spent tokens of unknown dollar cost, so
+   * `dollars` is a lower bound rather than a measured total. Omitted when
+   * false, so a fully metered flow's payload keeps its exact bytes and a
+   * kernel that predates the key never receives it.
+   */
+  dollars_unmetered?: boolean;
+}
+
 export interface KernelBudgetSpec {
   pricing?: 'frozen';
-  prior_spend?: { tokens_in: number; tokens_out: number; dollars: string; wallclock_ms: number; day?: number };
+  prior_spend?: KernelPriorSpend;
   max_tokens?: number;
   max_wallclock_ms?: number;
   window?: 'day';

package/src/worker-spend.ts

@@ -1,10 +1,19 @@
 import { pricedUsage } from './model-pricing.js';
+import type { StepUsage } from './protocol.js';
 import type { WorkerCliResult } from './worker-cli.js';
 
-/** Zero-dollar usage for an unpriced step, only when the CLI reported tokens. */
-function unmeteredUsage(input: number | undefined, output: number | undefined) {
-  if (input === undefined || output === undefined) return undefined;
-  return { tokens_in: input, tokens_out: output, dollars: '0.000000' };
+/**
+ * Usage for a step whose dollar cost is unknown (unpriced or undeclared model).
+ *
+ * It carries the reported tokens and `dollars_unmetered: true`, and never a
+ * `dollars` amount: unknown cost is not journaled as a measured $0. The kernel
+ * records the flag on the step's `budget`/`spend` and on the run total, counts
+ * the tokens toward token ceilings, and compares only metered dollars against
+ * `maxDollars`. A CLI that reported no tokens still marks the step unmetered,
+ * with zero tokens — the same token accounting any unreported step gets.
+ */
+function unmeteredUsage(input: number | undefined, output: number | undefined): StepUsage {
+  return { tokens_in: input ?? 0, tokens_out: output ?? 0, dollars_unmetered: true };
 }
 
 /**
@@ -12,12 +21,19 @@ function unmeteredUsage(input: number | undefined, output: number | undefined) {
  * (non-integer or negative) are the one remaining failure mode — those are
  * journaled as `worker_error` with the usage projected from clamped counts.
  *
- * Unpriced models are NOT a failure here: the step journals zero dollars, so it
- * never trips a dollar budget, but its reported tokens still count toward any
- * token budget. Preflight (see `budgetDiagnostics`) warns that such a step is
- * unmetered for dollars.
+ * Contract across preflight → worker → kernel (keep all three aligned):
+ * - preflight (`budgetDiagnostics`) warns `budget_unmetered` for a
+ *   dollar-budgeted step with no frozen price and lets it run;
+ * - this function returns priced usage (`dollars`) for a priced model, and
+ *   unmetered usage (`dollars_unmetered: true`, no `dollars`) otherwise —
+ *   never `undefined` for a successful decode, so token ceilings always see the
+ *   step and the journal always says whether its dollars are known;
+ * - the kernel (`machine/budget.rs`) enforces tokens on every charge and
+ *   dollars on metered charges only, and rejects unmetered usage that also
+ *   claims non-zero dollars.
+ * `tests/budget-unmetered-live.test.ts` pins the chain end to end.
  */
-export function workerSpend(result: WorkerCliResult, model?: string) {
+export function workerSpend(result: WorkerCliResult, model?: string): { result: WorkerCliResult; usage: StepUsage | undefined } {
   try {
     const usage = pricedUsage(model, result.tokens_input, result.tokens_output)
       ?? unmeteredUsage(result.tokens_input, result.tokens_output);

package/dist/cli/deterministic-failure.d.ts

@@ -1,5 +0,0 @@
-import type { StepFailedDetails } from '../failure-kinds.js';
-import type { JournalClient } from '../journal-client.js';
-/** Read completion evidence through the existing protocol, including later pages. */
-export declare function deterministicFailureDetails(client: JournalClient, runId: string): Promise<StepFailedDetails | undefined>;
-//# sourceMappingURL=deterministic-failure.d.ts.map

package/dist/cli/deterministic-failure.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"deterministic-failure.d.ts","sourceRoot":"","sources":["../../src/cli/deterministic-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,qFAAqF;AACrF,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAqCxC"}

package/dist/cli/deterministic-failure.js

@@ -1,66 +0,0 @@
-const STDERR_TAIL_BYTES = 1_024;
-/** Read completion evidence through the existing protocol, including later pages. */
-export async function deterministicFailureDetails(client, runId) {
-    const snapshot = await client.runGet(runId);
-    if (!Object.values(snapshot.steps).some(step => step.type === 'deterministic'))
-        return undefined;
-    let fromSeq = 1;
-    const failures = new Map();
-    while (true) {
-        const { entries } = await client.journalRead(runId, fromSeq, 100);
-        if (entries.length === 0)
-            break;
-        for (const raw of entries) {
-            const entry = record(raw);
-            const seq = entry?.['seq'];
-            if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
-                throw new Error('invalid journal sequence in command failure inspection');
-            }
-            fromSeq = seq + 1;
-            const stepId = entry?.['step_id'];
-            if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string'
-                || snapshot.steps[stepId]?.type !== 'deterministic')
-                continue;
-            // A later completion supersedes an earlier failed attempt.
-            failures.delete(stepId);
-            const payload = record(entry['payload']);
-            // Post-#292 the kernel preserves the captured `{exit_code, stdout_tail,
-            // stderr_tail}` in `output` on failed completions; prefer it. Fall back
-            // to `trajectory_tail` for journal records emitted before that fix.
-            const output = record(payload?.['output']) ?? record(payload?.['trajectory_tail']);
-            const exitCode = output?.['exit_code'];
-            if (payload?.['disposition'] !== 'step_done' || payload['completionReason'] === 'success'
-                || typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode) || exitCode === 0)
-                continue;
-            failures.set(stepId, {
-                stepId,
-                exitCode,
-                stderrTail: stderrTail(output?.['stderr_tail']),
-                hint: `flows replay ${shellQuote(runId)} --at ${shellQuote(stepId)}`,
-            });
-        }
-    }
-    return [...failures.values()].at(-1);
-}
-function record(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value : undefined;
-}
-function stderrTail(value) {
-    if (typeof value !== 'string')
-        return '';
-    const bytes = Buffer.from(value, 'utf8');
-    let start = Math.max(0, bytes.length - STDERR_TAIL_BYTES);
-    // Drop a partial leading code point, avoiding replacement-byte expansion.
-    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
-        start += 1;
-    // Preserve tabs/newlines; replace binary controls (including ESC and CR),
-    // C1 controls and Unicode formatting controls without growing the excerpt.
-    return bytes.subarray(start).toString('utf8')
-        .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
-}
-function shellQuote(value) {
-    return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
-        ? value : `'${value.replace(/'/g, "'\\''")}'`;
-}
-//# sourceMappingURL=deterministic-failure.js.map

package/dist/cli/deterministic-failure.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"deterministic-failure.js","sourceRoot":"","sources":["../../src/cli/deterministic-failure.ts"],"names":[],"mappings":"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"}

package/src/cli/deterministic-failure.ts

@@ -1,69 +0,0 @@
-import type { StepFailedDetails } from '../failure-kinds.js';
-import type { JournalClient } from '../journal-client.js';
-
-const STDERR_TAIL_BYTES = 1_024;
-
-/** Read completion evidence through the existing protocol, including later pages. */
-export async function deterministicFailureDetails(
-  client: JournalClient,
-  runId: string,
-): Promise<StepFailedDetails | undefined> {
-  const snapshot = await client.runGet(runId);
-  if (!Object.values(snapshot.steps).some(step => step.type === 'deterministic')) return undefined;
-  let fromSeq = 1;
-  const failures = new Map<string, StepFailedDetails>();
-  while (true) {
-    const { entries } = await client.journalRead(runId, fromSeq, 100);
-    if (entries.length === 0) break;
-    for (const raw of entries) {
-      const entry = record(raw);
-      const seq = entry?.['seq'];
-      if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < fromSeq) {
-        throw new Error('invalid journal sequence in command failure inspection');
-      }
-      fromSeq = seq + 1;
-      const stepId = entry?.['step_id'];
-      if (entry?.['entry_type'] !== 'step.completed' || typeof stepId !== 'string'
-        || snapshot.steps[stepId]?.type !== 'deterministic') continue;
-      // A later completion supersedes an earlier failed attempt.
-      failures.delete(stepId);
-      const payload = record(entry['payload']);
-      // Post-#292 the kernel preserves the captured `{exit_code, stdout_tail,
-      // stderr_tail}` in `output` on failed completions; prefer it. Fall back
-      // to `trajectory_tail` for journal records emitted before that fix.
-      const output = record(payload?.['output']) ?? record(payload?.['trajectory_tail']);
-      const exitCode = output?.['exit_code'];
-      if (payload?.['disposition'] !== 'step_done' || payload['completionReason'] === 'success'
-        || typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode) || exitCode === 0) continue;
-      failures.set(stepId, {
-        stepId,
-        exitCode,
-        stderrTail: stderrTail(output?.['stderr_tail']),
-        hint: `flows replay ${shellQuote(runId)} --at ${shellQuote(stepId)}`,
-      });
-    }
-  }
-  return [...failures.values()].at(-1);
-}
-
-function record(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? value as Record<string, unknown> : undefined;
-}
-
-function stderrTail(value: unknown): string {
-  if (typeof value !== 'string') return '';
-  const bytes = Buffer.from(value, 'utf8');
-  let start = Math.max(0, bytes.length - STDERR_TAIL_BYTES);
-  // Drop a partial leading code point, avoiding replacement-byte expansion.
-  while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
-  // Preserve tabs/newlines; replace binary controls (including ESC and CR),
-  // C1 controls and Unicode formatting controls without growing the excerpt.
-  return bytes.subarray(start).toString('utf8')
-    .replace(/[\p{Cc}\p{Cf}]/gu, character => character === '\n' || character === '\t' ? character : '?');
-}
-
-function shellQuote(value: string): string {
-  return /^[A-Za-z0-9_-]+$/.test(value) && !value.startsWith('-')
-    ? value : `'${value.replace(/'/g, "'\\''")}'`;
-}