svamp-cli 0.2.98 → 0.2.100

package/bin/skills/loop/bin/loop-init.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+// loop-init.mjs — project the loop config into Claude Code's native files.
+// Generates, in a target project dir:
+//   LOOP.md (if absent), .claude/loop/{loop.config.json,loop-state.json,bin/*},
+//   .claude/settings.json hooks (Stop gate + LOOP.md injection),
+//   and (optional) .claude/agents/loop-evaluator.md.
+// Usage:
+//   node loop-init.mjs <dir> --task "..." [--criteria "..."] [--oracle "cmd"]
+//        [--max N] [--evaluator on|off] [--model NAME] [--loop-file LOOP.md]
+import { mkdirSync, writeFileSync, copyFileSync, readFileSync, existsSync, chmodSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith('--')) { a[t.slice(2)] = (argv[i + 1] && !argv[i + 1].startsWith('--')) ? argv[++i] : true; }
+    else a._.push(t);
+  }
+  return a;
+}
+const args = parseArgs(process.argv.slice(2));
+const dir = resolve(args._[0] || process.cwd());
+const loopFile = args['loop-file'] || 'LOOP.md';
+const oracle = typeof args.oracle === 'string' ? args.oracle : null;
+const max = args.max ? Number(args.max) : 20;
+const evaluatorOn = args.evaluator !== 'off';
+const model = typeof args.model === 'string' ? args.model : null;
+const task = typeof args.task === 'string' ? args.task : '(describe the task here)';
+const criteria = typeof args.criteria === 'string' ? args.criteria : null;
+
+const loopDir = join(dir, '.claude', 'loop');
+const binDir = join(loopDir, 'bin');
+mkdirSync(binDir, { recursive: true });
+mkdirSync(join(dir, '.claude', 'agents'), { recursive: true });
+
+// 1. Copy hook scripts so the project is self-contained.
+for (const f of ['state-fp.mjs', 'stop-gate.mjs', 'inject-loop.mjs', 'loop-status.mjs', 'precompact.mjs']) {
+  const dest = join(binDir, f);
+  copyFileSync(join(HERE, f), dest);
+  try { chmodSync(dest, 0o755); } catch {}
+}
+
+// 2. loop.config.json
+const config = {
+  loop_file: loopFile,
+  oracle: oracle ? { command: oracle, timeout_sec: 600 } : null,
+  evaluator: { enabled: evaluatorOn, model },
+  max_iterations: max,
+  budget: (args['max-runtime'] || args['max-tokens']) ? {
+    ...(args['max-runtime'] ? { max_runtime_sec: Number(args['max-runtime']) } : {}),
+    ...(args['max-tokens'] ? { max_tokens: Number(args['max-tokens']) } : {}),
+  } : undefined,
+};
+writeFileSync(join(loopDir, 'loop.config.json'), JSON.stringify(config, null, 2));
+
+// 3. loop-state.json (machine state, daemon/gate-owned)
+writeFileSync(join(loopDir, 'loop-state.json'), JSON.stringify({
+  active: true, iteration: 0, phase: 'running', started_at: new Date().toISOString(),
+}, null, 2));
+
+// 4. LOOP.md (agent + human editable) — only if not present
+const loopPath = join(dir, loopFile);
+if (!existsSync(loopPath)) {
+  writeFileSync(loopPath, `# Loop Task
+
+## Task
+${task}
+
+## Success criteria
+${criteria
+  ? criteria.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => (l.startsWith('-') ? l : `- ${l}`)).join('\n')
+  : '- (define objective success criteria)'}
+${oracle ? `- The oracle passes: \`${oracle}\`` : ''}
+- An independent evaluator confirms the work is genuinely complete.
+
+## Plan
+- (the agent fills this in)
+
+## Progress
+- (the agent appends iteration notes here; this is durable memory)
+`);
+}
+
+// 5. .claude/settings.json hooks (merge if present)
+const settingsPath = join(dir, '.claude', 'settings.json');
+let settings = {};
+if (existsSync(settingsPath)) { try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch {} }
+const node = process.execPath;
+const cmd = (script) => `"${node}" "${join(binDir, script)}"`;
+settings.hooks = settings.hooks || {};
+settings.hooks.SessionStart = [{ hooks: [{ type: 'command', command: cmd('inject-loop.mjs') }] }];
+settings.hooks.UserPromptSubmit = [{ hooks: [{ type: 'command', command: cmd('inject-loop.mjs') }] }];
+settings.hooks.Stop = [{ hooks: [{ type: 'command', command: cmd('stop-gate.mjs') }] }];
+settings.hooks.PreCompact = [{ hooks: [{ type: 'command', command: cmd('precompact.mjs') }] }];
+writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+
+// 6. Evaluator agent (materialized) — optional
+if (evaluatorOn) {
+  const fm = ['---', 'name: loop-evaluator',
+    'description: Skeptical independent reviewer that decides if a loop task is genuinely complete.',
+    'tools: Read, Bash, Grep, Glob', ...(model ? [`model: ${model}`] : []), '---', ''].join('\n');
+  writeFileSync(join(dir, '.claude', 'agents', 'loop-evaluator.md'), fm +
+`You are an INDEPENDENT, skeptical reviewer. You did NOT write the code under review.
+
+You are given: the task/goal (from LOOP.md), the current diff, and the oracle output.
+Decide whether the work is GENUINELY and COMPLETELY done — default to "continue" on any doubt.
+
+Check:
+- Does it actually satisfy every success criterion in LOOP.md (not just look plausible)?
+- Does the oracle genuinely pass, and does it actually cover the requirement?
+- Edge cases, stubbed/faked functionality, regressions.
+
+Return ONLY a JSON object:
+{"verdict":"done"|"continue","reason":"<concise>","guidance":"<what to fix if continue>"}
+Be strict. A false "done" is far worse than one more iteration.
+`);
+}
+
+console.log(`✅ loop initialised in ${dir}
+  task file : ${loopFile}
+  oracle    : ${oracle || '(none)'}
+  evaluator : ${evaluatorOn ? 'on' + (model ? ` (${model})` : '') : 'off'}
+  max iters : ${max}
+  hooks     : SessionStart, UserPromptSubmit, Stop  (.claude/settings.json)`);

package/bin/skills/loop/bin/loop-status.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// loop-status.mjs — show a loop's current state + per-iteration history timeline.
+// Usage: node loop-status.mjs [project-dir] [--json] [-n <count>]
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+const nIdx = args.indexOf('-n');
+const limit = nIdx !== -1 ? Number(args[nIdx + 1]) : 20;
+const dir = resolve(args.find((a) => !a.startsWith('-') && a !== String(limit)) || process.cwd());
+const LOOP_DIR = join(dir, '.claude', 'loop');
+
+const readJSON = (p, f) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return f; } };
+const state = readJSON(join(LOOP_DIR, 'loop.config.json'), null)
+  ? readJSON(join(LOOP_DIR, 'loop-state.json'), {})
+  : null;
+
+let history = [];
+try {
+  history = readFileSync(join(LOOP_DIR, 'history.jsonl'), 'utf8')
+    .split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+} catch {}
+
+if (json) {
+  console.log(JSON.stringify({ state, history: history.slice(-limit) }, null, 2));
+} else if (!state) {
+  console.log('No loop configured in', dir);
+} else {
+  const icon = { done: '✅', gave_up: '🛑', continue: '🔄', running: '🔄' };
+  console.log(`Loop in ${dir}`);
+  console.log(`  phase: ${state.phase || '?'} | iteration: ${state.iteration ?? 0}${state.gave_up_reason ? ` | gave up: ${state.gave_up_reason}` : ''}`);
+  if (state.last_oracle) console.log(`  oracle: ${String(state.last_oracle).split('\n')[0]}`);
+  console.log(`  history (last ${Math.min(limit, history.length)} of ${history.length}):`);
+  for (const h of history.slice(-limit)) {
+    console.log(`    ${icon[h.decision] || '·'} iter ${h.iteration} [${h.decision}] ${h.ts}${h.reason ? ' — ' + h.reason : ''}`);
+  }
+}

package/bin/skills/loop/bin/precompact.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// precompact.mjs — Claude Code `PreCompact` hook. Records a compaction event in
+// the loop's history timeline (so the monitor shows context resets) and reminds
+// the agent that LOOP.md is the durable handoff across compaction.
+import { readFileSync, appendFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROJECT = resolve(HERE, '..', '..', '..');
+const LOOP_DIR = join(PROJECT, '.claude', 'loop');
+
+let active = false;
+try { active = JSON.parse(readFileSync(join(LOOP_DIR, 'loop-state.json'), 'utf8')).active !== false; } catch {}
+if (!active) process.exit(0);
+
+let iteration = 0;
+try { iteration = JSON.parse(readFileSync(join(LOOP_DIR, 'loop-state.json'), 'utf8')).iteration || 0; } catch {}
+try {
+  appendFileSync(join(LOOP_DIR, 'history.jsonl'),
+    JSON.stringify({ ts: new Date().toISOString(), iteration, decision: 'compaction' }) + '\n');
+} catch {}
+
+// Context is about to be compacted — LOOP.md (auto-injected on the next turn) is
+// the durable handoff. Nudge the agent to ensure its progress is captured there.
+process.stdout.write('Context is being compacted. LOOP.md is your durable memory across this reset — ensure your latest progress, plan, and remaining work are written there before continuing.');
+process.exit(0);

package/bin/skills/loop/bin/routine-cli.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// routine-cli.mjs — manage + run routines.
+//   add/list/remove/enable/disable/run-now  — CRUD + manual fire
+//   serve [--port N]                         — scheduler tick + webhook HTTP server
+//
+// Delivery uses the svamp CLI: a fired routine becomes a message (or loop
+// kickoff) into the bound session via `svamp session send`.
+import { execFileSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RoutineStore } from './routine-store.mjs';
+import { RoutineRunner } from './routine-runner.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const LOOP_INIT = join(HERE, 'loop-init.mjs');
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t.startsWith('--')) a[t.slice(2)] = (argv[i + 1] && !argv[i + 1].startsWith('--')) ? argv[++i] : true;
+    else a._.push(t);
+  }
+  return a;
+}
+
+// ---- real delivery via svamp CLI ---------------------------------------
+async function cliDeliver({ routine, resolved }) {
+  const sid = routine.session_id;
+  if (resolved.kind === 'message') {
+    execFileSync('svamp', ['session', 'send', sid, resolved.text], { stdio: 'pipe' });
+    return;
+  }
+  // loop action: set up the loop in the project dir, then kick the session.
+  const dir = routine.action.loop?.dir || routine.dir;
+  if (dir) {
+    const initArgs = [LOOP_INIT, resolve(dir), '--task', resolved.task || routine.action.loop?.task || '(task)'];
+    if (routine.action.loop?.oracle) initArgs.push('--oracle', routine.action.loop.oracle);
+    initArgs.push('--evaluator', routine.action.loop?.evaluator || 'off');
+    execFileSync(process.execPath, initArgs, { stdio: 'pipe' });
+  }
+  execFileSync('svamp', ['session', 'send', sid,
+    `Begin the loop (LOOP MODE). Task: ${resolved.task}. Iterate until the gate lets you stop.`], { stdio: 'pipe' });
+}
+
+function buildRoutineFromArgs(a) {
+  const r = { session_id: a.session, name: a.name || 'routine', overlap: a.overlap || 'queue' };
+  if (a.schedule) r.trigger = { type: 'schedule', cron: a.schedule, missed: a.missed || 'skip', tz: a.tz };
+  else if (a.webhook || a.api) r.trigger = { type: a.api ? 'api' : 'webhook', methods: a.get ? ['GET'] : ['GET', 'POST'], public: !!a.public };
+  else r.trigger = { type: 'manual' };
+  if (a.loop) r.action = { kind: 'loop', task_template: a.task || '', loop: { dir: a.dir, oracle: a.oracle, evaluator: a.evaluator || 'off' } };
+  else r.action = { kind: 'message', template: a.message || a.task || 'run' };
+  return r;
+}
+
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  const cmd = a._[0];
+  const store = new RoutineStore();
+  const runner = new RoutineRunner({ store, deliver: cliDeliver, log: console.error });
+
+  switch (cmd) {
+    case 'add': {
+      if (!a.session) { console.error('--session <id> required'); process.exit(1); }
+      const r = store.save(buildRoutineFromArgs(a));
+      console.log(`✅ added routine ${r.id} (${r.name}) trigger=${r.trigger.type} action=${r.action.kind}`);
+      if (r.trigger.key) console.log(`   webhook key: ${r.trigger.key}`);
+      break;
+    }
+    case 'list': {
+      const rs = store.list();
+      if (a.json) { console.log(JSON.stringify(rs, null, 2)); break; }
+      if (!rs.length) { console.log('(no routines)'); break; }
+      for (const r of rs) console.log(`${r.enabled ? '●' : '○'} ${r.id}  ${r.name}  [${r.trigger.type}${r.trigger.cron ? ' ' + r.trigger.cron : ''}] -> ${r.action.kind}  session=${r.session_id}`);
+      break;
+    }
+    case 'remove': ok(store.remove(a._[1]), `removed ${a._[1]}`); break;
+    case 'enable': store.setEnabled(a._[1], true); console.log(`enabled ${a._[1]}`); break;
+    case 'disable': store.setEnabled(a._[1], false); console.log(`disabled ${a._[1]}`); break;
+    case 'run-now': console.log(JSON.stringify(await runner.runNow(a._[1], {}), null, 2)); break;
+    case 'serve': await serve(runner, store, Number(a.port) || 8722); break;
+    default:
+      console.log(`usage: routine-cli <add|list|remove|enable|disable|run-now|serve>
+  add --session <id> --name <n> [--schedule "*/5 * * * *" [--missed catchup]] [--webhook|--api [--get] [--public]] (--message "..." | --loop --dir <path> --task "..." [--oracle "cmd"])
+  serve [--port 8722]`);
+  }
+  function ok(c, m) { console.log(c ? '✅ ' + m : '✗ ' + m); }
+}
+
+async function serve(runner, store, port) {
+  // catch up missed schedules, then tick every 20s (per-minute dedupe inside).
+  await runner.catchUp(new Date(Date.now() - 24 * 3600 * 1000), new Date());
+  const timer = setInterval(() => { runner.tick(new Date()).catch((e) => console.error('tick error', e)); }, 20000);
+
+  const server = createServer((req, res) => {
+    const u = new URL(req.url, `http://localhost:${port}`);
+    if (u.pathname === '/' || u.pathname === '/health') { res.writeHead(200).end('routines ok'); return; }
+    const m = u.pathname.match(/^\/routine\/([\w.-]+)$/);
+    if (!m) { res.writeHead(404).end('not found'); return; }
+    const id = m[1];
+    const key = u.searchParams.get('key');
+    const query = Object.fromEntries(u.searchParams.entries());
+    let chunks = '';
+    req.on('data', (c) => { chunks += c; if (chunks.length > 1e6) req.destroy(); });
+    req.on('end', async () => {
+      let body = {}; try { body = chunks ? JSON.parse(chunks) : {}; } catch {}
+      const result = await runner.webhook(id, { key, method: req.method, body, query });
+      res.writeHead(result.status || 200, { 'content-type': 'application/json' }).end(JSON.stringify(result));
+    });
+  });
+  server.listen(port, () => {
+    console.log(`🪝 routine server on http://localhost:${port}`);
+    console.log(`   webhook URL pattern: http://localhost:${port}/routine/<id>?key=<key>`);
+    console.log(`   expose publicly:  svamp service expose routines --port ${port}`);
+    console.log(`   scheduler: ticking every 20s`);
+  });
+  process.on('SIGINT', () => { clearInterval(timer); server.close(); process.exit(0); });
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/bin/skills/loop/bin/routine-core.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// routine-core.mjs — dependency-free primitives for the routine layer:
+//   * cron matching + next-fire (standard 5-field cron)
+//   * payload templating (${body.x}/${query.x}/${now}) for trigger -> action
+//   * routine spec validation
+// No external deps (mirrors the loop gate). Pure + unit-testable.
+
+// ---- cron ---------------------------------------------------------------
+const FIELD_RANGES = [
+  [0, 59], // minute
+  [0, 23], // hour
+  [1, 31], // day of month
+  [1, 12], // month
+  [0, 6],  // day of week (0=Sun)
+];
+
+function parseField(token, [min, max]) {
+  const set = new Set();
+  for (const part of token.split(',')) {
+    let m;
+    if (part === '*') { for (let i = min; i <= max; i++) set.add(i); }
+    else if ((m = part.match(/^\*\/(\d+)$/))) { const s = +m[1]; for (let i = min; i <= max; i += s) set.add(i); }
+    else if ((m = part.match(/^(\d+)-(\d+)\/(\d+)$/))) { const [, a, b, s] = m; for (let i = +a; i <= +b; i += +s) set.add(i); }
+    else if ((m = part.match(/^(\d+)-(\d+)$/))) { const [, a, b] = m; for (let i = +a; i <= +b; i++) set.add(i); }
+    else if ((m = part.match(/^(\d+)$/))) { set.add(+m[1]); }
+    else throw new Error(`invalid cron field: "${token}"`);
+  }
+  for (const v of set) if (v < min || v > max) throw new Error(`cron value ${v} out of range [${min},${max}]`);
+  return set;
+}
+
+export function parseCron(expr) {
+  const fields = String(expr).trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error(`cron must have 5 fields, got ${fields.length}: "${expr}"`);
+  const [minute, hour, dom, month, dow] = fields.map((f, i) => parseField(f, FIELD_RANGES[i]));
+  const domRestricted = fields[2] !== '*';
+  const dowRestricted = fields[4] !== '*';
+  return { minute, hour, dom, month, dow, domRestricted, dowRestricted };
+}
+
+/** Does `date` (minute resolution) match the cron expr? */
+export function cronMatches(expr, date) {
+  const c = typeof expr === 'string' ? parseCron(expr) : expr;
+  if (!c.minute.has(date.getMinutes())) return false;
+  if (!c.hour.has(date.getHours())) return false;
+  if (!c.month.has(date.getMonth() + 1)) return false;
+  const domOk = c.dom.has(date.getDate());
+  const dowOk = c.dow.has(date.getDay());
+  // Standard cron: when BOTH dom and dow are restricted, match is OR; else AND.
+  if (c.domRestricted && c.dowRestricted) return domOk || dowOk;
+  return domOk && dowOk;
+}
+
+/** First firing strictly after `from` (defaults to now-ish; caller passes Date). */
+// Return a Date whose LOCAL fields equal the wall-clock time in `tz`, so
+// cronMatches (which reads local getHours/getMinutes/...) effectively matches
+// against that timezone. Falls back to the input on any error.
+export function inZone(date, tz) {
+  if (!tz) return date;
+  try {
+    const p = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour12: false,
+      year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })
+      .formatToParts(date).reduce((o, x) => { o[x.type] = x.value; return o; }, {});
+    return new Date(+p.year, +p.month - 1, +p.day, +(p.hour === '24' ? 0 : p.hour), +p.minute);
+  } catch { return date; }
+}
+
+export function nextFire(expr, from, tz) {
+  const c = parseCron(expr);
+  const d = new Date(from.getTime());
+  d.setSeconds(0, 0);
+  d.setMinutes(d.getMinutes() + 1); // strictly after
+  const limit = 366 * 24 * 60; // scan up to ~1 year of minutes
+  for (let i = 0; i < limit; i++) {
+    if (cronMatches(c, tz ? inZone(d, tz) : d)) return new Date(d.getTime());
+    d.setMinutes(d.getMinutes() + 1);
+  }
+  return null;
+}
+
+// ---- templating ---------------------------------------------------------
+function resolvePath(ctx, path) {
+  return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), ctx);
+}
+/** Replace ${a.b.c} from ctx; missing -> empty string. No code eval. */
+export function renderTemplate(template, ctx) {
+  return String(template).replace(/\$\{([\w.$]+)\}/g, (_, p) => {
+    const v = resolvePath(ctx, p);
+    return v == null ? '' : (typeof v === 'object' ? JSON.stringify(v) : String(v));
+  });
+}
+
+// ---- spec validation ----------------------------------------------------
+const TRIGGER_TYPES = ['manual', 'schedule', 'webhook', 'api'];
+const ACTION_KINDS = ['message', 'loop'];
+const OVERLAP = ['queue', 'skip', 'replace'];
+
+export function validateRoutine(r) {
+  const errs = [];
+  if (!r || typeof r !== 'object') return ['routine must be an object'];
+  if (!r.session_id) errs.push('session_id required');
+  if (!r.name) errs.push('name required');
+  const t = r.trigger;
+  if (!t || !TRIGGER_TYPES.includes(t.type)) errs.push(`trigger.type must be one of ${TRIGGER_TYPES.join('|')}`);
+  if (t?.type === 'schedule') {
+    try { parseCron(t.cron); } catch (e) { errs.push(`trigger.cron: ${e.message}`); }
+    if (t.missed && !['catchup', 'skip'].includes(t.missed)) errs.push('trigger.missed must be catchup|skip');
+  }
+  const a = r.action;
+  if (!a || !ACTION_KINDS.includes(a.kind)) errs.push(`action.kind must be one of ${ACTION_KINDS.join('|')}`);
+  if (a?.kind === 'message' && !a.template) errs.push('action.template required for message action');
+  if (a?.kind === 'loop' && !a.loop && !a.task_template) errs.push('action.loop or action.task_template required for loop action');
+  if (r.overlap && !OVERLAP.includes(r.overlap)) errs.push(`overlap must be one of ${OVERLAP.join('|')}`);
+  // Security: a public (keyless) webhook + loop action = unauthenticated task
+  // injection into the session. Require a key for loop actions.
+  if ((t?.type === 'webhook' || t?.type === 'api') && t.public && a?.kind === 'loop')
+    errs.push('a public webhook/api may not use a loop action (unauthenticated task injection) — use a message action or require a key');
+  return errs;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === 'next') console.log(nextFire(rest.join(' '), new Date())?.toISOString() || 'no fire');
+  else if (cmd === 'matches') console.log(cronMatches(rest.slice(0, 5).join(' '), new Date()));
+  else console.log('usage: routine-core.mjs next "<cron>" | matches "<cron>"');
+}

package/bin/skills/loop/bin/routine-runner.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// routine-runner.mjs — fires routines (schedule tick / webhook / manual),
+// applies overlap + missed-run policies, and delivers the resolved action
+// (message | loop) via an injectable `deliver` fn. Pure logic; the actual
+// CLI delivery + timer + HTTP server live in routine-cli.mjs.
+import { cronMatches, renderTemplate, nextFire, inZone } from './routine-core.mjs';
+
+const minuteKey = (d) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}-${d.getHours()}-${d.getMinutes()}`;
+
+export class RoutineRunner {
+  /** @param {{store, deliver:(ctx)=>Promise<any>, now?:()=>Date, onReplace?:(id)=>void, log?:Function}} o */
+  constructor({ store, deliver, now = () => new Date(), onReplace, log = () => {} }) {
+    this.store = store; this.deliver = deliver; this.now = now; this.onReplace = onReplace; this.log = log;
+    this.active = new Set();           // routine ids with an in-flight loop run
+    this._firedMinute = new Map();     // id -> minuteKey (in-memory dedupe within a process)
+  }
+
+  resolveAction(routine, payload = {}) {
+    const ctx = { ...payload, now: this.now().toISOString(), routine: { id: routine.id, name: routine.name } };
+    const a = routine.action;
+    if (a.kind === 'message') return { kind: 'message', text: renderTemplate(a.template, ctx) };
+    const task = renderTemplate(a.task_template || a.loop?.task || '', ctx);
+    return { kind: 'loop', task, loop: a.loop };
+  }
+
+  markDone(id) { this.active.delete(id); }
+
+  /** Deliveries counted today via a dedicated counter (NOT derived from the
+   * capped last_runs audit, which would undercount past 20 runs/day). */
+  _deliveredToday(routine) {
+    const today = this.now().toDateString();
+    return routine.daily && routine.daily.date === today ? routine.daily.n : 0;
+  }
+
+  /** Core fire path with overlap + daily-cap policy. via = 'schedule'|'webhook'|'api'|'manual'.
+   * NOTE: `active` guards genuinely CONCURRENT in-flight deliveries only — the runner
+   * cannot observe a spawned loop's full duration (delivery is fire-and-forget), so it
+   * is cleared once delivery returns. True loop-duration overlap needs a loop-state
+   * signal (future). `replace` calls onReplace (best-effort) then proceeds. */
+  async fire(routine, payload = {}, via = 'manual') {
+    if (!routine.enabled) return { skipped: 'disabled' };
+    // Defense-in-depth (also enforced at validate time): never run a loop action
+    // from a public/keyless webhook (unauthenticated task injection).
+    if (routine.action?.kind === 'loop' && (routine.trigger?.type === 'webhook' || routine.trigger?.type === 'api') && routine.trigger?.public)
+      return { skipped: 'forbidden (public webhook + loop)' };
+    const today = this.now().toDateString();
+    // Reserve a daily slot SYNCHRONOUSLY (before any await) so concurrent fires
+    // serialize on the JS event loop and cannot all read n=0 and over-deliver.
+    const r0 = this.store.get(routine.id) || routine;
+    const usedToday = (r0.daily && r0.daily.date === today) ? r0.daily.n : 0;
+    if (routine.daily_cap && usedToday >= routine.daily_cap) {
+      this.store.recordRun(routine.id, { via, delivered: routine.action.kind, outcome: 'skipped (daily cap)' });
+      return { skipped: 'daily_cap' };
+    }
+    if (this.active.has(routine.id)) {
+      if (routine.overlap === 'skip') { this.store.recordRun(routine.id, { via, delivered: routine.action.kind, outcome: 'skipped (busy)' }); return { skipped: 'busy' }; }
+      if (routine.overlap === 'replace') { try { this.onReplace?.(routine.id); } catch {} }
+      // 'queue'/'replace' -> proceed
+    }
+    this.active.add(routine.id);
+    if (routine.daily_cap) { r0.daily = { date: today, n: usedToday + 1 }; this.store.save(r0); } // reserve
+    const resolved = this.resolveAction(routine, payload);
+    let outcome = 'delivered';
+    try {
+      await this.deliver({ routine, action: routine.action, resolved, payload, via });
+    } catch (e) {
+      outcome = 'error: ' + (e?.message || e);
+      if (routine.daily_cap) { const rb = this.store.get(routine.id); if (rb?.daily?.date === today && rb.daily.n > 0) { rb.daily.n -= 1; this.store.save(rb); } } // roll back reservation
+    } finally { this.active.delete(routine.id); }
+    const r = this.store.get(routine.id) || routine;
+    r.last_fired_at = this.now().toISOString();
+    r.last_runs = [{ firedAt: r.last_fired_at, via, delivered: resolved.kind, outcome }, ...(r.last_runs || [])].slice(0, 20);
+    this.store.save(r);
+    return { fired: true, via, resolved, outcome };
+  }
+
+  /** Schedule tick — fire any matching schedule routine once per minute. */
+  async tick(date = this.now()) {
+    const results = [];
+    for (const r of this.store.list()) {
+      if (!r.enabled || r.trigger?.type !== 'schedule') continue;
+      if (!cronMatches(r.trigger.cron, inZone(date, r.trigger.tz))) continue;
+      const mk = minuteKey(date);
+      if (this._firedMinute.get(r.id) === mk) continue; // already fired this minute
+      this._firedMinute.set(r.id, mk);
+      results.push({ id: r.id, ...(await this.fire(r, { tick: date.toISOString() }, 'schedule')) });
+    }
+    return results;
+  }
+
+  /** Webhook/api fire: validate key + method, then fire with payload. */
+  async webhook(id, { key, method = 'POST', body = {}, query = {} } = {}) {
+    const r = this.store.get(id);
+    if (!r) return { status: 404, error: 'routine not found' };
+    if (r.trigger?.type !== 'webhook' && r.trigger?.type !== 'api') return { status: 400, error: 'not a webhook routine' };
+    if (!r.enabled) return { status: 409, error: 'routine disabled' };
+    if (!r.trigger.public && r.trigger.key && key !== r.trigger.key) return { status: 401, error: 'bad key' };
+    const methods = r.trigger.methods || ['GET', 'POST'];
+    if (!methods.includes(method)) return { status: 405, error: 'method not allowed' };
+    const res = await this.fire(r, { body, query }, r.trigger.type);
+    return { status: 200, ...res };
+  }
+
+  async runNow(id, payload = {}) {
+    const r = this.store.get(id);
+    if (!r) return { error: 'not found' };
+    return this.fire(r, payload, 'manual');
+  }
+
+  /** On startup, fire schedule routines whose time was missed while down (catchup). */
+  async catchUp(sinceDate, nowDate = this.now()) {
+    const results = [];
+    for (const r of this.store.list()) {
+      if (!r.enabled || r.trigger?.type !== 'schedule' || r.trigger.missed !== 'catchup') continue;
+      const deadlineMs = (r.trigger.deadline_sec || 3600) * 1000;
+      const since = new Date(Math.max(sinceDate.getTime(), nowDate.getTime() - deadlineMs));
+      const due = nextFire(r.trigger.cron, since, r.trigger.tz);   // first scheduled time after `since` (in the routine's tz)
+      if (due && due <= nowDate) {
+        const last = r.last_fired_at ? new Date(r.last_fired_at) : new Date(0);
+        if (last < due) results.push({ id: r.id, ...(await this.fire(r, { catchup: due.toISOString() }, 'schedule')) });
+      }
+    }
+    return results;
+  }
+}

package/bin/skills/loop/bin/routine-store.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// routine-store.mjs — persistence + CRUD for routine specs.
+// Specs live as JSON files under a routines dir (default ~/.svamp/routines/),
+// one file per routine, atomic writes, restored on restart.
+import { mkdirSync, writeFileSync, renameSync, readdirSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { validateRoutine } from './routine-core.mjs';
+
+export function defaultRoutinesDir() {
+  return process.env.SVAMP_ROUTINES_DIR || join(homedir(), '.svamp', 'routines');
+}
+const genId = () => 'rt_' + randomBytes(5).toString('hex');
+const genKey = () => randomBytes(18).toString('base64url');
+
+export class RoutineStore {
+  constructor(dir = defaultRoutinesDir()) { this.dir = dir; mkdirSync(dir, { recursive: true }); }
+  _path(id) { return join(this.dir, `${id}.json`); }
+
+  list() {
+    return readdirSync(this.dir).filter((f) => f.endsWith('.json')).map((f) => {
+      try { return JSON.parse(readFileSync(join(this.dir, f), 'utf8')); } catch { return null; }
+    }).filter(Boolean);
+  }
+  get(id) { try { return JSON.parse(readFileSync(this._path(id), 'utf8')); } catch { return null; } }
+
+  /** Create/update. Assigns id, key (for webhook/api), defaults; validates. */
+  save(routine) {
+    const r = { overlap: 'queue', enabled: true, last_runs: [], ...routine };
+    if (!r.id) r.id = genId();
+    if ((r.trigger?.type === 'webhook' || r.trigger?.type === 'api') && !r.trigger.key) r.trigger.key = genKey();
+    const errs = validateRoutine(r);
+    if (errs.length) throw new Error('invalid routine: ' + errs.join('; '));
+    const tmp = this._path(r.id) + '.tmp';
+    writeFileSync(tmp, JSON.stringify(r, null, 2));
+    renameSync(tmp, this._path(r.id));
+    return r;
+  }
+  remove(id) { const p = this._path(id); if (existsSync(p)) { rmSync(p); return true; } return false; }
+  setEnabled(id, enabled) { const r = this.get(id); if (!r) return null; r.enabled = enabled; return this.save(r); }
+
+  /** Append a capped run-history entry. */
+  recordRun(id, entry) {
+    const r = this.get(id); if (!r) return null;
+    r.last_runs = [{ firedAt: new Date().toISOString(), ...entry }, ...(r.last_runs || [])].slice(0, 20);
+    return this.save(r);
+  }
+}