@guuey/mcp-apps-host 0.28.1 → 0.30.0

package/dist/action.d.ts

@@ -61,13 +61,42 @@ export type McpToolCallResult = {
  *    (the wsToken TTL is 180 s; without the relay a view on SSE/polling
  *    dies at that mark — guuey#220);
  *  - `ggui_runtime_pull` — the host-relayed polling rung where the
- *    sandbox's own transports are blocked (bridge-pull, terminal rung).
+ *    sandbox's own transports are blocked (bridge-pull, terminal rung);
+ *  - `ggui_runtime_telemetry` — the card's own health events, relayed only
+ *    as the closed kind set {@link UI_TELEMETRY_KINDS}, filtered here before
+ *    the relay calls the door.
  *
- * Two of these are transport plumbing whose arguments are opaque runtime
+ * Three of these are runtime plumbing whose arguments are opaque runtime
  * state — see {@link UI_SEMANTIC_ACTION_TOOLS} for the ONLY set a host may
  * treat as "the user did something".
  */
 export declare const UI_ACTION_TOOLS: ReadonlySet<string>;
+/** The card-health telemetry tool. Never a user gesture. */
+export declare const UI_TELEMETRY_TOOL = "ggui_runtime_telemetry";
+/**
+ * What an admitted telemetry kind may carry as `detail`: nothing (`none`), or
+ * one exact, closed shape with no free text — three booleans (`boot-path`), a
+ * transport kind and a boolean (`subscribe`), or a render session id
+ * (`render-session-id`).
+ */
+export type UiTelemetryDetailRule = "none" | "boot-path" | "subscribe" | "render-session-id";
+/**
+ * The closed set of health-event kinds a card may report through the relay:
+ * event names and ggui's own ids only, no free text and no user identity.
+ * Exact strings, never a prefix. The server doors admit exactly the same set
+ * and refuse a whole call that carries anything else; this twin filters
+ * events before the door, so a conforming host never sends a refusable call.
+ */
+export declare const UI_TELEMETRY_KINDS: ReadonlyMap<string, UiTelemetryDetailRule>;
+/** The per-call event cap the doors enforce. */
+export declare const MAX_UI_TELEMETRY_EVENTS = 40;
+/**
+ * The telemetry call the host relays: the card's `sessionId` (when it is a
+ * string) and only the admitted events, oldest first, at most
+ * {@link MAX_UI_TELEMETRY_EVENTS}. Whole events are dropped, never edited.
+ * `undefined` when nothing is left to relay.
+ */
+export declare function admittedTelemetryArguments(args: McpToolStructuredContent | undefined): McpToolStructuredContent | undefined;
 /**
  * The strict subset of {@link UI_ACTION_TOOLS} that carries a USER gesture —
  * the only calls a host may project into user-facing affordances (composer

package/dist/action.d.ts.map

@@ -1 +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;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,iBAAiB,CAK7D;AAkCD;;;;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;IACtB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;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;AAKD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,uJACyG,CAAC;AAElJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAmD1D"}
+{"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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAK9C,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,mBAAmB,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAYxE,CAAC;AAEH,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAmE1C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,wBAAwB,GAAG,SAAS,GACzC,wBAAwB,GAAG,SAAS,CAatC;AAOD;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,2CACG,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,iBAAiB,CAK7D;AAkCD;;;;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;IACtB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;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;AAKD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,uJACyG,CAAC;AAElJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CA4D1D"}

package/dist/action.js

@@ -23,9 +23,12 @@
  *    (the wsToken TTL is 180 s; without the relay a view on SSE/polling
  *    dies at that mark — guuey#220);
  *  - `ggui_runtime_pull` — the host-relayed polling rung where the
- *    sandbox's own transports are blocked (bridge-pull, terminal rung).
+ *    sandbox's own transports are blocked (bridge-pull, terminal rung);
+ *  - `ggui_runtime_telemetry` — the card's own health events, relayed only
+ *    as the closed kind set {@link UI_TELEMETRY_KINDS}, filtered here before
+ *    the relay calls the door.
  *
- * Two of these are transport plumbing whose arguments are opaque runtime
+ * Three of these are runtime plumbing whose arguments are opaque runtime
  * state — see {@link UI_SEMANTIC_ACTION_TOOLS} for the ONLY set a host may
  * treat as "the user did something".
  */
@@ -33,7 +36,118 @@ export const UI_ACTION_TOOLS = new Set([
     "ggui_runtime_submit_action",
     "ggui_runtime_refresh_ws_token",
     "ggui_runtime_pull",
+    "ggui_runtime_telemetry",
 ]);
+/** The card-health telemetry tool. Never a user gesture. */
+export const UI_TELEMETRY_TOOL = "ggui_runtime_telemetry";
+/**
+ * The closed set of health-event kinds a card may report through the relay:
+ * event names and ggui's own ids only, no free text and no user identity.
+ * Exact strings, never a prefix. The server doors admit exactly the same set
+ * and refuse a whole call that carries anything else; this twin filters
+ * events before the door, so a conforming host never sends a refusable call.
+ */
+export const UI_TELEMETRY_KINDS = new Map([
+    ["boot.path", "boot-path"],
+    ["boot.static_only_no_bridge", "none"],
+    ["status.connecting", "none"],
+    ["status.reconnecting", "none"],
+    ["status.connected", "none"],
+    ["status.disconnected", "none"],
+    ["subscribe.resolved", "subscribe"],
+    ["doorbell.ring", "render-session-id"],
+]);
+/** The per-call event cap the doors enforce. */
+export const MAX_UI_TELEMETRY_EVENTS = 40;
+/** A render session id as ggui's hosted service mints it: `render_<uuid>`. */
+const RENDER_SESSION_ID_RE = /^render_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const SUBSCRIBE_TRANSPORT_KINDS = new Set(["ws", "sse", "polling"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExactlyKeys(value, keys) {
+    const own = Object.keys(value);
+    return own.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+/** The detail parsed as JSON, or `undefined` when it is not JSON (the event is then dropped). */
+function parsedJson(detail) {
+    try {
+        return JSON.parse(detail);
+    }
+    catch {
+        return undefined;
+    }
+}
+function telemetryDetailAdmitted(rule, detail) {
+    if (detail === undefined)
+        return true;
+    if (typeof detail !== "string")
+        return false;
+    switch (rule) {
+        case "none":
+            return false;
+        case "render-session-id":
+            return RENDER_SESSION_ID_RE.test(detail);
+        case "boot-path": {
+            const v = parsedJson(detail);
+            return (isPlainObject(v) &&
+                hasExactlyKeys(v, ["hasStaticContent", "hasLiveTrio", "bridgeCapable"]) &&
+                typeof v["hasStaticContent"] === "boolean" &&
+                typeof v["hasLiveTrio"] === "boolean" &&
+                typeof v["bridgeCapable"] === "boolean");
+        }
+        case "subscribe": {
+            const v = parsedJson(detail);
+            return (isPlainObject(v) &&
+                hasExactlyKeys(v, ["kind", "hasAck"]) &&
+                typeof v["kind"] === "string" &&
+                SUBSCRIBE_TRANSPORT_KINDS.has(v["kind"]) &&
+                typeof v["hasAck"] === "boolean");
+        }
+    }
+}
+/** One event the host will relay: its keys are exactly `at`, `kind` and an admitted `detail`. */
+function admittedTelemetryEvent(event) {
+    if (!isPlainObject(event))
+        return undefined;
+    if (Object.keys(event).some((k) => k !== "at" && k !== "kind" && k !== "detail"))
+        return undefined;
+    const at = event["at"];
+    if (typeof at !== "number" || !Number.isFinite(at) || at < 0)
+        return undefined;
+    const kind = event["kind"];
+    const rule = typeof kind === "string" ? UI_TELEMETRY_KINDS.get(kind) : undefined;
+    if (rule === undefined || !telemetryDetailAdmitted(rule, event["detail"]))
+        return undefined;
+    return event;
+}
+/**
+ * The telemetry call the host relays: the card's `sessionId` (when it is a
+ * string) and only the admitted events, oldest first, at most
+ * {@link MAX_UI_TELEMETRY_EVENTS}. Whole events are dropped, never edited.
+ * `undefined` when nothing is left to relay.
+ */
+export function admittedTelemetryArguments(args) {
+    if (args === undefined || !Array.isArray(args["events"]))
+        return undefined;
+    const events = [];
+    for (const event of args["events"]) {
+        const admitted = admittedTelemetryEvent(event);
+        if (admitted !== undefined)
+            events.push(admitted);
+    }
+    if (events.length === 0)
+        return undefined;
+    const sessionId = args["sessionId"];
+    return {
+        ...(typeof sessionId === "string" ? { sessionId } : {}),
+        events: events.slice(-MAX_UI_TELEMETRY_EVENTS),
+    };
+}
+/** The local answer when a telemetry call has nothing admitted to relay: ggui's own `{ok: true}` shape. */
+function telemetryNothingToRelayResult() {
+    return { content: [], structuredContent: { ok: true } };
+}
 /**
  * The strict subset of {@link UI_ACTION_TOOLS} that carries a USER gesture —
  * the only calls a host may project into user-facing affordances (composer
@@ -187,6 +301,15 @@ export function createMcpUiActionRelay(deps) {
             return unavailableToolCallResult();
         if (!request.resourceUri.startsWith("ui://"))
             return unavailableToolCallResult();
+        // The card's health events: only the admitted kinds reach the door, and a
+        // door that refuses the tool (an older server) answers in-band like any
+        // other failure. Telemetry never touches the pull circuit.
+        let callArguments = request.arguments;
+        if (request.name === UI_TELEMETRY_TOOL) {
+            callArguments = admittedTelemetryArguments(request.arguments);
+            if (callArguments === undefined)
+                return telemetryNothingToRelayResult();
+        }
         const isPull = request.name === PULL_TOOL;
         // Circuit OPEN for this locator's pull → fail-fast, never touch the door.
         if (isPull && (pullFailures.get(request.resourceUri) ?? 0) >= PULL_CIRCUIT_THRESHOLD) {
@@ -194,7 +317,7 @@ export function createMcpUiActionRelay(deps) {
         }
         let raw;
         try {
-            raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+            raw = await deps.callTool(request.resourceUri, request.name, callArguments);
         }
         catch {
             if (isPull)

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { resolveViewMount, snapshotViewMount, toolResultViewMount, type LocatorV
 export { ACTION_STAGED_MSG, isStageableAction, stagedActionText, withActionStaging, type ActionStaging, } from "./action-staging.js";
 export { createMcpUiResourceReader, declaredResourceCsp, uiResourceChannel, type CreateMcpUiResourceReaderDeps, type McpResourceReadResult, } from "./reader.js";
 export type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps";
-export { asToolCallResult, createMcpUiActionRelay, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, UI_SEMANTIC_ACTION_TOOLS, type CreateMcpUiActionRelayDeps, type McpToolCallContent, type McpToolCallResult, type McpToolStructuredContent, type UiActionRequest, } from "./action.js";
+export { admittedTelemetryArguments, asToolCallResult, createMcpUiActionRelay, MAX_UI_TELEMETRY_EVENTS, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, UI_SEMANTIC_ACTION_TOOLS, UI_TELEMETRY_KINDS, UI_TELEMETRY_TOOL, type CreateMcpUiActionRelayDeps, type UiTelemetryDetailRule, type McpToolCallContent, type McpToolCallResult, type McpToolStructuredContent, type UiActionRequest, } from "./action.js";
 export { initializeResult, initialViewHostState, resourceReadResponse, RESOURCES_READ_METHOD, teardownMessage, toolCallResponse, TOOLS_CALL_METHOD, viewHostElapsed, viewHostReceive, diagnoseCspViolation, type CspViolationLike, type ViewCspDiagnosis, type ViewCspOrigins, type ViewHostBehavior, type ViewHostEffect, type ViewHostOutbound, type ViewHostPhase, type ViewHostInfo, type ViewHostState, type ViewHostTransition, type ViewRequestId, } from "./view-host-protocol.js";
 export { attachViewHost, viewDocumentHtml, MESSAGE_ANSWER_CAP_MS, type AttachViewHostConfig, type UserMessageDelivery, type ViewCspEvents, type ViewFrameLike, type ViewHostEvents, } from "./view-host.js";
 export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, type SandboxPageDeliveryConfig, } from "./sandbox-page.js";

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,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC;AAIrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,EACzB,eAAe,EACf,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,uBAAuB,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIzF,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,2BAA2B,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,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC;AAIrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,EAC7B,KAAK,yBAAyB,GAC/B,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,uBAAuB,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAIzF,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,WAAW,GACjB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -7,7 +7,7 @@ export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourc
 export { resolveViewMount, snapshotViewMount, toolResultViewMount, } from "./card-mount.js";
 export { ACTION_STAGED_MSG, isStageableAction, stagedActionText, withActionStaging, } from "./action-staging.js";
 export { createMcpUiResourceReader, declaredResourceCsp, uiResourceChannel, } from "./reader.js";
-export { asToolCallResult, createMcpUiActionRelay, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, UI_SEMANTIC_ACTION_TOOLS, } from "./action.js";
+export { admittedTelemetryArguments, asToolCallResult, createMcpUiActionRelay, MAX_UI_TELEMETRY_EVENTS, unavailableToolCallResult, UI_ACTION_TOOLS, UI_ACTION_UNAVAILABLE_TEXT, UI_SEMANTIC_ACTION_TOOLS, UI_TELEMETRY_KINDS, UI_TELEMETRY_TOOL, } from "./action.js";
 export { initializeResult, initialViewHostState, resourceReadResponse, RESOURCES_READ_METHOD, teardownMessage, toolCallResponse, TOOLS_CALL_METHOD, viewHostElapsed, viewHostReceive, diagnoseCspViolation, } from "./view-host-protocol.js";
 export { attachViewHost, viewDocumentHtml, MESSAGE_ANSWER_CAP_MS, } from "./view-host.js";
 export { attachSandboxPageDelivery, isSandboxProxyReady, SANDBOX_PROXY_READY_METHOD, SANDBOX_RESOURCE_READY_METHOD, } from "./sandbox-page.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.28.1",
+  "version": "0.30.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",
@@ -33,9 +33,9 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/protocol": "0.23.0",
+    "@ggui-ai/protocol": "0.24.0",
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@silverprotocol/core": "0.7.2"
+    "@silverprotocol/core": "0.11.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/action.ts

@@ -57,9 +57,12 @@ export type McpToolCallResult = {
  *    (the wsToken TTL is 180 s; without the relay a view on SSE/polling
  *    dies at that mark — guuey#220);
  *  - `ggui_runtime_pull` — the host-relayed polling rung where the
- *    sandbox's own transports are blocked (bridge-pull, terminal rung).
+ *    sandbox's own transports are blocked (bridge-pull, terminal rung);
+ *  - `ggui_runtime_telemetry` — the card's own health events, relayed only
+ *    as the closed kind set {@link UI_TELEMETRY_KINDS}, filtered here before
+ *    the relay calls the door.
  *
- * Two of these are transport plumbing whose arguments are opaque runtime
+ * Three of these are runtime plumbing whose arguments are opaque runtime
  * state — see {@link UI_SEMANTIC_ACTION_TOOLS} for the ONLY set a host may
  * treat as "the user did something".
  */
@@ -67,8 +70,137 @@ export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
   "ggui_runtime_submit_action",
   "ggui_runtime_refresh_ws_token",
   "ggui_runtime_pull",
+  "ggui_runtime_telemetry",
 ]);
 
+/** The card-health telemetry tool. Never a user gesture. */
+export const UI_TELEMETRY_TOOL = "ggui_runtime_telemetry";
+
+/**
+ * What an admitted telemetry kind may carry as `detail`: nothing (`none`), or
+ * one exact, closed shape with no free text — three booleans (`boot-path`), a
+ * transport kind and a boolean (`subscribe`), or a render session id
+ * (`render-session-id`).
+ */
+export type UiTelemetryDetailRule = "none" | "boot-path" | "subscribe" | "render-session-id";
+
+/**
+ * The closed set of health-event kinds a card may report through the relay:
+ * event names and ggui's own ids only, no free text and no user identity.
+ * Exact strings, never a prefix. The server doors admit exactly the same set
+ * and refuse a whole call that carries anything else; this twin filters
+ * events before the door, so a conforming host never sends a refusable call.
+ */
+export const UI_TELEMETRY_KINDS: ReadonlyMap<string, UiTelemetryDetailRule> = new Map<
+  string,
+  UiTelemetryDetailRule
+>([
+  ["boot.path", "boot-path"],
+  ["boot.static_only_no_bridge", "none"],
+  ["status.connecting", "none"],
+  ["status.reconnecting", "none"],
+  ["status.connected", "none"],
+  ["status.disconnected", "none"],
+  ["subscribe.resolved", "subscribe"],
+  ["doorbell.ring", "render-session-id"],
+]);
+
+/** The per-call event cap the doors enforce. */
+export const MAX_UI_TELEMETRY_EVENTS = 40;
+
+/** A render session id as ggui's hosted service mints it: `render_<uuid>`. */
+const RENDER_SESSION_ID_RE = /^render_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const SUBSCRIBE_TRANSPORT_KINDS: ReadonlySet<string> = new Set(["ws", "sse", "polling"]);
+
+function isPlainObject(value: unknown): value is { [key: string]: unknown } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactlyKeys(value: { [key: string]: unknown }, keys: readonly string[]): boolean {
+  const own = Object.keys(value);
+  return own.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(value, k));
+}
+
+/** The detail parsed as JSON, or `undefined` when it is not JSON (the event is then dropped). */
+function parsedJson(detail: string): unknown {
+  try {
+    return JSON.parse(detail);
+  } catch {
+    return undefined;
+  }
+}
+
+function telemetryDetailAdmitted(rule: UiTelemetryDetailRule, detail: unknown): boolean {
+  if (detail === undefined) return true;
+  if (typeof detail !== "string") return false;
+  switch (rule) {
+    case "none":
+      return false;
+    case "render-session-id":
+      return RENDER_SESSION_ID_RE.test(detail);
+    case "boot-path": {
+      const v = parsedJson(detail);
+      return (
+        isPlainObject(v) &&
+        hasExactlyKeys(v, ["hasStaticContent", "hasLiveTrio", "bridgeCapable"]) &&
+        typeof v["hasStaticContent"] === "boolean" &&
+        typeof v["hasLiveTrio"] === "boolean" &&
+        typeof v["bridgeCapable"] === "boolean"
+      );
+    }
+    case "subscribe": {
+      const v = parsedJson(detail);
+      return (
+        isPlainObject(v) &&
+        hasExactlyKeys(v, ["kind", "hasAck"]) &&
+        typeof v["kind"] === "string" &&
+        SUBSCRIBE_TRANSPORT_KINDS.has(v["kind"]) &&
+        typeof v["hasAck"] === "boolean"
+      );
+    }
+  }
+}
+
+/** One event the host will relay: its keys are exactly `at`, `kind` and an admitted `detail`. */
+function admittedTelemetryEvent(event: unknown): McpToolStructuredContent | undefined {
+  if (!isPlainObject(event)) return undefined;
+  if (Object.keys(event).some((k) => k !== "at" && k !== "kind" && k !== "detail")) return undefined;
+  const at = event["at"];
+  if (typeof at !== "number" || !Number.isFinite(at) || at < 0) return undefined;
+  const kind = event["kind"];
+  const rule = typeof kind === "string" ? UI_TELEMETRY_KINDS.get(kind) : undefined;
+  if (rule === undefined || !telemetryDetailAdmitted(rule, event["detail"])) return undefined;
+  return event;
+}
+
+/**
+ * The telemetry call the host relays: the card's `sessionId` (when it is a
+ * string) and only the admitted events, oldest first, at most
+ * {@link MAX_UI_TELEMETRY_EVENTS}. Whole events are dropped, never edited.
+ * `undefined` when nothing is left to relay.
+ */
+export function admittedTelemetryArguments(
+  args: McpToolStructuredContent | undefined,
+): McpToolStructuredContent | undefined {
+  if (args === undefined || !Array.isArray(args["events"])) return undefined;
+  const events: McpToolStructuredContent[] = [];
+  for (const event of args["events"]) {
+    const admitted = admittedTelemetryEvent(event);
+    if (admitted !== undefined) events.push(admitted);
+  }
+  if (events.length === 0) return undefined;
+  const sessionId = args["sessionId"];
+  return {
+    ...(typeof sessionId === "string" ? { sessionId } : {}),
+    events: events.slice(-MAX_UI_TELEMETRY_EVENTS),
+  };
+}
+
+/** The local answer when a telemetry call has nothing admitted to relay: ggui's own `{ok: true}` shape. */
+function telemetryNothingToRelayResult(): McpToolCallResult {
+  return { content: [], structuredContent: { ok: true } };
+}
+
 /**
  * The strict subset of {@link UI_ACTION_TOOLS} that carries a USER gesture —
  * the only calls a host may project into user-facing affordances (composer
@@ -265,6 +397,15 @@ export function createMcpUiActionRelay(
     if (!UI_ACTION_TOOLS.has(request.name)) return unavailableToolCallResult();
     if (!request.resourceUri.startsWith("ui://")) return unavailableToolCallResult();
 
+    // The card's health events: only the admitted kinds reach the door, and a
+    // door that refuses the tool (an older server) answers in-band like any
+    // other failure. Telemetry never touches the pull circuit.
+    let callArguments = request.arguments;
+    if (request.name === UI_TELEMETRY_TOOL) {
+      callArguments = admittedTelemetryArguments(request.arguments);
+      if (callArguments === undefined) return telemetryNothingToRelayResult();
+    }
+
     const isPull = request.name === PULL_TOOL;
     // Circuit OPEN for this locator's pull → fail-fast, never touch the door.
     if (isPull && (pullFailures.get(request.resourceUri) ?? 0) >= PULL_CIRCUIT_THRESHOLD) {
@@ -273,7 +414,7 @@ export function createMcpUiActionRelay(
 
     let raw: unknown;
     try {
-      raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
+      raw = await deps.callTool(request.resourceUri, request.name, callArguments);
     } catch {
       if (isPull) recordPull(request.resourceUri, true); // transport failure == unavailable
       return unavailableToolCallResult(); // in-band

package/src/index.ts

@@ -46,13 +46,18 @@ export {
 // `ViewCspOrigins`, re-exported under its spec name for mount consumers.
 export type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps";
 export {
+  admittedTelemetryArguments,
   asToolCallResult,
   createMcpUiActionRelay,
+  MAX_UI_TELEMETRY_EVENTS,
   unavailableToolCallResult,
   UI_ACTION_TOOLS,
   UI_ACTION_UNAVAILABLE_TEXT,
   UI_SEMANTIC_ACTION_TOOLS,
+  UI_TELEMETRY_KINDS,
+  UI_TELEMETRY_TOOL,
   type CreateMcpUiActionRelayDeps,
+  type UiTelemetryDetailRule,
   type McpToolCallContent,
   type McpToolCallResult,
   type McpToolStructuredContent,