pi-sdk-web 0.1.0

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * pi-web - browser Web access for Pi via the Pi SDK.
+ *
+ * Usage:
+ *   pi-web r <name> [--port <port>]   Run web mode for a session (default port 4080)
+ *   pi-web list                       List all sessions (name, id, cwd), newest first
+ *   pi-web help                       Show this help
+ */
+import { SettingsManager, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, resolveModelScopeWithDiagnostics, } from "@earendil-works/pi-coding-agent";
+import { findSessionByName, listSessions, loadBuiltinExtensions } from "./session.js";
+import { PiWebServer } from "./server.js";
+const DEFAULT_PORT = 4080;
+const DOC = `pi-web - browser Web access for Pi (via Pi SDK)
+
+Usage:
+  pi-web r <name> [--port <port>]   Run web mode for the session (default port ${DEFAULT_PORT})
+  pi-web list                       List all sessions (name, id, cwd), newest first
+  pi-web help                       Show this help
+`;
+function parsePort(value) {
+    if (value === undefined)
+        return DEFAULT_PORT;
+    if (!/^\d+$/.test(value))
+        throw new Error(`Invalid port: ${value} (must be a number)`);
+    const port = parseInt(value, 10);
+    if (!(1 <= port && port <= 65535))
+        throw new Error(`Invalid port: ${port} (must be 1-65535)`);
+    return port;
+}
+async function cmdList() {
+    const sessions = await listSessions();
+    if (sessions.length === 0) {
+        console.log("(no sessions)");
+        return;
+    }
+    const width = Math.max(...sessions.map((s) => (s.name ?? "(unnamed)").length));
+    for (const s of sessions) {
+        console.log(`${(s.name ?? "(unnamed)").padEnd(width)}  ${s.id}  ${s.cwd}`);
+    }
+}
+async function cmdResume(name, port) {
+    const { info, sessionManager } = await findSessionByName(name);
+    const cwd = sessionManager.getCwd();
+    if (cwd) {
+        try {
+            process.chdir(cwd);
+        }
+        catch {
+            // Session cwd no longer exists - keep current directory (same as pii)
+            console.error(`Session cwd not found (${cwd}), keeping current directory`);
+        }
+    }
+    // Create services the way Pi's CLI does: extensions (including built-in
+    // llama.cpp and packages that register providers like deepinfra) load into
+    // the same modelRuntime used below, so scopedModels resolution sees them.
+    const agentDir = getAgentDir();
+    const settingsManager = SettingsManager.create(sessionManager.getCwd(), agentDir);
+    const services = await createAgentSessionServices({
+        cwd: sessionManager.getCwd(),
+        agentDir,
+        settingsManager,
+        resourceLoaderOptions: { extensionFactories: await loadBuiltinExtensions() },
+    });
+    // Resolve enabledModels (settings) into scopedModels, matching Pi's CLI
+    const enabledModels = settingsManager.getEnabledModels();
+    const scopedModels = enabledModels && enabledModels.length > 0
+        ? (await resolveModelScopeWithDiagnostics(enabledModels, services.modelRuntime, {
+            signal: AbortSignal.timeout(15_000),
+        })).scopedModels
+        : [];
+    const { session } = await createAgentSessionFromServices({ services, sessionManager, scopedModels });
+    const server = new PiWebServer(session, { port });
+    await server.start();
+    console.log(`server at http://127.0.0.1:${port}/ (session: ${info.name ?? info.id})`);
+    const shutdown = async (signal) => {
+        console.log(`\n${signal} received, shutting down...`);
+        await server.stop();
+        try {
+            session.dispose();
+        }
+        catch {
+            // ignore
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    // Keep the process alive (http server handles this naturally)
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+        console.log(DOC);
+        process.exit(cmd ? 0 : 1);
+    }
+    if (cmd === "list") {
+        await cmdList();
+        return;
+    }
+    if (cmd === "r" || cmd === "resume") {
+        let name;
+        let port;
+        for (let i = 1; i < args.length; i++) {
+            const arg = args[i];
+            if (arg === "--port") {
+                port = parsePort(args[i + 1]);
+                i++;
+            }
+            else if (arg.startsWith("--port=")) {
+                port = parsePort(arg.slice("--port=".length));
+            }
+            else if (name === undefined) {
+                name = arg;
+            }
+            else {
+                throw new Error(`unexpected argument: ${arg}\nusage: pi-web r <name> [--port <port>]`);
+            }
+        }
+        if (!name)
+            throw new Error("usage: pi-web r <name> [--port <port>]");
+        await cmdResume(name, port ?? DEFAULT_PORT);
+        return;
+    }
+    throw new Error(`unknown command: ${cmd}\n${DOC}`);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,526 @@
+/**
+ * pi-sdk-web server: HTTP static files + WebSocket bridge to a Pi AgentSession.
+ *
+ * The WebSocket protocol mirrors the existing Python bridge (server.py) so the
+ * browser client (static/app.js) works unchanged:
+ *   - On connect:  {type:"state", data:{...}} then {type:"history", data:{entries,leafId}}
+ *   - Pi events:   broadcast verbatim (message_start/update/end, tool_execution_*, ...)
+ *   - UI requests: extension_ui_request broadcast (resolved via extension_ui_response)
+ *   - Client msgs: prompt/abort/get_stats/bash/cycle_model/set_model/... -> session methods
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ModelRegistry, VERSION, } from "@earendil-works/pi-coding-agent";
+import { WebSocket, WebSocketServer } from "ws";
+import { WebUIContext } from "./ui-context.js";
+const DEFAULT_PORT = 4080;
+// Static frontend: prefer the in-package copy (built by `npm run build` for
+// global installs), fall back to the repo-root static/ during development.
+const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const STATIC_DIR = [resolve(PACKAGE_DIR, "static"), resolve(PACKAGE_DIR, "..", "static")].find((p) => existsSync(p)) ??
+    resolve(PACKAGE_DIR, "..", "static");
+// Events after which footer stats should be refreshed (TUI does this too)
+const STATS_REFRESH_EVENTS = new Set([
+    "agent_settled",
+    "turn_end",
+    "tool_execution_end",
+    "compaction_end",
+    "entry_appended",
+    "session_info_changed",
+    "thinking_level_changed",
+]);
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "application/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".ico": "image/x-icon",
+};
+export class PiWebServer {
+    session;
+    port;
+    staticDir;
+    uiContext;
+    httpServer = null;
+    wsServer = null;
+    clients = new Set();
+    unsubscribe = null;
+    constructor(session, options = {}) {
+        this.session = session;
+        this.port = options.port ?? DEFAULT_PORT;
+        this.staticDir = options.staticDir ?? STATIC_DIR;
+        this.uiContext = new WebUIContext((obj) => this.broadcast(obj));
+    }
+    // ------------------------------------------------------------------
+    // Lifecycle
+    // ------------------------------------------------------------------
+    async start() {
+        // Bind extensions with the web UI context (replaces the TUI/RPC context)
+        await this.session.bindExtensions({
+            uiContext: this.uiContext,
+            // "rpc" is the closest ExtensionMode: dialog-capable UI (hasUI=true),
+            // but not terminal-only UI
+            mode: "rpc",
+        });
+        this.httpServer = createServer((req, res) => this.handleHttp(req, res));
+        // Some components (ws internals, MCP-style extensions) accumulate 'close'
+        // listeners on the server; raise the limit to avoid MaxListenersExceededWarning
+        this.httpServer.setMaxListeners(50);
+        this.wsServer = new WebSocketServer({ server: this.httpServer, path: "/ws" });
+        this.wsServer.setMaxListeners(50);
+        this.wsServer.on("connection", (ws) => this.handleConnection(ws));
+        await new Promise((resolvePromise, reject) => {
+            this.httpServer.once("error", reject);
+            this.httpServer.listen(this.port, "127.0.0.1", () => resolvePromise());
+        });
+        // Forward session events to all browser clients
+        this.unsubscribe = this.session.subscribe((event) => {
+            this.broadcast(event);
+            if (STATS_REFRESH_EVENTS.has(event.type)) {
+                this.broadcastStats();
+            }
+        });
+    }
+    async stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        for (const client of this.clients) {
+            try {
+                client.close();
+            }
+            catch {
+                // ignore
+            }
+        }
+        this.clients.clear();
+        await new Promise((resolvePromise) => {
+            this.wsServer?.close(() => resolvePromise());
+            if (!this.wsServer)
+                resolvePromise();
+        });
+        await new Promise((resolvePromise) => {
+            this.httpServer?.close(() => resolvePromise());
+            if (!this.httpServer)
+                resolvePromise();
+        });
+    }
+    // ------------------------------------------------------------------
+    // Broadcast helpers
+    // ------------------------------------------------------------------
+    broadcast(obj) {
+        if (this.clients.size === 0)
+            return;
+        let message;
+        try {
+            message = JSON.stringify(obj);
+        }
+        catch {
+            return;
+        }
+        for (const client of this.clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(message);
+            }
+        }
+    }
+    broadcastStats() {
+        try {
+            const stats = this.session.getSessionStats();
+            this.broadcast({ type: "stats", data: stats });
+        }
+        catch {
+            // stats unavailable - skip
+        }
+    }
+    /** Broadcast the full state (model/thinking/session name) after mutations. */
+    broadcastState() {
+        try {
+            this.broadcast({ type: "state", data: this.buildState() });
+        }
+        catch {
+            // state unavailable - skip
+        }
+    }
+    // ------------------------------------------------------------------
+    // HTTP: static files
+    // ------------------------------------------------------------------
+    async handleHttp(req, res) {
+        if (req.method !== "GET") {
+            res.writeHead(405).end();
+            return;
+        }
+        let path = (req.url ?? "/").split("?")[0];
+        if (path === "/")
+            path = "/index.html";
+        const filePath = resolve(this.staticDir, "." + path);
+        if (!filePath.startsWith(resolve(this.staticDir))) {
+            res.writeHead(403).end();
+            return;
+        }
+        try {
+            const data = await readFile(filePath);
+            const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+            res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream" });
+            res.end(data);
+        }
+        catch {
+            res.writeHead(404).end();
+        }
+    }
+    // ------------------------------------------------------------------
+    // WebSocket: connection, initial state, client messages
+    // ------------------------------------------------------------------
+    handleConnection(ws) {
+        this.clients.add(ws);
+        ws.on("close", () => this.clients.delete(ws));
+        ws.on("error", () => this.clients.delete(ws));
+        ws.on("message", (data) => this.handleClientMessage(ws, String(data)));
+        // Initial state (state + history), mirroring the Python bridge
+        this.sendJson(ws, { type: "state", data: this.buildState() });
+        this.sendJson(ws, { type: "history", data: this.buildHistory() });
+    }
+    sendJson(ws, obj) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(obj));
+        }
+    }
+    buildState() {
+        const state = {
+            model: this.session.model,
+            thinkingLevel: this.session.thinkingLevel,
+            sessionId: this.session.sessionId,
+            sessionName: this.session.sessionManager.getSessionName(),
+            autoCompactionEnabled: this.session.autoCompactionEnabled,
+            messageCount: this.session.messages.length,
+            version: VERSION,
+            cwd: this.formatCwd(this.session.sessionManager.getCwd()),
+            gitBranch: this.getGitBranch(this.session.sessionManager.getCwd()),
+            commands: this.getCommands(),
+        };
+        try {
+            state.sessionStats = this.session.getSessionStats();
+        }
+        catch {
+            // ignore
+        }
+        return state;
+    }
+    buildHistory() {
+        try {
+            return {
+                entries: this.session.sessionManager.getEntries(),
+                leafId: this.session.sessionManager.getLeafId(),
+            };
+        }
+        catch {
+            return { entries: [], leafId: null };
+        }
+    }
+    formatCwd(cwd) {
+        const home = process.env.HOME ?? "";
+        if (home && (cwd === home || cwd.startsWith(home + "/"))) {
+            return "~" + cwd.slice(home.length);
+        }
+        return cwd;
+    }
+    getGitBranch(cwd) {
+        try {
+            const stdout = execFileSync("git", ["branch", "--show-current"], {
+                cwd,
+                timeout: 3000,
+                encoding: "utf8",
+                // execFileSync prints child stderr to our stderr on failure (e.g.
+                // "fatal: not a git repository" in non-git dirs) - suppress it
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            return stdout.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    getCommands() {
+        try {
+            // Mirror Pi's get_commands RPC response: extension commands, prompt
+            // templates, and skills (source: extension | prompt | skill)
+            const commands = [];
+            for (const c of this.session.extensionRunner.getRegisteredCommands()) {
+                commands.push({ name: c.invocationName, description: c.description, source: "extension", sourceInfo: c.sourceInfo });
+            }
+            for (const t of this.session.promptTemplates) {
+                commands.push({ name: t.name, description: t.description, source: "prompt", sourceInfo: t.sourceInfo });
+            }
+            for (const s of this.session.resourceLoader.getSkills().skills) {
+                commands.push({ name: `skill:${s.name}`, description: s.description, source: "skill", sourceInfo: s.sourceInfo });
+            }
+            return commands;
+        }
+        catch {
+            return [];
+        }
+    }
+    handleClientMessage(ws, raw) {
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            this.sendJson(ws, { type: "error", error: "Invalid JSON" });
+            return;
+        }
+        const cmdType = data.type;
+        if (typeof cmdType !== "string") {
+            this.sendJson(ws, { type: "error", error: "Missing 'type'" });
+            return;
+        }
+        this.dispatch(cmdType, data).catch((err) => {
+            this.sendJson(ws, { type: "error", error: err instanceof Error ? err.message : String(err) });
+        });
+    }
+    async dispatch(cmdType, data) {
+        switch (cmdType) {
+            case "prompt": {
+                const message = typeof data.message === "string" ? data.message : "";
+                if (!message)
+                    throw new Error("Missing 'message'");
+                await this.session.prompt(message);
+                break;
+            }
+            case "abort":
+                await this.session.abort();
+                break;
+            case "get_stats":
+                this.broadcastStats();
+                break;
+            case "bash": {
+                const command = typeof data.command === "string" ? data.command : "";
+                if (!command)
+                    throw new Error("Missing 'command'");
+                const excludeFromContext = data.excludeFromContext === true;
+                // Let extensions intercept/enhance the command (same as Pi RPC/TUI):
+                // user_bash handlers may provide a result or operations for execution.
+                const eventResult = await this.session.extensionRunner.emitUserBash({
+                    type: "user_bash",
+                    command,
+                    excludeFromContext,
+                    cwd: this.session.sessionManager.getCwd(),
+                });
+                if (eventResult?.result) {
+                    this.session.recordBashResult(command, eventResult.result, { excludeFromContext });
+                    this.broadcast({ type: "bash_result", command, data: eventResult.result });
+                    break;
+                }
+                const result = await this.session.executeBash(command, undefined, {
+                    excludeFromContext,
+                    operations: eventResult?.operations,
+                });
+                this.broadcast({ type: "bash_result", command, data: result });
+                break;
+            }
+            case "cycle_model":
+                await this.session.cycleModel();
+                this.broadcastState();
+                break;
+            case "set_model": {
+                const provider = data.provider;
+                const modelId = data.modelId;
+                if (!provider || !modelId)
+                    throw new Error("Missing 'provider' or 'modelId'");
+                const model = this.session.modelRuntime.getAvailableSnapshot().find((m) => m.provider === provider && m.id === modelId);
+                if (!model)
+                    throw new Error(`Model not found: ${provider}/${modelId}`);
+                await this.session.setModel(model);
+                this.broadcastState();
+                break;
+            }
+            case "get_available_models":
+                this.broadcast({ type: "models", data: this.session.modelRuntime.getAvailableSnapshot() });
+                break;
+            case "cycle_thinking_level":
+                this.session.cycleThinkingLevel();
+                this.broadcastState();
+                break;
+            case "set_thinking_level": {
+                const level = data.level;
+                if (!level)
+                    throw new Error("Missing 'level'");
+                this.session.setThinkingLevel(level);
+                this.broadcastState();
+                break;
+            }
+            case "get_available_thinking_levels":
+                this.broadcast({ type: "thinking_levels", data: this.session.getAvailableThinkingLevels() });
+                break;
+            case "compact":
+                await this.session.compact(typeof data.customInstructions === "string" ? data.customInstructions : undefined);
+                break;
+            case "reload":
+                // Align with TUI /reload: refuse while streaming or compacting
+                if (!this.session.isIdle)
+                    throw new Error("Wait for the current response to finish before reloading.");
+                if (this.session.isCompacting)
+                    throw new Error("Wait for compaction to finish before reloading.");
+                await this.session.reload();
+                this.broadcastState();
+                break;
+            case "export": {
+                const path = typeof data.path === "string" && data.path ? data.path : undefined;
+                const exportedPath = path?.endsWith(".jsonl")
+                    ? this.session.exportToJsonl(path)
+                    : await this.session.exportToHtml(path);
+                this.broadcast({
+                    type: "extension_ui_request",
+                    id: crypto.randomUUID(),
+                    method: "notify",
+                    title: "/export",
+                    message: `Session exported to: ${exportedPath}`,
+                    notifyType: "info",
+                });
+                break;
+            }
+            case "get_scoped_models":
+                this.broadcast({
+                    type: "scoped_models",
+                    data: {
+                        scoped: this.session.scopedModels.map((s) => ({
+                            provider: s.model.provider,
+                            id: s.model.id,
+                            thinkingLevel: s.thinkingLevel,
+                        })),
+                        available: this.session.modelRuntime.getAvailableSnapshot(),
+                    },
+                });
+                break;
+            case "set_scoped_models": {
+                const models = Array.isArray(data.models) ? data.models : [];
+                const resolved = [];
+                for (const m of models) {
+                    const provider = m.provider;
+                    const modelId = m.modelId;
+                    if (!provider || !modelId)
+                        continue;
+                    const model = this.session.modelRuntime
+                        .getAvailableSnapshot()
+                        .find((x) => x.provider === provider && x.id === modelId);
+                    if (model)
+                        resolved.push({ model, thinkingLevel: m.thinkingLevel });
+                }
+                this.session.setScopedModels(resolved);
+                this.broadcastState();
+                break;
+            }
+            case "set_session_name": {
+                const name = typeof data.name === "string" ? data.name : "";
+                if (!name)
+                    throw new Error("Missing 'name'");
+                this.session.setSessionName(name);
+                this.broadcastState();
+                break;
+            }
+            case "extension_ui_response": {
+                const id = typeof data.id === "string" ? data.id : "";
+                if (!id)
+                    throw new Error("Missing 'id'");
+                const extra = Object.fromEntries(Object.entries(data).filter(([k]) => k !== "type" && k !== "id"));
+                this.uiContext.respond(id, extra);
+                break;
+            }
+            case "command": {
+                const name = typeof data.name === "string" ? data.name : "";
+                const args = typeof data.args === "string" ? data.args : "";
+                if (!name)
+                    throw new Error("Missing 'name'");
+                await this.executeCommand(name, args);
+                break;
+            }
+            default:
+                throw new Error(`Unsupported command: ${cmdType}`);
+        }
+    }
+    /**
+     * Execute an extension slash command (e.g. /ctx-status) by invoking its
+     * registered handler with a command context.
+     *
+     * The context reports `hasUI: false` so extensions that offer a TUI dialog
+     * fall back to text output (e.g. magic-context's /ctx-status writes a custom
+     * session entry, which flows to the browser via entry_appended). Custom
+     * entries produced by the command are additionally shown as a browser
+     * modal (mirroring the TUI dialog behavior).
+     */
+    async executeCommand(name, args) {
+        const cmd = this.session.extensionRunner.getCommand(name);
+        if (!cmd)
+            throw new Error(`Unknown command: ${name}`);
+        // Capture custom entries appended while the command runs
+        const captured = [];
+        const listener = (event) => {
+            const ev = event;
+            if (ev.type === "entry_appended" && ev.entry?.type === "custom") {
+                captured.push({ customType: ev.entry.customType ?? "custom", data: ev.entry.data });
+            }
+        };
+        const unsubscribe = this.session.subscribe(listener);
+        try {
+            await cmd.handler(args, this.buildCommandContext());
+        }
+        finally {
+            unsubscribe();
+        }
+        // Show command output as a modal (TUI-like). The session entry remains
+        // for history; the modal is the transient presentation.
+        for (const entry of captured) {
+            const data = entry.data;
+            const message = data?.text ?? (data !== undefined ? JSON.stringify(data, null, 2) : "");
+            this.broadcast({
+                type: "extension_ui_request",
+                id: crypto.randomUUID(),
+                method: "notify",
+                title: data?.title ?? `/${name}`,
+                message,
+                notifyType: "info",
+            });
+        }
+    }
+    buildCommandContext() {
+        const sm = this.session.sessionManager;
+        return {
+            ui: this.uiContext,
+            // No dialog-capable UI: extension commands fall back to text output
+            mode: "print",
+            hasUI: false,
+            cwd: sm.getCwd(),
+            sessionManager: sm,
+            modelRegistry: new ModelRegistry(this.session.modelRuntime),
+            model: this.session.model,
+            scopedModels: [],
+            thinkingLevel: this.session.thinkingLevel,
+            isIdle: () => this.session.isIdle,
+            isProjectTrusted: () => true,
+            signal: undefined,
+            abort: () => {
+                void this.session.abort();
+            },
+            hasPendingMessages: () => this.session.pendingMessageCount > 0,
+            shutdown: () => { },
+            getContextUsage: () => this.session.getContextUsage(),
+            compact: (options) => {
+                void this.session.compact(options?.customInstructions);
+            },
+            getSystemPrompt: () => this.session.systemPrompt,
+            getSystemPromptOptions: () => ({}),
+            waitForIdle: () => this.session.waitForIdle(),
+            newSession: async () => ({ cancelled: true }),
+            fork: async () => ({ cancelled: true }),
+            navigateTree: async () => ({ cancelled: true }),
+            switchSession: async () => ({ cancelled: true }),
+            reload: async () => { },
+        };
+    }
+}