@spencerboucher/switchyard 0.3.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@ flowchart TB
   subgraph clients["Clients: windows onto the same work"]
     phone["Phone<br/>(installable web app)"]
     browser["Desktop browser"]
-    term["Terminal client and CLI"]
+    term["Pi terminal and CLI"]
   end
 
   coord["<b>Coordinator</b><br/>tasks, schedules, notifications,<br/>sign-in, sync<br/><i>never runs code</i>"]
@@ -37,7 +37,7 @@ There are three kinds of parts:
 
 - **The coordinator** is the one always-on service. It keeps tasks, schedules, notifications, devices and the shared view of every session, and it decides what runs where. It never runs an agent and never holds your provider credentials, so it can live anywhere: a container, a small server, or your laptop.
 - **Hosts** are your machines. A host agent runs Pi as your OS user, with your repositories, worktrees, Pi packages and model logins, and connects *outbound* to the coordinator. A host needs no open ports, and a laptop can come and go: its sessions keep running while the coordinator is down, and the events catch up when it returns.
-- **Clients** are views. The web app works on desktop and as an installed app on a phone; the terminal client and the scriptable CLI work over the same API. Any client can watch, answer and steer a session; none of them owns it.
+- **Clients** are views. The web app works on desktop and as an installed app on a phone; in a terminal you get Pi's own TUI for any session (`switchyard tui`, or a whole herdr session mirroring Switchyard), and the scriptable CLI works over the same API. Any client can watch, answer and steer a session; none of them owns it.
 
 For a single machine, `switchyard up` runs the coordinator and a host in one process. For more, run the coordinator as a server and enroll each machine as a host. The protocol is the same either way.
 
@@ -77,7 +77,7 @@ sequenceDiagram
 | Area | What you get |
 |---|---|
 | **Sessions** | Persistent Pi conversations on any host; the same live session in every client; steer or queue follow-ups; take over and return to automation; resume after crashes with the same conversation (never a silent new one); import existing Pi sessions |
-| **Workspaces** | A git worktree per task or session inside the repository, discovery of worktrees you made yourself, setup commands, and removal that refuses to lose uncommitted or unmerged work |
+| **Workspaces** | A git worktree per task or session inside the repository, discovery of worktrees you made yourself, setup commands, removal that refuses to lose uncommitted or unmerged work, and project folders per host whose repositories are added automatically |
 | **Tasks and board** | Backlog, Ready, In progress, Review, Done; dependencies with cycle detection; priorities; per-project concurrency limits; a Now view explaining why queued work waits |
 | **Review** | Changed files and diffs on desktop and phone, line comments sent as one follow-up, request changes, accept |
 | **Bounded continuation** | Optional: keep the agent working toward an objective, within a maximum number of continuations, a time limit and token or cost caps, ending in your checks and your review |
@@ -116,7 +116,7 @@ switchyard up
 ```sh
 docker run -d --name switchyard -p 127.0.0.1:7400:7400 -v switchyard-data:/data \
   -e SWITCHYARD_PUBLIC_URL=https://switchyard.example.com \
-  ghcr.io/justmytwospence/switchyard:0.3.0
+  ghcr.io/justmytwospence/switchyard:0.5.0
 docker exec switchyard switchyard init    # prints a single-use sign-in link for your first device
 ```
 
@@ -154,7 +154,8 @@ Switchyard is young and moving quickly. It is tested against Pi `>=1.4.0 <1.6.0`
 |---|---|
 | [Deployment](docs/deployment.md) | Single machine, server, reverse proxies, VPNs, hosts, environment reference, privilege model |
 | [Sign-in and devices](docs/auth.md) | The owner model, pairing, passkeys, single sign-on, host enrollment, revocation |
-| [CLI and terminal client](docs/cli.md) | Every `switchyard` command, credentials, terminal key bindings |
+| [CLI](docs/cli.md) | Every `switchyard` command and credentials |
+| [Terminal sessions](docs/terminal-sessions.md) | Pi's own TUI for every session, from any terminal, and the herdr integration |
 | [Operations](docs/operations.md) | Backup, restore, migrations, retention, logs, health, diagnostics |
 | [Adapters](docs/adapters.md) | Rendering a Pi plugin's UI in every client; shipping an adapter with your Pi package |
 | [Architecture](docs/architecture.md) | Components, data ownership, the host and client protocols, packages |

package/dist/bridge/switchyard-terminal.js

@@ -0,0 +1,527 @@
+/**
+ * Switchyard terminal extension, loaded with `-e` into an interactive Pi that runs inside a
+ * Switchyard terminal holder (a pty). It is the control channel the host uses instead of
+ * `pi --mode rpc`: it answers the same JSONL commands (`prompt`, `steer`, `follow_up`, `abort`,
+ * `get_state`, ...), forwards session events in RPC shape, and lets remote clients answer extension
+ * dialogs while they are also shown in the terminal (whichever answer comes first wins).
+ *
+ * It connects to the holder's socket named by `SWITCHYARD_CONTROL_SOCKET`, imports only Node
+ * built-ins, and never throws: without the variable it does nothing.
+ *
+ * Dialogs: every extension's `ctx.ui` is the same object, so replacing `select`, `confirm`,
+ * `input` and `editor` on it routes all dialogs through the race below. When that object cannot be
+ * patched, `remoteDialogs` is false and the host tells remote clients to answer in the terminal.
+ */
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+const PATCHED = Symbol.for("switchyard.terminal");
+const WRAPPED = Symbol.for("switchyard.terminal.wrapped");
+function messageText(message) {
+    const content = message?.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((c) => c?.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n");
+}
+/** Pi's `toJsonEvent` for `message_update` (`dist/modes/json-event.js`). */
+export function jsonMessageUpdate(event) {
+    const aev = event?.assistantMessageEvent ?? {};
+    let out;
+    if (aev.type === "toolcall_start") {
+        const { partial, ...rest } = aev;
+        const call = partial?.content?.[aev.contentIndex];
+        out = { ...rest, id: call?.id, toolName: call?.name };
+    }
+    else if (aev && typeof aev === "object" && "partial" in aev) {
+        const { partial: _p, ...rest } = aev;
+        out = rest;
+    }
+    else {
+        out = aev;
+    }
+    return { type: "message_update", usage: event?.message?.usage, assistantMessageEvent: out };
+}
+function addUsage(totals, usage) {
+    if (!usage || typeof usage !== "object")
+        return;
+    if (typeof usage.totalTokens === "number")
+        totals.tokens += usage.totalTokens;
+    if (typeof usage.cost?.total === "number")
+        totals.cost += usage.cost.total;
+}
+/** Token and cost totals over session entries, like Pi's `getSessionStats()`. */
+export function sessionTotals(entries) {
+    const totals = { tokens: 0, cost: 0 };
+    for (const e of entries) {
+        if (e?.type === "usage")
+            addUsage(totals, e.usage);
+        else if ((e?.type === "branch_summary" || e?.type === "compaction") && e.usage) {
+            addUsage(totals, e.usage);
+        }
+        else if (e?.type === "message") {
+            const m = e.message;
+            if (m?.role === "assistant" || m?.role === "toolResult")
+                addUsage(totals, m.usage);
+        }
+    }
+    return totals;
+}
+export default function switchyardTerminal(pi) {
+    const socketPath = process.env.SWITCHYARD_CONTROL_SOCKET;
+    if (!socketPath)
+        return;
+    let ctx = null;
+    let remoteDialogs = false;
+    let entryCount = 0;
+    const pending = new Map();
+    const early = [];
+    const queue = { steering: [], followUp: [] };
+    let socket = null;
+    const send = (obj) => {
+        try {
+            if (!socket || socket.destroyed)
+                return;
+            socket.write(`${JSON.stringify(obj)}\n`);
+        }
+        catch {
+            // never throw into Pi
+        }
+    };
+    const sendQueue = () => send({ type: "queue_update", ...queue });
+    const flushEntries = () => {
+        try {
+            const entries = ctx?.sessionManager?.getEntries?.() ?? [];
+            for (const entry of entries.slice(entryCount))
+                send({ type: "entry_appended", entry });
+            entryCount = entries.length;
+        }
+        catch {
+            // ignore
+        }
+    };
+    // ---- dialogs ----
+    const parseBody = (method, body) => {
+        if (method === "confirm")
+            return body.cancelled ? false : body.confirmed === true;
+        return body.cancelled ? undefined : body.value;
+    };
+    const race = (ui, method, orig, title, second, opts) => {
+        if (opts?.signal?.aborted)
+            return orig.call(ui, title, second, opts);
+        const id = randomUUID();
+        const ac = new AbortController();
+        const signals = [ac.signal, opts?.signal].filter(Boolean);
+        const signal = signals.length > 1 ? AbortSignal.any(signals) : ac.signal;
+        const extra = method === "select"
+            ? { options: second }
+            : method === "confirm"
+                ? { message: second }
+                : { placeholder: second };
+        const request = {
+            type: "extension_ui_request",
+            id,
+            method,
+            title,
+            ...extra,
+            ...(opts?.timeout ? { timeout: opts.timeout } : {}),
+        };
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = (value) => {
+                if (done)
+                    return;
+                done = true;
+                pending.delete(id);
+                resolve(value);
+            };
+            pending.set(id, {
+                request,
+                onRemote: (body) => {
+                    const value = parseBody(method, body);
+                    ac.abort();
+                    finish(value);
+                },
+            });
+            send(request);
+            Promise.resolve()
+                .then(() => orig.call(ui, title, second, { ...(opts ?? {}), signal }))
+                .then((value) => {
+                if (ac.signal.aborted)
+                    return;
+                send({
+                    type: "extension_ui_closed",
+                    id,
+                    by: opts?.signal?.aborted ? "pi" : "terminal",
+                });
+                finish(value);
+            }, () => {
+                if (ac.signal.aborted)
+                    return;
+                send({ type: "extension_ui_closed", id, by: "terminal" });
+                finish(method === "confirm" ? false : undefined);
+            });
+        });
+    };
+    const raceEditor = (ui, orig, title, prefill) => {
+        const id = randomUUID();
+        const request = {
+            type: "extension_ui_request",
+            id,
+            method: "editor",
+            title,
+            ...(prefill !== undefined ? { prefill } : {}),
+        };
+        return new Promise((resolve) => {
+            let done = false;
+            let remote = false;
+            const finish = (value) => {
+                if (done)
+                    return;
+                done = true;
+                pending.delete(id);
+                resolve(value);
+            };
+            pending.set(id, {
+                request,
+                onRemote: (body) => {
+                    remote = true;
+                    // The terminal editor takes no abort signal: dismiss it with Esc.
+                    send({ type: "holder_keys", data: "\u001b" });
+                    finish(parseBody("editor", body));
+                },
+            });
+            send(request);
+            Promise.resolve()
+                .then(() => orig.call(ui, title, prefill))
+                .then((value) => {
+                if (remote)
+                    return;
+                send({ type: "extension_ui_closed", id, by: "terminal" });
+                finish(value);
+            }, () => {
+                if (remote)
+                    return;
+                send({ type: "extension_ui_closed", id, by: "terminal" });
+                finish(undefined);
+            });
+        });
+    };
+    const fire = (method, fields) => send({ type: "extension_ui_request", id: randomUUID(), method, ...fields });
+    const patchUi = (c) => {
+        try {
+            const ui = c.ui;
+            if (!ui || typeof ui !== "object") {
+                remoteDialogs = false;
+                return;
+            }
+            if (ui[PATCHED]) {
+                remoteDialogs = c.ui.select === ui.select && ui.select?.[WRAPPED] === true;
+                return;
+            }
+            const wrap = (fn) => {
+                fn[WRAPPED] = true;
+                return fn;
+            };
+            for (const method of ["select", "confirm", "input"]) {
+                const orig = ui[method];
+                if (typeof orig !== "function")
+                    continue;
+                ui[method] = wrap((title, second, opts) => race(ui, method, orig, title, second, opts));
+            }
+            const origEditor = ui.editor;
+            if (typeof origEditor === "function") {
+                ui.editor = wrap((title, prefill) => raceEditor(ui, origEditor, title, prefill));
+            }
+            const origNotify = ui.notify;
+            if (typeof origNotify === "function") {
+                ui.notify = (message, type) => {
+                    const r = origNotify.call(ui, message, type);
+                    fire("notify", { message, notifyType: type });
+                    return r;
+                };
+            }
+            const origStatus = ui.setStatus;
+            if (typeof origStatus === "function") {
+                ui.setStatus = (key, text) => {
+                    const r = origStatus.call(ui, key, text);
+                    fire("setStatus", { statusKey: key, statusText: text });
+                    return r;
+                };
+            }
+            const origWidget = ui.setWidget;
+            if (typeof origWidget === "function") {
+                ui.setWidget = (key, content, options) => {
+                    const r = origWidget.call(ui, key, content, options);
+                    if (content === undefined || Array.isArray(content)) {
+                        fire("setWidget", {
+                            widgetKey: key,
+                            widgetLines: content,
+                            widgetPlacement: options?.placement,
+                        });
+                    }
+                    return r;
+                };
+            }
+            const origTitle = ui.setTitle;
+            if (typeof origTitle === "function") {
+                ui.setTitle = (title) => {
+                    const r = origTitle.call(ui, title);
+                    fire("setTitle", { title });
+                    return r;
+                };
+            }
+            Object.defineProperty(ui, PATCHED, { value: true });
+            remoteDialogs = c.ui.select === ui.select && ui.select?.[WRAPPED] === true;
+        }
+        catch {
+            remoteDialogs = false;
+        }
+    };
+    // ---- commands ----
+    const content = (message, images) => {
+        if (!Array.isArray(images) || images.length === 0)
+            return message;
+        return [
+            { type: "text", text: message },
+            ...images.map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType })),
+        ];
+    };
+    const respond = (id, command, data, error) => {
+        if (error !== undefined)
+            send({ type: "response", id, command, success: false, error });
+        else if (data === undefined)
+            send({ type: "response", id, command, success: true });
+        else
+            send({ type: "response", id, command, success: true, data });
+    };
+    const handleCommand = (cmd) => {
+        const id = cmd.id;
+        const type = String(cmd.type);
+        if (!ctx) {
+            // Commands that arrive before the session started run once it has.
+            early.push(cmd);
+            return;
+        }
+        try {
+            switch (type) {
+                case "get_state":
+                    respond(id, type, {
+                        sessionId: ctx.sessionManager.getSessionId(),
+                        sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+                        sessionName: pi.getSessionName?.() ?? null,
+                        isStreaming: !ctx.isIdle(),
+                        pendingMessageCount: ctx.hasPendingMessages() ? 1 : 0,
+                    });
+                    return;
+                case "prompt": {
+                    const message = String(cmd.message ?? "");
+                    if (message.startsWith("/")) {
+                        respond(id, type, undefined, "Slash commands from Switchyard need the terminal in terminal sessions: type it there");
+                        return;
+                    }
+                    if (!ctx.isIdle()) {
+                        respond(id, type, undefined, "Session is running: choose Steer or Queue follow-up");
+                        return;
+                    }
+                    pi.sendUserMessage(content(message, cmd.images));
+                    respond(id, type, { disposition: "started" });
+                    return;
+                }
+                case "steer":
+                case "follow_up": {
+                    const message = String(cmd.message ?? "");
+                    const idle = ctx.isIdle();
+                    pi.sendUserMessage(content(message, cmd.images), {
+                        deliverAs: type === "steer" ? "steer" : "followUp",
+                    });
+                    if (!idle) {
+                        (type === "steer" ? queue.steering : queue.followUp).push(message);
+                        sendQueue();
+                    }
+                    respond(id, type, { disposition: idle ? "started" : "queued" });
+                    return;
+                }
+                case "abort":
+                    ctx.abort();
+                    respond(id, type);
+                    return;
+                case "clear_queue":
+                    respond(id, type, { steering: [], followUp: [] });
+                    return;
+                case "set_session_name": {
+                    const name = String(cmd.name ?? "").trim();
+                    if (!name) {
+                        respond(id, type, undefined, "Session name cannot be empty");
+                        return;
+                    }
+                    pi.setSessionName(name);
+                    respond(id, type);
+                    return;
+                }
+                case "get_session_stats": {
+                    const totals = sessionTotals(ctx.sessionManager.getEntries());
+                    respond(id, type, { tokens: { total: totals.tokens }, cost: totals.cost });
+                    return;
+                }
+                case "shutdown":
+                    respond(id, type);
+                    setImmediate(() => {
+                        try {
+                            ctx.shutdown();
+                        }
+                        catch {
+                            // ignore
+                        }
+                    });
+                    return;
+                default:
+                    respond(id, type, undefined, `Unknown command: ${type}`);
+            }
+        }
+        catch (err) {
+            respond(id, type, undefined, err instanceof Error ? err.message : String(err));
+        }
+    };
+    const onLine = (line) => {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!msg || typeof msg !== "object")
+            return;
+        if (msg.type === "extension_ui_response") {
+            pending.get(String(msg.id))?.onRemote(msg);
+            return;
+        }
+        if (msg.type === "control_attached") {
+            for (const p of pending.values())
+                send(p.request);
+            return;
+        }
+        if (typeof msg.type === "string" && msg.id !== undefined)
+            handleCommand(msg);
+    };
+    // ---- socket ----
+    try {
+        const s = createConnection(socketPath);
+        socket = s;
+        let buf = "";
+        s.setEncoding("utf8");
+        s.on("data", (chunk) => {
+            buf += chunk;
+            let nl = buf.indexOf("\n");
+            while (nl >= 0) {
+                const line = buf.slice(0, nl).replace(/\r$/, "");
+                buf = buf.slice(nl + 1);
+                if (line)
+                    onLine(line);
+                nl = buf.indexOf("\n");
+            }
+        });
+        s.on("error", () => {
+            socket = null;
+        });
+        s.on("close", () => {
+            if (socket === s)
+                socket = null;
+        });
+        s.unref();
+        s.write(`${JSON.stringify({ role: "extension" })}\n`);
+    }
+    catch {
+        socket = null;
+    }
+    // ---- events ----
+    const on = (name, fn) => {
+        try {
+            pi.on(name, (event, c) => {
+                try {
+                    fn(event, c);
+                }
+                catch {
+                    // never throw into Pi
+                }
+            });
+        }
+        catch {
+            // ignore
+        }
+    };
+    on("session_start", (event, c) => {
+        ctx = c;
+        patchUi(c);
+        entryCount = c.sessionManager.getEntries().length;
+        const sessionId = c.sessionManager.getSessionId();
+        const sessionFile = c.sessionManager.getSessionFile() ?? null;
+        send({ type: "extension_hello", pid: process.pid, remoteDialogs, sessionId, sessionFile });
+        if (event?.reason && event.reason !== "startup") {
+            send({ type: "switchyard_native", sessionId, sessionFile });
+        }
+        for (const cmd of early.splice(0))
+            handleCommand(cmd);
+    });
+    for (const name of [
+        "agent_start",
+        "message_start",
+        "tool_execution_start",
+        "tool_execution_update",
+        "tool_execution_end",
+        "session_info_changed",
+    ]) {
+        on(name, (event) => send(event));
+    }
+    on("message_start", (event) => {
+        if (event?.message?.role !== "user")
+            return;
+        const text = messageText(event.message);
+        for (const list of [queue.steering, queue.followUp]) {
+            const i = list.indexOf(text);
+            if (i >= 0) {
+                list.splice(i, 1);
+                sendQueue();
+                return;
+            }
+        }
+    });
+    on("message_update", (event) => send(jsonMessageUpdate(event)));
+    on("message_end", (event) => {
+        send(event);
+        flushEntries();
+    });
+    on("turn_end", () => flushEntries());
+    on("agent_settled", (event) => {
+        send({ type: "agent_settled", aborted: event?.aborted === true });
+        flushEntries();
+        if (queue.steering.length > 0 || queue.followUp.length > 0) {
+            queue.steering = [];
+            queue.followUp = [];
+            sendQueue();
+        }
+    });
+    on("session_compact", () => {
+        send({ type: "compaction_end", result: true });
+        flushEntries();
+    });
+    on("session_compact_failed", (event) => send({
+        type: "compaction_end",
+        result: null,
+        aborted: event?.aborted === true,
+        errorMessage: event?.errorMessage ?? "unknown error",
+    }));
+    on("ui_prompt_start", (event) => send({ type: "ui_prompt", event: event.type, kind: event.kind, title: event.title ?? null }));
+    on("ui_prompt_end", (event) => send({ type: "ui_prompt", event: event.type, kind: event.kind, title: event.title ?? null }));
+    on("input", (event) => {
+        if (event?.source !== "interactive" || !event.streamingBehavior)
+            return;
+        (event.streamingBehavior === "steer" ? queue.steering : queue.followUp).push(String(event.text ?? ""));
+        sendQueue();
+    });
+}
+//# sourceMappingURL=switchyard-terminal.js.map