@relayflows/sdk 2.0.11 → 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';
@@ -68,9 +69,10 @@ 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, model, relayContext, cwd, signal);
+    return runViaAgentRelay(kind, instruction, wakeContext, effectiveModel, relayContext, cwd, signal);
   }
 
   if (kind === 'relayflows-wrapper-v1') {
@@ -78,17 +80,17 @@ export async function runAgentCli(
       cli,
       instruction,
       wakeContext,
-      model,
+      effectiveModel,
       wrapperEnvironment(process.env),
       wrapperLimits,
       signal,
-    )), model);
+    )), 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 {
@@ -106,7 +108,7 @@ 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);
 }
 
 /** Wait under the same worker lease for an authoritative task receipt. */

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,9 +106,10 @@ 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,
@@ -115,7 +117,7 @@ export class AgentWorker extends EventEmitter {
           { 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