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

package/src/protocol.ts

@@ -0,0 +1,265 @@
+/** Shared browser/server protocol. Data only; no SDK, DOM, or native imports. */
+export const APP_ROUTE_IDS = ["chat", "quantize", "finetune", "dataset", "status"] as const;
+
+export type ApprovalDecision = "allow" | "deny";
+
+export interface ImageAttachment {
+  data: string;
+  mimeType: string;
+}
+
+export type ClientMessage =
+  | { type: "prompt"; text: string; images?: ImageAttachment[] }
+  | { type: "abort" }
+  // `editedArgs`: when the user edited the proposed arguments in the
+  // approval card's textarea before approving, the (re-parsed) JSON object
+  // to substitute for the tool's original input — mutated onto the pi SDK's
+  // ToolCallEvent.input in place (the SDK's documented mutation contract;
+  // see installApprovalGate). Ignored on "deny". `alwaysAllow`: persist this
+  // tool to the durable always-allow config (chat/tool-approvals.ts) so
+  // future calls to the SAME TOOL NAME skip the card entirely, on this and
+  // every other session.
+  | { type: "approval"; callId: string; decision: ApprovalDecision; editedArgs?: Record<string, unknown>; alwaysAllow?: boolean }
+  // Toggle the model's reasoning channel on/off (only meaningful when the
+  // model supports thinking — ready.thinking). Maps to Pi's session thinking
+  // level: "medium" (on) ↔ "off". Pi sends it as enable_thinking to the server.
+  | { type: "set_thinking"; enabled: boolean }
+  // Opt-in toggle (default OFF): "let the agent
+  // touch files on this machine". Persisted per-browser by the client
+  // (localStorage `mlxbun.codingTools`); the ALLOWLIST decision is enforced
+  // here, server-side. buildPiAgentSurface's tool list is fixed for the
+  // life of an AgentSession (pi's DefaultResourceLoader config is baked in
+  // at createAgentSessionServices time), so this can't rewire an
+  // in-progress session — it takes effect starting with the next
+  // new_session/open_session/fork_session (createRuntimeFactory reads
+  // this.codingToolsRequested fresh every time the SDK calls it, including
+  // from AgentSessionRuntime.newSession()'s internal re-invocation). The
+  // `coding_tools` ServerMessage below reports the honest current-vs-pending
+  // state so the UI can say so instead of implying it applies immediately.
+  | { type: "set_coding_tools"; enabled: boolean }
+  // Select the active LoRA adapter for subsequent turns (null = none/base).
+  // app.html mounts it (POST /v1/adapters) before sending this; the
+  // before_provider_request hook injects it into the provider payload.
+  | { type: "set_adapter"; id: string | null }
+  // Per-request sampling overrides. Each field is optional; null/undefined
+  // means "leave it to the server default" (the mode-aware recommended
+  // value resolved in toOptions). A present numeric value is injected into
+  // the provider payload and always wins. The before_provider_request hook
+  // injects whatever is set here.
+  //
+  // `scope` (`02d723a:docs/design/web-chat-redesign.md` Appendix A,
+  // beat-matrix Axis 4 "per-message sampling scope"): "session" (default,
+  // omitting the field means this too) persists
+  // the override on the connection until changed — today's behavior,
+  // unchanged. "next_turn" stores a ONE-SHOT override applied to exactly
+  // the next prompt's injection, then cleared automatically — it never
+  // touches the session-level values (a later plain set_sampling with
+  // scope:"session" or omitted still sees whatever was there before this
+  // message). Composition when both are present: next_turn's SET fields
+  // win over session's for that one request; anything next_turn leaves
+  // null/unset falls back to the session-level override for that field
+  // (composeSampling — session-level itself falls back to the server's
+  // mode-aware default per injectSampling's existing contract).
+  | {
+      type: "set_sampling";
+      scope?: "session" | "next_turn";
+      temperature?: number | null;
+      top_p?: number | null;
+      top_k?: number | null;
+      min_p?: number | null;
+      xtc_probability?: number | null;
+      xtc_threshold?: number | null;
+      repetition_penalty?: number | null;
+      repetition_context_size?: number | null;
+      presence_penalty?: number | null;
+      frequency_penalty?: number | null;
+      seed?: number | null;
+    }
+  // Per-session USER system prompt, layered ON TOP OF (not replacing) the
+  // built-in surface prompt (buildWebChatSystemPrompt + memoryHint). null
+  // clears it. Applied by the before_agent_start hook on the NEXT turn (pi
+  // calls it fresh inside every session.prompt(), so this is a true
+  // per-turn injection, not a session-creation-only setting — see
+  // installSystemPromptHook). Presets v1 (composer.ts) send this alongside
+  // set_sampling to apply a saved bundle.
+  | { type: "set_system_prompt"; text: string | null }
+  // Session management (recent-chats sidebar + new chat).
+  | { type: "new_session" }
+  | { type: "list_sessions" }
+  | { type: "open_session"; path: string }
+  | { type: "fork_session"; path: string }
+  | { type: "delete_session"; path: string }
+  // Message actions. All three navigate the session's leaf
+  // pointer via AgentSession.navigateTree() then re-prompt — a sibling
+  // branch in the SAME session file, never a new one (see the helpers above
+  // findLastUserMessageEntry for the full rationale). Regenerate re-sends the
+  // last user message's original content verbatim; edit_resend re-sends it
+  // with edited text (images preserved); switch_sibling moves the active
+  // leaf to a previously-created sibling (an earlier edit/regeneration)
+  // without sending anything new.
+  | { type: "regenerate" }
+  | { type: "edit_resend"; text: string }
+  | { type: "switch_sibling"; entryId: string }
+  // App-aware assistant (`02d723a:docs/design/web-chat-redesign.md` Appendix A,
+  // beat-matrix Axis 12): pushed
+  // by chat.ts on every route change AND on wizard-step change (quantize/
+  // finetune/dataset), never on a timer. `context` is opaque here (the
+  // browser's AppContext shape, packages/module-chat/src/panel/assistant.ts) — stored verbatim
+  // as the connection's currentAppContext and returned by the
+  // get_current_app_context tool, plus mined for the compact one-line
+  // ambient context auto-prepended to the NEXT prompt (see
+  // installAppContextHook / ambientContextLine). This is a DIFFERENT frame
+  // from the server->client `context` ServerMessage (context-window usage,
+  // above) — same name, opposite direction, disambiguated by which type
+  // union it's a member of; the two are never in scope at the same call
+  // site (ClientMessage here vs. ServerMessage below).
+  | { type: "context"; context: AppUiContext };
+
+export interface UiSnapshotElement {
+  ref: string;
+  tag: string;
+  label: string;
+  kind: "interactive" | "region";
+  role?: string;
+  selector: string;
+  spotlightId?: string;
+}
+
+export interface UiSnapshot {
+  route: string;
+  capturedAt: string;
+  elements: UiSnapshotElement[];
+}
+
+export interface WizardStep {
+  index: number;
+  count: number;
+  label: string;
+}
+
+export interface AppUiContext {
+  route: string;
+  view?: string;
+  step?: WizardStep;
+  snapshot: UiSnapshot;
+}
+
+export type AppRouteId = (typeof APP_ROUTE_IDS)[number];
+
+export interface ReadyGenDefaults {
+  temperature: number | null;
+  topP: number | null;
+  topK: number | null;
+}
+
+export type ServerMessage =
+  // `vision`: whether the loaded model can accept images (drives the UI's
+  // image-attach affordance — false on e4b until the SigLIP sidecar lands).
+  // `audio`: whether the loaded model can accept `input_audio` parts (audio
+  // tower loaded or loadable). Discovery-only for now: pi's Model.input type
+  // has no "audio" modality, so unlike `vision` this flag never feeds the
+  // provider declaration — clients use it instead of probing for a 400.
+  // `thinking`: whether the model has a switchable reasoning channel (drives
+  // the UI's thinking on/off toggle; false hides it).
+  // transcription: a Whisper checkpoint is configured or resolvable for
+  // /v1/audio/sessions — drives the composer's hold-to-talk mic button.
+  | { type: "ready"; model: string; vision: boolean; audio: boolean; thinking: boolean; genDefaults: ReadyGenDefaults; transcription?: boolean }
+  | { type: "turn_start" }
+  | { type: "text_delta"; delta: string }
+  | { type: "thinking_delta"; delta: string }
+  | { type: "tool_start"; callId: string; tool: string; args: unknown }
+  | { type: "tool_approval_request"; callId: string; tool: string; args: unknown }
+  | { type: "tool_update"; callId: string; chunk: unknown }
+  | { type: "tool_end"; callId: string; ok: boolean; result: unknown }
+  | { type: "turn_end" }
+  | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
+  // Replay a session's transcript (rebuilds the thread); and the sidebar list.
+  | { type: "history"; items: HistoryItem[] }
+  | { type: "sessions"; items: SessionListItem[]; activePath?: string }
+  // Sibling group for the LAST user message (edit-and-resend's `< i/n >`
+  // toggle). Sent after every history rebuild and after a
+  // completed turn. `count` <= 1 means no toggle to show (the common case:
+  // no edits/regenerations yet). `entryId` is the currently-active sibling's
+  // id; `siblingIds` is the full ordered group so the client can resolve
+  // "previous/next" locally and send switch_sibling with a concrete id
+  // (never inferred/guessed — the server is the source of truth for order).
+  | { type: "siblings"; entryId?: string; index: number; count: number; siblingIds: string[] }
+  // Context-window usage indicator. tokens/percent are null right after a
+  // compaction until the next assistant reply (pi can't estimate yet).
+  | { type: "context"; tokens: number | null; contextWindow: number; percent: number | null }
+  // Effective vs. pending codingTools state (set_coding_tools above).
+  // `active` is what the CURRENT session actually built with (gates
+  // whether the approval card can ever fire); `pending` is the browser's
+  // most recent request, which only takes effect on the next
+  // new/opened/forked session — surfaced so the settings copy can say
+  // "will apply to your next new chat" instead of lying about immediacy.
+  | { type: "coding_tools"; active: boolean; pending: boolean }
+  // Full always-allow set for THIS machine (chat/tool-approvals.ts), sent on
+  // `ready` and after any change, so the settings panel can list/forget
+  // durable per-tool approvals without a separate REST round-trip.
+  | { type: "tool_approvals"; alwaysAllow: string[] }
+  // App-aware assistant: the navigate_app / spotlight_ui tools'
+  // side-channel notifications, mapped 1:1 from the tool call's params —
+  // never guessed or re-derived, so chat.ts's router/spotlight get exactly
+  // what the model asked for. `route` here is always a validated
+  // AppRouteId (isAppRouteId already ran server-side before this frame is
+  // ever sent — see navigate_app's execute). ui_spotlight's fields mirror
+  // SpotlightRequest 1:1 (assistant.ts resolves ref/label/selector/target
+  // client-side, in that precedence order, against its last snapshot).
+  | { type: "ui_navigate"; route: AppRouteId }
+  | { type: "ui_spotlight"; ref?: string; label?: string; selector?: string; target?: string; message?: string; route?: AppRouteId }
+  | { type: "error"; message: string };
+
+export interface HistoryToolItem {
+  callId: string;
+  name: string;
+  args: unknown;
+  /** Tool result text, filled from the matching toolResult message. */
+  result: string;
+}
+
+export interface HistoryItem {
+  role: "user" | "assistant";
+  text: string;
+  /** Model reasoning/thinking, kept separate from the final answer. */
+  thinking?: string;
+  tools: HistoryToolItem[];
+  /** Session entry id (user items only). Lets the browser correlate "the
+   *  last user message" in the replayed thread with the `siblings` frame's
+   *  entryId, so it knows which DOM node gets the edit/sibling-toggle UI.
+   *  Undefined for assistant items — they aren't fork targets. */
+  entryId?: string;
+}
+
+export interface SessionListItem {
+  path: string;
+  id: string;
+  title: string;
+  /** Last-modified epoch ms (newest first). */
+  modified: number;
+  messageCount: number;
+  forked: boolean;
+}
+
+export interface SamplingOverrides {
+  temperature?: number | null;
+  top_p?: number | null;
+  top_k?: number | null;
+  min_p?: number | null;
+  xtc_probability?: number | null;
+  xtc_threshold?: number | null;
+  repetition_penalty?: number | null;
+  repetition_context_size?: number | null;
+  presence_penalty?: number | null;
+  frequency_penalty?: number | null;
+  seed?: number | null;
+}
+
+/** The shared envelope of the module's JSON endpoints and of the app's other `/api/*` ones the panel reads: success or
+ * failure, with an error message and whatever fields the endpoint adds. */
+export interface ApiEnvelope {
+  ok?: boolean;
+  error?: string;
+  message?: string;
+  [key: string]: unknown;
+}

package/src/provider.ts

@@ -0,0 +1,72 @@
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+export interface PiModelOptions {
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  vision?: boolean;
+}
+
+/** Capabilities advertised by the local model through Pi's OpenAI adapter. */
+export function piModelDefinition(options: PiModelOptions = {}) {
+  return {
+    id: "local",
+    name: options.name ?? "mlx-bun (local)",
+    api: "openai-completions" as const,
+    reasoning: options.reasoning ?? false,
+    compat: { supportsDeveloperRole: false, sendSessionAffinityHeaders: true,
+      ...(options.reasoning ? { thinkingFormat: "qwen-chat-template" as const } : {}) },
+    input: (options.vision ? ["text", "image"] : ["text"]) as ("text" | "image")[],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: options.contextWindow ?? 32768,
+    maxTokens: options.maxTokens ?? 100_000,
+  };
+}
+
+export const PI_PROVIDER_ID = "mlx-bun";
+export const PI_API_KEY = "sk-mlx-bun-local";
+export const PI_LOCAL_MODEL_ID = piModelDefinition().id;
+export const PI_API = piModelDefinition().api;
+export const DEFAULT_CONTEXT_WINDOW = piModelDefinition().contextWindow;
+export const DEFAULT_MAX_TOKENS = piModelDefinition().maxTokens;
+
+
+/** A resolved pi model handle. Not re-exported from the package index, so we
+ *  derive it from the registry's `find()` return type. */
+export type PiModel = NonNullable<ReturnType<ModelRegistry["find"]>>;
+
+export interface PiProviderOptions extends PiModelOptions {
+  /** The key Pi sends as its bearer token; default the shared local key. The module's model bridge checks a per-run secret. */
+  apiKey?: string;
+}
+
+export interface PiProviderWiring {
+  authStorage: AuthStorage;
+  modelRegistry: ModelRegistry;
+  model: PiModel;
+}
+
+/**
+ * Build the in-memory auth + registry and resolve the local model for a pi
+ * session pointed at `baseUrl` (e.g. "http://127.0.0.1:8080/v1"). The runtime
+ * key satisfies pi's auth check for our zero-cost local provider; no disk
+ * (no models.json, no ~/.pi cross-talk).
+ */
+export function buildPiProvider(baseUrl: string, opts: PiProviderOptions = {}): PiProviderWiring {
+  const apiKey = opts.apiKey ?? PI_API_KEY;
+  const authStorage = AuthStorage.inMemory();
+  authStorage.setRuntimeApiKey(PI_PROVIDER_ID, apiKey);
+
+  const modelRegistry = ModelRegistry.inMemory(authStorage);
+  modelRegistry.registerProvider(PI_PROVIDER_ID, {
+    baseUrl,
+    apiKey,
+    api: PI_API,
+    models: [piModelDefinition(opts)],
+  });
+
+  const model = modelRegistry.find(PI_PROVIDER_ID, PI_LOCAL_MODEL_ID);
+  if (!model) throw new Error("failed to register mlx-bun/local model");
+  return { authStorage, modelRegistry, model };
+}

package/src/routes.ts

@@ -0,0 +1,49 @@
+// The module's HTTP routes: the read-only session surface (search and export over the session
+// directory) and the durable tool-approval settings. Paths are resolved per request, so a host
+// creates storage entries on first use, not at startup.
+import type { RouteHandler } from "@mlx-bun/app-core";
+import { readSessionFile, sessionEntries } from "./session-files";
+import { searchSessions } from "./session-search";
+import { listAlwaysAllowedTools, revokeToolAlwaysAllowed } from "./tool-approvals";
+
+const error = (message: string, status = 400) => Response.json({ ok: false, error: message }, { status });
+
+export interface ChatRoutePaths {
+  /** The session directory the Pi backend persists to. */
+  sessionDir(): string;
+  /** The always-allow file the approval gate reads. */
+  approvalsFile(): string;
+}
+
+/** Handlers by route id (`manifest.routes`). */
+export function createChatHandlers(paths: ChatRoutePaths): Record<"sessions-search" | "sessions-export" | "approvals" | "approvals-revoke", RouteHandler> {
+  const guarded = (handler: RouteHandler): RouteHandler => async request => {
+    try { return await handler(request); } catch (cause) {
+      console.error(`[chat] ${request.method} ${new URL(request.url).pathname}: ${cause instanceof Error ? cause.message : String(cause)}`);
+      return error(cause instanceof Error ? cause.message : String(cause), 500);
+    }
+  };
+  return {
+    "sessions-search": guarded(async request => {
+      const query = (new URL(request.url).searchParams.get("q") ?? "").trim();
+      if (!query) return error("q is required");
+      return Response.json({ ok: true, results: await searchSessions(paths.sessionDir(), query) });
+    }),
+    "sessions-export": guarded(async request => {
+      const path = (new URL(request.url).searchParams.get("path") ?? "").trim();
+      if (!path) return error("path is required");
+      const file = await readSessionFile(paths.sessionDir(), path);
+      if (!file.ok) return file.reason === "forbidden"
+        ? error("path must be under the session directory", 403) : error("session not found", 404);
+      return Response.json({ ok: true, path, entries: sessionEntries(file.content) });
+    }),
+    approvals: guarded(() => Response.json({ ok: true, alwaysAllow: listAlwaysAllowedTools(paths.approvalsFile()) })),
+    "approvals-revoke": guarded(async request => {
+      const body: unknown = await request.json().catch(() => undefined);
+      const tool = body && typeof body === "object" && !Array.isArray(body) && "tool" in body ? body.tool : undefined;
+      if (typeof tool !== "string" || !tool) return error("tool required");
+      const file = revokeToolAlwaysAllowed(tool, paths.approvalsFile());
+      return Response.json({ ok: true, alwaysAllow: Object.keys(file.allows).sort() });
+    }),
+  };
+}

package/src/session-files.ts

@@ -0,0 +1,36 @@
+import { readFile, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+export function isUnderSessionDir(path: string, sessionDir: string): boolean {
+  const root = resolve(sessionDir), candidate = resolve(path);
+  return candidate === root || candidate.startsWith(root + sep);
+}
+
+export type SessionRead = { ok: true; content: string } | { ok: false; reason: "forbidden" | "not_found" };
+
+/** Check both the submitted path and its resolved target. Configured directory
+ * aliases are allowed, but neither a leaf nor parent symlink may escape it. */
+export async function readSessionFile(sessionDir: string, path: string): Promise<SessionRead> {
+  if (!isUnderSessionDir(path, sessionDir)) return { ok: false, reason: "forbidden" };
+  try {
+    const [root, target] = await Promise.all([realpath(sessionDir), realpath(path)]);
+    if (!isUnderSessionDir(target, root)) return { ok: false, reason: "forbidden" };
+    return { ok: true, content: await readFile(target, "utf8") };
+  } catch { return { ok: false, reason: "not_found" }; }
+}
+
+/** The working directory a Pi session file records in its header, if any. */
+export function recordedSessionCwd(content: string): string | undefined {
+  const header = sessionEntries(content).find(entry => (entry as { type?: unknown }).type === "session") as { cwd?: unknown } | undefined;
+  return typeof header?.cwd === "string" && header.cwd ? header.cwd : undefined;
+}
+
+/** Preserve raw JSON values and tolerate malformed or mid-append lines. */
+export function sessionEntries(content: string): unknown[] {
+  const entries: unknown[] = [];
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try { entries.push(JSON.parse(line.trim())); } catch { /* incomplete JSONL line */ }
+  }
+  return entries;
+}

package/src/session-search.ts

@@ -0,0 +1,175 @@
+// Read-only substring search over Pi's JSONL transcripts; no SDK runtime or index.
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readSessionFile } from "./session-files";
+
+export interface SearchMatch {
+  /** Plain text around the match; the consumer owns HTML escaping/highlighting. */
+  snippet: string;
+  /** Matched [start,end) UTF-16 offsets within the snippet. */
+  ranges: Array<[number, number]>;
+  role: string;
+}
+
+export interface SessionSearchResult {
+  sessionPath: string;
+  sessionTitle: string;
+  matches: SearchMatch[];
+}
+
+interface ParsedLine {
+  type?: string;
+  message?: { role?: string; content?: unknown; timestamp?: number };
+  name?: string;
+}
+
+/** Best-effort JSON.parse of one JSONL line; never throws. Mirrors
+ *  pi-coding-agent's own parseSessionEntryLine tolerance (skip malformed
+ *  lines rather than fail the whole file). */
+function parseLine(line: string): ParsedLine | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed) as ParsedLine;
+  } catch {
+    return null;
+  }
+}
+
+/** Flatten a message's content (string | content-block array) to plain text,
+ *  same shape pi-coding-agent's own extractTextContent handles. */
+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 "";
+}
+
+const MAX_MATCHES_PER_SESSION = 10;
+const MAX_TOTAL_MATCHES = 50;
+const SNIPPET_RADIUS = 60;
+
+/** Build one snippet window (±SNIPPET_RADIUS chars) around a single match
+ *  index in `text`, plus the match's own [start,end) offsets translated into
+ *  the snippet's local coordinate space. Pure — independently testable. */
+export function buildSnippet(text: string, matchStart: number, matchLen: number): { snippet: string; range: [number, number] } {
+  const start = Math.max(0, matchStart - SNIPPET_RADIUS);
+  const end = Math.min(text.length, matchStart + matchLen + SNIPPET_RADIUS);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < text.length ? "…" : "";
+  const snippet = prefix + text.slice(start, end) + suffix;
+  const localStart = matchStart - start + prefix.length;
+  return { snippet, range: [localStart, localStart + matchLen] };
+}
+
+/** Map folded code units back to original offsets. Lowercasing can expand
+ * characters (İ → i + combining dot), so slicing by folded offsets is wrong. */
+function foldWithIndex(text: string): { folded: string; index: number[] } {
+  let folded = "";
+  const index: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    const piece = text[i]!.toLowerCase();
+    for (let j = 0; j < piece.length; j++) index.push(i);
+    folded += piece;
+  }
+  return { folded, index };
+}
+
+/** Translate both ends of each folded substring match to original offsets. */
+function findOccurrences(textLower: string, qLower: string, index: readonly number[]): Array<[number, number]> {
+  if (!qLower) return [];
+  const offsets: Array<[number, number]> = [];
+  let i = 0;
+  for (;;) {
+    const idx = textLower.indexOf(qLower, i);
+    if (idx === -1) break;
+    const start = index[idx] ?? idx;
+    const lastFoldedIdx = idx + qLower.length - 1;
+    const end = index[lastFoldedIdx] ?? lastFoldedIdx;
+    offsets.push([start, end - start + 1]);
+    i = idx + qLower.length;
+  }
+  return offsets;
+}
+
+/** Scan one session file's raw JSONL content for `query` (case-insensitive
+ *  substring), returning up to MAX_MATCHES_PER_SESSION per session. Pure
+ *  given the file content string — split out from the disk read so it's
+ *  unit-testable without touching the filesystem. */
+export function searchSessionContent(content: string, query: string): SessionSearchResult | null {
+  const qLower = query.toLowerCase();
+  if (!qLower) return null;
+
+  const lines = content.split("\n");
+  const sessionPath = "";
+  let title = "";
+  let firstUserMessage = "";
+  const matches: SearchMatch[] = [];
+
+  for (const line of lines) {
+    const entry = parseLine(line);
+    if (!entry) continue;
+    if (entry.type === "session_info" && typeof entry.name === "string" && entry.name.trim()) {
+      title = entry.name.trim();
+      continue;
+    }
+    if (entry.type !== "message" || !entry.message) continue;
+    const role = entry.message.role;
+    if (role !== "user" && role !== "assistant") continue;
+    const text = contentText(entry.message.content);
+    if (!text) continue;
+    if (!firstUserMessage && role === "user") firstUserMessage = text;
+
+    if (matches.length >= MAX_MATCHES_PER_SESSION) continue;
+    const { folded: textLower, index } = foldWithIndex(text);
+    const offsets = findOccurrences(textLower, qLower, index);
+    for (const [off, len] of offsets) {
+      if (matches.length >= MAX_MATCHES_PER_SESSION) break;
+      const { snippet, range } = buildSnippet(text, off, len);
+      matches.push({ snippet, ranges: [range], role });
+    }
+  }
+
+  if (matches.length === 0) return null;
+  return {
+    sessionPath,
+    sessionTitle: (title || firstUserMessage || "New chat").slice(0, 80),
+    matches,
+  };
+}
+
+/** Flat directory scan in listing order, capped across sessions. Missing,
+ * unreadable, or concurrently removed files do not fail the remaining search. */
+export async function searchSessions(sessionDir: string, query: string): Promise<SessionSearchResult[]> {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  let files: string[];
+  try {
+    files = (await readdir(sessionDir)).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return []; // no session dir yet — never throw, just no results
+  }
+
+  const results: SessionSearchResult[] = [];
+  let total = 0;
+  for (const file of files) {
+    if (total >= MAX_TOTAL_MATCHES) break;
+    const path = join(sessionDir, file);
+    const fileContent = await readSessionFile(sessionDir, path);
+    if (!fileContent.ok) continue; // deleted, unreadable, or outside via a symlink
+    const result = searchSessionContent(fileContent.content, trimmed);
+    if (!result) continue;
+    result.sessionPath = path;
+    const remaining = MAX_TOTAL_MATCHES - total;
+    if (result.matches.length > remaining) result.matches = result.matches.slice(0, remaining);
+    total += result.matches.length;
+    results.push(result);
+  }
+  return results;
+}

package/src/surface.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { createWebTools } from "./web-tools";
+
+/** Optional read-only capabilities other modules contribute to a chat (`extensions.ts` builds it from the registry's
+ * `chat.tool` and `chat.guidance`); named for memory, the first contributor. */
+export interface MemorySurface {
+  /** The contributors attest that every advertised tool only reads state. */
+  readOnly: true;
+  toolNames: readonly string[];
+  customTools: readonly ToolDefinition[];
+  skillPaths: readonly string[];
+  hint: string;
+}
+
+/** Assemble definitions without discovering stores, materializing skills, or widening access. */
+export function buildPiAgentSurface(memory?: MemorySurface) {
+  if (memory && memory.readOnly !== true) throw new Error("Memory tools must be explicitly read-only");
+  return {
+    memoryEnabled: memory !== undefined,
+    memoryToolNames: [...(memory?.toolNames ?? [])],
+    readOnlyToolNames: [...(memory?.toolNames ?? [])],
+    customTools: [...createWebTools(), ...(memory?.customTools ?? [])],
+    skillPaths: [...(memory?.skillPaths ?? [])],
+    memoryHint: memory?.hint ?? "",
+  };
+}