@djangocfg/widget-chat 0.1.1

package/src/core/tools/capability.ts

@@ -0,0 +1,34 @@
+import type { ToolCatalogEntry } from "./catalogue";
+
+/**
+ * The agent's arsenal — the composer's `+` menu.
+ *
+ * Absent ⇒ no `+` at all. A replay has no arsenal to offer.
+ *
+ * The catalogue is the HOST's: registration is conditional on the server's
+ * capabilities, so a list shipped here would promise what a turn cannot deliver.
+ *
+ * A pick does NOT run the tool. Running one needs arguments and a form; the
+ * agent decides how to do the work.
+ */
+export interface ToolsCapability {
+  /** The catalogue, in the order it should be offered. */
+  readonly entries: readonly ToolCatalogEntry[];
+  /**
+   * The server has not answered yet. `entries` is then EMPTY BECAUSE UNKNOWN,
+   * not because it has none — three states, not two.
+   *
+   * Without it a slow answer renders identically to "no tools": the trigger
+   * vanishes, reappears when the reply lands, and vanishes again on the next
+   * room whose answer is not cached. The control holds its place instead.
+   */
+  readonly loading?: boolean;
+  /**
+   * Told that a pick happened, AFTER it is staged. Absent ⇒ nothing else runs.
+   *
+   * A notification, not a decision: the package stages the pick on the draft and
+   * `buildOutbound` turns it into a marker, so a host that also composed text
+   * here would make two writers of one outbound turn.
+   */
+  readonly onPick?: (entry: ToolCatalogEntry) => void;
+}

package/src/core/tools/catalogue.ts

@@ -0,0 +1,109 @@
+// The tool catalogue as data. Registration on the server is conditional on
+// what it can reach, so the list is read, never assumed.
+//
+// May import: ./rank.
+
+import { scoreTool } from "./rank";
+
+/** One capability, as the registry already describes it. */
+export interface ToolCatalogEntry {
+  /** The registry's own name, e.g. `transcribe_audio`. Also what a pick names. */
+  readonly id: string;
+  /** What the row READS. Short enough for a narrow pane. */
+  readonly name: string;
+  /**
+   * One human line, authored separately from the tool's own description — that
+   * one is model-facing and mostly disambiguation against neighbouring tools.
+   */
+  readonly summary: string;
+  /** The registry's grouping key (`stt`, `web`, `disk`, …), used verbatim. */
+  readonly category: string;
+  /**
+   * The registry's own search keywords. Searching "voice" must reach a tool
+   * spelled `transcribe_audio`.
+   */
+  readonly keywords?: readonly string[];
+  /**
+   * Glyph KEY, never a node — the catalogue crosses the transport as data. An unmapped
+   * key draws nothing rather than failing.
+   */
+  readonly icon?: string;
+  /**
+   * What a pick still wants, when anything.
+   *
+   * Absent for most tools by design: picking states an intent and the object
+   * arrives as the sentence typed next. The exceptions want something a
+   * sentence cannot carry, and the composer says so rather than letting the
+   * turn send and the agent ask.
+   *
+   * Derived on the server from the tool's own required arguments, never authored here.
+   */
+  readonly needs?: "file" | "skill";
+}
+
+/** A category and the tools in it, in display order. */
+export interface ToolCatalogGroup {
+  readonly category: string;
+  readonly entries: readonly ToolCatalogEntry[];
+}
+
+/**
+ * Group by the registry's own category; a second taxonomy here would drift.
+ * Order follows first appearance, so the host's ordering decides.
+ */
+export function groupToolsByCategory(
+  entries: readonly ToolCatalogEntry[],
+): readonly ToolCatalogGroup[] {
+  const order: string[] = [];
+  const byCategory = new Map<string, ToolCatalogEntry[]>();
+
+  for (const entry of entries) {
+    const bucket = byCategory.get(entry.category);
+    if (bucket === undefined) {
+      order.push(entry.category);
+      byCategory.set(entry.category, [entry]);
+      continue;
+    }
+    bucket.push(entry);
+  }
+
+  return order.map((category) => ({
+    category,
+    entries: byCategory.get(category) ?? [],
+  }));
+}
+
+/**
+ * Matches id, name, summary and keywords, in any keyboard layout. Name alone is
+ * not enough: a user with a recording types "voice", which `transcribe_audio`
+ * does not contain.
+ *
+ * Matching and ordering read the same score, so a row can never rank above
+ * another it does not also out-match.
+ */
+export function toolMatchesQuery(entry: ToolCatalogEntry, query: string): boolean {
+  return scoreTool(entry, query) > 0;
+}
+
+/**
+ * The catalogue narrowed to a query, ranked, grouped for display.
+ *
+ * Ranking runs BEFORE grouping and orders entries within each group; the groups
+ * themselves keep the registry's order. Sorting groups by their best hit would
+ * move a heading up and down as the user types, and a category that jumps is
+ * harder to scan than one that stays put.
+ *
+ * Sort is stable on equal scores, so an empty query — where every entry scores
+ * alike — leaves the registry's order untouched.
+ */
+export function filterToolCatalogue(
+  entries: readonly ToolCatalogEntry[],
+  query: string,
+): readonly ToolCatalogGroup[] {
+  const scored = entries
+    .map((entry) => ({ entry, score: scoreTool(entry, query) }))
+    .filter((row) => row.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return groupToolsByCategory(scored.map((row) => row.entry));
+}

package/src/core/tools/index.ts

@@ -0,0 +1,17 @@
+// The tool arsenal: what this agent can do here, as data.
+//
+// Pure by design — the catalogue arrives from the host (Go owns the registry),
+// and the surface rendering it is meant to be swappable. May import: nothing.
+
+export type { ToolsCapability } from "./capability";
+export {
+  filterToolCatalogue,
+  groupToolsByCategory,
+  toolMatchesQuery,
+  type ToolCatalogEntry,
+  type ToolCatalogGroup,
+} from "./catalogue";
+export { queryLayoutForms } from "./layout";
+export { nextRow, stepForKey, NO_ROW } from "./nav";
+export { scoreTool } from "./rank";
+export { forgetTool, recentTools, rememberTool, RECENT_LIMIT } from "./recent";

package/src/core/tools/layout.ts

@@ -0,0 +1,44 @@
+// Keyboard-layout transliteration for search input.
+//
+// May import: nothing.
+
+/**
+ * QWERTY→ЙЦУКЕН by physical key. The pair is positional, not phonetic: `g`
+ * and `п` are the same key, so someone who meant "generate" and left the
+ * layout on Russian produces "пуньфеу".
+ */
+const RU_BY_KEY = "йцукенгшщзхъфывапролджэячсмитьбю.ёЙЦУКЕНГШЩЗХЪФЫВАПРОЛДЖЭЯЧСМИТЬБЮ,Ё";
+const EN_BY_KEY = "qwertyuiop[]asdfghjkl;'zxcvbnm,./`QWERTYUIOP{}ASDFGHJKL:\"ZXCVBNM<>?~";
+
+const TO_EN = new Map<string, string>();
+const TO_RU = new Map<string, string>();
+for (const [index, ru] of [...RU_BY_KEY].entries()) {
+  const en = EN_BY_KEY[index];
+  if (en === undefined) continue;
+  TO_EN.set(ru, en);
+  TO_RU.set(en, ru);
+}
+
+function transliterate(value: string, table: ReadonlyMap<string, string>): string {
+  let out = "";
+  for (const char of value) out += table.get(char) ?? char;
+  return out;
+}
+
+/**
+ * What was typed, plus each layout reading of it.
+ *
+ * Both directions: the mistake runs either way, and guessing which costs a
+ * keystroke. The original comes first, so a caller can rank an exact hit above
+ * a transliterated one.
+ */
+export function queryLayoutForms(query: string): readonly string[] {
+  const typed = query.trim();
+  if (typed === "") return [];
+
+  const forms = [typed];
+  for (const candidate of [transliterate(typed, TO_EN), transliterate(typed, TO_RU)]) {
+    if (candidate !== typed && !forms.includes(candidate)) forms.push(candidate);
+  }
+  return forms;
+}

package/src/core/tools/nav.ts

@@ -0,0 +1,32 @@
+// Where an arrow key moves a menu cursor.
+//
+// May import: nothing.
+
+/** Nothing is selected yet — the state a freshly opened menu is in. */
+export const NO_ROW = -1;
+
+/**
+ * The next cursor position, or `NO_ROW` when the key does not move it.
+ *
+ * Movement WRAPS. The list is short and the user is aiming at one row, so
+ * stopping at the end costs a direction change to reach what is one step the
+ * other way.
+ *
+ * From nothing selected, Down opens at the top and Up at the BOTTOM: the last
+ * row is then one keystroke away instead of `count - 1` of them.
+ *
+ * Pure, and separate from the hook binding it, because this package has no DOM
+ * to render a hook into — the same reason the recall ladder is a pure module.
+ */
+export function nextRow(current: number, step: number, count: number): number {
+  if (count === 0 || step === 0) return NO_ROW;
+  if (current < 0) return step > 0 ? 0 : count - 1;
+  return (current + step + count) % count;
+}
+
+/** The step an arrow key asks for; 0 for every other key. */
+export function stepForKey(key: string): number {
+  if (key === "ArrowDown") return 1;
+  if (key === "ArrowUp") return -1;
+  return 0;
+}

package/src/core/tools/rank.ts

@@ -0,0 +1,60 @@
+// How well a catalogue entry answers a query.
+//
+// May import: ./catalogue, ./layout.
+
+import type { ToolCatalogEntry } from "./catalogue";
+import { queryLayoutForms } from "./layout";
+
+/**
+ * Field weights. A summary hit is often incidental: "gen" matches "the agent's
+ * browser", which is how an unranked filter put Browser navigate first.
+ */
+const NAME = 1000;
+const ID = 800;
+const KEYWORD = 600;
+const SUMMARY = 200;
+
+/** A prefix hit beats one mid-word: "gen" means Generate before Regenerate. */
+const PREFIX_BONUS = 100;
+
+/** Every layout form after the first is a guess about what the user meant. */
+const TRANSLITERATED_PENALTY = 50;
+
+function fieldScore(haystack: string, needle: string, weight: number): number {
+  const at = haystack.toLowerCase().indexOf(needle);
+  if (at < 0) return 0;
+  return weight + (at === 0 ? PREFIX_BONUS : 0);
+}
+
+function scoreForNeedle(entry: ToolCatalogEntry, needle: string): number {
+  const keywords = (entry.keywords ?? []).reduce(
+    (best, keyword) => Math.max(best, fieldScore(keyword, needle, KEYWORD)),
+    0,
+  );
+  // Best field, not the sum: summing lets a long summary outrank an exact name.
+  return Math.max(
+    fieldScore(entry.name, needle, NAME),
+    fieldScore(entry.id, needle, ID),
+    keywords,
+    fieldScore(entry.summary, needle, SUMMARY),
+  );
+}
+
+/**
+ * 0 when the entry does not match at all; higher is more relevant.
+ *
+ * An empty query scores every entry equally, so the caller's own order (the
+ * registry's) survives — the menu at rest is not a search result.
+ */
+export function scoreTool(entry: ToolCatalogEntry, query: string): number {
+  const forms = queryLayoutForms(query);
+  if (forms.length === 0) return 1;
+
+  let best = 0;
+  for (const [index, form] of forms.entries()) {
+    const score = scoreForNeedle(entry, form.toLowerCase());
+    if (score === 0) continue;
+    best = Math.max(best, score - (index === 0 ? 0 : TRANSLITERATED_PENALTY));
+  }
+  return best;
+}

package/src/core/tools/recent.ts

@@ -0,0 +1,39 @@
+// Recently used tools, as data.
+//
+// May import: ./catalogue.
+
+import type { ToolCatalogEntry } from "./catalogue";
+
+/**
+ * How many recents a user can hold in their head before the group stops being
+ * a shortcut and becomes a second catalogue to read.
+ */
+export const RECENT_LIMIT = 5;
+
+/** Most recent first, capped, no duplicates. */
+export function rememberTool(recent: readonly string[], id: string): readonly string[] {
+  return [id, ...recent.filter((known) => known !== id)].slice(0, RECENT_LIMIT);
+}
+
+export function forgetTool(recent: readonly string[], id: string): readonly string[] {
+  return recent.filter((known) => known !== id);
+}
+
+/**
+ * Recent ids resolved against the CURRENT catalogue, in recency order.
+ *
+ * A tool the host no longer registers drops out rather than rendering a row
+ * that picks nothing. The stored list is not pruned — the tool may return.
+ */
+export function recentTools(
+  entries: readonly ToolCatalogEntry[],
+  recent: readonly string[],
+): readonly ToolCatalogEntry[] {
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const resolved: ToolCatalogEntry[] = [];
+  for (const id of recent) {
+    const entry = byId.get(id);
+    if (entry !== undefined) resolved.push(entry);
+  }
+  return resolved;
+}

package/src/core/transcript.ts

@@ -0,0 +1,301 @@
+/**
+ * The transcript reducer — the ONE place a stream becomes messages.
+ *
+ * Pure and synchronous on purpose: every streaming bug the predecessor shipped
+ * (duplicated fragments after a retry, tool output attached to the wrong call,
+ * a failed turn rendered as a normal reply) is reproducible here in
+ * milliseconds, with no React and no DOM. `@rules/testing.md` calls this the
+ * main rung for exactly that reason.
+ *
+ * Normalized as `ids[] + byId{}` so a message can re-render without the list
+ * re-rendering — the transcript subscribes to ids, each row to its own id.
+ */
+
+import type { StreamChunk } from "./chunks";
+import type { ChatMessage, MessagePart, MessageStatus, ToolPart, ToolState } from "./parts";
+
+export interface TranscriptState {
+  readonly ids: readonly string[];
+  readonly byId: Readonly<Record<string, ChatMessage>>;
+  /** The message currently receiving chunks, if any. */
+  readonly streamingId: string | null;
+}
+
+export const emptyTranscript: TranscriptState = { ids: [], byId: {}, streamingId: null };
+
+function replacePart(
+  message: ChatMessage,
+  at: number,
+  part: MessagePart,
+): ChatMessage {
+  const parts = message.parts.slice();
+  parts[at] = part;
+  return { ...message, parts };
+}
+
+function appendPart(message: ChatMessage, part: MessagePart): ChatMessage {
+  return { ...message, parts: [...message.parts, part] };
+}
+
+/**
+ * Append the part, or REPLACE the one already carrying that id.
+ *
+ * For WHOLE parts only — `file` and `data`, which arrive complete in one chunk.
+ * A repeated id there is the same part revised, never a second part: the
+ * server re-sends its plan block under the stable id `plan-current` on every
+ * step, and the transport's own accumulator (`collectBlock`,
+ * `transport/web/chat-map.ts`) is replace-by-id for exactly that reason. A
+ * blind append stacks one plan card per step.
+ *
+ * Deliberately NOT used by `text-start` / `reasoning-start` / `tool-input-start`,
+ * which create an EMPTY part that deltas then fill. Replacement there would let
+ * a repeated start chunk wipe the text already accumulated under that id —
+ * strictly worse than the duplicate empty part it would be preventing.
+ *
+ * Replacement keeps the ORIGINAL position rather than moving the part to the
+ * end: the plan was authored where it first appeared, and a card that jumps
+ * down the transcript on each revision makes a different claim about the turn.
+ */
+function upsertPart(message: ChatMessage, part: MessagePart): ChatMessage {
+  const at = message.parts.findIndex((p) => p.id === part.id);
+  if (at === -1) return appendPart(message, part);
+  const parts = [...message.parts];
+  parts[at] = part;
+  return { ...message, parts };
+}
+
+function withMessage(state: TranscriptState, message: ChatMessage): TranscriptState {
+  const known = message.id in state.byId;
+  return {
+    ids: known ? state.ids : [...state.ids, message.id],
+    byId: { ...state.byId, [message.id]: message },
+    streamingId: state.streamingId,
+  };
+}
+
+/** Locate a part by key, or -1. Keys are unique within a message by construction. */
+function findPart(
+  message: ChatMessage,
+  match: (part: MessagePart) => boolean,
+): number {
+  for (let i = message.parts.length - 1; i >= 0; i -= 1) {
+    const part = message.parts[i];
+    if (part !== undefined && match(part)) return i;
+  }
+  return -1;
+}
+
+function findTool(message: ChatMessage, toolCallId: string): number {
+  return findPart(message, (p): boolean => p.type === "tool" && p.id === toolCallId);
+}
+
+/** Preserve the input we already have when a state transition does not carry it. */
+function inputOf(state: ToolState): unknown {
+  return state.state === "input-streaming" ? undefined : state.input;
+}
+
+function updateTool(
+  message: ChatMessage,
+  toolCallId: string,
+  next: (part: ToolPart) => ToolPart,
+): ChatMessage {
+  const at = findTool(message, toolCallId);
+  if (at < 0) return message;
+  const part = message.parts[at];
+  if (part === undefined || part.type !== "tool") return message;
+  return replacePart(message, at, next(part));
+}
+
+/**
+ * Text and reasoning deltas share everything but the discriminant, so they
+ * share the code — a copied pair drifts, and the two paths must stay identical
+ * or `reset` will clear one and not the other.
+ */
+function applyDelta(
+  message: ChatMessage,
+  kind: "text" | "reasoning",
+  partId: string,
+  delta: string,
+): ChatMessage {
+  const at = findPart(message, (p) => p.type === kind && p.id === partId);
+  if (at < 0) return message;
+  const part = message.parts[at];
+  if (part === undefined || (part.type !== "text" && part.type !== "reasoning")) return message;
+  return replacePart(message, at, { ...part, text: part.text + delta });
+}
+
+export function reduce(state: TranscriptState, chunk: StreamChunk): TranscriptState {
+  switch (chunk.type) {
+    case "message-start": {
+      const message: ChatMessage = {
+        id: chunk.messageId,
+        role: "assistant",
+        parts: [],
+        status: { state: "streaming" },
+        createdAt: chunk.createdAt,
+      };
+      return { ...withMessage(state, message), streamingId: chunk.messageId };
+    }
+    case "reset": {
+      const current = currentMessage(state);
+      if (current === null) return state;
+      return withMessage(state, { ...current, parts: [] });
+    }
+    case "finish":
+      return finishWith(state, { state: "complete" });
+    case "error":
+      return finishWith(state, { state: "failed", message: chunk.message });
+    case "interrupted":
+      return finishWith(state, { state: "interrupted" });
+    default:
+      return reduceIntoCurrent(state, chunk);
+  }
+}
+
+function currentMessage(state: TranscriptState): ChatMessage | null {
+  if (state.streamingId === null) return null;
+  return state.byId[state.streamingId] ?? null;
+}
+
+function finishWith(state: TranscriptState, status: MessageStatus): TranscriptState {
+  const current = currentMessage(state);
+  if (current === null) return state;
+  return { ...withMessage(state, { ...current, status }), streamingId: null };
+}
+
+/**
+ * Chunks that target the in-flight message.
+ *
+ * A chunk arriving with no message in flight is DROPPED rather than implicitly
+ * opening one. Silent auto-creation hides an adapter that forgot
+ * `message-start`, and the resulting transcript looks plausible while being
+ * wrong — the failure has to be visible in a test, not smoothed over.
+ */
+function reduceIntoCurrent(
+  state: TranscriptState,
+  chunk: Exclude<StreamChunk, { type: "message-start" | "reset" | "finish" | "error" | "interrupted" }>,
+): TranscriptState {
+  const current = currentMessage(state);
+  if (current === null) return state;
+
+  switch (chunk.type) {
+    case "text-start":
+      return withMessage(
+        state,
+        appendPart(current, { type: "text", id: chunk.partId, text: "" }),
+      );
+    case "text-delta":
+      return withMessage(state, applyDelta(current, "text", chunk.partId, chunk.delta));
+    case "reasoning-start":
+      return withMessage(
+        state,
+        appendPart(current, {
+          type: "reasoning",
+          id: chunk.partId,
+          text: "",
+          streaming: true,
+        }),
+      );
+    case "reasoning-delta":
+      return withMessage(state, applyDelta(current, "reasoning", chunk.partId, chunk.delta));
+    case "reasoning-end": {
+      const at = findPart(current, (p) => p.type === "reasoning" && p.id === chunk.partId);
+      const part = at < 0 ? undefined : current.parts[at];
+      // An end for a block that never opened is dropped rather than synthesised:
+      // a part with no text and no measurement is an empty disclosure.
+      if (part === undefined || part.type !== "reasoning") return state;
+      return withMessage(
+        state,
+        replacePart(current, at, {
+          ...part,
+          streaming: false,
+          // Keep what the engine measured; absent stays absent rather than
+          // becoming a zero, which would read as "thought for 0ms".
+          ...(chunk.elapsedMs === undefined ? {} : { elapsedMs: chunk.elapsedMs }),
+          ...(chunk.tokens === undefined ? {} : { tokens: chunk.tokens }),
+        }),
+      );
+    }
+    case "tool-input-start":
+      return withMessage(
+        state,
+        appendPart(current, {
+          type: "tool",
+          id: chunk.toolCallId,
+          toolName: chunk.toolName,
+          toolState: { state: "input-streaming", inputText: "" },
+        }),
+      );
+    case "tool-input-delta":
+      return withMessage(
+        state,
+        updateTool(current, chunk.toolCallId, (part) =>
+          part.toolState.state === "input-streaming"
+            ? {
+                ...part,
+                toolState: {
+                  state: "input-streaming",
+                  inputText: part.toolState.inputText + chunk.delta,
+                },
+              }
+            : part,
+        ),
+      );
+    case "tool-input-available":
+      return withMessage(
+        state,
+        updateTool(current, chunk.toolCallId, (part) => ({
+          ...part,
+          toolState: { state: "input-available", input: chunk.input },
+        })),
+      );
+    case "tool-output":
+      return withMessage(
+        state,
+        updateTool(current, chunk.toolCallId, (part) => ({
+          ...part,
+          toolState: {
+            state: "output-available",
+            input: inputOf(part.toolState),
+            output: chunk.output,
+          },
+        })),
+      );
+    case "tool-error":
+      return withMessage(
+        state,
+        updateTool(current, chunk.toolCallId, (part) => ({
+          ...part,
+          toolState: {
+            state: "output-error",
+            input: inputOf(part.toolState),
+            error: chunk.error,
+          },
+        })),
+      );
+    case "data":
+      return withMessage(state, upsertPart(current, chunk.part));
+  }
+}
+
+/** Append a message the user authored. Never streams, so it lands complete. */
+export function appendUserMessage(
+  state: TranscriptState,
+  message: ChatMessage,
+): TranscriptState {
+  return withMessage(state, message);
+}
+
+export function reduceAll(
+  state: TranscriptState,
+  chunks: readonly StreamChunk[],
+): TranscriptState {
+  return chunks.reduce(reduce, state);
+}
+
+export function selectMessages(state: TranscriptState): readonly ChatMessage[] {
+  return state.ids.flatMap((id) => {
+    const message = state.byId[id];
+    return message === undefined ? [] : [message];
+  });
+}