Skip to content

The Open Standard for Generative UI

9.3 KB
Raw Blame
import type { AssistantMessage, Message, ToolCall, ToolMessage } from "../types";

/**
 * Real per-call lifecycle of a tool invocation.
 *
 * Derived from AG-UI stream events (never faked from `!!content`):
 *  - `streaming` — arguments are still arriving (`TOOL_CALL_ARGS` deltas).
 *  - `executing` — arguments closed (`TOOL_CALL_END` seen), awaiting a result.
 *  - `complete`  — a `TOOL_CALL_RESULT` landed without an error.
 *  - `error`     — a `TOOL_CALL_RESULT`/`RUN_ERROR` carried a failure.
 *
 * @category Types
 */
export type ToolCallStatus = "streaming" | "executing" | "complete" | "error";

/**
 * Single source of truth for one tool call + its (optional) result, used by the
 * UI layer instead of reading raw `ToolCall`/`ToolMessage` separately.
 *
 * Discriminated by `status` so impossible states are unrepresentable: the view
 * literally cannot read `result`/`errorText` in a state where they don't exist,
 * nor render an error as a success.
 *
 *  - `streaming` → args still arriving; `input` is `Partial<T>`, no result.
 *  - `executing` → args closed; `input` is `T`, awaiting result.
 *  - `complete`  → result landed OK; `input` is `T`, `result` is a string.
 *  - `error`     → result landed with a failure; `errorText` present.
 *
 * `input` is {@link partialJSONParse}'d **once** by the selector — never a raw
 * string for the consumer to parse.
 *
 * @category Types
 */
export type ToolActivity<T = unknown> =
  | {
      status: "streaming";
      id: string;
      toolName: string;
      toolCall: ToolCall;
      toolMessage: null;
      input: Partial<T>;
      result?: undefined;
      isError: false;
      errorText?: undefined;
      statusMessage?: string;
    }
  | {
      status: "executing";
      id: string;
      toolName: string;
      toolCall: ToolCall;
      toolMessage: null;
      input: T;
      result?: undefined;
      isError: false;
      errorText?: undefined;
      statusMessage?: string;
    }
  | {
      status: "complete";
      id: string;
      toolName: string;
      toolCall: ToolCall;
      toolMessage: ToolMessage;
      input: T;
      result: string;
      isError: false;
      errorText?: undefined;
      statusMessage?: string;
    }
  | {
      status: "error";
      id: string;
      toolName: string;
      toolCall: ToolCall;
      toolMessage: ToolMessage;
      input: T;
      result: string;
      isError: true;
      errorText?: string;
      statusMessage?: string;
    };

const isDev = () => typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production";

/**
 * Closes dangling brackets/quotes for a partial (mid-stream) JSON string so it
 * can be parsed for a best-effort snapshot. Conservative: only trims a trailing
 * object key that is provably awaiting a value (signalled by a trailing colon),
 * leaving complete array/values intact.
 */
function balanceOpenJSON(raw: string): string {
  const closers: string[] = [];
  let inString = false;
  let escaped = false;

  for (let i = 0; i < raw.length; i++) {
    const ch = raw[i];
    if (inString) {
      if (escaped) escaped = false;
      else if (ch === "\\") escaped = true;
      else if (ch === '"') inString = false;
      continue;
    }
    if (ch === '"') inString = true;
    else if (ch === "{") closers.push("}");
    else if (ch === "[") closers.push("]");
    else if (ch === "}" || ch === "]") closers.pop();
  }

  let out = raw;
  if (inString) {
    // Mid-string: drop a dangling escape, then close the string literal.
    if (escaped) out = out.slice(0, -1);
    out += '"';
  }

  // Drop a dangling object key with no value yet (`… "key":`). The colon is the
  // reliable "awaiting value" signal — a trailing string WITHOUT a colon may be
  // a complete array element/value, so leave it. Then drop any exposed comma.
  out = out.replace(/(?:,\s*)?"(?:[^"\\]|\\.)*"\s*:\s*$/, "");
  out = out.replace(/,\s*$/, "");

  for (let i = closers.length - 1; i >= 0; i--) out += closers[i];
  return out;
}

/**
 * Tolerant single-pass JSON parse for streamed tool arguments. Tries a straight
 * parse, then a bracket-balanced parse for partial input. **Never throws** —
 * returns `{}` when nothing parseable can be recovered.
 *
 * @category Utilities
 */
export function partialJSONParse(raw: string): unknown {
  if (!raw) return {};
  try {
    return JSON.parse(raw);
  } catch {
    /* fall through to the balanced attempt */
  }
  try {
    return JSON.parse(balanceOpenJSON(raw));
  } catch {
    return {};
  }
}

let warnedTitle = false;

/**
 * Maps the deprecated `_title` tool-arg key onto a typed `statusMessage` for one
 * minor release (with a one-time dev warning). Prefer a renderer-owned typed
 * field going forward.
 */
function readStatusMessage(input: unknown): string | undefined {
  if (input && typeof input === "object" && "_title" in input) {
    const value = (input as Record<string, unknown>)["_title"];
    if (typeof value === "string") {
      if (isDev() && !warnedTitle) {
        warnedTitle = true;
        console.warn(
          "[OpenUI] The `_title` tool-arg key is deprecated and will be removed; " +
            "the renderer now exposes a typed `statusMessage` on ToolActivity instead.",
        );
      }
      return value;
    }
  }
  return undefined;
}

/**
 * Pairs every tool call on an assistant message with its result message **by
 * `toolCallId`** (id-keyed, no positional `break`), producing a typed
 * {@link ToolActivity} per call. Turn-safe even when tool messages trail or
 * interleave with other messages.
 *
 * @param message       The assistant message owning the tool calls.
 * @param allMessages   The full thread message list (scanned for tool results).
 * @param executingIds  Tool-call ids whose args have closed but whose result
 *                      hasn't landed (the store's `executingToolCallIds`).
 *
 * @category Utilities
 */
export function pairToolActivity(
  message: AssistantMessage,
  allMessages: ReadonlyArray<Message>,
  executingIds: ReadonlySet<string> = new Set(),
): ToolActivity[] {
  const byCallId = new Map<string, ToolMessage>();
  // Every tool-call id owned by ANY assistant message — used to detect orphan
  // tool results (a `role:"tool"` message whose call exists nowhere).
  const ownedCallIds = new Set<string>();
  for (const m of allMessages) {
    if (m.role === "tool") {
      const tm = m as ToolMessage;
      if (tm.toolCallId) byCallId.set(tm.toolCallId, tm);
    } else if (m.role === "assistant") {
      for (const tc of (m as AssistantMessage).toolCalls ?? []) ownedCallIds.add(tc.id);
    }
  }

  const activities = (message.toolCalls ?? []).map((toolCall): ToolActivity => {
    const toolMessage = byCallId.get(toolCall.id) ?? null;
    const input = partialJSONParse(toolCall.function.arguments) as Record<string, unknown>;
    const statusMessage = readStatusMessage(input);
    const base = {
      id: toolCall.id,
      toolName: toolCall.function.name,
      toolCall,
      statusMessage,
    };

    if (toolMessage) {
      return toolMessage.error
        ? {
            ...base,
            status: "error",
            toolMessage,
            input: input as never,
            result: toolMessage.content,
            isError: true,
            errorText: toolMessage.error,
          }
        : {
            ...base,
            status: "complete",
            toolMessage,
            input: input as never,
            result: toolMessage.content,
            isError: false,
          };
    }

    return executingIds.has(toolCall.id)
      ? {
          ...base,
          status: "executing",
          toolMessage: null,
          input: input as never,
          isError: false,
        }
      : {
          ...base,
          status: "streaming",
          toolMessage: null,
          input: input as Partial<unknown>,
          isError: false,
        };
  });

  // Orphan tool results: tool messages that trail THIS assistant message but
  // belong to no tool call anywhere. Previously these still rendered (as a
  // generic result chip); pairing by id alone would drop them. Attribute each
  // to the assistant message it positionally trails so it renders exactly once.
  const msgIndex = allMessages.findIndex((m) => m.id === message.id);
  if (msgIndex !== -1) {
    for (let i = msgIndex + 1; i < allMessages.length; i++) {
      const m = allMessages[i];
      if (!m || m.role !== "tool") break;
      const tm = m as ToolMessage;
      if (!tm.toolCallId || ownedCallIds.has(tm.toolCallId)) continue;
      const orphanCall: ToolCall = {
        id: tm.toolCallId,
        type: "function",
        function: { name: "", arguments: "" },
      };
      // Key by the (unique) tool-message id, not the toolCallId — two orphan
      // results can share a toolCallId in persisted history and would otherwise
      // collide on the React key.
      const base = { id: tm.id, toolName: "", toolCall: orphanCall };
      activities.push(
        tm.error
          ? {
              ...base,
              status: "error",
              toolMessage: tm,
              input: {} as never,
              result: tm.content,
              isError: true,
              errorText: tm.error,
            }
          : {
              ...base,
              status: "complete",
              toolMessage: tm,
              input: {} as never,
              result: tm.content,
              isError: false,
            },
      );
    }
  }

  return activities;
}