@volter/supercode-orchestrator 0.4.4

package/ir.mjs

@@ -0,0 +1,205 @@
+// The orchestrator IR's runtime vocabulary: the surface key, the delivery
+// target, the route match, and the empty shapes the loop starts from.
+//
+// The records themselves are the ontology's (`crates/interchange/src/orchestration/`,
+// generated into `ontology.d.ts`), and reading or writing a folder is the
+// harness's orchestration doors (`orchestration.mjs`). What lives here is what the reducer,
+// the scheduler, the operator door and the adapters compute with in memory,
+// and nothing that decodes or encodes a file.
+//
+// Nothing in this module touches the filesystem or a clock.
+
+export class LoadError extends Error {
+  constructor(file, key, message) {
+    super(`${file}${key ? ` [${key}]` : ''}: ${message}`);
+    this.name = 'LoadError';
+    this.file = file;
+    this.key = key;
+  }
+}
+
+// ---------------------------------------------------------------- helpers
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Hermes `cron/jobs.py:2486-2492`: `context_from` is a list of job ids (or
+ * `"self"`) whose most recent output is prepended at fire time; a string is
+ * one id, an empty value is none. Stored as a list or null, as Hermes stores it.
+ */
+export function decodeContextFrom(file, key, v) {
+  if (v === undefined || v === null) return null;
+  const items = typeof v === 'string' ? [v] : Array.isArray(v) ? v : null;
+  if (!items) throw new LoadError(file, key, 'expected a job id, a list of job ids, or "self"');
+  const refs = items.map((x) => String(x).trim()).filter(Boolean);
+  return refs.length ? refs : null;
+}
+
+// ---------------------------------------------------------------- surface keys
+
+export const CHAT_TYPES = new Set(['dm', 'group', 'channel', 'thread']);
+
+/** `agent:<profile>:<platform>:<kind>[:<chat_id>][:<thread_id>][:<participant_id>]` */
+export function renderSurfaceKey(profile, key) {
+  const parts = ['agent', profile || 'main', key.platform, key.kind];
+  if (key.chat_id) parts.push(key.chat_id);
+  if (key.thread_id) parts.push(key.thread_id);
+  if (key.participant_id) parts.push(key.participant_id);
+  return parts.join(':');
+}
+
+/** Inverse of renderSurfaceKey for the simple (unescaped) forms Hermes writes. */
+export function parseSurfaceKey(text) {
+  const p = String(text).split(':');
+  if (p[0] !== 'agent' || p.length < 4) return null;
+  const key = { platform: p[2], kind: p[3] };
+  if (p[4]) key.chat_id = p[4];
+  if (p[5]) key.thread_id = p[5];
+  if (p[6]) key.participant_id = p[6];
+  return { profile: p[1] === 'main' ? 'default' : p[1], key };
+}
+
+export function surfaceKeyString(key) {
+  return [key.platform, key.kind, key.chat_id ?? '', key.thread_id ?? '', key.participant_id ?? ''].join('|');
+}
+
+// ---------------------------------------------------------------- targets
+
+/** Hermes `deliver` word → Target. `origin | local | home | <platform>[:<chat_id>[:<thread_id>]]`. */
+export function parseTarget(file, key, word, extra) {
+  if (word === undefined || word === null) return null;
+  if (typeof word !== 'string' || word.length === 0) throw new LoadError(file, key, 'expected a delivery word');
+  if (word === 'origin' || word === 'local' || word === 'home') return { kind: word };
+  const p = word.split(':');
+  const t = { kind: 'explicit', platform: p[0] };
+  const chat = p[1] ?? extra?.chat_id ?? null;
+  if (chat) t.chat_id = String(chat);
+  const thread = p[2] ?? extra?.thread_id ?? null;
+  if (thread) t.thread_id = String(thread);
+  return t;
+}
+
+export function renderTarget(t) {
+  if (!t) return null;
+  if (t.kind !== 'explicit') return t.kind;
+  let s = t.platform;
+  if (t.chat_id) s += `:${t.chat_id}`;
+  if (t.thread_id) s += `:${t.thread_id}`;
+  return s;
+}
+
+// ---------------------------------------------------------------- O-records
+
+/**
+ * Hermes's session reset (`gateway/config.py` `SessionResetPolicy`), read from the home's own
+ * `session_reset:` (or `gateway.session_reset:`): `mode` none | daily | idle | both, `at_hour` (local,
+ * default 4), `idle_minutes` (default 1440). Hermes's default is `none`: a session never resets on its own.
+ */
+export function sessionReset(profile) {
+  const config = profile?.residue?.config ?? {};
+  const raw = config.session_reset ?? config.gateway?.session_reset ?? {};
+  return {
+    mode: raw.mode ?? 'none',
+    at_hour: raw.at_hour ?? 4,
+    idle_minutes: raw.idle_minutes ?? 1440,
+  };
+}
+
+/**
+ * A platform's home channel as Hermes keeps it (`platforms.<p>.home_channel`, where `/sethome` saves it),
+ * as a chat key; with no platform, the first platform that has one. Null when there is none.
+ */
+/**
+ * A surface as Hermes's session key (`gateway/session.py` `build_session_key`), the form the codec writes
+ * into `gateway_routing` (Rust `render_hermes_session_key`): `agent:<main|profile>:<platform>:<kind>` and
+ * then the chat, thread and participant that are present.
+ */
+export function hermesSessionKey(profileName, key) {
+  if (key?.key?.startsWith?.('agent:')) return key.key;
+  const ns = !profileName || profileName === 'default' ? 'main' : profileName;
+  return ['agent', ns, key.platform ?? '', key.kind ?? '', key.chat_id, key.thread_id, key.participant_id].filter((part, i) => i < 4 || (part !== undefined && part !== null && part !== '')).join(':');
+}
+
+export function homeChannel(profile, platform = null) {
+  const channels = profile?.channels ?? {};
+  const names = platform ? [platform] : Object.keys(channels);
+  for (const name of names) {
+    const h = channels[name]?.extra?.home_channel;
+    if (h?.chat_id) {
+      // Hermes's home channel names no chat kind; addressed as an explicit target is (`chatKey`)
+      const key = { platform: name, kind: 'dm', chat_id: String(h.chat_id) };
+      if (h.thread_id) key.thread_id = String(h.thread_id);
+      return key;
+    }
+  }
+  return null;
+}
+
+export const END_REASONS = new Set(['idle', 'daily', 'reset', 'new', 'handoff', 'error']);
+
+export const FIRE_STATUSES = new Set(['claimed', 'running', 'succeeded', 'failed', 'timeout', 'unknown']);
+
+export const OBLIGATION_STATES = new Set(['pending', 'sent', 'failed', 'dropped']);
+
+/** Most-specific-first: thread > chat > guild > platform; ties by declaration order. */
+export function routeSpecificity(r) {
+  return (r.match.thread_id ? 8 : 0) + (r.match.chat_id ? 4 : 0) + (r.match.guild_id ? 2 : 0) + 1;
+}
+
+export function resolveRoute(routes, key, guildId) {
+  let best = null;
+  for (const r of routes) {
+    const m = r.match;
+    if (m.platform !== key.platform) continue;
+    if (m.guild_id && m.guild_id !== guildId) continue;
+    if (m.chat_id && m.chat_id !== key.chat_id) continue;
+    if (m.thread_id && m.thread_id !== key.thread_id) continue;
+    if (!best || routeSpecificity(r) > routeSpecificity(best)) best = r;
+  }
+  return best ? best.profile : null;
+}
+
+// ---------------------------------------------------------------- profiles / state
+
+export function emptyProfile(name, dir) {
+  return {
+    name, dir,
+    worker: null,
+    persona: null,
+    channels: {},
+    routes: [],
+    jobs: {},
+    subscriptions: {},
+    access: { allowlist: {}, admins: {}, policy: {} },
+    bindings: {},
+    fires: [],
+    obligations: [],
+    residue: { config: {}, files: [] },
+  };
+}
+
+export function emptyRuntime() {
+  return { leases: {}, queues: {}, adapters: {}, pending_requests: {}, clock: null };
+}
+
+export function emptyState(root) {
+  return { root, profiles: { default: emptyProfile('default', root) }, runtime: emptyRuntime() };
+}
+
+/** Stable, secret-free JSON of the persisted half of the state (runtime omitted). */
+export function canonicalJson(value) {
+  return JSON.stringify(sortKeys(value), null, 2) + '\n';
+}
+export function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (isObj(v)) {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortKeys(v[k]);
+    return out;
+  }
+  return v;
+}
+export function persistedView(state) {
+  const { runtime, ...rest } = state;
+  return rest;
+}

package/kanban-worker.mjs

@@ -0,0 +1,155 @@
+// A worker for one board task (docs/plans/hermes-compat.md row 14). Hermes's dispatcher spawns its worker
+// as `hermes -p <assignee> --cli --accept-hooks [--skills <s>]… [-m <model> [--provider <p>]]
+// [--reasoning <e>] [--toolsets <t>] chat -q "work kanban task <id>" [-Q]`, detached, in the task's
+// workspace, its output to the task's log, the task in its environment (`KANBAN_ENV`), and watches the
+// pid. The orchestrator's loop runs that dispatcher with `HERMES_BIN` naming `bin/hermes-worker.mjs`, so
+// this is the process Hermes spawned and watches: it runs the assignee profile's own worker for the one
+// query, with Hermes's task protocol, the task's skills and the home's memory in its system prompt and the
+// board's tools on its door, prints the answer to the log and exits, as `hermes chat -q` does. A profile
+// whose worker is Hermes runs Hermes itself.
+import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
+import { load } from './orchestration.mjs';
+import { INSTRUCTION_ARGUMENTS, activationCwd, activationEnv, sandboxArguments, approvalPolicy, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter } from './activation.mjs';
+import { workerRoute } from './worker-route.mjs';
+import { KANBAN_ENV, untrustedServerVerdict, hermesApproval, hermesInstall, hermesToolEnv, kanbanPrompt, memorySnapshot, mirrorSession } from './hermes-cli.mjs';
+import { mountOrchestratorMcp } from './mcp/mount.mjs';
+import { normalizeWorkerEvent, WORKER_STORE } from './loop.mjs';
+import { permissionResponse } from './reducer.mjs';
+
+/** Hermes's worker argv, as `_default_spawn` builds it. */
+export function parseHermesArgv(argv) {
+  const out = { profile: null, skills: [], model: null, provider: null, reasoning: null, toolsets: null, query: null, quiet: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === '-p' || a === '--profile') out.profile = next();
+    else if (a === '--skills' || a === '-s') out.skills.push(...String(next()).split(',').map((x) => x.trim()).filter(Boolean));
+    else if (a === '-m' || a === '--model') out.model = next();
+    else if (a === '--provider') out.provider = next();
+    else if (a === '--reasoning') out.reasoning = next();
+    else if (a === '--toolsets') out.toolsets = next();
+    else if (a === '-q' || a === '--query') out.query = next();
+    else if (a === '-Q') out.quiet = true;
+  }
+  return out;
+}
+
+/** The orchestrator's root for a profile's home: the root is the `default` profile, `profiles/<name>` the rest. */
+function rootOf(home) {
+  return basename(dirname(home)) === 'profiles' ? dirname(dirname(home)) : home;
+}
+
+export async function runKanbanWorker(argv, env = process.env) {
+  const say = (line) => process.stdout.write(`${line}\n`);
+  const args = parseHermesArgv(argv);
+  if (!env.HERMES_HOME || !args.query) { say('hermes-worker: HERMES_HOME and -q are required (the dispatcher sets both)'); return 2; }
+  const home = resolve(env.HERMES_HOME);
+  const root = rootOf(home);
+  const { state, vault } = await load(root);
+  const profile = Object.values(state.profiles).find((p) => resolve(p.dir) === home) ?? state.profiles[args.profile ?? 'default'];
+  if (!profile?.worker?.harness) { say(`hermes-worker: no worker for profile ${args.profile ?? home}`); return 2; }
+  if (profile.worker.harness === 'hermes') return runHermes(argv, env);
+  const harness = profile.worker.harness;
+  const task = Object.fromEntries(KANBAN_ENV.filter((k) => env[k]).map((k) => [k, env[k]]));
+  const taskId = task.HERMES_KANBAN_TASK ?? 'none';
+  const workspace = env.HERMES_KANBAN_WORKSPACE;
+  const cwd = workspace && existsSync(workspace) && statSync(workspace).isDirectory() ? workspace : activationCwd(profile, profile.worker.cwd);
+  const worker = { ...profile.worker, ...(args.model ? { model: args.model } : {}) };
+  if (args.toolsets) say(`hermes-worker: --toolsets ${args.toolsets} is Hermes's agent's setting, carried and not performed for ${harness}`);
+
+  materializePersona(profile);
+  materializeSkills(profile);
+  const route = workerRoute(profile, worker, vault);
+  const surfaceKey = `kanban|task|${taskId}`;
+  const runEnv = { ...hermesToolEnv(profile.dir), ...activationEnv({ root, profile, surfaceKey, vault }), ...route.env, ...task };
+  // Hermes's system prompt for a dispatched worker: the home's memory, the task protocol, the task's skills
+  const memory = await memorySnapshot(profile.dir).catch(() => '');
+  const board = await kanbanPrompt(profile.dir, { skills: args.skills, task: taskId, env: task });
+  const instructions = [memory, board.guidance, board.skills].filter(Boolean).join('\n\n');
+
+  const client = new SupercodeHarnessClient(env.SUPERCODE_BIN ? { command: env.SUPERCODE_BIN } : {});
+  try {
+    return await runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say });
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+async function runTurn({ client, profile, harness, worker, route, root, vault, surfaceKey, runEnv, instructions, task, cwd, args, say }) {
+  const descriptor = (await client.supportReport()).harnesses.find((h) => h.id === harness);
+  const base = descriptor?.runtime?.default_launch;
+  if (!base) { say(`hermes-worker: ${harness} publishes no launch`); return 2; }
+  const reasoning = args.reasoning && harness === 'codex' ? ['-c', `model_reasoning_effort=${JSON.stringify(args.reasoning)}`] : [];
+  const launch = {
+    program: base.program,
+    arguments: [...(base.arguments ?? []), ...modelArguments(worker), ...route.args, ...(instructions && INSTRUCTION_ARGUMENTS[harness] ? INSTRUCTION_ARGUMENTS[harness](instructions) : []), ...reasoning, ...sandboxArguments(profile, harness), ...limitArguments(profile, worker, (level, line) => say(line))],
+    env: { ...(base.env ?? {}), ...runEnv },
+  };
+  const mount = mountOrchestratorMcp({ root, profile, harness, surfaceKey, launch, vault, task });
+  const policy = approvalPolicy(profile, harness);
+  const runtime = await client.startManagedRuntime({ harness, cwd, launch: mount.launch, ...(mount.mcp_servers ? { mcp_servers: mount.mcp_servers } : {}), ...(policy ? { approval_policy: policy } : {}) });
+  let text = '';
+  // `agent.max_turns` for a worker that takes no cap at launch, held as the daemon holds it (loop.mjs `holdTurnLimit`)
+  const counter = turnCounter(profile, harness);
+  const outcome = await new Promise((done) => {
+    const on = (ev) => {
+      if (counter?.count(ev)) {
+        say(`hermes-worker: ${counter.cap + 1} model calls in one turn passes agent.max_turns ${counter.cap}; the turn is interrupted`);
+        void Promise.resolve(runtime.interrupt?.()).catch((error) => say(`hermes-worker: interrupt failed: ${error.message}`));
+      }
+      let w = normalizeWorkerEvent(ev);
+      if (!w) return;
+      if (w.kind === 'final' && counter) w = counter.settle(w);
+      if (w.kind === 'text') text += w.block && text ? `\n\n${w.delta}` : w.delta;
+      else if (w.kind === 'request') {
+        // Hermes's approval rule for a single-query worker (`approvals.single_query_mode` for a dangerous command)
+        const gated = untrustedServerVerdict(profile, w.tool, 'single_query', { mcp: w.mcp && !String(w.tool ?? '').startsWith('mcp__orchestrator__') });
+        void (gated ? Promise.resolve(gated) : hermesApproval(profile.dir, { command: w.command ?? null, context: 'single_query' })).catch(() => null).then((hermes) => {
+          const approve = hermes ? hermes.verdict === 'allow' : profile.worker?.permission?.unattended === 'approve';
+          if (!hermes || hermes.verdict !== 'allow') say(`hermes-worker: ${approve ? 'approved' : 'denied'} a permission request with nobody attending (${hermes ? `Hermes: ${hermes.why}` : 'worker.permission.unattended'}): ${w.subject}`);
+          runtime.respond(JSON.parse(w.id), permissionResponse(w.options, approve, hermes?.message ?? null)).catch(() => {});
+        });
+      } else if (w.kind === 'final') {
+        if (w.outcome === 'error') say(`hermes-worker: the turn failed: ${w.message ?? 'no reason given'}`);
+        done(w.outcome === 'error' ? 1 : 0);
+      } else if (w.kind === 'error' || w.kind === 'ended') {
+        say(`hermes-worker: the worker ${w.kind === 'error' ? 'failed' : 'ended'}: ${w.message ?? w.reason ?? 'no reason given'}`);
+        done(1);
+      }
+    };
+    runtime.on('event', on);
+    runtime.on('closed', on);
+    runtime.on('runtimeError', on);
+    runtime.sendInput(args.query).catch((error) => { say(`hermes-worker: ${error.message}`); done(1); });
+  });
+  if (text) say(text);
+  // the run's transcript in the home's session store, as a Hermes worker's is: tagged `kanban`
+  await mirrorRun(client, profile, harness, runtime.handle.runtime_id).catch((error) => say(`hermes-worker: mirror: ${error.message}`));
+  await runtime.close().catch(() => {});
+  return outcome;
+}
+
+async function mirrorRun(client, profile, harness, sessionId) {
+  const store = WORKER_STORE[harness];
+  if (!store) return;
+  const { sessions } = await client.discover({ harnesses: [harness], homes: store(join(profile.dir, harness)), include_child_sessions: true, root_session_id: sessionId, limit: 8 });
+  const locator = sessions.find((d) => d.locator.session_id === sessionId)?.locator;
+  if (!locator) return;
+  const loaded = await client.loadWindow(locator, { message_limit: 1_000_000 });
+  await mirrorSession(profile.dir, { id: sessionId, sessionKey: null, binding: { key: { platform: 'kanban' }, worker: { harness } }, session: loaded.session, locator: locator.storage?.path ?? null });
+}
+
+/** A profile whose worker is Hermes: the dispatcher's own command, run as Hermes would have run it. */
+function runHermes(argv, env) {
+  const install = hermesInstall();
+  if (!install?.bin) { process.stdout.write('hermes-worker: the profile\'s worker is Hermes, and no Hermes is installed on PATH\n'); return 2; }
+  const { HERMES_BIN: _, ...rest } = env;
+  return new Promise((done) => {
+    const child = spawn(join(install.bin, 'hermes'), argv, { env: rest, stdio: 'inherit' });
+    child.on('close', (code) => done(code ?? 1));
+    child.on('error', () => done(1));
+  });
+}

package/lease.mjs

@@ -0,0 +1,51 @@
+// The daemon's lease (`<home>/orchestrator.lock`), read the way the Rust
+// `Lease` reads it. A lease names a pid on a machine: a home on a volume that
+// another machine mounted (the sandbox before this one) names that machine's
+// pid, which says nothing here, and a pid from before a restart names nothing
+// now. So a lease is live only on the machine and boot that wrote it.
+import { readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+export const LOCK_FILE = 'orchestrator.lock';
+
+/** This machine's name and, on Linux, its boot id (Rust `this_host`). */
+export function thisHost() {
+  let boot = null;
+  try { boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() || null; } catch { /* not Linux */ }
+  return { host: hostname() || null, boot };
+}
+
+/** `kill(pid, 0)`: liveness without touching the process. EPERM means alive. */
+export function pidIsLive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** Whether the lease is this machine's, since this boot. Only such a lease's pid may be signalled. */
+export function leaseIsHere(lease) {
+  const here = thisHost();
+  if (lease?.host && lease.host !== here.host) return false;
+  if (lease?.boot && here.boot && lease.boot !== here.boot) return false;
+  return true;
+}
+
+/** Whether the daemon a lease names is alive now: here, and its pid live. */
+export function leaseIsLive(lease) {
+  return Boolean(lease) && leaseIsHere(lease) && pidIsLive(lease.pid);
+}
+
+/** The lease, whether or not its daemon lives; null when absent or unreadable. */
+export function readLease(root) {
+  try {
+    const lease = JSON.parse(readFileSync(join(root, LOCK_FILE), 'utf8'));
+    return Number.isInteger(lease?.pid) ? lease : null;
+  } catch {
+    return null;
+  }
+}