@guuey/mcp-apps-host 0.3.0 → 0.4.0

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/action.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The Host role's ACTION side (guuey#158) — the `tools/call` sibling of
+ * `reader.ts`. A mounted card's sandbox posts a runtime action to the host
+ * (SEP-1865 / ggui's relay-host contract); the host relays it over an
+ * AUTHENTICATED transport it owns, and hands the result back in-band. Two
+ * invariants mirror the reader:
+ *
+ *  - the relay NEVER throws into the sandbox bridge: allowlist miss,
+ *    transport failure, and un-narrowable answers all collapse to an
+ *    in-band `isError` result the card can display;
+ *  - runtime re-narrowing, not trust: transports are host-supplied and the
+ *    upstream answer is wire data — every content arm is re-checked before
+ *    it crosses into the sandbox.
+ */
+/** The wire arms a relay hands back to the sandbox — re-narrowed, never trusted. */
+export type McpToolCallContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    });
+};
+/**
+ * `structuredContent` is protocol-open by design (the MCP spec types it as
+ * an arbitrary JSON object) — the index signature is the honest wire type,
+ * not an erasure of a known shape.
+ */
+export type McpToolStructuredContent = {
+    [key: string]: unknown;
+};
+/**
+ * The SEP-1865 CallToolResult surface a host hands back to the sandbox.
+ * A `type` alias, deliberately: the MCP SDK's own result types carry Zod
+ * passthrough index signatures, and only type aliases (never interfaces)
+ * get the implicit index signature that makes this assignable to them.
+ */
+export type McpToolCallResult = {
+    content: McpToolCallContent[];
+    isError?: boolean;
+    structuredContent?: McpToolStructuredContent;
+};
+/**
+ * The runtime-action tools a card sandbox may relay — the client-side twin
+ * of the server allowlist (defense in depth: the proxy enforces it again).
+ */
+export declare const UI_ACTION_TOOLS: ReadonlySet<string>;
+/** The in-band answer for anything the relay cannot (or will not) do. */
+export declare const UI_ACTION_UNAVAILABLE_TEXT = "This action isn't available right now.";
+/**
+ * Narrow an untrusted `tools/call` answer to the arms the sandbox may see.
+ * Unknown content arms are DROPPED (never forwarded opaque); a value that
+ * is not result-shaped at all is `undefined` (the relay answers in-band).
+ */
+export declare function asToolCallResult(value: unknown): McpToolCallResult | undefined;
+/** The host-supplied transport {@link createMcpUiActionRelay} assembles over. */
+export interface CreateMcpUiActionRelayDeps {
+    /**
+     * One `tools/call` bound to the mounted card's locator `uri` over the
+     * host's authenticated channel. Returns the raw result (narrowed here),
+     * or `undefined` when the upstream denied/lost the session. Throwing is
+     * treated as unavailable.
+     */
+    callTool: (uri: string, name: string, args: McpToolStructuredContent | undefined) => Promise<unknown>;
+}
+/** The request shape a mounted card's `onCallTool` bridge produces. */
+export interface UiActionRequest {
+    /** The mounted card's persisted `ui://` locator — the action's scope. */
+    resourceUri: string;
+    name: string;
+    arguments?: McpToolStructuredContent;
+}
+/**
+ * Assemble the sandbox-facing action relay from a host transport. The
+ * returned function is shaped for an `onCallTool` bridge: it always
+ * resolves (never rejects), answering in-band.
+ */
+export declare function createMcpUiActionRelay(deps: CreateMcpUiActionRelayDeps): (request: UiActionRequest) => Promise<McpToolCallResult>;
+//# sourceMappingURL=action.d.ts.map

package/dist/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAC3C;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CACnB,CAAC;CACH,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAE9C,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAyC3C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAgB9E;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,QAAQ,EAAE,CACR,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,wBAAwB,GAAG,SAAS,KACvC,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAa1D"}

package/dist/action.js

@@ -0,0 +1,106 @@
+/**
+ * The Host role's ACTION side (guuey#158) — the `tools/call` sibling of
+ * `reader.ts`. A mounted card's sandbox posts a runtime action to the host
+ * (SEP-1865 / ggui's relay-host contract); the host relays it over an
+ * AUTHENTICATED transport it owns, and hands the result back in-band. Two
+ * invariants mirror the reader:
+ *
+ *  - the relay NEVER throws into the sandbox bridge: allowlist miss,
+ *    transport failure, and un-narrowable answers all collapse to an
+ *    in-band `isError` result the card can display;
+ *  - runtime re-narrowing, not trust: transports are host-supplied and the
+ *    upstream answer is wire data — every content arm is re-checked before
+ *    it crosses into the sandbox.
+ */
+/**
+ * The runtime-action tools a card sandbox may relay — the client-side twin
+ * of the server allowlist (defense in depth: the proxy enforces it again).
+ */
+export const UI_ACTION_TOOLS = new Set([
+    "ggui_runtime_submit_action",
+]);
+/** The in-band answer for anything the relay cannot (or will not) do. */
+export const UI_ACTION_UNAVAILABLE_TEXT = "This action isn't available right now.";
+function unavailable() {
+    return {
+        content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
+        isError: true,
+    };
+}
+function isJsonObjectLike(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asContentArm(value) {
+    if (!isJsonObjectLike(value))
+        return undefined;
+    const type = value["type"];
+    if (type === "text" && typeof value["text"] === "string") {
+        return { type: "text", text: value["text"] };
+    }
+    if (type === "image" &&
+        typeof value["data"] === "string" &&
+        typeof value["mimeType"] === "string") {
+        return { type: "image", data: value["data"], mimeType: value["mimeType"] };
+    }
+    if (type === "resource" && isJsonObjectLike(value["resource"])) {
+        const res = value["resource"];
+        if (typeof res["uri"] !== "string")
+            return undefined;
+        const mimeType = typeof res["mimeType"] === "string" ? { mimeType: res["mimeType"] } : {};
+        if (typeof res["text"] === "string") {
+            return { type: "resource", resource: { uri: res["uri"], ...mimeType, text: res["text"] } };
+        }
+        if (typeof res["blob"] === "string") {
+            return { type: "resource", resource: { uri: res["uri"], ...mimeType, blob: res["blob"] } };
+        }
+    }
+    return undefined;
+}
+/**
+ * Narrow an untrusted `tools/call` answer to the arms the sandbox may see.
+ * Unknown content arms are DROPPED (never forwarded opaque); a value that
+ * is not result-shaped at all is `undefined` (the relay answers in-band).
+ */
+export function asToolCallResult(value) {
+    if (!isJsonObjectLike(value))
+        return undefined;
+    const rawContent = value["content"];
+    if (!Array.isArray(rawContent))
+        return undefined;
+    const content = [];
+    for (const entry of rawContent) {
+        const arm = asContentArm(entry);
+        if (arm)
+            content.push(arm);
+    }
+    return {
+        content,
+        ...(value["isError"] === true ? { isError: true } : {}),
+        ...(isJsonObjectLike(value["structuredContent"])
+            ? { structuredContent: value["structuredContent"] }
+            : {}),
+    };
+}
+/**
+ * Assemble the sandbox-facing action relay from a host transport. The
+ * returned function is shaped for an `onCallTool` bridge: it always
+ * resolves (never rejects), answering in-band.
+ */
+export function createMcpUiActionRelay(deps) {
+    return async (request) => {
+        if (!UI_ACTION_TOOLS.has(request.name))
+            return unavailable();
+        if (!request.resourceUri.startsWith("ui://"))
+            return unavailable();
+        let raw;
+        try {
+            raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+        }
+        catch {
+            return unavailable(); // transport failure == unavailable, in-band
+        }
+        if (raw === undefined)
+            return unavailable();
+        return asToolCallResult(raw) ?? unavailable();
+    };
+}

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,7 @@
  */
 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";
+export { asToolCallResult, createMcpUiActionRelay, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, type CreateMcpUiActionRelayDeps, type McpToolCallContent, type McpToolCallResult, type McpToolStructuredContent, type UiActionRequest, } from "./action.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;AACrB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -6,3 +6,5 @@
 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";
+export { asToolCallResult, createMcpUiActionRelay, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, } from "./action.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.4.0",
   "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",
@@ -27,7 +27,7 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/protocol": "0.6.3",
+    "@ggui-ai/protocol": "0.9.0",
     "@silverprotocol/core": "0.4.1"
   },
   "devDependencies": {
@@ -52,10 +52,10 @@
     "url": "git+https://github.com/withguuey/guuey-sdks.git",
     "directory": "packages/mcp-apps-host"
   },
-  "homepage": "https://guuey.com",
   "bugs": {
-    "url": "https://github.com/loqu-co/guuey/issues"
+    "url": "https://github.com/withguuey/guuey-sdks/issues"
   },
+  "homepage": "https://guuey.com",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",

package/src/action.ts

@@ -0,0 +1,166 @@
+/**
+ * The Host role's ACTION side (guuey#158) — the `tools/call` sibling of
+ * `reader.ts`. A mounted card's sandbox posts a runtime action to the host
+ * (SEP-1865 / ggui's relay-host contract); the host relays it over an
+ * AUTHENTICATED transport it owns, and hands the result back in-band. Two
+ * invariants mirror the reader:
+ *
+ *  - the relay NEVER throws into the sandbox bridge: allowlist miss,
+ *    transport failure, and un-narrowable answers all collapse to an
+ *    in-band `isError` result the card can display;
+ *  - runtime re-narrowing, not trust: transports are host-supplied and the
+ *    upstream answer is wire data — every content arm is re-checked before
+ *    it crosses into the sandbox.
+ */
+
+/** The wire arms a relay hands back to the sandbox — re-narrowed, never trusted. */
+export type McpToolCallContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | {
+      type: "resource";
+      resource: { uri: string; mimeType?: string } & (
+        | { text: string }
+        | { blob: string }
+      );
+    };
+
+/**
+ * `structuredContent` is protocol-open by design (the MCP spec types it as
+ * an arbitrary JSON object) — the index signature is the honest wire type,
+ * not an erasure of a known shape.
+ */
+export type McpToolStructuredContent = {
+  [key: string]: unknown;
+};
+
+/**
+ * The SEP-1865 CallToolResult surface a host hands back to the sandbox.
+ * A `type` alias, deliberately: the MCP SDK's own result types carry Zod
+ * passthrough index signatures, and only type aliases (never interfaces)
+ * get the implicit index signature that makes this assignable to them.
+ */
+export type McpToolCallResult = {
+  content: McpToolCallContent[];
+  isError?: boolean;
+  structuredContent?: McpToolStructuredContent;
+};
+
+/**
+ * The runtime-action tools a card sandbox may relay — the client-side twin
+ * of the server allowlist (defense in depth: the proxy enforces it again).
+ */
+export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
+  "ggui_runtime_submit_action",
+]);
+
+/** The in-band answer for anything the relay cannot (or will not) do. */
+export const UI_ACTION_UNAVAILABLE_TEXT =
+  "This action isn't available right now.";
+
+function unavailable(): McpToolCallResult {
+  return {
+    content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
+    isError: true,
+  };
+}
+
+function isJsonObjectLike(value: unknown): value is McpToolStructuredContent {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asContentArm(value: unknown): McpToolCallContent | undefined {
+  if (!isJsonObjectLike(value)) return undefined;
+  const type = value["type"];
+  if (type === "text" && typeof value["text"] === "string") {
+    return { type: "text", text: value["text"] };
+  }
+  if (
+    type === "image" &&
+    typeof value["data"] === "string" &&
+    typeof value["mimeType"] === "string"
+  ) {
+    return { type: "image", data: value["data"], mimeType: value["mimeType"] };
+  }
+  if (type === "resource" && isJsonObjectLike(value["resource"])) {
+    const res = value["resource"];
+    if (typeof res["uri"] !== "string") return undefined;
+    const mimeType =
+      typeof res["mimeType"] === "string" ? { mimeType: res["mimeType"] } : {};
+    if (typeof res["text"] === "string") {
+      return { type: "resource", resource: { uri: res["uri"], ...mimeType, text: res["text"] } };
+    }
+    if (typeof res["blob"] === "string") {
+      return { type: "resource", resource: { uri: res["uri"], ...mimeType, blob: res["blob"] } };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Narrow an untrusted `tools/call` answer to the arms the sandbox may see.
+ * Unknown content arms are DROPPED (never forwarded opaque); a value that
+ * is not result-shaped at all is `undefined` (the relay answers in-band).
+ */
+export function asToolCallResult(value: unknown): McpToolCallResult | undefined {
+  if (!isJsonObjectLike(value)) return undefined;
+  const rawContent = value["content"];
+  if (!Array.isArray(rawContent)) return undefined;
+  const content: McpToolCallContent[] = [];
+  for (const entry of rawContent) {
+    const arm = asContentArm(entry);
+    if (arm) content.push(arm);
+  }
+  return {
+    content,
+    ...(value["isError"] === true ? { isError: true } : {}),
+    ...(isJsonObjectLike(value["structuredContent"])
+      ? { structuredContent: value["structuredContent"] }
+      : {}),
+  };
+}
+
+/** The host-supplied transport {@link createMcpUiActionRelay} assembles over. */
+export interface CreateMcpUiActionRelayDeps {
+  /**
+   * One `tools/call` bound to the mounted card's locator `uri` over the
+   * host's authenticated channel. Returns the raw result (narrowed here),
+   * or `undefined` when the upstream denied/lost the session. Throwing is
+   * treated as unavailable.
+   */
+  callTool: (
+    uri: string,
+    name: string,
+    args: McpToolStructuredContent | undefined,
+  ) => Promise<unknown>;
+}
+
+/** The request shape a mounted card's `onCallTool` bridge produces. */
+export interface UiActionRequest {
+  /** The mounted card's persisted `ui://` locator — the action's scope. */
+  resourceUri: string;
+  name: string;
+  arguments?: McpToolStructuredContent;
+}
+
+/**
+ * Assemble the sandbox-facing action relay from a host transport. The
+ * returned function is shaped for an `onCallTool` bridge: it always
+ * resolves (never rejects), answering in-band.
+ */
+export function createMcpUiActionRelay(
+  deps: CreateMcpUiActionRelayDeps,
+): (request: UiActionRequest) => Promise<McpToolCallResult> {
+  return async (request) => {
+    if (!UI_ACTION_TOOLS.has(request.name)) return unavailable();
+    if (!request.resourceUri.startsWith("ui://")) return unavailable();
+    let raw: unknown;
+    try {
+      raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+    } catch {
+      return unavailable(); // transport failure == unavailable, in-band
+    }
+    if (raw === undefined) return unavailable();
+    return asToolCallResult(raw) ?? unavailable();
+  };
+}

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,26 @@ 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";
+export {
+  asToolCallResult,
+  createMcpUiActionRelay,
+  UI_ACTION_TOOLS,
+  UI_ACTION_UNAVAILABLE_TEXT,
+  type CreateMcpUiActionRelayDeps,
+  type McpToolCallContent,
+  type McpToolCallResult,
+  type McpToolStructuredContent,
+  type UiActionRequest,
+} from "./action.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 };
+  };
+}