@guuey/mcp-apps-host 0.12.2 → 0.14.0

package/dist/action-staging.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The post-turn action-STAGING policy (guuey#356 — lifted VERBATIM from the
+ * widget's #198/#215/#218 civilization so every mount shares ONE copy).
+ *
+ * The beat it solves: after a turn completes there is no live turn to feed
+ * a card action into — relaying would only surface the "agent not
+ * listening" degradation at exactly the moment the agent's own copy
+ * invited the tap. Instead, an ALLOWLISTED semantic action with an honest
+ * text form stages a human-readable projection into the composer: one
+ * Enter sends it as the next turn. Everything else — internal transport
+ * rungs, foreign plumbing, shapes with no honest projection — rides the
+ * exact pre-#198 relay/stub path, so fallback chains keep receiving the
+ * in-band answers their rungs expect and raw plumbing never reaches the
+ * composer (guuey#218's prod defect class).
+ *
+ * A staged answer is deliberately NOT `isError` (guuey#215): queueing is
+ * an acceptance, and the error flag fed apps' legacy failure overlays.
+ */
+import { type McpToolCallResult } from "./action.js";
+import type { UiActionRequest } from "./action.js";
+/** The staged-acceptance notice a view receives instead of a relay answer. */
+export declare const ACTION_STAGED_MSG = "Queued \u2014 press Send to continue.";
+/**
+ * guuey#198: the post-turn action policy's two host callbacks — when no
+ * turn is live, a card action stages into the composer instead of dying in
+ * the relay's degradation.
+ */
+export interface ActionStaging {
+    /** A turn is currently in flight — the live relay path applies. */
+    isTurnLive: () => boolean;
+    /** Prefill the composer with the projection (append, never clobber) and focus it. */
+    stage: (text: string) => void;
+}
+/**
+ * guuey#218: ONLY an allowlisted semantic action may stage — keyed on the
+ * SEMANTIC set ({@link UI_SEMANTIC_ACTION_TOOLS}), never the wider relay
+ * allowlist, so a relayable transport rung is never stage-eligible.
+ */
+export declare function isStageableAction(name: string): boolean;
+/**
+ * The human-readable projection of a card action — what lands in the
+ * composer as the user's next message (guuey#198, option (b)). `null`
+ * when the action shape has no honest text form (nested/non-primitive
+ * arguments): projecting only part of the arguments could stage a
+ * MISLEADING selection, so those degrade to the relay/stub path instead.
+ *
+ * guuey#215: a semantic-envelope call carries the USER'S action inside its
+ * arguments (`actionId` + the action's own params), so the projection
+ * unwraps the envelope — humanizing the carrier name would stage plumbing,
+ * not the user's words. No string `actionId` ⇒ no honest projection ⇒
+ * relay path.
+ */
+export declare function stagedActionText(name: string, args: unknown): string | null;
+/**
+ * Wrap ANY `onCallTool`-shaped hook with the staging policy (guuey#356):
+ * post-turn + allowlisted + honest projection → stage and answer the
+ * STAGED notice; every other call — mid-turn, non-semantic, or
+ * projection-less — delegates to `inner` byte-identically. A mount passes
+ * two callbacks ({@link ActionStaging}) and gets the widget's exact
+ * ratified behavior; `staging` absent returns `inner` unchanged, so the
+ * wrap composes freely at construction sites.
+ */
+export declare function withActionStaging(inner: (request: UiActionRequest) => Promise<McpToolCallResult>, staging: ActionStaging | undefined): (request: UiActionRequest) => Promise<McpToolCallResult>;
+//# sourceMappingURL=action-staging.d.ts.map

package/dist/action-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-staging.d.ts","sourceRoot":"","sources":["../src/action-staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAA4B,KAAK,iBAAiB,EAAiC,MAAM,aAAa,CAAC;AAC9G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,0CAAqC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,qFAAqF;IACrF,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAY3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,EAC/D,OAAO,EAAE,aAAa,GAAG,SAAS,GACjC,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAY1D"}

package/dist/action-staging.js

@@ -0,0 +1,112 @@
+/**
+ * The post-turn action-STAGING policy (guuey#356 — lifted VERBATIM from the
+ * widget's #198/#215/#218 civilization so every mount shares ONE copy).
+ *
+ * The beat it solves: after a turn completes there is no live turn to feed
+ * a card action into — relaying would only surface the "agent not
+ * listening" degradation at exactly the moment the agent's own copy
+ * invited the tap. Instead, an ALLOWLISTED semantic action with an honest
+ * text form stages a human-readable projection into the composer: one
+ * Enter sends it as the next turn. Everything else — internal transport
+ * rungs, foreign plumbing, shapes with no honest projection — rides the
+ * exact pre-#198 relay/stub path, so fallback chains keep receiving the
+ * in-band answers their rungs expect and raw plumbing never reaches the
+ * composer (guuey#218's prod defect class).
+ *
+ * A staged answer is deliberately NOT `isError` (guuey#215): queueing is
+ * an acceptance, and the error flag fed apps' legacy failure overlays.
+ */
+import { UI_SEMANTIC_ACTION_TOOLS } from "./action.js";
+/** The staged-acceptance notice a view receives instead of a relay answer. */
+export const ACTION_STAGED_MSG = "Queued — press Send to continue.";
+/**
+ * guuey#218: ONLY an allowlisted semantic action may stage — keyed on the
+ * SEMANTIC set ({@link UI_SEMANTIC_ACTION_TOOLS}), never the wider relay
+ * allowlist, so a relayable transport rung is never stage-eligible.
+ */
+export function isStageableAction(name) {
+    return UI_SEMANTIC_ACTION_TOOLS.has(name);
+}
+/** "selectSlot" → "Select slot"; "book_slot" → "Book slot". */
+function humanizeActionName(name) {
+    const words = name
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .trim();
+    return words.length === 0 ? name : words[0].toUpperCase() + words.slice(1);
+}
+/** The protocol-open wire shape — same guard idiom as action.ts's. */
+function isStructuredArgs(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function projectAction(name, args) {
+    const title = humanizeActionName(name);
+    if (args === undefined || args === null)
+        return title;
+    if (typeof args !== "object" || Array.isArray(args))
+        return null;
+    const entries = Object.entries(args);
+    if (entries.length === 0)
+        return title;
+    const pairs = [];
+    for (const [key, value] of entries) {
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            return null;
+        }
+        pairs.push(`${key} ${String(value)}`);
+    }
+    return `${title}: ${pairs.join(", ")}`;
+}
+/**
+ * The human-readable projection of a card action — what lands in the
+ * composer as the user's next message (guuey#198, option (b)). `null`
+ * when the action shape has no honest text form (nested/non-primitive
+ * arguments): projecting only part of the arguments could stage a
+ * MISLEADING selection, so those degrade to the relay/stub path instead.
+ *
+ * guuey#215: a semantic-envelope call carries the USER'S action inside its
+ * arguments (`actionId` + the action's own params), so the projection
+ * unwraps the envelope — humanizing the carrier name would stage plumbing,
+ * not the user's words. No string `actionId` ⇒ no honest projection ⇒
+ * relay path.
+ */
+export function stagedActionText(name, args) {
+    if (UI_SEMANTIC_ACTION_TOOLS.has(name)) {
+        if (!isStructuredArgs(args))
+            return null;
+        const actionId = args["actionId"];
+        if (typeof actionId !== "string" || actionId.length === 0)
+            return null;
+        const rest = {};
+        for (const [key, value] of Object.entries(args)) {
+            if (key !== "actionId")
+                rest[key] = value;
+        }
+        return projectAction(actionId, rest);
+    }
+    return projectAction(name, args);
+}
+/**
+ * Wrap ANY `onCallTool`-shaped hook with the staging policy (guuey#356):
+ * post-turn + allowlisted + honest projection → stage and answer the
+ * STAGED notice; every other call — mid-turn, non-semantic, or
+ * projection-less — delegates to `inner` byte-identically. A mount passes
+ * two callbacks ({@link ActionStaging}) and gets the widget's exact
+ * ratified behavior; `staging` absent returns `inner` unchanged, so the
+ * wrap composes freely at construction sites.
+ */
+export function withActionStaging(inner, staging) {
+    if (staging === undefined)
+        return inner;
+    return async (request) => {
+        if (!staging.isTurnLive() && isStageableAction(request.name)) {
+            const text = stagedActionText(request.name, request.arguments);
+            if (text !== null) {
+                staging.stage(text);
+                return { content: [{ type: "text", text: ACTION_STAGED_MSG }] };
+            }
+        }
+        return inner(request);
+    };
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  */
 export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultLocator, toolResultUiResource, uiLocator, type McpUiResourcePayload, } from "./block-ui.js";
 export { resolveViewMount, snapshotViewMount, toolResultViewMount, type LocatorViewMount, type ResolvedViewMount, type UiResourceReader, type ViewMount, type ViewMountChannel, } from "./card-mount.js";
+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";

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,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,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,KAAK,oBAAoB,EACzB,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"}
+{"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,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,KAAK,oBAAoB,EACzB,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"}

package/dist/index.js

@@ -5,6 +5,7 @@
  */
 export { asResourcePayload, asUiResource, blockUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, snapshotUiResource, toolResultLocator, toolResultUiResource, uiLocator, } from "./block-ui.js";
 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 { initializeResult, initialViewHostState, resourceReadResponse, RESOURCES_READ_METHOD, teardownMessage, toolCallResponse, TOOLS_CALL_METHOD, viewHostElapsed, viewHostReceive, diagnoseCspViolation, } from "./view-host-protocol.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/mcp-apps-host",
-  "version": "0.12.2",
+  "version": "0.14.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,7 +33,7 @@
     }
   },
   "dependencies": {
-    "@ggui-ai/protocol": "0.11.0",
+    "@ggui-ai/protocol": "0.12.0",
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@silverprotocol/core": "0.5.1"
   },
@@ -50,7 +50,7 @@
     "@types/react": "^19.0.0",
     "react": "^19.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.2.7"
   },
   "publishConfig": {
     "access": "public"

package/src/action-staging.ts

@@ -0,0 +1,128 @@
+/**
+ * The post-turn action-STAGING policy (guuey#356 — lifted VERBATIM from the
+ * widget's #198/#215/#218 civilization so every mount shares ONE copy).
+ *
+ * The beat it solves: after a turn completes there is no live turn to feed
+ * a card action into — relaying would only surface the "agent not
+ * listening" degradation at exactly the moment the agent's own copy
+ * invited the tap. Instead, an ALLOWLISTED semantic action with an honest
+ * text form stages a human-readable projection into the composer: one
+ * Enter sends it as the next turn. Everything else — internal transport
+ * rungs, foreign plumbing, shapes with no honest projection — rides the
+ * exact pre-#198 relay/stub path, so fallback chains keep receiving the
+ * in-band answers their rungs expect and raw plumbing never reaches the
+ * composer (guuey#218's prod defect class).
+ *
+ * A staged answer is deliberately NOT `isError` (guuey#215): queueing is
+ * an acceptance, and the error flag fed apps' legacy failure overlays.
+ */
+import { UI_SEMANTIC_ACTION_TOOLS, type McpToolCallResult, type McpToolStructuredContent } from "./action.js";
+import type { UiActionRequest } from "./action.js";
+
+/** The staged-acceptance notice a view receives instead of a relay answer. */
+export const ACTION_STAGED_MSG = "Queued — press Send to continue.";
+
+/**
+ * guuey#198: the post-turn action policy's two host callbacks — when no
+ * turn is live, a card action stages into the composer instead of dying in
+ * the relay's degradation.
+ */
+export interface ActionStaging {
+  /** A turn is currently in flight — the live relay path applies. */
+  isTurnLive: () => boolean;
+  /** Prefill the composer with the projection (append, never clobber) and focus it. */
+  stage: (text: string) => void;
+}
+
+/**
+ * guuey#218: ONLY an allowlisted semantic action may stage — keyed on the
+ * SEMANTIC set ({@link UI_SEMANTIC_ACTION_TOOLS}), never the wider relay
+ * allowlist, so a relayable transport rung is never stage-eligible.
+ */
+export function isStageableAction(name: string): boolean {
+  return UI_SEMANTIC_ACTION_TOOLS.has(name);
+}
+
+/** "selectSlot" → "Select slot"; "book_slot" → "Book slot". */
+function humanizeActionName(name: string): string {
+  const words = name
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .trim();
+  return words.length === 0 ? name : words[0].toUpperCase() + words.slice(1);
+}
+
+/** The protocol-open wire shape — same guard idiom as action.ts's. */
+function isStructuredArgs(value: unknown): value is McpToolStructuredContent {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function projectAction(name: string, args: unknown): string | null {
+  const title = humanizeActionName(name);
+  if (args === undefined || args === null) return title;
+  if (typeof args !== "object" || Array.isArray(args)) return null;
+  const entries = Object.entries(args);
+  if (entries.length === 0) return title;
+  const pairs: string[] = [];
+  for (const [key, value] of entries) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+      return null;
+    }
+    pairs.push(`${key} ${String(value)}`);
+  }
+  return `${title}: ${pairs.join(", ")}`;
+}
+
+/**
+ * The human-readable projection of a card action — what lands in the
+ * composer as the user's next message (guuey#198, option (b)). `null`
+ * when the action shape has no honest text form (nested/non-primitive
+ * arguments): projecting only part of the arguments could stage a
+ * MISLEADING selection, so those degrade to the relay/stub path instead.
+ *
+ * guuey#215: a semantic-envelope call carries the USER'S action inside its
+ * arguments (`actionId` + the action's own params), so the projection
+ * unwraps the envelope — humanizing the carrier name would stage plumbing,
+ * not the user's words. No string `actionId` ⇒ no honest projection ⇒
+ * relay path.
+ */
+export function stagedActionText(name: string, args: unknown): string | null {
+  if (UI_SEMANTIC_ACTION_TOOLS.has(name)) {
+    if (!isStructuredArgs(args)) return null;
+    const actionId = args["actionId"];
+    if (typeof actionId !== "string" || actionId.length === 0) return null;
+    const rest: McpToolStructuredContent = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (key !== "actionId") rest[key] = value;
+    }
+    return projectAction(actionId, rest);
+  }
+  return projectAction(name, args);
+}
+
+/**
+ * Wrap ANY `onCallTool`-shaped hook with the staging policy (guuey#356):
+ * post-turn + allowlisted + honest projection → stage and answer the
+ * STAGED notice; every other call — mid-turn, non-semantic, or
+ * projection-less — delegates to `inner` byte-identically. A mount passes
+ * two callbacks ({@link ActionStaging}) and gets the widget's exact
+ * ratified behavior; `staging` absent returns `inner` unchanged, so the
+ * wrap composes freely at construction sites.
+ */
+export function withActionStaging(
+  inner: (request: UiActionRequest) => Promise<McpToolCallResult>,
+  staging: ActionStaging | undefined,
+): (request: UiActionRequest) => Promise<McpToolCallResult> {
+  if (staging === undefined) return inner;
+  return async (request) => {
+    if (!staging.isTurnLive() && isStageableAction(request.name)) {
+      const text = stagedActionText(request.name, request.arguments);
+      if (text !== null) {
+        staging.stage(text);
+        return { content: [{ type: "text", text: ACTION_STAGED_MSG }] };
+      }
+    }
+    return inner(request);
+  };
+}

package/src/index.ts

@@ -26,6 +26,13 @@ export {
   type ViewMount,
   type ViewMountChannel,
 } from "./card-mount.js";
+export {
+  ACTION_STAGED_MSG,
+  isStageableAction,
+  stagedActionText,
+  withActionStaging,
+  type ActionStaging,
+} from "./action-staging.js";
 export {
   createMcpUiResourceReader,
   declaredResourceCsp,