@relayflows/sdk 2.0.29 → 2.0.31

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';