@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.3.0-rc.0

package/dist/console-blueprint-routes.js

@@ -0,0 +1,348 @@
+/**
+ * Console blueprint resolution + try-live routes.
+ *
+ *   GET  /ggui/console/blueprint/:id       — same-origin HTTP mirror of
+ *        the `ggui_render_blueprint` MCP tool. Resolves a
+ *        manifest-declared blueprint id to its compiled bundle +
+ *        metadata via the wired `UiRegistry`; lets the SPA's
+ *        `/preview/<id>` route mount the blueprint with a single fetch
+ *        instead of negotiating a full MCP round-trip from the browser.
+ *   POST /ggui/console/blueprint/:id/try   — create a render, compile
+ *        the blueprint's componentCode, commit a render with its full
+ *        contract (actionSpec/streamSpec/propsSpec from the manifest),
+ *        mint a shortCode, and return `{sessionId, shortCode, url}`.
+ *        The returned `/s/<shortCode>` lands on the console's render
+ *        viewer + subscribes to the render over `/ws`.
+ *
+ * Scope: registered only when a `UiRegistry` is present (same gate
+ * as the MCP render handler — no registry = no render path, no
+ * endpoint). No bearer auth: console routes are same-origin
+ * operator-facing; the operator already has OS access to the TSX
+ * sources this endpoint serves back.
+ *
+ * GET failure shape: { error, message } with a matching HTTP code.
+ *   - 404 for unknown id OR known-id-no-bundle (source-only /
+ *     compile-failed). The operator's remediation is the same in
+ *     both cases (fix the manifest / fix the entry / fix the
+ *     compile); splitting codes would add noise without signal.
+ *   - 400 for malformed id parameters (empty, oversized).
+ *
+ * Shape symmetry: GET matches `GguiRenderBlueprintOutput` exactly, so
+ * the browser-side fetch can share a type import with MCP-tool
+ * callers without a translation layer.
+ *
+ * Try-live gates (all three required):
+ *   - `uiRegistry`     — blueprint resolution
+ *   - `renderStore`    — render persistence
+ *   - `shortCodeIndex` — shortCode → render binding
+ *
+ * Partial gate (uiRegistry alone) → 503 with a remediation hint.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+import { checkRenderSchemaCompat, SchemaCompatError, } from "./schema-compat.js";
+/**
+ * 18-char URL-safe shortCode for `POST /ggui/console/blueprint/:id/try`
+ * — visually distinct from the 16-char render-minted shortCodes in
+ * `@ggui-ai/mcp-server-handlers/renders/render.ts` so operators
+ * reading logs can tell a try-live render from an agent-rendered one
+ * at a glance. Same confusable-free alphabet
+ * (`[a-z0-9]` minus `1lI0Oo`) so the code stays hand-typable. Entropy
+ * ≈ 18 × log₂(31) ≈ 89 bits.
+ */
+function generateTryLiveShortCode() {
+    const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
+    const bytes = randomBytes(18);
+    let out = "";
+    for (let i = 0; i < 18; i += 1) {
+        out += alphabet[bytes[i] % alphabet.length];
+    }
+    return out;
+}
+/**
+ * Mount `GET /ggui/console/blueprint/:id` +
+ * `POST /ggui/console/blueprint/:id/try` onto the express app.
+ * Returns nothing — the routes self-register.
+ */
+export function mountConsoleBlueprintRoutes(opts) {
+    const { app, uiRegistry, renderStore, shortCodeIndex, handlers, schemaCompatMode, logger } = opts;
+    if (renderStore && shortCodeIndex) {
+        const renderStoreForTry = renderStore;
+        const shortCodeIndexForTry = shortCodeIndex;
+        app.post("/ggui/console/blueprint/:id/try", async (req, res) => {
+            applyDevtoolSecurityHeaders(res);
+            const blueprintId = req.params["id"];
+            if (typeof blueprintId !== "string" || blueprintId.length === 0 || blueprintId.length > 256) {
+                res.status(400).json({
+                    error: "invalid_request",
+                    message: "`id` path parameter must be a non-empty string (≤256 chars)",
+                });
+                return;
+            }
+            try {
+                const entry = await uiRegistry.get(blueprintId);
+                if (!entry) {
+                    res.status(404).json({
+                        error: "not_found",
+                        message: `No blueprint registered with id "${blueprintId}". Check ggui.json#blueprints.include globs + ggui.ui.json#id values.`,
+                    });
+                    return;
+                }
+                const bundle = await uiRegistry.getBundle(blueprintId);
+                if (!bundle) {
+                    res.status(404).json({
+                        error: "bundle_not_available",
+                        message: `Blueprint "${blueprintId}" (${entry.manifest.name}) has no bundle available. Either the TSX entry is missing or compile-on-demand failed.`,
+                    });
+                    return;
+                }
+                // Materialize streamed bundles to a string — the render
+                // stores componentCode inline. Same rule the sibling GET
+                // endpoint applies.
+                let code;
+                if (typeof bundle.code === "string") {
+                    code = bundle.code;
+                }
+                else {
+                    const reader = bundle.code.getReader();
+                    const decoder = new TextDecoder();
+                    let out = "";
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        if (typeof value === "string")
+                            out += value;
+                        else if (value instanceof Uint8Array)
+                            out += decoder.decode(value, { stream: true });
+                    }
+                    out += decoder.decode();
+                    code = out;
+                }
+                // Same default appId the CLI's pairing-authenticated /mcp
+                // ingress resolves for single-tenant OSS — the render is
+                // scoped to the same tenant.
+                const appId = DEFAULT_BUILDER_APP_ID;
+                // Phase B: a render IS the addressable unit; the prior
+                // (sessionId, stackItemId) pair collapses to a single
+                // sessionId. The blueprint id makes a natural slug; a
+                // same-blueprint retry replaces the row.
+                const sessionId = `try-${blueprintId}-${randomUUID()}`;
+                const createdAt = Date.now();
+                const contract = entry.manifest.contract ?? {};
+                const render = {
+                    id: sessionId,
+                    appId,
+                    type: "component",
+                    componentCode: code,
+                    contentType: bundle.contentType,
+                    eventSequence: 0,
+                    createdAt,
+                    lastActivityAt: createdAt,
+                    expiresAt: createdAt + 24 * 60 * 60 * 1000,
+                    description: `Blueprint try-live: ${entry.manifest.name}`,
+                    // Data contract fields from the manifest. Each is
+                    // conditionally spread — absent on the manifest →
+                    // absent on the GguiSession (keeps shape honest + avoids
+                    // an empty-shape contract tripping structural
+                    // validators downstream).
+                    ...(contract.propsSpec ? { propsSpec: contract.propsSpec } : {}),
+                    ...(contract.actionSpec ? { actionSpec: contract.actionSpec } : {}),
+                    ...(contract.streamSpec ? { streamSpec: contract.streamSpec } : {}),
+                };
+                // Schema compatibility check. Fires BEFORE the render
+                // commits — if the blueprint's pre-declared actionSpec
+                // hints at a same-server tool whose schemas don't align,
+                // the operator gets a named `SCHEMA_MISMATCH_ERROR`
+                // response at registration time instead of an agent-side
+                // surprise on the first dispatched action. Mode sourced
+                // from `createGguiServer({schemaCompatCheck})`; defaults
+                // to `'reject'`. See `./schema-compat.ts`.
+                try {
+                    const report = checkRenderSchemaCompat(render, handlers, schemaCompatMode, `console blueprint-try:${blueprintId}`);
+                    if (!report.compatible) {
+                        // Non-throwing path (mode === 'warn'): log with full
+                        // detail so the operator has an observable surface.
+                        logger.warn("schema_compat_warn", {
+                            site: "console_blueprint_try",
+                            blueprintId,
+                            findingCount: report.findings.length,
+                            findings: report.findings.map((f) => ({
+                                kind: f.kind,
+                                specName: f.specName,
+                                toolName: f.toolName,
+                                reason: f.reason,
+                                violationCount: f.violations.length,
+                            })),
+                        });
+                    }
+                }
+                catch (err) {
+                    if (err instanceof SchemaCompatError) {
+                        logger.warn("console_blueprint_try_schema_compat_rejected", {
+                            blueprintId,
+                            findingCount: err.report.findings.length,
+                        });
+                        res.status(422).json({
+                            error: "SCHEMA_MISMATCH_ERROR",
+                            message: err.message,
+                            findings: err.report.findings.map((f) => ({
+                                kind: f.kind,
+                                specName: f.specName,
+                                toolName: f.toolName,
+                                reason: f.reason,
+                                violationCount: f.violations.length,
+                            })),
+                        });
+                        return;
+                    }
+                    throw err;
+                }
+                try {
+                    await renderStoreForTry.commit({ render, appId });
+                }
+                catch (err) {
+                    logger.warn("console_blueprint_try_commit_failed", {
+                        blueprintId,
+                        sessionId,
+                        error: String(err),
+                    });
+                    res.status(500).json({
+                        error: "commit_failed",
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                    return;
+                }
+                // Mint the shortCode last — if earlier steps failed the
+                // client never sees a dangling mapping. Best-effort bind
+                // to match render.ts's posture (a put failure shouldn't
+                // fail the whole try-live — a 500 here would leave the
+                // render behind with no way to resolve from
+                // `/s/<shortCode>`, but the operator can still hit the
+                // render via `/ggui/console/sessions`).
+                const shortCode = generateTryLiveShortCode();
+                try {
+                    await shortCodeIndexForTry.put(shortCode, {
+                        sessionId,
+                        appId,
+                    });
+                }
+                catch (err) {
+                    logger.warn("console_blueprint_try_shortcode_failed", {
+                        blueprintId,
+                        sessionId,
+                        shortCode,
+                        error: String(err),
+                    });
+                    // Don't fail the response — the client can reopen via
+                    // the renders list. Surface the issue in the payload
+                    // so the SPA can show a degraded banner.
+                    res.status(200).json({
+                        sessionId,
+                        shortCode: null,
+                        url: null,
+                        warning: "shortCode minted but not persisted; viewer link unavailable. Open via /ggui/console/sessions.",
+                    });
+                    return;
+                }
+                res.json({
+                    sessionId,
+                    shortCode,
+                    url: `/s/${shortCode}`,
+                });
+            }
+            catch (err) {
+                logger.warn("console_blueprint_try_failed", {
+                    blueprintId,
+                    error: String(err),
+                });
+                res.status(500).json({
+                    error: "try_failed",
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        });
+    }
+    else {
+        // Partial wiring — /try would attempt a render create that
+        // has nowhere to land. Surface with 503 + specific message
+        // so the operator knows which seam to add (console cookie +
+        // shortCodeIndex live on `console.sessionCookie: true`).
+        app.post("/ggui/console/blueprint/:id/try", (_req, res) => {
+            applyDevtoolSecurityHeaders(res);
+            res.status(503).json({
+                error: "try_not_wired",
+                message: "POST /ggui/console/blueprint/:id/try requires `renderChannel: true` + `shortCodeIndex` on createGguiServer. The CLI enables both by default via `console.sessionCookie: true`.",
+            });
+        });
+    }
+    app.get("/ggui/console/blueprint/:id", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const blueprintId = req.params["id"];
+        if (typeof blueprintId !== "string" || blueprintId.length === 0 || blueprintId.length > 256) {
+            res.status(400).json({
+                error: "invalid_request",
+                message: "`id` path parameter must be a non-empty string (≤256 chars)",
+            });
+            return;
+        }
+        try {
+            const entry = await uiRegistry.get(blueprintId);
+            if (!entry) {
+                res.status(404).json({
+                    error: "not_found",
+                    message: `No blueprint registered with id "${blueprintId}". Check ggui.json#blueprints.include globs + ggui.ui.json#id values.`,
+                });
+                return;
+            }
+            const bundle = await uiRegistry.getBundle(blueprintId);
+            if (!bundle) {
+                res.status(404).json({
+                    error: "bundle_not_available",
+                    message: `Blueprint "${blueprintId}" (${entry.manifest.name}) has no bundle available. Either the TSX entry is missing or compile-on-demand failed — check the manifest directory.`,
+                });
+                return;
+            }
+            // Same string-materialization rule as the MCP render handler:
+            // collapse stream bundles to a plain string so the browser
+            // fetch can JSON-parse the response in one shot.
+            let code;
+            if (typeof bundle.code === "string") {
+                code = bundle.code;
+            }
+            else {
+                const reader = bundle.code.getReader();
+                const decoder = new TextDecoder();
+                let out = "";
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (typeof value === "string")
+                        out += value;
+                    else if (value instanceof Uint8Array)
+                        out += decoder.decode(value, { stream: true });
+                }
+                out += decoder.decode();
+                code = out;
+            }
+            res.json({
+                blueprintId,
+                blueprintName: entry.manifest.name,
+                code,
+                contentType: bundle.contentType,
+            });
+        }
+        catch (err) {
+            logger.warn("console_blueprint_resolve_failed", {
+                blueprintId,
+                error: String(err),
+            });
+            res.status(500).json({
+                error: "resolve_failed",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+}

package/dist/console-chat-routes.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Console dev-chat round-trip route.
+ *
+ *   POST /ggui/console/chat/message — OSS dev chat round-trip.
+ *
+ * Routes the message through `ggui_render` whenever the server was
+ * composed with a real generator — turning the chat surface into
+ * the cohesive agent experience: every user message commits a
+ * render against a thread-scoped render; the render handler owns
+ * generation, cache, and provisional preview; the client renders
+ * the resulting render inline using `GguiSessionRenderer`.
+ *
+ * Shape: `{ text, threadId?, sessionId? }` →
+ * `{ threadId, userMessage, agentMessage, ui? }`.
+ *   - `ui` is populated only when the render handler is wired AND
+ *     the call succeeded. `ui.sessionId` is the render id the client
+ *     subscribes to over `/ws`; the committed render arrives via
+ *     the subscribe ack's single `render` field, which the client
+ *     mounts inline to show the agent's generated component.
+ *   - When the render handler is NOT wired (no `mcpApps`, placeholder
+ *     mode, or no BYOK), `ui` is absent and `agentMessage.text`
+ *     carries an honest text-only acknowledgment. This preserves
+ *     the text-only round-trip path so operators without a key can
+ *     still exercise the chat UI end-to-end.
+ *   - `sessionId` is echoed on every response and should be passed
+ *     back on subsequent messages so the thread reuses one render.
+ *
+ * Same-origin only — no bearer auth. The console surface is
+ * always the operator's own browser pointing at their own `ggui
+ * serve` instance; adding bearer auth here would block the
+ * dev-page-is-usable claim without meaningful security gain.
+ *
+ * The render invocation uses `DEFAULT_BUILDER_APP_ID` for tenant
+ * scope — same well-known value the `/mcp` endpoint collapses to
+ * in OSS single-user mode. Matches blueprint + vector scoping
+ * applied by the generator / cache seams.
+ *
+ * Handler gate: without a generator wired, a render call would
+ * allocate a render + shortCode with empty componentCode
+ * (codeReady:false) per turn without any visible UI — honest
+ * behavior but useless. Falling through to the canned-text path
+ * keeps the chat surface usable without a BYOK key AND preserves
+ * the exact Lane-1 chat-page spec assertion (`/OSS agent
+ * generation/`) without a copy change.
+ */
+import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import type { Express } from "express";
+import type { ZodRawShape } from "zod";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /**
+     * `ggui_render` handler — present only when the composer resolved
+     * generation deps (the gate that makes a render turn useful).
+     */
+    readonly renderHandler?: SharedHandler<ZodRawShape, ZodRawShape>;
+    /** `ggui_handshake` handler paired with the render handler. */
+    readonly handshakeHandler?: SharedHandler<ZodRawShape, ZodRawShape>;
+    /**
+     * Console session-cookie wiring. Present only when the cookie flow
+     * is enabled — each successful render turn then mints a same-origin
+     * HttpOnly cookie so the chat can open the /ws subscription without
+     * a separate POST to /ggui/console/session-cookie.
+     */
+    readonly sessionCookie?: {
+        readonly secret: string;
+        readonly ttlSec?: number;
+        readonly secure: boolean;
+    };
+    /** Structured logger. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `POST /ggui/console/chat/message` onto the express app.
+ * Returns nothing — the route self-registers.
+ */
+export declare function mountConsoleChatRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-chat-routes.d.ts.map

package/dist/console-chat-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-chat-routes.d.ts","sourceRoot":"","sources":["../src/console-chat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAIvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAsJ/D"}

package/dist/console-chat-routes.js

@@ -0,0 +1,182 @@
+/**
+ * Console dev-chat round-trip route.
+ *
+ *   POST /ggui/console/chat/message — OSS dev chat round-trip.
+ *
+ * Routes the message through `ggui_render` whenever the server was
+ * composed with a real generator — turning the chat surface into
+ * the cohesive agent experience: every user message commits a
+ * render against a thread-scoped render; the render handler owns
+ * generation, cache, and provisional preview; the client renders
+ * the resulting render inline using `GguiSessionRenderer`.
+ *
+ * Shape: `{ text, threadId?, sessionId? }` →
+ * `{ threadId, userMessage, agentMessage, ui? }`.
+ *   - `ui` is populated only when the render handler is wired AND
+ *     the call succeeded. `ui.sessionId` is the render id the client
+ *     subscribes to over `/ws`; the committed render arrives via
+ *     the subscribe ack's single `render` field, which the client
+ *     mounts inline to show the agent's generated component.
+ *   - When the render handler is NOT wired (no `mcpApps`, placeholder
+ *     mode, or no BYOK), `ui` is absent and `agentMessage.text`
+ *     carries an honest text-only acknowledgment. This preserves
+ *     the text-only round-trip path so operators without a key can
+ *     still exercise the chat UI end-to-end.
+ *   - `sessionId` is echoed on every response and should be passed
+ *     back on subsequent messages so the thread reuses one render.
+ *
+ * Same-origin only — no bearer auth. The console surface is
+ * always the operator's own browser pointing at their own `ggui
+ * serve` instance; adding bearer auth here would block the
+ * dev-page-is-usable claim without meaningful security gain.
+ *
+ * The render invocation uses `DEFAULT_BUILDER_APP_ID` for tenant
+ * scope — same well-known value the `/mcp` endpoint collapses to
+ * in OSS single-user mode. Matches blueprint + vector scoping
+ * applied by the generator / cache seams.
+ *
+ * Handler gate: without a generator wired, a render call would
+ * allocate a render + shortCode with empty componentCode
+ * (codeReady:false) per turn without any visible UI — honest
+ * behavior but useless. Falling through to the canned-text path
+ * keeps the chat surface usable without a BYOK key AND preserves
+ * the exact Lane-1 chat-page spec assertion (`/OSS agent
+ * generation/`) without a copy change.
+ */
+import { randomUUID } from "node:crypto";
+import { DEFAULT_BUILDER_APP_ID } from "./auth.js";
+import { mintDevtoolCookie } from "./console-auth.js";
+import { applyDevtoolSecurityHeaders } from "./console-headers.js";
+/**
+ * Mount `POST /ggui/console/chat/message` onto the express app.
+ * Returns nothing — the route self-registers.
+ */
+export function mountConsoleChatRoutes(opts) {
+    const { app, renderHandler, handshakeHandler, sessionCookie, logger } = opts;
+    app.post("/ggui/console/chat/message", async (req, res) => {
+        applyDevtoolSecurityHeaders(res);
+        const body = (req.body ?? {});
+        const text = typeof body.text === "string" ? body.text.trim() : "";
+        if (text.length === 0) {
+            res.status(400).json({
+                error: "invalid_request",
+                message: "`text` (non-empty string) is required",
+            });
+            return;
+        }
+        if (text.length > 4000) {
+            res.status(400).json({
+                error: "invalid_request",
+                message: "`text` must be <= 4000 chars",
+            });
+            return;
+        }
+        const threadId = typeof body.threadId === "string" && body.threadId.length > 0
+            ? body.threadId
+            : `chat-${randomUUID()}`;
+        const now = Date.now();
+        const userMessage = {
+            id: `msg-${randomUUID()}`,
+            role: "user",
+            text,
+            createdAt: now,
+        };
+        // Attempt real generation through `ggui_render` when wired.
+        // `renderHandler` is undefined when mcpApps was disabled or
+        // the operator built a custom handler set without render. The
+        // handler itself returns `codeReady:false` when generation deps
+        // aren't wired (no BYOK) — we surface that honestly on the
+        // agentMessage text without pretending a UI landed.
+        let ui;
+        let agentText;
+        if (renderHandler && handshakeHandler) {
+            try {
+                const requestId = randomUUID();
+                const handshakeInput = {
+                    story: { intent: text, contract: {} },
+                };
+                const hsRaw = await handshakeHandler.handler(handshakeInput, {
+                    appId: DEFAULT_BUILDER_APP_ID,
+                    requestId,
+                });
+                const handshakeId = hsRaw.handshakeId;
+                const raw = await renderHandler.handler({ handshakeId, contract: {} }, { appId: DEFAULT_BUILDER_APP_ID, requestId });
+                const result = raw;
+                ui = {
+                    sessionId: result.sessionId,
+                    shortCode: result.shortCode,
+                    codeReady: result.codeReady,
+                    ...(result.cache ? { cache: result.cache } : {}),
+                };
+                // If console cookie auth is enabled, mint a session
+                // cookie so the chat can open the /ws subscription without
+                // a separate POST to /ggui/console/session-cookie. Single round-trip
+                // per turn; cookie is same-origin HttpOnly.
+                if (sessionCookie) {
+                    const mint = mintDevtoolCookie({
+                        sessionId: result.sessionId,
+                        appId: DEFAULT_BUILDER_APP_ID,
+                        secret: sessionCookie.secret,
+                        ...(sessionCookie.ttlSec !== undefined ? { ttlSec: sessionCookie.ttlSec } : {}),
+                        secure: sessionCookie.secure,
+                    });
+                    res.setHeader("Set-Cookie", mint.setCookieHeader);
+                }
+                if (result.codeReady) {
+                    agentText = result.cache?.hit
+                        ? "Reused a matching UI from cache for your request."
+                        : "Generated a UI for your request.";
+                }
+                else {
+                    // Generator ran but produced no code (no BYOK, generator
+                    // error, or placeholder mode). Honest text so the
+                    // operator knows why the surface didn't render a UI.
+                    agentText =
+                        "I received your message, but generation did not produce a UI " +
+                            "(no BYOK key configured, or the provider declined). Export " +
+                            "ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY / " +
+                            "OPENROUTER_API_KEY and retry.";
+                    // Drop the ui payload — no code ready means nothing to
+                    // render inline. The agent text carries the diagnosis.
+                    ui = undefined;
+                }
+            }
+            catch (err) {
+                logger.warn?.("console_chat_render_failed", {
+                    threadId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                agentText =
+                    "Generation failed: " +
+                        (err instanceof Error ? err.message : String(err)) +
+                        ". The chat surface is still live — retry or try a different prompt.";
+                ui = undefined;
+            }
+        }
+        const agentMessage = {
+            id: `msg-${randomUUID()}`,
+            role: "agent",
+            text: agentText ??
+                // No render handler at all — text-only fallback. Keeps the
+                // Lane-1 chat-page spec green by preserving the exact copy
+                // it asserts against.
+                "Message received. OSS agent generation is not yet wired — " +
+                    "this is the text-only dev chat. Full responses " +
+                    "and generated UIs arrive once the generator port lands.",
+            createdAt: now + 1,
+        };
+        logger.debug?.("console_chat_message", {
+            threadId,
+            userMessageId: userMessage.id,
+            textLength: text.length,
+            uiSessionId: ui?.sessionId,
+            uiCodeReady: ui?.codeReady,
+        });
+        res.status(200).json({
+            threadId,
+            userMessage,
+            agentMessage,
+            ...(ui ? { ui } : {}),
+        });
+    });
+}

package/dist/console-config-routes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Console manifest-read route.
+ *
+ *   GET /ggui/console/config — VSCode-settings-style read of the
+ *   resolved `ggui.json`. Returns the parsed manifest, the raw
+ *   file contents for display, and the introspected v1 JSON Schema
+ *   (which carries field descriptions via the `.describe()` calls
+ *   on `GguiJsonV1`).
+ *
+ * Source resolution: walks up from `process.cwd()` to find the
+ * nearest `ggui.json`. Honest about three states:
+ *   - found + valid → `{source: {found:true, path}, manifest, raw, schema}`
+ *   - found + invalid → `{source: {found:true, path, error: {message}},
+ *     raw, schema}` (no manifest field — the operator inspects the raw
+ *     bytes + sees the validation error so they can fix the file)
+ *   - not found → `{source: {found:false, searchedFrom}, schema}`
+ *     (the schema still ships so operators can browse what would be
+ *     configurable IF a manifest existed)
+ *
+ * Read-only. Form controls on the same payload and a PATCH
+ * endpoint with atomic write + conflict detection layer on top.
+ */
+import type { Express } from "express";
+import type { Logger } from "./logger.js";
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Structured logger for read/conversion warnings. */
+    readonly logger: Logger;
+}
+/**
+ * Mount `GET /ggui/console/config` onto the express app. Returns
+ * nothing — the route self-registers.
+ */
+export declare function mountConsoleConfigRoutes(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=console-config-routes.d.ts.map

package/dist/console-config-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-config-routes.d.ts","sourceRoot":"","sources":["../src/console-config-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAIvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA0DjE"}