@ggui-ai/cli 0.1.0-rc.1

package/dist/serve-command.js

@@ -0,0 +1,616 @@
+import { launchBrowser } from './dev-command.js';
+/**
+ * Default bind port. Distinct from `ggui dev`'s 6780 so both can run
+ * simultaneously without colliding. Not a registered port; chosen for
+ * memorability + non-collision with the dev hub.
+ */
+export const DEFAULT_SERVE_PORT = 6781;
+/** Default bind host. Loopback only — matches `ggui dev`. */
+export const DEFAULT_SERVE_HOST = '127.0.0.1';
+/**
+ * Parse the raw `ggui serve` argv tail. Returns a discriminated
+ * shape — `error` field is non-undefined on malformed input.
+ *
+ * Flag surface per the §10.2a lock:
+ *   - `--port <n>` / `--host <addr>`: bind target.
+ *   - `--mcp-only`: opt-down to MCP-only.
+ *   - `--all`: REJECTED with a pointer to the real default. See doc lock.
+ *   - `--help` / `-h`: help sentinel.
+ */
+export function parseServeFlags(args) {
+    const out = {
+        port: DEFAULT_SERVE_PORT,
+        host: DEFAULT_SERVE_HOST,
+        mcpOnly: false,
+        devAllowAll: false,
+        publicDemo: false,
+        multiTenant: false,
+        oauth: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--port') {
+            const v = args[++i];
+            if (v === undefined) {
+                return { ...out, error: '--port requires a value' };
+            }
+            const n = Number(v);
+            if (!Number.isInteger(n) || n < 0 || n > 65535) {
+                return {
+                    ...out,
+                    error: `--port must be an integer in [0, 65535], got "${v}"`,
+                };
+            }
+            out.port = n;
+            continue;
+        }
+        if (arg === '--host') {
+            const v = args[++i];
+            if (v === undefined || v === '') {
+                return { ...out, error: '--host requires a value' };
+            }
+            out.host = v;
+            continue;
+        }
+        if (arg === '--mcp-only') {
+            out.mcpOnly = true;
+            continue;
+        }
+        if (arg === '--dev-allow-all') {
+            out.devAllowAll = true;
+            continue;
+        }
+        if (arg === '--public-demo') {
+            out.publicDemo = true;
+            continue;
+        }
+        if (arg === '--multi-tenant') {
+            out.multiTenant = true;
+            continue;
+        }
+        if (arg === '--oauth') {
+            out.oauth = true;
+            continue;
+        }
+        if (arg === '--public-base-url') {
+            const v = args[++i];
+            if (v === undefined || v === '') {
+                return { ...out, error: '--public-base-url requires a value' };
+            }
+            if (!/^https?:\/\//.test(v)) {
+                return {
+                    ...out,
+                    error: `--public-base-url must start with http:// or https://, got "${v}"`,
+                };
+            }
+            // Strip trailing slash so callers don't have to think about
+            // `${baseUrl}/s/` vs `${baseUrl}//s/` — both are common typos.
+            out.publicBaseUrl = v.replace(/\/+$/, '');
+            continue;
+        }
+        if (arg === '--public') {
+            out.publicAutoTunnel = true;
+            continue;
+        }
+        if (arg === '--i-know-its-public') {
+            out.iKnowItsPublic = true;
+            continue;
+        }
+        if (arg === '--no-open') {
+            out.noOpen = true;
+            continue;
+        }
+        if (arg === '--mcp-instructions') {
+            const v = args[++i];
+            if (v === undefined || v === '') {
+                return { ...out, error: '--mcp-instructions requires a value' };
+            }
+            if (v !== 'default' &&
+                v !== 'aggressive' &&
+                v !== 'always' &&
+                v !== 'minimal' &&
+                v !== 'off') {
+                return {
+                    ...out,
+                    error: `--mcp-instructions must be one of [default, aggressive, always, minimal, off], got "${v}"`,
+                };
+            }
+            out.mcpInstructions = v;
+            continue;
+        }
+        if (arg === '--keys-file') {
+            const v = args[++i];
+            if (v === undefined || v === '') {
+                return { ...out, error: '--keys-file requires a value' };
+            }
+            out.keysFile = v;
+            continue;
+        }
+        if (arg === '--admin-token') {
+            const v = args[++i];
+            if (v === undefined || v === '') {
+                return { ...out, error: '--admin-token requires a value' };
+            }
+            out.adminToken = v;
+            continue;
+        }
+        if (arg === '--ephemeral') {
+            out.ephemeral = true;
+            continue;
+        }
+        if (arg === '--all') {
+            // §10.2a lock: --all is NOT a first-class flag. The default
+            // already runs everything. Reject with a pointer so users
+            // learn the real mental model in one interaction.
+            return {
+                ...out,
+                error: '--all is not a flag. The default already runs everything (MCP + agent). ' +
+                    'Use --mcp-only to run just the MCP server.',
+            };
+        }
+        if (arg === '--help' || arg === '-h') {
+            return { ...out, error: '__help__' };
+        }
+        return { ...out, error: `unknown option "${arg ?? ''}"` };
+    }
+    if (out.devAllowAll && out.publicDemo) {
+        return {
+            ...out,
+            error: '--dev-allow-all and --public-demo are mutually exclusive. ' +
+                '--dev-allow-all is for local-only development (no rate limit, ' +
+                '"DEV ALLOW-ALL" warning); --public-demo is for an operator-paid ' +
+                'public demo (rate-limited, "PUBLIC DEMO" copy). Pick one.',
+        };
+    }
+    if (out.multiTenant && (out.devAllowAll || out.publicDemo)) {
+        return {
+            ...out,
+            error: '--multi-tenant is incompatible with --dev-allow-all and --public-demo. ' +
+                'Multi-tenant requires real per-user identities (kind:"user" / kind:"app"); ' +
+                'the any-bearer modes collapse every caller to kind:"builder" which the ' +
+                'multi-tenant gate rejects. Drop the other flag and pair with real bearers.',
+        };
+    }
+    if (out.publicAutoTunnel && out.publicBaseUrl !== undefined) {
+        return {
+            ...out,
+            error: '--public and --public-base-url are mutually exclusive. ' +
+                '--public auto-spawns a cloudflared quick-tunnel and sets the URL; ' +
+                '--public-base-url pins an explicit URL. Pick one.',
+        };
+    }
+    if (out.publicAutoTunnel && out.devAllowAll && !out.iKnowItsPublic) {
+        return {
+            ...out,
+            error: '--public + --dev-allow-all exposes any-bearer auth to the open ' +
+                'internet via cloudflared. Add --i-know-its-public to acknowledge ' +
+                'this, or pair real bearers and drop --dev-allow-all.',
+        };
+    }
+    return out;
+}
+export function describeServeBanner(input) {
+    const httpUrl = `http://${input.host}:${input.port}`;
+    const lines = [
+        '',
+        `  ${input.serverName} v${input.serverVersion} — community edition · open self-hosted personal-mode`,
+        '',
+        // Operator-facing URL goes first — it's the "open a browser here"
+        // signal that closes the first-run story. Landing page lives at `/`
+        // by default when `ggui serve` is the entry point (see
+        // `cli.ts::buildMcpServerBackend`).
+        `  open      →  ${httpUrl}/`,
+        `  mcp       →  ${httpUrl}/mcp`,
+        `  health    →  ${httpUrl}/ggui/health`,
+        `  tools     →  ${input.toolCount} registered`,
+        `  agent     →  ${describeAgentStatus(input.agent)}`,
+        ...(input.embeddingModel
+            ? [`  rag       →  ${input.embeddingModel} (cached at ~/.ggui/models/)`]
+            : []),
+    ];
+    if (input.publicBaseUrl) {
+        lines.push(`  public    →  ${input.publicBaseUrl}/`);
+    }
+    if (input.pairCode && !input.devAllowAll && !input.publicDemo) {
+        // Pair code is meaningless under any-bearer-auth modes (every
+        // bearer already authenticates); skip it to keep the banner
+        // truthful. Visual + machine-readable pairing affordance. The
+        // machine-readable `PAIR_CODE <code>` line is emitted separately
+        // by `runServe` before the banner; this line is operator-facing.
+        lines.push(`  pair code →  ${input.pairCode}   (valid ~10m)`);
+    }
+    if (input.adminToken) {
+        // Admin token gates the console `/keys` plane (list / mint /
+        // revoke). Operator pastes it into the `/admin-login` page on
+        // first visit. Printed in the same column as the pair-code so
+        // both bearers are obvious in the boot banner.
+        lines.push(`  admin token →  ${input.adminToken}   (console /keys gate — paste at /admin-login)`);
+    }
+    if (input.noLlmKey) {
+        // First-run nudge — without an LLM key, ggui_push falls back to
+        // codeReady:false and the iframe never bootstraps. Surface the
+        // /settings URL alongside admin-token so the operator can paste a
+        // key without restarting (the file store is hot-read on every
+        // generation; setting through /settings takes effect immediately).
+        const settingsUrl = input.publicBaseUrl
+            ? `${input.publicBaseUrl}/settings`
+            : `${httpUrl}/settings`;
+        lines.push(`  ⚠ no LLM key configured. paste one at ${settingsUrl}`, `        (admin-gated — use the admin token above) or export`, `        ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY /`, `        OPENROUTER_API_KEY before re-running.`);
+    }
+    lines.push('');
+    if (input.devAllowAll) {
+        // Loud warning — `--dev-allow-all` accepts any bearer (including
+        // the no-bearer probe MCP custom connectors send) as builder.
+        // Operators should never expose this surface to the open internet
+        // outside an ephemeral tunnel for connector smoke testing.
+        lines.push(`  ⚠ DEV ALLOW-ALL: every bearer authenticates as builder.`, `        For local dev / tunnel smoke ONLY. Never expose to the open`, `        internet. Drop --dev-allow-all to switch back to strict auth.`);
+    }
+    else if (input.publicDemo) {
+        // Distinct from --dev-allow-all: public-demo is a deliberate
+        // operator posture, not an escape hatch. Surfaces (a) cost
+        // attribution (the operator's BYOK funds every visitor's
+        // generations) and (b) the rate-limit ceiling so the operator
+        // remembers what protection is in place if the demo blows up.
+        lines.push(`  ⚠ PUBLIC DEMO: every bearer authenticates as builder.`, `        End-user generations bill the operator's LLM key in`, `        ~/.ggui/credentials.json. Per-IP rate limit on ggui_push`, `        bounds abuse. Drop --public-demo for strict auth.`);
+    }
+    else {
+        lines.push(`  auth: strict — only pair-minted bearer tokens authenticate /mcp.`, `        Pair via the code above (landing page or \`POST /pair\`).`, `        Override the adapter via GguiServer({ auth }) in code for`, `        custom deployments (OIDC, Cognito, etc.).`);
+        if (input.multiTenant) {
+            lines.push(``, `  multi-tenant: each authenticated user manages their OWN LLM`, `        keys at /settings — the gate uses the request's bearer`, `        (Authorization: Bearer their-paired-token), NOT the`, `        admin token. Per-user scope is auto-derived from the`, `        identity (userId / appId).`, `        Note: ggui_push generation still resolves BYOK at the`, `        operator scope (env + credentials-file 'global'). Per-`, `        user generation-time BYOK is a follow-up — for now,`, `        multi-tenant lets each user MANAGE their key plane`, `        without granting them the operator's admin token.`);
+        }
+        if (input.oauth) {
+            lines.push(``, `  oauth: enabled — MCP custom-connector hosts (claude.ai etc.)`, `         can discover via /.well-known/oauth-* and complete the`, `         auth dance against /oauth/{authorize,token,register}.`, `         Paste the paired bearer on the consent page.`);
+        }
+    }
+    lines.push('', `  Ctrl-C to stop.`, '');
+    return lines;
+}
+/**
+ * Banner cell for the `agent` line. Pure — tests pin the copy.
+ */
+export function describeAgentStatus(status) {
+    if (status.kind === 'running') {
+        const runner = status.language === 'ts' ? 'node --import=tsx' : 'node';
+        return `${status.entry} (${runner}) — running`;
+    }
+    switch (status.reason) {
+        case '--mcp-only':
+            return `disabled (--mcp-only)`;
+        case 'no ggui.json':
+            return `disabled (no ggui.json)`;
+        case 'ggui.json has no agent.entry':
+            return `disabled (ggui.json has no agent.entry)`;
+    }
+}
+/**
+ * Boot the backend, start the agent (if any), print the banner, then
+ * block until the shutdown signal fires. On signal, stops both
+ * components gracefully and resolves.
+ *
+ * Agent-crash policy (§10.2a lock): a crash AFTER boot surfaces as
+ * an `onEvent({type:'status', status:'crashed'})` delivery — the
+ * serve loop keeps MCP running and waits for shutdown. No auto-
+ * restart in v1. Operators compose restart policies via their own
+ * supervisor.
+ *
+ * MCP failure surfaces as a thrown error from `backendFactory()` /
+ * `backend.listen()` and propagates to `cli.ts` (exit 1).
+ *
+ * Pure enough to unit-test: the HTTP binding, signal wiring, and
+ * banner render are all either injected or pinned by
+ * {@link describeServeBanner} / {@link describeAgentStatus}.
+ */
+export async function runServe(opts) {
+    const backend = opts.backendFactory();
+    const boundPort = await backend.listen(opts.flags.port, opts.flags.host);
+    // Start the agent AFTER the MCP server is listening. Rationale:
+    // most agents call MCP as soon as they boot; binding first means
+    // the agent's first connect always succeeds. If the agent's
+    // start() throws, we've still bound MCP and can surface the agent
+    // error cleanly without leaving an orphan HTTP server.
+    let agentHandle = null;
+    let unsubscribeAgent = null;
+    if (opts.agent) {
+        const supervision = opts.agent;
+        try {
+            agentHandle = await supervision.adapter.start(supervision.startInput);
+            if (supervision.onEvent) {
+                unsubscribeAgent = agentHandle.subscribe(supervision.onEvent);
+            }
+        }
+        catch (err) {
+            // Start-time failure is a permanent config error per the
+            // AgentRuntimeAdapter contract. Clean up the bound server so
+            // we don't leak a socket.
+            await backend.close();
+            throw err;
+        }
+    }
+    // Pre-mint an initial pairing code so a fresh operator's first-run
+    // flow has a concrete starting point. Without this, `/admin/pair/
+    // init` is gated by a builder bearer the operator doesn't have yet
+    // under strict auth — a chicken-and-egg that only devAllowAll hid.
+    // `activeInit()` on the landing page + the `PAIR_CODE` boot beacon
+    // below both read from the resulting pending code. Absent pairing
+    // (future embedding host opts out) → skip the mint + beacon + the
+    // banner line, leaving the operator on whatever bearer path their
+    // custom adapter provides.
+    //
+    // Skipped under `--dev-allow-all` — every bearer authenticates as
+    // builder there, so a pair code would be cargo-cult dressing on a
+    // permissive auth surface and harnesses parsing `PAIR_CODE` would
+    // get a value that's not actually load-bearing.
+    let initialPair;
+    if (backend.pairingService && !opts.flags.devAllowAll && !opts.flags.publicDemo) {
+        initialPair = await backend.pairingService.initPairing();
+    }
+    // Machine-readable ready beacon. Stable single-line format for
+    // test harnesses + supervisors; goes out BEFORE the pretty banner
+    // so consumers can gate on it without grepping multi-line output.
+    // Format: `READY <baseUrl>\n`.
+    opts.stdout.write(`READY http://${opts.flags.host}:${boundPort}\n`);
+    if (initialPair) {
+        // Paired beacon for harnesses — same stable-line contract as READY.
+        // Format: `PAIR_CODE <code>\n`. Expiry is implicit via the ~10m
+        // TTL the `InMemoryPairingService` ships with; harnesses that
+        // need it can read `GET /ggui/console/info#pairing.pending`.
+        opts.stdout.write(`PAIR_CODE ${initialPair.code}\n`);
+    }
+    if (backend.adminToken) {
+        // Machine-readable admin-token beacon — same stable-line contract
+        // as READY + PAIR_CODE. Harnesses pre-populate the console admin
+        // cookie by reading this off stdout.
+        opts.stdout.write(`ADMIN_TOKEN ${backend.adminToken}\n`);
+    }
+    const bannerLines = describeServeBanner({
+        port: boundPort,
+        host: opts.flags.host,
+        toolCount: backend.toolCount,
+        serverName: backend.serverName,
+        serverVersion: backend.serverVersion,
+        agent: opts.agentStatus,
+        devAllowAll: opts.flags.devAllowAll,
+        publicDemo: opts.flags.publicDemo,
+        multiTenant: opts.flags.multiTenant,
+        oauth: opts.flags.oauth,
+        ...(opts.flags.publicBaseUrl !== undefined
+            ? { publicBaseUrl: opts.flags.publicBaseUrl }
+            : {}),
+        ...(initialPair
+            ? {
+                pairCode: initialPair.code,
+                pairCodeExpiresAt: initialPair.codeExpiresAt,
+            }
+            : {}),
+        ...(backend.adminToken ? { adminToken: backend.adminToken } : {}),
+        ...(opts.noLlmKey ? { noLlmKey: true } : {}),
+        ...(backend.embeddingModel ? { embeddingModel: backend.embeddingModel } : {}),
+    });
+    opts.stdout.write(`${bannerLines.join('\n')}\n`);
+    // Auto-open the operator's browser at the local URL. The server's
+    // `landingRedirect` then routes first-run operators (no LLM creds)
+    // to the admin onboarding flow at `/admin-login?next=/admin/llm-keys`,
+    // so the URL bar lands on the right page without the CLI needing
+    // to know which target to pick. Skipped for: `--no-open`, non-TTY
+    // (CI / supervised / piped), `--mcp-only` (no UI surface to open).
+    // Errors are swallowed — the banner already shows the URL so the
+    // operator can copy/paste if launchBrowser fails (xdg-open missing,
+    // etc.).
+    const shouldAutoOpenServe = !opts.flags.noOpen
+        && !opts.flags.mcpOnly
+        && opts.stdout === process.stdout
+        && process.stdout.isTTY === true;
+    if (shouldAutoOpenServe) {
+        const localUrl = `http://${opts.flags.host}:${boundPort}`;
+        const result = launchBrowser(localUrl);
+        opts.stdout.write(result.ok
+            ? `\n  opening browser → ${localUrl}\n`
+            : `\n  (couldn't auto-open browser: ${result.error})\n`);
+    }
+    const stopAll = async () => {
+        // Stop the agent BEFORE the server so the agent doesn't try
+        // one last call into an already-torn-down MCP surface. Swallow
+        // stop errors — the log has already delivered the crash signal
+        // if there was one, and the server close is the priority.
+        if (unsubscribeAgent)
+            unsubscribeAgent();
+        unsubscribeAgent = null;
+        if (agentHandle) {
+            try {
+                await agentHandle.stop();
+            }
+            catch {
+                /* best-effort */
+            }
+            agentHandle = null;
+        }
+        await backend.close();
+    };
+    if (opts.shutdownSignal.aborted) {
+        await stopAll();
+        return 0;
+    }
+    await new Promise((resolve) => {
+        opts.shutdownSignal.addEventListener('abort', () => {
+            resolve();
+        }, { once: true });
+    });
+    await stopAll();
+    return 0;
+}
+export const SERVE_HELP = `ggui serve — run the open self-hosted personal-mode app
+
+Boots the @ggui-ai/mcp-server binding with persistent defaults AND
+(by default) supervises your agent alongside it. The current MCP
+handler surface is the blueprint-read family (search / list_featured
+/ render); more tools come online as @ggui-ai/mcp-server-handlers
+grows.
+
+First-run bundle (all on by default):
+  - Landing page at /          — operator opens a browser and sees
+                                  server identity + pair-code card.
+  - Session viewer at /r/<code> — same-origin viewer for sessions
+                                  minted by ggui_push; same-origin
+                                  HTTP-only cookie authenticates the
+                                  live-channel /ws upgrade.
+  - POST /pair + POST /admin/pair/init — pairing endpoint for MCP
+                                  hosts and third-party clients.
+  - Live-channel /ws            — live session plane for MCP Apps
+                                  iframes and the console.
+
+Embedding hosts that want a different shape (no landing page, no
+pairing, programmatic control) should compose createGguiServer()
+directly in code rather than invoking \`ggui serve\`.
+
+Usage:
+  ggui serve [options]
+
+Options:
+  --port <n>             Bind port (default: ${DEFAULT_SERVE_PORT}, 0 = OS-assigned).
+  --host <addr>          Bind host (default: ${DEFAULT_SERVE_HOST}).
+  --mcp-only             Run just the MCP server; do not supervise an agent.
+  --dev-allow-all        Accept any non-empty bearer (incl. no bearer) as
+                         builder. Local-dev / tunnel smoke ONLY — never
+                         expose to the open internet.
+  --public-demo          Public-facing demo posture: same any-bearer auth
+                         as --dev-allow-all, plus per-IP rate limit on
+                         ggui_push (30 generations / 10 min) and a
+                         "PUBLIC DEMO — operator pays" banner. Mutually
+                         exclusive with --dev-allow-all.
+  --multi-tenant         Multi-tenant posture: switches the /settings LLM-
+                         keys gate from admin-token to auth-adapter so
+                         each authenticated end-user manages their OWN
+                         key plane (scope = userId/appId). kind:'builder'
+                         identities are rejected at the gate. Strict-auth
+                         only; mutually exclusive with --dev-allow-all
+                         and --public-demo. (Generation-time BYOK still
+                         resolves at the operator 'global' scope — a
+                         follow-up will thread per-user BYOK through
+                         ggui_push.)
+  --public-base-url <u>  Override the public base URL used to compose
+                         iframe-runtime + shortCode URLs. Set this to a
+                         tunnel URL (https://<random>.trycloudflare.com)
+                         when testing against a remote MCP host so URLs
+                         resolve from the host's perspective. Without
+                         this, URLs derive from --host:--port and only
+                         work from the same machine.
+  --oauth                Mount OAuth 2.1 + PKCE + Dynamic Client
+                         Registration routes (.well-known/oauth-* +
+                         /oauth/{authorize,token,register}). Required
+                         for MCP custom-connector hosts (claude.ai,
+                         ChatGPT) whose Add Connector form has no field
+                         for a pre-shared bearer; OAuth lets them do
+                         a discovery → DCR → consent dance ending in
+                         the same paired bearer the strict-auth flow
+                         already mints. Pure-bearer clients (Claude
+                         Desktop with bearer in config) work without it.
+  --admin-token <t>      Pin the admin bearer that gates the console
+                         /keys plane (list / mint / revoke pairings +
+                         /admin-login route). Without this, the server
+                         mints a fresh ggui_admin_* token per boot and
+                         prints it on the banner. Pin a stable value
+                         when you want the bearer to survive restarts
+                         (e.g. paste once into a password manager).
+  --ephemeral            Disable cross-restart persistence. Without
+                         this flag, the HMAC secrets that sign MCP
+                         Apps bootstrap tokens and signed render URLs
+                         are read or minted under .ggui/persistent/
+                         (project-local if a ggui.json was resolved,
+                         else ~/.ggui/persistent/) so cached tokens
+                         survive a server restart. Pass this flag to
+                         keep restarts ephemeral (tests / CI / nuclear-
+                         revoke). Override the dir via GGUI_PERSISTENT_DIR.
+  --help, -h             Show this help.
+
+Agent runtime:
+  The default boots your agent alongside MCP. The agent's entry file
+  comes from ggui.json:
+
+    { "agent": { "entry": "./agent.ts" } }
+
+  Supported extensions: .js / .mjs / .cjs (node), .ts / .tsx / .mts
+  (node --import=tsx). No ggui.json, or no agent.entry, falls back
+  to MCP-only with a warning. Malformed ggui.json or a bad entry
+  is a hard error.
+
+  Agent crashes after startup are logged; the MCP server keeps
+  running. No auto-restart — compose that with your own supervisor.
+
+Persistent storage (default-on; opt-out via --ephemeral):
+  By default \`ggui serve\` writes a small bundle under .ggui/persistent/
+  (project-local if a ggui.json was resolved, else ~/.ggui/persistent/)
+  so cached MCP Apps tokens, signed render URLs, shortCodes, sessions,
+  vectors, and paired bearers survive a restart — claude.ai chat-history
+  revisits keep working.
+
+  Bundle layout:
+
+    .ggui/persistent/
+      ├── bootstrap-secret.hex      (HMAC, 0600)
+      ├── render-signer-secret.hex  (HMAC, 0600)
+      ├── short-codes.sqlite        (/r/<code> + /api/bootstrap/<code> resolution)
+      ├── sessions.sqlite           (SessionStore — stack items + event history)
+      ├── vectors.sqlite            (RAG corpus)
+      └── keys.json                 (paired bearers)
+
+  Override the dir with \`GGUI_PERSISTENT_DIR\`. Pass \`--ephemeral\` to
+  skip the bundle entirely (tests, CI loops, nuclear-revoke).
+
+  Explicit ggui.json#storage declarations always win — declare
+  \`{ "sessions": { "driver": "memory" } }\` to opt sessions back to
+  in-memory while keeping other surfaces persistent. Custom sqlite
+  paths via ggui.json#storage are honored verbatim:
+
+    {
+      "storage": {
+        "sessions": { "driver": "sqlite", "path": "./ggui-sessions.sqlite" },
+        "vectors":  { "driver": "sqlite", "path": "./ggui-vectors.sqlite" },
+        "threads":  { "driver": "sqlite", "path": "./ggui-threads.sqlite" }
+      }
+    }
+
+  Threads: the persistent-chat route family (/threads) is opt-in.
+  Absent \`storage.threads\` leaves the routes unmounted — pairs
+  with Portal's self-hosted origins only when declared. Driver
+  semantics:
+    - \`driver: "sqlite"\` — durable. Threads survive restart.
+      /ggui/health reports \`threads.durability: "durable"\`;
+      Portal hides its non-durable caveat.
+    - \`driver: "memory"\` — routes mount but data is lost on
+      restart. /ggui/health reports \`threads.durability:
+      "ephemeral"\`; Portal shows its caveat.
+
+  Paths resolve relative to the ggui.json directory. The sqlite
+  driver needs \`better-sqlite3\` installed in your project.
+
+Recommended setups:
+
+  Local-only smoke (no tunnel, no remote MCP host):
+    ggui serve
+
+  claude.ai custom connector (over a public tunnel):
+    1. Tunnel: cloudflared tunnel --url http://localhost:6781
+    2. ggui serve --oauth \\
+                  --public-base-url https://<tunnel>.trycloudflare.com
+    3. Note PAIR_CODE from boot. Visit the landing page (the public URL
+       above), complete pairing, save the bearer.
+    4. claude.ai → Settings → Connectors → Add custom connector.
+       URL: https://<tunnel>.trycloudflare.com/mcp
+       Client ID / Secret: leave empty (server uses Dynamic Client
+       Registration; no pre-shared secret needed).
+    5. Click Connect → claude.ai redirects you to a paste-key page.
+       Paste the bearer from step 3. Done.
+
+  Quick local-dev WITHOUT auth (NEVER over a public tunnel):
+    ggui serve --dev-allow-all
+
+Current limits:
+  - Strict-auth only: /mcp rejects any bearer that isn't pair-minted.
+    The CLI pre-mints one pairing code on boot (printed as
+    \`PAIR_CODE <code>\` and shown in the banner + on the landing
+    page). Complete \`POST /pair {code, deviceName}\` to receive a
+    bearer you can use with MCP. Embed @ggui-ai/mcp-server in your
+    own entrypoint to inject a different AuthAdapter (OIDC, Cognito,
+    etc.) for production.
+  - Single-tenant: every request scopes to one \`builder\` app id.
+`;

package/dist/serve-fallback.d.ts

@@ -0,0 +1,64 @@
+import { GguiJsonLoadError, type GguiJsonV1 } from '@ggui-ai/project-config/node';
+import type { AgentStatus, ServeAgentSupervision } from './serve-command.js';
+/**
+ * Resolved state of the agent component at `ggui serve` boot time.
+ *
+ * - `status.kind === 'running'` → `supervision` populated; the
+ *   runner supervises the agent.
+ * - `status.kind === 'disabled'` → `supervision` absent; the
+ *   runner boots MCP-only with the banner surfacing the reason.
+ *
+ * `warnings` carries non-fatal messages the CLI prints BEFORE the
+ * banner (stderr). Hard errors (malformed ggui.json, bad entry
+ * extension) are thrown and caught by the CLI wrapper (exit 1).
+ */
+export interface ResolvedAgentPlan {
+    readonly status: AgentStatus;
+    readonly supervision?: ServeAgentSupervision;
+    readonly warnings: readonly string[];
+    /**
+     * Fully-parsed `ggui.json` when one was found (regardless of whether
+     * `agent.entry` is present). `null` when no manifest was found on the
+     * ancestor walk. CLI callers use this to resolve the storage block
+     * into concrete adapters via `resolveStorageFromConfig`.
+     */
+    readonly manifest: GguiJsonV1 | null;
+    /**
+     * Absolute path to the manifest's parent directory — the canonical
+     * root for resolving relative paths declared in the manifest
+     * (`storage.sessions.path`, `agent.entry`, future additive fields).
+     * `null` when no manifest was found.
+     */
+    readonly projectRoot: string | null;
+}
+export interface ResolveAgentPlanOptions {
+    /** `true` = operator opted out of agent supervision. */
+    readonly mcpOnly: boolean;
+    /** Starting directory for the ancestor walk to `ggui.json`. */
+    readonly cwd: string;
+    /**
+     * Event sink for the agent supervision. Tests pass a collector;
+     * production passes a function that writes `[agent …]` lines
+     * to `process.stderr`. Absent = silent.
+     */
+    readonly onAgentEvent?: ServeAgentSupervision['onEvent'];
+}
+/**
+ * Apply the §10.2a matrix. Throws `GguiJsonLoadError` for cases 3
+ * (malformed JSON, schema failure) and a generic `Error` for case
+ * 4 (unsupported agent.entry extension / missing file hint).
+ *
+ * Returns a `ResolvedAgentPlan` for cases 1, 2, 5, and 6:
+ *
+ *   1. `--mcp-only`                          → disabled, silent
+ *   2. no ggui.json found                    → disabled, warn
+ *   5. ggui.json present, no agent.entry     → disabled, warn
+ *   6. valid agent.entry                     → running, no warn
+ */
+export declare function resolveAgentPlan(opts: ResolveAgentPlanOptions): ResolvedAgentPlan;
+/**
+ * Re-export for tests that want to assert on malformed-config
+ * handling without importing project-config transitively.
+ */
+export { GguiJsonLoadError };
+//# sourceMappingURL=serve-fallback.d.ts.map

package/dist/serve-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-fallback.d.ts","sourceRoot":"","sources":["../src/serve-fallback.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,iBAAiB,EAEjB,KAAK,UAAU,EAChB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,KAAK,EACV,WAAW,EACX,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,uBAAuB,GAC5B,iBAAiB,CA+EnB;AAqBD;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,CAAC"}