@volter/supercode-orchestrator 0.4.4

package/events.mjs

@@ -0,0 +1,107 @@
+// Events: the only inputs to the reducer (docs/ORCHESTRATOR-IR.md §3).
+// Adapters, the clock, the HTTP listener and the SDK event stream produce
+// them; nothing else does. Constructors validate shape so a malformed adapter
+// fails here, not inside the reducer.
+
+import { CHAT_TYPES } from './ir.mjs';
+
+function req(cond, message) {
+  if (!cond) throw new TypeError(`event: ${message}`);
+}
+
+/**
+ * §3's `inbound`. Beside the surface key and the text it carries the four
+ * fields ORC-1 F4 found every real transport produces and the IR had no room
+ * for: `message_id` (the threading / reaction / edit target), and the three
+ * sender flags `is_me` / `is_bot` / `mention`. `is_me` is the loop-safety one —
+ * without it the loop cannot recognise its own echo (§4.1 step 0).
+ * All four are optional: an adapter that cannot produce one says so with
+ * `null`, never with a guess.
+ */
+export function inbound({
+  profile, key, sender, sender_name = null, text, attachments = [], at, adapter = key?.platform, guild_id = null,
+  message_id = null, is_me = false, is_bot = null, mention = false,
+}) {
+  req(typeof profile === 'string' && profile, 'profile (the adapter-owning profile) is required');
+  req(key && typeof key.platform === 'string' && CHAT_TYPES.has(key.kind), 'key needs platform and a kind');
+  req(typeof sender === 'string' && sender, 'sender is required');
+  req(typeof text === 'string', 'text must be a string');
+  req(typeof at === 'string', 'at must be an RFC 3339 string');
+  req(is_bot === null || typeof is_bot === 'boolean', 'is_bot must be a boolean or null (the Chat SDK\'s "unknown")');
+  const k = { platform: key.platform, kind: key.kind };
+  if (key.chat_id) k.chat_id = String(key.chat_id);
+  if (key.thread_id) k.thread_id = String(key.thread_id);
+  if (key.participant_id) k.participant_id = String(key.participant_id);
+  return {
+    type: 'inbound', profile, key: k, sender, sender_name, text, attachments, at, adapter, guild_id,
+    message_id: message_id === null ? null : String(message_id),
+    is_me: Boolean(is_me), is_bot, mention: Boolean(mention),
+  };
+}
+
+/**
+ * `inactivity_s` is how long a fire's worker may go silent before the fire is
+ * closed as a timeout (Hermes's `HERMES_CRON_TIMEOUT`; 0 = no limit); null
+ * means Hermes's default, 600.
+ */
+export function tick(at, inactivity_s = null, max_parallel = null) {
+  req(typeof at === 'string', 'at must be an RFC 3339 string');
+  req(inactivity_s === null || (typeof inactivity_s === 'number' && inactivity_s >= 0), 'inactivity_s must be a non-negative number or null');
+  req(max_parallel === null || (Number.isInteger(max_parallel) && max_parallel > 0), 'max_parallel must be a positive integer or null');
+  return { type: 'tick', at, inactivity_s, max_parallel };
+}
+
+/**
+ * §3's `webhook`. `event` is the event type the source named (its header, else
+ * the body's own), `delivery_id` the source's id for this delivery; either is
+ * null when the call carried none.
+ */
+export function webhook({ name, payload = null, verified = false, at, event = null, delivery_id = null }) {
+  req(typeof name === 'string' && name, 'name is required');
+  req(typeof at === 'string', 'at must be an RFC 3339 string');
+  req(event === null || typeof event === 'string', 'event must be a string or null');
+  req(delivery_id === null || typeof delivery_id === 'string', 'delivery_id must be a string or null');
+  return { type: 'webhook', name, payload, verified: Boolean(verified), at, event, delivery_id };
+}
+
+export function worker({ profile, keyString, runtime_id, ev, at }) {
+  req(typeof profile === 'string', 'profile is required');
+  req(typeof keyString === 'string', 'keyString is required');
+  req(ev && typeof ev.kind === 'string', 'ev.kind is required');
+  return { type: 'worker', profile, keyString, runtime_id: runtime_id ?? null, ev, at };
+}
+
+/**
+ * `configured: false` marks an adapter that can never connect as set up (a
+ * missing package or credential), as against one that is down for now:
+ * Hermes's delivery preflight counts only a configured platform as connected.
+ */
+export function adapterStatus({ platform, state, error = null, at, configured = true }) {
+  req(state === 'up' || state === 'down', 'state must be up|down');
+  return { type: 'adapter', platform, state, error, at, configured: configured !== false };
+}
+
+export function operator({ verb, profile = 'default', args = {}, at }) {
+  req(typeof verb === 'string', 'verb is required');
+  return { type: 'operator', verb, profile, args, at };
+}
+
+/**
+ * A fire's gate finished (the loop ran it off the queue). `script`:
+ * `{ok, output}`; `monitor`: `{ok, changed, hash, block, error}`; either null
+ * when the job has none.
+ */
+export function gateResult({ profile, fire_id, at, script = null, monitor = null }) {
+  req(typeof profile === 'string' && profile, 'profile is required');
+  req(typeof fire_id === 'string' && fire_id, 'fire_id is required');
+  req(typeof at === 'string', 'at must be an RFC 3339 string');
+  return { type: 'gate_result', profile, fire_id, at, script, monitor };
+}
+
+export function restart(at) {
+  return { type: 'restart', at };
+}
+
+export function stopping(at) {
+  return { type: 'stopping', at };
+}

package/gates.mjs

@@ -0,0 +1,281 @@
+// A fire's gate, the I/O half (docs/architecture/orchestrator.md §4.3 step 2a): the job's
+// pre-run script and its monitor source, run by the loop off the event queue. Transcribed from
+// Hermes 0.21.0: `cron/scheduler.py` `_run_job_script` / `_get_script_timeout`, and
+// `cron/monitor.py`. The reducer half (what the answer means) is `gateResult` in cron.mjs.
+
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Hermes `_DEFAULT_SCRIPT_TIMEOUT`. */
+export const DEFAULT_SCRIPT_TIMEOUT_S = 3600;
+/** `cron/monitor.py`: diff and output caps, and the bounded GET. */
+export const MAX_DIFF_CHARS = 4000;
+export const MAX_OUTPUT_CHARS = 8000;
+export const URL_TIMEOUT_MS = 30_000;
+export const MAX_URL_BYTES = 262_144;
+const SNAPSHOT = 'monitor_last_output.txt';
+/** Bytes kept from a script's stdout or stderr; the pipe keeps draining past it. */
+export const MAX_SCRIPT_OUTPUT_BYTES = 1_048_576;
+/** Node's timer ceiling (a longer delay fires at once). */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * Secrets out of a script's output before it reaches a prompt, a chat or a
+ * hash. Hermes runs its `agent/redact.py` redactor (13 pattern families);
+ * this is a partial transcription: every value the daemon holds as a secret
+ * (the profile vault) by value, and the common credential shapes Hermes's
+ * prefix and private-key patterns catch.
+ */
+const SECRET_SHAPES = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}/g,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+  /\bxox[abposr]-[A-Za-z0-9-]{10,}/g,
+  /\bxapp-[A-Za-z0-9-]{10,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+  /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/g,
+  /(authorization:\s*(?:bearer|basic)\s+)[^\s]+/gi,
+];
+
+export function redactSecrets(text, secrets = []) {
+  let out = String(text ?? '');
+  for (const value of secrets) if (typeof value === 'string' && value.length >= 8) out = out.split(value).join('***');
+  for (const re of SECRET_SHAPES) out = out.replace(re, (m, head) => (typeof head === 'string' && m.startsWith(head) ? `${head}***` : '***'));
+  return out;
+}
+
+/** Hermes `_get_script_timeout`: `HERMES_CRON_SCRIPT_TIMEOUT`, then `cron.script_timeout_seconds`, then an hour. */
+export function scriptTimeoutSeconds(profile, env = process.env) {
+  for (const raw of [env.HERMES_CRON_SCRIPT_TIMEOUT, profile?.residue?.config?.cron?.script_timeout_seconds]) {
+    if (raw === undefined || raw === null || String(raw).trim() === '') continue;
+    const n = Math.trunc(Number(String(raw).trim()));
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return DEFAULT_SCRIPT_TIMEOUT_S;
+}
+
+/**
+ * A child's environment: a short allowlist of what a script needs to run,
+ * plus `HERMES_HOME` (the profile folder). Stricter than Hermes, which passes
+ * its whole environment minus the secrets it scrubs (`build_subprocess_env`);
+ * a script that needs another variable reads it from its own files.
+ */
+function scriptEnv() {
+  const env = {};
+  for (const k of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'USER', 'SHELL']) if (process.env[k] !== undefined) env[k] = process.env[k];
+  return env;
+}
+
+/**
+ * Hermes `_run_job_script`: the script must live under the profile's
+ * `scripts/` (a relative path resolves there; an absolute or `~` path must
+ * resolve inside it, symlinks followed); `.sh`/`.bash` run with bash, anything
+ * else with python3; the cwd is the job's workdir, else the scripts folder.
+ * Returns `{ok, output}`; a failure's output is the reason, in Hermes's words.
+ */
+export async function runJobScript(profile, scriptPath, workdir = null, { env = process.env, signal = null, secrets = [] } = {}) {
+  const raw = String(scriptPath ?? '');
+  if (raw.includes('\0')) return { ok: false, output: `Blocked: script path contains a NUL byte: ${JSON.stringify(raw)}` };
+  const scriptsDir = join(profile.dir, 'scripts');
+  mkdirSync(scriptsDir, { recursive: true });
+  const root = realpathSync(scriptsDir);
+  const expanded = raw === '~' || raw.startsWith('~/') ? join(homedir(), raw.slice(1)) : raw;
+  const candidate = resolve(isAbsolute(expanded) ? expanded : join(root, expanded));
+  // containment before existence, as Hermes checks it: nothing is said about a path outside
+  const inside = (p) => p === root || p.startsWith(`${root}/`);
+  if (!inside(candidate)) return { ok: false, output: `Blocked: script path resolves outside the scripts directory (${root}): ${JSON.stringify(raw)}` };
+  if (!existsSync(candidate)) return { ok: false, output: `Script not found: ${candidate}` };
+  const path = realpathSync(candidate);
+  if (!inside(path)) return { ok: false, output: `Blocked: script path resolves outside the scripts directory (${root}): ${JSON.stringify(raw)}` };
+  if (!statSync(path).isFile()) return { ok: false, output: `Script path is not a file: ${path}` };
+  const argv = ['.sh', '.bash'].includes(extname(path).toLowerCase()) ? ['bash', [path]] : ['python3', [path]];
+  const cwd = workdir && existsSync(workdir) ? workdir : dirname(path);
+  const timeoutS = scriptTimeoutSeconds(profile, env);
+  return new Promise((done) => {
+    const out = { stdout: [], stderr: [] };
+    const size = { stdout: 0, stderr: 0 };
+    let finished = false;
+    const child = spawn(argv[0], argv[1], { cwd, env: { ...scriptEnv(), HERMES_HOME: profile.dir }, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already gone */ } };
+    const end = (result) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      done(result);
+    };
+    const onAbort = () => { kill(); end({ ok: false, output: 'Script cancelled because the daemon is stopping' }); };
+    const timer = setTimeout(() => { kill(); end({ ok: false, output: `Script timed out after ${timeoutS}s: ${path}` }); }, Math.min(timeoutS * 1000, MAX_TIMER_MS));
+    timer.unref?.();
+    if (signal?.aborted) onAbort(); else signal?.addEventListener?.('abort', onAbort, { once: true });
+    // kept up to the cap and decoded once, so a split multi-byte character is whole
+    for (const name of ['stdout', 'stderr']) {
+      child[name].on('data', (chunk) => {
+        if (size[name] >= MAX_SCRIPT_OUTPUT_BYTES) return;
+        const room = MAX_SCRIPT_OUTPUT_BYTES - size[name];
+        out[name].push(chunk.length > room ? chunk.subarray(0, room) : chunk);
+        size[name] += Math.min(chunk.length, room);
+      });
+    }
+    const text = (name) => {
+      const decoded = Buffer.concat(out[name]).toString('utf8').trim();
+      return redactSecrets(size[name] >= MAX_SCRIPT_OUTPUT_BYTES ? `${decoded}\n... [output truncated]` : decoded, secrets);
+    };
+    child.on('error', (error) => end({ ok: false, output: `Script execution failed: ${error.message}` }));
+    child.on('close', (code) => {
+      const stdout = text('stdout');
+      const stderr = text('stderr');
+      if (code !== 0) {
+        const parts = [`Script exited with code ${code}`];
+        if (stderr) parts.push(`stderr:\n${stderr}`);
+        if (stdout) parts.push(`stdout:\n${stdout}`);
+        end({ ok: false, output: parts.join('\n') });
+      } else end({ ok: true, output: stdout });
+    });
+  });
+}
+
+/** `cron/monitor.py` `_fetch_monitor_url`: a bounded GET, the body as text. */
+async function fetchMonitorUrl(url, signal = null) {
+  if (!/^https?:\/\//i.test(url)) return { ok: false, output: `monitor_url must be http(s): ${JSON.stringify(url)}` };
+  try {
+    const res = await fetch(url, { headers: { 'user-agent': 'hermes-cron-monitor' }, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(URL_TIMEOUT_MS)]) : AbortSignal.timeout(URL_TIMEOUT_MS) });
+    if (!res.ok) return { ok: false, output: `monitor_url fetch failed: HTTP Error ${res.status}: ${res.statusText}` };
+    const reader = res.body?.getReader();
+    const chunks = [];
+    let size = 0;
+    while (reader) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      size += value.length;
+      if (size > MAX_URL_BYTES) { await reader.cancel(); break; }
+    }
+    return { ok: true, output: Buffer.concat(chunks).subarray(0, MAX_URL_BYTES).toString('utf8') };
+  } catch (error) {
+    return { ok: false, output: `monitor_url fetch failed: ${error.message}` };
+  }
+}
+
+/**
+ * `difflib.unified_diff(old, new, fromfile="previous", tofile="current",
+ * lineterm="")` over lines, with its three lines of context and range format.
+ * The matching is a longest common subsequence (difflib's matcher differs on
+ * some inputs; the block is context for a model, not a patch).
+ */
+export function unifiedDiff(oldText, newText) {
+  const a = splitlines(oldText);
+  const b = splitlines(newText);
+  const codes = opcodes(a, b);
+  const out = [];
+  for (const group of grouped(codes, 3)) {
+    if (!out.length) out.push('--- previous', '+++ current');
+    const first = group[0];
+    const last = group[group.length - 1];
+    out.push(`@@ -${range(first[1], last[2])} +${range(first[3], last[4])} @@`);
+    for (const [tag, i1, i2, j1, j2] of group) {
+      if (tag === 'equal') { for (const line of a.slice(i1, i2)) out.push(` ${line}`); continue; }
+      if (tag === 'replace' || tag === 'delete') for (const line of a.slice(i1, i2)) out.push(`-${line}`);
+      if (tag === 'replace' || tag === 'insert') for (const line of b.slice(j1, j2)) out.push(`+${line}`);
+    }
+  }
+  const diff = out.join('\n');
+  return diff.length > MAX_DIFF_CHARS ? `${diff.slice(0, MAX_DIFF_CHARS)}\n... [diff truncated]` : diff;
+}
+
+/** Python's `str.splitlines()`: every line boundary it knows, no trailing empty line. */
+function splitlines(text) {
+  const lines = String(text).split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/);
+  if (lines.length && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+function range(start, stop) {
+  let beginning = start + 1;
+  const length = stop - start;
+  if (length === 1) return `${beginning}`;
+  if (!length) beginning -= 1;
+  return `${beginning},${length}`;
+}
+
+/** difflib-shaped opcodes from a longest common subsequence (a whole replace past 4M cells). */
+function opcodes(a, b) {
+  const n = a.length;
+  const m = b.length;
+  if (n * m > 4_000_000) return n || m ? [['replace', 0, n, 0, m]] : [];
+  const L = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) L[i][j] = a[i] === b[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+  const codes = [];
+  const push = (tag, i1, i2, j1, j2) => {
+    const prev = codes[codes.length - 1];
+    if (prev && prev[0] === tag) { prev[2] = i2; prev[4] = j2; return; }
+    if (prev && tag !== 'equal' && prev[0] !== 'equal') { prev[0] = 'replace'; prev[2] = i2; prev[4] = j2; return; }
+    codes.push([tag, i1, i2, j1, j2]);
+  };
+  let i = 0;
+  let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) { push('equal', i, i + 1, j, j + 1); i++; j++; }
+    else if (j < m && (i === n || L[i][j + 1] >= L[i + 1][j])) { push('insert', i, i, j, j + 1); j++; }
+    else { push('delete', i, i + 1, j, j); i++; }
+  }
+  return codes;
+}
+
+/** difflib `get_grouped_opcodes(n)`. */
+function grouped(codes, n) {
+  if (!codes.length) return [];
+  const cs = codes.map((c) => [...c]);
+  if (cs[0][0] === 'equal') { const [t, i1, i2, j1, j2] = cs[0]; cs[0] = [t, Math.max(i1, i2 - n), i2, Math.max(j1, j2 - n), j2]; }
+  const z = cs.length - 1;
+  if (cs[z][0] === 'equal') { const [t, i1, i2, j1, j2] = cs[z]; cs[z] = [t, i1, Math.min(i2, i1 + n), j1, Math.min(j2, j1 + n)]; }
+  const groups = [];
+  let group = [];
+  for (let [tag, i1, i2, j1, j2] of cs) {
+    if (tag === 'equal' && i2 - i1 > n + n) {
+      group.push([tag, i1, Math.min(i2, i1 + n), j1, Math.min(j2, j1 + n)]);
+      groups.push(group);
+      group = [];
+      i1 = Math.max(i1, i2 - n);
+      j1 = Math.max(j1, j2 - n);
+    }
+    group.push([tag, i1, i2, j1, j2]);
+  }
+  if (group.length && !(group.length === 1 && group[0][0] === 'equal')) groups.push(group);
+  return groups;
+}
+
+/**
+ * `cron/monitor.py` `check_monitor`: run the source; its exact output bytes are
+ * hashed. Unchanged → `{changed: false}`. Changed or first → the snapshot is
+ * written before the agent runs (detection is the state boundary) and the
+ * block goes into the prompt; the hash rides back for the reducer to keep in
+ * `monitor_state`. A source that fails persists nothing.
+ */
+export async function checkMonitor(profile, job, gate, { workdir = null, signal = null, secrets = [] } = {}) {
+  const source = gate.monitor_script
+    ? await runJobScript(profile, gate.monitor_script, workdir, { signal, secrets })
+    : await fetchMonitorUrl(gate.monitor_url, signal);
+  if (!source.ok) return { ok: false, error: source.output };
+  const output = source.output;
+  const hash = createHash('sha256').update(output, 'utf8').digest('hex');
+  const last = job.residue?.monitor_state?.last_output_hash ?? null;
+  if (last !== null && hash === last) return { ok: true, changed: false };
+  const snapshot = join(profile.dir, 'cron', 'output', job.id, SNAPSHOT);
+  let old = '';
+  try { if (last !== null && existsSync(snapshot)) old = readFileSync(snapshot, 'utf8'); } catch { /* as in Hermes: read failures give no previous output */ }
+  const shown = output.length > MAX_OUTPUT_CHARS ? `${output.slice(0, MAX_OUTPUT_CHARS)}\n... [output truncated]` : output;
+  const block = last === null
+    ? `## Monitor Baseline (first run)\n\nThis is the first observation of the monitored source — there is no previous output to diff against.\n\n### Current output\n\n\`\`\`\n${shown}\n\`\`\``
+    : `## MONITOR CHANGE DETECTED\n\nThe monitored source's output changed since the last run.\n\n### Diff (previous → current)\n\n\`\`\`diff\n${unifiedDiff(old, output)}\n\`\`\`\n\n### Current output\n\n\`\`\`\n${shown}\n\`\`\``;
+  try {
+    mkdirSync(dirname(snapshot), { recursive: true });
+    writeFileSync(snapshot, output);
+  } catch { /* as in Hermes: a failed snapshot write is logged there, not fatal */ }
+  return { ok: true, changed: true, hash, block };
+}