@cjhyy/code-shell-server 0.8.0

package/dist/worker-bridge-core.js

@@ -0,0 +1,315 @@
+// packages/server/src/worker-bridge-core.ts
+//
+// WorkerBridgeCore — transport-agnostic driver for a per-user agent worker
+// subprocess speaking line-delimited JSON-RPC over stdio.
+//
+// This is the Electron-free half of the old AgentBridge, split out so other
+// hosts (e.g. packages/server driving per-user stdio workers) can reuse it.
+// It owns:
+//   - child process spawn / respawn (one worker at a time, spawned on demand)
+//   - stdout line framing (readline split) + listener dispatch
+//   - request/response correlation (id → resolver, with timeout / consume /
+//     settle-on-exit semantics)
+//   - inbound line injection (`injectWorkerMessage`) with a pluggable
+//     `prepareInbound` hook for host-specific rewriting (e.g. agent/run trust)
+//   - worker generation counter (bumped on every successful spawn)
+//   - pending outbox flushed once the worker's stdin exists
+//   - crash accounting (N crashes per rolling window ⇒ "gave up")
+//   - graceful shutdown (SIGTERM)
+//
+// It must have ZERO electron imports. All host semantics (renderer fan-out,
+// pet projection, browser/credential intercepts, …) live in the caller via
+// the constructor callbacks and `subscribeLines`.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+const DEFAULT_RESTART_WINDOW_MS = 60_000;
+const DEFAULT_RESTART_LIMIT = 3;
+/** Truncate a wire line for logs. */
+export function previewLine(s, max = 200) {
+    return s.length > max ? s.slice(0, max) + `…(+${s.length - max} more)` : s;
+}
+export class WorkerBridgeCore {
+    opts;
+    child = null;
+    /** Pending lines that arrived before the worker's stdin existed. */
+    outbox = [];
+    restartCount = 0;
+    restartWindowStart = Date.now();
+    generation = 0;
+    lineListeners = new Set();
+    pendingRequests = new Map();
+    restartWindowMs;
+    restartLimit;
+    constructor(opts) {
+        this.opts = opts;
+        this.restartWindowMs = opts.restartWindowMs ?? DEFAULT_RESTART_WINDOW_MS;
+        this.restartLimit = opts.restartLimit ?? DEFAULT_RESTART_LIMIT;
+    }
+    log(event, data) {
+        this.opts.log?.(event, data);
+    }
+    /** Current worker generation (0 until the first successful spawn). */
+    workerGeneration() {
+        return this.generation;
+    }
+    hasChild() {
+        return this.child !== null;
+    }
+    /** stdin exists and is not destroyed — a line write won't be dropped. */
+    canSend() {
+        return !!this.child?.stdin && !this.child.stdin.destroyed;
+    }
+    hasLiveWorker() {
+        return !!this.child?.stdin?.writable && !this.child.stdin.destroyed;
+    }
+    /**
+     * Spawn the worker if none is alive. `cwd` is the working directory the
+     * Engine will use (i.e. the repo root). Idempotent if a child is alive.
+     */
+    ensureWorker(requestedCwd) {
+        if (this.child)
+            return;
+        const workerCwd = requestedCwd ?? this.opts.fallbackCwd?.() ?? process.cwd();
+        this.log("spawn.start", {
+            cwd: workerCwd,
+            requestedCwd,
+            restartCount: this.restartCount,
+        });
+        let child;
+        try {
+            child = spawn(this.opts.execPath ?? process.execPath, [this.opts.entryPath], {
+                cwd: workerCwd,
+                env: this.opts.buildEnv ? this.opts.buildEnv() : process.env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (e) {
+            // spawn() can throw synchronously (e.g. invalid execPath). Don't let it
+            // bubble out of the caller uncaught — declare give-up so the host
+            // rejects the pending run instead of hanging.
+            this.log("spawn.throw", { error: String(e) });
+            this.child = null;
+            this.opts.onSpawnFailed?.();
+            return;
+        }
+        this.child = child;
+        this.log("spawn.ok", { pid: child.pid, cwd: workerCwd, requestedCwd });
+        if (!child.stdout || !child.stdin || !child.stderr) {
+            this.log("spawn.error", { reason: "stdio not piped" });
+            this.child = null;
+            this.opts.onSpawnFailed?.();
+            return;
+        }
+        this.generation += 1;
+        this.opts.onWorkerStarted?.({ generation: this.generation, pid: child.pid });
+        const rl = createInterface({ input: child.stdout });
+        rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            // Request/response correlation first: a consumed response never reaches
+            // the listeners (host-internal RPC); a non-consumed one is settled AND
+            // still dispatched so downstream mirrors see the identical stream.
+            if (this.settleMatchingRequest(line))
+                return;
+            for (const listener of [...this.lineListeners]) {
+                try {
+                    listener(line);
+                }
+                catch (e) {
+                    // A listener must never break worker streaming.
+                    this.log("line_listener.threw", { error: String(e) });
+                }
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            this.opts.onStderr?.(chunk.toString());
+        });
+        // A failed spawn (ENOENT/EACCES/EAGAIN/process-limit) emits 'error' and
+        // NO 'exit'. Without this listener Node throws it as an uncaught
+        // exception, and neither exit path fires, so pending host runs hang
+        // forever. Treat a spawn error like a give-up crash.
+        child.on("error", (err) => {
+            this.log("child.error", { error: String(err) });
+            try {
+                rl.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.child = null;
+            this.outbox = [];
+            this.settlePendingOnExit();
+            this.opts.onSpawnError?.(err);
+        });
+        child.on("exit", (code, signal) => {
+            // Close the readline interface bound to the dead child's stdout so it
+            // (and its "line" listener) doesn't leak across restarts.
+            rl.close();
+            this.log("child.exit", { code, signal, pid: child.pid });
+            this.child = null;
+            this.outbox = []; // any queued messages were for the dead child; drop
+            this.settlePendingOnExit();
+            if (code === 0 && signal === null) {
+                // Normal completion. Reset restart counter — clean exits don't count.
+                this.restartCount = 0;
+                this.opts.onExit?.({ code, signal, clean: true, gaveUp: false });
+                return;
+            }
+            // Real crash. Note it but DON'T pre-emptively respawn — the next run
+            // will trigger a fresh spawn anyway. We just decide whether to declare
+            // "gave up" so the host can surface it.
+            const gaveUp = this.shouldDeclareGaveUp();
+            if (gaveUp)
+                this.log("crash.gave_up", { restartCount: this.restartCount });
+            else
+                this.log("crash.tolerable", { restartCount: this.restartCount });
+            this.opts.onExit?.({ code, signal, clean: false, gaveUp });
+        });
+        // Flush queued lines now that stdin exists.
+        for (const queued of this.outbox) {
+            child.stdin.write(queued + "\n");
+        }
+        this.outbox = [];
+    }
+    /** Returns true after >= restartLimit crashes in the current window. */
+    shouldDeclareGaveUp() {
+        const now = Date.now();
+        if (now - this.restartWindowStart > this.restartWindowMs) {
+            this.restartWindowStart = now;
+            this.restartCount = 0;
+        }
+        this.restartCount++;
+        return this.restartCount > this.restartLimit;
+    }
+    /**
+     * If `line` is a response to a pending request(), settle it. Returns true
+     * when the line was consumed (must NOT be dispatched to listeners).
+     */
+    settleMatchingRequest(line) {
+        if (this.pendingRequests.size === 0)
+            return false;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return false;
+        }
+        if (msg.id === undefined || msg.id === null)
+            return false;
+        const pending = this.pendingRequests.get(msg.id);
+        if (!pending)
+            return false;
+        pending.settle(msg.error
+            ? { status: "error", error: msg.error }
+            : { status: "result", result: msg.result });
+        return pending.consume;
+    }
+    settlePendingOnExit() {
+        for (const pending of [...this.pendingRequests.values()]) {
+            if (pending.settleOnExit)
+                pending.settle({ status: "workerExit" });
+        }
+    }
+    /**
+     * Register an observer of every worker stdout line that wasn't consumed by
+     * a `consume: true` request. Returns an unsubscribe. A throwing listener
+     * never disrupts the stream.
+     */
+    subscribeLines(listener) {
+        this.lineListeners.add(listener);
+        return () => this.lineListeners.delete(listener);
+    }
+    /**
+     * Write one JSON-RPC line to the worker's stdin (newline appended). Returns
+     * false when there is no live worker (caller decides drop/fallback). A
+     * stream write error propagates to the caller, matching a direct write.
+     */
+    sendLine(line) {
+        const stdin = this.child?.stdin;
+        if (!stdin || stdin.destroyed)
+            return false;
+        stdin.write(line + "\n");
+        return true;
+    }
+    /**
+     * Inject a JSON-RPC line into the worker exactly as a first-party front end
+     * would. The host's `prepareInbound` hook runs first (metadata rewriting +
+     * on-demand spawn side effects); the possibly-rewritten line is then
+     * written, or dropped with a log when no worker is alive — identical
+     * semantics for every front end (renderer, mobile remote, orchestrators).
+     */
+    injectWorkerMessage(rawLine) {
+        const prep = this.opts.prepareInbound
+            ? this.opts.prepareInbound(rawLine)
+            : { line: rawLine, method: undefined };
+        if (!this.canSend()) {
+            this.log("inject.dropped", {
+                reason: this.child ? "stdin destroyed" : "no child",
+                method: prep.method,
+            });
+            return;
+        }
+        this.log("inject→worker", { method: prep.method, raw: previewLine(prep.line) });
+        this.sendLine(prep.line);
+    }
+    /**
+     * Send a correlated JSON-RPC request and await its response by id.
+     * `params` is omitted from the frame when undefined. Never rejects — the
+     * outcome union carries error/timeout/send-failure states for the caller
+     * to map onto its own semantics.
+     */
+    request(method, params, options) {
+        const { id } = options;
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.pendingRequests.delete(id);
+                resolve(outcome);
+            };
+            const timer = setTimeout(() => settle({ status: "timeout" }), options.timeoutMs);
+            // unref so a long-lived correlation can never be the only thing keeping the
+            // process alive. Callers legitimately use very long timeouts (the Panel App
+            // fire-and-forget agent/run uses 24h); without this, a pending request of
+            // that length blocks a clean exit for a day. Settling still works normally
+            // while the process is running — unref only removes the event-loop hold.
+            timer.unref?.();
+            this.pendingRequests.set(id, {
+                consume: options.consume === true,
+                settleOnExit: options.settleOnExit === true,
+                settle,
+            });
+            const frame = JSON.stringify({
+                jsonrpc: "2.0",
+                id,
+                method,
+                ...(params === undefined ? {} : { params }),
+            });
+            // Wake a lazily-unspawned worker before writing, so a spawn-triggering
+            // request (pet/IM-gateway agent/run) isn't dropped by sendLine and left
+            // to hang until timeout. Idempotent when a child is already alive.
+            if (options.ensureWorker)
+                this.ensureWorker(options.ensureWorkerCwd);
+            let sent = false;
+            let sendError;
+            try {
+                sent = this.sendLine(frame);
+            }
+            catch (e) {
+                sendError = e;
+            }
+            if (options.failFast && (!sent || sendError !== undefined)) {
+                settle({ status: "sendFailed", error: sendError });
+            }
+        });
+    }
+    /** Graceful shutdown: SIGTERM the worker (no-op when none is alive). */
+    kill() {
+        this.log("kill", { pid: this.child?.pid });
+        this.child?.kill("SIGTERM");
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@cjhyy/code-shell-server",
+  "version": "0.8.0",
+  "description": "CodeShell server transport layer — mobile remote HTTP/WS host, pairing, passcode gate, tunnel, rooms, uploads, and session/attachment services. Electron-free; precursor of the auth gateway.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./storage": {
+      "types": "./dist/index.storage.d.ts",
+      "import": "./dist/index.storage.js"
+    },
+    "./worker": {
+      "types": "./dist/index.worker.d.ts",
+      "import": "./dist/index.worker.js"
+    },
+    "./mobile-remote": {
+      "types": "./dist/index.mobile-remote.d.ts",
+      "import": "./dist/index.mobile-remote.js"
+    },
+    "./serve": {
+      "types": "./dist/index.serve.d.ts",
+      "import": "./dist/index.serve.js"
+    }
+  },
+  "bin": {
+    "code-shell-serve": "./dist/bin/code-shell-serve.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run clean && tsc -p tsconfig.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@cjhyy/code-shell-capability-coding": "0.8.0",
+    "@cjhyy/code-shell-core": "0.8.0",
+    "@cjhyy/code-shell-web": "0.8.0",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.21.0"
+  },
+  "engines": {
+    "node": ">=20.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjhyy/codeshell.git",
+    "directory": "packages/server"
+  },
+  "homepage": "https://github.com/cjhyy/codeshell/tree/main/packages/server#readme",
+  "bugs": {
+    "url": "https://github.com/cjhyy/codeshell/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}