@ouro.bot/cli 0.1.0-alpha.959 → 0.1.0-alpha.960

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.960",
+      "changes": [
+        "Shepherd can watch sessions in the GitHub Copilot app. Add a `copilotApp` record to the machine config (`ouro vault config set --agent <agent> --scope machine --key copilotApp.stateDir --value \"$HOME/.copilot\"`) and Shepherd follows the app's sessions instead of cmux or Herdr: it notices when one stops or waits for a permission, judges it, and answers with a queued message. It leaves alone a session you messaged in the last five minutes, or in the last half hour while you are at the Mac with the app in front, and a turn you stopped yourself. Messages from other agents, schedules and Shepherd itself do not count as yours."
+      ]
+    },
     {
       "version": "0.1.0-alpha.959",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.959",
+  "runtimeVersion": "0.1.0-alpha.960",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.959</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.960</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/heart/shepherd/operations.js

@@ -87,7 +87,7 @@ function parseShepherdOperation(args) {
     const common = { agent, ...(values.has("json") ? { json: true } : {}) };
     const host = () => {
         const value = required("host");
-        return value === "cmux" || value === "herdr" ? value : fail();
+        return value === "cmux" || value === "herdr" || value === "copilot-app" ? value : fail();
     };
     if (operation === "status")
         return { kind: "shepherd.status", ...common };

package/dist/heart/shepherd-config.js

@@ -37,6 +37,7 @@ exports.shepherdRepairHint = shepherdRepairHint;
 exports.shepherdConfigFacts = shepherdConfigFacts;
 exports.shepherdSenseStatus = shepherdSenseStatus;
 exports.defaultHerdrSocketPath = defaultHerdrSocketPath;
+exports.defaultCopilotAppStateDir = defaultCopilotAppStateDir;
 exports.defaultCmuxSocketPath = defaultCmuxSocketPath;
 exports.resolveShepherdConnection = resolveShepherdConnection;
 const fs = __importStar(require("node:fs"));
@@ -44,7 +45,7 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../nerves/runtime");
 function shepherdRepairHint(agent) {
-    return `human-required: in a cmux terminal run 'ouro vault config set --agent ${agent} --scope machine --key cmux.socketCapability --value "$CMUX_SOCKET_CAPABILITY"' (or set cmux.socketPassword when cmux is in password mode), then 'ouro up'. On Herdr instead: 'ouro vault config set --agent ${agent} --scope machine --key herdr.socketPath --value "$HOME/.config/herdr/herdr.sock"', then 'ouro up'.`;
+    return `human-required: for the GitHub Copilot app run 'ouro vault config set --agent ${agent} --scope machine --key copilotApp.stateDir --value "$HOME/.copilot"', then 'ouro up'. Or in a cmux terminal run 'ouro vault config set --agent ${agent} --scope machine --key cmux.socketCapability --value "$CMUX_SOCKET_CAPABILITY"' (or set cmux.socketPassword when cmux is in password mode), then 'ouro up'. On Herdr instead: 'ouro vault config set --agent ${agent} --scope machine --key herdr.socketPath --value "$HOME/.config/herdr/herdr.sock"', then 'ouro up'.`;
 }
 function text(record, key) {
     const value = record?.[key];
@@ -66,6 +67,8 @@ function cmuxAuth(cmux) {
     return null;
 }
 function shepherdConfigFacts(machinePayload) {
+    if (hostRecord(machinePayload, "copilotApp"))
+        return { configured: true, detail: "GitHub Copilot app" };
     const cmux = hostRecord(machinePayload, "cmux");
     const auth = cmuxAuth(cmux);
     if (!auth && hostRecord(machinePayload, "herdr"))
@@ -87,6 +90,10 @@ function shepherdSenseStatus(enabled, machinePayload) {
 function defaultHerdrSocketPath(homeDir = os.homedir()) {
     return path.join(homeDir, ".config", "herdr", "herdr.sock");
 }
+/** The Copilot app's state directory, where it writes `run/ws.port` and `run/ws.token`. */
+function defaultCopilotAppStateDir(homeDir = os.homedir()) {
+    return path.join(homeDir, ".copilot");
+}
 /** cmux's own default: `~/.local/state/cmux/cmux-<uid>.sock`, then the older unscoped `cmux.sock`. */
 function defaultCmuxSocketPath(homeDir = os.homedir(), uid = process.getuid?.() ?? 0, exists = fs.existsSync) {
     const dir = path.join(homeDir, ".local", "state", "cmux");
@@ -97,14 +104,17 @@ function defaultCmuxSocketPath(homeDir = os.homedir(), uid = process.getuid?.()
 function resolveShepherdConnection(agent, machinePayload, defaultSocketPath = defaultCmuxSocketPath) {
     const cmux = hostRecord(machinePayload, "cmux");
     const herdr = hostRecord(machinePayload, "herdr");
+    const copilotApp = hostRecord(machinePayload, "copilotApp");
     const auth = cmuxAuth(cmux);
-    const host = auth ? "cmux" : herdr ? "herdr" : "none";
+    const host = copilotApp ? "copilot-app" : auth ? "cmux" : herdr ? "herdr" : "none";
     (0, runtime_1.emitNervesEvent)({
         component: "senses",
         event: "senses.shepherd_connection_resolved",
         message: "resolved Shepherd terminal host connection settings",
-        meta: { agent, host, auth: auth?.kind ?? "missing" },
+        meta: { agent, host, auth: host === "copilot-app" ? "app-token-file" : auth?.kind ?? "missing" },
     });
+    if (copilotApp)
+        return { ok: true, connection: { host: "copilot-app", stateDir: text(copilotApp, "stateDir") || defaultCopilotAppStateDir() } };
     if (auth)
         return { ok: true, connection: { host: "cmux", socketPath: text(cmux, "socketPath") || defaultSocketPath(), auth } };
     if (herdr)

package/dist/senses/shepherd/copilot-app.js

@@ -0,0 +1,648 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COPILOT_APP_HOST = void 0;
+exports.copilotAppUrl = copilotAppUrl;
+exports.copilotAppHumanPresent = copilotAppHumanPresent;
+exports.readConversation = readConversation;
+exports.copilotAppRequest = copilotAppRequest;
+exports.createCopilotAppHost = createCopilotAppHost;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const ws_1 = __importDefault(require("ws"));
+const runtime_1 = require("../../nerves/runtime");
+const cmux_1 = require("./cmux");
+/**
+ * The GitHub Copilot app host. The app runs a local WebSocket server whose port and token it
+ * rewrites under `<stateDir>/run/` on every launch, so each connection reads them fresh. Shepherd
+ * connects as an observer (`observer=1`), so the app never binds a session's tool callbacks to it.
+ *
+ * Every connection receives every running session's events. A return is `session.idle` (not a
+ * human stop), a permission or question the human must answer, or a terminal `session.error`, still
+ * standing after the grace period. `assistant.turn_end` is not a return: the app sends one after
+ * every model step. Sub-agent events (top-level `agentId`) are work, never a return. The "screen" is
+ * the session's recent conversation, rendered from `session-state/<id>/events.jsonl`. A reply is a
+ * queued `send_message`, so it never touches the human's draft.
+ *
+ * The app does not say which session is on screen, so a session counts as the human's when the
+ * human messaged it in the last five minutes, or in the last half hour while they are at the Mac with
+ * the app in front. Only a message with no `source` and no `agentId` is the human's: agents,
+ * schedules and autopilot tag theirs, and Shepherd's carry its `[agent for human]` label.
+ */
+exports.COPILOT_APP_HOST = "copilot-app";
+const GRACE_MS = 3_000;
+const TIMEOUT_MS = 10_000;
+const HUMAN_HOLD_MS = 5 * 60_000;
+const PRESENT_HOLD_MS = 30 * 60_000;
+const PRESENT_IDLE_S = 120;
+const INVENTORY_MS = 10_000;
+const CHUNK_BYTES = 256 * 1024;
+const SCAN_BYTES = 8 * 1024 * 1024;
+const TAIL_EVENTS = 400;
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000, 30_000];
+/** Bookkeeping events that neither start nor end work. */
+const QUIET_EVENTS = new Set(["model.messages_snapshot", "session.usage_checkpoint", "session.usage_record", "session.background_tasks_changed", "session.title_changed"]);
+const BLOCKED_FRAMES = new Set(["user_input_request", "exit_plan_mode_request", "elicitation_request", "auto_mode_switch_request"]);
+const RESOLVED_FRAMES = new Set(["user_input_resolved", "exit_plan_mode_resolved", "elicitation_resolved", "auto_mode_switch_resolved"]);
+/** Every Shepherd message starts with its `[agent for human]` label, whichever process sent it. */
+const SHEPHERD_LABEL = /^\[[^\]\n]{1,80} for [^\]\n]{1,80}\] /;
+const PERMISSION_KEYS = { y: "approve-once", 1: "approve-once", 2: "approve-for-session", n: "reject", 3: "reject" };
+/** Asset lines can be megabytes and carry no conversation. */
+const BINARY_LINE = Buffer.from("\"session.binary_asset\"");
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * The app's current server address. Every app build (release, dev, PR) writes `ws.port` and
+ * `ws.token`; the release app also writes `ws.release.*`, so those win. The port file holds
+ * `<port>\n<pid>`, and a file whose app has exited is skipped.
+ */
+function copilotAppUrl(stateDir, alive = processAlive) {
+    const run = path.join(stateDir, "run");
+    for (const prefix of ["ws.release", "ws"]) {
+        let port, pid, token;
+        try {
+            ;
+            [port, pid] = fs.readFileSync(path.join(run, `${prefix}.port`), "utf-8").split(/\r?\n/).map(line => line.trim());
+            token = fs.readFileSync(path.join(run, `${prefix}.token`), "utf-8").split(/\r?\n/)[0].trim();
+        }
+        catch {
+            continue;
+        }
+        if (!/^\d+$/.test(port) || !token)
+            continue;
+        if (pid && /^\d+$/.test(pid) && !alive(Number(pid)))
+            continue;
+        return `ws://127.0.0.1:${port}?token=${encodeURIComponent(token)}&observer=1`;
+    }
+    throw new Error(`the GitHub Copilot app is not running (no live server files in ${run})`);
+}
+const runFile = (file, args, done) => { (0, node_child_process_1.execFile)(file, args, { timeout: 2_000 }, (error, stdout) => done(error, String(stdout))); };
+/** macOS: the Copilot app is frontmost and the keyboard or mouse moved recently. Anything unreadable counts as present, so Shepherd holds back. */
+function copilotAppHumanPresent(run = runFile) {
+    const output = (file, args) => new Promise(resolve => run(file, args, (error, stdout) => resolve(error ? null : stdout)));
+    return (async () => {
+        const asn = (await output("/usr/bin/lsappinfo", ["front"]))?.trim();
+        if (!asn)
+            return true;
+        const info = await output("/usr/bin/lsappinfo", ["info", "-only", "name", asn]);
+        if (info === null)
+            return true;
+        if (!/"GitHub Copilot"/.test(info))
+            return false;
+        const hid = await output("/usr/sbin/ioreg", ["-c", "IOHIDSystem", "-d", "4"]);
+        const idle = hid?.match(/"HIDIdleTime" = (\d+)/);
+        return !idle || Number(idle[1]) / 1e9 < PRESENT_IDLE_S;
+    })();
+}
+/** Whether a `user.message` is the human's own: agents, schedules and autopilot tag theirs. */
+function humanMessage(event, data) {
+    return event.type === "user.message" && event.agentId === undefined && data.source === undefined && !SHEPHERD_LABEL.test(str(data.content) ?? "");
+}
+/** Up to `TAIL_EVENTS` event lines from the end of the log, oldest first, skipping asset lines. */
+function tailEvents(file) {
+    const fd = fs.openSync(file, "r");
+    const lines = [];
+    try {
+        let position = fs.fstatSync(fd).size;
+        let carry = Buffer.alloc(0);
+        const keep = (line) => {
+            if (line.length > 0 && !line.subarray(0, 200).includes(BINARY_LINE))
+                lines.push(line);
+        };
+        while (position > 0 && lines.length < TAIL_EVENTS) {
+            const length = Math.min(CHUNK_BYTES, position);
+            position -= length;
+            const chunk = Buffer.alloc(length);
+            fs.readSync(fd, chunk, 0, length, position);
+            const text = Buffer.concat([chunk, carry]);
+            let end = text.length;
+            for (let at = text.lastIndexOf(10, end - 1); at >= 0; at = text.lastIndexOf(10, end - 1)) {
+                keep(text.subarray(at + 1, end));
+                end = at;
+                if (lines.length >= TAIL_EVENTS)
+                    break;
+            }
+            carry = text.subarray(0, end);
+            // One huge line (an asset) is dropped once it outgrows the scan budget.
+            if (carry.length > SCAN_BYTES)
+                carry = Buffer.alloc(0);
+        }
+        if (position === 0 && lines.length < TAIL_EVENTS)
+            keep(carry);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return lines.reverse();
+}
+/** The session's recent top-level conversation, oldest first, and what is still waiting on the human. */
+function readConversation(stateDir, sessionId) {
+    if (!/^[A-Za-z0-9-]+$/.test(sessionId))
+        throw new Error("invalid Copilot app session id");
+    const lines = [];
+    const permissions = new Map();
+    let humanAt = null;
+    const push = (block) => {
+        for (const line of block.split(/\r?\n/))
+            lines.push(line);
+    };
+    for (const raw of tailEvents(path.join(stateDir, "session-state", sessionId, "events.jsonl"))) {
+        let event;
+        try {
+            event = JSON.parse(raw.toString("utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(event))
+            continue;
+        const data = isRecord(event.data) ? event.data : {};
+        if (humanMessage(event, data)) {
+            const at = Date.parse(str(event.timestamp) ?? "");
+            if (!Number.isNaN(at))
+                humanAt = at;
+        }
+        // Sub-agents talk among themselves; the conversation is the session's own.
+        if (event.agentId !== undefined)
+            continue;
+        switch (event.type) {
+            case "user.message":
+                if (str(data.content))
+                    push(`› ${str(data.source) ? `(${data.source}) ` : ""}${data.content}`);
+                break;
+            case "assistant.message":
+                if (str(data.content))
+                    push(data.content);
+                break;
+            case "tool.execution_start": {
+                const args = isRecord(data.arguments) ? data.arguments : {};
+                const what = str(args.description) ?? str(args.command) ?? str(args.question) ?? str(args.path) ?? "";
+                push(`• ${str(data.toolName) ?? "tool"}${what ? `: ${what.replace(/\s+/g, " ").slice(0, 160)}` : ""}`);
+                break;
+            }
+            case "session.task_complete":
+                if (str(data.summary))
+                    push(`Task complete: ${data.summary}`);
+                break;
+            case "session.error":
+                push(`Error: ${str(data.message) ?? str(data.errorType) ?? "unknown"}`);
+                break;
+            case "permission.requested": {
+                const id = str(data.requestId);
+                if (!id || data.resolvedByHook === true)
+                    break;
+                const request = isRecord(data.permissionRequest) ? data.permissionRequest : {};
+                permissions.set(id, str(request.intention) ?? str(request.fullCommandText) ?? str(request.kind) ?? "a tool call");
+                break;
+            }
+            case "permission.completed":
+                if (str(data.requestId))
+                    permissions.delete(data.requestId);
+                break;
+        }
+    }
+    const pending = [...permissions.entries()].at(-1);
+    if (pending)
+        lines.push(`Waiting for permission: ${pending[1].replace(/\s+/g, " ").slice(0, 300)}`);
+    return { lines, pendingPermission: pending?.[0] ?? null, humanAt };
+}
+/** One connection: frames go to `onFrame` until the socket closes. Throws if the socket cannot be created. */
+function openStream(url, openSocket, onFrame, onClose) {
+    const socket = openSocket(url);
+    const queue = [];
+    let failure;
+    socket.on("open", () => { for (const line of queue.splice(0))
+        socket.send(line); });
+    socket.on("message", (data) => {
+        try {
+            const frame = JSON.parse(data.toString());
+            if (isRecord(frame))
+                onFrame(frame);
+        }
+        catch {
+            // A frame that is not JSON is ignored.
+        }
+    });
+    socket.on("error", (error) => { failure = error; });
+    socket.on("close", () => onClose(failure));
+    return {
+        send(frame) {
+            const line = JSON.stringify(frame);
+            if (socket.readyState === ws_1.default.OPEN)
+                socket.send(line);
+            else
+                queue.push(line);
+        },
+        close: () => socket.close(),
+    };
+}
+/** One request on its own connection, settled by the first frame `match` accepts (or throws on). */
+function copilotAppRequest(stateDir, frame, match, options = {}) {
+    const openSocket = options.openSocket ?? ((url) => new ws_1.default(url));
+    return new Promise((resolve, reject) => {
+        let stream;
+        try {
+            stream = openStream(copilotAppUrl(stateDir), openSocket, (reply) => {
+                try {
+                    const value = match(reply);
+                    if (value !== undefined)
+                        settle(() => resolve(value));
+                }
+                catch (error) {
+                    settle(() => reject(error));
+                }
+            }, (error) => settle(() => reject(new Error(`Copilot app ${String(frame.type)}: ${error?.message ?? "connection closed"}`))));
+        }
+        catch (error) {
+            return reject(error);
+        }
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            stream.close();
+            fn();
+        };
+        const timer = setTimeout(() => settle(() => reject(new Error(`Copilot app ${String(frame.type)} timed out`))), options.timeoutMs ?? TIMEOUT_MS);
+        stream.send(frame);
+    });
+}
+function sessionsFrom(frame, focused) {
+    const workspaces = Array.isArray(frame.workspaces) ? frame.workspaces.filter(isRecord) : [];
+    const sessions = [];
+    for (const workspace of workspaces) {
+        if (workspace.archivedAt)
+            continue;
+        const session = isRecord(workspace.session) ? workspace.session : null;
+        const id = str(session?.sessionId);
+        if (!session || !id)
+            continue;
+        sessions.push({
+            id,
+            ref: id.slice(0, 8),
+            workspace: str(workspace.id),
+            workspaceTitle: str(workspace.projectName) ?? str(workspace.name),
+            title: str(session.title) ?? str(workspace.name) ?? "",
+            cwd: str(workspace.displayPath),
+            // `isRunning` means busy right now, not that an agent exists: every listed session has one.
+            agent: "copilot",
+            focused: focused(id),
+        });
+    }
+    return sessions;
+}
+function createCopilotAppHost(connection, options = {}) {
+    const schedule = options.schedule ?? cmux_1.realSchedule;
+    const now = options.now ?? Date.now;
+    const humanPresent = options.humanPresent ?? copilotAppHumanPresent;
+    const openSocket = options.openSocket ?? ((url) => new ws_1.default(url));
+    const { stateDir } = connection;
+    /** Human messages this host saw live, newer than the log may show yet. */
+    const humanAt = new Map();
+    const request = (frame, match) => copilotAppRequest(stateDir, frame, match, { openSocket });
+    async function workspaceList() {
+        const requestId = `ouro-${(0, node_crypto_1.randomUUID)()}`;
+        return request({ type: "list_workspaces", request_id: requestId }, (frame) => {
+            if (frame.request_id !== requestId)
+                return undefined;
+            if (frame.type === "error")
+                throw new Error(`Copilot app could not list sessions: ${str(frame.message) ?? "error"}`);
+            return frame.type === "workspace_list" ? frame : undefined;
+        });
+    }
+    function lastHuman(sessionId) {
+        let logged = null;
+        try {
+            logged = readConversation(stateDir, sessionId).humanAt;
+        }
+        catch {
+            // A session with no log yet has no human message in it.
+        }
+        return Math.max(humanAt.get(sessionId) ?? -Infinity, logged ?? -Infinity);
+    }
+    async function list() {
+        const frame = await workspaceList();
+        let present;
+        const ages = new Map();
+        for (const session of sessionsFrom(frame, () => false))
+            ages.set(session.id, now() - lastHuman(session.id));
+        if ([...ages.values()].some(age => age >= HUMAN_HOLD_MS && age < PRESENT_HOLD_MS))
+            present = await humanPresent();
+        return sessionsFrom(frame, (id) => {
+            const age = ages.get(id);
+            return age < HUMAN_HOLD_MS || (present === true && age < PRESENT_HOLD_MS);
+        });
+    }
+    return {
+        name: exports.COPILOT_APP_HOST,
+        async retirementInventory() {
+            const frame = await workspaceList();
+            if (!Array.isArray(frame.workspaces) || (Array.isArray(frame.deferred_workspace_ids) && frame.deferred_workspace_ids.length > 0)) {
+                throw new Error("invalid Copilot app session inventory");
+            }
+            const ids = sessionsFrom(frame, () => false).map(session => session.id);
+            if (new Set(ids).size !== ids.length)
+                throw new Error("invalid Copilot app session inventory identity");
+            return ids;
+        },
+        list,
+        async read(sessionId, lines) {
+            const conversation = readConversation(stateDir, sessionId);
+            // An empty screen is no basis for a judgment; the sense records the error and sends nothing.
+            if (conversation.lines.length === 0)
+                throw new Error("could not read this Copilot app session's conversation");
+            return conversation.lines.slice(-Math.max(1, lines)).join("\n");
+        },
+        async prompt(sessionId, line) {
+            const requestId = `ouro-${(0, node_crypto_1.randomUUID)()}`;
+            await request({ type: "send_message", session_id: sessionId, prompt: line, delivery_mode: "enqueue", request_id: requestId }, (frame) => {
+                if (frame.request_id !== requestId)
+                    return undefined;
+                if (frame.type === "session_message_sent")
+                    return true;
+                if (frame.type === "session_message_delivery_unknown")
+                    throw new Error(`Copilot app could not confirm delivery: ${str(frame.detail) ?? "unknown"}`);
+                if (frame.type === "error" || frame.type === "session_resume_failed") {
+                    throw new Error(`Copilot app refused the message: ${str(frame.message) ?? str(frame.reason) ?? String(frame.type)}`);
+                }
+                return undefined;
+            });
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_copilot_app_prompted", message: "sent a message to a Copilot app session", meta: { chars: line.length } });
+        },
+        async key(sessionId, key) {
+            if (key === "ctrl-c" || key === "escape") {
+                const requestId = `ouro-${(0, node_crypto_1.randomUUID)()}`;
+                await request({ type: "abort_session", session_id: sessionId, request_id: requestId }, (frame) => {
+                    if (frame.type === "error" && frame.request_id === requestId)
+                        throw new Error(`Copilot app refused to stop the session: ${str(frame.message) ?? "error"}`);
+                    const event = isRecord(frame.event) ? frame.event : null;
+                    return frame.type === "session_event" && frame.session_id === sessionId && event?.type === "session.idle" ? true : undefined;
+                });
+                return;
+            }
+            const result = PERMISSION_KEYS[key];
+            if (!result)
+                throw new Error(`the Copilot app has no '${key}' key: send a line, y/1 (approve), 2 (approve for the session), n/3 (reject) or ctrl-c (stop)`);
+            const pending = readConversation(stateDir, sessionId).pendingPermission;
+            if (!pending)
+                throw new Error("this Copilot app session is not waiting for a permission; nothing was sent");
+            await request({ type: "respond_to_permission", session_id: sessionId, request_id: pending, result }, (frame) => {
+                if (frame.type === "error" && (frame.request_id === pending || frame.session_id === sessionId))
+                    throw new Error(`Copilot app refused the answer: ${str(frame.message) ?? "error"}`);
+                const event = isRecord(frame.event) ? frame.event : null;
+                return frame.type === "session_event" && event?.type === "permission.completed" && isRecord(event.data) && event.data.requestId === pending ? true : undefined;
+            });
+        },
+        async signal(_sessionId, status) {
+            // The app has no status line or notification an outside client can set; owner notices carry the news.
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_copilot_app_signal", message: "Copilot app has no status line; Shepherd status kept in its own records", meta: { status: status ?? null } });
+        },
+        watch(handlers) {
+            let closed = false;
+            let attempt = 0;
+            let stream = null;
+            let cancelReconnect = null;
+            let cancelInventory = null;
+            const pending = new Map();
+            /** What each session is waiting on the human for: permission ids and blocking frames. */
+            const blocked = new Map();
+            const lastBody = new Map();
+            const activity = new Map();
+            let inventory = [];
+            const publish = (error) => {
+                handlers.observed?.({
+                    at: now(),
+                    sessions: inventory.map((session) => ({ session, activity: activity.get(session.id) ?? "unknown", observedAt: now() })),
+                    ...(error ? { error } : {}),
+                });
+            };
+            const cancel = (sessionId) => {
+                pending.get(sessionId)?.();
+                pending.delete(sessionId);
+            };
+            /** The stop counts only if no new work started during the grace period. */
+            const settle = (sessionId, transitionId, backgroundWork) => {
+                cancel(sessionId);
+                activity.set(sessionId, "idle");
+                pending.set(sessionId, schedule(() => {
+                    pending.delete(sessionId);
+                    // Only sessions in the workspace list are judged; a side chat's parent is.
+                    const session = inventory.find(candidate => candidate.id === sessionId);
+                    if (!session)
+                        return;
+                    handlers.returned({
+                        sessionId, transitionId, agent: session.agent, cwd: session.cwd ?? null,
+                        workspaceTitle: session.workspaceTitle ?? null, title: session.title,
+                        lastBody: lastBody.get(sessionId) ?? null, backgroundWork,
+                    });
+                }, GRACE_MS));
+            };
+            const working = (sessionId) => {
+                cancel(sessionId);
+                activity.set(sessionId, "working");
+            };
+            const block = (sessionId, key, transition = key) => {
+                const set = blocked.get(sessionId) ?? new Set();
+                set.add(key);
+                blocked.set(sessionId, set);
+                settle(sessionId, `${exports.COPILOT_APP_HOST}:${sessionId}:${transition}`, null);
+            };
+            /** An answered request; the session is working again unless it still waits on another. */
+            const unblock = (sessionId, key) => {
+                const set = blocked.get(sessionId);
+                set?.delete(key);
+                if (!set?.size)
+                    working(sessionId);
+            };
+            const onEvent = (sessionId, event) => {
+                const type = str(event.type) ?? "";
+                const data = isRecord(event.data) ? event.data : {};
+                if (QUIET_EVENTS.has(type) || type.endsWith("_delta"))
+                    return;
+                if (humanMessage(event, data)) {
+                    humanAt.set(sessionId, now());
+                    handlers.focused(sessionId);
+                }
+                // A sub-agent's events are its parent's work, never a stop.
+                if (event.agentId !== undefined) {
+                    if (!blocked.get(sessionId)?.size)
+                        working(sessionId);
+                    return;
+                }
+                const transitionId = `${exports.COPILOT_APP_HOST}:${sessionId}:${str(event.id) ?? `t${now()}`}`;
+                switch (type) {
+                    case "session.idle": {
+                        blocked.delete(sessionId);
+                        // A stop the human asked for is theirs to follow up.
+                        if (data.aborted === true) {
+                            cancel(sessionId);
+                            activity.set(sessionId, "idle");
+                            return handlers.focused(sessionId);
+                        }
+                        // The app sends idle only with no background agents or shells in flight; older builds listed them.
+                        const tasks = isRecord(data.backgroundTasks) ? data.backgroundTasks : null;
+                        const running = tasks ? [tasks.agents, tasks.shells].some(list => Array.isArray(list) && list.length > 0) : false;
+                        return settle(sessionId, transitionId, running);
+                    }
+                    case "session.shutdown":
+                        // The runtime ended: nothing is waiting and nothing can be answered.
+                        blocked.delete(sessionId);
+                        cancel(sessionId);
+                        activity.set(sessionId, "idle");
+                        return;
+                    case "session.error":
+                        if (data.eligibleForAutoSwitch === true)
+                            break;
+                        lastBody.set(sessionId, `Error: ${str(data.message) ?? str(data.errorType) ?? "unknown"}`);
+                        return settle(sessionId, transitionId, null);
+                    case "permission.requested":
+                        if (data.resolvedByHook === true || !str(data.requestId))
+                            break;
+                        return block(sessionId, data.requestId);
+                    case "permission.completed":
+                        return unblock(sessionId, str(data.requestId) ?? "");
+                    case "assistant.message":
+                        if (str(data.content))
+                            lastBody.set(sessionId, data.content);
+                        break;
+                    case "session.task_complete":
+                        if (str(data.summary))
+                            lastBody.set(sessionId, data.summary);
+                        break;
+                }
+                // A turn end is one model step, not a stop, and a waiting request keeps the session waiting.
+                if (type === "assistant.turn_end" || blocked.get(sessionId)?.size)
+                    return;
+                working(sessionId);
+            };
+            const onFrame = (frame) => {
+                if (closed)
+                    return;
+                const type = str(frame.type) ?? "";
+                if (type === "server_hello") {
+                    attempt = 0;
+                    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_copilot_app_connected", message: "Copilot app event stream connected", meta: {} });
+                    return;
+                }
+                if (type === "workspace_list") {
+                    // Advisory only: the send path re-checks focus through list().
+                    inventory = sessionsFrom(frame, (id) => now() - (humanAt.get(id) ?? -Infinity) < HUMAN_HOLD_MS);
+                    for (const id of [...activity.keys()])
+                        if (!inventory.some(session => session.id === id))
+                            activity.delete(id);
+                    return publish();
+                }
+                const sessionId = str(frame.session_id);
+                if (!sessionId)
+                    return;
+                if (type === "session_event" && isRecord(frame.event)) {
+                    // History replays describe the past, never a new stop.
+                    if (!frame.history_request_id)
+                        onEvent(sessionId, frame.event);
+                    return;
+                }
+                // A request without an id is keyed by its kind, so its resolution can still clear it.
+                if (BLOCKED_FRAMES.has(type)) {
+                    const id = str(frame.request_id);
+                    return block(sessionId, id ?? type, id ?? `${type}@${now()}`);
+                }
+                if (RESOLVED_FRAMES.has(type))
+                    return unblock(sessionId, str(frame.request_id) ?? type.replace(/_resolved$/, "_request"));
+            };
+            // Reconnect and close cancel the next refresh, so it only ever runs on a live stream.
+            const refreshInventory = (current) => {
+                current.send({ type: "list_workspaces", request_id: `ouro-${(0, node_crypto_1.randomUUID)()}` });
+                cancelInventory = schedule(() => refreshInventory(current), INVENTORY_MS);
+            };
+            const reconnect = (error) => {
+                stream = null;
+                cancelInventory?.();
+                cancelInventory = null;
+                // Answers given while disconnected are not replayed, so nothing stays waiting across a gap.
+                blocked.clear();
+                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_copilot_app_closed", message: "Copilot app event stream closed; reconnecting", meta: { delay, error: error?.message ?? null } });
+                publish("host_unavailable");
+                cancelReconnect = schedule(connect, delay);
+            };
+            const connect = () => {
+                cancelReconnect = null;
+                try {
+                    // Stops while disconnected are not replayed; the next idle or permission event is.
+                    stream = openStream(copilotAppUrl(stateDir), openSocket, onFrame, reconnect);
+                }
+                catch (error) {
+                    return reconnect(error);
+                }
+                refreshInventory(stream);
+            };
+            connect();
+            return {
+                close() {
+                    closed = true;
+                    cancelReconnect?.();
+                    cancelInventory?.();
+                    for (const stop of pending.values())
+                        stop();
+                    pending.clear();
+                    stream?.close();
+                },
+            };
+        },
+    };
+}

package/dist/senses/shepherd/host.js

@@ -4,10 +4,13 @@ exports.createShepherdHost = createShepherdHost;
 const runtime_1 = require("../../nerves/runtime");
 const client_1 = require("./client");
 const cmux_1 = require("./cmux");
+const copilot_app_1 = require("./copilot-app");
 const herdr_1 = require("./herdr");
 /** The host for this machine's connection. */
 function createShepherdHost(connection, options) {
     (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_host_created", message: "opened the Shepherd terminal host", meta: { host: connection.host } });
+    if (connection.host === "copilot-app")
+        return (0, copilot_app_1.createCopilotAppHost)(connection, { schedule: options.schedule, now: options.now });
     return connection.host === "herdr"
         ? (0, herdr_1.createHerdrHost)(connection, { schedule: options.schedule })
         : (0, cmux_1.createCmuxHost)((0, client_1.createCmuxClient)(connection, { agentName: options.agentName }), { now: options.now, schedule: options.schedule });

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.959",
+  "version": "0.1.0-alpha.960",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.959",
+      "version": "0.1.0-alpha.960",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.959",
+  "version": "0.1.0-alpha.960",
   "engines": {
     "node": ">=22"
   },