mlx-bun 0.5.0 → 1.0.0

package/src/native/mic_capture.swift

@@ -1,92 +0,0 @@
-// Microphone capture sidecar for `mlx-bun dictate`: AVAudioEngine input
-// → 16 kHz mono float32 little-endian PCM on stdout, continuously, in
-// 20 ms buffers. Control lines go to stderr: "ready", and with --hotkey
-// <keycode>, "hotkey down" / "hotkey up" from a CGEvent listen-only tap
-// (needs the terminal app to have Input Monitoring; the mic needs
-// Microphone permission — macOS prompts on first use).
-//
-//   mic-capture [--rate 16000] [--hotkey 61]      (61 = Right Option)
-
-import AVFoundation
-import CoreGraphics
-import Foundation
-
-var rate: Double = 16000
-var hotkey: Int64? = nil
-var args = Array(CommandLine.arguments.dropFirst())
-while !args.isEmpty {
-    let a = args.removeFirst()
-    switch a {
-    case "--rate": rate = Double(args.removeFirst()) ?? 16000
-    case "--hotkey": hotkey = Int64(args.removeFirst())
-    default:
-        FileHandle.standardError.write("usage: mic-capture [--rate 16000] [--hotkey <keycode>]\n".data(using: .utf8)!)
-        exit(2)
-    }
-}
-
-let err = FileHandle.standardError
-let out = FileHandle.standardOutput
-let writeLock = NSLock()
-func note(_ s: String) { err.write((s + "\n").data(using: .utf8)!) }
-
-var hotkeyDown = false
-let engine = AVAudioEngine()
-let input = engine.inputNode
-let inFormat = input.outputFormat(forBus: 0)
-guard let outFormat = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: rate, channels: 1, interleaved: true),
-      let converter = AVAudioConverter(from: inFormat, to: outFormat) else {
-    note("error: cannot build audio converter"); exit(1)
-}
-input.installTap(onBus: 0, bufferSize: AVAudioFrameCount(inFormat.sampleRate * 0.02), format: inFormat) { buffer, _ in
-    let ratio = rate / inFormat.sampleRate
-    let capacity = AVAudioFrameCount(Double(buffer.frameLength) * ratio) + 32
-    guard let outBuf = AVAudioPCMBuffer(pcmFormat: outFormat, frameCapacity: capacity) else { return }
-    var consumed = false
-    var convError: NSError? = nil
-    converter.convert(to: outBuf, error: &convError) { _, status in
-        if consumed { status.pointee = .noDataNow; return nil }
-        consumed = true
-        status.pointee = .haveData
-        return buffer
-    }
-    if convError != nil || outBuf.frameLength == 0 { return }
-    let bytes = Data(bytes: outBuf.floatChannelData![0], count: Int(outBuf.frameLength) * 4)
-    writeLock.lock(); out.write(bytes); writeLock.unlock()
-}
-do { try engine.start() } catch { note("error: audio engine failed: \(error)"); exit(1) }
-note("ready rate=\(Int(rate)) input=\(Int(inFormat.sampleRate))Hz/\(inFormat.channelCount)ch")
-
-if let key = hotkey {
-    let mask: CGEventMask = (1 << CGEventType.flagsChanged.rawValue) | (1 << CGEventType.keyDown.rawValue) | (1 << CGEventType.keyUp.rawValue)
-    let callback: CGEventTapCallBack = { _, type, event, _ in
-        let code = event.getIntegerValueField(.keyboardEventKeycode)
-        if code == hotkey! {
-            var isDown = false
-            switch type {
-            case .keyDown: isDown = true
-            case .keyUp: isDown = false
-            case .flagsChanged:
-                let f = event.flags
-                isDown = f.contains(.maskAlternate) || f.contains(.maskCommand) || f.contains(.maskControl) || f.contains(.maskShift) || f.contains(.maskSecondaryFn)
-            default: return Unmanaged.passUnretained(event)
-            }
-            if isDown != hotkeyDown { hotkeyDown = isDown; note(isDown ? "hotkey down" : "hotkey up") }
-        }
-        return Unmanaged.passUnretained(event)
-    }
-    guard let tap = CGEvent.tapCreate(tap: .cgSessionEventTap, place: .headInsertEventTap, options: .listenOnly, eventsOfInterest: mask, callback: callback, userInfo: nil) else {
-        note("error: cannot create event tap — grant Input Monitoring to your terminal (System Settings → Privacy & Security)")
-        exit(3)
-    }
-    let source = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, tap, 0)
-    CFRunLoopAddSource(CFRunLoopGetCurrent(), source, .commonModes)
-    CGEvent.tapEnable(tap: tap, enable: true)
-    note("hotkey \(key) armed")
-}
-// stdin EOF (parent gone) ends the helper
-DispatchQueue.global().async {
-    _ = FileHandle.standardInput.readDataToEndOfFile()
-    exit(0)
-}
-CFRunLoopRun()

package/src/native-pack.ts

@@ -1,163 +0,0 @@
-// Native runtime pack (decision 2026-06-12, "one binary" discussion):
-// the mlx-bun executable ships alone (~61 MB, 100% our code + Bun); the
-// MLX native runtime (libmlx, libmlxc, libjaccl, mlx.metallib) is a
-// separate versioned tarball downloaded ON FIRST RUN into
-// ~/Library/Caches/mlx-bun/native-v<ver>-<arch>/ — resumable and
-// sha256-verified through the same downloadOne machinery as model
-// downloads, visible on the status page /downloads tracker.
-//
-// Resolution order for the libs (mirrored in src/mlx/ffi.ts):
-//   MLX_BUN_LIBMLXC env > beside the executable (sidecar dist/ layout,
-//   docs/reference/distribution.md) > the native-pack cache dir > homebrew.
-// Dev trees and embedders therefore never download anything.
-
-import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { downloadOne } from "./download";
-import { runtimeValue } from "./runtime-config";
-
-export const NATIVE_PACK_VERSION = "0.5.0";
-export const MLX_CORE_VERSION = "0.32.2";
-export const NATIVE_PACK_FILES = [
-  "libmlxc.dylib", "libmlx.dylib", "libjaccl.dylib", "mlx.metallib",
-  "libmlx_bun_expert_io.dylib", "mlx-bun-frame-extract", "mlx-bun-mic-capture",
-] as const;
-
-// RELEASE-TIME BAKE: scripts/build-native-pack.sh prints the sha256/size for
-// the freshly built tarball — publish `native-v0.4.0` with both assets and
-// paste the values here BEFORE tagging the package release (0.5.0 adds the
-// mlx-bun-mic-capture dictation sidecar) (the download
-// 404s until the GitHub release exists; dev trees resolve via homebrew/env
-// and never hit this path).
-const SHA256: Record<string, string> = {
-  arm64: "6ff825499ca48bd4e9adebeefac78108cc4328971011c233210d65a0aa78b427",
-};
-const SIZE: Record<string, number> = {
-  arm64: 41945454,
-};
-
-export function nativePackName(arch = process.arch): string {
-  return `mlx-bun-native-v${NATIVE_PACK_VERSION}-${arch}.tar.gz`;
-}
-
-/** GitHub release asset; override with MLX_BUN_NATIVE_PACK_URL. While
- *  the repo is private the download needs a token (GITHUB_TOKEN or
- *  `gh auth token`); once public it works anonymously. */
-export function nativePackUrl(arch = process.arch): string {
-  return runtimeValue("MLX_BUN_NATIVE_PACK_URL") ??
-    `https://github.com/joshuarossi/mlx-bun/releases/download/native-v${NATIVE_PACK_VERSION}/${nativePackName(arch)}`;
-}
-
-export function nativePackDir(arch = process.arch): string {
-  return join(homedir(), "Library", "Caches", "mlx-bun", `native-v${NATIVE_PACK_VERSION}-${arch}`);
-}
-
-/** Where the native runtime currently resolves from, or null if absent
- *  everywhere (= a fresh machine that needs the pack). */
-export function nativeRuntimeDir(): string | null {
-  const explicit = runtimeValue("MLX_BUN_LIBMLXC");
-  if (explicit) return dirname(explicit);
-  const candidates = [
-    dirname(process.execPath),
-    nativePackDir(),
-    "/opt/homebrew/lib",
-    "/usr/local/lib",
-  ];
-  for (const dir of candidates)
-    if (existsSync(join(dir, "libmlxc.dylib"))) return dir;
-  return null;
-}
-
-async function githubToken(): Promise<string | null> {
-  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
-  try {
-    const proc = Bun.spawn(["gh", "auth", "token"], { stdout: "pipe", stderr: "ignore" });
-    const out = (await new Response(proc.stdout).text()).trim();
-    return (await proc.exited) === 0 && out ? out : null;
-  } catch {
-    return null;
-  }
-}
-
-/** Map a github.com/<o>/<r>/releases/download/<tag>/<name> URL to a
- *  presigned asset URL via the API. Returns null when no token is
- *  available or the lookup fails (caller falls back to the plain URL,
- *  which works for public repos). */
-async function resolveGithubAssetUrl(url: string): Promise<string | null> {
-  const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/releases\/download\/([^/]+)\/(.+)$/.exec(url);
-  const token = await githubToken();
-  if (!m || !token) return null;
-  try {
-    const [, owner, repo, tag, name] = m;
-    const rel = await fetch(`https://api.github.com/repos/${owner}/${repo}/releases/tags/${tag}`, {
-      headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
-    });
-    if (!rel.ok) return null;
-    const assets = ((await rel.json()) as { assets: Array<{ name: string; url: string }> }).assets;
-    const asset = assets.find((a) => a.name === name);
-    if (!asset) return null;
-    const head = await fetch(asset.url, {
-      redirect: "manual",
-      headers: { authorization: `Bearer ${token}`, accept: "application/octet-stream" },
-    });
-    return head.headers.get("location"); // presigned; no auth needed past here
-  } catch {
-    return null;
-  }
-}
-
-export interface EnsureNativeOptions {
-  url?: string;
-  sha256?: string;
-  sizeBytes?: number;
-  destDir?: string;
-  onProgress?: (received: number, total: number) => void;
-}
-
-/** Make the native runtime available; returns its directory. No-op when
- *  any resolution candidate already has it. */
-export async function ensureNativeRuntime(opts: EnsureNativeOptions = {}): Promise<string> {
-  const existing = nativeRuntimeDir();
-  if (existing && !opts.destDir) return existing;
-
-  const arch = process.arch;
-  const url = opts.url ?? nativePackUrl(arch);
-  const sha256 = opts.sha256 ?? SHA256[arch];
-  const sizeBytes = opts.sizeBytes ?? SIZE[arch];
-  const destDir = opts.destDir ?? nativePackDir(arch);
-  if (NATIVE_PACK_FILES.every((file) => existsSync(join(destDir, file))))
-    return destDir;
-  if (!sha256 || !sizeBytes)
-    throw new Error(`no native pack published for ${arch} — set MLX_BUN_LIBMLXC or install mlx via homebrew`);
-
-  const tarPath = join(tmpdir(), `mlx-bun-native-${sha256.slice(0, 12)}.tar.gz`);
-  let fetchUrl = url;
-  let token: string | null = null;
-  if (url.startsWith("https://github.com/")) {
-    // Public repo: the releases/download URL works anonymously. Private
-    // repo: it 404s — resolve the asset's signed URL via the API
-    // (Accept: octet-stream + token → 302 with a presigned location).
-    const resolved = await resolveGithubAssetUrl(url);
-    if (resolved) fetchUrl = resolved;
-    else token = await githubToken(); // public-repo path; token unused but harmless
-  }
-  await downloadOne(fetchUrl, token, tarPath, { size: sizeBytes, sha256, name: nativePackName(arch) },
-    (_file, received, total) => opts.onProgress?.(received, total));
-
-  // Extract to a staging dir, then rename into place (atomic-ish: a
-  // crashed extract never leaves a half-populated cache dir).
-  const staging = `${destDir}.staging-${process.pid}`;
-  rmSync(staging, { recursive: true, force: true });
-  mkdirSync(staging, { recursive: true });
-  const untar = Bun.spawn(["tar", "-xzf", tarPath, "-C", staging], { stderr: "pipe" });
-  if ((await untar.exited) !== 0)
-    throw new Error(`native pack extract failed: ${await new Response(untar.stderr).text()}`);
-  for (const f of NATIVE_PACK_FILES)
-    if (!existsSync(join(staging, f))) throw new Error(`native pack missing ${f}`);
-  rmSync(destDir, { recursive: true, force: true });
-  mkdirSync(dirname(destDir), { recursive: true });
-  renameSync(staging, destDir);
-  rmSync(tarPath, { force: true });
-  return destDir;
-}

package/src/pi-provider.ts

@@ -1,53 +0,0 @@
-// mlx-bun pi-provider — the in-memory pi provider/registry/auth wiring that
-// points a pi AgentSession at the local mlx-bun server's loopback /v1.
-//
-// Shared by BOTH embed paths so the wiring can't drift:
-//   - src/pi-web.ts      (headless web-chat session over a WebSocket)
-//   - src/pi-terminal.ts (pi's own interactive TUI, in-process)
-//
-// The provider advertises a single, stable model id ("local"); the server
-// runs exactly one model at a time and which one varies run-to-run, so a
-// fixed id resolves to "whatever is loaded" and never goes stale. The real
-// repo id rides in the model `name` and is still reported by /v1/models.
-// This mirrors src/harness-pi.ts (the external-provider path).
-
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
-
-/** 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"]>>;
-
-import { PI_PROVIDER_ID, PI_API_KEY, PI_API, PI_LOCAL_MODEL_ID, piModelDefinition,
-  type PiModelOptions } from "./contracts/pi-provider";
-export { PI_PROVIDER_ID, PI_API_KEY, PI_API, PI_LOCAL_MODEL_ID,
-  DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS } from "./contracts/pi-provider";
-export interface PiProviderOptions extends PiModelOptions {}
-
-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 authStorage = AuthStorage.inMemory();
-  authStorage.setRuntimeApiKey(PI_PROVIDER_ID, PI_API_KEY);
-
-  const modelRegistry = ModelRegistry.inMemory(authStorage);
-  modelRegistry.registerProvider(PI_PROVIDER_ID, {
-    baseUrl,
-    apiKey: PI_API_KEY,
-    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/pi-session.ts

@@ -1,81 +0,0 @@
-// Shared pi front-door assembly for mlx-bun's embedded web + terminal agents.
-//
-// This is the single place that decides which custom tools and bundled skills
-// are visible to pi. Keeping that policy here prevents the browser and TUI from
-// drifting — especially for personal memory, whose prompt surface must be
-// relevant-but-not-dominant.
-
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { createWebTools, WEB_TOOL_NAMES } from "./web-tools";
-import { materializeBundledSkillPaths } from "./web/skills";
-import {
-  createMemoryTools,
-  MEMORY_TOOL_NAMES,
-  memoryIndexHint,
-  isMemoryEnabled,
-  createReferenceTools,
-  REFERENCE_TOOL_NAMES,
-} from "./memory/tools";
-
-/** Built-in pi coding tools plus mlx-bun's non-mutating web tools. */
-export const PI_BASE_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls", ...WEB_TOOL_NAMES] as const;
-
-export interface PiAgentSurfaceOptions {
-  /** Force memory on/off for tests. Default: auto-detect vault existence. */
-  memory?: "auto" | "on" | "off";
-  /** Include web_search/web_fetch/weather. Default true. */
-  webTools?: boolean;
-  /** Include read/bash/edit/write/grep/find/ls. Default true. */
-  codingTools?: boolean;
-}
-
-export interface PiAgentSurface {
-  memoryEnabled: boolean;
-  /** Tool allowlist to pass to createAgentSession/createAgentSessionFromServices. */
-  tools: string[];
-  /** Custom tools to pass to pi. Built-ins are selected by name in `tools`. */
-  customTools: ToolDefinition[];
-  /** Skill paths for DefaultResourceLoader.additionalSkillPaths. */
-  skillPaths: string[];
-  /** Short prompt addendum. Empty unless memory is enabled. */
-  memoryHint: string;
-}
-
-async function resolveMemoryEnabled(mode: PiAgentSurfaceOptions["memory"]): Promise<boolean> {
-  if (mode === "on") return true;
-  if (mode === "off") return false;
-  return isMemoryEnabled();
-}
-
-/**
- * Build the shared tool + skill surface for both pi front doors.
- *
- * Memory policy: if the user enabled memory (vault exists), memory is available.
- * It is still a scoped retrieval capability, not a default first step for every
- * prompt. If memory is absent, no memory skill/tool schemas are exposed at all.
- */
-export async function buildPiAgentSurface(opts: PiAgentSurfaceOptions = {}): Promise<PiAgentSurface> {
-  const memoryEnabled = await resolveMemoryEnabled(opts.memory ?? "auto");
-  const includeWeb = opts.webTools ?? true;
-  const includeCoding = opts.codingTools ?? true;
-
-  const tools: string[] = [];
-  if (includeCoding) tools.push("read", "bash", "edit", "write", "grep", "find", "ls");
-  const customTools: ToolDefinition[] = [];
-  if (includeWeb) {
-    tools.push(...WEB_TOOL_NAMES);
-    customTools.push(...createWebTools());
-  }
-  if (memoryEnabled) {
-    tools.push(...MEMORY_TOOL_NAMES, ...REFERENCE_TOOL_NAMES);
-    customTools.push(...createMemoryTools(), ...createReferenceTools());
-  }
-
-  return {
-    memoryEnabled,
-    tools,
-    customTools,
-    skillPaths: materializeBundledSkillPaths({ includeMemory: memoryEnabled }),
-    memoryHint: memoryEnabled ? await memoryIndexHint() : "",
-  };
-}

package/src/pi-terminal.ts

@@ -1,274 +0,0 @@
-// mlx-bun pi-terminal — drive pi's OWN interactive TUI in-process against the
-// local mlx-bun server (Phase 16 P3/P4). No subprocess, no requirement that
-// the user install pi: pi is a bundled dependency, so we build an
-// AgentSessionRuntime with the SDK and hand it to pi's exported InteractiveMode.
-//
-// This is the terminal twin of src/pi-web.ts (the headless web embed). They
-// share the provider wiring (src/pi-provider.ts) and the curated skills
-// (src/web/skills.ts); the differences are:
-//   - we build an AgentSessionRuntime (InteractiveMode needs the runtime, not
-//     the bare session createAgentSession returns), via the same
-//     createAgentSessionServices + createAgentSessionFromServices the pi CLI
-//     uses (dist/main.js) — see examples/sdk/13-session-runtime.ts;
-//   - tool approval is pi's own built-in TUI prompt, so there's no custom
-//     approval gate here (the web path needs one only because the browser
-//     drives approvals over a WebSocket);
-//   - the system prompt is a custom mlx-bun CODING-agent persona (the web
-//     path is a general chat assistant);
-//   - sessions persist (~/.mlx-bun/pi) so /resume and history work.
-//
-// Modes mirror pi's CLI: interactive (InteractiveMode), one-shot print
-// (`-p` / `--mode json` → runPrintMode), and JSONL RPC (`--mode rpc` →
-// runRpcMode). All three are SDK exports, so the embedded CLI keeps pi's
-// headless surface.
-
-import { homedir } from "node:os";
-import { join } from "node:path";
-import {
-  InteractiveMode,
-  SessionManager,
-  createAgentSessionFromServices,
-  createAgentSessionRuntime,
-  createAgentSessionServices,
-  initTheme,
-  runPrintMode,
-  runRpcMode,
-  type CreateAgentSessionRuntimeFactory,
-} from "@earendil-works/pi-coding-agent";
-import { buildPiAgentSurface } from "./pi-session";
-import { buildPiProvider, DEFAULT_CONTEXT_WINDOW } from "./pi-provider";
-
-/** How the embedded agent runs. Mirrors pi's CLI appMode. */
-export type PiTerminalMode = "interactive" | "print" | "rpc";
-
-/**
- * Full toolset the terminal agent is offered: pi's built-in coding tools plus
- * our outward-facing web tools. pi treats this list as an allowlist, so a
- * custom tool's name MUST appear here or it's filtered out before the model
- * sees it. Mutating tools (bash/edit/write) surface pi's own TUI approval
- * prompt at call time — we don't add a gate.
- */
-/**
- * System prompt for the embedded terminal coding agent.
- *
- * This fully REPLACES pi's default coding-agent prompt (it flows to
- * buildSystemPrompt's `customPrompt` via the resource loader's `systemPrompt`).
- * We replace rather than append so the agent's identity is mlx-bun's, not
- * "operating inside pi, a coding agent harness", and so pi's block of internal
- * documentation paths is dropped. pi still auto-appends the current date and
- * working directory, so we don't repeat them here.
- *
- * Unlike the web chat (a general assistant), this is a true terminal CODING
- * agent: it lives in the user's project directory with real read/run/edit
- * tools. The capability list stays honest about which tools ask for approval
- * so the model never promises an action the user must still confirm.
- */
-export function buildTerminalSystemPrompt(modelLabel?: string): string {
-  const model = modelLabel ? `the local model \`${modelLabel}\`` : "a local model";
-  return `You are mlx-bun's terminal coding agent — a capable, hands-on pair programmer working alongside the user in their terminal. You run on ${model} entirely on the user's own Apple-silicon Mac via mlx-bun, so the whole session stays local and private; nothing leaves the machine except the explicit web tools below.
-
-You operate inside the user's current project directory. Available capabilities when relevant: read-only file inspection (read, ls, find, grep), web search/fetch (web_search, web_fetch), weather, and user-approved local actions (bash, edit, write).
-
-Use tools in service of helping the user, not as a performance. For ordinary social conversation, answer naturally yourself. For real-world facts, current events, schedules, releases, local information, recommendations, restaurants, movies, prices, travel, docs, or anything likely to have changed, look it up with web_search/web_fetch or weather instead of relying on memory or guessing. For coding tasks, inspect the files, investigate before you answer, and follow through to a working result. When you need to change code or run something, propose the concrete edit or command and let the approval prompt handle consent — don't ask permission in prose first.
-
-Environment metadata such as current date, working directory, model name, and available tools may be provided for context; do not report or summarize that metadata unless the user asks for it or it is directly relevant. Do not narrate tool policies or internal workflows.
-
-Be honest about what you did and what you found, including mistakes, dead ends, and anything you couldn't do. Keep responses tight and skimmable: format with Markdown, show file paths and commands plainly, and cite links when you used the web.`;
-}
-
-export interface RunEmbeddedPiOptions {
-  /** mlx-bun server base URL, e.g. "http://localhost:8080/v1". */
-  baseUrl: string;
-  /** Real served model id, used to label the model in the prompt + registry. */
-  modelLabel?: string;
-  /** Context window advertised to pi. Default: DEFAULT_CONTEXT_WINDOW. */
-  contextWindow?: number;
-  /** Whether the served model has a switchable thinking channel. */
-  reasoning?: boolean;
-  /** Whether the served model accepts images (server's vision capability —
-   *  /v1/models `vision`). MUST match the real model: see PiProviderOptions. */
-  vision?: boolean;
-  /** Run mode. Default: "interactive". */
-  mode?: PiTerminalMode;
-  /** Print mode output format ("text" final-only, "json" event stream). */
-  printFormat?: "text" | "json";
-  /** First message to send (print: the prompt; interactive: pre-filled turn). */
-  initialMessage?: string;
-  /** Additional messages to send after initialMessage. */
-  messages?: string[];
-  /** Force pi's verbose startup banner (interactive only). */
-  verbose?: boolean;
-}
-
-/**
- * Build an AgentSessionRuntime against the local server and run pi in the
- * requested mode. Returns the process exit code. Disposes the runtime on the
- * way out. Runs in the SAME process as the server when the CLI started one —
- * pi's TUI event loop and the generation queue share the JS thread (mlx
- * compute is native); pi's rendering is differential and cheap.
- */
-export async function runEmbeddedPi(opts: RunEmbeddedPiOptions): Promise<number> {
-  const mode = opts.mode ?? "interactive";
-  const cwd = process.cwd();
-  // Own session/settings dir, isolated from any standalone pi install.
-  const agentDir = join(homedir(), ".mlx-bun", "pi");
-  const sessionDir = join(agentDir, "sessions", `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`);
-
-  const { authStorage, modelRegistry, model } = buildPiProvider(opts.baseUrl, {
-    contextWindow: opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
-    name: opts.modelLabel ? `${opts.modelLabel} (mlx-bun local)` : undefined,
-    reasoning: opts.reasoning ?? false,
-    vision: opts.vision ?? false,
-  });
-
-  // Shared pi tool/skill surface. Memory is included only when the user has
-  // enabled a vault; if present it remains scoped to user-specific continuity.
-  const surface = await buildPiAgentSurface();
-  const systemPrompt = buildTerminalSystemPrompt(opts.modelLabel) + surface.memoryHint;
-
-  // The runtime factory: same shape as pi's own CLI (dist/main.js) and the
-  // shipped examples/sdk/13-session-runtime.ts. The same factory is reused by
-  // pi for /new, /resume, /fork — so the provider/prompt/tools are stable
-  // across session switches within the TUI.
-  const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd: rcwd, sessionManager, sessionStartEvent }) => {
-    const services = await createAgentSessionServices({
-      cwd: rcwd,
-      agentDir,
-      authStorage,
-      modelRegistry,
-      resourceLoaderOptions: {
-        // Isolated from the user's own ~/.pi: don't inherit their extensions,
-        // prompt templates, themes, or auto-discovered skills.
-        noExtensions: true,
-        noSkills: true,
-        noPromptTemplates: true,
-        noThemes: true,
-        // A coding agent in a project dir SHOULD read the project's own
-        // AGENTS.md / CLAUDE.md context files (unlike the web chat).
-        noContextFiles: false,
-        // Our curated skills on top (noSkills above only disables discovery).
-        additionalSkillPaths: surface.skillPaths,
-        // Replace pi's default coding-agent prompt with our mlx-bun persona.
-        systemPrompt,
-      },
-    });
-    return {
-      ...(await createAgentSessionFromServices({
-        services,
-        sessionManager,
-        sessionStartEvent,
-        model,
-        tools: surface.tools,
-        customTools: surface.customTools,
-      })),
-      services,
-      diagnostics: services.diagnostics,
-    };
-  };
-
-  const sessionManager = SessionManager.create(cwd, sessionDir);
-  const runtime = await createAgentSessionRuntime(createRuntime, { cwd, agentDir, sessionManager });
-
-  try {
-    if (mode === "rpc") {
-      // runRpcMode never returns (Promise<never>); it owns stdin/stdout.
-      await runRpcMode(runtime);
-      return 0;
-    }
-    if (mode === "print") {
-      return await runPrintMode(runtime, {
-        mode: opts.printFormat ?? "text",
-        messages: opts.messages,
-        initialMessage: opts.initialMessage,
-      });
-    }
-    // interactive — initialize the theme (pi's CLI does this before the TUI)
-    // then run pi's own full interactive mode.
-    initTheme(runtime.services.settingsManager.getTheme(), true);
-    await new InteractiveMode(runtime, {
-      initialMessage: opts.initialMessage,
-      initialMessages: opts.messages,
-      verbose: opts.verbose,
-    }).run();
-    return 0;
-  } finally {
-    try {
-      await runtime.dispose();
-    } catch {
-      // Best-effort teardown; never mask the real exit path.
-    }
-  }
-}
-
-/** Result of parsing the pi passthrough argv into an embedded run config. */
-export interface ParsedPiArgs {
-  mode: PiTerminalMode;
-  printFormat: "text" | "json";
-  /** Joined free-text message (the trailing words / `-p <text>`). */
-  message?: string;
-  /** pi's verbose startup banner (interactive only). */
-  verbose: boolean;
-  /** Unknown flags that were dropped (with their values) — callers should
-   *  warn so `--resume`-style pi flags don't fail silently. */
-  ignored: string[];
-}
-
-/**
- * Parse the argv left over after mlx-bun's own flags are stripped into a
- * mode + message for runEmbeddedPi. Pure (takes `isStdinPiped`) so it's
- * unit-testable. Covers the headline pi modes:
- *   - `-p` / `--print`            → print (text), prompt from -p value / words / stdin
- *   - `--mode json` / `-p --json` → print (json)
- *   - `--mode rpc`                → rpc
- *   - piped stdin (non-TTY)       → print (text), like pi's own CLI
- *   - anything else               → interactive (trailing words pre-fill turn 1)
- * The built-in agent is deliberately scoped to these modes. The full pi
- * flag surface (--continue, --resume, @file expansion, extensions, themes)
- * belongs to the user's OWN pi — point it at this server with
- * `mlx-bun harness pi`.
- */
-export function parsePiArgs(passthrough: string[], isStdinPiped: boolean): ParsedPiArgs {
-  let print = false;
-  let rpc = false;
-  let json = false;
-  let verbose = false;
-  const words: string[] = [];
-  const ignored: string[] = [];
-  for (let i = 0; i < passthrough.length; i++) {
-    const a = passthrough[i]!;
-    if (a === "-p" || a === "--print") {
-      print = true;
-    } else if (a === "--json") {
-      json = true;
-    } else if (a === "--verbose") {
-      verbose = true;
-    } else if (a === "--mode") {
-      const m = passthrough[++i];
-      if (m === "rpc") rpc = true;
-      else if (m === "json") { print = true; json = true; }
-      else if (m === "text") print = true;
-    } else if (a.startsWith("-")) {
-      // Unknown flag for the built-in agent: drop it AND its value (the full
-      // pi flag surface lives in the user's own pi via `mlx-bun harness pi`).
-      // Without the value-swallow, `mlx-bun pi --resume abc123` started a
-      // chat with the message "abc123". A following token that looks like
-      // another flag is not a value, so it isn't consumed.
-      const next = passthrough[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        ignored.push(`${a} ${next}`);
-        i++;
-      } else {
-        ignored.push(a);
-      }
-    } else {
-      words.push(a);
-    }
-  }
-  const message = words.length > 0 ? words.join(" ") : undefined;
-  const printFormat = json ? "json" : "text";
-  if (rpc) return { mode: "rpc", printFormat: "text", message, verbose, ignored };
-  // `-p`/`--mode` request print; piped stdin makes a bare invocation one-shot
-  // too, matching pi's own CLI (it reads stdin → switches to print mode).
-  if (print || isStdinPiped) return { mode: "print", printFormat, message, verbose, ignored };
-  return { mode: "interactive", printFormat, message, verbose, ignored };
-}