mlx-bun 0.0.4

package/src/web/skills/web-research/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: web-research
+description: Use when the user asks you to research something, do a deep dive, fact-check a claim, compare options, or answer a question that needs current, accurate, real-world information ("what's the latest on…", prices, releases, news, specs). Gives a rigorous workflow for searching the web, reading primary sources, cross-checking claims, and answering with citations.
+---
+
+# Web Research
+
+A workflow for answering questions that need current, accurate, real-world
+information, using the `web_search` and `web_fetch` tools. The goal is a
+trustworthy, well-sourced answer — not a guess dressed up as one.
+
+## When to use this
+
+- The answer depends on current events, recent releases, prices, versions,
+  or anything that changes over time.
+- The user wants a thorough or authoritative answer, or asks for sources.
+- A specific claim needs verifying, or you would otherwise be speculating.
+
+## Workflow
+
+1. **Plan.** Restate the question in your own words and list the 2–4 concrete
+   things you need to find out. This keeps the searches focused.
+2. **Search broadly.** Call `web_search` with a few focused queries — one idea
+   per query — rather than a single vague one. Vary the wording if the first
+   results are weak.
+3. **Read the best sources.** Use `web_fetch` to actually read the most
+   relevant results. Prefer primary sources (official docs, the original
+   announcement, the paper, the vendor's own page) over blogs and aggregators.
+   Read at least two or three independent sources.
+4. **Cross-check.** Confirm each key fact appears in more than one independent
+   source. Where sources disagree, surface the disagreement instead of picking
+   one silently.
+5. **Answer.** Lead with a direct answer, then the supporting detail. Cite
+   every nontrivial claim with a Markdown link to a page you actually fetched.
+   Separate what's well-supported from what's uncertain.
+
+## Quality rules
+
+- Check publication dates; for fast-moving topics, prefer recent sources.
+- Never cite a page you didn't fetch, and never invent quotes, numbers, or URLs.
+- Quote sparingly and exactly.
+- If the sources are thin or conflicting, say so plainly — don't overstate
+  confidence to sound complete.
+- If a search returns nothing useful, try different terms before giving up.

package/src/web/skills.ts

@@ -0,0 +1,59 @@
+// mlx-bun bundled skills — curated pi skills the web chat ships with.
+//
+// Why materialize to disk? pi loads skills by reading SKILL.md from a
+// filesystem path, but mlx-bun also ships as a single `bun build --compile`
+// binary where source files don't exist on disk. So each SKILL.md is
+// embedded into the bundle as a text import (the same trick app.html uses)
+// and written to ~/.mlx-bun/skills/<name>/SKILL.md at startup. One source of
+// truth that resolves identically when run from source and from the binary —
+// no build-script changes, no sidecar files.
+//
+// These load via DefaultResourceLoader.additionalSkillPaths even though the
+// web session keeps noSkills:true: that flag only disables auto-discovery of
+// the user's personal ~/.pi and project .pi skills, so the chat stays
+// isolated while still getting our curated set (resource-loader.js:277).
+//
+// To add a skill: drop a folder under ./skills/<name>/SKILL.md, add a text
+// import for it, and append it to BUNDLED_SKILLS.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import webResearchMd from "./skills/web-research/SKILL.md" with { type: "text" };
+
+interface BundledSkill {
+  /** Directory name under the skills root; should match the SKILL.md `name`. */
+  name: string;
+  /** Raw SKILL.md contents, embedded at build time. */
+  md: string;
+}
+
+const BUNDLED_SKILLS: readonly BundledSkill[] = [
+  { name: "web-research", md: webResearchMd },
+];
+
+/** Where the bundled skills are written; also pi's per-session scratch root. */
+export function bundledSkillsRoot(): string {
+  return join(homedir(), ".mlx-bun", "skills");
+}
+
+/** Memoize: the embedded content can't change within a process run. */
+let materialized = false;
+
+/**
+ * Write the embedded skills to disk (overwriting, so updates propagate) and
+ * return the root directory to pass as a single additionalSkillPaths entry.
+ * pi scans it for per-skill SKILL.md files. Runs its disk writes once per
+ * process even when called per browser connection.
+ */
+export function materializeBundledSkills(): string {
+  const root = bundledSkillsRoot();
+  if (materialized) return root;
+  for (const skill of BUNDLED_SKILLS) {
+    const dir = join(root, skill.name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), skill.md);
+  }
+  materialized = true;
+  return root;
+}

package/src/web-tools.ts

@@ -0,0 +1,426 @@
+// mlx-bun web-tools — outward-facing capabilities for the web chat agent:
+// web_search, web_fetch, and weather. These are pi custom tools (defineTool)
+// registered alongside the built-in coding tools so the local model can pull
+// in current, real-world information instead of only inspecting the machine.
+//
+// Design notes:
+//  - Keyless by default. weather uses Open-Meteo (no key, no anti-bot),
+//    web_fetch is a plain HTTP GET, and web_search defaults to DuckDuckGo's
+//    keyless HTML endpoint. Setting TAVILY_API_KEY or BRAVE_API_KEY upgrades
+//    web_search to that provider's JSON API (more reliable, ranked results).
+//  - Non-mutating: none of these touch the user's filesystem, so the web
+//    chat's approval gate auto-allows them (they're not in GATED_TOOLS).
+//    They DO make outbound network requests — that's the one thing that
+//    leaves the machine, and only when the user asks for live info.
+//  - execute() never throws on a network/upstream failure: it returns the
+//    error as tool text so the model can read it and adapt (retry, tell the
+//    user, fall back) rather than the turn aborting.
+//
+// The pure helpers (htmlToText, wmoCodeToText, parseDuckDuckGoHtml, the
+// formatters) are exported and unit-tested without touching the network.
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+/** Tool names, exported so pi-web can add them to its tool allowlist. */
+export const WEB_TOOL_NAMES = ["web_search", "web_fetch", "weather"] as const;
+
+/** Browser-ish UA: some endpoints (DuckDuckGo) serve a challenge to blanks. */
+const USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+const FETCH_TIMEOUT_MS = 20_000;
+/** Cap on text returned to the model from a fetched page. */
+const MAX_FETCH_CHARS = 12_000;
+const DEFAULT_SEARCH_RESULTS = 5;
+const MAX_SEARCH_RESULTS = 10;
+
+// ---- low-level fetch helper ------------------------------------------
+
+/** Combine the tool's abort signal with a wall-clock timeout. */
+function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  const timeout = AbortSignal.timeout(ms);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+interface FetchResult {
+  ok: boolean;
+  status: number;
+  finalUrl: string;
+  contentType: string;
+  text: string;
+}
+
+/** GET/POST a URL and read the body as text, with timeout + abort wiring. */
+async function httpText(
+  url: string,
+  opts: { method?: string; headers?: Record<string, string>; body?: string; signal?: AbortSignal; timeoutMs?: number },
+): Promise<FetchResult> {
+  const res = await fetch(url, {
+    method: opts.method ?? "GET",
+    headers: { "user-agent": USER_AGENT, ...opts.headers },
+    body: opts.body,
+    redirect: "follow",
+    signal: withTimeout(opts.signal, opts.timeoutMs ?? FETCH_TIMEOUT_MS),
+  });
+  const contentType = res.headers.get("content-type") ?? "";
+  const text = await res.text();
+  return { ok: res.ok, status: res.status, finalUrl: res.url || url, contentType, text };
+}
+
+/** Normalize anything thrown by fetch (timeout, DNS, abort) into a message. */
+function describeFetchError(err: unknown): string {
+  if (err instanceof Error) {
+    if (err.name === "TimeoutError") return "request timed out";
+    if (err.name === "AbortError") return "request was cancelled";
+    return err.message;
+  }
+  return String(err);
+}
+
+// ---- pure helpers (unit-tested) --------------------------------------
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", "#39": "'", "#34": '"',
+};
+
+/** Decode the handful of HTML entities that show up in scraped text. */
+export function decodeEntities(s: string): string {
+  return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body: string) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return NAMED_ENTITIES[body] ?? whole;
+  });
+}
+
+/** Strip all HTML tags from a fragment and decode entities (single-line). */
+export function stripTags(html: string): string {
+  return decodeEntities(html.replace(/<[^>]*>/g, "")).replace(/\s+/g, " ").trim();
+}
+
+/** Extract the <title> of an HTML document, if any. */
+export function extractTitle(html: string): string | undefined {
+  const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return m ? stripTags(m[1] ?? "") : undefined;
+}
+
+/**
+ * Reduce an HTML document to readable plain text: drop script/style/head,
+ * turn block-level boundaries into newlines, strip remaining tags, decode
+ * entities, and collapse runaway whitespace.
+ */
+export function htmlToText(html: string): string {
+  let s = html
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<(script|style|noscript|template|svg)[^>]*>[\s\S]*?<\/\1>/gi, "")
+    .replace(/<head[^>]*>[\s\S]*?<\/head>/gi, "");
+  // Block-level close/break tags become newlines so structure survives.
+  s = s.replace(/<\/(p|div|section|article|li|ul|ol|tr|h[1-6]|header|footer|nav|blockquote)>/gi, "\n");
+  s = s.replace(/<br\s*\/?>/gi, "\n");
+  s = s.replace(/<[^>]+>/g, "");
+  s = decodeEntities(s);
+  // Collapse spaces/tabs, trim each line, squeeze blank-line runs.
+  s = s.replace(/[ \t\f\v]+/g, " ");
+  s = s.split("\n").map((line) => line.trim()).join("\n");
+  s = s.replace(/\n{3,}/g, "\n\n");
+  return s.trim();
+}
+
+/** Clamp text to a max length, appending a clear truncation marker. */
+export function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return text.slice(0, max) + `\n\n…[truncated ${text.length - max} more characters]`;
+}
+
+/** WMO weather interpretation codes (Open-Meteo) → human description. */
+export function wmoCodeToText(code: number): string {
+  const map: Record<number, string> = {
+    0: "clear sky", 1: "mainly clear", 2: "partly cloudy", 3: "overcast",
+    45: "fog", 48: "depositing rime fog",
+    51: "light drizzle", 53: "moderate drizzle", 55: "dense drizzle",
+    56: "light freezing drizzle", 57: "dense freezing drizzle",
+    61: "slight rain", 63: "moderate rain", 65: "heavy rain",
+    66: "light freezing rain", 67: "heavy freezing rain",
+    71: "slight snowfall", 73: "moderate snowfall", 75: "heavy snowfall",
+    77: "snow grains",
+    80: "slight rain showers", 81: "moderate rain showers", 82: "violent rain showers",
+    85: "slight snow showers", 86: "heavy snow showers",
+    95: "thunderstorm", 96: "thunderstorm with slight hail", 99: "thunderstorm with heavy hail",
+  };
+  return map[code] ?? `unknown (code ${code})`;
+}
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/** Resolve a DuckDuckGo redirect href (//duckduckgo.com/l/?uddg=…) to the real URL. */
+export function resolveDdgHref(href: string): string {
+  const decoded = decodeEntities(href);
+  const m = decoded.match(/[?&]uddg=([^&]+)/);
+  if (m && m[1]) {
+    try {
+      return decodeURIComponent(m[1]);
+    } catch {
+      return decoded;
+    }
+  }
+  return decoded.startsWith("//") ? "https:" + decoded : decoded;
+}
+
+/**
+ * Parse the result list out of html.duckduckgo.com/html/ output. Pairs each
+ * result anchor (title + href) with the following snippet anchor by order.
+ * Returns [] when the page carries no results (e.g. a challenge/empty page).
+ */
+export function parseDuckDuckGoHtml(html: string, limit: number): SearchResult[] {
+  const results: SearchResult[] = [];
+  const linkRe = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+  const snippetRe = /<a[^>]*class="[^"]*result__snippet[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+  const snippets: string[] = [];
+  let sm: RegExpExecArray | null;
+  while ((sm = snippetRe.exec(html)) !== null) snippets.push(stripTags(sm[1] ?? ""));
+  let lm: RegExpExecArray | null;
+  let i = 0;
+  while ((lm = linkRe.exec(html)) !== null && results.length < limit) {
+    const url = resolveDdgHref(lm[1] ?? "");
+    const title = stripTags(lm[2] ?? "");
+    if (!title || !url) {
+      i++;
+      continue;
+    }
+    results.push({ title, url, snippet: snippets[i] ?? "" });
+    i++;
+  }
+  return results;
+}
+
+/** Render a result list as numbered Markdown for the model. */
+export function formatSearchResults(query: string, results: SearchResult[], provider: string): string {
+  if (results.length === 0) {
+    return `No results found for "${query}" (via ${provider}).`;
+  }
+  const lines = results.map((r, idx) => {
+    const head = `${idx + 1}. ${r.title}\n   ${r.url}`;
+    return r.snippet ? `${head}\n   ${r.snippet}` : head;
+  });
+  return `Search results for "${query}" (via ${provider}):\n\n${lines.join("\n\n")}`;
+}
+
+// ---- weather: Open-Meteo geocode + forecast --------------------------
+
+interface GeoPlace {
+  name: string;
+  latitude: number;
+  longitude: number;
+  country?: string;
+  admin1?: string;
+}
+
+/** Format an Open-Meteo forecast response into a compact human summary. */
+export function formatWeather(place: GeoPlace, data: unknown, fahrenheit: boolean): string {
+  const d = data as {
+    current?: {
+      temperature_2m?: number;
+      apparent_temperature?: number;
+      relative_humidity_2m?: number;
+      wind_speed_10m?: number;
+      weather_code?: number;
+    };
+    daily?: { time?: string[]; weather_code?: number[]; temperature_2m_max?: number[]; temperature_2m_min?: number[]; precipitation_probability_max?: number[] };
+  };
+  const tUnit = fahrenheit ? "°F" : "°C";
+  const wUnit = fahrenheit ? "mph" : "km/h";
+  const where = [place.name, place.admin1, place.country].filter(Boolean).join(", ");
+  const lines: string[] = [`Weather for ${where}:`];
+
+  const cur = d.current;
+  if (cur?.temperature_2m != null) {
+    const desc = cur.weather_code != null ? `, ${wmoCodeToText(cur.weather_code)}` : "";
+    const parts = [`${Math.round(cur.temperature_2m)}${tUnit}${desc}`];
+    if (cur.apparent_temperature != null) parts.push(`feels like ${Math.round(cur.apparent_temperature)}${tUnit}`);
+    if (cur.relative_humidity_2m != null) parts.push(`humidity ${Math.round(cur.relative_humidity_2m)}%`);
+    if (cur.wind_speed_10m != null) parts.push(`wind ${Math.round(cur.wind_speed_10m)} ${wUnit}`);
+    lines.push(`Now: ${parts.join(", ")}.`);
+  }
+
+  const daily = d.daily;
+  if (daily?.time?.length) {
+    lines.push("");
+    lines.push("Forecast:");
+    for (let i = 0; i < daily.time.length; i++) {
+      const code = daily.weather_code?.[i];
+      const hi = daily.temperature_2m_max?.[i];
+      const lo = daily.temperature_2m_min?.[i];
+      const pop = daily.precipitation_probability_max?.[i];
+      const desc = code != null ? wmoCodeToText(code) : "";
+      const range = hi != null && lo != null ? `${Math.round(lo)}–${Math.round(hi)}${tUnit}` : "";
+      const rain = pop != null ? `, precip ${pop}%` : "";
+      lines.push(`- ${daily.time[i]}: ${[range, desc].filter(Boolean).join(", ")}${rain}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+async function geocode(name: string, signal: AbortSignal | undefined): Promise<GeoPlace | undefined> {
+  const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(name)}&count=1&language=en&format=json`;
+  const res = await httpText(url, { signal });
+  if (!res.ok) return undefined;
+  const json = JSON.parse(res.text) as { results?: GeoPlace[] };
+  return json.results?.[0];
+}
+
+// ---- web_search providers --------------------------------------------
+
+async function searchTavily(query: string, count: number, signal: AbortSignal | undefined, apiKey: string): Promise<SearchResult[]> {
+  const res = await httpText("https://api.tavily.com/search", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ api_key: apiKey, query, max_results: count, search_depth: "basic" }),
+    signal,
+  });
+  if (!res.ok) throw new Error(`Tavily returned HTTP ${res.status}`);
+  const json = JSON.parse(res.text) as { results?: Array<{ title?: string; url?: string; content?: string }> };
+  return (json.results ?? []).slice(0, count).map((r) => ({ title: r.title ?? r.url ?? "", url: r.url ?? "", snippet: r.content ?? "" }));
+}
+
+async function searchBrave(query: string, count: number, signal: AbortSignal | undefined, apiKey: string): Promise<SearchResult[]> {
+  const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;
+  const res = await httpText(url, { headers: { "x-subscription-token": apiKey, accept: "application/json" }, signal });
+  if (!res.ok) throw new Error(`Brave returned HTTP ${res.status}`);
+  const json = JSON.parse(res.text) as { web?: { results?: Array<{ title?: string; url?: string; description?: string }> } };
+  return (json.web?.results ?? []).slice(0, count).map((r) => ({ title: r.title ?? r.url ?? "", url: r.url ?? "", snippet: stripTags(r.description ?? "") }));
+}
+
+async function searchDuckDuckGo(query: string, count: number, signal: AbortSignal | undefined): Promise<SearchResult[]> {
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+  const res = await httpText(url, { headers: { accept: "text/html" }, signal });
+  if (!res.ok) throw new Error(`DuckDuckGo returned HTTP ${res.status}`);
+  return parseDuckDuckGoHtml(res.text, count);
+}
+
+/** Pick the search backend from env; returns the provider label too. */
+function resolveSearchProvider(): { name: string; run: (q: string, n: number, s: AbortSignal | undefined) => Promise<SearchResult[]> } {
+  const tavily = process.env.TAVILY_API_KEY;
+  if (tavily) return { name: "Tavily", run: (q, n, s) => searchTavily(q, n, s, tavily) };
+  const brave = process.env.BRAVE_API_KEY;
+  if (brave) return { name: "Brave", run: (q, n, s) => searchBrave(q, n, s, brave) };
+  return { name: "DuckDuckGo", run: searchDuckDuckGo };
+}
+
+// ---- tool definitions ------------------------------------------------
+
+function textResult(text: string): { content: [{ type: "text"; text: string }]; details: Record<string, never> } {
+  return { content: [{ type: "text", text }], details: {} };
+}
+
+const webSearchTool = defineTool({
+  name: "web_search",
+  label: "Web Search",
+  description:
+    "Search the web for current, real-world information (news, facts, docs, anything that changes over time or that you don't already know). " +
+    "Returns a ranked list of result titles, URLs, and snippets. Follow up with web_fetch to read a result in full.",
+  parameters: Type.Object({
+    query: Type.String({ description: "The search query." }),
+    count: Type.Optional(Type.Number({ description: `Number of results to return (default ${DEFAULT_SEARCH_RESULTS}, max ${MAX_SEARCH_RESULTS}).` })),
+  }),
+  execute: async (_id, params, signal) => {
+    const query = params.query.trim();
+    if (!query) return textResult("web_search needs a non-empty query.");
+    const count = Math.max(1, Math.min(MAX_SEARCH_RESULTS, Math.round(params.count ?? DEFAULT_SEARCH_RESULTS)));
+    const provider = resolveSearchProvider();
+    try {
+      const results = await provider.run(query, count, signal);
+      if (results.length === 0 && provider.name === "DuckDuckGo") {
+        return textResult(
+          `No results for "${query}". DuckDuckGo (the keyless default) may be rate-limiting; ` +
+            `set TAVILY_API_KEY or BRAVE_API_KEY for a reliable search backend.`,
+        );
+      }
+      return textResult(formatSearchResults(query, results, provider.name));
+    } catch (err) {
+      return textResult(`Web search failed (${provider.name}): ${describeFetchError(err)}`);
+    }
+  },
+});
+
+const webFetchTool = defineTool({
+  name: "web_fetch",
+  label: "Fetch URL",
+  description:
+    "Fetch a URL and return its contents as readable text (HTML pages are stripped to plain text). " +
+    "Use this to read a web page, article, or API/JSON endpoint — e.g. after web_search, or when the user gives you a link.",
+  parameters: Type.Object({
+    url: Type.String({ description: "The absolute http(s) URL to fetch." }),
+  }),
+  execute: async (_id, params, signal) => {
+    let url = params.url.trim();
+    if (!/^https?:\/\//i.test(url)) url = "https://" + url;
+    try {
+      const res = await httpText(url, { headers: { accept: "text/html,application/json,text/plain,*/*" }, signal });
+      const header = `Fetched ${res.finalUrl} (HTTP ${res.status})`;
+      if (!res.ok) return textResult(`${header}\n\n${truncate(htmlToText(res.text), 2_000)}`);
+      const isHtml = /text\/html|application\/xhtml/i.test(res.contentType);
+      if (isHtml) {
+        const title = extractTitle(res.text);
+        const body = truncate(htmlToText(res.text), MAX_FETCH_CHARS);
+        return textResult(`${header}${title ? `\nTitle: ${title}` : ""}\n\n${body}`);
+      }
+      const isTextual = /text\/|application\/(json|xml|javascript|x-ndjson)|\+json|\+xml/i.test(res.contentType) || res.contentType === "";
+      if (!isTextual) {
+        return textResult(`${header}\n\nContent-Type ${res.contentType || "unknown"} is not text; not displaying ${res.text.length} bytes of binary data.`);
+      }
+      return textResult(`${header}\n\n${truncate(res.text, MAX_FETCH_CHARS)}`);
+    } catch (err) {
+      return textResult(`Failed to fetch ${url}: ${describeFetchError(err)}`);
+    }
+  },
+});
+
+const weatherTool = defineTool({
+  name: "weather",
+  label: "Weather",
+  description:
+    "Get current weather conditions and a short forecast for a place. Accepts a city/place name (e.g. 'Austin', 'Paris, France', 'Tokyo'). " +
+    "No API key required.",
+  parameters: Type.Object({
+    location: Type.String({ description: "City or place name to look up." }),
+    unit: Type.Optional(Type.String({ description: "Temperature unit: 'celsius' or 'fahrenheit' (default celsius)." })),
+  }),
+  execute: async (_id, params, signal) => {
+    const location = params.location.trim();
+    if (!location) return textResult("weather needs a location.");
+    const fahrenheit = params.unit === "fahrenheit";
+    try {
+      const place = await geocode(location, signal);
+      if (!place) return textResult(`Couldn't find a place named "${location}".`);
+      const params2 = new URLSearchParams({
+        latitude: String(place.latitude),
+        longitude: String(place.longitude),
+        current: "temperature_2m,relative_humidity_2m,apparent_temperature,precipitation,weather_code,wind_speed_10m",
+        daily: "weather_code,temperature_2m_max,temperature_2m_min,precipitation_probability_max",
+        timezone: "auto",
+        forecast_days: "3",
+      });
+      if (fahrenheit) {
+        params2.set("temperature_unit", "fahrenheit");
+        params2.set("wind_speed_unit", "mph");
+      }
+      const res = await httpText(`https://api.open-meteo.com/v1/forecast?${params2.toString()}`, { signal });
+      if (!res.ok) return textResult(`Weather lookup failed: Open-Meteo returned HTTP ${res.status}.`);
+      return textResult(formatWeather(place, JSON.parse(res.text), fahrenheit));
+    } catch (err) {
+      return textResult(`Weather lookup failed: ${describeFetchError(err)}`);
+    }
+  },
+});
+
+/** All web tools, ready to pass to createAgentSession({ customTools }). */
+export function createWebTools(): ToolDefinition[] {
+  return [webSearchTool, webFetchTool, weatherTool];
+}

package/src/weights.ts

@@ -0,0 +1,91 @@
+// Weights: model directory → lazy mlx arrays.
+//
+// Tensor data goes through mlx's native safetensors loader
+// (mlx_load_safetensors): opening is milliseconds, and each tensor's bytes
+// are read into an mlx-owned (page-aligned, Metal-visible) buffer only
+// when first evaluated — the same lazy semantics as Python's mx.load.
+//
+// Why not wrap our own mmap pointers? Verified in Phase 1: GPU ops on
+// externally-wrapped buffers read garbage unless the pointer is
+// page-aligned, and safetensors tensor offsets are arbitrary (not even
+// element-aligned). CPU-stream ops on wrapped pointers are correct, but
+// the weights' consumers are GPU kernels. See PLAN.md Phase 1 findings.
+//
+// The JS-side parser (ShardedSafetensors) stays as the metadata source:
+// names, shapes, dtypes, byte sizes — for the registry, fit reports, and
+// validation — without touching tensor bytes.
+
+import { ptr, read } from "bun:ffi";
+import { ShardedSafetensors, type TensorInfo } from "./safetensors";
+import { MlxArray, cpuStream } from "./mlx/array";
+import { C } from "./mlx/ffi";
+
+const cstr = (s: string) => Buffer.from(s + "\0", "utf8");
+
+export class Weights {
+  readonly shards: ShardedSafetensors;
+  /** shard filename → native mlx map handle (string → lazy array). */
+  readonly #maps = new Map<string, bigint>();
+  readonly #arrays = new Map<string, MlxArray>();
+
+  private constructor(shards: ShardedSafetensors) {
+    this.shards = shards;
+  }
+
+  static async open(modelDir: string): Promise<Weights> {
+    const self = new Weights(await ShardedSafetensors.open(modelDir));
+    for (const [file, sf] of self.shards.files) {
+      // out-param slots read back via read.u64, not [0] (DFG stale-read
+      // bug — see outArray in mlx/ffi.ts). Cold path, but the rule is
+      // uniform: native wrote it, read.* reads it.
+      const arrMap = new BigUint64Array([C.mlx_map_string_to_array_new()]);
+      const metaMap = new BigUint64Array([C.mlx_map_string_to_string_new()]);
+      const arrMapPtr = ptr(arrMap);
+      const metaMapPtr = ptr(metaMap);
+      const status = C.mlx_load_safetensors(
+        arrMapPtr, metaMapPtr, ptr(cstr(sf.path)), cpuStream,
+      );
+      C.mlx_map_string_to_string_free(read.u64(metaMapPtr, 0));
+      if (status !== 0) throw new Error(`mlx_load_safetensors(${sf.path}) failed`);
+      self.#maps.set(file, read.u64(arrMapPtr, 0));
+    }
+    return self;
+  }
+
+  get tensorNames(): string[] {
+    return this.shards.tensorNames;
+  }
+
+  info(name: string): TensorInfo {
+    return this.shards.info(name);
+  }
+
+  has(name: string): boolean {
+    return this.shards.tensorToFile.has(name);
+  }
+
+  /** Lazy mlx array for a tensor; cached per name. */
+  tensor(name: string): MlxArray {
+    let arr = this.#arrays.get(name);
+    if (!arr) {
+      const sf = this.shards.tensorToFile.get(name);
+      if (!sf) throw new Error(`no tensor named ${name}`);
+      const mapHandle = [...this.#maps.entries()]
+        .find(([file]) => this.shards.files.get(file) === sf)![1];
+      const slot = new BigUint64Array([C.mlx_array_new()]);
+      const slotPtr = ptr(slot);
+      if (C.mlx_map_string_to_array_get(slotPtr, mapHandle, ptr(cstr(name))) !== 0)
+        throw new Error(`tensor ${name} missing from native map`);
+      arr = new MlxArray(read.u64(slotPtr, 0));
+      this.#arrays.set(name, arr);
+    }
+    return arr;
+  }
+
+  dispose(): void {
+    for (const arr of this.#arrays.values()) arr.dispose();
+    this.#arrays.clear();
+    for (const map of this.#maps.values()) C.mlx_map_string_to_array_free(map);
+    this.#maps.clear();
+  }
+}