@blocksdiy/react-common 1.50.1 → 1.52.0

package/dist/utils/agui-interrupts.js

@@ -0,0 +1,351 @@
+export const TOOL_APPROVALS_METADATA_KEY = "blocks.toolApprovals";
+const SUBAGENT_TOOL_NAME = "task";
+/**
+ * A rejected call never ran; its result is the rejection. The server always uses
+ * HumanInTheLoopMiddleware's standard reject (the Reject button, typing, and a new
+ * Send Message). Used only when no record of the decision exists: a
+ * tool that failed also carries `error`.
+ */
+const REJECTED_RESULT_PREFIXES = ["User rejected the tool call for `"];
+export const APPROVAL_STATUS_LINE = {
+    waiting: "Waiting for approval",
+    approved: "Approved",
+    rejected: "Rejected",
+};
+/** Appended to a decided card's status while another request of the pause is open. */
+export const WAITING_FOR_OTHER_SUFFIX = " · waiting for your decision on the other request";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === "string";
+const nonEmpty = (value) => (isString(value) && value ? value : null);
+const parseArgs = (raw) => {
+    try {
+        const parsed = JSON.parse(raw || "{}");
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+export const requestKey = (interruptId, index) => `${interruptId}#${index}`;
+/** The name the model sees for a describe name (wf-actions-py `model_tool_name`). */
+const modelToolName = (describeName) => describeName.replace(/[^a-zA-Z0-9_-]/g, "_").toLowerCase();
+/**
+ * The server arms each approval with its tool's describe name as the request's
+ * `description`. Trusted only when it maps back to the request's name: a pause armed
+ * without one (and every pause parked before) carries the middleware's default text.
+ */
+const displayNameOf = (name, description) => isString(description) && description && name && modelToolName(description) === name ? description : null;
+const rawOf = (interrupt) => {
+    const metadata = isRecord(interrupt.metadata) ? interrupt.metadata : {};
+    const langgraph = isRecord(metadata.langgraph) ? metadata.langgraph : {};
+    return isRecord(langgraph.raw) ? langgraph.raw : {};
+};
+const allowedOf = (configs, index, name) => {
+    const read = (config) => isRecord(config) && Array.isArray(config.allowed_decisions) ? config.allowed_decisions.filter(isString) : [];
+    // The middleware appends one request and one config per gated call, in step.
+    const positional = configs[index];
+    if (isRecord(positional) && (!name || positional.action_name == null || positional.action_name === name)) {
+        return read(positional);
+    }
+    const byName = configs.find((config) => isRecord(config) && config.action_name === name);
+    return byName ? read(byName) : read(positional);
+};
+/** The newest assistant message's calls that have no result yet, in order. */
+const waitingCalls = (messages) => {
+    const answered = new Set();
+    for (const message of messages) {
+        if (message.role === "tool" && "toolCallId" in message && isString(message.toolCallId)) {
+            answered.add(message.toolCallId);
+        }
+    }
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message.role !== "assistant") {
+            continue;
+        }
+        const calls = "toolCalls" in message && Array.isArray(message.toolCalls) ? message.toolCalls : [];
+        return calls
+            .filter((call) => !answered.has(call.id))
+            .map((call) => ({ id: call.id, name: call.function.name, args: parseArgs(call.function.arguments) }));
+    }
+    return [];
+};
+/**
+ * Every request of the open interrupts, in the order the server needs decisions,
+ * each paired with its transcript call by order.
+ */
+export const requestsOf = (interrupts, messages) => {
+    const waiting = waitingCalls(messages);
+    const tasks = waiting.filter((call) => call.name === SUBAGENT_TOOL_NAME);
+    const own = waiting.filter((call) => call.name !== SUBAGENT_TOOL_NAME);
+    const host = tasks[0] ?? null;
+    const used = new Set();
+    const out = [];
+    for (const interrupt of interrupts) {
+        const raw = rawOf(interrupt);
+        const requests = Array.isArray(raw.action_requests) ? raw.action_requests : [];
+        const configs = Array.isArray(raw.review_configs) ? raw.review_configs : [];
+        requests.forEach((request, index) => {
+            const fields = isRecord(request) ? request : {};
+            const name = isString(fields.name) ? fields.name : "";
+            const match = own.find((call) => call.name === name && !used.has(call.id)) ?? null;
+            if (match) {
+                used.add(match.id);
+            }
+            out.push({
+                interruptId: interrupt.id,
+                index,
+                key: requestKey(interrupt.id, index),
+                name,
+                args: isRecord(fields.args) ? fields.args : {},
+                allowedDecisions: allowedOf(configs, index, name),
+                toolCallId: match?.id ?? null,
+                anchorToolCallId: match ? match.id : (host?.id ?? null),
+                displayName: displayNameOf(name, fields.description),
+            });
+        });
+    }
+    return out;
+};
+export const isApprovalRequest = (request) => request.allowedDecisions.includes("approve");
+/** Thrown with fixed text when an answer pairs with no open interrupt and is not the welcome seed. */
+export const INTERRUPT_NOT_OPEN_ERROR = "answerInterrupt: nothing is waiting for this answer";
+/**
+ * A question's answer as HumanInTheLoopMiddleware's `respond` message -- and as the welcome
+ * seed's tool result, so both read the same. `?? null`: JSON.stringify(undefined) drops the
+ * key, which the server refuses.
+ */
+export const respondMessageOf = (answer) => JSON.stringify(answer ?? null);
+const decisionOf = (answer) => answer.type === "respond" ? { type: "respond", message: respondMessageOf(answer.message) } : { type: answer.type };
+/**
+ * The welcome seed (`initialUserChoices`): connect writes an ask_user call that no run made,
+ * so nothing is parked behind it. Its signature is the one the server used
+ * (`answer_orphan_pause`): no user message yet, and the call still waits on the newest
+ * assistant message.
+ */
+export const isWelcomeSeedCall = (messages, toolCallId) => !messages.some((message) => message.role === "user") && waitingCalls(messages).some((call) => call.id === toolCallId);
+/**
+ * Where a question card's answer goes: the open request it pairs with by order; the seed's
+ * tool result when nothing is open; otherwise nowhere -- the caller
+ * throws INTERRUPT_NOT_OPEN_ERROR. Never `command.resume`.
+ */
+export const answerRouteOf = (interrupts, messages, toolCallId) => {
+    const request = requestsOf(interrupts, messages).find((candidate) => candidate.toolCallId === toolCallId && !isApprovalRequest(candidate));
+    if (request) {
+        return { kind: "respond", request };
+    }
+    if (interrupts.length === 0 && isWelcomeSeedCall(messages, toolCallId)) {
+        return { kind: "seed" };
+    }
+    return { kind: "refuse" };
+};
+/**
+ * The deprecated `resolveInterrupt(resume)`: a `{decisions}` payload for the ONE
+ * open interrupt, as a standard resolved entry. Null when it cannot be routed.
+ */
+export const singleInterruptResume = (interrupts, payload) => interrupts.length === 1 && isRecord(payload) && Array.isArray(payload.decisions)
+    ? [{ interruptId: interrupts[0].id, status: "resolved", payload: { decisions: payload.decisions } }]
+    : null;
+/**
+ * After a run that carried `resume[]`: anything but RUN_FINISHED (a RUN_ERROR such as a refused
+ * resume, a stop, a dropped stream) may have consumed the resume on the server, while
+ * @ag-ui/client changes `pendingInterrupts` only on RUN_FINISHED. The chat then forgets them and
+ * reconnects; the connect re-sends what is really open.
+ */
+export const needsReconnectAfter = (sentResume, finished) => sentResume && !finished;
+/** One `resolved` entry per open interrupt, or null while any request is unanswered. */
+export const buildResumeEntries = (interrupts, requests, answers) => {
+    if (interrupts.length === 0) {
+        return null;
+    }
+    const entries = [];
+    for (const interrupt of interrupts) {
+        const decisions = [];
+        for (const request of requests.filter((r) => r.interruptId === interrupt.id)) {
+            const answer = answers.get(request.key);
+            if (!answer) {
+                return null;
+            }
+            decisions.push(decisionOf(answer));
+        }
+        entries.push({ interruptId: interrupt.id, status: "resolved", payload: { decisions } });
+    }
+    return entries;
+};
+/**
+ * Typing while the turn is parked: the typed text goes out as a normal
+ * message, and each open interrupt gets the protocol's own `cancelled` entry, with no payload.
+ * The server rejects every waiting approval with the standard text, skips every question with
+ * one fixed marker, and appends the message after them.
+ */
+export const cancelledResumeEntries = (interrupts) => interrupts.map((interrupt) => ({ interruptId: interrupt.id, status: "cancelled" }));
+/**
+ * Forgets the agent's open interrupts. CopilotKit 1.70.2 keeps
+ * `pendingInterrupts` across a thread swap and a reconnect, and @ag-ui/client 0.0.59
+ * then refuses the next run AND connect ("Thread has N pending interrupt(s) not
+ * addressed by resume"). Call it on a thread swap and right before every connect
+ * the chat starts; the connect's own RUN_FINISHED re-sends what is still open.
+ */
+export const forgetOpenInterrupts = (agent) => {
+    if (agent) {
+        agent.pendingInterrupts = [];
+    }
+};
+/** This browser's own approval decisions, by anchor, until a reload brings the record. */
+export const localStampsByAnchor = (requests, answers) => {
+    const out = new Map();
+    for (const request of requests) {
+        const answer = answers.get(request.key);
+        if (!answer || answer.type === "respond" || !isApprovalRequest(request) || !request.anchorToolCallId) {
+            continue;
+        }
+        const list = out.get(request.anchorToolCallId) ?? [];
+        list.push({
+            // A sub-agent's call is not in this transcript; its request key stands in.
+            toolCallId: request.toolCallId ?? request.key,
+            decision: answer.type,
+            toolName: request.name,
+            displayName: request.displayName,
+            args: request.args,
+        });
+        out.set(request.anchorToolCallId, list);
+    }
+    return out;
+};
+export const mergeStamps = (previous, next) => {
+    if (next.size === 0) {
+        return previous;
+    }
+    const merged = new Map(previous);
+    next.forEach((stamps, anchor) => merged.set(anchor, [...(merged.get(anchor) ?? []), ...stamps]));
+    return merged;
+};
+/**
+ * The decided-here stamps after the chat forgets what is open. A same-thread reload keeps them:
+ * the connect's snapshot brings the record, and until it lands nothing else draws the card. A
+ * thread or chat swap, or a reconnect after a failed run, clears them.
+ */
+export const stampsAfterInterruptReset = (previous, { keepStamps }) => (keepStamps || previous.size === 0 ? previous : new Map());
+/** Takes back exactly the stamps `mergeStamps` added (by identity), when their send did not go through. */
+export const dropStamps = (previous, added) => {
+    if (added.size === 0) {
+        return previous;
+    }
+    const kept = new Map();
+    previous.forEach((stamps, anchor) => {
+        const drop = new Set(added.get(anchor) ?? []);
+        const rest = stamps.filter((stamp) => !drop.has(stamp));
+        if (rest.length > 0) {
+            kept.set(anchor, rest);
+        }
+    });
+    return kept;
+};
+export const toolApprovalsOf = (message) => {
+    if (!isRecord(message) || !isRecord(message.metadata)) {
+        return [];
+    }
+    const raw = message.metadata[TOOL_APPROVALS_METADATA_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.flatMap((item) => isRecord(item) &&
+        (item.decision === "approve" || item.decision === "reject") &&
+        isString(item.toolName) &&
+        isString(item.toolCallId)
+        ? [
+            {
+                toolCallId: item.toolCallId,
+                decision: item.decision,
+                toolName: item.toolName,
+                displayName: nonEmpty(item.displayName),
+                args: isRecord(item.args) ? item.args : {},
+            },
+        ]
+        : []);
+};
+const rejectedByResult = (result) => isString(result) && REJECTED_RESULT_PREFIXES.some((prefix) => result.startsWith(prefix));
+/** `insert_items_in_orders` → `insert items in orders`. */
+export const toolWords = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .replace(/[_\s-]+/g, " ")
+    .trim()
+    .toLowerCase();
+export const toolCallOf = (messages, toolCallId) => {
+    for (const message of messages) {
+        if (message.role !== "assistant" || !("toolCalls" in message) || !Array.isArray(message.toolCalls)) {
+            continue;
+        }
+        const call = message.toolCalls.find((candidate) => candidate.id === toolCallId);
+        if (call) {
+            return { name: call.function.name, args: parseArgs(call.function.arguments) };
+        }
+    }
+    return null;
+};
+const titleOf = (toolName) => {
+    const words = toolWords(toolName);
+    return words.charAt(0).toUpperCase() + words.slice(1);
+};
+const statusOf = (decision) => decision === "approve" ? "approved" : "rejected";
+export const approvalCardsForToolCall = ({ toolCallId, toolName, toolArgs, toolResult, toolMessage, requests, answers, localStamps, }) => {
+    const live = requests.filter((request) => request.anchorToolCallId === toolCallId && isApprovalRequest(request));
+    if (live.length > 0) {
+        const othersOpen = requests.some((request) => !answers.has(request.key));
+        return live.map((request) => {
+            const answer = answers.get(request.key);
+            const status = answer && answer.type !== "respond" ? statusOf(answer.type) : "waiting";
+            const waitingForOthers = status !== "waiting" && othersOpen;
+            return {
+                key: request.key,
+                title: titleOf(request.displayName ?? request.name),
+                args: request.args,
+                status,
+                statusLine: waitingForOthers
+                    ? `${APPROVAL_STATUS_LINE[status]}${WAITING_FOR_OTHER_SUFFIX}`
+                    : APPROVAL_STATUS_LINE[status],
+                request: status === "waiting" ? { interruptId: request.interruptId, index: request.index } : null,
+                waitingForOthers,
+            };
+        });
+    }
+    // The server's record wins once a reload brought it; until then, this browser's own.
+    const recorded = toolApprovalsOf(toolMessage);
+    const decided = recorded.length > 0 ? recorded : (localStamps.get(toolCallId) ?? []);
+    if (decided.length > 0) {
+        return decided.map((stamp) => {
+            const status = statusOf(stamp.decision);
+            return {
+                key: `${toolCallId}#${stamp.toolCallId}`,
+                title: titleOf(stamp.displayName ?? stamp.toolName),
+                args: stamp.args,
+                status,
+                statusLine: APPROVAL_STATUS_LINE[status],
+                request: null,
+                waitingForOthers: false,
+            };
+        });
+    }
+    if (toolName !== SUBAGENT_TOOL_NAME && rejectedByResult(toolResult)) {
+        return [
+            {
+                key: `${toolCallId}#rejected`,
+                title: titleOf(toolName),
+                args: isRecord(toolArgs) ? toolArgs : {},
+                status: "rejected",
+                statusLine: APPROVAL_STATUS_LINE.rejected,
+                request: null,
+                waitingForOthers: false,
+            },
+        ];
+    }
+    return [];
+};
+/**
+ * Whether the tool's normal step renders under its cards: a sub-agent's `task` step
+ * always does; a parent call's only once approved AND sent (while waiting it has not
+ * run; a rejected call never runs; an approval waiting for the pause's other cards has
+ * not been sent yet).
+ */
+export const toolStepVisibleBelowCards = (toolName, cards) => toolName === SUBAGENT_TOOL_NAME || cards.every((card) => card.status === "approved" && !card.waitingForOthers);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocksdiy/react-common",
-  "version": "1.50.1",
+  "version": "1.52.0",
   "type": "module",
   "description": "React common",
   "keywords": [],
@@ -39,7 +39,7 @@
     "penpal": "^8.0.0",
     "react": "^19.2.8",
     "use-stick-to-bottom": "1.1.4",
-    "@blocksdiy/blocks-client-api": "1.25.1"
+    "@blocksdiy/blocks-client-api": "1.5.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.18",