cortena-ui 1.4.2 → 1.6.0

package/src/agent-chat/bridge.ts

@@ -0,0 +1,445 @@
+/**
+ * AG-UI events -> the three `AgentChatClient` sinks.
+ *
+ * Ported from `cortena-shared/src/agui/bridge.ts` (Cortena monorepo, DESIGN-37
+ * step 1). `cortena-shared` is not published, so the translation lives here;
+ * keep the two in step. It knows nothing about HTTP or `@ag-ui/client`, which
+ * is why the tests can drive it with a literal array of events.
+ *
+ * One change against the original, and it is the reason this file is not a
+ * copy: **TOOL_CALL_ARGS is handled.** cortenacore's mapper emits
+ * `TOOL_CALL_START` -> `TOOL_CALL_ARGS { toolCallId, delta }` -> `TOOL_CALL_END`
+ * at tool-start time, with the whole argument object stringified into one
+ * `delta`. The original bridge had no case for it, so every tool card in the
+ * AG-UI path showed a name and a spinner and never showed what the tool was
+ * called with. The deltas are accumulated per call id and parsed when they
+ * form valid JSON, which is also correct for a transport that streams the
+ * arguments a fragment at a time.
+ */
+
+import { type A2UIChatBlock, foldA2UIBlocks, readA2UIBlock } from "./a2ui-block";
+import type {
+  AgentApprovalEvent,
+  AgentChatEvent,
+  AgentToolEvent,
+  AgentApprovalDecision,
+} from "./types";
+
+/** The subset of an AG-UI event this bridge reads. */
+export interface AguiIncomingEvent {
+  type: string;
+  messageId?: string;
+  delta?: string;
+  toolCallId?: string;
+  toolCallName?: string;
+  content?: string;
+  message?: string;
+  name?: string;
+  value?: unknown;
+  metadata?: Record<string, unknown>;
+  snapshot?: unknown;
+  outcome?: { type?: string; interrupts?: Array<Record<string, unknown>> };
+}
+
+/** `CUSTOM` event names cortenacore emits that this bridge acts on. */
+export const AGUI_CUSTOM_NAMES = {
+  CHAT_ABORTED: "cortena.chat.aborted",
+  TOOL_PROGRESS: "cortena.tool.progress",
+  APPROVAL_REQUEST: "cortena.approval.request",
+  APPROVAL_RESOLVED: "cortena.approval.resolved",
+  A2UI: "cortena.a2ui",
+} as const;
+
+export interface AgentChatBridgeOptions {
+  runId: string;
+  sessionKey: string;
+  chat: (event: AgentChatEvent) => void;
+  tool?: (event: AgentToolEvent) => void;
+  approval?: (event: AgentApprovalEvent) => void;
+  now?: () => number;
+}
+
+type ContentBlock = {
+  type: "thinking" | "text" | "a2ui";
+  thinking?: string;
+  text?: string;
+  a2ui?: A2UIChatBlock;
+};
+
+const DECISIONS: readonly string[] = ["allow-once", "allow-always", "deny"];
+
+export class AgentChatBridge {
+  readonly runId: string;
+  readonly sessionKey: string;
+
+  private readonly chat: (event: AgentChatEvent) => void;
+  private readonly tool: ((event: AgentToolEvent) => void) | undefined;
+  private readonly approval: ((event: AgentApprovalEvent) => void) | undefined;
+  private readonly now: () => number;
+
+  private seq = 0;
+  /** Text of the assistant message currently streaming. */
+  private text = "";
+  private textMessageId: string | null = null;
+  private reasoning = "";
+  /**
+   * The reasoning accumulated before each assistant message began, by message
+   * id, and the whole of the re-attach defence for the chain of thought.
+   *
+   * A re-attach re-streams the run from the top, so every REASONING delta
+   * arrives a second time. Restoring this snapshot when a message id starts
+   * again rewinds the buffer to exactly the point the first pass reached,
+   * whichever side of `TEXT_MESSAGE_START` the reasoning arrived on.
+   */
+  private readonly reasoningAtStart = new Map<string, string>();
+  /**
+   * A2UI blocks seen this run. The chat treats the content array as a
+   * snapshot, so every emission carries all of them — the same rule the text
+   * follows, and what makes a re-attach land in the same place.
+   */
+  private a2ui: A2UIChatBlock[] = [];
+  /** Accumulated `TOOL_CALL_ARGS` deltas, per tool call id. */
+  private readonly args = new Map<string, string>();
+  /**
+   * A2UI messages already folded onto each surface, by their serialised form.
+   *
+   * A re-attach re-streams the run from the beginning, so every
+   * `CUSTOM cortena.a2ui` arrives again. Folding concatenates, so without this
+   * the surface's message list doubled on the first reconnection and trebled
+   * on the second — a table drawn once, then drawn again underneath itself.
+   */
+  private readonly seenA2ui = new Map<string, Set<string>>();
+  private terminal = false;
+  private readonly pendingInterrupts: Array<Record<string, unknown>> = [];
+
+  constructor(opts: AgentChatBridgeOptions) {
+    this.runId = opts.runId;
+    this.sessionKey = opts.sessionKey;
+    this.chat = opts.chat;
+    this.tool = opts.tool;
+    this.approval = opts.approval;
+    this.now = opts.now ?? (() => Date.now());
+  }
+
+  /** True once RUN_FINISHED or RUN_ERROR has been seen; no retry after this. */
+  get finished(): boolean {
+    return this.terminal;
+  }
+
+  /** Interrupts carried by the terminal RUN_FINISHED, if any. */
+  get interrupts(): ReadonlyArray<Record<string, unknown>> {
+    return this.pendingInterrupts;
+  }
+
+  private blocks(): ContentBlock[] {
+    const content: ContentBlock[] = [];
+    if (this.reasoning) {
+      content.push({ type: "thinking", thinking: this.reasoning });
+    }
+    if (this.text) {
+      content.push({ type: "text", text: this.text });
+    }
+    for (const block of this.a2ui) {
+      content.push({ type: "a2ui", a2ui: block });
+    }
+    return content;
+  }
+
+  private emitDelta(): void {
+    const content = this.blocks();
+    if (content.length === 0) {
+      return;
+    }
+    this.chat({
+      runId: this.runId,
+      sessionKey: this.sessionKey,
+      seq: ++this.seq,
+      state: "delta",
+      message: { role: "assistant", content, timestamp: this.now() },
+    });
+  }
+
+  private emitFinal(interrupted = false): void {
+    const content = this.blocks();
+    this.chat({
+      runId: this.runId,
+      sessionKey: this.sessionKey,
+      seq: ++this.seq,
+      state: "final",
+      // Carried through so the store can tell "the run succeeded" from "the
+      // run is waiting for you". Both arrive as RUN_FINISHED.
+      ...(interrupted ? { interrupted: true } : {}),
+      ...(content.length > 0
+        ? { message: { role: "assistant", content, timestamp: this.now() } }
+        : {}),
+    });
+  }
+
+  /** Surface a transport failure the way a run error is surfaced. */
+  fail(message: string): void {
+    if (this.terminal) {
+      return;
+    }
+    this.terminal = true;
+    this.chat({
+      runId: this.runId,
+      sessionKey: this.sessionKey,
+      seq: ++this.seq,
+      state: "error",
+      errorMessage: message,
+    });
+  }
+
+  handleEvent(event: AguiIncomingEvent): void {
+    switch (event.type) {
+      case "RUN_STARTED":
+        // The run begins here, so the streaming buffers do too. This is the
+        // only place the chain of thought is cleared outright.
+        this.textMessageId = null;
+        this.text = "";
+        this.reasoning = "";
+        break;
+      case "TEXT_MESSAGE_START": {
+        // A new assistant message replaces the text buffer, and *only* the
+        // text buffer. cortenacore emits the REASONING deltas before the
+        // message they explain, so clearing the reasoning here threw away the
+        // chain of thought a moment after it arrived — the thinking block
+        // never rendered at all. Re-attach doubling is handled instead by
+        // rewinding to the snapshot taken when this message id first started.
+        const id = event.messageId ?? null;
+        this.textMessageId = id;
+        this.text = "";
+        if (id !== null) {
+          const before = this.reasoningAtStart.get(id);
+          if (before === undefined) {
+            this.reasoningAtStart.set(id, this.reasoning);
+          } else {
+            this.reasoning = before;
+          }
+        }
+        break;
+      }
+      case "TEXT_MESSAGE_CONTENT":
+        if (event.messageId && event.messageId !== this.textMessageId) {
+          this.textMessageId = event.messageId;
+          this.text = "";
+        }
+        this.text += event.delta ?? "";
+        this.emitDelta();
+        break;
+      case "REASONING_MESSAGE_CONTENT":
+        this.reasoning += event.delta ?? "";
+        this.emitDelta();
+        break;
+      case "TOOL_CALL_START":
+        this.tool?.({
+          event: "tool.start",
+          data: {
+            ...(event.toolCallId === undefined ? {} : { id: event.toolCallId }),
+            ...(event.toolCallName === undefined ? {} : { name: event.toolCallName }),
+            startedAt: this.now(),
+          },
+        });
+        break;
+      case "TOOL_CALL_ARGS":
+        this.accumulateArgs(event);
+        break;
+      case "TOOL_CALL_END":
+        // Nothing more will arrive for this call's arguments; emit whatever
+        // accumulated, even when it never parsed, so the card shows something.
+        this.flushArgs(event.toolCallId);
+        break;
+      case "TOOL_CALL_RESULT":
+        // The metadata travels WITH the event. It carries `isError`, and the
+        // `meta` a Cortena tool attaches to a failure — the status, the code
+        // and the message — and it is the only trustworthy account of how the
+        // call went. Dropping it here is what forced the store to guess at an
+        // envelope inside `content`, and the guess was wrong for every real
+        // result cortenacore emits.
+        this.tool?.({
+          event: event.metadata?.isError === true ? "tool.error" : "tool.complete",
+          data: {
+            ...(event.toolCallId === undefined ? {} : { id: event.toolCallId }),
+            output: event.content,
+            ...(event.metadata ? { metadata: event.metadata } : {}),
+            completedAt: this.now(),
+          },
+        });
+        break;
+      case "CUSTOM":
+        this.handleCustom(event);
+        break;
+      case "RUN_FINISHED": {
+        this.terminal = true;
+        const interrupted = event.outcome?.type === "interrupt";
+        if (interrupted) {
+          this.pendingInterrupts.push(...(event.outcome?.interrupts ?? []));
+        }
+        this.emitFinal(interrupted);
+        break;
+      }
+      case "RUN_ERROR":
+        this.terminal = true;
+        this.chat({
+          runId: this.runId,
+          sessionKey: this.sessionKey,
+          seq: ++this.seq,
+          state: "error",
+          errorMessage: event.message ?? "An error occurred",
+        });
+        break;
+      default:
+        break;
+    }
+  }
+
+  /**
+   * Accumulate one `TOOL_CALL_ARGS` delta and publish the best reading of it.
+   *
+   * Published on every delta rather than only at `TOOL_CALL_END`, because a
+   * run that is interrupted between the two — an approval, an abort, a dropped
+   * stream — would otherwise show a tool card with no input at all, which is
+   * the state the card exists to avoid.
+   */
+  private accumulateArgs(event: AguiIncomingEvent): void {
+    const id = event.toolCallId;
+    if (!id) {
+      return;
+    }
+    const next = (this.args.get(id) ?? "") + (event.delta ?? "");
+    this.args.set(id, next);
+    this.publishArgs(id, next);
+  }
+
+  private flushArgs(id?: string): void {
+    if (!id) {
+      return;
+    }
+    const raw = this.args.get(id);
+    if (raw === undefined) {
+      return;
+    }
+    this.args.delete(id);
+    this.publishArgs(id, raw);
+  }
+
+  private publishArgs(id: string, raw: string): void {
+    if (!raw) {
+      return;
+    }
+    this.tool?.({ event: "tool.args", data: { id, input: parseArgs(raw) } });
+  }
+
+  /**
+   * The block with any message this surface has already been sent removed;
+   * `null` when nothing in it is new.
+   */
+  private freshA2UI(block: A2UIChatBlock | null): A2UIChatBlock | null {
+    if (!block) {
+      return null;
+    }
+    let seen = this.seenA2ui.get(block.surfaceId);
+    if (!seen) {
+      seen = new Set();
+      this.seenA2ui.set(block.surfaceId, seen);
+    }
+    const messages: unknown[] = [];
+    for (const message of block.messages) {
+      const key = stableKey(message);
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      messages.push(message);
+    }
+    // An error still deserves a card even when its messages are all repeats.
+    if (messages.length === 0 && !block.error) {
+      return null;
+    }
+    return { ...block, messages };
+  }
+
+  private handleCustom(event: AguiIncomingEvent): void {
+    const value = (event.value ?? {}) as Record<string, unknown>;
+    const id = typeof value.id === "string" ? value.id : "";
+    switch (event.name) {
+      case AGUI_CUSTOM_NAMES.TOOL_PROGRESS:
+        this.tool?.({
+          event: "tool.progress",
+          data: {
+            ...(typeof value.toolCallId === "string" ? { id: value.toolCallId } : {}),
+            output: value.partialResult,
+          },
+        });
+        break;
+      case AGUI_CUSTOM_NAMES.APPROVAL_REQUEST: {
+        const request = (value.request ?? {}) as Record<string, unknown>;
+        this.approval?.({
+          type: "request",
+          request: {
+            id,
+            toolName: typeof request.command === "string" ? request.command : "exec",
+            args: request,
+            timestamp: typeof value.createdAtMs === "number" ? value.createdAtMs : this.now(),
+            // Captured here, where the run and the session are facts about the
+            // event rather than about whatever is in flight when the user
+            // eventually presses a button.
+            runId: this.runId,
+            sessionKey: this.sessionKey,
+          },
+        });
+        break;
+      }
+      case AGUI_CUSTOM_NAMES.A2UI: {
+        // One event per block; folding here means two pushes to one surface
+        // reach the renderer as a single message list, which is how a surface
+        // the agent streams in pieces ends up drawn once.
+        const block = this.freshA2UI(readA2UIBlock(value));
+        if (block) {
+          this.a2ui = foldA2UIBlocks([...this.a2ui, block]);
+          this.emitDelta();
+        }
+        break;
+      }
+      case AGUI_CUSTOM_NAMES.APPROVAL_RESOLVED:
+        this.approval?.({
+          type: "resolved",
+          id,
+          decision:
+            typeof value.decision === "string" && DECISIONS.includes(value.decision)
+              ? (value.decision as AgentApprovalDecision)
+              : null,
+        });
+        break;
+      default:
+        // cortena.chat.aborted needs no change here: abort() has already reset
+        // the local streaming state before the request went out.
+        break;
+    }
+  }
+}
+
+/**
+ * A message's identity for de-duplication.
+ *
+ * `JSON.stringify` is enough: these are payloads the transport just parsed out
+ * of JSON, so key order is the order the server wrote, and the same message
+ * arriving twice on a re-attach serialises identically both times.
+ */
+function stableKey(message: unknown): string {
+  try {
+    return JSON.stringify(message) ?? "undefined";
+  } catch {
+    // Circular, which a JSON transport cannot produce. Never equal to anything.
+    return `${Math.random()}`;
+  }
+}
+
+/** Arguments as an object when the accumulation parses, as the raw text otherwise. */
+function parseArgs(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}