lazyclaw 6.3.0 → 6.4.0

package/workflow/declarative.mjs

@@ -0,0 +1,101 @@
+// workflow/declarative.mjs — parse + compile + run a declarative workflow.
+//
+// Workflows used to be hand-written .mjs that passed arbitrary node functions
+// to the executor (workflow/executor.mjs). This compiles a DATA definition
+// (JSON; a node-type library backs it) into the same WorkflowNode shape, so a
+// workflow can be authored, stored, and run from config — and, next, served by
+// the daemon over HTTP. Orchestration (ordering, timeout, retry, cleanup,
+// cancellation) is still the existing executor; this layer only builds nodes.
+//
+// Definition shape:
+//   { name?, input?, nodes: [ { id, type, config?, deps?, timeoutMs?, retry? } ] }
+// Data flows by {{ref}}: a node's config can reference any prior node's output
+// by id (e.g. "{{fetchUser.name}}"), resolved from a shared bag at run time.
+
+import { runSequential } from './executor.mjs';
+import { NODE_TYPES, resolveRefs } from './nodes.mjs';
+
+export class WorkflowError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'WorkflowError';
+    this.code = code || 'WF_ERR';
+  }
+}
+
+// Validate the static shape (ids present + unique, nodes is an array). Type
+// existence is checked at compile time, where the caps-provided types are known.
+export function validateWorkflow(def) {
+  if (!def || typeof def !== 'object' || Array.isArray(def)) {
+    throw new WorkflowError('workflow must be an object', 'WF_SHAPE');
+  }
+  if (!Array.isArray(def.nodes) || def.nodes.length === 0) {
+    throw new WorkflowError('workflow needs a non-empty nodes[] array', 'WF_NODES');
+  }
+  const ids = new Set();
+  for (const n of def.nodes) {
+    if (!n || typeof n !== 'object') throw new WorkflowError('each node must be an object', 'WF_NODE');
+    if (typeof n.id !== 'string' || !n.id.trim()) throw new WorkflowError('each node needs a non-empty string id', 'WF_NODE_ID');
+    if (ids.has(n.id)) throw new WorkflowError(`duplicate node id: ${n.id}`, 'WF_DUP_ID');
+    ids.add(n.id);
+    if (typeof n.type !== 'string' || !n.type.trim()) throw new WorkflowError(`node "${n.id}" needs a type`, 'WF_NODE_TYPE');
+  }
+  return def;
+}
+
+export function parseWorkflow(text) {
+  let def;
+  try { def = JSON.parse(text); }
+  catch (e) { throw new WorkflowError(`invalid workflow JSON: ${e.message}`, 'WF_PARSE'); }
+  return validateWorkflow(def);
+}
+
+// Parse a workflow def from a minimal YAML subset (no new dependency — see
+// workflow/yaml_min.mjs for the supported grammar), then validate it the same
+// way as JSON. For authoring ergonomics; JSON remains the canonical format.
+export async function parseWorkflowYaml(text) {
+  const { parseYamlMin } = await import('./yaml_min.mjs');
+  let def;
+  try { def = parseYamlMin(text); }
+  catch (e) { throw new WorkflowError(`invalid workflow YAML: ${e.message}`, 'WF_PARSE'); }
+  return validateWorkflow(def);
+}
+
+// Compile a (validated) definition into executor nodes. caps.nodeTypes adds
+// side-effecting node types (http/shell/llm/channel) the caller chose to grant;
+// the built-in safe types are always present. Returns { nodes, bag } where bag
+// accumulates each node's output by id for {{ref}} resolution.
+export function compileWorkflow(def, caps = {}) {
+  validateWorkflow(def);
+  const registry = { ...NODE_TYPES, ...(caps.nodeTypes && typeof caps.nodeTypes === 'object' ? caps.nodeTypes : {}) };
+  for (const spec of def.nodes) {
+    if (typeof registry[spec.type] !== 'function') {
+      throw new WorkflowError(`unknown node type "${spec.type}" (node "${spec.id}") — known: ${Object.keys(registry).join(', ')}`, 'WF_UNKNOWN_TYPE');
+    }
+  }
+  const bag = {};
+  const nodes = def.nodes.map((spec) => ({
+    id: spec.id,
+    deps: Array.isArray(spec.deps) ? spec.deps : undefined,
+    timeoutMs: spec.timeoutMs,
+    retry: spec.retry,
+    execute: async (input, ctx = {}) => {
+      const handler = registry[spec.type];
+      const cfg = resolveRefs(spec.config || {}, bag);
+      const out = await handler(cfg, { input, bag, caps, signal: ctx.signal });
+      bag[spec.id] = out;
+      return out;
+    },
+  }));
+  return { nodes, bag };
+}
+
+// Compile + run a declarative workflow sequentially. Returns the executor's
+// { success, results, session } (session[id] = each node's output).
+export async function runWorkflow(def, opts = {}) {
+  const { nodes, bag } = compileWorkflow(def, opts.caps || {});
+  // Seed the run input so a node can reference it as {{input}} (e.g. the text of
+  // an inbound Slack message that triggered the workflow).
+  if (opts.input !== undefined) bag.input = opts.input;
+  return runSequential(nodes, opts.input ?? null, { signal: opts.signal });
+}

package/workflow/named.mjs

@@ -0,0 +1,71 @@
+// workflow/named.mjs — stored, named declarative workflows + run-by-name.
+//
+// A named workflow lives in cfg.workflows[<name>] (alongside cfg.cron /
+// cfg.channels), so it can be triggered by name from the CLI, a cron job, or an
+// inbound Slack message — the Hermes-style automation spine. Entry shape:
+//   cfg.workflows[name] = { def: { nodes:[...] }, channel?: 'slack:#x',
+//                           schedule?: '0 9 * * *', replyNode?: 'reply' }
+// The def is the same declarative format runDeclarativeRequest already runs;
+// this module only adds storage + a name guard + reply-text selection.
+
+import { runDeclarativeRequest } from './run_request.mjs';
+
+const NAME_RE = /^[A-Za-z0-9_.-]+$/;
+export function validWorkflowName(name) {
+  return typeof name === 'string' && name.length > 0 && NAME_RE.test(name);
+}
+
+export function getNamedWorkflow(cfg, name) {
+  const entry = cfg && cfg.workflows && typeof cfg.workflows === 'object' ? cfg.workflows[name] : undefined;
+  return entry && typeof entry === 'object' && entry.def ? entry : null;
+}
+
+export function listNamedWorkflows(cfg) {
+  const ws = (cfg && cfg.workflows && typeof cfg.workflows === 'object') ? cfg.workflows : {};
+  return Object.keys(ws).sort().map((name) => ({
+    name,
+    channel: ws[name]?.channel || null,
+    schedule: ws[name]?.schedule || null,
+    nodes: Array.isArray(ws[name]?.def?.nodes) ? ws[name].def.nodes.length : 0,
+  }));
+}
+
+// Find the named workflow bound to an inbound channel (entry.channel, e.g.
+// "slack:#ops" or "slack:C123"), or null. Used by POST /inbound to trigger a
+// workflow on a Slack message. Matches the channel id/name after stripping the
+// "slack:"/"#" prefixes so a binding written either way still resolves.
+export function workflowForChannel(cfg, channel) {
+  if (!channel) return null;
+  const ws = (cfg && cfg.workflows && typeof cfg.workflows === 'object') ? cfg.workflows : {};
+  const c = String(channel).replace(/^#/, '');
+  for (const name of Object.keys(ws)) {
+    const bound = ws[name] && ws[name].channel;
+    if (!bound || !ws[name].def) continue;
+    const target = String(bound).replace(/^slack:/, '').replace(/^#/, '');
+    if (target === c) return { name, ...ws[name] };
+  }
+  return null;
+}
+
+// Run a stored workflow by name. opts is forwarded to runDeclarativeRequest
+// (providerLookup for the llm node, fetchImpl, input, sessionId, signal).
+export async function runNamedWorkflow(name, cfg, opts = {}) {
+  const entry = getNamedWorkflow(cfg, name);
+  if (!entry) throw new Error(`no workflow named "${name}"`);
+  return runDeclarativeRequest(entry.def, cfg, opts);
+}
+
+// The text to surface back (Slack reply / CLI output): the explicitly-named
+// replyNode if set, else the LAST node's output. A workflow ending in an
+// http/json node returns an object, so authors should name a reply node.
+export function namedReplyText(result, entry = {}) {
+  const session = (result && result.session) || {};
+  if (entry.replyNode && entry.replyNode in session) {
+    const v = session[entry.replyNode];
+    return typeof v === 'string' ? v : JSON.stringify(v);
+  }
+  const keys = Object.keys(session);
+  if (!keys.length) return '';
+  const v = session[keys[keys.length - 1]];
+  return typeof v === 'string' ? v : JSON.stringify(v);
+}

package/workflow/named_cron.mjs

@@ -0,0 +1,50 @@
+// workflow/named_cron.mjs — schedule a named declarative workflow via cron.
+//
+// Mirrors goals_cron.mjs: install an OS cron job (launchd / crontab) whose
+// command is `lazyclaw workflow run <name>`, so the OS scheduler fires the
+// stored workflow on its schedule (no resident daemon loop). The job runs the
+// def and posts its reply to the bound channel (commands/workflow_named.mjs).
+// LAZYCLAW_SKIP_CRON_INSTALL writes the config but skips the backend install,
+// so the wiring is unit-testable with no real launchd/crontab.
+//
+// Note: launchd/crontab do NOT capture the shell env, so a scheduled run that
+// posts to Slack needs SLACK_BOT_TOKEN available to the cron environment
+// (export it in the launch context) — same requirement as the goal-tick fan-out.
+
+import * as cronMod from '../cron.mjs';
+import { readConfig as defaultRead, writeConfig as defaultWrite } from '../lib/config.mjs';
+
+export function attachWorkflowCron(name, schedule, deps = {}) {
+  const cron = deps.cron || cronMod;
+  const readConfig = deps.readConfig || defaultRead;
+  const writeConfig = deps.writeConfig || defaultWrite;
+  cron.parseCronSpec(schedule); // validate before touching state
+  const cfg = readConfig();
+  const jobName = `wf-${name}`;
+  const cmd = ['lazyclaw', 'workflow', 'run', name];
+  cron.upsertJob(cfg, jobName, schedule, cmd);
+  writeConfig(cfg);
+  if (process.env.LAZYCLAW_SKIP_CRON_INSTALL) return { jobName, skipped: true };
+  const backend = cron.pickBackend();
+  if (backend === 'launchd') cron.installLaunchdJob(jobName, schedule, cmd);
+  else cron.installCrontabJob(jobName, schedule, cmd);
+  return { jobName, skipped: false };
+}
+
+export function detachWorkflowCron(name, deps = {}) {
+  const cron = deps.cron || cronMod;
+  const readConfig = deps.readConfig || defaultRead;
+  const writeConfig = deps.writeConfig || defaultWrite;
+  const cfg = readConfig();
+  const jobName = `wf-${name}`;
+  if (!cfg.cron || !cfg.cron[jobName]) return false;
+  cron.removeJob(cfg, jobName);
+  writeConfig(cfg);
+  if (process.env.LAZYCLAW_SKIP_CRON_INSTALL) return true;
+  const backend = cron.pickBackend();
+  try {
+    if (backend === 'launchd') cron.uninstallLaunchdJob(jobName);
+    else cron.uninstallCrontabJob(jobName);
+  } catch { /* best-effort — cron sync recovers */ }
+  return true;
+}

package/workflow/nodes.mjs

@@ -0,0 +1,67 @@
+// workflow/nodes.mjs — the built-in node-type library for declarative workflows.
+//
+// A declarative workflow is data: a list of { id, type, config } specs. The
+// compiler (workflow/declarative.mjs) turns each spec into a WorkflowNode the
+// executor understands, resolving {{ref}} placeholders in `config` against a
+// shared bag of prior node outputs first. Each node TYPE is a pure handler:
+//   handler(config, ctx) => output    (sync or async)
+//   ctx = { input, bag, caps, signal }
+// Built-in types here are SAFE (no I/O). Side-effecting types (http, shell,
+// llm, channel-send) are injected via caps.nodeTypes so the daemon decides
+// what a workflow is allowed to do — capability injection, not ambient power.
+
+// Resolve a dotted ref ("a.b.c") against the bag of prior outputs.
+export function getRef(bag, pathStr) {
+  const parts = String(pathStr).split('.');
+  let v = bag;
+  for (const p of parts) {
+    if (v == null) return undefined;
+    v = v[p.trim()];
+  }
+  return v;
+}
+
+const WHOLE_REF = /^\{\{\s*([\w.$-]+)\s*\}\}$/;
+const INLINE_REF = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+
+// Deep-resolve {{ref}} placeholders in a config value against the bag. A string
+// that is EXACTLY "{{ref}}" becomes the raw referenced value (may be a non-
+// string); inline refs inside a longer string interpolate to text.
+export function resolveRefs(value, bag) {
+  if (typeof value === 'string') {
+    const whole = value.match(WHOLE_REF);
+    if (whole) return getRef(bag, whole[1]);
+    return value.replace(INLINE_REF, (_, ref) => {
+      const v = getRef(bag, ref);
+      if (v == null) return '';
+      return typeof v === 'object' ? JSON.stringify(v) : String(v);
+    });
+  }
+  if (Array.isArray(value)) return value.map((x) => resolveRefs(x, bag));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = resolveRefs(v, bag);
+    return out;
+  }
+  return value;
+}
+
+export const NODE_TYPES = {
+  // Emit a constant (or a ref'd value). The simplest source node.
+  set: (cfg) => (cfg && 'value' in cfg ? cfg.value : null),
+  // A string built from prior outputs. cfg.text already had its {{refs}}
+  // interpolated by the compiler, so this just returns the resolved string.
+  template: (cfg) => String(cfg?.text ?? ''),
+  // Parse a JSON string ({ parse }) into a value, or stringify ({ stringify }).
+  // Lets a downstream node {{ref}} into an http body's fields, etc.
+  json: (cfg) => {
+    if (cfg && 'parse' in cfg) { try { return JSON.parse(String(cfg.parse)); } catch { return null; } }
+    if (cfg && 'stringify' in cfg) return JSON.stringify(cfg.stringify);
+    return null;
+  },
+  // Shallow-merge a list of objects into one (later entries win).
+  merge: (cfg) => Object.assign({}, ...((Array.isArray(cfg?.values) ? cfg.values : []).filter((v) => v && typeof v === 'object'))),
+  // { value } unless it is null/undefined/'' — then { fallback }. Useful after
+  // an optional http/llm step that may have produced nothing.
+  default: (cfg) => { const v = cfg?.value; return (v === null || v === undefined || v === '') ? (cfg?.fallback ?? null) : v; },
+};

package/workflow/run_request.mjs

@@ -0,0 +1,74 @@
+// workflow/run_request.mjs — bridge a declarative workflow definition + the
+// daemon/CLI config into a safe run. Caps are derived from config, NOT from the
+// workflow: http (SSRF-guarded) is always granted; llm is bound to the
+// configured provider when one resolves. Shell and other powerful types are
+// NOT granted here — a posted workflow can never spawn a process. Returns a
+// plain serializable result; throws WorkflowError on a malformed definition.
+
+import { validateWorkflow, runWorkflow, compileWorkflow } from './declarative.mjs';
+import { buildCaps } from './builtin_caps.mjs';
+import { runPersistent, loadState } from './persistent.mjs';
+
+// Caps from config (never the workflow): http always, llm bound to the
+// configured provider, nothing else. Shared by the stateless + persistent paths.
+function _capsFromConfig(cfg, opts) {
+  const provider = typeof opts.providerLookup === 'function' ? opts.providerLookup(cfg.provider) : null;
+  const grants = { http: { fetchImpl: opts.fetchImpl || globalThis.fetch } };
+  if (provider && typeof provider.sendMessage === 'function') {
+    grants.llm = { provider, apiKey: cfg['api-key'], model: cfg.model };
+  }
+  return buildCaps(grants);
+}
+
+export async function runDeclarativeRequest(def, cfg = {}, opts = {}) {
+  validateWorkflow(def); // throws WorkflowError (caught by the caller → 400)
+  // sessionId opts in to the persisted/resumable engine (state under opts.dir).
+  if (opts.sessionId) return runDeclarativePersistent(def, cfg, opts);
+  const caps = _capsFromConfig(cfg, opts);
+  const r = await runWorkflow(def, { caps, input: opts.input, signal: opts.signal });
+  return {
+    ok: r.success,
+    success: r.success,
+    session: r.session || {},
+    results: (r.results || []).map((x) => ({ id: x.id, status: x.status, duration: x.duration })),
+    ...(r.error ? { error: r.error.message, failedAt: r.failedAt } : {}),
+  };
+}
+
+// Persisted/resumable run: state is keyed by sessionId under opts.dir. A second
+// call with the same sessionId resumes — already-succeeded nodes are skipped.
+// CRITICAL: the declarative {{ref}} bag is closed over the compiled nodes, so on
+// resume the skipped nodes never repopulate it. We pre-seed the bag from the
+// prior state's success outputs, or a downstream {{ref}} to a skipped node would
+// resolve to undefined.
+export async function runDeclarativePersistent(def, cfg = {}, opts = {}) {
+  validateWorkflow(def);
+  const caps = _capsFromConfig(cfg, opts);
+  const { nodes, bag } = compileWorkflow(def, caps);
+  if (opts.input !== undefined) bag.input = opts.input;
+  const prior = loadState(opts.sessionId, opts.dir);
+  if (prior && prior.nodes) {
+    for (const id of (prior.order || [])) {
+      const ns = prior.nodes[id];
+      if (ns && ns.status === 'success' && 'output' in ns) bag[id] = ns.output;
+    }
+  }
+  const r = await runPersistent(nodes, { sessionId: opts.sessionId, dir: opts.dir, signal: opts.signal });
+  // Reconstruct the {nodeId: output} session view from the persisted state so
+  // the response shape matches the stateless path.
+  const session = {};
+  if (r.state && r.state.nodes) {
+    for (const id of (r.state.order || [])) {
+      const ns = r.state.nodes[id];
+      if (ns && 'output' in ns) session[id] = ns.output;
+    }
+  }
+  return {
+    ok: r.success,
+    success: r.success,
+    session,
+    sessionId: opts.sessionId,
+    executedNodes: r.executedNodes || [],
+    ...(r.error ? { error: r.error, failedAt: r.failedAt } : {}),
+  };
+}

package/workflow/yaml_min.mjs

@@ -0,0 +1,97 @@
+// workflow/yaml_min.mjs — a MINIMAL, dependency-free block-YAML parser for
+// declarative workflow definitions. NOT a full YAML implementation (no anchors,
+// aliases, tags, multi-document, or complex keys) — it covers exactly what a
+// workflow def needs and errors clearly on anything else rather than guessing:
+//   - block mappings        key: value
+//   - block sequences       - item
+//   - sequences of mappings  - id: a\n  type: b   (the `nodes:` shape)
+//   - scalars               strings / numbers / true / false / null
+//   - quoted strings        "x" / 'x'
+//   - inline JSON flow       [a, b] / {k: v}      (delegated to JSON.parse)
+//   - block scalars         | (literal) / > (folded)   (good for llm prompts)
+// Tabs are rejected (YAML forbids them for indentation). The result is a plain
+// JS value passed to validateWorkflow, so a bad def still fails the same checks.
+
+export class YamlMinError extends Error {
+  constructor(message) { super(message); this.name = 'YamlMinError'; this.code = 'YAML_MIN'; }
+}
+
+function scalar(text) {
+  const s = text.trim();
+  if (s === '') return null;
+  // A flow indicator ([ or {) must be valid inline JSON — error rather than
+  // silently treating an unclosed/garbled flow value as a string.
+  if (s[0] === '[' || s[0] === '{') {
+    try { return JSON.parse(s); } catch (e) { throw new YamlMinError(`invalid inline JSON: ${s}`); }
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === 'null' || s === '~') return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(s)) return Number(s);
+  if (s[0] === '"' && s[s.length - 1] === '"') { try { return JSON.parse(s); } catch { return s.slice(1, -1); } }
+  if (s[0] === "'" && s[s.length - 1] === "'") return s.slice(1, -1);
+  return s;
+}
+
+export function parseYamlMin(text) {
+  const src = String(text).replace(/\r\n/g, '\n').split('\n');
+  // Keep raw lines but track logical (non-blank/comment) ones with their index.
+  const lines = [];
+  for (const raw of src) {
+    if (/^\s*#/.test(raw) || raw.trim() === '') continue;
+    if (/^\s*\t/.test(raw)) throw new YamlMinError('tabs are not allowed for indentation');
+    lines.push(raw);
+  }
+  let i = 0;
+  const indentOf = (l) => l.length - l.trimStart().length;
+  const curIndent = () => (i < lines.length ? indentOf(lines[i]) : -1);
+
+  function parseBlock(indent) {
+    const t = lines[i].trim();
+    return (t === '-' || t.startsWith('- ')) ? parseSeq(indent) : parseMap(indent);
+  }
+
+  function parseMap(indent) {
+    const obj = {};
+    while (i < lines.length && indentOf(lines[i]) === indent) {
+      const line = lines[i].trim();
+      const ci = line.indexOf(':');
+      if (ci < 0) throw new YamlMinError(`expected "key: value", got: ${line}`);
+      const key = line.slice(0, ci).trim();
+      const rest = line.slice(ci + 1).trim();
+      i++;
+      if (rest === '|' || rest === '>') { obj[key] = blockScalar(indent, rest); }
+      else if (rest === '') {
+        obj[key] = (i < lines.length && curIndent() > indent) ? parseBlock(curIndent()) : null;
+      } else { obj[key] = scalar(rest); }
+    }
+    return obj;
+  }
+
+  function parseSeq(indent) {
+    const arr = [];
+    while (i < lines.length && indentOf(lines[i]) === indent && (lines[i].trim() === '-' || lines[i].trim().startsWith('- '))) {
+      const rest = lines[i].trim().slice(1).trim();
+      if (rest === '') { i++; arr.push(curIndent() > indent ? parseBlock(curIndent()) : null); }
+      else if (/^[^[{"'][^:]*:(\s|$)/.test(rest)) {
+        // "- key: val ..." → a mapping item; re-emit the first key at indent+2
+        // so parseMap reads it together with this item's deeper-indented keys.
+        lines[i] = ' '.repeat(indent + 2) + rest;
+        arr.push(parseMap(indent + 2));
+      } else { i++; arr.push(scalar(rest)); }
+    }
+    return arr;
+  }
+
+  function blockScalar(parentIndent, style) {
+    const out = [];
+    while (i < lines.length && indentOf(lines[i]) > parentIndent) {
+      out.push(lines[i].slice(parentIndent + 2));
+      i++;
+    }
+    return out.join(style === '>' ? ' ' : '\n');
+  }
+
+  if (i >= lines.length) return {};
+  return parseBlock(curIndent());
+}