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

package/dist/storage.d.ts

@@ -0,0 +1,89 @@
+import type { SessionStore, ThreadStore, VectorStore } from '@ggui-ai/mcp-server-core';
+import type { StorageConfig } from '@ggui-ai/project-config';
+export interface ResolveStorageFromConfigOptions {
+    /**
+     * Directory used to resolve relative `path` values in the storage
+     * config. Typically the directory containing `ggui.json` so a
+     * manifest saying `"path": "./ggui-sessions.sqlite"` lands next to
+     * the manifest (not CWD, which would silently create a file wherever
+     * the process happened to be started).
+     *
+     * Absolute paths in the config are honored verbatim. Omitting
+     * `baseDir` means relative paths resolve against `process.cwd()` —
+     * fine for ad-hoc programmatic callers, but `ggui serve` always
+     * passes the project root so the behavior is deterministic.
+     */
+    readonly baseDir?: string;
+}
+export interface ResolvedStorageStores {
+    /** Concrete SessionStore, iff the config declared one. Undefined =
+     * caller falls back to createGguiServer's in-memory default. */
+    readonly sessionStore?: SessionStore;
+    /** Concrete VectorStore, iff the config declared one. Undefined =
+     * caller falls back to createGguiServer's in-memory default. */
+    readonly vectors?: VectorStore;
+    /** Concrete ThreadStore, iff the config declared one. Undefined
+     * ONLY when `storage.threads` is absent from the manifest — in
+     * that case the caller skips the `threads:` opt-in on
+     * `createGguiServer` and no thread routes mount at all.
+     *
+     * When the manifest declares `storage.threads`, a store is
+     * ALWAYS returned:
+     *   - `driver: 'memory'` → `InMemoryThreadStore` (ephemeral but
+     *     real; routes mount and work until restart).
+     *   - `driver: 'sqlite'` → `SqliteThreadStore` (durable).
+     *
+     * This is the one semantic deviation from sessions/vectors, which
+     * treat `driver: 'memory'` as a no-op because `createGguiServer`
+     * already defaults those to in-memory stores internally. Threads
+     * don't have an implicit default — the whole route family is
+     * opt-in — so `'memory'` has to resolve to a real store or be
+     * rejected at schema time. Resolving to `InMemoryThreadStore` is
+     * the less-surprising of the two. */
+    readonly threadStore?: ThreadStore;
+    /**
+     * Durability claim for the resolved thread store. Present iff
+     * `threadStore` is present. `'durable'` for sqlite; `'ephemeral'`
+     * for memory. Callers pass this straight through to
+     * `createGguiServer({ threads: { durability } })` so the server's
+     * `/ggui/health` advertisement matches the active store.
+     */
+    readonly threadDurability?: 'durable' | 'ephemeral';
+}
+/**
+ * Instantiate the concrete storage adapters declared in a parsed
+ * `ggui.json#storage` block.
+ *
+ *   - Absent config                    → `{}` (every surface
+ *                                         falls back to createGguiServer's
+ *                                         in-memory defaults, or in the
+ *                                         case of `threads:`, no thread
+ *                                         routes at all).
+ *
+ *   - `sessions` / `vectors`:
+ *       - `driver: 'memory'`            → omitted from the bundle
+ *                                         (same fallback — declaring
+ *                                         memory is the same outcome
+ *                                         as omitting it; present
+ *                                         for intent visibility).
+ *       - `driver: 'sqlite'`            → `SqliteSessionStore` /
+ *                                         `SqliteVectorStore`.
+ *
+ *   - `threads`:
+ *       - `driver: 'memory'`            → `InMemoryThreadStore` +
+ *                                         `threadDurability: 'ephemeral'`.
+ *                                         Routes mount; data lost on
+ *                                         restart. Declaring this is
+ *                                         how an operator asks for
+ *                                         ephemeral threads.
+ *       - `driver: 'sqlite'`            → `SqliteThreadStore` +
+ *                                         `threadDurability: 'durable'`.
+ *
+ * Dynamic import of `@ggui-ai/mcp-server-core/sqlite` means
+ * `better-sqlite3` is only required when the config actually declares
+ * sqlite somewhere. Memory-only configs don't touch the optional peer
+ * dep — `InMemoryThreadStore` is a static import because the in-memory
+ * subpath has no peer dep cost.
+ */
+export declare function resolveStorageFromConfig(config: StorageConfig | undefined, opts?: ResolveStorageFromConfigOptions): Promise<ResolvedStorageStores>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAqDA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,+BAA+B;IAC9C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC;oEACgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;oEACgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B;;;;;;;;;;;;;;;;;yCAiBqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,IAAI,GAAE,+BAAoC,GACzC,OAAO,CAAC,qBAAqB,CAAC,CAgDhC"}

package/dist/storage.js

@@ -0,0 +1,171 @@
+/**
+ * Storage config → concrete adapter resolver.
+ *
+ * Bridges `@ggui-ai/project-config`'s declarative `ggui.json#storage`
+ * block to the concrete `@ggui-ai/mcp-server-core` adapters. Thin and
+ * boring by design: one config → one set of instances.
+ *
+ * ## Why this lives in @ggui-ai/mcp-server (not core, not project-config)
+ *
+ *   - `@ggui-ai/project-config` is browser-safe + purely declarative.
+ *     It must not import `better-sqlite3` (which is a Node addon) or
+ *     any concrete adapter — that would poison the import graph for
+ *     paste-a-manifest validators, dev UIs, the Studio dashboard.
+ *
+ *   - `@ggui-ai/mcp-server-core` is the interfaces + reference adapters
+ *     layer. It exposes the adapters on subpath exports
+ *     (`/sqlite`, `/in-memory`, …) but intentionally doesn't know about
+ *     `ggui.json` — keeping the interface layer free of file-format
+ *     coupling lets non-OSS consumers (hosted closed runtimes, future
+ *     private adapters) bind the same interfaces without dragging the
+ *     OSS manifest schema through their code.
+ *
+ *   - `@ggui-ai/mcp-server` is the OSS runtime that actually reads
+ *     `ggui.json` and serves requests. That's where the bridge
+ *     belongs — one hop away from the actual `ggui serve` caller.
+ *
+ * ## Why `better-sqlite3` gets imported dynamically
+ *
+ * `better-sqlite3` is an optional peer dep of `@ggui-ai/mcp-server-core`.
+ * If we `import { SqliteSessionStore } from '@ggui-ai/mcp-server-core/sqlite'`
+ * at the top of this file, any consumer that doesn't opt into SQLite
+ * storage still pays the peer-dep cost (the module graph resolves the
+ * subpath at import time, which tries to load better-sqlite3's N-API
+ * binary). Dynamic `await import(...)` keeps the cost truly optional:
+ * SQLite is loaded only when `storage.sessions.driver === 'sqlite'` or
+ * `storage.vectors.driver === 'sqlite'`.
+ *
+ * ## Why this is async + returns a bundle instead of augmenting createGguiServer
+ *
+ * `createGguiServer` stays synchronous — no public API break. Callers
+ * who want storage from config write:
+ *
+ * ```ts
+ * const { sessionStore, vectors } =
+ *   await resolveStorageFromConfig(manifest.storage, { baseDir: projectRoot });
+ * const server = createGguiServer({ sessionStore, vectors });
+ * ```
+ *
+ * Explicit instances passed to `createGguiServer` still win — this
+ * resolver is a convenience for the ggui.json path, not a requirement.
+ */
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+// `InMemoryThreadStore` is a static import — unlike the sqlite
+// adapters, the in-memory subpath carries no optional peer dep cost
+// (no `better-sqlite3`, no N-API binding). `storage.threads.driver =
+// 'memory'` uses this to mount actual thread routes instead of being
+// a silent no-op like sessions/vectors (which createGguiServer
+// already defaults to in-memory internally).
+import { InMemoryThreadStore } from '@ggui-ai/mcp-server-core/in-memory';
+/**
+ * Instantiate the concrete storage adapters declared in a parsed
+ * `ggui.json#storage` block.
+ *
+ *   - Absent config                    → `{}` (every surface
+ *                                         falls back to createGguiServer's
+ *                                         in-memory defaults, or in the
+ *                                         case of `threads:`, no thread
+ *                                         routes at all).
+ *
+ *   - `sessions` / `vectors`:
+ *       - `driver: 'memory'`            → omitted from the bundle
+ *                                         (same fallback — declaring
+ *                                         memory is the same outcome
+ *                                         as omitting it; present
+ *                                         for intent visibility).
+ *       - `driver: 'sqlite'`            → `SqliteSessionStore` /
+ *                                         `SqliteVectorStore`.
+ *
+ *   - `threads`:
+ *       - `driver: 'memory'`            → `InMemoryThreadStore` +
+ *                                         `threadDurability: 'ephemeral'`.
+ *                                         Routes mount; data lost on
+ *                                         restart. Declaring this is
+ *                                         how an operator asks for
+ *                                         ephemeral threads.
+ *       - `driver: 'sqlite'`            → `SqliteThreadStore` +
+ *                                         `threadDurability: 'durable'`.
+ *
+ * Dynamic import of `@ggui-ai/mcp-server-core/sqlite` means
+ * `better-sqlite3` is only required when the config actually declares
+ * sqlite somewhere. Memory-only configs don't touch the optional peer
+ * dep — `InMemoryThreadStore` is a static import because the in-memory
+ * subpath has no peer dep cost.
+ */
+export async function resolveStorageFromConfig(config, opts = {}) {
+    if (!config)
+        return {};
+    const sessionsSqlite = config.sessions?.driver === 'sqlite';
+    const vectorsSqlite = config.vectors?.driver === 'sqlite';
+    const threadsSqlite = config.threads?.driver === 'sqlite';
+    const threadsMemory = config.threads?.driver === 'memory';
+    const result = {};
+    // Handle the memory-threads branch BEFORE the sqlite dynamic import
+    // gate so `driver: 'memory'`-only configs don't pull in
+    // better-sqlite3 at all.
+    if (threadsMemory) {
+        result.threadStore = new InMemoryThreadStore();
+        result.threadDurability = 'ephemeral';
+    }
+    if (!sessionsSqlite && !vectorsSqlite && !threadsSqlite)
+        return result;
+    // Single dynamic import serves every sqlite adapter — better-sqlite3's
+    // N-API binding loads once even if the import lands twice; the
+    // subpath barrel is cached by Node's module loader.
+    const { SqliteSessionStore, SqliteVectorStore, SqliteThreadStore } = await import('@ggui-ai/mcp-server-core/sqlite');
+    if (config.sessions && config.sessions.driver === 'sqlite') {
+        const filename = resolveStoragePath(config.sessions.path, opts.baseDir);
+        ensureParentDir(filename);
+        result.sessionStore = new SqliteSessionStore({ filename });
+    }
+    if (config.vectors && config.vectors.driver === 'sqlite') {
+        const filename = resolveStoragePath(config.vectors.path, opts.baseDir);
+        ensureParentDir(filename);
+        result.vectors = new SqliteVectorStore({ filename });
+    }
+    if (config.threads && config.threads.driver === 'sqlite') {
+        const filename = resolveStoragePath(config.threads.path, opts.baseDir);
+        ensureParentDir(filename);
+        result.threadStore = new SqliteThreadStore({ filename });
+        result.threadDurability = 'durable';
+    }
+    return result;
+}
+/**
+ * Create the parent directory of a sqlite database file if it doesn't
+ * already exist. Turns the declarative `path: './data/sessions.sqlite'`
+ * into a working adapter without forcing the operator to mkdir by hand
+ * — better-sqlite3 refuses to open a file whose parent doesn't exist,
+ * and the parent is uninteresting bookkeeping the manifest already
+ * implies.
+ *
+ * Not "silent file creation" — the operator declared the path in
+ * `ggui.json`; honoring it is the whole point of opt-in. No-op for
+ * `:memory:` and for paths whose parent already exists.
+ */
+function ensureParentDir(resolvedPath) {
+    if (resolvedPath === ':memory:')
+        return;
+    mkdirSync(path.dirname(resolvedPath), { recursive: true });
+}
+/**
+ * Resolve a storage `path` from the manifest. Absolute paths pass
+ * through; relative paths resolve against `baseDir` (typically the
+ * ggui.json directory). `baseDir` absent falls back to `process.cwd()`
+ * so ad-hoc programmatic callers still work.
+ *
+ * `:memory:` is intentionally NOT special-cased here — callers who
+ * want an in-memory database should declare `driver: 'memory'` in the
+ * manifest. An explicit `:memory:` as a sqlite path is honored (passes
+ * straight through to better-sqlite3), but it's a power-user escape
+ * hatch, not the documented path.
+ */
+function resolveStoragePath(rawPath, baseDir) {
+    if (rawPath === ':memory:')
+        return rawPath;
+    if (path.isAbsolute(rawPath))
+        return rawPath;
+    const root = baseDir ?? process.cwd();
+    return path.resolve(root, rawPath);
+}

package/dist/thread-transport.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Thread transport — HTTP routes for the persistent-chat surface.
+ *
+ * Thin binding over `@ggui-ai/mcp-server-handlers/threads`. Every
+ * route:
+ *
+ *   1. Resolves identity via the existing `AuthAdapter` (same path
+ *      `/mcp` + pairing use — no second identity plane).
+ *   2. Maps the identity to a stable `ownerId` string (see
+ *      {@link ThreadOwnerResolver}).
+ *   3. Calls the shared handler with `{ ownerId, requestId }`.
+ *   4. Maps handler / store errors to stable HTTP status codes.
+ *
+ * Routes mounted:
+ *
+ *   POST   /threads                       → createThread
+ *   GET    /threads                       → listThreads
+ *   GET    /threads/:id                   → getThread
+ *   PATCH  /threads/:id                   → applyThreadAction
+ *   GET    /threads/:id/messages          → listMessages
+ *   POST   /threads/:id/messages          → appendMessage
+ *   GET    /threads/:id/stream            → observeMessages (SSE)
+ *
+ * Error mapping (the ONLY transport-level semantic):
+ *
+ *   InvalidThreadRequestError           → 400 bad_request
+ *   ThreadNotFoundError                 → 404 not_found (wrong-owner + missing
+ *                                          collapse to the same code)
+ *   InvalidThreadActionError            → 400 bad_request (defense-in-depth;
+ *                                          handler-level schema parses first)
+ *   ThreadActionInvalidStateError       → 409 conflict
+ *   UnauthenticatedError                → 401 unauthenticated
+ *   (anything else)                     → 500 internal
+ *
+ * Error envelopes match the pairing-transport shape so clients see one
+ * error-body contract across every non-/mcp route:
+ *
+ *   { error: { code: 'bad_request' | 'not_found' | 'conflict' | ...,
+ *              message: string,
+ *              details?: unknown } }
+ */
+import type { Express } from 'express';
+import type { AuthAdapter, AuthResult, ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { Logger } from './logger.js';
+/** Default URL prefix the thread routes are mounted at. */
+export declare const DEFAULT_THREADS_PATH = "/threads";
+/**
+ * Resolve the stable thread-partition key (`ownerId`) from the
+ * authenticated identity.
+ *
+ * The protocol pins the canonical shapes:
+ *   - Closed-cloud variants: `cognito_<sub>` / `guest_<uuidv4>` (not
+ *     our concern here — the closed binding supplies its own resolver).
+ *   - Self-hosted: `paired_<pairingId>` for pairing-minted tokens;
+ *     kind-scoped fallback for everything else.
+ *
+ * The default {@link defaultThreadOwnerFromIdentity} implements that
+ * rule. Operators who need a different partition key (e.g. a multi-
+ * user OSS fork) pass their own via `threads.ownerFromIdentity`.
+ */
+export type ThreadOwnerResolver = (result: AuthResult) => string;
+export declare const DEFAULT_BUILDER_OWNER_ID = "builder";
+/**
+ * Default identity → ownerId mapping for the OSS server.
+ *
+ * Preserves the protocol's "self-hosted → typically `paired_<pairingId>`"
+ * convention whenever the token was minted by pairing: the bridge in
+ * `createGguiServer` passes `metadata: { pairingId }` on `onTokenIssued`,
+ * which surfaces here via `AuthResult.metadata.pairingId`. Fallbacks:
+ *
+ *   - `source: 'cognito'` with a `sub` metadata field → `cognito_<sub>`
+ *     (parallel adapters in any closed cloud runtime; not a shape the
+ *     OSS server ships today but the mapping is stable so custom
+ *     adapters are uniform).
+ *   - `kind: 'user'` → `user_<workspaceId ?? userId>` — same partition
+ *     rule `defaultAppIdFromIdentity` uses.
+ *   - `kind: 'builder'` with no pairing metadata (dev mode / manual
+ *     token) → {@link DEFAULT_BUILDER_OWNER_ID}.
+ *
+ * Keeping every OSS-reachable identity collapsed to ONE owner by
+ * default is correct: OSS is a single-operator tier. Operators who
+ * split owners across multiple tokens pass a custom resolver.
+ */
+export declare function defaultThreadOwnerFromIdentity(result: AuthResult): string;
+export interface ThreadTransportOptions {
+    /** Required. Store implementation the handlers call through to. */
+    readonly store: ThreadStore;
+    /**
+     * Required. Same AuthAdapter the `/mcp` + live-channel + pairing
+     * endpoints use. Identity resolution goes through this — thread
+     * routes never invent their own auth path.
+     */
+    readonly auth: AuthAdapter;
+    /** Structured logger. Child loggers are derived per-route. */
+    readonly logger: Logger;
+    /**
+     * URL prefix. Defaults to `/threads`. Six routes are registered
+     * beneath it:
+     *   POST / GET on the prefix itself, GET / PATCH on `/:id`,
+     *   GET / POST on `/:id/messages`.
+     */
+    readonly path?: string;
+    /**
+     * Identity → ownerId mapping. Defaults to
+     * {@link defaultThreadOwnerFromIdentity}. A hosted closed runtime
+     * overrides to map Cognito claims to `cognito_<sub>` / `guest_<id>`;
+     * OSS forks that partition multiple operators override as needed.
+     */
+    readonly ownerFromIdentity?: ThreadOwnerResolver;
+}
+/**
+ * Mount the six thread routes onto an existing Express app.
+ *
+ * Idempotent is NOT a goal — call once per server. `createGguiServer`
+ * owns the single call site via `opts.threads`.
+ */
+export declare function mountThreadTransport(app: Express, opts: ThreadTransportOptions): void;
+//# sourceMappingURL=thread-transport.d.ts.map

package/dist/thread-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-transport.d.ts","sourceRoot":"","sources":["../src/thread-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAE1D,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAiBlC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;AAEjE,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAqBzE;AAED,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;CAClD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,sBAAsB,GAC3B,IAAI,CAwYN"}