@relayflows/sdk 2.0.10 → 2.0.12

package/src/preflight.ts

@@ -8,6 +8,7 @@ import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
 import { helperCall } from './yaml-helpers.js';
+import { resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
 import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
 import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
 import { readMountRegistry } from './mount-registry.js';
@@ -22,8 +23,10 @@ export interface CliResolution {
   stepId: string;
   cli: string;
   source: CliResolutionSource;
-  /** Model the step or selected named agent declared, probed with the CLI. */
+  /** Effective model probed with the CLI. */
   model?: string;
+  /** Exact source selected by step > named agent > adapter default priority. */
+  modelSource?: CliModelSource;
 }
 
 export interface CliProbeResult {
@@ -208,18 +211,17 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     };
   }
   const diagnostics: PreflightDiagnostic[] = [];
+  const cliResolutionDiagnostics: PreflightDiagnostic[] = [];
   const resolutions: CliResolution[] = [];
   const resolutionByStep = new Map<string, CliResolution>();
   const cliProbeResults = new Map<string, CliProbeOutcome>();
 
-  diagnostics.push(...unknownModelDiagnostics(compiled, options));
   diagnostics.push(...scopeDiagnostics(compiled, options));
   for (const server of new Set(options.mcpServers ?? [])) {
     if (options.mcp !== undefined && Object.hasOwn(options.mcp, server)) continue;
     diagnostics.push({ severity: 'refusal', kind: 'mcp_undeclared_server', server,
       message: `MCP server "${server}" is not declared in the nearest flows.json mcp map.` });
   }
-  diagnostics.push(...budgetDiagnostics(compiled));
   // Resolve the complete flow before touching any environment fact. A later
   // statically unresolved CLI makes the whole submission impossible, so no
   // earlier command, provider/model, or trigger probe may run first.
@@ -228,7 +230,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     if (step.type === 'agent' && helperCall(step) !== undefined) continue;
     const resolution = resolveCli(step, compiled, options.projectCli);
     if (resolution === undefined) {
-      diagnostics.push({
+      cliResolutionDiagnostics.push({
         severity: 'refusal',
         kind: 'cli_unresolved',
         stepId: step.id,
@@ -239,7 +241,19 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
       resolutionByStep.set(step.id, resolution);
     }
   }
-  if (diagnostics.length > 0) {
+  diagnostics.push(...cliResolutionDiagnostics);
+  if (cliResolutionDiagnostics.length > 0) {
+    return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
+  }
+  diagnostics.push(...unknownModelDiagnostics(compiled, options, resolutionByStep));
+  diagnostics.push(...budgetDiagnostics(
+    compiled,
+    new Map(resolutions.map(resolution => [resolution.stepId, {
+      cli: resolution.cli,
+      ...(resolution.model === undefined ? {} : { model: resolution.model }),
+    }])),
+  ));
+  if (diagnostics.some((diagnostic) => diagnostic.severity === 'refusal')) {
     return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
   }
 
@@ -311,6 +325,7 @@ function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightR
 function unknownModelDiagnostics(
   flow: FlowSpec,
   options: PreflightOptions,
+  resolutionByStep: ReadonlyMap<string, CliResolution> = new Map(),
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
   // model_unknown is a governance check: it exists to enforce a project's
@@ -340,16 +355,21 @@ function unknownModelDiagnostics(
   }
 
   for (const step of flow.steps) {
-    if (step.type === 'deterministic' || step.model === undefined) continue;
-    if (isKnownModel(step.model, options.models)) continue;
-    const resolution = resolveCli(step, flow, options.projectCli);
+    if (step.type === 'deterministic') continue;
+    const resolution = resolutionByStep.get(step.id);
+    // Selected named declarations were checked once above, including unused
+    // declarations. Other sources are step declarations or adapter defaults.
+    if (resolution?.modelSource === 'named') continue;
+    const model = resolution?.model ?? step.model;
+    if (model === undefined || isKnownModel(model, options.models)) continue;
+    if (!enforceRegistry) continue;
     diagnostics.push({
       severity: 'refusal',
       kind: 'model_unknown',
       stepId: step.id,
       ...(resolution === undefined ? {} : { cli: resolution.cli }),
-      model: step.model,
-      message: unknownModelMessage(step.id, step.model, resolution?.cli, options.modelRegistryPath),
+      model,
+      message: unknownModelMessage(step.id, model, resolution?.cli, options.modelRegistryPath),
     });
   }
 
@@ -402,14 +422,16 @@ function resolveCli(
   const named = step.type === 'agent' && step.agent !== undefined
     ? flow.agents?.[step.agent]
     : undefined;
-  // Model comes only from the step or its explicitly selected declaration.
-  // There is deliberately no flow/project or host default.
-  const effectiveModel = step.model ?? named?.model;
-  const model = effectiveModel !== undefined ? { model: effectiveModel } : {};
-  if (step.cli !== undefined) return { stepId: step.id, cli: step.cli, source: 'step', ...model };
-  if (named !== undefined) return { stepId: step.id, cli: named.cli, source: 'named', ...model };
-  if (flow.cli !== undefined) return { stepId: step.id, cli: flow.cli, source: 'flow', ...model };
-  if (projectCli !== undefined) return { stepId: step.id, cli: projectCli, source: 'project', ...model };
+  const resolved = (cli: string, source: CliResolutionSource): CliResolution => {
+    const effectiveModel = resolveCliModelSelection(cli, { step: step.model, named: named?.model });
+    return { stepId: step.id, cli, source,
+      ...(effectiveModel.model === undefined ? {} : { model: effectiveModel.model }),
+      ...(effectiveModel.source === undefined ? {} : { modelSource: effectiveModel.source }) };
+  };
+  if (step.cli !== undefined) return resolved(step.cli, 'step');
+  if (named !== undefined) return resolved(named.cli, 'named');
+  if (flow.cli !== undefined) return resolved(flow.cli, 'flow');
+  if (projectCli !== undefined) return resolved(projectCli, 'project');
   return undefined;
 }
 

package/src/protocol.ts

@@ -77,6 +77,8 @@ export interface StepSpend {
 }
 
 export interface RunStartParams {
+  /** Caller-owned retry identity. Reuse with a different spec is refused. */
+  admission_key?: string;
   reuse_from_run_id?: string;
   /**
    * The kernel spec dialect — the ONE boundary shape `RunSpec::parse`

package/src/spec.ts

@@ -238,10 +238,11 @@ export interface AgentStepSpec extends BaseStepSpec {
   /** Inert preflight declaration; overrides the flow/project CLI default. */
   cli?: string;
   /**
-   * Model the declared CLI must use. Raw Claude/Codex adapters receive their
-   * real model flag; an identified Relayflows wrapper receives it in its
-   * same-process execution request. Declared here so the choice is journaled with the step
-   * instead of being ambient host state.
+   * Model the declared CLI must use. A step declaration wins over its selected
+   * named agent and any registered adapter default. Raw Claude/Codex adapters
+   * receive the effective model as a real flag; an identified Relayflows
+   * wrapper receives an explicitly declared model in its same-process request.
+   * The effective choice is journaled instead of being ambient host state.
    */
   model?: string;
   surfaces?: AgentSurfaces;

package/src/worker-cli.ts

@@ -6,6 +6,7 @@ import {
   agentExecution,
   llmExecution,
   cliAdapterKind,
+  resolveCliModel,
   type CliInvocation,
   type CliAdapterKind,
 } from './cli-adapter.js';
@@ -15,8 +16,7 @@ import {
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
 import {
-  agentRelaySpawn,
-  deriveAgentName,
+  runAgentRelayTask,
   AgentRelayTransportError,
   type AgentTransport,
 } from './agent-relay-transport.js';
@@ -32,6 +32,7 @@ export const WAKE_CONTEXT_ENV = 'RELAYFLOW_WAKE_CONTEXT';
 export const MODEL_ENV = 'RELAYFLOW_MODEL';
 
 export interface WorkerCliResult {
+  relay_task?: import('./agent-relay-receipt.js').RelayTaskReceipt;
   tokens_input?: number;
   tokens_output?: number;
   exit_code: number | null;
@@ -40,12 +41,14 @@ export interface WorkerCliResult {
 }
 
 /**
- * Optional identity threaded through so the relay transport can derive a
- * stable, DM-addressable agent name (flows#385).
+ * Journal identity and durable dispatch storage used by the Relay task transport.
  */
 export interface AgentRelayContext {
   runId: string;
   stepId: string;
+  idempotencyKey: string;
+  dataDir?: string;
+  resultSchema?: unknown;
 }
 
 export async function runAgentCli(
@@ -66,27 +69,28 @@ export async function runAgentCli(
     throw new Error('Lease-bound agent execution requires macOS or Linux process-group cancellation; Windows is unsupported.');
   }
   const kind = cliAdapterKind(cli);
+  const effectiveModel = resolveCliModel(cli, model);
+
+  if (mode === 'agent' && transport === 'relay') {
+    return runViaAgentRelay(kind, instruction, wakeContext, effectiveModel, relayContext, cwd, signal);
+  }
 
   if (kind === 'relayflows-wrapper-v1') {
     return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
       instruction,
       wakeContext,
-      model,
+      effectiveModel,
       wrapperEnvironment(process.env),
       wrapperLimits,
       signal,
-    )), model);
-  }
-
-  if (mode === 'agent' && transport === 'relay') {
-    return runViaAgentRelay(kind, instruction, model, relayContext, cwd);
+    )), effectiveModel);
   }
 
   const env: NodeJS.ProcessEnv = { ...process.env };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
-  const invocation = mode === 'llm' ? llmExecution(kind, instruction, model) : agentExecution(kind, instruction, model);
+  const invocation = mode === 'llm' ? llmExecution(kind, instruction, effectiveModel) : agentExecution(kind, instruction, effectiveModel);
 
   if (wakeContext !== undefined) {
     try {
@@ -104,57 +108,49 @@ export async function runAgentCli(
   // Structured provider output carries the authoritative token counts.
   const args = [...invocation.args];
   args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'json'] : ['--json']));
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), model);
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), effectiveModel);
 }
 
-/**
- * Relay-transport path (flows#385). Fires an agent-relay spawn HTTP request
- * that registers the CLI as a first-class workspace participant DMs can
- * steer, then reports the spawn outcome as a WorkerCliResult. Streaming
- * completion tracking is a follow-up — this initial slice proves the
- * transport wire and returns quickly with the registered name in stdout.
- */
+/** Wait under the same worker lease for an authoritative task receipt. */
 async function runViaAgentRelay(
-  kind: CliAdapterKind,
-  instruction: string,
-  model: string | undefined,
-  relayContext: AgentRelayContext | undefined,
-  worker_cwd: string | undefined,
+  kind: CliAdapterKind, instruction: string, wakeContext: unknown,
+  model: string | undefined, context: AgentRelayContext | undefined,
+  worker_cwd: string | undefined, signal: AbortSignal | undefined,
 ): Promise<WorkerCliResult> {
-  if (kind === 'relayflows-wrapper-v1') {
-    return {
-      exit_code: null,
-      stdout_tail: '',
-      stderr_tail: 'agent-relay transport does not support the relayflows-wrapper-v1 same-process session.',
-    };
-  }
-  if (relayContext === undefined) {
-    return {
-      exit_code: null,
-      stdout_tail: '',
-      stderr_tail: 'agent-relay transport requires a relayContext (runId, stepId); the caller did not thread it through.',
-    };
-  }
-  const name = deriveAgentName(relayContext.runId, relayContext.stepId);
   try {
-    const handle = await agentRelaySpawn({
-      name,
-      cli: kind,
-      task: instruction,
-      ...(model === undefined ? {} : { model }),
-      ...(worker_cwd === undefined ? {} : { worker_cwd }),
-    });
-    return {
-      exit_code: 0,
-      stdout_tail: JSON.stringify({ registeredName: handle.registeredName, invocationId: handle.invocationId }),
-      stderr_tail: '',
+    if (kind === 'relayflows-wrapper-v1') throw new Error('Relay task transport does not support same-process wrappers.');
+    if (!context?.dataDir) throw new Error('Relay task transport requires a durable data directory and journal dispatch identity.');
+    const task = instruction + (wakeContext === undefined ? '' : `\n\nWake context (journaled):\n${JSON.stringify(wakeContext)}`)
+      + '\n\nReport the final task output with the injected agent_result tool and final=true. Wait for its successful durable acknowledgment before exiting.';
+    const received = await runAgentRelayTask({
+      cli: kind, task, model, worker_cwd, result_schema: context.resultSchema,
+      runId: context.runId, stepId: context.stepId, idempotencyKey: context.idempotencyKey,
+      dataDir: context.dataDir,
+    }, { signal });
+    const receipt = { ...received, error: received.error === null ? null : redactRelayError(received.error) };
+    const accounting = receipt.task_execution.accounting;
+    const result: WorkerCliResult = {
+      relay_task: receipt, exit_code: receipt.status === 'completed' ? 0 : 1,
+      stdout_tail: receipt.status === 'completed' ? JSON.stringify(receipt.output) : '',
+      stderr_tail: receipt.status === 'failed' ? `Relay task failed: ${receipt.error}` : '',
+      ...(accounting?.tokens_input === undefined ? {} : { tokens_input: accounting.tokens_input }),
+      ...(accounting?.tokens_output === undefined ? {} : { tokens_output: accounting.tokens_output }),
     };
+    return requirePricedUsage(result, model);
   } catch (error) {
-    const detail = error instanceof AgentRelayTransportError
-      ? error.message
-      : `agent-relay spawn failed: ${(error as Error).message ?? String(error)}`;
-    return { exit_code: null, stdout_tail: '', stderr_tail: detail };
+    signal?.throwIfAborted();
+    const detail = error instanceof AgentRelayTransportError ? error.message
+      : error instanceof Error ? error.message : 'Relay task transport failed';
+    return { exit_code: null, stdout_tail: '', stderr_tail: redactRelayError(detail) };
+  }
+}
+
+function redactRelayError(message: string): string {
+  for (const key of ['RELAY_AGENT_TOKEN', 'RELAY_API_KEY']) {
+    const secret = process.env[key];
+    if (secret) message = message.replaceAll(secret, '[redacted]');
   }
+  return message.replace(/\b(?:at|rk|nt|ot|br|arr)_(?:live_)?[A-Za-z0-9_-]+/g, '[redacted]');
 }
 
 async function spawnInvocation(

package/src/worker-spend.ts

@@ -1,17 +1,28 @@
 import { pricedUsage } from './model-pricing.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' };
+}
+
 /**
  * Attach token/dollar usage to a worker's CLI result. Invalid token counts
  * (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: `pricedUsage` returns
- * `dollars: null` and preflight (see `budgetDiagnostics`) has already refused
- * declared dollar budgets against unpriced models before the CLI dispatched.
+ * 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.
  */
 export function workerSpend(result: WorkerCliResult, model?: string) {
-  try { return { result, usage: pricedUsage(model, result.tokens_input, result.tokens_output) }; }
+  try {
+    const usage = pricedUsage(model, result.tokens_input, result.tokens_output)
+      ?? unmeteredUsage(result.tokens_input, result.tokens_output);
+    return { result, usage };
+  }
   catch (error) {
     return {
       result: { ...result, exit_code: null, stderr_tail: error instanceof Error ? error.message : 'Invalid model usage' },

package/src/worker.ts

@@ -5,6 +5,7 @@ import type { JournalClient } from './journal-client.js';
 import type { Pins, StepDispatchEvent } from './protocol.js';
 import type { KernelAgentStep } from './spec.js';
 import { runAgentCli } from './worker-cli.js';
+import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
 import { helperCall } from './yaml-helpers.js';
@@ -105,16 +106,18 @@ export class AgentWorker extends EventEmitter {
       return;
     }
     let humanIntervention = false;
+    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.instruction === 'string'
-        ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, spec.model, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
+        ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
           dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id,
           onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
         }, typeof spec.cwd === 'string' ? spec.cwd : undefined,
           spec.transport === 'relay' ? 'relay' : 'direct',
-          { runId: dispatch.run_id, stepId: dispatch.step_id })
+          { runId: dispatch.run_id, stepId: dispatch.step_id, idempotencyKey: dispatch.idempotency_key,
+            dataDir: this.options.dataDir, resultSchema: spec.verification?.json_schema })
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
-    const { result, usage } = workerSpend(completed, spec.model);
+    const { result, usage } = workerSpend(completed, effectiveModel);
     const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
 
     // Output shape: if the CLI's stdout parses as JSON, promote THAT
@@ -130,7 +133,8 @@ export class AgentWorker extends EventEmitter {
     // emitting an error JSON with exit 0. `completionReason` is
     // derived from exit code, so a CLI that exits 0 while emitting
     // `{"error":...}` will report success with an error payload.
-    const output = parseJsonOutput(result.stdout_tail) ?? result;
+    const output = result.relay_task?.status === 'completed' && result.exit_code === 0
+      ? result.relay_task.output : parseJsonOutput(result.stdout_tail) ?? result;
 
     await this.client.stepComplete(
       dispatch.run_id,
@@ -140,6 +144,10 @@ export class AgentWorker extends EventEmitter {
       completionReason,
       {
         output,
+        ...(result.relay_task === undefined ? {} : { trajectory_tail: { relay_task: {
+          invocation_id: result.relay_task.invocation_id, status: result.relay_task.status,
+          task_execution: result.relay_task.task_execution, error: result.relay_task.error,
+        } } }),
         ...(humanIntervention ? { human_intervention: true } : {}),
         ...(usage !== undefined ? { usage } : {}),
         started_pins: dispatch.pins,