@ouro.bot/cli 0.1.0-alpha.91 → 0.1.0-alpha.910

package/dist/senses/shepherd/client.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CmuxSocketError = void 0;
+exports.createCmuxClient = createCmuxClient;
+const node_crypto_1 = require("node:crypto");
+const net = __importStar(require("node:net"));
+const shepherd_config_1 = require("../../heart/shepherd-config");
+const runtime_1 = require("../../nerves/runtime");
+class CmuxSocketError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CmuxSocketError";
+    }
+}
+exports.CmuxSocketError = CmuxSocketError;
+const ACCESS_REFUSED = /access denied|authentication required|invalid password|not authorized|unauthori[sz]ed/i;
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function createCmuxClient(connection, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const repair = (0, shepherd_config_1.shepherdRepairHint)(options.agentName ?? "<agent>");
+    const wrap = (line) => connection.auth.kind === "capability"
+        ? `_cmux_capability_v1 ${connection.auth.token} ${line}`
+        : line;
+    const refusal = (text) => text.startsWith("ERROR:") && ACCESS_REFUSED.test(text)
+        ? new CmuxSocketError("auth", `cmux refused the socket connection (${text.slice(0, 200)}); ${repair}`)
+        : null;
+    const connectError = (error) => new CmuxSocketError("unavailable", `cmux socket is not reachable at ${connection.socketPath} (${String(error.code)}); is cmux running?`);
+    /** Opens a connection, runs the password handshake when needed, and hands back a line reader. */
+    function open(onLine, onEnd) {
+        return new Promise((resolve) => {
+            const socket = net.createConnection(connection.socketPath);
+            let buffer = "";
+            let handshake = connection.auth.kind === "password";
+            socket.setEncoding("utf-8");
+            socket.on("error", (error) => onEnd(connectError(error)));
+            socket.on("close", () => onEnd());
+            socket.on("data", (chunk) => {
+                buffer += chunk;
+                let index = buffer.indexOf("\n");
+                while (index >= 0) {
+                    const line = buffer.slice(0, index).trim();
+                    buffer = buffer.slice(index + 1);
+                    index = buffer.indexOf("\n");
+                    if (!line)
+                        continue;
+                    if (handshake) {
+                        handshake = false;
+                        if (line.startsWith("ERROR:") && !line.includes("Unknown command 'auth'")) {
+                            socket.destroy();
+                            onEnd(new CmuxSocketError("auth", `cmux rejected the socket password (${line.slice(0, 200)}); ${repair}`));
+                            continue;
+                        }
+                        resolve(socket);
+                        continue;
+                    }
+                    onLine(line);
+                }
+            });
+            socket.on("connect", () => {
+                if (connection.auth.kind === "password")
+                    socket.write(`auth ${connection.auth.password}\n`);
+                else
+                    resolve(socket);
+            });
+        });
+    }
+    function request(line) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let socket = null;
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                socket?.destroy();
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => finish(new CmuxSocketError("timeout", `cmux did not answer within ${timeoutMs} ms`)), timeoutMs);
+            void open((response) => finish(refusal(response), response), (error) => finish(error ?? new CmuxSocketError("unavailable", "cmux closed the socket before answering"))).then((opened) => {
+                socket = opened;
+                opened.write(`${wrap(line)}\n`);
+            });
+        });
+    }
+    const v2Line = (method, params) => JSON.stringify({ id: (0, node_crypto_1.randomUUID)(), method, params });
+    function parseV2(text) {
+        const parsed = parseRecord(text);
+        if (!parsed)
+            throw new CmuxSocketError(text.startsWith("ERROR:") ? "command_failed" : "protocol", `unexpected cmux response: ${text.slice(0, 200)}`);
+        if (parsed.ok === true)
+            return isRecord(parsed.result) ? parsed.result : {};
+        const error = isRecord(parsed.error) ? parsed.error : {};
+        throw new CmuxSocketError(typeof error.code === "string" ? error.code : "error", typeof error.message === "string" && error.message ? error.message : "cmux error");
+    }
+    return {
+        async call(method, params = {}) {
+            const text = await request(v2Line(method, params));
+            const result = parseV2(text);
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_call", message: "cmux socket call answered", meta: { method } });
+            return result;
+        },
+        async command(line) {
+            const text = await request(line);
+            if (text.startsWith("ERROR:"))
+                throw new CmuxSocketError("command_failed", text.slice(0, 500));
+            return text;
+        },
+        stream(params, handlers) {
+            let closed = false;
+            let socket = null;
+            const end = (error) => {
+                if (closed)
+                    return;
+                closed = true;
+                socket?.destroy();
+                handlers.onClose(error);
+            };
+            void open((line) => {
+                if (closed)
+                    return;
+                const refused = refusal(line);
+                if (refused)
+                    return end(refused);
+                const frame = parseRecord(line);
+                if (!frame)
+                    return end(new CmuxSocketError("protocol", `unexpected cmux event frame: ${line.slice(0, 200)}`));
+                if (frame.ok === false) {
+                    try {
+                        parseV2(line);
+                    }
+                    catch (error) {
+                        return end(error);
+                    }
+                }
+                handlers.onFrame(frame);
+            }, end).then((opened) => {
+                socket = opened;
+                if (closed)
+                    opened.destroy();
+                else
+                    opened.write(`${wrap(v2Line("events.stream", params))}\n`);
+            });
+            return { close: () => end() };
+        },
+    };
+}

package/dist/senses/shepherd/cmux.js

@@ -0,0 +1,332 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUIET_MAX_MS = exports.QUIET_MS = exports.POLL_MS = exports.BACKGROUND_GRACE_MS = exports.GRACE_MS = exports.CMUX_STATUS_KEY = void 0;
+exports.realSchedule = realSchedule;
+exports.readCmuxHookSession = readCmuxHookSession;
+exports.createCmuxHost = createCmuxHost;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * The cmux host (0.64.22 or later). A return is cmux's own "agent stopped" signal: an
+ * `agent.hook.Stop` event, which cmux publishes for every agent its hooks cover (Claude Code,
+ * Codex, Copilot and more). After a short grace period, a stop is dropped if the agent resumed. A
+ * stop that cmux's session store says left background work running waits longer, and is then
+ * passed on marked as such: the agent is still working, not handing back control. Terminals no hook has spoken for
+ * (an agent cmux does not hook, such as Agency today) are polled: output that stops changing for a
+ * quiet window counts as a return. cmux has no bell or output event, so polling is the fallback.
+ */
+exports.CMUX_STATUS_KEY = "ouro";
+exports.GRACE_MS = 3_000;
+/** A stop with background work still running waits this much longer before it is judged (as working, unless the work finished). */
+exports.BACKGROUND_GRACE_MS = 30_000;
+exports.POLL_MS = 4_000;
+exports.QUIET_MS = 8_000;
+/** A quiet terminal judged as still working or not an agent is checked less often, doubling up to this. */
+exports.QUIET_MAX_MS = 300_000;
+const POLL_LINES = 40;
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+const STOP_HOOKS = new Set(["Stop", "StopFailure"]);
+/** Hooks that say nothing about whether the main agent is working. */
+const NEUTRAL_HOOKS = new Set(["SubagentStop", "Notification"]);
+const NAMED_KEYS = new Set(["enter", "escape", "up", "down", "tab"]);
+const SUBMIT_DELAY_MS = 300;
+/** A timer that can be cancelled; the sense and the host take it as an option so tests can drive time. */
+function realSchedule(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    return () => clearTimeout(timer);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+/** A v1 socket argument: quoted, with the characters cmux's tokenizer treats as special escaped. */
+function socketQuote(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+/** cmux keeps each hooked agent's session in `~/.cmuxterm/<agent>-hook-sessions.json`, keyed by the agent's own session id. */
+function readCmuxHookSession(homeDir, agent, sessionId) {
+    try {
+        const store = JSON.parse(fs.readFileSync(path.join(homeDir, ".cmuxterm", `${path.basename(agent)}-hook-sessions.json`), "utf-8"));
+        const sessions = isRecord(store) && isRecord(store.sessions) ? store.sessions : {};
+        // Hook events name the session `<agent>-<id>`; the store keys it by the bare id.
+        const key = [sessionId, sessionId.replace(`${agent}-`, "")].find((candidate) => isRecord(sessions[candidate]));
+        return key ? sessions[key] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function createCmuxHost(client, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const now = options.now ?? Date.now;
+    const schedule = options.schedule ?? realSchedule;
+    /** What hook events taught: which surface a session runs in, and which agent and folder it has. */
+    const hooked = new Map();
+    const sessionSurface = new Map();
+    /** Terminals showing a Shepherd status, so it can be cleared when the agent resumes. */
+    const statused = new Map();
+    /** Quiet windows stretched by `pace`. */
+    const quietMs = new Map();
+    /** One status entry per terminal: cmux keys status pills per workspace, and a workspace can hold several agents. */
+    const statusKey = (surface) => `${exports.CMUX_STATUS_KEY}_${surface.ref.replace(/\W/g, "_")}`;
+    const clearStatus = (surfaceId) => {
+        const entry = statused.get(surfaceId);
+        if (!entry)
+            return;
+        statused.delete(surfaceId);
+        client.command(`clear_status ${entry.key} --tab=${entry.workspaceId}`).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_status_error", message: "could not clear a Shepherd status", meta: { error: error.message } });
+        });
+    };
+    async function surfaces() {
+        const tree = await client.call("system.tree", { all_windows: true });
+        return list(tree.windows).flatMap((window) => list(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => list(workspace.panes).flatMap((pane) => list(pane.surfaces)).map((surface) => ({
+            id: str(surface.id) ?? "",
+            ref: str(surface.ref) ?? "",
+            workspace: str(workspace.ref),
+            workspaceId: str(workspace.id) ?? "",
+            title: str(surface.title) ?? "",
+            type: str(surface.type) ?? "",
+            agent: hooked.get(str(surface.id) ?? "")?.agent ?? null,
+            // The human's terminal: the focused surface of the selected workspace in a visible window.
+            focused: surface.focused === true && workspace.selected === true && window.visible !== false,
+        })));
+    }
+    async function locate(sessionId) {
+        const surface = (await surfaces()).find((entry) => entry.id === sessionId || entry.ref === sessionId);
+        if (!surface)
+            throw new Error(`no cmux terminal ${sessionId}`);
+        return surface;
+    }
+    async function read(sessionId, lines) {
+        const result = await client.call("surface.read_text", { surface_id: sessionId, lines, scrollback: true });
+        return typeof result.text === "string" ? result.text : "";
+    }
+    return {
+        name: "cmux",
+        async list() {
+            return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ id, ref, workspace, title, agent, focused }) => ({ id, ref, workspace, title, agent, focused }));
+        },
+        read,
+        async prompt(sessionId, line) {
+            const surface = await locate(sessionId);
+            const target = { workspace_id: surface.workspaceId, surface_id: surface.id };
+            // A paste lands as one block, so no character of it is read as a keystroke; Enter follows on its own.
+            await client.call("terminal.paste", { ...target, text: line, submit_key: "none" });
+            await new Promise((resolve) => schedule(() => resolve(undefined), SUBMIT_DELAY_MS));
+            await client.call("surface.send_key", { ...target, key: "enter" });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_cmux_prompted", message: "typed a line into a cmux terminal", meta: { chars: line.length } });
+        },
+        async key(sessionId, key) {
+            const surface = await locate(sessionId);
+            const target = { workspace_id: surface.workspaceId, surface_id: surface.id };
+            if (NAMED_KEYS.has(key))
+                await client.call("surface.send_key", { ...target, key });
+            else
+                await client.call("surface.send_text", { ...target, text: key });
+        },
+        async signal(sessionId, status, notification) {
+            const surface = await locate(sessionId);
+            const key = statusKey(surface);
+            await client.command(status
+                ? `set_status ${key} ${socketQuote(status)} --tab=${surface.workspaceId} --panel=${surface.id}`
+                : `clear_status ${key} --tab=${surface.workspaceId}`);
+            if (status)
+                statused.set(surface.id, { key, workspaceId: surface.workspaceId });
+            else
+                statused.delete(surface.id);
+            if (notification)
+                await client.call("notification.create", { title: notification.title, subtitle: "", body: notification.body, workspace_id: surface.workspaceId });
+        },
+        pace(sessionId, slower) {
+            if (slower)
+                quietMs.set(sessionId, Math.min((quietMs.get(sessionId) ?? exports.QUIET_MS) * 2, exports.QUIET_MAX_MS));
+            else
+                quietMs.delete(sessionId);
+        },
+        watch(handlers) {
+            let closed = false;
+            let cursor = null;
+            let attempt = 0;
+            let stream = null;
+            let cancelReconnect = null;
+            let cancelPoll = null;
+            const pending = new Map();
+            const screens = new Map();
+            const forget = (surfaceId) => {
+                hooked.delete(surfaceId);
+                for (const [session, surface] of sessionSurface)
+                    if (surface === surfaceId)
+                        sessionSurface.delete(session);
+            };
+            const cancelPending = (surfaceId) => {
+                pending.get(surfaceId)?.();
+                pending.delete(surfaceId);
+            };
+            /** A stop becomes a return only if nothing resumed it within the grace period; background work earns it a longer wait. */
+            const stopped = (surfaceId, transitionId, agent, sessionId, cwd, waited = false) => {
+                cancelPending(surfaceId);
+                pending.set(surfaceId, schedule(() => {
+                    pending.delete(surfaceId);
+                    const session = sessionId ? readCmuxHookSession(homeDir, agent, sessionId) : null;
+                    const backgroundWork = session?.hadPendingBackgroundWorkAtStop === true || session?.agentLifecycle === "backgroundWorkPending" || session?.agentLifecycle === "running";
+                    if (backgroundWork && !waited) {
+                        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_stop_deferred", message: "a cmux stop left background work running; waiting longer", meta: { agent } });
+                        return stopped(surfaceId, transitionId, agent, sessionId, cwd, true);
+                    }
+                    handlers.returned({ sessionId: surfaceId, transitionId, agent, cwd: str(session?.cwd) ?? cwd, lastBody: str(session?.lastBody), backgroundWork });
+                }, waited ? exports.BACKGROUND_GRACE_MS : exports.GRACE_MS));
+            };
+            const onEvent = (frame) => {
+                const name = str(frame.name) ?? "";
+                const payload = isRecord(frame.payload) ? frame.payload : {};
+                const surfaceId = str(payload.surface_id) ?? str(frame.surface_id);
+                if (name === "surface.focused" && surfaceId) {
+                    quietMs.delete(surfaceId);
+                    return handlers.focused(surfaceId);
+                }
+                if (name === "surface.closed" && surfaceId) {
+                    cancelPending(surfaceId);
+                    forget(surfaceId);
+                    screens.delete(surfaceId);
+                    statused.delete(surfaceId);
+                    return;
+                }
+                if (!name.startsWith("agent.hook.") || (payload.phase !== undefined && payload.phase !== "received"))
+                    return;
+                const hook = name.slice("agent.hook.".length);
+                const sessionId = str(payload.session_id);
+                if (sessionId && surfaceId)
+                    sessionSurface.set(sessionId, surfaceId);
+                const surface = surfaceId ?? (sessionId ? sessionSurface.get(sessionId) : undefined);
+                if (!surface)
+                    return;
+                const agent = str(payload._source) ?? str(frame.source) ?? "unknown";
+                const cwd = str(payload.cwd);
+                hooked.set(surface, { agent, cwd, sessionId });
+                if (STOP_HOOKS.has(hook))
+                    return stopped(surface, `cmux:${String(frame.boot_id)}:${String(frame.seq)}`, agent, sessionId, cwd);
+                if (NEUTRAL_HOOKS.has(hook))
+                    return;
+                // The agent is working again: no pending stop, and no stale status.
+                cancelPending(surface);
+                clearStatus(surface);
+                // An agent that exited leaves a plain terminal, which the quiet-screen fallback watches again.
+                if (hook === "SessionEnd")
+                    forget(surface);
+            };
+            const connect = () => {
+                cancelReconnect = null;
+                stream = client.stream({ ...(cursor !== null ? { after_seq: cursor } : {}), categories: ["agent", "surface"], include_heartbeats: false }, {
+                    onFrame: (frame) => {
+                        if (frame.type === "ack") {
+                            attempt = 0;
+                            const resume = isRecord(frame.resume) ? frame.resume : {};
+                            // A first connection, a restart or a gap starts from cmux's latest event: old stops are not replayed as new returns.
+                            if (cursor === null || resume.gap === true)
+                                cursor = typeof resume.latest_seq === "number" ? resume.latest_seq : cursor;
+                            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_cmux_connected", message: "cmux event stream connected", meta: { gap: resume.gap === true } });
+                            return;
+                        }
+                        if (frame.type !== "event" || typeof frame.seq !== "number" || (cursor !== null && frame.seq <= cursor))
+                            return;
+                        cursor = frame.seq;
+                        onEvent(frame);
+                    },
+                    onClose: (error) => {
+                        stream = null;
+                        if (closed)
+                            return;
+                        const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+                        attempt += 1;
+                        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_closed", message: "cmux event stream closed; reconnecting", meta: { delay, error: error?.message ?? null } });
+                        cancelReconnect = schedule(connect, delay);
+                    },
+                });
+            };
+            /** Terminals with no hook: output that changed and then held still for the quiet window is a return. */
+            const poll = async () => {
+                try {
+                    const terminals = (await surfaces()).filter((surface) => surface.type === "terminal" && !hooked.has(surface.id));
+                    const seen = new Set(terminals.map((surface) => surface.id));
+                    for (const id of screens.keys())
+                        if (!seen.has(id))
+                            screens.delete(id);
+                    for (const surface of terminals) {
+                        const hash = (0, node_crypto_1.createHash)("sha256").update(await read(surface.id, POLL_LINES)).digest("hex");
+                        const last = screens.get(surface.id);
+                        const at = now();
+                        if (!last)
+                            screens.set(surface.id, { hash, changedAt: at, active: false });
+                        else if (last.hash !== hash) {
+                            screens.set(surface.id, { hash, changedAt: at, active: true });
+                            clearStatus(surface.id);
+                        }
+                        else if (last.active && at - last.changedAt >= (quietMs.get(surface.id) ?? exports.QUIET_MS)) {
+                            last.active = false;
+                            handlers.returned({ sessionId: surface.id, transitionId: `cmux:quiet:${surface.id}:${last.changedAt}`, agent: null, cwd: null, lastBody: null, backgroundWork: null });
+                        }
+                    }
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_poll_error", message: "could not poll cmux terminals; the next poll retries", meta: { error: error.message } });
+                }
+                if (!closed)
+                    cancelPoll = schedule(() => void poll(), exports.POLL_MS);
+            };
+            connect();
+            void poll();
+            return {
+                close() {
+                    closed = true;
+                    cancelReconnect?.();
+                    cancelPoll?.();
+                    for (const cancel of pending.values())
+                        cancel();
+                    stream?.close();
+                },
+            };
+        },
+    };
+}