@mlx-bun/module-chat 0.0.0-stage → 1.0.0

package/src/history.ts

@@ -0,0 +1,188 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import type { SessionEntry, SessionInfo } from "@earendil-works/pi-coding-agent";
+import type { ImageAttachment, HistoryToolItem, HistoryItem, SessionListItem } from "./protocol";
+
+/** Flatten a content value (string | content-parts) to its text. */
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((p): p is { type: string; text: string } =>
+        !!p && (p as { type?: string }).type === "text" && typeof (p as { text?: unknown }).text === "string")
+      .map((p) => p.text)
+      .join("");
+  }
+  return "";
+}
+
+function contentThinking(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((p): p is { type: string; thinking: string } =>
+      !!p && (p as { type?: string }).type === "thinking" && typeof (p as { thinking?: unknown }).thinking === "string")
+    .map((p) => p.thinking)
+    .join("");
+}
+
+/**
+ * Turn a session's entries into a flat, browser-renderable transcript.
+ *
+ * Walks message entries in order: user/assistant text become items, the
+ * assistant's toolCall parts become tool items, and each later toolResult
+ * is merged back onto its tool by callId. Non-message entries (model
+ * changes, compaction, thinking) are skipped. Pure so it's unit-tested
+ * without a live session.
+ */
+export function serializeHistory(entries: readonly SessionEntry[]): HistoryItem[] {
+  const items: HistoryItem[] = [];
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const m = (entry as { message?: unknown }).message as
+      | { role?: string; content?: unknown; toolCallId?: string }
+      | undefined;
+    if (!m) continue;
+    if (m.role === "user") {
+      const text = contentText(m.content);
+      if (text.trim()) items.push({ role: "user", text, tools: [], entryId: entry.id });
+    } else if (m.role === "assistant") {
+      const parts = Array.isArray(m.content) ? (m.content as unknown[]) : [];
+      const text = contentText(parts);
+      const thinking = contentThinking(parts);
+      const tools: HistoryToolItem[] = parts
+        .filter((p): p is { type: string; id?: unknown; name?: unknown; arguments?: unknown } =>
+          !!p && (p as { type?: string }).type === "toolCall")
+        .map((p) => ({ callId: String(p.id ?? ""), name: String(p.name ?? "tool"), args: p.arguments, result: "" }));
+      if (text.trim() || thinking.trim() || tools.length > 0)
+        items.push({ role: "assistant", text, ...(thinking.trim() ? { thinking } : {}), tools });
+    } else if (m.role === "toolResult") {
+      const callId = String(m.toolCallId ?? "");
+      const result = contentText(m.content);
+      for (let i = items.length - 1; i >= 0; i--) {
+        const it = items[i];
+        if (!it) continue;
+        const tool = it.tools.find((t) => t.callId === callId);
+        if (tool) {
+          tool.result = result;
+          break;
+        }
+      }
+    }
+  }
+  return items;
+}
+
+/** Map browser image attachments to pi's ImageContent shape (or undefined). */
+export function toPiImages(images?: ImageAttachment[]): ImageContent[] | undefined {
+  if (!images || images.length === 0) return undefined;
+  return images.map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType }));
+}
+
+// ---- Message actions: regenerate / edit-and-resend (pure helpers) ----
+//
+// Both features reuse ONE pi SDK primitive: AgentSession.navigateTree(entryId)
+// on a user-message entry moves the session's leaf pointer to that entry's
+// PARENT (without deleting anything) and returns the message's own text in
+// `editorText`. Calling session.prompt(...) right after appends a NEW child
+// under that same parent — i.e. a sibling of the original message, in the
+// SAME session file. This is exactly "regenerate" (re-send the identical
+// content) and "edit-and-resend" (re-send edited content) without any
+// file-level fork/session spam.
+//
+// navigateTree's own editorText is TEXT-ONLY (pi's editor-reopen use case
+// doesn't carry images). We extract the full original `content` ourselves
+// (text + images) from the entry directly so regenerate/edit-resend don't
+// silently drop image attachments — a small improvement over what the SDK
+// primitive alone would give us.
+
+/** One user message entry as found by findLastUserMessageEntry/userMessageSiblings. */
+export interface UserMessageEntryInfo {
+  id: string;
+  parentId: string | null;
+  text: string;
+  images: ImageContent[];
+}
+
+/** Extract {text, images} from a user message's raw `content` field
+ *  (string | (TextContent|ImageContent)[]). Pure. */
+function extractUserContent(content: unknown): { text: string; images: ImageContent[] } {
+  if (typeof content === "string") return { text: content, images: [] };
+  if (Array.isArray(content)) {
+    const text = contentText(content);
+    const images = (content as unknown[])
+      .filter((p): p is { type: string; data: string; mimeType: string } =>
+        !!p && (p as { type?: string }).type === "image" &&
+        typeof (p as { data?: unknown }).data === "string" && typeof (p as { mimeType?: unknown }).mimeType === "string")
+      .map((p) => ({ type: "image" as const, data: p.data, mimeType: p.mimeType }));
+    return { text, images };
+  }
+  return { text: "", images: [] };
+}
+
+/** Find the LAST user-message entry in a session's entries (in append order).
+ *  Used by both `regenerate` (re-send it as-is) and as the sibling group's
+ *  anchor for `edit_resend` (always edits the last user message, not any
+ *  earlier one). Pure. */
+export function findLastUserMessageEntry(entries: readonly SessionEntry[]): UserMessageEntryInfo | undefined {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (!e || e.type !== "message") continue;
+    const m = (e as { message?: { role?: string; content?: unknown } }).message;
+    if (m?.role !== "user") continue;
+    const { text, images } = extractUserContent(m.content);
+    return { id: e.id, parentId: e.parentId, text, images };
+  }
+  return undefined;
+}
+
+/** Sibling group (edit history) for a user message: every user-message entry
+ *  sharing the same parentId, in append order, plus the 1-based index of
+ *  `entryId` within that group. Drives the browser's `< i/n >` toggle. Pure. */
+export interface SiblingGroup {
+  parentId: string | null;
+  siblingIds: string[];
+  index: number; // 1-based position of the queried entryId within siblingIds
+}
+
+export function userMessageSiblings(entries: readonly SessionEntry[], entryId: string): SiblingGroup | undefined {
+  const target = entries.find((e) => e.id === entryId);
+  if (!target) return undefined;
+  const parentId = target.parentId;
+  const siblingIds = entries
+    .filter((e): e is SessionEntry & { type: "message" } =>
+      e.type === "message" && e.parentId === parentId &&
+      (e as { message?: { role?: string } }).message?.role === "user")
+    .map((e) => e.id);
+  const index = siblingIds.indexOf(entryId) + 1;
+  if (index === 0) return undefined;
+  return { parentId, siblingIds, index };
+}
+
+/** Walk DOWN from an entry to the deepest descendant, always following the
+ *  MOST RECENTLY APPENDED child at each level (last in getChildren's
+ *  insertion order) — i.e. "what would this branch show if it were the
+ *  active leaf". Used by `switch_sibling` to resolve a sibling's own leaf
+ *  (which may itself have further edits/regenerations under it) rather than
+ *  just landing on the sibling's own root entry. Pure given a children-lookup
+ *  function so it's unit-testable without a live SessionManager. */
+export function deepestLeafFrom(fromId: string, getChildren: (parentId: string) => SessionEntry[]): string {
+  let cur = fromId;
+  for (;;) {
+    const children = getChildren(cur);
+    if (children.length === 0) return cur;
+    cur = children[children.length - 1]!.id;
+  }
+}
+
+/** Map pi's SessionInfo[] to sidebar rows, newest first. */
+export function toSessionListItems(infos: readonly SessionInfo[]): SessionListItem[] {
+  return infos
+    .map((s) => ({
+      path: s.path,
+      id: s.id,
+      title: ((s.name && s.name.trim()) || (s.firstMessage && s.firstMessage.trim()) || "New chat").slice(0, 80),
+      modified: s.modified instanceof Date ? s.modified.getTime() : new Date(s.modified as unknown as string).getTime(),
+      messageCount: s.messageCount,
+      forked: !!s.parentSessionPath,
+    }))
+    .sort((a, b) => b.modified - a.modified);
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+import type { AppModule, ModuleRuntime } from "@mlx-bun/app-core";
+import { createChatSocket, type ChatBackendFactory } from "./backend";
+import { describeModel, type ServedModel } from "./describe";
+import { createExtensionSurface } from "./extensions";
+import { manifest } from "./manifest";
+import { startModelBridge, type ModelBridge } from "./model-bridge";
+import { createPiBackend } from "./pi-backend";
+import { createChatHandlers } from "./routes";
+
+export { manifest } from "./manifest";
+export { createChatSocket } from "./backend";
+export type { ChatBackend, ChatBackendFactory, SendFrame } from "./backend";
+export { describeModel } from "./describe";
+export type { ServedModel } from "./describe";
+export { createExtensionSurface, piTool } from "./extensions";
+export { generateThroughHost, startModelBridge } from "./model-bridge";
+export type { ModelBridge } from "./model-bridge";
+export { createPiBackend } from "./pi-backend";
+export type { PiBackendOptions, PiBackendPaths } from "./pi-backend";
+export { createChatHandlers } from "./routes";
+export type { ChatRoutePaths } from "./routes";
+export { readSessionFile, recordedSessionCwd, sessionEntries } from "./session-files";
+export { searchSessions } from "./session-search";
+export { isToolAlwaysAllowed, listAlwaysAllowedTools, loadToolApprovals, revokeToolAlwaysAllowed, setToolAlwaysAllowed } from "./tool-approvals";
+export type * from "./protocol";
+
+/** What a host decides for the chat beyond its services. */
+export interface ChatModuleOptions {
+  /** A read-only server: the agent gets no file-changing tool and every gated call is denied. Default false. */
+  readOnly?: boolean;
+  /** The working directory Pi's tools and the session header record; default the process's. */
+  cwd?: string;
+}
+
+/** The chat module. The host implements `modelHost` (the current model's `generate`), `storage` (`sessions/`, `pi-sessions/`, `tool-approvals.json`) and `registry`. */
+export function createChatModule(options: ChatModuleOptions = {}): AppModule<"modelHost" | "storage" | "registry"> {
+  return {
+    ...manifest,
+    activate({ services }): ModuleRuntime {
+      const { modelHost, storage, registry } = services;
+      const paths = () => ({ agentDir: storage.path("agent"), sessionDir: storage.path("sessions"), toolApprovalsFile: storage.path("approvals") });
+      let bridge: ModelBridge | undefined;
+      const token = crypto.randomUUID();
+      // The loopback Pi talks to starts with the first chat connection; the port is read when that connection's backend starts.
+      const loopback = () => bridge ??= startModelBridge(modelHost, token);
+      const surface = createExtensionSurface(registry);
+      const factory: ChatBackendFactory = send => {
+        // The model is described when the connection starts (its `ready` frame); its speech-to-text flag comes from the same reading.
+        let served: ServedModel | undefined;
+        return createPiBackend({
+          paths: { ...paths(), ...(options.cwd ? { cwd: options.cwd } : {}) },
+          port: () => loopback().port, apiKey: token,
+          readOnly: options.readOnly ?? false, memory: surface,
+          model: async () => {
+            served = await describeModel(modelHost);
+            return { modelId: served.modelId, contextWindow: served.contextWindow, vision: served.vision, audio: served.audio, thinking: served.thinking, genDefaults: served.genDefaults };
+          },
+          transcription: async () => served?.transcription ?? false,
+        })(send);
+      };
+      const socket = createChatSocket(factory);
+      return {
+        routes: createChatHandlers({ sessionDir: () => storage.path("sessions"), approvalsFile: () => storage.path("approvals") }),
+        sockets: { chat: socket },
+        status: () => ({ chats: socket.connections, loopback: bridge !== undefined }),
+        async dispose() {
+          try { await socket.dispose(); } finally { await bridge?.close(); }
+        },
+      };
+    },
+  };
+}
+
+export default createChatModule();

package/src/manifest.ts

@@ -0,0 +1,26 @@
+// The module's static manifest: plain data, read by hosts and documentation generators without
+// loading a model or native code (this file imports only types). `index.ts` adds `activate`.
+import type { AppModule } from "@mlx-bun/app-core";
+
+export const manifest = {
+  id: "chat",
+  title: "Chat",
+  summary: "The default assistant: a Pi agent over the served model, on a WebSocket per browser tab, with recent chats, tool approvals, and the tools other modules contribute.",
+  requires: ["modelHost", "storage", "registry"],
+  // Session routes keep their shipped paths: the browser and external tools read them at `/api/sessions/*`, the settings at `/api/settings/tool-approvals`.
+  routes: [
+    { id: "sessions-search", method: "GET", path: "/api/sessions/search", summary: "Search saved chats by title and content (`q`); read-only", response: "json", mount: "root" },
+    { id: "sessions-export", method: "GET", path: "/api/sessions/export", summary: "One saved chat's raw entries (`path`, under the session directory); read-only", response: "json", mount: "root" },
+    { id: "approvals", method: "GET", path: "/api/settings/tool-approvals", summary: "The tools the user chose to always allow", response: "json", mount: "root" },
+    { id: "approvals-revoke", method: "DELETE", path: "/api/settings/tool-approvals", summary: "Forget one always-allow choice (`tool` in the JSON body)", response: "json", mount: "root" },
+  ],
+  sockets: [
+    { id: "chat", path: "/ws/chat", summary: "One chat session per connection: prompts, streamed tokens, tool cards and approvals, saved-chat management", mount: "root" },
+  ],
+  storage: [
+    { key: "sessions", path: "sessions", kind: "directory", purpose: "Saved chats, one Pi JSONL file each (also read by the memory pipeline)" },
+    { key: "agent", path: "pi-sessions", kind: "directory", purpose: "The Pi agent's own directory" },
+    { key: "approvals", path: "tool-approvals.json", kind: "file", purpose: "Tools the user chose to always allow, mode 0600" },
+  ],
+  panel: { tag: "mlx-chat-panel", entry: "@mlx-bun/module-chat/panel", title: "Chat", path: "/chat", workspace: true },
+} as const satisfies Omit<AppModule<"modelHost" | "storage" | "registry">, "activate">;

package/src/model-bridge.ts

@@ -0,0 +1,75 @@
+// The loopback the Pi SDK talks to. Pi's OpenAI client reaches its model over HTTP and takes no
+// transport of ours, so the module answers on a private loopback listener, and every request goes
+// through the `modelHost` service: a lease on the current model, its `generate` operation, and a
+// release when the response body ends. A model switch is followed because each request asks the
+// host for the current model; the request's own `model` field (Pi's `local`) is the host's to route.
+// The listener is created on the first chat connection, takes only Pi's per-run bearer token, and
+// closes with the module.
+import type { ModelHost, ModelLease } from "@mlx-bun/app-core";
+
+export interface ModelBridge {
+  readonly port: number;
+  /** What Pi sends as its API key; any other bearer is refused. */
+  readonly token: string;
+  close(): Promise<void>;
+}
+
+/** The path the model host receives; a host's `generate` ignores the origin. */
+const WIRE = "http://model.local/v1/chat/completions";
+
+const failure = (status: number, message: string, type: string) => Response.json({ error: { message, type } }, { status });
+
+/** A response that holds its lease until the body has ended, been cancelled or failed. */
+function holding(response: Response, lease: ModelLease): Response {
+  if (!response.body) { lease.release(); return response; }
+  const reader = response.body.getReader();
+  let done = false;
+  const finish = () => { if (!done) { done = true; lease.release(); } };
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read();
+        if (chunk.done) { finish(); controller.close(); } else controller.enqueue(chunk.value);
+      } catch (error) { finish(); controller.error(error); }
+    },
+    cancel(reason) { finish(); return reader.cancel(reason).catch(() => {}); },
+  });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+
+/** Forwards one chat completion to the current model. */
+export async function generateThroughHost(models: Pick<ModelHost, "acquire" | "defaultFor">, request: Request): Promise<Response> {
+  let lease: ModelLease;
+  try {
+    const id = await models.defaultFor("generate");
+    if (id === undefined) return failure(503, "no model is served", "model_unavailable");
+    lease = await models.acquire(id, { need: ["generate"], signal: request.signal });
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    return failure(code === "closed" ? 503 : code === "load-failed" ? 502 : 400, error instanceof Error ? error.message : String(error), "model_unavailable");
+  }
+  try {
+    const generate = lease.operations.generate;
+    if (!generate) { lease.release(); return failure(400, `model ${lease.model.id} cannot generate`, "model_unavailable"); }
+    const headers = new Headers(request.headers);
+    headers.delete("authorization");
+    return holding(await generate(new Request(WIRE, { method: "POST", headers, body: await request.arrayBuffer(), signal: request.signal })), lease);
+  } catch (error) {
+    lease.release();
+    if (request.signal.aborted) return new Response(null, { status: 499 });
+    return failure(502, error instanceof Error ? error.message : String(error), "model_unavailable");
+  }
+}
+
+export function startModelBridge(models: Pick<ModelHost, "acquire" | "defaultFor">, token: string = crypto.randomUUID()): ModelBridge {
+  const server = Bun.serve({
+    hostname: "127.0.0.1", port: 0, idleTimeout: 0,
+    async fetch(request) {
+      const { pathname } = new URL(request.url);
+      if (request.headers.get("authorization") !== `Bearer ${token}`) return failure(401, "unauthorized", "invalid_api_key");
+      if (request.method !== "POST" || pathname !== "/v1/chat/completions") return failure(404, "not found", "not_found");
+      return generateThroughHost(models, request);
+    },
+  });
+  return { port: server.port!, token, close: async () => { await server.stop(true); } };
+}

package/src/panel/adapters-panel.ts

@@ -0,0 +1,287 @@
+// Part of the chat panel (`@mlx-bun/module-chat`), bundled into the app's browser build.
+//
+// Adapter routing table: the deep surface behind
+// the composer's ⚙ button beside #chat-adapter. Shows every on-disk
+// adapter with its three states (available / loaded+mounted /
+// selected-for-this-chat), base model, rank, size on disk, and RAM cost
+// when mounted (GET /v1/adapters now reports `ram_bytes` — see
+// `02d723a:docs/reference/server-api.md`), with compatible-graying and a why-not
+// tooltip. Actions: mount, select, unselect, and stack two compatible
+// adapters as "a+b" — resolveSpec/injectAdapter already support composite
+// ids end to end (proved in packages/module-chat/tests/chat-policy.test.ts's stacking
+// test; the shape-validated mount is proved against real weights in the
+// MLX_BUN_TEST_LORA=1-gated `02d723a:tests/parity/lora.test.ts`).
+//
+// Single source of SELECTION state, not a single fetch: composer.ts's quick
+// <select> and this table each hit /v1/adapters(+/available) independently
+// (same endpoints, same shapes) rather than sharing one in-memory cache —
+// but chat.ts keeps them from disagreeing about what's SELECTED by writing
+// through both on every change (adapterSel.onchange syncs
+// adaptersPanel.selectedSpec; this table's actions sync #chat-adapter's
+// value back). What must never drift is which adapter(s) are active for
+// the chat, not which HTTP call fetched the list.
+
+import { $, api, toast, trapFocus, type FocusTrap } from "./dom";
+import { esc } from "./markdown";
+import { setPopoverClose } from "./popovers";
+
+/** Shape returned by GET /v1/adapters/available (on-disk, unfiltered). */
+export interface AvailableAdapterRow {
+  id: string;
+  path: string;
+  rank: number | null;
+  scale: number;
+  base_model: string | null;
+  mounted: boolean;
+  compatible: boolean;
+}
+
+/** Shape returned by GET /v1/adapters (mounted only, with RAM cost). */
+export interface MountedAdapterRow {
+  id: string;
+  path: string;
+  rank: number | null;
+  scale: number;
+  size_bytes: number;
+  mounted_layers: number;
+  ram_bytes: number;
+}
+
+function fmtBytes(n: number | null | undefined): string {
+  if (n == null) return "—";
+  if (n >= 2 ** 20) return (n / 2 ** 20).toFixed(1) + " MB";
+  if (n >= 2 ** 10) return (n / 2 ** 10).toFixed(1) + " KB";
+  return n + " B";
+}
+
+/** Send callback type shared with the rest of chat.ts's WS wiring. */
+type Send = (obj: unknown) => boolean;
+
+export class AdaptersPanelState {
+  available: AvailableAdapterRow[] = [];
+  mounted: Map<string, MountedAdapterRow> = new Map();
+  /** The composer's current single-select value ("" = none), kept in sync
+   *  so the table can show which one/ones are "selected for this chat". */
+  selectedSpec: string | null = null;
+  /** Multi-select scratch state for the "stack" flow — ids the user has
+   *  ticked in the table before hitting "apply stack". Cleared on apply. */
+  stackPicks: Set<string> = new Set();
+}
+
+let trap: FocusTrap | null = null;
+
+/** Fetch both adapter endpoints once and refresh every dependent view: the
+ *  table body (if open, with its actions re-wired against `send`) and the
+ *  composer's quick <select> (renderAdapterOptionsHtml, imported from
+ *  composer.ts — one source of truth, not a second fetch). `send` is
+ *  required (not optional) so a refresh never silently leaves the table's
+ *  mount/select/stack buttons wired to a no-op. */
+export async function refreshAdaptersPanel(state: AdaptersPanelState, send: Send): Promise<void> {
+  const [availD, mountedD] = await Promise.all([
+    api("/v1/adapters/available").catch(() => ({ ok: false } as const)),
+    api("/v1/adapters").catch(() => ({ ok: false } as const)),
+  ]);
+  state.available = ((availD as { adapters?: AvailableAdapterRow[] }).adapters) || [];
+  const mountedList = ((mountedD as { adapters?: MountedAdapterRow[] }).adapters) || [];
+  state.mounted = new Map(mountedList.map((a) => [a.id, a]));
+  // Drop stack picks for adapters that vanished from disk (e.g. an
+  // in-flight delete elsewhere).
+  for (const id of [...state.stackPicks]) if (!state.available.some((a) => a.id === id)) state.stackPicks.delete(id);
+  renderAdaptersBody(state, send);
+}
+
+/** Parse the composer's currently-selected spec ("" | "id" | "a+b") into
+ *  the set of ids it names, for the table's per-row "selected" badge. */
+function selectedIds(state: AdaptersPanelState): Set<string> {
+  const spec = state.selectedSpec;
+  if (!spec) return new Set();
+  return new Set(spec.split("+").map((s) => s.trim()).filter(Boolean));
+}
+
+/** Render one adapter row: id/badges, base-model/rank/size/RAM meta line,
+ *  incompatible-why note, and the mount/select/unselect/stack actions.
+ *  Pure enough to unit-test (no fetch inside), takes callbacks for the
+ *  actions so the DOM wiring lives in one place (initAdaptersPanel). */
+export function renderAdapterRow(
+  a: AvailableAdapterRow,
+  opts: {
+    mountedInfo: MountedAdapterRow | undefined;
+    isSelected: boolean;
+    stackPicked: boolean;
+    stackModeOn: boolean;
+  },
+): string {
+  const { mountedInfo, isSelected, stackPicked, stackModeOn } = opts;
+  const rowClasses = ["ad-row"];
+  if (!a.compatible) rowClasses.push("incompatible");
+  if (isSelected) rowClasses.push("selected");
+  const badges: string[] = [];
+  if (mountedInfo) badges.push('<span class="ad-badge mounted">mounted</span>');
+  if (isSelected) badges.push('<span class="ad-badge selected">selected</span>');
+  const meta: string[] = [];
+  if (a.base_model) meta.push("base <b>" + esc(a.base_model.split("/").pop()) + "</b>");
+  if (a.rank) meta.push("rank <b>" + esc(a.rank) + "</b>");
+  meta.push("disk <b>" + esc(fmtBytes(mountedInfo ? mountedInfo.size_bytes : null) === "—" ? "—" : fmtBytes(mountedInfo ? mountedInfo.size_bytes : null)) + "</b>");
+  if (mountedInfo) meta.push("RAM <b>" + esc(fmtBytes(mountedInfo.ram_bytes)) + "</b>");
+  const why = !a.compatible
+    ? '<div class="ad-why">' + (a.base_model
+        ? "trained for " + esc(a.base_model) + ", not the currently-served model"
+        : "not compatible with the currently-served model") + "</div>"
+    : "";
+  const actions: string[] = [];
+  if (a.compatible) {
+    if (stackModeOn) {
+      actions.push(
+        '<label class="ad-stack-chk"><input type="checkbox" class="ad-stack-pick" data-id="' + esc(a.id) + '"' +
+        (stackPicked ? " checked" : "") + (!mountedInfo ? " disabled title=\"mount first to stack it\"" : "") + '> stack</label>',
+      );
+    }
+    if (!mountedInfo) {
+      actions.push('<button type="button" class="ad-mount" data-id="' + esc(a.id) + '" data-path="' + esc(a.path) + '">Mount</button>');
+    } else if (!isSelected) {
+      actions.push('<button type="button" class="ad-select primary" data-id="' + esc(a.id) + '">Select</button>');
+    } else {
+      actions.push('<button type="button" class="ad-unselect" data-id="' + esc(a.id) + '">Unselect</button>');
+    }
+  }
+  return (
+    '<div class="' + rowClasses.join(" ") + '" data-adapter-row="' + esc(a.id) + '">' +
+      '<div class="ad-row-main">' +
+        '<div class="ad-row-head"><span class="ad-row-id" title="' + esc(a.id) + '">' + esc(a.id) + "</span>" + badges.join("") + "</div>" +
+        '<div class="ad-meta">' + meta.join(" · ") + "</div>" +
+        why +
+      "</div>" +
+      '<div class="ad-actions">' + actions.join("") + "</div>" +
+    "</div>"
+  );
+}
+
+/** Full table body: a stack-mode toggle + composed-spec bar (when picks
+ *  exist), then one section of rows. Exported so packages/module-chat/tests/panel.test.ts can
+ *  exercise esc() discipline without a live DOM/network. */
+export function renderAdaptersBodyHtml(state: AdaptersPanelState): string {
+  if (!state.available.length) {
+    return (
+      '<div class="ad-empty">No adapters found on disk yet.<br>' +
+      "Fine-tune one in the Developer tab, or drop an adapter directory into " +
+      "<code>~/.mlx-bun/adapters</code>.</div>"
+    );
+  }
+  const selected = selectedIds(state);
+  const stackModeOn = state.stackPicks.size > 0 || selected.size > 1;
+  const rows = state.available.map((a) => renderAdapterRow(a, {
+    mountedInfo: state.mounted.get(a.id),
+    isSelected: selected.has(a.id),
+    stackPicked: state.stackPicks.has(a.id),
+    stackModeOn,
+  })).join("");
+  const picks = [...state.stackPicks];
+  const stackBar = picks.length
+    ? '<div class="ad-stack-bar"><span class="lbl">Stack:</span><span class="expr">' +
+        esc(picks.join(" + ")) + '</span><button type="button" id="ad-stack-apply" class="ad-actions-btn">Apply</button>' +
+        '<button type="button" id="ad-stack-clear" class="ad-actions-btn">Clear</button></div>'
+    : "";
+  return (
+    '<div class="ad-note">Every adapter found on disk, mounted or not. Mounting loads it into ' +
+    "memory (RAM cost shown once mounted); selecting makes it active for this chat's next turn " +
+    "(a fresh KV segment). Tick two mounted adapters' “stack” boxes to compose them as " +
+    '<code>a+b</code> — the server already supports it end to end.</div>' +
+    stackBar +
+    '<div class="ad-sec-title">On disk (' + state.available.length + ")</div>" +
+    rows
+  );
+}
+
+function renderAdaptersBody(state: AdaptersPanelState, send: Send): void {
+  const body = $("adapters-body");
+  if (!body) return;
+  body.innerHTML = renderAdaptersBodyHtml(state);
+  wireRowActions(state, send);
+}
+
+function wireRowActions(state: AdaptersPanelState, send: Send): void {
+  const body = $("adapters-body");
+  if (!body) return;
+  body.querySelectorAll<HTMLButtonElement>(".ad-mount").forEach((btn) => {
+    btn.onclick = async () => {
+      const id = btn.dataset.id!, path = btn.dataset.path!;
+      btn.disabled = true; btn.textContent = "Mounting…";
+      const r = await api("/v1/adapters", { method: "POST", body: { id, path } });
+      if (r && (r.error || r.ok === false)) {
+        toast("adapter: " + (r.error || "mount failed"), "err");
+        btn.disabled = false; btn.textContent = "Mount";
+        return;
+      }
+      toast("mounted " + id, "ok");
+      await refreshAdaptersPanel(state, send);
+    };
+  });
+  body.querySelectorAll<HTMLButtonElement>(".ad-select").forEach((btn) => {
+    btn.onclick = () => {
+      const id = btn.dataset.id!;
+      state.selectedSpec = id;
+      state.stackPicks.clear();
+      send({ type: "set_adapter", id });
+      const sel = $("chat-adapter") as HTMLSelectElement | null;
+      if (sel && [...sel.options].some((o) => o.value === id)) sel.value = id;
+      toast("adapter selected — new turns start a fresh KV segment", "ok");
+      renderAdaptersBody(state, send);
+    };
+  });
+  body.querySelectorAll<HTMLButtonElement>(".ad-unselect").forEach((btn) => {
+    btn.onclick = () => {
+      state.selectedSpec = null;
+      send({ type: "set_adapter", id: null });
+      const sel = $("chat-adapter") as HTMLSelectElement | null;
+      if (sel) sel.value = "";
+      renderAdaptersBody(state, send);
+    };
+  });
+  body.querySelectorAll<HTMLInputElement>(".ad-stack-pick").forEach((chk) => {
+    chk.onchange = () => {
+      const id = chk.dataset.id!;
+      if (chk.checked) state.stackPicks.add(id); else state.stackPicks.delete(id);
+      renderAdaptersBody(state, send);
+    };
+  });
+  const apply = $("ad-stack-apply") as HTMLButtonElement | null;
+  if (apply) apply.onclick = () => {
+    if (state.stackPicks.size < 2) { toast("stack needs at least two ticked adapters", "err"); return; }
+    const spec = [...state.stackPicks].join("+");
+    state.selectedSpec = spec;
+    send({ type: "set_adapter", id: spec });
+    const sel = $("chat-adapter") as HTMLSelectElement | null;
+    if (sel) sel.value = ""; // composite spec has no matching single <option>
+    toast("stacked " + spec + " — new turns start a fresh KV segment", "ok");
+    renderAdaptersBody(state, send);
+  };
+  const clear = $("ad-stack-clear") as HTMLButtonElement | null;
+  if (clear) clear.onclick = () => { state.stackPicks.clear(); renderAdaptersBody(state, send); };
+}
+
+function openPanel(state: AdaptersPanelState, send: Send): void {
+  const ov = $("adapters-overlay");
+  ov.classList.add("open");
+  $("adapters-manage").setAttribute("aria-expanded", "true");
+  if (trap) trap.capture();
+  refreshAdaptersPanel(state, send);
+}
+export function closeAdaptersPanel(): void {
+  $("adapters-overlay").classList.remove("open");
+  $("adapters-manage").setAttribute("aria-expanded", "false");
+  if (trap) trap.restore();
+}
+
+/** Wire the ⚙ button + overlay close affordances. Escape is handled by the
+ *  global closeTopOverlay sweep in shell.ts (one mechanism, not a bespoke
+ *  listener per overlay — same pattern as the HF modal / sampling popover). */
+export function initAdaptersPanel(state: AdaptersPanelState, send: Send): void {
+  const btn = $("adapters-manage");
+  if (!btn) return;
+  trap = trapFocus($("adapters-panel"), () => $("adapters-overlay").classList.contains("open"));
+  btn.onclick = () => openPanel(state, send);
+  const close = $("adapters-close");
+  if (close) close.onclick = closeAdaptersPanel;
+  $("adapters-overlay").addEventListener("click", (e) => { if (e.target === $("adapters-overlay")) closeAdaptersPanel(); });
+  setPopoverClose("adapters-overlay", closeAdaptersPanel);
+}