@agents24/chat-react 0.3.0 → 0.3.2

package/README.md

@@ -22,7 +22,8 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 - `appendStableStreamingTurn(messages, userMessage, assistantMessage)`
 - `upsertStableAssistantMessage(messages, input)`
 - normalized chat message, part, transport, and storage types
-- typed V2 `pendingHitl`, `isResolvingHitl`, and `resumeHitl(...)` controller state/actions in package `0.3.0`
+- typed V2 `pendingHitl`, `isResolvingHitl`, and `resumeHitl(...)` controller state/actions in the current `0.3.x` contract
+- strict HITL response-block parsing and `waitForMcpOauthComplete(...)` for validated host-owned OAuth popup completion
 - `partsFromResponseBlocks(blocks, fallbackText)`
 - `renderChatPart(part, message, renderOptions)`
 - `@agents24/chat-react/ui` for shared shadcn-derived `Message`, `Bubble`, `Attachment`, `Marker`, `MessageResponse`, `AgentChatMessage`, `AgentChatComposer`, `McpConnectRequiredCard`, and Agents24 message/attachment adapters
@@ -32,7 +33,9 @@ The package owns thread hydration, older-page pagination, stream/reattach state,
 
 Hosts can pass `onRuntimeEvent(event, context)` and `onThreadDetailLoaded(detail)` to layer product-specific runtime UI, trace panels, analytics, or metadata over the shared chat lifecycle without forking stream handling. That surface is enough for running-history badges and read-only live thread inspectors without a separate host-owned reattach state machine.
 
-`ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `hitl`, `error`, and `data`. The shared compact HITL card renders pending and terminal states for Tool review, MCP authentication, User Approval, and app-data permission. Tool review exposes only **Allow once** and **Don't allow**; Edit and Respond are not part of the contract. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
+`ChatMessage.parts` is the only render model. Backend `response_blocks` are normalized into ordered parts such as `text`, `tool-get_meteo`, `ui-blocks`, `reasoning`, `hitl`, `error`, and `data`. The shared HITL action strip renders a neutral, borderless pending state and a compact terminal outcome for Tool review, MCP authentication, User Approval, and app-data permission. Tool review exposes only **Allow once** and **Don't allow**; verbose risk metadata, argument details, Edit, and Respond are not part of the chat presentation. Tool UI is client-owned through `renderPart`, `toolRenderers`, and `fallbackToolRenderer`; the package does not infer English tool labels or group tool rows.
+
+MCP OAuth remains a host side effect. `startMcpAuth(...)` returns both `authorization_url` and the authoritative `callback_origin`; hosts open the popup and pass both values to `waitForMcpOauthComplete(...)` before calling `resumeHitl(...)`. The utility verifies popup identity, callback origin, server identity, and connection UUID and owns timeout/close cleanup.
 
 `useStreamingText` owns reusable visual pacing for active assistant text. It returns `displayedText`, `isAnimating`, `mode`, and `parseIncompleteMarkdown` so host renderers can pass those values into their markdown component without the package depending on any markdown/UI library. The package only chooses text timing, cache behavior, reduced-motion handling, and active text-part helpers.
 

package/dist/index.cjs

@@ -81,7 +81,8 @@ __export(index_exports, {
   useMessageScroller: () => import_message_scroller2.useMessageScroller,
   useMessageScrollerScrollable: () => import_message_scroller2.useMessageScrollerScrollable,
   useMessageScrollerVisibility: () => import_message_scroller2.useMessageScrollerVisibility,
-  useStreamingText: () => useStreamingText
+  useStreamingText: () => useStreamingText,
+  waitForMcpOauthComplete: () => waitForMcpOauthComplete
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -385,6 +386,22 @@ var assistantTextFromEvents = (events) => {
 };
 var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
 var optionalString = (value) => typeof value === "string" && value.trim() ? value.trim() : void 0;
+var HITL_ACTIONS_BY_KIND = {
+  tool_review: ["approve", "reject"],
+  mcp_auth: ["connect", "skip"],
+  user_approval: ["approve", "reject"],
+  app_data_permission: ["approve", "reject"]
+};
+var HITL_STATUSES = ["pending", "resolved", "expired", "cancelled", "invalidated"];
+function exactHitlActions(kind, value) {
+  if (!Array.isArray(value)) throw new Error("Invalid V2 HITL response block.");
+  const actions = value.map((item) => String(item));
+  const expected = HITL_ACTIONS_BY_KIND[kind];
+  if (actions.length !== expected.length || actions.some((action, index) => action !== expected[index])) {
+    throw new Error("Invalid V2 HITL response block.");
+  }
+  return actions;
+}
 var toolStateFromStatus = (status) => {
   const normalized = String(status || "").trim().toLowerCase();
   if (["failed", "error"].includes(normalized)) return "output-error";
@@ -491,17 +508,19 @@ var partsFromResponseBlocks = (blocks, fallbackText) => {
       const interruptId = optionalString(block.interruptId) || optionalString(hitl.interrupt_id);
       const hitlKind = optionalString(block.hitlKind) || optionalString(hitl.kind);
       const status = optionalString(block.status) || optionalString(hitl.status) || "pending";
-      const allowedActions = Array.isArray(hitl.allowed_actions) ? hitl.allowed_actions.filter((value) => ["approve", "reject", "connect", "skip"].includes(String(value))) : [];
-      if (!interruptId || allowedActions.length === 0 || !["tool_review", "mcp_auth", "user_approval", "app_data_permission"].includes(String(hitlKind))) {
+      if (!interruptId || !["tool_review", "mcp_auth", "user_approval", "app_data_permission"].includes(String(hitlKind)) || !HITL_STATUSES.includes(status)) {
         throw new Error("Invalid V2 HITL response block.");
       }
+      const kind = hitlKind;
+      const allowedActions = exactHitlActions(kind, hitl.allowed_actions);
       const resolution = asRecord(block.resolution);
+      const resolver = asRecord(resolution?.resolver);
       parts.push({
         id,
         type: "hitl",
         kind: "hitl",
         interruptId,
-        hitlKind,
+        hitlKind: kind,
         message: optionalString(hitl.message) || optionalString(block.text) || "Input is required to continue.",
         allowedActions,
         status,
@@ -511,7 +530,10 @@ var partsFromResponseBlocks = (blocks, fallbackText) => {
           outcome: optionalString(resolution.outcome),
           reason: optionalString(resolution.reason),
           resolvedAt: optionalString(resolution.resolved_at),
-          resolver: asRecord(resolution.resolver)
+          resolver: resolver ? {
+            principalType: optionalString(resolver.principal_type) || optionalString(resolver.principalType) || null,
+            principalId: optionalString(resolver.principal_id) || optionalString(resolver.principalId) || null
+          } : null
         } : null,
         raw: block
       });
@@ -1961,6 +1983,59 @@ var LatestThreadScroller = {
   Outline: LatestThreadScrollerOutline
 };
 
+// src/mcp-oauth.ts
+var CONNECTION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function normalizedOrigin(value) {
+  try {
+    return new URL(value).origin;
+  } catch {
+    throw new Error("MCP authorization returned an invalid callback origin.");
+  }
+}
+function waitForMcpOauthComplete({
+  popup,
+  callbackOrigin,
+  serverId,
+  timeoutMs = 12e4
+}) {
+  if (!popup) return Promise.reject(new Error("Could not open the MCP authorization popup."));
+  const expectedOrigin = normalizedOrigin(callbackOrigin);
+  const expectedServerId = String(serverId || "").trim();
+  if (!expectedServerId) return Promise.reject(new Error("MCP authorization is missing its server identity."));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      window.clearTimeout(timeout);
+      window.clearInterval(closeTimer);
+      window.removeEventListener("message", onMessage);
+      if (result instanceof Error) reject(result);
+      else resolve(result);
+    };
+    const onMessage = (event) => {
+      if (event.source !== popup || event.origin !== expectedOrigin) return;
+      const data = event.data;
+      if (data?.type !== "mcp-oauth-complete" || data.server_id !== expectedServerId) return;
+      if (!data.success) {
+        finish(new Error("MCP authorization failed."));
+        return;
+      }
+      const connectionId = String(data.connection_id || "").trim();
+      if (!CONNECTION_ID_PATTERN.test(connectionId)) return;
+      finish({ connectionId });
+    };
+    const timeout = window.setTimeout(
+      () => finish(new Error("MCP authorization timed out.")),
+      Math.max(1, timeoutMs)
+    );
+    const closeTimer = window.setInterval(() => {
+      if (popup.closed) finish(new Error("MCP authorization window was closed before connecting."));
+    }, 500);
+    window.addEventListener("message", onMessage);
+  });
+}
+
 // src/renderers.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var DefaultToolPart = ({ part }) => {
@@ -2398,6 +2473,7 @@ var import_message_scroller2 = require("@shadcn/react/message-scroller");
   useMessageScroller,
   useMessageScrollerScrollable,
   useMessageScrollerVisibility,
-  useStreamingText
+  useStreamingText,
+  waitForMcpOauthComplete
 });
 //# sourceMappingURL=index.cjs.map