@relayflows/sdk 2.0.36 → 2.0.38

package/src/child-stop.ts

@@ -6,6 +6,8 @@ import { execFileSync, type ChildProcess } from 'node:child_process';
  * the `flows run` event loop alive long after the step itself has settled.
  */
 export const FORCE_KILL_DELAY_MS = 1_000;
+/** Bound for proving that a forced process group has actually disappeared. */
+export const GROUP_EXIT_CONFIRM_TIMEOUT_MS = 1_000;
 
 /**
  * The one stop path for a spawned agent process.
@@ -65,6 +67,7 @@ export function childStop(
   child: ChildProcess,
   ownsGroup: boolean,
   forceKillDelayMs: number = FORCE_KILL_DELAY_MS,
+  onStopped: (error?: Error) => void = () => {},
 ): ChildStop {
   // Pinned at the spawn rather than read per signal. Every interesting use of
   // this id happens AFTER the direct child has been reaped — the escalation
@@ -74,6 +77,17 @@ export function childStop(
   // which is exactly the window both of those need to address.
   const pid = child.pid;
   let forceTimer: NodeJS.Timeout | undefined;
+  let groupPoll: NodeJS.Timeout | undefined;
+  let forced = false;
+  let forcedAt: number | undefined;
+  let stopped = false;
+  const notifyStopped = (error?: Error): void => {
+    if (stopped) return;
+    stopped = true;
+    if (groupPoll !== undefined) clearTimeout(groupPoll);
+    groupPoll = undefined;
+    onStopped(error);
+  };
   const cancel = (): void => {
     if (forceTimer !== undefined) clearTimeout(forceTimer);
     forceTimer = undefined;
@@ -106,6 +120,21 @@ export function childStop(
       }
     });
   };
+  const awaitGroupExit = (): void => {
+    if (!groupAnswers()) {
+      notifyStopped();
+      return;
+    }
+    if (forcedAt !== undefined && Date.now() - forcedAt >= GROUP_EXIT_CONFIRM_TIMEOUT_MS) {
+      notifyStopped(new Error(`Process groups did not stop answering within ${GROUP_EXIT_CONFIRM_TIMEOUT_MS}ms after SIGKILL.`));
+      return;
+    }
+    if (groupPoll !== undefined) return;
+    groupPoll = setTimeout(() => {
+      groupPoll = undefined;
+      awaitGroupExit();
+    }, 10);
+  };
   const signalTree = (name: NodeJS.Signals): void => {
     if (ownsGroup && pid !== undefined) {
       escapedGroups ??= descendantGroups(pid);
@@ -127,6 +156,9 @@ export function childStop(
     kill: (): void => {
       cancel();
       signalTree('SIGKILL');
+      forced = true;
+      forcedAt ??= Date.now();
+      awaitGroupExit();
     },
     terminate: (): void => {
       cancel();
@@ -134,6 +166,9 @@ export function childStop(
       forceTimer = setTimeout(() => {
         forceTimer = undefined;
         signalTree('SIGKILL');
+        forced = true;
+        forcedAt ??= Date.now();
+        awaitGroupExit();
       }, forceKillDelayMs);
       // Deliberately REFERENCED, unlike every other timer we arm. The survivor
       // this escalation exists for is the one that ignored `SIGTERM` and holds
@@ -144,9 +179,13 @@ export function childStop(
       // `maySettleOnChildExit` confirms the group is empty.
     },
     maySettleOnChildExit: (): boolean => {
-      if (forceTimer === undefined) return true;
+      if (forceTimer === undefined && !forced) {
+        notifyStopped();
+        return true;
+      }
       if (groupAnswers()) return false;
       cancel();
+      notifyStopped();
       return true;
     },
   };

package/src/cli/add-extension.ts

@@ -36,7 +36,7 @@ function eventKeys(manifest: FlowExtensionManifest): readonly string[] {
 
 function formatBudget(budget: FlowExtensionManifest['permissions']['budget']): string {
   if (budget === undefined) return 'inherits base';
-  return [budget.dollars === undefined ? '' : `$${budget.dollars}`, budget.wallclock ?? ''].filter(Boolean).join(' / ') || 'inherits base';
+  return [budget.tokens === undefined ? '' : `${budget.tokens} tokens`, budget.dollars === undefined ? '' : `$${budget.dollars}`, budget.wallclock ?? ''].filter(Boolean).join(' / ') || 'inherits base';
 }
 
 export function describeExtension(manifest: FlowExtensionManifest): string[] {

package/src/cli/check.ts

@@ -1,4 +1,5 @@
 import { communicationInstruction } from '../communication/spec.js';
+import { rememberResolvedCliIdentities } from '../resolved-cli-identity.js';
 import { checkCommunicationEnvironment } from '../communication/preflight.js';
 import { accessSync, constants, readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
@@ -15,6 +16,7 @@ import { parseMcpConfig } from '../mcp-config.js';
 import type { StepGateInspection } from '../gate-contract.js';
 import type { CheckFailureKind, CheckWarningKind } from '../failure-kinds.js';
 import {
+  cliProbeKey,
   preflight,
   type CliResolution,
   type CliProbeResult,
@@ -123,6 +125,8 @@ type CliProbeOutcomeMap = Map<string, CliProbeOutcome>;
  * anything that depends on how the flow is about to be invoked opts in here.
  */
 export interface CheckInvocation {
+  /** Environment used only by provider executable/auth/model probes. */
+  environment?: NodeJS.ProcessEnv;
   /**
    * Report `agent_worker_unresolved` when the spec has `agent` steps.
    *
@@ -200,11 +204,15 @@ export function checkAuthoredFlow(
     const projectConfig = options !== undefined
       ? options.projectConfig
       : projectConfigOrOptions as ProjectConfig | undefined;
-    const effectiveProbeCache = cliProbeCache ?? options?.probeCache;
+    // Keep the exact probe result so the executable identity selected during
+    // readiness is the one written onto the admitted step. Without an
+    // explicit map, preflight would allocate a private cache and a bare CLI
+    // name could be resolved again under the later worker cwd.
+    const effectiveProbeCache = cliProbeCache ?? options?.probeCache ?? new Map<string, CliProbeOutcome>();
     const config = projectConfig ?? readProjectConfig(dirname(absolutePath));
-    const probes = systemProbes(dirname(absolutePath), config);
+    const probes = systemProbes(dirname(absolutePath), config, invocation.environment);
     const result = preflight(authoring, {
-      ...(effectiveProbeCache === undefined ? {} : { cliProbeCache: effectiveProbeCache }),
+      cliProbeCache: effectiveProbeCache,
       projectCli: config.cli,
       projectConfigPath: config.path,
       projectSearchStart: dirname(absolutePath),
@@ -218,6 +226,7 @@ export function checkAuthoredFlow(
           result.resolutions,
           dirname(absolutePath),
           config.directory,
+          effectiveProbeCache,
         )
       : undefined;
     if (flow?.steps.some(step => step.type === 'agent' && communicationInstruction(step.instruction))) {
@@ -450,10 +459,11 @@ function findConfig(start: string): string | undefined {
   }
 }
 
-function systemProbes(flowDirectory: string, config: ProjectConfig): PreflightProbes {
+function systemProbes(flowDirectory: string, config: ProjectConfig, environment?: NodeJS.ProcessEnv): PreflightProbes {
   return {
     helper: helperReady,
-    cli: (cli, source, model, execution) => probeCli(cli, source === 'project' ? config.directory : flowDirectory, model, execution),
+    cli: (cli, source, model, execution) => probeCli(cli,
+      source === 'project' ? config.directory : flowDirectory, model, execution, environment),
     executor: (trigger) => config.executors.includes(trigger.executor),
     // A deterministic step runs in the daemon's working directory — the
     // directory `flows run` was invoked from, or Cloud's code mount — not in
@@ -469,20 +479,34 @@ function bindResolvedCliPaths(
   resolutions: readonly CliResolution[],
   flowDirectory: string,
   configDirectory: string,
+  probeCache: ReadonlyMap<string, CliProbeOutcome>,
 ): FlowSpec {
   const byStep = new Map(resolutions.map((resolution) => [resolution.stepId, resolution]));
-  return {
+  const identities = new Map<string, string>();
+  const bound: FlowSpec = {
     ...flow,
     steps: flow.steps.map((step) => {
       if (step.type === 'deterministic') return step;
       const resolution = byStep.get(step.id);
       if (resolution === undefined) return step;
       const directory = resolution.source === 'project' ? configDirectory : flowDirectory;
-      return { ...step, cli: canonicalCli(resolution.cli, directory),
+      const managed = step.type === 'agent' && communicationInstruction(step.instruction) !== undefined;
+      const outcome = probeCache.get(cliProbeKey(resolution, managed));
+      const executable = outcome !== undefined && 'result' in outcome
+        ? outcome.result.executable
+        : undefined;
+      const boundCli = executable !== undefined && isAbsolute(executable)
+        ? executable
+        : canonicalCli(resolution.cli, directory);
+      if (executable !== undefined && isAbsolute(executable)) {
+        identities.set(step.id, resolution.cli);
+      }
+      return { ...step, cli: boundCli,
         ...(resolution.modelSource === 'adapter' && resolution.model !== undefined
           ? { model: resolution.model } : {}) };
     }),
   };
+  return rememberResolvedCliIdentities(bound, identities);
 }
 
 function canonicalCli(cli: string, directory: string): string {

package/src/cli/cli-probe.ts

@@ -1,13 +1,15 @@
-import { accessSync, constants } from 'node:fs';
-import { isAbsolute, resolve } from 'node:path';
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { basename, isAbsolute, resolve } from 'node:path';
 import { execFile, spawnSync } from 'node:child_process';
 import { agentEnvironment, brokerEnvironment } from '../communication/environment.js';
 import { adapterIdentification, authenticationProbe, classifyModelProbeFailure, cliAdapterKind,
   displayInvocation, modelReadinessProbe, type CliInvocation } from '../cli-adapter.js';
 import { MODEL_ENV } from '../worker-cli.js';
 import { CliProbeError, type CliProbeResult } from '../preflight.js';
+import { pinCliAlias, pinCliAliasSync } from './pinned-cli-alias.js';
 
 interface ProbeRequest {
+  argv0?: string;
   executable: string;
   directory: string;
   invocation: CliInvocation;
@@ -27,20 +29,27 @@ export async function probeCliAsync(...args: Parameters<typeof probeSequence>):
   return next.value;
 }
 
-export function resolveExecutable(command: string, directory: string): string | undefined {
-  return driveSync(executableSequence(command, directory));
+export function resolveExecutable(command: string, directory: string, environment: NodeJS.ProcessEnv = process.env): string | undefined {
+  return driveSync(executableSequence(command, directory, environment));
 }
 
 function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
   let next = sequence.next();
   while (!next.done) {
     const request = next.value;
-    const result = spawnSync(request.executable, request.invocation.args, {
-      ...probeOptions(request),
-      // Preserve the old synchronous probe contract: provider CLIs must not
-      // inherit a readable stdin that can block auth/identify probes.
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
+    const pinned = pinCliAliasSync(request.executable, request.argv0 ?? basename(request.executable));
+    const result = (() => {
+      try {
+        return spawnSync(pinned.executable, request.invocation.args, {
+          ...probeOptions(request),
+          // Preserve the old synchronous probe contract: provider CLIs must not
+          // inherit a readable stdin that can block auth/identify probes.
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+      } finally {
+        pinned.release();
+      }
+    })();
     const failure = classifySpawnFailure(result.error, result.signal, request.invocation.timeoutMs);
     if (failure !== undefined) throw failure;
     next = sequence.next({ status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' });
@@ -48,30 +57,35 @@ function driveSync<T>(sequence: Generator<ProbeRequest, T, ProbeOutput>): T {
   return next.value;
 }
 
-function probeOptions({ directory, invocation, environment }: ProbeRequest) {
+function probeOptions({ argv0, directory, invocation, environment }: ProbeRequest) {
   const env = { ...environment };
   delete env[MODEL_ENV];
   if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
   return { cwd: directory, encoding: 'utf8' as const, timeout: invocation.timeoutMs,
-    maxBuffer: 1024 * 1024, env };
+    maxBuffer: 1024 * 1024, env, ...(argv0 === undefined ? {} : { argv0 }) };
 }
 
-function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
-  return new Promise((resolve, reject) => {
-    const child = execFile(request.executable, request.invocation.args, probeOptions(request),
-      (error, stdout, stderr) => {
-        // Numeric exit codes are probe results; launch, timeout, signal and buffer
-        // errors are failures to collect a fact, just as in the synchronous driver.
-        if (error?.killed && typeof error.code !== 'string') return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
-        const failure = classifySpawnFailure(
-          error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined,
-          error?.signal ?? null, request.invocation.timeoutMs);
-        if (failure !== undefined) return reject(failure);
-        resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
-          stdout, stderr });
-      });
-    child.stdin?.end();
-  });
+async function runProbeAsync(request: ProbeRequest): Promise<ProbeOutput> {
+  const pinned = await pinCliAlias(request.executable, request.argv0 ?? basename(request.executable));
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = execFile(pinned.executable, request.invocation.args, probeOptions(request),
+        (error, stdout, stderr) => {
+          // Numeric exit codes are probe results; launch, timeout, signal and buffer
+          // errors are failures to collect a fact, just as in the synchronous driver.
+          if (error?.killed && typeof error.code !== 'string') return reject(new CliProbeError(`timeout:${request.invocation.timeoutMs}ms`));
+          const failure = classifySpawnFailure(
+            error !== null && typeof error.code !== 'number' && error.signal == null ? error : undefined,
+            error?.signal ?? null, request.invocation.timeoutMs);
+          if (failure !== undefined) return reject(failure);
+          resolve({ status: error === null ? 0 : typeof error.code === 'number' ? error.code : null,
+            stdout, stderr });
+        });
+      child.stdin?.end();
+    });
+  } finally {
+    await pinned.release();
+  }
 }
 
 function* probeSequence(
@@ -79,19 +93,31 @@ function* probeSequence(
   directory: string,
   model?: string,
   execution?: 'managed',
+  sourceEnvironment: NodeJS.ProcessEnv = process.env,
 ): Generator<ProbeRequest, CliProbeResult, ProbeOutput> {
-  const executable = yield* executableSequence(cli, directory);
+  const executable = yield* executableSequence(cli, directory, sourceEnvironment);
   if (executable === undefined) return { exists: false, authenticated: false };
-  const kind = cliAdapterKind(executable);
+  // The declaration selects the adapter; the canonical executable selects
+  // the bytes. Package-manager links commonly name `claude` or `codex` while
+  // targeting a generic `cli.js`, whose basename must not rewrite the adapter
+  // contract after resolution.
+  const kind = cliAdapterKind(cli);
   // Relay owns interactive CLI launch/injection. Its generic PTY path is not
   // the headless wrapper protocol; do not demand that protocol from Gemini,
   // Cursor, OpenCode, or other interactive tools. Never invent an auth pass.
   if (execution === 'managed' && kind === 'relayflows-wrapper-v1') {
-    return { exists: true, supported: true, authenticated: 'unverified' };
+    return { exists: true, supported: true, authenticated: 'unverified', executable };
   }
   const environment = execution === 'managed'
-    ? { ...brokerEnvironment(process.env), ...agentEnvironment(executable) } : process.env;
-  const probe = (invocation: CliInvocation): ProbeRequest => ({ executable, directory, invocation, environment });
+    ? { ...brokerEnvironment(sourceEnvironment), ...agentEnvironment(cli, sourceEnvironment) }
+    : sourceEnvironment;
+  const probe = (invocation: CliInvocation): ProbeRequest => ({
+    executable,
+    argv0: basename(cli),
+    directory,
+    invocation,
+    environment,
+  });
   const identification = adapterIdentification(kind);
   const identified = yield probe(identification.invocation);
   if (
@@ -108,6 +134,7 @@ function* probeSequence(
       exists: true,
       supported: true,
       authenticated: (yield probe(auth)).status === 0,
+      executable,
       authCommand,
     };
   }
@@ -124,6 +151,7 @@ function* probeSequence(
       supported: true,
       authenticated: true,
       modelAvailable: true,
+      executable,
       authCommand,
       modelCommand,
     };
@@ -143,6 +171,7 @@ function* probeSequence(
     supported: true,
     authenticated,
     modelAvailable: false,
+    executable,
     authCommand,
     modelCommand,
     modelExitCode: scopedProbe.status,
@@ -176,19 +205,28 @@ function redactProbeOutput(text: string): string {
     .replace(/\b[A-Fa-f0-9]{32,}\b/g, '<redacted-hex>');
 }
 
-function* executableSequence(command: string, directory: string): Generator<ProbeRequest, string | undefined, ProbeOutput> {
+function* executableSequence(command: string, directory: string, environment: NodeJS.ProcessEnv): Generator<ProbeRequest, string | undefined, ProbeOutput> {
   if (command.includes('/') || isAbsolute(command)) {
     const path = isAbsolute(command) ? command : resolve(directory, command);
-    try {
-      accessSync(path, constants.X_OK);
-      return path;
-    } catch {
-      return undefined;
-    }
+    return canonicalExecutable(path);
   }
   const result = yield { executable: 'which', directory: process.cwd(),
-    invocation: { args: [command], timeoutMs: 5_000 }, environment: process.env };
-  return result.status === 0 ? result.stdout.trim() : undefined;
+    invocation: { args: [command], timeoutMs: 5_000 }, environment };
+  return result.status === 0
+    ? canonicalExecutable(resolve(process.cwd(), result.stdout.trim()))
+    : undefined;
+}
+
+function canonicalExecutable(path: string): string | undefined {
+  try {
+    accessSync(path, constants.X_OK);
+    // Dispatch must retain the exact target that readiness probed. Keeping a
+    // symlink path would allow the link to be retargeted between admission and
+    // worker spawn even though the compiled step carries an absolute path.
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
 }
 
 function classifySpawnFailure(

package/src/cli/direct-run.ts

@@ -6,6 +6,7 @@ import { McpPreflightError } from './check-typescript.js';
 import { attachLocalAgent } from '../local-agent.js';
 import { LlmWorker } from '../llm-worker.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
+import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   AuthoredFlowExecutionError,
 } from '../authored-flow-executor.js';
@@ -20,7 +21,7 @@ import { authoredInput, authoredWorkerRemedy, localAgentRemedy } from './local-a
 import {
   authoredCompletion,
   authoredHumanParked,
-  authoredStepFailure,
+  authoredStepFailure, rootLeaseLostReport,
   connect,
   emptyReport,
   fromCheckReport,
@@ -38,6 +39,9 @@ export async function runDirectFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  // Consume and close the agent-only descriptor before authored source is
+  // imported by trigger preflight. Authored code never receives this object.
+  const agentEnvironment = localAgentEnvironment();
   let input: unknown;
   try {
     input = parseDirectInput(inputArgument);
@@ -78,13 +82,14 @@ export async function runDirectFlow(
     if (options.localAgent) {
       localAgent = await attachLocalAgent(
         client, dataDir, options.onPtyReady, authoredLocalAgentStream(admissionIdentity), workerCapacity,
+        undefined, [], agentEnvironment,
       );
       // A session owns one worker registration. Keep the workspace-free LLM
       // worker on its own connection so it cannot replace the agent worker.
       llmClient = new JournalClient(socketPath);
       await llmClient.connect();
       await llmClient.hello('flows-local-llm');
-      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity);
+      localLlm = new LlmWorker(llmClient, `${localAgent.stream}-llm`, workerCapacity, agentEnvironment);
       localLlm.on('error', onWorkerFailure('local-llm', error => { llmFailure = error; client.close(); }));
       await localLlm.attach();
     }
@@ -96,6 +101,7 @@ export async function runDirectFlow(
         onAdmitted: runId => { base.rootRunId = runId; },
         localAgentStream: localAgent?.stream,
         ...(localAgent === undefined ? {} : { workerCapacity }),
+        ...(agentEnvironment === undefined ? {} : { agentEnvironment }),
         lifecycle: {
           onProgress: options.onProgress,
           ...(options.onRunStarted !== undefined ? { onRunStarted: options.onRunStarted } : {}),
@@ -206,6 +212,9 @@ export async function runDirectFlow(
     if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
+    if (error instanceof AuthoredFlowExecutionError && error.code === 'root_lease_lost') {
+      return rootLeaseLostReport('run', base, socketPath, error);
+    }
     if (error instanceof AuthoredHumanParked) {
       return authoredHumanParked('run', base, socketPath, error, { dataDir, localAgent: options.localAgent === true });
     }

package/src/cli/pinned-cli-alias.ts

@@ -0,0 +1,74 @@
+import {
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs';
+import {
+  mkdtemp,
+  rm,
+  symlink,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export interface PinnedCliAlias {
+  executable: string;
+  release(): void;
+}
+
+export interface PinnedCliAliasSync {
+  executable: string;
+  release(): void;
+}
+
+function aliasName(identity: string): string {
+  const name = basename(identity);
+  if (name.length === 0 || name === '.' || name === '..') {
+    throw new Error(`Invalid CLI identity basename: ${JSON.stringify(identity)}`);
+  }
+  return name;
+}
+
+/** Execute pinned canonical bytes through the proved basename, including shebang scripts. */
+export async function pinCliAlias(executable: string, identity: string): Promise<PinnedCliAlias> {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = await mkdtemp(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    await symlink(executable, alias, 'file');
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}
+
+/** Synchronous counterpart for the synchronous preflight contract. */
+export function pinCliAliasSync(executable: string, identity: string): PinnedCliAliasSync {
+  const name = aliasName(identity);
+  if (basename(executable) === name) {
+    return { executable, release() {} };
+  }
+  const directory = mkdtempSync(join(tmpdir(), 'relayflow-cli-'));
+  const alias = join(directory, name);
+  try {
+    symlinkSync(executable, alias, 'file');
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let released = false;
+  return { executable: alias, release: () => {
+    if (released) return;
+    rmSync(directory, { recursive: true, force: true });
+    released = true;
+  } };
+}