@relayflows/sdk 2.0.9 → 2.0.11

package/src/journal-reader.ts

@@ -0,0 +1,165 @@
+import { constants } from 'node:fs';
+import { copyFile, mkdtemp, open, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { journalRecordOffset } from './journal-offset.js';
+
+// Journal version 1's closed vocabulary (relayflowd-core/src/entry.rs).
+const ENTRY_TYPES = new Set([
+  'run.spawned', 'run.cancel.requested', 'event.received', 'subscription.registered',
+  'subscription.matched', 'subscription.stale', 'step.routed', 'step.attempt.started',
+  'step.completed', 'wait.event', 'wait.human', 'sleep.until', 'wait.completed',
+  'stream.appended', 'memory.injected', 'channel.appended', 'channel.delivered',
+  'channel.acknowledged', 'effect.recorded', 'effect.confirmed', 'epoch.summary',
+  'segment.closed', 'run.completed',
+]);
+
+/** The persisted envelope from relayflowd-core/src/entry.rs. */
+export interface JournalEvent {
+  seq: number;
+  segment_id: number;
+  entry_type: string;
+  run_id: string;
+  step_id: string | null;
+  attempt: number | null;
+  at_ms: number;
+  payload: unknown;
+}
+
+export type JournalReadFailure =
+  | 'invalid_run_id' | 'run_not_found' | 'step_not_found' | 'journal_read_failed';
+
+export class JournalReadError extends Error {
+  constructor(readonly code: JournalReadFailure, message: string) {
+    super(message);
+    this.name = 'JournalReadError';
+  }
+}
+
+async function fingerprint(path: string): Promise<string | undefined> {
+  try {
+    const info = await stat(path, { bigint: true });
+    if (!info.isFile()) throw new Error(`Journal path is not a regular file: ${path}`);
+    return [info.dev, info.ino, info.size, info.mtimeNs, info.ctimeNs].join(':');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Walk a stable on-disk journal in sequence order, across every segment.
+ * `at` includes the step's terminal completion, or its last journaled event
+ * if it has not terminated. Retries are included.
+ *
+ * SQLite read-only connections can still create/change WAL shared-memory files.
+ * Copy the database and its WAL into private scratch space before opening it,
+ * and reject concurrent source changes instead of returning a torn snapshot.
+ * Only scratch files are written; the run, registry and daemon are untouched.
+ */
+export async function* walkJournal(
+  runId: string,
+  dataDir: string,
+  options: { at?: string } = {},
+): AsyncIterable<JournalEvent> {
+  // Run ids are path components, never paths. Permit imported run names as
+  // well as the ULIDs produced by the kernel.
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(runId)) {
+    throw new JournalReadError('invalid_run_id', 'Run id must contain only letters, digits, underscores or hyphens, starting with a letter or digit.');
+  }
+  const source = join(resolve(dataDir), 'runs', `${runId}.sqlite3`);
+  let scratch: string | undefined;
+  let database: import('node:sqlite').DatabaseSync | undefined;
+  try {
+    const before = await Promise.all([fingerprint(source), fingerprint(`${source}-wal`)]);
+    if (before[0] === undefined) {
+      throw new JournalReadError('run_not_found', `Run "${runId}" does not exist in "${dataDir}".`);
+    }
+    scratch = await mkdtemp(join(tmpdir(), 'flows-replay-'));
+    const snapshot = join(scratch, 'journal.sqlite3');
+    await copyFile(source, snapshot, constants.COPYFILE_EXCL);
+    if (before[1] !== undefined) await copyFile(`${source}-wal`, `${snapshot}-wal`, constants.COPYFILE_EXCL);
+    const after = await Promise.all([fingerprint(source), fingerprint(`${source}-wal`)]);
+    if (before.some((value, index) => value !== after[index])) {
+      throw new Error('Journal changed while taking the replay snapshot; retry replay.');
+    }
+    const file = await open(snapshot, 'r');
+    try {
+      const header = Buffer.alloc(16);
+      const { bytesRead } = await file.read(header, 0, 16, 0);
+      const expected = Buffer.from('SQLite format 3\0');
+      for (let offset = 0; offset < expected.length; offset += 1) {
+        if (offset >= bytesRead || header[offset] !== expected[offset]) {
+          throw new Error(`Invalid SQLite header at journal byte offset ${offset}.`);
+        }
+      }
+    } finally { await file.close(); }
+
+    // Lazy loading keeps all existing CLI verbs independent of node:sqlite.
+    const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite') as typeof import('node:sqlite');
+    database = new DatabaseSync(snapshot, { readOnly: true });
+    const metadata = database.prepare("SELECT value FROM meta WHERE key = 'run_id'").get();
+    if (metadata?.['value'] !== runId) throw new Error('Journal run id does not match the requested run.');
+    const version = database.prepare("SELECT value FROM meta WHERE key = 'journal_version'").get();
+    if (version?.['value'] !== '1') throw new Error('Unsupported journal version.');
+    const integrity = database.prepare('PRAGMA quick_check').all();
+    if (integrity.length !== 1 || integrity[0]?.['quick_check'] !== 'ok') throw new Error('Journal integrity check failed.');
+
+    let through: number | undefined;
+    if (options.at !== undefined) {
+      const row = database.prepare(`
+        SELECT COALESCE(MAX(CASE WHEN entry_type = 'step.completed'
+          AND json_valid(payload) AND json_extract(payload, '$.disposition') = 'step_done'
+          THEN seq END), MAX(seq)) AS seq FROM entries WHERE step_id = ?
+      `).get(options.at);
+      if (row?.['seq'] === null || row === undefined) {
+        throw new JournalReadError('step_not_found', `Step "${options.at}" is not journaled in run "${runId}".`);
+      }
+      through = integer(row['seq'], 'seq');
+    }
+    const rows = database.prepare(
+      'SELECT seq, segment_id, entry_type, step_id, attempt, at_ms, payload FROM entries'
+        + (through === undefined ? '' : ' WHERE seq <= ?') + ' ORDER BY seq',
+    ).iterate(...(through === undefined ? [] : [through]));
+    for (const row of rows) {
+      try {
+        if (typeof row['entry_type'] !== 'string' || !ENTRY_TYPES.has(row['entry_type'])
+          || typeof row['payload'] !== 'string'
+          || (row['step_id'] !== null && typeof row['step_id'] !== 'string')) {
+          throw new Error('Invalid journal entry or unknown record type.');
+        }
+        yield {
+          seq: integer(row['seq'], 'seq'),
+          segment_id: integer(row['segment_id'], 'segment_id'),
+          entry_type: row['entry_type'],
+          run_id: runId,
+          step_id: row['step_id'],
+          attempt: row['attempt'] === null ? null : integer(row['attempt'], 'attempt'),
+          at_ms: integer(row['at_ms'], 'at_ms'),
+          payload: JSON.parse(row['payload']),
+        };
+      } catch (error) {
+        const root = database.prepare("SELECT rootpage FROM sqlite_schema WHERE name = 'entries'").get();
+        const location = journalRecordOffset(snapshot, integer(root?.['rootpage'], 'rootpage'), integer(row['seq'], 'seq'));
+        throw new Error(`Entry seq ${row['seq']} at ${location}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  } catch (error) {
+    if (error instanceof JournalReadError) throw error;
+    throw new JournalReadError('journal_read_failed', `Cannot read journal for run "${runId}": ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    try {
+      database?.close();
+    } finally {
+      if (scratch !== undefined) await rm(scratch, { recursive: true, force: true });
+    }
+  }
+}
+
+function integer(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+    throw new Error(`Invalid journal ${field}: expected a safe integer.`);
+  }
+  return value;
+}

package/src/json-schema.ts

@@ -22,24 +22,7 @@ export function jsonSchemaError(schema: boolean | Record<string, unknown>): stri
   const unbounded = jsonSchemaBoundError(schema);
   if (unbounded !== undefined) return unbounded;
   try {
-    const dialect = typeof schema === 'object' && typeof schema['$schema'] === 'string'
-      ? schema['$schema'].replace(/#$/, '')
-      : DRAFT_2020_12;
-    const options = { strict: false, allErrors: true } as const;
-    if (dialect === DRAFT_4) {
-      new AjvDraft4(options).compile(schema);
-    } else if (dialect === DRAFT_6) {
-      const validator = new Ajv(options);
-      validator.addMetaSchema(draft6MetaSchema);
-      validator.compile(schema);
-    } else if (dialect === DRAFT_7) {
-      new Ajv(options).compile(schema);
-    } else if (dialect === DRAFT_2019_09) {
-      new Ajv2019(options).compile(schema);
-    } else {
-      // Ajv reports unknown dialect identifiers instead of guessing.
-      new Ajv2020(options).compile(schema);
-    }
+    compileSchema(schema);
     return undefined;
   } catch (error) {
     // A RangeError here is Ajv exhausting its own JS stack while COMPILING,
@@ -63,3 +46,36 @@ export function snapshotJsonSchema(schema: unknown, at: string): boolean | Recor
   if (snapshot !== null && !Array.isArray(snapshot) && typeof snapshot === 'object') return snapshot;
   throw new Error(`${at}: expected a JSON Schema object or boolean`);
 }
+
+function compileSchema(schema: boolean | Record<string, unknown>) {
+  const dialect = typeof schema === 'object' && typeof schema['$schema'] === 'string'
+    ? schema['$schema'].replace(/#$/, '')
+    : DRAFT_2020_12;
+  const options = { strict: false, allErrors: true } as const;
+  if (dialect === DRAFT_4) {
+    return new AjvDraft4(options).compile(schema);
+  } else if (dialect === DRAFT_6) {
+    const validator = new Ajv(options);
+    validator.addMetaSchema(draft6MetaSchema);
+    return validator.compile(schema);
+  } else if (dialect === DRAFT_7) {
+    return new Ajv(options).compile(schema);
+  } else if (dialect === DRAFT_2019_09) {
+    return new Ajv2019(options).compile(schema);
+  } else {
+    // Ajv reports unknown dialect identifiers instead of guessing.
+    return new Ajv2020(options).compile(schema);
+  }
+}
+
+/** A worker verdict; the kernel independently verifies the same schema. */
+export function jsonSchemaOutputError(schema: boolean | Record<string, unknown>, output: unknown): string | undefined {
+  const invalid = jsonSchemaError(schema);
+  if (invalid !== undefined) return invalid;
+  try {
+    const validate = compileSchema(schema);
+    return validate(output) ? undefined : JSON.stringify(validate.errors);
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}

package/src/llm-worker.ts

@@ -0,0 +1,82 @@
+import { workerSpend } from './worker-spend.js';
+import type { WorkerCliResult } from './worker-cli.js';
+import { EventEmitter } from 'node:events';
+import type { JournalClient } from './journal-client.js';
+import type { CompletionReason, StepDispatchEvent } from './protocol.js';
+import type { KernelLlmStep } from './spec.js';
+import { runAgentCli } from './worker-cli.js';
+import { withWorkerLease } from './worker-lease.js';
+import { workerInstruction } from './worker-input.js';
+import { jsonSchemaOutputError } from './json-schema.js';
+
+/** Bare value-producing LLM dispatch, without agent workspace/recovery pins. */
+export class LlmWorker extends EventEmitter {
+  private attached = false;
+  private closing = false;
+  private readonly inFlight = new Set<Promise<void>>();
+
+  constructor(private readonly client: JournalClient, private readonly workerId: string) {
+    super();
+  }
+
+  async attach(): Promise<void> {
+    if (this.attached || this.closing) throw new Error('llm worker: cannot attach twice or after close');
+    this.client.on('step.dispatch', this.onDispatch);
+    try {
+      await this.client.workerAttach(this.workerId, ['llm'], { workspace: [], streams: [] }, 1);
+      this.attached = true;
+    } catch (error) {
+      this.client.off('step.dispatch', this.onDispatch);
+      throw error;
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closing = true;
+    this.client.off('step.dispatch', this.onDispatch);
+    await Promise.allSettled([...this.inFlight]);
+  }
+
+  private readonly onDispatch = (dispatch: StepDispatchEvent): void => {
+    if (this.closing || dispatch.step_type !== 'llm') return;
+    const running = this.execute(dispatch).catch(error => { this.emit('error', error); });
+    this.inFlight.add(running);
+    void running.finally(() => { this.inFlight.delete(running); });
+  };
+
+  private async execute(dispatch: StepDispatchEvent): Promise<void> {
+    const spec = dispatch.spec as KernelLlmStep;
+    const schema = spec.verification?.json_schema;
+    const prompt = schema === undefined ? spec.prompt
+      : `${spec.prompt}\n\nReturn only a JSON value matching this JSON Schema (no Markdown fences):\n${JSON.stringify(schema)}`;
+    const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
+      typeof spec.cli === 'string' && typeof spec.prompt === 'string'
+        ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, spec.model, undefined, signal, 'llm')
+        : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
+    const { result, usage } = workerSpend(completed, spec.model);
+    let reason: CompletionReason = result.exit_code === 0 ? 'success' : 'worker_error';
+    let output: unknown = result.stdout_tail;
+    let detail = result.stderr_tail;
+    if (reason === 'success' && schema !== undefined) {
+      try {
+        output = JSON.parse(result.stdout_tail);
+        const invalid = jsonSchemaOutputError(schema, output);
+        if (invalid !== undefined) {
+          reason = 'verification_failed';
+          detail = `LLM output does not match its declared schema: ${invalid}`;
+        }
+      } catch {
+        reason = 'verification_failed';
+        detail = 'LLM output is not valid JSON.';
+      }
+    }
+    // Never submit schema-invalid JSON as a successful completion. The kernel
+    // also runs its own gate before making output available to dependents.
+    await this.client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+      dispatch.idempotency_key, reason, {
+        output,
+        ...(usage !== undefined ? { usage } : {}),
+        ...(reason === 'success' ? {} : { trajectory_tail: { error: detail } }),
+      });
+  }
+}

package/src/local-agent.ts

@@ -0,0 +1,30 @@
+import { randomUUID } from 'node:crypto';
+import type { JournalClient } from './journal-client.js';
+import { AgentWorker } from './worker.js';
+
+/** A local worker for stream-only steps; no workspace recovery is claimed. */
+export async function attachLocalAgent(client: JournalClient, dataDir?: string, onPtyReady?: (path: string) => void): Promise<{
+  stream: string;
+  readonly failure: unknown;
+  close(): Promise<void>;
+}> {
+  // A fresh, unconsumed stream has offset zero. The executor declares exactly
+  // this stream on its agent steps. No worktree revision is invented.
+  const stream = `local-agent-${randomUUID()}`;
+  const worker = new AgentWorker(client, {
+    workerId: stream,
+    capacity: 1,
+    dataDir, onPtyReady,
+    pins: { workspace: [], streams: [{ stream, read_offset: 0 }] },
+  });
+  let failure: unknown;
+  worker.on('error', error => { failure = error; client.close(); });
+  await worker.attach();
+  return {
+    stream,
+    get failure() { return failure; },
+    async close() {
+      await worker.close();
+    },
+  };
+}

package/src/mcp-client.ts

@@ -0,0 +1,97 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { Agent } from 'undici';
+import type { McpServerConfig } from './spec.js';
+import { McpStdioTransport } from './mcp-stdio.js';
+
+export type McpDiagnostic = 'spawn_failed' | 'handshake_timeout' | 'handshake_rejected' | 'mcp_disconnected';
+export class McpError extends Error {
+  constructor(readonly code: McpDiagnostic) { super(code); }
+}
+export interface McpSession {
+  listTools(): Promise<string[]>;
+  callTool(name: string, args: unknown): Promise<unknown>;
+  close(): Promise<void>;
+}
+
+/** One bounded session, never a reconnect/retry loop. Protocol and framing are
+ * supplied by the official SDK; this adapter owns resource lifetimes. */
+export async function openMcpSession(config: McpServerConfig, timeoutMs: number): Promise<McpSession> {
+  const client = new Client({ name: 'relayflows', version: '1.0.0' });
+  const controller = new AbortController();
+  let dispatcher: Agent | undefined;
+  let transport: Transport;
+  if ('command' in config) {
+    transport = new McpStdioTransport(config);
+  } else {
+    dispatcher = new Agent();
+    transport = new StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: { headers: config.headers },
+      reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 0, maxReconnectionDelay: 0, reconnectionDelayGrowFactor: 1 },
+      fetch: (url, init) => fetch(url, {
+        ...init, redirect: 'error',
+        signal: AbortSignal.any([controller.signal, ...(init?.signal ? [init.signal] : [])]),
+        dispatcher,
+      } as RequestInit),
+    });
+  }
+  let closing: Promise<void> | undefined;
+  const close = (): Promise<void> => closing ??= (async () => {
+    controller.abort();
+    try { await client.close(); } finally {
+      await transport.close();
+      await dispatcher?.destroy();
+    }
+  })();
+  let phase: 'handshake' | 'call' = 'handshake';
+  let failure: McpError | undefined;
+  let rejectTransport!: (error: McpError) => void;
+  const broken = new Promise<never>((_, reject) => { rejectTransport = reject; });
+  void broken.catch(() => undefined);
+  const fail = (code: McpDiagnostic): void => {
+    failure ??= new McpError(code);
+    rejectTransport(failure);
+  };
+  client.onerror = error => {
+    const code = (error as NodeJS.ErrnoException).code;
+    fail(phase === 'call' ? 'mcp_disconnected'
+      : code === 'ENOENT' || code === 'EACCES' ? 'spawn_failed' : 'handshake_rejected');
+  };
+  client.onclose = () => {
+    if (!closing) fail(phase === 'call' ? 'mcp_disconnected' : 'handshake_rejected');
+  };
+  const bounded = async <T>(work: () => Promise<T>): Promise<T> => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      if (failure) throw failure;
+      return await Promise.race([work(), broken, new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new McpError(phase === 'call' ? 'mcp_disconnected' : 'handshake_timeout')), timeoutMs);
+      })]);
+    } catch (error) {
+      await close();
+      throw error instanceof McpError ? error : new McpError(phase === 'call' ? 'mcp_disconnected' : 'handshake_rejected');
+    } finally { clearTimeout(timer); }
+  };
+  await bounded(() => client.connect(transport));
+  return {
+    listTools: () => bounded(async () => {
+      const names: string[] = [];
+      const cursors = new Set<string>();
+      let cursor: string | undefined;
+      do {
+        const page = await client.listTools(cursor === undefined ? {} : { cursor });
+        names.push(...page.tools.map(tool => tool.name));
+        cursor = page.nextCursor;
+        if (cursor !== undefined && cursors.has(cursor)) throw new McpError('handshake_rejected');
+        if (cursor !== undefined) cursors.add(cursor);
+      } while (cursor !== undefined);
+      return [...new Set(names)];
+    }),
+    callTool: (name, args) => {
+      phase = 'call';
+      return bounded(() => client.callTool({ name, arguments: args as Record<string, unknown> }));
+    },
+    close,
+  };
+}

package/src/mcp-config.ts

@@ -0,0 +1,42 @@
+import type { McpServerConfig } from './spec.js';
+
+/** Called on parsed project JSON before any process or connection is opened. */
+export function parseMcpConfig(value: unknown): Record<string, McpServerConfig> {
+  if (!record(value)) throw new Error('mcp must be a server map');
+  const result: Record<string, McpServerConfig> = Object.create(null);
+  for (const [name, config] of Object.entries(value)) {
+    const invalid = (): never => { throw new Error(`mcp.${name} has an invalid server configuration`); };
+    if (!name.trim() || !record(config)) invalid();
+    const entry = config as Record<string, unknown>;
+    const stdio = Object.hasOwn(entry, 'command');
+    if (stdio === Object.hasOwn(entry, 'url')) invalid();
+    const allowed = stdio ? ['command', 'args', 'env'] : ['url', 'headers'];
+    if (Object.keys(entry).some(key => !allowed.includes(key))) invalid();
+    if (stdio) {
+      if (!nonempty(entry.command)) invalid();
+      if (entry.args !== undefined && (!Array.isArray(entry.args)
+        || !entry.args.every(arg => typeof arg === 'string' && !arg.includes('\0')))) invalid();
+      if (entry.env !== undefined && (!Array.isArray(entry.env)
+        || !entry.env.every(key => typeof key === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        || new Set(entry.env).size !== entry.env.length)) invalid();
+    } else {
+      if (!nonempty(entry.url)) invalid();
+      let url: URL;
+      try { url = new URL(entry.url as string); } catch { invalid(); }
+      if (!['http:', 'https:'].includes(url!.protocol) || url!.username || url!.password || url!.hash) invalid();
+      if (entry.headers !== undefined) {
+        if (!record(entry.headers) || !Object.values(entry.headers).every(v => typeof v === 'string')) invalid();
+        try { new Headers(entry.headers as Record<string, string>); } catch { invalid(); }
+      }
+    }
+    result[name] = entry as McpServerConfig;
+  }
+  return result;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonempty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+}

package/src/mcp-stdio.ts

@@ -0,0 +1,84 @@
+import { childStop, type ChildStop } from './child-stop.js';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/sdk/shared/stdio.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import type { McpServerConfig } from './spec.js';
+
+/** SDK framing with parent-owned spawning/cleanup: SDK's stdio transport
+ * unconditionally inherits HOME/PATH/etc. and cannot enforce our env contract. */
+export class McpStdioTransport implements Transport {
+  onclose?: Transport['onclose'];
+  onerror?: Transport['onerror'];
+  onmessage?: Transport['onmessage'];
+  private child?: ChildProcessWithoutNullStreams;
+  private stopTree?: ChildStop;
+  private readonly buffer = new ReadBuffer({ maxBufferSize: 1_048_576 });
+  private closed?: Promise<void>;
+  private closing?: Promise<void>;
+  constructor(private readonly config: Extract<McpServerConfig, { command: string }>) {}
+
+  async start(): Promise<void> {
+    const env: NodeJS.ProcessEnv = Object.create(null);
+    for (const name of this.config.env ?? []) {
+      if (process.env[name] !== undefined) env[name] = process.env[name];
+    }
+    const child = this.child = spawn(this.config.command, this.config.args ?? [], {
+      env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+    });
+    this.stopTree = childStop(child, process.platform !== 'win32');
+    this.closed = new Promise(resolve => child.once('close', () => resolve()));
+    child.stderr.resume();
+    child.stdout.on('data', (chunk: Buffer) => {
+      if (this.closing) return;
+      try {
+        this.buffer.append(chunk);
+        let message: JSONRPCMessage | null;
+        while ((message = this.buffer.readMessage()) !== null) this.onmessage?.(message);
+      } catch (error) { this.onerror?.(error as Error); }
+    });
+    child.stdout.once('end', () => this.onclose?.());
+    child.stdout.on('error', error => this.onerror?.(error));
+    child.stdin.on('error', error => this.onerror?.(error));
+    child.on('error', error => this.onerror?.(error));
+    await new Promise<void>((resolve, reject) => {
+      child.once('spawn', resolve);
+      child.once('error', reject);
+    });
+  }
+
+  send(message: JSONRPCMessage): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.child || this.closing) return reject(new Error('MCP transport closed'));
+      this.child.stdin.write(serializeMessage(message), error => error ? reject(error) : resolve());
+    });
+  }
+
+  close(): Promise<void> {
+    return this.closing ??= this.stop();
+  }
+
+  private async stop(): Promise<void> {
+    const child = this.child;
+    if (!child) return;
+    child.stdin.end();
+    this.stopTree!.terminate();
+    // A direct-child close is insufficient: wrappers can leave descendants
+    // alive with either inherited pipes or completely detached stdio.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const deadline = new Promise<void>(resolve => { timer = setTimeout(resolve, 1000); });
+    await Promise.race([this.closed, deadline]);
+    if (!this.stopTree!.maySettleOnChildExit()) await deadline;
+    clearTimeout(timer);
+    if (child.exitCode === null && child.signalCode === null && child.pid !== undefined) {
+      const exited = new Promise<void>(resolve => child.once('exit', () => resolve()));
+      this.stopTree!.kill();
+      await exited;
+    }
+    child.stdin.destroy();
+    child.stdout.destroy();
+    child.stderr.destroy();
+    this.buffer.clear();
+    this.onclose?.();
+  }
+}

package/src/model-pricing.ts

@@ -0,0 +1,32 @@
+/** Frozen dollars per million tokens. Each rate is an integer microdollar per token. */
+export const MODEL_PRICING: Readonly<Record<string, Readonly<{ input: number; output: number }>>> = Object.freeze({
+  'claude-sonnet-4-6': Object.freeze({ input: 3, output: 15 }),
+  'claude-opus-4-7': Object.freeze({ input: 15, output: 75 }),
+  'codex-medium': Object.freeze({ input: 2, output: 8 }),
+  'codex-large': Object.freeze({ input: 5, output: 20 }),
+});
+
+export function hasPricing(model: string | undefined): boolean {
+  return model !== undefined && Object.hasOwn(MODEL_PRICING, model);
+}
+
+/**
+ * Cost accounting for a step's declared model.
+ *
+ * Returns `undefined` for unpriced models — callers should omit `usage`
+ * from the journal payload rather than sending nulls that break the kernel
+ * wire schema. The refusal for a declared dollar budget against an unpriced
+ * model is `budgetDiagnostics` at preflight (before any CLI dispatches).
+ * Throwing here after usage decode would waste the CLI invocation that
+ * preflight was meant to prevent.
+ */
+export function pricedUsage(model: string | undefined, input = 0, output = 0):
+  | { tokens_in: number; tokens_out: number; dollars: string }
+  | undefined
+{
+  if (![input, output].every(n => Number.isSafeInteger(n) && n >= 0)) throw new Error('Invalid token usage');
+  const price = model === undefined || !Object.hasOwn(MODEL_PRICING, model) ? undefined : MODEL_PRICING[model];
+  if (price === undefined) return undefined;
+  const micro = BigInt(input) * BigInt(price.input) + BigInt(output) * BigInt(price.output);
+  return { tokens_in: input, tokens_out: output, dollars: `${micro / 1_000_000n}.${String(micro % 1_000_000n).padStart(6, '0')}` };
+}

package/src/mount-registry.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isScopePath, SCOPE_MODES, type MountRegistry } from './scope-compiler.js';
+
+/**
+ * Local relayfile shim: nearest relayfile.mounts.json contains
+ * {version: 1, mounts: {acme: [{path: "api", modes: ["readonly"]}]}}.
+ * It describes existing mount capabilities, not additional flow permissions.
+ * No manifest means no known mounts. An unreadable/invalid manifest fails closed.
+ */
+export function readMountRegistry(start: string): MountRegistry {
+  let directory = start;
+  for (;;) {
+    const path = join(directory, 'relayfile.mounts.json');
+    let source: string;
+    try {
+      source = readFileSync(path, 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      const parent = dirname(directory);
+      if (parent === directory) return {};
+      directory = parent;
+      continue;
+    }
+    const value: unknown = JSON.parse(source);
+    if (!isObject(value) || value.version !== 1
+      || Object.keys(value).some(key => !['version', 'mounts'].includes(key))
+      || !isObject(value.mounts)) throw new Error(`Invalid relayfile mount manifest "${path}".`);
+    for (const [name, prefixes] of Object.entries(value.mounts)) {
+      if (!/^[A-Za-z0-9_-]+$/.test(name) || !Array.isArray(prefixes)
+        || !prefixes.every(prefix => isObject(prefix)
+          && Object.keys(prefix).every(key => ['path', 'modes'].includes(key))
+          && isScopePath(prefix.path) && Array.isArray(prefix.modes)
+          && prefix.modes.every(mode => SCOPE_MODES.includes(mode)))) {
+        throw new Error(`Invalid relayfile mount "${name}" in "${path}".`);
+      }
+    }
+    return value.mounts as MountRegistry;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}