@guuey/mcp-apps-host 0.3.0 → 0.3.1

package/README.md

@@ -18,6 +18,13 @@ role's client-side narrowing and mount contract:
   result) — never by replaying stored mount material. The read transport is injected
   (`UiResourceReader`); the host owns auth and user-ownership enforcement,
   and a deny is byte-identical to a miss.
+- **Generic reader assembly** (`createMcpUiResourceReader`): hand it one
+  host-owned `resources/read` callable (a raw MCP client, an authenticated
+  proxy — no SDK dependency imposed) and get a `UiResourceReader` back, with
+  the trust rules built in: deny == miss == placeholder, and the sandbox
+  channel derives from the _requested_ locator uri, never the response
+  (`uiResourceChannel`). `@guuey/agent-client`'s `createUiResourceReader` is
+  this assembly over guuey's platform proxy.
 - **Sandbox-trust channels** (`ViewMountChannel`): which sandbox host page a
   payload may mount in, until per-resource declared-CSP construction lands.
 

package/dist/card-mount.d.ts

@@ -51,15 +51,23 @@ export type ViewMountChannel = "inline" | "ggui" | "locator";
  * + its tool result — see the conformance map.) Until a reader is wired, the honest render
  * is the host's own placeholder, never a stale mount.
  */
-export type ViewMount = {
+export type ViewMount = ResolvedViewMount | LocatorViewMount;
+/**
+ * A view with mount material in hand — the arms a host can render directly,
+ * and the ONLY arms a `UiResourceReader` resolves (guuey#127): a read either
+ * yields mount material or the honest placeholder, never another locator.
+ */
+export interface ResolvedViewMount {
     channel: "inline" | "ggui";
     /** The payload an mcp-ui host mounts, identical in shape for both channels. */
     resource: McpUiResourcePayload;
-} | {
+}
+/** The durable-identity arm: no mount material, only the uri to re-fetch. */
+export interface LocatorViewMount {
     channel: "locator";
     /** The persisted `uiData.resourceUri` (`ui://` scheme) to re-fetch. */
     resourceUri: string;
-};
+}
 /**
  * Resolves a `"locator"` mount by a fresh `resources/read` of the uri over
  * an AUTHENTICATED channel the HOST owns — guuey must enforce its own

package/dist/card-mount.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"card-mount.d.ts","sourceRoot":"","sources":["../src/card-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAuD,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE/G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAW/D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;CAChC,GACD;IACE,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,SAAS,GAAG,SAAS,CAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAUhF"}
+{"version":3,"file":"card-mount.d.ts","sourceRoot":"","sources":["../src/card-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAuD,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE/G,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAW/D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,SAAS,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,SAAS,GAAG,SAAS,CAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAUhF"}

package/dist/index.d.ts

@@ -5,5 +5,6 @@
  */
 export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, type McpUiResourcePayload, } from "./block-ui.js";
 export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, type GguiRenderBootstrap, type GguiRenderDescriptor, type GguiShellHtmlOptions, } from "./ggui-render.js";
-export { snapshotViewMount, toolResultViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
+export { snapshotViewMount, toolResultViewMount, type LocatorViewMount, type ResolvedViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
+export { createMcpUiResourceReader, uiResourceChannel, type CreateMcpUiResourceReaderDeps, type McpResourceReadResult, } from "./reader.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -6,3 +6,4 @@
 export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultUiResource, uiLocator, } from "./block-ui.js";
 export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, } from "./ggui-render.js";
 export { snapshotViewMount, toolResultViewMount, } from "./card-mount.js";
+export { createMcpUiResourceReader, uiResourceChannel, } from "./reader.js";

package/dist/reader.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedViewMount, ViewMountChannel } from "./card-mount.js";
+/**
+ * One `resources/read` `contents[]` entry, structurally (SEP-1865). Kept a
+ * separate type from {@link McpUiResourcePayload} even though the shapes
+ * coincide today: this is the UNVALIDATED wire-side entry a transport hands
+ * over (phase 2 grows `_meta` here — per-resource declared CSP, conformance
+ * map step 3), while the payload is the narrowed thing a host mounts.
+ */
+export interface McpResourceReadResult {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    /** Base64 payload arm — hosts decode via {@link resourceHtml}. */
+    blob?: string;
+}
+/**
+ * Phase-1 sandbox-trust channel resolution (conformance map, retirement
+ * step 3): a `ui://ggui/…` locator mounts through the ggui-CSP host page
+ * (`"ggui"` — the shell boots ggui's runtime bundle and opens its WSS),
+ * anything else through the self-only page (`"inline"` — arbitrary tenant
+ * HTML). Retired when servers declare runtime/ws origins per resource
+ * (`_meta.ui.csp` on the read result); until then the uri prefix is the only
+ * signal a host has BEFORE fetching mount material.
+ */
+export declare function uiResourceChannel(resourceUri: string): Exclude<ViewMountChannel, "locator">;
+/** The host-supplied transport {@link createMcpUiResourceReader} assembles over. */
+export interface CreateMcpUiResourceReaderDeps {
+    /**
+     * One `resources/read` of `uri` on the host's own MCP connection (or an
+     * equivalent authenticated proxy), returning the first `contents[]` entry —
+     * or `undefined` when the read yields none. Throwing is treated as a miss.
+     */
+    readResource: (uri: string) => Promise<McpResourceReadResult | undefined>;
+}
+/**
+ * Assemble a `UiResourceReader` from a host-supplied `resources/read`
+ * transport. The returned reader resolves only the mountable arms — a read
+ * either yields mount material or the honest placeholder, never another
+ * locator.
+ */
+export declare function createMcpUiResourceReader(deps: CreateMcpUiResourceReaderDeps): (resourceUri: string) => Promise<ResolvedViewMount | undefined>;
+//# sourceMappingURL=reader.d.ts.map

package/dist/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAE3F;AAED,oFAAoF;AACpF,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;CAC3E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,6BAA6B,GAClC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAsBjE"}

package/dist/reader.js

@@ -0,0 +1,45 @@
+/**
+ * Phase-1 sandbox-trust channel resolution (conformance map, retirement
+ * step 3): a `ui://ggui/…` locator mounts through the ggui-CSP host page
+ * (`"ggui"` — the shell boots ggui's runtime bundle and opens its WSS),
+ * anything else through the self-only page (`"inline"` — arbitrary tenant
+ * HTML). Retired when servers declare runtime/ws origins per resource
+ * (`_meta.ui.csp` on the read result); until then the uri prefix is the only
+ * signal a host has BEFORE fetching mount material.
+ */
+export function uiResourceChannel(resourceUri) {
+    return resourceUri.startsWith("ui://ggui/") ? "ggui" : "inline";
+}
+/**
+ * Assemble a `UiResourceReader` from a host-supplied `resources/read`
+ * transport. The returned reader resolves only the mountable arms — a read
+ * either yields mount material or the honest placeholder, never another
+ * locator.
+ */
+export function createMcpUiResourceReader(deps) {
+    return async (resourceUri) => {
+        let entry;
+        try {
+            entry = await deps.readResource(resourceUri);
+        }
+        catch {
+            return undefined; // transport failure == deny == miss → placeholder
+        }
+        if (!entry)
+            return undefined;
+        // Runtime re-narrowing, not trust in the annotation: transports are
+        // host-supplied and may be plain JS. Same field rules as `asResourcePayload`,
+        // applied to the typed entry (which may carry extra wire fields — dropped).
+        if (typeof entry.uri !== "string")
+            return undefined;
+        if (typeof entry.text !== "string" && typeof entry.blob !== "string")
+            return undefined;
+        const resource = {
+            uri: entry.uri,
+            ...(typeof entry.mimeType === "string" ? { mimeType: entry.mimeType } : {}),
+            ...(typeof entry.text === "string" ? { text: entry.text } : {}),
+            ...(typeof entry.blob === "string" ? { blob: entry.blob } : {}),
+        };
+        return { channel: uiResourceChannel(resourceUri), resource };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The MCP Apps (SEP-1865) Host role for guuey's chat surfaces — view-mount narrowing across UI channels, ui:// locator rehydration by resources/read, and the sandbox-trust channel contract. Vendor-neutral: any spec-following MCP App mounts through it.",
   "license": "MIT",
   "type": "module",

package/src/card-mount.ts

@@ -63,17 +63,25 @@ export type ViewMountChannel = "inline" | "ggui" | "locator";
  * + its tool result — see the conformance map.) Until a reader is wired, the honest render
  * is the host's own placeholder, never a stale mount.
  */
-export type ViewMount =
-  | {
-      channel: "inline" | "ggui";
-      /** The payload an mcp-ui host mounts, identical in shape for both channels. */
-      resource: McpUiResourcePayload;
-    }
-  | {
-      channel: "locator";
-      /** The persisted `uiData.resourceUri` (`ui://` scheme) to re-fetch. */
-      resourceUri: string;
-    };
+export type ViewMount = ResolvedViewMount | LocatorViewMount;
+
+/**
+ * A view with mount material in hand — the arms a host can render directly,
+ * and the ONLY arms a `UiResourceReader` resolves (guuey#127): a read either
+ * yields mount material or the honest placeholder, never another locator.
+ */
+export interface ResolvedViewMount {
+  channel: "inline" | "ggui";
+  /** The payload an mcp-ui host mounts, identical in shape for both channels. */
+  resource: McpUiResourcePayload;
+}
+
+/** The durable-identity arm: no mount material, only the uri to re-fetch. */
+export interface LocatorViewMount {
+  channel: "locator";
+  /** The persisted `uiData.resourceUri` (`ui://` scheme) to re-fetch. */
+  resourceUri: string;
+}
 
 /**
  * Resolves a `"locator"` mount by a fresh `resources/read` of the uri over

package/src/index.ts

@@ -30,7 +30,15 @@ export {
 export {
   snapshotViewMount,
   toolResultViewMount,
+  type LocatorViewMount,
+  type ResolvedViewMount,
   type UiResourceReader,
   type ViewMount,
   type ViewMountChannel,
 } from "./card-mount.js";
+export {
+  createMcpUiResourceReader,
+  uiResourceChannel,
+  type CreateMcpUiResourceReaderDeps,
+  type McpResourceReadResult,
+} from "./reader.js";

package/src/reader.ts

@@ -0,0 +1,98 @@
+/**
+ * The generic SEP-1865 locator reader (guuey#127): resolve a persisted
+ * `ui://` locator ({@link LocatorViewMount}) into a mountable
+ * {@link ResolvedViewMount} by ONE fresh `resources/read` over a transport
+ * the HOST supplies.
+ *
+ * The transport is a structural callable — deliberately no
+ * `@modelcontextprotocol/sdk` dependency — because hosts hold wildly
+ * different connections: a raw MCP client (ggui's `with-guuey-web` sample
+ * keeps one for guest `tools/call` relay), an authenticated platform proxy
+ * (`@guuey/agent-client`'s `createUiResourceReader` is exactly this assembly
+ * over guuey's `GET /v1/threads/:threadId/ui-resource` route), or anything
+ * else that can perform one read. The host adapts whatever client it holds.
+ *
+ * Trust rules, identical to the platform reader and now in ONE place:
+ *
+ *  - a transport deny, a miss, and a thrown transport error are all
+ *    `undefined` → the host renders its placeholder, never an error surface
+ *    (deny == miss — no oracle for which locators resolve);
+ *  - enforcement (user-ownership, tenancy, credential handling) belongs
+ *    INSIDE the transport, before any bytes come back — this assembly never
+ *    sees a credential;
+ *  - the sandbox-trust channel derives from the REQUESTED locator uri, never
+ *    from the response — a server answering with a foreign `ui://ggui/…` uri
+ *    must not steer its HTML into the ggui-CSP host page.
+ */
+import type { McpUiResourcePayload } from "./block-ui.js";
+import type { ResolvedViewMount, ViewMountChannel } from "./card-mount.js";
+
+/**
+ * One `resources/read` `contents[]` entry, structurally (SEP-1865). Kept a
+ * separate type from {@link McpUiResourcePayload} even though the shapes
+ * coincide today: this is the UNVALIDATED wire-side entry a transport hands
+ * over (phase 2 grows `_meta` here — per-resource declared CSP, conformance
+ * map step 3), while the payload is the narrowed thing a host mounts.
+ */
+export interface McpResourceReadResult {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  /** Base64 payload arm — hosts decode via {@link resourceHtml}. */
+  blob?: string;
+}
+
+/**
+ * Phase-1 sandbox-trust channel resolution (conformance map, retirement
+ * step 3): a `ui://ggui/…` locator mounts through the ggui-CSP host page
+ * (`"ggui"` — the shell boots ggui's runtime bundle and opens its WSS),
+ * anything else through the self-only page (`"inline"` — arbitrary tenant
+ * HTML). Retired when servers declare runtime/ws origins per resource
+ * (`_meta.ui.csp` on the read result); until then the uri prefix is the only
+ * signal a host has BEFORE fetching mount material.
+ */
+export function uiResourceChannel(resourceUri: string): Exclude<ViewMountChannel, "locator"> {
+  return resourceUri.startsWith("ui://ggui/") ? "ggui" : "inline";
+}
+
+/** The host-supplied transport {@link createMcpUiResourceReader} assembles over. */
+export interface CreateMcpUiResourceReaderDeps {
+  /**
+   * One `resources/read` of `uri` on the host's own MCP connection (or an
+   * equivalent authenticated proxy), returning the first `contents[]` entry —
+   * or `undefined` when the read yields none. Throwing is treated as a miss.
+   */
+  readResource: (uri: string) => Promise<McpResourceReadResult | undefined>;
+}
+
+/**
+ * Assemble a `UiResourceReader` from a host-supplied `resources/read`
+ * transport. The returned reader resolves only the mountable arms — a read
+ * either yields mount material or the honest placeholder, never another
+ * locator.
+ */
+export function createMcpUiResourceReader(
+  deps: CreateMcpUiResourceReaderDeps,
+): (resourceUri: string) => Promise<ResolvedViewMount | undefined> {
+  return async (resourceUri) => {
+    let entry: McpResourceReadResult | undefined;
+    try {
+      entry = await deps.readResource(resourceUri);
+    } catch {
+      return undefined; // transport failure == deny == miss → placeholder
+    }
+    if (!entry) return undefined;
+    // Runtime re-narrowing, not trust in the annotation: transports are
+    // host-supplied and may be plain JS. Same field rules as `asResourcePayload`,
+    // applied to the typed entry (which may carry extra wire fields — dropped).
+    if (typeof entry.uri !== "string") return undefined;
+    if (typeof entry.text !== "string" && typeof entry.blob !== "string") return undefined;
+    const resource: McpUiResourcePayload = {
+      uri: entry.uri,
+      ...(typeof entry.mimeType === "string" ? { mimeType: entry.mimeType } : {}),
+      ...(typeof entry.text === "string" ? { text: entry.text } : {}),
+      ...(typeof entry.blob === "string" ? { blob: entry.blob } : {}),
+    };
+    return { channel: uiResourceChannel(resourceUri), resource };
+  };
+}