muonroi-cli 1.2.3 → 1.3.1

package/dist/packages/agent-harness-core/src/transports/ws.js

@@ -0,0 +1,222 @@
+/**
+ * WebSocket transport for @muonroi/agent-harness-core.
+ *
+ * Browser-safe: uses only globalThis.WebSocket (or an injected WebSocketImpl).
+ * No node:* imports — safe for both the Node bundle and the browser bundle.
+ *
+ * Token authentication is enforced at the URL level: the caller MUST supply a
+ * `token` string which is appended as `?token=<token>` to the connection URL.
+ * The server is responsible for rejecting connections with an absent/wrong token;
+ * this transport merely ensures the token is always present in the URL.
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Zod schema — copied from docs/agent-harness/ws-envelope.zod.ts (Task 0.4)
+// and refined to match protocol.ts field names exactly.
+// ---------------------------------------------------------------------------
+/**
+ * Recursive UINode schema.
+ * Kept loose on `role` (z.string()) because the canonical Role union lives in
+ * protocol.ts and duplicating it here would create drift risk.
+ */
+const UINodeSchema = z.lazy(() => z.object({
+    id: z.string(),
+    role: z.string(),
+    name: z.string().optional(),
+    value: z.string().optional(),
+    focus: z.literal(true).optional(),
+    selected: z.literal(true).optional(),
+    disabled: z.literal(true).optional(),
+    hidden: z.literal(true).optional(),
+    state: z.string().optional(),
+    props: z.record(z.string(), z.unknown()).optional(),
+    children: z.array(z.lazy(() => UINodeSchema)).optional(),
+}));
+/** dir: "frame" — server → client. Mirrors LiveFrame in protocol.ts exactly. */
+const FrameEnvelopeSchema = z.object({
+    dir: z.literal("frame"),
+    mode: z.literal("live"),
+    // NOTE: field name is `version`, NOT `protocolVersion` — see TRANSPORTS.md Editor Note.
+    version: z.literal("0.4.0"),
+    seq: z.number().int().nonnegative(),
+    ts: z.number().int().nonnegative(),
+    focus: z.string().optional(),
+    modals: z.array(z.string()).optional(),
+    nodes: z.array(UINodeSchema),
+});
+/** dir: "event" — server → client. Inner `t` discriminant preserved from LiveEvent. */
+const EventEnvelopeSchema = z.object({
+    dir: z.literal("event"),
+    t: z.union([z.literal("event"), z.literal("idle")]),
+    kind: z.string().optional(),
+    level: z.enum(["info", "warn", "error"]).optional(),
+    text: z.string().optional(),
+    target: z.string().optional(),
+    ttlMs: z.number().optional(),
+});
+/** dir: "cmd" — client → server. Carries harness commands. */
+const CommandEnvelopeSchema = z.object({
+    dir: z.literal("cmd"),
+    op: z.enum(["press", "type", "focus"]),
+    key: z.string().optional(),
+    text: z.string().optional(),
+    id: z.string().optional(),
+});
+export const WsEnvelopeSchema = z.discriminatedUnion("dir", [
+    FrameEnvelopeSchema,
+    EventEnvelopeSchema,
+    CommandEnvelopeSchema,
+]);
+// Also export UINodeSchema for consumers that need to validate subtrees
+export { UINodeSchema };
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Creates a WebSocket-based transport that validates every inbound message
+ * against the WsEnvelope discriminated union schema.
+ *
+ * Token enforcement design:
+ *   - Token is required at construction time; missing/empty → throws synchronously.
+ *   - Token is appended as `?token=<value>` (or `&token=<value>` if the URL
+ *     already has a query string). This matches the server-side expectation
+ *     documented in TRANSPORTS.md § Security Requirements.
+ *   - Server-side rejection (WS close 4001) bubbles as an onError event when
+ *     the socket fires its `close` event with code 4001.
+ */
+export function createWebSocketTransport(opts) {
+    const { url, token, WebSocketImpl } = opts;
+    // --- Token validation ---
+    if (!token || token.trim() === "") {
+        throw new Error("createWebSocketTransport: `token` is required and must be non-empty. " +
+            "The server enforces token authentication; omitting it will cause connection rejection.");
+    }
+    // --- Build authenticated URL ---
+    // Append ?token= (or &token= if a query string already exists) without
+    // modifying any existing query parameters.
+    const separator = url.includes("?") ? "&" : "?";
+    const authenticatedUrl = `${url}${separator}token=${encodeURIComponent(token)}`;
+    // --- Resolve WebSocket constructor ---
+    const WS = WebSocketImpl ?? (typeof globalThis !== "undefined" ? globalThis.WebSocket : undefined);
+    if (typeof WS !== "function") {
+        throw new Error("createWebSocketTransport: No WebSocket implementation available. " +
+            "Pass `WebSocketImpl` from the `ws` package (devDependency) in test/Node environments, " +
+            "or run in a browser / Node 22+ environment where globalThis.WebSocket exists.");
+    }
+    // --- Callback registries ---
+    const messageCallbacks = new Set();
+    const errorCallbacks = new Set();
+    function dispatchError(err, raw) {
+        if (errorCallbacks.size === 0)
+            return; // no-op if nobody is listening
+        for (const cb of errorCallbacks) {
+            try {
+                cb(err, raw);
+            }
+            catch {
+                // Swallow errors thrown inside error callbacks to avoid infinite loops.
+            }
+        }
+    }
+    // --- Open socket ---
+    const socket = new WS(authenticatedUrl);
+    // Attach an error listener immediately to prevent unhandled-error crashes.
+    // The `ws` npm package emits an "error" event for connection failures (including
+    // close-while-connecting), which Node.js turns into an uncaught exception when
+    // no listener is registered. We forward to onError callbacks if any exist,
+    // otherwise swallow (the socket will close naturally).
+    //
+    // Note: `ErrorEvent` is a browser/DOM global that does NOT exist in Node.js.
+    // The `ws` package passes a plain `{ error, message }` shaped object to the
+    // "error" event listener via the EventTarget API. We extract the error safely
+    // without referencing the browser-only `ErrorEvent` constructor.
+    socket.addEventListener("error", (event) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const raw = event;
+        let err;
+        if (raw?.error instanceof Error) {
+            err = raw.error;
+        }
+        else if (typeof raw?.message === "string") {
+            err = new Error(raw.message);
+        }
+        else {
+            err = new Error("WebSocket error");
+        }
+        dispatchError(err);
+    });
+    socket.addEventListener("message", (event) => {
+        const raw = typeof event.data === "string" ? event.data : String(event.data);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            dispatchError(new Error(`WS message is not valid JSON: ${String(e)}`), raw);
+            return;
+        }
+        const result = WsEnvelopeSchema.safeParse(parsed);
+        if (!result.success) {
+            dispatchError(new Error(`WS envelope validation failed: ${result.error.message}`), raw);
+            return;
+        }
+        for (const cb of messageCallbacks) {
+            try {
+                cb(result.data);
+            }
+            catch {
+                // Swallow to avoid one bad callback killing the rest.
+            }
+        }
+    });
+    socket.addEventListener("close", (event) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const closeCode = event.code;
+        if (closeCode === 4001) {
+            dispatchError(new Error(`WS connection rejected by server: token authentication failed (close code 4001)`));
+        }
+    });
+    // --- Public transport object ---
+    const transport = {
+        get readyState() {
+            return socket.readyState;
+        },
+        send(line) {
+            if (socket.readyState !== 1 /* OPEN */) {
+                dispatchError(new Error(`WS send failed: socket is not OPEN (readyState=${socket.readyState}). ` +
+                    "Wait for the connection to be established before sending."));
+                return;
+            }
+            socket.send(line);
+        },
+        onMessage(cb) {
+            messageCallbacks.add(cb);
+            return () => {
+                messageCallbacks.delete(cb);
+            };
+        },
+        onError(cb) {
+            errorCallbacks.add(cb);
+            return () => {
+                errorCallbacks.delete(cb);
+            };
+        },
+        close() {
+            messageCallbacks.clear();
+            errorCallbacks.clear();
+            // The `ws` npm package (used in test environments via WebSocketImpl) throws
+            // "WebSocket was closed before the connection was established" when close()
+            // is called while the socket is still in CONNECTING state (readyState 0).
+            // The browser spec allows this call — it just transitions the socket to CLOSING.
+            // Swallow the error so callers don't have to guard against the quirk.
+            try {
+                socket.close();
+            }
+            catch {
+                // Ignore close-while-connecting errors (ws package quirk).
+            }
+        },
+    };
+    return transport;
+}
+//# sourceMappingURL=ws.js.map

package/dist/packages/agent-harness-core/src/transports/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../../../../packages/agent-harness-core/src/transports/ws.ts"],"names":[],"mappings":"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"}

package/dist/packages/agent-harness-opentui/src/agent-mode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * agent-mode.ts — Runtime that the --agent-mode CLI flag activates.
+ *
+ * Transport (POSIX):
+ *   fd 3 (out, JSONL writes) and fd 4 (in, JSONL reads), opened via
+ *   createWriteStream/createReadStream. Parent must spawn with a 5-element
+ *   stdio array using node:child_process.spawn.
+ *
+ * Transport (Windows):
+ *   If env vars MUONROI_HARNESS_OUT_PIPE and MUONROI_HARNESS_IN_PIPE are set,
+ *   the child connects to those named pipes instead of using fd 3/4. The child
+ *   sends a { t: "handshake", ok: true } JSONL line on the out pipe once
+ *   connected, so the parent can synchronize before sending commands.
+ *
+ * For tests, pass opts.injectStreams to inject in-memory PassThrough streams
+ * instead of opening real fds — this avoids touching process state in tests.
+ */
+import type { LiveEvent } from "@muonroi/agent-harness-core/protocol";
+import type { SemanticRegistry } from "./reconciler-hook.js";
+export type AgentModeOptions = {
+    cols: number;
+    rows: number;
+    idleMs: number;
+    fakeClock?: boolean;
+    /** For tests: inject in-memory streams instead of fds 3/4. */
+    injectStreams?: {
+        out: NodeJS.WritableStream;
+        in: NodeJS.ReadableStream;
+    };
+    /** For tests: inject a writer for handshake instead of process.stdout. */
+    handshakeOut?: NodeJS.WritableStream;
+};
+export type AgentModeRuntime = {
+    registry: SemanticRegistry;
+    /** Build and emit a frame if content changed (dedup handled by reconciler hook). */
+    capture: () => void;
+    /** Emit an event (stream.delta, toast, idle). */
+    emitEvent: (e: LiveEvent) => void;
+    /** Register a handler for incoming commands from the host. */
+    onCommand: (h: (cmd: unknown) => void) => void;
+    /** Get the current timestamp (real or fake clock). */
+    now: () => number;
+    /** Tear down: close streams, dispose idle detector. */
+    dispose: () => void;
+};
+export declare function startAgentMode(opts: AgentModeOptions): Promise<AgentModeRuntime>;

package/dist/packages/agent-harness-opentui/src/agent-mode.js

@@ -0,0 +1,178 @@
+/**
+ * agent-mode.ts — Runtime that the --agent-mode CLI flag activates.
+ *
+ * Transport (POSIX):
+ *   fd 3 (out, JSONL writes) and fd 4 (in, JSONL reads), opened via
+ *   createWriteStream/createReadStream. Parent must spawn with a 5-element
+ *   stdio array using node:child_process.spawn.
+ *
+ * Transport (Windows):
+ *   If env vars MUONROI_HARNESS_OUT_PIPE and MUONROI_HARNESS_IN_PIPE are set,
+ *   the child connects to those named pipes instead of using fd 3/4. The child
+ *   sends a { t: "handshake", ok: true } JSONL line on the out pipe once
+ *   connected, so the parent can synchronize before sending commands.
+ *
+ * For tests, pass opts.injectStreams to inject in-memory PassThrough streams
+ * instead of opening real fds — this avoids touching process state in tests.
+ */
+import { createReadStream, createWriteStream } from "node:fs";
+import { createEventFilter } from "@muonroi/agent-harness-core/event-filter";
+import { createIdleDetector } from "@muonroi/agent-harness-core/idle";
+import { redactEvent } from "@muonroi/agent-harness-core/event-redact";
+import { createLineSplitter, createSidechannelWriter } from "@muonroi/agent-harness-core/transports/sidechannel";
+import { installOpenTUIHarness } from "./install.js";
+import { createSemanticRegistry } from "./reconciler-hook.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export async function startAgentMode(opts) {
+    const testing = opts.injectStreams !== undefined;
+    // --- Transport -----------------------------------------------------------
+    let outStream;
+    let inStream;
+    if (testing) {
+        // Tests inject PassThrough streams; skip fd opening and terminal resizing.
+        outStream = opts.injectStreams.out;
+        inStream = opts.injectStreams.in;
+    }
+    else if (process.platform === "win32" &&
+        process.env["MUONROI_HARNESS_OUT_PIPE"] &&
+        process.env["MUONROI_HARNESS_IN_PIPE"]) {
+        // Windows: connect to named pipes provided by the parent (test-spawn.ts).
+        // The parent creates both pipe servers before spawning this child, so both
+        // pipes are ready when we arrive here. On connect, emit a handshake line on
+        // the out pipe so the parent knows the transport is ready.
+        const { createConnection } = await import("node:net");
+        const outPipeName = process.env["MUONROI_HARNESS_OUT_PIPE"];
+        const inPipeName = process.env["MUONROI_HARNESS_IN_PIPE"];
+        const outSock = createConnection(outPipeName);
+        const inSock = createConnection(inPipeName);
+        // Wait for both sockets to establish their connection before proceeding.
+        // If either fails, log to stderr and exit — the parent will time out and
+        // surface a clear error.
+        await new Promise((resolve, reject) => {
+            let connected = 0;
+            const onConnect = () => {
+                if (++connected === 2)
+                    resolve();
+            };
+            outSock.once("connect", onConnect);
+            inSock.once("connect", onConnect);
+            outSock.once("error", reject);
+            inSock.once("error", reject);
+        }).catch((err) => {
+            process.stderr.write(`[agent-mode] named-pipe connect error: ${String(err)}\n`);
+            process.exit(1);
+        });
+        // Emit handshake so parent's waitForHandshake() can unblock.
+        outSock.write(JSON.stringify({ t: "handshake", ok: true }) + "\n");
+        outStream = outSock;
+        inStream = inSock;
+        // Apply determinism: force terminal dimensions so layout is reproducible.
+        process.stdout.columns = opts.cols;
+        process.stdout.rows = opts.rows;
+    }
+    else {
+        // POSIX (Linux/macOS): open fds 3 (write) and 4 (read). The parent is
+        // responsible for spawning with a 5-element stdio array via
+        // node:child_process.spawn (Bun's spawn does not forward extra fds on
+        // Windows — confirmed by spike-0c).
+        outStream = createWriteStream("", { fd: 3 });
+        inStream = createReadStream("", { fd: 4 });
+        // Apply determinism: force terminal dimensions so layout is reproducible.
+        process.stdout.columns = opts.cols;
+        process.stdout.rows = opts.rows;
+    }
+    // --- Clock ---------------------------------------------------------------
+    // now() is exposed on AgentModeRuntime so callers can get a consistent
+    // timestamp.  fakeClock returns 0 (a stable sentinel for tests) because the
+    // seq counter is now owned by installOpenTUIHarness internally.
+    const now = () => (opts.fakeClock ? 0 : Date.now());
+    // --- Semantic registry ---------------------------------------------------
+    const registry = createSemanticRegistry();
+    // --- Idle detector -------------------------------------------------------
+    const idle = createIdleDetector({
+        quiescenceMs: opts.idleMs,
+        onIdle: () => {
+            const line = createSidechannelWriter.serialize({ t: "idle" });
+            outStream.write(line);
+        },
+    });
+    // --- Harness install ------------------------------------------------------
+    // Wire registry → outStream via installOpenTUIHarness.  The transport wraps
+    // the raw outStream; close() is handled by uninstall() in dispose().
+    // onFrame threads idle.markActivity() so the idle detector resets after each
+    // emitted frame (prevents spurious idle events mid-render-burst).
+    const transport = {
+        send: (line) => outStream.write(line),
+        close: () => outStream.end(),
+    };
+    const harnessHandle = installOpenTUIHarness({
+        registry,
+        transport,
+        fps: 60,
+        onFrame: () => idle.markActivity(),
+        // Pass --agent-fake-clock through to the snapshot hook so LiveFrame.ts
+        // becomes deterministic (seq*16). Without this, ts = Date.now() and the
+        // determinism spec sees timestamps differ between runs.
+        fakeClock: opts.fakeClock,
+    });
+    // --- Command channel (in stream → handlers) ------------------------------
+    const commandHandlers = [];
+    const splitter = createLineSplitter((line) => {
+        try {
+            const cmd = JSON.parse(line);
+            // Any incoming command is "activity" — reset the idle quiescence timer
+            // so the next idle event fires after the system settles post-dispatch.
+            // Without this, wait_for({idle: true}) after press/type can never
+            // resolve because no frame write happens to mark activity (e.g., when
+            // the input changes textarea state but no Semantic field is mirrored).
+            idle.markActivity();
+            for (const h of commandHandlers)
+                h(cmd);
+        }
+        catch {
+            // Malformed JSONL from host — ignore silently.
+        }
+    });
+    inStream.on("data", (chunk) => {
+        splitter(chunk);
+    });
+    // --- Volume filter -------------------------------------------------------
+    // Reads MUONROI_HARNESS_EVENTS once at startup; default drops "llm-token".
+    const isKindAllowed = createEventFilter(process.env["MUONROI_HARNESS_EVENTS"]);
+    // --- Public API ----------------------------------------------------------
+    // capture() is called from app.tsx's addPostProcessFn after each renderer
+    // pass — it forces an immediate snapshot via captureNow() rather than waiting
+    // for the next poll interval tick.
+    const capture = () => {
+        harnessHandle.captureNow();
+    };
+    const emitEvent = (e) => {
+        // t:"idle" is the idle sentinel — not a LiveEvent with kind; bypass filter.
+        if (e.t === "event") {
+            if (!isKindAllowed(e.kind))
+                return; // filtered out — no-op
+        }
+        // Redact payload before writing to the wire.
+        const safe = e.t === "event" ? redactEvent(e) : e;
+        outStream.write(createSidechannelWriter.serialize(safe));
+        // stream.delta events mark activity (text is flowing — not yet idle).
+        if (e.t === "event" && e.kind === "stream.delta") {
+            idle.markActivity();
+        }
+    };
+    const onCommand = (h) => {
+        commandHandlers.push(h);
+    };
+    const dispose = () => {
+        harnessHandle.uninstall(); // stops poll interval; transport.close() ends outStream
+        idle.dispose();
+        // in stream is read-only — destroy if possible.
+        if (typeof inStream.destroy === "function") {
+            inStream.destroy();
+        }
+    };
+    return { registry, capture, emitEvent, onCommand, now, dispose };
+}
+//# sourceMappingURL=agent-mode.js.map

package/dist/packages/agent-harness-opentui/src/agent-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mode.js","sourceRoot":"","sources":["../../../../packages/agent-harness-opentui/src/agent-mode.ts"],"names":[],"mappings":"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"}

package/dist/packages/agent-harness-opentui/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./agent-mode.js";
+export * from "./input-bridge.js";
+export * from "./install.js";
+export * from "./reconciler-hook.js";
+export * from "./semantic.js";

package/dist/packages/agent-harness-opentui/src/index.js

@@ -0,0 +1,6 @@
+export * from "./agent-mode.js";
+export * from "./input-bridge.js";
+export * from "./install.js";
+export * from "./reconciler-hook.js";
+export * from "./semantic.js";
+//# sourceMappingURL=index.js.map

package/dist/packages/agent-harness-opentui/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/agent-harness-opentui/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC"}

package/dist/packages/agent-harness-opentui/src/input-bridge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Input bridge: consume JSONL commands from fd4 (via agentRuntime.onCommand)
+ * and inject them as synthetic key events into OpenTUI's keyHandler.
+ *
+ * Without this bridge the harness can OBSERVE the TUI (fd3 frames) but not
+ * DRIVE it — type/press operations sent by the driver are silently dropped.
+ *
+ * Key naming map: the harness uses friendly names ("Enter", "Down") to keep
+ * the protocol agent-agnostic. We translate to ParsedKey objects with the
+ * matching `name` field that OpenTUI's textarea/select components expect.
+ *
+ * For single-character input, the parser would normally emit one keypress per
+ * raw byte. We construct ParsedKey directly so we don't depend on terminal
+ * escape sequence conventions.
+ */
+import type { AgentModeRuntime } from "./agent-mode.js";
+/**
+ * Subscribe to agentRuntime.onCommand and inject synthetic key events into
+ * OpenTUI's keyHandler. Safe no-op when agentRuntime is undefined (normal user
+ * mode).
+ *
+ * Special key `__focus__:<id>` is intentionally NOT translated to OpenTUI input
+ * here — it is a driver-level signal currently ignored at this layer. (Focus
+ * routing in OpenTUI is owned by individual components; a global focus dispatch
+ * is out of scope for this bridge.)
+ */
+export declare function useAgentInputBridge(agentRuntime: AgentModeRuntime | undefined): void;

package/dist/packages/agent-harness-opentui/src/input-bridge.js

@@ -0,0 +1,126 @@
+/**
+ * Input bridge: consume JSONL commands from fd4 (via agentRuntime.onCommand)
+ * and inject them as synthetic key events into OpenTUI's keyHandler.
+ *
+ * Without this bridge the harness can OBSERVE the TUI (fd3 frames) but not
+ * DRIVE it — type/press operations sent by the driver are silently dropped.
+ *
+ * Key naming map: the harness uses friendly names ("Enter", "Down") to keep
+ * the protocol agent-agnostic. We translate to ParsedKey objects with the
+ * matching `name` field that OpenTUI's textarea/select components expect.
+ *
+ * For single-character input, the parser would normally emit one keypress per
+ * raw byte. We construct ParsedKey directly so we don't depend on terminal
+ * escape sequence conventions.
+ */
+import { useAppContext } from "@opentui/react";
+import { useEffect } from "react";
+// Mapping from harness key names to (partial) ParsedKey fields.
+// Names follow the `name` field OpenTUI emits for raw-mode keypress parsing.
+const NAMED = {
+    Enter: { name: "return", sequence: "\r", raw: "\r" },
+    Return: { name: "return", sequence: "\r", raw: "\r" },
+    Escape: { name: "escape", sequence: "\x1b", raw: "\x1b" },
+    Esc: { name: "escape", sequence: "\x1b", raw: "\x1b" },
+    Up: { name: "up", sequence: "\x1b[A", raw: "\x1b[A" },
+    Down: { name: "down", sequence: "\x1b[B", raw: "\x1b[B" },
+    Right: { name: "right", sequence: "\x1b[C", raw: "\x1b[C" },
+    Left: { name: "left", sequence: "\x1b[D", raw: "\x1b[D" },
+    Tab: { name: "tab", sequence: "\t", raw: "\t" },
+    Backspace: { name: "backspace", sequence: "\x7f", raw: "\x7f" },
+    Delete: { name: "delete", sequence: "\x1b[3~", raw: "\x1b[3~" },
+    Space: { name: "space", sequence: " ", raw: " " },
+    Home: { name: "home", sequence: "\x1b[H", raw: "\x1b[H" },
+    End: { name: "end", sequence: "\x1b[F", raw: "\x1b[F" },
+    PageUp: { name: "pageup", sequence: "\x1b[5~", raw: "\x1b[5~" },
+    PageDown: { name: "pagedown", sequence: "\x1b[6~", raw: "\x1b[6~" },
+};
+function makeKey(partial) {
+    // Some app key-handlers conditionally call key.preventDefault()/stopPropagation()
+    // (typed `?.()` so they tolerate undefined). When the host's keypress arrives
+    // through a terminal, OpenTUI attaches these methods; in agent-mode we
+    // synthesize the event directly, so we must attach them ourselves — otherwise
+    // the optional-chained call is a no-op and the textarea inserts the key
+    // natively in addition to whatever the handler did (e.g. typing `/` results
+    // in `//` because app.tsx manually insertText("/") and relies on
+    // preventDefault to suppress the textarea's own insert).
+    let _defaultPrevented = false;
+    let _propagationStopped = false;
+    const ev = {
+        name: partial.name,
+        ctrl: false,
+        meta: false,
+        shift: false,
+        option: false,
+        sequence: partial.sequence,
+        number: false,
+        raw: partial.raw,
+        eventType: "press",
+        source: "raw",
+        preventDefault() {
+            _defaultPrevented = true;
+        },
+        stopPropagation() {
+            _propagationStopped = true;
+        },
+        get defaultPrevented() {
+            return _defaultPrevented;
+        },
+        get propagationStopped() {
+            return _propagationStopped;
+        },
+    };
+    return ev;
+}
+function keyForChar(ch) {
+    return makeKey({ name: ch, sequence: ch, raw: ch });
+}
+function keyForNamed(key) {
+    const m = NAMED[key];
+    if (!m) {
+        // Unknown named key — fall back to treating it as a literal character if it's 1 char.
+        if (key.length === 1)
+            return keyForChar(key);
+        return null;
+    }
+    return makeKey(m);
+}
+/**
+ * Subscribe to agentRuntime.onCommand and inject synthetic key events into
+ * OpenTUI's keyHandler. Safe no-op when agentRuntime is undefined (normal user
+ * mode).
+ *
+ * Special key `__focus__:<id>` is intentionally NOT translated to OpenTUI input
+ * here — it is a driver-level signal currently ignored at this layer. (Focus
+ * routing in OpenTUI is owned by individual components; a global focus dispatch
+ * is out of scope for this bridge.)
+ */
+export function useAgentInputBridge(agentRuntime) {
+    const { keyHandler } = useAppContext();
+    useEffect(() => {
+        if (!agentRuntime || !keyHandler)
+            return;
+        // Toast-only stub in normal interactive mode provides emitEvent but not
+        // onCommand. Guard so the bridge no-ops cleanly instead of crashing the TUI.
+        if (typeof agentRuntime.onCommand !== "function")
+            return;
+        agentRuntime.onCommand((cmd) => {
+            if (!cmd || typeof cmd !== "object")
+                return;
+            const c = cmd;
+            if (c.op === "press" && typeof c.key === "string") {
+                if (c.key.startsWith("__focus__:"))
+                    return;
+                const k = keyForNamed(c.key);
+                if (k)
+                    keyHandler.emit("keypress", k);
+            }
+            else if (c.op === "type" && typeof c.text === "string") {
+                for (const ch of c.text) {
+                    keyHandler.emit("keypress", keyForChar(ch));
+                }
+            }
+        });
+    }, [agentRuntime, keyHandler]);
+}
+//# sourceMappingURL=input-bridge.js.map

package/dist/packages/agent-harness-opentui/src/input-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-bridge.js","sourceRoot":"","sources":["../../../../packages/agent-harness-opentui/src/input-bridge.tsx"],"names":[],"mappings":"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"}