@chatpanel/bridge 0.10.26 → 0.10.28

package/src/server.js

@@ -11,6 +11,12 @@
 //                     {type:'status'|'reasoning', text?}
 //                     {type:'done',  text?}    (text only if not streamed)
 //                     {type:'error', error}
+//   POST /v1/chat/completions, /v1/completions, /v1/responses
+//                 → OpenAI-compatible text adapters for the local agents
+//   POST /v1/messages → Anthropic-compatible text adapter for the local agents
+//   GET  /skills              → skill packages on disk (name + description + files)
+//   GET  /skills/<name>       → one skill, SKILL.md body included
+//   GET  /skills/<name>/file/<path> → one reference/template/asset from that package
 //
 // Binds to 127.0.0.1 only. A request guard (see `guard()`) enforces a loopback
 // Host (anti DNS-rebinding) and an allowlisted Origin; the command-spawning
@@ -30,17 +36,35 @@ import { pi, opencode, kiro, copilot, deepseek } from './engines/cli-agents.js';
 import { connectorsFor } from './connectors.js';
 import * as custom from './engines/custom.js';
 import { installService, uninstallService, serviceStatus, restartService } from './service.js';
+import { skillIndex, listRecords, readRecord, readPackageFile, skillsHealth } from './skills.js';
 import { AGENT_CLIS, enrichPath, enrichAgentEnv, findAgentBin, resolveCommand } from './env.js';
 import { stripHidden } from './sanitize.js';
 import { checkForUpdate, selfUpdate } from './update.js';
 import { callLocalMcp } from './mcp-local.js';
 import { assertPublicHttpUrl, assertPublicWebUrl } from './ssrf.js';
 import { startRun, endRun, cancelRun, cancelAll, activeRuns } from './runs.js';
+import {
+  CompatError,
+  anthropicError,
+  anthropicStream,
+  chatCompletionStream,
+  completionStream,
+  createAnthropicMessage,
+  createChatCompletion,
+  createCompletion,
+  createResponse,
+  openAIError,
+  parseAnthropicMessage,
+  parseChatCompletion,
+  parseCompletion,
+  parseResponse,
+  responseStream,
+} from './api-compat.js';
 
 // Hardcoded (not read from package.json) so it survives Bun's single-file
 // --compile, where package.json isn't on a readable FS. CI fails the publish if
 // this drifts from package.json, so the two can't silently diverge.
-const VERSION = '0.10.26';
+const VERSION = '0.10.28';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -163,7 +187,7 @@ function cors(req, res) {
   const allow = originAllowed(origin);
   res.setHeader('Access-Control-Allow-Origin', allow ? origin || '*' : 'null');
   res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-ChatPanel-Token');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Api-Key, Anthropic-Version, X-ChatPanel-Token');
   res.setHeader('Vary', 'Origin');
 }
 
@@ -219,7 +243,9 @@ function ensureToken() {
 function tokenOk(req) {
   if (!AUTH_TOKEN) return false;
   const h = String(req.headers['authorization'] || '');
-  const provided = (h.startsWith('Bearer ') ? h.slice(7) : String(req.headers['x-chatpanel-token'] || '')).trim();
+  const provided = (h.startsWith('Bearer ')
+    ? h.slice(7)
+    : String(req.headers['x-api-key'] || req.headers['x-chatpanel-token'] || '')).trim();
   if (!provided) return false;
   const a = Buffer.from(provided);
   const b = Buffer.from(AUTH_TOKEN);
@@ -232,6 +258,10 @@ function tokenOk(req) {
 // local coding-agent CLIs connect to them with no Origin header by design.
 const PRIVILEGED_POST = new Set([
   '/chat',
+  '/v1/chat/completions',
+  '/v1/completions',
+  '/v1/responses',
+  '/v1/messages',
   '/mcp-local',
   '/mcp-remote',
   '/fetch-title',
@@ -247,6 +277,28 @@ const PRIVILEGED_POST = new Set([
 ]);
 const PRIVILEGED_GET = new Set(['/debug']);
 
+// /skills* is NOT privileged, and that is a considered position rather than a
+// convenience. `privileged` adds exactly one thing over the origin allowlist: it requires
+// the Origin header to be PRESENT, so a no-Origin local process cannot pose as the
+// extension. Work through who that actually excludes for a read-only listing of files:
+//
+//   • a web page — always sends Origin, and a non-allowed one is already refused above;
+//   • a page on http://localhost — sends Origin, which `isExtensionOrigin` already
+//     accepts, so the privileged check never stopped it either way;
+//   • a page using <img>/<script> to force a no-Origin GET — cannot read the response,
+//     because it is JSON with no CORS grant to that origin;
+//   • remote SSRF into 127.0.0.1 — arrives with a non-loopback Host and dies at
+//     `hostAllowed` long before this;
+//   • a local process — the only caller left, and it can read the very same SKILL.md
+//     files straight off the disk.
+//
+// So the requirement excluded nothing that could not already read the bytes, while
+// breaking the one client that should have them: Chrome omits Origin on a simple GET from
+// an extension page (the POST routes get it only because a JSON body forces a preflight).
+// The origin allowlist stays and is what keeps web pages out. /debug remains privileged —
+// it exposes configuration a local process cannot otherwise see.
+const isPrivilegedGetPath = (p) => PRIVILEGED_GET.has(p);
+
 // SSRF guard for /mcp-remote lives in ./ssrf.js (assertPublicHttpUrl). Loopback
 // is allowed (the user's own localhost MCP server — the common "via bridge"
 // case; the extension can reach it directly anyway), cloud metadata is always
@@ -261,7 +313,7 @@ function guard(req, pathname) {
   if (origin && !originAllowed(origin)) return 'forbidden origin';
   const privileged =
     (req.method === 'POST' && PRIVILEGED_POST.has(pathname)) ||
-    (req.method === 'GET' && PRIVILEGED_GET.has(pathname));
+    (req.method === 'GET' && isPrivilegedGetPath(pathname));
   if (privileged && !(isExtensionOrigin(origin) || tokenOk(req))) {
     return 'forbidden: this endpoint requires the ChatPanel extension or a valid bridge token';
   }
@@ -310,7 +362,65 @@ async function handleHealth(res) {
       }),
   );
   const update = await checkForUpdate(VERSION).catch(() => ({ current: VERSION, updateAvailable: false }));
-  json(res, 200, { ok: true, version: VERSION, agents, update });
+  // ADDITIVE, and the client's only way to know this bridge can host skill packages —
+  // an older bridge simply omits it, which is what stops a newer extension assuming the
+  // endpoints exist. Never let a scan failure cost the caller its health check.
+  const skills = await skillsHealth().catch(() => null);
+  json(res, 200, { ok: true, version: VERSION, agents, update, ...(skills ? { skills } : {}) });
+}
+
+// --------------------------------------------------------------------------
+// Skill packages (F6 S2). Read-only: the store serves what is already on disk.
+// Installing FROM a hub waits for the scanner — a write endpoint that lands before
+// the gate is a window in which unscanned packages can be written, and windows like
+// that do not close on schedule.
+//
+// The three routes are the progressive-disclosure ladder, so a client pays for a
+// skill's body only when it picks one, and for a reference file only when it needs it.
+// --------------------------------------------------------------------------
+async function handleSkillsList(res) {
+  const { index, problems } = await skillIndex();
+  json(res, 200, { ok: true, skills: listRecords(index), problems });
+}
+
+async function handleSkillRead(res, name) {
+  const { index } = await skillIndex();
+  const skill = readRecord(index, name);
+  if (!skill) return json(res, 404, { ok: false, error: 'unknown skill' });
+  json(res, 200, { ok: true, skill });
+}
+
+async function handleSkillFile(res, name, relPath) {
+  const { index } = await skillIndex();
+  const out = await readPackageFile(index, name, relPath);
+  // One shape for every refusal: a caller learns that it may not have the file, not
+  // whether the path exists, which is the difference between an error and an oracle.
+  if (out.error) return json(res, out.error === 'unknown skill' ? 404 : 400, { ok: false, error: out.error });
+  json(res, 200, { ok: true, ...out });
+}
+
+async function compatibleModels() {
+  const rows = await Promise.all(
+    Object.entries(ENGINES)
+      .filter(([, entry]) => !entry.hidden)
+      .map(async ([id, entry]) => ({
+        id,
+        object: 'model',
+        created: 0,
+        owned_by: 'chatpanel',
+        available: !!(await entry.engine.available().catch(() => ({ ok: false }))).ok,
+      })),
+  );
+  return rows.filter((row) => row.available).map(({ available, ...row }) => row);
+}
+
+async function handleCompatibleModels(res, modelId = '') {
+  const models = await compatibleModels();
+  if (modelId) {
+    const model = models.find((row) => row.id === modelId);
+    return model ? json(res, 200, model) : json(res, 404, openAIError(new CompatError(`Model "${modelId}" not found`, 404, 'model')));
+  }
+  return json(res, 200, { object: 'list', data: models });
 }
 
 // POST /update — self-update (compiled-binary installs). Swaps the binary, replies,
@@ -404,6 +514,162 @@ async function handleChat(req, res) {
   }
 }
 
+async function runCompatibleAgent(config, onDelta, res) {
+  const target = ENGINES[config.agent];
+  if (!target || target.hidden) throw new CompatError(`Unknown ChatPanel agent "${config.agent}"`, 400, 'model');
+  const availability = await target.engine.available().catch((e) => ({ ok: false, reason: e?.message || String(e) }));
+  if (!availability.ok) throw new CompatError(availability.reason || `${config.agent} is unavailable`, 503, 'model');
+
+  const runId = `run_${Math.random().toString(36).slice(2, 10)}`;
+  const run = startRun(runId);
+  const onGone = () => run.cancel('disconnected');
+  res.on('close', onGone);
+  let output = '';
+  try {
+    await target.engine.chat(
+      { messages: config.messages, system: config.system, options: config.options, images: [] },
+      (event) => {
+        if (event?.type === 'delta' && event.text) {
+          output += event.text;
+          onDelta(event.text);
+        } else if (event?.type === 'done' && event.text && !output) {
+          output = event.text;
+          onDelta(event.text);
+        }
+      },
+      { signal: run.signal },
+    );
+    return output;
+  } finally {
+    res.off('close', onGone);
+    endRun(runId);
+  }
+}
+
+function beginSse(res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  });
+}
+
+function writeData(res, value) {
+  if (!res.writableEnded) res.write(`data: ${typeof value === 'string' ? value : JSON.stringify(value)}\n\n`);
+}
+
+function writeNamedEvent(res, name, value) {
+  if (!res.writableEnded) res.write(`event: ${name}\ndata: ${JSON.stringify(value)}\n\n`);
+}
+
+async function compatibleBody(req, res, parser, errorShape) {
+  try {
+    return parser(await readBody(req));
+  } catch (error) {
+    json(res, error?.status || 400, errorShape(error?.message?.startsWith('Unexpected') ? new CompatError(`Bad JSON: ${error.message}`) : error));
+    return null;
+  }
+}
+
+async function handleOpenAIChatCompletions(req, res) {
+  const config = await compatibleBody(req, res, parseChatCompletion, openAIError);
+  if (!config) return;
+  if (!config.stream) {
+    try {
+      const text = await runCompatibleAgent(config, () => {}, res);
+      return json(res, 200, createChatCompletion(config.requestedModel, text));
+    } catch (error) {
+      if (!res.writableEnded) return json(res, error?.status || 500, openAIError(error));
+      return;
+    }
+  }
+
+  beginSse(res);
+  const stream = chatCompletionStream(config.requestedModel, (event) => writeData(res, event));
+  try {
+    await runCompatibleAgent(config, (text) => stream.delta(text), res);
+    stream.done();
+  } catch (error) {
+    writeData(res, openAIError(error));
+  }
+  writeData(res, '[DONE]');
+  res.end();
+}
+
+async function handleOpenAICompletions(req, res) {
+  const config = await compatibleBody(req, res, parseCompletion, openAIError);
+  if (!config) return;
+  if (!config.stream) {
+    try {
+      const text = await runCompatibleAgent(config, () => {}, res);
+      return json(res, 200, createCompletion(config.requestedModel, text));
+    } catch (error) {
+      if (!res.writableEnded) return json(res, error?.status || 500, openAIError(error));
+      return;
+    }
+  }
+
+  beginSse(res);
+  const stream = completionStream(config.requestedModel, (event) => writeData(res, event));
+  try {
+    await runCompatibleAgent(config, (text) => stream.delta(text), res);
+    stream.done();
+  } catch (error) {
+    writeData(res, openAIError(error));
+  }
+  writeData(res, '[DONE]');
+  res.end();
+}
+
+async function handleOpenAIResponses(req, res) {
+  const config = await compatibleBody(req, res, parseResponse, openAIError);
+  if (!config) return;
+  if (!config.stream) {
+    try {
+      const text = await runCompatibleAgent(config, () => {}, res);
+      return json(res, 200, createResponse(config.requestedModel, text));
+    } catch (error) {
+      if (!res.writableEnded) return json(res, error?.status || 500, openAIError(error));
+      return;
+    }
+  }
+
+  beginSse(res);
+  const stream = responseStream(config.requestedModel, (event) => writeNamedEvent(res, event.type, event));
+  try {
+    await runCompatibleAgent(config, (text) => stream.delta(text), res);
+    stream.done();
+  } catch (error) {
+    const event = { type: 'error', sequence_number: 0, ...openAIError(error) };
+    writeNamedEvent(res, 'error', event);
+  }
+  res.end();
+}
+
+async function handleAnthropicMessages(req, res) {
+  const config = await compatibleBody(req, res, parseAnthropicMessage, anthropicError);
+  if (!config) return;
+  if (!config.stream) {
+    try {
+      const text = await runCompatibleAgent(config, () => {}, res);
+      return json(res, 200, createAnthropicMessage(config.requestedModel, text));
+    } catch (error) {
+      if (!res.writableEnded) return json(res, error?.status || 500, anthropicError(error));
+      return;
+    }
+  }
+
+  beginSse(res);
+  const stream = anthropicStream(config.requestedModel, (name, event) => writeNamedEvent(res, name, event));
+  try {
+    await runCompatibleAgent(config, (text) => stream.delta(text), res);
+    stream.done();
+  } catch (error) {
+    writeNamedEvent(res, 'error', anthropicError(error));
+  }
+  res.end();
+}
+
 /**
  * POST /cancel { id } — stop a run by name.
  *
@@ -772,6 +1038,21 @@ const server = createServer(async (req, res) => {
   if (blocked) return json(res, 403, { error: blocked });
   try {
     if (req.method === 'GET' && url.pathname === '/health') return handleHealth(res);
+    if (req.method === 'GET' && url.pathname === '/skills') return handleSkillsList(res);
+    if (req.method === 'GET' && url.pathname.startsWith('/skills/')) {
+      const rest = url.pathname.slice('/skills/'.length);
+      const cut = rest.indexOf('/file/');
+      if (cut === -1) return handleSkillRead(res, decodeURIComponent(rest));
+      return handleSkillFile(
+        res,
+        decodeURIComponent(rest.slice(0, cut)),
+        decodeURIComponent(rest.slice(cut + '/file/'.length)),
+      );
+    }
+    if (req.method === 'GET' && url.pathname === '/v1/models') return handleCompatibleModels(res);
+    if (req.method === 'GET' && url.pathname.startsWith('/v1/models/')) {
+      return handleCompatibleModels(res, decodeURIComponent(url.pathname.slice('/v1/models/'.length)));
+    }
     if (req.method === 'GET' && url.pathname === '/debug') {
       // L6: by default expose only version + agent AVAILABILITY (a boolean) — enough
       // to diagnose "is codex installed?". The full home dir, $PATH, and resolved
@@ -786,6 +1067,10 @@ const server = createServer(async (req, res) => {
       });
     }
     if (req.method === 'POST' && url.pathname === '/chat') return handleChat(req, res);
+    if (req.method === 'POST' && url.pathname === '/v1/chat/completions') return handleOpenAIChatCompletions(req, res);
+    if (req.method === 'POST' && url.pathname === '/v1/completions') return handleOpenAICompletions(req, res);
+    if (req.method === 'POST' && url.pathname === '/v1/responses') return handleOpenAIResponses(req, res);
+    if (req.method === 'POST' && url.pathname === '/v1/messages') return handleAnthropicMessages(req, res);
     // Stable endpoint: routes to the active chat. For CLIs configured once with a
     // fixed URL (e.g. `opencode mcp add chatpanel --url http://127.0.0.1:4319/mcp`).
     if (url.pathname === '/mcp') {

package/src/skills.js

@@ -0,0 +1,297 @@
+// skills.js — the skill package store.
+//
+// A ChatPanel skill has been a prompt in the extension's settings, which is fine until a
+// skill wants to carry the things the agentskills.io format carries: reference documents
+// loaded only when needed, templates, and scripts. None of those can live in a browser
+// extension — it has no filesystem, and running someone else's script inside it is on the
+// Never list. They live here.
+//
+// So the bridge becomes a skill HOST, not a skill consumer. It scans directories, parses
+// each SKILL.md into the shared record, and serves three levels on demand — the
+// progressive-disclosure ladder the format is built around:
+//
+//   list()               name + description + what files exist        (cheap, every turn)
+//   read(name)           the full SKILL.md body                       (when it is chosen)
+//   readFile(name, p)    one reference/asset                          (when it is needed)
+//
+// It also scans ~/.agents/skills — the cross-tool convention several agent CLIs already
+// use — so a skill written in another tool appears here with no export step. That is the
+// point of putting the store in the bridge rather than in one client.
+//
+// ── SECURITY ──────────────────────────────────────────────────────────────────────────
+// This module turns HTTP request strings into filesystem reads, which makes it the most
+// dangerous file in the repo. Three rules, none of them optional:
+//
+//   1. A REQUESTED NAME IS NEVER A PATH. `read('../../.ssh/id_rsa')` resolves the name
+//      against the scanned INDEX; a name that is not in the index does not exist. There
+//      is no code path from a URL segment to a path join.
+//   2. A REQUESTED FILE PATH IS CHECKED TWICE — lexically (the shared `isSafeSkillPath`,
+//      which refuses traversal, absolute paths, drive letters, backslashes and control
+//      characters) and then again after resolution, because a SYMLINK inside a skill
+//      directory passes every lexical check and still points at ~/.ssh.
+//   3. EVERY READ IS CAPPED. A skill directory is not necessarily authored by the person
+//      running it, and an unbounded read of a file someone else chose is a denial of
+//      service against the process the browser depends on.
+
+import { readFile as fsReadFile, readdir, stat, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import { join, resolve, sep } from 'node:path';
+import { isSafeSkillPath, normalizeSkill, SKILL_FILE_KINDS } from './events/skill-manifest.js';
+
+const MAX_SKILL_MD = 512 * 1024;   // a procedure document, not a corpus
+const MAX_ASSET = 4 * 1024 * 1024; // a reference doc or a template; images live elsewhere
+const MAX_SKILLS = 500;            // a scan is bounded work, not "whatever is on disk"
+const MAX_DEPTH = 2;               // <root>/<name>/ and <root>/<category>/<name>/
+
+/**
+ * Where skills are scanned from, in precedence order — first hit wins on a name clash,
+ * which makes ChatPanel's own directory authoritative over a shared one.
+ *
+ * `~/.agents/skills` is the cross-tool location; it is READ, never written, because it
+ * belongs to whatever else the user runs.
+ */
+export function skillRoots(env = process.env, home = os.homedir()) {
+  const extra = String(env.CHATPANEL_SKILL_DIRS || '')
+    .split(/[:;\n]/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return [
+    { dir: join(home, '.chatpanel', 'skills'), source: 'local', writable: true },
+    { dir: join(home, '.agents', 'skills'), source: 'agents-dir', writable: false },
+    ...extra.map((dir) => ({ dir: resolve(dir), source: 'external', writable: false })),
+  ];
+}
+
+/**
+ * The YAML subset a SKILL.md frontmatter block actually uses: scalars, inline `[a, b]`
+ * lists, and one level of nesting. Deliberately NOT a YAML parser — a real one is a
+ * dependency the bridge does not take, and a full parser is a larger attack surface than
+ * the five fields we read. Anything it does not understand is ignored, never guessed at.
+ */
+export function parseFrontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(String(text || ''));
+  if (!m) return { meta: {}, body: String(text || '') };
+  const out = {};
+  const stack = [{ indent: -1, obj: out }];
+  for (const raw of m[1].split(/\r?\n/)) {
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+    const indent = raw.length - raw.trimStart().length;
+    const line = raw.trim();
+    const kv = /^([A-Za-z_][\w.-]*)\s*:\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    const parent = stack[stack.length - 1].obj;
+    const [, key, rest] = kv;
+    if (rest === '') {
+      const child = {};
+      parent[key] = child;
+      stack.push({ indent, obj: child });
+      continue;
+    }
+    parent[key] = scalar(rest);
+  }
+  return { meta: out, body: String(text).slice(m[0].length) };
+}
+
+function scalar(v) {
+  const s = v.trim().replace(/\s+#.*$/, '').trim();
+  if (/^\[.*\]$/.test(s)) {
+    return s.slice(1, -1).split(',').map((x) => unquote(x.trim())).filter(Boolean);
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  return unquote(s);
+}
+
+const unquote = (s) => (/^(['"]).*\1$/.test(s) ? s.slice(1, -1) : s);
+
+/** A directory name usable as a skill id when the frontmatter has no `name`. */
+const ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * Turn a parsed SKILL.md plus its directory listing into the shared record.
+ *
+ * Local skills carry an ORIGIN, and therefore read as `community` rather than `user`.
+ * That is deliberate and it is the conservative answer: we cannot tell a skill the user
+ * wrote from one that arrived in a synced or checked-out directory, and treating the
+ * second as trusted is exactly the mistake. Only skills authored in ChatPanel itself are
+ * the user's own.
+ */
+export function skillRecord({ meta, body, dirName, relPath, source, files, hash }) {
+  const name = typeof meta.name === 'string' && meta.name.trim() ? meta.name.trim() : dirName;
+  const id = ID.test(String(name)) ? String(name) : dirName;
+  const grouped = {};
+  for (const kind of SKILL_FILE_KINDS) {
+    const list = files.filter((f) => f.startsWith(`${kind}/`)).map((f) => f.slice(kind.length + 1));
+    if (list.length) grouped[kind] = list;
+  }
+  return normalizeSkill({
+    id,
+    name: String(name),
+    command: ID.test(id) ? id : '',
+    description: typeof meta.description === 'string' ? meta.description : '',
+    prompt: body.trim(),
+    ...(typeof meta.version === 'string' ? { version: meta.version } : {}),
+    ...(Array.isArray(meta.platforms) ? { platforms: meta.platforms } : {}),
+    ...(Object.keys(grouped).length ? { files: grouped } : {}),
+    origin: { source, id: relPath, hash },
+  });
+}
+
+/** Does this skill run on the machine we are on? */
+export function platformOk(skill, platform = process.platform) {
+  const want = skill?.platforms;
+  if (!Array.isArray(want) || !want.length) return true;
+  const here = platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : 'linux';
+  return want.includes(here);
+}
+
+async function listDir(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return []; // a root that does not exist is not an error — most machines have neither
+  }
+}
+
+/** Files a package carries, relative to its directory, capped and traversal-checked. */
+async function packageFiles(dir) {
+  const out = [];
+  for (const kind of SKILL_FILE_KINDS) {
+    for (const entry of await listDir(join(dir, kind))) {
+      if (!entry.isFile()) continue; // no recursion, and never a symlink or a device
+      const rel = `${kind}/${entry.name}`;
+      if (isSafeSkillPath(rel)) out.push(rel);
+      if (out.length >= 200) return out;
+    }
+  }
+  return out;
+}
+
+async function loadSkill(dir, relPath, source) {
+  let text;
+  try {
+    const st = await stat(join(dir, 'SKILL.md'));
+    if (!st.isFile() || st.size > MAX_SKILL_MD) return null;
+    text = await fsReadFile(join(dir, 'SKILL.md'), 'utf8');
+  } catch {
+    return null;
+  }
+  const { meta, body } = parseFrontmatter(text);
+  const hash = `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 32)}`;
+  const dirName = relPath.split('/').pop();
+  const files = await packageFiles(dir);
+  const skill = skillRecord({ meta, body, dirName, relPath, source, files, hash });
+  return { skill, dir };
+}
+
+/**
+ * Scan every root. Returns an INDEX keyed by id — and that index is the only thing a
+ * later read may resolve a requested name against.
+ */
+export async function scanSkills({ roots = skillRoots(), platform = process.platform } = {}) {
+  const index = new Map();
+  const problems = [];
+  for (const { dir: root, source } of roots) {
+    const walk = async (dir, rel, depth) => {
+      if (index.size >= MAX_SKILLS || depth > MAX_DEPTH) return;
+      for (const entry of await listDir(dir)) {
+        if (index.size >= MAX_SKILLS) return;
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+        const child = join(dir, entry.name);
+        const loaded = await loadSkill(child, childRel, source).catch((e) => {
+          problems.push({ path: childRel, reason: String(e?.message || e) });
+          return null;
+        });
+        if (loaded) {
+          // First root wins: ChatPanel's own directory is authoritative over a shared one.
+          if (!index.has(loaded.skill.id) && platformOk(loaded.skill, platform)) {
+            index.set(loaded.skill.id, { ...loaded, root, source });
+          }
+        } else {
+          await walk(child, childRel, depth + 1);
+        }
+      }
+    };
+    await walk(root, '', 1);
+  }
+  return { index, problems };
+}
+
+/** Level 0 — what exists, cheaply. No bodies. */
+export function listRecords(index) {
+  return [...index.values()].map(({ skill }) => {
+    const { prompt, ...rest } = skill;
+    return { ...rest, promptChars: (prompt || '').length };
+  });
+}
+
+/** Level 1 — one skill, body included. `name` is resolved against the index, never joined. */
+export function readRecord(index, name) {
+  const hit = index.get(String(name || ''));
+  return hit ? hit.skill : null;
+}
+
+/**
+ * Level 2 — one file inside a package.
+ *
+ * The lexical check happens first and the resolved-path containment check happens after,
+ * because they catch different things: the first stops `../`, the second stops a symlink
+ * that points outside the package while looking perfectly ordinary.
+ */
+export async function readPackageFile(index, name, relPath) {
+  const hit = index.get(String(name || ''));
+  if (!hit) return { error: 'unknown skill' };
+  if (!isSafeSkillPath(relPath)) return { error: 'unsafe path' };
+  const kind = String(relPath).split('/')[0];
+  if (!SKILL_FILE_KINDS.includes(kind)) return { error: 'unsafe path' };
+
+  const target = resolve(hit.dir, relPath);
+  let real;
+  try {
+    real = await realpath(target);
+  } catch {
+    return { error: 'not found' };
+  }
+  // A symlink passes every string check ever written. Compare what the filesystem
+  // actually resolved to against the package root, with a separator so `/skills-evil`
+  // cannot pass as a child of `/skills`.
+  const rootReal = await realpath(hit.dir).catch(() => hit.dir);
+  if (real !== rootReal && !real.startsWith(rootReal + sep)) return { error: 'outside package' };
+
+  const st = await stat(real).catch(() => null);
+  if (!st?.isFile()) return { error: 'not found' };
+  if (st.size > MAX_ASSET) return { error: 'file too large' };
+  return { path: relPath, text: await fsReadFile(real, 'utf8') };
+}
+
+/**
+ * A cached view, because /health and every turn ask "what skills exist" far more often
+ * than the directories change. Short TTL rather than a watcher: a watcher on directories
+ * that may not exist, across three roots, is more moving parts than a 5-second staleness
+ * window is worth.
+ */
+const CACHE_MS = 5000;
+let cached = null;
+
+export async function skillIndex({ force = false, now = Date.now } = {}) {
+  const t = now();
+  if (!force && cached && t - cached.at < CACHE_MS) return cached.value;
+  const value = await scanSkills();
+  cached = { at: t, value };
+  return value;
+}
+
+export function clearSkillCache() { cached = null; }
+
+/** The `/health` summary — counts and roots, never contents. */
+export async function skillsHealth() {
+  const { index, problems } = await skillIndex();
+  return {
+    count: index.size,
+    roots: skillRoots().filter((r) => [...index.values()].some((v) => v.root === r.dir)).map((r) => r.dir),
+    ...(problems.length ? { problems: problems.length } : {}),
+  };
+}