@assistant-ui/core 0.3.16 → 0.3.17

package/src/runtime/utils/auto-status.ts

@@ -36,6 +36,15 @@ const AUTO_STATUS_COMPLETE = Object.freeze(
     { [symbolAutoStatus]: true },
   ),
 );
+const AUTO_STATUS_CANCELLED = Object.freeze(
+  Object.assign(
+    {
+      type: "incomplete" as const,
+      reason: "cancelled" as const,
+    },
+    { [symbolAutoStatus]: true },
+  ),
+);
 
 const AUTO_STATUS_PENDING = Object.freeze(
   Object.assign(
@@ -66,6 +75,7 @@ export const getAutoStatus = (
   hasInterruptedToolCalls: boolean,
   hasPendingToolCalls: boolean,
   error?: ReadonlyJSONValue,
+  isCancelled?: boolean,
 ): MessageStatus => {
   if (isLast && error) {
     return Object.assign(
@@ -84,7 +94,9 @@ export const getAutoStatus = (
       ? AUTO_STATUS_INTERRUPT
       : hasPendingToolCalls
         ? AUTO_STATUS_PENDING
-        : AUTO_STATUS_COMPLETE;
+        : isCancelled
+          ? AUTO_STATUS_CANCELLED
+          : AUTO_STATUS_COMPLETE;
 };
 
 export const getContentAutoStatus = (

package/src/runtime/utils/external-message-conversion.test.ts

@@ -110,4 +110,101 @@ describe("convertExternalMessageChunk", () => {
 
     expect(second).toBe(first);
   });
+
+  it("replaces a cached complete status after cancellation", () => {
+    const input = {};
+    const chunk = {
+      inputs: [input],
+      outputs: [{ id: "m1", role: "assistant" as const, content: "partial" }],
+    };
+    const cancelled = new Set(["m1"]);
+    const generatedFallbackMessages = new WeakSet<object>();
+    const first = convertExternalMessageChunk(chunk, 0, 1, false, undefined, {
+      message: undefined,
+      generatedFallbackMessages,
+    });
+
+    const second = convertExternalMessageChunk(
+      chunk,
+      0,
+      1,
+      false,
+      undefined,
+      { message: first, generatedFallbackMessages },
+      cancelled,
+    );
+
+    expect(first.status).toMatchObject({ type: "complete", reason: "unknown" });
+    expect(second).not.toBe(first);
+    expect(second.status).toMatchObject({
+      type: "incomplete",
+      reason: "cancelled",
+    });
+
+    const failed = convertExternalMessageChunk(
+      chunk,
+      0,
+      1,
+      false,
+      "failed",
+      { message: second, generatedFallbackMessages },
+      cancelled,
+    );
+    expect(failed.status).toMatchObject({
+      type: "incomplete",
+      reason: "error",
+      error: "failed",
+    });
+  });
+
+  it("cancels a joined chunk when any joined message was stopped", () => {
+    const generatedFallbackMessages = new WeakSet<object>();
+    const result = convertExternalMessageChunk(
+      {
+        inputs: [{}, {}],
+        outputs: [
+          { id: "m1", role: "assistant" as const, content: "first" },
+          { id: "m2", role: "assistant" as const, content: "second" },
+        ],
+      },
+      0,
+      1,
+      false,
+      undefined,
+      { message: undefined, generatedFallbackMessages },
+      new Set(["m2"]),
+    );
+
+    expect(result.status).toMatchObject({
+      type: "incomplete",
+      reason: "cancelled",
+    });
+  });
+
+  it("cancels an earlier message that is no longer the last one", () => {
+    const cancelled = new Set(["m1"]);
+    const generatedFallbackMessages = new WeakSet<object>();
+    const build = (id: string, idx: number) =>
+      convertExternalMessageChunk(
+        {
+          inputs: [{}],
+          outputs: [{ id, role: "assistant" as const, content: "text" }],
+        },
+        idx,
+        2,
+        false,
+        undefined,
+        { message: undefined, generatedFallbackMessages },
+        cancelled,
+      );
+
+    expect(build("m1", 0).status).toMatchObject({
+      type: "incomplete",
+      reason: "cancelled",
+    });
+    expect(build("m2", 1).status).toMatchObject({
+      type: "complete",
+      reason: "unknown",
+    });
+  });
 });

package/src/runtime/utils/external-message-conversion.ts

@@ -46,6 +46,7 @@ export type ExternalMessageConverterMessage =
 export type ExternalMessageConverterMetadata = {
   readonly toolStatuses?: Record<string, ToolExecutionStatus>;
   readonly error?: ReadonlyJSONValue;
+  readonly cancelledMessageIds?: ReadonlySet<string>;
   readonly messageTiming?: Record<string, MessageTiming>;
 };
 
@@ -358,7 +359,10 @@ export const chunkExternalMessages = <T>(
   return results;
 };
 
-export const shallowArrayEqual = (a: unknown[], b: unknown[]) => {
+export const shallowArrayEqual = (
+  a: readonly unknown[],
+  b: readonly unknown[],
+) => {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) {
     if (a[i] !== b[i]) return false;
@@ -378,9 +382,18 @@ export const convertExternalMessageChunk = <T>(
   isRunning: boolean,
   error: ReadonlyJSONValue | undefined,
   cache?: ExternalMessageConversionCache,
+  cancelledMessageIds?: ReadonlySet<string>,
 ) => {
   const isLast = idx === chunkCount - 1;
   const joined = joinExternalMessages(message.outputs);
+  const isCancelled =
+    cancelledMessageIds !== undefined &&
+    message.outputs.some(
+      (output) =>
+        output.role !== "tool" &&
+        output.id != null &&
+        cancelledMessageIds.has(output.id),
+    );
   const hasInterruptedToolCalls =
     typeof joined.content === "object" &&
     joined.content.some(isInterruptedToolCall);
@@ -393,6 +406,7 @@ export const convertExternalMessageChunk = <T>(
     hasInterruptedToolCalls,
     hasPendingToolCalls,
     isLast ? error : undefined,
+    isCancelled,
   );
   const fallbackId = `${FALLBACK_ID_PREFIX}${idx}`;
 
@@ -488,6 +502,8 @@ export const convertExternalMessages = <T extends WeakKey>(
       chunks.length,
       isRunning,
       metadata.error,
+      undefined,
+      metadata.cancelledMessageIds,
     ),
   );
   return completeExternalMessageConversion(result, metadata.error);

package/src/runtime/utils/resolveToolApprovalResponse.test.ts

@@ -88,4 +88,77 @@ describe("resolveToolApprovalResponse", () => {
       resolveToolApprovalResponse({ id: "a2" }, { optionId: "once" }),
     ).toThrow('no option with id "once"');
   });
+
+  it("resolves a free-form answer as approved and carries the text", () => {
+    expect(
+      resolveToolApprovalResponse(
+        { id: "q1", display: "text" },
+        { text: "staging" },
+      ),
+    ).toEqual({ approvalId: "q1", approved: true, text: "staging" });
+  });
+
+  it("carries the text alongside a chosen option", () => {
+    expect(
+      resolveToolApprovalResponse(
+        {
+          id: "q2",
+          display: "select",
+          allowFreeform: true,
+          options: [{ id: "other", kind: "_other" }],
+        },
+        { optionId: "other", approved: true, text: "somewhere else" },
+      ),
+    ).toEqual({
+      approvalId: "q2",
+      approved: true,
+      optionId: "other",
+      text: "somewhere else",
+    });
+  });
+
+  it("throws when the request does not accept a free-form answer", () => {
+    expect(() =>
+      resolveToolApprovalResponse(approval, { text: "anything" }),
+    ).toThrow("does not accept a free-form answer");
+    expect(() =>
+      resolveToolApprovalResponse(
+        { id: "a4", display: "select" },
+        { approved: true, text: "anything" },
+      ),
+    ).toThrow("does not accept a free-form answer");
+  });
+
+  it("refuses to infer approval from a bare answer on a decision", () => {
+    expect(() =>
+      resolveToolApprovalResponse(
+        { id: "a5", display: "decision", allowFreeform: true },
+        { text: "not this one" },
+      ),
+    ).toThrow("is a decision, not a question");
+    expect(() =>
+      resolveToolApprovalResponse(
+        { id: "a6", allowFreeform: true },
+        { text: "not this one" },
+      ),
+    ).toThrow("is a decision, not a question");
+  });
+
+  it("records the answer alongside an explicit decision on a gate", () => {
+    expect(
+      resolveToolApprovalResponse(
+        { id: "a7", display: "decision", allowFreeform: true },
+        { approved: false, text: "not this one" },
+      ),
+    ).toEqual({ approvalId: "a7", approved: false, text: "not this one" });
+  });
+
+  it("keeps a refusal a refusal when the request accepts text", () => {
+    expect(
+      resolveToolApprovalResponse(
+        { id: "q3", allowFreeform: true },
+        { approved: false, reason: "not answering" },
+      ),
+    ).toEqual({ approvalId: "q3", approved: false, reason: "not answering" });
+  });
 });

package/src/runtime/utils/resolveToolApprovalResponse.ts

@@ -1,6 +1,8 @@
-import type {
-  ToolApprovalOption,
-  ToolApprovalResponse,
+import {
+  toolApprovalAcceptsText,
+  type ToolApprovalDisplay,
+  type ToolApprovalOption,
+  type ToolApprovalResponse,
 } from "../../types/message";
 import type { RespondToToolApprovalOptions } from "../interfaces/thread-runtime-core";
 
@@ -12,16 +14,25 @@ const APPROVED_BY_KIND: Record<string, boolean> = {
 };
 
 /**
- * Resolves a renderer-facing approval response (boolean or optionId form)
- * against the approval's option list into the runtime-facing decision shape.
+ * Resolves a renderer-facing approval response (boolean, optionId, or
+ * free-form answer) against the approval's request shape into the
+ * runtime-facing decision shape.
  */
 export const resolveToolApprovalResponse = (
   approval: {
     readonly id: string;
+    readonly display?: ToolApprovalDisplay;
+    readonly allowFreeform?: boolean;
     readonly options?: readonly ToolApprovalOption[];
   },
   response: ToolApprovalResponse,
 ): RespondToToolApprovalOptions => {
+  const text = response.text;
+  if (text !== undefined && !toolApprovalAcceptsText(approval))
+    throw new Error(
+      `Tool approval "${approval.id}" does not accept a free-form answer; the request must declare display "text" or allowFreeform`,
+    );
+
   let approved: boolean;
   let optionId: string | undefined;
 
@@ -42,14 +53,24 @@ export const resolveToolApprovalResponse = (
       approved = APPROVED_BY_KIND[option.kind]!;
     }
     optionId = option.id;
-  } else {
+  } else if ("approved" in response) {
     approved = response.approved;
+  } else {
+    // A bare answer resolves a question, where answering is not refusing. On a
+    // decision the approval itself is the authorization, so inferring one from
+    // a typed note would let the note authorize the call.
+    if (approval.display !== "text" && approval.display !== "select")
+      throw new Error(
+        `Tool approval "${approval.id}" is a decision, not a question; respond with an explicit approved value, optionally alongside the answer`,
+      );
+    approved = true;
   }
 
   return {
     approvalId: approval.id,
     approved,
     ...(optionId !== undefined && { optionId }),
+    ...(text !== undefined && { text }),
     ...(response.reason != null && { reason: response.reason }),
   };
 };

package/src/runtime/utils/thread-message-like.ts

@@ -23,8 +23,8 @@ import type {
   MessageTiming,
   PartProviderMetadata,
   TextMessagePart,
-  ToolApprovalOption,
   ToolCallTiming,
+  ToolCallMessagePart,
   ToolCallMessagePartMcpMetadata,
 } from "../../types/message";
 import type {
@@ -66,15 +66,7 @@ export type ThreadMessageLike = {
             readonly timing?: ToolCallTiming;
             readonly mcp?: ToolCallMessagePartMcpMetadata;
             readonly providerMetadata?: PartProviderMetadata;
-            readonly approval?: {
-              readonly id: string;
-              readonly approved?: boolean;
-              readonly reason?: string;
-              readonly isAutomatic?: boolean;
-              readonly options?: readonly ToolApprovalOption[];
-              readonly optionId?: string;
-              readonly resolution?: "cancelled" | "expired";
-            };
+            readonly approval?: NonNullable<ToolCallMessagePart["approval"]>;
           }
       )[];
   readonly id?: string | undefined;

package/src/runtime/utils/tool-call-tree.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import type {
+  ThreadAssistantMessage,
+  ThreadAssistantMessagePart,
+  ThreadMessage,
+  ToolCallMessagePart,
+} from "../../types/message";
+import {
+  iterateToolCallParts,
+  mapToolCallPartsDeep,
+  walkToolCallTree,
+} from "./tool-call-tree";
+
+const toolCall = (
+  toolCallId: string,
+  messages?: readonly ThreadMessage[],
+): ToolCallMessagePart => ({
+  type: "tool-call",
+  toolCallId,
+  toolName: "t",
+  argsText: "{}",
+  args: {},
+  ...(messages !== undefined && { messages }),
+});
+
+const assistant = (
+  id: string,
+  content: readonly ThreadAssistantMessagePart[],
+): ThreadAssistantMessage =>
+  ({
+    id,
+    role: "assistant",
+    content,
+    status: { type: "complete", reason: "unknown" },
+    metadata: {
+      unstable_state: null,
+      unstable_annotations: [],
+      unstable_data: [],
+      steps: [],
+      custom: {},
+    },
+    createdAt: new Date(0),
+    attachments: [],
+  }) as unknown as ThreadAssistantMessage;
+
+const user = (id: string): ThreadMessage =>
+  ({
+    id,
+    role: "user",
+    content: [{ type: "text", text: "hi" }],
+    metadata: { custom: {} },
+    createdAt: new Date(0),
+    attachments: [],
+  }) as unknown as ThreadMessage;
+
+// root
+// └─ a ─ nested message "m2"
+//         ├─ b ─ nested message "m3"
+//         │       └─ c
+//         └─ d
+const tree = () => {
+  const c = toolCall("c");
+  const b = toolCall("b", [assistant("m3", [c])]);
+  const d = toolCall("d");
+  const a = toolCall("a", [assistant("m2", [b, d])]);
+  return { a, b, c, d };
+};
+
+describe("walkToolCallTree", () => {
+  it("yields every part in document order, each ahead of its descendants", () => {
+    const { a } = tree();
+    const entries = [
+      ...walkToolCallTree([user("m0"), assistant("m1", [a, toolCall("e")])]),
+    ];
+
+    expect(entries.map((entry) => entry.part.toolCallId)).toEqual([
+      "a",
+      "b",
+      "c",
+      "d",
+      "e",
+    ]);
+  });
+
+  it("reports the message that directly holds each part", () => {
+    const { a } = tree();
+    const entries = [...walkToolCallTree([assistant("m1", [a])])];
+
+    expect(
+      Object.fromEntries(
+        entries.map((entry) => [entry.part.toolCallId, entry.messageId]),
+      ),
+    ).toEqual({ a: "m1", b: "m2", c: "m3", d: "m2" });
+  });
+
+  it("skips messages whose content is not an array", () => {
+    const malformed = {
+      id: "m1",
+      role: "assistant",
+    } as unknown as ThreadMessage;
+    expect([...walkToolCallTree([malformed])]).toEqual([]);
+  });
+
+  it("skips a non-assistant message carrying a tool-call part", () => {
+    const malformed = {
+      ...user("m2"),
+      content: [toolCall("b")],
+    } as unknown as ThreadMessage;
+    const a = toolCall("a", [malformed]);
+
+    expect(
+      [...walkToolCallTree([assistant("m1", [a])])].map(
+        (entry) => entry.part.toolCallId,
+      ),
+    ).toEqual(["a"]);
+  });
+});
+
+describe("iterateToolCallParts", () => {
+  it("matches walkToolCallTree over the same content", () => {
+    const { a } = tree();
+    const content = [a, toolCall("e")];
+
+    expect([...iterateToolCallParts(content)].map((p) => p.toolCallId)).toEqual(
+      [...walkToolCallTree([assistant("m1", content)])].map(
+        (entry) => entry.part.toolCallId,
+      ),
+    );
+  });
+
+  it("ignores non tool-call parts", () => {
+    expect([
+      ...iterateToolCallParts([
+        { type: "text", text: "hi" } as ThreadAssistantMessagePart,
+        toolCall("a"),
+      ]),
+    ]).toHaveLength(1);
+  });
+});
+
+describe("mapToolCallPartsDeep", () => {
+  it("rewrites nested parts and reports the change", () => {
+    const { a } = tree();
+    const content = [a];
+    const { content: next, changed } = mapToolCallPartsDeep(content, (part) =>
+      part.toolCallId === "c" ? { ...part, isError: true } : part,
+    );
+
+    expect(changed).toBe(true);
+    const parts = [...iterateToolCallParts(next)];
+    expect(parts.find((part) => part.toolCallId === "c")?.isError).toBe(true);
+    expect(
+      parts.find((part) => part.toolCallId === "d")?.isError,
+    ).toBeUndefined();
+  });
+
+  it("skips a nested message whose content is not an array", () => {
+    const malformed = {
+      id: "m2",
+      role: "assistant",
+    } as unknown as ThreadMessage;
+    const a = toolCall("a", [malformed]);
+
+    expect(() =>
+      mapToolCallPartsDeep([a], (part) => ({ ...part, isError: true })),
+    ).not.toThrow();
+  });
+
+  it("keeps the original content identity when nothing changed", () => {
+    const { a } = tree();
+    const content = [a, toolCall("e")];
+    const result = mapToolCallPartsDeep(content, (part) => part);
+
+    expect(result.changed).toBe(false);
+    expect(result.content).toBe(content);
+  });
+
+  it("preserves untouched sibling messages by identity", () => {
+    const nested = assistant("m2", [toolCall("b")]);
+    const sibling = user("m3");
+    const a = toolCall("a", [nested, sibling]);
+    const { content: next } = mapToolCallPartsDeep([a], (part) =>
+      part.toolCallId === "b" ? { ...part, isError: true } : part,
+    );
+
+    const mapped = next[0] as ToolCallMessagePart;
+    expect(mapped).not.toBe(a);
+    expect(mapped.messages?.[1]).toBe(sibling);
+    expect(mapped.messages?.[0]).not.toBe(nested);
+  });
+});

package/src/runtime/utils/tool-call-tree.ts

@@ -0,0 +1,97 @@
+import type {
+  ThreadAssistantMessage,
+  ThreadAssistantMessagePart,
+  ThreadMessage,
+  ToolCallMessagePart,
+} from "../../types/message";
+
+export type ToolCallTreeEntry = {
+  readonly part: ToolCallMessagePart;
+  /** Id of the message whose content directly holds `part`. */
+  readonly messageId: string;
+};
+
+/**
+ * Walk every tool-call part reachable from `messages`. A tool call projects a
+ * child run as nested messages on `ToolCallMessagePart.messages`, so a
+ * subagent's own calls live below the top-level content and a seam that only
+ * scans the top level cannot reach them.
+ *
+ * Parts arrive in document order, each one ahead of its own descendants.
+ * `messageId` names the message that directly holds the part, which for a
+ * nested call is the child run's message rather than the top-level message the
+ * tree hangs from. Only assistant messages are descended, the same rule
+ * {@link mapToolCallPartsDeep} rewrites under, so a part this reports is always
+ * a part that can be written back.
+ */
+export function* walkToolCallTree(
+  messages: readonly ThreadMessage[],
+): Generator<ToolCallTreeEntry> {
+  for (const message of messages) {
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) {
+      continue;
+    }
+    for (const part of message.content) {
+      if (!part || part.type !== "tool-call") continue;
+      yield { part, messageId: message.id };
+      if (part.messages?.length) yield* walkToolCallTree(part.messages);
+    }
+  }
+}
+
+/**
+ * Content-level form of {@link walkToolCallTree}, for a caller that already
+ * holds one assistant message's content and does not need the owning id.
+ */
+export function* iterateToolCallParts(
+  content: readonly ThreadAssistantMessagePart[],
+): Generator<ToolCallMessagePart> {
+  for (const part of content) {
+    if (!part || part.type !== "tool-call") continue;
+    yield part;
+    if (part.messages?.length) {
+      for (const entry of walkToolCallTree(part.messages)) {
+        yield entry.part;
+      }
+    }
+  }
+}
+
+/**
+ * Rebuild `content` with `fn` applied to every tool-call part in the tree.
+ * Arrays and nested messages are reused wherever `fn` returned the part it was
+ * given, so an unchanged subtree keeps its identity and `changed` reports
+ * whether anything moved.
+ */
+export function mapToolCallPartsDeep(
+  content: readonly ThreadAssistantMessagePart[],
+  fn: (part: ToolCallMessagePart) => ToolCallMessagePart,
+): { content: readonly ThreadAssistantMessagePart[]; changed: boolean } {
+  let changed = false;
+  const next = content.map((part): ThreadAssistantMessagePart => {
+    if (part.type !== "tool-call") return part;
+    let mapped = fn(part);
+    if (mapped.messages !== undefined) {
+      let nestedChanged = false;
+      const nestedMessages = mapped.messages.map((nested) => {
+        if (nested.role !== "assistant" || !Array.isArray(nested.content)) {
+          return nested;
+        }
+        const assistant = nested as ThreadAssistantMessage;
+        const result = mapToolCallPartsDeep(assistant.content, fn);
+        if (!result.changed) return nested;
+        nestedChanged = true;
+        return { ...assistant, content: result.content };
+      });
+      if (nestedChanged) {
+        mapped =
+          mapped === part
+            ? { ...part, messages: nestedMessages }
+            : { ...mapped, messages: nestedMessages };
+      }
+    }
+    if (mapped !== part) changed = true;
+    return mapped;
+  });
+  return changed ? { content: next, changed } : { content, changed };
+}