@checkstack/ai-frontend 0.1.0

package/src/lib/stream-parser.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "bun:test";
+import {
+  asAppliedCard,
+  asConfirmCard,
+  chunkToEvent,
+  parseSseBuffer,
+  readChatStream,
+  type ChatStreamEvent,
+} from "./stream-parser";
+
+describe("asConfirmCard", () => {
+  test("recognises a well-formed confirm card", () => {
+    const card = asConfirmCard({
+      __confirm: true,
+      toolName: "automation.propose",
+      effect: "mutate",
+      summary: "Create automation X",
+      token: "propose:abc.def",
+      payload: { name: "X" },
+      expiresAt: "2026-06-01T00:10:00Z",
+    });
+    expect(card?.toolName).toBe("automation.propose");
+    expect(card?.effect).toBe("mutate");
+    expect(card?.token).toBe("propose:abc.def");
+  });
+
+  test("rejects a non-card object", () => {
+    expect(asConfirmCard({ rows: [] })).toBeUndefined();
+    expect(asConfirmCard({ __confirm: true, toolName: 1 })).toBeUndefined();
+    expect(asConfirmCard(null)).toBeUndefined();
+    expect(asConfirmCard("text")).toBeUndefined();
+  });
+
+  test("parses an update card's before -> after diff", () => {
+    const card = asConfirmCard({
+      __confirm: true,
+      toolName: "healthcheck.update",
+      effect: "mutate",
+      summary: "Update X",
+      token: "propose:1.2",
+      payload: {},
+      diff: [{ path: "intervalSeconds", before: 60, after: 30 }],
+      expiresAt: "2026-06-01T00:10:00Z",
+    });
+    expect(card?.diff).toEqual([
+      { path: "intervalSeconds", before: 60, after: 30 },
+    ]);
+  });
+});
+
+describe("asAppliedCard", () => {
+  test("recognises an auto-applied result with its diff", () => {
+    const card = asAppliedCard({
+      __applied: true,
+      toolName: "healthcheck.update",
+      summary: "Updated X",
+      result: { id: "hc1" },
+      diff: [{ path: "intervalSeconds", before: 60, after: 30 }],
+    });
+    expect(card?.toolName).toBe("healthcheck.update");
+    expect(card?.diff).toHaveLength(1);
+    expect(card?.result).toEqual({ id: "hc1" });
+  });
+
+  test("rejects a non-applied object", () => {
+    expect(asAppliedCard({ __confirm: true })).toBeUndefined();
+    expect(asAppliedCard({ __applied: true, toolName: 1 })).toBeUndefined();
+    expect(asAppliedCard(null)).toBeUndefined();
+  });
+});
+
+describe("chunkToEvent", () => {
+  test("maps text-delta and text chunks", () => {
+    expect(chunkToEvent({ type: "text-delta", delta: "Hi" })).toEqual({
+      type: "text-delta",
+      delta: "Hi",
+    });
+    expect(chunkToEvent({ type: "text", text: "Yo" })).toEqual({
+      type: "text-delta",
+      delta: "Yo",
+    });
+  });
+
+  test("maps a tool-input-available chunk to a tool-call event", () => {
+    expect(
+      chunkToEvent({
+        type: "tool-input-available",
+        toolCallId: "c1",
+        toolName: "incident.list",
+      }),
+    ).toEqual({ type: "tool-call", toolCallId: "c1", toolName: "incident.list" });
+  });
+
+  test("maps a tool-input-start chunk to a tool-call event", () => {
+    expect(
+      chunkToEvent({
+        type: "tool-input-start",
+        toolCallId: "c2",
+        toolName: "listCapabilities",
+      }),
+    ).toEqual({ type: "tool-call", toolCallId: "c2", toolName: "listCapabilities" });
+  });
+
+  test("maps a tool output carrying a confirm card to a confirm-card event", () => {
+    const event = chunkToEvent({
+      type: "tool-output-available",
+      toolCallId: "c3",
+      output: {
+        __confirm: true,
+        toolName: "automation.propose",
+        effect: "mutate",
+        summary: "do it",
+        token: "propose:1.2",
+        payload: {},
+        expiresAt: "2026-06-01T00:10:00Z",
+      },
+    });
+    expect(event).toMatchObject({ type: "confirm-card", toolCallId: "c3" });
+  });
+
+  test("a read tool output (no card) yields a tool-result event", () => {
+    expect(
+      chunkToEvent({
+        type: "tool-output-available",
+        toolCallId: "c4",
+        output: { rows: [] },
+      }),
+    ).toEqual({ type: "tool-result", toolCallId: "c4" });
+  });
+
+  test("maps a tool output carrying an auto-applied result to an applied-card event", () => {
+    const event = chunkToEvent({
+      type: "tool-output-available",
+      toolCallId: "c7",
+      output: {
+        __applied: true,
+        toolName: "automation.update",
+        summary: "Updated",
+        result: { id: "a1" },
+      },
+    });
+    expect(event).toMatchObject({ type: "applied-card", toolCallId: "c7" });
+  });
+
+  test("maps a tool-output-error chunk to a tool-error event", () => {
+    expect(
+      chunkToEvent({
+        type: "tool-output-error",
+        toolCallId: "c5",
+        errorText: "Not allowed to read the automation capability catalog",
+      }),
+    ).toEqual({
+      type: "tool-error",
+      toolCallId: "c5",
+      message: "Not allowed to read the automation capability catalog",
+    });
+  });
+
+  test("maps a tool-input-error chunk to a tool-error event with the tool name", () => {
+    expect(
+      chunkToEvent({
+        type: "tool-input-error",
+        toolCallId: "c6",
+        toolName: "getCapabilitySchema",
+        errorText: "invalid input",
+      }),
+    ).toEqual({
+      type: "tool-error",
+      toolCallId: "c6",
+      toolName: "getCapabilitySchema",
+      message: "invalid input",
+    });
+  });
+
+  test("maps an error chunk", () => {
+    expect(chunkToEvent({ type: "error", errorText: "boom" })).toEqual({
+      type: "error",
+      message: "boom",
+    });
+  });
+
+  test("ignores unknown chunk types", () => {
+    expect(chunkToEvent({ type: "start" })).toBeUndefined();
+    expect(chunkToEvent(42)).toBeUndefined();
+  });
+});
+
+describe("parseSseBuffer", () => {
+  test("extracts complete data payloads and keeps the partial remainder", () => {
+    const buf =
+      'data: {"type":"text-delta","delta":"a"}\n\n' +
+      'data: {"type":"text-delta","delta":"b"}\n\n' +
+      'data: {"type":"text-delta","del'; // incomplete trailing event
+    const { payloads, rest } = parseSseBuffer(buf);
+    expect(payloads).toHaveLength(2);
+    expect(rest).toContain('"del');
+  });
+
+  test("surfaces the [DONE] sentinel", () => {
+    const { payloads } = parseSseBuffer("data: [DONE]\n\n");
+    expect(payloads).toEqual(["[DONE]"]);
+  });
+});
+
+/** Build a ReadableStream of UTF-8 bytes from string chunks. */
+function streamOf(chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  let i = 0;
+  return new ReadableStream<Uint8Array>({
+    pull(controller) {
+      if (i < chunks.length) {
+        controller.enqueue(encoder.encode(chunks[i++]));
+      } else {
+        controller.close();
+      }
+    },
+  });
+}
+
+describe("readChatStream (DOM-free)", () => {
+  test("yields text deltas, a confirm card, then done across chunk boundaries", async () => {
+    const stream = streamOf([
+      'data: {"type":"text-delta","delta":"Hello "}\n\n',
+      'data: {"type":"text-de', // split mid-event
+      'lta","delta":"world"}\n\n',
+      'data: {"type":"tool-output-available","output":{"__confirm":true,"toolName":"automation.propose","effect":"mutate","summary":"s","token":"propose:1.2","payload":{},"expiresAt":"2026-06-01T00:10:00Z"}}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    for await (const e of readChatStream(stream)) events.push(e);
+
+    const text = events
+      .filter((e): e is { type: "text-delta"; delta: string } => e.type === "text-delta")
+      .map((e) => e.delta)
+      .join("");
+    expect(text).toBe("Hello world");
+    expect(events.some((e) => e.type === "confirm-card")).toBe(true);
+    expect(events.at(-1)?.type).toBe("done");
+  });
+});

package/src/lib/stream-parser.ts

@@ -0,0 +1,286 @@
+/**
+ * DOM-free parser for the AI-SDK UI message SSE stream (Phase 4 chat).
+ *
+ * The backend streams the Vercel-AI-SDK UI message stream as Server-Sent
+ * Events: lines of `data: <json>` separated by blank lines. This module turns a
+ * byte stream into incremental, typed chat events WITHOUT touching the DOM, so
+ * the streaming logic is unit-testable under `bun test` (which CI runs from the
+ * repo root WITHOUT happy-dom). React components consume these events; they are
+ * never tested via render.
+ */
+
+/** One changed field in a before -> after diff (mirrors ai-common AiFieldDiff). */
+export interface FieldDiff {
+  path: string;
+  before: unknown;
+  after: unknown;
+}
+
+/** A confirm card emitted when a mutate/destructive tool was proposed. */
+export interface ConfirmCard {
+  toolName: string;
+  effect: "mutate" | "destructive";
+  summary: string;
+  token: string;
+  payload: unknown;
+  /** Optional before -> after diff for an update proposal. */
+  diff?: FieldDiff[];
+  expiresAt: string;
+}
+
+/**
+ * An "applied" card emitted when a mutate tool AUTO-APPLIED (auto mode): the
+ * change already took effect, so it is read-only. Surfaced so the operator
+ * ALWAYS sees what changed/created, even when no confirmation was required.
+ */
+export interface AppliedCard {
+  toolName: string;
+  summary: string;
+  /** Optional before -> after diff for an auto-applied update. */
+  diff?: FieldDiff[];
+  /** The applied result (e.g. the created/updated object), for display. */
+  result: unknown;
+}
+
+/**
+ * Incremental events surfaced to the chat UI. Tool events carry the SDK's
+ * `toolCallId` so the reducer can correlate a tool call with its later result /
+ * error / confirm-card chunk and render them as one ordered, in-place part.
+ */
+export type ChatStreamEvent =
+  | { type: "text-delta"; delta: string }
+  | { type: "tool-call"; toolCallId: string; toolName: string }
+  | { type: "tool-result"; toolCallId: string }
+  | { type: "tool-error"; toolCallId: string; toolName?: string; message: string }
+  | { type: "confirm-card"; toolCallId: string; card: ConfirmCard }
+  | { type: "applied-card"; toolCallId: string; card: AppliedCard }
+  | { type: "error"; message: string }
+  | { type: "done" };
+
+/** True when the value is a record (object), narrowing `unknown` safely. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Narrow a parsed JSON value into a FieldDiff[] if it has the shape. */
+function asFieldDiff(value: unknown): FieldDiff[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const diffs: FieldDiff[] = [];
+  for (const entry of value) {
+    if (isRecord(entry) && typeof entry.path === "string") {
+      diffs.push({ path: entry.path, before: entry.before, after: entry.after });
+    }
+  }
+  return diffs.length > 0 ? diffs : undefined;
+}
+
+/** Narrow a parsed JSON object into a ConfirmCard if it has the shape. */
+export function asConfirmCard(value: unknown): ConfirmCard | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.__confirm !== true) return undefined;
+  const { toolName, effect, summary, token, payload, expiresAt } = value;
+  if (
+    typeof toolName !== "string" ||
+    (effect !== "mutate" && effect !== "destructive") ||
+    typeof summary !== "string" ||
+    typeof token !== "string" ||
+    typeof expiresAt !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    toolName,
+    effect,
+    summary,
+    token,
+    payload,
+    diff: asFieldDiff(value.diff),
+    expiresAt,
+  };
+}
+
+/** Narrow a parsed JSON object into an AppliedCard (auto-applied result). */
+export function asAppliedCard(value: unknown): AppliedCard | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.__applied !== true) return undefined;
+  const { toolName, summary, result } = value;
+  if (typeof toolName !== "string" || typeof summary !== "string") {
+    return undefined;
+  }
+  return { toolName, summary, result, diff: asFieldDiff(value.diff) };
+}
+
+/** Read a chunk's `toolCallId` (empty string when absent — defensive). */
+function asToolCallId(chunk: Record<string, unknown>): string {
+  return typeof chunk.toolCallId === "string" ? chunk.toolCallId : "";
+}
+
+/** Read a chunk's `errorText`, falling back to a generic message. */
+function asErrorText(chunk: Record<string, unknown>, fallback: string): string {
+  return typeof chunk.errorText === "string" ? chunk.errorText : fallback;
+}
+
+/**
+ * Map a single decoded AI-SDK UI-message-stream chunk to a chat event.
+ *
+ * The AI SDK chunk shapes used here (v6 UI message stream):
+ *  - `{ type: "text-delta", delta }` / `{ type: "text", text }` -> text
+ *  - `{ type: "tool-input-start" | "tool-input-available", toolCallId, toolName }`
+ *    -> a tool was called (de-duplicated by id in the reducer).
+ *  - `{ type: "tool-output-available", toolCallId, output }` -> a tool result; a
+ *    confirm-card return value is detected via `asConfirmCard`, otherwise it is a
+ *    plain read result that just marks the tool call done.
+ *  - `{ type: "tool-output-error", toolCallId, errorText }` -> a tool's `execute`
+ *    THREW. Without this branch a failing read tool (e.g. `listCapabilities`)
+ *    produced a silent EMPTY bubble: the SDK never routes a tool error through
+ *    the stream's `onError` (that is for stream/provider failures), so it would
+ *    be dropped entirely.
+ *  - `{ type: "tool-input-error", toolCallId, toolName, errorText }` -> the model
+ *    produced invalid tool arguments; surfaced the same way.
+ *  - `{ type: "error", errorText }` -> a stream/provider error.
+ * Unknown chunk types yield `undefined` (ignored).
+ */
+export function chunkToEvent(chunk: unknown): ChatStreamEvent | undefined {
+  if (!isRecord(chunk)) return undefined;
+  const type = chunk.type;
+
+  if (type === "text-delta" && typeof chunk.delta === "string") {
+    return { type: "text-delta", delta: chunk.delta };
+  }
+  if (type === "text" && typeof chunk.text === "string") {
+    return { type: "text-delta", delta: chunk.text };
+  }
+  if (
+    (type === "tool-input-available" ||
+      type === "tool-input-start" ||
+      type === "tool-call") &&
+    typeof chunk.toolName === "string"
+  ) {
+    return {
+      type: "tool-call",
+      toolCallId: asToolCallId(chunk),
+      toolName: chunk.toolName,
+    };
+  }
+  // The model produced invalid tool arguments (input never became available).
+  if (type === "tool-input-error") {
+    return {
+      type: "tool-error",
+      toolCallId: asToolCallId(chunk),
+      toolName: typeof chunk.toolName === "string" ? chunk.toolName : undefined,
+      message: asErrorText(chunk, "Invalid tool input"),
+    };
+  }
+  // Tool result chunks: a confirm card, otherwise a plain read result.
+  if (
+    type === "tool-output-available" ||
+    type === "tool-result" ||
+    type === "tool-output"
+  ) {
+    const output =
+      "output" in chunk ? chunk.output : "result" in chunk ? chunk.result : undefined;
+    const card = asConfirmCard(output);
+    if (card) {
+      return { type: "confirm-card", toolCallId: asToolCallId(chunk), card };
+    }
+    const applied = asAppliedCard(output);
+    if (applied) {
+      return { type: "applied-card", toolCallId: asToolCallId(chunk), card: applied };
+    }
+    return { type: "tool-result", toolCallId: asToolCallId(chunk) };
+  }
+  // A tool's `execute` threw (e.g. an authz/read failure inside the tool).
+  if (type === "tool-output-error") {
+    return {
+      type: "tool-error",
+      toolCallId: asToolCallId(chunk),
+      message: asErrorText(chunk, "Tool failed"),
+    };
+  }
+  if (type === "error") {
+    const message =
+      typeof chunk.errorText === "string"
+        ? chunk.errorText
+        : typeof chunk.error === "string"
+          ? chunk.error
+          : "Stream error";
+    return { type: "error", message };
+  }
+  return undefined;
+}
+
+/**
+ * Split a buffer of SSE text into complete `data:` JSON payloads, returning the
+ * parsed payloads plus the unconsumed remainder (an incomplete trailing event).
+ * SSE events are separated by a blank line; each event has one or more
+ * `data: ...` lines. The `[DONE]` sentinel is surfaced as `done`.
+ */
+export function parseSseBuffer(buffer: string): {
+  payloads: Array<unknown | "[DONE]">;
+  rest: string;
+} {
+  const payloads: Array<unknown | "[DONE]"> = [];
+  // Events end at a blank line (\n\n). Keep the trailing partial event in `rest`.
+  const parts = buffer.split("\n\n");
+  const rest = parts.pop() ?? "";
+  for (const event of parts) {
+    for (const line of event.split("\n")) {
+      const trimmed = line.trimStart();
+      if (!trimmed.startsWith("data:")) continue;
+      const data = trimmed.slice("data:".length).trim();
+      if (data === "[DONE]") {
+        payloads.push("[DONE]");
+        continue;
+      }
+      if (!data) continue;
+      try {
+        payloads.push(JSON.parse(data));
+      } catch {
+        // Ignore malformed JSON lines (defensive).
+      }
+    }
+  }
+  return { payloads, rest };
+}
+
+/**
+ * Consume a ReadableStream of SSE bytes, yielding {@link ChatStreamEvent}s. Pure
+ * w.r.t. the DOM — it only needs a `ReadableStream<Uint8Array>` (as returned by
+ * `fetch().body`) and `TextDecoder`, both available in node/bun and the browser.
+ */
+export async function* readChatStream(
+  stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<ChatStreamEvent> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const { payloads, rest } = parseSseBuffer(buffer);
+      buffer = rest;
+      for (const payload of payloads) {
+        if (payload === "[DONE]") {
+          yield { type: "done" };
+          continue;
+        }
+        const event = chunkToEvent(payload);
+        if (event) yield event;
+      }
+    }
+    // Flush any trailing complete event left in the buffer.
+    const { payloads } = parseSseBuffer(buffer + "\n\n");
+    for (const payload of payloads) {
+      if (payload === "[DONE]") {
+        yield { type: "done" };
+        continue;
+      }
+      const event = chunkToEvent(payload);
+      if (event) yield event;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/lib/use-chat-turn.ts

@@ -0,0 +1,163 @@
+import { useCallback, useRef, useState } from "react";
+import { useApi, fetchApiRef } from "@checkstack/frontend-api";
+import { pluginMetadata } from "@checkstack/ai-common";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  appendUserMessage,
+  startAssistantMessage,
+  applyStreamEvent,
+  finishAssistantMessage,
+  type ChatMessage,
+} from "./chat-state";
+import { readChatStream } from "./stream-parser";
+
+/** Generate a client-side message id (crypto.randomUUID is widely available). */
+function newId(): string {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * React hook that drives ONE streaming chat turn against /api/ai/chat. The
+ * heavy lifting (SSE parsing, state folding) lives in DOM-free, unit-tested
+ * modules (`stream-parser`, `chat-state`); this hook only wires them to React
+ * state and the platform `fetch` (which carries auth + base URL). Credentials
+ * never reach the browser — the response is a token/tool-event stream only.
+ */
+export function useChatTurn({
+  initialMessages = [],
+}: {
+  initialMessages?: ChatMessage[];
+} = {}) {
+  const fetchApi = useApi(fetchApiRef);
+  const [messages, setMessages] = useState<ChatMessage[]>(initialMessages);
+  const [streaming, setStreaming] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+  const aborter = useRef<AbortController | undefined>();
+
+  // Shared streaming driver: POST `body` to /chat, start a fresh assistant
+  // message (optionally appending a user message first), and fold the SSE
+  // events into it. Used by both `send` (a user turn) and `sendDecision` (a
+  // confirm-card acknowledgment, which has no user bubble).
+  const runStream = useCallback(
+    async ({
+      body,
+      userText,
+    }: {
+      body: Record<string, unknown>;
+      userText?: string;
+    }) => {
+      setError(undefined);
+      setStreaming(true);
+      setMessages((prev) => {
+        const base =
+          userText === undefined
+            ? prev
+            : appendUserMessage({ messages: prev, id: newId(), text: userText });
+        return startAssistantMessage({ messages: base, id: newId() });
+      });
+      const controller = new AbortController();
+      aborter.current = controller;
+      try {
+        const response = await fetchApi
+          .forPlugin(pluginMetadata.pluginId)
+          .fetch("/chat", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+          });
+        if (!response.ok || !response.body) {
+          const detail = await response.text().catch(() => "");
+          throw new Error(detail || `Chat failed (${response.status})`);
+        }
+        for await (const event of readChatStream(response.body)) {
+          // An in-stream error (the server's onError surfaced a provider/stream
+          // failure, e.g. a 400 `invalid_prompt`) arrives as a normal stream
+          // event, NOT a thrown exception, so the catch below never runs. Lift
+          // it into the durable `error` state so a post-turn message refetch
+          // (which re-hydrates from the persisted transcript that never captured
+          // this failed turn) cannot wipe it from view.
+          if (event.type === "error") setError(event.message);
+          setMessages((prev) => applyStreamEvent({ messages: prev, event }));
+        }
+      } catch (error_) {
+        const message = extractErrorMessage(error_, "Chat turn failed");
+        setError(message);
+        setMessages((prev) =>
+          applyStreamEvent({ messages: prev, event: { type: "error", message } }),
+        );
+      } finally {
+        setMessages((prev) => finishAssistantMessage({ messages: prev }));
+        setStreaming(false);
+        aborter.current = undefined;
+      }
+    },
+    [fetchApi],
+  );
+
+  const send = useCallback(
+    ({
+      conversationId,
+      connectionId,
+      model,
+      text,
+    }: {
+      conversationId: string;
+      connectionId: string;
+      model?: string;
+      text: string;
+    }) =>
+      runStream({
+        body: { conversationId, connectionId, model, message: text },
+        userText: text,
+      }),
+    [runStream],
+  );
+
+  // Stream the model's acknowledgment after the operator applies/declines a
+  // confirm card. The actual apply ran via `applyTool`; this only makes the
+  // model react (no user bubble is added).
+  const sendDecision = useCallback(
+    ({
+      conversationId,
+      connectionId,
+      model,
+      token,
+      decision,
+    }: {
+      conversationId: string;
+      connectionId: string;
+      model?: string;
+      token: string;
+      decision: "apply" | "decline";
+    }) =>
+      runStream({
+        body: {
+          conversationId,
+          connectionId,
+          model,
+          decision: { token, kind: decision },
+        },
+      }),
+    [runStream],
+  );
+
+  const stop = useCallback(() => {
+    aborter.current?.abort();
+  }, []);
+
+  const clearError = useCallback(() => setError(undefined), []);
+
+  return {
+    messages,
+    setMessages,
+    streaming,
+    error,
+    send,
+    sendDecision,
+    stop,
+    clearError,
+  };
+}