@guuey/mcp-apps-host 0.3.1 → 0.4.0

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

@@ -7,4 +7,5 @@ export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourc
 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 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,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"}
+{"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

@@ -7,3 +7,4 @@ export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourc
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.3.1",
+  "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/index.ts

@@ -42,3 +42,14 @@ export {
   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";