@ikon85/agent-workflow-kit 0.44.1 → 0.45.0

package/src/lib/routingAdapters/claude.mjs

@@ -1,8 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
 import { adaptClaudeRoutingInventory } from '../capabilityMatrix.mjs';
+import {
+  attestAccessPath,
+  capabilityPathMatchesPair,
+  selectCapabilityPath,
+} from '../routingAccessGraph.mjs';
+
+/**
+ * `claude-code × native` — the in-session Agent primitive. It can enforce a
+ * model, but it has no effort axis at all and reports no applied pair, so it can
+ * never produce an honest applied-effort receipt. Attested unavailable rather
+ * than bridged; the dated verify-spike carries the recorded evidence.
+ */
+export const CLAUDE_NATIVE_UNAVAILABLE = Object.freeze({
+  surfaceId: 'claude-code',
+  transportId: 'native',
+  reason: 'effort-axis-absent',
+  detail: 'the in-session Agent primitive enforces a model but exposes no effort '
+    + 'parameter and returns no applied pair',
+  evidence: 'verify-spike-18c',
+  observedAt: '2026-07-27',
+});
+
+/**
+ * The Claude host as a bridged child process. Model and effort are enforced per
+ * spawn and read back from the persisted session transcript, whose
+ * `message.model` is server-returned — the strongest attestation either host
+ * offers. `--output-format json` omits effort entirely, so the transcript, not
+ * stdout, is the readback channel.
+ *
+ * The Claude CLI silently ignores an unknown `--effort` and runs at its default,
+ * so the effort is validated against the model's own domain before the spawn and
+ * compared against the transcript after it.
+ */
+export const CLAUDE_CLI_HOST = Object.freeze({
+  transportId: 'claude-cli',
+  command: 'claude',
+  /** Anthropic models live under the `claude-code` surface of the pinned inventory. */
+  inventorySurface: 'claude-code',
+  attestationStrength: 'provider-attested',
+  forbiddenArgs: Object.freeze([]),
+  buildArgv({ modelId, effort, runId }) {
+    const argv = ['--print', '--model', modelId, '--session-id', runId,
+      '--output-format', 'json'];
+    if (effort !== null) argv.push('--effort', effort);
+    return Object.freeze(argv);
+  },
+  degraded() {
+    return false;
+  },
+  readApplied({ home, cwd, runId }) {
+    return readClaudeAppliedPair({ home, cwd, runId });
+  },
+});
 
-function matchesRoute(path, route) {
-  return ['surfaceId', 'providerId', 'modelId', 'transportId']
-    .every((field) => path[field] === route[field]);
+/** Claude's project directory name: the absolute cwd with `/` and `.` as `-`. */
+export function claudeProjectSlug(cwd) {
+  return resolve(cwd).replace(/[/.]/g, '-');
+}
+
+/**
+ * Read the applied pair out of `~/.claude/projects/<cwd-slug>/<session-id>.jsonl`:
+ * the last server-returned `message.model` and the last top-level `effort`.
+ */
+export async function readClaudeAppliedPair({ home, cwd, runId }) {
+  let raw;
+  try {
+    raw = await readFile(
+      join(home, '.claude', 'projects', claudeProjectSlug(cwd), `${runId}.jsonl`), 'utf8',
+    );
+  } catch {
+    return null;
+  }
+  let modelId = null;
+  let effort = null;
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof record?.message?.model === 'string') modelId = record.message.model;
+    if (typeof record?.effort === 'string') effort = record.effort;
+  }
+  return modelId === null ? null : Object.freeze({ modelId, effort, runId });
 }
 
 function appliedRoute(path, requestedRoute) {
@@ -25,13 +110,28 @@ function mismatchReason(path, requested, applied) {
   return null;
 }
 
+/**
+ * Attest the Claude surface's access paths for the Access-graph builder. The
+ * attestation carries capability facts and their observation dates only —
+ * authorization stays with the Routing profile and the capability probe.
+ */
+export function claudeAccessAttestations(inventory, dates) {
+  return Object.freeze(adaptClaudeRoutingInventory(inventory).paths
+    .map((path) => attestAccessPath(path, dates)));
+}
+
 export function createClaudeRoutingAdapter({ inventory, dispatchers = {} }) {
   const capabilities = adaptClaudeRoutingInventory(inventory);
   return Object.freeze({
     async prepare(requestedRoute) {
-      const path = capabilities.paths.find((candidate) => matchesRoute(candidate, requestedRoute));
+      const path = selectCapabilityPath(capabilities.paths, requestedRoute);
       if (!path) throw new Error('Claude route capability is not attested');
       if (!path.verified) throw new Error(path.verificationFailures.join('; '));
+      if (!capabilityPathMatchesPair(path, requestedRoute)) {
+        throw new Error(
+          `access pair is not attested: ${requestedRoute.modelId}+${requestedRoute.effort}`,
+        );
+      }
       const invoke = dispatchers[path.transportId];
       if (typeof invoke !== 'function') {
         throw new Error(`transport has no approved dispatcher: ${path.transportId}`);

package/src/lib/routingAdapters/codex.mjs

@@ -1,4 +1,12 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
 import { adaptClaudeRoutingInventory } from '../capabilityMatrix.mjs';
+import {
+  attestAccessPath,
+  capabilityPathMatchesPair,
+  selectCapabilityPath,
+} from '../routingAccessGraph.mjs';
 
 const MODEL_SELECTORS = ['model'];
 const EFFORT_SELECTORS = ['effort', 'reasoning_effort', 'model_reasoning_effort'];
@@ -60,11 +68,6 @@ function applySpawnSchemaEvidence(path, properties) {
   return candidate;
 }
 
-function matchesRoute(path, route) {
-  return ['surfaceId', 'providerId', 'modelId', 'transportId']
-    .every((field) => path[field] === route[field]);
-}
-
 function appliedRoute(path, requestedRoute) {
   return Object.freeze({
     ...requestedRoute,
@@ -85,6 +88,114 @@ function mismatchReason(path, requested, applied) {
   return null;
 }
 
+/**
+ * `codex × native` — the in-session Codex spawn primitive. The dated host
+ * inventory (2026-07-23, `.codex/agents/README.md`) exposes `task_name`,
+ * `message` and `fork_turns` and no per-spawn model or effort selector, so it
+ * can start a task but never prove a differentiated pair was applied. Attested
+ * unavailable rather than bridged.
+ */
+export const CODEX_NATIVE_UNAVAILABLE = Object.freeze({
+  surfaceId: 'codex',
+  transportId: 'native',
+  reason: 'spawn-schema-exposes-no-model-or-effort-selector',
+  detail: 'the native spawn schema carries task_name, message and fork_turns only',
+  evidence: 'codex-host-inventory',
+  observedAt: '2026-07-23',
+});
+
+/**
+ * The Codex host as a bridged child process. The applied pair lives in the
+ * rollout file's `turn_context`, which the client writes — strictly stronger
+ * than an argv echo, strictly weaker than Claude's server-returned model, so the
+ * attestation is `client-attested` and a receipt must not claim otherwise. The
+ * `--json` event stream carries neither model nor effort, and `--ephemeral`
+ * destroys the rollout file altogether, so it is forbidden here.
+ */
+export const CODEX_CLI_HOST = Object.freeze({
+  transportId: 'codex-cli',
+  command: 'codex',
+  /** OpenAI models live under the `codex` surface of the pinned inventory. */
+  inventorySurface: 'codex',
+  attestationStrength: 'client-attested',
+  forbiddenArgs: Object.freeze(['--ephemeral']),
+  buildArgv({ modelId, effort, cwd }) {
+    const argv = ['exec', '--json', '--model', modelId, '--cd', cwd];
+    if (effort !== null) argv.push('-c', `model_reasoning_effort="${effort}"`);
+    argv.push('-');
+    return Object.freeze(argv);
+  },
+  degraded(result) {
+    return codexRunDegraded(result?.stdout);
+  },
+  readApplied({ home, result }) {
+    const threadId = codexThreadId(result?.stdout);
+    return threadId === null ? null : readCodexAppliedPair({ home, threadId });
+  },
+});
+
+function* codexEvents(stdout) {
+  for (const line of String(stdout ?? '').split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      yield JSON.parse(line);
+    } catch {
+      continue;
+    }
+  }
+}
+
+/** The durable run identity Codex announces on its own event stream. */
+export function codexThreadId(stdout) {
+  for (const event of codexEvents(stdout)) {
+    if (event?.type !== 'thread.started') continue;
+    const id = event.thread_id ?? event.payload?.thread_id;
+    if (typeof id === 'string' && id !== '') return id;
+  }
+  return null;
+}
+
+/**
+ * Codex emits a soft `item.completed` metadata error before a hard failure. A
+ * consumer reading only the terminal status would take that degraded run for a
+ * clean one, so the bridge treats it as a failed dispatch.
+ */
+export function codexRunDegraded(stdout) {
+  for (const event of codexEvents(stdout)) {
+    if (event?.type !== 'item.completed') continue;
+    if (/Model metadata for .+ not found/i.test(JSON.stringify(event))) return true;
+  }
+  return false;
+}
+
+/** Read the applied pair out of the dated `rollout-…-<threadId>.jsonl` session file. */
+export async function readCodexAppliedPair({ home, threadId }) {
+  const root = join(home, '.codex', 'sessions');
+  let entries;
+  try {
+    entries = await readdir(root, { recursive: true });
+  } catch {
+    return null;
+  }
+  const file = entries.find((entry) => entry.endsWith(`-${threadId}.jsonl`)
+    && basename(entry).startsWith('rollout-'));
+  if (file === undefined) return null;
+  let raw;
+  try {
+    raw = await readFile(join(root, file), 'utf8');
+  } catch {
+    return null;
+  }
+  let modelId = null;
+  let effort = null;
+  for (const event of codexEvents(raw)) {
+    if (event?.type !== 'turn_context') continue;
+    if (typeof event.payload?.model === 'string') modelId = event.payload.model;
+    effort = typeof event.payload?.effort === 'string' ? event.payload.effort : null;
+  }
+  return modelId === null ? null : Object.freeze({ modelId, effort, runId: threadId });
+}
+
 export function adaptCodexRoutingInventory(inventory) {
   const source = object(inventory, 'Codex host attestation');
   timestamp(source.observedAt, 'Codex host attestation observedAt');
@@ -103,14 +214,28 @@ export function adaptCodexRoutingInventory(inventory) {
   });
 }
 
+/**
+ * Attest the Codex surface's access paths for the Access-graph builder. A host
+ * whose spawn schema exposes no selector attests no control, so the path never
+ * becomes a dispatchable Access-graph path.
+ */
+export function codexAccessAttestations(inventory, dates) {
+  return Object.freeze(adaptCodexRoutingInventory(inventory).paths
+    .map((path) => attestAccessPath(path, dates)));
+}
+
 export function createCodexRoutingAdapter({ inventory, dispatchers = {} }) {
   const capabilities = adaptCodexRoutingInventory(inventory);
   return Object.freeze({
     async prepare(requestedRoute) {
-      const path = capabilities.paths.find((candidate) =>
-        matchesRoute(candidate, requestedRoute));
+      const path = selectCapabilityPath(capabilities.paths, requestedRoute);
       if (!path) throw new Error('Codex route capability is not attested');
       if (!path.verified) throw new Error(path.verificationFailures.join('; '));
+      if (!capabilityPathMatchesPair(path, requestedRoute)) {
+        throw new Error(
+          `access pair is not attested: ${requestedRoute.modelId}+${requestedRoute.effort}`,
+        );
+      }
       const invoke = dispatchers[path.transportId];
       if (typeof invoke !== 'function') {
         throw new Error(`transport has no approved dispatcher: ${path.transportId}`);

package/src/lib/routingAdapters/hostBridge.mjs

@@ -0,0 +1,291 @@
+/**
+ * The host bridge — the security boundary between a Route decision and the host
+ * process that actually runs it.
+ *
+ * Every `(surface, transport)` pair in the agent-surface registry is accounted
+ * for exactly once: it is either bridged to a host command, or it carries a
+ * dated unavailable attestation. The census fails closed, so a transport added
+ * to the registry without either cannot quietly become undispatchable.
+ *
+ * The boundary itself is fixed, not per-call policy:
+ *
+ * - Invocation is `execFile`-style — a bare command plus an argv array. No shell
+ *   string is ever constructed, and a command that is not a bare binary name is
+ *   refused.
+ * - **Task text never rides in argv.** It goes to the child's stdin, because an
+ *   argv element is readable in the process list and bounded by argument-size
+ *   limits. A guard rejects argv that contains the task text.
+ * - The model-and-effort pair is schema-validated against the pinned inventory
+ *   before the spawn, and read back from the host's own record after it. A
+ *   surface that silently substitutes a default cannot pass.
+ * - cwd is bounded to the authorized workspace.
+ * - The child environment is an explicit allowlist, never the credential-rich
+ *   parent.
+ * - Every failure is reduced to a closed reason before it can reach a log or a
+ *   Dispatch receipt.
+ */
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { AGENT_SURFACE_REGISTRY } from '../agentSurfaceRegistry.mjs';
+import {
+  CLAUDE_CLI_HOST,
+  CLAUDE_NATIVE_UNAVAILABLE,
+  createClaudeRoutingAdapter,
+} from './claude.mjs';
+import {
+  CODEX_CLI_HOST,
+  CODEX_NATIVE_UNAVAILABLE,
+  createCodexRoutingAdapter,
+} from './codex.mjs';
+
+export const HOST_BRIDGE_VERSION = 1;
+
+/** The only environment names a bridged child inherits from its parent. */
+export const CHILD_ENV_ALLOWLIST = Object.freeze([
+  'PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR',
+]);
+
+/** The closed set of reasons a bridge failure may name. */
+export const BRIDGE_FAILURE_REASONS = Object.freeze([
+  'host bridge pair is not in the pinned inventory',
+  'host bridge effort is outside the model effort domain',
+  'host bridge cwd is outside the authorized workspace',
+  'host bridge refuses a shell invocation',
+  'host bridge refuses task text in argv',
+  'host bridge refuses an argument that destroys the readback channel',
+  'host bridge has no adapter for the agent surface',
+  'host bridge child exited with a failure',
+  'host bridge run was degraded by the host',
+  'host bridge could not read back the applied pair',
+  'host bridge applied pair differs from the requested pair',
+]);
+
+const BRIDGED_HOSTS = Object.freeze([CLAUDE_CLI_HOST, CODEX_CLI_HOST]);
+const UNAVAILABLE_TRANSPORTS = Object.freeze([
+  CLAUDE_NATIVE_UNAVAILABLE, CODEX_NATIVE_UNAVAILABLE,
+]);
+const ADAPTER_FACTORIES = Object.freeze({
+  'claude-code': createClaudeRoutingAdapter,
+  codex: createCodexRoutingAdapter,
+});
+
+const BARE_COMMAND = /^[A-Za-z0-9._-]+$/;
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000;
+
+/** Reduce any error to its closed reason; nothing else survives to a log. */
+export function redactBridgeError(error) {
+  const message = error instanceof Error ? error.message : '';
+  return new Error(BRIDGE_FAILURE_REASONS.find((reason) => message.startsWith(reason))
+    ?? 'host bridge rejected the dispatch');
+}
+
+/** The child inherits allowlisted names only — never an inherited parent env. */
+export function childEnvironment(parentEnv = {}, allowlist = CHILD_ENV_ALLOWLIST) {
+  const child = {};
+  for (const name of allowlist) {
+    const value = parentEnv?.[name];
+    if (typeof value === 'string' && value !== '') child[name] = value;
+  }
+  return Object.freeze(child);
+}
+
+/** The child runs inside the authorized worktree or it does not run. */
+export function assertBoundedCwd(cwd, workspaceRoot) {
+  if (typeof cwd !== 'string' || cwd === '' || typeof workspaceRoot !== 'string'
+      || workspaceRoot === '') {
+    throw new Error('host bridge cwd is outside the authorized workspace');
+  }
+  const target = resolve(cwd);
+  const step = relative(resolve(workspaceRoot), target);
+  if (step !== '' && (step.startsWith('..') || isAbsolute(step))) {
+    throw new Error('host bridge cwd is outside the authorized workspace');
+  }
+  return target;
+}
+
+/** argv carries validated controls only: no shell, no task text, no readback loss. */
+export function assertArgvSafe(host, argv, taskText) {
+  if (typeof host?.command !== 'string' || !BARE_COMMAND.test(host.command)
+      || !Array.isArray(argv) || argv.some((item) => typeof item !== 'string')) {
+    throw new Error('host bridge refuses a shell invocation');
+  }
+  const task = typeof taskText === 'string' ? taskText.trim() : '';
+  if (task !== '' && argv.some((item) => item.includes(task))) {
+    throw new Error('host bridge refuses task text in argv');
+  }
+  if ((host.forbiddenArgs ?? []).some((flag) => argv.includes(flag))) {
+    throw new Error('host bridge refuses an argument that destroys the readback channel');
+  }
+  return argv;
+}
+
+/**
+ * The roster identification rule. One host reports one model under several
+ * forms (`opus`, `opus[1m]`, `claude-opus-5`, `claude-opus-5[1m]`), so an
+ * observed id counts as identified only when the pinned inventory lists it as an
+ * identifier of exactly one model. An unlisted form is never guessed.
+ */
+export function canonicalModelId(inventory, surface, observed) {
+  if (typeof observed !== 'string' || observed === '') return null;
+  for (const snapshot of inventory?.snapshots ?? []) {
+    if (snapshot.surface !== surface) continue;
+    for (const model of snapshot.models ?? []) {
+      if (model.modelId === observed || (model.identifiers ?? []).includes(observed)) {
+        return model.modelId;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a requested pair against the pinned inventory. The surface is the
+ * host being driven, not the dispatching surface: a Codex session bridging to
+ * the Claude host must name an Anthropic pair.
+ */
+export function requireInventoryPair(inventory, surface, route) {
+  const modelId = canonicalModelId(inventory, surface, route?.modelId);
+  if (modelId === null) throw new Error('host bridge pair is not in the pinned inventory');
+  const effort = route?.effort ?? null;
+  const match = (inventory?.pairs ?? []).find((pair) => pair.surface === surface
+    && pair.modelId === modelId && (pair.effort ?? null) === effort);
+  if (match === undefined) {
+    throw new Error('host bridge effort is outside the model effort domain');
+  }
+  return Object.freeze({ surface, provider: match.provider, modelId, effort });
+}
+
+function assertAppliedPair(inventory, host, requested, applied) {
+  const modelId = canonicalModelId(inventory, host.inventorySurface, applied?.modelId);
+  if (modelId === null || typeof applied?.runId !== 'string' || applied.runId === '') {
+    throw new Error('host bridge could not read back the applied pair');
+  }
+  if (modelId !== requested.modelId || (applied.effort ?? null) !== requested.effort) {
+    throw new Error('host bridge applied pair differs from the requested pair');
+  }
+}
+
+/** The default runner: `execFile` argv, `shell` off, task text on stdin. */
+function spawnChild(command, argv, { cwd, env, stdin, timeoutMs }) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = execFile(command, argv, { cwd, env, shell: false, timeout: timeoutMs },
+      (error, stdout, stderr) => (error
+        ? rejectPromise(new Error('host bridge child exited with a failure'))
+        : resolvePromise({ stdout, stderr })));
+    child.stdin?.end(stdin ?? '');
+  });
+}
+
+async function runBridgedDispatch(host, context, route) {
+  const pair = requireInventoryPair(context.routingInventory, host.inventorySurface, route);
+  const cwd = assertBoundedCwd(context.cwd, context.workspaceRoot);
+  const argv = host.buildArgv({ ...pair, runId: context.runId, cwd });
+  assertArgvSafe(host, argv, context.task);
+  let result;
+  try {
+    result = await context.runChild(host.command, argv, {
+      cwd,
+      env: childEnvironment(context.env),
+      stdin: context.task,
+      timeoutMs: context.timeoutMs,
+    });
+  } catch {
+    throw new Error('host bridge child exited with a failure');
+  }
+  if (host.degraded(result)) throw new Error('host bridge run was degraded by the host');
+  const applied = await host.readApplied({ home: context.home, cwd, runId: context.runId, result });
+  assertAppliedPair(context.routingInventory, host, pair, applied);
+  return Object.freeze({
+    taskId: applied.runId,
+    appliedPair: pair,
+    attestationStrength: host.attestationStrength,
+  });
+}
+
+function bridgeContext(options) {
+  return Object.freeze({
+    routingInventory: options.routingInventory,
+    task: options.task,
+    cwd: options.cwd ?? process.cwd(),
+    workspaceRoot: options.workspaceRoot ?? options.cwd ?? process.cwd(),
+    home: options.home ?? homedir(),
+    env: options.env ?? process.env,
+    runId: options.runId ?? randomUUID(),
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    runChild: options.runChild ?? spawnChild,
+  });
+}
+
+/**
+ * The census: one entry per registry `(surface, transport)` pair, each bridged
+ * or attested unavailable. A pair with neither — or with both — throws.
+ */
+export function hostTransportCensus({ registry = AGENT_SURFACE_REGISTRY } = {}) {
+  const entries = [];
+  for (const surface of registry) {
+    for (const transportId of surface.adapter?.transports ?? []) {
+      const host = BRIDGED_HOSTS.find((bridge) => bridge.transportId === transportId);
+      const attestation = UNAVAILABLE_TRANSPORTS.find((entry) =>
+        entry.surfaceId === surface.id && entry.transportId === transportId);
+      if ((host === undefined) === (attestation === undefined)) {
+        throw new Error(
+          `host bridge census is undecided for ${surface.id}/${transportId}`,
+        );
+      }
+      entries.push(Object.freeze(host
+        ? {
+          surfaceId: surface.id, transportId, status: 'bridged',
+          command: host.command, attestationStrength: host.attestationStrength,
+          reason: null, evidence: null, observedAt: null,
+        }
+        : {
+          surfaceId: surface.id, transportId, status: 'unavailable',
+          command: null, attestationStrength: null,
+          reason: attestation.reason,
+          evidence: attestation.evidence,
+          observedAt: attestation.observedAt,
+        }));
+    }
+  }
+  return Object.freeze(entries);
+}
+
+/**
+ * The dispatcher map a surface adapter consumes: one entry per bridged transport
+ * of that surface. An attested-unavailable transport gets no entry, so the
+ * adapter refuses it as a transport with no approved dispatcher.
+ *
+ * The map is bound to exactly one task text, because that text is handed to the
+ * child's stdin and never to argv.
+ */
+export function createHostBridgeDispatchers(options) {
+  const context = bridgeContext(options);
+  const dispatchers = {};
+  for (const entry of hostTransportCensus({ registry: options.registry })) {
+    if (entry.surfaceId !== options.surfaceId || entry.status !== 'bridged') continue;
+    const host = BRIDGED_HOSTS.find((bridge) => bridge.transportId === entry.transportId);
+    dispatchers[entry.transportId] = async ({ route }) => {
+      try {
+        return await runBridgedDispatch(host, context, route);
+      } catch (error) {
+        throw redactBridgeError(error);
+      }
+    };
+  }
+  return Object.freeze(dispatchers);
+}
+
+/** A surface routing adapter whose approved dispatchers are the host bridges. */
+export function createBridgedRoutingAdapter(options) {
+  const factory = ADAPTER_FACTORIES[options?.surfaceId];
+  if (factory === undefined) {
+    throw new Error('host bridge has no adapter for the agent surface');
+  }
+  return factory({
+    inventory: options.capabilityInventory,
+    dispatchers: createHostBridgeDispatchers(options),
+  });
+}