lazyclaw 4.3.0 → 5.0.0

package/mas/tools/recall.mjs

@@ -0,0 +1,103 @@
+// recall tool — Phase B (v5 §4.5).
+//
+// FTS5-backed cross-scope recall. Reads from mas/index_db.mjs (the
+// SQLite mirror populated by Phase A's write-through hooks).
+//
+// Args:
+//   query:     required string
+//   scope:     optional array of 'sessions'|'skills'|'trajectories'|'memories'
+//              (default: all four)
+//   k:         optional integer, default 10, hard-capped at 50
+//   summarize: optional boolean (v5.1+ wires the trainer; v5.0 leaves
+//              summary null when set, so the agent gets raw hits.)
+//   filter:    optional object of UNINDEXED column equality filters
+//              (session_id, agent, outcome, trained_by, group_name, kind, since)
+
+import { openIndex, recall as indexRecall } from '../index_db.mjs';
+
+export const NAME = 'recall';
+export const DESCRIPTION =
+  'Search prior sessions, skills, trajectories, and memories by FTS5 query. Returns ranked snippets with metadata. Use this BEFORE asking the user to repeat themselves or before solving a problem from scratch.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    query: { type: 'string', description: 'FTS5 MATCH query. Plain words are AND-ed.' },
+    scope: { type: 'array', items: { type: 'string', enum: ['sessions', 'skills', 'trajectories', 'memories'] } },
+    k: { type: 'integer', minimum: 1, maximum: 50 },
+    summarize: { type: 'boolean' },
+    filter: { type: 'object', additionalProperties: true },
+  },
+  required: ['query'],
+};
+
+const DEFAULT_SCOPES = ['sessions', 'skills', 'trajectories', 'memories'];
+const MAX_K = 50;
+
+let _stubRecall = null;
+export function __setRecall(fn) { _stubRecall = typeof fn === 'function' ? fn : null; }
+
+export async function exec(args, { configDir } = {}) {
+  if (!args || typeof args.query !== 'string' || !args.query.trim()) {
+    return { ok: false, error: 'recall: query is required' };
+  }
+  const query = args.query.trim();
+  const scopes = Array.isArray(args.scope) && args.scope.length ? args.scope : DEFAULT_SCOPES;
+  const k = Math.max(1, Math.min(MAX_K, Number(args.k) || 10));
+  const filter = args.filter && typeof args.filter === 'object' ? args.filter : {};
+  const t0 = Date.now();
+
+  let out;
+  if (_stubRecall) {
+    try {
+      out = await _stubRecall(query, { scope: scopes, k });
+    } catch (err) {
+      return { ok: false, error: `recall: stub threw — ${err?.message || err}` };
+    }
+  } else {
+    try {
+      openIndex(configDir);
+    } catch (err) {
+      return { ok: false, error: `recall: openIndex failed — ${err?.message || err}` };
+    }
+    try {
+      out = indexRecall(query, { configDir, scope: scopes, k });
+    } catch (err) {
+      return { ok: false, error: `recall: query failed — ${err?.message || err}` };
+    }
+  }
+
+  // Apply optional UNINDEXED filter (metadata-level equality / since predicate).
+  let hits = Array.isArray(out.hits) ? out.hits : [];
+  const filterKeys = Object.keys(filter);
+  if (filterKeys.length) {
+    hits = hits.filter((h) => {
+      const meta = h.metadata || {};
+      for (const key of filterKeys) {
+        if (key === 'since') {
+          if (Number(meta.ts || 0) < Number(filter.since)) return false;
+        } else if (String(meta[key] ?? '') !== String(filter[key])) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+
+  return {
+    ok: true,
+    query,
+    hits: hits.slice(0, k),
+    summary: null,           // v5.0: raw hits only; v5.1 wires trainer.
+    summarizedBy: null,
+    latencyMs: Date.now() - t0,
+  };
+}
+
+export const TOOL = {
+  name: NAME,
+  category: 'learning',
+  sensitive: false,
+  description: DESCRIPTION,
+  parameters: PARAMETERS,
+  exec,
+};

package/mas/tools/registry.mjs

@@ -0,0 +1,93 @@
+// Tool registry — aggregates every first-party tool group plus any MCP-imported
+// tools so callers (tool_runner, splash renderer, agent toolset resolver) can
+// ask for them by name without knowing which file they live in.
+//
+// Each tool record: {name, category, sensitive, description, parameters, exec}
+//   - name: unique key (mcp tools use "mcp:<server>:<tool>")
+//   - category: 'exec' | 'fs' | 'net' | 'data' | 'agents' | 'learning' | ...
+//   - sensitive: when true, tool_runner requires `approve` hook before exec
+//   - parameters: JSON-Schema object (same shape as Phase 12a)
+//   - exec(args, ctx) -> {ok, ...}
+
+import * as bashTool from './bash.mjs';
+import * as readTool from './read.mjs';
+import * as writeTool from './write.mjs';
+import * as grepTool from './grep.mjs';
+
+function adaptLegacy(mod, { category, sensitive }) {
+  return {
+    name: mod.NAME,
+    category,
+    sensitive,
+    description: mod.DESCRIPTION,
+    parameters: mod.PARAMETERS,
+    exec: mod.exec,
+  };
+}
+
+// Built-in (Phase 12a) tools, adapted to v5 shape.
+const BUILTINS = [
+  adaptLegacy(bashTool,      { category: 'exec', sensitive: true  }),
+  adaptLegacy(readTool,      { category: 'fs',   sensitive: false }),
+  adaptLegacy(writeTool,     { category: 'fs',   sensitive: true  }),
+  adaptLegacy(grepTool,      { category: 'fs',   sensitive: false }),
+];
+
+import { TOOL as editTool }  from './edit.mjs';
+import { TOOL as patchTool } from './patch.mjs';
+import { TOOL as recallTool } from './recall.mjs';
+import { TOOLS as learningTools } from './learning.mjs';
+import { TOOLS as webTools } from './web.mjs';
+import { TOOLS as osTools } from './os.mjs';
+import { TOOLS as codingTools } from './coding.mjs';
+import { TOOLS as gitGroupTools } from './git.mjs';
+import { TOOLS as schedTools } from './scheduling.mjs';
+import { TOOLS as delTools } from './delegation.mjs';
+import { TOOLS as mediaTools } from './media.mjs';
+import { TOOLS as haTools } from './ha.mjs';
+import { TOOL  as clarifyTool } from './clarify.mjs';
+import { TOOLS as browserTools } from './browser.mjs';
+
+BUILTINS.push(editTool, patchTool);
+BUILTINS.push(recallTool);
+for (const t of learningTools) BUILTINS.push(t);
+for (const t of webTools) BUILTINS.push(t);
+for (const t of osTools) BUILTINS.push(t);
+for (const t of codingTools) BUILTINS.push(t);
+for (const t of gitGroupTools) BUILTINS.push(t);
+for (const t of schedTools) BUILTINS.push(t);
+for (const t of delTools) BUILTINS.push(t);
+for (const t of mediaTools) BUILTINS.push(t);
+for (const t of haTools) BUILTINS.push(t);
+BUILTINS.push(clarifyTool);
+for (const t of browserTools) BUILTINS.push(t);
+
+// Mutable; new groups (Tasks 2-14) push here; MCP client (Task 15) also pushes.
+const TOOLS = new Map();
+for (const t of BUILTINS) TOOLS.set(t.name, t);
+
+export function register(tool) {
+  if (!tool || typeof tool.name !== 'string') throw new Error('registry.register: tool.name required');
+  if (typeof tool.exec !== 'function')        throw new Error(`registry.register(${tool.name}): exec required`);
+  if (typeof tool.sensitive !== 'boolean')    throw new Error(`registry.register(${tool.name}): sensitive required`);
+  TOOLS.set(tool.name, tool);
+}
+
+export function registerGroup(group) {
+  if (!Array.isArray(group)) throw new Error('registry.registerGroup: array required');
+  for (const t of group) register(t);
+}
+
+export function unregister(name) { return TOOLS.delete(name); }
+
+export function lookup(name) { return TOOLS.get(name) || null; }
+
+export function listAll() { return [...TOOLS.values()]; }
+
+export function listNames() { return [...TOOLS.keys()]; }
+
+export function byCategory() {
+  const out = {};
+  for (const t of TOOLS.values()) (out[t.category] ||= []).push(t);
+  return out;
+}

package/mas/tools/scheduling.mjs

@@ -0,0 +1,62 @@
+// scheduling — cron_add / cron_remove / cron_list. Wraps cron.mjs but the
+// backend is overridable for tests via __setCronBackend.
+
+let _backend = null;
+export function __setCronBackend(b) { _backend = b; }
+
+async function getBackend() {
+  if (_backend) return _backend;
+  const cron = await import('../../cron.mjs').catch(() => null);
+  if (!cron) throw new Error('scheduling: cron.mjs not available');
+  return {
+    add:    async (j) => cron.add ? cron.add(j) : { ok: false, error: 'cron.add missing' },
+    list:   async ()  => cron.list ? cron.list() : [],
+    remove: async (n) => cron.remove ? cron.remove(n) : { ok: false, error: 'cron.remove missing' },
+  };
+}
+
+// Field-count validator independent of cron.mjs internals so we get a clean error.
+function looksLikeCronSpec(s) {
+  return typeof s === 'string' && s.trim().split(/\s+/).length === 5;
+}
+
+const cron_add = {
+  name: 'cron_add', category: 'scheduling', sensitive: true,
+  description: 'Schedule a recurring agent run or shell command.',
+  parameters: {
+    type: 'object',
+    properties: {
+      name:    { type: 'string' },
+      spec:    { type: 'string', description: '5-field cron spec.' },
+      command: { type: 'string' },
+    },
+    required: ['name', 'spec', 'command'],
+  },
+  async exec(args) {
+    if (!looksLikeCronSpec(args.spec)) return { ok: false, error: `cron_add: bad cron spec "${args.spec}"` };
+    const b = await getBackend();
+    return b.add({ name: args.name, spec: args.spec, command: args.command });
+  },
+};
+
+const cron_remove = {
+  name: 'cron_remove', category: 'scheduling', sensitive: true,
+  description: 'Remove a scheduled job by name.',
+  parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+  async exec(args) {
+    const b = await getBackend();
+    return b.remove(args.name);
+  },
+};
+
+const cron_list = {
+  name: 'cron_list', category: 'scheduling', sensitive: true,
+  description: 'List scheduled jobs.',
+  parameters: { type: 'object', properties: {} },
+  async exec() {
+    const b = await getBackend();
+    return { ok: true, jobs: await b.list() };
+  },
+};
+
+export const TOOLS = [cron_add, cron_remove, cron_list];

package/mas/tools/web.mjs

@@ -0,0 +1,137 @@
+// web — web_fetch (undici, SSRF block), web_search (Brave/Tavily/SerpAPI when
+// an API key env var is set), url_extract (extract links from HTML).
+// SSRF policy: reject loopback, RFC1918 private, link-local, file:, ftp:,
+// and any non-http(s) scheme.
+
+import { fetch } from 'undici';
+import dns from 'node:dns/promises';
+
+const PRIVATE_V4 = [
+  /^10\./, /^192\.168\./, /^172\.(1[6-9]|2\d|3[0-1])\./,
+  /^127\./, /^169\.254\./, /^0\./, /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+
+async function isSafeUrl(url) {
+  let u;
+  try { u = new URL(url); } catch { return { ok: false, error: 'bad URL' }; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: `scheme ${u.protocol} blocked` };
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host === '0.0.0.0') return { ok: false, error: 'loopback blocked (SSRF)' };
+  if (PRIVATE_V4.some(re => re.test(host))) return { ok: false, error: 'private address blocked (SSRF)' };
+  if (host.includes(':')) return { ok: false, error: 'IPv6 disabled' };
+  if (!/^[a-z0-9.-]+$/i.test(host)) return { ok: false, error: 'bad host' };
+  try {
+    const addrs = await dns.lookup(host, { all: true });
+    for (const a of addrs) {
+      if (PRIVATE_V4.some(re => re.test(a.address))) return { ok: false, error: 'resolves to private address (SSRF)' };
+      if (a.address === '127.0.0.1' || a.address === '::1') return { ok: false, error: 'resolves to loopback (SSRF)' };
+    }
+  } catch (e) {
+    return { ok: false, error: `dns: ${e.message}` };
+  }
+  return { ok: true };
+}
+
+const web_fetch = {
+  name: 'web_fetch', category: 'net', sensitive: true,
+  description: 'Fetch a public URL. Loopback / private / non-http(s) URLs are blocked.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url:     { type: 'string' },
+      method:  { type: 'string', enum: ['GET', 'POST'] },
+      headers: { type: 'object' },
+      body:    { type: 'string' },
+      maxBytes:{ type: 'number' },
+    },
+    required: ['url'],
+  },
+  async exec(args) {
+    const safe = await isSafeUrl(args.url);
+    if (!safe.ok) return { ok: false, error: `web_fetch: ${safe.error}` };
+    const maxBytes = Math.min(args.maxBytes || 2_000_000, 5_000_000);
+    try {
+      const res = await fetch(args.url, {
+        method: args.method || 'GET',
+        headers: args.headers || {},
+        body: args.body,
+        redirect: 'follow',
+      });
+      const buf = Buffer.from(await res.arrayBuffer());
+      const truncated = buf.length > maxBytes;
+      return {
+        ok: true, status: res.status,
+        headers: Object.fromEntries(res.headers),
+        body: buf.slice(0, maxBytes).toString('utf8'),
+        truncated,
+      };
+    } catch (e) { return { ok: false, error: `web_fetch: ${e.message}` }; }
+  },
+};
+
+const web_search = {
+  name: 'web_search', category: 'net', sensitive: false,
+  description: 'Search the public web via Brave (BRAVE_API_KEY), Tavily (TAVILY_API_KEY), or SerpAPI (SERPAPI_API_KEY).',
+  parameters: {
+    type: 'object',
+    properties: { query: { type: 'string' }, k: { type: 'number' } },
+    required: ['query'],
+  },
+  async exec(args, ctx) {
+    const env = ctx?.env || process.env;
+    if (env.BRAVE_API_KEY) return braveSearch(args, env.BRAVE_API_KEY);
+    if (env.TAVILY_API_KEY) return tavilySearch(args, env.TAVILY_API_KEY);
+    if (env.SERPAPI_API_KEY) return serpApiSearch(args, env.SERPAPI_API_KEY);
+    return { ok: false, error: 'web_search: no provider configured (set BRAVE_API_KEY / TAVILY_API_KEY / SERPAPI_API_KEY)' };
+  },
+};
+
+async function braveSearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${k}`, {
+      headers: { 'X-Subscription-Token': key, 'Accept': 'application/json' },
+    });
+    const j = await r.json();
+    return { ok: true, results: (j?.web?.results || []).slice(0, k).map(x => ({ title: x.title, url: x.url, snippet: x.description })) };
+  } catch (e) { return { ok: false, error: `brave: ${e.message}` }; }
+}
+async function tavilySearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch('https://api.tavily.com/search', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ api_key: key, query, max_results: k }),
+    });
+    const j = await r.json();
+    return { ok: true, results: (j?.results || []).slice(0, k).map(x => ({ title: x.title, url: x.url, snippet: x.content })) };
+  } catch (e) { return { ok: false, error: `tavily: ${e.message}` }; }
+}
+async function serpApiSearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch(`https://serpapi.com/search.json?q=${encodeURIComponent(query)}&num=${k}&api_key=${key}`);
+    const j = await r.json();
+    return { ok: true, results: (j?.organic_results || []).slice(0, k).map(x => ({ title: x.title, url: x.link, snippet: x.snippet })) };
+  } catch (e) { return { ok: false, error: `serpapi: ${e.message}` }; }
+}
+
+const url_extract = {
+  name: 'url_extract', category: 'net', sensitive: false,
+  description: 'Extract all href URLs from an HTML string.',
+  parameters: {
+    type: 'object',
+    properties: { html: { type: 'string' }, base: { type: 'string' } },
+    required: ['html'],
+  },
+  async exec(args) {
+    const urls = new Set();
+    const re = /href\s*=\s*["']([^"']+)["']/gi;
+    let m;
+    while ((m = re.exec(args.html))) {
+      try {
+        urls.add(args.base ? new URL(m[1], args.base).toString() : m[1]);
+      } catch { urls.add(m[1]); }
+    }
+    return { ok: true, urls: [...urls] };
+  },
+};
+
+export const TOOLS = [web_fetch, web_search, url_extract];

package/mas/toolsets.mjs

@@ -0,0 +1,64 @@
+// toolsets — named bundles of tool names that an agent can be assigned via
+// `lazyclaw agent edit <name> --toolset coding-min`. Built-ins ship in
+// code; user-defined sets live in <configDir>/toolsets.json.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BUILTIN = {
+  'coding-min':  { tools: ['bash', 'read', 'write', 'edit', 'patch', 'grep', 'git_status', 'git_diff'] },
+  'web-research':{ tools: ['web_fetch', 'web_search', 'url_extract', 'read', 'write', 'recall'] },
+  'devops':      { tools: ['bash', 'git_status', 'git_diff', 'git_log', 'git_commit', 'cron_add', 'cron_list', 'http_request'] },
+  'learning':    { tools: ['recall', 'skill_view', 'skill_create', 'skill_edit', 'memory_read', 'memory_write', 'user_view', 'user_update'] },
+  'media':       { tools: ['image_describe', 'image_generate', 'transcribe'] },
+  'agentic':     { tools: ['task_spawn', 'delegate', 'clarify', 'recall', 'skill_view'] },
+};
+
+function configFile(opts) {
+  const dir = opts?.configDir || process.env.LAZYCLAW_CONFIG_DIR || path.join(process.env.HOME || '.', '.lazyclaw');
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, 'toolsets.json');
+}
+
+function readUser(opts) {
+  const f = configFile(opts);
+  if (!fs.existsSync(f)) return {};
+  try { return JSON.parse(fs.readFileSync(f, 'utf8')); }
+  catch { return {}; }
+}
+
+function writeUser(data, opts) {
+  fs.writeFileSync(configFile(opts), JSON.stringify(data, null, 2));
+}
+
+export function listToolsets(opts) {
+  const user = readUser(opts);
+  const out = [];
+  for (const [name, t] of Object.entries(BUILTIN)) out.push({ name, ...t, source: 'builtin' });
+  for (const [name, t] of Object.entries(user))    out.push({ name, ...t, source: 'user' });
+  return out;
+}
+
+export function resolveToolset(name, opts) {
+  const user = readUser(opts);
+  const t = user[name] || BUILTIN[name];
+  if (!t || !Array.isArray(t.tools)) throw new Error(`toolset "${name}" not found`);
+  return [...t.tools];
+}
+
+export function addToolset({ name, tools }, opts) {
+  if (!name || !Array.isArray(tools)) throw new Error('addToolset: name + tools[] required');
+  if (BUILTIN[name]) throw new Error(`toolset "${name}" is built-in; pick a different name`);
+  const data = readUser(opts);
+  data[name] = { tools };
+  writeUser(data, opts);
+  return data[name];
+}
+
+export function removeToolset(name, opts) {
+  if (BUILTIN[name]) throw new Error(`cannot remove built-in toolset "${name}"`);
+  const data = readUser(opts);
+  delete data[name];
+  writeUser(data, opts);
+  return true;
+}

package/mas/trajectory_export.mjs

@@ -0,0 +1,169 @@
+// mas/trajectory_export.mjs — Phase H1.
+//
+// Trajectory exporter (spec §2.7). Read-only serialiser — never spawns
+// a trainer, never touches weights. Reads JSONL records produced by
+// mas/trajectory_store.mjs and emits one of four downstream formats:
+//
+//   jsonl     — raw transcripts (record verbatim, one per line)
+//   atropos   — NousResearch/atropos: {messages, reward, metadata}
+//   axolotl   — Axolotl ShareGPT: {conversations: [{from, value}]}
+//   openai-ft — OpenAI fine-tune: {messages: [{role, content}]}
+//
+// Filters: --since <Nd|Nh|Nm> (relative window), --outcome <done|failed|abandoned>.
+// `reward` for atropos is null by default per spec Appendix B.6 #22
+// (reward signal undefined for v5.0 — `--reward none` is the default).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const FORMATS = Object.freeze(['atropos', 'axolotl', 'openai-ft', 'jsonl']);
+
+function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+function trajectoriesDir(configDir) {
+  return path.join(configDir, 'trajectories');
+}
+
+// Parse "7d" / "12h" / "30m" into a millisecond window relative to now.
+// Returns null if input is empty/undefined (no filter).
+function parseSince(spec) {
+  if (!spec) return null;
+  const m = String(spec).match(/^(\d+)\s*([dhm])$/i);
+  if (!m) throw new Error(`invalid --since: ${spec} (expected Nd|Nh|Nm)`);
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  const mult = unit === 'd' ? 86400_000 : unit === 'h' ? 3600_000 : 60_000;
+  return Date.now() - n * mult;
+}
+
+function* iterRecords(configDir) {
+  const root = trajectoriesDir(configDir);
+  if (!fs.existsSync(root)) return;
+  const buckets = fs.readdirSync(root).sort();
+  for (const bucket of buckets) {
+    const bdir = path.join(root, bucket);
+    let stat; try { stat = fs.statSync(bdir); } catch { continue; }
+    if (!stat.isDirectory()) continue;
+    for (const f of fs.readdirSync(bdir).sort()) {
+      if (!f.endsWith('.jsonl')) continue;
+      let raw;
+      try { raw = fs.readFileSync(path.join(bdir, f), 'utf8'); } catch { continue; }
+      for (const line of raw.split('\n')) {
+        const s = line.trim();
+        if (!s) continue;
+        try { yield JSON.parse(s); } catch { /* skip corrupt */ }
+      }
+    }
+  }
+}
+
+// Build a uniform message list from a TrajectoryRecord. The store's
+// canonical shape carries systemPrompt + userMessages + turns; downstream
+// formats all want a chronological role+content sequence so we synthesise
+// one here.
+function toMessages(rec) {
+  const out = [];
+  if (rec.systemPrompt) out.push({ role: 'system', content: String(rec.systemPrompt) });
+  for (const u of rec.userMessages || []) {
+    out.push({ role: 'user', content: String(u) });
+  }
+  for (const t of rec.turns || []) {
+    if (!t || !t.role) continue;
+    // turns may already include the user echo; keep them — downstream
+    // trainers expect duplicates filtered at their own dedupe stage.
+    out.push({ role: t.role, content: String(t.content || '') });
+  }
+  return out;
+}
+
+function formatAtropos(rec) {
+  return {
+    messages: toMessages(rec),
+    reward: null,                     // §B.6 #22 default
+    metadata: {
+      id: rec.id,
+      taskId: rec.taskId,
+      agentName: rec.agentName,
+      workerProvider: rec.workerProvider,
+      workerModel: rec.workerModel,
+      outcome: rec.outcome,
+      startedAt: rec.startedAt,
+      endedAt: rec.endedAt,
+    },
+  };
+}
+
+function formatAxolotl(rec) {
+  // ShareGPT role mapping: system→system, user→human, assistant→gpt,
+  // tool→tool. Keeps the channel a downstream Axolotl recipe can filter.
+  const FROM = { system: 'system', user: 'human', assistant: 'gpt', tool: 'tool' };
+  return {
+    conversations: toMessages(rec).map(m => ({
+      from: FROM[m.role] || m.role,
+      value: m.content,
+    })),
+  };
+}
+
+function formatOpenAIFT(rec) {
+  return { messages: toMessages(rec) };
+}
+
+function serialise(rec, format) {
+  switch (format) {
+    case 'jsonl':     return JSON.stringify(rec);
+    case 'atropos':   return JSON.stringify(formatAtropos(rec));
+    case 'axolotl':   return JSON.stringify(formatAxolotl(rec));
+    case 'openai-ft': return JSON.stringify(formatOpenAIFT(rec));
+    default: throw new Error(`unknown format: ${format}`);
+  }
+}
+
+// Public API. Returns { count, outFile, format }. Filesystem side effect
+// is a single .jsonl under <outDir> named `trajectories-<format>-<ts>.jsonl`.
+export async function exportTrajectories({
+  format,
+  configDir,
+  outDir,
+  since,
+  filter = {},
+} = {}) {
+  if (!FORMATS.includes(format)) throw new Error(`unknown format: ${format}`);
+  const cfgDir = configDir || defaultConfigDir();
+  const dest = outDir || path.join(cfgDir, 'exports');
+  fs.mkdirSync(dest, { recursive: true });
+
+  const sinceMs = parseSince(since);
+  const outcomeFilter = filter && filter.outcome;
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const outFile = path.join(dest, `trajectories-${format}-${stamp}.jsonl`);
+  const fd = fs.openSync(outFile, 'w');
+  let count = 0;
+  try {
+    for (const rec of iterRecords(cfgDir)) {
+      if (sinceMs !== null && (rec.startedAt || 0) < sinceMs) continue;
+      if (outcomeFilter && rec.outcome !== outcomeFilter) continue;
+      fs.writeSync(fd, serialise(rec, format) + '\n');
+      count++;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { count, outFile, format };
+}
+
+// Parse `outcome=done` style key=value filter strings into a plain object.
+// Exported so the CLI can share the parser.
+export function parseFilterArg(str) {
+  if (!str) return {};
+  const out = {};
+  for (const part of String(str).split(',')) {
+    const [k, v] = part.split('=').map(s => s && s.trim());
+    if (k && v) out[k] = v;
+  }
+  return out;
+}