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

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @ggui-ai/mcp-server — open self-hosted MCP server for the ggui protocol.
+ *
+ * **Role**: thin HTTP/MCP binding layer.
+ * Composes `@ggui-ai/mcp-server-handlers` (real handler logic) with
+ * `@ggui-ai/mcp-server-core` in-memory reference adapters to produce a
+ * runnable open server. No business logic lives here — if you need to
+ * change tool behavior, edit the shared handler package.
+ *
+ * Zero-config boot:
+ *
+ * ```ts
+ * import { createGguiServer } from '@ggui-ai/mcp-server';
+ * const server = createGguiServer();
+ * await server.listen(4567);
+ * ```
+ *
+ * This package deliberately does NOT:
+ *
+ *   - embed AWS / DDB / Redis / cloud-specific wiring (those bind to
+ *     `@ggui-ai/mcp-server-core` interfaces in separate adapter
+ *     packages),
+ *   - implement authoring / pairing / UI generation (those are separate
+ *     packages + protocol flows).
+ *
+ * The `ggui serve` CLI command boots this server with the OSS defaults.
+ */
+export type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
+export type { GadgetDescriptor, McpAppsMode, SessionStackEntry, StackItem, SystemStackItem, } from '@ggui-ai/protocol';
+export type { GenerationCredentials, GenerationDeps, } from '@ggui-ai/mcp-server-handlers';
+export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsStackItem, } from '@ggui-ai/mcp-server-handlers';
+export { createGguiServer, defaultHandlers } from './server.js';
+export type { CreateGguiServerOptions, GguiServer, } from './server.js';
+export { FileSystemCodeStore } from './code-store-fs.js';
+export type { FileSystemCodeStoreOptions } from './code-store-fs.js';
+export type { McpServerMount } from './mcp-mounts.js';
+export { composeWiredActionRouterFromMounts } from './mcp-mounts.js';
+export type { McpService, ServicePath } from './mcp-mounts.js';
+export { validateMcpServices, validateServicePath } from './mcp-mounts.js';
+export { composePreviewReservedValidator, mergeReservedValidators, } from './reserved-validators.js';
+export { checkStackItemSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
+export type { SchemaCompatFinding, SchemaCompatMode, SchemaCompatReport, StackItemContractShape, ToolSchemaRef, } from './schema-compat.js';
+export type { ServerInfo } from './build-mcp.js';
+export { UnauthenticatedError, DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity, } from './auth.js';
+export { createConsoleLogger } from './logger.js';
+export type { Logger } from './logger.js';
+export { createSessionChannelServer, DEFAULT_SESSION_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './session-channel.js';
+export type { SessionChannelOptions, SessionChannelServer, WiredActionContext, WiredActionRouter, } from './session-channel.js';
+export { resolveStorageFromConfig } from './storage.js';
+export type { ResolveStorageFromConfigOptions, ResolvedStorageStores, } from './storage.js';
+export { DEFAULT_PAIRING_ADMIN_INIT_PATH, DEFAULT_PAIRING_PATH, mountPairingTransport, } from './pairing-transport.js';
+export type { PairingTransportOptions } from './pairing-transport.js';
+export { USER_SESSION_COOKIE_NAME, DEFAULT_USER_SESSION_TTL_SEC, cookieAuthMiddleware, extractUserSessionCookie, formatUserSessionCookieHeader, formatClearUserSessionCookieHeader, readUserSessionCookie, readUserSessionCookieFromHeaders, } from './user-session-auth.js';
+export type { FormatUserSessionCookieInput } from './user-session-auth.js';
+export { createPairLoginRateLimitMiddleware, resolveClientIp, } from './rate-limit-middleware.js';
+export type { PairLoginRateLimitOptions } from './rate-limit-middleware.js';
+export { CSRF_HEADER_NAME, CSRF_RESPONSE_HEADER_NAME, DEFAULT_CSRF_TOKEN_PATH, createCsrfMiddleware, mintCsrfToken, mountCsrfTokenRoute, } from './csrf-middleware.js';
+export type { CsrfMiddlewareOptions, MintCsrfTokenInput, MountCsrfTokenRouteOptions, } from './csrf-middleware.js';
+export { createSecurityHeadersMiddleware } from './security-headers-middleware.js';
+export type { SecurityHeadersMiddlewareOptions } from './security-headers-middleware.js';
+export { composeOAuthUserId, } from './oauth-login-types.js';
+export type { OAuthLoginProvider, AuthorizeUrlInput, ExchangeCodeInput, OAuthExchangeResult, OAuthProviderConfigRecord, OAuthAuthResult, } from './oauth-login-types.js';
+export { DEFAULT_OAUTH_START_PATH, DEFAULT_OAUTH_CALLBACK_PATH, DEFAULT_OAUTH_PROVIDERS_LIST_PATH, OAUTH_PKCE_COOKIE_NAME, mountOAuthLoginRoutes, } from './oauth-login.js';
+export { DEFAULT_EMAIL_LOGIN_START_PATH, DEFAULT_EMAIL_LOGIN_VERIFY_PATH, DEFAULT_EMAIL_LOGIN_CONFIG_PATH, ConsoleEmailSender, InMemoryMagicLinkStore, mountEmailLoginRoutes, } from './email-login.js';
+export type { EmailSender, EmailMessage, MagicLinkStore, MagicLinkRecord, MintTokenInput, EmailLoginRoutesOptions, } from './email-login.js';
+export { ResendEmailSender } from './email-resend.js';
+export type { ResendEmailSenderOptions } from './email-resend.js';
+export { SmtpEmailSender } from './email-smtp.js';
+export type { SmtpEmailSenderOptions } from './email-smtp.js';
+export { selectEmailSenderFromEnv } from './email-sender-from-env.js';
+export type { EmailSenderKind, EmailSenderSelection, SelectEmailSenderOptions, } from './email-sender-from-env.js';
+export { MCP_INSTRUCTIONS_PRESETS, resolveMcpInstructions, } from './instructions-presets.js';
+export type { McpInstructionsPreset, McpInstructionsValue, } from './instructions-presets.js';
+export type { OAuthLoginRoutesOptions } from './oauth-login.js';
+export { googleLoginProvider } from './oauth-providers/google.js';
+export type { GoogleLoginProviderOptions } from './oauth-providers/google.js';
+export { githubLoginProvider } from './oauth-providers/github.js';
+export type { GithubLoginProviderOptions } from './oauth-providers/github.js';
+export { createOAuthProvidersStore } from './oauth-providers-store.js';
+export type { OAuthProvidersStore, OAuthProvidersStoreOptions, PutInput as OAuthProvidersStorePutInput, } from './oauth-providers-store.js';
+export { DEFAULT_ADMIN_OAUTH_PROVIDERS_PATH, mountAdminOAuthProvidersTransport, } from './admin-oauth-providers-transport.js';
+export type { AdminOAuthProvidersTransportOptions } from './admin-oauth-providers-transport.js';
+export type { CompletePairingInput, Pairing, PairingCompletion, PairingInit, PairingService, PairingWithToken, } from '@ggui-ai/mcp-server-core';
+export { DEFAULT_BUILDER_OWNER_ID, DEFAULT_THREADS_PATH, defaultThreadOwnerFromIdentity, mountThreadTransport, } from './thread-transport.js';
+export type { ThreadOwnerResolver, ThreadTransportOptions, } from './thread-transport.js';
+export { InMemoryShortCodeIndex } from '@ggui-ai/mcp-server-core/in-memory';
+export type { ShortCodeIndex } from '@ggui-ai/mcp-server-core';
+export { InMemoryAuthAdapter } from '@ggui-ai/mcp-server-core/in-memory';
+export type { InMemoryAuthAdapterOptions } from '@ggui-ai/mcp-server-core/in-memory';
+export { FixedWindowRateLimiter, InMemoryQuotaStore, } from '@ggui-ai/mcp-server-core/in-memory';
+export type { FixedWindowRateLimiterOptions, InMemoryQuotaStoreOptions, } from '@ggui-ai/mcp-server-core/in-memory';
+export type { RateLimiter, QuotaStore } from '@ggui-ai/mcp-server-core';
+export { ManifestBlueprintProvider } from '@ggui-ai/mcp-server-core/in-memory';
+export type { ManifestBlueprintSeed, ManifestBlueprintProviderOptions, } from '@ggui-ai/mcp-server-core/in-memory';
+export type { BlueprintProvider } from '@ggui-ai/mcp-server-core';
+export type { DiscoveredPrimitiveCatalog } from '@ggui-ai/project-config/node';
+export type { LoadedTheme } from '@ggui-ai/project-config/node';
+export type { OperatorConfig } from '@ggui-ai/project-config';
+export type { ThemeWriter, ThemeFileUploader, } from './console-theme-routes.js';
+export type { LlmProvider, LlmSelection, ProviderKeyRef, UiGenerateEvent, UiGenerateInput, UiGenerateResult, UiGenerator, GeneratorTier, GeneratorRegistry, GeneratorSlugParts, } from '@ggui-ai/mcp-server-core';
+export { formatGeneratorSlug, isValidGeneratorSlug, parseGeneratorSlug, } from '@ggui-ai/mcp-server-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,122 @@
+/**
+ * @ggui-ai/mcp-server — open self-hosted MCP server for the ggui protocol.
+ *
+ * **Role**: thin HTTP/MCP binding layer.
+ * Composes `@ggui-ai/mcp-server-handlers` (real handler logic) with
+ * `@ggui-ai/mcp-server-core` in-memory reference adapters to produce a
+ * runnable open server. No business logic lives here — if you need to
+ * change tool behavior, edit the shared handler package.
+ *
+ * Zero-config boot:
+ *
+ * ```ts
+ * import { createGguiServer } from '@ggui-ai/mcp-server';
+ * const server = createGguiServer();
+ * await server.listen(4567);
+ * ```
+ *
+ * This package deliberately does NOT:
+ *
+ *   - embed AWS / DDB / Redis / cloud-specific wiring (those bind to
+ *     `@ggui-ai/mcp-server-core` interfaces in separate adapter
+ *     packages),
+ *   - implement authoring / pairing / UI generation (those are separate
+ *     packages + protocol flows).
+ *
+ * The `ggui serve` CLI command boots this server with the OSS defaults.
+ */
+// No-credentials fallback helpers — re-exported so the OSS CLI can
+// build the no-credentials card stack item (pointing at the resolved
+// `/settings` URL) without taking a direct `@ggui-ai/mcp-server-handlers`
+// dependency.
+export { NO_CREDENTIALS_SYSTEM_CARD_KIND, buildNoCredentialsStackItem, } from '@ggui-ai/mcp-server-handlers';
+export { createGguiServer, defaultHandlers } from './server.js';
+// Content-addressable code delivery (2026-05-03). FileSystemCodeStore
+// is the OSS dev default; in-memory variant ships in
+// `@ggui-ai/mcp-server-core/in-memory` for tests + ephemeral runs.
+export { FileSystemCodeStore } from './code-store-fs.js';
+export { composeWiredActionRouterFromMounts } from './mcp-mounts.js';
+export { validateMcpServices, validateServicePath } from './mcp-mounts.js';
+// Reserved-channel payload validator composition.
+// `composePreviewReservedValidator` binds the A2UI adapter
+// for `_ggui:preview`; `mergeReservedValidators` layers caller-provided
+// extras on top. `createGguiServer` composes these automatically —
+// consumers that embed the session-channel server directly (via
+// `createSessionChannelServer`) wire them up manually.
+export { composePreviewReservedValidator, mergeReservedValidators, } from './reserved-validators.js';
+// Schema compatibility checker. Exposes the helper, the policy-mode
+// type, the canonical error, and the default mode constant. Consumers
+// embedding their own endpoint paths (custom hosted wrappers) can
+// reuse the helper directly.
+export { checkStackItemSchemaCompat, DEFAULT_SCHEMA_COMPAT_MODE, SchemaCompatError, } from './schema-compat.js';
+export { UnauthenticatedError, DEFAULT_BUILDER_APP_ID, defaultAppIdFromIdentity, } from './auth.js';
+export { createConsoleLogger } from './logger.js';
+export { createSessionChannelServer, DEFAULT_SESSION_CHANNEL_PATH, DEFAULT_WIRED_TOOL_TIMEOUT_MS, } from './session-channel.js';
+export { resolveStorageFromConfig } from './storage.js';
+export { DEFAULT_PAIRING_ADMIN_INIT_PATH, DEFAULT_PAIRING_PATH, mountPairingTransport, } from './pairing-transport.js';
+// End-user browser-session cookie + login routes. Cookie + endpoints
+// are mounted automatically by `createGguiServer` when pairing is
+// enabled; re-exported here so embedders composing custom transports
+// can reuse the cookie shape directly.
+export { USER_SESSION_COOKIE_NAME, DEFAULT_USER_SESSION_TTL_SEC, cookieAuthMiddleware, extractUserSessionCookie, formatUserSessionCookieHeader, formatClearUserSessionCookieHeader, readUserSessionCookie, readUserSessionCookieFromHeaders, } from './user-session-auth.js';
+// Per-IP rate limit on `/pair`. Mounted automatically by
+// `createGguiServer` when pairing is enabled. Re-exported so hosted
+// bindings can swap in their own RateLimiter (Redis-backed,
+// sliding-window, etc.) and reuse the middleware.
+export { createPairLoginRateLimitMiddleware, resolveClientIp, } from './rate-limit-middleware.js';
+// Browser-session hardening: CSRF (double-submit, HMAC-bound to the
+// session cookie), audit hooks (wired through
+// `LoginRoutesOptions.auditSink`), and security headers
+// (X-Frame-Options DENY, Referrer-Policy, X-Content-Type-Options).
+// All three mount automatically.
+export { CSRF_HEADER_NAME, CSRF_RESPONSE_HEADER_NAME, DEFAULT_CSRF_TOKEN_PATH, createCsrfMiddleware, mintCsrfToken, mountCsrfTokenRoute, } from './csrf-middleware.js';
+export { createSecurityHeadersMiddleware } from './security-headers-middleware.js';
+// OAuth login providers. Server mounts admin transport always +
+// login routes when publicBaseUrl is set; operators paste
+// credentials at /admin/oauth-providers and end-users sign in at
+// /login via provider buttons.
+export { composeOAuthUserId, } from './oauth-login-types.js';
+export { DEFAULT_OAUTH_START_PATH, DEFAULT_OAUTH_CALLBACK_PATH, DEFAULT_OAUTH_PROVIDERS_LIST_PATH, OAUTH_PKCE_COOKIE_NAME, mountOAuthLoginRoutes, } from './oauth-login.js';
+export { DEFAULT_EMAIL_LOGIN_START_PATH, DEFAULT_EMAIL_LOGIN_VERIFY_PATH, DEFAULT_EMAIL_LOGIN_CONFIG_PATH, ConsoleEmailSender, InMemoryMagicLinkStore, mountEmailLoginRoutes, } from './email-login.js';
+export { ResendEmailSender } from './email-resend.js';
+export { SmtpEmailSender } from './email-smtp.js';
+export { selectEmailSenderFromEnv } from './email-sender-from-env.js';
+export { MCP_INSTRUCTIONS_PRESETS, resolveMcpInstructions, } from './instructions-presets.js';
+export { googleLoginProvider } from './oauth-providers/google.js';
+export { githubLoginProvider } from './oauth-providers/github.js';
+export { createOAuthProvidersStore } from './oauth-providers-store.js';
+export { DEFAULT_ADMIN_OAUTH_PROVIDERS_PATH, mountAdminOAuthProvidersTransport, } from './admin-oauth-providers-transport.js';
+export { DEFAULT_BUILDER_OWNER_ID, DEFAULT_THREADS_PATH, defaultThreadOwnerFromIdentity, mountThreadTransport, } from './thread-transport.js';
+// Zero-config in-memory reference for the console shortCode → session
+// lookup. Re-exported here (alongside `createGguiServer`) so CLI hosts
+// composing the OSS first-run path can pass one without taking a direct
+// dep on `@ggui-ai/mcp-server-core`. For durable deployments the
+// operator swaps in their own `ShortCodeIndex` implementation.
+export { InMemoryShortCodeIndex } from '@ggui-ai/mcp-server-core/in-memory';
+// In-memory reference AuthAdapter. Re-exported for the same reason as
+// `InMemoryShortCodeIndex` — CLI hosts that want strict auth (no
+// implicit `devAllowAll`) construct one with `devAllowAll: false` and
+// pass it to `createGguiServer({ auth: ... })` without taking a direct
+// `@ggui-ai/mcp-server-core` dep. `ggui serve` does this by default to
+// keep its `/mcp` ingress honest; pair-minted tokens register through
+// `onTokenIssued`.
+export { InMemoryAuthAdapter } from '@ggui-ai/mcp-server-core/in-memory';
+// In-memory rate-limiter + quota-store reference adapters. Re-exported
+// for the same reason as `InMemoryAuthAdapter` — CLI hosts can compose
+// `--public-demo` posture (per-IP rate limit on ggui_push) without
+// taking a direct `@ggui-ai/mcp-server-core` dep. The default fallback
+// inside `createGguiServer` is `NoopRateLimiter`; this is the smallest
+// non-trivial alternative.
+export { FixedWindowRateLimiter, InMemoryQuotaStore, } from '@ggui-ai/mcp-server-core/in-memory';
+// Manifest-backed blueprint provider.
+// CLI hosts construct one from `discoverLocalUis()` results and pass it
+// as `createGguiServer({ blueprintProvider: ... })` so every UI declared
+// in `ggui.json#blueprints.include` surfaces through
+// `ggui_list_featured_blueprints`. Re-exported here for the same reason
+// as `InMemoryShortCodeIndex` — CLI hosts shouldn't need a direct
+// `@ggui-ai/mcp-server-core` dep to compose the first-run server.
+export { ManifestBlueprintProvider } from '@ggui-ai/mcp-server-core/in-memory';
+// Generator-registry helpers re-exported so callers composing a
+// custom registry don't need a direct `@ggui-ai/mcp-server-core`
+// import just for slug parsing.
+export { formatGeneratorSlug, isValidGeneratorSlug, parseGeneratorSlug, } from '@ggui-ai/mcp-server-core';

package/dist/instructions-presets.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Server-level instructions presets for the MCP `InitializeResult.
+ * instructions` field.
+ *
+ * **What this string does**: per the MCP spec
+ * (`@modelcontextprotocol/sdk/types.js`), `instructions` is "a hint to
+ * the model" that hosts MAY add to the system prompt. Its job is to
+ * help the LLM **understand the server's tools and protocol**. It is
+ * NOT an enforcement mechanism — the LLM weighs it against the host's
+ * own system prompt, the user's chat-level instructions, and built-in
+ * tool-selection priors.
+ *
+ * **Difference from per-tool description**: per-tool descriptions
+ * answer "what does THIS tool do?" Server instructions answer "what is
+ * this server, and how do its tools fit together?" Both are spec-
+ * defined hints, both compose into the same system prompt.
+ *
+ * **Why presets explain protocol, not behavior**: previous iterations
+ * tried to nudge the LLM to "render every response" via imperative
+ * language. In observed practice this is worth less than a single
+ * line of user-side custom instruction, AND the spec doesn't promise
+ * the field has that pull. Honest framing: the presets explain what
+ * ggui is, how the three lifecycle tools relate, and how rendered UIs
+ * route actions/streams back. The LLM picks tools when its judgment
+ * matches; for stronger pull, ship a recommended user-instruction
+ * snippet (see the console `/settings` onboarding card).
+ *
+ * **Preset depth**:
+ *
+ *   - `'default'`    — concise protocol explainer (server identity +
+ *                      live-UI mechanism + lifecycle bullets).
+ *   - `'aggressive'` — adds the action-routing detail.
+ *   - `'always'`     — adds a worked invocation example.
+ *   - `'minimal'`    — server identity only.
+ *   - `'off'`        — omit the field entirely.
+ *
+ * Names are kept (vs renaming to `verbose` etc.) for compat with the
+ * already-shipped `--mcp-instructions` CLI flag and operator configs.
+ */
+/**
+ * Preset name → instruction-string map. Operators select a preset by
+ * passing `mcpInstructions: 'default'` (etc.) to `createGguiServer`.
+ * Pass an arbitrary string to substitute custom copy. Pass `'off'` or
+ * the empty string to omit the field entirely.
+ *
+ * @public
+ */
+export declare const MCP_INSTRUCTIONS_PRESETS: {
+    /**
+     * Concise protocol explainer — what ggui is, four-spec mental
+     * model, lifecycle with nextStep-driven routing, complementary
+     * tools. No-preset default.
+     */
+    readonly default: string;
+    /**
+     * Default protocol primer + the host-side action-routing detail
+     * (Pattern α direct dispatch vs Pattern β cross-server consent
+     * bridge). Pick when the operator wants the LLM to also reason
+     * about how the underlying tools/call envelopes flow.
+     */
+    readonly aggressive: string;
+    /**
+     * `aggressive` + a worked invocation example. Useful when the
+     * operator wants the LLM to see a complete handshake → push
+     * pattern at boot.
+     */
+    readonly always: string;
+    /**
+     * Server identity only — no protocol detail. Pick when the
+     * operator wants per-tool descriptions to be the sole signal.
+     */
+    readonly minimal: "This server speaks the ggui protocol — an open standard for delivering interactive UIs to end-users (https://github.com/ggui-ai/ggui).";
+    /**
+     * Sentinel value. The wiring layer sees `'off'` and passes
+     * `instructions: undefined` to the McpServer constructor — the
+     * server omits the field on InitializeResult entirely.
+     */
+    readonly off: "";
+};
+/**
+ * The preset enum's string keys, exported as a type for caller
+ * autocomplete.
+ *
+ * @public
+ */
+export type McpInstructionsPreset = keyof typeof MCP_INSTRUCTIONS_PRESETS;
+/**
+ * The values `createGguiServer.mcpInstructions` accepts:
+ *
+ *   - One of the preset names: `'default' | 'aggressive' | 'always' | 'minimal' | 'off'`.
+ *   - An arbitrary string — used verbatim as the `instructions` field.
+ *   - `undefined` — falls through to the no-preset default (`'default'`).
+ *
+ * @public
+ */
+export type McpInstructionsValue = McpInstructionsPreset | string;
+/**
+ * Resolve the operator-provided value into the actual string the MCP
+ * server should send. Returns `undefined` when the result is empty
+ * (the constructor should omit the field).
+ *
+ * **No-preset default = `'default'`.** All behavior-text presets
+ * explain the protocol now (vs nudging tool-use), so the previous
+ * "aggressive as no-preset default" rationale no longer applies —
+ * `'default'` is the appropriate baseline. Operators who want fuller
+ * protocol detail opt into `'aggressive'` or `'always'`. To turn
+ * instructions off entirely, pass `'off'`.
+ *
+ * @public
+ */
+export declare function resolveMcpInstructions(value: McpInstructionsValue | undefined): string | undefined;
+//# sourceMappingURL=instructions-presets.d.ts.map

package/dist/instructions-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions-presets.d.ts","sourceRoot":"","sources":["../src/instructions-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA4FH;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;IACnC;;;;OAIG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IASH;;;OAGG;;IAIH;;;;OAIG;;CAEK,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG,MAAM,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAAG,SAAS,GACtC,MAAM,GAAG,SAAS,CAWpB"}

package/dist/instructions-presets.js

@@ -0,0 +1,195 @@
+/**
+ * Server-level instructions presets for the MCP `InitializeResult.
+ * instructions` field.
+ *
+ * **What this string does**: per the MCP spec
+ * (`@modelcontextprotocol/sdk/types.js`), `instructions` is "a hint to
+ * the model" that hosts MAY add to the system prompt. Its job is to
+ * help the LLM **understand the server's tools and protocol**. It is
+ * NOT an enforcement mechanism — the LLM weighs it against the host's
+ * own system prompt, the user's chat-level instructions, and built-in
+ * tool-selection priors.
+ *
+ * **Difference from per-tool description**: per-tool descriptions
+ * answer "what does THIS tool do?" Server instructions answer "what is
+ * this server, and how do its tools fit together?" Both are spec-
+ * defined hints, both compose into the same system prompt.
+ *
+ * **Why presets explain protocol, not behavior**: previous iterations
+ * tried to nudge the LLM to "render every response" via imperative
+ * language. In observed practice this is worth less than a single
+ * line of user-side custom instruction, AND the spec doesn't promise
+ * the field has that pull. Honest framing: the presets explain what
+ * ggui is, how the three lifecycle tools relate, and how rendered UIs
+ * route actions/streams back. The LLM picks tools when its judgment
+ * matches; for stronger pull, ship a recommended user-instruction
+ * snippet (see the console `/settings` onboarding card).
+ *
+ * **Preset depth**:
+ *
+ *   - `'default'`    — concise protocol explainer (server identity +
+ *                      live-UI mechanism + lifecycle bullets).
+ *   - `'aggressive'` — adds the action-routing detail.
+ *   - `'always'`     — adds a worked invocation example.
+ *   - `'minimal'`    — server identity only.
+ *   - `'off'`        — omit the field entirely.
+ *
+ * Names are kept (vs renaming to `verbose` etc.) for compat with the
+ * already-shipped `--mcp-instructions` CLI flag and operator configs.
+ */
+/**
+ * Action-routing pattern detail (Pattern α / Pattern β). Layered atop
+ * `default` by the `aggressive` and `always` presets — `default`
+ * already covers the actionSpec wire shape via the MENTAL MODEL
+ * block; this paragraph adds the host-side dispatch semantics that
+ * matter when an operator wants the LLM to also reason about how the
+ * underlying tools/call envelopes flow.
+ */
+const ACTION_ROUTING_PARAGRAPH = "Action routing: every actionSpec entry is a GESTURE — a discrete event the agent reacts to on its next turn. When the user interacts, the iframe relays the action through `ggui_runtime_submit_action` to the server, which appends the event onto a per-stack-item pipe. Your `ggui_consume` long-poll unblocks mid-turn with the event payload plus a uiContext snapshot of every declared contextSpec slot. There is no synchronous server-side tool-fire — `actions drive turns` is a structural invariant (docs/principles/actions-vs-context.md): an action always waits for the agent. Cross-MCP `nextStep` hints work the same way: the agent reads the event's `actionData.nextStep`, decides whether to honor it, and calls the named tool on the next turn (the tool MAY live on a different MCP server — declare it in `agentCapabilities.tools` so the cross-ref invariant passes).";
+/**
+ * Worked invocation example. Layered atop the `aggressive` content by
+ * `always` only — shows the literal handshake → push pattern an
+ * operator can copy.
+ */
+const WORKED_EXAMPLE_PARAGRAPH = "Example: ggui_handshake({ sessionId: 's_…', intent: 'a settings panel for notification preferences', blueprintDraft: { contract: {...}, variance: { persona: 'minimalist' } } }) returns { handshakeId: 'h_…', suggestion: { origin: 'cache' | 'agent' | 'synth', blueprintMeta: { blueprintId, contractHash, codeHash?, generator, variance }, amendments?, validationFindings? }, contractHash: '<hex>' }. ACCEPT PATH: ggui_push({ handshakeId: 'h_…', decision: { kind: 'accept' } }) — reuses the provisional blueprintId. OVERRIDE PATH: ggui_push({ handshakeId: 'h_…', decision: { kind: 'override', blueprintDraft: { contract: { ...refined } } } }) — mints a fresh blueprintId against your new draft.";
+/**
+ * The default-preset body, captured as a const so `aggressive` and
+ * `always` can layer additional paragraphs on top without diverging
+ * from the protocol-primer baseline.
+ */
+const DEFAULT_PRESET_BODY = [
+    'GGUI PROTOCOL — open standard for agents to deliver real interactive UIs to end-users (https://github.com/ggui-ai/ggui). You are the agent; the user is on the other side of a rendered UI, NOT a text terminal. Every user message — whether an obvious UI request (a card, a form, a list, a chart, a settings panel) OR conversational chat (a greeting, a question, a follow-up, even "hey") — must be rendered via the ggui_* tools rather than replied to in plain text. There is no plain-text reply path. For greetings, render a greeting/chat UI. For questions, render an answer card. For "hey", render a hello-bubble or a quick-reply chooser. The renderer can paint any HTML/CSS/JS your contract describes — including simple text bubbles — so "should I use ggui?" reduces to "always".',
+    '',
+    '═══ MENTAL MODEL ═══',
+    '',
+    'Every UI you render is described by a DataContract — a typed declaration of four data surfaces. You author the contract at handshake time; the contract is what the renderer compiles + the agent later interacts with. Four specs, each with one job:',
+    '',
+    '  • propsSpec    — agent → client (one-shot data). The initial values the rendered UI displays. Push sends these as `props`; ggui_update mutates them after delivery. e.g. a weather card has {temperature, condition, city} on propsSpec.',
+    '',
+    '  • actionSpec   — client → agent (discrete events). User gestures (clicks, submits) that drive the agent\'s NEXT TURN. Each entry has a `label`, optional `schema` for the payload, and optional `nextStep: "<toolName>"`. When `nextStep` is present, it names the tool the agent SHOULD call next AND the same name MUST also appear in `agentCapabilities.tools` (cross-ref invariant; rejection code `cross_reference_unresolved`). Omit `nextStep` entirely when the agent should decide freely from broader context (open-ended form submits). e.g. a feedback form has `submit` on actionSpec with `nextStep:"record_feedback"` (and `record_feedback` listed under `agentCapabilities.tools`).',
+    '',
+    '  • contextSpec  — client → agent (observed state, not events). Continuous client state the agent observes — slider position, draft text, current selection. Use contextSpec when you need to KNOW the state but don\'t need to ACT on every change. On MCP Apps hosts the runtime auto-mirrors the snapshot into the host\'s widget-context surface (the agent sees it on the next turn without polling). On raw MCP clients there is no auto-mirror — call ggui_get_stack to read `contextSnapshot` when you need the latest values. e.g. a calendar has `selectedDate` on contextSpec.',
+    '',
+    '  • streamSpec   — agent → client (live updates). Live outbound channels for streaming data to the UI mid-render — chat tokens, progress events, log lines, time-series data. Each entry has a `schema` for the frame shape; you push frames via ggui_emit. e.g. a chat surface has `assistantMessage` on streamSpec for token-by-token output.',
+    '',
+    'PLACEMENT RULE for actionSpec vs contextSpec: "does this thing need the agent\'s next-turn reasoning?" Yes → actionSpec. No → contextSpec. There is no third category (full rule: docs/principles/actions-vs-context.md).',
+    '',
+    '═══ LIFECYCLE ═══',
+    '',
+    'Every chat that touches ggui follows this loop:',
+    '',
+    '  1. ggui_new_session — FIRST CALL of any chat. Mints a sessionId. Call once per conversation; thread the result through every subsequent handshake.',
+    '',
+    '  2. ggui_handshake — negotiate a contract for the next UI. Post {sessionId, intent, blueprintDraft: {contract, variance?, generator?}}. `variance` is optional and lets you steer cache lookup + gen by axis: `persona` ("minimalist", "playful"), `aesthetic` ("dense", "spacious"), `intentContext` (free-form usage notes), `seedPrompt` (deterministic seed). Server runs BlueprintSearch + contract-validation in parallel and returns a handshakeId + suggestion (origin: cache | agent | synth). cache → blueprint already exists, push delivers it instantly. agent → novel-but-clean draft, gen runs on push. synth → your draft failed validation, server amended it; diff is on suggestion.amendments.',
+    '',
+    '  3. ggui_push — deliver the UI. handshakeId is REQUIRED (from step 2); calling push without it fails with `handshake_not_found`. Send {handshakeId, decision: {kind:"accept"}} to use the suggestion verbatim, OR {handshakeId, decision: {kind:"override", blueprintDraft:{...}}} to mint fresh against a new draft. If the contract declares propsSpec, props is REQUIRED. Handshake records are SINGLE-USE and expire after 10 minutes. On error: `handshake_not_found` → call ggui_handshake again. `contract_violation` (props don\'t match propsSpec) / `contract_schema_invalid` (an inner JSON Schema is malformed) / `cross_reference_unresolved` (`actionSpec[*].nextStep` or `streamSpec[*].source.tool` names a tool not in `agentCapabilities.tools`) / `schema_mismatch_error` (action schema not a subset of the named tool\'s inputSchema) / `missing_props` → fix the input and retry with the SAME handshakeId (still valid until consumed).',
+    '',
+    '  4. NEXT STEP — read the push response. If it carries a `nextStep` field, call that tool with the given args. Push only emits `nextStep` when the contract declared a non-empty actionSpec (i.e., the UI has interactive buttons/forms); in that case nextStep names ggui_consume and your job is to long-poll for the user\'s gesture. If the push response has NO nextStep, the UI is pure-display (props only, no actionSpec) — you can end your turn; the user reads the UI and types their next prompt when they\'re ready.',
+    '',
+    '  5. ggui_consume (when push said to) — long-poll for user interaction. Keyed by stackItemId. Blocks up to ~15 min (deployment-configurable); returns when an actionSpec event arrives or the session closes. Each return carries `{events, status}`: `events[]` is the discrete action(s) the user just took. Each event is an envelope `{intent, actionData, uiContext, actionId, firedAt}` — `actionData` is WHAT the user did (action name + validated payload, plus `nextStep` hint if the author declared one); `uiContext` is the iframe-local snapshot of every declared contextSpec slot AT THE MOMENT the action fired (form fields, selected tab, slider value, scroll position — whatever the contract declared). Both inform your reaction without a second round trip. Honor each event\'s `actionData.nextStep` hint if the tool is available, then loop back to step 2 to render the response. Continue until consume returns status:"completed" or no further follow-up is needed.',
+    '',
+    '  6. ggui_update — reflect the new state in the UI. After ANY domain-tool call whose result changed data the rendered UI displays (e.g. `todo_toggle` flips a todo\'s `done`, `cart_add_item` extends a cart, `note_save` persists text), you MUST immediately call `ggui_update` with the refreshed props so the user sees what just happened. The rendered UI does NOT auto-refresh — it only shows the props it was last given. Skipping `ggui_update` after a state-mutating tool call leaves the user staring at stale state and is the #1 wire bug. Pattern: `consume → domain-tool → ggui_update → loop to consume`. Two modes: `{stackItemId, kind:"replace", props}` sends the FULL new props map (use when most fields changed or you want deterministic restoration); `{stackItemId, kind:"merge", patch}` sends ONLY the delta as RFC 7396 JSON Merge Patch (shallow merge, recurse on nested objects, `null` deletes a key, arrays fully replace — use when most props stay the same and only one or two fields changed). Prefer `merge` after a single domain-tool mutation; prefer `replace` when restoring state or when most fields changed. The only times you skip `ggui_update` are: (a) the domain tool was pure-read (todo_list, search, etc.) AND its result wasn\'t for the UI, or (b) the contract has no propsSpec (pure-display with no mutable state).',
+    '',
+    'In short: let the protocol\'s `nextStep` fields drive routing. Every ggui_* tool whose response logically chains forwards (new_session → handshake → push → consume) emits a nextStep when there IS a next step; the absence of nextStep means "you\'re done with this thread for now."',
+    '',
+    '═══ COMPLEMENTARY TOOLS ═══',
+    '',
+    '  • ggui_update    — refresh a delivered UI with new props WITHOUT destroying it. Two modes: `kind:"replace"` (full props) or `kind:"merge"` (RFC 7396 delta — see step 6). ALWAYS call this after any state-mutating tool call; re-pushing would lose scroll position, focus, and uncommitted input. Forgetting `ggui_update` after a mutation is the most common protocol bug.',
+    '',
+    '  • ggui_emit    — push frames to a streamSpec channel on a delivered UI. Use when the contract declared streamSpec (chat tokens, progress bars, live data). Frames must match the channel\'s declared `schema`. The live channel of the wire carries these.',
+    '',
+    '  • ggui_pop       — pop the top stack item (e.g., close a modal you pushed). Idempotent — popping an empty stack returns null without error.',
+    '',
+    '  • ggui_close     — explicitly end a session. Optional; sessions GC on their own. Use when the user has clearly finished and you want to free resources.',
+    '',
+    '  • ggui_get_session / ggui_get_stack — inspect current session state if you\'ve lost track of what\'s rendered. ggui_get_stack also returns each item\'s `contextSnapshot` — the canonical way to read contextSpec values from a raw MCP client.',
+    '',
+    '═══ HOST RENDERING ═══',
+    '',
+    'Two host shapes consume push output identically — your job is the same:',
+    '',
+    '  • MCP Apps hosts (claude.ai, MCP-Apps-aware desktop clients) — push responses carry the rendered UI inline via `_meta.ggui.bootstrap`; the host displays it automatically. The user interacts with the UI directly, and contextSpec snapshots flow back into your widget-context surface without any agent action.',
+    '',
+    '  • Plain MCP clients (Claude Agent SDK without MCP Apps host adapter, raw CLI clients) — push responses carry a renderer URL in the structured content; the host either embeds it as an iframe or displays it as a link. Wire flow is identical (handshake → push → consume); only the rendering surface differs.',
+    '',
+    'Rendered UIs are LIVE — actionSpec entries route back to you as events you receive via consume (each gesture\'s payload validated against the entry\'s declared schema). You don\'t write glue code for any of this; declaring the spec at handshake time is enough.',
+    '',
+    '═══ TOOL DISCOVERY (lazy-loading hosts) ═══',
+    '',
+    'Some MCP hosts (notably claude.ai\'s connector model) use PROGRESSIVE tool discovery — only a small priority subset of tools is warmed at conversation start; the rest must be explicitly discovered via `tool_search` before they\'re callable. The ggui_* loop crosses this boundary on every push: handshake/push warm easily because you call them early, but `ggui_consume` and `ggui_update` are needed AFTER push and the host may not have loaded them yet.',
+    '',
+    'SYMPTOM: a tool call fails with a message like "tool has not been loaded yet — call tool_search first" or "you do not have the correct parameter names." RECOVERY: call `tool_search` with the tool name as a query (e.g. `tool_search({ query: "ggui_consume" })`), wait for the load to complete, then retry the original call with the same args. Same pattern for `ggui_update`. After one successful `tool_search` per tool per conversation, subsequent calls work directly.',
+    '',
+    'WHEN IN DOUBT: if the push response carries `nextStep`, the host has effectively asked you to call that tool. Don\'t skip ggui_consume because the host whined about it being unloaded — `tool_search` first, then call. Skipping it leaves the user staring at a UI whose actions silently never reach the agent — the worst protocol failure mode.',
+];
+/**
+ * Preset name → instruction-string map. Operators select a preset by
+ * passing `mcpInstructions: 'default'` (etc.) to `createGguiServer`.
+ * Pass an arbitrary string to substitute custom copy. Pass `'off'` or
+ * the empty string to omit the field entirely.
+ *
+ * @public
+ */
+export const MCP_INSTRUCTIONS_PRESETS = {
+    /**
+     * Concise protocol explainer — what ggui is, four-spec mental
+     * model, lifecycle with nextStep-driven routing, complementary
+     * tools. No-preset default.
+     */
+    default: DEFAULT_PRESET_BODY.join('\n'),
+    /**
+     * Default protocol primer + the host-side action-routing detail
+     * (Pattern α direct dispatch vs Pattern β cross-server consent
+     * bridge). Pick when the operator wants the LLM to also reason
+     * about how the underlying tools/call envelopes flow.
+     */
+    aggressive: [...DEFAULT_PRESET_BODY, '', ACTION_ROUTING_PARAGRAPH].join('\n'),
+    /**
+     * `aggressive` + a worked invocation example. Useful when the
+     * operator wants the LLM to see a complete handshake → push
+     * pattern at boot.
+     */
+    always: [
+        ...DEFAULT_PRESET_BODY,
+        '',
+        ACTION_ROUTING_PARAGRAPH,
+        '',
+        WORKED_EXAMPLE_PARAGRAPH,
+    ].join('\n'),
+    /**
+     * Server identity only — no protocol detail. Pick when the
+     * operator wants per-tool descriptions to be the sole signal.
+     */
+    minimal: 'This server speaks the ggui protocol — an open standard for delivering interactive UIs to end-users (https://github.com/ggui-ai/ggui).',
+    /**
+     * Sentinel value. The wiring layer sees `'off'` and passes
+     * `instructions: undefined` to the McpServer constructor — the
+     * server omits the field on InitializeResult entirely.
+     */
+    off: '',
+};
+/**
+ * Resolve the operator-provided value into the actual string the MCP
+ * server should send. Returns `undefined` when the result is empty
+ * (the constructor should omit the field).
+ *
+ * **No-preset default = `'default'`.** All behavior-text presets
+ * explain the protocol now (vs nudging tool-use), so the previous
+ * "aggressive as no-preset default" rationale no longer applies —
+ * `'default'` is the appropriate baseline. Operators who want fuller
+ * protocol detail opt into `'aggressive'` or `'always'`. To turn
+ * instructions off entirely, pass `'off'`.
+ *
+ * @public
+ */
+export function resolveMcpInstructions(value) {
+    if (value === undefined) {
+        return MCP_INSTRUCTIONS_PRESETS.default;
+    }
+    if (value in MCP_INSTRUCTIONS_PRESETS) {
+        const resolved = MCP_INSTRUCTIONS_PRESETS[value];
+        return resolved.length > 0 ? resolved : undefined;
+    }
+    // Caller passed a custom string. Empty string → omit.
+    return value.length > 0 ? value : undefined;
+}