@runtypelabs/persona 4.17.0 → 4.18.0

package/src/utils/history-messages.test.ts

@@ -0,0 +1,284 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+import type { AgentWidgetMessage } from "../types";
+import {
+  isHistoryDisplayUnavailable,
+  mapWireMessages,
+  mergeWireMessagesById,
+  type HistoryWireConversationSummary,
+  type HistoryWireMessage,
+} from "./history-messages";
+
+type HistoryWireFixture = {
+  list: HistoryWireConversationSummary[];
+  detail: {
+    id: string;
+    messages: HistoryWireMessage[];
+    nextMessageCursor: string | null;
+  };
+};
+
+const fixture = JSON.parse(
+  readFileSync(
+    new URL("./__fixtures__/client-conversation-history-wire.json", import.meta.url),
+    "utf8"
+  )
+) as HistoryWireFixture;
+
+function byId(messages: AgentWidgetMessage[]) {
+  return new Map(messages.map((message) => [message.id, message]));
+}
+
+describe("mapWireMessages: fixture parity", () => {
+  const mapped = mapWireMessages(fixture.detail.messages);
+  const messages = byId(mapped);
+
+  it("keeps every renderable wire message in server order", () => {
+    expect(mapped.map((message) => message.id)).toEqual([
+      "msg_string",
+      "msg_divergent",
+      "msg_empty_projection",
+      "msg_hidden_llm_content",
+      "msg_raw_directive",
+      "msg_image",
+      "msg_file",
+      "msg_absent_content",
+      "msg_terminal_finalized",
+    ]);
+  });
+
+  it("renders an ordinary string message as-is", () => {
+    const message = messages.get("msg_string")!;
+    expect(message.role).toBe("user");
+    expect(message.content).toBe("Where is my order?");
+    expect(message.createdAt).toBe("2026-02-01T00:00:00.000Z");
+    expect(message.contentParts).toBeUndefined();
+    expect(message.llmContent).toBeUndefined();
+  });
+
+  it("renders the display projection and leaks no model content", () => {
+    const message = messages.get("msg_divergent")!;
+    expect(message.content).toBe("Order A-1 is on its way.");
+    const serialized = JSON.stringify(message);
+    expect(serialized).not.toContain("directive");
+    expect(serialized).not.toContain("order_card");
+    expect(message.llmContent).toBeUndefined();
+    expect(message.rawContent).toBeUndefined();
+  });
+
+  it("treats a deliberately empty projection as empty, not as a fallback", () => {
+    const message = messages.get("msg_empty_projection")!;
+    expect(message.content).toBe("");
+    expect(JSON.stringify(message)).not.toContain("open_modal");
+    expect(isHistoryDisplayUnavailable(message)).toBe(false);
+  });
+
+  it("marks withheld messages unavailable without any model-only fragment", () => {
+    for (const id of ["msg_hidden_llm_content", "msg_raw_directive", "msg_absent_content"]) {
+      const message = messages.get(id)!;
+      expect(message.content).toBe("");
+      expect(isHistoryDisplayUnavailable(message)).toBe(true);
+      expect(message.contentParts).toBeUndefined();
+      expect(message.llmContent).toBeUndefined();
+      expect(message.rawContent).toBeUndefined();
+      // Nothing beyond identity, an empty body, and the marker survives.
+      expect(Object.keys(message).sort()).toEqual([
+        "agentMetadata",
+        "content",
+        "createdAt",
+        "id",
+        "role",
+      ]);
+      expect(JSON.stringify(message)).not.toContain("order_card");
+    }
+  });
+
+  it("maps image parts through the multi-modal helpers", () => {
+    const message = messages.get("msg_image")!;
+    expect(message.contentParts).toEqual([
+      { type: "text", text: "Looks like this:" },
+      { type: "image", image: "data:image/png;base64,AAAA" },
+    ]);
+    expect(message.content).toBe("Looks like this:");
+  });
+
+  it("maps file parts and falls back to empty visible text", () => {
+    const message = messages.get("msg_file")!;
+    expect(message.contentParts).toEqual([
+      {
+        type: "file",
+        data: "ZmFrZQ==",
+        mimeType: "application/pdf",
+        filename: "receipt.pdf",
+      },
+    ]);
+    expect(message.content).toBe("");
+  });
+
+  it("shows the finalized projection on the terminal assistant turn", () => {
+    const message = messages.get("msg_terminal_finalized")!;
+    expect(message.role).toBe("assistant");
+    expect(message.content).toBe("It is in transit and arrives Thursday.");
+    const serialized = JSON.stringify(message);
+    expect(serialized).not.toContain("in_transit");
+    expect(serialized).not.toContain("track");
+  });
+
+  it("never fabricates a model channel for any mapped message", () => {
+    for (const message of mapped) {
+      expect(message.llmContent).toBeUndefined();
+      expect(message.rawContent).toBeUndefined();
+    }
+  });
+
+  it("exposes the list summary shape the UI paginates", () => {
+    const [summary] = fixture.list;
+    expect(summary.preview).toBe("It is in transit and arrives Thursday.");
+    expect(summary.messageCount).toBe(9);
+  });
+});
+
+describe("mapWireMessages: image-only fallback", () => {
+  it("uses the shared image fallback text when there is no visible text", () => {
+    const [message] = mapWireMessages([
+      {
+        id: "m1",
+        role: "user",
+        content: [{ type: "image", image: "https://example.com/a.png" }],
+        displayAvailable: true,
+        timestamp: "2026-02-01T00:00:00.000Z",
+      },
+    ]);
+    expect(message.content).toBe("[Image]");
+  });
+
+  it("drops unrecognized parts instead of surfacing them", () => {
+    const [message] = mapWireMessages([
+      {
+        id: "m1",
+        role: "assistant",
+        content: [
+          { type: "tool_use", name: "track", input: { orderId: "A-1" } },
+          { type: "text", text: "Done." },
+        ],
+        displayAvailable: true,
+        timestamp: "2026-02-01T00:00:00.000Z",
+      },
+    ]);
+    expect(message.contentParts).toEqual([{ type: "text", text: "Done." }]);
+    expect(JSON.stringify(message)).not.toContain("tool_use");
+  });
+});
+
+describe("mapWireMessages: role filtering", () => {
+  it("drops roles the widget does not render", () => {
+    const mapped = mapWireMessages([
+      { id: "a", role: "user", content: "hi", displayAvailable: true },
+      { id: "b", role: "tool", content: "{}", displayAvailable: true },
+      { id: "c", role: "developer", content: "x", displayAvailable: true },
+      { id: "d", role: "system", content: "note", displayAvailable: true },
+      { id: "e", role: "assistant", content: "yo", displayAvailable: true },
+    ]);
+    expect(mapped.map((message) => message.id)).toEqual(["a", "d", "e"]);
+  });
+});
+
+describe("mapWireMessages: timestamp synthesis", () => {
+  const olderPage: HistoryWireMessage[] = [
+    { id: "p1", role: "user", content: "one", displayAvailable: true },
+    { id: "p2", role: "assistant", content: "two", displayAvailable: true },
+    { id: "p3", role: "user", content: "three", displayAvailable: true },
+  ];
+  const bound = "2026-02-01T00:00:00.000Z";
+
+  it("keeps server order strictly earlier than the prepend bound", () => {
+    const mapped = mapWireMessages(olderPage, { beforeCreatedAt: bound });
+    const times = mapped.map((message) => Date.parse(message.createdAt));
+    expect(mapped.map((message) => message.id)).toEqual(["p1", "p2", "p3"]);
+    expect(times[0]).toBeLessThan(times[1]);
+    expect(times[1]).toBeLessThan(times[2]);
+    for (const time of times) {
+      expect(time).toBeLessThan(Date.parse(bound));
+    }
+  });
+
+  it("is deterministic across runs", () => {
+    const first = mapWireMessages(olderPage, { beforeCreatedAt: bound });
+    const second = mapWireMessages(olderPage, { beforeCreatedAt: bound });
+    expect(first.map((message) => message.createdAt)).toEqual(
+      second.map((message) => message.createdAt)
+    );
+  });
+
+  it("interleaves synthesized values with neighboring real timestamps", () => {
+    const mapped = mapWireMessages([
+      {
+        id: "a",
+        role: "user",
+        content: "one",
+        displayAvailable: true,
+        timestamp: "2026-02-01T00:00:00.000Z",
+      },
+      { id: "b", role: "assistant", content: "two", displayAvailable: true },
+      { id: "c", role: "assistant", content: "three", displayAvailable: true },
+      {
+        id: "d",
+        role: "user",
+        content: "four",
+        displayAvailable: true,
+        timestamp: "2026-02-01T00:01:00.000Z",
+      },
+      { id: "e", role: "assistant", content: "five", displayAvailable: true },
+    ]);
+    const times = mapped.map((message) => Date.parse(message.createdAt));
+    expect(times).toEqual([...times].sort((x, y) => x - y));
+    expect(times[1]).toBeGreaterThan(times[0]);
+    expect(times[2]).toBeLessThan(times[3]);
+    // No older bound: a trailing run steps forward from the last real value.
+    expect(times[4]).toBeGreaterThan(times[3]);
+  });
+
+  it("keeps a fully timestampless older page before the bound", () => {
+    const mapped = mapWireMessages(
+      [
+        { id: "x", role: "user", content: "one", displayAvailable: true },
+        { id: "y", role: "assistant", content: "two", displayAvailable: true },
+      ],
+      { beforeCreatedAt: bound }
+    );
+    expect(mapped.map((message) => message.createdAt)).toEqual([
+      "2026-01-31T23:59:59.998Z",
+      "2026-01-31T23:59:59.999Z",
+    ]);
+  });
+});
+
+describe("mergeWireMessagesById", () => {
+  const existing: AgentWidgetMessage[] = [
+    { id: "m2", role: "assistant", content: "old two", createdAt: "2026-02-01T00:00:02.000Z" },
+    { id: "m3", role: "user", content: "three", createdAt: "2026-02-01T00:00:03.000Z" },
+  ];
+  const incoming: AgentWidgetMessage[] = [
+    { id: "m1", role: "user", content: "one", createdAt: "2026-02-01T00:00:01.000Z" },
+    { id: "m2", role: "assistant", content: "new two", createdAt: "2026-02-01T00:00:02.000Z" },
+  ];
+
+  it("dedupes by id with incoming winning and sorts once by createdAt", () => {
+    const merged = mergeWireMessagesById(existing, incoming);
+    expect(merged.map((message) => message.id)).toEqual(["m1", "m2", "m3"]);
+    expect(merged.find((message) => message.id === "m2")?.content).toBe("new two");
+  });
+
+  it("falls back to sequence then id when createdAt ties", () => {
+    const at = "2026-02-01T00:00:00.000Z";
+    const merged = mergeWireMessagesById(
+      [
+        { id: "b", role: "user", content: "b", createdAt: at, sequence: 2 },
+        { id: "a", role: "user", content: "a", createdAt: at, sequence: 1 },
+      ],
+      [{ id: "c", role: "user", content: "c", createdAt: at, sequence: 1 }]
+    );
+    expect(merged.map((message) => message.id)).toEqual(["a", "c", "b"]);
+  });
+});

package/src/utils/history-messages.ts

@@ -0,0 +1,284 @@
+/**
+ * History Wire Message Mapping
+ *
+ * Adapter from the Runtype `/v1/client/conversations` wire shape to widget
+ * messages. The display projection (`displayContent`) is the only visible
+ * authority: model-only content is never rendered and never re-enters the
+ * model channel (`llmContent`/`rawContent` are never fabricated here).
+ */
+
+import type {
+  AgentMessageMetadata,
+  AgentWidgetMessage,
+  AgentWidgetMessageRole,
+  ContentPart,
+} from "../types";
+import {
+  IMAGE_ONLY_MESSAGE_FALLBACK_TEXT,
+  createFilePart,
+  createImagePart,
+  createTextPart,
+  getDisplayText,
+  hasImages,
+} from "./content";
+
+/** One message as served by the client conversation history route. */
+export type HistoryWireMessage = {
+  id: string;
+  role: string;
+  /** Model content: string (legacy render-safe fallback) or multi-modal parts. */
+  content?: string | unknown[];
+  /** Server-owned display projection. Absent and empty are distinct states. */
+  displayContent?: string;
+  /** False when no visible form is reconstructable (model content withheld). */
+  displayAvailable: boolean;
+  timestamp?: string;
+};
+
+/** One row of the conversation list. */
+export type HistoryWireConversationSummary = {
+  id: string;
+  title: string;
+  targetId: string | null;
+  flowId: string;
+  preview: string | null;
+  messageCount: number;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type MapWireMessagesOptions = {
+  /**
+   * Oldest `createdAt` already in the transcript. Present when mapping an older
+   * page that will be prepended: synthesized timestamps must land before it.
+   */
+  beforeCreatedAt?: string;
+};
+
+/** `agentMetadata` carrying the history marker; widened locally, not in types.ts. */
+type HistoryAgentMetadata = AgentMessageMetadata & {
+  /** Server withheld this message's content and no display form exists. */
+  historyDisplayUnavailable?: true;
+};
+
+const WIDGET_ROLES: readonly string[] = ["user", "assistant", "system"];
+
+/** Anchor for a page with no real timestamps and no older bound. */
+const SYNTHETIC_EPOCH_MS = 0;
+
+function parseMs(value: string | undefined): number | null {
+  if (typeof value !== "string" || value === "") return null;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Known content parts only; anything else is dropped rather than surfaced. */
+function toContentPart(part: unknown): ContentPart | null {
+  if (typeof part !== "object" || part === null) return null;
+  const raw = part as Record<string, unknown>;
+  switch (raw.type) {
+    case "text":
+      return typeof raw.text === "string" ? createTextPart(raw.text) : null;
+    case "image":
+      return typeof raw.image === "string"
+        ? createImagePart(raw.image, {
+            mimeType: optionalString(raw.mimeType),
+            alt: optionalString(raw.alt),
+          })
+        : null;
+    case "file":
+      return typeof raw.data === "string" &&
+        typeof raw.mimeType === "string" &&
+        typeof raw.filename === "string"
+        ? createFilePart(raw.data, raw.mimeType, raw.filename)
+        : null;
+    case "audio":
+      return typeof raw.audio === "string"
+        ? {
+            type: "audio",
+            audio: raw.audio,
+            ...(optionalString(raw.mimeType) !== undefined && {
+              mimeType: raw.mimeType as string,
+            }),
+          }
+        : null;
+    case "video":
+      return typeof raw.video === "string"
+        ? {
+            type: "video",
+            video: raw.video,
+            ...(optionalString(raw.mimeType) !== undefined && {
+              mimeType: raw.mimeType as string,
+            }),
+          }
+        : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Fill missing timestamps against the transcript boundary.
+ *
+ * A run of missing values counts back in 1 ms steps from its upper bound (the
+ * next real timestamp, the older-page bound, or the lower of the two), so every
+ * synthesized value stays strictly earlier than that bound and increases in
+ * server order. With no upper bound the run steps forward from the previous
+ * real timestamp. Deterministic: derived only from the inputs.
+ */
+function resolveCreatedAt(
+  wire: readonly HistoryWireMessage[],
+  beforeCreatedAt: string | undefined
+): string[] {
+  const boundMs = parseMs(beforeCreatedAt);
+  const times = wire.map((message) => parseMs(message.timestamp));
+  const resolved: number[] = new Array<number>(wire.length);
+
+  let index = 0;
+  while (index < times.length) {
+    const known = times[index];
+    if (known !== null) {
+      resolved[index] = known;
+      index += 1;
+      continue;
+    }
+    let end = index;
+    while (end + 1 < times.length && times[end + 1] === null) end += 1;
+    const runLength = end - index + 1;
+    const lower = index > 0 ? resolved[index - 1] : null;
+    const next = end + 1 < times.length ? times[end + 1] : null;
+    const upper =
+      next !== null && boundMs !== null
+        ? Math.min(next, boundMs)
+        : (next ?? boundMs);
+    for (let offset = 0; offset < runLength; offset += 1) {
+      resolved[index + offset] =
+        upper !== null
+          ? upper - (runLength - offset)
+          : lower !== null
+            ? lower + offset + 1
+            : SYNTHETIC_EPOCH_MS + offset;
+    }
+    index = end + 1;
+  }
+
+  return resolved.map((ms) => new Date(ms).toISOString());
+}
+
+/**
+ * Map wire history messages to widget messages.
+ *
+ * Display priority: `displayContent` (including an empty string) wins; a plain
+ * string model `content` is the legacy fallback; parts become `contentParts`.
+ */
+export function mapWireMessages(
+  wire: HistoryWireMessage[],
+  opts?: MapWireMessagesOptions
+): AgentWidgetMessage[] {
+  const createdAtByIndex = resolveCreatedAt(wire, opts?.beforeCreatedAt);
+  const mapped: AgentWidgetMessage[] = [];
+
+  wire.forEach((message, index) => {
+    if (typeof message?.id !== "string" || message.id === "") return;
+    if (!WIDGET_ROLES.includes(message.role)) return;
+    const role = message.role as AgentWidgetMessageRole;
+    const createdAt = createdAtByIndex[index];
+
+    // No reconstructable visible form: render nothing, mark the gap.
+    if (message.displayAvailable === false) {
+      const agentMetadata: HistoryAgentMetadata = {
+        historyDisplayUnavailable: true,
+      };
+      mapped.push({ id: message.id, role, content: "", createdAt, agentMetadata });
+      return;
+    }
+
+    if (typeof message.displayContent === "string") {
+      mapped.push({
+        id: message.id,
+        role,
+        content: message.displayContent,
+        createdAt,
+      });
+      return;
+    }
+
+    if (typeof message.content === "string") {
+      mapped.push({ id: message.id, role, content: message.content, createdAt });
+      return;
+    }
+
+    if (Array.isArray(message.content)) {
+      const parts = message.content
+        .map(toContentPart)
+        .filter((part): part is ContentPart => part !== null);
+      const text = getDisplayText(parts);
+      mapped.push({
+        id: message.id,
+        role,
+        content:
+          text || (hasImages(parts) ? IMAGE_ONLY_MESSAGE_FALLBACK_TEXT : ""),
+        createdAt,
+        ...(parts.length > 0 && { contentParts: parts }),
+      });
+      return;
+    }
+
+    mapped.push({ id: message.id, role, content: "", createdAt });
+  });
+
+  return mapped;
+}
+
+/**
+ * The visitor-visible projection when it diverges from the model channel that
+ * `/client/chat` stores (contract fact #15). `undefined` means the stored model
+ * content already IS the projection, so nothing extra needs sending.
+ */
+export function divergentDisplayProjection(
+  message: AgentWidgetMessage
+): string | undefined {
+  const display = message.content;
+  if (typeof display !== "string" || display === "") return undefined;
+  const model =
+    message.contentParts ?? message.llmContent ?? message.rawContent ?? display;
+  if (typeof model === "string" && model === display) return undefined;
+  return display;
+}
+
+/** True when the server withheld this history message's content. */
+export function isHistoryDisplayUnavailable(
+  message: AgentWidgetMessage
+): boolean {
+  const metadata = message.agentMetadata as HistoryAgentMetadata | undefined;
+  return metadata?.historyDisplayUnavailable === true;
+}
+
+/**
+ * Merge pages by message id (incoming wins) into one array sorted the way
+ * `sortMessages` sorts: `createdAt`, then `sequence`, then id.
+ */
+export function mergeWireMessagesById(
+  existing: AgentWidgetMessage[],
+  incoming: AgentWidgetMessage[]
+): AgentWidgetMessage[] {
+  const byId = new Map<string, AgentWidgetMessage>();
+  for (const message of existing) byId.set(message.id, message);
+  for (const message of incoming) byId.set(message.id, message);
+
+  return [...byId.values()].sort((a, b) => {
+    const timeA = new Date(a.createdAt).getTime();
+    const timeB = new Date(b.createdAt).getTime();
+    if (!Number.isNaN(timeA) && !Number.isNaN(timeB) && timeA !== timeB) {
+      return timeA - timeB;
+    }
+    const seqA = a.sequence ?? 0;
+    const seqB = b.sequence ?? 0;
+    if (seqA !== seqB) return seqA - seqB;
+    return a.id.localeCompare(b.id);
+  });
+}

package/src/utils/icons.ts

@@ -66,6 +66,7 @@ import {
   EllipsisVertical,
   Menu,
   House,
+  PanelLeft,
   // ---------- Actions ----------
   Plus,
   Minus,
@@ -220,6 +221,8 @@ const LUCIDE_ICONS = {
   "ellipsis-vertical": EllipsisVertical,
   "menu": Menu,
   "house": House,
+  // Sidebar glyph shared with the history rail's collapse controls.
+  "panel-left": PanelLeft,
   // Actions
   "plus": Plus,
   "minus": Minus,