@agilno-tech/rivet 0.1.0-alpha.0

package/src/clients/claude.js

@@ -0,0 +1,214 @@
+import { lstat } from 'node:fs/promises';
+
+import { checkCompatibility, validVersion } from './compatibility.js';
+import { createLaunchContract, failAgent } from './contract.js';
+import { createProcessRunner } from './process-runner.js';
+import { agentResultContract } from './result-contract.js';
+import { featureDecompositionResultContract } from '../feature/decomposition-contract.js';
+import { serializeLaunchContract } from '../prompts/launch-contract.js';
+import { serializeProtocolLaunch } from '../protocols/presentation.js';
+import { serializePlanningContract } from '../prompts/planning-contract.js';
+import { CLAUDE_FEATURE_PROFILE } from '../feature/client-profile.js';
+
+const ARGS = Object.freeze([
+  '--print', '--input-format', 'text', '--output-format', 'json', '--no-session-persistence', '{stdin}',
+]);
+const PLANNING_TOOLS = 'Read,Glob,Grep';
+const PLANNING_SCHEMA = JSON.stringify(featureDecompositionResultContract().schema);
+export const CLAUDE_ADAPTER_SYNTAX = Object.freeze({
+  version: 1,
+  provider: 'claude',
+  observedVersion: '2.1.207 (Claude Code)',
+  testedVersions: Object.freeze(['2.1.207 (Claude Code)', '2.1.274 (Claude Code)']),
+  requiredOptions: Object.freeze(['--print', '--input-format', '--output-format', '--no-session-persistence', '--model', '--effort', '--permission-mode', '--tools', '--json-schema', '--max-budget-usd']),
+  versionArgs: Object.freeze(['--version']),
+  args: ARGS,
+  inputMode: 'stdin-text',
+  outputMode: 'json-structured-output-envelope-v1',
+  optionalArgs: Object.freeze([
+    '--model <id>', '--effort <low|medium|high|max>', '--max-budget-usd <amount>',
+    '--permission-mode <acceptEdits|dontAsk|plan>', '--safe-mode',
+    '--tools <Read,Glob,Grep>', '--json-schema <approved-schema>',
+  ]),
+});
+
+const CONFIG_KEYS = new Set(['executable', 'interpreter', 'expectedVersion', 'args', 'environment', 'timeoutMs', 'maxOutputBytes']);
+const PLANNING_CONFIG_KEYS = new Set(['executable', 'interpreter', 'expectedVersion', 'worktree', 'environment', 'timeoutMs', 'maxOutputBytes']);
+
+function stable(operation) {
+  try { return operation(); } catch { failAgent('template-invalid'); }
+}
+
+function capture(input, keys, required) {
+  return stable(() => {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) failAgent('template-invalid');
+    const ownKeys = Reflect.ownKeys(input);
+    if (ownKeys.length > keys.size || ownKeys.some(key => typeof key !== 'string' || !keys.has(key))) failAgent('template-invalid');
+    const output = Object.create(null);
+    for (const key of ownKeys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      output[key] = input[key];
+    }
+    if (required.some(key => !Object.hasOwn(output, key))) failAgent('template-invalid');
+    return output;
+  });
+}
+
+function captureArgs(input) {
+  return stable(() => {
+    if (!Array.isArray(input)) failAgent('template-invalid');
+    const prototype = Object.getPrototypeOf(input);
+    const length = input.length;
+    if (prototype !== Array.prototype || !Number.isSafeInteger(length)
+      || length < ARGS.length || length > ARGS.length + 13) failAgent('template-invalid');
+    const result = [];
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      const value = input[index];
+      const maxLength = result.at(-1) === '--json-schema' ? 4096 : 200;
+      if (typeof value !== 'string' || value.length === 0 || value.length > maxLength || /[\u0000\r\n]/.test(value)) failAgent('template-invalid');
+      result.push(value);
+    }
+    const required = ARGS.slice(0, -1);
+    if (result.at(-1) !== '{stdin}' || result.filter(value => value === '{stdin}').length !== 1
+      || required.some((value, index) => result[index] !== value)) failAgent('template-invalid');
+    const seen = new Set();
+    for (let index = required.length; index < result.length - 1; index += 1) {
+      const option = result[index];
+      if (seen.has(option)) failAgent('template-invalid');
+      seen.add(option);
+      if (option === '--safe-mode') continue;
+      const value = result[index + 1];
+      index += 1;
+      if (option === '--model' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(value)) continue;
+      if (option === '--effort' && ['low', 'medium', 'high', 'max'].includes(value)) continue;
+      if (option === '--max-budget-usd' && /^(?:0|[1-9]\d*)(?:\.\d{1,6})?$/.test(value)
+        && Number(value) > 0 && Number(value) <= 10_000) continue;
+      if (option === '--permission-mode' && ['acceptEdits', 'dontAsk', 'plan'].includes(value)) continue;
+      if (option === '--tools' && value === PLANNING_TOOLS) continue;
+      if (option === '--json-schema' && value === PLANNING_SCHEMA) continue;
+      failAgent('template-invalid');
+    }
+    return Object.freeze(result.filter(value => value !== '{stdin}'));
+  });
+}
+
+function captureEnvironment(input) {
+  if (input === undefined) return undefined;
+  return stable(() => {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.getPrototypeOf(input) !== Object.prototype) failAgent('template-invalid');
+    const keys = Reflect.ownKeys(input);
+    if (keys.length > 64 || keys.some(key => typeof key !== 'string')) failAgent('template-invalid');
+    const output = Object.create(null);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      const value = input[key];
+      if (typeof value !== 'string') failAgent('template-invalid');
+      output[key] = value;
+    }
+    return Object.freeze(output);
+  });
+}
+
+export function createClaudeClient(input) {
+  const config = capture(input, CONFIG_KEYS, ['executable', 'args']);
+  if (typeof config.executable !== 'string' || !config.executable.startsWith('/') || config.executable.length > 1024
+    || (config.interpreter !== undefined && (typeof config.interpreter !== 'string' || !config.interpreter.startsWith('/') || config.interpreter.length > 1024))
+    || (config.expectedVersion !== undefined && !validVersion(config.expectedVersion))) failAgent('template-invalid');
+  const args = captureArgs(config.args);
+  if (['--max-budget-usd', '--tools', '--json-schema'].some(option => args.includes(option))) failAgent('template-invalid');
+  const environment = captureEnvironment(config.environment);
+  const executable = config.executable;
+  const interpreter = config.interpreter;
+  const expectedVersion = config.expectedVersion;
+  const timeoutMs = config.timeoutMs;
+  const maxOutputBytes = config.maxOutputBytes;
+
+  async function launch(contractInput, optionInput = {}) {
+    const options = capture(optionInput, new Set(['signal','protocolContext']), []);
+    const signalState = stable(() => {
+      const value = options.signal;
+      if (value !== undefined && (!(value instanceof AbortSignal) || Object.getPrototypeOf(value) !== AbortSignal.prototype)) failAgent('template-invalid');
+      return Object.freeze({ value, aborted: value?.aborted === true });
+    });
+    if (signalState.aborted) failAgent('aborted');
+    const contract = createLaunchContract(contractInput);
+    serializeProtocolLaunch(contract, options.protocolContext);
+    const runner = await createProcessRunner({
+      executable, interpreter, worktree: contract.worktree.path,
+      worktreeIdentity: { dev: contract.worktree.dev, ino: contract.worktree.ino },
+      environment, signal: signalState.value,
+      timeoutMs: Math.min(timeoutMs ?? contract.budget.maxRuntimeMs, contract.budget.maxRuntimeMs, 10 * 60_000),
+      maxOutputBytes, allowOptionArgs: true, resultFormat: 'claude-json',
+    });
+    await checkCompatibility(runner, 'claude', [...args, '--json-schema', '--max-budget-usd'], expectedVersion);
+    return runner.run({
+      args: Object.freeze([
+        ...args,
+        '--json-schema', JSON.stringify(agentResultContract(contract.evidence).schema),
+        '--max-budget-usd', String(contract.budget.maxCostUsd),
+      ]),
+      cwd: '.', payload: serializeLaunchContract(contract), protocolContext: options.protocolContext, signal: signalState.value,
+    });
+  }
+
+  return Object.freeze({ provider: 'claude', syntaxVersion: 1, launch });
+}
+
+export function createClaudePlanningClient(input) {
+  const config = capture(input, PLANNING_CONFIG_KEYS, ['executable', 'worktree']);
+  if (typeof config.executable !== 'string' || !config.executable.startsWith('/') || config.executable.length > 1024
+    || (config.interpreter !== undefined && (typeof config.interpreter !== 'string' || !config.interpreter.startsWith('/') || config.interpreter.length > 1024))
+    || (config.expectedVersion !== undefined && !validVersion(config.expectedVersion))
+    || typeof config.worktree !== 'string' || !config.worktree.startsWith('/') || config.worktree.length > 1024) {
+    failAgent('template-invalid');
+  }
+  const args = captureArgs([
+    ...ARGS.slice(0, -1),
+    '--model', CLAUDE_FEATURE_PROFILE.model,
+    '--effort', CLAUDE_FEATURE_PROFILE.planning.effort,
+    '--max-budget-usd', String(CLAUDE_FEATURE_PROFILE.planning.maxCostUsd),
+    '--permission-mode', 'dontAsk',
+    '--tools', PLANNING_TOOLS,
+    '--json-schema', PLANNING_SCHEMA,
+    '{stdin}',
+  ]);
+  const environment = captureEnvironment(config.environment);
+  const executable = config.executable;
+  const interpreter = config.interpreter;
+  const expectedVersion = config.expectedVersion;
+  const worktree = config.worktree;
+
+  async function propose(contract, optionInput = {}) {
+    const options = capture(optionInput, new Set(['signal']), []);
+    const signal = options.signal;
+    if (signal !== undefined && (!(signal instanceof AbortSignal) || Object.getPrototypeOf(signal) !== AbortSignal.prototype)) {
+      failAgent('template-invalid');
+    }
+    if (signal?.aborted) failAgent('aborted');
+    let metadata;
+    try { metadata = await lstat(worktree, { bigint: true }); } catch { failAgent('provider-unavailable'); }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) failAgent('provider-unavailable');
+    const identity = Object.freeze({ dev: metadata.dev.toString(), ino: metadata.ino.toString() });
+    const runner = await createProcessRunner({
+      executable, interpreter, worktree, worktreeIdentity: identity, environment, signal,
+      timeoutMs: config.timeoutMs, maxInputBytes: 512 * 1024,
+      maxOutputBytes: config.maxOutputBytes ?? 512 * 1024, allowOptionArgs: true,
+    });
+    await checkCompatibility(runner, 'claude', [...args, '--json-schema', '--max-budget-usd'], expectedVersion);
+    return runner.runPlanning({
+      args,
+      cwd: '.',
+      payload: serializePlanningContract({
+        worktree: { path: worktree, ...identity, reservationId: 'planning-read-only' },
+        contract,
+      }),
+      signal,
+    });
+  }
+
+  return Object.freeze({ provider: 'claude', syntaxVersion: 1, propose });
+}

package/src/clients/codex.js

@@ -0,0 +1,180 @@
+import { lstat } from 'node:fs/promises';
+
+import { checkCompatibility, validVersion } from './compatibility.js';
+import { createLaunchContract, failAgent } from './contract.js';
+import { createProcessRunner } from './process-runner.js';
+import { serializeLaunchContract } from '../prompts/launch-contract.js';
+import { serializeProtocolLaunch } from '../protocols/presentation.js';
+import { serializePlanningContract } from '../prompts/planning-contract.js';
+
+const ARGS = Object.freeze(['exec', '--ephemeral', '--ignore-user-config', '--color', 'never', '{stdin}']);
+export const CODEX_ADAPTER_SYNTAX = Object.freeze({
+  version: 1,
+  provider: 'codex',
+  observedVersion: 'codex-cli 0.148.0-alpha.9',
+  testedVersions: Object.freeze(['codex-cli 0.148.0-alpha.9', 'codex-cli 0.155.0-alpha.16']),
+  requiredOptions: Object.freeze(['--ephemeral', '--ignore-user-config', '--color', '--sandbox']),
+  versionArgs: Object.freeze(['--version']),
+  args: ARGS,
+  inputMode: 'stdin-text',
+  outputMode: 'direct-final-text-envelope-v1',
+  optionalArgs: Object.freeze(['--model <id>', '--sandbox <read-only|workspace-write>', '--strict-config']),
+});
+
+const CONFIG_KEYS = new Set(['executable', 'interpreter', 'expectedVersion', 'args', 'environment', 'timeoutMs', 'maxOutputBytes']);
+const PLANNING_CONFIG_KEYS = new Set(['executable', 'interpreter', 'expectedVersion', 'worktree', 'environment', 'timeoutMs', 'maxOutputBytes']);
+
+function stable(operation) {
+  try { return operation(); } catch { failAgent('template-invalid'); }
+}
+
+function capture(input, keys, required) {
+  return stable(() => {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) failAgent('template-invalid');
+    const ownKeys = Reflect.ownKeys(input);
+    if (ownKeys.length > keys.size || ownKeys.some(key => typeof key !== 'string' || !keys.has(key))) failAgent('template-invalid');
+    const output = Object.create(null);
+    for (const key of ownKeys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      output[key] = input[key];
+    }
+    if (required.some(key => !Object.hasOwn(output, key))) failAgent('template-invalid');
+    return output;
+  });
+}
+
+function captureArgs(input) {
+  return stable(() => {
+    if (!Array.isArray(input)) failAgent('template-invalid');
+    const prototype = Object.getPrototypeOf(input);
+    const length = input.length;
+    if (prototype !== Array.prototype || !Number.isSafeInteger(length)
+      || length < ARGS.length || length > ARGS.length + 6) failAgent('template-invalid');
+    const result = [];
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      const value = input[index];
+      if (typeof value !== 'string' || value.length === 0 || value.length > 200 || /[\u0000\r\n]/.test(value)) failAgent('template-invalid');
+      result.push(value);
+    }
+    const required = ARGS.slice(0, -1);
+    if (result.at(-1) !== '{stdin}' || result.filter(value => value === '{stdin}').length !== 1
+      || required.some((value, index) => result[index] !== value)) failAgent('template-invalid');
+    const seen = new Set();
+    for (let index = required.length; index < result.length - 1; index += 1) {
+      const option = result[index];
+      if (seen.has(option)) failAgent('template-invalid');
+      seen.add(option);
+      if (option === '--strict-config') continue;
+      const value = result[index + 1];
+      index += 1;
+      if (option === '--model' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(value)) continue;
+      if (option === '--sandbox' && ['read-only', 'workspace-write'].includes(value)) continue;
+      failAgent('template-invalid');
+    }
+    return Object.freeze(result.filter(value => value !== '{stdin}'));
+  });
+}
+
+function captureEnvironment(input) {
+  if (input === undefined) return undefined;
+  return stable(() => {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.getPrototypeOf(input) !== Object.prototype) failAgent('template-invalid');
+    const keys = Reflect.ownKeys(input);
+    if (keys.length > 64 || keys.some(key => typeof key !== 'string')) failAgent('template-invalid');
+    const output = Object.create(null);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) failAgent('template-invalid');
+      const value = input[key];
+      if (typeof value !== 'string') failAgent('template-invalid');
+      output[key] = value;
+    }
+    return Object.freeze(output);
+  });
+}
+
+export function createCodexClient(input) {
+  const config = capture(input, CONFIG_KEYS, ['executable', 'args']);
+  if (typeof config.executable !== 'string' || !config.executable.startsWith('/') || config.executable.length > 1024
+    || (config.interpreter !== undefined && (typeof config.interpreter !== 'string' || !config.interpreter.startsWith('/') || config.interpreter.length > 1024))
+    || (config.expectedVersion !== undefined && !validVersion(config.expectedVersion))) failAgent('template-invalid');
+  const args = captureArgs(config.args);
+  const environment = captureEnvironment(config.environment);
+  const executable = config.executable;
+  const interpreter = config.interpreter;
+  const expectedVersion = config.expectedVersion;
+  const timeoutMs = config.timeoutMs;
+  const maxOutputBytes = config.maxOutputBytes;
+
+  async function launch(contractInput, optionInput = {}) {
+    const options = capture(optionInput, new Set(['signal','protocolContext']), []);
+    const signalState = stable(() => {
+      const value = options.signal;
+      if (value !== undefined && (!(value instanceof AbortSignal) || Object.getPrototypeOf(value) !== AbortSignal.prototype)) failAgent('template-invalid');
+      return Object.freeze({ value, aborted: value?.aborted === true });
+    });
+    if (signalState.aborted) failAgent('aborted');
+    const contract = createLaunchContract(contractInput);
+    serializeProtocolLaunch(contract, options.protocolContext);
+    const runner = await createProcessRunner({
+      executable, interpreter, worktree: contract.worktree.path,
+      worktreeIdentity: { dev: contract.worktree.dev, ino: contract.worktree.ino },
+      environment, signal: signalState.value,
+      timeoutMs: Math.min(timeoutMs ?? contract.budget.maxRuntimeMs, contract.budget.maxRuntimeMs, 10 * 60_000),
+      maxOutputBytes, allowOptionArgs: true,
+    });
+    await checkCompatibility(runner, 'codex', args, expectedVersion);
+    return runner.run({ args, cwd: '.', payload: serializeLaunchContract(contract), protocolContext: options.protocolContext, signal: signalState.value });
+  }
+
+  return Object.freeze({ provider: 'codex', syntaxVersion: 1, launch });
+}
+
+export function createCodexPlanningClient(input) {
+  const config = capture(input, PLANNING_CONFIG_KEYS, ['executable', 'worktree']);
+  if (typeof config.executable !== 'string' || !config.executable.startsWith('/') || config.executable.length > 1024
+    || (config.interpreter !== undefined && (typeof config.interpreter !== 'string' || !config.interpreter.startsWith('/') || config.interpreter.length > 1024))
+    || (config.expectedVersion !== undefined && !validVersion(config.expectedVersion))
+    || typeof config.worktree !== 'string' || !config.worktree.startsWith('/') || config.worktree.length > 1024) {
+    failAgent('template-invalid');
+  }
+  const args = captureArgs([...ARGS.slice(0, -1), '--sandbox', 'read-only', '{stdin}']);
+  const environment = captureEnvironment(config.environment);
+  const executable = config.executable;
+  const interpreter = config.interpreter;
+  const expectedVersion = config.expectedVersion;
+  const worktree = config.worktree;
+
+  async function propose(contract, optionInput = {}) {
+    const options = capture(optionInput, new Set(['signal']), []);
+    const signal = options.signal;
+    if (signal !== undefined && (!(signal instanceof AbortSignal) || Object.getPrototypeOf(signal) !== AbortSignal.prototype)) {
+      failAgent('template-invalid');
+    }
+    if (signal?.aborted) failAgent('aborted');
+    let metadata;
+    try { metadata = await lstat(worktree, { bigint: true }); } catch { failAgent('provider-unavailable'); }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) failAgent('provider-unavailable');
+    const identity = Object.freeze({ dev: metadata.dev.toString(), ino: metadata.ino.toString() });
+    const runner = await createProcessRunner({
+      executable, interpreter, worktree, worktreeIdentity: identity, environment, signal,
+      timeoutMs: config.timeoutMs, maxInputBytes: 512 * 1024,
+      maxOutputBytes: config.maxOutputBytes ?? 512 * 1024, allowOptionArgs: true,
+    });
+    await checkCompatibility(runner, 'codex', args, expectedVersion);
+    return runner.runPlanning({
+      args,
+      cwd: '.',
+      payload: serializePlanningContract({
+        worktree: { path: worktree, ...identity, reservationId: 'planning-read-only' },
+        contract,
+      }),
+      signal,
+    });
+  }
+
+  return Object.freeze({ provider: 'codex', syntaxVersion: 1, propose });
+}

package/src/clients/compatibility.js

@@ -0,0 +1,23 @@
+import { failAgent } from './contract.js';
+
+// Evidence of tested releases belongs in docs, not an executable allowlist.
+export function validVersion(value) {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= 200
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+export function missingCapabilities(help, required) {
+  const declared = new Set();
+  for (const line of help.split('\n')) {
+    const match = line.match(/^\s*(?:-[A-Za-z?],?\s+)?(--[a-z][a-z0-9-]*)(?=[\s=,]|$)/);
+    if (match) declared.add(match[1]);
+  }
+  return required.filter(option => !declared.has(option));
+}
+
+export async function checkCompatibility(runner, provider, args, expectedVersion) {
+  const observed = await runner.probeVersion();
+  if (!validVersion(observed) || (expectedVersion !== undefined && observed !== expectedVersion)) failAgent('provider-unavailable');
+  const required = [...new Set(args.filter(value => /^--[a-z][a-z0-9-]*$/.test(value)))];
+  if (missingCapabilities(await runner.probeHelp(provider), required).length) failAgent('provider-unavailable');
+}

package/src/clients/contract.js

@@ -0,0 +1,224 @@
+const CONTRACT_KEYS = new Set([
+  'nodeId', 'parentId', 'objective', 'ownedPaths', 'authority', 'commands', 'evidence',
+  'budget', 'worktree', 'contextRefs', 'heartbeatInterval', 'stopConditions',
+]);
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const REF = /^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/;
+const ACTION = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|conin\$|conout\$|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const TOKEN_VALUE = /(?:\b(?:Bearer|Basic)\s+[A-Za-z0-9+/_.:=-]{8,}|\b(?:sk-|gh[pousr]_|github_pat_|xox[baprs]-)[A-Za-z0-9_-]{8,}|\bAKIA[0-9A-Z]{16}\b)/i;
+const SENSITIVE_LABELS = Object.freeze([
+  'password', 'passwd', 'secret', 'apikey', 'accesskey', 'privatekey', 'authorization',
+  'credential', 'credentials', 'token', 'accesstoken', 'apitoken', 'authtoken',
+]);
+const launchContracts = new WeakSet();
+
+export class AgentContractError extends Error {
+  constructor(reason = 'invalid-contract') {
+    const messages = {
+      'invalid-contract': 'Agent launch contract is invalid.',
+      'invalid-script': 'Fake agent script is invalid.',
+      'output-invalid': 'Agent output is invalid.',
+      'output-overflow': 'Agent output exceeded its safe limit.',
+      timeout: 'Agent execution timed out.',
+      'launch-timeout': 'Agent provider launch timed out.',
+      'unsupported-platform': 'Agent clients are unsupported on this platform.',
+      aborted: 'Agent execution was cancelled.',
+      'provider-unavailable': 'Configured agent provider is unavailable.',
+      'executable-unsafe': 'Configured agent executable is unsafe.',
+      'cwd-unsafe': 'Agent working directory is unsafe.',
+      'argument-invalid': 'Agent provider argument is invalid.',
+      'template-invalid': 'Agent provider template is invalid.',
+      'spawn-failed': 'Agent provider could not be started safely.',
+    };
+    super(messages[reason] ?? messages['invalid-contract']);
+    this.name = 'AgentContractError';
+    this.code = `ERR_AGENT_${reason.replaceAll('-', '_').toUpperCase()}`;
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+export function failAgent(reason) { throw new AgentContractError(reason); }
+
+function captureRecord(input, keys, required, reason = 'invalid-contract') {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) failAgent(reason);
+  let ownKeys;
+  try { ownKeys = Reflect.ownKeys(input); } catch { failAgent(reason); }
+  if (ownKeys.length > keys.size || ownKeys.some(key => typeof key !== 'string' || !keys.has(key))) failAgent(reason);
+  const output = Object.create(null);
+  try {
+    for (const key of ownKeys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) failAgent(reason);
+      output[key] = input[key];
+    }
+  } catch (error) {
+    failAgent(reason);
+  }
+  if (required.some(key => !Object.hasOwn(output, key))) failAgent(reason);
+  return output;
+}
+
+export function containsSecretMaterial(value) {
+  if (typeof value !== 'string') return false;
+  if (value.length > 1024 * 1024) return true;
+  let detection;
+  try { detection = value.normalize('NFKC').replace(/\p{Cf}/gu, ''); } catch { return true; }
+  if (TOKEN_VALUE.test(detection)) return true;
+  const separator = character => character === ' ' || character === '\t' || character === '.' || character === '-' || character === '_';
+  const wrapper = character => character === '"' || character === "'" || character === '“' || character === '”'
+    || character === '‘' || character === '’' || character === '\\';
+  for (let delimiter = 0; delimiter < detection.length; delimiter += 1) {
+    if (detection[delimiter] !== ':' && detection[delimiter] !== '=') continue;
+    let valueIndex = delimiter + 1;
+    while (valueIndex < detection.length && (separator(detection[valueIndex]) || wrapper(detection[valueIndex]))) valueIndex += 1;
+    if (valueIndex >= detection.length || ',}]'.includes(detection[valueIndex])) continue;
+    for (const label of SENSITIVE_LABELS) {
+      let cursor = delimiter - 1;
+      while (cursor >= 0 && (separator(detection[cursor]) || wrapper(detection[cursor]))) cursor -= 1;
+      let labelIndex = label.length - 1;
+      while (labelIndex >= 0 && cursor >= 0) {
+        while (cursor >= 0 && (separator(detection[cursor]) || wrapper(detection[cursor]))) cursor -= 1;
+        if (cursor < 0 || detection[cursor].toLowerCase() !== label[labelIndex]) break;
+        cursor -= 1;
+        labelIndex -= 1;
+      }
+      if (labelIndex >= 0) continue;
+      while (cursor >= 0 && wrapper(detection[cursor])) cursor -= 1;
+      if (cursor < 0 || !/[A-Za-z0-9]/.test(detection[cursor])) return true;
+    }
+  }
+  return false;
+}
+
+function string(value, maximum, pattern) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > maximum
+    || value.normalize('NFKC') !== value || /[\u0000]/.test(value) || containsSecretMaterial(value)
+    || (pattern && !pattern.test(value))) failAgent('invalid-contract');
+  return value;
+}
+
+function id(value) { return string(value, 64, ID); }
+
+function relativePath(value) {
+  string(value, 500);
+  if (value.startsWith('/') || value.startsWith('-') || value.endsWith('/') || value.includes('//')
+    || /[\\:\u0000-\u001f\u007f]/.test(value)) failAgent('invalid-contract');
+  const parts = value.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..' || part.endsWith('.') || part.endsWith(' ')
+    || part.toUpperCase().toLowerCase() === '.git' || WINDOWS_RESERVED.test(part))) failAgent('invalid-contract');
+  return value;
+}
+
+function array(input, maximum, convert) {
+  if (!Array.isArray(input)) failAgent('invalid-contract');
+  let length;
+  try { length = input.length; } catch { failAgent('invalid-contract'); }
+  if (!Number.isSafeInteger(length) || length > maximum) failAgent('invalid-contract');
+  const output = [];
+  try {
+    for (let index = 0; index < length; index += 1) {
+      if (!Object.hasOwn(input, index)) failAgent('invalid-contract');
+      output.push(convert(input[index]));
+    }
+  } catch (error) {
+    failAgent('invalid-contract');
+  }
+  if (new Set(output.map(value => typeof value === 'string' ? value.toUpperCase().toLowerCase() : value)).size !== output.length) failAgent('invalid-contract');
+  return Object.freeze(output);
+}
+
+function authority(input) {
+  const value = captureRecord(input, new Set(['actions', 'providers']), ['actions', 'providers']);
+  return Object.freeze({
+    actions: array(value.actions, 64, child => string(child, 100, ACTION)),
+    providers: array(value.providers, 32, child => string(child, 100, ACTION)),
+  });
+}
+
+function budget(input) {
+  const value = captureRecord(input, new Set(['maxTokens', 'maxRuntimeMs', 'maxCostUsd']), ['maxTokens', 'maxRuntimeMs', 'maxCostUsd']);
+  if (!Number.isSafeInteger(value.maxTokens) || value.maxTokens <= 0 || value.maxTokens > 10_000_000
+    || !Number.isSafeInteger(value.maxRuntimeMs) || value.maxRuntimeMs <= 0 || value.maxRuntimeMs > 86_400_000
+    || typeof value.maxCostUsd !== 'number' || !Number.isFinite(value.maxCostUsd) || value.maxCostUsd < 0 || value.maxCostUsd > 100_000) {
+    failAgent('invalid-contract');
+  }
+  return Object.freeze({ maxTokens: value.maxTokens, maxRuntimeMs: value.maxRuntimeMs, maxCostUsd: value.maxCostUsd });
+}
+
+export function captureWorktree(input) {
+  const value = captureRecord(input, new Set(['path', 'dev', 'ino', 'reservationId']), ['path', 'dev', 'ino', 'reservationId']);
+  const path = string(value.path, 1024);
+  if (!isAbsolute(path) || resolve(path) !== path || /[\\:\r\n]/.test(path)) failAgent('invalid-contract');
+  return Object.freeze({
+    path, dev: string(value.dev, 64, /^[0-9]+$/), ino: string(value.ino, 64, /^[0-9]+$/), reservationId: id(value.reservationId),
+  });
+}
+
+export function createLaunchContract(input) {
+  const value = captureRecord(input, CONTRACT_KEYS, [...CONTRACT_KEYS]);
+  const parentId = value.parentId === null ? null : id(value.parentId);
+  if (!Number.isSafeInteger(value.heartbeatInterval) || value.heartbeatInterval < 100 || value.heartbeatInterval > 3_600_000) failAgent('invalid-contract');
+  const contract = Object.freeze({
+    version: 1,
+    nodeId: id(value.nodeId), parentId,
+    objective: string(value.objective, 16_384),
+    ownedPaths: array(value.ownedPaths, 256, relativePath),
+    authority: authority(value.authority),
+    commands: array(value.commands, 128, child => string(child, 100, ACTION)),
+    evidence: array(value.evidence, 128, child => string(child, 200, REF)),
+    budget: budget(value.budget), worktree: captureWorktree(value.worktree),
+    contextRefs: array(value.contextRefs, 128, child => string(child, 200, REF)),
+    heartbeatInterval: value.heartbeatInterval,
+    stopConditions: array(value.stopConditions, 64, child => string(child, 200, ACTION)),
+  });
+  launchContracts.add(contract);
+  return contract;
+}
+
+export function isLaunchContract(value) { return launchContracts.has(value); }
+
+export function immutableJson(value, reason = 'output-invalid') {
+  const active = new WeakSet();
+  function clone(child, depth) {
+    if (depth > 16) failAgent(reason);
+    if (child === null || typeof child === 'boolean' || typeof child === 'string') {
+      if (typeof child === 'string' && child.length > 16_384) failAgent(reason);
+      return child;
+    }
+    if (typeof child === 'number') {
+      if (!Number.isFinite(child)) failAgent(reason);
+      return child;
+    }
+    if (!child || typeof child !== 'object' || active.has(child)) failAgent(reason);
+    active.add(child);
+    try {
+      if (Array.isArray(child)) {
+        if (child.length > 256) failAgent(reason);
+        const output = [];
+        for (let index = 0; index < child.length; index += 1) {
+          const descriptor = Object.getOwnPropertyDescriptor(child, String(index));
+          if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) failAgent(reason);
+          output.push(clone(descriptor.value, depth + 1));
+        }
+        return Object.freeze(output);
+      }
+      const prototype = Object.getPrototypeOf(child);
+      if (prototype !== Object.prototype && prototype !== null) failAgent(reason);
+      const keys = Reflect.ownKeys(child);
+      if (keys.length > 256 || keys.some(key => typeof key !== 'string')) failAgent(reason);
+      const output = Object.create(null);
+      for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(child, key);
+        if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value') || key.length > 200) failAgent(reason);
+        output[key] = clone(descriptor.value, depth + 1);
+      }
+      return Object.freeze(output);
+    } finally { active.delete(child); }
+  }
+  try { return clone(value, 0); } catch (error) {
+    failAgent(reason);
+  }
+}
+import { isAbsolute, resolve } from 'node:path';