@h-rig/server 0.0.6-alpha.0

package/dist/src/inspector/agent-runtime.js

@@ -0,0 +1,1077 @@
+// @bun
+// packages/server/src/inspector/agent-runtime.ts
+import { spawn } from "child_process";
+import { createHash } from "crypto";
+import { accessSync, constants, realpathSync } from "fs";
+import { createInterface } from "readline";
+
+// packages/server/src/inspector/prompt.ts
+function renderSkills(skills) {
+  return skills.map((skill) => `- ${skill.name}: ${skill.rationale}`).join(`
+`);
+}
+function stableJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+function compactSnapshot(snapshot) {
+  const recentFindings = Array.isArray(snapshot.recentFindings) ? snapshot.recentFindings.filter((finding) => {
+    const kind = typeof finding.kind === "string" ? finding.kind : "";
+    const severity = typeof finding.severity === "string" ? finding.severity : "";
+    const source = typeof finding.source === "string" ? finding.source : "";
+    if (source === "inspector-agent") {
+      return false;
+    }
+    return kind !== "run.observed" || severity === "warn" || severity === "error";
+  }) : [];
+  return {
+    activeRuns: snapshot.activeRuns ?? [],
+    recentFindings,
+    followups: snapshot.followups ?? [],
+    analysisReports: snapshot.analysisReports ?? [],
+    availableTools: snapshot.availableTools ?? []
+  };
+}
+function buildInspectorBaseInstructions(options) {
+  return [
+    "You are Rig Global Inspector, the permanent supervisor for this workspace.",
+    "You operate as an out-of-band overlay around Rig execution, not inside the worker execution flow.",
+    "The lower runtime and provider layers are inspector-blind. Keep them that way.",
+    "App-server turns are transport boundaries only. They are not your operating model.",
+    "Stay broad, autonomous, and continuous in your judgment. Use turns only as a way to receive updates and emit progress.",
+    "Use full contextual judgment. There is no fixed intervention ladder.",
+    "You may patch task code or Rig itself, interrupt runs, relaunch runs, create follow-up tasks, run reviews, and improve the harness when confidence is high.",
+    "Be decisive, but stay surgical. Prefer the smallest action that materially improves the current situation.",
+    "Stay aware of all observable runs, the harness state, upstream drift tasks, and repeated failure patterns.",
+    "Document important findings and decisions through the inspector journal tools so the system retains a durable memory of what happened.",
+    "Treat TDD as the default for code and behavior changes unless a narrow recorded exception applies.",
+    "Before landing meaningful implementation work, run local review or another verification path that produces direct evidence.",
+    "When a human is not needed, do not wait. When a human is needed, create the right follow-up or journal note instead of stalling silently.",
+    "",
+    `Project root: ${options.projectRoot}`,
+    "",
+    "Required skills:",
+    renderSkills(options.requiredSkills),
+    "",
+    "Recommended skills:",
+    renderSkills(options.recommendedSkills)
+  ].join(`
+`);
+}
+function buildInspectorDeveloperInstructions(options) {
+  return [
+    "Operate pragmatically and keep momentum.",
+    "Use the native Codex capabilities and the semantic inspector tools together.",
+    "You are free to inspect, edit, test, relaunch, review, and continue as far as the current situation warrants.",
+    "Yield when you reach a useful checkpoint, need fresher external state, or detect that continued looping would be wasteful.",
+    "Prefer semantic inspector tools for journal, follow-up task, upstream-sync, review, and run-inspection operations.",
+    "Use shell, read, write, edit, and git directly when that is the fastest reliable way to diagnose or repair the system.",
+    "When you create or modify code, keep the red-green-refactor discipline visible in your reasoning and actions.",
+    "Before claiming something is fixed, verify it directly.",
+    "Spawn specialist child agents when parallel work is useful, but remain the full-context owner and take over when they are not doing the job well enough.",
+    "You are responsible both for task oversight and for Rig self-improvement when a clear win-win fix is available.",
+    "",
+    `Workspace root: ${options.projectRoot}`,
+    "",
+    "Skill catalog in scope:",
+    renderSkills([...options.requiredSkills, ...options.recommendedSkills])
+  ].join(`
+`);
+}
+function buildInspectorTurnPrompt(options) {
+  const compact = compactSnapshot(options.snapshot);
+  return [
+    "Rig inspector update.",
+    `reason: ${options.reason}`,
+    `timestamp: ${options.now}`,
+    "Review the current state and use broad judgment about whether intervention is warranted.",
+    "You may take multiple actions inside this turn if that is the most effective way to improve the situation.",
+    "Do not become noisy or repetitive when nothing material changed.",
+    "When you reach a useful checkpoint, emit one compact operator update in this form:",
+    "STATUS: <observed|acted|escalated|waiting>",
+    "NOTE: <one or two concise sentences>",
+    "Then yield so the server can deliver the next update when needed.",
+    "",
+    "Current snapshot:",
+    stableJson(compact)
+  ].join(`
+`);
+}
+
+// packages/server/src/bootstrap.ts
+import { RIG_DEFINITION_DIRNAME, resolveMonorepoRoot } from "@rig/runtime";
+
+// packages/server/src/inspector/tools.ts
+var INSPECTOR_TOOL_DEFINITIONS = [
+  {
+    name: "read_inspector_snapshot",
+    description: "Read the current global inspector snapshot including active runs, recent findings, follow-ups, reports, and available semantic tools.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: "discover_active_runs",
+    description: "List currently active Rig runs known to the inspector overlay.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: "inspect_run",
+    description: "Inspect one run in detail, including session paths, capabilities, and recent journal observations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: { type: "string" }
+      },
+      required: ["runId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "record_inspector_note",
+    description: "Append a durable note to the inspector journal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: { type: "string" },
+        summary: { type: "string" },
+        details: { type: "object" }
+      },
+      required: ["summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "list_inspector_missions",
+    description: "List durable inspector missions with status, pending effects, posted results, and completion proof state.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: "create_inspector_mission",
+    description: "Create a durable inspector-owned mission for a source task contract. The sourceTask is preserved in the mission JSON state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sourceTask: { type: "object" },
+        owner: { type: "string" },
+        summary: { type: "string" }
+      },
+      required: ["sourceTask"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "read_inspector_mission",
+    description: "Read a durable inspector mission, including sourceTask, pending effects, posted results, proof, and mission journal.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" }
+      },
+      required: ["missionId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "request_inspector_effect",
+    description: "Request a provider-worker effect for an inspector mission. Pending effects gate acceptance until posted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" },
+        effectId: { type: "string" },
+        kind: { type: "string" },
+        executor: { type: "string" },
+        summary: { type: "string" },
+        input: { type: "object" }
+      },
+      required: ["missionId", "kind", "executor", "summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "post_inspector_effect_result",
+    description: "Post a provider-worker effect result. Partial, blocked, or failed results block completion proof.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" },
+        effectId: { type: "string" },
+        status: { type: "string", enum: ["completed", "partial", "blocked", "failed"] },
+        summary: { type: "string" },
+        result: { type: "object" },
+        postedBy: { type: "string" }
+      },
+      required: ["missionId", "effectId", "status", "summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "accept_inspector_mission",
+    description: "Accept a mission closeout and emit completionProof when no pending/blocking effects remain.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" },
+        acceptedBy: { type: "string" },
+        summary: { type: "string" },
+        evidence: { type: "array", items: { type: "string" } }
+      },
+      required: ["missionId", "summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "reject_inspector_mission",
+    description: "Reject a mission closeout without emitting completionProof.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" },
+        rejectedBy: { type: "string" },
+        summary: { type: "string" },
+        rationale: { type: "string" }
+      },
+      required: ["missionId", "summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "block_inspector_mission",
+    description: "Mark a mission blocked without emitting completionProof.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" },
+        blockedBy: { type: "string" },
+        summary: { type: "string" },
+        details: { type: "object" }
+      },
+      required: ["missionId", "summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "complete_inspector_mission",
+    description: "Return the accepted mission completionProof. This fails until the mission has been accepted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        missionId: { type: "string" }
+      },
+      required: ["missionId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "create_followup_task",
+    description: "Create or dedupe a structured follow-up task for work the inspector discovered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        originRunId: { type: "string" },
+        summary: { type: "string" },
+        dedupeKey: { type: "string" },
+        details: { type: "object" }
+      },
+      required: ["summary"],
+      additionalProperties: true
+    }
+  },
+  {
+    name: "provision_skill",
+    description: "Return the role-aware Rig skill set that should be in force for an agent or specialist lane.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: { type: "string" },
+        role: { type: "string" },
+        taskKind: { type: "string" },
+        exception: { type: "object" }
+      },
+      additionalProperties: true
+    }
+  },
+  {
+    name: "run_local_review",
+    description: "Run the local Rig reviewer/validator flow for a task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: { type: "string" },
+        taskId: { type: "string" },
+        focus: { type: "array", items: { type: "string" } }
+      },
+      required: ["taskId"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "scan_upstream_drift",
+    description: "Run the separate upstream-sync workflow and create follow-up tasks for needed ports.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scanId: { type: "string" }
+      },
+      additionalProperties: true
+    }
+  },
+  {
+    name: "generate_analysis_report",
+    description: "Generate an inspector analysis report from journaled run and oversight data.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reportId: { type: "string" },
+        reportType: { type: "string" },
+        runId: { type: "string" }
+      },
+      additionalProperties: true
+    }
+  }
+];
+
+// packages/server/src/inspector/agent-runtime.ts
+var DEFAULT_CLIENT_INFO = {
+  name: "rig_global_inspector",
+  title: "Rig Global Inspector",
+  version: "0.1.0"
+};
+function createInspectorAgentRuntime(options) {
+  const now = options.now ?? (() => new Date().toISOString());
+  const pollMs = Math.max(100, options.pollMs ?? 2000);
+  const startTimeoutMs = Math.max(1000, options.startTimeoutMs ?? 20000);
+  const model = options.model ?? process.env.RIG_INSPECTOR_MODEL ?? null;
+  const skills = [...options.requiredSkills, ...options.recommendedSkills];
+  const transport = options.transportFactory?.() ?? createCodexInspectorTransport({
+    model
+  });
+  const baseInstructions = buildInspectorBaseInstructions({
+    projectRoot: options.projectRoot,
+    requiredSkills: options.requiredSkills,
+    recommendedSkills: options.recommendedSkills
+  });
+  const developerInstructions = buildInspectorDeveloperInstructions({
+    projectRoot: options.projectRoot,
+    requiredSkills: options.requiredSkills,
+    recommendedSkills: options.recommendedSkills
+  });
+  let pollTimer = null;
+  let status = "stopped";
+  let threadId = null;
+  let processId = null;
+  let lastFingerprint = null;
+  let lastPromptAt = null;
+  let lastTurnCompletedAt = null;
+  let lastAssistantMessage = null;
+  let lastError = null;
+  let inFlight = null;
+  let pendingTurn = null;
+  const dispatchPrompt = async (turn) => {
+    status = "running";
+    lastPromptAt = now();
+    try {
+      const result = await transport.sendTurn(turn.prompt);
+      lastAssistantMessage = result.assistantMessage;
+      lastTurnCompletedAt = now();
+      lastError = result.error;
+      lastFingerprint = turn.fingerprint;
+      status = result.status === "completed" ? "idle" : "errored";
+      if (options.journal) {
+        if (result.assistantMessage) {
+          options.journal.appendObservation({
+            id: `inspector-agent-message:${Date.now()}`,
+            runId: null,
+            dedupeKey: null,
+            kind: "agent.message",
+            severity: "info",
+            source: "inspector-agent",
+            summary: result.assistantMessage.split(`
+`)[0].slice(0, 240),
+            details: {
+              status: result.status,
+              message: result.assistantMessage
+            },
+            createdAt: now()
+          });
+        }
+        if (result.error) {
+          options.journal.appendObservation({
+            id: `inspector-agent-error:${Date.now()}`,
+            runId: null,
+            dedupeKey: null,
+            kind: "agent.error",
+            severity: "warn",
+            source: "inspector-agent",
+            summary: result.error,
+            details: {
+              status: result.status
+            },
+            createdAt: now()
+          });
+        }
+      }
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : String(error);
+      status = "errored";
+      if (options.journal) {
+        options.journal.appendObservation({
+          id: `inspector-agent-crash:${Date.now()}`,
+          runId: null,
+          dedupeKey: null,
+          kind: "agent.error",
+          severity: "warn",
+          source: "inspector-agent",
+          summary: lastError,
+          details: null,
+          createdAt: now()
+        });
+      }
+    } finally {
+      inFlight = null;
+      if (pendingTurn) {
+        const next = pendingTurn;
+        pendingTurn = null;
+        if (next.fingerprint === lastFingerprint) {
+          return;
+        }
+        inFlight = dispatchPrompt(next);
+        await inFlight;
+      }
+    }
+  };
+  const queuePrompt = async (turn) => {
+    if (inFlight) {
+      pendingTurn = turn;
+      return false;
+    }
+    inFlight = dispatchPrompt(turn);
+    await inFlight;
+    return true;
+  };
+  const tickNow = async (reason) => {
+    if (status === "stopped" || status === "starting") {
+      return false;
+    }
+    const snapshot = options.snapshotProvider();
+    const prompt = buildInspectorTurnPrompt({
+      reason,
+      snapshot,
+      now: now()
+    });
+    const fingerprint = hashSnapshot(snapshot);
+    if (reason !== "startup" && fingerprint === lastFingerprint) {
+      return false;
+    }
+    return queuePrompt({
+      fingerprint,
+      prompt
+    });
+  };
+  return {
+    async start() {
+      if (status === "starting" || status === "idle" || status === "running") {
+        return false;
+      }
+      if (status === "errored") {
+        await transport.stop().catch(() => {});
+        threadId = null;
+        processId = null;
+      }
+      status = "starting";
+      try {
+        const started = await withTimeout(transport.startSession({
+          projectRoot: options.projectRoot,
+          model,
+          baseInstructions,
+          developerInstructions,
+          dynamicTools: INSPECTOR_TOOL_DEFINITIONS,
+          invokeDynamicTool: options.invokeDynamicTool
+        }), startTimeoutMs, `Inspector agent start timed out after ${startTimeoutMs}ms`);
+        threadId = started.threadId;
+        processId = started.processId;
+        status = "idle";
+        pollTimer = setInterval(() => {
+          tickNow("poll").catch((error) => {
+            lastError = error instanceof Error ? error.message : String(error);
+            status = "errored";
+          });
+        }, pollMs);
+        await tickNow("startup");
+        return true;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        status = "errored";
+        throw error;
+      }
+    },
+    async stop() {
+      if (pollTimer) {
+        clearInterval(pollTimer);
+      }
+      pollTimer = null;
+      pendingTurn = null;
+      await transport.stop();
+      status = "stopped";
+      threadId = null;
+      processId = null;
+    },
+    isRunning() {
+      return status !== "stopped";
+    },
+    tickNow,
+    snapshot() {
+      return {
+        ...transport.snapshot(),
+        status,
+        threadId,
+        processId,
+        queueDepth: pendingTurn ? 1 : 0,
+        lastFingerprint,
+        lastPromptAt,
+        lastTurnCompletedAt,
+        lastAssistantMessage,
+        lastError,
+        model,
+        skills
+      };
+    }
+  };
+}
+function hashPrompt(prompt) {
+  return createHash("sha1").update(prompt).digest("hex");
+}
+function hashSnapshot(snapshot) {
+  const compact = {
+    activeRuns: snapshot.activeRuns ?? [],
+    recentFindings: (snapshot.recentFindings ?? []).filter((finding) => {
+      const kind = typeof finding.kind === "string" ? finding.kind : "";
+      const severity = typeof finding.severity === "string" ? finding.severity : "";
+      const source = typeof finding.source === "string" ? finding.source : "";
+      if (source === "inspector-agent") {
+        return false;
+      }
+      return kind !== "run.observed" || severity === "warn" || severity === "error";
+    }),
+    followups: snapshot.followups ?? [],
+    analysisReports: snapshot.analysisReports ?? [],
+    availableTools: snapshot.availableTools ?? []
+  };
+  return hashPrompt(JSON.stringify(compact));
+}
+function createCodexInspectorTransport(options) {
+  const turnTimeoutMs = Math.max(5000, options.turnTimeoutMs ?? 45000);
+  let child = null;
+  let threadId = null;
+  let processId = null;
+  let status = "stopped";
+  let lastAssistantMessage = null;
+  let lastError = null;
+  const pendingResponses = new Map;
+  const assistantMessageText = new Map;
+  const inFlightToolCalls = new Set;
+  const recentProtocolEvents = [];
+  let nextRequestId = 1;
+  let sendQueue = Promise.resolve();
+  let currentTurn = null;
+  let invokeDynamicTool = null;
+  const rememberProtocolEvent = (event) => {
+    recentProtocolEvents.push(event);
+    if (recentProtocolEvents.length > 25) {
+      recentProtocolEvents.splice(0, recentProtocolEvents.length - 25);
+    }
+  };
+  const sendMessage = async (payload) => {
+    if (!child) {
+      throw new Error("Inspector agent session is not started.");
+    }
+    const activeChild = child;
+    if (activeChild.stdin.destroyed || !activeChild.stdin.writable) {
+      throw new Error(lastError ?? "Inspector agent transport is not writable.");
+    }
+    rememberProtocolEvent({
+      at: new Date().toISOString(),
+      direction: "send",
+      kind: payload.method ? "request" : "response",
+      method: typeof payload.method === "string" ? payload.method : `response:${String(payload.id ?? "unknown")}`
+    });
+    const line = `${JSON.stringify(payload)}
+`;
+    sendQueue = sendQueue.then(() => writeChildLine(activeChild, line));
+    await sendQueue;
+  };
+  const sendRequest = async (method, params) => {
+    const id = nextRequestId;
+    nextRequestId += 1;
+    const response = new Promise((resolve, reject) => {
+      pendingResponses.set(id, { resolve, reject });
+    });
+    response.catch(() => {});
+    try {
+      await sendMessage({ id, method, params });
+    } catch (error) {
+      pendingResponses.delete(id);
+      throw error;
+    }
+    return response;
+  };
+  const sendResponse = async (id, result) => {
+    await sendMessage({ id, result });
+  };
+  const sendError = async (id, message) => {
+    await sendMessage({
+      id,
+      error: {
+        code: -32603,
+        message
+      }
+    });
+  };
+  const trackToolCall = (call) => {
+    inFlightToolCalls.add(call);
+    call.finally(() => inFlightToolCalls.delete(call)).catch((err) => {
+      console.warn("[inspector/agent-runtime] in-flight tool call failure:", err);
+    });
+  };
+  const handleServerRequest = (message) => {
+    const method = message.method;
+    const requestId = message.id;
+    if (!method || requestId === undefined) {
+      return;
+    }
+    if (method === "item/tool/call") {
+      const params = message.params ?? {};
+      const toolName = normalizeString(params.tool);
+      const toolArgs = asRecord(params.arguments) ?? {};
+      const toolCall = (async () => {
+        if (!toolName || !invokeDynamicTool) {
+          rememberProtocolEvent({
+            at: new Date().toISOString(),
+            direction: "recv",
+            kind: "request",
+            method: "item/tool/call:malformed"
+          });
+          await sendError(requestId, "Malformed inspector dynamic tool call.");
+          return;
+        }
+        try {
+          const invocation = await invokeDynamicTool(toolName, toolArgs);
+          await sendResponse(requestId, {
+            contentItems: [
+              {
+                type: "inputText",
+                text: typeof invocation.details === "string" ? invocation.details : JSON.stringify({
+                  status: invocation.status,
+                  summary: invocation.summary,
+                  details: invocation.details
+                }, null, 2)
+              }
+            ],
+            success: invocation.status !== "failed" && invocation.status !== "missing"
+          });
+        } catch (error) {
+          const messageText = error instanceof Error ? error.message : String(error);
+          await sendResponse(requestId, {
+            contentItems: [{ type: "inputText", text: messageText }],
+            success: false
+          });
+        }
+      })();
+      trackToolCall(toolCall);
+      return;
+    }
+    if (method === "item/commandExecution/requestApproval" || method === "item/fileChange/requestApproval") {
+      trackToolCall(sendResponse(requestId, { decision: "approved_for_session" }));
+      return;
+    }
+    if (method === "item/permissions/requestApproval") {
+      trackToolCall(sendResponse(requestId, {
+        permissions: asRecord(message.params)?.permissions ?? {},
+        scope: "session"
+      }));
+      return;
+    }
+    if (method === "item/tool/requestUserInput") {
+      trackToolCall(sendResponse(requestId, { answers: {} }));
+      return;
+    }
+    if (method === "mcpServer/elicitation/request") {
+      trackToolCall(sendResponse(requestId, { action: "decline" }));
+      return;
+    }
+    if (method === "applyPatchApproval" || method === "execCommandApproval") {
+      trackToolCall(sendResponse(requestId, { decision: "approved_for_session" }));
+      return;
+    }
+    trackToolCall(sendError(requestId, `Unsupported inspector app-server request: ${method}`));
+  };
+  const handleNotification = (message) => {
+    const method = message.method;
+    const params = message.params ?? {};
+    if (!method) {
+      return;
+    }
+    if (method === "thread/started") {
+      const thread = asRecord(params.thread);
+      threadId = normalizeString(thread?.id);
+      status = "idle";
+      return;
+    }
+    if (method === "turn/started") {
+      status = "running";
+      currentTurn?.events.push({ method, params });
+      return;
+    }
+    if (method === "item/agentMessage/delta") {
+      const itemId = normalizeString(params.itemId);
+      const delta = typeof params.delta === "string" ? params.delta : "";
+      if (itemId && delta) {
+        assistantMessageText.set(itemId, `${assistantMessageText.get(itemId) ?? ""}${delta}`);
+      }
+      return;
+    }
+    if (method === "item/completed") {
+      const item = asRecord(params.item);
+      const itemType = normalizeString(item?.type);
+      const itemId = normalizeString(item?.id);
+      currentTurn?.events.push({ method, params });
+      if (itemType === "agentMessage" && itemId) {
+        const finalText = normalizeString(item?.text) ?? assistantMessageText.get(itemId) ?? "";
+        assistantMessageText.delete(itemId);
+        if (finalText.trim()) {
+          lastAssistantMessage = finalText.trim();
+        }
+      }
+      return;
+    }
+    if (method === "error") {
+      lastError = normalizeString(params.message) ?? JSON.stringify(params);
+      currentTurn?.events.push({ method, params });
+      return;
+    }
+    if (method === "turn/completed") {
+      const turn = asRecord(params.turn);
+      const error = asRecord(turn?.error);
+      const completion = {
+        status: normalizeString(turn?.status) ?? "failed",
+        error: normalizeString(error?.message),
+        assistantMessage: lastAssistantMessage,
+        events: currentTurn?.events ?? []
+      };
+      status = completion.status === "completed" ? "idle" : "errored";
+      currentTurn?.resolve(completion);
+      currentTurn = null;
+      return;
+    }
+  };
+  const bootstrapChild = (config) => {
+    const codexExecutable = resolveCodexExecutable();
+    child = spawn(codexExecutable, ["app-server"], {
+      cwd: config.projectRoot,
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    processId = child.pid ?? null;
+    const stdout = createInterface({ input: child.stdout });
+    const stderr = createInterface({ input: child.stderr });
+    stdout.on("line", (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        return;
+      }
+      let message;
+      try {
+        message = JSON.parse(trimmed);
+      } catch {
+        return;
+      }
+      if (message.method) {
+        if (message.id !== undefined) {
+          rememberProtocolEvent({
+            at: new Date().toISOString(),
+            direction: "recv",
+            kind: "request",
+            method: message.method
+          });
+          handleServerRequest(message);
+        } else {
+          rememberProtocolEvent({
+            at: new Date().toISOString(),
+            direction: "recv",
+            kind: "notification",
+            method: message.method
+          });
+          handleNotification(message);
+        }
+        return;
+      }
+      if (message.id !== undefined) {
+        rememberProtocolEvent({
+          at: new Date().toISOString(),
+          direction: "recv",
+          kind: "response",
+          method: `response:${String(message.id)}`
+        });
+        const pending = pendingResponses.get(message.id);
+        if (!pending) {
+          return;
+        }
+        pendingResponses.delete(message.id);
+        if (message.error) {
+          pending.reject(new Error(formatJsonRpcError(message.error)));
+        } else {
+          pending.resolve(message.result ?? {});
+        }
+      }
+    });
+    stderr.on("line", (line) => {
+      if (line.trim()) {
+        rememberProtocolEvent({
+          at: new Date().toISOString(),
+          direction: "recv",
+          kind: "stderr",
+          method: line.trim().slice(0, 240)
+        });
+        lastError = line.trim();
+      }
+    });
+    child.once("error", (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      lastError = message;
+      status = "errored";
+      for (const [id, pending] of pendingResponses.entries()) {
+        pending.reject(new Error(message));
+        pendingResponses.delete(id);
+      }
+      if (currentTurn) {
+        currentTurn.reject(new Error(message));
+        currentTurn = null;
+      }
+      threadId = null;
+      processId = null;
+      child = null;
+    });
+    child.once("close", (code, signal) => {
+      const exitMessage = `Inspector app-server exited (${String(code ?? signal ?? "unknown")})`;
+      for (const [id, pending] of pendingResponses.entries()) {
+        pending.reject(new Error(exitMessage));
+        pendingResponses.delete(id);
+      }
+      if (currentTurn) {
+        currentTurn.reject(new Error(exitMessage));
+        currentTurn = null;
+      }
+      status = "stopped";
+      lastError = exitMessage;
+      threadId = null;
+      processId = null;
+      child = null;
+    });
+    return child;
+  };
+  return {
+    async startSession(config) {
+      if (child) {
+        return { threadId, processId };
+      }
+      invokeDynamicTool = config.invokeDynamicTool;
+      status = "starting";
+      const activeChild = bootstrapChild(config);
+      await waitForChildSpawn(activeChild);
+      await sendRequest("initialize", {
+        clientInfo: DEFAULT_CLIENT_INFO,
+        capabilities: {
+          experimentalApi: true
+        }
+      });
+      const started = await sendRequest("thread/start", {
+        model: config.model ?? options.model ?? null,
+        cwd: config.projectRoot,
+        approvalPolicy: "never",
+        sandbox: "danger-full-access",
+        serviceName: "rig_global_inspector",
+        personality: "pragmatic",
+        ephemeral: false,
+        baseInstructions: config.baseInstructions,
+        developerInstructions: config.developerInstructions,
+        dynamicTools: config.dynamicTools
+      });
+      const thread = asRecord(started.thread);
+      threadId = normalizeString(thread?.id) ?? threadId;
+      if (!threadId) {
+        const preview = JSON.stringify(started).slice(0, 400);
+        throw new Error(`Codex thread/start response did not include thread.id (got: ${preview}). ` + `Likely codex protocol version mismatch \u2014 current Rig speaks codex 0.130 schema.`);
+      }
+      status = "idle";
+      return { threadId, processId };
+    },
+    async sendTurn(prompt) {
+      if (!child || !threadId) {
+        throw new Error("Inspector agent session is not ready.");
+      }
+      if (currentTurn) {
+        throw new Error("Inspector agent turn already in progress.");
+      }
+      lastAssistantMessage = null;
+      lastError = null;
+      const turnResult = new Promise((resolve, reject) => {
+        currentTurn = {
+          resolve,
+          reject,
+          events: []
+        };
+      });
+      try {
+        await sendRequest("turn/start", {
+          threadId,
+          approvalPolicy: "never",
+          input: [
+            {
+              type: "text",
+              text: prompt,
+              text_elements: []
+            }
+          ]
+        });
+      } catch (error) {
+        currentTurn = null;
+        throw error;
+      }
+      let result;
+      try {
+        result = await withTimeout(turnResult, turnTimeoutMs, `Inspector agent turn timed out after ${turnTimeoutMs}ms`);
+      } catch (error) {
+        currentTurn = null;
+        if (child) {
+          terminateChild(child);
+          child = null;
+        }
+        throw error;
+      }
+      if (inFlightToolCalls.size > 0) {
+        await Promise.allSettled(Array.from(inFlightToolCalls));
+      }
+      return result;
+    },
+    snapshot() {
+      return {
+        status,
+        threadId,
+        processId,
+        queueDepth: 0,
+        lastAssistantMessage,
+        lastError,
+        recentProtocolEvents: [...recentProtocolEvents]
+      };
+    },
+    async stop() {
+      if (child) {
+        terminateChild(child);
+        child = null;
+      }
+      status = "stopped";
+      threadId = null;
+      processId = null;
+    }
+  };
+}
+function writeChildLine(child, line) {
+  return new Promise((resolve, reject) => {
+    child.stdin.write(line, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+function terminateChild(child) {
+  if (child.killed) {
+    return;
+  }
+  try {
+    child.kill("SIGTERM");
+  } catch {}
+}
+async function waitForChildSpawn(child) {
+  await new Promise((resolve, reject) => {
+    const onSpawn = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    const cleanup = () => {
+      child.off("spawn", onSpawn);
+      child.off("error", onError);
+    };
+    child.once("spawn", onSpawn);
+    child.once("error", onError);
+  });
+}
+function resolveCodexExecutable() {
+  const candidate = process.env.RIG_INSPECTOR_CODEX_BIN ?? Bun.which("codex");
+  if (!candidate) {
+    throw new Error("Codex CLI is not available on PATH for the inspector app-server.");
+  }
+  let resolvedCandidate;
+  try {
+    resolvedCandidate = realpathSync(candidate);
+  } catch {
+    throw new Error(`Codex CLI is not executable for the inspector app-server: ${candidate}`);
+  }
+  try {
+    accessSync(resolvedCandidate, constants.X_OK);
+  } catch {
+    throw new Error(`Codex CLI is not executable for the inspector app-server: ${candidate}`);
+  }
+  return resolvedCandidate;
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function formatJsonRpcError(error) {
+  if (!error) {
+    return "Unknown app-server error";
+  }
+  const parts = [error.message, error.data ? JSON.stringify(error.data) : null].filter(Boolean);
+  return parts.join(" ");
+}
+async function withTimeout(promise, timeoutMs, message) {
+  let timer = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+export {
+  createInspectorAgentRuntime
+};