onto-mcp 0.3.2 → 0.4.0

package/dist/core-runtime/cli/spawn-watcher.js

@@ -1,54 +1,128 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-/**
- * Attempt to spawn the onto:review live watcher in a side pane / split / new tab
- * using the most appropriate terminal multiplexer detected from the environment.
- *
- * Detection priority (most universal first):
- *   1. tmux (any OS, via $TMUX env var) — splits the pane identified by
- *      `$TMUX_PANE` so the watcher stays beside the invoking pane even if
- *      the user has switched panes during startReviewSession.
- *   2. iTerm2 on macOS (via $TERM_PROGRAM === 'iTerm.app') — targets the
- *      session identified by `$ITERM_SESSION_ID`, which is inherited from
- *      the invoking session at process start, so splits land beside the
- *      pane that actually launched onto:review. If the env var is missing
- *      or no matching session is found, the spawn is refused (returns
- *      spawned: false) rather than falling back to the currently-focused
- *      tab — a default target would land the watcher on whichever tab happens to
- *      be frontmost at spawn time, which is the bug this path exists to
- *      avoid.
- *   3. Apple Terminal on macOS (via $TERM_PROGRAM === 'Apple_Terminal')
- *      — best effort; Terminal.app lacks a stable session identifier, so
- *      the spawn opens a new tab rather than a tab-targeted split.
- *
- * `sessionRoot` is required. It is passed through to the watcher script as
- * an explicit argument, which bypasses the `.onto/review/.latest-session`
- * pointer and therefore avoids the cross-session race that the global
- * pointer would otherwise create under concurrent review invocations.
- *
- * Returns silently with `spawned: false` if no supported mechanism is found.
- * The caller should print an explicit recovery hint in that case.
- *
- * This function never throws — it returns a result object instead, so the
- * runtime continues even if the spawn fails.
- */
-export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
-    // Resolution order for the watcher helper:
-    //   1. <projectRoot>/scripts/onto-review-watch.sh — co-located with the
-    //      review target (onto repo invocations, full-repo projects).
-    //   2. <ontoHome>/scripts/onto-review-watch.sh   — install-local script when
-    //      projectRoot is an isolated workspace and the watcher helper lives in
-    //      the repo home.
-    // Without the install-local script branch, any invocation with --project-root pointed at a
-    // non-repo location silently degrades to "watcher script not found"
-    // (observed 2026-04-22 self-review finding). The two-slot search keeps
-    // deterministic wrappers viable without forcing them to symlink or copy.
-    const candidates = [
-        path.join(projectRoot, "scripts", "onto-review-watch.sh"),
+const CODEX_APP_LAUNCHER_ENV = "ONTO_RUNTIME_WATCHER_CODEX_APP_LAUNCHER";
+function escapeAppleScriptString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function expandHomePath(value) {
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith("~/"))
+        return path.join(os.homedir(), value.slice(2));
+    return value;
+}
+function resolveConfiguredPath(value) {
+    const expanded = expandHomePath(value.trim());
+    return path.isAbsolute(expanded) ? expanded : path.resolve(expanded);
+}
+function yamlDoubleQuote(value) {
+    return JSON.stringify(value);
+}
+function sanitizedConfigName(sessionRoot) {
+    return `onto-runtime-${path.basename(sessionRoot).replace(/[^A-Za-z0-9._-]/g, "-")}`;
+}
+function warpLaunchConfigurationRoot() {
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(appData, "warp", "Warp", "data", "launch_configurations");
+    }
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), ".warp", "launch_configurations");
+    }
+    const xdgDataHome = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+    return path.join(xdgDataHome, "warp-terminal", "launch_configurations");
+}
+function openUri(uri) {
+    if (process.platform === "darwin") {
+        return spawnSync("open", [uri], { stdio: "ignore" }).status === 0;
+    }
+    if (process.platform === "win32") {
+        return spawnSync("cmd", ["/c", "start", "", uri], {
+            stdio: "ignore",
+            windowsHide: true,
+        }).status === 0;
+    }
+    return spawnSync("xdg-open", [uri], { stdio: "ignore" }).status === 0;
+}
+function writeWarpLaunchConfiguration(projectRoot, sessionRoot, watcherArgs) {
+    const configName = sanitizedConfigName(sessionRoot);
+    const configRoot = warpLaunchConfigurationRoot();
+    fs.mkdirSync(configRoot, { recursive: true });
+    const configPath = path.join(configRoot, `${configName}.yaml`);
+    fs.writeFileSync(configPath, [
+        "# Generated by onto-mcp runtime stream observation.",
+        "---",
+        `name: ${yamlDoubleQuote(`Onto Runtime ${path.basename(sessionRoot)}`)}`,
+        "windows:",
+        "  - tabs:",
+        "      - title: onto runtime",
+        "        layout:",
+        `          cwd: ${yamlDoubleQuote(path.resolve(projectRoot))}`,
+        "          commands:",
+        `            - exec: ${yamlDoubleQuote(watcherArgs)}`,
+        "        color: cyan",
+        "",
+    ].join("\n"), "utf8");
+    return configName;
+}
+function isCodexDesktopShell() {
+    return (process.env.CODEX_SHELL === "1" ||
+        typeof process.env.CODEX_THREAD_ID === "string" ||
+        (process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE ?? "")
+            .toLowerCase()
+            .includes("codex"));
+}
+function isWarpShell() {
+    return (process.env.TERM_PROGRAM === "WarpTerminal" ||
+        process.env.WARP_IS_LOCAL_SHELL_SESSION === "1" ||
+        typeof process.env.WARP_BOOTSTRAPPED === "string");
+}
+function isCursorIntegratedTerminal() {
+    const cursorSignals = [
+        process.env.CURSOR_TRACE_ID,
+        process.env.CURSOR_AGENT,
+        process.env.CURSOR_SESSION_ID,
+        process.env.VSCODE_CWD,
+        process.env.VSCODE_IPC_HOOK_CLI,
+        process.env.VSCODE_GIT_ASKPASS_MAIN,
     ];
+    return (process.env.TERM_PROGRAM === "vscode" &&
+        cursorSignals.some((value) => value?.toLowerCase().includes("cursor")));
+}
+function spawnViaMacAppKeystrokes(args) {
+    if (process.platform !== "darwin")
+        return false;
+    const escapedAppName = escapeAppleScriptString(args.appName);
+    const escapedCommand = escapeAppleScriptString(args.watcherArgs);
+    const script = `set previousClipboard to the clipboard\n` +
+        `set the clipboard to "${escapedCommand}"\n` +
+        `tell application "${escapedAppName}" to activate\n` +
+        `delay 0.2\n` +
+        `tell application "System Events"\n` +
+        args.focusTerminalScript +
+        `  delay 0.2\n` +
+        `  keystroke "v" using {command down}\n` +
+        `  key code 36\n` +
+        `end tell\n` +
+        `delay 0.2\n` +
+        `set the clipboard to previousClipboard\n` +
+        `return "matched"`;
+    const result = spawnSync("osascript", ["-e", script], { encoding: "utf8" });
+    return result.status === 0 && result.stdout.trim() === "matched";
+}
+function spawnViaConfiguredLauncher(args) {
+    const result = spawnSync(args.launcherPath, [args.watcherScript, args.sessionRoot, args.projectRoot, args.watcherArgs], { stdio: "ignore" });
+    return result.status === 0;
+}
+function spawnWatcherPaneForScript(projectRoot, sessionRoot, scriptName, ontoHome, disabledEnvName) {
+    if (disabledEnvName && process.env[disabledEnvName] === "0") {
+        return { spawned: false, reason: `${disabledEnvName}=0` };
+    }
+    const candidates = [path.join(projectRoot, "scripts", scriptName)];
     if (ontoHome && ontoHome !== projectRoot) {
-        candidates.push(path.join(ontoHome, "scripts", "onto-review-watch.sh"));
+        candidates.push(path.join(ontoHome, "scripts", scriptName));
     }
     const watcherScript = candidates.find((c) => fs.existsSync(c));
     if (!watcherScript) {
@@ -61,6 +135,30 @@ export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
     // without producing a visible side pane or extra terminal tab on every
     // run. Enabled via `ONTO_WATCHER_DRY_RUN=1`.
     const dryRun = process.env.ONTO_WATCHER_DRY_RUN === "1";
+    const skippedAttachReasons = [];
+    const customCommand = process.env.ONTO_RUNTIME_WATCHER_COMMAND;
+    if (typeof customCommand === "string" && customCommand.trim().length > 0) {
+        if (dryRun) {
+            return { spawned: true, mechanism: "custom_command", dry_run: true };
+        }
+        const command = customCommand
+            .replaceAll("{watcherCommand}", watcherArgs)
+            .replaceAll("{watcherScript}", watcherScript)
+            .replaceAll("{sessionRoot}", sessionRoot)
+            .replaceAll("{projectRoot}", projectRoot);
+        try {
+            const result = spawnSync(command, [], {
+                shell: true,
+                stdio: "ignore",
+            });
+            if (result.status === 0) {
+                return { spawned: true, mechanism: "custom_command" };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
     // Priority 1: tmux (works on any OS, most universal)
     if (process.env.TMUX) {
         if (dryRun) {
@@ -86,6 +184,69 @@ export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
             // fall through
         }
     }
+    if (isCodexDesktopShell()) {
+        const configuredLauncher = process.env[CODEX_APP_LAUNCHER_ENV];
+        if (configuredLauncher?.trim()) {
+            const launcherPath = resolveConfiguredPath(configuredLauncher);
+            if (!fs.existsSync(launcherPath)) {
+                skippedAttachReasons.push(`${CODEX_APP_LAUNCHER_ENV} not found`);
+            }
+            else if (dryRun) {
+                return { spawned: true, mechanism: "codex_app", dry_run: true };
+            }
+            else {
+                try {
+                    if (spawnViaConfiguredLauncher({
+                        launcherPath,
+                        watcherScript,
+                        sessionRoot,
+                        projectRoot,
+                        watcherArgs,
+                    })) {
+                        return { spawned: true, mechanism: "codex_app" };
+                    }
+                    skippedAttachReasons.push(`${CODEX_APP_LAUNCHER_ENV} failed`);
+                }
+                catch {
+                    skippedAttachReasons.push(`${CODEX_APP_LAUNCHER_ENV} failed`);
+                }
+            }
+        }
+        else {
+            skippedAttachReasons.push(`${CODEX_APP_LAUNCHER_ENV} not set`);
+        }
+    }
+    if (isWarpShell()) {
+        if (dryRun) {
+            return { spawned: true, mechanism: "warp", dry_run: true };
+        }
+        try {
+            const configName = writeWarpLaunchConfiguration(projectRoot, sessionRoot, watcherArgs);
+            if (openUri(`warp://launch/${encodeURIComponent(configName)}`)) {
+                return { spawned: true, mechanism: "warp" };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (isCursorIntegratedTerminal()) {
+        if (dryRun) {
+            return { spawned: true, mechanism: "cursor", dry_run: true };
+        }
+        try {
+            if (spawnViaMacAppKeystrokes({
+                appName: "Cursor",
+                watcherArgs,
+                focusTerminalScript: `  key code 50 using {control down, shift down}\n`,
+            })) {
+                return { spawned: true, mechanism: "cursor" };
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
     // Priority 2: iTerm2 on macOS
     // Target the originating session via $ITERM_SESSION_ID (inherited at
     // process start), so the split lands beside the pane that launched
@@ -168,6 +329,64 @@ export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
     }
     return {
         spawned: false,
-        reason: "no supported terminal multiplexer detected (tmux, iTerm2, Apple Terminal)",
+        reason: [
+            ...skippedAttachReasons,
+            "no supported terminal attach target detected (tmux, configured Codex app launcher, Warp, Cursor, iTerm2, Apple Terminal)",
+        ].join("; "),
     };
 }
+/**
+ * Attempt to spawn the onto:review live watcher in a side pane / split / new tab
+ * using the most appropriate terminal multiplexer detected from the environment.
+ *
+ * Detection priority (most universal first):
+ *   1. ONTO_RUNTIME_WATCHER_COMMAND — host-provided launcher template.
+ *   2. tmux (any OS, via $TMUX env var) — splits the pane identified by
+ *      `$TMUX_PANE` so the watcher stays beside the invoking pane even if
+ *      the user has switched panes during startReviewSession.
+ *   3. Codex Desktop — only via ONTO_RUNTIME_WATCHER_CODEX_APP_LAUNCHER;
+ *      default UI keystroke automation is intentionally not used because
+ *      the app chat composer and terminal panel are not distinguishable by
+ *      a stable runtime-owned handle.
+ *   4. Warp — writes a launch configuration and opens the Warp launch URI.
+ *   5. Cursor — best-effort integrated-terminal UI automation.
+ *   6. iTerm2 on macOS (via $TERM_PROGRAM === 'iTerm.app') — targets the
+ *      session identified by `$ITERM_SESSION_ID`, which is inherited from
+ *      the invoking session at process start, so splits land beside the
+ *      pane that actually launched onto:review. If the env var is missing
+ *      or no matching session is found, the spawn is refused (returns
+ *      spawned: false) rather than falling back to the currently-focused
+ *      tab — a default target would land the watcher on whichever tab happens to
+ *      be frontmost at spawn time, which is the bug this path exists to
+ *      avoid.
+ *   7. Apple Terminal on macOS (via $TERM_PROGRAM === 'Apple_Terminal')
+ *      — best effort; Terminal.app lacks a stable session identifier, so
+ *      the spawn opens a new tab rather than a tab-targeted split.
+ *
+ * `sessionRoot` is required. It is passed through to the watcher script as
+ * an explicit argument, which bypasses the `.onto/review/.latest-session`
+ * pointer and therefore avoids the cross-session race that the global
+ * pointer would otherwise create under concurrent review invocations.
+ *
+ * Returns silently with `spawned: false` if no supported mechanism is found.
+ * The caller should print an explicit recovery hint in that case.
+ *
+ * This function never throws — it returns a result object instead, so the
+ * runtime continues even if the spawn fails.
+ */
+export function spawnWatcherPane(projectRoot, sessionRoot, ontoHome) {
+    // Resolution order for the watcher helper:
+    //   1. <projectRoot>/scripts/onto-review-watch.sh — co-located with the
+    //      review target (onto repo invocations, full-repo projects).
+    //   2. <ontoHome>/scripts/onto-review-watch.sh   — install-local script when
+    //      projectRoot is an isolated workspace and the watcher helper lives in
+    //      the repo home.
+    // Without the install-local script branch, any invocation with --project-root pointed at a
+    // non-repo location silently degrades to "watcher script not found"
+    // (observed 2026-04-22 self-review finding). The two-slot search keeps
+    // deterministic wrappers viable without forcing them to symlink or copy.
+    return spawnWatcherPaneForScript(projectRoot, sessionRoot, "onto-review-watch.sh", ontoHome);
+}
+export function spawnRuntimeWatcherPane(projectRoot, sessionRoot, ontoHome) {
+    return spawnWatcherPaneForScript(projectRoot, sessionRoot, "onto-runtime-watch.sh", ontoHome, "ONTO_RUNTIME_WATCHER");
+}

package/dist/core-runtime/cli/start-review-session.js

@@ -37,7 +37,7 @@ export async function startReviewSession(argv) {
     }
     await runMaterializeReviewPromptPacketsCli(promptPacketsArgs);
     // Write `.latest-session` pointer so the watcher script and other tools can
-    // auto-discover the current session without parsing buffered npm stdout.
+    // auto-discover the current session without parsing buffered adapter stdout.
     // This is a deterministic side-effect: a single line containing the absolute
     // session-root path. Best-effort — failure here must not block session start.
     try {
@@ -50,8 +50,8 @@ export async function startReviewSession(argv) {
     return {
         session_root: sessionRoot,
         bounded_start_steps: [
-            "review:prepare-session",
-            "review:materialize-prompt-packets",
+            "prepare_review_session",
+            "materialize_review_prompt_packets",
         ],
     };
 }

package/dist/core-runtime/llm/llm-caller.js

@@ -19,6 +19,7 @@ import path from "node:path";
 import os from "node:os";
 import { loadCoreLensRegistry } from "../discovery/lens-registry.js";
 import { DEFAULT_GROK_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, normalizeLlmModelSwitcher, } from "./model-switcher.js";
+import { appendRuntimeModelCallLogFromCurrentContext, appendRuntimeStreamChunkFromCurrentContextSync, } from "../observability/runtime-stream-observation.js";
 /**
  * Bridge: OntoConfig + CLI overrides → Partial<LlmCallConfig> that callLlm consumes.
  *
@@ -83,6 +84,7 @@ const DEFAULT_MAX_RETRIES = 1;
  */
 function emitModelCallLog(line) {
     process.stderr.write(`[model-call] ${line}\n`);
+    appendRuntimeModelCallLogFromCurrentContext(line);
 }
 function readCodexAuthState() {
     const codexAuthPath = path.join(os.homedir(), ".codex", "auth.json");
@@ -311,14 +313,23 @@ async function callCodexCli(systemPrompt, userPrompt, modelId, reasoningEffort,
     const child = spawn("codex", args, {
         stdio: ["pipe", "pipe", "pipe"],
     });
+    const codexStreamSourceBase = {
+        kind: "process",
+        label: "codex-cli",
+    };
+    const codexStreamSource = child.pid !== undefined
+        ? { ...codexStreamSourceBase, processId: child.pid }
+        : codexStreamSourceBase;
     let stdout = "";
     let stderr = "";
     let timedOut = false;
     child.stdout.on("data", (chunk) => {
         stdout += String(chunk);
+        appendRuntimeStreamChunkFromCurrentContextSync("stdout", chunk, codexStreamSource);
     });
     child.stderr.on("data", (chunk) => {
         stderr += String(chunk);
+        appendRuntimeStreamChunkFromCurrentContextSync("stderr", chunk, codexStreamSource);
     });
     child.stdin.write(combinedPrompt);
     child.stdin.end();

package/dist/core-runtime/llm/llm-tool-loop.js

@@ -50,6 +50,7 @@
  */
 import { BoundaryViolationError, findToolByName, } from "../cli/onto-tools.js";
 import { DEFAULT_GROK_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, } from "./model-switcher.js";
+import { appendRuntimeModelCallLogFromCurrentContext, } from "../observability/runtime-stream-observation.js";
 const MAX_ITERATIONS = 12;
 const MAX_TOKENS_PER_TURN = 4096;
 /**
@@ -61,6 +62,7 @@ const MAX_TOKENS_PER_TURN = 4096;
  */
 function emitModelCallLog(line) {
     process.stderr.write(`[model-call] ${line}\n`);
+    appendRuntimeModelCallLogFromCurrentContext(line);
 }
 /**
  * Run a tool-calling conversation until the model produces a final text

package/dist/core-runtime/observability/runtime-stream-observation.js

@@ -0,0 +1,118 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import fs from "node:fs";
+import path from "node:path";
+const runtimeObservationContext = new AsyncLocalStorage();
+export function runtimeStreamEventLogPath(sessionRoot) {
+    return path.join(path.resolve(sessionRoot), "runtime-events.ndjson");
+}
+export function runWithRuntimeObservationContext(context, fn) {
+    const normalized = {
+        pipeline: context.pipeline,
+        sessionRoot: path.resolve(context.sessionRoot),
+        ...(context.source ? { source: context.source } : {}),
+    };
+    return runtimeObservationContext.run(normalized, fn);
+}
+function buildSource(source) {
+    const result = {
+        kind: source?.kind ?? "runtime",
+        label: source?.label ?? source?.kind ?? "runtime",
+    };
+    if (source?.unitId)
+        result.unitId = source.unitId;
+    if (source?.stageId)
+        result.stageId = source.stageId;
+    if (source?.processId !== undefined)
+        result.processId = source.processId;
+    return result;
+}
+function buildRuntimeStreamEvent(input) {
+    const sessionRoot = path.resolve(input.sessionRoot);
+    return {
+        schema_version: 1,
+        event_kind: "runtime_stream",
+        timestamp: (input.timestamp ?? new Date()).toISOString(),
+        pipeline: input.pipeline,
+        session_id: path.basename(sessionRoot),
+        session_root: sessionRoot,
+        source: buildSource(input.source),
+        stream: input.stream,
+        message: input.message,
+    };
+}
+export function appendRuntimeStreamEventSync(input) {
+    try {
+        const sessionRoot = path.resolve(input.sessionRoot);
+        fs.mkdirSync(sessionRoot, { recursive: true });
+        const event = buildRuntimeStreamEvent({ ...input, sessionRoot });
+        fs.appendFileSync(runtimeStreamEventLogPath(sessionRoot), `${JSON.stringify(event)}\n`, "utf8");
+    }
+    catch {
+        // Observation is operational; it must never affect pipeline execution.
+    }
+}
+export function appendRuntimeStreamChunkSync(input, chunk) {
+    const text = String(chunk).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    for (const line of text.split("\n")) {
+        if (line.length === 0)
+            continue;
+        appendRuntimeStreamEventSync({
+            ...input,
+            message: line,
+        });
+    }
+}
+export function appendRuntimeStatusEventSync(args) {
+    appendRuntimeStreamEventSync({
+        pipeline: args.pipeline,
+        sessionRoot: args.sessionRoot,
+        source: {
+            kind: args.sourceKind ?? "runtime",
+            label: args.sourceLabel,
+            ...(args.stageId ? { stageId: args.stageId } : {}),
+        },
+        stream: "status",
+        message: args.message,
+    });
+}
+export function appendRuntimeModelCallLogFromCurrentContext(line) {
+    const context = runtimeObservationContext.getStore();
+    if (!context)
+        return;
+    appendRuntimeStreamEventSync({
+        pipeline: context.pipeline,
+        sessionRoot: context.sessionRoot,
+        source: {
+            kind: "llm",
+            label: context.source?.label ?? "model-call",
+            ...(context.source?.unitId ? { unitId: context.source.unitId } : {}),
+            ...(context.source?.stageId ? { stageId: context.source.stageId } : {}),
+        },
+        stream: "stderr",
+        message: `[model-call] ${line}`,
+    });
+}
+export function appendRuntimeStreamChunkFromCurrentContextSync(stream, chunk, source) {
+    const context = runtimeObservationContext.getStore();
+    if (!context)
+        return;
+    const mergedSource = {
+        kind: source?.kind ?? context.source?.kind ?? "runtime",
+        label: source?.label ?? context.source?.label ?? "runtime",
+    };
+    const unitId = source?.unitId ?? context.source?.unitId;
+    if (unitId)
+        mergedSource.unitId = unitId;
+    const stageId = source?.stageId ?? context.source?.stageId;
+    if (stageId)
+        mergedSource.stageId = stageId;
+    const processId = source?.processId ?? context.source?.processId;
+    if (processId !== undefined)
+        mergedSource.processId = processId;
+    appendRuntimeStreamChunkSync({
+        pipeline: context.pipeline,
+        sessionRoot: context.sessionRoot,
+        source: mergedSource,
+        stream,
+    }, chunk);
+}