@ggui-ai/mcp-server 0.1.0-rc.1

package/dist/code-store-fs.js

@@ -0,0 +1,98 @@
+/**
+ * FileSystemCodeStore — node:fs-backed {@link CodeStore}. The OSS dev
+ * default for `ggui serve`.
+ *
+ * Default root is `~/.ggui/code-cache/`; operators can override per
+ * `createGguiServer({ codeStore })` for tests or project-local caches.
+ *
+ * ## Layout
+ *
+ * Two-level directory sharding by hash prefix to avoid stuffing one
+ * directory with thousands of files:
+ *
+ *   <root>/<hash[0..2]>/<hash[2..]>.js
+ *
+ * e.g. `~/.ggui/code-cache/ab/cdef...0123.js`. The `.js` suffix isn't
+ * load-bearing for retrieval — `get(hash)` is the only read API and it
+ * derives the path from the hash — but operators occasionally `cat`
+ * one for debugging, and the suffix tells their editor to syntax-
+ * highlight as JavaScript.
+ *
+ * ## Atomicity
+ *
+ * `put` writes via temp-file + rename for atomic-or-throw — readers
+ * never see a half-written file. The mkdir-recursive call before write
+ * is idempotent and races safely (Linux `mkdir -p` semantics).
+ *
+ * ## Persistence + cleanup
+ *
+ * The store grows unbounded. Operators who care can periodically
+ * `rm -rf ~/.ggui/code-cache/` — every entry is content-addressable
+ * and immutable, so a re-fetch will repopulate from upstream code on
+ * next push. There is no eviction policy in the seam itself.
+ *
+ * ## Permissions
+ *
+ * Files are written with default umask. The cache contains compiled
+ * componentCode the agent generated; nothing more sensitive than what
+ * already shipped over the wire to the iframe. Operators who need
+ * tighter perms wrap with their own umask.
+ */
+import { createHash } from 'node:crypto';
+import { access, constants as fsConstants, mkdir, readFile, rename, writeFile, } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { CODE_HASH_REGEX, } from '@ggui-ai/mcp-server-core';
+export class FileSystemCodeStore {
+    root;
+    constructor(opts = {}) {
+        this.root = opts.root ?? join(homedir(), '.ggui', 'code-cache');
+    }
+    /** Absolute on-disk path for a given hash. Two-level sharded layout. */
+    absPath(hash) {
+        // Sharding: `<root>/<hash[0..2]>/<hash[2..]>.js`. Validation on
+        // every put + get below means `hash` is always 64 lowercase hex.
+        return join(this.root, hash.slice(0, 2), `${hash.slice(2)}.js`);
+    }
+    async put(hash, code) {
+        if (!CODE_HASH_REGEX.test(hash)) {
+            throw new Error(`FileSystemCodeStore.put: hash must match ${CODE_HASH_REGEX.source}, got ${JSON.stringify(hash)}`);
+        }
+        const absPath = this.absPath(hash);
+        // Idempotent: if the file already exists, skip rewrite. Cheap fast
+        // path that avoids unnecessary disk churn when the same blueprint
+        // is pushed repeatedly.
+        if (await fileExists(absPath))
+            return;
+        await mkdir(dirname(absPath), { recursive: true });
+        // Temp-file + rename for atomic-or-throw write; readers never see
+        // partial bytes.
+        const tmpPath = `${absPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+        await writeFile(tmpPath, code, { encoding: 'utf-8' });
+        await rename(tmpPath, absPath);
+    }
+    async get(hash) {
+        if (!CODE_HASH_REGEX.test(hash))
+            return null;
+        try {
+            return await readFile(this.absPath(hash), { encoding: 'utf-8' });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    hashOf(code) {
+        return createHash('sha256').update(code, 'utf-8').digest('hex');
+    }
+}
+async function fileExists(absPath) {
+    try {
+        await access(absPath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/console-auth.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Embedded-ui cookie auth plane.
+ *
+ * This module owns the THIRD of the three token kinds the server
+ * tracks for the embedded UI:
+ *
+ *   1. bootstrap tokens       — short-TTL, single-use, MCP Apps iframes.
+ *   2. session tokens         — longer-TTL, reusable, post-bootstrap
+ *                               reconnect creds.
+ *   3. console cookies    — longer-TTL, reusable, same-origin
+ *                               browser-only, issued by this server
+ *                               for ITS OWN console landing/viewer
+ *                               pages. **Scoped narrowly**: consumed
+ *                               ONLY at the live-channel WebSocket
+ *                               upgrade when `cookieAuth` is wired.
+ *                               NEVER authenticates `/mcp`, `/pair`,
+ *                               `/threads`, or any other ingress.
+ *
+ * Isolation invariant (load-bearing). The cookie uses the SAME HMAC
+ * shape as the bootstrap/session tokens but a distinct `kind` claim
+ * (`'console-session'`). That makes cross-kind confusion
+ * impossible: a cookie value CAN'T verify as a bootstrap or session
+ * token. Secrets are shared across kinds because they live in the
+ * same trust domain (server-minted same-origin creds) and kind
+ * discrimination is sufficient.
+ *
+ * Rationale for cookie-over-bearer. Browsers can't set `Authorization`
+ * on native WebSocket upgrades. A same-origin HTTP-only cookie travels
+ * automatically on the upgrade request, is unreadable from JS
+ * (blocks XSS exfil), and is scoped to this origin by the browser
+ * SameSite rules. The one genuine mismatch case (cookie authentication
+ * on cross-origin requests) is defense-in-depth: set `SameSite=Strict`
+ * so the cookie never leaves the console's origin in the first
+ * place.
+ *
+ * Lifecycle. Cookie is minted at `POST /ggui/console/session-cookie`
+ * (operator posts a shortCode → server resolves → sets Set-Cookie).
+ * Cookie is consumed at `GET /ws` upgrade (if the server composition
+ * wires `cookieAuth` to the session-channel). Never mutated in
+ * between.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/**
+ * Cookie name. Chosen deliberately to NOT conflict with common framework
+ * cookies (Express session, CSRF, etc.). Change carries a compat
+ * concern — the console SPA + the session-channel upgrade read by
+ * this exact name. Keep this export as the single source of truth.
+ */
+export declare const CONSOLE_COOKIE_NAME = "ggui_console_session";
+/**
+ * Result of minting a cookie. Callers set the cookie on their response
+ * (the cookie endpoint) and echo the bound `sessionId`/`appId` back in
+ * the response body so the client SPA can bootstrap the viewer without
+ * a follow-up round-trip.
+ */
+export interface DevtoolCookieMint {
+    readonly cookieValue: string;
+    readonly setCookieHeader: string;
+    readonly expiresAt: number;
+    readonly sessionId: string;
+    readonly appId: string;
+}
+export interface MintDevtoolCookieInput {
+    readonly sessionId: string;
+    readonly appId: string;
+    /** HMAC secret. Shared with bootstrap + session tokens by design. */
+    readonly secret: string;
+    /** Cookie TTL in seconds. Defaults to 8 hours. */
+    readonly ttlSec?: number;
+    /**
+     * When `true`, adds `Secure` to the Set-Cookie attribute string so
+     * the cookie is only sent over HTTPS. Operators fronting the server
+     * with TLS pass `true`; local dev / HTTP-only deployments leave it
+     * falsy. No auto-detect — explicit is safer.
+     */
+    readonly secure?: boolean;
+    /** Cookie path. Defaults to `/`. */
+    readonly path?: string;
+    /**
+     * SameSite policy. Defaults to `'Strict'` — same-origin operator
+     * convenience means we actively want the cookie NOT to travel on
+     * cross-origin navigations.
+     */
+    readonly sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Mint a cookie value bound to `{ sessionId, appId }` and the formatted
+ * `Set-Cookie` header to send on the response. Caller does
+ * `res.setHeader('Set-Cookie', result.setCookieHeader)`.
+ */
+export declare function mintDevtoolCookie(input: MintDevtoolCookieInput): DevtoolCookieMint;
+/**
+ * Parse a raw `Cookie:` header and extract the console cookie
+ * value, or `null` if absent.
+ *
+ * Minimal manual parser — intentionally avoids pulling in a cookie
+ * library for a single cookie name. Handles the shapes we actually
+ * see (single cookie, multiple `; `-separated pairs, URL-encoded
+ * values); anything exotic returns null rather than trying to be
+ * clever.
+ */
+export declare function extractDevtoolCookie(cookieHeader: string | undefined): string | null;
+/**
+ * Read the console cookie off incoming headers. Thin wrapper
+ * around {@link extractDevtoolCookie} that accepts Node's
+ * `IncomingHttpHeaders` directly — the shape both the Express
+ * request and the raw `IncomingMessage` use.
+ *
+ * Node's declared `headers['cookie']` type is `string | undefined`;
+ * both Express (post-body-parser) and node:http (the WebSocket
+ * upgrade path) consistently deliver a single string. Multi-line
+ * `Cookie:` header arrays are not a real shape we see in practice,
+ * so we don't try to support them — if a future runtime produces
+ * that shape the cookie silently 404s, which is the correct
+ * degraded behavior for this auth plane.
+ */
+export declare function readDevtoolCookieFromHeaders(headers: IncomingHttpHeaders): string | null;
+/**
+ * Verified claims extracted from an console cookie. Scope is
+ * deliberately narrow: just the binding the session-channel upgrade
+ * needs to enforce `subscribe.sessionId === cookie.sessionId`.
+ */
+export interface DevtoolCookieClaims {
+    readonly sessionId: string;
+    readonly appId: string;
+}
+/**
+ * Verify an console cookie value. Returns the claims on success,
+ * `null` on any failure (signature, expiry, wrong kind, malformed).
+ *
+ * Never throws. Failures collapse to `null` so callers don't have to
+ * distinguish failure reasons in the hot path — an invalid cookie
+ * means "no cookie" for auth purposes. A future refinement could
+ * differentiate "cookie expired" (prompt re-mint) from "cookie is
+ * for another server" (hard reject), but that distinction is not
+ * surfaced today.
+ */
+export declare function verifyDevtoolCookie(cookieValue: string, secret: string): DevtoolCookieClaims | null;
+//# sourceMappingURL=console-auth.d.ts.map

package/dist/console-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-auth.d.ts","sourceRoot":"","sources":["../src/console-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAOrD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,GAC5B,iBAAiB,CAqBnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,IAAI,CAIf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,mBAAmB,GAAG,IAAI,CAO5B"}

package/dist/console-auth.js

@@ -0,0 +1,102 @@
+import { DEFAULT_DEVTOOL_SESSION_TTL_SEC, mintDevtoolSessionToken, verifyToken, } from '@ggui-ai/mcp-server-core';
+/**
+ * Cookie name. Chosen deliberately to NOT conflict with common framework
+ * cookies (Express session, CSRF, etc.). Change carries a compat
+ * concern — the console SPA + the session-channel upgrade read by
+ * this exact name. Keep this export as the single source of truth.
+ */
+export const CONSOLE_COOKIE_NAME = 'ggui_console_session';
+/**
+ * Mint a cookie value bound to `{ sessionId, appId }` and the formatted
+ * `Set-Cookie` header to send on the response. Caller does
+ * `res.setHeader('Set-Cookie', result.setCookieHeader)`.
+ */
+export function mintDevtoolCookie(input) {
+    const ttlSec = input.ttlSec ?? DEFAULT_DEVTOOL_SESSION_TTL_SEC;
+    const { token, claims } = mintDevtoolSessionToken({ sessionId: input.sessionId, appId: input.appId, ttlSec }, input.secret);
+    const attrs = [
+        `${CONSOLE_COOKIE_NAME}=${token}`,
+        `Path=${input.path ?? '/'}`,
+        `Max-Age=${ttlSec}`,
+        `SameSite=${input.sameSite ?? 'Strict'}`,
+        `HttpOnly`,
+    ];
+    if (input.secure)
+        attrs.push('Secure');
+    return {
+        cookieValue: token,
+        setCookieHeader: attrs.join('; '),
+        expiresAt: claims.exp * 1000,
+        sessionId: input.sessionId,
+        appId: input.appId,
+    };
+}
+/**
+ * Parse a raw `Cookie:` header and extract the console cookie
+ * value, or `null` if absent.
+ *
+ * Minimal manual parser — intentionally avoids pulling in a cookie
+ * library for a single cookie name. Handles the shapes we actually
+ * see (single cookie, multiple `; `-separated pairs, URL-encoded
+ * values); anything exotic returns null rather than trying to be
+ * clever.
+ */
+export function extractDevtoolCookie(cookieHeader) {
+    if (!cookieHeader)
+        return null;
+    const pairs = cookieHeader.split(';');
+    for (const raw of pairs) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const name = trimmed.slice(0, eq);
+        if (name !== CONSOLE_COOKIE_NAME)
+            continue;
+        const value = trimmed.slice(eq + 1);
+        return value ? decodeURIComponent(value) : null;
+    }
+    return null;
+}
+/**
+ * Read the console cookie off incoming headers. Thin wrapper
+ * around {@link extractDevtoolCookie} that accepts Node's
+ * `IncomingHttpHeaders` directly — the shape both the Express
+ * request and the raw `IncomingMessage` use.
+ *
+ * Node's declared `headers['cookie']` type is `string | undefined`;
+ * both Express (post-body-parser) and node:http (the WebSocket
+ * upgrade path) consistently deliver a single string. Multi-line
+ * `Cookie:` header arrays are not a real shape we see in practice,
+ * so we don't try to support them — if a future runtime produces
+ * that shape the cookie silently 404s, which is the correct
+ * degraded behavior for this auth plane.
+ */
+export function readDevtoolCookieFromHeaders(headers) {
+    const raw = headers['cookie'];
+    if (typeof raw === 'string')
+        return extractDevtoolCookie(raw);
+    return null;
+}
+/**
+ * Verify an console cookie value. Returns the claims on success,
+ * `null` on any failure (signature, expiry, wrong kind, malformed).
+ *
+ * Never throws. Failures collapse to `null` so callers don't have to
+ * distinguish failure reasons in the hot path — an invalid cookie
+ * means "no cookie" for auth purposes. A future refinement could
+ * differentiate "cookie expired" (prompt re-mint) from "cookie is
+ * for another server" (hard reject), but that distinction is not
+ * surfaced today.
+ */
+export function verifyDevtoolCookie(cookieValue, secret) {
+    const result = verifyToken(cookieValue, secret, 'console-session');
+    if (!result.ok)
+        return null;
+    return {
+        sessionId: result.claims.sessionId,
+        appId: result.claims.appId,
+    };
+}

package/dist/console-cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Console-facing blueprint-cache trace sink + REST/SSE endpoints
+ * powering `/devtools/cache` in the @ggui-ai/console SPA.
+ *
+ * This is the OSS-default sink the `ggui serve` process registers via
+ * {@link setCacheTraceSink}. A hosted closed runtime may swap in a
+ * durable sink (e.g. Redis-backed) — the matcher only knows about the
+ * {@link CacheTraceSink} contract.
+ *
+ * **Two surfaces, both admin-gated:**
+ *   - `GET /ggui/console/cache/recent?limit=<n>` — JSON snapshot of the
+ *     ring buffer's most recent N events, oldest-first within the page.
+ *     Used for initial page load.
+ *   - `GET /ggui/console/cache/stream` — SSE stream of new events as
+ *     they fire. Heartbeat every 15s to keep proxies awake.
+ *
+ * **Memory bound.** Default capacity = 200 events. Each event carries
+ * a (truncated) intent + up to 5 candidate scores — at ~5KB/event that's
+ * ~1MB peak. Operator can override via
+ * `createGguiServer({ cacheTrace: { capacity }})` if running on a small
+ * box.
+ *
+ * **Why a separate file from console-llm-trace.** Both share the same
+ * shape (bounded buffer + SSE fanout + admin-gated REST), but:
+ *
+ *   1. The contract differ — `LlmTraceSink` carries provider/model/
+ *      tokens, `CacheTraceSink` carries scope/intent/decision/
+ *      candidates. Generic-typing one buffer over both narrows the
+ *      operator UI's awareness of which fields to format.
+ *   2. The two can be swapped independently — a hosted closed runtime
+ *      may want a durable LLM trace (cost analysis) but a lossy cache
+ *      trace (ops signal only). One file per sink keeps that swap lean.
+ */
+import type { Express } from 'express';
+import type { CacheTraceEvent, CacheTraceSink } from '@ggui-ai/mcp-server-handlers/session-mutations';
+/** SSE listener — receives one event per cache lookup. */
+type SseListener = (event: CacheTraceEvent) => void;
+/**
+ * In-memory ring buffer + listener fanout. Implements
+ * {@link CacheTraceSink} so it can be passed to
+ * {@link setCacheTraceSink}.
+ *
+ * **Why a class, not a closure.** Same reasoning as
+ * {@link BoundedLlmTraceSink} — tests + operators read state
+ * (`recent()`, listener count); subclass is the extension point if a
+ * hosted closed runtime wants to pipe events to Redis / DDB / S3 in
+ * addition to the ring buffer.
+ */
+export declare class BoundedCacheTraceSink implements CacheTraceSink {
+    private readonly capacity;
+    private readonly buffer;
+    private readonly listeners;
+    constructor(opts?: {
+        readonly capacity?: number;
+    });
+    emit(event: CacheTraceEvent): void;
+    /**
+     * Snapshot of the most-recent `limit` events, oldest-first within
+     * the returned slice (so the operator UI can append in chronological
+     * order without re-sorting).
+     */
+    recent(limit: number): readonly CacheTraceEvent[];
+    /** Subscribe to live events. Returns an unsubscribe function. */
+    subscribe(listener: SseListener): () => void;
+    /** Listener count — for tests + the eventual `/devtools/info` view. */
+    listenerCount(): number;
+    /** Buffer size — for tests + future bound enforcement assertions. */
+    size(): number;
+}
+/**
+ * Mount the `/ggui/console/cache/recent` + `/.../stream` routes on
+ * `app`. Caller is responsible for installing the admin gate
+ * middleware on these paths beforehand — this function does not
+ * re-implement auth.
+ */
+export declare function mountConsoleCacheRoutes(app: Express, sink: BoundedCacheTraceSink): void;
+export {};
+//# sourceMappingURL=console-cache.d.ts.map

package/dist/console-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-cache.d.ts","sourceRoot":"","sources":["../src/console-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAqB,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACf,MAAM,gDAAgD,CAAC;AAGxD,0DAA0D;AAC1D,KAAK,WAAW,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAExC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAUjD,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAclC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE;IAKjD,iEAAiE;IACjE,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,IAAI;IAO5C,uEAAuE;IACvE,aAAa,IAAI,MAAM;IAIvB,qEAAqE;IACrE,IAAI,IAAI,MAAM;CAGf;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,qBAAqB,GAC1B,IAAI,CA8CN"}

package/dist/console-cache.js

@@ -0,0 +1,105 @@
+import { applyDevtoolSecurityHeaders } from './console-headers.js';
+/**
+ * In-memory ring buffer + listener fanout. Implements
+ * {@link CacheTraceSink} so it can be passed to
+ * {@link setCacheTraceSink}.
+ *
+ * **Why a class, not a closure.** Same reasoning as
+ * {@link BoundedLlmTraceSink} — tests + operators read state
+ * (`recent()`, listener count); subclass is the extension point if a
+ * hosted closed runtime wants to pipe events to Redis / DDB / S3 in
+ * addition to the ring buffer.
+ */
+export class BoundedCacheTraceSink {
+    capacity;
+    buffer = [];
+    listeners = new Set();
+    constructor(opts) {
+        const cap = opts?.capacity ?? 200;
+        if (!Number.isFinite(cap) || cap <= 0) {
+            throw new Error(`BoundedCacheTraceSink: capacity must be a positive integer, got ${cap}`);
+        }
+        this.capacity = Math.floor(cap);
+    }
+    emit(event) {
+        this.buffer.push(event);
+        if (this.buffer.length > this.capacity) {
+            this.buffer.shift();
+        }
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // One bad listener must not block fan-out to others.
+            }
+        }
+    }
+    /**
+     * Snapshot of the most-recent `limit` events, oldest-first within
+     * the returned slice (so the operator UI can append in chronological
+     * order without re-sorting).
+     */
+    recent(limit) {
+        const n = Math.max(0, Math.min(limit, this.buffer.length));
+        return this.buffer.slice(-n);
+    }
+    /** Subscribe to live events. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Listener count — for tests + the eventual `/devtools/info` view. */
+    listenerCount() {
+        return this.listeners.size;
+    }
+    /** Buffer size — for tests + future bound enforcement assertions. */
+    size() {
+        return this.buffer.length;
+    }
+}
+/**
+ * Mount the `/ggui/console/cache/recent` + `/.../stream` routes on
+ * `app`. Caller is responsible for installing the admin gate
+ * middleware on these paths beforehand — this function does not
+ * re-implement auth.
+ */
+export function mountConsoleCacheRoutes(app, sink) {
+    // GET /ggui/console/cache/recent?limit=<n> — JSON snapshot.
+    app.get('/ggui/console/cache/recent', (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const limitRaw = req.query['limit'];
+        let limit = 100;
+        if (typeof limitRaw === 'string') {
+            const parsed = Number.parseInt(limitRaw, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                limit = Math.min(500, parsed);
+            }
+        }
+        res.json({ events: sink.recent(limit) });
+    });
+    // GET /ggui/console/cache/stream — SSE live stream.
+    // Heartbeat comment every 15s so reverse proxies don't kill the
+    // connection on idle. Client cleanup unregisters the listener.
+    app.get('/ggui/console/cache/stream', (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        res.setHeader('content-type', 'text/event-stream');
+        res.setHeader('cache-control', 'no-store');
+        res.setHeader('connection', 'keep-alive');
+        // Flush headers immediately so the EventSource starts receiving.
+        res.flushHeaders?.();
+        const heartbeat = setInterval(() => {
+            // SSE comment frame — clients ignore but proxies see traffic.
+            res.write(': ping\n\n');
+        }, 15000);
+        const off = sink.subscribe((event) => {
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        });
+        req.on('close', () => {
+            clearInterval(heartbeat);
+            off();
+        });
+    });
+}

package/dist/console-headers.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Security headers for console responses.
+ *
+ * Scope: applied ONLY to surfaces the console SPA itself owns —
+ * the `/ggui/console/*` API routes + the static mount + its SPA
+ * fallback. Deliberately NOT applied to `/mcp`, `/pair`, `/threads`,
+ * `/ggui/auth-check`, `/ggui/health` — those are API contract that
+ * browsers don't interpret as HTML, and bleeding CSP onto them adds
+ * noise without security value.
+ *
+ * The policy is the NARROWEST that keeps the current viewer working.
+ * Lifting any directive carries a real product decision; do NOT widen
+ * casually.
+ *
+ *   - `default-src 'none'` — deny by default, opt into every source.
+ *   - `script-src 'self' blob: data: <ggui-shell-hash>` — Vite emits
+ *     `<script type="module" src="/assets/...">` with no inline scripts
+ *     or eval (`'self'` covers that). `blob:` covers the outer dynamic
+ *     `import(blob:URL)` call in `ReactComponentRenderer`'s
+ *     `loadModule`: the renderer wraps compiled ESM in a Blob,
+ *     `URL.createObjectURL`s it, and dynamically imports the resulting
+ *     blob URL. `data:` covers the INNER bare-specifier rewrite path
+ *     in `@ggui-ai/design/rendering/rewrite-imports.ts`: `import React
+ *     from 'react'` inside the generated module becomes `import
+ *     React from 'data:text/javascript,…shim…'`, and the browser
+ *     imports that `data:` URL as a script subresource. Stripping
+ *     either directive silently breaks the renderer — jsdom tests
+ *     can't detect this because jsdom doesn't enforce CSP; the
+ *     `live-generation.spec.ts` browser proof is what catches it.
+ *     Both sources are produced by code running in THIS
+ *     origin; neither permits third-party script loading, and
+ *     neither enables `eval` / `new Function` (that needs
+ *     `'unsafe-eval'`, which is explicitly absent).
+ *
+ *     `<ggui-shell-hash>` is `GGUI_SESSION_SHELL_SCRIPT_HASH` from
+ *     `mcp-apps-outbound.ts` — the sha-256 source-expression
+ *     authorising the inline `<script>` block of the production thin
+ *     shell `<McpAppIframe>` mounts via `srcdoc`. `srcdoc` iframes
+ *     inherit the parent's CSP, so without the hash the shell's
+ *     bootstrap script is blocked at parse time and the renderer is
+ *     never fetched (lifecycle stuck at `mounting`, specs pinning
+ *     `code-ready` time out). Hash CSP is the right shape because the
+ *     shell body is static + known at build time; binding the policy
+ *     to the exact bytes is narrower than `'unsafe-inline'` and
+ *     narrower than a runtime nonce. Drift between this CSP and the
+ *     actual script body is caught by `mcp-apps-outbound.test.ts` —
+ *     edit the script, regenerate the hash.
+ *
+ *     `'unsafe-inline'` is still NEVER allowed for scripts; the hash
+ *     mechanism preserves the strict-no-inline posture for everything
+ *     except the one known shell body whose bytes are pinned.
+ *   - `style-src 'self' 'unsafe-inline'` — React `style={...}` props
+ *     produce inline `style=""` attributes. `'unsafe-inline'` is
+ *     required for those attribute-level styles; it does NOT open the
+ *     door to inline `<script>` or `<style>` blocks (different CSP
+ *     directive). Scoped, not dangerous.
+ *   - `connect-src 'self'` — covers both same-origin `fetch()` to
+ *     `/ggui/console/session-cookie` and the `new WebSocket('/ws')`
+ *     upgrade. CSP Level 3 treats `'self'` as matching the document's
+ *     origin across http/https/ws/wss, which is exactly the scope.
+ *   - `img-src 'self' data:` — no images in the minimal viewer today,
+ *     but data: URIs are a common future need (inline SVG, favicons).
+ *     `'self'` alone would reject a minor future surface; adding data:
+ *     now avoids a churn commit later.
+ *   - `font-src 'self'` — no custom fonts in-tree, but a future design
+ *     pass likely adds one. `'self'` matches that future without
+ *     permissively allowing third-party font CDNs.
+ *   - `frame-ancestors 'none'` — the console is NOT a frame target.
+ *     The MCP Apps iframe shell is the framed surface (lives at a
+ *     different URL with its own CSP); embedding THIS page inside
+ *     another document would always be a clickjacking concern. Pairs
+ *     with `X-Frame-Options: DENY` for legacy-browser coverage.
+ *   - `base-uri 'none'` — no `<base>` tag in `index.html`; deny
+ *     injection.
+ *   - `form-action 'self'` — if a future slice adds a form, restrict
+ *     submissions to same origin. Today there are no forms.
+ *
+ * What's deliberately NOT here:
+ *
+ *   - `upgrade-insecure-requests` — operators run console on plain
+ *     HTTP during local dev; forcing HTTPS would break that. TLS is
+ *     the operator's choice via reverse proxy.
+ *   - `report-uri` / `report-to` — no CSP telemetry ingestion today.
+ *     A future hardening slice can add one; keeping this off avoids
+ *     tying the OSS server to a specific reporting endpoint.
+ *   - `Strict-Transport-Security` — same reasoning: operator owns HSTS
+ *     via their reverse proxy / load balancer. The OSS server must
+ *     stay HTTP-friendly for dev and self-hosted loopback.
+ *
+ * Header shape (in the order `setHeader` applies):
+ *
+ *   Content-Security-Policy: <policy>
+ *   X-Content-Type-Options: nosniff
+ *   X-Frame-Options: DENY
+ *   Referrer-Policy: strict-origin-when-cross-origin
+ *   Cross-Origin-Opener-Policy: same-origin
+ */
+import type { Response } from 'express';
+import type { ServerResponse } from 'node:http';
+/**
+ * The CSP directive string. Exported so tests can assert against the
+ * exact shape without hard-coding the directive order inside the test
+ * file. Change this string and a focused header test catches the
+ * regression.
+ */
+export declare const DEVTOOL_CSP: string;
+/**
+ * Other security headers applied alongside CSP. Split from `DEVTOOL_CSP`
+ * so tests can enumerate them separately. Keep this list small +
+ * well-justified — every header is a compat risk on the operator's
+ * browser matrix.
+ */
+export declare const DEVTOOL_SECURITY_HEADERS: ReadonlyArray<readonly [string, string]>;
+/**
+ * Apply the console security header set to a response. Pure
+ * side-effect on `res`; returns `void`. Safe to call multiple times on
+ * the same response — `setHeader` overwrites.
+ *
+ * Accepts both Express `Response` and raw Node `ServerResponse` so the
+ * `express.static` `setHeaders(res, path, stat)` callback (which passes
+ * `ServerResponse`) can reuse the same helper.
+ */
+export declare function applyDevtoolSecurityHeaders(res: Response | ServerResponse): void;
+//# sourceMappingURL=console-headers.d.ts.map

package/dist/console-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-headers.d.ts","sourceRoot":"","sources":["../src/console-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,MAcd,CAAC;AAEb;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAClD,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAO1B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,QAAQ,GAAG,cAAc,GAC7B,IAAI,CAIN"}