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

package/dist/console-theme-routes.js

@@ -0,0 +1,202 @@
+/**
+ * Console theme picker routes — `GET /ggui/console/theme` +
+ * `POST /ggui/console/theme`.
+ *
+ * Shape:
+ *
+ *   GET /ggui/console/theme
+ *     → 200 {
+ *         presets: ThemeEntry[],   // from @ggui-ai/design#listThemes()
+ *         current: ThemeConfig | null,  // ggui.json#theme as parsed
+ *         writerEnabled: boolean,  // POST availability
+ *       }
+ *
+ *   POST /ggui/console/theme
+ *     body: ThemeConfig | null     // null = clear field, fall back to default
+ *     → 200 { ok: true }
+ *     → 400 { error: 'invalid_config', issue }    — schema rejected
+ *     → 501 { error: 'writer_not_configured' }    — opts.themeWriter omitted
+ *     → 500 { error: 'write_failed', message }    — writer threw
+ *
+ * Authentication: piggy-backs on the same admin gate the LLM-keys
+ * routes use — operator-only since the value persists to ggui.json,
+ * which the OSS server treats as trusted manifest input. End-users
+ * who paired into a session don't get to mutate the project's
+ * theme. Multi-tenant deployments may relax this in a follow-up by
+ * scoping overrides per user (overrides become server state, not
+ * file state).
+ */
+import { ThemeConfigSchema, safeParseThemeDocument, } from '@ggui-ai/project-config';
+import { applyDevtoolSecurityHeaders } from './console-headers.js';
+/**
+ * Filename gate for `POST /ggui/console/theme/upload`. Operators upload
+ * arbitrary names; we constrain to a small alphabet that can't escape
+ * the project directory or shadow tooling files.
+ */
+const SAFE_FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
+const FORBIDDEN_FILENAMES = new Set(['ggui.json', 'package.json']);
+/**
+ * Mount `GET /ggui/console/theme` + `POST /ggui/console/theme` onto
+ * the express app. Returns nothing — the routes self-register.
+ *
+ * The current-config state is held in-process (mutable closure) so
+ * subsequent GETs reflect the latest POST without re-reading
+ * ggui.json. Writes are durable via the supplied `themeWriter`.
+ */
+export function mountDevtoolThemeRoutes(opts) {
+    const { app, themeWriter, themeFileUploader, requestHasAdminAuth, onConfigChange } = opts;
+    let currentConfig = opts.initialConfig;
+    // Single helper for the two POST paths so the cell update + the
+    // change-notifier fire in lockstep. Errors from the notifier are
+    // swallowed — the operator's save already landed on disk, so a
+    // downstream subscription glitch shouldn't surface as a UI failure.
+    const updateConfig = (next) => {
+        currentConfig = next;
+        if (onConfigChange !== undefined) {
+            try {
+                onConfigChange(next);
+            }
+            catch {
+                /* observer-side failure is non-load-bearing */
+            }
+        }
+    };
+    const writerEnabled = themeWriter !== undefined;
+    const uploadEnabled = themeWriter !== undefined && themeFileUploader !== undefined;
+    // GET /ggui/console/theme — picker data
+    app.get('/ggui/console/theme', (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!requestHasAdminAuth(req)) {
+            res.status(401).json({ error: 'admin_auth_required' });
+            return;
+        }
+        // The list of registered presets is owned by `@ggui-ai/design`,
+        // which the console client imports directly. The server only
+        // returns the resolved-from-manifest selection + the writer's
+        // posture; the client renders the preset grid from listThemes()
+        // on its own.
+        res.status(200).json({
+            current: currentConfig,
+            writerEnabled,
+            uploadEnabled,
+        });
+    });
+    // POST /ggui/console/theme — persist a selection
+    app.post('/ggui/console/theme', async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!requestHasAdminAuth(req)) {
+            res.status(401).json({ error: 'admin_auth_required' });
+            return;
+        }
+        if (themeWriter === undefined) {
+            res.status(501).json({
+                error: 'writer_not_configured',
+                message: 'Theme writes require the CLI to provide a themeWriter — ' +
+                    'launch via `ggui serve` (writer is wired) instead of using ' +
+                    'createGguiServer directly without the option.',
+            });
+            return;
+        }
+        // body is `ThemeConfig | null`. Empty body / `null` clears.
+        const raw = (req.body ?? null);
+        let parsed;
+        if (raw === null) {
+            parsed = null;
+        }
+        else {
+            const result = ThemeConfigSchema.safeParse(raw);
+            if (!result.success) {
+                res.status(400).json({
+                    error: 'invalid_config',
+                    issue: result.error.flatten(),
+                });
+                return;
+            }
+            parsed = result.data;
+        }
+        try {
+            await themeWriter(parsed);
+            updateConfig(parsed);
+            res.status(200).json({ ok: true, current: parsed });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(500).json({ error: 'write_failed', message });
+        }
+    });
+    // POST /ggui/console/theme/upload — write a DTCG theme document
+    // alongside ggui.json and switch the manifest to point at it.
+    //
+    // Body shape: { filename: string, content: unknown, mode: 'light' | 'dark' }
+    //
+    //   - filename is constrained by SAFE_FILENAME_RE — no path
+    //     separators, no `ggui.json` / `package.json` collision.
+    //   - content is validated via `safeParseThemeDocument` (plain DTCG
+    //     v1) so a malformed paste is rejected before hitting disk.
+    //   - On success we run `themeFileUploader(filename, content)`
+    //     followed by `themeWriter({ file: './<filename>', mode })`,
+    //     so a save lands the file AND updates the manifest atomically
+    //     from the operator's POV. Partial-failure recovery is the
+    //     CLI's responsibility — the seam contract says either both
+    //     side-effects land or both throw.
+    app.post('/ggui/console/theme/upload', async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        if (!requestHasAdminAuth(req)) {
+            res.status(401).json({ error: 'admin_auth_required' });
+            return;
+        }
+        if (themeWriter === undefined || themeFileUploader === undefined) {
+            res.status(501).json({
+                error: 'upload_not_configured',
+                message: 'Theme uploads require both themeWriter and themeFileUploader — ' +
+                    'launch via `ggui serve` (both are wired) instead of using ' +
+                    'createGguiServer directly without the options.',
+            });
+            return;
+        }
+        const body = (req.body ?? {});
+        const filename = typeof body.filename === 'string' ? body.filename : '';
+        if (!SAFE_FILENAME_RE.test(filename)) {
+            res.status(400).json({
+                error: 'invalid_filename',
+                message: 'filename must match /^[a-zA-Z0-9._-]+\\.json$/ — no path ' +
+                    'separators, ends with .json. Got: ' + JSON.stringify(filename),
+            });
+            return;
+        }
+        if (FORBIDDEN_FILENAMES.has(filename)) {
+            res.status(400).json({
+                error: 'forbidden_filename',
+                message: `filename "${filename}" would shadow a reserved file.`,
+            });
+            return;
+        }
+        const mode = body.mode;
+        if (mode !== 'light' && mode !== 'dark') {
+            res.status(400).json({
+                error: 'invalid_mode',
+                message: 'mode must be "light" or "dark".',
+            });
+            return;
+        }
+        const docResult = safeParseThemeDocument(body.content);
+        if (!docResult.success) {
+            res.status(400).json({
+                error: 'invalid_content',
+                issue: docResult.error.flatten(),
+            });
+            return;
+        }
+        try {
+            await themeFileUploader(filename, docResult.data);
+            const nextConfig = { file: `./${filename}`, mode };
+            await themeWriter(nextConfig);
+            updateConfig(nextConfig);
+            res.status(200).json({ ok: true, current: nextConfig });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(500).json({ error: 'write_failed', message });
+        }
+    });
+}

package/dist/console-timeline.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Console-facing session-event timeline endpoints powering
+ * `/devtools/timeline` in the @ggui-ai/console SPA.
+ *
+ * Unlike `/devtools/llm-trace`, the timeline does NOT introduce a new
+ * sink — every event the operator wants to step through already
+ * exists in the {@link SessionStore} (inbound user
+ * actions + tool calls + UI mutations) and the
+ * {@link SessionStreamBuffer} (outbound stream cursor). This module is
+ * a thin read-only window over both.
+ *
+ * **Two surfaces, both admin-gated:**
+ *
+ *   - `GET /ggui/console/timeline/sessions` — list of sessions visible
+ *     to the timeline picker. All statuses (active / completed /
+ *     expired) — operators frequently want to debug a session AFTER it
+ *     terminated. Sorted most-recent-`lastActivityAt` first; defaults
+ *     to 50 rows, clamped to [1, 200] via `?limit=`.
+ *
+ *   - `GET /ggui/console/timeline/:sessionId/events` — the full event
+ *     log for one session, oldest-first, drained from
+ *     `sessionStore.observe(id, { tail: false })`. Also reports the
+ *     outbound stream cursor (`streamBuffer.currentSeq`) so the
+ *     operator can see live-channel progress without a separate fetch.
+ *
+ * Why REST-only (no SSE): replay is a snapshot. The operator picks a
+ * session and steps through what happened — they want a stable frozen
+ * view, not a live tail. SSE would force the scrubber to keep chasing
+ * a moving end-of-stream and complicate the UI without paying for it.
+ *
+ * Memory: bounded by whatever the underlying SessionStore retains.
+ * `InMemorySessionStore` keeps everything for the process lifetime —
+ * fine for OSS dev. A hosted closed runtime's persistent store is the
+ * durability surface.
+ */
+import type { Express } from 'express';
+import type { SessionStore, SessionStreamBuffer } from '@ggui-ai/mcp-server-core';
+/**
+ * Mount `/ggui/console/timeline/*` routes on `app`. Caller is
+ * responsible for admin-gating the path prefix beforehand — this
+ * function does not re-implement auth (matches the
+ * `mountConsoleLlmTraceRoutes` shape in console-llm-trace.ts).
+ */
+export declare function mountConsoleTimelineRoutes(app: Express, sessionStore: SessionStore | undefined, streamBuffer: SessionStreamBuffer | undefined): void;
+//# sourceMappingURL=console-timeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-timeline.d.ts","sourceRoot":"","sources":["../src/console-timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAqB,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAkElC;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,YAAY,EAAE,mBAAmB,GAAG,SAAS,GAC5C,IAAI,CA8JN"}

package/dist/console-timeline.js

@@ -0,0 +1,169 @@
+import { applyDevtoolSecurityHeaders } from './console-headers.js';
+/**
+ * Drain {@link SessionStore.observe} into an array. The observe iterator
+ * with `{ tail: false }` resolves cleanly after replaying every stored
+ * event, so this is a plain `for await`. Bound by the store's per-
+ * session retention (in-memory: full history; hosted: store-defined).
+ */
+async function drainSessionEvents(sessionStore, sessionId) {
+    const out = [];
+    for await (const event of sessionStore.observe(sessionId, {
+        fromSeq: 1,
+        tail: false,
+    })) {
+        out.push(event);
+    }
+    return out;
+}
+/**
+ * Mount `/ggui/console/timeline/*` routes on `app`. Caller is
+ * responsible for admin-gating the path prefix beforehand — this
+ * function does not re-implement auth (matches the
+ * `mountConsoleLlmTraceRoutes` shape in console-llm-trace.ts).
+ */
+export function mountConsoleTimelineRoutes(app, sessionStore, streamBuffer) {
+    // GET /ggui/console/timeline/sessions?limit=<n>
+    app.get('/ggui/console/timeline/sessions', async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const limitRaw = req.query['limit'];
+        let limit = 50;
+        if (typeof limitRaw === 'string') {
+            const parsed = Number.parseInt(limitRaw, 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                limit = Math.min(200, parsed);
+            }
+        }
+        // Zero-config shape: no store wired (pure-MCP boot) → empty list.
+        if (!sessionStore) {
+            const body = { sessions: [], total: 0 };
+            res.json(body);
+            return;
+        }
+        try {
+            // No status filter — operators want to debug completed +
+            // expired sessions, not just live ones. Limit is post-filter
+            // so the response stays bounded.
+            const sessions = await sessionStore.list({});
+            const summaries = [];
+            const now = Date.now();
+            for (const session of sessions) {
+                let streamSeq = 0;
+                if (streamBuffer) {
+                    try {
+                        streamSeq = await streamBuffer.currentSeq(session.id);
+                    }
+                    catch {
+                        // Stream-cursor lookup is best-effort metadata; an
+                        // adapter error must not blank the picker.
+                    }
+                }
+                // Compute status from session state (the store doesn't
+                // surface its private `closed` flag on the Session type).
+                // We mirror the InMemorySessionStore's `computeStatus` rule:
+                // expired = expiresAt <= now, otherwise active. The
+                // 'completed' state needs the closed flag to disambiguate;
+                // we report 'active' until eviction. Operators reading the
+                // detail pane get the authoritative status from the store.
+                const status = session.expiresAt <= now ? 'expired' : 'active';
+                summaries.push({
+                    sessionId: session.id,
+                    appId: session.appId,
+                    stackSize: session.stack.length,
+                    createdAt: session.createdAt,
+                    lastActivityAt: session.lastActivityAt,
+                    status,
+                    streamSeq,
+                });
+            }
+            // Most-recent activity first. Tiebreak on sessionId for
+            // stable ordering across reloads.
+            summaries.sort((a, b) => {
+                const byRecency = b.lastActivityAt - a.lastActivityAt;
+                if (byRecency !== 0)
+                    return byRecency;
+                return a.sessionId.localeCompare(b.sessionId);
+            });
+            const trimmed = summaries.slice(0, limit);
+            const body = {
+                sessions: trimmed,
+                total: summaries.length,
+            };
+            res.json(body);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: 'timeline_sessions_list_failed',
+                message: err instanceof Error
+                    ? `Session store failed to list — ${err.message}`
+                    : `Session store failed to list — ${String(err)}`,
+            });
+        }
+    });
+    // GET /ggui/console/timeline/:sessionId/events
+    app.get('/ggui/console/timeline/:sessionId/events', async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const sessionId = req.params['sessionId'];
+        if (!sessionId || sessionId.length === 0) {
+            res.status(400).json({
+                error: 'invalid_session_id',
+                message: 'sessionId path parameter is required',
+            });
+            return;
+        }
+        // Zero-config shape: no store wired → empty events.
+        if (!sessionStore) {
+            const body = {
+                sessionId,
+                events: [],
+                streamSeq: 0,
+                status: 'unknown',
+            };
+            res.json(body);
+            return;
+        }
+        try {
+            const session = await sessionStore.get(sessionId);
+            if (!session) {
+                // 404 is the right status — but we still return a well-
+                // formed body so the SPA can render an "expired/dropped"
+                // notice without a special-case branch. Body matches the
+                // schema; status code disambiguates.
+                const body = {
+                    sessionId,
+                    events: [],
+                    streamSeq: 0,
+                    status: 'unknown',
+                };
+                res.status(404).json(body);
+                return;
+            }
+            const events = await drainSessionEvents(sessionStore, sessionId);
+            let streamSeq = 0;
+            if (streamBuffer) {
+                try {
+                    streamSeq = await streamBuffer.currentSeq(sessionId);
+                }
+                catch {
+                    // Best-effort. Inbound events stand on their own.
+                }
+            }
+            const now = Date.now();
+            const status = session.expiresAt <= now ? 'expired' : 'active';
+            const body = {
+                sessionId,
+                events,
+                streamSeq,
+                status,
+            };
+            res.json(body);
+        }
+        catch (err) {
+            res.status(500).json({
+                error: 'timeline_events_drain_failed',
+                message: err instanceof Error
+                    ? `Session store failed to drain — ${err.message}`
+                    : `Session store failed to drain — ${String(err)}`,
+            });
+        }
+    });
+}

package/dist/console-validator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Console-facing validator-trace sink + REST/SSE endpoints powering
+ * `/devtools/validator` in the @ggui-ai/console SPA.
+ *
+ * This is the OSS-default sink the `ggui serve` process registers via
+ * {@link setValidatorTraceSink}. A hosted closed runtime may swap in a
+ * durable sink (e.g. Redis-backed) — the harness only knows about the
+ * {@link ValidatorTraceSink} contract.
+ *
+ * **Two surfaces, both admin-gated:**
+ *   - `GET /ggui/console/validator/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/validator/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
+ * the source-under-check (capped at ~16KB by truncateSourceForTrace)
+ * plus the full issues array — at ~20-30KB/event that's ~4-6MB peak.
+ * Operator can override via `createGguiServer({ validatorTrace: {
+ * capacity }})` if running on a small box.
+ */
+import type { Express } from 'express';
+import type { ValidatorTraceEvent, ValidatorTraceSink } from '@ggui-ai/ui-gen/harness/validator-trace-sink';
+/** SSE listener — receives one event per runCheck invocation. */
+type SseListener = (event: ValidatorTraceEvent) => void;
+/**
+ * In-memory ring buffer + listener fanout. Implements
+ * {@link ValidatorTraceSink} so it can be passed to
+ * {@link setValidatorTraceSink}.
+ *
+ * **Why a class, not a closure.** Tests + operators read state
+ * (`recent()`, listener count) — instance methods on a class beat a
+ * pile of getter functions captured in scope. The shape is also the
+ * extension point if a hosted closed runtime wants to subclass and
+ * pipe events to Redis / DDB / S3 in addition to the ring buffer.
+ */
+export declare class BoundedValidatorTraceSink implements ValidatorTraceSink {
+    private readonly capacity;
+    private readonly buffer;
+    private readonly listeners;
+    constructor(opts?: {
+        readonly capacity?: number;
+    });
+    emit(event: ValidatorTraceEvent): 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 ValidatorTraceEvent[];
+    /** 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/validator/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 mountConsoleValidatorRoutes(app: Express, sink: BoundedValidatorTraceSink): void;
+export {};
+//# sourceMappingURL=console-validator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-validator.d.ts","sourceRoot":"","sources":["../src/console-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAqB,OAAO,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,8CAA8C,CAAC;AAGtD,iEAAiE;AACjE,KAAK,WAAW,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAExC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAUjD,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;IActC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IAKrD,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,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,yBAAyB,GAC9B,IAAI,CA8CN"}

package/dist/console-validator.js

@@ -0,0 +1,105 @@
+import { applyDevtoolSecurityHeaders } from './console-headers.js';
+/**
+ * In-memory ring buffer + listener fanout. Implements
+ * {@link ValidatorTraceSink} so it can be passed to
+ * {@link setValidatorTraceSink}.
+ *
+ * **Why a class, not a closure.** Tests + operators read state
+ * (`recent()`, listener count) — instance methods on a class beat a
+ * pile of getter functions captured in scope. The shape is also the
+ * extension point if a hosted closed runtime wants to subclass and
+ * pipe events to Redis / DDB / S3 in addition to the ring buffer.
+ */
+export class BoundedValidatorTraceSink {
+    capacity;
+    buffer = [];
+    listeners = new Set();
+    constructor(opts) {
+        const cap = opts?.capacity ?? 200;
+        if (!Number.isFinite(cap) || cap <= 0) {
+            throw new Error(`BoundedValidatorTraceSink: 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/validator/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 mountConsoleValidatorRoutes(app, sink) {
+    // GET /ggui/console/validator/recent?limit=<n> — JSON snapshot.
+    app.get('/ggui/console/validator/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/validator/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/validator/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-welcome.d.ts

@@ -0,0 +1,7 @@
+import type { OperatorConfig } from '@ggui-ai/project-config';
+export interface WelcomePageInputs {
+    readonly operator?: OperatorConfig;
+    readonly appName?: string;
+}
+export declare const renderWelcomeHtml: (inputs: WelcomePageInputs, serverName: string) => string;
+//# sourceMappingURL=console-welcome.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console-welcome.d.ts","sourceRoot":"","sources":["../src/console-welcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAoDD,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,iBAAiB,EACzB,YAAY,MAAM,KACjB,MA6KF,CAAC"}