mlx-bun 0.4.0 → 1.0.0

package/src/{serve → server}/token-streams.ts

@@ -2,13 +2,10 @@
 // StreamDecoder (mlx-lm byte-parity incremental detokenizer), ToolAwareStream
 // (tool-call / reasoning-channel routing), StopMatcher (decoded-text stop
 // sequences), ThinkingTagSplitter (<think> markup → reasoning deltas).
-// Extracted from src/server.ts (repo-taming Phase 4).
-import type { ToolDefinition } from "../chat-template";
-import type { LoadedTokenizer } from "../tokenizer";
-import {
-  CHANNEL_END, CHANNEL_START, parseGeneratedToolCalls, parseToolCalls,
-  TOOL_CALL_END, TOOL_CALL_START,
-} from "../tool-call";
+import type { ToolDefinition } from "@mlx-bun/inference/input";
+import type { LoadedTokenizer } from "@mlx-bun/inference/input";
+import type { SentinelTokens } from "@mlx-bun/inference/input";
+import { parseGeneratedToolCalls, parseToolCalls } from "@mlx-bun/inference/input/tool-call";
 
 export interface OpenAIToolCall {
   id: string;
@@ -16,28 +13,26 @@ export interface OpenAIToolCall {
   function: { name: string; arguments: string };
 }
 
-export type ToolStreamMode = "gemma-sentinel" | "plain" | "buffered-text";
+export type ToolStreamMode = "sentinel-tokens" | "plain" | "buffered-text";
 
-/** Pick the stream router for a model family. The token-id sentinel router is
- *  Gemma-4-ONLY: ids 48/49 (<|tool_call>/<tool_call|>) and 100/101
- *  (<|channel>/<channel|>) are special tokens of that tokenizer family
- *  (src/tool-call.ts). On every other tokenizer — MiniCPM5, Qwen3/3.5, and
- *  the Tier-0 generics (llama, qwen2, phi3, …) — those ids are ordinary
- *  low-id vocab, so the sentinel router would silently swallow output into a
- *  phantom tool/reasoning segment. Everyone else parses tool calls from
- *  decoded text (buffered-text; parseGeneratedToolCalls covers the
- *  OpenAI-JSON <tool_call>, Qwen <function=…>, and MiniCPM5 <function name=…>
- *  shapes) when tools are present, and streams plain otherwise. Models whose
- *  markup isn't covered fail soft: the markup stays in content. */
-export function selectToolStreamMode(modelType: string, hasTools: boolean): ToolStreamMode {
-  if (modelType.startsWith("gemma4")) return "gemma-sentinel";
+/** Pick the stream router. A model whose profile declares sentinel tokens
+ *  (special tokens delimiting tool calls and the reasoning channel, resolved
+ *  against its tokenizer) is routed at the token level: on any other tokenizer
+ *  the same ids would be ordinary vocab, so a router must never guess them.
+ *  Everyone else parses tool calls from decoded text (buffered-text;
+ *  parseGeneratedToolCalls covers the OpenAI-JSON <tool_call>, Qwen
+ *  <function=…>, and MiniCPM5 <function name=…> shapes) when tools are present,
+ *  and streams plain otherwise. Models whose markup isn't covered fail soft:
+ *  the markup stays in content. */
+export function selectToolStreamMode(sentinels: SentinelTokens | null | undefined, hasTools: boolean): ToolStreamMode {
+  if (sentinels) return "sentinel-tokens";
   return hasTools ? "buffered-text" : "plain";
 }
 
-/** Routes generated tokens. Gemma uses family-specific sentinel token ids;
- *  MiniCPM5 and other text-template models use decoded-text parsing so
- *  ordinary tokenizer ids like "<" are never swallowed globally. Exported for
- *  unit tests (gemma-channel reasoning split). */
+/** Routes generated tokens. Models declaring sentinel tokens are routed by id;
+ *  text-template models use decoded-text parsing so ordinary tokenizer ids
+ *  like "<" are never swallowed globally. Exported for unit tests
+ *  (reasoning-channel split). */
 export class ToolAwareStream {
   readonly #decoder: StreamDecoder;
   #inTool = false;
@@ -51,9 +46,9 @@ export class ToolAwareStream {
   #textToolParseFailed = false;
   readonly toolSegments: number[][] = [];
 
-  /** Gemma reasoning-channel state (gemma-sentinel mode). The model wraps
-   *  chain-of-thought as `<|channel>thought\n…<channel|>` using special tokens
-   *  100/101 that the content decoder strips, so reasoning is captured here at
+  /** Reasoning-channel state (sentinel-tokens mode). The model wraps
+   *  chain-of-thought as `<|channel>thought\n…<channel|>` using the channel
+   *  sentinel tokens, which the content decoder strips, so reasoning is captured here at
    *  the token level. A SEPARATE decoder keeps the reasoning byte-stream's
    *  incremental state independent of content's. The `thought` channel-name
    *  word is stripped before the reasoning text (mlx-lm's think-start marker
@@ -74,11 +69,14 @@ export class ToolAwareStream {
     readonly mode: ToolStreamMode,
     readonly tools: ToolDefinition[] | null,
     /** Fired when parseGeneratedToolCalls rejects the emitted markup. The
-     *  fill table (src/fill/) subscribes: a request whose tool call the
+     *  fill table (packages/inference/src/generation/fill/) subscribes: a request whose tool call the
      *  parser refuses is a request whose template rendering disagreed with
      *  what the model emits, so its strict rows are disarmed. */
     private readonly onParseFailure?: () => void,
+    /** The resolved sentinel ids; required in sentinel-tokens mode. */
+    private readonly sentinels?: SentinelTokens | null,
   ) {
+    if (mode === "sentinel-tokens" && !sentinels) throw new Error("sentinel-tokens routing needs the resolved sentinel ids");
     this.#decoder = new StreamDecoder(tokenizer, mode !== "buffered-text");
     this.#channelDecoder = new StreamDecoder(tokenizer, true);
   }
@@ -101,7 +99,7 @@ export class ToolAwareStream {
     return rest;
   }
 
-  /** Drain reasoning captured since the last call (gemma-channel thinking). */
+  /** Drain reasoning captured since the last call (channel-token thinking). */
   takeReasoning(): string {
     const r = this.#reasoning;
     this.#reasoning = "";
@@ -139,7 +137,7 @@ export class ToolAwareStream {
 
   /** Returns the content text delta for this token ("" while capturing). */
   push(token: number): string {
-    if (this.mode !== "gemma-sentinel") {
+    if (this.mode !== "sentinel-tokens") {
       this.#text += this.#decoder.push(token);
       if (this.mode === "plain") {
         const out = this.#text.slice(this.#sent);
@@ -149,7 +147,7 @@ export class ToolAwareStream {
       return this.#textDelta();
     }
     if (this.#inTool) {
-      if (token === TOOL_CALL_END) {
+      if (token === this.sentinels!.toolCallEnd) {
         this.#inTool = false;
         this.toolSegments.push(this.#toolTokens);
         this.#toolTokens = [];
@@ -160,11 +158,11 @@ export class ToolAwareStream {
     }
     // Reasoning channel: tokens between <|channel> and <channel|> are thought,
     // captured to #reasoning (drained via takeReasoning), never content. An
-    // empty block (<|channel>thought\n<channel|>, emitted by larger Gemmas even
+    // empty block (<|channel>thought\n<channel|>, emitted by some checkpoints even
     // with thinking off) yields only the "\n" as reasoning (mlx-lm parity) and
     // leaks nothing into content.
     if (this.#inChannel) {
-      if (token === CHANNEL_END) {
+      if (token === this.sentinels!.channelEnd) {
         this.#inChannel = false;
         this.#reasoning += this.#feedChannel(this.#channelDecoder.flush());
       } else {
@@ -172,13 +170,13 @@ export class ToolAwareStream {
       }
       return "";
     }
-    if (token === CHANNEL_START) {
+    if (token === this.sentinels!.channelStart) {
       this.#inChannel = true;
       this.#channelNameDone = false;
       this.#channelNamePending = "";
       return "";
     }
-    if (token === TOOL_CALL_START) {
+    if (token === this.sentinels!.toolCallStart) {
       this.#inTool = true;
       return "";
     }
@@ -186,7 +184,7 @@ export class ToolAwareStream {
   }
 
   flush(): string {
-    if (this.mode !== "gemma-sentinel") {
+    if (this.mode !== "sentinel-tokens") {
       this.#text += this.#decoder.flush();
       if (this.mode === "buffered-text") {
         const calls = this.toolCalls();
@@ -221,7 +219,7 @@ export class ToolAwareStream {
   }
 
   toolCalls(): OpenAIToolCall[] {
-    if (this.mode !== "gemma-sentinel") {
+    if (this.mode !== "sentinel-tokens") {
       if (this.#textToolCalls) return this.#textToolCalls;
       try {
         this.#textToolCalls = parseGeneratedToolCalls(this.#text, this.tools ?? []).map((c) => ({

package/src/server/worker-routes.ts

@@ -0,0 +1,311 @@
+// The private admin surface an isolation worker serves on its Unix socket,
+// ahead of the model routes: readiness for the parent, a connection-owned
+// execution lease for managed GPU jobs, a drain that stops admission and
+// waits for the work in flight, the model worker's memory task model for the
+// parent's synthesis, the worker's event stream (`/admin/events`), and its model's
+// adapter operation (`/admin/adapters`). It is
+// never mounted on a TCP listener, where every one of these paths is unknown
+// (404), as they are on a worker that lacks the capability behind one.
+import type { AdapterOperation, EventBus } from "@mlx-bun/app-core";
+import type { DisposableResource } from "@mlx-bun/inference/contracts/portable";
+import { memoryHealth, memoryLine, type WorkerMemory } from "../jobs/worker-memory";
+import type { TaskCompletionClient as MemoryCompletionClient, TaskCompletionRequest as MemoryCompletionRequest } from "@mlx-bun/app-core";
+
+export interface WorkerRouteGroup { handle(request: Request): Promise<Response | null> }
+
+export type WorkerState = "ready" | "draining";
+
+export interface WorkerRoutesOptions {
+  /** The `/v1/models` id the parent addresses this worker by. */
+  modelId: string;
+  /** The host's exclusive execution lease: it resolves once generation in
+   * flight has finished, so drain waits on it and jobs hold it. A host without
+   * one (the transcription-only app) has no `/admin/lease` route (404) and
+   * drains on admitted requests alone. */
+  acquireExecutionLease?(signal: AbortSignal): Promise<DisposableResource>;
+  /** Drain waits at most this long for in-flight work; a request body may
+   * lower it (`timeout_ms`). Default 120 s, the app's shutdown deadline. */
+  drainTimeoutMs?: number;
+  pid?: number;
+  /** The model form's memory task model (Gemma-4 e4b with its chunk adapter,
+   * loaded by the first call): `POST /admin/memory/complete` runs one memory
+   * `complete` or `completeBatch` on it for the isolated parent's synthesis,
+   * under the execution lease; the call that loads it loads exactly the
+   * snapshot the call carries. The composition owns it and closes it after
+   * `close()` has joined the calls. Without it (or without a lease) there is
+   * no such route (404). */
+  memoryTaskModel?: { clientFor(signal: AbortSignal, snapshot: string): MemoryCompletionClient };
+  /** The worker's own events (its engine's request timings and samples, its model's memory): `GET /admin/events` streams them
+   * as JSON lines for the parent, which publishes them on its bus. A worker with only `memory` streams readings alone. */
+  events?: Pick<EventBus, "subscribe">;
+  /** The MLX memory this process holds now (jobs/worker-memory.ts). `/health` reports it, and the event stream carries it as a
+   * `worker.memory` line at connect, when it changed at each interval, and after every `request.finished`. */
+  memory?: () => WorkerMemory | undefined;
+  /** Milliseconds between the stream's memory readings. Default 1000. */
+  memoryIntervalMs?: number;
+  /** The worker's model's `adapters` operation (list, mount, unmount, merge under the engine's lock), which the parent's models module
+   * reaches through `POST /admin/adapters`, admitted and drained like model work. Without it there is no such route (404). */
+  adapters?: AdapterOperation;
+}
+
+/** The body of one private adapter call: `op` names the operation and the rest is its arguments. */
+export type WorkerAdapterCall =
+  | { op: "list" }
+  | { op: "mount"; id: string; path: string }
+  | { op: "unmount"; id: string }
+  | { op: "merge"; adapters: [string, string]; output: string; scales?: number[] };
+
+function parseAdapterCall(value: unknown): WorkerAdapterCall {
+  const body = value as Record<string, unknown> | null;
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new Error("expected a JSON object");
+  const text = (field: unknown, name: string) => { if (typeof field !== "string" || !field) throw new Error(`${name} expects a non-empty string`); return field; };
+  switch (body.op) {
+    case "list": return { op: "list" };
+    case "mount": return { op: "mount", id: text(body.id, "id"), path: text(body.path, "path") };
+    case "unmount": return { op: "unmount", id: text(body.id, "id") };
+    case "merge": {
+      const { adapters, scales } = body;
+      if (!Array.isArray(adapters) || adapters.length !== 2) throw new Error("adapters expects two directories");
+      if (scales !== undefined && (!Array.isArray(scales) || !scales.every(item => typeof item === "number" && Number.isFinite(item)))) throw new Error("scales expects finite numbers");
+      return { op: "merge", adapters: [text(adapters[0], "adapters[0]"), text(adapters[1], "adapters[1]")], output: text(body.output, "output"), ...(scales ? { scales: scales as number[] } : {}) };
+    }
+    default: throw new Error('op expects "list", "mount", "unmount" or "merge"');
+  }
+}
+
+/** The private memory call's body: one `complete` (a single row) or one
+ * `completeBatch`, and `snapshot`, the task model directory the parent
+ * selected and retains on this worker, the one a loading call loads. */
+export interface WorkerMemoryCall { call: "complete" | "completeBatch"; snapshot: string; requests: MemoryCompletionRequest[] }
+
+function parseMemoryCall(value: unknown): WorkerMemoryCall {
+  const body = value as { call?: unknown; snapshot?: unknown; requests?: unknown } | null;
+  if (!body || typeof body !== "object" || (body.call !== "complete" && body.call !== "completeBatch"))
+    throw new Error('call expects "complete" or "completeBatch"');
+  if (typeof body.snapshot !== "string" || !body.snapshot) throw new Error("snapshot expects the selected task model directory");
+  if (!Array.isArray(body.requests) || (body.call === "complete" && body.requests.length !== 1))
+    throw new Error(body.call === "complete" ? "complete expects exactly one request" : "requests expects an array");
+  const requests = body.requests.map((row: unknown, index): MemoryCompletionRequest => {
+    const { stage, input, maxTokens } = (row ?? {}) as { stage?: unknown; input?: { system?: unknown; user?: unknown } | null; maxTokens?: unknown };
+    if (typeof stage !== "string" || !stage || !input || typeof input !== "object" || typeof input.user !== "string" ||
+      (input.system !== undefined && typeof input.system !== "string") || typeof maxTokens !== "number" || !Number.isSafeInteger(maxTokens) || maxTokens < 1)
+      throw new Error(`requests[${index}] expects { stage, input: { system?, user }, maxTokens >= 1 }`);
+    return { stage, input: { ...(input.system !== undefined ? { system: input.system as string } : {}), user: input.user }, maxTokens };
+  });
+  return { call: body.call, snapshot: body.snapshot, requests };
+}
+
+const encoder = new TextEncoder();
+const describe = (error: unknown) => error instanceof Error ? error.message : String(error);
+const methodNotAllowed = (allow: string) => Response.json({ error: { message: `use ${allow}` } }, { status: 405, headers: { allow } });
+
+/** The group is a wrapper so it can count the model requests it admits;
+ * streaming bodies outlive `handle`, and the execution lease covers those. */
+export function createWorkerRoutes(options: WorkerRoutesOptions) {
+  let draining = false, inFlight = 0, closed = false;
+  const idleWaiters = new Set<() => void>();
+  /** Aborted by close(): every pending lease acquisition composes with it, and close joins them. */
+  const shutdown = new AbortController();
+  const pending = new Set<Promise<unknown>>();
+  const track = <T>(work: Promise<T>): Promise<T> => {
+    pending.add(work);
+    work.finally(() => { pending.delete(work); }).catch(() => {});
+    return work;
+  };
+  const held = new Set<{ release(): void; controller: ReadableStreamDefaultController<Uint8Array> }>();
+  const state = (): WorkerState => draining ? "draining" : "ready";
+  const health = () => {
+    const memory = options.memory?.();
+    return Response.json({ status: "ok", state: state(), model: options.modelId,
+      pid: options.pid ?? process.pid, in_flight: inFlight, leases: held.size, ...(memory ? { memory: memoryHealth(memory) } : {}) });
+  };
+  const closing = () => Response.json({ error: { message: "worker is closing", type: "unavailable" } }, { status: 503 });
+
+  // A parent-managed GPU job holds this response open. The connection owns
+  // the lease, so the parent dying cannot strand the worker's execution lock.
+  const lease = async (request: Request): Promise<Response> => {
+    const acquire = options.acquireExecutionLease!;
+    if (closed) return closing();
+    let lease: DisposableResource;
+    try { lease = await track(acquire(AbortSignal.any([request.signal, shutdown.signal]))); }
+    catch (error) {
+      if (closed) return closing();
+      if (request.signal.aborted) return new Response(null, { status: 499 });
+      return Response.json({ error: { message: `execution lease failed: ${error instanceof Error ? error.message : String(error)}`, type: "lease_failed" } }, { status: 503 });
+    }
+    // The acquisition may have resolved after close() ran: never publish a lease then.
+    if (closed || request.signal.aborted) { lease.dispose(); return closed ? closing() : new Response(null, { status: 499 }); }
+    const entry = { release: () => {}, controller: undefined as unknown as ReadableStreamDefaultController<Uint8Array> };
+    let released = false;
+    entry.release = () => {
+      if (released) return;
+      released = true;
+      held.delete(entry);
+      request.signal.removeEventListener("abort", entry.release);
+      lease.dispose();
+    };
+    held.add(entry);
+    request.signal.addEventListener("abort", entry.release, { once: true });
+    if (request.signal.aborted) entry.release();
+    return new Response(new ReadableStream<Uint8Array>({
+      start(controller) { entry.controller = controller; controller.enqueue(encoder.encode("leased\n")); },
+      cancel() { entry.release(); },
+    }), { headers: { "content-type": "application/octet-stream" } });
+  };
+
+  // The parent's synthesis sends one memory stage call or batch; the ordered
+  // raw outputs answer it (`{ outputs }`). The execution lease is taken before
+  // the task model's lazy load (of the call's snapshot) and released only
+  // after every row has joined, so memory work never overlaps generation or a
+  // managed job's lease. The parent disconnecting (a cancelled run, its
+  // shutdown) or close() aborts the rows; close() joins them.
+  const memory = async (request: Request): Promise<Response> => {
+    const task = options.memoryTaskModel!, acquire = options.acquireExecutionLease!;
+    if (closed) return closing();
+    let body: WorkerMemoryCall;
+    try { body = parseMemoryCall(await request.json()); }
+    catch (error) {
+      if (request.signal.aborted) return new Response(null, { status: 499 });
+      return Response.json({ error: { message: `invalid memory call: ${describe(error)}`, type: "invalid_request_error" } }, { status: 400 });
+    }
+    const signal = AbortSignal.any([request.signal, shutdown.signal]);
+    try {
+      const outputs = await track((async () => {
+        const exclusive = await acquire(signal);
+        try {
+          signal.throwIfAborted();
+          const client = task.clientFor(signal, body.snapshot);
+          return body.call === "complete" ? [await client.complete(body.requests[0]!)] : await client.completeBatch(body.requests);
+        } finally { exclusive.dispose(); }
+      })());
+      return Response.json({ outputs });
+    } catch (error) {
+      if (closed) return closing();
+      if (request.signal.aborted) return new Response(null, { status: 499 });
+      return Response.json({ error: { message: describe(error), type: "memory_failed" } }, { status: 500 });
+    }
+  };
+
+  // One private adapter call for the parent's models module: it runs on the model this worker holds, under its engine lock.
+  const adapters = async (request: Request): Promise<Response> => {
+    const operation = options.adapters!;
+    let call: WorkerAdapterCall;
+    try { call = parseAdapterCall(await request.json()); }
+    catch (error) {
+      if (request.signal.aborted) return new Response(null, { status: 499 });
+      return Response.json({ error: { message: `invalid adapter call: ${describe(error)}`, type: "invalid_request_error" } }, { status: 400 });
+    }
+    try {
+      switch (call.op) {
+        case "list": return Response.json({ adapters: await operation.list(request.signal) });
+        case "mount": return Response.json({ adapter: await operation.mount(call.id, call.path, request.signal) });
+        case "unmount": return Response.json({ removed: await operation.unmount(call.id, request.signal) });
+        case "merge": return Response.json({ stats: await operation.merge({ adapters: call.adapters, output: call.output, ...(call.scales ? { scales: call.scales } : {}) }, request.signal) });
+      }
+    } catch (error) {
+      if (request.signal.aborted) return new Response(null, { status: 499 });
+      return Response.json({ error: { message: describe(error), type: "adapter_failed" } }, { status: 400 });
+    }
+  };
+
+  // The parent subscribes to what this worker's engine publishes. Each connection is one subscription, released when
+  // the parent leaves or the surface closes; a held connection is not model work, so drain does not wait for it.
+  const streams = new Set<() => void>();
+  const events = (request: Request): Response => {
+    let unsubscribe = () => {}, stop = () => {}, timer: ReturnType<typeof setInterval> | undefined;
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        // The MLX memory reading follows the stream's own events: once at connect, after each finished request, and on the interval when it changed.
+        let last = "";
+        const reading = () => {
+          const memory = options.memory?.();
+          const key = memory ? JSON.stringify(memory) : "";
+          if (!memory || key === last) return;
+          last = key;
+          try { controller.enqueue(encoder.encode(memoryLine(memory))); } catch { stop(); }
+        };
+        unsubscribe = options.events?.subscribe("*", event => {
+          try { controller.enqueue(encoder.encode(JSON.stringify(event) + "\n")); } catch { stop(); return; }
+          if (event.type === "request.finished") reading();
+        }) ?? (() => {});
+        stop = () => { streams.delete(stop); unsubscribe(); clearInterval(timer); try { controller.close(); } catch { /* already ended */ } };
+        streams.add(stop);
+        request.signal.addEventListener("abort", stop, { once: true });
+        controller.enqueue(encoder.encode("\n"));
+        if (options.memory) { reading(); timer = setInterval(reading, options.memoryIntervalMs ?? 1_000); timer.unref?.(); }
+      },
+      cancel() { stop(); },
+    });
+    return new Response(stream, { headers: { "content-type": "application/x-ndjson" } });
+  };
+
+  // Drain: no new model request is admitted from now on (503), then wait for
+  // the admitted ones to return and for generation to quiesce, within the
+  // deadline. The report is honest either way; the gate stays shut.
+  const drain = async (request: Request): Promise<Response> => {
+    let timeoutMs = options.drainTimeoutMs ?? 120_000;
+    const text = await request.text();
+    if (text.trim()) {
+      let body: { timeout_ms?: unknown };
+      try { body = JSON.parse(text) as typeof body; } catch { return Response.json({ error: { message: "invalid JSON body" } }, { status: 400 }); }
+      if (body.timeout_ms !== undefined) {
+        if (typeof body.timeout_ms !== "number" || !(body.timeout_ms >= 0)) return Response.json({ error: { message: "timeout_ms expects a number >= 0" } }, { status: 400 });
+        timeoutMs = body.timeout_ms;
+      }
+    }
+    draining = true;
+    const started = Date.now();
+    const signal = AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs), shutdown.signal]);
+    let drained = false;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        if (inFlight === 0) return resolve();
+        // A signal aborted before we listen would never fire the listener.
+        if (signal.aborted) return reject(signal.reason);
+        const wake = () => { idleWaiters.delete(wake); signal.removeEventListener("abort", stop); resolve(); };
+        const stop = () => { idleWaiters.delete(wake); reject(signal.reason); };
+        idleWaiters.add(wake);
+        signal.addEventListener("abort", stop, { once: true });
+      });
+      if (options.acquireExecutionLease) (await track(options.acquireExecutionLease(signal))).dispose();
+      drained = !closed;
+    } catch (error) { if (!signal.aborted) throw error; }
+    return Response.json({ drained, state: state(), model: options.modelId, in_flight: inFlight, leases: held.size,
+      waited_ms: Date.now() - started, timed_out: !drained && !request.signal.aborted });
+  };
+
+  return {
+    state,
+    wrap(model: WorkerRouteGroup): WorkerRouteGroup {
+      return { async handle(request) {
+        const { pathname } = new URL(request.url);
+        if (pathname === "/health") return request.method === "GET" ? health() : methodNotAllowed("GET");
+        if (pathname === "/admin/lease" && options.acquireExecutionLease) return request.method === "POST" ? lease(request) : methodNotAllowed("POST");
+        if (pathname === "/admin/drain") return request.method === "POST" ? drain(request) : methodNotAllowed("POST");
+        if (pathname === "/admin/events" && (options.events || options.memory)) return request.method === "GET" ? events(request) : methodNotAllowed("GET");
+        if (draining) return Response.json({ error: { message: "worker is draining; no new requests are admitted", type: "draining" } }, { status: 503 });
+        inFlight++;
+        try {
+          // Memory and adapter calls are admitted and drained like model requests.
+          if (pathname === "/admin/memory/complete" && options.memoryTaskModel && options.acquireExecutionLease) return request.method === "POST" ? await memory(request) : methodNotAllowed("POST");
+          if (pathname === "/admin/adapters" && options.adapters) return request.method === "POST" ? await adapters(request) : methodNotAllowed("POST");
+          return await model.handle(request);
+        } finally { if (--inFlight === 0) for (const wake of [...idleWaiters]) wake(); }
+      } };
+    },
+    /** Shutdown: refuse new leases and memory calls, cancel pending
+     * acquisitions and memory calls and join them (every row settled), and
+     * release every connection-held lease and end its stream, so the
+     * listener's graceful stop is not waiting on a job's open connection. */
+    async close(): Promise<void> {
+      closed = true;
+      shutdown.abort(new Error("worker admin surface closed"));
+      for (const end of [...streams]) end();
+      for (const entry of [...held]) {
+        entry.release();
+        try { entry.controller.close(); } catch { /* already cancelled */ }
+      }
+      await Promise.allSettled([...pending]);
+    },
+  };
+}

package/src/storage/paths.ts

@@ -0,0 +1,61 @@
+// Every default location the app writes. Everything lives under one root,
+// `MLX_BUN_HOME` (default `~/.mlx-bun`); the Hugging Face hub cache holds
+// downloads only. Explicit user paths (flags, request fields, composition
+// options) always win over these defaults. Nothing is resolved at module load:
+// MLX_BUN_HOME comes from the runtime configuration and HOME from the
+// environment on each call (Bun's os.homedir() keeps the startup HOME).
+import { runtimeValue } from "@mlx-bun/inference/runtime/config";
+import { basename, join } from "node:path";
+import { MODEL_LAYOUT, mlxBunHome, openModelRegistry, userHome } from "@mlx-bun/app-services/home";
+
+export { mlxBunHome, userHome };
+
+/** The layout under the root, one entry per owner; the model index's own entries come from the host library. */
+const LAYOUT = {
+  ...MODEL_LAYOUT, // models: convert, web quantize and fuse outputs (plain model directories); registryDb: the derived index, rebuilt by scan
+  adapters: "adapters", // train, web fine-tune, merge, memory-stage adapters
+  exports: "exports", // adapter export manifests
+  kv: "kv", // saved prompt/KV state, one directory per model identity; one byte budget across them (engine/kv-budget.ts)
+  datasets: "datasets",
+  jobsDb: "db/jobs.sqlite",
+  memoryDb: "db/memory.sqlite",
+  jobLogs: "jobs",
+  wiki: "wiki",
+  skills: "skills",
+  logs: "logs",
+  credentials: "hf.json",
+} as const;
+export type StorageEntry = keyof typeof LAYOUT;
+
+/** A default location under `root` (the app's home unless a composition supplies one). */
+export function storagePath(entry: StorageEntry, root: string = mlxBunHome()): string {
+  return join(root, LAYOUT[entry]);
+}
+
+/** Adapter stores earlier versions wrote; listed read-only, never written or moved. */
+export function legacyAdapterDirs(home: string = userHome()): string[] {
+  return [join(home, ".cache/mlx-bun/adapters"), join(home, ".cache/mlx-bun/mlx-bun-finetunes"), join(home, ".cache/mlx-bun-finetunes")];
+}
+
+/** The stores the adapter listing reads: the app's own adapter store (where `train`, web fine-tunes, merges and memory stages write by default)
+ * under `root`, then the stores earlier versions wrote, read-only. */
+export function adapterStores(root: string = mlxBunHome(), home: string = userHome()): string[] {
+  return [storagePath("adapters", root), ...legacyAdapterDirs(home)];
+}
+
+/** A model's short name for derived output directories: the repo name of an
+ * `org/name` id or a hub snapshot path, else the directory's basename. */
+export function modelShortName(model: string): string {
+  const snapshot = /models--[^/]+?--([^/]+)\/snapshots\//.exec(model);
+  const name = snapshot ? snapshot[1]! : basename(model.replace(/\/+$/, ""));
+  return name.replace(/[^\w.-]/g, "") || "model";
+}
+
+/** The model index over the hub cache and the app's own model directory. */
+export const openRegistry = openModelRegistry;
+
+/** The app's explicit vault override, resolved without creating it. */
+export function memoryVaultPath(): string {
+  const override = runtimeValue("MLX_BUN_WIKI")?.trim();
+  return override ? override.replace(/^~(?=$|[/\\])/, userHome()) : storagePath("wiki");
+}

package/src/web/assets.ts

@@ -0,0 +1,37 @@
+/** Owns the browser's static files. The application mounts this alongside
+ * HTTP and WebSocket handlers; creating it neither opens a socket nor imports
+ * an inference engine. Prepack supplies generated JS; source checkouts build
+ * it in memory when absent, without requiring writable installation files. */
+export async function createWebHandler() {
+  const publicFile = (name: string) => Bun.file(new URL(`./public/${name}`, import.meta.url)).text();
+  const standalone = import.meta.filename.startsWith("/$bunfs/");
+  const script = Bun.file(new URL(standalone ? "./app.js" : "../../dist/web/app.js", import.meta.url));
+  if (standalone && !await script.exists()) throw new Error("Standalone app is missing its embedded browser bundle; rebuild with build:binary.");
+  const appSource = await script.exists()
+    ? script.text()
+    : import("./build").then(({ buildWebBundle }) => buildWebBundle());
+  const [html, app, highlight, theme, manifest, icon, worker] = await Promise.all([
+    publicFile("app.html"), appSource, publicFile("vendor/hljs.js"), publicFile("vendor/hljs-theme.css"),
+    publicFile("manifest.webmanifest"), publicFile("icon.svg"), publicFile("sw.js"),
+  ]);
+  const cache = "public, max-age=3600";
+  const files: Record<string, { body: string; type: string; cache?: string }> = {
+    "/": { body: html, type: "text/html; charset=utf-8" },
+    "/assets/app.js": { body: app, type: "text/javascript; charset=utf-8", cache },
+    "/assets/hljs.js": { body: highlight, type: "text/javascript; charset=utf-8", cache },
+    "/assets/hljs.css": { body: theme, type: "text/css; charset=utf-8", cache },
+    "/manifest.webmanifest": { body: manifest, type: "application/manifest+json; charset=utf-8", cache },
+    "/assets/icon.svg": { body: icon, type: "image/svg+xml; charset=utf-8", cache },
+    "/sw.js": { body: worker, type: "text/javascript; charset=utf-8", cache: "no-store" },
+  };
+  const legacy = new Set(["/status", "/chat", "/quantize", "/finetune", "/dataset"]);
+  return (request: Request): Response | null => {
+    if (request.method !== "GET") return null;
+    const path = new URL(request.url).pathname;
+    const file = Object.hasOwn(files, path) ? files[path] : undefined;
+    if (file) return new Response(file.body, { headers: {
+      "content-type": file.type, ...(file.cache ? { "cache-control": file.cache } : {}),
+    } });
+    return legacy.has(path) ? Response.redirect(`/#${path}`, 302) : null;
+  };
+}

package/src/web/{src → browser}/api.ts

@@ -1,11 +1,12 @@
-// GENERATED-ADJACENT source module — part of the src/web/src/* split (plan
-// §7/§9 Phase 2). Built into src/web/app.js by scripts/build-web.ts.
+// GENERATED-ADJACENT source module — part of the apps/mlx-bun/src/web/browser/*
+// split. Built into apps/mlx-bun/dist/web/app.js by
+// scripts/build-web.ts.
 //
 // Thin JSON-fetch helper + the SSE job-stream wrapper used by the
 // quantize/finetune/dataset controllers. Behavior-identical port of the
 // original inline <script> in app.html (api()/jobStream()).
 
-import type { ApiEnvelope, JobEvent, JobStreamHandlers } from "./protocol";
+import type { ApiEnvelope } from "./protocol";
 
 export type ApiOpts = (Omit<RequestInit, "body"> & { body?: unknown }) | undefined;
 
@@ -28,7 +29,7 @@ export async function api<T extends ApiEnvelope = ApiEnvelope>(path: string, opt
   try { data = text ? JSON.parse(text) : {}; } catch { data = { ok: false, error: text.slice(0, 400) || ("HTTP " + r.status) }; }
   // OpenAI-envelope errors are {error:{message,…}} — unwrap to a string so
   // callers can concatenate without printing "[object Object]"
-  // (web-ui-pass-plan.md #4).
+  // (`02d723a:docs/archive/planning/web-ui-pass-plan.md` #4).
   if (data && data.error && typeof data.error === "object") {
     const errObj = data.error as { message?: string };
     data.error = errObj.message || JSON.stringify(errObj).slice(0, 400);
@@ -36,22 +37,3 @@ export async function api<T extends ApiEnvelope = ApiEnvelope>(path: string, opt
   if (!r.ok && data.ok === undefined) data = { ok: false, error: (data.error as string) || data.message || ("HTTP " + r.status) };
   return data as T;
 }
-
-/**
- * Wraps an EventSource over /api/jobs/:id/stream and dispatches typed
- * events. Server -> client line protocol (JSON per `data:` line) — see
- * JobEvent in ./protocol.ts (pointer comment there to the server-side
- * source). Returns the EventSource so callers can .close().
- */
-export function jobStream(jobId: string, handlers: JobStreamHandlers): EventSource {
-  const es = new EventSource("/api/jobs/" + encodeURIComponent(jobId) + "/stream");
-  es.onmessage = (ev: MessageEvent) => {
-    let e: JobEvent;
-    try { e = JSON.parse(ev.data); } catch { return; }
-    const fn = handlers[e.type] as ((e: JobEvent) => void) | undefined;
-    if (fn) fn(e);
-  };
-  es.addEventListener("end", () => es.close());
-  es.onerror = () => { if (handlers.error) handlers.error(); };
-  return es;
-}

package/src/web/browser/chat-host.ts

@@ -0,0 +1,17 @@
+// The app's side of the chat panel (`@mlx-bun/module-chat`'s `<mlx-chat-panel>`): what lives beside the chat on this
+// page and is wired through the panel's `host` property. Memory's provenance chips replace the default tool card for
+// memory tools; the memory entry and consent card in the sidebar are attached once the panel's markup exists; the
+// agent-tools settings render in the settings dialog. The panel knows none of this: a host without a memory panel or a
+// settings dialog leaves the properties out.
+import { initMemoryPanel, memoryToolChip } from "./memory-panel";
+import { renderCodingToolsState, renderToolApprovals, storedCodingToolsPreference } from "./shell";
+
+export const chatHost = {
+  mounted() { initMemoryPanel(); },
+  toolCard(parent: HTMLElement, tool: string, args: unknown) { return memoryToolChip(parent, tool || "", args); },
+  settings: {
+    codingToolsPreference: storedCodingToolsPreference,
+    codingTools: renderCodingToolsState,
+    approvals: renderToolApprovals,
+  },
+};