lazyclaw 3.99.3 → 3.99.4

package/config_features.mjs

@@ -0,0 +1,241 @@
+// Config-driven CLI surfaces — auth-profile rotation, pairing
+// (sender allowlist), nodes (device registration), and outbound
+// messaging webhooks. Each one is a thin record-keeper layered on
+// top of the existing readConfig / writeConfig pair: the CLI never
+// stores a separate file.
+//
+// All four were called out as OpenClaw parity gaps; we implement
+// them as plain config keys here so the SAME `lazyclaw config get`
+// flow keeps working and `lazyclaw export | jq` already covers
+// backups without us writing a second exporter.
+
+// Auth profiles ────────────────────────────────────────────────
+//
+// cfg.authProfiles[provider] = [{ key, label, addedAt }]
+//
+// Picked over a single `api-key` field so a user can keep multiple
+// keys for the same provider (work / personal / spare) and rotate
+// when one hits a rate limit. The rotation cursor lives in
+// cfg.authActiveProfile[provider] = label so the choice persists
+// across invocations.
+
+export function authList(cfg, provider) {
+  const profiles = (cfg.authProfiles || {})[provider] || [];
+  return profiles.map((p) => ({
+    label: p.label,
+    addedAt: p.addedAt,
+    keyMasked: maskKey(p.key),
+  }));
+}
+
+export function authAdd(cfg, provider, key, label) {
+  if (!provider) throw new Error('provider is required');
+  if (!key) throw new Error('key is required');
+  cfg.authProfiles = cfg.authProfiles || {};
+  cfg.authProfiles[provider] = cfg.authProfiles[provider] || [];
+  const lbl = (label || `profile-${cfg.authProfiles[provider].length + 1}`).trim();
+  if (cfg.authProfiles[provider].some((p) => p.label === lbl)) {
+    throw new Error(`profile "${lbl}" already exists for ${provider}`);
+  }
+  cfg.authProfiles[provider].push({ key, label: lbl, addedAt: new Date().toISOString() });
+  // First-added profile becomes active so the user gets working
+  // auth rotation without a separate `auth use` step.
+  cfg.authActiveProfile = cfg.authActiveProfile || {};
+  if (!cfg.authActiveProfile[provider]) cfg.authActiveProfile[provider] = lbl;
+  return lbl;
+}
+
+export function authRemove(cfg, provider, label) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  const idx = arr.findIndex((p) => p.label === label);
+  if (idx < 0) throw new Error(`no profile "${label}" for ${provider}`);
+  arr.splice(idx, 1);
+  if ((cfg.authActiveProfile || {})[provider] === label) {
+    cfg.authActiveProfile[provider] = arr[0]?.label || '';
+  }
+}
+
+export function authUse(cfg, provider, label) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  if (!arr.some((p) => p.label === label)) {
+    throw new Error(`no profile "${label}" for ${provider}`);
+  }
+  cfg.authActiveProfile = cfg.authActiveProfile || {};
+  cfg.authActiveProfile[provider] = label;
+}
+
+export function authRotate(cfg, provider) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  if (arr.length < 2) return null;
+  cfg.authActiveProfile = cfg.authActiveProfile || {};
+  const cur = cfg.authActiveProfile[provider];
+  const idx = arr.findIndex((p) => p.label === cur);
+  const next = arr[(idx + 1) % arr.length];
+  cfg.authActiveProfile[provider] = next.label;
+  return next.label;
+}
+
+// Resolves the api-key the chat / agent flow should send. Falls
+// back to the legacy single `api-key` field so existing configs
+// keep working without a migration.
+export function resolveApiKey(cfg, provider) {
+  const arr = (cfg.authProfiles || {})[provider] || [];
+  const active = (cfg.authActiveProfile || {})[provider];
+  const hit = arr.find((p) => p.label === active) || arr[0];
+  if (hit?.key) return hit.key;
+  return cfg['api-key'] || '';
+}
+
+function maskKey(key) {
+  if (!key) return '';
+  const s = String(key);
+  if (s.length <= 8) return '****' + s.slice(-2);
+  return s.slice(0, 4) + '…' + s.slice(-4);
+}
+
+// Pairing (sender allowlist) ───────────────────────────────────
+//
+// cfg.pairing = [{ id, label, addedAt }]
+//
+// Sender ids are the opaque strings the messaging layer hands us
+// (e.g. Slack member id, Discord user id, phone number for SMS
+// bridges). Anything that isn't on the allowlist gets rejected by
+// the inbound handler — same shape as openclaw `pairing approve`.
+
+export function pairingList(cfg) {
+  return (cfg.pairing || []).slice();
+}
+
+export function pairingAdd(cfg, id, label) {
+  if (!id) throw new Error('id is required');
+  cfg.pairing = cfg.pairing || [];
+  if (cfg.pairing.some((p) => p.id === id)) {
+    throw new Error(`id "${id}" already paired`);
+  }
+  cfg.pairing.push({ id, label: label || '', addedAt: new Date().toISOString() });
+}
+
+export function pairingRemove(cfg, id) {
+  const arr = cfg.pairing || [];
+  const idx = arr.findIndex((p) => p.id === id);
+  if (idx < 0) throw new Error(`id "${id}" not found`);
+  arr.splice(idx, 1);
+}
+
+export function pairingHas(cfg, id) {
+  return (cfg.pairing || []).some((p) => p.id === id);
+}
+
+// Nodes (device registration) ──────────────────────────────────
+//
+// cfg.nodes = [{ id, platform, label, registeredAt }]
+//
+// CLI side of `openclaw nodes` — the actual mobile companion apps
+// aren't in scope here, but the registration table lets a future
+// app (or just `curl`) authenticate against `lazyclaw daemon`.
+// Platform is free-form ('macos' / 'ios' / 'android' / 'web' /
+// 'cli') so we don't constrain future surfaces.
+
+export function nodesList(cfg) {
+  return (cfg.nodes || []).slice();
+}
+
+export function nodesRegister(cfg, id, platform = 'cli', label = '') {
+  if (!id) throw new Error('id is required');
+  cfg.nodes = cfg.nodes || [];
+  if (cfg.nodes.some((n) => n.id === id)) {
+    throw new Error(`node "${id}" already registered`);
+  }
+  cfg.nodes.push({
+    id,
+    platform: String(platform || 'cli').toLowerCase(),
+    label: label || '',
+    registeredAt: new Date().toISOString(),
+  });
+}
+
+export function nodesRemove(cfg, id) {
+  const arr = cfg.nodes || [];
+  const idx = arr.findIndex((n) => n.id === id);
+  if (idx < 0) throw new Error(`node "${id}" not found`);
+  arr.splice(idx, 1);
+}
+
+// Messaging — outbound webhooks ────────────────────────────────
+//
+// cfg.messaging.webhooks[name] = { kind: 'slack'|'discord', url }
+//
+// We deliberately store webhook URLs (not bot tokens) because that
+// keeps the install footprint small — any user can paste a Slack
+// "Incoming Webhook" URL and start sending without registering an
+// app. Bot tokens can be added later as a separate `messaging.tokens`
+// shape when we wire the bidirectional inbox.
+
+const WEBHOOK_PATTERNS = {
+  slack:   /^https?:\/\/hooks\.slack\.com\//i,
+  discord: /^https?:\/\/(?:discord(?:app)?\.com|canary\.discord\.com)\/api\/webhooks\//i,
+};
+
+function detectKind(url) {
+  for (const [kind, re] of Object.entries(WEBHOOK_PATTERNS)) {
+    if (re.test(url)) return kind;
+  }
+  return 'generic';
+}
+
+export function messageList(cfg) {
+  const map = (cfg.messaging || {}).webhooks || {};
+  return Object.entries(map).map(([name, v]) => ({
+    name,
+    kind: v.kind,
+    urlMasked: v.url ? v.url.slice(0, 32) + '…' + v.url.slice(-6) : '',
+  }));
+}
+
+export function messageAdd(cfg, name, url, kindOverride) {
+  if (!name) throw new Error('name is required');
+  if (!url) throw new Error('url is required');
+  cfg.messaging = cfg.messaging || {};
+  cfg.messaging.webhooks = cfg.messaging.webhooks || {};
+  if (cfg.messaging.webhooks[name]) {
+    throw new Error(`webhook "${name}" already exists`);
+  }
+  cfg.messaging.webhooks[name] = {
+    kind: kindOverride || detectKind(url),
+    url,
+    addedAt: new Date().toISOString(),
+  };
+}
+
+export function messageRemove(cfg, name) {
+  const map = (cfg.messaging || {}).webhooks || {};
+  if (!map[name]) throw new Error(`webhook "${name}" not found`);
+  delete map[name];
+}
+
+export async function messageSend(cfg, name, text, opts = {}) {
+  const map = (cfg.messaging || {}).webhooks || {};
+  const hook = map[name];
+  if (!hook) throw new Error(`webhook "${name}" not configured — add via \`lazyclaw message add\``);
+  const fetchFn = opts.fetch || globalThis.fetch;
+  if (!fetchFn) throw new Error('no fetch implementation');
+
+  // Slack and Discord both accept a JSON body but with different key
+  // shapes — Slack uses { text }, Discord uses { content }. The
+  // generic kind sends a plain JSON envelope so user-supplied
+  // endpoints can ingest whatever shape they like via { text }.
+  let body;
+  if (hook.kind === 'discord') body = JSON.stringify({ content: text });
+  else                          body = JSON.stringify({ text });
+
+  const res = await fetchFn(hook.url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body,
+  });
+  if (!res.ok) {
+    const errText = (await (res.text?.() || Promise.resolve(''))).slice(0, 300);
+    throw new Error(`webhook ${hook.kind} send failed: ${res.status} ${errText}`);
+  }
+  return { ok: true, kind: hook.kind, status: res.status };
+}

package/cron.mjs

@@ -0,0 +1,359 @@
+// Cron — recurring `lazyclaw agent` runs.
+//
+// `lazyclaw cron add daily-summary "0 9 * * *" -- agent "Summarise
+// today's TODOs"` schedules the agent invocation every weekday at
+// 9 AM. On macOS we install a launchd plist; on Linux / WSL we
+// append a crontab entry. Both backends carry a per-job marker so
+// `cron list` / `cron remove` round-trip cleanly.
+//
+// Why this is built into the CLI:
+// - Most "make this scheduled" recipes for AI agents devolve into
+//   "add a crontab entry that pipes through a wrapper" — that's
+//   what we generate here, but with the right env vars to land in
+//   the user's lazyclaw config and a stable id for removal.
+// - launchd plists on macOS don't honor `crontab -e`, so a
+//   single-platform implementation would feel broken to half the
+//   user base.
+//
+// The job spec lives in `cfg.cron[<name>]` so it survives
+// uninstall/reinstall of the OS-level scheduler — `cron sync`
+// reconciles. Schedule strings use 5-field cron syntax everywhere
+// (the launchd backend internally translates to plist
+// StartCalendarInterval entries).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+
+const MARKER_PREFIX = '# lazyclaw-cron:';
+
+class CronError extends Error {
+  constructor(message, code) { super(message); this.name = 'CronError'; this.code = code || 'CRON_ERR'; }
+}
+
+// 5-field cron spec parser — minimal but strict enough that
+// "every Tuesday at 14:30" doesn't silently land at "every minute".
+// Supports: number, *, range a-b, list a,b,c, step */n.
+const FIELD_RANGES = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour',   min: 0, max: 23 },
+  { name: 'dom',    min: 1, max: 31 },
+  { name: 'month',  min: 1, max: 12 },
+  { name: 'dow',    min: 0, max: 6  },
+];
+
+export function parseCronSpec(spec) {
+  const tokens = String(spec || '').trim().split(/\s+/);
+  if (tokens.length !== 5) {
+    throw new CronError(`bad cron spec "${spec}" — need 5 fields, got ${tokens.length}`, 'CRON_BAD_SPEC');
+  }
+  const out = {};
+  for (let i = 0; i < 5; i++) {
+    const range = FIELD_RANGES[i];
+    out[range.name] = parseField(tokens[i], range);
+  }
+  return out;
+}
+
+function parseField(field, { name, min, max }) {
+  // Wildcard short-circuit.
+  if (field === '*') return { kind: 'any' };
+  // Step expressions: */N or RANGE/N.
+  const slash = field.indexOf('/');
+  if (slash >= 0) {
+    const head = field.slice(0, slash);
+    const step = Number(field.slice(slash + 1));
+    if (!Number.isFinite(step) || step < 1) {
+      throw new CronError(`bad step "${field}" in ${name}`, 'CRON_BAD_STEP');
+    }
+    if (head === '' || head === '*') return { kind: 'step', from: min, to: max, step };
+    const dash = head.indexOf('-');
+    if (dash < 0) throw new CronError(`bad step base "${head}" in ${name}`, 'CRON_BAD_STEP');
+    const a = Number(head.slice(0, dash)), b = Number(head.slice(dash + 1));
+    expectInRange(a, min, max, name); expectInRange(b, min, max, name);
+    return { kind: 'step', from: a, to: b, step };
+  }
+  // List a,b,c.
+  if (field.includes(',')) {
+    const items = field.split(',').map((p) => parseField(p, { name, min, max }));
+    return { kind: 'list', items };
+  }
+  // Range a-b.
+  const dash = field.indexOf('-');
+  if (dash >= 0) {
+    const a = Number(field.slice(0, dash)), b = Number(field.slice(dash + 1));
+    expectInRange(a, min, max, name); expectInRange(b, min, max, name);
+    return { kind: 'range', from: a, to: b };
+  }
+  // Plain number.
+  const n = Number(field);
+  expectInRange(n, min, max, name);
+  return { kind: 'value', value: n };
+}
+
+function expectInRange(n, min, max, fieldName) {
+  if (!Number.isFinite(n) || n < min || n > max) {
+    throw new CronError(`${fieldName} value ${n} out of range ${min}–${max}`, 'CRON_OUT_OF_RANGE');
+  }
+}
+
+// Expand a parsed field into the explicit list of values it
+// matches. launchd needs explicit values, not patterns.
+export function expandField(parsed, { min, max }) {
+  if (!parsed) return [];
+  switch (parsed.kind) {
+    case 'any':   return null; // null === "every"
+    case 'value': return [parsed.value];
+    case 'range': return inclusive(parsed.from, parsed.to);
+    case 'step': {
+      const out = [];
+      for (let i = parsed.from; i <= parsed.to; i += parsed.step) out.push(i);
+      return out;
+    }
+    case 'list': {
+      const out = new Set();
+      for (const item of parsed.items) {
+        const xs = expandField(item, { min, max });
+        if (xs === null) return null;
+        xs.forEach((v) => out.add(v));
+      }
+      return [...out].sort((a, b) => a - b);
+    }
+    default: return [];
+  }
+}
+
+function inclusive(a, b) {
+  const [from, to] = a <= b ? [a, b] : [b, a];
+  return Array.from({ length: to - from + 1 }, (_, i) => from + i);
+}
+
+// ── id / shape ──────────────────────────────────────────────────
+
+const NAME_RE = /^[A-Za-z0-9_.-]+$/;
+
+export function ensureValidName(name) {
+  if (!name || !NAME_RE.test(name)) {
+    throw new CronError(`name "${name}" must match ${NAME_RE}`, 'CRON_BAD_NAME');
+  }
+}
+
+export function listJobs(cfg) {
+  return Object.entries(cfg.cron || {}).map(([name, j]) => ({
+    name,
+    schedule: j.schedule,
+    command: j.command,
+    addedAt: j.addedAt,
+  }));
+}
+
+export function getJob(cfg, name) {
+  return (cfg.cron || {})[name] || null;
+}
+
+export function upsertJob(cfg, name, schedule, command) {
+  ensureValidName(name);
+  parseCronSpec(schedule); // throws on bad spec
+  if (!command || (Array.isArray(command) && !command.length)) {
+    throw new CronError('command is required', 'CRON_NO_COMMAND');
+  }
+  cfg.cron = cfg.cron || {};
+  const existed = !!cfg.cron[name];
+  cfg.cron[name] = {
+    schedule,
+    command: Array.isArray(command) ? command : [String(command)],
+    addedAt: existed ? cfg.cron[name].addedAt : new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  return existed ? 'updated' : 'created';
+}
+
+export function removeJob(cfg, name) {
+  if (!cfg.cron || !cfg.cron[name]) throw new CronError(`no job "${name}"`, 'CRON_NO_JOB');
+  delete cfg.cron[name];
+}
+
+// ── installer (system scheduler) ────────────────────────────────
+
+export function pickBackend() {
+  if (process.platform === 'darwin') return 'launchd';
+  return 'crontab';
+}
+
+export function plistPath(name) {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `com.lazyclaw.${name}.plist`);
+}
+
+export function buildPlist(name, schedule, command) {
+  const parsed = parseCronSpec(schedule);
+  const min   = expandField(parsed.minute, { min: 0,  max: 59 });
+  const hour  = expandField(parsed.hour,   { min: 0,  max: 23 });
+  const dom   = expandField(parsed.dom,    { min: 1,  max: 31 });
+  const month = expandField(parsed.month,  { min: 1,  max: 12 });
+  const dow   = expandField(parsed.dow,    { min: 0,  max: 6  });
+  // launchd takes a single dict per fire-time. We expand the cron
+  // schedule into the cartesian product of (Minute × Hour × Day ×
+  // Month × Weekday); each null field means "every" so we encode
+  // nothing for it. For most schedules this is small (e.g. "every
+  // weekday 9 AM" = 5 entries).
+  const entries = cartesian([
+    minOrNull(min), minOrNull(hour), minOrNull(dom), minOrNull(month), minOrNull(dow),
+  ]);
+  const intervals = entries.map(([Minute, Hour, Day, Month, Weekday]) => {
+    const dict = {};
+    if (Minute  !== null) dict.Minute  = Minute;
+    if (Hour    !== null) dict.Hour    = Hour;
+    if (Day     !== null) dict.Day     = Day;
+    if (Month   !== null) dict.Month   = Month;
+    if (Weekday !== null) dict.Weekday = Weekday;
+    return dict;
+  });
+  const programArguments = command;
+  const stdoutPath = path.join(os.homedir(), '.lazyclaw', 'logs', `cron-${name}.out.log`);
+  const stderrPath = path.join(os.homedir(), '.lazyclaw', 'logs', `cron-${name}.err.log`);
+  return renderPlist({
+    label: `com.lazyclaw.${name}`,
+    programArguments,
+    intervals,
+    stdoutPath,
+    stderrPath,
+  });
+}
+
+function minOrNull(arr) {
+  return arr === null ? [null] : arr;
+}
+
+function cartesian(arrs) {
+  return arrs.reduce((acc, arr) => acc.flatMap((row) => arr.map((v) => row.concat([v]))), [[]]);
+}
+
+function renderPlist({ label, programArguments, intervals, stdoutPath, stderrPath }) {
+  const argLines = programArguments.map((a) => `      <string>${escapeXml(a)}</string>`).join('\n');
+  const intervalDicts = intervals.map((i) => {
+    const inner = Object.entries(i)
+      .map(([k, v]) => `      <key>${k}</key>\n      <integer>${v}</integer>`).join('\n');
+    return `    <dict>\n${inner}\n    </dict>`;
+  }).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argLines}
+  </array>
+  <key>StartCalendarInterval</key>
+  <array>
+${intervalDicts}
+  </array>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(stderrPath)}</string>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// ── crontab backend (Linux / WSL) ───────────────────────────────
+
+export function buildCrontabLine(name, schedule, command) {
+  const cmdStr = command.map(shellQuote).join(' ');
+  return `${schedule} ${cmdStr} ${MARKER_PREFIX}${name}`;
+}
+
+function shellQuote(arg) {
+  if (arg === '' || /[\s'"\\$`]/.test(arg)) return `'${String(arg).replace(/'/g, `'\\''`)}'`;
+  return String(arg);
+}
+
+// Reads current crontab; ignores "no crontab" exit codes.
+function readCrontab() {
+  const r = spawnSync('crontab', ['-l'], { encoding: 'utf8' });
+  if (r.status === 0) return r.stdout || '';
+  // exit 1 + stderr "no crontab" === empty crontab; treat as ''.
+  return '';
+}
+
+function writeCrontab(text) {
+  const r = spawnSync('crontab', ['-'], { input: text, encoding: 'utf8' });
+  if (r.status !== 0) {
+    throw new CronError(`crontab write failed: ${r.stderr || r.status}`, 'CRON_WRITE_FAIL');
+  }
+}
+
+export function installCrontabJob(name, schedule, command) {
+  const line = buildCrontabLine(name, schedule, command);
+  const cur = readCrontab();
+  // Drop any prior line for the same name so update == replace.
+  const filtered = cur.split('\n').filter((ln) => !ln.endsWith(`${MARKER_PREFIX}${name}`));
+  const next = [...filtered, line].filter(Boolean).join('\n') + '\n';
+  writeCrontab(next);
+  return line;
+}
+
+export function uninstallCrontabJob(name) {
+  const cur = readCrontab();
+  if (!cur) return false;
+  const next = cur.split('\n').filter((ln) => !ln.endsWith(`${MARKER_PREFIX}${name}`)).join('\n');
+  writeCrontab(next + (next.endsWith('\n') ? '' : '\n'));
+  return cur !== next + (next.endsWith('\n') ? '' : '\n');
+}
+
+// ── launchd backend (macOS) ─────────────────────────────────────
+
+export function installLaunchdJob(name, schedule, command) {
+  const text = buildPlist(name, schedule, command);
+  const dst = plistPath(name);
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.mkdirSync(path.join(os.homedir(), '.lazyclaw', 'logs'), { recursive: true });
+  fs.writeFileSync(dst, text);
+  // Try to load the agent so it takes effect now. If launchctl
+  // refuses (already loaded, no GUI session), surface the error
+  // but leave the plist on disk — `launchctl load` later will
+  // pick it up.
+  spawnSync('launchctl', ['unload', dst], { stdio: 'ignore' });
+  const r = spawnSync('launchctl', ['load', dst], { encoding: 'utf8' });
+  if (r.status !== 0) {
+    throw new CronError(`launchctl load failed: ${r.stderr || r.status}`, 'CRON_LAUNCHD_FAIL');
+  }
+  return dst;
+}
+
+export function uninstallLaunchdJob(name) {
+  const dst = plistPath(name);
+  if (fs.existsSync(dst)) spawnSync('launchctl', ['unload', dst], { stdio: 'ignore' });
+  if (fs.existsSync(dst)) fs.unlinkSync(dst);
+}
+
+// ── cron run (one-shot, fired by the system) ────────────────────
+
+/**
+ * Synchronous run path that the OS scheduler invokes via the
+ * stored ProgramArguments. Reads the named job from the saved
+ * config, resolves the command to its argv, and exec()s it.
+ */
+export function runJob(cfg, name) {
+  const job = getJob(cfg, name);
+  if (!job) throw new CronError(`no job "${name}"`, 'CRON_NO_JOB');
+  const [bin, ...args] = job.command;
+  const r = spawnSync(bin, args, { stdio: 'inherit' });
+  return r.status ?? 0;
+}
+
+export { CronError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "3.99.3",
+  "version": "3.99.4",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama and orchestrating multi-step LLM workflows. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",
@@ -40,6 +40,12 @@
     "ratelimit.mjs",
     "config-validate.mjs",
     "rates-validate.mjs",
+    "config_features.mjs",
+    "workspace.mjs",
+    "browse.mjs",
+    "sandbox.mjs",
+    "skills_install.mjs",
+    "cron.mjs",
     "providers/",
     "workflow/",
     "web/",

package/sandbox.mjs

@@ -0,0 +1,127 @@
+// Sandbox — wrap a child process in a Docker container.
+//
+// `lazyclaw chat --sandbox docker:<image>` (or the equivalent on
+// `agent`) routes the underlying `claude` CLI invocation through
+//
+//   docker run --rm -i --network=<net> \
+//              -v <cwd>:<cwd> -w <cwd> \
+//              -e <pass-through env vars> \
+//              <image> claude -p ...
+//
+// instead of running `claude` directly on the host. Two reasons:
+//
+// 1. Filesystem confinement. The default --workdir mount only
+//    exposes the current working directory; tools that try to
+//    chdir into $HOME or read /etc see an empty container fs.
+// 2. Network policy. By default we set --network=none so the
+//    sandboxed agent cannot reach the public internet — useful
+//    when handing it untrusted prompts. Pass `--network host` /
+//    `bridge` via flags when the workflow needs outbound access
+//    (e.g. it has to call an API).
+//
+// Caveats — call out so users aren't surprised:
+//
+// - The user's `claude` login lives in $HOME/.claude/. The sandbox
+//   doesn't expose $HOME by default, so the wrapped CLI can't see
+//   that auth and will prompt for login. To run sandboxed under
+//   the user's existing subscription, mount $HOME/.claude:
+//
+//     lazyclaw chat --sandbox docker:node:20 \
+//                   --sandbox-mount "$HOME/.claude:/root/.claude:ro"
+//
+// - Sandboxing only applies when the picked provider goes through
+//   a subprocess (currently `claude-cli`). API providers
+//   (anthropic / openai / gemini) hit the network from
+//   *lazyclaw's* process, not a child — sandboxing them is a
+//   no-op and we surface a warning.
+
+import { spawn } from 'node:child_process';
+
+class SandboxError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SandboxError';
+    this.code = code || 'SANDBOX_ERR';
+  }
+}
+
+/**
+ * Parse a `--sandbox` flag. Accepts:
+ *   docker:<image>           — Docker with default policy
+ *   docker:<image>?<args>     — query-string-style overrides
+ *   off | none | -            — explicit "no sandbox"
+ *
+ * Returns null when sandboxing is off, or
+ * { kind: 'docker', image, network, mounts: string[], envPassthrough: string[] }.
+ */
+export function parseSandboxSpec(spec, flags = {}) {
+  if (!spec || /^(off|none|-)$/i.test(String(spec))) return null;
+  const m = String(spec).match(/^([a-z]+):(.+)$/i);
+  if (!m) throw new SandboxError(`bad sandbox spec "${spec}" — expected "docker:<image>"`, 'SANDBOX_BAD_SPEC');
+  const [, kind, rest] = m;
+  if (kind.toLowerCase() !== 'docker') {
+    throw new SandboxError(`unsupported sandbox kind "${kind}" — only "docker" is implemented`, 'SANDBOX_UNSUPPORTED');
+  }
+  return {
+    kind: 'docker',
+    image: rest.trim(),
+    // Default to --network=none for safety. Override via:
+    //   --sandbox-network host   (or bridge / a named network)
+    network: flags['sandbox-network'] || 'none',
+    // --sandbox-mount can repeat; cli.parseArgs collects repeats
+    // into an array.
+    mounts: arrayify(flags['sandbox-mount']),
+    envPassthrough: arrayify(flags['sandbox-env']),
+  };
+}
+
+function arrayify(v) {
+  if (v === undefined || v === null) return [];
+  return Array.isArray(v) ? v : [String(v)];
+}
+
+/**
+ * Build the docker run argv that wraps a child invocation. The
+ * caller hands us the original [bin, ...args] they were going to
+ * spawn; we return [docker, ...dockerArgs] that puts the same
+ * thing inside the container.
+ */
+export function buildDockerArgs(spec, [bin, ...binArgs], opts = {}) {
+  if (!spec || spec.kind !== 'docker') {
+    throw new SandboxError('buildDockerArgs requires a docker spec', 'SANDBOX_BAD_SPEC');
+  }
+  const cwd = opts.cwd || process.cwd();
+  const args = [
+    'run', '--rm', '-i',
+    '--network', spec.network || 'none',
+    '-v', `${cwd}:${cwd}`,
+    '-w', cwd,
+  ];
+  for (const mount of spec.mounts) {
+    if (!mount.includes(':')) {
+      throw new SandboxError(`bad mount "${mount}" — expected host:container[:mode]`, 'SANDBOX_BAD_MOUNT');
+    }
+    args.push('-v', mount);
+  }
+  for (const envName of spec.envPassthrough) {
+    args.push('-e', envName);
+  }
+  args.push(spec.image, bin, ...binArgs);
+  return args;
+}
+
+/**
+ * Spawn `bin` with `args` either bare (no sandbox) or under the
+ * docker wrapper. Returns the child process; the caller drives
+ * stdio and handles exit. Mirrors `child_process.spawn`'s shape.
+ */
+export function spawnSandboxed(spec, bin, args, spawnOpts = {}) {
+  if (!spec) return spawn(bin, args, spawnOpts);
+  if (spec.kind !== 'docker') {
+    throw new SandboxError(`unsupported kind "${spec.kind}"`, 'SANDBOX_UNSUPPORTED');
+  }
+  const dockerArgs = buildDockerArgs(spec, [bin, ...args], { cwd: spawnOpts.cwd });
+  return spawn('docker', dockerArgs, spawnOpts);
+}
+
+export { SandboxError };

package/skills_install.mjs

@@ -0,0 +1,239 @@
+// Remote skill installer.
+//
+// Resolves an OpenClaw-style spec into a set of locally-installed
+// skills:
+//
+//   lazyclaw skills install <user>/<repo>           — main branch
+//   lazyclaw skills install <user>/<repo>@<ref>     — branch / tag / sha
+//   lazyclaw skills install <user>/<repo>@<ref>:<path>
+//                                                    — only files under <path>
+//
+// The "registry" is just GitHub. `lazyclaw skills install
+// anthropic-skills/code-review@v1.2` fetches the tarball at
+//   https://codeload.github.com/anthropic-skills/code-review/tar.gz/v1.2
+// and installs every `.md` it finds at the repo root and under
+// `skills/` (or under the explicit subpath after the colon).
+//
+// Why GitHub directly instead of a hosted ClawHub: zero new
+// infrastructure, the public-pasteable URL is what users already
+// share, and tag pinning is reproducible.
+//
+// We deliberately do NOT auto-execute anything — skills are .md
+// files whose content goes into the LLM's system prompt. No code
+// runs. The worst-case ingest is "the prompt makes the model
+// behave oddly", which is recoverable by `lazyclaw skills remove`.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+
+const GITHUB_SPEC = /^([\w.-]+)\/([\w.-]+)(?:@([^:]+))?(?::(.+))?$/;
+const SKILL_EXT = '.md';
+const MAX_TARBALL_BYTES = 16 * 1024 * 1024; // 16 MiB
+const FETCH_TIMEOUT_MS = 30_000;
+
+export class SkillInstallError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SkillInstallError';
+    this.code = code || 'SKILL_INSTALL_ERR';
+  }
+}
+
+export function parseGithubSpec(spec) {
+  const m = String(spec || '').match(GITHUB_SPEC);
+  if (!m) return null;
+  const [, owner, repo, ref, subpath] = m;
+  return {
+    owner,
+    repo,
+    ref: ref || 'main',
+    subpath: subpath ? normaliseSubpath(subpath) : '',
+  };
+}
+
+function normaliseSubpath(p) {
+  // Refuse absolute paths and `..` components — the extracted
+  // archive is treated as untrusted and we never want to walk
+  // outside it.
+  const s = String(p || '').replace(/^\.?\//, '').replace(/\\/g, '/');
+  if (path.isAbsolute(s) || s.split('/').includes('..')) {
+    throw new SkillInstallError(`bad subpath "${p}"`, 'SKILL_BAD_SUBPATH');
+  }
+  return s;
+}
+
+export function tarballUrl({ owner, repo, ref }) {
+  return `https://codeload.github.com/${owner}/${repo}/tar.gz/${encodeURIComponent(ref)}`;
+}
+
+/**
+ * Download + extract a GitHub tarball into <tmpdir>/<random>/.
+ * Returns the absolute path of the extracted top-level directory
+ * (codeload puts everything under <repo>-<sha>/ so we follow that).
+ */
+export async function fetchAndExtract(spec, opts = {}) {
+  const fetchFn = opts.fetch || globalThis.fetch;
+  if (!fetchFn) throw new SkillInstallError('no fetch implementation', 'SKILL_NO_FETCH');
+  const url = tarballUrl(spec);
+  const maxBytes = Number(opts.maxBytes) > 0 ? Number(opts.maxBytes) : MAX_TARBALL_BYTES;
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(new Error(`timeout after ${FETCH_TIMEOUT_MS}ms`)), opts.timeoutMs || FETCH_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetchFn(url, {
+      headers: { 'user-agent': 'lazyclaw-skills/1.0' },
+      redirect: 'follow',
+      signal: ac.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!res.ok) {
+    throw new SkillInstallError(`fetch ${url} → ${res.status}`, 'SKILL_FETCH_FAIL');
+  }
+
+  // Stream the tarball into a temp dir using the system `tar` binary.
+  // Cheaper than pulling a Node tar dependency, and `tar` is on PATH
+  // wherever lazyclaw runs (macOS / Linux / WSL / modern Windows).
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lazyclaw-skill-'));
+  const child = spawn('tar', ['-xz', '-C', tmp], {
+    stdio: ['pipe', 'inherit', 'pipe'],
+  });
+  let stderrBuf = '';
+  child.stderr.on('data', (chunk) => { stderrBuf += chunk; });
+
+  // Cap how much we'll feed into tar so a malicious upstream can't
+  // exhaust disk. Counts the gzipped bytes; uncompressed could be
+  // 10× larger but skill bundles are typically << 1 MB compressed.
+  let total = 0;
+  const exited = new Promise((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) reject(new SkillInstallError(`tar exited ${code}: ${stderrBuf.slice(0, 300)}`, 'SKILL_TAR_FAIL'));
+      else resolve();
+    });
+  });
+
+  // Convert the WHATWG ReadableStream from `fetch` to a Node Readable
+  // and pipe to tar. Node 18+ exposes the conversion natively.
+  const nodeStream = res.body && typeof res.body.getReader === 'function'
+    ? Readable.fromWeb(res.body)
+    : res.body;
+  if (!nodeStream || typeof nodeStream.on !== 'function') {
+    child.stdin.end();
+    await exited.catch(() => {});
+    fs.rmSync(tmp, { recursive: true, force: true });
+    throw new SkillInstallError('tarball body is not a stream', 'SKILL_BAD_BODY');
+  }
+  await new Promise((resolve, reject) => {
+    nodeStream.on('data', (chunk) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        nodeStream.destroy(new SkillInstallError(`tarball exceeds ${maxBytes} bytes (override with --max-bytes)`, 'SKILL_TOO_BIG'));
+        return;
+      }
+      if (!child.stdin.write(chunk)) nodeStream.pause();
+    });
+    child.stdin.on('drain', () => nodeStream.resume());
+    nodeStream.on('error', reject);
+    nodeStream.on('end', () => { child.stdin.end(); resolve(); });
+  });
+  await exited;
+
+  // codeload tarballs always have a single top-level dir named
+  // <repo>-<sha-or-ref>/. Find it.
+  const entries = fs.readdirSync(tmp);
+  const top = entries.find((n) => fs.statSync(path.join(tmp, n)).isDirectory());
+  if (!top) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    throw new SkillInstallError('extracted archive is empty', 'SKILL_EMPTY');
+  }
+  return { tmpRoot: tmp, extracted: path.join(tmp, top) };
+}
+
+/**
+ * Walk an extracted repo and pick the .md files that look like
+ * skills. Heuristic:
+ *   - if a `skills/` directory exists at the root, only files
+ *     under there count
+ *   - else, .md files at the repo root only (one level deep)
+ *   - if `subpath` is set in the spec, that wins absolutely —
+ *     all .md under spec.subpath are eligible
+ */
+export function pickSkillFiles(extractedRoot, subpath = '') {
+  const root = subpath ? path.join(extractedRoot, subpath) : extractedRoot;
+  if (!fs.existsSync(root)) return [];
+  if (subpath) return collectMd(root, root, /* recurse */ true);
+  const skillsDir = path.join(extractedRoot, 'skills');
+  if (fs.existsSync(skillsDir)) return collectMd(skillsDir, skillsDir, true);
+  // Fallback: top-level only — README is the only meaningful .md
+  // most repos ship at the root, and that usually IS the skill.
+  return collectMd(extractedRoot, extractedRoot, false);
+}
+
+function collectMd(dir, baseRoot, recurse) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recurse) out.push(...collectMd(full, baseRoot, true));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith(SKILL_EXT)) continue;
+    out.push({ relative: path.relative(baseRoot, full), abs: full });
+  }
+  return out.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+
+/**
+ * Install every picked skill into <configDir>/skills/<name>.md.
+ * Default name: file basename without .md, lower-cased, slashes
+ * replaced with `-`. `--prefix foo/` prepends `foo-` to every
+ * installed name so a multi-skill repo doesn't clobber adjacent
+ * locally-managed skills.
+ *
+ * Skips files that already exist unless `force` is true.
+ */
+export function installPickedSkills(picked, configDir, opts = {}) {
+  const skillsRoot = path.join(configDir, 'skills');
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  const installed = [];
+  const skipped = [];
+  for (const f of picked) {
+    const base = path.basename(f.relative, SKILL_EXT).toLowerCase();
+    const safe = base.replace(/[^a-z0-9_.-]+/g, '-');
+    const name = (opts.prefix ? opts.prefix.replace(/[^a-z0-9_.-]+/g, '-') + '-' : '') + safe;
+    const dst = path.join(skillsRoot, name + SKILL_EXT);
+    if (fs.existsSync(dst) && !opts.force) {
+      skipped.push({ name, reason: 'exists', dst });
+      continue;
+    }
+    fs.copyFileSync(f.abs, dst);
+    installed.push({ name, src: f.relative, dst, bytes: fs.statSync(dst).size });
+  }
+  return { installed, skipped };
+}
+
+export async function installFromGithub(spec, configDir, opts = {}) {
+  const parsed = typeof spec === 'string' ? parseGithubSpec(spec) : spec;
+  if (!parsed) throw new SkillInstallError(`bad spec — expected user/repo[@ref][:path]`, 'SKILL_BAD_SPEC');
+  const { tmpRoot, extracted } = await fetchAndExtract(parsed, opts);
+  try {
+    const picked = pickSkillFiles(extracted, parsed.subpath);
+    if (!picked.length) {
+      throw new SkillInstallError(
+        `no .md skills found in ${parsed.owner}/${parsed.repo}@${parsed.ref}${parsed.subpath ? ':' + parsed.subpath : ''}`,
+        'SKILL_NONE_FOUND'
+      );
+    }
+    const r = installPickedSkills(picked, configDir, opts);
+    return { spec: parsed, ...r };
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+}

package/workspace.mjs

@@ -0,0 +1,158 @@
+// Workspace — OpenClaw-parity convention for project-rooted system
+// prompts. A workspace is a directory at
+//
+//   ~/.lazyclaw/workspaces/<name>/
+//     ├─ AGENTS.md   — what the assistant should DO
+//     ├─ SOUL.md     — how the assistant should THINK / behave
+//     ├─ TOOLS.md    — what tools / commands it can reach for
+//
+// `lazyclaw chat --workspace foo` (or `agent --workspace foo`) reads
+// the three files and synthesises a single system prompt. Skill
+// composition still works alongside — workspace lives at the head,
+// then any --skill content. Missing files are skipped silently so
+// a half-set-up workspace still works.
+//
+// Why three files instead of one giant SYSTEM.md: the OpenClaw
+// convention separates concerns so reviewers / teammates can edit
+// the "what" (AGENTS) without churning the "how" (SOUL) — and the
+// TOOLS file commonly comes from a generator (read from
+// `lazyclaw providers list` etc).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FILES = [
+  { name: 'AGENTS.md', heading: 'AGENTS — what to do' },
+  { name: 'SOUL.md',   heading: 'SOUL — how to behave' },
+  { name: 'TOOLS.md',  heading: 'TOOLS — what is available' },
+];
+
+export function workspaceRoot(cfgDir) {
+  return path.join(cfgDir, 'workspaces');
+}
+
+export function workspaceDir(cfgDir, name) {
+  if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+    throw new Error('workspace name must match [A-Za-z0-9_.-]+');
+  }
+  return path.join(workspaceRoot(cfgDir), name);
+}
+
+// List every workspace under ~/.lazyclaw/workspaces/. Returns
+// metadata (which of the three files are present, total size) so
+// `lazyclaw workspace list` can show the user at a glance which
+// workspaces are populated vs scaffolded-but-empty.
+export function listWorkspaces(cfgDir) {
+  const root = workspaceRoot(cfgDir);
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    const dir = path.join(root, name);
+    let st;
+    try { st = fs.statSync(dir); } catch { continue; }
+    if (!st.isDirectory()) continue;
+    const files = {};
+    let totalBytes = 0;
+    for (const f of FILES) {
+      const p = path.join(dir, f.name);
+      try {
+        const fst = fs.statSync(p);
+        files[f.name] = { bytes: fst.size, mtimeMs: fst.mtimeMs };
+        totalBytes += fst.size;
+      } catch { /* missing — leave undefined */ }
+    }
+    out.push({ name, dir, files, totalBytes });
+  }
+  // Newest-modified first.
+  out.sort((a, b) => {
+    const ma = Math.max(0, ...Object.values(a.files).map((f) => f.mtimeMs));
+    const mb = Math.max(0, ...Object.values(b.files).map((f) => f.mtimeMs));
+    return mb - ma;
+  });
+  return out;
+}
+
+// Scaffold a fresh workspace. Each file gets a tiny stub the user
+// can replace. We deliberately don't pre-populate from a template
+// repo — the OpenClaw stubs are intentionally short so the user
+// reads them before editing.
+export function initWorkspace(cfgDir, name) {
+  const dir = workspaceDir(cfgDir, name);
+  if (fs.existsSync(dir)) throw new Error(`workspace "${name}" already exists`);
+  fs.mkdirSync(dir, { recursive: true });
+  const stubs = {
+    'AGENTS.md':
+`# Agents
+
+What this assistant is asked to DO. Plain English.
+
+- Primary goal: ...
+- Daily routines: ...
+- When stuck, escalate to: ...
+`,
+    'SOUL.md':
+`# Soul
+
+How the assistant should BEHAVE — voice, defaults, hard rules.
+
+- Tone: ...
+- Defaults: prefer concise answers; ask before destructive actions.
+- Never: hand-wave, fabricate citations, or skip running tests.
+`,
+    'TOOLS.md':
+`# Tools
+
+What the assistant can reach for, and how to invoke each one.
+
+- \`lazyclaw browse <url>\` — fetch + markdown-ify a page
+- \`lazyclaw message send <name> <text>\` — Slack / Discord webhook
+- \`lazyclaw agent ...\` — one-shot LLM call
+
+Add project-specific tools below.
+`,
+  };
+  for (const [name, body] of Object.entries(stubs)) {
+    fs.writeFileSync(path.join(dir, name), body, 'utf8');
+  }
+  return dir;
+}
+
+// Compose the three files into a single system prompt. Returns ''
+// when the workspace is empty (caller falls back to whatever it had
+// before). Skip-on-missing keeps the contract forgiving.
+export function composeWorkspacePrompt(cfgDir, name) {
+  if (!name) return '';
+  const dir = workspaceDir(cfgDir, name);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`workspace "${name}" not found at ${dir}`);
+  }
+  const blocks = [];
+  for (const f of FILES) {
+    const p = path.join(dir, f.name);
+    let body;
+    try { body = fs.readFileSync(p, 'utf8').trim(); } catch { continue; }
+    if (!body) continue;
+    blocks.push(`# ${f.heading}\n\n${body}`);
+  }
+  return blocks.join('\n\n---\n\n');
+}
+
+// Read just one file's content so the CLI can `workspace show`
+// without printing all three.
+export function readWorkspaceFile(cfgDir, name, fileName) {
+  const dir = workspaceDir(cfgDir, name);
+  const allowed = FILES.map((f) => f.name);
+  if (!allowed.includes(fileName)) {
+    throw new Error(`unknown file "${fileName}" — must be one of ${allowed.join(', ')}`);
+  }
+  const p = path.join(dir, fileName);
+  return fs.readFileSync(p, 'utf8');
+}
+
+export function removeWorkspace(cfgDir, name) {
+  const dir = workspaceDir(cfgDir, name);
+  if (!fs.existsSync(dir)) throw new Error(`workspace "${name}" not found`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+export const WORKSPACE_FILES = FILES.map((f) => f.name);