@cjhyy/code-shell-server 0.9.7 → 0.9.9

package/dist/hub/outbound-transport.js

@@ -0,0 +1,122 @@
+const DEFAULT_LIMITS = {
+    maxFrameBytes: 64 * 1024 * 1024,
+    maxSocketBacklogBytes: 8 * 1024 * 1024,
+    maxTotalBacklogBytes: 128 * 1024 * 1024,
+};
+/**
+ * Bound the WS write queue separately from the replay buffer. A disconnected
+ * browser can recover through the existing authenticated snapshot protocol;
+ * keeping an unread socket alive would retain every subsequent stream frame.
+ */
+export class HubOutboundTransport {
+    options;
+    limits;
+    dropped = new WeakSet();
+    largeFrames = new WeakMap();
+    constructor(options) {
+        this.options = options;
+        this.limits = { ...DEFAULT_LIMITS, ...options.limits };
+        for (const value of Object.values(this.limits)) {
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new Error("Outbound transport limits must be positive safe integers");
+        }
+    }
+    send(tab, line) {
+        if (tab.readyState !== tab.OPEN || this.dropped.has(tab))
+            return false;
+        const frameBytes = Buffer.byteLength(line);
+        if (frameBytes > this.limits.maxFrameBytes) {
+            this.drop(tab, "frame-too-large", frameBytes);
+            return false;
+        }
+        const largeFrame = this.largeFrames.get(tab);
+        const followingBytes = frameBytes + 14;
+        if (largeFrame
+            ? largeFrame.followingBytes + followingBytes > this.limits.maxSocketBacklogBytes
+            : this.backlog(tab) > this.limits.maxSocketBacklogBytes) {
+            this.drop(tab, "socket-backlog", frameBytes);
+            return false;
+        }
+        // Prefer retiring the largest lagging peer to disconnecting a healthy
+        // recipient. Still count closing sockets until ws releases their buffers:
+        // terminate() can complete asynchronously, and ignoring those bytes would
+        // permit transient allocations above the shared bound.
+        const wireBytes = followingBytes;
+        if (this.totalBacklog() + wireBytes > this.limits.maxTotalBacklogBytes) {
+            const lagging = [...this.options.tabs()]
+                .filter((peer) => peer !== tab &&
+                peer.readyState === peer.OPEN &&
+                !this.dropped.has(peer) &&
+                this.backlog(peer) > 0)
+                .sort((left, right) => this.backlog(right) - this.backlog(left));
+            for (const peer of lagging) {
+                this.drop(peer, "total-backlog", frameBytes);
+                if (this.totalBacklog() + wireBytes <= this.limits.maxTotalBacklogBytes)
+                    break;
+            }
+            if (this.totalBacklog() + wireBytes > this.limits.maxTotalBacklogBytes) {
+                this.drop(tab, "total-backlog", frameBytes);
+                return false;
+            }
+        }
+        // A valid large snapshot must be allowed to reach the browser before the
+        // next small stream notification. Otherwise a perfectly healthy but slow
+        // connection would be terminated mid-history and reconnect forever. Bound
+        // its following stream tail independently until the large write drains.
+        const pendingLarge = !largeFrame && frameBytes > this.limits.maxSocketBacklogBytes
+            ? { followingBytes: 0 }
+            : undefined;
+        if (pendingLarge)
+            this.largeFrames.set(tab, pendingLarge);
+        if (largeFrame)
+            largeFrame.followingBytes += followingBytes;
+        try {
+            tab.send(line, (error) => {
+                if (pendingLarge && this.largeFrames.get(tab) === pendingLarge)
+                    this.largeFrames.delete(tab);
+                if (error)
+                    this.drop(tab, "send-error", frameBytes);
+            });
+            return true;
+        }
+        catch {
+            this.drop(tab, "send-error", frameBytes);
+            return false;
+        }
+    }
+    backlog(tab) {
+        const amount = tab.bufferedAmount;
+        return Number.isFinite(amount) && amount >= 0 ? amount : Number.POSITIVE_INFINITY;
+    }
+    totalBacklog() {
+        let total = 0;
+        for (const tab of this.options.tabs())
+            total += this.backlog(tab);
+        return total;
+    }
+    drop(tab, reason, frameBytes) {
+        if (this.dropped.has(tab))
+            return;
+        this.dropped.add(tab);
+        this.largeFrames.delete(tab);
+        const metadata = {
+            reason,
+            frameBytes,
+            socketBacklogBytes: this.backlog(tab),
+            totalBacklogBytes: this.totalBacklog(),
+        };
+        // A graceful close frame would wait behind the very backlog being bounded.
+        try {
+            tab.terminate();
+        }
+        catch {
+            // Races with socket teardown must not affect other viewers or worker routing.
+        }
+        try {
+            this.options.onDrop?.(metadata);
+        }
+        catch {
+            // Diagnostics must not break the stream router either.
+        }
+    }
+}

package/dist/hub/run-replay.d.ts

@@ -0,0 +1,42 @@
+export interface HubStreamCursor {
+    epoch: string;
+    sequence: number;
+}
+/**
+ * A refresh can happen before the worker persists its current assistant text.
+ * Retain that run's stream separately from the durable pre-run transcript.
+ * The host takes snapshots synchronously, so its cursor also covers all live
+ * notifications sent before the snapshot response, without replaying twice.
+ */
+export declare class HubRunReplay {
+    private readonly limits;
+    private readonly epoch;
+    private sequence;
+    private totalBytes;
+    private readonly sessions;
+    constructor(limits?: {
+        maxBytes: number;
+        maxEvents: number;
+        maxTotalBytes?: number;
+    });
+    begin(sessionId: string, requestId: string, baselineEvents: number): void;
+    /** Only a new, still-tracked conversation can safely replay before disk publication. */
+    hasEmptyBaseline(sessionId: string): boolean;
+    append(sessionId: string, event: unknown): HubStreamCursor;
+    finish(sessionId: string, requestId: string): void;
+    snapshot<T>(sessionId: string, durableEvents: readonly T[]): {
+        liveStream?: {
+            events: {
+                sequence: number;
+                event: unknown;
+            }[];
+            truncated: boolean;
+        } | undefined;
+        transcript: T[];
+        streamCursor: {
+            epoch: `${string}-${string}-${string}-${string}-${string}`;
+            sequence: number;
+        };
+    };
+    clear(): void;
+}

package/dist/hub/run-replay.js

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+/**
+ * A refresh can happen before the worker persists its current assistant text.
+ * Retain that run's stream separately from the durable pre-run transcript.
+ * The host takes snapshots synchronously, so its cursor also covers all live
+ * notifications sent before the snapshot response, without replaying twice.
+ */
+export class HubRunReplay {
+    limits;
+    epoch = randomUUID();
+    sequence = 0;
+    totalBytes = 0;
+    sessions = new Map();
+    constructor(limits = {
+        maxBytes: 8 * 1024 * 1024,
+        maxEvents: 16_000,
+        maxTotalBytes: 64 * 1024 * 1024,
+    }) {
+        this.limits = limits;
+    }
+    begin(sessionId, requestId, baselineEvents) {
+        let log = this.sessions.get(sessionId);
+        if (!log) {
+            log = {
+                baselineEvents: Number.isSafeInteger(baselineEvents) ? Math.max(0, baselineEvents) : 0,
+                events: [],
+                bytes: 0,
+                truncated: false,
+                requests: new Set(),
+            };
+            this.sessions.set(sessionId, log);
+        }
+        log.requests.add(requestId);
+    }
+    /** Only a new, still-tracked conversation can safely replay before disk publication. */
+    hasEmptyBaseline(sessionId) {
+        return this.sessions.get(sessionId)?.baselineEvents === 0;
+    }
+    append(sessionId, event) {
+        const sequence = ++this.sequence;
+        const log = this.sessions.get(sessionId);
+        if (log && !log.truncated) {
+            const serialized = JSON.stringify(event) ?? "null";
+            const bytes = Buffer.byteLength(serialized);
+            if (log.bytes + bytes > this.limits.maxBytes ||
+                log.events.length >= this.limits.maxEvents ||
+                this.totalBytes + bytes > (this.limits.maxTotalBytes ?? 64 * 1024 * 1024)) {
+                // Never silently present an arbitrary tail as a complete conversation.
+                // The caller falls back to the full durable log and exposes this flag.
+                log.truncated = true;
+                log.events = [];
+                this.totalBytes -= log.bytes;
+                log.bytes = 0;
+            }
+            else {
+                // Own the wire value. Later changes to the worker message object must
+                // not change a previously captured stream or invalidate its byte limit.
+                log.events.push({ sequence, event: JSON.parse(serialized) });
+                log.bytes += bytes;
+                this.totalBytes += bytes;
+            }
+        }
+        return { epoch: this.epoch, sequence };
+    }
+    finish(sessionId, requestId) {
+        const log = this.sessions.get(sessionId);
+        if (!log)
+            return;
+        log.requests.delete(requestId);
+        if (!log.requests.size) {
+            this.totalBytes -= log.bytes;
+            this.sessions.delete(sessionId);
+        }
+    }
+    snapshot(sessionId, durableEvents) {
+        const log = this.sessions.get(sessionId);
+        return {
+            transcript: log && !log.truncated ? durableEvents.slice(0, log.baselineEvents) : durableEvents.slice(),
+            streamCursor: { epoch: this.epoch, sequence: this.sequence },
+            ...(log
+                ? { liveStream: { events: structuredClone(log.events), truncated: log.truncated } }
+                : {}),
+        };
+    }
+    clear() {
+        this.sessions.clear();
+        this.totalBytes = 0;
+    }
+}

package/dist/hub/session-management.d.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type SessionState } from "@cjhyy/code-shell-core";
+/** Synchronous, side-effect-free transcript snapshot used by HTTP exports and WS replay. */
+export declare function readHubTranscript(sessionRootDir: string, sessionId: string): unknown[];
+/** Host authorization reads only bounded metadata, never a transcript or mutable engine bundle. */
+export declare function readHubSessionState(sessionRootDir: string, sessionId: string): SessionState;
+export declare function createHubSessions(options: {
+    cwd: string;
+    sessionRootDir: string;
+    dataDir: string;
+    isAuthorized: (req: IncomingMessage) => Promise<boolean>;
+    isRunning: (sessionId: string) => boolean;
+    onChanged: (sessionId: string) => void;
+}): {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+    list: (params?: URLSearchParams) => Promise<{
+        sessions: {
+            preview?: string | undefined;
+            sessionId: string;
+            cwd: string;
+            title: string;
+            customTitle: string;
+            startedAt: number;
+            lastActiveAt: number;
+            model: string;
+            status: import("@cjhyy/code-shell-core").SessionStatus;
+            turnCount: number;
+            archivedAt: number | null;
+            running: boolean;
+        }[];
+        nextCursor: string | null;
+    }>;
+};
+/** Keep engine attachment wrappers out of title/search/preview surfaces. */
+export declare function hubSessionPreview(value: unknown): string | undefined;
+export declare function transcriptMarkdown(title: string, transcript: readonly unknown[]): string;