@cjhyy/code-shell-server 0.8.0

package/dist/serve/cli.js

@@ -0,0 +1,115 @@
+// packages/server/src/serve/cli.ts
+//
+// `code-shell-serve` — boot the headless no-account web host from a terminal:
+//
+//   code-shell-serve --cwd ~/work/repo [--port 8790] [--host 127.0.0.1]
+//                    [--passcode <code>] [--data-dir <dir>]
+//
+// Access control is passcode + remember-cookie only (决策见 TODO 约束边界
+// 「服务端部署不做账号体系」). Default bind is loopback; binding 0.0.0.0 is a
+// deliberate operator choice.
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { startHeadlessServer } from "./headless-server.js";
+const SERVE_HELP = `Usage: code-shell-serve [options]
+
+Run the CodeShell headless Web host for a workspace.
+
+Options:
+  --cwd <path>         Workspace root (default: current directory)
+  --host <host>        Bind host (default: 127.0.0.1)
+  --port <port>        Bind port, 0 selects a free port (default: 8790)
+  --passcode <code>    Set or rotate the access passcode
+  --data-dir <path>    Access-control data directory
+  --static-root <path> Override the built Web app directory
+  -h, --help           Show this help and exit`;
+const VALUE_FLAGS = new Set([
+    "--cwd",
+    "--host",
+    "--port",
+    "--passcode",
+    "--data-dir",
+    "--static-root",
+]);
+export function parseServeArgs(argv, env = process.env) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const key = argv[i];
+        if (!key || !VALUE_FLAGS.has(key)) {
+            throw new Error(`unknown argument: ${key ?? ""}\n\n${SERVE_HELP}`);
+        }
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith("--")) {
+            throw new Error(`missing value for ${key}\n\n${SERVE_HELP}`);
+        }
+        args[key.slice(2)] = value;
+        i++;
+    }
+    const home = env.CODE_SHELL_HOME || join(homedir(), ".code-shell");
+    const port = Number(args.port ?? "8790");
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`invalid --port: ${args.port}`);
+    }
+    return {
+        cwd: resolve(args.cwd ?? process.cwd()),
+        host: args.host ?? "127.0.0.1",
+        port,
+        ...(args.passcode ? { passcode: args.passcode } : {}),
+        dataDir: args["data-dir"] ? resolve(args["data-dir"]) : join(home, "serve"),
+        ...(args["static-root"] ? { staticRootDir: resolve(args["static-root"]) } : {}),
+    };
+}
+/** Locate the stdio worker entry the same way desktop's AgentBridge does. */
+export function resolveWorkerEntry() {
+    const require = createRequire(import.meta.url);
+    return require.resolve("@cjhyy/code-shell-capability-coding/bin/agent-server-stdio");
+}
+/** Locate the built browser app (packages/web `app` build), when present. */
+export function resolveWebAppRoot() {
+    try {
+        const require = createRequire(import.meta.url);
+        // package.json is exposed via the web package's exports map exactly so a
+        // CJS-style resolve (createRequire) can locate the package root; dist-app
+        // is the app build output sibling.
+        const pkgJson = require.resolve("@cjhyy/code-shell-web/package.json");
+        const candidate = join(pkgJson, "..", "dist-app");
+        return existsSync(candidate) ? candidate : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runServeCli(argv = process.argv.slice(2)) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(SERVE_HELP);
+        return;
+    }
+    const parsed = parseServeArgs(argv);
+    const staticRootDir = parsed.staticRootDir ?? resolveWebAppRoot();
+    const server = await startHeadlessServer({
+        host: parsed.host,
+        port: parsed.port,
+        cwd: parsed.cwd,
+        dataDir: parsed.dataDir,
+        workerEntryPath: resolveWorkerEntry(),
+        ...(staticRootDir ? { staticRootDir } : {}),
+        ...(parsed.passcode ? { passcode: parsed.passcode } : {}),
+        log: (event, data) => console.error(`[serve] ${event}${data ? ` ${JSON.stringify(data)}` : ""}`),
+    });
+    console.log(`CodeShell web host listening at ${server.url}`);
+    console.log(`Workspace: ${parsed.cwd}`);
+    if (!staticRootDir) {
+        console.log("No web app build found — WS endpoint only (/ws). Build packages/web first.");
+    }
+    if (server.generatedPasscode) {
+        console.log(`Access passcode (generated, save it now): ${server.generatedPasscode}`);
+    }
+    const shutdown = () => {
+        console.log("shutting down…");
+        void server.close().then(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}

package/dist/serve/headless-server.d.ts

@@ -0,0 +1,40 @@
+import { AccessPasscode } from "../mobile-remote/access-passcode.js";
+import { WorkerBridgeCore, type WorkerBridgeLog } from "../worker-bridge-core.js";
+export interface HeadlessServeOptions {
+    /** Bind host. Default 127.0.0.1 — expose beyond loopback deliberately. */
+    host?: string;
+    /** Bind port. 0 picks an ephemeral port (tests). Default 8790. */
+    port?: number;
+    /** Workspace root the agent worker runs in. */
+    cwd: string;
+    /** Directory for serve state (access.json). */
+    dataDir: string;
+    /** Absolute path of the agent-server-stdio worker entry. */
+    workerEntryPath: string;
+    /** Session root override for tests/relocated workers. Defaults to core's canonical root. */
+    sessionRootDir?: string;
+    /** Runtime binary for the worker; defaults to process.execPath. */
+    execPath?: string;
+    /** Built web app root; when absent the server is WS/API-only. */
+    staticRootDir?: string;
+    /**
+     * Set (rotate) the access passcode at boot. When omitted and none is
+     * configured yet, a random one is generated and returned in
+     * `generatedPasscode` — the CLI prints it once.
+     */
+    passcode?: string;
+    log?: WorkerBridgeLog;
+}
+export interface HeadlessServer {
+    url: string;
+    host: string;
+    port: number;
+    /** Present only when this boot had to generate a fresh passcode. */
+    generatedPasscode?: string;
+    passcode: AccessPasscode;
+    bridge: WorkerBridgeCore;
+    /** Live authenticated tab count (for tests/status). */
+    tabCount(): number;
+    close(): Promise<void>;
+}
+export declare function startHeadlessServer(opts: HeadlessServeOptions): Promise<HeadlessServer>;

package/dist/serve/headless-server.js

@@ -0,0 +1,276 @@
+// packages/server/src/serve/headless-server.ts
+//
+// Headless serve entry — the no-account web host (TODO「服务端部署 + Web
+// Client（无账号体系）」Phase 1').
+//
+// Composition, all pre-existing parts:
+//   - AccessPasscode        HTTP gate (challenge page) + WS `allows()`;
+//                           passcode + remember-cookie is the ONLY access
+//                           control — no AuthN/AuthZ, no users, by decision.
+//   - WorkerBridgeCore      spawns/drives ONE agent-server-stdio worker.
+//   - resolveSafe           path-traversal-safe static file resolution.
+//
+// The browser speaks the CORE protocol (agent/run, agent/approve,
+// agent/streamEvent, …) as a first-party front end: this module is a thin
+// WS ↔ worker-stdio pipe, NOT a re-implementation of the desktop mobile
+// orchestrator. Every authenticated tab sees the identical line stream
+// (same semantics as AgentBridge's renderer fan-out).
+//
+// Restart recovery: sessions persist on disk in the worker's data dir; a
+// server restart spawns a fresh worker on the first inbound frame and the
+// browser re-lists sessions over the same protocol.
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { SessionManager } from "@cjhyy/code-shell-core";
+import { AccessPasscode } from "../mobile-remote/access-passcode.js";
+import { resolveSafe } from "../mobile-remote/mobile-static.js";
+import { contentTypeFor } from "../static-files.js";
+import { WorkerBridgeCore, previewLine } from "../worker-bridge-core.js";
+export async function startHeadlessServer(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const log = opts.log ?? (() => { });
+    const workspaceCwd = resolve(opts.cwd);
+    const sessionManager = new SessionManager(opts.sessionRootDir);
+    const passcode = new AccessPasscode({ filePath: join(opts.dataDir, "access.json") });
+    let generatedPasscode;
+    if (opts.passcode) {
+        passcode.set(opts.passcode);
+    }
+    else if (!passcode.isSet()) {
+        generatedPasscode = randomBytes(6).toString("base64url");
+        passcode.set(generatedPasscode);
+    }
+    const tabs = new Set();
+    const broadcast = (line) => {
+        for (const tab of tabs) {
+            if (tab.readyState === tab.OPEN)
+                tab.send(line);
+        }
+    };
+    const bridge = new WorkerBridgeCore({
+        entryPath: opts.workerEntryPath,
+        execPath: opts.execPath,
+        fallbackCwd: () => opts.cwd,
+        log,
+        onStderr: (text) => log("worker.stderr", { text: previewLine(text) }),
+        onExit: (info) => {
+            // Synthetic serve-level notification so the UI can show "agent worker
+            // stopped" without conflating it with in-protocol agent/status.
+            broadcast(JSON.stringify({
+                jsonrpc: "2.0",
+                method: "serve/workerExit",
+                params: { clean: info.clean, gaveUp: info.gaveUp },
+            }));
+        },
+    });
+    bridge.subscribeLines(broadcast);
+    const serveStatic = (req, res) => {
+        const root = opts.staticRootDir;
+        if (!root) {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("no web app bundled; WS endpoint at /ws");
+            return;
+        }
+        const pathname = decodeSafely(new URL(req.url ?? "/", "http://localhost").pathname);
+        if (pathname === null) {
+            res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+            res.end("bad path");
+            return;
+        }
+        let filePath = pathname === "/" ? null : resolveSafe(root, pathname.replace(/^\//, ""));
+        if (filePath === null || !existsSync(filePath)) {
+            // SPA fallback: any unknown (or traversal-rejected) HTML navigation gets
+            // index.html; non-navigation asset misses stay 404.
+            const accept = req.headers.accept ?? "";
+            const wantsHtml = typeof accept === "string" && accept.includes("text/html");
+            if (!wantsHtml && pathname !== "/") {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("not found");
+                return;
+            }
+            filePath = join(root, "index.html");
+            if (!existsSync(filePath)) {
+                res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+                res.end("web app not built");
+                return;
+            }
+        }
+        try {
+            const body = readFileSync(filePath);
+            res.writeHead(200, {
+                "content-type": contentTypeFor(extname(filePath)),
+                "cache-control": "no-cache",
+            });
+            res.end(body);
+        }
+        catch {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("not found");
+        }
+    };
+    const server = createServer((req, res) => {
+        // The passcode gate fronts EVERY route — same posture as the tunnel mode
+        // of the mobile remote host. gate() renders the challenge page for HTML
+        // navigations and sets the remember cookie on success.
+        if (!passcode.gate(req, res))
+            return;
+        serveStatic(req, res);
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    server.on("upgrade", (req, socket, head) => {
+        const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (pathname !== "/ws" || !passcode.allows(req)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            tabs.add(ws);
+            log("tab.connected", { tabs: tabs.size });
+            ws.on("message", (data) => {
+                const line = String(data);
+                // Validate framing before touching the worker: a malformed frame from
+                // one tab must never kill the shared pipe.
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    log("tab.frame_dropped", { reason: "not json", raw: previewLine(line) });
+                    return;
+                }
+                if (!parsed || parsed.jsonrpc !== "2.0") {
+                    log("tab.frame_dropped", { reason: "not jsonrpc", raw: previewLine(line) });
+                    return;
+                }
+                const hostReply = replyToHostSessionQuery(parsed, sessionManager, workspaceCwd);
+                if (hostReply) {
+                    ws.send(hostReply);
+                    return;
+                }
+                // This host intentionally exposes one workspace. A browser must not be
+                // able to escape it by supplying another cwd, and a missing cwd must
+                // not silently become the worker's global no-repo conversation.
+                const workerLine = parsed.method === "agent/run"
+                    ? JSON.stringify({
+                        ...parsed,
+                        params: { ...(parsed.params ?? {}), cwd: workspaceCwd },
+                    })
+                    : line;
+                // Spawn-on-first-frame (idempotent): the browser's first request wakes
+                // the worker, mirroring the renderer's spawn-on-agent/run semantics.
+                bridge.ensureWorker(opts.cwd);
+                bridge.injectWorkerMessage(workerLine);
+            });
+            ws.on("close", () => {
+                tabs.delete(ws);
+                log("tab.closed", { tabs: tabs.size });
+            });
+            ws.on("error", () => {
+                tabs.delete(ws);
+            });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port ?? 8790, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : (opts.port ?? 8790);
+    const url = `http://${host}:${port}`;
+    log("serve.listening", { url });
+    return {
+        url,
+        host,
+        port,
+        ...(generatedPasscode ? { generatedPasscode } : {}),
+        passcode,
+        bridge,
+        tabCount: () => tabs.size,
+        close: async () => {
+            for (const tab of tabs) {
+                try {
+                    tab.terminate();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            tabs.clear();
+            bridge.kill();
+            await new Promise((resolve) => {
+                wss.close(() => {
+                    server.close(() => resolve());
+                });
+                // server.close() alone waits out keep-alive HTTP sockets forever;
+                // drop them so shutdown is prompt.
+                server.closeAllConnections?.();
+            });
+        },
+    };
+}
+function replyToHostSessionQuery(message, sessionManager, workspaceCwd) {
+    if (message.method !== "agent/query" || message.id === undefined)
+        return undefined;
+    const queryType = message.params?.type;
+    if (queryType === "sessions") {
+        const sessions = sessionManager
+            .list()
+            .filter((session) => resolve(session.cwd) === workspaceCwd)
+            .map((session) => ({
+            sessionId: session.sessionId,
+            cwd: session.cwd,
+            startedAt: session.startedAt,
+            model: session.model,
+            status: session.status,
+            turnCount: session.turnCount,
+            ...(session.preview ? { preview: session.preview } : {}),
+        }));
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id: message.id,
+            result: { type: "sessions", data: sessions },
+        });
+    }
+    if (queryType !== "session_detail")
+        return undefined;
+    const sessionId = message.params?.sessionId;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        return hostQueryError(message.id, -32602, "sessionId required for session_detail");
+    }
+    try {
+        const bundle = sessionManager.resume(sessionId);
+        if (resolve(bundle.state.cwd) !== workspaceCwd) {
+            return hostQueryError(message.id, -32001, "Session not found in this workspace");
+        }
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id: message.id,
+            result: {
+                type: "session_detail",
+                data: { state: bundle.state, transcript: bundle.transcript.getEvents() },
+            },
+        });
+    }
+    catch (error) {
+        return hostQueryError(message.id, -32001, error instanceof Error ? error.message : "Session not found");
+    }
+}
+function hostQueryError(id, code, message) {
+    return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+/** decodeURIComponent that returns null instead of throwing on bad input. */
+function decodeSafely(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/sessions-service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * List session files persisted by the agent worker.
+ * Uses core's canonical session root so CODE_SHELL_HOME matches the worker.
+ */
+import { type TurnCompletionKind } from "@cjhyy/code-shell-core";
+export interface DesktopSessionSummary {
+    id: string;
+    /** Path to the session file on disk. */
+    file: string;
+    size: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare function listSessions(baseDir?: string): Promise<DesktopSessionSummary[]>;
+/**
+ * Remove a session's on-disk data. Modern sessions are a directory
+ * `<sessionsDir>/<id>/` (transcript.jsonl + state.json — see core
+ * session-manager.ts:93,141). Pre-directory sessions were flat
+ * `<id>.jsonl`/`<id>.json` files; we remove those too for back-compat.
+ * `baseDir` is overridable for tests. Unsafe ids (slashes / "." / "..")
+ * are rejected without any filesystem access.
+ */
+export declare function deleteSessionDir(id: string, baseDir?: string): Promise<void>;
+/** @deprecated retained for the existing IPC handler; delegates to deleteSessionDir. */
+export declare function deleteSession(id: string): Promise<void>;
+/**
+ * Reap quick-chat data left by an unclean prior desktop exit. This must run
+ * before a new renderer/worker can claim a qchat id; normal live cleanup is
+ * coordinated by QuickChatOwnershipRegistry instead.
+ */
+export declare function cleanupStaleQuickChatSessions(baseDir?: string): Promise<string[]>;
+export interface DiskSessionMeta {
+    id: string;
+    engineSessionId: string;
+    cwd: string;
+    title: string;
+    updatedAt: number;
+    /** Session origin — only "desktop" / "automation" are listed (see filter). */
+    origin: "desktop" | "automation";
+    /** Normalized durable status for Pet/display consumers. */
+    status?: "active" | "paused" | "completed" | "failed" | "cancelled";
+    /** Exceptional completed-run boundary; absent means a normal final answer. */
+    completionKind?: TurnCompletionKind;
+    /** Durable archival timestamp; absent = not archived. */
+    archivedAt?: number;
+    /** Workspace profile/digital human bound to this Session. */
+    workspaceProfile?: string;
+}
+export interface ListDiskSessionsResult {
+    sessions: DiskSessionMeta[];
+    nextCursor: string | null;
+}
+/**
+ * List top-level (non-sub-agent) sessions from disk, newest first, paginated.
+ * Filter on state.json `parentSessionId`:
+ *   - key absent  → legacy → skip (存量 not auto-rebuilt)
+ *   - null / ""   → top-level → show
+ *   - non-empty   → sub-agent → filter out
+ */
+export declare function listDiskSessions(opts: {
+    limit: number;
+    cursor?: string;
+    includeArchived?: boolean;
+}, baseDir?: string): Promise<ListDiskSessionsResult>;
+/**
+ * Set (number) or clear (undefined) a session's durable archival marker on
+ * disk, then atomically replace `state.json`. This is the main-process writer
+ * counterpart to `listDiskSessions`' `archivedAt` filter: main has no live
+ * Engine/SessionManager handle, so it mutates the same `state.json` the worker
+ * persists. The rest of the state is preserved verbatim; only `archivedAt` is
+ * added or removed. Unsafe ids and missing sessions throw.
+ */
+export declare function archiveDiskSession(id: string, archivedAt: number | undefined, baseDir?: string): Promise<void>;