@evandu/super-pi 0.1.22 → 0.1.23

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-DkgwgGW6.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BndehVXj.css">
+    <script type="module" crossorigin src="/assets/index-LWO_0omC.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BKKZnCis.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/command-handler.d.ts

@@ -4,6 +4,7 @@ import type { ConversationService } from "./application/conversation-service.js"
 import type { RunService } from "./application/run-service.js";
 import type { ExtensionUiService } from "./application/extension-ui-service.js";
 import type { CatalogService } from "./application/catalog-service.js";
+import type { TerminalService } from "./terminal.js";
 export type SocketSender = (event: ServerEvent) => void;
 /**
  * Routes client commands to appropriate application services and converts results or errors.
@@ -14,9 +15,22 @@ export declare class CommandHandler {
     private readonly runService;
     private readonly extensionUiService;
     private readonly catalogService;
-    constructor(workspaceService: WorkspaceService, conversationService: ConversationService, runService: RunService, extensionUiService: ExtensionUiService, catalogService: CatalogService);
+    /**
+     * The terminal, or undefined when `SUPER_PI_TERMINAL` is off.
+     *
+     * Optional rather than always-present so that the common installation has no route to a shell AT ALL,
+     * not a route that refuses. `terminal-*` commands fall through to the unknown-command error when this
+     * is undefined, which is a refusal that names the command rather than one that pretends it exists.
+     */
+    private readonly terminalService?;
+    constructor(workspaceService: WorkspaceService, conversationService: ConversationService, runService: RunService, extensionUiService: ExtensionUiService, catalogService: CatalogService, terminalService?: TerminalService);
     /**
      * Processes a client command.
+     *
+     * `remoteAddress` is passed for the terminal alone. Every other command is authorised by the socket
+     * itself, which was already admitted at upgrade; the terminal additionally needs to know WHERE the
+     * connection came from, because it is the one command family whose blast radius is the whole machine
+     * rather than one workspace. See `TerminalService.handle`.
      */
-    handleCommand(command: ClientCommand, sendToSocket?: SocketSender): Promise<string | void>;
+    handleCommand(command: ClientCommand, sendToSocket?: SocketSender, remoteAddress?: string): Promise<string | void>;
 }

package/dist/server/command-handler.js

@@ -7,17 +7,39 @@ export class CommandHandler {
     runService;
     extensionUiService;
     catalogService;
-    constructor(workspaceService, conversationService, runService, extensionUiService, catalogService) {
+    /**
+     * The terminal, or undefined when `SUPER_PI_TERMINAL` is off.
+     *
+     * Optional rather than always-present so that the common installation has no route to a shell AT ALL,
+     * not a route that refuses. `terminal-*` commands fall through to the unknown-command error when this
+     * is undefined, which is a refusal that names the command rather than one that pretends it exists.
+     */
+    terminalService;
+    constructor(workspaceService, conversationService, runService, extensionUiService, catalogService, terminalService) {
         this.workspaceService = workspaceService;
         this.conversationService = conversationService;
         this.runService = runService;
         this.extensionUiService = extensionUiService;
         this.catalogService = catalogService;
+        this.terminalService = terminalService;
     }
     /**
      * Processes a client command.
+     *
+     * `remoteAddress` is passed for the terminal alone. Every other command is authorised by the socket
+     * itself, which was already admitted at upgrade; the terminal additionally needs to know WHERE the
+     * connection came from, because it is the one command family whose blast radius is the whole machine
+     * rather than one workspace. See `TerminalService.handle`.
      */
-    async handleCommand(command, sendToSocket) {
+    async handleCommand(command, sendToSocket, remoteAddress) {
+        if (command.type === "terminal.open" || command.type === "terminal.input" || command.type === "terminal.resize" || command.type === "terminal.close") {
+            if (!this.terminalService) {
+                sendToSocket?.({ type: "terminal.status", enabled: false, reason: "终端未启用。设置 SUPER_PI_TERMINAL=1 后重启 Super Pi 即可使用。" });
+                return;
+            }
+            await this.terminalService.handle(command, remoteAddress, sendToSocket ?? (() => { }));
+            return;
+        }
         if (command.type === "model.rules.set") {
             await this.catalogService.setModelRules(command.rules);
             return;

package/dist/server/http-server.js

@@ -140,6 +140,15 @@ export function createHttpServer(options) {
         }
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
         const remote = request.socket.remoteAddress ?? "";
+        /**
+         * THE TERMINAL IS NOT AN API ENDPOINT, and the routing above deliberately cannot reach one.
+         *
+         * Every command family in `CommandHandler` is answerable over plain HTTP except the terminal, which
+         * is WebSocket-only (`terminal.*` messages). `serverContext` therefore carries only the two
+         * predicates `/api/terminal` needs - is it on, and if not why - and NOT a handle on `TerminalService`.
+         * There is consequently no code path from an HTTP request to a spawned shell, which is the property
+         * worth having: the browser's own origin could not reach it even with a forged request.
+         */
         if (url.pathname === "/api/memory/tool" || url.pathname === "/api/memory") {
             if (!context.memory) {
                 response.writeHead(503).end();
@@ -188,6 +197,24 @@ export function createHttpServer(options) {
                 .end(JSON.stringify({ status: "ok", service: "super-pi", ...version }));
             return;
         }
+        /**
+         * WHETHER THE TERMINAL EXISTS, as a plain GET rather than part of the `state` snapshot.
+         *
+         * It is deployment configuration, not application state: it does not change while the server runs,
+         * it is identical for every workspace, and putting it on `state` would drag it into the persistence
+         * layer and into every existing snapshot schema for no benefit. A `GET` also means the right rail
+         * can decide whether to RENDER the tab at all - and not rendering it is the point, because a tab
+         * that is present and refuses is a tab that invites a user to keep clicking a closed door.
+         *
+         * No address check: this leaks nothing beyond "is this build configured for a shell", which is
+         * already printed in the server's own startup banner to whoever can see the console.
+         */
+        if (url.pathname === "/api/terminal") {
+            const enabled = context.terminalEnabled?.() ?? false;
+            response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
+                .end(JSON.stringify({ enabled, reason: enabled ? "" : (context.terminalDisabledReason?.() ?? "终端未启用。") }));
+            return;
+        }
         if (url.pathname === "/api/subagent/dispatch") {
             if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
                 response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Sub-agent dispatch requires a loopback or private network POST");

package/dist/server/index.js

@@ -17,7 +17,8 @@ import { RunService } from "./application/run-service.js";
 import { ConversationService } from "./application/conversation-service.js";
 import { WorkspaceService } from "./application/workspace-service.js";
 import { CommandHandler } from "./command-handler.js";
-import { createHttpServer, getLanIps, parseServerArgs } from "./http-server.js";
+import { TerminalService, terminalDisabledReason } from "./terminal.js";
+import { createHttpServer, getLanIps, isLocalOrPrivateAddress, parseServerArgs } from "./http-server.js";
 import { WsBroadcaster, WsServer } from "./ws-server.js";
 import { initRunningVersion } from "./version.js";
 // ------------------------------------------------------------- Environment & paths
@@ -114,6 +115,19 @@ const runService = new RunService(store, runtime, subagents, broadcaster, extens
 runService.setMemory(memory);
 const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
 const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, initialAgentDirs);
+/**
+ * The terminal, constructed before `serverContext` because that object carries the two predicates
+ * `/api/terminal` answers with.
+ *
+ * Constructed UNCONDITIONALLY so the service exists to answer a refusal with a sentence, but it re-checks
+ * `SUPER_PI_TERMINAL` internally, so construction and `/api/terminal` cannot disagree. The workspace
+ * lookup goes through `store` rather than through the command body so that `terminal.open` has no path
+ * field to fill in, which is the structural half of the containment story documented in `terminal.ts`.
+ */
+const terminalService = new TerminalService({
+    workspaceFor: (workspaceId) => store.snapshot().workspaces.find((workspace) => workspace.id === workspaceId),
+    isTrustedPeer: (remoteAddress) => isLocalOrPrivateAddress(remoteAddress),
+});
 const serverContext = {
     memory,
     paths,
@@ -127,8 +141,10 @@ const serverContext = {
     runService,
     extensionUiService,
     catalogService,
+    terminalEnabled: () => terminalService.enabled,
+    terminalDisabledReason: () => terminalDisabledReason(),
 };
-const commandHandler = new CommandHandler(workspaceService, conversationService, runService, extensionUiService, catalogService);
+const commandHandler = new CommandHandler(workspaceService, conversationService, runService, extensionUiService, catalogService, terminalService);
 // ------------------------------------------------------------- Lifecycle & shutdown
 let shutdownPromise;
 async function closeHttpServer() {
@@ -142,6 +158,8 @@ async function shutdown(reason) {
         // Stop accepting new connections first. Existing clients stay connected until
         // their cancelled work has recorded its terminal state.
         const httpClosed = closeHttpServer();
+        // Kill every shell BEFORE the sockets close, so a PTY is never outlived by the server that owns it.
+        terminalService.closeAll();
         runService.abortAll();
         workflows.abortAll();
         releaseAllCapabilities();
@@ -161,7 +179,22 @@ process.on("SIGINT", () => { void shutdown("SIGINT").finally(() => process.exit(
 process.on("SIGTERM", () => { void shutdown("SIGTERM").finally(() => process.exit(0)); });
 // ------------------------------------------------------------- Transports & startup
 const httpServer = createHttpServer({ context: serverContext, onShutdown: shutdown });
-const wsServer = new WsServer({ httpServer, broadcaster, commandHandler, catalogService, accessToken, rootDir });
+const wsServer = new WsServer({
+    httpServer,
+    broadcaster,
+    commandHandler,
+    catalogService,
+    accessToken,
+    rootDir,
+    // Closing a tab must close its shells. Routed through the service rather than reaching into it so the
+    // per-session bookkeeping (output flush, pending timer) still runs - `closeAll` is for shutdown, not
+    // for one socket's worth of sessions.
+    onSocketClose: (sessionIds) => {
+        for (const sessionId of sessionIds) {
+            terminalService.handle({ type: "terminal.close", sessionId }, "127.0.0.1", () => { });
+        }
+    },
+});
 httpServer.listen(port, host, () => {
     const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
     console.log(`Super Pi is running at http://${displayHost}:${port}`);
@@ -171,4 +204,12 @@ httpServer.listen(port, host, () => {
             console.log(`  - Network: http://${ip}:${port}`);
         }
     }
+    // Stated in the banner rather than left to be discovered, because the terminal is a SHELL and the
+    // operator should never have to read the source to find out one is exposed on this machine.
+    if (terminalService.enabled) {
+        console.log("  - Terminal: enabled (SUPER_PI_TERMINAL) - the right rail's 终端 tab runs a real shell.");
+    }
+    else {
+        console.log("  - Terminal: disabled. Set SUPER_PI_TERMINAL=1 and restart to enable the 终端 tab.");
+    }
 });

package/dist/server/persistence/sqlite-state-repository.js

@@ -21,6 +21,8 @@ export class SqliteStateRepository {
             Object.assign(state, { [String(overlay.name)]: JSON.parse(String(overlay.json)) });
         }
         const messages = this.db.prepare("SELECT json FROM messages WHERE conversation=?");
+        if (!Array.isArray(state.conversations))
+            state.conversations = [];
         for (const conversation of state.conversations) {
             const metadata = this.db.prepare("SELECT json FROM metadata WHERE conversation=?").get(conversation.id);
             if (metadata) {
@@ -33,6 +35,8 @@ export class SqliteStateRepository {
                 const message = JSON.parse(String(r.json));
                 return [message.id, message];
             }));
+            if (!Array.isArray(conversation.messages))
+                conversation.messages = [];
             conversation.messages = conversation.messages.map(message => overrides.get(message.id) ?? message);
             // Timestamp overlays are stored beside the base conversation metadata.
             const stamp = this.db.prepare("SELECT stamp FROM timestamps WHERE conversation=?").get(conversation.id);
@@ -40,6 +44,27 @@ export class SqliteStateRepository {
                 conversation.updatedAt = String(stamp.stamp);
         }
         const runs = new Map(this.db.prepare("SELECT id,json FROM runs").all().map(r => [String(r.id), JSON.parse(String(r.json))]));
+        /**
+         * WHY THESE TWO ARE RE-CHECKED HERE, AND THE UPGRADE THEY PROTECT.
+         *
+         * `state.json` is the LEGACY store, and `openStateStore` imports one into an empty database verbatim.
+         * A state written by a Super Pi older than sub-agent dispatch has no `subagentRuns` key at all, so
+         * `state.subagentRuns.map` threw `Cannot read properties of undefined (reading 'map')` and the server
+         * exited 1 on its very first `load` - before the HTTP listener existed, so there was no page, no
+         * error in the UI, and nothing to retry. An upgrade that cannot start is the worst failure this
+         * project can ship.
+         *
+         * The same applies to `conversations` just above, for a state written before conversations existed.
+         * Both are defaulted to `[]` rather than repaired, because an absent collection is genuinely empty:
+         * there is nothing to invent, and `Store.openRepository` already reconciles a real (if empty) list.
+         *
+         * NOTE THAT NO BROWSER TEST COULD HAVE CAUGHT THIS. `scripts/run-check.mjs` runs the whole browser
+         * batch with `SUPER_PI_PERSISTENCE=json`, so every browser suite takes the JSON repository and the
+         * SQLite import path is never executed by the suite. It was found by running one of those suites
+         * standalone, which is the only way the SQLite default is ever used.
+         */
+        if (!Array.isArray(state.subagentRuns))
+            state.subagentRuns = [];
         state.subagentRuns = state.subagentRuns.map(run => runs.get(run.id) ?? run);
         return state;
     }

package/dist/server/server-context.d.ts

@@ -45,4 +45,15 @@ export interface ServerContext {
     runService: RunService;
     extensionUiService: ExtensionUiService;
     catalogService: CatalogService;
+    /**
+     * Whether the right rail's terminal tab should exist, and why not when it should not.
+     *
+     * TWO PREDICATES AND NOT A `TerminalService` HANDLE, and that is the load-bearing part. `/api/terminal`
+     * only ever needs to answer "is it on"; handing the HTTP layer the service itself would put a
+     * `spawn` within reach of a GET request, and the terminal is the one part of this server that is not
+     * confined to a workspace. Keeping the handle on `CommandHandler` alone means the only route to a
+     * shell is a WebSocket message that `TerminalService.assertUsable` has already vetted.
+     */
+    terminalEnabled?: () => boolean;
+    terminalDisabledReason?: () => string;
 }

package/dist/server/terminal.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The right rail's terminal, as a SERVER-SIDE SESSION MANAGER.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS AT ALL, stated plainly because it is the most consequential file in the project
+ * ---------------------------------------------------------------------------------------------
+ *
+ * Everything else in Super Pi is a control plane for a MODEL. This file hands a browser a SHELL on the
+ * machine Super Pi runs on. That is categorically different in kind, not in degree: a chat message can
+ * at worst make the model write a file inside a workspace, whereas one keystroke here runs whatever the
+ * user typed, with the full privileges of the server process, with no workspace containment and no
+ * capability scope.
+ *
+ * The server binds `0.0.0.0` by default (see `index.ts`), which exists so a phone on the same Wi-Fi can
+ * reach Super Pi without an SSH tunnel. Combined with a shell, that turns "anyone on the LAN who can
+ * open a web page" into "anyone on the LAN who can open a web page has a root-or-you shell". The
+ * project already knows this shape of problem - `http-server.ts` guards file writes and uploads behind
+ * `isLocalOrPrivateAddress` for exactly this reason - but a file write is bounded by the workspace root
+ * and this is not.
+ *
+ * So the guards here are deliberately redundant, and each one closes a hole the others do not:
+ *
+ *   1. OPT-IN, OFF BY DEFAULT. `SUPER_PI_TERMINAL` must be set to `1`/`true`/`on` before a single shell
+ *      is spawned. The default install has no terminal at all - the tab is not even rendered. Enabling
+ *      it is a deliberate act by someone who knows what it does.
+ *   2. NETWORK SCOPE. Even enabled, a command is refused unless the WebSocket arrived from loopback or
+ *      an RFC 1918 / link-local / ULA address (`isLocalOrPrivateAddress`, the same predicate the file
+ *      endpoints use). A request that arrives from a routed or proxied address is refused by name.
+ *   3. THE BROWSER NEVER CHOOSES THE WORKING DIRECTORY. `terminal.open` carries a WORKSPACE ID and
+ *      nothing else; this file resolves the id against the store and spawns in that workspace's path.
+ *      A browser that asked for `C:\` or `/etc` gets its own workspace's directory instead, because
+ *      there is no code path on which a client-supplied path reaches `spawn`.
+ *   4. BOUNDED SESSIONS. `MAX_SESSIONS` shells, one per client tab, capped so a loop of reconnects
+ *      cannot accumulate processes.
+ *
+ * What is NOT here is a per-command allowlist. A terminal that refuses `rm` or `curl` is not a terminal,
+ * and pretending otherwise would be worse than the honest version: with (1) and (2) the operator has
+ * chosen to expose a shell to their own LAN, and from there every command is the operator's own.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * WHY `node-pty` AND NOT `child_process.spawn`
+ * ---------------------------------------------------------------------------------------------
+ *
+ * `spawn("bash", { stdio: "pipe" })` gives a program three pipes and no terminal. Programs that ask
+ * whether stdout is a TTY take the "I am being piped" branch and behave differently: no colours, no
+ * progress bars, and `vim` / `top` / `less` refuse outright with "not a terminal". A terminal panel
+ * that cannot run those is a command runner wearing a terminal's clothes.
+ *
+ * `node-pty` allocates a real pseudo-terminal (ConPTY on Windows, `forkpty` elsewhere), which is the
+ * only way to get them. The cost is a native module, and it is paid only by operators who set
+ * `SUPER_PI_TERMINAL=1` - see `loadPty` below, which is reached lazily and never at import time.
+ */
+import type { ServerEvent, Workspace } from "./types.js";
+/** One shell per browser tab, and a hard ceiling so reconnects cannot accumulate processes. */
+export declare const MAX_SESSIONS = 8;
+/**
+ * The terminal's wire protocol, as members of the EXISTING `ClientCommand` / `ServerEvent` unions rather
+ * than a second transport.
+ *
+ * Reusing the command channel is what makes this feature cheap to wire: the WebSocket already carries
+ * authentication, and `ws-server.ts` already answers exactly one socket. A parallel HTTP endpoint with
+ * server-sent events would have had to re-implement both, and the terminal's traffic is bidirectional -
+ * keystrokes have to flow back the same way output does.
+ */
+export type TerminalCommand = {
+    type: "terminal.open";
+    sessionId: string;
+    workspaceId: string;
+    cols?: number;
+    rows?: number;
+} | {
+    type: "terminal.input";
+    sessionId: string;
+    data: string;
+} | {
+    type: "terminal.resize";
+    sessionId: string;
+    cols: number;
+    rows: number;
+} | {
+    type: "terminal.close";
+    sessionId: string;
+};
+export type TerminalEvent = {
+    type: "terminal.output";
+    sessionId: string;
+    data: string;
+} | {
+    type: "terminal.exit";
+    sessionId: string;
+    exitCode: number;
+} | {
+    type: "terminal.error";
+    sessionId: string;
+    message: string;
+} | {
+    type: "terminal.status";
+    enabled: boolean;
+    reason?: string;
+};
+/**
+ * Reads the opt-in flag. Anything other than an explicit truthy string leaves the terminal OFF, so a
+ * typo in a deployment config fails closed rather than silently exposing a shell.
+ */
+export declare function isTerminalEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The sentence a browser shows when the terminal is missing. Says WHICH of the three gates closed. */
+export declare function terminalDisabledReason(env?: NodeJS.ProcessEnv): string;
+export declare class TerminalService {
+    private readonly sessions;
+    private readonly workspaceFor;
+    /** Whether a command from this peer is allowed to touch a shell at all. */
+    private readonly isTrustedPeer;
+    constructor(options: {
+        workspaceFor: (workspaceId: string) => Workspace | undefined;
+        isTrustedPeer: (remoteAddress: string | undefined) => boolean;
+        enabled?: boolean;
+    });
+    readonly enabled: boolean;
+    /**
+     * WHY THE PEER CHECK LIVES ON EVERY COMMAND AND NOT ONLY ON `open`.
+     *
+     * The obvious implementation authorises `terminal.open` and then trusts the session. That leaves a
+     * live shell reachable by a socket opened BEFORE the address changed - and, on this server, the
+     * browser is same-origin on whatever host it was opened from, so a user who tunnels in, opens a
+     * terminal, and then forwards their port to a colleague has silently widened the audience for every
+     * keystroke that follows.
+     *
+     * `isTrustedPeer` is re-evaluated per command. It is a pure function of the socket's remote address,
+     * so the cost is one predicate per keystroke and the guarantee is that no session outlives its
+     * socket's authorisation.
+     */
+    private assertUsable;
+    handle(command: TerminalCommand, remoteAddress: string | undefined, send: (event: ServerEvent) => void): Promise<void>;
+    private enqueue;
+    private flush;
+    private kill;
+    /** Every shell, for shutdown. Exits without reporting anything - the server is going away. */
+    closeAll(): void;
+}