lazyclaw 3.88.0

package/providers/registry.mjs

@@ -0,0 +1,144 @@
+// Provider registry for LazyClaw chat.
+// Each provider exposes { name, sendMessage(messages, opts) } where
+// sendMessage returns an AsyncIterable<string> of token chunks.
+//
+// The mock provider is the offline default exercised by phase 3 tests.
+// The real Anthropic Messages-API streaming provider lives next door in
+// providers/anthropic.mjs and is re-exported here so callers only need to
+// know about PROVIDERS.
+
+import { anthropicProvider } from './anthropic.mjs';
+import { openaiProvider } from './openai.mjs';
+import { ollamaProvider } from './ollama.mjs';
+import { geminiProvider } from './gemini.mjs';
+
+/**
+ * @typedef {{ role: 'user'|'assistant'|'system', content: string }} ChatMessage
+ */
+
+/**
+ * @typedef {Object} Provider
+ * @property {string} name
+ * @property {(messages: ChatMessage[], opts: { apiKey?: string, model?: string }) => AsyncIterable<string>} sendMessage
+ */
+
+async function* mockChunks(text, delayMs = 5, signal) {
+  for (const ch of text) {
+    if (signal?.aborted) {
+      const e = new Error('aborted');
+      e.code = 'ABORT';
+      throw e;
+    }
+    await new Promise(r => setTimeout(r, delayMs));
+    yield ch;
+  }
+}
+
+/** @type {Provider} */
+export const mockProvider = {
+  name: 'mock',
+  async *sendMessage(messages, opts = {}) {
+    const last = messages[messages.length - 1];
+    const reply = `mock-reply: ${last?.content ?? ''}`;
+    // Honor opts.signal so the chat REPL's Ctrl+C handler (and any
+    // other caller) can stop the stream mid-flight. The other concrete
+    // providers already do this; the mock should match for symmetry.
+    yield* mockChunks(reply, 5, opts.signal);
+  },
+};
+
+export { anthropicProvider, openaiProvider, ollamaProvider, geminiProvider };
+
+export const PROVIDERS = {
+  mock: mockProvider,
+  anthropic: anthropicProvider,
+  openai: openaiProvider,
+  ollama: ollamaProvider,
+  gemini: geminiProvider,
+};
+
+// Static metadata for `lazyclaw providers list/info`. Kept next to PROVIDERS
+// so adding a provider in one place can't drift from the list shown to users.
+export const PROVIDER_INFO = {
+  mock: {
+    name: 'mock',
+    requiresApiKey: false,
+    docs: 'In-process echo provider. Replies "mock-reply: <last user message>". Used for offline tests and demos.',
+    defaultModel: null,
+    suggestedModels: [],
+  },
+  anthropic: {
+    name: 'anthropic',
+    requiresApiKey: true,
+    keyPrefix: 'sk-ant-',
+    docs: 'Anthropic Messages API. Supports streaming + extended thinking.',
+    endpoint: 'https://api.anthropic.com/v1/messages',
+    defaultModel: 'claude-opus-4-7',
+    suggestedModels: ['claude-opus-4-7', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
+  },
+  openai: {
+    name: 'openai',
+    requiresApiKey: true,
+    keyPrefix: 'sk-',
+    docs: 'OpenAI Chat Completions API. Streaming via SSE with [DONE] terminator.',
+    endpoint: 'https://api.openai.com/v1/chat/completions',
+    defaultModel: 'gpt-4.1',
+    suggestedModels: ['gpt-4.1', 'gpt-4o', 'gpt-4o-mini'],
+  },
+  ollama: {
+    name: 'ollama',
+    requiresApiKey: false,
+    docs: 'Local Ollama daemon. Streams newline-delimited JSON from /api/chat. No auth — defaults to 127.0.0.1:11434, override via OLLAMA_HOST or opts.baseUrl.',
+    endpoint: 'http://127.0.0.1:11434/api/chat',
+    defaultModel: 'llama3.1',
+    suggestedModels: ['llama3.1', 'llama3.2', 'mistral', 'qwen2.5-coder'],
+  },
+  gemini: {
+    name: 'gemini',
+    requiresApiKey: true,
+    docs: 'Google Generative Language API (Gemini). SSE streaming via :streamGenerateContent?alt=sse. Auth via ?key= query param.',
+    endpoint: 'https://generativelanguage.googleapis.com/v1/models/{model}:streamGenerateContent',
+    defaultModel: 'gemini-1.5-pro',
+    suggestedModels: ['gemini-1.5-pro', 'gemini-1.5-flash', 'gemini-2.0-flash'],
+  },
+};
+
+/**
+ * Split a unified "provider/model" string (OpenClaw style:
+ * "anthropic/claude-opus-4-7"). Also accepts a bare model id and returns
+ * provider=null so callers can fall back to a separately-stored provider.
+ * @param {string} s
+ * @returns {{ provider: string|null, model: string }}
+ */
+export function parseProviderModel(s) {
+  if (!s || typeof s !== 'string') return { provider: null, model: '' };
+  const slash = s.indexOf('/');
+  if (slash > 0) {
+    return { provider: s.slice(0, slash).trim().toLowerCase(), model: s.slice(slash + 1).trim() };
+  }
+  return { provider: null, model: s.trim() };
+}
+
+/**
+ * Mask an API key for safe display. Keeps a recognised vendor prefix
+ * (sk-ant-, sk-, etc.) and the last 4 characters; masks everything in
+ * between. Returns '' when no key is set.
+ *
+ * The vendor prefix is deliberately conservative: only the well-known
+ * ones (sk-ant-, sk-) — anything else yields "****…tail" with no prefix
+ * so we never accidentally surface a meaningful chunk of a custom key.
+ * @param {string|undefined|null} key
+ * @returns {string}
+ */
+const KNOWN_KEY_PREFIXES = ['sk-ant-', 'sk-or-', 'sk-'];
+export function maskApiKey(key) {
+  if (!key) return '';
+  const s = String(key);
+  let prefix = '';
+  for (const p of KNOWN_KEY_PREFIXES) {
+    if (s.startsWith(p)) { prefix = p; break; }
+  }
+  const tail = s.length - prefix.length >= 8 ? s.slice(-4) : '';
+  const middleLen = Math.max(4, Math.min(12, s.length - prefix.length - tail.length));
+  return `${prefix}${'*'.repeat(middleLen)}${tail}`;
+}

package/providers/retry.mjs

@@ -0,0 +1,103 @@
+// Opt-in retry wrapper for provider streams.
+//
+// Why this is a wrapper, not a provider option:
+//   - The retry decision is *policy*, not *transport*. Different callers
+//     want different retry budgets (a CLI script may want 3, a long-running
+//     daemon may want 10 with a max wall clock).
+//   - Wrapping keeps the providers themselves simple — they remain pure
+//     async iterators over a single attempt.
+//
+// Strategy:
+//   1. We only retry RATE_LIMIT errors that surface *before* any chunk has
+//      been yielded. Once the model has started speaking we cannot retry
+//      without producing duplicate output, so mid-stream RATE_LIMIT bubbles
+//      to the caller unchanged.
+//   2. Sleep duration is `min(opts.retryAfterMs, opts.maxBackoffMs)` —
+//      we trust `Retry-After` but cap it so a misbehaving provider can't
+//      pin us for an hour.
+//   3. `attempts` is exclusive of the initial call: `attempts: 3` means
+//      one attempt + up to three retries.
+//   4. AbortSignal is checked in the sleep so a cancel during the wait
+//      doesn't have to wait for the wake-up.
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_MAX_BACKOFF_MS = 60_000;
+const ABSOLUTE_MAX_BACKOFF_MS = 5 * 60_000;  // hard ceiling, ignores caller
+
+function clampBackoff(retryAfterMs, max) {
+  const ceiling = Math.min(max, ABSOLUTE_MAX_BACKOFF_MS);
+  if (!Number.isFinite(retryAfterMs) || retryAfterMs < 0) return ceiling;
+  return Math.min(retryAfterMs, ceiling);
+}
+
+async function abortableSleep(ms, signal) {
+  if (ms <= 0) return;
+  if (signal?.aborted) {
+    const e = new Error('aborted during retry backoff');
+    e.code = 'ABORT';
+    throw e;
+  }
+  await new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      signal?.removeEventListener?.('abort', onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(t);
+      const e = new Error('aborted during retry backoff');
+      e.code = 'ABORT';
+      reject(e);
+    }
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Wrap a provider's sendMessage with rate-limit-aware retries.
+ *
+ * @param {{ name: string, sendMessage: Function }} provider
+ * @param {{
+ *   attempts?: number,
+ *   maxBackoffMs?: number,
+ *   onRetry?: (info: { attempt: number, retryAfterMs: number, err: Error }) => void,
+ *   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>,
+ * }} retryOpts
+ */
+export function withRateLimitRetry(provider, retryOpts = {}) {
+  const attempts = Number.isFinite(retryOpts.attempts) ? retryOpts.attempts : DEFAULT_ATTEMPTS;
+  const maxBackoffMs = retryOpts.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS;
+  const sleep = retryOpts.sleep || abortableSleep;
+  const onRetry = retryOpts.onRetry;
+
+  return {
+    name: `${provider.name}+retry`,
+    async *sendMessage(messages, opts = {}) {
+      let lastErr = null;
+      for (let attempt = 0; attempt <= attempts; attempt++) {
+        let yieldedAny = false;
+        try {
+          for await (const chunk of provider.sendMessage(messages, opts)) {
+            yieldedAny = true;
+            yield chunk;
+          }
+          return;
+        } catch (err) {
+          lastErr = err;
+          // Mid-stream errors cannot be retried: we'd produce duplicate text.
+          if (yieldedAny) throw err;
+          // Only retry RATE_LIMIT and only if we still have attempts left.
+          if (err?.code !== 'RATE_LIMIT' || attempt >= attempts) throw err;
+          const wait = clampBackoff(err.retryAfterMs, maxBackoffMs);
+          if (typeof onRetry === 'function') {
+            try { onRetry({ attempt: attempt + 1, retryAfterMs: wait, err }); } catch { /* swallow */ }
+          }
+          await sleep(wait, opts.signal);
+        }
+      }
+      // Loop exits only when attempts exhausted; lastErr always set.
+      throw lastErr;
+    },
+  };
+}
+
+export { clampBackoff, abortableSleep };

package/ratelimit.mjs

@@ -0,0 +1,65 @@
+// Token-bucket rate limiter, opt-in for the daemon.
+//
+// Why token bucket and not fixed-window:
+//   - Fixed windows allow burst-double at the boundary (last second of
+//     window N + first second of window N+1 → 2× the limit). Token
+//     bucket smooths that out.
+//   - Bucket math is two arithmetic operations per request (refill +
+//     deduct), no per-request log entries to truncate.
+//
+// Per-key buckets — `key` is whatever the caller wants to scope by.
+// The daemon uses the remote IP. A future caller could scope by API
+// key prefix or path.
+//
+// Memory bound: stale buckets are evicted on access (the bucket would
+// have refilled to capacity anyway after `capacity / rate` seconds, so
+// we lose nothing by dropping it). No background sweep needed.
+
+const DEFAULT_CAPACITY = 60;          // requests
+const DEFAULT_REFILL_PER_SEC = 1;     // 60 req/min sustained
+
+export class TokenBucketLimiter {
+  /**
+   * @param {{ capacity?: number, refillPerSec?: number, now?: () => number }} [opts]
+   */
+  constructor(opts = {}) {
+    this.capacity = opts.capacity ?? DEFAULT_CAPACITY;
+    this.refillPerSec = opts.refillPerSec ?? DEFAULT_REFILL_PER_SEC;
+    this.now = opts.now ?? (() => Date.now());
+    /** @type {Map<string, { tokens: number, last: number }>} */
+    this.buckets = new Map();
+  }
+
+  /**
+   * Try to consume one token from the bucket for `key`.
+   * Returns { allowed: boolean, retryAfterMs: number, remaining: number }.
+   *
+   * When `allowed: false`, `retryAfterMs` is the wall-clock delay until
+   * one token would be available — the daemon advertises this in the
+   * `Retry-After` header so a polite client backs off correctly.
+   */
+  consume(key) {
+    const t = this.now();
+    let b = this.buckets.get(key);
+    if (!b) {
+      b = { tokens: this.capacity, last: t };
+      this.buckets.set(key, b);
+    }
+    const elapsedSec = Math.max(0, (t - b.last) / 1000);
+    b.tokens = Math.min(this.capacity, b.tokens + elapsedSec * this.refillPerSec);
+    b.last = t;
+    if (b.tokens >= 1) {
+      b.tokens -= 1;
+      return { allowed: true, retryAfterMs: 0, remaining: Math.floor(b.tokens) };
+    }
+    const deficit = 1 - b.tokens;
+    const retryAfterMs = Math.ceil((deficit / this.refillPerSec) * 1000);
+    return { allowed: false, retryAfterMs, remaining: 0 };
+  }
+
+  /** Forget the bucket for `key`. Used by tests and by callers that
+   *  know a client is gone. Memory is otherwise self-healing. */
+  forget(key) {
+    this.buckets.delete(key);
+  }
+}

package/rates-validate.mjs

@@ -0,0 +1,58 @@
+// Structural integrity check for cfg.rates. Distinct from runtime
+// "doctor" checks — this is purely about shape: keys in
+// "provider/model" form, required fields present, numbers non-
+// negative.
+//
+// Shared between `lazyclaw rates validate` (CLI) and
+// `GET /rates/validate` (daemon) so both produce bit-for-bit
+// identical output.
+
+/**
+ * @param {Record<string, unknown>} rates           cfg.rates map (or undefined)
+ * @param {Record<string, unknown>} providers       Registered providers map (keys = provider names)
+ * @returns {{ ok: boolean, rateCount: number, issues: string[], warnings: string[] }}
+ */
+export function validateRates(rates, providers) {
+  const issues = [];
+  const warnings = [];
+  const safeRates = (rates && typeof rates === 'object' && !Array.isArray(rates)) ? rates : {};
+  const knownProviders = new Set(Object.keys(providers || {}));
+  for (const key of Object.keys(safeRates)) {
+    if (!key.includes('/')) {
+      issues.push(`key "${key}": expected "provider/model" shape (slash required)`);
+      continue;
+    }
+    const [provider] = key.split('/');
+    if (!knownProviders.has(provider)) {
+      warnings.push(`key "${key}": provider "${provider}" not in registered providers (registered: ${[...knownProviders].join(', ')})`);
+    }
+    const card = safeRates[key];
+    if (!card || typeof card !== 'object') {
+      issues.push(`key "${key}": value must be an object`);
+      continue;
+    }
+    for (const required of ['inputPer1M', 'outputPer1M']) {
+      const v = card[required];
+      if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+        issues.push(`key "${key}": ${required} must be a non-negative finite number (got ${JSON.stringify(v)})`);
+      }
+    }
+    for (const optional of ['cacheReadPer1M', 'cacheCreatePer1M']) {
+      if (card[optional] !== undefined) {
+        const v = card[optional];
+        if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+          issues.push(`key "${key}": ${optional} must be a non-negative finite number when set (got ${JSON.stringify(v)})`);
+        }
+      }
+    }
+    if (card.currency !== undefined && typeof card.currency !== 'string') {
+      issues.push(`key "${key}": currency must be a string (got ${typeof card.currency})`);
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    rateCount: Object.keys(safeRates).length,
+    issues,
+    warnings,
+  };
+}

package/sessions.mjs

@@ -0,0 +1,177 @@
+// Persistent chat sessions for LazyClaw.
+//
+// Storage layout under <configDir>/sessions/:
+//   <id>.jsonl — append-only log of {role, content, ts} turns
+//
+// Why JSONL not a single JSON file:
+//   - Atomic append per turn — no read-modify-write race when two
+//     terminals talk to the same session.
+//   - O(1) write per turn regardless of conversation length.
+//   - The last-turn timestamp is the file mtime, so listSessions does
+//     not have to read every file to sort.
+//
+// `loadTurns` is the only operation that reads the whole log; it splits
+// on '\n' and JSON.parses each non-empty line, ignoring malformed lines
+// rather than failing the chat.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const SESSIONS_DIRNAME = 'sessions';
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function sessionsDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, SESSIONS_DIRNAME);
+}
+
+export function sessionPath(id, configDir = defaultConfigDir()) {
+  if (!id || /[/\\]/.test(id) || id === '.' || id === '..') {
+    throw new Error(`invalid session id: ${id}`);
+  }
+  return path.join(sessionsDir(configDir), `${id}.jsonl`);
+}
+
+export function listSessions(configDir = defaultConfigDir()) {
+  const dir = sessionsDir(configDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(name => name.endsWith('.jsonl'))
+    .map(name => {
+      const fullPath = path.join(dir, name);
+      const stat = fs.statSync(fullPath);
+      return {
+        id: name.slice(0, -'.jsonl'.length),
+        path: fullPath,
+        bytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+      };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+export function loadTurns(id, configDir = defaultConfigDir()) {
+  const p = sessionPath(id, configDir);
+  if (!fs.existsSync(p)) return [];
+  const raw = fs.readFileSync(p, 'utf8');
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); }
+    catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+export function appendTurn(id, role, content, configDir = defaultConfigDir()) {
+  if (role !== 'user' && role !== 'assistant' && role !== 'system') {
+    throw new Error(`invalid role: ${role}`);
+  }
+  const p = sessionPath(id, configDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const line = JSON.stringify({ role, content: String(content ?? ''), ts: Date.now() }) + '\n';
+  fs.appendFileSync(p, line);
+}
+
+export function clearSession(id, configDir = defaultConfigDir()) {
+  const p = sessionPath(id, configDir);
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}
+
+export function resetSession(id, configDir = defaultConfigDir()) {
+  // Truncate without removing — mtime advances so the session stays at
+  // the top of `listSessions` order (it was just touched).
+  const p = sessionPath(id, configDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, '');
+}
+
+/**
+ * Render a session as shareable Markdown. The session id and turn count
+ * become the H1 / metadata block; each turn becomes a section with the
+ * role as H2 and the content as a fenced block when it looks like code,
+ * else plain prose.
+ *
+ * Why fenced blocks: assistant replies often contain code that would
+ * otherwise be mis-rendered as Markdown. We use a triple-backtick fence
+ * with a language tag of `text` only when no code-fence is already
+ * present in the turn content (so models that already produce
+ * pre-formatted code blocks don't end up double-fenced).
+ *
+ * @param {string} id
+ * @param {string} [configDir]
+ * @returns {string}
+ */
+export function exportMarkdown(id, configDir = defaultConfigDir()) {
+  const turns = loadTurns(id, configDir);
+  const lines = [`# Session: ${id}`, ''];
+  if (turns.length === 0) {
+    lines.push('_(empty)_');
+    return lines.join('\n');
+  }
+  const first = new Date(turns[0]?.ts || Date.now()).toISOString();
+  const last = new Date(turns[turns.length - 1]?.ts || Date.now()).toISOString();
+  lines.push(`- Turns: ${turns.length}`, `- First: ${first}`, `- Last: ${last}`, '');
+  for (const t of turns) {
+    const role = t.role === 'user' ? 'User' : t.role === 'assistant' ? 'Assistant' : 'System';
+    lines.push(`## ${role}`, '');
+    const text = String(t.content || '');
+    lines.push(text, '');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Structured export — JSON object with session id + ISO timestamps.
+ * Useful for piping into jq or feeding analytics tooling that
+ * doesn't want to parse markdown.
+ *
+ * Shape:
+ *   { id, turnCount, first?, last?, turns: [{ role, content, ts }] }
+ *
+ * `first` / `last` are omitted on empty sessions so a downstream
+ * tool can distinguish "no turns yet" from "first turn at epoch 0".
+ *
+ * @param {string} id
+ * @param {string} [configDir]
+ * @returns {string} pretty-printed JSON (2-space indent)
+ */
+export function exportJson(id, configDir = defaultConfigDir()) {
+  const turns = loadTurns(id, configDir);
+  const out = { id, turnCount: turns.length };
+  if (turns.length > 0) {
+    out.first = new Date(turns[0]?.ts || Date.now()).toISOString();
+    out.last = new Date(turns[turns.length - 1]?.ts || Date.now()).toISOString();
+  }
+  out.turns = turns.map(t => ({
+    role: t.role,
+    content: String(t.content || ''),
+    ts: typeof t.ts === 'number' ? t.ts : null,
+  }));
+  return JSON.stringify(out, null, 2);
+}
+
+/**
+ * Plain-text export — `<ROLE>:` headers and turn content separated
+ * by blank lines, no markdown / fences / headers. Ideal for paste-
+ * into-anything contexts (issue templates, plain-text email).
+ *
+ * @param {string} id
+ * @param {string} [configDir]
+ * @returns {string}
+ */
+export function exportText(id, configDir = defaultConfigDir()) {
+  const turns = loadTurns(id, configDir);
+  if (turns.length === 0) return `Session: ${id}\n(empty)\n`;
+  const lines = [`Session: ${id}`, `Turns: ${turns.length}`, ''];
+  for (const t of turns) {
+    const role = (t.role || 'unknown').toUpperCase();
+    lines.push(`${role}:`);
+    lines.push(String(t.content || ''));
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/skills.mjs

@@ -0,0 +1,97 @@
+// Skills are markdown files in <configDir>/skills/<name>.md whose contents
+// are prepended to the system prompt when chat or agent runs with --skill.
+//
+// This is the OpenClaw "skill" concept reduced to its load-bearing core:
+// reusable instruction bundles, named, locally stored, no remote registry.
+//
+// Why .md and not JSON-with-content: skills are written by humans for
+// humans, and markdown keeps headers / lists / code blocks readable both
+// in the file system and inside the model prompt.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const SKILLS_DIRNAME = 'skills';
+const SKILL_EXT = '.md';
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function skillsDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, SKILLS_DIRNAME);
+}
+
+export function skillPath(name, configDir = defaultConfigDir()) {
+  if (!name || /[/\\]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
+    throw new Error(`invalid skill name: ${name}`);
+  }
+  return path.join(skillsDir(configDir), `${name}${SKILL_EXT}`);
+}
+
+export function listSkills(configDir = defaultConfigDir()) {
+  const dir = skillsDir(configDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(name => name.endsWith(SKILL_EXT))
+    .map(name => {
+      const full = path.join(dir, name);
+      const stat = fs.statSync(full);
+      const head = readFirstLine(full);
+      return {
+        name: name.slice(0, -SKILL_EXT.length),
+        path: full,
+        bytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+        summary: head.replace(/^#+\s*/, '').slice(0, 120),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function readFirstLine(p) {
+  try {
+    const buf = fs.readFileSync(p, 'utf8');
+    const nl = buf.indexOf('\n');
+    return nl < 0 ? buf : buf.slice(0, nl);
+  } catch { return ''; }
+}
+
+export function loadSkill(name, configDir = defaultConfigDir()) {
+  const p = skillPath(name, configDir);
+  if (!fs.existsSync(p)) throw new Error(`skill not found: ${name}`);
+  return fs.readFileSync(p, 'utf8');
+}
+
+export function installSkill(name, content, configDir = defaultConfigDir()) {
+  const p = skillPath(name, configDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+export function removeSkill(name, configDir = defaultConfigDir()) {
+  const p = skillPath(name, configDir);
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}
+
+/**
+ * Compose the system prompt for a chat/agent invocation. Concatenates each
+ * named skill's contents with a separator, in the order given. Returns null
+ * when no skills are requested so the caller can pass through unchanged.
+ *
+ * @param {string[]} names
+ * @param {string} [configDir]
+ */
+export function composeSystemPrompt(names, configDir = defaultConfigDir()) {
+  if (!names || names.length === 0) return null;
+  const blocks = [];
+  for (const n of names) {
+    const trimmed = String(n || '').trim();
+    if (!trimmed) continue;
+    const body = loadSkill(trimmed, configDir);
+    blocks.push(`<!-- skill: ${trimmed} -->\n${body.trim()}`);
+  }
+  return blocks.length ? blocks.join('\n\n---\n\n') : null;
+}

package/web/server.mjs

@@ -0,0 +1,33 @@
+// Tiny static file server used by phase 3+ acceptance tests.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+};
+
+export function startStaticServer(rootDir, port = 0) {
+  const root = path.resolve(rootDir);
+  const server = http.createServer((req, res) => {
+    let urlPath = (req.url || '/').split('?')[0];
+    if (urlPath === '/') urlPath = '/index.html';
+    const file = path.normalize(path.join(root, urlPath));
+    if (!file.startsWith(root)) { res.statusCode = 403; res.end('forbidden'); return; }
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) { res.statusCode = 404; res.end('not found'); return; }
+    res.setHeader('content-type', MIME[path.extname(file)] || 'application/octet-stream');
+    res.setHeader('cache-control', 'no-store');
+    res.end(fs.readFileSync(file));
+  });
+  return new Promise(resolve => {
+    server.listen(port, '127.0.0.1', () => {
+      const addr = server.address();
+      const realPort = typeof addr === 'object' && addr ? addr.port : port;
+      resolve({ server, port: realPort, url: `http://127.0.0.1:${realPort}` });
+    });
+  });
+}