muonroi-cli 1.8.4 → 1.9.0

package/LICENSE

@@ -1,9 +1,21 @@
-Copyright (c) 2026 muonroi. All rights reserved.
+MIT License
 
-Commercial / Proprietary License
+Copyright (c) 2026 muonroi
 
-This software and associated documentation files (the "Software") are proprietary to muonroi.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Unauthorized copying, modification, distribution, transmission, performance, display or other use of this Software, via any medium, is strictly prohibited.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/packages/agent-harness-core/src/driver.d.ts

@@ -1,5 +1,13 @@
 import { type Predicate } from "./predicate.js";
-import type { LiveEvent, LiveFrame, UINode } from "./protocol.js";
+import type { LiveEvent, LiveFrame, UINode, VisualFrame } from "./protocol.js";
+import { type VisualQualityReport } from "./visual-quality.js";
+/** A single decoded cell from the rendered grid (returned by `visual_cell`). */
+export type VisualCell = {
+    char: string;
+    fg: string;
+    bg: string;
+    attrs: number;
+};
 type WaitConditionIdle = {
     idle: true;
 };
@@ -31,6 +39,9 @@ type DriverDeps = {
 type Ingested = {
     kind: "frame";
     frame: LiveFrame;
+} | {
+    kind: "visual";
+    frame: VisualFrame;
 } | {
     kind: "idle";
 } | {
@@ -69,6 +80,21 @@ export type Driver = {
      */
     events: (filter?: EventFilter) => AsyncIterable<LiveEvent>;
     render_text: () => string;
+    /** Latest VisualFrame — the ACTUAL rendered cell grid (colors + attributes),
+     *  or null if the TUI has not emitted one (renderer not attached). */
+    snapshot_visual: () => VisualFrame | null;
+    /** Render the visual grid as plain text (what a human reads on screen) —
+     *  faithful to the rendered characters, unlike render_text (semantic tree). */
+    render_visual: () => string;
+    /** Decode the cell at (row, col) — char + fg/bg hex + attribute bits — from
+     *  the latest VisualFrame, accounting for wide (2-col) glyphs. Null if out of
+     *  range or no visual frame yet. */
+    visual_cell: (row: number, col: number) => VisualCell | null;
+    /** Programmatic visual-quality heuristics over the latest VisualFrame:
+     *  near-empty-row ratio, blank-row runs, whitespace density, and mojibake —
+     *  the exact "messy render" signals the semantic tree is blind to. Null if no
+     *  visual frame yet. */
+    visual_quality: () => VisualQualityReport | null;
     _ingest: (m: Ingested) => void;
     /** Called when the TUI exits. Cleanly terminates all active `events()` iterables. */
     _closeAllSubscribers: () => void;

package/dist/packages/agent-harness-core/src/driver.js

@@ -1,5 +1,6 @@
 import { evaluatePredicate, predicateSchema } from "./predicate.js";
 import { matchSelector } from "./selector.js";
+import { computeVisualQuality } from "./visual-quality.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -12,6 +13,7 @@ const PER_SUBSCRIBER_QUEUE_CAP = 256;
 // ---------------------------------------------------------------------------
 export function createDriver(deps) {
     let latestFrame = null;
+    let latestVisualFrame = null;
     let lastIdleAt = -1;
     const eventBuffer = [];
     const waiters = new Set();
@@ -276,10 +278,54 @@ export function createDriver(deps) {
                 return "(no frame)";
             return latestFrame.nodes.map((n) => renderNode(n, 0)).join("\n");
         },
+        snapshot_visual() {
+            return latestVisualFrame;
+        },
+        render_visual() {
+            if (!latestVisualFrame)
+                return "(no visual frame)";
+            return latestVisualFrame.lines
+                .map((ln) => ln.spans
+                .map((s) => s.text)
+                .join("")
+                .replace(/\s+$/, ""))
+                .join("\n");
+        },
+        visual_cell(row, col) {
+            const frame = latestVisualFrame;
+            if (!frame)
+                return null;
+            const line = frame.lines[row];
+            if (!line)
+                return null;
+            // Walk spans accumulating display columns; a wide glyph spans 2 columns
+            // but its span.width already reflects that, so index within the run by
+            // string position while tracking the column cursor.
+            let colCursor = 0;
+            for (const span of line.spans) {
+                const chars = [...span.text];
+                for (const ch of chars) {
+                    // A char occupies span.width / chars.length columns on average; for
+                    // the common width===text-length case this is 1. Round to stay integral.
+                    const chCols = Math.max(1, Math.round(span.width / Math.max(1, chars.length)));
+                    if (col >= colCursor && col < colCursor + chCols) {
+                        return { char: ch, fg: span.fg, bg: span.bg, attrs: span.attrs };
+                    }
+                    colCursor += chCols;
+                }
+            }
+            return null;
+        },
+        visual_quality() {
+            return latestVisualFrame ? computeVisualQuality(latestVisualFrame) : null;
+        },
         _ingest(m) {
             if (m.kind === "frame") {
                 latestFrame = m.frame;
             }
+            else if (m.kind === "visual") {
+                latestVisualFrame = m.frame;
+            }
             else if (m.kind === "idle") {
                 lastIdleAt = Date.now();
             }

package/dist/packages/agent-harness-core/src/event-filter.js

@@ -28,9 +28,20 @@ export const LIFECYCLE_PRESET = new Set([
     "askcard-cancel",
     "sprint-stage",
     "sprint-halt",
+    // Emitted at product-loop/index.ts on plan commit; a wake-at-milestone monitor
+    // must see it. Was previously dropped by this preset despite being emitted.
+    "sprint-plan-committed",
     "route-decision",
     "steer-inject",
     "usage",
+    // Ephemeral kinds carry a visualText snapshot for wake-at-milestone monitors
+    // (event-tee.ts EPHEMERAL_KINDS). The default preset must not drop them, or a
+    // monitor on MUONROI_HARNESS_EVENT_LOG misses errors/timeouts/disconnects.
+    "ee-timeout",
+    "ee-error",
+    "grounding-flag",
+    "stream-retry",
+    "disconnect",
 ]);
 /**
  * Returns a predicate that returns true when an event kind is allowed to emit.

package/dist/packages/agent-harness-core/src/event-redact.js

@@ -53,6 +53,13 @@ const ALLOWED_FIELDS = {
         status: "pass",
         round: "pass",
         correlationId: "pass",
+        // Liveness counters. Plain magnitudes (like elapsedMs / charCount above) —
+        // no prompt or response content — and without them a harness consumer
+        // cannot tell a slow reasoning call from a hung one, because `elapsedMs`
+        // alone freezes whenever the tick generator stops being pulled.
+        streamedChars: "pass",
+        lastDeltaAgeMs: "pass",
+        elapsedMs: "pass",
     },
     "council-turn-length": {
         role: "pass",

package/dist/packages/agent-harness-core/src/event-tee.d.ts

@@ -0,0 +1,64 @@
+/**
+ * event-tee.ts — optional JSONL sink for harness LiveEvents.
+ *
+ * Why: the MCP wake mechanism that re-invokes an external agent is a background
+ * task (e.g. a milestone watcher), which is a SEPARATE process from the MCP
+ * server. That watcher can only read files — it cannot reach the in-process
+ * driver that holds the real UI. So a generic, reusable milestone watcher needs
+ * the harness to persist events to a file it can tail.
+ *
+ * The DB only records debate-END rows (synthesis/debate_complete), so a
+ * DB-poll watcher is blind to mid-flight modal pauses (askcard-open) that never
+ * write a DB row. Teeing every LiveEvent to a JSONL file closes that gap for
+ * ANY event kind.
+ *
+ * Ephemeral events (toast, disconnect, retry, ee-*) flash and vanish before an
+ * agent can wake + render, so for those kinds — and ONLY those — we attach a
+ * plain-text visual snapshot captured at emit time, so the watcher's wake
+ * payload carries the exact frame. Persistent states (askcard, post-debate
+ * card) stay put, so the agent renders them fresh on demand; embedding a stale
+ * snapshot for those would be worse, not better.
+ *
+ * ON BY DEFAULT (see {@link resolveEventLogPath}): an opt-in sink is one nobody
+ * remembers to opt into, and the cost of the log missing is an agent that
+ * cannot tell "waiting for a human" from "hung" — the exact confusion this file
+ * exists to prevent. Set MUONROI_HARNESS_EVENT_LOG=0 (or "off"/"false") to
+ * disable, or to a path to choose your own.
+ */
+import type { LiveEvent } from "./protocol.js";
+/**
+ * Event kinds that flash and disappear before an agent can wake + render.
+ * Only these carry an at-emit visual snapshot in the teed line.
+ */
+export declare const EPHEMERAL_KINDS: ReadonlySet<string>;
+/** One teed JSONL record. */
+export interface TeedEventLine {
+    ts: number;
+    kind: string;
+    event: LiveEvent;
+    /** Present only for EPHEMERAL_KINDS — plain-text visual frame at emit time. */
+    visualText?: string;
+}
+/**
+ * Resolve where events are teed, from the MUONROI_HARNESS_EVENT_LOG value.
+ *
+ * - unset/blank → a per-pid file in the OS temp dir (the default-on path)
+ * - "0" / "off" / "false" / "no" → null, sink disabled
+ * - anything else → that literal path
+ *
+ * Per-pid keeps concurrent harness servers from interleaving into one file, and
+ * puts the log where the OS already reclaims it — no rotation to maintain.
+ *
+ * @param pid - process id (injectable for tests).
+ */
+export declare function resolveEventLogPath(envValue?: string, pid?: number): string | null;
+/**
+ * Build an event-tee sink. Returns null only when the sink is explicitly
+ * disabled — see {@link resolveEventLogPath}.
+ *
+ * @param getVisualText - lazily renders the current visual frame to plain text
+ *   (driver.render_visual). Called ONLY for ephemeral kinds, so persistent
+ *   events pay nothing.
+ * @param envValue - value of MUONROI_HARNESS_EVENT_LOG (injectable for tests).
+ */
+export declare function createEventTee(getVisualText: () => string | null, envValue?: string): ((event: LiveEvent) => void) | null;

package/dist/packages/agent-harness-core/src/event-tee.js

@@ -0,0 +1,104 @@
+/**
+ * event-tee.ts — optional JSONL sink for harness LiveEvents.
+ *
+ * Why: the MCP wake mechanism that re-invokes an external agent is a background
+ * task (e.g. a milestone watcher), which is a SEPARATE process from the MCP
+ * server. That watcher can only read files — it cannot reach the in-process
+ * driver that holds the real UI. So a generic, reusable milestone watcher needs
+ * the harness to persist events to a file it can tail.
+ *
+ * The DB only records debate-END rows (synthesis/debate_complete), so a
+ * DB-poll watcher is blind to mid-flight modal pauses (askcard-open) that never
+ * write a DB row. Teeing every LiveEvent to a JSONL file closes that gap for
+ * ANY event kind.
+ *
+ * Ephemeral events (toast, disconnect, retry, ee-*) flash and vanish before an
+ * agent can wake + render, so for those kinds — and ONLY those — we attach a
+ * plain-text visual snapshot captured at emit time, so the watcher's wake
+ * payload carries the exact frame. Persistent states (askcard, post-debate
+ * card) stay put, so the agent renders them fresh on demand; embedding a stale
+ * snapshot for those would be worse, not better.
+ *
+ * ON BY DEFAULT (see {@link resolveEventLogPath}): an opt-in sink is one nobody
+ * remembers to opt into, and the cost of the log missing is an agent that
+ * cannot tell "waiting for a human" from "hung" — the exact confusion this file
+ * exists to prevent. Set MUONROI_HARNESS_EVENT_LOG=0 (or "off"/"false") to
+ * disable, or to a path to choose your own.
+ */
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Event kinds that flash and disappear before an agent can wake + render.
+ * Only these carry an at-emit visual snapshot in the teed line.
+ */
+export const EPHEMERAL_KINDS = new Set([
+    "toast",
+    "disconnect",
+    "stream-retry",
+    "ee-timeout",
+    "ee-error",
+    "grounding-flag",
+]);
+/** Values that turn the sink off. Anything else is treated as a path. */
+const DISABLE_VALUES = new Set(["0", "off", "false", "no"]);
+/**
+ * Resolve where events are teed, from the MUONROI_HARNESS_EVENT_LOG value.
+ *
+ * - unset/blank → a per-pid file in the OS temp dir (the default-on path)
+ * - "0" / "off" / "false" / "no" → null, sink disabled
+ * - anything else → that literal path
+ *
+ * Per-pid keeps concurrent harness servers from interleaving into one file, and
+ * puts the log where the OS already reclaims it — no rotation to maintain.
+ *
+ * @param pid - process id (injectable for tests).
+ */
+export function resolveEventLogPath(envValue, pid = process.pid) {
+    const raw = (envValue ?? "").trim();
+    if (DISABLE_VALUES.has(raw.toLowerCase()))
+        return null;
+    if (raw)
+        return raw;
+    return join(tmpdir(), `muonroi-harness-events-${pid}.jsonl`);
+}
+/**
+ * Build an event-tee sink. Returns null only when the sink is explicitly
+ * disabled — see {@link resolveEventLogPath}.
+ *
+ * @param getVisualText - lazily renders the current visual frame to plain text
+ *   (driver.render_visual). Called ONLY for ephemeral kinds, so persistent
+ *   events pay nothing.
+ * @param envValue - value of MUONROI_HARNESS_EVENT_LOG (injectable for tests).
+ */
+export function createEventTee(getVisualText, envValue) {
+    const path = resolveEventLogPath(envValue);
+    if (!path)
+        return null;
+    return (event) => {
+        // The idle sentinel arrives as { t: "idle" } — never here. Guard anyway so
+        // a malformed event can't crash the ingest loop.
+        const kind = event.kind;
+        if (typeof kind !== "string")
+            return;
+        const line = { ts: Date.now(), kind, event };
+        if (EPHEMERAL_KINDS.has(kind)) {
+            try {
+                const visual = getVisualText();
+                if (visual)
+                    line.visualText = visual;
+            }
+            catch (err) {
+                // A visual-render failure must not drop the event record itself.
+                console.error(`[event-tee] visual snapshot failed for kind=${kind}: ${err?.message}`);
+            }
+        }
+        try {
+            appendFileSync(path, `${JSON.stringify(line)}\n`);
+        }
+        catch (err) {
+            console.error(`[event-tee] append failed (path=${path}, kind=${kind}): ${err?.message}`);
+        }
+    };
+}
+//# sourceMappingURL=event-tee.js.map

package/dist/packages/agent-harness-core/src/mcp-server.d.ts

@@ -13,6 +13,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Driver } from "./driver.js";
+import type { LiveEvent } from "./protocol.js";
 /**
  * The result returned by a HarnessSpawn implementation.
  * Both the POSIX fd-3/4 and Windows named-pipe transports satisfy this shape.
@@ -46,6 +47,18 @@ export declare function validateStartArgs(args: string[]): {
     bad: string;
 };
 export declare function sanitizeEnv(env: Record<string, string>): Record<string, string>;
+/**
+ * Build the child TUI's environment for tui.start.
+ *
+ * Starts from the driver's own env so PATH/HOME survive, overlays the
+ * caller-supplied keys, THEN strips the dangerous ones. The merge-before-strip
+ * order keeps the security posture (NODE_OPTIONS/LD_PRELOAD/… still removed)
+ * while guaranteeing PATH is present: bun drops the fd 3/4 stdio channels when a
+ * child is spawned with a partial env that lacks PATH, which yields a null
+ * inWrite and crashes the whole driver on spawn. `base` defaults to process.env
+ * and is injectable for tests.
+ */
+export declare function buildChildEnv(callerEnv?: Record<string, string>, base?: Record<string, string | undefined>): Record<string, string>;
 /**
  * Opt-in extra cwd roots for tui.start, layered ON TOP of the default
  * {home, repo-root} allowlist. The posture stays deny-by-default: only roots an
@@ -72,6 +85,8 @@ export declare function validateMockLlmPath(value: string): boolean;
 export declare function buildCapabilitiesPayload(): {
     protocol: string;
     features: readonly string[];
+    /** Where LiveEvents are teed as JSONL, or null when the sink is disabled. */
+    eventLogPath: string | null;
 };
 export declare function registerReadTools(server: McpServer, getDriver: () => Driver | null): void;
 export declare function registerActionTools(server: McpServer, getDriver: () => Driver | null): void;
@@ -95,6 +110,16 @@ export declare function registerAsyncTools(server: McpServer, getDriver: () => D
 export declare function createMcpHarnessServer({ spawn }: {
     spawn: HarnessSpawn;
 }): McpServer;
+/**
+ * Build the onLine sidechannel handler: parse each JSON line, ingest frames /
+ * visuals / idle / events into the driver, and tee events to the optional JSONL
+ * sink. Extracted (and exported) so the frame/event/tee wiring is unit-testable
+ * without a live TUI or an MCP protocol handshake.
+ *
+ * @param driver   the driver to ingest into (only _ingest is used).
+ * @param eventTee optional sink from createEventTee (null → no tee).
+ */
+export declare function makeLineHandler(driver: Pick<Driver, "_ingest">, eventTee: ((event: LiveEvent) => void) | null): (line: string) => void;
 /**
  * Run the MCP harness driver over stdio with the OpenTUI spawn implementation
  * injected by the consumer.