@relayflows/sdk 2.0.30 → 2.0.32

package/src/steps-green.ts

@@ -0,0 +1,168 @@
+// The read side of `onNonZero: 'record'`. A `steps_green` gate names earlier
+// deterministic steps and asserts every one of them recorded exit code zero.
+// The verdict comes from the journal — the recorded outcome each step already
+// produced — so asserting it costs nothing and cannot disagree with what ran.
+
+import { bindingDependencies } from './input-binding.js';
+import type { StepSpec, StepsGreenGate, VerificationSpec } from './spec.js';
+
+export const STEPS_GREEN_KEYS = ['type', 'ids'] as const;
+
+export function isStepsGreenGate(gate: VerificationSpec | undefined): gate is StepsGreenGate {
+  return gate?.type === 'steps_green';
+}
+
+/** Shape errors for one gate, without reference to the rest of the flow. */
+export function stepsGreenErrors(gate: Record<string, unknown>, at: string, stepType: string): string[] {
+  const errors: string[] = [];
+  if (stepType !== 'deterministic') {
+    errors.push(`${at}: gate_host_unsupported: steps_green is supported only on deterministic steps`);
+  }
+  const ids = gate['ids'];
+  if (!Array.isArray(ids) || ids.length === 0
+    || !ids.every(id => typeof id === 'string' && id.trim().length > 0)) {
+    errors.push(`${at}.ids: gate_ids_invalid: expected a non-empty array of step ids`);
+    return errors;
+  }
+  if (new Set(ids).size !== ids.length) {
+    errors.push(`${at}.ids: gate_ids_invalid: step ids must be unique`);
+  }
+  return errors;
+}
+
+/**
+ * Flow-level errors: the ids must resolve to earlier deterministic steps whose
+ * recorded outcome this gate can actually read. Refusing here is the whole
+ * point — a gate that silently reads nothing is the `|| true` failure mode
+ * this feature replaces.
+ */
+export function stepsGreenReferenceErrors(steps: readonly unknown[]): string[] {
+  const errors: string[] = [];
+  const sources = new Map(steps.flatMap((step, index) =>
+    isObject(step) && typeof step['id'] === 'string' ? [[step['id'], { step, index }] as const] : []));
+  for (const [index, step] of steps.entries()) {
+    if (!isObject(step)) continue;
+    const gate = step['verification'];
+    if (!isObject(gate) || gate['type'] !== 'steps_green') continue;
+    const ids = gate['ids'];
+    if (!Array.isArray(ids)) continue;
+    const at = `spec.steps[${index}].verification.ids`;
+    for (const id of ids) {
+      if (typeof id !== 'string') continue;
+      const source = sources.get(id);
+      if (source === undefined) {
+        errors.push(`${at}: gate_source_unsupported: unknown step "${id}"`);
+        continue;
+      }
+      if (source.index >= index) {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" must precede this step; forward and self references are not supported`);
+        continue;
+      }
+      if (source.step['type'] !== 'deterministic') {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" is a ${String(source.step['type'])} step and records no exit code`);
+        continue;
+      }
+      // The gate binds the source's whole output envelope, which requires a
+      // declared output schema. Every source shape is reachable except this
+      // one: `output_contains` is the single gate the compiler cannot widen
+      // without dropping the author's own check.
+      const sourceGate = source.step['verification'];
+      if (isObject(sourceGate) && sourceGate['type'] === 'output_contains') {
+        errors.push(`${at}: gate_source_unsupported: source "${id}" declares an output_contains gate, which cannot also carry the output schema this gate reads`);
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Lower every `steps_green` gate into a generated deterministic gate step.
+ *
+ * The host keeps its own command and its own exit policy; the gate is a
+ * separate step, always fatal, that binds each named source's journaled output
+ * envelope and refuses any nonzero or malformed exit code. Dependents of the
+ * host gain a barrier on the gate, so "these steps were green" is established
+ * before anything downstream of the assertion runs.
+ *
+ * Runs BEFORE `lowerNamedGates`, which then adds each source's own named-gate
+ * barrier to the generated step and rewrites named-gate hosts to the permissive
+ * envelope schema this gate's bindings need.
+ */
+export function lowerStepsGreenGates(steps: readonly StepSpec[]): StepSpec[] {
+  const used = new Set(steps.map(step => step.id));
+  const barriers = new Map<string, string>();
+  for (const step of steps) {
+    // Deterministic hosts only, which `validateSpec` already enforces; the
+    // narrowing here is what lets the rewrite below stay type-exact.
+    if (step.type !== 'deterministic' || !isStepsGreenGate(step.verification)) continue;
+    let id = `${step.id}.green`;
+    while (used.has(id)) id += '.green';
+    used.add(id);
+    barriers.set(step.id, id);
+  }
+  if (barriers.size === 0) return [...steps];
+
+  // Every source's envelope has to be bindable. A source that declares no
+  // gate, or the implicit exit_code gate, gets the permissive whole-output
+  // schema; its exit policy is untouched, so a recording source stays red.
+  const bound = new Set(steps.flatMap(step =>
+    isStepsGreenGate(step.verification) ? step.verification.ids : []));
+  const output: StepSpec[] = [];
+  for (const step of steps) {
+    const dependencies = [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])];
+    const dependsOn = [...new Set([...dependencies, ...dependencies.flatMap(id => barriers.get(id) ?? [])])];
+    let producer: StepSpec = dependsOn.length ? { ...step, dependsOn } : step;
+    if (bound.has(step.id) && producer.type === 'deterministic'
+      && (producer.verification === undefined || producer.verification.type === 'exit_code')) {
+      producer = { ...producer, verification: { type: 'json_schema', schema: true } };
+    }
+    const gate = step.verification;
+    if (producer.type !== 'deterministic' || !isStepsGreenGate(gate)) {
+      output.push(producer);
+      continue;
+    }
+    // The host's own gate becomes the implicit exit_code check. Its command
+    // still runs, and its own `onNonZero` still applies to its own exit. A
+    // host that is itself read by a later gate keeps the bindable envelope.
+    output.push({
+      ...producer,
+      verification: bound.has(step.id) ? { type: 'json_schema', schema: true } : { type: 'exit_code' },
+    });
+    const input = Object.fromEntries(gate.ids.map((id, index) => [String(index), { step: id }]));
+    output.push({
+      id: barriers.get(step.id)!, type: 'deterministic',
+      // A named source that is itself a gate host must have passed its own
+      // assertion too — depending on the source alone would read its command
+      // exit and let this barrier pass while the inner gate is still red.
+      dependsOn: [...new Set([step.id, ...gate.ids, ...gate.ids.flatMap(id => barriers.get(id) ?? [])])], input,
+      command: greenCommand(gate.ids),
+      verification: { type: 'exit_code' }, maxIterations: step.maxIterations ?? 1,
+      ...(step.requirements === undefined ? {} : { requirements: step.requirements }),
+    });
+  }
+  return output;
+}
+
+/**
+ * Compiler-owned Node command. Author-supplied ids are JSON literals and the
+ * recorded envelopes travel only through FLOWS_INPUT, never through shell text.
+ */
+function greenCommand(ids: readonly string[]): string {
+  const script = `const input=JSON.parse(process.env.FLOWS_INPUT);
+const ids=${JSON.stringify(ids)};
+const red=[];
+for(let i=0;i<ids.length;i++){
+const envelope=input[String(i)];
+if(envelope===null||typeof envelope!=='object'||Array.isArray(envelope)){red.push(ids[i]+': no recorded outcome');continue;}
+const code=envelope.exit_code;
+if(typeof code!=='number'||!Number.isInteger(code)){red.push(ids[i]+': recorded no integer exit_code');continue;}
+if(code!==0)red.push(ids[i]+': exit code '+code);
+}
+if(red.length>0){process.stderr.write('steps_green: '+red.join('; ')+'\\n');process.exit(1);}
+process.stdout.write('steps_green:pass');`;
+  return `node -e '${script.replaceAll("'", "'\\''")}'`;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/validate.ts

@@ -19,10 +19,12 @@ import type {
 import { SPEC_SCHEMA_VERSION } from './spec.js';
 import { validateOutputDeclaration } from './output-schema.js';
 import { modelNameError } from './model-name.js';
+import { agentCwdDeclarationError, agentCwdTransportError } from './agent-cwd.js';
 import { unknownKeyErrors } from './unknown-keys.js';
 import { stepDependencyErrors } from './step-dependencies.js';
 import { inputBindingErrors } from './input-binding.js';
 import { NAMED_GATE_KEYS, namedGateErrors } from './named-gates.js';
+import { STEPS_GREEN_KEYS, stepsGreenErrors, stepsGreenReferenceErrors } from './steps-green.js';
 import {
   AGENT_DECLARATION_FIELDS,
   FLOW_FIELDS,
@@ -74,6 +76,7 @@ const BUDGET_KEYS = ['maxTokensIn', 'maxTokensOut', 'maxDollars', 'maxTokens', '
 const VERIFICATION_KEYS: Record<string, readonly string[]> = {
   ...NAMED_GATE_KEYS,
   exit_code: ['type', 'expect'],
+  steps_green: STEPS_GREEN_KEYS,
   output_contains: ['type', 'value'],
   json_schema: ['type', 'schema'],
 };
@@ -195,6 +198,9 @@ class Validator {
     // Dependents must reference real step ids and form a DAG (no cycles).
     for (const error of stepDependencyErrors(steps, this.ids)) this.fail(error);
     for (const error of inputBindingErrors(steps)) this.fail(error);
+    // A steps_green gate that names nothing readable is the `|| true` failure
+    // it replaces, so its references are refused at the flow level, not lowered.
+    for (const error of stepsGreenReferenceErrors(steps)) this.fail(error);
     return this.result();
   }
 
@@ -443,10 +449,14 @@ class Validator {
       } catch (error) {
         this.fail(error instanceof Error ? error.message : `${at}.schema: expected JSON-compatible data`);
       }
+    // Below here are the gates the COMPILER lowers; above are the three the
+    // kernel evaluates itself. The enumeration follows the same split.
+    } else if (gate.type === 'steps_green') {
+      for (const error of stepsGreenErrors(v, at, stepType)) this.fail(error);
     } else if (Object.hasOwn(NAMED_GATE_KEYS, gate.type)) {
       for (const error of namedGateErrors(v, input, at)) this.fail(error);
     } else {
-      this.fail(`${at}.type: unknown_gate_kind: expected exit_code | output_contains | json_schema | references_input | subprocess_gate | word_count_bounds | regex_match | artifact_exists`);
+      this.fail(`${at}.type: unknown_gate_kind: expected exit_code | output_contains | json_schema | steps_green | references_input | subprocess_gate | word_count_bounds | regex_match | artifact_exists`);
     }
   }
 
@@ -460,6 +470,12 @@ class Validator {
     if (st.timeoutMs !== undefined && !isPosInt(st.timeoutMs)) {
       this.fail(`${at}.timeoutMs: expected a positive integer`);
     }
+    // Only the two policies the kernel enum names. A third spelling would
+    // deserialize-fail in the kernel, so it is refused where the author can
+    // still read the error.
+    if (st.onNonZero !== undefined && st.onNonZero !== 'fail' && st.onNonZero !== 'record') {
+      this.fail(`${at}.onNonZero: expected fail | record`);
+    }
   }
 
   private validateLlm(st: LlmStepSpec, at: string): void {
@@ -486,13 +502,7 @@ class Validator {
     }
     this.validateCli(st.cli, at);
     this.validateModel(st.model, at);
-    // The kernel refuses a relative cwd at run.start; refuse it here so `flows
-    // check` and the run agree. Not resolved against the checking directory:
-    // that would make the compiled spec (and its hash) depend on where the
-    // check ran. `f.agent` resolves before compiling, so it never lands here.
-    if (st.cwd !== undefined && (!isNonEmptyString(st.cwd) || !st.cwd.startsWith('/'))) {
-      this.fail(`${at}.cwd: expected an absolute path (got ${JSON.stringify(st.cwd)})`);
-    }
+    this.validateCwd(st, at);
     if (st.surfaces !== undefined) this.validateSurfaces(st.surfaces, `${at}.surfaces`);
     if (st.permissions !== undefined) this.validatePermissions(st.permissions, `${at}.permissions`);
   }
@@ -503,6 +513,23 @@ class Validator {
     }
   }
 
+  /**
+   * The declaration half of `cwd`: lexical, so an author sees the refusal from
+   * `flows check` rather than from a dispatch. Whether the directory exists and
+   * lies inside the run root is the worker's question (`agent-cwd.ts`), asked on
+   * the host that shares the agent's filesystem.
+   */
+  private validateCwd(st: AgentStepSpec, at: string): void {
+    if (st.cwd === undefined) return;
+    const problem = agentCwdDeclarationError(st.cwd);
+    if (problem !== undefined) {
+      this.fail(`${at}.cwd: ${problem}`);
+      return;
+    }
+    const unsupported = agentCwdTransportError(st.cwd, st.transport);
+    if (unsupported !== undefined) this.fail(`${at}.${unsupported}`);
+  }
+
   private validateModel(model: unknown, at: string, required = false): void {
     // Rejecting the empty string matters: it would reach the CLI as
     // RELAYFLOW_MODEL='', which reads as "declared, and declared as

package/src/worker-lease.ts

@@ -1,6 +1,33 @@
-import type { JournalClient } from './journal-client.js';
+import { JournalProtocolError, type JournalClient } from './journal-client.js';
 import type { StepDispatchEvent } from './protocol.js';
 
+export class WorkerLeaseLostError extends Error {
+  constructor(readonly reason: 'already_expired' | 'renewal_expired' | 'completion_expired', message: string) {
+    super(message);
+    this.name = 'WorkerLeaseLostError';
+  }
+}
+
+/** No cause traversal: worker errors preserve their original identity. */
+export function isLeaseLost(error: unknown): boolean {
+  return error instanceof WorkerLeaseLostError || (error instanceof JournalProtocolError
+    && (error.code === 'lease_conflict' || (error.code === 'run_terminal'
+      && ['step.heartbeat', 'step.complete', 'step.wait'].includes(error.verb ?? ''))));
+}
+
+export function onWorkerFailure(label: string, fatal: (error: unknown) => void) {
+  return (error: unknown, dispatch?: StepDispatchEvent): void => {
+    // Without the dispatch there is no attempt to hand back to the kernel: fail closed.
+    if (!isLeaseLost(error) || dispatch === undefined) { fatal(error); return; }
+    // The kernel owns this attempt's fate; its journal supplies the run outcome.
+    // stderr keeps this diagnostic out of structured reports on stdout.
+    process.emitWarning(
+      `${label}: run_id=${dispatch.run_id} step_id=${dispatch.step_id} attempt=${dispatch.attempt}: ${String(error)}`,
+      { code: 'FLOWS_WORKER_LEASE_LOST' },
+    );
+  };
+}
+
 /** Hold the dispatched lease only while its subprocess is still ours to run. */
 export async function withWorkerLease<T>(
   client: JournalClient,
@@ -16,12 +43,15 @@ export async function withWorkerLease<T>(
   const fail = (error: unknown): void => { controller.abort(error); };
   const armExpiry = (deadline: number): number => {
     const remaining = deadline - Date.now();
-    if (!Number.isFinite(remaining) || remaining <= 0) {
+    if (!Number.isFinite(remaining)) {
       throw new Error(`Agent lease is already expired for ${dispatch.run_id}/${dispatch.step_id}.`);
     }
+    if (remaining <= 0) {
+      throw new WorkerLeaseLostError('already_expired', `Agent lease is already expired for ${dispatch.run_id}/${dispatch.step_id}.`);
+    }
     latestDeadline = deadline;
     if (expiryTimer !== undefined) clearTimeout(expiryTimer);
-    expiryTimer = setTimeout(() => fail(new Error(
+    expiryTimer = setTimeout(() => fail(new WorkerLeaseLostError('renewal_expired',
       `Agent lease expired before renewal for ${dispatch.run_id}/${dispatch.step_id}.`,
     )), remaining);
     return remaining;
@@ -34,7 +64,7 @@ export async function withWorkerLease<T>(
     // A response handled after local expiry cannot revive ownership, even
     // if its future deadline was issued before this event loop stalled.
     if (Date.now() >= latestDeadline) {
-      throw new Error(`Agent lease expired before renewal for ${dispatch.run_id}/${dispatch.step_id}.`);
+      throw new WorkerLeaseLostError('renewal_expired', `Agent lease expired before renewal for ${dispatch.run_id}/${dispatch.step_id}.`);
     }
     const remaining = armExpiry(result.lease_deadline_ms);
     if (!stopped) {
@@ -57,7 +87,7 @@ export async function withWorkerLease<T>(
     // Timer callbacks can be delayed behind a resolved subprocess promise.
     // Check the clock itself before permitting step.complete.
     if (Date.now() >= latestDeadline) {
-      throw new Error(`Agent lease expired before completion for ${dispatch.run_id}/${dispatch.step_id}.`);
+      throw new WorkerLeaseLostError('completion_expired', `Agent lease expired before completion for ${dispatch.run_id}/${dispatch.step_id}.`);
     }
     return result;
   } finally {

package/src/worker.ts

@@ -6,6 +6,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 { agentStepCwd } from './agent-cwd.js';
 import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
 import { workerInstruction } from './worker-input.js';
@@ -22,6 +23,14 @@ export interface AgentWorkerOptions {
   requiredStreams?: string[];
   dataDir?: string;
   onPtyReady?: (path: string) => void;
+  /**
+   * The run root a step's declared `cwd` is resolved against and held inside.
+   * Defaults to this process's working directory, which is what the run root
+   * is: `flows run` attaches the worker from the directory it was invoked in,
+   * and that directory is the uploaded tree on the Cloud path. Named here so
+   * the root a dispatch is measured against is a value, not an assumption.
+   */
+  runRoot?: string;
 }
 
 /**
@@ -95,7 +104,7 @@ export class AgentWorker extends EventEmitter {
     if (this.closing) return;
     if (dispatch.step_type !== 'agent') return;
     const running: Promise<void> = this.execute(dispatch).catch((error: unknown) => {
-      this.emit('error', error);
+      this.emit('error', error, dispatch);
     });
     this.inFlight.add(running);
     void running.finally(() => { this.inFlight.delete(running); });
@@ -113,21 +122,28 @@ 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);
+      await completeCommunicationDispatch(this.client, dispatch, communication, this.options.dataDir, this.options.runRoot);
       return;
     }
     let humanIntervention = false;
     const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
+    // Resolved here, before the lease, because this is the process that shares
+    // the agent's filesystem. A refusal completes the step the way a missing
+    // CLI does — journaled as `worker_error` with the reason — rather than
+    // spawning into a directory nobody established is inside the run root.
+    const cwd = agentStepCwd(spec, dispatch.step_id, this.options.runRoot);
     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, effectiveModel, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
-          dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
-          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, 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' }));
+      'refusal' in cwd
+        ? Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: cwd.refusal })
+        : typeof spec.cli === 'string' && typeof spec.instruction === 'string'
+          ? 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, attempt: dispatch.attempt,
+            onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
+          }, 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 })
+          : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
     const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';