@relayflows/sdk 2.0.35 → 2.0.37

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/step-settling.ts

@@ -0,0 +1,19 @@
+/**
+ * A step's LAST settling `step.completed`: the verdict the kernel settled the
+ * step on. `retry` and `park` completions record an attempt the kernel did
+ * NOT settle it on (relayflowd-core `Disposition`) — crash recovery's
+ * `crashed`, a `worker_error` with iterations left — and precede the attempt
+ * that did, so neither the first completion nor a completion count is the
+ * step's verdict. Shared by the authored reader and the Bun result verifier,
+ * which must agree on which completion a claim is judged against.
+ */
+export function settlingCompletion<T>(entries: readonly T[], stepId: string): T | undefined {
+  return entries.filter(entry => {
+    if (typeof entry !== 'object' || entry === null) return false;
+    const { entry_type: type, step_id: step, payload } = entry as Record<string, unknown>;
+    if (type !== 'step.completed' || step !== stepId) return false;
+    const disposition = typeof payload === 'object' && payload !== null
+      ? (payload as Record<string, unknown>)['disposition'] : undefined;
+    return disposition !== 'retry' && disposition !== 'park';
+  }).at(-1);
+}

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

package/src/yaml-helper-effect.ts

@@ -8,6 +8,7 @@ import type { StepDispatchEvent } from './protocol.js';
 import { atomicJson, readSlackReceipt, receiptPath, slackWriteback } from './slack-writeback.js';
 import { invokeHelper, type HelperCall } from './yaml-helpers.js';
 import { withWorkerLease } from './worker-lease.js';
+import { NO_MODEL_COST } from './reported-cost.js';
 
 export function helperMount(provider: string, env = process.env): string | undefined {
   const root = [env.RELAYFILE_MOUNT_PATH, env.WORKSPACE_ROOT, env.WORKFORCE_SANDBOX_ROOT,
@@ -73,6 +74,6 @@ export async function completeHelperDispatch(
     return { ...call, idempotencyKey: `${dispatch.run_id}:${dispatch.step_id}`, receipt };
   });
   await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
-    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins, reported_cost: NO_MODEL_COST,
       effects: [{ surface_path: surfacePath, idempotency_key: dispatch.idempotency_key }] });
 }

package/src/yaml-helpers.ts

@@ -3,6 +3,7 @@ import { githubClient, linearClient, slackClient, type RelayTransport } from '@r
 import type { AgentStepSpec, KernelAgentStep, YamlHelperParams } from './spec.js';
 import { canonicalize } from './canonical.js';
 import { unknownKeyErrors } from './unknown-keys.js';
+import { HELPER_INSTRUCTION_PREFIX } from './helper-instruction.js';
 
 const string = { type: 'string', minLength: 1 };
 const text = { type: 'string' };
@@ -61,7 +62,7 @@ export type HelperCall = { [P in keyof YamlHelperParams]: { [V in keyof YamlHelp
   { type: 'effect'; provider: P; verb: V; params: YamlHelperParams[P][V] }
 }[keyof YamlHelperParams[P]] }[keyof YamlHelperParams];
 
-const prefix = 'relayflows:helper:v1\n';
+const prefix = HELPER_INSTRUCTION_PREFIX;
 const commonFields = ['id', 'dependsOn', 'maxIterations', 'verification', 'output'] as const;
 const isObject = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);