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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Rossi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @mlx-bun/module-chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The default assistant as an application module (`AppModule<"modelHost" | "storage" | "registry">`, design:
+[Modular application](../../ARCHITECTURE.md#modular-application)): a Pi agent over the served model, one session per
+browser tab on a WebSocket, saved chats, durable tool approvals, the tools other modules contribute, and the browser
+panel. Nothing here imports an app or another module; the model, the storage root and the registry come from the host.
+The mlx-bun app installs it (`apps/mlx-bun/src/modules.ts`) and runs it in its persistent state.
+
+## What it serves
+
+Declared in `src/manifest.ts`, at the paths the browser and external tools already use (all `mount: "root"`):
+`GET /ws/chat` (the socket), `GET /api/sessions/search`, `GET /api/sessions/export` (read-only over the session
+directory), and `GET`/`DELETE /api/settings/tool-approvals`. The host serves the socket (`createModuleSockets` in
+`@mlx-bun/app-services`) and stops the module, which closes every chat, before it drains. A host that serves no
+sockets refuses the module.
+
+| Storage entry | Path under `MLX_BUN_HOME` | Holds |
+| --- | --- | --- |
+| `sessions` | `sessions/` | Saved chats, one Pi JSONL file each; the memory pipeline reads them too |
+| `agent` | `pi-sessions/` | The Pi agent's own directory |
+| `approvals` | `tool-approvals.json` | Tools the user chose to always allow (mode 0600; absent, corrupt or unknown-version data means ask again) |
+
+Entries resolve when a chat or route first needs them, so a host that never chats writes nothing. An embedder's explicit
+path for an entry wins (`createStorage`'s `explicit` map); `createChatModule({ readOnly, cwd })` carries what the host
+decides beyond its services: a read-only server (no file-changing tool, every gated call denied) and Pi's working
+directory.
+
+## The model
+
+Every model access goes through `modelHost`. A connection describes the current model from its wire when it starts
+(`src/describe.ts`: `GET /v1/models` for capabilities and sampling defaults, `/stats` for the enforced context), so
+the same code serves a model in this process and one behind an isolation worker, and a switch is followed because each
+request asks the host for the *current* model. The Pi SDK takes a base URL, not a transport, so the module runs a private
+loopback (`src/model-bridge.ts`: `127.0.0.1`, an ephemeral port, started with the first chat, a per-run bearer token, only
+`POST /v1/chat/completions`) that leases the current model's `generate` for each request and releases the lease when the
+response body ends or is cancelled. Pi's own model id, `local`, is the host's to route.
+
+## What other modules contribute
+
+`src/extensions.ts` reads the registry when each session is built: `chat.tool` contributions (a name, schema, `run`, and
+the attestation `readOnly: true`; a tool that does not attest is never offered; an optional `available()` decides per
+session) become Pi tools that run without an approval prompt, and `chat.guidance` contributions add a prompt hint and a
+skill directory. Memory is the first contributor (`@mlx-bun/module-memory/chat`), offered only while the vault exists.
+
+## Browser panel
+
+`src/panel/` defines `<mlx-chat-panel>`, the module's `panel` (`workspace: true`): the shell gives it the whole page, leads
+the tabs with it, keeps it attached while another page shows (a turn in flight survives a visit elsewhere) and calls its
+`enter()` and `leave()`. It renders into the light DOM with its own markup (`template.ts`) and stylesheet (`style.ts`),
+takes the host page's design tokens and base element styles, and imports only its own files and `protocol.ts`, the data
+protocol it shares with the backend. It carries its own markdown renderer, composer (attachments, sampling and system-prompt
+popovers, `#` mentions, chat-with-files retrieval), recent-chats sidebar, adapter routing table, the hold-to-talk mic
+(`voice.ts`, which calls transcription's `/v1/audio/sessions` routes over HTTP), and the app-aware assistant.
+
+What the panel needs from its host page, beyond its connection, is the `host` property (`panel/host.ts`, all optional): a
+`mounted` callback (memory attaches its sidebar entry and consent card), a `toolCard` hook (memory's provenance chips),
+and the agent-tools `settings` section of the host's settings dialog. Its methods for the host are `newChat`,
+`copyLastResponse`, `setCodingTools`, `refreshAdapters`, `focusComposer`, `toggleThinking`, `recentChats`, `openSession`,
+`exportActiveChat`, the mobile drawer (`toggleDrawer`, `closeDrawer`, `drawerOpen`) and the popovers for the host's Escape
+sweep (`popoverOpen`, `closePopover`). The host page also supplies a `#toasts` container and, for the assistant, its own
+routes, overlays and spotlight targets (`panel/ui-catalog.ts` names them: the chat's knowledge of this app, which should
+move to contributions once the shell lists them).
+
+The assistant follows open shadow roots when it captures visible controls or resolves spotlight targets, so the job
+modules' encapsulated forms remain available in its page context. Its wizard-step observer rebinds on navigation as
+the shell mounts those panels, and skips controls inside hidden pages or assistant chrome. Routed spotlight requests
+wait for navigation and layout before resolving a control, including a panel's first visit or return after detachment.
+
+## Tests
+
+Model-free. [module](tests/module.test.ts) loads the module in a host with a scripted model host and drives a real chat on a
+real listener with the real Pi SDK: the wire-described `ready`, a prompt, a contributed read-only tool, the answer, and the
+saved chat reopened with the same transcript; the socket's close codes; the read-only policy.
+[model-bridge](tests/model-bridge.test.ts), [describe](tests/describe.test.ts) and [extensions](tests/extensions.test.ts)
+cover the loopback (authorization, leases), the description and the registry surface. The moved suites keep their
+expectations: [chat-backend](tests/chat-backend.test.ts) (socket lifetime, Pi disposal, the approval gate, facts read at
+connect), [chat-policy](tests/chat-policy.test.ts), [chat-runtime](tests/chat-runtime.test.ts) (the real SDK against fixed
+loopback SSE, transcripts in app-supplied paths), [session-search](tests/session-search.test.ts),
+[tool-approvals](tests/tool-approvals.test.ts), [web-tools](tests/web-tools.test.ts), [routes](tests/routes.test.ts), and
+[panel](tests/panel.test.ts) (happy-dom: markdown streaming parity, the turn lifecycle through the real element, composer,
+mentions, adapters, retrieval, the assistant). The app's boot test
+([boot](../../apps/mlx-bun/tests/web/boot.test.ts)) runs the built bundle against `app.html` and covers the panel mounted
+by the shell, its host side and its drawer. The opt-in
+[real-weights test](../../apps/mlx-bun/tests/engine/chat-native.test.ts) (`MLX_BUN_APP_TEST_MODEL=<snapshot directory>`)
+serves a model through the app and runs a greedy chat with a read-only tool call and a reopened session; with
+`MLX_BUN_CHAT_TRANSCRIPT=<file>` it writes the transcript's structure so two builds can be compared.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@mlx-bun/module-chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Chat module for mlx-bun applications: the default assistant, a Pi agent over the served model on a WebSocket, saved chats, tool approvals and the browser panel",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./panel": "./src/panel/index.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "bun ../../scripts/typecheck.ts --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@mlx-bun/app-core": "1.0.0",
+    "@mlx-bun/inference": "1.0.0",
+    "@earendil-works/pi-ai": "0.80.3",
+    "@earendil-works/pi-coding-agent": "0.80.3",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "@mlx-bun/app-host": "1.0.0",
+    "@mlx-bun/app-services": "1.0.0",
+    "happy-dom": "20.10.6"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ]
+}

package/src/app-tools.ts

@@ -0,0 +1,101 @@
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { APP_ROUTE_IDS, type AppRouteId, type AppUiContext, type ServerMessage } from "./protocol";
+import { resolveAppRoute } from "./policy";
+
+function appAwareTextResult(text: string, details: unknown = {}): { content: [{ type: "text"; text: string }]; details: unknown } {
+  return { content: [{ type: "text", text }], details };
+}
+
+/** Build the three app-aware tools for one connection. `getContext` reads
+ *  the connection's currentAppContext (last `context` ClientMessage, or
+ *  null before the first one arrives); `notify` sends a ServerMessage
+ *  (ui_navigate/ui_spotlight) to that same browser tab. Pure enough to
+ *  unit test the tool -> frame mapping via a fake notify collecting sent
+ *  frames (tests/chat-policy.test.ts). */
+export function createAppAwareTools(
+  getContext: () => AppUiContext | null,
+  notify: (msg: ServerMessage) => void,
+): ToolDefinition[] {
+  const getCurrentAppContext = defineTool({
+    name: "get_current_app_context",
+    label: "Get Current App Context",
+    description:
+      "Returns the current web-app UI context: route, view, wizard step (if on one), and a uiSnapshot of visible interactive elements (ref, label, selector, spotlightId). Call this before spotlight_ui to pick the correct ref, label, or target — do not guess selectors blind.",
+    parameters: Type.Object({}),
+    execute: async () => {
+      const ctx = getContext();
+      if (!ctx) {
+        return appAwareTextResult(
+          "No app context received yet — the browser hasn't reported its current view. Ask the user what page they're on, or proceed without UI tools.",
+        );
+      }
+      return appAwareTextResult(JSON.stringify(ctx, null, 2), { context: ctx });
+    },
+  });
+
+  const navigateApp = defineTool({
+    name: "navigate_app",
+    label: "Navigate App",
+    description:
+      "Navigate the user's browser to a different page in the app. Use when they ask to be taken somewhere (e.g. \"take me to Quantize\", \"open the fine-tune wizard\"). Pass route or page as one of: chat, quantize, finetune, dataset, status (or \"#/quantize\"-style). Reversible and never needs approval. Does not highlight a specific control — use spotlight_ui separately for that.",
+    parameters: Type.Object({
+      route: Type.Optional(Type.String({ description: "chat | quantize | finetune | dataset | status (or #/quantize)" })),
+      page: Type.Optional(Type.String({ description: "Same as route — alternate param name" })),
+    }),
+    execute: async (_id, params) => {
+      const resolved = resolveAppRoute(params.route ?? params.page ?? "");
+      if (!resolved) {
+        return {
+          ...appAwareTextResult(`Unknown route. Valid routes: ${APP_ROUTE_IDS.join(", ")}.`),
+          isError: true,
+        };
+      }
+      notify({ type: "ui_navigate", route: resolved });
+      return appAwareTextResult(
+        `Navigating the user to ${resolved}. They can see the page now — use spotlight_ui if you need to point at a specific control.`,
+        { route: resolved },
+      );
+    },
+  });
+
+  const spotlightUi = defineTool({
+    name: "spotlight_ui",
+    label: "Spotlight UI",
+    description:
+      "Highlight a visible UI control with a brief, auto-dismissing spotlight (never blocks the user — they can keep working through it). Call get_current_app_context first and prefer ref from its uiSnapshot.elements; or pass label (visible text, e.g. \"Source model\"); or selector; or target (a curated catalog id, e.g. hub-browse, quantize-source). Optional route navigates there first. Optional message is a short hint shown in the popover.",
+    parameters: Type.Object({
+      ref: Type.Optional(Type.String({ description: "Element ref from uiSnapshot.elements[].ref (preferred)" })),
+      label: Type.Optional(Type.String({ description: "Visible label/text to match, e.g. Source model, New chat" })),
+      selector: Type.Optional(Type.String({ description: "CSS selector, when ref/label are unknown" })),
+      target: Type.Optional(Type.String({ description: "Curated catalog id, e.g. hub-browse, quantize-source, sampling-pill" })),
+      route: Type.Optional(Type.String({ description: "Navigate to this route first (chat, quantize, finetune, dataset, status)" })),
+      message: Type.Optional(Type.String({ description: "Short hint shown in the spotlight popover" })),
+    }),
+    execute: async (_id, params) => {
+      const hasLocator = !!params.ref?.trim() || !!params.label?.trim() || !!params.selector?.trim() || !!params.target?.trim();
+      if (!hasLocator) {
+        return { ...appAwareTextResult("Provide at least one of: ref (from uiSnapshot), label, selector, or target."), isError: true };
+      }
+      let route: AppRouteId | undefined;
+      if (params.route) {
+        route = resolveAppRoute(params.route) ?? undefined;
+        if (!route) {
+          return { ...appAwareTextResult(`Unknown route "${params.route}". Valid routes: ${APP_ROUTE_IDS.join(", ")}.`), isError: true };
+        }
+      }
+      notify({
+        type: "ui_spotlight",
+        ref: params.ref, label: params.label, selector: params.selector, target: params.target,
+        route, message: params.message,
+      });
+      const desc = params.ref ?? params.label ?? params.selector ?? params.target ?? "element";
+      return appAwareTextResult(
+        `Highlighting ${desc}${params.message ? `: ${params.message}` : ""}. The spotlight fades on its own in a few seconds.`,
+        { ...params, route },
+      );
+    },
+  });
+
+  return [getCurrentAppContext, navigateApp, spotlightUi];
+}

package/src/backend.ts

@@ -0,0 +1,108 @@
+import type { SocketHandler, SocketPeer } from "@mlx-bun/app-core";
+import type { ClientMessage, ServerMessage } from "./protocol";
+
+/** One connection owns one backend. Disposal cancels active turns and pending approvals.
+ * It may race start(); implementations must release resources acquired after disposal. */
+export interface ChatBackend {
+  start(): Promise<void>;
+  handle(message: ClientMessage): Promise<void>;
+  dispose(): void | Promise<void>;
+}
+export type SendFrame = (message: ServerMessage) => void;
+export type ChatBackendFactory = (send: SendFrame) => ChatBackend;
+
+interface Connection {
+  backend: ChatBackend;
+  closed: boolean;
+  disposal?: Promise<void>;
+}
+
+/** Transport owns socket lifetime; the backend owns agent/session lifetime.
+ * Messages remain concurrent so abort/approval frames can interrupt an active prompt. */
+export function createChatSocket(factory: ChatBackendFactory): SocketHandler & { dispose(): Promise<void>; readonly connections: number } {
+  const connections = new Map<SocketPeer, Connection>();
+  const disposing = new Set<Promise<void>>();
+  const starting = new Set<Promise<void>>();
+  const handling = new Set<Promise<void>>();
+  const cleanupErrors: unknown[] = [];
+  let closing: Promise<void> | undefined;
+  let stopped = false;
+  const send = (socket: SocketPeer, message: ServerMessage) => {
+    try { socket.send(JSON.stringify(message)); } catch { /* disconnected */ }
+  };
+  const error = (socket: SocketPeer, cause: unknown) => send(socket, {
+    type: "error", message: cause instanceof Error ? cause.message : String(cause),
+  });
+  const release = (connection: Connection): Promise<void> => {
+    if (connection.disposal) return connection.disposal;
+    connection.closed = true;
+    // Socket callbacks cannot return disposal errors to an owner. Retain them
+    // for handler shutdown while observing each rejection immediately.
+    const done = connection.disposal = Promise.resolve().then(() => connection.backend.dispose())
+      .catch(cause => { cleanupErrors.push(cause); });
+    disposing.add(done);
+    void done.finally(() => disposing.delete(done));
+    return done;
+  };
+  return {
+    /** Chats open now. */
+    get connections() { return connections.size; },
+    async open(socket) {
+      if (stopped) { socket.close(); return; }
+      let connection: Connection | undefined;
+      try {
+        const backend = factory(message => {
+          if (!stopped && connection && !connection.closed) send(socket, message);
+        });
+        connection = { backend, closed: false };
+        connections.set(socket, connection);
+        const start = backend.start();
+        starting.add(start);
+        try { await start; } finally { starting.delete(start); }
+      } catch (cause) {
+        if (!stopped && !connection?.closed) error(socket, cause);
+        connections.delete(socket);
+        if (connection) await release(connection);
+        // Failed startup must not leave an untracked transport blocking listener drain.
+        socket.close(1011, "Chat startup failed");
+      }
+    },
+    async message(socket, raw) {
+      const connection = connections.get(socket);
+      if (!connection || connection.closed) { if (!stopped) error(socket, "no active session"); return; }
+      let message: ClientMessage;
+      try {
+        const parsed: unknown = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || typeof (parsed as { type?: unknown }).type !== "string") throw new Error();
+        message = parsed as ClientMessage;
+      } catch { error(socket, "invalid JSON message"); return; }
+      try {
+        const operation = connection.backend.handle(message);
+        handling.add(operation);
+        try { await operation; } finally { handling.delete(operation); }
+      } catch (cause) { if (!connection.closed) error(socket, cause); }
+    },
+    close(socket) {
+      const connection = connections.get(socket);
+      connections.delete(socket);
+      if (connection) void release(connection);
+    },
+    dispose() {
+      return closing ??= (async () => {
+        stopped = true;
+        for (const [socket, connection] of [...connections]) {
+          void release(connection);
+          try { socket.close(1001, "Server shutting down"); } catch (error) { cleanupErrors.push(error); }
+        }
+        connections.clear();
+        await Promise.all([...disposing]);
+        // Cancel first, then join work that can acquire/release resources after
+        // an await. Messages remain concurrent during the connection lifetime.
+        await Promise.allSettled([...starting, ...handling]);
+        await Promise.all([...disposing]);
+        if (cleanupErrors.length === 1) throw cleanupErrors[0];
+        if (cleanupErrors.length) throw new AggregateError(cleanupErrors, "chat cleanup failed");
+      })();
+    },
+  };
+}

package/src/describe.ts

@@ -0,0 +1,47 @@
+// What the served model is, as the browser needs it (`ready` frame). Read over the model host's
+// own wire when each chat connects: the wire describes whichever model is current, in this process
+// or behind an isolation worker, so chat never asks a model family anything.
+import type { ModelHost } from "@mlx-bun/app-core";
+
+export interface ServedModel {
+  readonly modelId: string;
+  /** The context the server enforces; undefined when it reports none. */
+  readonly contextWindow: number | undefined;
+  readonly vision: boolean;
+  readonly audio: boolean;
+  readonly thinking: boolean;
+  /** A speech-to-text checkpoint is available: the composer offers hold-to-talk. */
+  readonly transcription: boolean;
+  readonly genDefaults: { readonly temperature: number | null; readonly topP: number | null; readonly topK: number | null };
+}
+
+const number = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+/** Reads the current model's discovery row and its enforced context. Rejects when no model is served or the wire answers with an error. */
+export async function describeModel(models: Pick<ModelHost, "acquire" | "defaultFor">, signal?: AbortSignal): Promise<ServedModel> {
+  const id = await models.defaultFor("generate");
+  if (id === undefined) throw new Error("no model is served");
+  const lease = await models.acquire(id, { need: ["generate"], ...(signal ? { signal } : {}) });
+  try {
+    const generate = lease.operations.generate;
+    if (!generate) throw new Error(`model ${id} cannot generate`);
+    const read = async (path: string) => {
+      const response = await generate(new Request(`http://model.local${path}`, signal ? { signal } : {}));
+      if (!response.ok) { await response.body?.cancel().catch(() => {}); throw new Error(`the model host answered ${response.status} on ${path}`); }
+      return await response.json() as Record<string, unknown>;
+    };
+    const [models_, stats] = await Promise.all([read("/v1/models"), read("/stats")]);
+    const rows = (Array.isArray(models_.data) ? models_.data : []) as Record<string, unknown>[];
+    const row = rows.find(item => item.id === id) ?? rows.find(item => item.current === true) ?? rows.find(item => item.transcription !== true) ?? {};
+    const defaults = (row.gen_defaults ?? {}) as Record<string, unknown>;
+    const capabilities = (row.capabilities ?? {}) as Record<string, unknown>;
+    const admission = (stats.admission ?? {}) as Record<string, unknown>;
+    return {
+      modelId: id,
+      contextWindow: number(admission.enforced_context_tokens) ?? number(row.context_window),
+      vision: row.vision === true, audio: row.audio === true, thinking: row.reasoning === true,
+      transcription: capabilities.transcription === true,
+      genDefaults: { temperature: number(defaults.temperature) ?? null, topP: number(defaults.top_p) ?? null, topK: number(defaults.top_k) ?? null },
+    };
+  } finally { lease.release(); }
+}

package/src/events.ts

@@ -0,0 +1,75 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { ServerMessage } from "./protocol";
+
+/**
+ * Translate one pi AgentSessionEvent into zero or more WS frames.
+ *
+ * Pure and side-effect-free so it can be unit-tested without a live
+ * session. The approval gate is handled separately (in the tool_call
+ * extension handler), so the tool_execution_start event here simply
+ * renders the tool card; it does not itself request approval.
+ *
+ * Returns [] for events that have no browser-facing representation.
+ */
+export function mapEventToFrames(event: AgentSessionEvent): ServerMessage[] {
+  switch (event.type) {
+    case "turn_start":
+      return [{ type: "turn_start" }];
+    case "turn_end": {
+      // A turn can complete with stopReason "error" (e.g. the model request
+      // 400'd) WITHOUT any error being thrown up to the WS message handler, so
+      // it would otherwise vanish — the browser just sees an empty turn ("no
+      // messages"). Surface it as an error frame so the UI can show it.
+      const msg = (event as { message?: { stopReason?: string; errorMessage?: string; responseId?: string } }).message;
+      if (msg?.stopReason === "error") {
+        return [
+          { type: "error", message: msg.errorMessage || "the model request failed" },
+          { type: "turn_end" },
+        ];
+      }
+      return [{ type: "turn_end" }];
+    }
+    case "message_update": {
+      const ame = event.assistantMessageEvent;
+      if (ame.type === "text_delta") return [{ type: "text_delta", delta: ame.delta }];
+      if (ame.type === "thinking_delta") return [{ type: "thinking_delta", delta: ame.delta }];
+      return [];
+    }
+    case "tool_execution_start":
+      return [
+        {
+          type: "tool_start",
+          callId: event.toolCallId,
+          tool: event.toolName,
+          args: event.args,
+        },
+      ];
+    case "tool_execution_update":
+      return [
+        {
+          type: "tool_update",
+          callId: event.toolCallId,
+          chunk: event.partialResult,
+        },
+      ];
+    case "tool_execution_end":
+      return [
+        {
+          type: "tool_end",
+          callId: event.toolCallId,
+          ok: !event.isError,
+          result: event.result,
+        },
+      ];
+    case "queue_update":
+      return [
+        {
+          type: "queue_update",
+          steering: event.steering,
+          followUp: event.followUp,
+        },
+      ];
+    default:
+      return [];
+  }
+}

package/src/extensions.ts

@@ -0,0 +1,44 @@
+// What other modules contribute to a chat session through the registry: their tools (`chat.tool`)
+// and the guidance for them (`chat.guidance`: a prompt hint and a skill). Read when each session is
+// built, so a contributor that activates later, or whose tools become available later (a memory
+// vault created after startup), is seen by the next chat. The chat never names a contributor.
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { ChatToolContribution, Registry } from "@mlx-bun/app-core";
+import type { MemorySurface } from "./surface";
+
+const available = async (contribution: { available?(): boolean | Promise<boolean> }): Promise<boolean> => {
+  try { return await contribution.available?.() ?? true; } catch { return false; }
+};
+
+/** A contributed tool as a Pi tool definition: the same name, schema and text result, run with the turn's abort signal. */
+export function piTool(contribution: ChatToolContribution) {
+  return defineTool({
+    name: contribution.name,
+    label: contribution.label ?? contribution.name,
+    description: contribution.description,
+    parameters: contribution.parameters as unknown as TSchema,
+    execute: async (_id, params, signal) => ({
+      content: [{ type: "text" as const, text: await contribution.run(params as Record<string, unknown>, signal ?? new AbortController().signal) }],
+      details: {},
+    }),
+  });
+}
+
+/** The registry's tools and guidance as the surface a session is built with; undefined when nothing is available. Only tools that attest `readOnly` are offered. */
+export function createExtensionSurface(registry: Pick<Registry, "list">): () => Promise<MemorySurface | undefined> {
+  return async () => {
+    const tools = (await Promise.all(registry.list("chat.tool").map(async entry =>
+      entry.contribution.readOnly === true && await available(entry.contribution) ? [entry.contribution] : []))).flat();
+    const guidance = (await Promise.all(registry.list("chat.guidance").map(async entry => await available(entry.contribution) ? [entry.contribution] : []))).flat();
+    if (!tools.length) return undefined;
+    const skillPaths: string[] = [], hints: string[] = [];
+    for (const item of guidance) {
+      const path = await item.skillPath?.();
+      if (path && !skillPaths.includes(path)) skillPaths.push(path);
+      const hint = await item.hint?.();
+      if (hint) hints.push(hint);
+    }
+    return { readOnly: true, toolNames: tools.map(tool => tool.name), customTools: tools.map(piTool), skillPaths, hint: hints.join("") };
+  };
+}