Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

37.5 KB
Raw Blame
/**
 * Inc.7 (frontend) — tool-event attribution by tool_call_id.
 *
 * With in-turn tool concurrency, a single step can have several same-named tool
 * actions in flight. The processor must attribute each tool_execution_end /
 * _failed to the action with the matching tool_call_id, not to the
 * "last running tool" (which mis-attributes output/status the moment completion
 * order differs from reverse-start order).
 */
import { readFileSync } from "node:fs"
import { describe, it, expect, vi } from "vitest"

vi.mock("next/navigation", () => ({ useRouter: () => ({ push: vi.fn() }) }))
vi.mock("@/contexts/i18n-context", () => ({
  useI18n: () => ({ t: (key: string) => key }),
}))
vi.mock("@/contexts/app-context-chat", () => ({
  useApp: () => ({ openFilePreview: vi.fn(), dispatch: vi.fn() }),
}))
vi.mock("@/lib/api-wrapper", () => ({ apiRequest: vi.fn() }))
// These pull in heavy/optional deps (e.g. pptxviewjs) not needed for the
// pure reducer under test.
vi.mock("@/components/file/docx-preview-renderer", () => ({
  DocxPreviewRenderer: () => null,
}))
vi.mock("@/components/file/excel-preview-renderer", () => ({
  ExcelPreviewRenderer: () => null,
}))
vi.mock("@/components/file/pptx-preview-renderer", () => ({
  PptxPreviewRenderer: () => null,
}))

import {
  getFriendlyToolName,
  getProgressNarrationText,
  getRawToolName,
  processTraceEvents,
} from "./TraceEventRenderer"
import { resolveDynamicTranslation, type Locale } from "@/i18n/translations"
import type { TranslateDynamic } from "@/contexts/i18n-context"
import en from "@/i18n/locales/en"
import zh from "@/i18n/locales/zh"

const t = (key: string, vars?: Record<string, string | number>) =>
  vars?.tool ? `${key}:${vars.tool}` : key

const ev = (event_type: string, data: Record<string, unknown>) => ({
  event_type,
  step_id: "step-1",
  data,
})

const stepStart = ev("dag_step_start", { step_name: "Search" })

describe("processTraceEvents DAG step outcomes", () => {
  it.each([undefined, "failed", "completed"])(
    "keeps a failed DAG step separate from successful siblings when task status is %s",
    (taskStatus) => {
      const steps = processTraceEvents([
        stepStart,
        ev("dag_step_end", { status: "completed", result: "Verified output" }),
        { ...ev("dag_step_start", { step_name: "Verify remaining data" }), step_id: "verify" },
        {
          ...ev("dag_step_end", { status: "failed", error: "Iteration limit reached" }),
          step_id: "verify",
        },
      ], t, taskStatus)

      expect(steps[0]).toMatchObject({ status: "completed", output: "Verified output" })
      expect(steps[1]).toMatchObject({ status: "failed", output: "" })
      expect(steps[1].actions).toEqual([
        expect.objectContaining({
          type: "error",
          status: "failed",
          data: { error: "Iteration limit reached" },
        }),
      ])
    },
  )

  it.each(["dag_step_end", "dag_step_failed"])("ends unfinished actions on %s without changing completed work", (eventType) => {
    const [step] = processTraceEvents([
      stepStart,
      ev("tool_execution_start", { tool_name: "read_file", tool_call_id: "done" }),
      ev("tool_execution_end", { tool_name: "read_file", tool_call_id: "done", result: "Verified rows" }),
      ev("tool_execution_start", { tool_name: "web_search", tool_call_id: "pending-1" }),
      ev("tool_execution_start", { tool_name: "web_search", tool_call_id: "pending-2" }),
      ev(eventType, { status: "failed", error: "Step stopped" }),
    ], t, "completed")

    expect(step.status).toBe("failed")
    expect(step.actions[0]).toMatchObject({ status: "completed", data: { output: "Verified rows" } })
    expect(step.actions.slice(1)).toHaveLength(2)
    step.actions.slice(1).forEach((action) => {
      expect(action).toMatchObject({ status: "failed", data: { error: "Step stopped" } })
    })
  })

  it("uses the existing fallback for failed DAG steps without an error message", () => {
    const [step] = processTraceEvents([
      stepStart,
      ev("dag_step_end", { status: "failed" }),
    ], t)

    expect(step.status).toBe("failed")
    expect(step.actions[0].data.error).toBe("traceEventRenderer.unknownError")
  })

  it.each(["completed", undefined])("preserves successful and legacy DAG ends with status %s", (status) => {
    const [step] = processTraceEvents([
      stepStart,
      ev("dag_step_end", { ...(status ? { status } : {}), result: "Verified output" }),
    ], t)

    expect(step).toMatchObject({ status: "completed", output: "Verified output" })
    expect(step.actions[0]).toMatchObject({ type: "info", status: "completed" })
  })
})

// Every status in the final settling pass crossed with every step shape that
// can reach it. A step only holds pending/running/completed/failed before that
// pass, and a pending step never carries a name, so "unfinished" means running.
describe("processTraceEvents settling of stopped processes", () => {
  type Shape = "running" | "running+action" | "completed" | "completed+action" | "failed" | "failed+action"
  type Settled = {
    step: string
    actions: Array<[status: string, error: string | undefined]>
  }

  const stepEnd = (data: Record<string, unknown>) => ev("dag_step_end", data)
  const shapeEvents: Record<Shape, ReturnType<typeof ev>[]> = {
    running: [stepStart],
    "running+action": [stepStart, ev("llm_call_start", { model_name: "m" })],
    completed: [stepStart, stepEnd({ status: "completed" })],
    "completed+action": [
      stepStart,
      stepEnd({ status: "completed" }),
      ev("llm_call_start", { model_name: "m" }),
    ],
    failed: [stepStart, stepEnd({ status: "failed", error: "boom" })],
    "failed+action": [
      stepStart,
      stepEnd({ status: "failed", error: "boom" }),
      ev("llm_call_start", { model_name: "m" }),
    ],
  }

  const unknownError = "traceEventRenderer.unknownError"
  const reported: Settled["actions"][number] = ["failed", "boom"]
  // Known existing behaviour, pinned as it is today: a running action stays
  // spinning under a step that has already settled, under "completed" when the
  // step failed and under "paused" or "waiting_for_user" when the step completed
  // or failed. A later fix that settles these actions should update the
  // `spinning` entries in those rows; that change is not a regression.
  const spinning: Settled["actions"][number] = ["running", undefined]

  const expectations: Record<string, Record<Shape, Settled>> = {
    interrupted: {
      running: { step: "interrupted", actions: [] },
      "running+action": { step: "interrupted", actions: [["interrupted", undefined]] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "completed", actions: [["interrupted", undefined]] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, ["interrupted", undefined]] },
    },
    failed: {
      running: { step: "failed", actions: [] },
      "running+action": { step: "failed", actions: [["failed", unknownError]] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "failed", actions: [["failed", unknownError]] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, ["failed", unknownError]] },
    },
    completed: {
      running: { step: "completed", actions: [] },
      "running+action": { step: "completed", actions: [["completed", undefined]] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "completed", actions: [["completed", undefined]] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, spinning] },
    },
    paused: {
      running: { step: "paused", actions: [] },
      "running+action": { step: "paused", actions: [["completed", undefined]] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "completed", actions: [spinning] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, spinning] },
    },
    waiting_for_user: {
      running: { step: "waiting_for_user", actions: [] },
      "running+action": { step: "waiting_for_user", actions: [["completed", undefined]] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "completed", actions: [spinning] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, spinning] },
    },
    // Not stopped statuses: the settling pass must leave the step untouched.
    running: {
      running: { step: "running", actions: [] },
      "running+action": { step: "running", actions: [spinning] },
      completed: { step: "completed", actions: [] },
      "completed+action": { step: "completed", actions: [spinning] },
      failed: { step: "failed", actions: [reported] },
      "failed+action": { step: "failed", actions: [reported, spinning] },
    },
  }

  const cases = Object.entries(expectations).flatMap(([status, byShape]) =>
    (Object.keys(byShape) as Shape[]).map((shape) => [status, shape, byShape[shape]] as const),
  )

  it.each(cases)("settles a %s process with a %s step", (status, shape, expected) => {
    const [step] = processTraceEvents(shapeEvents[shape] as never, t, status)
    expect({
      step: step.status,
      actions: step.actions.map((action) => [action.status, action.data.error]),
    }).toEqual(expected)
  })

  it("settles nothing when the process status is absent", () => {
    const [step] = processTraceEvents(shapeEvents["running+action"] as never, t)
    expect(step.status).toBe("running")
    expect(step.actions.map((action) => action.status)).toEqual(["running"])
  })
})

describe("processTraceEvents exact settlement projection", () => {
  const toolActions = (events: Parameters<typeof processTraceEvents>[0]) =>
    processTraceEvents(events, t).flatMap(step =>
      step.actions.filter(action => action.type === "tool"),
    )
  const event = (
    event_type: string,
    step_id: string,
    data: Record<string, unknown>,
  ) => ({ event_type, step_id, data })
  const startStep = (stepId: string, name = stepId) =>
    event("react_task_start", stepId, { step_name: name })
  const startTool = (
    stepId: string,
    invocationId: string | undefined,
    result?: string,
    settlement = false,
  ) => [
    event("tool_execution_start", stepId, {
      tool_name: "approval_gate",
      tool_call_id: "tool_call_0",
      ...(invocationId ? { invocation_id: invocationId } : {}),
      ...(settlement ? { settlement_delivery: true } : {}),
    }),
    event("tool_execution_end", stepId, {
      tool_name: "approval_gate",
      tool_call_id: "tool_call_0",
      ...(invocationId ? { invocation_id: invocationId } : {}),
      ...(settlement ? { settlement_delivery: true } : {}),
      result: { output: result ?? "waiting" },
    }),
  ]

  it("settles only the exact invocation when one step reuses a provider id", () => {
    const events = [
      startStep("same-step"),
      ...startTool("same-step", "invocation-a", "first"),
      ...startTool("same-step", "invocation-b", "second"),
      ...startTool("same-step", "invocation-b", "settled-second", true),
    ]

    const steps = processTraceEvents(events, t)
    const actions = steps.flatMap(step => step.actions.filter(action => action.type === "tool"))
    expect(actions).toHaveLength(2)
    expect(actions.find(action => action.data.invocation_id === "invocation-a")?.data.output).toBe("first")
    expect(actions.find(action => action.data.invocation_id === "invocation-b")?.data.output).toBe("settled-second")
  })

  it("settles only the exact invocation across steps that reuse a provider id", () => {
    const events = [
      startStep("step-a"),
      ...startTool("step-a", "invocation-a", "first"),
      startStep("step-b"),
      ...startTool("step-b", "invocation-b", "second"),
      ...startTool("fresh-resume-step", "invocation-a", "settled-first", true),
    ]

    const steps = processTraceEvents(events, t)
    const actions = steps.flatMap(step => step.actions.filter(action => action.type === "tool"))
    expect(actions).toHaveLength(2)
    expect(actions.find(action => action.data.invocation_id === "invocation-a")?.data.output).toBe("settled-first")
    expect(actions.find(action => action.data.invocation_id === "invocation-b")?.data.output).toBe("second")
    expect(steps.some(step => step.stepId === "fresh-resume-step")).toBe(false)
  })

  it("does not let an unknown exact identity hijack a legacy candidate", () => {
    const events = [
      startStep("step-a"),
      ...startTool("step-a", undefined, "legacy"),
      ...startTool("step-a", "unknown-invocation", "orphan-settlement", true),
    ]

    const actions = toolActions(events)
    expect(actions).toHaveLength(2)
    expect(actions.find(action => !action.data.invocation_id)?.data.output).toBe("legacy")
    expect(actions.find(action => action.data.invocation_id === "unknown-invocation")?.data.output).toBe("orphan-settlement")
  })

  it("keeps a paired orphan settlement visible without a task-start event", () => {
    const actions = toolActions([
      ...startTool("truncated-step", "orphan-invocation", "terminal", true),
    ])

    expect(actions).toHaveLength(1)
    expect(actions[0]).toMatchObject({
      status: "completed",
      data: {
        invocation_id: "orphan-invocation",
        output: "terminal",
      },
    })
  })

  it("keeps an orphan terminal event visible when settlement START is truncated", () => {
    const steps = processTraceEvents([
      event("tool_execution_end", "truncated-step", {
        tool_name: "approval_gate",
        tool_call_id: "tool_call_0",
        invocation_id: "orphan-invocation",
        settlement_delivery: true,
        result: { output: "terminal" },
      }),
    ] as never, t)

    expect(steps).toHaveLength(1)
    expect(steps[0].stepName).toBe("traceEventRenderer.taskExecution")
    expect(steps[0].actions).toEqual([
      expect.objectContaining({
        status: "completed",
        data: expect.objectContaining({ output: "terminal" }),
      }),
    ])
  })

  it("uses step identity only for ambiguous legacy settlements", () => {
    const events = [
      startStep("step-a"),
      ...startTool("step-a", undefined, "waiting-a"),
      startStep("step-b"),
      ...startTool("step-b", undefined, "waiting-b"),
      ...startTool("step-a", undefined, "settled-a", true),
      ...startTool("step-b", undefined, "settled-b", true),
    ]

    const actions = toolActions(events)
    expect(actions).toHaveLength(2)
    expect(actions.map(action => action.data.output).sort()).toEqual(["settled-a", "settled-b"])
  })

  it("namespaces exact and legacy settlement cache keys", () => {
    const exactId = "tool_call_0::step-a"
    const events = [
      startStep("step-a"),
      ...startTool("step-a", undefined, "legacy-waiting"),
      startStep("step-b"),
      ...startTool("step-b", exactId, "exact-waiting"),
      ...startTool("step-a", undefined, "legacy-settled", true),
      ...startTool("step-b", exactId, "exact-settled", true),
    ]

    const actions = toolActions(events)
    expect(actions).toHaveLength(2)
    expect(actions.find(action => !action.data.invocation_id)?.data.output).toBe("legacy-settled")
    expect(actions.find(action => action.data.invocation_id === exactId)?.data.output).toBe("exact-settled")
  })

  it("projects a failed settlement onto the exact card and clears stale output", () => {
    const events = [
      startStep("step-a"),
      ...startTool("step-a", "invocation-a", "Approve?"),
      event("tool_execution_start", "resume", {
        tool_name: "approval_gate",
        tool_call_id: "tool_call_0",
        invocation_id: "invocation-a",
        settlement_delivery: true,
      }),
      event("tool_execution_failed", "resume", {
        tool_name: "approval_gate",
        tool_call_id: "tool_call_0",
        invocation_id: "invocation-a",
        settlement_delivery: true,
        error: "Rejected",
      }),
    ]

    const actions = toolActions(events)
    expect(actions).toHaveLength(1)
    expect(actions[0]).toMatchObject({ status: "failed", data: { error: "Rejected" } })
    expect(actions[0].data.output).toBeUndefined()
  })
})

describe("processTraceEvents tool_call_id attribution", () => {
  it("normalizes malformed trace data before nested access", () => {
    const malformedEvents = [
      {
        event_type: "workforce_delegation_start",
        step_id: "worker-null",
        timestamp: 1,
        data: null,
      },
      {
        event_type: "workforce_delegation_end",
        step_id: "worker-string",
        timestamp: 2,
        data: "not-an-object",
      },
      {
        event_type: "tool_execution_start",
        step_id: "worker-array",
        timestamp: 3,
        data: [],
      },
    ]

    expect(() => processTraceEvents(malformedEvents as never, t)).not.toThrow()
  })

  it("does not throw when tool_name in the payload is not a string", () => {
    // tool_name's "string" type is a compile-time annotation, not a runtime
    // guarantee: a malformed/legacy backend payload could send a number,
    // object, or null. getFriendlyToolName must not crash on it.
    const malformedToolNameEvents = [
      ev("tool_execution_start", { tool_name: 42 }),
      ev("tool_execution_start", { tool_name: { unexpected: "object" } }),
      ev("tool_execution_start", { tool_name: null }),
    ]

    expect(() => processTraceEvents(malformedToolNameEvents as never, t)).not.toThrow()
  })

  it("attributes concurrent same-name tool results by tool_call_id", () => {
    const events = [
      stepStart,
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "A",
        tool_args: { query: "a" },
      }),
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "B",
        tool_args: { query: "b" },
      }),
      // First-started finishes first: this is the order that breaks LIFO.
      ev("tool_execution_end", {
        tool_name: "web_search",
        tool_call_id: "A",
        result: { output: "RESULT_A" },
      }),
      ev("tool_execution_end", {
        tool_name: "web_search",
        tool_call_id: "B",
        result: { output: "RESULT_B" },
      }),
    ]

    const steps = processTraceEvents(events as never, t)
    const toolActions = steps[0].actions.filter((a) => a.type === "tool")
    const a = toolActions.find((x) => x.data.tool_call_id === "A")
    const b = toolActions.find((x) => x.data.tool_call_id === "B")

    expect(a?.data.output).toBe("RESULT_A")
    expect(b?.data.output).toBe("RESULT_B")
    expect(a?.status).toBe("completed")
    expect(b?.status).toBe("completed")
  })

  it("attributes a concurrent tool failure by tool_call_id", () => {
    const events = [
      stepStart,
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "A",
        tool_args: { query: "a" },
      }),
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "B",
        tool_args: { query: "b" },
      }),
      ev("tool_execution_failed", {
        tool_name: "web_search",
        tool_call_id: "A",
        error: "boom-A",
      }),
      ev("tool_execution_end", {
        tool_name: "web_search",
        tool_call_id: "B",
        result: { output: "RESULT_B" },
      }),
    ]

    const steps = processTraceEvents(events as never, t)
    const toolActions = steps[0].actions.filter((a) => a.type === "tool")
    const a = toolActions.find((x) => x.data.tool_call_id === "A")
    const b = toolActions.find((x) => x.data.tool_call_id === "B")

    expect(a?.status).toBe("failed")
    expect(a?.data.error).toBe("boom-A")
    expect(b?.status).toBe("completed")
    expect(b?.data.output).toBe("RESULT_B")
  })

  it("updates step.output for sequential tools within one step", () => {
    // Two tools run one-after-another (never overlapping). step.output must
    // track the latest tool's output, exactly as it did before concurrency was
    // introduced — counting total tool actions would wrongly freeze it.
    const events = [
      stepStart,
      ev("tool_execution_start", {
        tool_name: "calculator",
        tool_call_id: "A",
        tool_args: { expression: "1+1" },
      }),
      ev("tool_execution_end", {
        tool_name: "calculator",
        tool_call_id: "A",
        result: { output: "RESULT_A" },
      }),
      ev("tool_execution_start", {
        tool_name: "calculator",
        tool_call_id: "B",
        tool_args: { expression: "2+2" },
      }),
      ev("tool_execution_end", {
        tool_name: "calculator",
        tool_call_id: "B",
        result: { output: "RESULT_B" },
      }),
    ]

    const steps = processTraceEvents(events as never, t)
    expect(steps[0].output).toBe("RESULT_B")
  })

  it("does not clobber step.output when tools run concurrently", () => {
    // Both tools are in flight at once, so the step-level scalar is ambiguous;
    // the processor leaves it unset and the per-action outputs carry the data.
    const events = [
      stepStart,
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "A",
        tool_args: { query: "a" },
      }),
      ev("tool_execution_start", {
        tool_name: "web_search",
        tool_call_id: "B",
        tool_args: { query: "b" },
      }),
      ev("tool_execution_end", {
        tool_name: "web_search",
        tool_call_id: "A",
        result: { output: "RESULT_A" },
      }),
      ev("tool_execution_end", {
        tool_name: "web_search",
        tool_call_id: "B",
        result: { output: "RESULT_B" },
      }),
    ]

    const steps = processTraceEvents(events as never, t)
    // step.output is left at its initial value, not clobbered by whichever
    // concurrent tool happened to finish last.
    expect(steps[0].output).not.toBe("RESULT_A")
    expect(steps[0].output).not.toBe("RESULT_B")
    const toolActions = steps[0].actions.filter((a) => a.type === "tool")
    expect(toolActions.find((x) => x.data.tool_call_id === "A")?.data.output).toBe(
      "RESULT_A"
    )
    expect(toolActions.find((x) => x.data.tool_call_id === "B")?.data.output).toBe(
      "RESULT_B"
    )
  })

  it("falls back to last running tool when tool_call_id is absent (legacy)", () => {
    const events = [
      stepStart,
      ev("tool_execution_start", {
        tool_name: "calculator",
        tool_args: { expression: "1+1" },
      }),
      ev("tool_execution_end", {
        tool_name: "calculator",
        result: { output: "2" },
      }),
    ]

    const steps = processTraceEvents(events as never, t)
    const toolActions = steps[0].actions.filter((a) => a.type === "tool")
    expect(toolActions).toHaveLength(1)
    expect(toolActions[0].status).toBe("completed")
    expect(toolActions[0].data.output).toBe("2")
  })
})

describe("processTraceEvents unavailable connector placeholder", () => {
  const tc = (key: string, vars?: Record<string, string | number>) =>
    vars?.connector ? `${key}:${vars.connector}` : t(key, vars)
  const failedCall = (toolName: string, result: unknown) =>
    [
      stepStart,
      ev("tool_execution_start", { tool_name: toolName, tool_call_id: "A" }),
      ev("tool_execution_failed", {
        tool_name: toolName,
        tool_call_id: "A",
        error: "MCP server tools could not be loaded.",
        result,
      }),
    ].map((event, index) => ({ ...event, timestamp: index + 1 }))
  const failedToolAction = (toolName: string, title: string) => ({
    id: "event-1",
    type: "tool",
    title: `traceEventRenderer.executeTool:${title}`,
    status: "failed",
    timestamp: 2000,
    data: {
      tool: toolName,
      args: undefined,
      code: "",
      tool_call_id: "A",
      sandboxed: false,
      error: "MCP server tools could not be loaded.",
    },
  })

  it("renders a call carrying unavailable_server as a connector status line", () => {
    const steps = processTraceEvents(
      failedCall("mcp_google_drive_42_unavailable", {
        success: false,
        is_error: true,
        unavailable_server: "Google Drive",
      }) as never,
      tc,
    )

    expect(steps[0].actions).toEqual([
      {
        id: "event-1",
        type: "info",
        title: "traceEventRenderer.connectorUnavailable:Google Drive",
        status: "completed",
        timestamp: 2000,
        data: { statusLine: true },
      },
    ])
  })

  it.each([
    ["a non-empty error", "MCP server credentials are unavailable.", { statusLine: true, error: "MCP server credentials are unavailable." }],
    ["a blank error", "  ", { statusLine: true }],
    ["a non-string error", 42, { statusLine: true }],
  ])("sets the status line detail from result.error given %s", (_, error, data) => {
    const steps = processTraceEvents(
      failedCall("mcp_google_drive_42_unavailable", {
        success: false,
        is_error: true,
        error,
        unavailable_server: "Google Drive",
      }) as never,
      tc,
    )

    expect(steps[0].actions).toEqual([
      expect.objectContaining({ type: "info", data }),
    ])
  })

  it("only converts tool failures into a connector status line", () => {
    const steps = processTraceEvents(
      [
        stepStart,
        ev("dag_step_failed", {
          error: "step failed",
          result: { unavailable_server: "Google Drive" },
        }),
      ].map((event, index) => ({ ...event, timestamp: index + 1 })) as never,
      tc,
    )

    expect(steps[0].actions).toEqual([
      {
        id: "event-1",
        type: "error",
        title: "traceEventRenderer.executionFailed",
        status: "failed",
        timestamp: 2000,
        data: { error: "step failed" },
      },
    ])
  })

  it("keeps an ordinary MCP tool failure as a failed tool call", () => {
    const steps = processTraceEvents(
      failedCall("mcp_notion_search", {
        success: false,
        is_error: true,
        content: [{ text: "boom" }],
      }) as never,
      tc,
    )

    expect(steps[0].actions).toEqual([
      failedToolAction("mcp_notion_search", "Mcp Notion Search"),
    ])
  })

  it.each([
    ["missing", { success: false, is_error: true }],
    ["empty", { success: false, is_error: true, unavailable_server: " " }],
    ["non-string", { success: false, is_error: true, unavailable_server: 42 }],
    ["non-object result", "MCP server tools could not be loaded."],
  ])("falls back to the tool failure when unavailable_server is %s", (_, result) => {
    const steps = processTraceEvents(
      failedCall("mcp_google_drive_42_unavailable", result) as never,
      tc,
    )

    expect(steps[0].actions).toEqual([
      failedToolAction(
        "mcp_google_drive_42_unavailable",
        "Mcp Google Drive 42 Unavailable",
      ),
    ])
  })

  const placeholderFailure = (toolCallId?: string) =>
    ev("tool_execution_failed", {
      tool_name: "mcp_google_drive_42_unavailable",
      ...(toolCallId ? { tool_call_id: toolCallId } : {}),
      error: "MCP server tools could not be loaded.",
      result: { success: false, is_error: true, unavailable_server: "Google Drive" },
    })
  const statusLineAction = (id: string, timestamp: number) => ({
    id,
    type: "info",
    title: "traceEventRenderer.connectorUnavailable:Google Drive",
    status: "completed",
    timestamp,
    data: { statusLine: true },
  })

  const S = "web_search"
  const P = "mcp_google_drive_42_unavailable"
  const start = (tool: string, id?: string) =>
    ev("tool_execution_start", { tool_name: tool, ...(id ? { tool_call_id: id } : {}) })
  const endS = ev("tool_execution_end", {
    tool_name: S,
    tool_call_id: "A",
    result: { output: "RESULT_S" },
  })
  const run = (...events: Array<ReturnType<typeof ev>>) =>
    processTraceEvents(
      [stepStart, ...events, ev("dag_step_end", {})].map((event, index) => ({
        ...event,
        timestamp: index + 1,
      })) as never,
      tc,
    )[0].actions
  const webSearchCards = (actions: ReturnType<typeof run>) =>
    actions.filter((a) => a.data.tool === S)
  const placeholderCards = (actions: ReturnType<typeof run>) =>
    actions.filter((a) => a.data.tool === P)

  it("replaces the placeholder card when a sibling reuses its id and ends later", () => {
    const actions = run(start(S, "A"), start(P, "A"), placeholderFailure("A"), endS)

    expect(actions).toHaveLength(2)
    expect(webSearchCards(actions)).toEqual([
      expect.objectContaining({ status: "completed", data: expect.objectContaining({ output: "RESULT_S" }) }),
    ])
    expect(placeholderCards(actions)).toEqual([])
    expect(actions[1]).toEqual(statusLineAction("event-2", 3000))
  })

  it("appends a status line without removing cards when a sibling reusing the id ends first", () => {
    const actions = run(start(S, "A"), start(P, "A"), endS, placeholderFailure("A"))

    expect(actions).toHaveLength(3)
    // The end lookup ignores tool names (baseline, out of scope): S's result lands on P's card.
    expect(actions[0]).toMatchObject({ type: "tool", status: "completed", data: { tool: S } })
    expect(actions[0].data.output).toBeUndefined()
    expect(actions[1]).toMatchObject({
      type: "tool",
      status: "completed",
      data: { tool: P, output: "RESULT_S" },
    })
    expect(actions[2]).toEqual(statusLineAction("event-4", 5000))
  })

  it.each([
    ["does not match the placeholder card", "B", "C"],
    ["is missing", undefined, undefined],
  ])("appends a status line and keeps every card when the failure id %s", (_, startId, failedId) => {
    const actions = run(start(S, "A"), start(P, startId), placeholderFailure(failedId), endS)

    expect(actions).toHaveLength(3)
    expect(webSearchCards(actions)).toEqual([
      expect.objectContaining({ status: "completed", data: expect.objectContaining({ output: "RESULT_S" }) }),
    ])
    expect(placeholderCards(actions)).toHaveLength(1)
    expect(actions[2]).toEqual(statusLineAction("event-3", 4000))
  })

  it("replaces only the running placeholder card when a completed card shares its id", () => {
    const endP = ev("tool_execution_end", {
      tool_name: P,
      tool_call_id: "A",
      result: { output: "RESULT_P" },
    })
    const actions = run(start(P, "A"), endP, start(P, "A"), placeholderFailure("A"))

    expect(actions).toHaveLength(2)
    expect(actions[0]).toMatchObject({
      type: "tool",
      status: "completed",
      data: { tool: P, output: "RESULT_P" },
    })
    expect(actions[1]).toEqual(statusLineAction("event-3", 4000))
  })

  it("appends a status line when two running cards share the id and tool name", () => {
    const actions = run(start(P, "A"), start(P, "A"), placeholderFailure("A"))

    expect(actions).toHaveLength(3)
    expect(placeholderCards(actions)).toHaveLength(2)
    expect(actions[2]).toEqual(statusLineAction("event-3", 4000))
  })

  it("renders a failure without a matching start as only a status line", () => {
    const events = [stepStart, placeholderFailure("A")].map((event, index) => ({
      ...event,
      timestamp: index + 1,
    }))

    const steps = processTraceEvents(events as never, tc)

    expect(steps[0].actions).toEqual([statusLineAction("event-1", 2000)])
  })
})

describe("getFriendlyToolName", () => {
  it("prettifies an unmapped snake_case tool name", () => {
    expect(getFriendlyToolName("some_future_tool")).toBe("Some Future Tool")
  })

  it("returns empty string for malformed (non-string) input instead of throwing", () => {
    expect(() => getFriendlyToolName(42 as never)).not.toThrow()
    expect(() => getFriendlyToolName({ unexpected: "object" } as never)).not.toThrow()
    expect(() => getFriendlyToolName(null as never)).not.toThrow()
    expect(getFriendlyToolName(42 as never)).toBe("")
    expect(getFriendlyToolName({ unexpected: "object" } as never)).toBe("")
    expect(getFriendlyToolName(null as never)).toBe("")
  })
})

// The mocked useI18n() above (t: key => key) means every other test in this
// file exercises processTraceEvents' own logic, not what the toolNames map
// actually resolves to — deleting the whole map would leave them green. Use
// the real resolver here so a regression in en.ts/zh.ts's toolNames entries,
// or in getFriendlyToolName's lookup path, actually fails a test.
describe("getFriendlyToolName against the real translation trees", () => {
  const realTDynamic = (locale: Locale): TranslateDynamic => (key, fallback) =>
    resolveDynamicTranslation(locale, key, fallback)

  it("resolves a mapped tool name to its curated phrase in both locales", () => {
    expect(getFriendlyToolName("web_search", realTDynamic("en"))).toBe("Searching the web")
    expect(getFriendlyToolName("web_search", realTDynamic("zh"))).toBe("正在搜索网络")
  })

  it("falls back to the prettified raw name for a tool absent from the map", () => {
    expect(getFriendlyToolName("some_future_tool", realTDynamic("en"))).toBe(
      "Some Future Tool",
    )
    expect(getFriendlyToolName("some_future_tool", realTDynamic("zh"))).toBe(
      "Some Future Tool",
    )
  })
})

describe("getRawToolName", () => {
  it("falls through to data.tool_name when response.tool_name is a truthy non-string", () => {
    // response.tool_name and data.tool_name must be checked independently —
    // `a || b` then type-checking the combined result gives up here instead
    // of falling through, because the truthy (but non-string) 42 already
    // won the `||` before either side was ever checked for being a string.
    const event = {
      data: { response: { tool_name: 42 }, tool_name: "web_search" },
    } as never
    expect(getRawToolName(event)).toBe("web_search")
  })

  it("prefers response.tool_name over data.tool_name when both are valid strings", () => {
    const event = {
      data: { response: { tool_name: "fetch_web_content" }, tool_name: "web_search" },
    } as never
    expect(getRawToolName(event)).toBe("fetch_web_content")
  })

  it("returns an empty string when neither field is a string", () => {
    expect(getRawToolName({ data: {} } as never)).toBe("")
    expect(getRawToolName({} as never)).toBe("")
  })
})

describe("getProgressNarrationText", () => {
  it("falls through to content when message is an empty string, via ||", () => {
    // Deliberately || not ?? — an empty message string is falsy under ||
    // (falls through to content) but not under ?? (only null/undefined
    // fall through). A regression back to ?? would silently re-break this.
    const event = { data: { message: "", content: "text" } } as never
    expect(getProgressNarrationText(event)).toBe("text")
  })

  it("prefers message over content when both are present", () => {
    const event = { data: { message: "the message", content: "the content" } } as never
    expect(getProgressNarrationText(event)).toBe("the message")
  })

  it("returns an empty string for a non-string value and for no data at all", () => {
    expect(getProgressNarrationText({ data: { message: 42 } } as never)).toBe("")
    expect(getProgressNarrationText({} as never)).toBe("")
  })
})

describe("every toolNames entry resolves through getFriendlyToolName", () => {
  // The single-key test above only pins web_search; the other 55 entries
  // per locale were unpinned — a typo'd value, or a key present in one
  // locale's source object but silently dropped en route to the resolver,
  // would go unnoticed. Iterate every key actually in the source file
  // (self-referential, so no per-key value needs hand-copying here) and
  // assert getFriendlyToolName resolves it exactly.
  //
  // Typed with `satisfies Partial<…>` rather than annotated
  // `Record<Locale, …>`: a downstream build can replace @/i18n/translations
  // with one that adds locales, widening Locale beyond the source objects
  // this repo ships (src/lib/time-utils.ts types displayDateLocales as a
  // Partial for the same reason, and its test pins that annotation). An
  // exhaustive Record here would demand an entry for a locale core has no
  // module to import, breaking their type-check on a file only this repo
  // owns. `satisfies` still rejects a wrong value shape or a key that is not
  // a Locale at all.
  const toolNames = {
    en: en.traceEventRenderer.toolNames,
    zh: zh.traceEventRenderer.toolNames,
  } satisfies Partial<Record<Locale, Record<string, string>>>

  for (const locale of Object.keys(toolNames) as (keyof typeof toolNames)[]) {
    it(`resolves all ${Object.keys(toolNames[locale]).length} ${locale} entries to their literal source value`, () => {
      const tDynamic = (key: string, fallback: string) =>
        resolveDynamicTranslation(locale, key, fallback)
      for (const [toolName, expected] of Object.entries(toolNames[locale])) {
        expect(getFriendlyToolName(toolName, tDynamic)).toBe(expected)
      }
    })
  }

  it("keeps the same set of tool names mapped in both locales", () => {
    expect(Object.keys(toolNames.en).sort()).toEqual(Object.keys(toolNames.zh).sort())
  })

  it("keeps the fixture's Locale boundary a Partial", () => {
    // Everything above iterates only the keys the fixture actually has, so it
    // would all still pass if the annotation regressed to an exhaustive
    // `Record<Locale, …>`: while Locale is exactly en | zh the two types are
    // interchangeable here, and no runtime assertion can tell them apart. The
    // difference only surfaces in a build that widens Locale, which this repo
    // never runs -- so pin the boundary in the source text, the way
    // src/lib/time-utils.test.ts pins displayDateLocales' Partial.
    //
    // The needle is assembled from fragments rather than written out whole:
    // this guard sits in the file it guards, so a single literal would match
    // its own occurrence and keep passing after the fixture had regressed.
    const boundary = ["} satisfies Partial<Record<Locale, ", "Record<string, string>>>"].join("")
    const source = readFileSync("src/components/chat/trace-event-processing.test.ts", "utf8")

    expect(source).toContain(boundary)
  })
})