@volter/supercode-interchange 0.1.22 → 0.1.24

package/trigger-records.mjs

@@ -0,0 +1,77 @@
+// Inbound-trigger facts from the complete owning-home read. Secret values do
+// not cross this projection; authentication is only their recorded presence.
+import { stringifyNativeJsonMember } from './native-json.mjs';
+import { hermesDelivery } from './hermes-read-validation.mjs';
+import { nativeTrim } from './text.mjs';
+import { hermesYamlKeys } from './hermes-read-yaml.mjs';
+
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const text = (row, key) => typeof row?.[key] === 'string' && row[key] ? row[key] : null;
+function scalar(row, key) {
+  const value = row?.[key];
+  return typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' ? stringifyNativeJsonMember(row, key) : null;
+}
+function webhook(name, events, delivery, raw, authenticated, description) {
+  const deliver = { target: delivery == null ? 'log' : delivery.kind === 'explicit' ? delivery.platform : delivery.kind };
+  const chat = (delivery?.kind === 'explicit' ? delivery.chat_id : null) ?? (scalar(raw, 'deliver_chat_id') || null);
+  if (chat != null) deliver.chat_id = chat;
+  const result = { name, kind: 'webhook', deliver, enabled: typeof raw.enabled === 'boolean' ? raw.enabled : raw.enabled !== 'false', authenticated };
+  if (events.length) result.events = events;
+  if (description != null) result.description = description;
+  return result;
+}
+export function folderTriggerRecords(subscriptions, config) {
+  const dynamic = Object.keys(subscriptions).sort(compare).map(name => {
+    const raw = subscriptions[name], events = Array.isArray(raw.events) ? raw.events.map((value, at) => typeof value === 'string' ? value : stringifyNativeJsonMember(raw.events, String(at))) : [];
+    return webhook(name, events, hermesDelivery('', name, raw.deliver, raw.deliver_extra), raw, typeof raw.secret === 'string', raw.description);
+  });
+  // The channel codec flattens only its top-level extra object, in source
+  // member order; a placeholder enters credentials rather than extras.
+  const channel = config.platforms?.webhook;
+  let routes;
+  const extra = value => { if (!(typeof value === 'string' && /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/u.test(value))) routes = value; };
+  if (object(channel)) for (const key of hermesYamlKeys(channel)) {
+    const value = channel[key];
+    if (key === 'extra' && object(value) && Object.hasOwn(value, 'routes')) extra(value.routes);
+    else if (key === 'extra.routes') extra(value);
+  }
+  const fixed = object(routes) ? hermesYamlKeys(routes).flatMap(name => {
+    const raw = routes[name]; if (!object(raw)) return [];
+    const events = Array.isArray(raw.events) ? raw.events.flatMap((_, at) => { const word = scalar(raw.events, String(at)); return word == null ? [] : [word]; })
+      : typeof raw.events === 'string' ? raw.events.replace(/^[\[\]]+|[\[\]]+$/gu, '').split(',').map(word => nativeTrim(word).replace(/^["']+|["']+$/gu, '')).filter(Boolean) : [];
+    const word = scalar(raw, 'deliver') || null;
+    const delivery = word == null ? null : { kind: 'explicit', platform: word, chat_id: scalar(raw.deliver_extra, 'chat_id') || null };
+    return [webhook(name, events, delivery, raw, Object.hasOwn(raw, 'secret'), scalar(raw, 'description'))];
+  }) : [];
+  return { dynamic, fixed };
+}
+export function openclawTriggerRecords(config, profiles, defaultAgent) {
+  const hooks = config.hooks; if (!object(hooks)) return null;
+  const enabled = typeof hooks.enabled === 'boolean' ? hooks.enabled : false;
+  const authenticated = typeof hooks.token === 'string' || Object.hasOwn(hooks, 'tokenFile');
+  const base = (text(hooks, 'path') ?? '/hooks').replace(/\/+$/u, '');
+  const perProfile = new Map([...profiles.keys()].sort(compare).map(name => [name, new Map()]));
+  if (Array.isArray(hooks.mappings)) hooks.mappings.forEach((raw, index) => {
+    if (!object(raw)) return;
+    const id = text(raw, 'id') ?? `hook-${index}`;
+    const owner = raw.agentId === defaultAgent ? 'default' : typeof raw.agentId === 'string' ? raw.agentId : 'default';
+    const selected = perProfile.get(owner) ?? perProfile.get('default');
+    const match = object(raw.match) ? raw.match : {}, path = text(match, 'path');
+    const name = text(raw, 'id') ?? path?.replace(/^\/+/, '') ?? `mapping-${index}`;
+    const deliver = {}, target = {}, events = [];
+    for (const [wire, field] of [['action', 'action'], ['profile', 'agentId'], ['session_key', 'sessionKey'], ['wake_mode', 'wakeMode'], ['model', 'model']]) { const value = text(raw, field); if (value != null) target[wire] = value; }
+    if (typeof raw.deliver === 'string') {
+      deliver.target = raw.deliver;
+      if (typeof raw.to === 'string' || typeof raw.to === 'number') deliver.chat_id = scalar(raw, 'to');
+    } else { const value = text(raw, 'channel'); if (value != null) deliver.target = value; }
+    for (const key of ['source', 'event']) { const value = text(match, key); if (value != null) events.push(`${key}=${value}`); }
+    const row = { name, kind: 'hook_mapping', route: `${base}/${path?.replace(/^\/+/, '') ?? name}`, target, deliver,
+      enabled: enabled && (typeof raw.enabled === 'boolean' ? raw.enabled : true), authenticated };
+    if (events.length) row.events = events;
+    const description = text(raw, 'description'); if (description != null) row.description = description;
+    selected.set(id, { index, row });
+  });
+  const mappings = [...perProfile.values()].flatMap(subs => [...subs.keys()].sort(compare).map(name => subs.get(name))).sort((a, b) => a.index - b.index).map(value => value.row);
+  return { enabled, authenticated, base, mappings };
+}

package/triggers-read.mjs

@@ -0,0 +1,67 @@
+// Recorded inbound endpoints after complete home validity. No endpoint is
+// opened, resolved or modified by this reader.
+import { isAbsolute } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { readTriggerFolderHome } from './hermes-read-home.mjs';
+import { readOpenclawTriggerHome } from './openclaw-profile-home.mjs';
+import { nativeDuplicateObjectKeys, parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+
+export const TRIGGER_HARNESSES = Object.freeze(['hermes', 'openclaw', 'orchestrator']);
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const refuse = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+const filesystem = (path, cwd) => !path.length || isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/u.test(path) ? path : join(cwd, path);
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) refuse(`${name} has too many fields`);
+    return parseNativeJson(`{${value.map((_, at) => `${JSON.stringify(fields[at])}:${stringifyNativeJsonMember(value, String(at))}`).join(',')}}`);
+  }
+  if (!object(value)) refuse(`${name} must be a struct`);
+  if (nativeDuplicateObjectKeys(value).some(key => fields.includes(key))) refuse(`${name} has a duplicate field`);
+  return value;
+}
+function query(params, env) {
+  const selected = struct(params, ['harness', 'homes'], 'triggers params');
+  if (selected.harness != null && typeof selected.harness !== 'string') refuse('harness must be a string');
+  const homes = resolveHarnessHomes(env);
+  if (Object.hasOwn(selected, 'homes')) {
+    const supplied = struct(selected.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') refuse(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  if (selected.harness != null && !TRIGGER_HARNESSES.includes(selected.harness)) refuse(`\`${selected.harness}\` has no inbound-trigger store Volter Harness reads; \`triggers.list\` is supported for: ${TRIGGER_HARNESSES.join(', ')}`, -32020);
+  return { harness: selected.harness ?? null, homes };
+}
+function folderRows(harness, supplied, cwd) {
+  const home = harness === 'hermes' ? parent(supplied) ?? '.' : supplied;
+  let profiles; try { profiles = readTriggerFolderHome(filesystem(home, cwd), harness); } catch { return []; }
+  const rows = [];
+  for (const name of [...profiles.keys()].filter(name => harness !== 'hermes' || name === 'default').sort((a, b) => Number(a !== 'default') - Number(b !== 'default') || compare(a, b))) {
+    const dir = name === 'default' ? home : join(join(home, 'profiles'), name), selected = profiles.get(name);
+    for (const [records, file] of [[selected.dynamic, 'webhook_subscriptions.json'], [selected.fixed, 'config.yaml']]) for (const record of records) {
+      const target = { action: 'background' }; if (name !== 'default') target.profile = name;
+      rows.push({ ...record, harness, route: `${name === 'default' ? '' : `/p/${name}`}/webhooks/${record.name}`, target, source: join(dir, file) });
+    }
+  }
+  return rows;
+}
+function openclawRows(home, cwd) {
+  let hooks; try { hooks = readOpenclawTriggerHome(filesystem(home, cwd)); } catch { return []; }
+  if (hooks == null) return [];
+  const { base, enabled, authenticated } = hooks, source = join(home, 'openclaw.json');
+  const builtin = (name, session_key, description) => ({ name, harness: 'openclaw', kind: `builtin_${name}`, route: `${base}/${name}`, target: { action: name, session_key }, deliver: {}, enabled, authenticated, source, description });
+  return [builtin('wake', 'main', 'built-in: enqueue a system event into the main session'), builtin('agent', 'isolated', 'built-in: run an isolated agent turn'),
+    ...hooks.mappings.map(row => ({ ...row, harness: 'openclaw', source }))];
+}
+export function listTriggers(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const selected = query(params, env);
+  return { schema: 'supercode.triggers.v1', triggers: TRIGGER_HARNESSES.flatMap(harness => selected.harness != null && selected.harness !== harness ? []
+    : harness === 'openclaw' ? openclawRows(selected.homes.openclaw, cwd) : folderRows(harness, selected.homes[harness], cwd)).map(row => ({
+      name: row.name, harness: row.harness, kind: row.kind, route: row.route, ...(row.events?.length ? { events: row.events } : {}),
+      target: row.target, deliver: row.deliver, enabled: row.enabled, authenticated: row.authenticated, source: row.source,
+      ...(row.description != null ? { description: row.description } : {}),
+    })) };
+}

package/workflow-read.mjs

@@ -0,0 +1,165 @@
+// The complete read-only board codec. Mutations and dispatch remain the
+// owning harness's verbs; opening these tables creates no board or index.
+import { readdirSync, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { childPath } from './session-spend-files.mjs';
+import { profilePathJoin as join } from './profile-paths.mjs';
+import { hermesTableExists, readHermesRows } from './hermes-read-store.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, parseNativeJson, setNativeFloat, setNativeInteger, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { nativeTrim } from './text.mjs';
+
+const minimum = -(1n << 63n), maximum = (1n << 63n) - 1n;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const compare = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const file = path => { try { return statSync(path).isFile(); } catch { return false; } };
+const invalid = message => { throw Object.assign(new Error(message), { rpcCode: -32602 }); };
+const filesystem = (path, cwd) => isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/u.test(path) ? path : childPath(cwd, path);
+const taskColumns = new Set(['id', 'title', 'body', 'assignee', 'status', 'priority', 'created_by', 'created_at', 'started_at', 'completed_at', 'workspace_kind', 'workspace_path', 'branch_name', 'tenant', 'idempotency_key', 'result', 'skills', 'model_override', 'provider_override']);
+const lanes = new Set(['triage', 'todo', 'scheduled', 'ready', 'running', 'blocked', 'review', 'done', 'archived']);
+
+function params(value) {
+  if (Array.isArray(value)) {
+    if (value.length > 2) invalid('workflow load params have too many fields');
+    value = parseNativeJson(`{${value.map((_, at) => `${JSON.stringify(['from', 'home'][at])}:${stringifyNativeJsonMember(value, String(at))}`).join(',')}}`);
+  }
+  if (!object(value)) invalid('workflow load params must be a struct');
+  if (nativeDuplicateObjectKeys(value).some(key => ['from', 'home'].includes(key))) invalid('workflow load params have a duplicate field');
+  if (typeof value.home !== 'string') invalid('home must be a string');
+  if (value.from != null && !['hermes', 'supercode'].includes(value.from)) invalid('from must be hermes or supercode');
+  return { home: value.home, from: value.from ?? null };
+}
+function text(row, key) {
+  const value = row[key];
+  return typeof value === 'string' ? value.length ? value : null : typeof value === 'number' ? stringifyNativeJsonMember(row, key) : null;
+}
+function integer(row, key) {
+  const value = row[key];
+  if (typeof value === 'number') return nativeInteger(row, key, { signed: true });
+  if (typeof value !== 'string' || !/^[+-]?[0-9]+$/u.test(value)) return null;
+  const exact = BigInt(value); return exact < minimum || exact > maximum ? null : exact;
+}
+function sortedJson(value, parent, key) {
+  if (Array.isArray(value)) return `[${value.map((child, at) => sortedJson(child, value, String(at))).join(',')}]`;
+  if (object(value)) return `{${Object.keys(value).sort(compare).map(name => `${JSON.stringify(name)}:${sortedJson(value[name], value, name)}`).join(',')}}`;
+  return parent === undefined ? stringifyNativeJson(value) : stringifyNativeJsonMember(parent, key);
+}
+function jsonValue(row, key) {
+  const value = text(row, key); if (value == null) return undefined;
+  try {
+    const parsed = parseNativeJson(value);
+    // A shallow numeric box retains the scalar token. Object parsing keeps
+    // the native depth boundary rather than spending it on a wrapper.
+    return typeof parsed === 'number' ? parseNativeJson(`{"value":${value}}`) : { value: parseNativeJson(sortedJson(parsed)) };
+  } catch { return undefined; }
+}
+const jsonText = (row, key) => jsonValue(row, key)?.value;
+
+// sidecar::ms_to_rfc3339: saturating seconds-to-ms conversion, Euclidean
+// remainder and negative whole seconds clamped to epoch. BigInt also keeps
+// calendar years beyond JavaScript Date's range rather than rounding them.
+function at(row, key) {
+  const seconds = integer(row, key); if (seconds == null) return null;
+  const product = seconds * 1000n, ms = product < minimum ? minimum : product > maximum ? maximum : product;
+  const millis = (ms % 1000n + 1000n) % 1000n;
+  const secs = ms < 0n ? 0n : ms / 1000n, days = secs / 86400n, rem = secs % 86400n;
+  const z = days + 719468n, era = z / 146097n, doe = z - era * 146097n;
+  const yoe = (doe - doe / 1460n + doe / 36524n - doe / 146096n) / 365n;
+  const yearBase = yoe + era * 400n, doy = doe - (365n * yoe + yoe / 4n - yoe / 100n);
+  const mp = (5n * doy + 2n) / 153n, day = doy - (153n * mp + 2n) / 5n + 1n;
+  const month = mp < 10n ? mp + 3n : mp - 9n, year = month <= 2n ? yearBase + 1n : yearBase;
+  const pad = (value, width = 2) => String(value).padStart(width, '0');
+  return `${pad(year, 4)}-${pad(month)}-${pad(day)}T${pad(rem / 3600n)}:${pad(rem % 3600n / 60n)}:${pad(rem % 60n)}.${pad(millis, 3)}Z`;
+}
+function skills(row) {
+  const value = jsonText(row, 'skills');
+  return Array.isArray(value) ? value.filter(item => typeof item === 'string') : (text(row, 'skills') ?? '').split(',').map(nativeTrim).filter(Boolean);
+}
+const ordered = entries => parseNativeJson(`{${[...entries].sort(([left], [right]) => compare(left, right)).map(([key, value]) => `${JSON.stringify(key)}:${stringifyNativeJson(value)}`).join(',')}}`);
+function task(row) {
+  const id = text(row, 'id'); if (id == null) return null;
+  const status = text(row, 'status') ?? '', lane = lanes.has(status) ? status : 'unknown';
+  const recordedKind = text(row, 'workspace_kind'), kind = recordedKind == null ? 'scratch' : ['scratch', 'dir', 'worktree'].includes(recordedKind) ? recordedKind : 'unknown';
+  const kept = new Map(Object.keys(row).filter(key => !taskColumns.has(key) && row[key] != null).map(key => [key, stringifyNativeJsonMember(row, key)]));
+  if (lane === 'unknown') kept.set('status', JSON.stringify(status));
+  if (kind === 'unknown') kept.set('workspace_kind', stringifyNativeJsonMember(row, 'workspace_kind'));
+  const residue = parseNativeJson(`{${[...kept].sort(([left], [right]) => compare(left, right)).map(([key, encoded]) => `${JSON.stringify(key)}:${encoded}`).join(',')}}`);
+  const result = { id, title: text(row, 'title') ?? '', body: text(row, 'body'), assignee: text(row, 'assignee'), machine: null, subtask_of: null, lane, priority: 0,
+    tenant: text(row, 'tenant'), idempotency_key: text(row, 'idempotency_key'), workspace: { kind, path: text(row, 'workspace_path'), branch: text(row, 'branch_name') }, skills: skills(row),
+    model: text(row, 'model_override'), provider: text(row, 'provider_override'), created_by: text(row, 'created_by'), created_at: at(row, 'created_at'), started_at: at(row, 'started_at'), completed_at: at(row, 'completed_at'),
+    result: text(row, 'result'), attempts: [], reviews: [], comments: [], residue };
+  setNativeInteger(result, 'priority', integer(row, 'priority') ?? 0n); return result;
+}
+function attemptSession(value) {
+  const field = key => typeof value?.[key] === 'string' ? value[key] : null;
+  const result = { surface: field('surface'), id: field('session_id'), harness: field('harness'), machine: field('machine'), pane: field('pane'), address: field('address'), mode: field('mode'), pid: null };
+  const pid = nativeInteger(value, 'pid', { signed: true }); if (pid != null) setNativeInteger(result, 'pid', pid); return result;
+}
+function attempt(row) {
+  const id = text(row, 'id'); if (id == null) return null;
+  const summary = text(row, 'summary'), box = jsonValue(row, 'metadata'); let metadata = box?.value, session = null;
+  if (object(metadata) && Object.hasOwn(metadata, 'supercode')) { session = attemptSession(metadata.supercode); delete metadata.supercode; }
+  if (object(metadata) && !Object.keys(metadata).length) metadata = undefined;
+  const handoff = summary != null || metadata !== undefined ? { summary, metadata: metadata ?? null } : null;
+  if (handoff && typeof metadata === 'number') {
+    const exact = nativeInteger(box, 'value');
+    if (exact == null) setNativeFloat(handoff, 'metadata', metadata); else setNativeInteger(handoff, 'metadata', exact);
+  }
+  return { id, profile: text(row, 'profile'), step: text(row, 'step_key'), status: text(row, 'status') ?? '', started_at: at(row, 'started_at'), ended_at: at(row, 'ended_at'),
+    outcome: text(row, 'outcome'), handoff, error: text(row, 'error'), session };
+}
+function review(row) {
+  const verdicts = { review_requested: 'requested', approved: 'approved', review_approved: 'approved', changes_requested: 'changes_requested', escalated: 'escalated' };
+  const kind = text(row, 'kind'), verdict = Object.hasOwn(verdicts, kind) ? verdicts[kind] : null;
+  if (verdict == null) return null;
+  const payload = jsonText(row, 'payload'), field = key => typeof payload?.[key] === 'string' ? payload[key] : null;
+  return { verdict, by: field('reviewer') ?? field('by') ?? field('profile'), reason: field('reason'), at: at(row, 'created_at') };
+}
+const rows = (db, table, sql) => hermesTableExists(db, table) ? readHermesRows(db, sql) ?? [] : [];
+function board(slug, root, db) {
+  const tasks = new Map();
+  for (const row of rows(db, 'tasks', 'SELECT * FROM tasks')) { const value = task(row); if (value) tasks.set(value.id, value); }
+  for (const row of rows(db, 'supercode_cards', 'SELECT * FROM supercode_cards')) {
+    const value = tasks.get(text(row, 'task_id')); if (value) { value.machine = text(row, 'machine'); value.subtask_of = text(row, 'subtask_of'); }
+  }
+  for (const row of rows(db, 'task_runs', 'SELECT * FROM task_runs ORDER BY id')) {
+    const value = tasks.get(text(row, 'task_id')), run = attempt(row); if (value && run) value.attempts.push(run);
+  }
+  for (const row of rows(db, 'task_events', 'SELECT task_id, kind, payload, created_at FROM task_events ORDER BY id')) {
+    const value = tasks.get(text(row, 'task_id')), event = review(row); if (value && event) value.reviews.push(event);
+  }
+  for (const row of rows(db, 'task_comments', 'SELECT task_id, author, body, created_at FROM task_comments ORDER BY id')) {
+    const value = tasks.get(text(row, 'task_id')), author = text(row, 'author'), body = text(row, 'body');
+    if (value && author != null && body != null) value.comments.push({ author, body, at: at(row, 'created_at') });
+  }
+  const dependencies = rows(db, 'task_links', 'SELECT parent_id, child_id FROM task_links ORDER BY parent_id, child_id').flatMap(row => {
+    const parent = text(row, 'parent_id'), child = text(row, 'child_id'); return parent != null && child != null ? [{ parent, child }] : [];
+  });
+  return { slug, name: null, root, tasks: ordered(tasks), dependencies };
+}
+function named(home) {
+  const root = join(join(home, 'kanban'), 'boards'); let entries;
+  try { entries = readdirSync(root, { encoding: 'buffer' }); } catch { return []; }
+  return entries.sort(Buffer.compare).flatMap(entry => { try { const slug = utf8.decode(entry); return slug && !slug.startsWith('_') ? [{ slug, path: childPath(root, entry) }] : []; } catch { return []; } });
+}
+function declaresSupercode(home) {
+  if (file(join(join(home, 'kanban'), 'ztrack.json'))) return true;
+  const boards = join(join(home, 'kanban'), 'boards');
+  try { return readdirSync(boards, { encoding: 'buffer' }).some(entry => file(childPath(childPath(boards, entry), 'ztrack.json'))); }
+  catch { return false; }
+}
+
+export function loadWorkflow(paramsValue, context = {}) {
+  const selected = params(paramsValue), home = filesystem(selected.home, context.cwd ?? process.cwd());
+  let from = selected.from;
+  if (from == null) from = declaresSupercode(home) || !file(join(home, 'kanban.db')) ? 'supercode' : 'hermes';
+  const boards = new Map(), name = from === 'hermes' ? 'kanban.db' : 'ztrack.json';
+  const defaultFile = from === 'hermes' ? join(home, name) : join(join(home, 'kanban'), name);
+  if (file(defaultFile)) boards.set('default', board('default', selected.home, from === 'hermes' ? defaultFile : `${defaultFile}.board.db`));
+  for (const entry of named(home)) {
+    const marker = childPath(entry.path, name); if (!file(marker)) continue;
+    const displayed = join(join(join(selected.home, 'kanban'), 'boards'), entry.slug);
+    boards.set(entry.slug, board(entry.slug, displayed, from === 'hermes' ? marker : childPath(entry.path, `${name}.board.db`)));
+  }
+  return { workflow: { root: selected.home, boards: ordered(boards) } };
+}