@chatpanel/bridge 0.10.27 → 0.10.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.10.27",
+  "version": "0.10.28",
   "type": "module",
   "description": "Local bridge that exposes the AI coding agents installed on your machine \u2014 Claude Code (CLI), Codex (CLI), and Antigravity CLI (formerly Gemini CLI, which remains available for business/enterprise) \u2014 to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [
@@ -36,7 +36,9 @@
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
     "test": "node --test tests/*.test.mjs",
-    "build:bin": "bash scripts/build-binaries.sh"
+    "build:bin": "bash scripts/build-binaries.sh",
+    "sync:events": "node scripts/sync-events.mjs",
+    "test:events-sync": "node scripts/sync-events.mjs --check"
   },
   "dependencies": {},
   "optionalDependencies": {

package/scripts/sync-events.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Vendors the shared contracts the bridge needs from `chatpanel-events`.
+//
+// The bridge has ZERO runtime dependencies on purpose — it is installed by a curl
+// one-liner and compiled into a single binary, and every dependency is a thing that can
+// fail at install time on someone's laptop. So shared contracts arrive the way
+// @chatpanel/pii does: copied in, generated, never hand-edited.
+//
+//   node scripts/sync-events.mjs           refresh src/events/ from the package
+//   node scripts/sync-events.mjs --check   verify they match (CI drift guard); exit 1 if not
+//
+// A hand-copy is how `sanitize.js` could silently diverge from the engine it came from.
+// This makes divergence a failing test instead of a bug report.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Deliberately short. `skill-manifest.js` imports only `scopes.js`, which is why that
+// vocabulary was split out of `capability.js` — vendoring the capability machinery and
+// the event schema to reach a five-element array would defeat the point.
+const FILES = ['scopes.js', 'skill-manifest.js'];
+
+function pkgDir() {
+  return [
+    join(ROOT, 'node_modules', '@chatpanel', 'events'),
+    join(ROOT, '..', 'chatpanel-events'),
+  ].find((d) => existsSync(join(d, 'skill-manifest.js')));
+}
+
+const check = process.argv.includes('--check');
+const src = pkgDir();
+
+if (!src) {
+  const msg = 'chatpanel-events not found (check out ../chatpanel-events).';
+  if (check) { console.error(`sync-events --check: ${msg}`); process.exit(1); }
+  console.warn(`sync-events: ${msg} Leaving src/events as-is.`);
+  process.exit(0);
+}
+
+const outDir = join(ROOT, 'src', 'events');
+if (!check) mkdirSync(outDir, { recursive: true });
+
+const banner = (f) => `// GENERATED — do not edit.\n`
+  + `// Source of truth: chatpanel-events/${f} (npm @chatpanel/events).\n`
+  + `// Edit there, then run: npm run sync:events\n`
+  + `//\n`
+  + `// Vendored rather than depended on: the bridge ships zero runtime dependencies so a\n`
+  + `// curl one-liner install cannot fail on someone's registry, and so the compiled\n`
+  + `// single-file binary has nothing to resolve.\n\n`;
+
+let drift = 0;
+for (const f of FILES) {
+  const want = banner(f) + readFileSync(join(src, f), 'utf8');
+  const dest = join(outDir, f);
+  const have = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+  if (have === want) continue;
+  if (check) { console.error(`sync-events --check: src/events/${f} differs from chatpanel-events`); drift += 1; continue; }
+  writeFileSync(dest, want);
+  console.log(`sync-events: updated src/events/${f}`);
+}
+
+if (check) {
+  if (drift) { console.error('Run `npm run sync:events` and commit the result.'); process.exit(1); }
+  console.log('sync-events --check: src/events matches chatpanel-events ✓');
+}

package/src/events/scopes.js

@@ -0,0 +1,20 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/scopes.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// scopes.js — the data-scope vocabulary, on its own so it can travel alone.
+//
+// One list names what anything in ChatPanel may touch. Capabilities declare `reads`
+// and `writes` from it, sources declare `reads`, and a skill package declares `reads`
+// — three declarations, one vocabulary, or "what may this reach" gets three answers.
+//
+// It is a separate module rather than a constant inside capability.js because the
+// consumers have very different weights. The bridge vendors the skill contract and has
+// zero runtime dependencies by design; pulling the capability machinery and the event
+// schema behind it to reach a five-element array would be the transitive-graph mistake
+// the extension's first-paint budget exists to prevent, one repo over.
+export const DATA_SCOPES = Object.freeze(['notes', 'meetings', 'chats', 'page', 'files', 'net']);

package/src/events/skill-manifest.js

@@ -0,0 +1,338 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-events/skill-manifest.js (npm @chatpanel/events).
+// Edit there, then run: npm run sync:events
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve.
+
+// skill-manifest.js — what a skill IS, for every client that stores or runs one.
+//
+// A skill was a settings record: a prompt plus a few dropdowns, normalized by whichever
+// client happened to save it. That was survivable while every skill was hand-written by
+// the person running it. It stops being survivable the moment a skill can ARRIVE from
+// somewhere — a hub, a repo, another agent's skill directory — because the questions
+// change from "what does this prompt say" to "where did it come from, what may it reach,
+// and has anything checked it".
+//
+// So this module owns the record. Not the storage (a platform question), not the UI (a
+// platform question), not the fetching (F6 S3) — the shape, its evolution, and the two
+// derivations no client may compute for itself:
+//
+//   • TRUST IS DERIVED, NEVER DECLARED. A skill cannot say it is trusted. `trustOf()`
+//     reads provenance: shipped by us -> 'built-in', fetched -> 'community', neither ->
+//     'user'. A stored `trust` field is stripped on normalize, and `builtin` is forced
+//     false whenever an origin is present — otherwise "trusted" would be a string an
+//     importer sets.
+//   • DECLARED ACCESS IS COMPUTED FROM THE RECORD. Everything a skill can reach is
+//     readable before it runs, which is what makes load-time approval possible (P10).
+//     If a reviewer's summary were assembled by the install screen, the install screen
+//     would be the security boundary.
+//
+// Versioning follows the log's discipline: additive only, absence means the previous
+// default, and the upcast chain exists from the start so adding v3 does not mean
+// rewriting every reader.
+
+import { DATA_SCOPES } from './scopes.js';
+
+export class SkillManifestError extends Error {
+  constructor(code, message) { super(message); this.name = 'SkillManifestError'; this.code = code; }
+}
+
+/** Schema version of the RECORD. Distinct from `version`, which is the author's semver. */
+export const SKILL_MANIFEST_VERSION = 2;
+
+export const SKILL_CONTEXTS = Object.freeze(['auto', 'page', 'selection', 'tabs', 'none']);
+export const SKILL_HISTORY_SCOPES = Object.freeze(['none', 'chats', 'meetings', 'all']);
+export const SKILL_MCP_MODES = Object.freeze(['none', 'selected', 'default']);
+
+/**
+ * Derived, never stored. 'community' is deliberately the level for a skill fetched from
+ * a vendor repo with a famous name — only what we ship went through our review.
+ */
+export const SKILL_TRUST = Object.freeze(['built-in', 'user', 'community']);
+
+/**
+ * The directories a package may carry, matching the agentskills.io layout. `scripts` is
+ * the tier-3 one: it cannot run in a browser extension and must not be offered as if it
+ * could (see `needsBridge`).
+ */
+export const SKILL_FILE_KINDS = Object.freeze(['references', 'scripts', 'assets', 'templates', 'examples']);
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+
+// A slash command is typed by a human and matched case-insensitively against a stored
+// string; anything outside this grammar either cannot be typed or collides with the
+// leading-slash parse.
+const COMMAND = /^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * A file path inside a package directory.
+ *
+ * The check is a security boundary, not tidiness: these strings become filesystem paths
+ * in the bridge's skill store, and a package is authored by a stranger. Rejected are
+ * absolute paths, any `..` segment, backslashes (a Windows separator that a POSIX
+ * `split('/')` would not see as one), leading/trailing whitespace and control characters.
+ * Allowing one of them is a directory-traversal write on someone's machine.
+ */
+export function isSafeSkillPath(p) {
+  if (!str(p) || p.length > 255) return false;
+  if (p !== p.trim()) return false;
+  if (p.includes('\\')) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/.test(p)) return false;
+  if (p.startsWith('/') || /^[a-z]:/i.test(p)) return false;
+  const parts = p.split('/');
+  if (parts.some((seg) => seg === '' || seg === '.' || seg === '..')) return false;
+  return true;
+}
+
+/** Did this skill come from somewhere, or did the user write it? */
+export function originOf(skill) {
+  const o = skill?.origin;
+  return o && typeof o === 'object' && str(o.source) && str(o.id) ? o : null;
+}
+
+/**
+ * Derived from provenance, never read from the record. A skill that arrived from outside
+ * is 'community' whoever published it; 'built-in' means we shipped it.
+ */
+export function trustOf(skill) {
+  if (originOf(skill)) return 'community';
+  return skill?.builtin ? 'built-in' : 'user';
+}
+
+/** The files a package carries, per directory, already filtered to safe paths. */
+export function skillFiles(skill) {
+  const files = skill?.files;
+  const out = {};
+  if (!files || typeof files !== 'object') return out;
+  for (const kind of SKILL_FILE_KINDS) {
+    const list = Array.isArray(files[kind]) ? files[kind].filter(isSafeSkillPath) : [];
+    if (list.length) out[kind] = [...new Set(list)];
+  }
+  return out;
+}
+
+/**
+ * True when running this skill fully needs a host that can execute code — i.e. the
+ * bridge. The extension may still store, show and run the PROMPT half; what it may not
+ * do is pretend the scripts ran.
+ */
+export function needsBridge(skill) {
+  return (skillFiles(skill).scripts || []).length > 0;
+}
+
+/**
+ * Everything this skill can reach, computed from the record. This is what an install
+ * review, the Plugins lens and an admin export all read — one derivation, so the three
+ * cannot disagree about what was approved.
+ */
+export function declaredAccess(skill = {}) {
+  const files = skillFiles(skill);
+  const mcpMode = SKILL_MCP_MODES.includes(skill.mcpMode) ? skill.mcpMode : 'none';
+  const context = SKILL_CONTEXTS.includes(skill.context) ? skill.context : 'auto';
+  const history = SKILL_HISTORY_SCOPES.includes(skill.historyContext) ? skill.historyContext : 'none';
+  const reads = new Set(Array.isArray(skill.reads) ? skill.reads.filter((r) => DATA_SCOPES.includes(r)) : []);
+  // The dropdowns ARE access statements; a record that declared `reads` separately from
+  // them could claim less than it takes.
+  if (context !== 'none') reads.add('page');
+  if (history === 'chats' || history === 'all') reads.add('chats');
+  if (history === 'meetings' || history === 'all') reads.add('meetings');
+  return {
+    trust: trustOf(skill),
+    reads: [...reads].sort(),
+    page: context,
+    history,
+    mcp: mcpMode,
+    mcpServerIds: mcpMode === 'selected' && Array.isArray(skill.mcpServerIds) ? [...skill.mcpServerIds] : [],
+    sources: Array.isArray(skill.sources) ? [...new Set(skill.sources.filter(str))].sort() : [],
+    surfaces: Array.isArray(skill.surfaces) ? [...new Set(skill.surfaces.filter(str))].sort() : [],
+    scripts: files.scripts || [],
+    needsBridge: needsBridge(skill),
+    meeting: !!skill.meeting,
+  };
+}
+
+/** Human label for where a skill came from, for the surfaces that must show provenance. */
+export function originLabel(skill) {
+  const o = originOf(skill);
+  if (!o) return trustOf(skill) === 'built-in' ? 'Built-in' : 'Written here';
+  return o.id.length > 48 ? `${o.source} · …${o.id.slice(-40)}` : `${o.source} · ${o.id}`;
+}
+
+/** Two records describing the same upstream skill — for update checks and dedupe. */
+export function sameSkillOrigin(a, b) {
+  const x = originOf(a);
+  const y = originOf(b);
+  return !!x && !!y && x.source === y.source && x.id === y.id;
+}
+
+/**
+ * Has upstream changed since this was installed? `null` when unanswerable (no origin, or
+ * nothing was hashed) — which callers must treat as "do not claim it is current" rather
+ * than as "up to date".
+ */
+export function skillIsStale(skill, upstreamHash) {
+  const o = originOf(skill);
+  if (!o || !str(o.hash) || !str(upstreamHash)) return null;
+  return o.hash !== upstreamHash;
+}
+
+/**
+ * Validate a skill DECLARATION — the static surface approved before anything runs.
+ * Throws on the first problem, like `validateCapability`.
+ */
+export function validateSkill(skill) {
+  if (!skill || typeof skill !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
+  if (!str(skill.id)) throw new SkillManifestError('SHAPE', 'skill.id required');
+  if (!str(skill.name)) throw new SkillManifestError('SHAPE', `skill '${skill.id}': name required`);
+  if (skill.prompt != null && typeof skill.prompt !== 'string') {
+    throw new SkillManifestError('SHAPE', `skill '${skill.id}': prompt must be a string`);
+  }
+  if (skill.command != null && skill.command !== '' && !COMMAND.test(String(skill.command))) {
+    throw new SkillManifestError('SHAPE', `skill '${skill.id}': command must match ${COMMAND}`);
+  }
+  for (const [field, allowed] of [
+    ['context', SKILL_CONTEXTS], ['historyContext', SKILL_HISTORY_SCOPES], ['mcpMode', SKILL_MCP_MODES],
+  ]) {
+    if (skill[field] != null && !allowed.includes(skill[field])) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be one of ${allowed}`);
+    }
+  }
+  if (skill.reads != null) {
+    if (!Array.isArray(skill.reads) || !skill.reads.every((r) => DATA_SCOPES.includes(r))) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': reads must be within ${DATA_SCOPES}`);
+    }
+  }
+  for (const field of ['sources', 'surfaces']) {
+    if (skill[field] != null && (!Array.isArray(skill[field]) || !skill[field].every(str))) {
+      throw new SkillManifestError('SHAPE', `skill '${skill.id}': ${field} must be an array of ids`);
+    }
+  }
+  if (skill.origin != null) {
+    const o = skill.origin;
+    if (typeof o !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': origin must be an object`);
+    // Without a source and an id it cannot be re-fetched or compared, which is the whole
+    // reason the field exists; a half-origin is worse than none because it looks answered.
+    if (!str(o.source) || !str(o.id)) {
+      throw new SkillManifestError('ORIGIN', `skill '${skill.id}': origin needs both source and id`);
+    }
+  }
+  if (skill.files != null) {
+    if (typeof skill.files !== 'object') throw new SkillManifestError('SHAPE', `skill '${skill.id}': files must be an object`);
+    for (const kind of Object.keys(skill.files)) {
+      if (!SKILL_FILE_KINDS.includes(kind)) {
+        throw new SkillManifestError('FILES', `skill '${skill.id}': unknown file kind '${kind}'`);
+      }
+      const list = skill.files[kind];
+      if (!Array.isArray(list) || !list.every(str)) {
+        throw new SkillManifestError('FILES', `skill '${skill.id}': files.${kind} must be an array of paths`);
+      }
+      const bad = list.find((p) => !isSafeSkillPath(p));
+      if (bad) throw new SkillManifestError('PATH', `skill '${skill.id}': unsafe path in files.${kind}: ${JSON.stringify(bad)}`);
+    }
+  }
+  // Files without an origin means someone hand-wrote a package record; that is allowed,
+  // but scripts without an origin cannot be scanned against anything, and an unscannable
+  // script is exactly what the admission gate exists to refuse.
+  if (!originOf(skill) && (skill.files?.scripts || []).length) {
+    throw new SkillManifestError('ORIGIN', `skill '${skill.id}': scripts require an origin to be scannable`);
+  }
+  return skill;
+}
+
+/**
+ * v(n) -> v(n+1). Each MUST be total: it may not throw for any record of its version.
+ *
+ * v1 -> v2 stamps the version and nothing else, on purpose. Every field F6 adds is
+ * absence-means-the-old-default, so there is nothing to fill in — the same discipline as
+ * storing which plugins are DISABLED rather than the full state, so a field added later
+ * needs no migration.
+ */
+export const SKILL_UPCASTERS = Object.freeze({
+  1: (s) => ({ ...s, v: SKILL_MANIFEST_VERSION }),
+});
+
+/** Carry a stored skill forward to the current schema. Pure; never mutates the input. */
+export function upcastSkill(stored) {
+  if (!stored || typeof stored !== 'object') throw new SkillManifestError('SHAPE', 'skill must be an object');
+  // A record written before the version existed is v1 by definition.
+  let s = typeof stored.v === 'number' ? stored : { ...stored, v: 1 };
+  let guard = 0;
+  while (s.v < SKILL_MANIFEST_VERSION) {
+    const step = SKILL_UPCASTERS[s.v];
+    if (!step) throw new SkillManifestError('UPCAST', `no upcaster from v${s.v}`);
+    s = step(s);
+    if (++guard > 64) throw new SkillManifestError('UPCAST', 'upcaster chain did not terminate');
+  }
+  if (s.v > SKILL_MANIFEST_VERSION) {
+    throw new SkillManifestError('UPCAST', `skill is v${s.v}; this reader only knows v${SKILL_MANIFEST_VERSION}`);
+  }
+  return s;
+}
+
+export function upcastSkills(stored) {
+  return (Array.isArray(stored) ? stored : []).map(upcastSkill);
+}
+
+/**
+ * Coerce a record into the canonical shape a writer stores. Total and forgiving — this
+ * runs on save, where throwing would cost a user their edit; `validateSkill` is the
+ * strict gate, used where a record ARRIVES.
+ *
+ * The security-relevant coercions are the ones that cannot be left to a caller:
+ * `trust` is never persisted, `builtin` cannot survive an origin, and an unsafe file
+ * path is dropped rather than stored and rejected later.
+ */
+export function normalizeSkill(skill) {
+  if (!skill || typeof skill !== 'object') return skill;
+  const out = { ...upcastSkill(skill) };
+
+  // Skills predate the enabled flag — absence means enabled.
+  out.enabled = out.enabled !== false;
+
+  const mode = String(out.mcpMode || 'none').toLowerCase();
+  out.mcpMode = SKILL_MCP_MODES.includes(mode) ? mode : 'none';
+  const ids = Array.isArray(out.mcpServerIds) ? out.mcpServerIds : [];
+  out.mcpServerIds = out.mcpMode === 'selected'
+    ? [...new Set(ids.map((id) => String(id || '').trim()).filter(Boolean))]
+    : [];
+
+  // Derived, never stored: a record that could assert its own trust would make every
+  // check downstream a formality.
+  delete out.trust;
+
+  const origin = originOf(out);
+  if (origin) {
+    out.builtin = false; // "we shipped it" is not something an import may claim
+    out.origin = {
+      source: origin.source,
+      id: origin.id,
+      ...(str(origin.url) ? { url: origin.url } : {}),
+      ...(str(origin.hash) ? { hash: origin.hash } : {}),
+      ...(origin.scanned && typeof origin.scanned === 'object' ? { scanned: { ...origin.scanned } } : {}),
+    };
+  } else if (out.origin != null) {
+    delete out.origin; // a half-origin looks answered and is not
+  }
+
+  if (out.reads != null) {
+    out.reads = [...new Set((Array.isArray(out.reads) ? out.reads : []).filter((r) => DATA_SCOPES.includes(r)))].sort();
+  }
+  for (const field of ['sources', 'surfaces']) {
+    if (out[field] != null) {
+      out[field] = [...new Set((Array.isArray(out[field]) ? out[field] : []).filter(str))];
+    }
+  }
+
+  if (out.files != null) {
+    const files = skillFiles(out);
+    if (Object.keys(files).length) out.files = files;
+    else delete out.files;
+  }
+
+  if (out.version != null && !str(out.version)) delete out.version;
+
+  return out;
+}

package/src/server.js

@@ -14,6 +14,9 @@
 //   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
@@ -33,6 +36,7 @@ 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';
@@ -60,7 +64,7 @@ import {
 // 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.27';
+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;
 
@@ -273,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
@@ -287,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';
   }
@@ -336,7 +362,41 @@ 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() {
@@ -978,6 +1038,17 @@ 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)));

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 } : {}),
+  };
+}