@ggui-ai/mcp-server 0.1.0-rc.3 → 0.2.0-alpha.3

package/dist/mcp-mounts.d.ts

@@ -1,7 +1,7 @@
 /**
  * mcp-mounts — aggregate external MCP tool handler bundles onto the
  * ggui `/mcp` surface so one session can see ggui-native tools (e.g.
- * `ggui_push`) AND mounted tools (e.g. `tasks_*`) through a single
+ * `ggui_render`) AND mounted tools (e.g. `tasks_*`) through a single
  * MCP connection.
  *
  * Scope lock: a **mount** is a named bundle of `SharedHandler`
@@ -20,9 +20,9 @@
  * `buildMcpServer` registration, `toolCount`, telemetry, and logging
  * all Just Work.
  */
-import type { ZodRawShape } from 'zod';
-import type { HandlerContext, SharedHandler } from '@ggui-ai/mcp-server-handlers';
-import type { WiredActionContext, WiredActionRouter } from './session-channel.js';
+import type { HandlerContext, SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import type { ZodRawShape } from "zod";
+import type { WiredActionContext, WiredActionRouter } from "./render-channel.js";
 /**
  * Runtime ctx the mount-router hands the mount handler. Structurally a
  * superset of `HandlerContext` (so the mount's `handler(input, ctx)`
@@ -30,7 +30,7 @@ import type { WiredActionContext, WiredActionRouter } from './session-channel.js
  * {@link WiredActionContext}.
  *
  * Why the type is exported: TS-authored mount tools that want to read
- * `ctx.sendPropsUpdate` / `ctx.stackItemId` import this and narrow their
+ * `ctx.sendPropsUpdate` / `ctx.renderId` import this and narrow their
  * `handler` parameter (e.g. `async handler(input, ctx) { const wired =
  * ctx as WiredMountContext; … }`). JS-authored mounts (.mjs) read the
  * fields structurally — they're present on the runtime object whether
@@ -40,25 +40,25 @@ import type { WiredActionContext, WiredActionRouter } from './session-channel.js
  * narrow on `HandlerContext`. Widening that type would force every
  * shared handler (ggui-native + mounted) to acknowledge a wired-only
  * surface, even handlers that never run through the wired-action path
- * (e.g. `ggui_push`, blueprint search). The structural superset here
+ * (e.g. `ggui_render`, blueprint search). The structural superset here
  * keeps the canonical contract narrow without sacrificing access for
  * mount tools that opt in.
  */
 /**
  * Intersection (not interface-extension) because `HandlerContext` declares
- * `sessionId?` / `stackItemId?` as optional — the canonical context shape any
- * handler may see — whereas `WiredActionContext` declares them as required
- * (the wired-action dispatcher always knows the active session + stack
- * frame at invocation time). Interface-extends rejects "narrowing
- * optional → required" via TS2320 ("cannot simultaneously extend"), but
- * an intersection composes the two perfectly: optional ∧ required ≡ required.
+ * `renderId?` as optional — the canonical context shape any handler may
+ * see — whereas `WiredActionContext` declares it as required (the
+ * wired-action dispatcher always knows the active render at invocation
+ * time). Interface-extends rejects "narrowing optional → required" via
+ * TS2320 ("cannot simultaneously extend"), but an intersection composes
+ * the two perfectly: optional ∧ required ≡ required.
  *
  * Surface for consumers stays identical — a TS-authored mount that types
- * its `handler` parameter as `WiredMountContext` reads `sessionId: string`
- * + `stackItemId: string` (no `| undefined`) + every `HandlerContext` field
+ * its `handler` parameter as `WiredMountContext` reads `renderId: string`
+ * (no `| undefined`) + every `HandlerContext` field
  * (`appId`, `requestId`, optional `apiKeyHash`).
  */
-export type WiredMountContext = Omit<HandlerContext, 'sessionId' | 'stackItemId'> & WiredActionContext;
+export type WiredMountContext = Omit<HandlerContext, "renderId"> & WiredActionContext;
 /**
  * One named bundle of tool handlers the server should aggregate onto
  * its MCP surface.
@@ -78,7 +78,7 @@ export interface McpServerMount {
     readonly name: string;
     /**
      * Tool handler bundle. Each entry is a `SharedHandler` — the same
-     * shape ggui-native handlers (blueprint family, session-mutations,
+     * shape ggui-native handlers (blueprint family, renders,
      * threads) already use. The server calls {@link SharedHandler.handler}
      * through `buildMcpServer`'s regular registration path; validation,
      * logging, and output-schema parsing all happen uniformly.
@@ -90,7 +90,7 @@ export interface McpServerMount {
  * raw string via {@link validateServicePath}.
  */
 export type ServicePath = string & {
-    readonly __brand: 'ServicePath';
+    readonly __brand: "ServicePath";
 };
 /**
  * Validate + brand a service HTTP path. Throws on malformed input or
@@ -209,9 +209,9 @@ export declare function composeHandlersWithMounts(baseHandlers: ReadonlyArray<Sh
  *
  * Ownership + scoping:
  *   - Only MOUNT handlers participate. ggui-native handlers
- *     (`ggui_push`, `ggui_handshake`, etc.) are platform tools and
+ *     (`ggui_render`, `ggui_handshake`, etc.) are platform tools and
  *     deliberately NOT exposed as wire-dispatchable actions — a
- *     component that tried to dispatch `ggui_push` would bypass the
+ *     component that tried to dispatch `ggui_render` would bypass the
  *     agentic-loop contract.
  *   - Name collisions across mounts are prevented at aggregation
  *     time by {@link composeHandlersWithMounts}, so the first-match
@@ -226,7 +226,8 @@ export declare function composeHandlersWithMounts(baseHandlers: ReadonlyArray<Sh
  *     {@link WiredActionContext}. The runtime ctx the mount handler
  *     sees is a structural superset
  *     ({@link WiredMountContext}) so a JS-authored mount can call
- *     `ctx.sendPropsUpdate(ctx.stackItemId, {...})` directly. The static
+ *     `ctx.sendPropsUpdate({...})` directly (closed over `ctx.renderId`).
+ *     The static
  *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
  *     untouched — tooling that doesn't read the wired fields keeps its
  *     existing types.

package/dist/mcp-mounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-mounts.d.ts","sourceRoot":"","sources":["../src/mcp-mounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,aAAa,CAAC,GAC/E,kBAAkB,CAAC;AAErB;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAsBvE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAiB1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,SAAS,GAC9C,aAAa,CAAC,UAAU,CAAC,CAyC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EACpE,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,GAChD,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAyDxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACjD,cAAc,EAAE,MAAM,cAAc,GACnC,iBAAiB,GAAG,IAAI,CA2C1B"}
+{"version":3,"file":"mcp-mounts.d.ts","sourceRoot":"","sources":["../src/mcp-mounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GAAG,kBAAkB,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAsBvE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAiB1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,SAAS,GAC9C,aAAa,CAAC,UAAU,CAAC,CAyC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EACpE,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,GAChD,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAoDxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACjD,cAAc,EAAE,MAAM,cAAc,GACnC,iBAAiB,GAAG,IAAI,CAyC1B"}

package/dist/mcp-mounts.js

@@ -4,16 +4,16 @@
  * silently swallow OAuth discovery / health / per-app traffic.
  */
 const RESERVED_SERVICE_PATHS = new Set([
-    '/',
-    '/mcp',
-    '/protocol',
-    '/ops',
-    '/ws',
-    '/health',
-    '/.well-known',
-    '/oauth',
-    '/_ggui',
-    '/ggui',
+    "/",
+    "/mcp",
+    "/protocol",
+    "/ops",
+    "/ws",
+    "/health",
+    "/.well-known",
+    "/oauth",
+    "/_ggui",
+    "/ggui",
 ]);
 const SERVICE_PATH_REGEX = /^\/[a-zA-Z0-9_/-]+$/;
 /**
@@ -31,7 +31,7 @@ export function validateServicePath(p) {
     if (!SERVICE_PATH_REGEX.test(p)) {
         throw new Error(`createGguiServer: mcpServices path "${p}" is malformed — must start with "/" and contain only letters, digits, "-", "_", and "/".`);
     }
-    if (p.length > 1 && p.endsWith('/')) {
+    if (p.length > 1 && p.endsWith("/")) {
         throw new Error(`createGguiServer: mcpServices path "${p}" must not end with "/" (use "${p.slice(0, -1)}" instead).`);
     }
     if (RESERVED_SERVICE_PATHS.has(p)) {
@@ -57,8 +57,8 @@ export function validateMcpServices(services) {
         return services ?? [];
     const seenPaths = new Set();
     for (const svc of services) {
-        if (typeof svc.name !== 'string' || svc.name.length === 0) {
-            throw new Error('createGguiServer: every `mcpServices` entry must carry a non-empty string `name` (for validation-error clarity).');
+        if (typeof svc.name !== "string" || svc.name.length === 0) {
+            throw new Error("createGguiServer: every `mcpServices` entry must carry a non-empty string `name` (for validation-error clarity).");
         }
         validateServicePath(svc.path);
         if (seenPaths.has(svc.path)) {
@@ -67,7 +67,7 @@ export function validateMcpServices(services) {
         seenPaths.add(svc.path);
         const seenTools = new Set();
         for (const h of svc.handlers) {
-            if (typeof h.outputSchema !== 'object' ||
+            if (typeof h.outputSchema !== "object" ||
                 h.outputSchema === null ||
                 Object.keys(h.outputSchema).length === 0) {
                 throw new Error(`createGguiServer: service "${svc.name}" handler "${h.name}" declares an empty \`outputSchema\` — this silently strips \`structuredContent\` at the MCP SDK boundary. Declare the fields the handler returns (e.g. \`outputSchema: { items: z.array(...) }\`).`);
@@ -104,13 +104,11 @@ export function composeHandlersWithMounts(baseHandlers, mounts) {
     // any other string = the mount's `name` that first claimed the tool.
     const owner = new Map();
     for (const h of baseHandlers)
-        owner.set(h.name, 'ggui');
-    const aggregated = [
-        ...baseHandlers,
-    ];
+        owner.set(h.name, "ggui");
+    const aggregated = [...baseHandlers];
     for (const mount of mounts) {
-        if (typeof mount.name !== 'string' || mount.name.length === 0) {
-            throw new Error('createGguiServer: every `mcpMounts` entry must carry a non-empty string `name` (for diagnostic telemetry + collision-error clarity).');
+        if (typeof mount.name !== "string" || mount.name.length === 0) {
+            throw new Error("createGguiServer: every `mcpMounts` entry must carry a non-empty string `name` (for diagnostic telemetry + collision-error clarity).");
         }
         for (const mh of mount.handlers) {
             // `outputSchema: {}` (empty `ZodRawShape`) silently strips
@@ -126,16 +124,14 @@ export function composeHandlersWithMounts(baseHandlers, mounts) {
             // legitimate no-output tool ever lands in a mount, declare
             // `{ ok: z.literal(true) }` or equivalent — the zero-field
             // case is never what you want over the wire.
-            if (typeof mh.outputSchema !== 'object' ||
+            if (typeof mh.outputSchema !== "object" ||
                 mh.outputSchema === null ||
                 Object.keys(mh.outputSchema).length === 0) {
                 throw new Error(`createGguiServer: mount "${mount.name}" handler "${mh.name}" declares an empty \`outputSchema\` — this silently strips \`structuredContent\` at the MCP SDK boundary. Declare the fields the handler returns (e.g. \`outputSchema: { items: z.array(...) }\`). If the tool genuinely returns nothing, declare a sentinel like \`{ ok: z.literal(true) }\`.`);
             }
             const prior = owner.get(mh.name);
             if (prior !== undefined) {
-                const priorLabel = prior === 'ggui'
-                    ? 'a ggui-native tool'
-                    : `mount "${prior}"`;
+                const priorLabel = prior === "ggui" ? "a ggui-native tool" : `mount "${prior}"`;
                 throw new Error(`createGguiServer: mount "${mount.name}" registers tool "${mh.name}" which collides with ${priorLabel}. Rename the tool or drop the duplicate mount.`);
             }
             owner.set(mh.name, mount.name);
@@ -153,9 +149,9 @@ export function composeHandlersWithMounts(baseHandlers, mounts) {
  *
  * Ownership + scoping:
  *   - Only MOUNT handlers participate. ggui-native handlers
- *     (`ggui_push`, `ggui_handshake`, etc.) are platform tools and
+ *     (`ggui_render`, `ggui_handshake`, etc.) are platform tools and
  *     deliberately NOT exposed as wire-dispatchable actions — a
- *     component that tried to dispatch `ggui_push` would bypass the
+ *     component that tried to dispatch `ggui_render` would bypass the
  *     agentic-loop contract.
  *   - Name collisions across mounts are prevented at aggregation
  *     time by {@link composeHandlersWithMounts}, so the first-match
@@ -170,7 +166,8 @@ export function composeHandlersWithMounts(baseHandlers, mounts) {
  *     {@link WiredActionContext}. The runtime ctx the mount handler
  *     sees is a structural superset
  *     ({@link WiredMountContext}) so a JS-authored mount can call
- *     `ctx.sendPropsUpdate(ctx.stackItemId, {...})` directly. The static
+ *     `ctx.sendPropsUpdate({...})` directly (closed over `ctx.renderId`).
+ *     The static
  *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
  *     untouched — tooling that doesn't read the wired fields keeps its
  *     existing types.
@@ -212,8 +209,7 @@ export function composeWiredActionRouterFromMounts(mounts, resolveContext) {
             const baseCtx = resolveContext();
             const ctx = {
                 ...baseCtx,
-                sessionId: wiredCtx.sessionId,
-                stackItemId: wiredCtx.stackItemId,
+                renderId: wiredCtx.renderId,
                 sendPropsUpdate: wiredCtx.sendPropsUpdate,
             };
             return handler.handler(input, ctx);