@relayflows/sdk 2.0.31 → 2.0.33

package/src/cloud-transcript-codex.ts

@@ -32,12 +32,22 @@ export const CODEX_FRAME_TYPES: ReadonlySet<string> = new Set([
 /** Item types whose lifecycles are matched and whose fields are read. */
 const SUPPORTED_ITEMS: ReadonlySet<string> = new Set([
   'agent_message', 'reasoning', 'command_execution', 'file_change', 'mcp_tool_call', 'error',
+  // The rest of Codex's `ThreadItemDetails` union
+  // (codex-rs/exec/src/exec_events.rs). Without these three, a real agent turn
+  // reported them as bare `unknown` placeholders naming a type and a size —
+  // honest, but useless: `todo_list` in particular updates continuously
+  // through a turn, so it was the most frequent thing a reader could not read.
+  'web_search', 'todo_list', 'collab_tool_call',
 ]);
 
 const ITEM_FRAMES: ReadonlySet<string> = new Set(['item.started', 'item.updated', 'item.completed']);
 
 /** Calls are numbered; an `apply_patch` is file activity, not a call. */
-const NUMBERED_ITEMS: ReadonlySet<string> = new Set(['command_execution', 'mcp_tool_call']);
+const NUMBERED_ITEMS: ReadonlySet<string> = new Set([
+  'command_execution', 'mcp_tool_call', 'web_search', 'collab_tool_call',
+]);
+/** Todo entries listed per snapshot; a longer plan is counted, not printed. */
+const TODO_MAX_ITEMS = 12;
 
 interface Lifecycle {
   snapshots: Array<Record<string, unknown>>;
@@ -246,6 +256,65 @@ function mcpEntry(item: Record<string, unknown>, complete: boolean, context: Con
     });
 }
 
+/**
+ * `web_search`: a query and what was done with it (`WebSearchItem` — `query`,
+ * `action`, optional structured `results`). Rendered as a call rather than
+ * prose, so a reader sees the search in sequence beside the commands.
+ */
+function webSearchEntry(item: Record<string, unknown>, complete: boolean, context: Context,
+  seq: number): TranscriptEntry | null {
+  const query = str(item['query']);
+  if (query === null) return null;
+  const action = isRecord(item['action']) ? str(item['action']['type']) : str(item['action']);
+  const results = item['results'];
+  const count = Array.isArray(results) ? results.length : null;
+  return tool('web_search', bounded(query, context.clean),
+    count === null ? null : JSON.stringify(results).length, false, {
+      seq, status: action === null ? null : bounded(action, context.clean, 40),
+      exit_code: null,
+      output_excerpt: count === null ? null : `${count} result${count === 1 ? '' : 's'}`,
+      output_truncated: false, complete, error: null,
+    });
+}
+
+/**
+ * `collab_tool_call`: Codex driving other Codex threads (`CollabToolCallItem` —
+ * `tool`, `sender_thread_id`, `receiver_thread_ids`, `agents_states`).
+ *
+ * The per-agent states are reduced to a count per status rather than listed:
+ * `agents_states` is a map keyed by agent id, and ids are not something a
+ * transcript reader can act on.
+ */
+function collabEntry(item: Record<string, unknown>, complete: boolean, context: Context,
+  seq: number): TranscriptEntry | null {
+  const name = str(item['tool']);
+  if (name === null) return null;
+  const receivers = Array.isArray(item['receiver_thread_ids']) ? item['receiver_thread_ids'].length : 0;
+  const states = isRecord(item['agents_states']) ? item['agents_states'] : null;
+  const byStatus = new Map<string, number>();
+  if (states !== null) {
+    for (const state of Object.values(states)) {
+      const status = isRecord(state) ? str(state['status']) : null;
+      if (status !== null) byStatus.set(status, (byStatus.get(status) ?? 0) + 1);
+    }
+  }
+  // Redacted like every neighbouring field. A status is provider text, not a
+  // closed vocabulary this module controls, and it was the one string here that
+  // reached the page without passing the redactor.
+  const summary = bounded(
+    [...byStatus.entries()].sort().map(([status, n]) => `${n} ${status}`).join(', '),
+    context.clean,
+  );
+  const status = str(item['status']);
+  return tool('collab_tool_call',
+    bounded(`${name}${receivers > 0 ? ` → ${receivers} thread${receivers === 1 ? '' : 's'}` : ''}`, context.clean),
+    null, status === 'failed', {
+      seq, status: status === null ? null : bounded(status, context.clean, 40),
+      exit_code: null, output_excerpt: summary.length === 0 ? null : summary,
+      output_truncated: false, complete, error: null,
+    });
+}
+
 function fileChangeEntry(item: Record<string, unknown>, complete: boolean, context: Context): TranscriptEntry | null {
   const raw = item['changes'];
   if (!Array.isArray(raw)) return null;
@@ -288,12 +357,35 @@ function itemEntries(item: Record<string, unknown>, complete: boolean, context:
     if (message === null) return [placeholder(context, itemType)];
     return [{ kind: 'error', source: 'item', message: bounded(message, context.clean, ERROR_MAX_CHARS) }];
   }
-  if (itemType === 'command_execution' || itemType === 'mcp_tool_call') {
+  if (itemType === 'todo_list') {
+    // A plan, not a call: it carries no status and earns no sequence number.
+    // `items[]` is `{text, completed}` (TodoListItem/TodoItem).
+    const items = Array.isArray(item['items']) ? item['items'] : null;
+    if (items === null) return [placeholder(context, itemType)];
+    const listed = items.slice(0, TODO_MAX_ITEMS).flatMap((entry) => {
+      const todo = isRecord(entry) ? entry : undefined;
+      const text = str(todo?.['text']);
+      return text === null ? [] : [{ text: context.clean(text), done: todo!['completed'] === true }];
+    });
+    // Counted across the whole plan; only the *display* is capped. Counting the
+    // prefix rendered a 13-item plan whose last item was done as `0/13`, which
+    // is exactly backwards from "the rest are counted, not printed".
+    const done = items.filter(entry => isRecord(entry) && entry['completed'] === true).length;
+    return [{
+      kind: 'todo', total: items.length, done,
+      items: listed, ...(items.length > listed.length ? { omitted: items.length - listed.length } : {}),
+      ...(complete ? {} : { complete: false }),
+    }];
+  }
+  if (itemType === 'command_execution' || itemType === 'mcp_tool_call'
+    || itemType === 'web_search' || itemType === 'collab_tool_call') {
     // The number is only spent on a call this module could actually read, so a
     // malformed item leaves no gap in the sequence.
     const seq = context.state.seq + 1;
-    const entry = itemType === 'command_execution'
-      ? commandEntry(item, complete, context, seq) : mcpEntry(item, complete, context, seq);
+    const entry = itemType === 'command_execution' ? commandEntry(item, complete, context, seq)
+      : itemType === 'mcp_tool_call' ? mcpEntry(item, complete, context, seq)
+      : itemType === 'web_search' ? webSearchEntry(item, complete, context, seq)
+      : collabEntry(item, complete, context, seq);
     if (entry === null) return [placeholder(context, itemType)];
     context.state.seq = seq;
     return [entry];

package/src/cloud-transcript-types.ts

@@ -138,6 +138,22 @@ export interface TranscriptResult {
   cache_creation: number | null;
 }
 
+/**
+ * Codex's running to-do list (`TodoListItem`). A plan, not a call: it carries
+ * no status and takes no sequence number, and it updates repeatedly through a
+ * turn — which is why leaving it unparsed was the most visible gap.
+ */
+export interface TranscriptTodo {
+  kind: 'todo';
+  total: number;
+  done: number;
+  items: Array<{ text: string; done: boolean }>;
+  /** Entries past the per-snapshot cap: counted, never printed. */
+  omitted?: number;
+  /** False when read off a snapshot that never completed. */
+  complete?: boolean;
+}
+
 export interface TranscriptUnknown {
   kind: 'unknown';
   type: string;
@@ -152,7 +168,8 @@ export interface TranscriptUnparsed {
 export type TranscriptEntry =
   | TranscriptAttempt | TranscriptAttemptOmitted | TranscriptInit | TranscriptMessage
   | TranscriptThinking | TranscriptTool | TranscriptFileChange | TranscriptThread
-  | TranscriptTurn | TranscriptError | TranscriptResult | TranscriptUnknown | TranscriptUnparsed;
+  | TranscriptTurn | TranscriptError | TranscriptResult | TranscriptTodo
+  | TranscriptUnknown | TranscriptUnparsed;
 
 export interface ParsedTranscript {
   entries: TranscriptEntry[];

package/src/cloud-transcript.ts

@@ -34,7 +34,7 @@ import { redact } from './redact.js';
 export type {
   ParsedTranscript, TranscriptEntry, TranscriptAttempt, TranscriptAttemptOmitted, TranscriptError,
   TranscriptFileChange, TranscriptInit, TranscriptMessage, TranscriptResult, TranscriptThinking,
-  TranscriptThread, TranscriptTool, TranscriptToolCodex, TranscriptTurn, TranscriptUnknown,
+  TranscriptThread, TranscriptTodo, TranscriptTool, TranscriptToolCodex, TranscriptTurn, TranscriptUnknown,
   TranscriptUnparsed,
 } from './cloud-transcript-types.js';
 
@@ -297,6 +297,14 @@ export function renderAgentTranscript(parsed: ParsedTranscript): string[] {
       case 'thinking':
         lines.push(`  thinking  ${thousands(entry.chars)} chars (not shown)`);
         break;
+      case 'todo': {
+        // The plan the agent is working to, as it stood at this snapshot.
+        const progress = `${entry.done}/${entry.total}`;
+        lines.push(`  plan  ${progress}${entry.complete === false ? ' (in progress)' : ''}`);
+        for (const todo of entry.items) lines.push(`    ${todo.done ? '✓' : '·'} ${safe(todo.text)}`);
+        if (entry.omitted !== undefined) lines.push(`    …${entry.omitted} more`);
+        break;
+      }
       case 'tool': {
         const size = entry.is_error ? 'ERROR'
           : entry.result_chars === null ? 'no result' : `${thousands(entry.result_chars)} chars`;

package/src/helper-reference.ts

@@ -27,7 +27,8 @@ export function helperNamespacesUsed(body: string, root: string): ReadonlySet<st
   const program = parseFlowBody(body);
   if (program === null) return textFallback(body, root);
   const used = new Set<string>();
-  walk(program, (node) => {
+  const scope = { rootFunctionFound: false };
+  walkReferences(program, root, false, scope, (node) => {
     if (node.type !== 'MemberExpression') return;
     const object = node.object as AstNode | undefined;
     if (object?.type !== 'Identifier' || object.name !== root) return;
@@ -111,20 +112,144 @@ type AstNode = {
   [key: string]: unknown;
 };
 
-/** Depth-first over every child node, without pulling in a second package. */
-function walk(node: AstNode, visit: (node: AstNode) => void): void {
-  visit(node);
+/**
+ * Depth-first over references that still resolve to the outer flow context.
+ *
+ * A nested callback/method parameter or lexical destructuring can reuse the
+ * context's spelling while binding an unrelated value. Counting its members
+ * would refuse the flow for a mount it never touches. Acorn gives us binding
+ * shapes, so scopes are tracked as syntax instead of guessed from text.
+ */
+function walkReferences(
+  node: AstNode,
+  root: string,
+  shadowed: boolean,
+  state: { rootFunctionFound: boolean },
+  visit: (node: AstNode) => void,
+): void {
+  if (isFunction(node)) {
+    const parameters = Array.isArray(node.params) ? node.params.filter(isNode) : [];
+    const bindsParameter = parameters.some(parameter => patternBinds(parameter, root));
+    let bodyHidden = shadowed;
+    const isRootFunction = bindsParameter && !state.rootFunctionFound;
+    if (isRootFunction) state.rootFunctionFound = true;
+    else if (bindsParameter || (isNode(node.id) && patternBinds(node.id, root)) || functionVarBinds(node, root)) {
+      bodyHidden = true;
+    }
+    // Parameter initializers run before the function body and are outside a
+    // body-level `var` scope. Keep them visible unless the parameter list
+    // itself binds the root name (in which case all parameter references are
+    // local to that parameter environment).
+    const parameterHidden = shadowed || (bindsParameter && !isRootFunction);
+    for (const parameter of parameters) walkReferences(parameter, root, parameterHidden, state, visit);
+    const body = isNode(node.body) ? node.body : undefined;
+    if (body !== undefined) walkReferences(body, root, bodyHidden, state, visit);
+    return;
+  }
+  let hidden = shadowed;
+  if (node.type === 'BlockStatement' && blockBinds(node, root)) {
+    hidden = true;
+  } else if (node.type === 'CatchClause' && isNode(node.param) && patternBinds(node.param, root)) {
+    hidden = true;
+  }
+
+  if (!hidden) visit(node);
   for (const key of Object.keys(node)) {
     if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
     const child = node[key];
     if (Array.isArray(child)) {
-      for (const entry of child) if (isNode(entry)) walk(entry, visit);
+      for (const entry of child) if (isNode(entry)) walkReferences(entry, root, hidden, state, visit);
     } else if (isNode(child)) {
-      walk(child, visit);
+      walkReferences(child, root, hidden, state, visit);
     }
   }
 }
 
+function isFunction(node: AstNode): boolean {
+  return node.type === 'ArrowFunctionExpression'
+    || node.type === 'FunctionExpression'
+    || node.type === 'FunctionDeclaration';
+}
+
+/** Lexical declarations bind across their complete block, including TDZ. */
+function blockBinds(node: AstNode, root: string): boolean {
+  const statements = Array.isArray(node.body) ? node.body.filter(isNode) : [];
+  return statements.some((statement) => {
+    if (statement.type === 'VariableDeclaration' && statement.kind !== 'var') {
+      const declarations = Array.isArray(statement.declarations)
+        ? statement.declarations.filter(isNode) : [];
+      return declarations.some(declaration => isNode(declaration.id) && patternBinds(declaration.id, root));
+    }
+    return (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration')
+      && isNode(statement.id) && patternBinds(statement.id, root);
+  });
+}
+
+/** Identifier occurrences that introduce bindings, including nested patterns. */
+function patternBinds(pattern: AstNode, root: string): boolean {
+  switch (pattern.type) {
+    case 'Identifier':
+      return pattern.name === root;
+    case 'AssignmentPattern':
+      return isNode(pattern.left) && patternBinds(pattern.left, root);
+    case 'RestElement':
+      return isNode(pattern.argument) && patternBinds(pattern.argument, root);
+    case 'ArrayPattern': {
+      const elements = Array.isArray(pattern.elements) ? pattern.elements : [];
+      return elements.some(element => isNode(element) && patternBinds(element, root));
+    }
+    case 'ObjectPattern': {
+      const properties = Array.isArray(pattern.properties) ? pattern.properties : [];
+      return properties.some(property => {
+        if (!isNode(property)) return false;
+        if (property.type === 'RestElement') {
+          return isNode(property.argument) && patternBinds(property.argument, root);
+        }
+        // Object keys are labels, not bindings. Only the value side introduces
+        // the local (including a default-value AssignmentPattern's left side).
+        return property.type === 'Property'
+          && isNode(property.value)
+          && patternBinds(property.value, root);
+      });
+    }
+    default:
+      return false;
+  }
+}
+
+/** `var` is function-scoped, so a nested function's declaration hides the
+ * outer flow context for its entire body, including code before the
+ * declaration. Nested functions have their own var scopes and are skipped. */
+function functionVarBinds(node: AstNode, root: string): boolean {
+  const body = isNode(node.body) ? node.body : undefined;
+  if (body === undefined) return false;
+  let found = false;
+  const scan = (current: AstNode): void => {
+    if (found) return;
+    if (current !== body && isFunction(current)) return;
+    if (current.type === 'VariableDeclaration' && current.kind === 'var') {
+      const declarations = Array.isArray(current.declarations)
+        ? current.declarations.filter(isNode) : [];
+      if (declarations.some(declaration => isNode(declaration.id) && patternBinds(declaration.id, root))) {
+        found = true;
+        return;
+      }
+    }
+    for (const key of Object.keys(current)) {
+      if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+      const child = current[key];
+      if (Array.isArray(child)) {
+        for (const entry of child) if (isNode(entry)) scan(entry);
+      } else if (isNode(child)) {
+        scan(child);
+      }
+      if (found) return;
+    }
+  };
+  scan(body);
+  return found;
+}
+
 function isNode(value: unknown): value is AstNode {
   return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string';
 }

package/src/hosted-extension-runtime.ts

@@ -26,7 +26,7 @@ const REALPATH = realpath;
 const PATH_DIRNAME = dirname;
 const PATH_JOIN = join;
 const PATH_RESOLVE = resolve;
-const SOFTWARE_FACTORY_SHA256 = '49c993220b9c34fab2d4b0e51911656f62b8b657f534d988691960d45bb9d9b6';
+const SOFTWARE_FACTORY_SHA256 = 'b97a3466c2affabb61afa655d4b2f726942d753c0466740b64ba26a78da359c6';
 const ARRAY_IS_ARRAY = Array.isArray;
 const OBJECT_FREEZE = Object.freeze;
 const WEAK_MAP_GET = Function.prototype.call.bind(WeakMap.prototype.get) as <K extends object, V>(

package/src/hosted-extension-sandbox.ts

@@ -109,7 +109,7 @@ const ADDRESS_SPACE_BYTES = 16 * 1024 * 1024 * 1024;
 const DATA_BYTES = 3 * 1024 * 1024 * 1024;
 const SURFACE_RUNTIME_SHA256 = OBJECT_FREEZE({
   'flow.js': '4aaeacc55de3074f4d121ce7253c3be50a93757e6540ba8159889a9450d1c05c',
-  'helpers/providers.js': '7bc62eccaa3a9e786ae0a689bf74160585149e91feef8208e17ef8eca51eed7f',
+  'helpers/providers.js': '4eb06d0d85ca0a3434bb2dbba7407e3d95eef2dfbedaeb0e2de0c0c0ea812457',
   'provider-trigger.js': 'e2664c65397f93fb486eb6f1e756c7cec3f88b3851d79c23567cad986f80f1ff',
   'schedule.js': '8fe72f176a75ec0b5f26e12db7a597575c259a2e2cbb59690f9dc20a5e63940b',
   'triggers.js': '4a3515b571a318f6c7a5661f9310bc9af43e3faf20ea39903a9b363c51258e4c',

package/src/package-version.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Read the installed SDK package version from the manifest beside this module.
+ *
+ * The same relative URL works from `src/` during development and `dist/` in a
+ * built or npm-installed package. Reading the manifest at runtime keeps the
+ * CLI output tied to the bytes that are actually installed instead of a
+ * hardcoded release value that can drift between package files.
+ */
+export function packageVersion(): string {
+  try {
+    const manifest: unknown = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+    );
+    const version = (manifest as { version?: unknown }).version;
+    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+  } catch {
+    // Version display is cosmetic. Keep the CLI usable if a host strips the
+    // manifest from an otherwise runnable package artifact.
+    return '0.0.0';
+  }
+}

package/src/preflight.ts

@@ -65,7 +65,7 @@ export class CliProbeError extends Error {
   }
 }
 
-type CliProbeOutcome =
+export type CliProbeOutcome =
   | { result: CliProbeResult }
   | { failure: CliProbeFailureDetail | null };
 
@@ -89,6 +89,8 @@ export interface PreflightProbes {
 }
 
 export interface PreflightOptions {
+  /** Reuse only within one run and one CLI resolution environment; failures are cached too. */
+  cliProbeCache?: Map<string, CliProbeOutcome>;
   pluginSearchStart?: string;
   /** Validated tools.mcp header and nearest flows.json connections. */
   mcpServers?: readonly string[];
@@ -99,6 +101,7 @@ export interface PreflightOptions {
   /** Exact, project-owned model allowlist from the nearest flows.json. */
   models?: readonly string[];
   modelRegistryPath?: string;
+  probeCache?: Map<string, CliProbeOutcome>;
   probes: PreflightProbes;
 }
 
@@ -194,7 +197,12 @@ async function probeMcp(result: PreflightResult, options: PreflightOptions): Pro
   return { ...result, ok: !result.diagnostics.some(d => d.severity === 'refusal'), mcpTools: Object.freeze(inventory) };
 }
 
-function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+type ResolutionOptions = Omit<PreflightOptions, 'probes' | 'probeCache'>;
+
+/** Resolve static declarations before any CLI, model, command or trigger probe. */
+export function resolvePreflight(flow: unknown, options: ResolutionOptions): PreflightResult & {
+  compiled?: import('./compile.js').CompiledFlowSpec;
+} {
   // Compile before touching any environment fact. `compileSpec` snapshots raw
   // input into inert data, validates it against the closed authoring schema,
   // and lowers `output` sugar into its json_schema gate — so the gate plan
@@ -235,7 +243,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
   const cliResolutionDiagnostics: PreflightDiagnostic[] = [];
   const resolutions: CliResolution[] = [];
   const resolutionByStep = new Map<string, CliResolution>();
-  const cliProbeResults = new Map<string, CliProbeOutcome>();
+  const cliProbeResults = options.cliProbeCache ?? new Map<string, CliProbeOutcome>();
 
   // A pure fact about the compiled snapshot, collected before anything that
   // can return early. An unresolved CLI, an unknown model or a bad scope all
@@ -289,6 +297,18 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     return { ok: false, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics };
   }
 
+  return { ok: true, gates: compiled.steps.map(inspectStepGate), resolutions, diagnostics, compiled };
+}
+
+function preflightSync(flow: unknown, options: PreflightOptions): PreflightResult {
+  const { compiled, ...result } = resolvePreflight(flow, options);
+  if (!result.ok || compiled === undefined) return result;
+  const { diagnostics, resolutions } = result;
+  const resolutionByStep = new Map(resolutions.map(resolution => [resolution.stepId, resolution]));
+  // `cliProbeCache` is the public run-scoped name; `probeCache` is retained as
+  // a compatibility alias for the async authored-preflight path.
+  const cliProbeResults = options.cliProbeCache ?? options.probeCache ?? new Map<string, CliProbeOutcome>();
+
   for (const step of compiled.steps) {
     probeNamedGate(step, options.probes, diagnostics);
     warnOnVacuousGate(step, diagnostics);
@@ -333,7 +353,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
  * fact about the filesystem. Missing manifest means no known mounts — a grant
  * still parses but refuses as `mount_unknown` in that case.
  */
-function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightRefusal[] {
+function scopeDiagnostics(flow: FlowSpec, options: ResolutionOptions): PreflightRefusal[] {
   const workspace = flow.workspace;
   const toolsFs = flow.tools?.fs;
   if (workspace === undefined && toolsFs === undefined) return [];
@@ -357,7 +377,7 @@ function scopeDiagnostics(flow: FlowSpec, options: PreflightOptions): PreflightR
 /** Pure authoring validation: no executable, command, trigger, or daemon probe. */
 function unknownModelDiagnostics(
   flow: FlowSpec,
-  options: PreflightOptions,
+  options: ResolutionOptions,
   resolutionByStep: ReadonlyMap<string, CliResolution> = new Map(),
 ): PreflightRefusal[] {
   const diagnostics: PreflightRefusal[] = [];
@@ -471,7 +491,7 @@ function unknownModelMessage(
   return `Step "${stepId}" declares model "${model}"${cliContext}, but it is not listed in ${source}; add the exact model only after verifying that project is allowed to use it.`;
 }
 
-function unresolvedCliMessage(stepId: string, options: PreflightOptions): string {
+function unresolvedCliMessage(stepId: string, options: ResolutionOptions): string {
   const context = options.projectConfigPath !== undefined
     ? ` Nearest project config "${options.projectConfigPath}" declares no cli; outer configs are shadowed.`
     : options.projectSearchStart !== undefined
@@ -501,6 +521,10 @@ function resolveCli(
   return undefined;
 }
 
+export function cliProbeKey(resolution: CliResolution, managed = false): string {
+  return JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+}
+
 function probeResolvedCli(
   resolution: CliResolution,
   probes: PreflightProbes,
@@ -514,7 +538,7 @@ function probeResolvedCli(
   // Model is part of the key: the same CLI probed with two different models
   // is two different questions, and caching on the CLI alone would let a
   // model that the CLI cannot resolve inherit an earlier model's pass.
-  const cacheKey = JSON.stringify([resolution.cli, resolution.source, resolution.model ?? null, managed]);
+  const cacheKey = cliProbeKey(resolution, managed);
   let outcome = cache.get(cacheKey);
   if (outcome === undefined) {
     try {

package/src/relay-cli.ts

@@ -1,7 +1,6 @@
-import { readFileSync } from 'node:fs';
-
 import { runCli } from './cli.js';
 import { CLI_VERBS, CLI_VERB_NAMES, type CliCommandSpec } from './cli-commands.js';
+import { packageVersion } from './package-version.js';
 
 /**
  * The `@relayflows/sdk/relay-cli` entrypoint: a mountable CLI surface.
@@ -56,28 +55,6 @@ function toCommandSpec(verb: CliCommandSpec & { variants?: unknown }): CliComman
   return spec;
 }
 
-/**
- * Read this package's version from its own manifest.
- *
- * Resolved from `import.meta.url` rather than imported, because `package.json`
- * sits outside `rootDir` and a hardcoded literal would silently go stale at the
- * next release. `src/` and `dist/` are both one level below the manifest, so
- * the same relative path is correct before and after a build.
- */
-function packageVersion(): string {
-  try {
-    const manifest: unknown = JSON.parse(
-      readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
-    );
-    const version = (manifest as { version?: unknown }).version;
-    return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
-  } catch {
-    // A surface that cannot read its own manifest is still perfectly runnable;
-    // refusing to mount over a cosmetic field would be the worse failure.
-    return '0.0.0';
-  }
-}
-
 /**
  * Build the relayflows CLI surface.
  *