cortena-ui 1.4.2 → 1.6.0

package/src/agent-chat/session.ts

@@ -0,0 +1,549 @@
+/**
+ * Sessions, history and the filter chain.
+ *
+ * Ported from `cortena-shared/src/stores/use-chat.ts` and
+ * `cortenaweb/components/chat/message-bubble.tsx` (Cortena monorepo).
+ * `cortena-shared` is not published, so the rules the two transports share
+ * live here; keep them in step.
+ *
+ * The one deliberate difference is where the current session key is kept.
+ * cortenaweb puts it in `localStorage`, which is shared by every tab of an
+ * origin, so a second window adopted the first window's session: it inherited
+ * a stream that was not its own and both windows then showed the same content.
+ * Sessions here are **per window** — the key lives in `sessionStorage`, under a
+ * name scoped to the extension — so opening the extension twice starts two
+ * sessions. Both stay listed and either window can resume either one; two
+ * windows on one session may both send, and cortenacore serialises the runs.
+ */
+
+import { truncate } from "./step-label";
+import type { AgentChatMessage, AgentChatStep } from "./types";
+
+/* ── minting and remembering a key ───────────────────────────────────────── */
+
+/**
+ * A new session key, minted client-side.
+ *
+ * `agent:<agentId>:new-<Date.now()>-<random36>`. cortenacore reads the
+ * `agent:<id>:` prefix to bind the session to that agent's template, and the
+ * key is the AG-UI `threadId` verbatim, prefix included. Minting it rather than
+ * asking for one is what lets the first message go out immediately.
+ */
+export function mintSessionKey(agentId: string): string {
+  return `agent:${agentId}:new-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+}
+
+/** Was this key minted locally for a chat that had no session yet? */
+export function isProvisionalSessionKey(key: string): boolean {
+  return /(^|:)new-\d+-[a-z0-9]+$/.test(key);
+}
+
+/** Does this session belong to this agent? `sessions.list` is filtered by it. */
+export function isSessionOfAgent(key: string, agentId: string): boolean {
+  return key.startsWith(`agent:${agentId}:`);
+}
+
+/** The `sessionStorage` name the current key is kept under, per extension. */
+export function sessionStorageKey(scope: string): string {
+  return `cortena.agent-chat.${scope}.session`;
+}
+
+/** The `sessionStorage` name the open/collapsed state is kept under. */
+export function viewStorageKey(scope: string): string {
+  return `cortena.agent-chat.${scope}.view`;
+}
+
+/** The `sessionStorage` name this window's progress steps are kept under. */
+export function stepsStorageKey(scope: string): string {
+  return `cortena.agent-chat.${scope}.steps`;
+}
+
+/**
+ * `sessionStorage`, or nothing.
+ *
+ * Absent during SSR and refused outright when a browser blocks storage for the
+ * origin, and neither is a reason for the chat not to work: without it a window
+ * simply forgets its session on reload.
+ */
+export function windowSessionStorage(): Storage | null {
+  try {
+    return typeof window === "undefined" ? null : window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function readStoredSessionKey(scope: string): string | null {
+  try {
+    return windowSessionStorage()?.getItem(sessionStorageKey(scope)) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredSessionKey(scope: string, key: string | null): void {
+  try {
+    const storage = windowSessionStorage();
+    if (!storage) {
+      return;
+    }
+    if (key === null) {
+      storage.removeItem(sessionStorageKey(scope));
+    } else {
+      storage.setItem(sessionStorageKey(scope), key);
+    }
+  } catch {
+    // A blocked storage is not a reason to lose the run in flight.
+  }
+}
+
+/* ── the progress steps of the turn ──────────────────────────────────────── */
+
+/** Most steps kept, in memory and in `sessionStorage`. A turn that long is a runaway loop. */
+export const STEP_LIMIT = 50;
+
+/**
+ * Most bytes the steps slot may occupy.
+ *
+ * `sessionStorage` is a few megabytes for the whole origin, shared with
+ * everything else the host keeps there, and a step count alone does not bound
+ * the size: fifty steps whose labels are all near the limit, with a failure
+ * message on each, is a slot nobody budgeted for. Over the cap the OLDEST are
+ * dropped, one at a time, because the recent ones are the ones a reload has to
+ * bring back.
+ */
+const STEP_BYTE_LIMIT = 64 * 1024;
+
+/** Longest tool call id or tool name kept, in storage and on `data-tool`. */
+export const STORED_TEXT_LIMIT = 80;
+
+/**
+ * The steps of the current turn, and the session they belong to.
+ *
+ * They go in the per-window store beside the session key, for the same reason
+ * the key does: a tab is reloaded mid-run, or a host remounts the surface on a
+ * route change, and both threw the whole strip away. (Collapsing the pop-up is
+ * NOT one of them — the panel is `hidden`, not unmounted, and the run streams
+ * into it either way.) Messages come back from `chat.history`; steps do not
+ * exist on the server, so this is the only place they can come back from.
+ *
+ * Scoped to a session key, and checked on read: resuming a different session
+ * must not inherit the last one's steps.
+ */
+export function readStoredSteps(scope: string, sessionKey: string): AgentChatStep[] {
+  try {
+    const raw = windowSessionStorage()?.getItem(stepsStorageKey(scope));
+    if (!raw) {
+      return [];
+    }
+    const parsed = JSON.parse(raw) as { sessionKey?: unknown; steps?: unknown };
+    if (parsed?.sessionKey !== sessionKey || !Array.isArray(parsed.steps)) {
+      return [];
+    }
+    return (parsed.steps as AgentChatStep[])
+      .filter((step) => typeof step?.id === "string" && typeof step?.label === "string")
+      .map(restoreStep)
+      .slice(-STEP_LIMIT);
+  } catch {
+    // Storage refused, or somebody else wrote the slot. Neither is worth a
+    // broken chat; the strip simply starts empty.
+    return [];
+  }
+}
+
+/** Every status a step may legitimately come back with. */
+const STEP_STATUSES: ReadonlySet<string> = new Set([
+  "running",
+  "done",
+  "error",
+  "stopped",
+  "paused",
+]);
+
+/**
+ * A step as it comes back from storage.
+ *
+ * The important cases are `running` and `paused`. Neither is true any more:
+ * the run that owned the call ended when the surface went away — a reload, a
+ * remount on a route change; a collapsed pop-up only HIDES the strip and never
+ * reaches this path — and no result will arrive for it now, so a restored
+ * spinner spins until the user gives up and reloads again, which restores it.
+ *
+ * It comes back `stopped`, with no message. Neutral is the honest reading:
+ * nothing failed, the work simply did not continue, and "Interrupted." drawn in
+ * the failure colour told the user their call had broken when the page had.
+ *
+ * An unrecognised status is treated the same way. Nothing else writes this
+ * slot today, but it is per-origin `sessionStorage` and this is the only place
+ * that decides what a strip is allowed to render.
+ */
+function restoreStep(step: AgentChatStep): AgentChatStep {
+  const known = STEP_STATUSES.has(step.status);
+  if (known && step.status !== "running" && step.status !== "paused") {
+    return step;
+  }
+  const restored: AgentChatStep = {
+    ...step,
+    status: "stopped",
+    endedAt: step.endedAt ?? Date.now(),
+  };
+  delete restored.errorMessage;
+  return restored;
+}
+
+/**
+ * The fields of a step that are safe to keep, and the only ones kept.
+ *
+ * `args` is deliberately absent. A tool call's arguments are the user's data —
+ * what they searched for, whose record they opened, the body of what they
+ * wrote — and `sessionStorage` is readable by every script on the origin,
+ * survives the run, and is the sort of thing that ends up in a support bundle.
+ * Nothing on screen needs them after the run: the LABEL is already derived
+ * from them, and the label is what a restored strip shows.
+ */
+function storedStep(step: AgentChatStep): AgentChatStep {
+  return {
+    // Bounded, both of them. Neither is written by this package: the id is the
+    // producer's `toolCallId` and the name is whatever the model called, so a
+    // single call carrying 9 kB of either filled the byte cap on its own and
+    // pushed every real step out of the slot.
+    id: truncate(step.id, STORED_TEXT_LIMIT),
+    toolName: truncate(step.toolName, STORED_TEXT_LIMIT),
+    label: step.label,
+    status: step.status,
+    startedAt: step.startedAt,
+    ...(step.endedAt === undefined ? {} : { endedAt: step.endedAt }),
+    ...(step.errorMessage === undefined ? {} : { errorMessage: step.errorMessage }),
+  };
+}
+
+/** The slot's contents, projected and trimmed to fit the byte cap. */
+export function serialiseSteps(sessionKey: string, steps: readonly AgentChatStep[]): string {
+  let kept = steps.slice(-STEP_LIMIT).map(storedStep);
+  let json = JSON.stringify({ sessionKey, steps: kept });
+  while (kept.length > 1 && json.length > STEP_BYTE_LIMIT) {
+    kept = kept.slice(1);
+    json = JSON.stringify({ sessionKey, steps: kept });
+  }
+  return json;
+}
+
+export function writeStoredSteps(
+  scope: string,
+  sessionKey: string | null,
+  steps: readonly AgentChatStep[],
+): void {
+  try {
+    const storage = windowSessionStorage();
+    if (!storage) {
+      return;
+    }
+    if (!sessionKey || steps.length === 0) {
+      storage.removeItem(stepsStorageKey(scope));
+      return;
+    }
+    storage.setItem(stepsStorageKey(scope), serialiseSteps(sessionKey, steps));
+  } catch {
+    // Blocked, or over quota. The run in flight is not worth losing over it.
+  }
+}
+
+/* ── history ─────────────────────────────────────────────────────────────── */
+
+function generateId(): string {
+  return `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+function isToolRelatedMessage(msg: Record<string, unknown>): boolean {
+  const role = typeof msg.role === "string" ? msg.role.toLowerCase() : "";
+  if (role === "tool" || role === "toolresult" || role === "tool_result") {
+    return true;
+  }
+  const content = msg.content as Array<{ type: string }> | undefined;
+  if (Array.isArray(content) && content.length > 0) {
+    const toolTypes = new Set([
+      "tool_use",
+      "tool_call",
+      "tool_result",
+      "toolresult",
+      "server_tool_use",
+    ]);
+    const hasText = content.some((c) => c.type === "text" || c.type === "thinking");
+    const hasToolBlocks = content.some((c) => toolTypes.has(c.type));
+    if (hasToolBlocks && !hasText) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Strip `System: [timestamp] …` lines and `[System Message]` prefixes the
+ * runtime prepends to a user turn as agent context. They are not user text.
+ */
+function stripSystemPrefixes(text: string): string {
+  return text
+    .split("\n")
+    .filter((line) => !/^System:\s*\[/.test(line) && !line.startsWith("[System Message]"))
+    .join("\n")
+    .replace(/^\n+/, "");
+}
+
+/** Lift `<thinking>…</thinking>` out of plain text. */
+export function separateThinking(text: string): { thinkingText?: string; mainText: string } {
+  const match = text.match(/<thinking>([\s\S]*?)<\/thinking>/);
+  if (!match?.[1]) {
+    return { mainText: text };
+  }
+  const thinkingText = match[1].trim();
+  const mainText = text.replace(/<thinking>[\s\S]*?<\/thinking>\s*/, "").trim();
+  return { ...(thinkingText ? { thinkingText } : {}), mainText };
+}
+
+function parseOneHistoryMessage(raw: unknown): AgentChatMessage {
+  const msg = raw as Record<string, unknown>;
+  const content = msg.content as
+    | Array<{ type: string; text?: string; thinking?: string; a2ui?: unknown }>
+    | undefined;
+  let text = Array.isArray(content)
+    ? content
+        .filter((c) => c.type === "text" && c.text)
+        .map((c) => c.text!)
+        .join("")
+    : typeof msg.content === "string"
+      ? msg.content
+      : typeof msg.text === "string"
+        ? msg.text
+        : "";
+
+  const isToolMessage = isToolRelatedMessage(msg);
+  const role = ((msg.role as string) === "user" ? "user" : "assistant") as "user" | "assistant";
+  if (role === "user") {
+    text = stripSystemPrefixes(text);
+  }
+
+  let thinkingText = "";
+  if (typeof msg.thinking === "string" && msg.thinking.trim()) {
+    thinkingText = msg.thinking.trim();
+  } else if (Array.isArray(content)) {
+    thinkingText = content
+      .filter((c) => c.type === "thinking")
+      .map((c) => c.thinking ?? c.text ?? "")
+      .filter(Boolean)
+      .join("\n\n");
+  }
+  if (!thinkingText) {
+    const { thinkingText: tagThinking, mainText } = separateThinking(text);
+    if (tagThinking) {
+      return {
+        id: typeof msg.id === "string" ? msg.id : generateId(),
+        role,
+        text: mainText,
+        timestamp: (msg.timestamp as number) ?? Date.now(),
+        thinkingText: tagThinking,
+        ...(isToolMessage ? { isToolMessage } : {}),
+      };
+    }
+  }
+
+  return {
+    id: typeof msg.id === "string" ? msg.id : generateId(),
+    role,
+    text,
+    timestamp: (msg.timestamp as number) ?? Date.now(),
+    ...(thinkingText ? { thinkingText } : {}),
+    ...(isToolMessage ? { isToolMessage } : {}),
+  };
+}
+
+/**
+ * Merge an agent turn — assistant messages plus tool call and result messages —
+ * into one visible message. Everything except the final substantive response is
+ * folded into the chain of thought. Only a genuine user message breaks the turn.
+ */
+function mergeConsecutiveAssistantMessages(messages: AgentChatMessage[]): AgentChatMessage[] {
+  const result: AgentChatMessage[] = [];
+  let run: AgentChatMessage[] = [];
+
+  const flush = () => {
+    const first = run[0];
+    if (!first) {
+      return;
+    }
+    if (run.length === 1) {
+      result.push(first);
+      run = [];
+      return;
+    }
+    let visibleIdx = run.length - 1;
+    while (visibleIdx > 0 && !(run[visibleIdx]?.text ?? "").trim()) {
+      visibleIdx--;
+    }
+    const visible = run[visibleIdx] ?? first;
+    const cot: string[] = [];
+    for (let i = 0; i < run.length; i++) {
+      const entry = run[i];
+      if (!entry) {
+        continue;
+      }
+      if (i === visibleIdx) {
+        if (visible.thinkingText) {
+          cot.push(visible.thinkingText);
+        }
+        continue;
+      }
+      if (entry.thinkingText) {
+        cot.push(entry.thinkingText);
+      }
+      if (entry.text.trim()) {
+        cot.push(entry.text.trim());
+      }
+    }
+    const combined = cot.filter(Boolean).join("\n\n");
+    result.push({ ...visible, ...(combined ? { thinkingText: combined } : {}) });
+    run = [];
+  };
+
+  for (const msg of messages) {
+    const isRealUser = msg.role === "user" && !msg.isToolMessage && msg.text.trim().length > 0;
+    if (isRealUser) {
+      flush();
+      result.push(msg);
+    } else {
+      run.push(msg);
+    }
+  }
+  flush();
+  return result;
+}
+
+/** Raw transcript records to the messages the list renders. */
+export function parseHistoryMessages(raw: readonly unknown[]): AgentChatMessage[] {
+  return mergeConsecutiveAssistantMessages(raw.map(parseOneHistoryMessage));
+}
+
+/**
+ * The history shrink guard.
+ *
+ * A history load must not shrink the session already on screen. The first
+ * message of a new chat loads history while the turn is still in flight and the
+ * user's message has not been persisted yet; replacing wholesale threw that
+ * message away, and the reply survived, so the symptom was a conversation with
+ * the answer but not the question.
+ *
+ * Only the same session, and only against losing messages: a longer or equal
+ * history still replaces, so an edit, a deletion made elsewhere and a compaction
+ * all land normally.
+ */
+export function wouldShrinkHistory(params: {
+  currentSessionKey: string | null;
+  loadedSessionKey: string;
+  currentCount: number;
+  loadedCount: number;
+}): boolean {
+  return (
+    params.currentSessionKey === params.loadedSessionKey &&
+    params.loadedCount < params.currentCount
+  );
+}
+
+/* ── the filter chain ────────────────────────────────────────────────────── */
+
+/** A JSON blob a tool or an extension API returned, echoed as a message. */
+function isToolResult(text: string): boolean {
+  const trimmed = text.trim();
+  const wrapped =
+    (trimmed.startsWith("[") && trimmed.endsWith("]")) ||
+    (trimmed.startsWith("{") && trimmed.endsWith("}"));
+  if (!wrapped) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === "object" && parsed !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** Raw skill-file content the model echoed instead of acting on. */
+function isSkillContent(text: string): boolean {
+  const trimmed = text.trim();
+  return (
+    /^name:\s*\S+.*\bdescription:.*\btype:\s*skill\b/i.test(trimmed) ||
+    /^---\s*\n[\s\S]*?\btype:\s*skill\b[\s\S]*?\n---/m.test(trimmed)
+  );
+}
+
+/** Runtime diagnostics: token counters, a leaked api-key hint. */
+function isAgentDiagnostics(text: string): boolean {
+  const trimmed = text.trim();
+  return /Tokens:\s*\d+.*Cache:.*Context:/s.test(trimmed) || /\bapi-key\s+sk-/.test(trimmed);
+}
+
+/** Tool execution output that leaked into history as its own message. */
+function isToolOutput(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (/^Tool\s+\S+\s+not found$/i.test(trimmed)) {
+    return true;
+  }
+  if (trimmed === "(no output)") {
+    return true;
+  }
+  if (/^total\s+\d+\s+[d-][rwx-]{9}/.test(trimmed)) {
+    return true;
+  }
+  if (/^[d-][rwx-]{9}[@+]?\s+\d+\s+\S+\s+\S+/.test(trimmed)) {
+    return true;
+  }
+  if (/(?:^|\n)[A-Z_]{2,}=\S/m.test(trimmed)) {
+    if (
+      /\b(?:PATH|PWD|HOME|USER|INIT_CWD|PNPM_|NODE_|npm_|CORTENA_|CORTENACORE_|CORTENABOT_)/m.test(
+        trimmed,
+      )
+    ) {
+      return true;
+    }
+    if ((trimmed.match(/(?:^|\n)[A-Z_]{3,}=\S/gm) ?? []).length >= 3) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Should this message be hidden?
+ *
+ * The same chain cortenaweb's bubble applies, in the same order. It exists
+ * because tool plumbing leaks into a transcript in several recognisable shapes,
+ * and a chat that renders them reads as broken. Tool detail is not lost: it is
+ * in the tool strip and in the chain of thought.
+ *
+ * A reply that is only UI the agent drew has no text at all, so an A2UI block
+ * counts as content — without that, the surface the user asked for is filtered
+ * away and nothing appears.
+ */
+export function isHiddenMessage(message: AgentChatMessage): boolean {
+  if (message.isError) {
+    return false;
+  }
+  if (message.isToolMessage) {
+    return true;
+  }
+  if (
+    message.role === "assistant" &&
+    !message.text.trim() &&
+    !message.thinkingText &&
+    !message.a2ui?.length
+  ) {
+    return true;
+  }
+  if (message.role === "user") {
+    return !message.text.trim() && !message.attachments?.length;
+  }
+  const text = message.text;
+  return isToolResult(text) || isSkillContent(text) || isAgentDiagnostics(text) || isToolOutput(text);
+}