@relayflows/sdk 2.0.35 → 2.0.37

package/src/cli/run.ts

@@ -23,13 +23,15 @@ import {
 import type { ParkCause, RunFailureKind, RunWarningKind, StepFailedDetails } from '../failure-kinds.js';
 import { inspectionHint, renderInspection, renderStepEvidence, stepFailureDetails } from './step-failure.js';
 import { JournalClient, JournalProtocolError } from '../journal-client.js';
-import { attachLocalAgent } from '../local-agent.js';
+import { attachLocalAgent, declaredLocalAgentStreams } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import { readAuthoredRootMetadata, resumeDurableAuthoredFlow, type AuthoredRootMetadata } from '../authored-root.js';
+import type { AuthoredFlowSuspendedResult } from '../authored-flow-executor.js';
 import type {
   RunCompletionReason,
   RunOutcome,
   RunStatus,
+  SubscriptionSnapshot,
 } from '../protocol.js';
 import type { StepType } from '../spec.js';
 import {
@@ -37,12 +39,13 @@ import {
   type LoweredCompletionReason,
 } from '../authored-completion.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
+import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   checkFlow,
   type CheckReport,
 } from './check.js';
 
-export type RunExitCode = 0 | 1 | 2 | 3;
+export type RunExitCode = 0 | 1 | 2 | 3 | 4;
 export type RunCommand = 'run' | 'resume' | 'answer';
 
 export interface ParkedStep {
@@ -52,7 +55,7 @@ export interface ParkedStep {
 
 export interface RunDiagnostic extends StepFailedDetails {
   severity: 'refusal' | 'failure' | 'parked' | 'warning' | 'declined';
-  kind: RunFailureKind | RunWarningKind | RunCompletionReason;
+  kind: RunFailureKind | RunWarningKind | RunCompletionReason | 'subscription_suspended';
   message: string;
 }
 
@@ -61,10 +64,14 @@ export interface RunReport {
   command: RunCommand;
   path?: string;
   runId?: string;
-  /** Authored root to resume/collect when runId identifies a failed child. */
+  /** Authored root owning subscriptions when runId names a failed child. */
   rootRunId?: string;
   socketPath?: string;
-  status?: RunStatus;
+  status?: RunStatus | 'suspended';
+  /** Cloud consumes this exact durable boundary before launching a resume. */
+  suspension?: AuthoredFlowSuspendedResult['suspension'] & { settleMs?: number; idleAtMs?: number };
+  /** Durable subscription projection for Cloud routing and cleanup. */
+  subscriptions?: SubscriptionSnapshot[];
   completionReason?: RunCompletionReason;
   /**
    * What the body passed to `done(reason, { detail })`, normalized: redacted,
@@ -103,6 +110,26 @@ export interface RunExecution {
   report: RunReport;
 }
 
+export function suspendedExecution(
+  command: RunCommand,
+  base: CheckReport | RunReport,
+  socketPath: string,
+  runId: string,
+  result: AuthoredFlowSuspendedResult & { readonly rootRunId: string },
+): RunExecution {
+  return {
+    exitCode: 4,
+    report: {
+      ...fromBase(command, base), ok: false, runId, socketPath, status: 'suspended',
+      suspension: result.suspension, completedSteps: result.journalSteps.length,
+      diagnostics: [...base.diagnostics, {
+        severity: 'warning', kind: 'subscription_suspended',
+        message: `Flow "${result.name}" suspended for ${result.suspension.kind}.`,
+      }],
+    },
+  };
+}
+
 export interface RunProgress {
   runId: string;
   stepId: string;
@@ -150,20 +177,22 @@ export async function runFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  const agentEnvironment = localAgentEnvironment();
   const prepared = parseDigestReference(path) ? await prepareDigestRun(path, options.bucket) : undefined;
   if (prepared && 'exitCode' in prepared) return prepared;
-  const checked = prepared ?? checkFlow(path);
+  const checked = prepared ?? checkFlow(path, { environment: agentEnvironment });
   if (!checked.report.ok || checked.flow === undefined) {
     return { exitCode: 2, report: fromCheckReport('run', checked.report) };
   }
 
-  return executeCheckedFlow(checked, dataDir, options);
+  return executeCheckedFlow(checked, dataDir, options, agentEnvironment);
 }
 
 async function executeCheckedFlow(
   checked: ReturnType<typeof checkFlow>,
   dataDir: string,
   options: RunLifecycleOptions,
+  agentEnvironment?: NodeJS.ProcessEnv,
 ): Promise<RunExecution> {
   const socketPath = socketFor(dataDir);
   // Carry the preflight's diagnostics as a RunReport from here on, so the
@@ -185,11 +214,14 @@ async function executeCheckedFlow(
     // Use the checked CLI/model and declared surfaces unchanged. The worker
     // advertises its existing pins; the daemon still owns surface matching.
     if (options.localAgent) {
-      localAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
+      localAgent = await attachLocalAgent(
+        client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
+        undefined, declaredLocalAgentStreams(spec), agentEnvironment,
+      );
     }
     if (options.localAgent && spec.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
       const { attachCommunicationWorkers } = await import('../communication/local.js');
-      communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+      communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir, agentEnvironment);
     }
     if (options.onJournalEntry !== undefined) client.on('entry', options.onJournalEntry);
     const outcome = await startWatched(client, spec, options);
@@ -252,6 +284,9 @@ export async function resumeFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  // Resume can load authored source; consume the descriptor before reading the
+  // journal so no source evaluation can race credential pickup.
+  const agentEnvironment = localAgentEnvironment();
   const socketPath = socketFor(dataDir);
   const base = emptyReport('resume');
   const client = new JournalClient(socketPath);
@@ -271,6 +306,7 @@ export async function resumeFlow(
   try {
     authoredRoot = await readAuthoredRootMetadata(client, runId);
     if (authoredRoot !== undefined) {
+      base.rootRunId = runId;
       // Both worker-surface mismatches are refusals, not protocol failures.
       // They used to throw bare `Error`s, which landed on `protocol_error`
       // ("RUN <id> unknown") and told nobody what to do instead; and the
@@ -293,11 +329,12 @@ export async function resumeFlow(
       if (options.localAgent) {
         authoredAgent = await attachLocalAgent(
           client, dataDir, options.onPtyReady, authoredRoot.localAgentStream, workerCapacity,
+          undefined, [], agentEnvironment,
         );
         authoredLlmClient = new JournalClient(socketPath);
         await authoredLlmClient.connect();
         await authoredLlmClient.hello('flows-authored-resume-llm');
-        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity);
+        authoredLlm = new LlmWorker(authoredLlmClient, `${authoredAgent.stream}-llm`, workerCapacity, agentEnvironment);
         authoredLlm.on('error', onWorkerFailure('resume-llm', error => {
           llmFailure = error;
           client.close();
@@ -308,9 +345,13 @@ export async function resumeFlow(
         dataDir,
         localAgentStream: authoredAgent?.stream,
         ...(authoredAgent === undefined ? {} : { workerCapacity }),
+        ...(agentEnvironment === undefined ? {} : { agentEnvironment }),
         lifecycle: options,
       });
       if (result === undefined) throw new Error('authored root disappeared during resume');
+      if (result.state === 'suspended') {
+        return suspendedExecution('resume', base, socketPath, runId, result);
+      }
       return authoredCompletion('resume', base, socketPath, result, runId);
     }
     // resumeHelperEffect subsumes the old resumeSlackEffect: it handles the
@@ -318,12 +359,16 @@ export async function resumeFlow(
     // second call the earlier rebase left is a stale reference from before
     // the helper fanout renamed the API.
     if (options.localAgent) {
-      authoredAgent = await attachLocalAgent(client, dataDir, options.onPtyReady, undefined, options.agentCapacity);
       const entries = (await client.journalRead(runId, 1)).entries as Array<{ entry_type: string; payload?: { spec?: import('../spec.js').KernelRunSpec } }>;
       const spec = entries.find(entry => entry.entry_type === 'run.spawned')?.payload?.spec;
+      if (!spec) throw new Error('Cannot attach a local worker: the journaled run spec is missing');
+      authoredAgent = await attachLocalAgent(
+        client, dataDir, options.onPtyReady, undefined, options.agentCapacity,
+        undefined, declaredLocalAgentStreams(spec), agentEnvironment,
+      );
       if (spec?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
         const { attachCommunicationWorkers } = await import('../communication/local.js');
-        communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir);
+        communicationWorkers = await attachCommunicationWorkers(spec, socketPath, dataDir, agentEnvironment);
       }
     }
     const onEntry = options.onJournalEntry;
@@ -955,7 +1000,7 @@ async function inspectOutOfBandStep(
 }
 
 // Match kernel/relayflowd/src/server/client.rs: allow the lease sweep to dispatch a retry.
-const LEASE_SWEEP_GRACE_MS = 5_000;
+export const LEASE_SWEEP_GRACE_MS = 5_000;
 
 async function waitForRunningStep(
   client: JournalClient,
@@ -1056,7 +1101,7 @@ function throwIfCanceled(signal: AbortSignal | undefined, stepId: string): void
   if (signal?.aborted === true) throw new Error(`waiting for running step "${stepId}" was canceled`);
 }
 
-function delay(ms: number, signal?: AbortSignal): Promise<void> {
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolveDelay, rejectDelay) => {
     const finish = (): void => {
       signal?.removeEventListener('abort', cancel);

package/src/cli/subscription-report.ts

@@ -0,0 +1,51 @@
+import { JournalClient } from '../journal-client.js';
+import type { SubscriptionInspectResult } from '../protocol.js';
+import type { RunExecution } from './run.js';
+
+/** One JSON emission boundary covers authored/declarative run and resume outcomes. */
+export async function withSubscriptionMetadata(
+  execution: RunExecution,
+  inspect: (socket: string, runId: string) => Promise<SubscriptionInspectResult> = inspectSubscriptions,
+): Promise<RunExecution> {
+  const { report } = execution;
+  const rootRunId = report.rootRunId ?? report.runId;
+  if (rootRunId === undefined || execution.exitCode === 2) {
+    return { ...execution, report: { ...report, subscriptions: [] } };
+  }
+  try {
+    if (report.socketPath === undefined) throw new Error('run report has no daemon socket');
+    const { subscriptions } = await inspect(report.socketPath, rootRunId);
+    let suspension = report.suspension;
+    if (suspension?.kind === 'event_wait') {
+      const state = subscriptions.find(item => item.subscriptionId === suspension!.subscriptionId);
+      if (state?.state !== 'active' || !Number.isSafeInteger(state.idleAtMs)
+        || !Number.isSafeInteger(state.settleMs) || !Number.isSafeInteger(state.deadlineAtMs)) {
+        throw new Error('event wait has no active durable timing snapshot');
+      }
+      suspension = { ...suspension, settleMs: state.settleMs,
+        idleAtMs: state.idleAtMs, deadlineAtMs: state.deadlineAtMs };
+    }
+    return { ...execution, report: { ...report, subscriptions,
+      ...(suspension === undefined ? {} : { suspension }) } };
+  } catch (error) {
+    // Missing authority is not an empty snapshot: Cloud must not close bindings
+    // or schedule timers from invented state. Preserve the run's diagnostic,
+    // but fail this report instead of presenting a usable suspension/success.
+    const { suspension: _suspension, subscriptions: _subscriptions, ...failed } = report;
+    return { exitCode: 1, report: { ...failed, ok: false, diagnostics: [
+      ...report.diagnostics, { severity: 'failure', kind: 'protocol_error',
+        message: `Cannot inspect durable subscriptions: ${error instanceof Error ? error.message : 'unknown error'}` },
+    ] } };
+  }
+}
+
+async function inspectSubscriptions(socket: string, runId: string): Promise<SubscriptionInspectResult> {
+  const client = new JournalClient(socket);
+  try {
+    await client.connect();
+    await client.hello('flows-subscription-report');
+    return await client.subscriptionInspect({ run_id: runId });
+  } finally {
+    client.close();
+  }
+}

package/src/cli-adapter.ts

@@ -10,10 +10,11 @@ import {
   registeredAdapters,
 } from './adapters/index.js';
 import type { CliAdapterKind } from './adapters/index.js';
-import type { CliInvocation, CliAdapterIdentification } from './adapters/base.js';
+import type { CliInvocation, CliAdapterIdentification, ModelProbeFailure } from './adapters/base.js';
 
 export type { CliAdapterKind } from './adapters/index.js';
-export type { CliInvocation, CliAdapterIdentification, HeadlessAdapter } from './adapters/base.js';
+export type { CliInvocation, CliAdapterIdentification, HeadlessAdapter, ModelProbeFailure,
+  ModelProbeFailureCause } from './adapters/base.js';
 
 export {
   WRAPPER_IDENTIFY_ARG,
@@ -73,6 +74,11 @@ export function modelReadinessProbe(kind: CliAdapterKind, model: string): CliInv
   return registeredAdapters()[kind].buildModelReadinessProbe(model);
 }
 
+/** Why a failed readiness probe failed, when the adapter recognises its output. */
+export function classifyModelProbeFailure(kind: CliAdapterKind, output: string): ModelProbeFailure | undefined {
+  return registeredAdapters()[kind].classifyModelProbeFailure?.(output);
+}
+
 /** Build the actual worker argv; this is shared contract, not probe-only lore. */
 export function agentExecution(
   kind: CliAdapterKind,

package/src/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { withSubscriptionMetadata } from './cli/subscription-report.js';
 import { addPlugin } from './cli/add.js';
 import { parsePluginArgs, runPluginCommand, type PluginArgs } from './cli/plugin.js';
 import { watchCheck } from './cli-watch.js';
@@ -77,7 +78,7 @@ export interface CliIo {
   tty?: boolean;
 }
 
-type CliExitCode = 0 | 1 | 2 | 3;
+type CliExitCode = 0 | 1 | 2 | 3 | 4;
 
 /**
  * Every shape `parseArgs` can produce. Exported for `cli-commands.ts`, whose
@@ -413,13 +414,14 @@ export async function runCli(
   // preflight) is worse than printing `Observer:` on a later line, so we
   // emit the run report immediately and finalize the observer link after.
   if (parsed.json) {
+    const reported = await withSubscriptionMetadata(execution);
     const observerUrl = await observerUrlFrom(observerMint, logged);
-    emitRunReport(execution, parsed.json, logged, observerUrl, await mirror?.receipt());
+    emitRunReport(reported, parsed.json, logged, observerUrl, await mirror?.receipt());
     // Last, and after the report: the run's own output is what the mirror
     // uploads, and a run's exit code has never waited on Cloud. The mirror
     // bounds itself and never rejects.
-    await mirror?.finish(execution.report);
-    return execution.exitCode;
+    await mirror?.finish(reported.report);
+    return reported.exitCode;
   }
   emitRunReport(execution, parsed.json, logged);
   await finalizeObserverLine(observerMint, logged);
@@ -437,6 +439,11 @@ export async function runCli(
 async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckReport }> {
   const helper = await checkHelperBody(path);
   if (!helper.report.ok) return helper;
+  // The activity checker loads the TypeScript compiler. YAML checks and
+  // unrelated CLI commands should not pay that startup cost on every run.
+  const { checkAuthoredActivities } = await import('./cli/check-activities.js');
+  const activities = await checkAuthoredActivities(path);
+  if (!activities.report.ok) return activities;
   const mcp = await checkTypeScriptFlow(path);
   const triggers = isAuthoredFlowPath(path)
     ? await checkAuthoredTriggers(path)
@@ -452,8 +459,8 @@ async function checkAuthoredFlowComposed(path: string): Promise<{ report: CheckR
       // The authored definition sees helper flags, body use and `cli:`
       // declarations; the compiled view underneath knows only its steps.
       ...(triggers?.report.requirements === undefined ? {} : { requirements: triggers.report.requirements }),
-      diagnostics: [...helper.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
-      ok: helper.report.ok && mcp.report.ok && triggerOk,
+      diagnostics: [...helper.report.diagnostics, ...activities.report.diagnostics, ...mcp.report.diagnostics, ...triggerDiagnostics],
+      ok: helper.report.ok && activities.report.ok && mcp.report.ok && triggerOk,
     },
   };
 }

package/src/communication/local.ts

@@ -8,7 +8,8 @@ import { loadRelayModules } from './relay.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from './preflight.js';
 import { requireCommunicationCli } from './worker.js';
 
-export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath: string, dataDir: string) {
+export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath: string, dataDir: string,
+  environment?: NodeJS.ProcessEnv) {
   const steps = spec.steps.filter(step => step.type === 'agent' && communicationInstruction(step.instruction));
   checkCommunicationEnvironment(spec);
   try { await loadRelayModules(); }
@@ -28,7 +29,7 @@ export async function attachCommunicationWorkers(spec: KernelRunSpec, socketPath
       requireCommunicationCli(step.cli ?? spec.cli);
       if (step.surfaces?.workspace?.length) throw new Error('Local communication workers support stream surfaces only');
       const client = new JournalClient(socketPath);
-      const worker = new AgentWorker(client, { workerId: `communication-${randomUUID()}`, dataDir,
+      const worker = new AgentWorker(client, { workerId: `communication-${randomUUID()}`, dataDir, environment,
         requiredStreams: [channelName(step.id, '$receipts')],
         pins: { workspace: [], streams: step.surfaces?.streams?.map(({ stream }) => ({ stream, read_offset: 0 })) ?? [] } });
       workers.push({ client, worker });

package/src/communication/worker.ts

@@ -18,13 +18,15 @@ export function requireCommunicationCli(cli: string | undefined): void {
   if (!cli?.trim()) throw new Error('Agent communication requires a declared CLI executable');
 }
 export async function completeCommunicationDispatch(client: JournalClient, dispatch: StepDispatchEvent,
-  instruction: CommunicationInstruction, dataDir: string, runRoot?: string): Promise<void> {
+  instruction: CommunicationInstruction, dataDir: string, runRoot?: string,
+  environment?: NodeJS.ProcessEnv): Promise<void> {
   const spec = dispatch.spec as KernelAgentStep;
   requireCommunicationCli(spec.cli);
   let output: unknown;
   let completionReason: 'success' | 'worker_error' = 'success';
   try {
-    output = await withWorkerLease(client, dispatch, signal => run(client, dispatch, instruction, spec, dataDir, signal, runRoot));
+    output = await withWorkerLease(client, dispatch, signal =>
+      run(client, dispatch, instruction, spec, dataDir, signal, runRoot, environment));
   } catch (error) {
     completionReason = 'worker_error';
     output = { error: error instanceof Error ? error.message : String(error) };
@@ -34,7 +36,8 @@ export async function completeCommunicationDispatch(client: JournalClient, dispa
       started_pins: dispatch.pins, end_pins: dispatch.pins });
 }
 async function run(client: JournalClient, dispatch: StepDispatchEvent, instruction: CommunicationInstruction,
-  spec: KernelAgentStep, dataDir: string, lease: AbortSignal, runRoot?: string): Promise<unknown> {
+  spec: KernelAgentStep, dataDir: string, lease: AbortSignal, runRoot?: string,
+  environment?: NodeJS.ProcessEnv): Promise<unknown> {
   // Same contract as the CLI worker: a declared directory is resolved and held
   // inside the same run root the CLI worker measures against, before anything
   // is spawned. Thrown, not reported, because `completeCommunicationDispatch`
@@ -80,7 +83,7 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
     handle = await relay.broker.spawnPty({ name, cli: basename(spec.cli!).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
       model: resolveCliModel(spec.cli!, spec.model), cwd: directory,
       harnessConfig: { runtime: 'pty', command: quote(spec.cli!), args: [],
-        cwd: directory, env: { ...agentEnvironment(spec.cli!),
+        cwd: directory, env: { ...agentEnvironment(spec.cli!, environment ?? process.env),
           RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
         delivery: { mode: 'pty-injection', format: 'relay-block' } } });
     const ready = await handle.waitForReady(Math.min(instruction.timeoutMs, 90_000));

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/failure-kinds.ts

@@ -15,6 +15,7 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'mcp_unreachable',
   'budget_syntax_invalid',
   'cli_missing',
+  'cli_outdated',
   'cli_unauthenticated',
   'cli_unresolved',
   'cli_unsupported',
@@ -24,6 +25,7 @@ const PREFLIGHT_ENVIRONMENT_FAILURE_KINDS = [
   'memory_unreachable',
   'no_executor',
   'probe_failed',
+  'provider_usage_limited',
   'scope_syntax_invalid',
   'mount_unknown',
   'scope_ungrantable',

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/index.ts

@@ -173,6 +173,12 @@ export type {
   EffectRef,
   EventEmitParams,
   EventEmitResult,
+  SubscriptionCloseParams,
+  SubscriptionCloseResult,
+  SubscriptionNextParams,
+  SubscriptionNextResult,
+  SubscriptionOpenParams,
+  SubscriptionOpenResult,
   HelloParams,
   HelloResult,
   JournalReadParams,

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, 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;
@@ -442,8 +451,17 @@ export class JournalClient extends EventEmitter {
     });
   }
 
-  eventEmit(runId: string, eventKey: string, payload: unknown): Promise<VerbContract['event.emit']['result']> {
-    return this.request('event.emit', { run_id: runId, event_key: eventKey, payload });
+  eventEmit(
+    runId: string,
+    eventKey: string,
+    payload: unknown,
+    options: Pick<EventEmitParams, 'delivery_id' | 'actor'> = {},
+  ): Promise<VerbContract['event.emit']['result']> {
+    return this.request('event.emit', { run_id: runId, event_key: eventKey, payload, ...options });
+  }
+
+  subscriptionPark(params: VerbContract['subscription.park']['params']): Promise<VerbContract['subscription.park']['result']> {
+    return this.request('subscription.park', params);
   }
 
   /**
@@ -457,6 +475,41 @@ export class JournalClient extends EventEmitter {
     return this.request('event.submit', { spec, event });
   }
 
+  /** Prepare a body subscription. Cloud must activate the returned request before a body can observe it. */
+  subscriptionOpen(params: VerbContract['subscription.open']['params']): Promise<VerbContract['subscription.open']['result']> {
+    return this.request('subscription.open', params, null);
+  }
+
+  /** Commit Cloud's durable binding receipt and ingress fence. */
+  subscriptionActivate(params: VerbContract['subscription.activate']['params']): Promise<VerbContract['subscription.activate']['result']> {
+    return this.request('subscription.activate', params, null);
+  }
+
+  /** Append to one activated subscription under its immutable router receipt. */
+  subscriptionDeliver(params: VerbContract['subscription.deliver']['params']): Promise<VerbContract['subscription.deliver']['result']> {
+    return this.request('subscription.deliver', params, null);
+  }
+
+  /** Read durable subscription state without changing timers or ingress. */
+  subscriptionInspect(params: VerbContract['subscription.inspect']['params']): Promise<VerbContract['subscription.inspect']['result']> {
+    return this.request('subscription.inspect', params);
+  }
+
+  /** Fence the exact activated receipt after router-side overflow. */
+  subscriptionFenceOverflow(params: VerbContract['subscription.fence_overflow']['params']): Promise<VerbContract['subscription.fence_overflow']['result']> {
+    return this.request('subscription.fence_overflow', params, null);
+  }
+
+  /** Return a durable wake, or an explicit suspension with no daemon-side sleep. */
+  subscriptionNext(params: VerbContract['subscription.next']['params']): Promise<VerbContract['subscription.next']['result']> {
+    return this.request('subscription.next', params, null);
+  }
+
+  /** Close a body subscription; the server refuses later external appends. */
+  subscriptionClose(params: VerbContract['subscription.close']['params']): Promise<VerbContract['subscription.close']['result']> {
+    return this.request('subscription.close', params, null);
+  }
+
   channelAppend(params: VerbContract['channel.append']['params']): Promise<VerbContract['channel.append']['result']> {
     return this.request('channel.append', params);
   }

package/src/journal-reader.ts

@@ -8,6 +8,8 @@ import { journalRecordOffset } from './journal-offset.js';
 // Journal version 1's closed vocabulary (relayflowd-core/src/entry.rs).
 const ENTRY_TYPES = new Set([
   'run.spawned', 'run.cancel.requested', 'event.received', 'subscription.registered',
+  'subscription.prepared', 'subscription.opened', 'subscription.closed',
+  'subscription.overflow.fenced', 'subscription.acknowledged',
   'subscription.matched', 'subscription.stale', 'step.routed', 'step.attempt.started',
   'step.completed', 'wait.event', 'wait.human', 'sleep.until', 'wait.completed',
   'stream.appended', 'memory.injected', 'channel.appended', 'channel.delivered',

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