negotium 0.1.7 → 0.1.9

package/dist/runtime/src/agents/codex-registry.ts

@@ -0,0 +1,115 @@
+import { unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentRegistry } from "#agents/contracts";
+import { writeCodexRollout } from "#agents/rollout/codex";
+import { logger } from "#platform/logger";
+import { readConversation } from "#storage/conversations";
+import { CODEX_EFFORT_VALUES, type EffortLevel } from "#types";
+
+const VALID_EFFORTS = new Set<EffortLevel>(CODEX_EFFORT_VALUES);
+
+// Codex CLI's own empirical default is gpt-5.6-sol (`codex exec` 2026-07-10 →
+// "model: gpt-5.6-sol"), but we deliberately default to gpt-5.6-luna — the
+// cheapest/fastest GPT-5.6 tier — for a general always-on assistant where most
+// queries are light. Heavier work escalates to terra/sol via set_model. This
+// value is passed explicitly to the SDK (see event-processor resolveDefaultModel),
+// so the footer and the actual model stay in sync.
+export const codexRegistry: AgentRegistry = {
+  kind: "codex",
+  defaultModel: "gpt-5.6-luna",
+  // defaultEffort intentionally omitted — Codex SDK treats absence as
+  // "reasoning off". Setting "high"/etc. would silently flip on reasoning.
+
+  expandModelAlias(s) {
+    return s;
+  },
+
+  validateModel(s) {
+    // Codex doesn't publish a closed model list and OpenAI ships new IDs
+    // (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, o3, ...) frequently. Best-effort: accept any
+    // non-empty string. Bad IDs surface at SDK call time with a clear error.
+    return typeof s === "string" && s.length > 0;
+  },
+
+  validEfforts: CODEX_EFFORT_VALUES,
+  validateEffort(s) {
+    // GPT-5.6 accepts low/medium/high/xhigh/max; 'minimal'
+    // was removed because the Codex API rejects it when default tools
+    // (image_gen, web_search) are active.
+    return VALID_EFFORTS.has(s);
+  },
+
+  footerLabel(model, effort) {
+    // Codex omits effort to mean "reasoning off". Show `(off)` explicitly so
+    // the user can distinguish from claude (which always has a default).
+    return `${model} · ${effort ?? "(off)"}`;
+  },
+
+  writeRollout(opts) {
+    // Codex SDK exposes the resume key as `threadId`; AgentRegistry unifies
+    // the name to `sessionId` so callers don't branch on agent.
+    // `reuseSessionId` (if any) is forwarded as `threadId` so claude→codex→claude
+    // round-trips also keep one continuous codex thread instead of orphaning a
+    // fresh uuidv7 on every switch.
+    const { threadId, rolloutPath } = writeCodexRollout({
+      cwd: opts.cwd,
+      entries: opts.entries,
+      model: opts.model ?? codexRegistry.defaultModel,
+      ...(opts.effort ? { effort: opts.effort } : {}),
+      ...(opts.reuseSessionId ? { threadId: opts.reuseSessionId } : {}),
+    });
+    return { sessionId: threadId, rolloutPath };
+  },
+
+  // Codex SDK has no fork API. We synthesize a rollout from the
+  // provider-agnostic conversation log (same path as `set_agent` cross-agent
+  // bridging). Caveats: extractChatPairs folds tool_use/tool_result into
+  // assistant text as `[Tool: ...]` annotations, so structural tool history
+  // is lost.
+  async forkSession({ cwd, userId, topicName, model, effort }) {
+    const entries = readConversation(userId, topicName);
+    const { threadId, rolloutPath } = writeCodexRollout({
+      cwd,
+      entries,
+      model: model ?? codexRegistry.defaultModel,
+      ...(effort ? { effort } : {}),
+    });
+    return { forkId: threadId, rolloutPath };
+  },
+
+  // Codex stores rollouts at `~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<ts>-<threadId>.jsonl`.
+  // The date prefix is unknown at cleanup time (it's the *original* write
+  // timestamp, not "now"), so we glob across the whole sessions tree by
+  // threadId suffix. With at most a few thousand files in active use this
+  // is well under a millisecond on a warm filesystem.
+  async cleanupRollouts({ sessionIds }) {
+    if (sessionIds.length === 0) return;
+    const sessionsDir = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+    const failures: unknown[] = [];
+    // One Glob per threadId so a single corrupt entry can't poison the rest.
+    // Bun.Glob's `scan` yields paths relative to its base dir.
+    for (const tid of sessionIds) {
+      try {
+        const glob = new Bun.Glob(`**/rollout-*-${tid}.jsonl`);
+        for await (const rel of glob.scan({ cwd: sessionsDir, onlyFiles: true })) {
+          const path = join(sessionsDir, rel);
+          try {
+            unlinkSync(path);
+          } catch (e) {
+            if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") {
+              logger.warn({ err: e, path }, "codex cleanupRollouts: unlink failed");
+              failures.push(e);
+            }
+          }
+        }
+      } catch (e) {
+        logger.warn({ err: e, threadId: tid }, "codex cleanupRollouts: scan failed");
+        failures.push(e);
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, "codex cleanupRollouts failed");
+    }
+  },
+};

package/dist/runtime/src/agents/codex-tree-kill.ts

@@ -0,0 +1,365 @@
+/**
+ * Codex process tree kill helper.
+ *
+ * The @openai/codex-sdk spawns `codex` as a direct child of our bot process but
+ * does not expose the resulting PID and does not detach the child into its own
+ * process group. So when we call `abortController.abort()`, the SDK sends a
+ * single SIGTERM that may or may not reach grandchild tool processes (shells,
+ * MCP servers spawned by codex itself). To guarantee abort actually stops
+ * activity we identify the codex children we spawned and SIGTERM their whole
+ * descendant tree, with a SIGKILL fallback for stragglers.
+ *
+ * Strategy (post-2026-05-14 fix):
+ *   1. Acquire a global spawn lock that's held across the entire window
+ *      from baseline snapshot through the first SDK event (when codex is
+ *      actually spawned — `runStreamed()` returns a lazy async generator,
+ *      so the real `child_process.spawn()` happens on the first iterator
+ *      `.next()`, not when `runStreamed()` is awaited).
+ *   2. Snapshot direct codex children of `process.pid` BEFORE forcing the
+ *      first iterator step.
+ *   3. After the first event lands, diff against a fresh snapshot to
+ *      identify our PIDs and register them in `globalOwnedCodexPids` so
+ *      concurrent codex callers don't claim them as their own.
+ *   4. On abort, walk each PID's descendant tree via `pgrep -P` and signal
+ *      every node. Unregister on exit.
+ *
+ * Platform: relies on `pgrep` and `ps` — macOS/Linux only. Windows is not
+ * supported (Otium already requires POSIX for the rest of the stack).
+ */
+
+import { execFileSync } from "node:child_process";
+import { logger } from "#platform/logger";
+
+// 5s gives MCP stdio servers (codex spawns these as grandchildren) a realistic
+// shutdown window. 2s was empirically too aggressive: stdio MCP servers in the
+// middle of writing a response would get SIGKILL'd before they finished.
+const SIGKILL_DELAY_MS = 5_000;
+const CODEX_PROC_NAME_MATCH = /codex/i;
+// Cap tree-walk depth. Defends against pathological or malicious cycles that
+// slip past the visited-set guard (e.g. via PID reuse), and against deeply
+// nested codex+MCP+shell trees blowing the stack.
+const TREE_DEPTH_CAP = 16;
+
+/** Return direct child PIDs of `parentPid`. Returns [] on error or no children. */
+function getDirectChildren(parentPid: number): number[] {
+  try {
+    const out = execFileSync("pgrep", ["-P", String(parentPid)], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return [];
+    return out
+      .split("\n")
+      .map((s) => Number(s))
+      .filter((n) => Number.isFinite(n) && n > 0);
+  } catch {
+    // pgrep exits 1 when no matches; treat as empty.
+    return [];
+  }
+}
+
+/** Return the executable name (comm) of a process, or "" if unavailable. */
+function getProcName(pid: number): string {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "comm="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Return the start time of `pid` as the raw `ps -o lstart=` string (e.g.
+ * "Tue May 12 10:49:35 2026"), or "" if unavailable. Used as a fingerprint
+ * to defend against PID reuse — even if the OS reassigns a baseline PID to
+ * a fresh codex spawn, the lstart string will differ.
+ *
+ * macOS and Linux both support `ps -o lstart=` with the same date format.
+ */
+function getProcLstart(pid: number): string {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** (pid, lstart) fingerprint pair — same PID + same lstart = same process. */
+export type CodexProcStamp = { pid: number; lstart: string };
+
+/**
+ * Recursively collect `rootPid` and all its descendants, up to `TREE_DEPTH_CAP`
+ * levels deep. Cycle-safe via the `out` Set; depth-cap-safe via the `depth`
+ * parameter (defends against pathological trees the Set guard might miss,
+ * e.g. PID reuse mid-walk).
+ */
+function collectTree(rootPid: number, out: Set<number> = new Set(), depth = 0): Set<number> {
+  if (out.has(rootPid)) return out;
+  out.add(rootPid);
+  if (depth >= TREE_DEPTH_CAP) {
+    logger.warn(
+      { rootPid, depth, cap: TREE_DEPTH_CAP },
+      "codex-tree-kill: tree depth cap reached, descendants beyond this point not collected",
+    );
+    return out;
+  }
+  for (const child of getDirectChildren(rootPid)) {
+    collectTree(child, out, depth + 1);
+  }
+  return out;
+}
+
+/**
+ * Snapshot current codex-named direct children of `process.pid` along with
+ * each PID's lstart (start time) fingerprint. Returning the lstart map lets
+ * `findNewCodexChildren` distinguish "PID X was in baseline and is the same
+ * process" from "PID X was in baseline but the OS reassigned that PID to a
+ * fresh codex" — only the latter is novel.
+ */
+export function snapshotCodexChildren(): Map<number, string> {
+  const out = new Map<number, string>();
+  for (const pid of getDirectChildren(process.pid)) {
+    const name = getProcName(pid);
+    if (!name || !CODEX_PROC_NAME_MATCH.test(name)) continue;
+    const lstart = getProcLstart(pid);
+    // If lstart can't be read (race: process died between getDirectChildren
+    // and getProcLstart), still record the PID with an empty fingerprint —
+    // any later snapshot with a real lstart will compare as "different" and
+    // count it as novel, which is the safer side to err on.
+    out.set(pid, lstart);
+  }
+  return out;
+}
+
+/**
+ * PIDs already owned by an active codex caller (normal provider or fork).
+ * `findNewCodexChildren` excludes these so concurrent callers can't claim
+ * each other's PIDs when their baselines happen to miss them (e.g. the other
+ * caller's spawn raced in between baseline and first-event diff).
+ *
+ * Callers must `registerOwnedCodexPids` after diff, and `unregisterOwnedCodexPids`
+ * in their cleanup `finally` block to avoid leaking entries on long-running bots.
+ */
+const globalOwnedCodexPids = new Set<number>();
+
+export function registerOwnedCodexPids(pids: Iterable<number>): void {
+  for (const p of pids) globalOwnedCodexPids.add(p);
+}
+
+export function unregisterOwnedCodexPids(pids: Iterable<number>): void {
+  for (const p of pids) globalOwnedCodexPids.delete(p);
+}
+
+/**
+ * Codex children that are novel relative to `baseline`. A PID is novel if:
+ *   - it wasn't in baseline, OR
+ *   - it was in baseline but with a different lstart (PID reuse — old codex
+ *     died and the OS reassigned the PID to our new spawn)
+ * AND it isn't already owned by a concurrent codex caller.
+ */
+export function findNewCodexChildren(baseline: Map<number, string>): number[] {
+  const current = snapshotCodexChildren();
+  const novel: number[] = [];
+  for (const [pid, lstart] of current) {
+    const baselineLstart = baseline.get(pid);
+    // Same PID + same lstart fingerprint → continuation of the same process,
+    // not novel. Same PID + different lstart → PID reuse, treat as novel.
+    if (baselineLstart !== undefined && baselineLstart === lstart) continue;
+    if (globalOwnedCodexPids.has(pid)) continue;
+    novel.push(pid);
+  }
+  return novel;
+}
+
+/**
+ * Serialize the spawn critical section across concurrent codex callers
+ * (`codexProvider` and `queryCodexForkSession`). The lock MUST be held from
+ * baseline snapshot through the first generator event, because the SDK's
+ * `runStreamed()` is lazy — the actual `child_process.spawn()` happens when
+ * the iterator advances, not when `runStreamed()` resolves. Without a lock
+ * spanning that window, two callers see overlapping codex children and
+ * mis-attribute them on abort, leading to cross-kills.
+ *
+ * Only the spawn phase is serialized (typically a few hundred ms — codex's
+ * first event lands quickly). The actual LLM streaming after the first event
+ * runs concurrently as before.
+ */
+let codexSpawnChain: Promise<void> = Promise.resolve();
+
+/**
+ * Acquire the codex-spawn lock. Returns a release callback. Caller MUST invoke
+ * the release callback in a `finally` block (or via the convenience wrapper
+ * `withCodexSpawnSerial`) — otherwise the chain stalls indefinitely.
+ */
+export async function acquireCodexSpawnLock(): Promise<() => void> {
+  const prev = codexSpawnChain;
+  let release!: () => void;
+  let released = false;
+  codexSpawnChain = new Promise<void>((r) => {
+    release = () => {
+      if (released) return;
+      released = true;
+      r();
+    };
+  });
+  await prev;
+  return release;
+}
+
+/**
+ * Convenience wrapper for short, single-await critical sections. Prefer
+ * `acquireCodexSpawnLock` when the lock must span multiple awaits including
+ * iterator advancement (the codex spawn case).
+ */
+export async function withCodexSpawnSerial<T>(fn: () => Promise<T>): Promise<T> {
+  const release = await acquireCodexSpawnLock();
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}
+
+/** True iff `pid` is still alive. */
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True iff `pid` is alive and still appears to be the same process captured by
+ * `lstart`. An empty lstart means we could not fingerprint the original process,
+ * so we refuse to SIGKILL it later rather than risk killing a reused PID.
+ */
+function isSameProcess(pid: number, lstart: string): boolean {
+  return lstart !== "" && isAlive(pid) && getProcLstart(pid) === lstart;
+}
+
+type CodexKillPlan = {
+  rootPids: number[];
+  targets: Map<number, string>;
+};
+
+/** Capture the complete tree before signalling changes parent/child relationships. */
+function signalCodexTrees(rootPids: number[]): CodexKillPlan | null {
+  if (rootPids.length === 0) return null;
+
+  const targets = new Map<number, string>();
+  for (const root of rootPids) {
+    for (const pid of collectTree(root)) {
+      if (!targets.has(pid)) targets.set(pid, getProcLstart(pid));
+    }
+  }
+
+  logger.warn({ rootPids, totalPids: targets.size }, "codex-tree-kill: SIGTERM process tree");
+  for (const pid of targets.keys()) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // already dead or permission denied
+    }
+  }
+  return { rootPids, targets };
+}
+
+function hasSameProcessSurvivors(targets: Map<number, string>): boolean {
+  for (const [pid, lstart] of targets) {
+    if (isSameProcess(pid, lstart)) return true;
+  }
+  return false;
+}
+
+/** Kill survivors from a previously fingerprinted plan without risking PID reuse. */
+function killCodexStragglers({ rootPids, targets }: CodexKillPlan): void {
+  const aliveTargets: number[] = [];
+  let droppedAsPossibleReuse = 0;
+  for (const [pid, lstart] of targets) {
+    if (isSameProcess(pid, lstart)) {
+      aliveTargets.push(pid);
+    } else if (isAlive(pid)) {
+      droppedAsPossibleReuse++;
+    }
+  }
+  if (aliveTargets.length === 0) return;
+
+  // PID-reuse defence: re-walk the trees (children may have spawned siblings
+  // mid-SIGTERM), but ONLY signal PIDs that were in the SIGTERM-time targets.
+  const reachable = new Set<number>(aliveTargets);
+  for (const root of rootPids) {
+    const rootLstart = targets.get(root);
+    if (rootLstart && isSameProcess(root, rootLstart)) {
+      for (const pid of collectTree(root)) reachable.add(pid);
+    }
+  }
+  const stragglers: number[] = [];
+  for (const pid of reachable) {
+    const lstart = targets.get(pid);
+    if (lstart && isSameProcess(pid, lstart)) stragglers.push(pid);
+    else if (isAlive(pid)) droppedAsPossibleReuse++;
+  }
+  logger.warn(
+    {
+      aliveRoots: rootPids.filter((pid) => {
+        const lstart = targets.get(pid);
+        return lstart ? isSameProcess(pid, lstart) : false;
+      }),
+      totalStragglers: stragglers.length,
+      droppedAsPossibleReuse,
+    },
+    "codex-tree-kill: SIGKILL fallback after SIGTERM timeout",
+  );
+  for (const pid of stragglers) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // already dead
+    }
+  }
+}
+
+/**
+ * SIGTERM every PID in the descendant tree of each root in `rootPids`, then
+ * schedule a SIGKILL fallback after `SIGKILL_DELAY_MS` for any survivors.
+ * Safe to call multiple times; no-op if all PIDs are already dead.
+ */
+export function killCodexTrees(rootPids: number[]): void {
+  const plan = signalCodexTrees(rootPids);
+  if (!plan) return;
+
+  const killTimer = setTimeout(() => {
+    killCodexStragglers(plan);
+  }, SIGKILL_DELAY_MS);
+  killTimer.unref?.();
+}
+
+/**
+ * Reap every Codex tree owned by this node during process shutdown.
+ *
+ * The direct-child snapshot covers the narrow spawn window before a provider
+ * has registered its PID. Unlike the normal abort path, this function awaits
+ * the grace period with a referenced timer so node shutdown cannot exit before
+ * SIGKILL fallback has had a chance to remove resistant MCP/shell descendants.
+ */
+export async function killOwnedCodexTreesForShutdown(graceMs = 3_000): Promise<void> {
+  const roots = new Set(globalOwnedCodexPids);
+  for (const pid of snapshotCodexChildren().keys()) roots.add(pid);
+  const plan = signalCodexTrees([...roots]);
+  if (!plan) return;
+
+  const deadline = Date.now() + Math.max(0, graceMs);
+  while (Date.now() < deadline && hasSameProcessSurvivors(plan.targets)) {
+    await new Promise<void>((resolve) =>
+      setTimeout(resolve, Math.min(100, Math.max(1, deadline - Date.now()))),
+    );
+  }
+  killCodexStragglers(plan);
+}

package/dist/runtime/src/agents/contracts.ts

@@ -0,0 +1,69 @@
+import type { ConversationEntry } from "#storage/conversations";
+import type { AgentKind, EffortLevel } from "#types";
+
+/**
+ * Inputs to a rollout synthesis call. The conversation log is provider-agnostic
+ * — each registry's encoder reshapes it into the SDK-native rollout format
+ * (claude jsonl / codex jsonl) so a subsequent `resume`/`resumeThread` picks
+ * up the cross-agent dialogue as if it had always been native.
+ */
+export interface WriteRolloutOptions {
+  /** Working directory the resumed session will report. */
+  cwd: string;
+  /** Provider-agnostic event log to encode. */
+  entries: ConversationEntry[];
+  /**
+   * If set, the synthetic rollout is written using this id as the SDK
+   * session/thread key — i.e. the file lands at the SAME path the SDK
+   * already manages for an earlier run on this agent.
+   */
+  reuseSessionId?: string;
+  /** Effective model the synthesized provider session will resume with. */
+  model?: string;
+  /** Effective reasoning effort recorded by providers whose rollout format carries it. */
+  effort?: EffortLevel;
+}
+
+export interface WriteRolloutResult {
+  sessionId: string;
+  rolloutPath: string;
+}
+
+export interface ForkRegistryOptions {
+  parentSessionId: string;
+  cwd: string;
+  userId: number | string;
+  topicName: string;
+  title?: string;
+  /** Effective model/effort of the fork's first resumed turn. */
+  model?: string;
+  effort?: EffortLevel;
+}
+
+export interface ForkRegistryResult {
+  forkId: string;
+  rolloutPath: string;
+}
+
+export interface CleanupRolloutsOptions {
+  cwd: string;
+  sessionIds: string[];
+}
+
+/**
+ * Per-agent runtime config registry. Centralizes the bits that differ between
+ * agents so caller code can stay agent-agnostic.
+ */
+export interface AgentRegistry {
+  kind: AgentKind;
+  defaultModel: string;
+  defaultEffort?: EffortLevel;
+  expandModelAlias(s: string): string;
+  validateModel(s: string): boolean;
+  validEfforts: readonly EffortLevel[];
+  validateEffort(s: EffortLevel): boolean;
+  footerLabel(model: string, effort?: EffortLevel): string;
+  writeRollout(opts: WriteRolloutOptions): WriteRolloutResult;
+  forkSession(opts: ForkRegistryOptions): Promise<ForkRegistryResult>;
+  cleanupRollouts(opts: CleanupRolloutsOptions): Promise<void>;
+}

package/dist/runtime/src/agents/deep-map.ts

@@ -0,0 +1,13 @@
+/** Recursively apply fn to every string value in a nested object/array. */
+export function deepMapStrings(value: unknown, fn: (s: string) => string): unknown {
+  if (typeof value === "string") return fn(value);
+  if (Array.isArray(value)) return value.map((v) => deepMapStrings(v, fn));
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = deepMapStrings(v, fn);
+    }
+    return out;
+  }
+  return value;
+}

package/dist/runtime/src/agents/execution-host.ts

@@ -0,0 +1,91 @@
+import {
+  referencesRuntimeSecretStorage as defaultReferencesRuntimeSecretStorage,
+  shouldRedirectVaultTool as defaultShouldRedirectVaultTool,
+} from "#agents/vault-tool-policy";
+import { CLAUDE_EXECUTABLE, codexAuthFilePath } from "#platform/config";
+import { getMcpServersForQuery as defaultGetMcpServersForQuery } from "#platform/mcp-config";
+import { redactVaultSecrets as defaultRedactVaultSecrets } from "#storage/vault";
+import type { AgentQueryOptions } from "#types";
+
+/**
+ * Host-owned services used by the provider execution layer.
+ *
+ * The default implementation preserves standalone Negotium behaviour. An
+ * embedding host may replace these callbacks once during process bootstrap so
+ * providers use that host's MCP catalog and device-local secret store without
+ * importing any host-specific runtime code into Negotium.
+ */
+export interface AgentExecutionHost {
+  getMcpServersForQuery(opts: AgentQueryOptions): Record<string, unknown>;
+  redactVaultSecrets(userId: string, value: string): string;
+  referencesRuntimeSecretStorage(value: unknown): boolean;
+  shouldRedirectVaultTool(userId: string, toolName: string, input: unknown): boolean;
+  claudeCodeExecutablePath(): string | undefined;
+  codexAuthFilePath(): string;
+  transformQueryOptions?(opts: AgentQueryOptions): AgentQueryOptions;
+}
+
+const defaultHost: AgentExecutionHost = {
+  getMcpServersForQuery: defaultGetMcpServersForQuery,
+  redactVaultSecrets: defaultRedactVaultSecrets,
+  referencesRuntimeSecretStorage: defaultReferencesRuntimeSecretStorage,
+  shouldRedirectVaultTool: defaultShouldRedirectVaultTool,
+  claudeCodeExecutablePath: () => CLAUDE_EXECUTABLE,
+  codexAuthFilePath,
+};
+
+const hostRegistrations: Array<{
+  id: symbol;
+  overrides: Partial<AgentExecutionHost>;
+}> = [];
+
+function activeHost(): AgentExecutionHost {
+  const host = { ...defaultHost };
+  for (const registration of hostRegistrations) Object.assign(host, registration.overrides);
+  return host;
+}
+
+/** Configure provider host services. Returns a disposer useful for tests. */
+export function configureAgentExecutionHost(overrides: Partial<AgentExecutionHost>): () => void {
+  const registration = { id: Symbol("agent-execution-host"), overrides };
+  hostRegistrations.push(registration);
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    const index = hostRegistrations.findIndex((entry) => entry.id === registration.id);
+    if (index >= 0) hostRegistrations.splice(index, 1);
+  };
+}
+
+export function hostedMcpServers(opts: AgentQueryOptions): Record<string, unknown> {
+  return activeHost().getMcpServersForQuery(opts);
+}
+
+export function redactHostedSecrets(userId: string, value: string): string {
+  return activeHost().redactVaultSecrets(userId, value);
+}
+
+export function referencesHostedSecretStorage(value: unknown): boolean {
+  return activeHost().referencesRuntimeSecretStorage(value);
+}
+
+export function shouldRedirectHostedVaultTool(
+  userId: string,
+  toolName: string,
+  input: unknown,
+): boolean {
+  return activeHost().shouldRedirectVaultTool(userId, toolName, input);
+}
+
+export function transformHostedQueryOptions(opts: AgentQueryOptions): AgentQueryOptions {
+  return activeHost().transformQueryOptions?.(opts) ?? opts;
+}
+
+export function hostedClaudeCodeExecutablePath(): string | undefined {
+  return activeHost().claudeCodeExecutablePath();
+}
+
+export function hostedCodexAuthFilePath(): string {
+  return activeHost().codexAuthFilePath();
+}

package/dist/runtime/src/agents/fixtures/claude-attachments.jsonl

@@ -0,0 +1,2 @@
+{"parentUuid":"88e296c8-370a-4c40-a248-10fb661fc81d","isSidechain":false,"attachment":{"type":"deferred_tools_delta","addedNames":["AskUserQuestion","CronCreate","CronDelete","CronList","EnterPlanMode","EnterWorktree","ExitPlanMode","ExitWorktree","Monitor","NotebookEdit","PushNotification","RemoteTrigger","TaskOutput","TaskStop","TodoWrite","WebFetch","WebSearch","mcp__claude_ai_Google_Drive__authenticate","mcp__claude_ai_Google_Drive__complete_authentication"],"addedLines":["AskUserQuestion","CronCreate","CronDelete","CronList","EnterPlanMode","EnterWorktree","ExitPlanMode","ExitWorktree","Monitor","NotebookEdit","PushNotification","RemoteTrigger","TaskOutput","TaskStop","TodoWrite","WebFetch","WebSearch","mcp__claude_ai_Google_Drive__authenticate","mcp__claude_ai_Google_Drive__complete_authentication"],"removedNames":[]},"type":"attachment","uuid":"72cd3544-9370-45f4-97c7-700ac90fcb7f","timestamp":"2026-05-01T13:31:34.909Z","userType":"external","entrypoint":"sdk-ts","cwd":"/private/tmp/claude-poc-cwd","sessionId":"104a73cb-ae08-4464-b655-753b906cb197","version":"2.1.126","gitBranch":"HEAD"}
+{"parentUuid":"72cd3544-9370-45f4-97c7-700ac90fcb7f","isSidechain":false,"attachment":{"type":"skill_listing","content":"- update-config: Use this skill to configure the Claude Code harness via settings.json. Automated behaviors (\"from now on when X\", \"each time X\", \"whenever X\", \"before/after X\") require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill them. Also use for: permissions (\"allow X\", \"add permission\", \"move permission to\"), env vars (\"set X=Y\"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: \"allow npm commands\", \"add bq permission to global settings\", \"move permission to user settings\", \"set DEBUG=true\", \"when claude stops show X\". For simple settings like theme/model, suggest the /config command.\n- keybindings-help: Use when the user wants to customize keyboard shortcuts, rebind keys, add chord bindings, or modify ~/.claude/keybindings.json. Examples: \"rebind ctrl+s\", \"add a chord shortcut\", \"change the submit key\", \"customize keybindings\".\n- simplify: Review changed code for reuse, quality, and efficiency, then fix any issues found.\n- fewer-permission-prompts: Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project .claude/settings.json to reduce permission prompts.\n- loop: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo). Omit the interval to let the model self-pace. - When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval (e.g. \"check the deploy every 5 minutes\", \"keep running /babysit-prs\"). Do NOT invoke for one-off tasks.\n- schedule: Create, update, list, or run scheduled remote agents (routines) that execute on a cron schedule. - When the user wants to schedule a recurring or one-time remote agent (\"run this every Monday\", \"open a cleanup PR for X in 2 weeks\"), or to manage existing routines. ALSO OFFER PROACTIVELY: after you finish work that has a natural future follow-up, end your reply with a one-line offer to schedule a background agent to do it. Strong signals: a feature flag / gate / experiment / staged rollout was just shipped (offer a one-time agent in ~2 weeks to open a cleanup PR or evaluate results), a new alert/monitor was created (offer a recurring agent to triage it), a TODO/migration with a \"remove once X\" condition was left behind (offer a one-time agent to do the removal). Skip the offer for refactors, bug fixes, and anything that is done once it ships. Name a concrete action and cadence (\"in 2 weeks\", \"every Monday\") and only offer when the run just succeeded — do not pitch a schedule for something that has not happened yet.\n- claude-api: Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements).\nTRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project.\nSKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML.\n- init: Initialize a new CLAUDE.md file with codebase documentation\n- review: Review a pull request\n- security-review: Complete a security review of the pending changes on the current branch","skillCount":10,"isInitial":true},"type":"attachment","uuid":"51fe817e-380d-42d7-a4f4-b6d75e19ba63","timestamp":"2026-05-01T13:31:34.909Z","userType":"external","entrypoint":"sdk-ts","cwd":"/private/tmp/claude-poc-cwd","sessionId":"104a73cb-ae08-4464-b655-753b906cb197","version":"2.1.126","gitBranch":"HEAD"}