@volter/supercode-orchestrator 0.4.4

package/mcp/tools.mjs

@@ -0,0 +1,57 @@
+// The orchestrator's model-facing tool table (docs/ORCHESTRATOR-IR.md §7; docs/plans/hermes-compat.md row 13).
+//
+// The worker's model sees Hermes's own tools: `hermes-tools.json` is the pinned Hermes's (v2026.8.31)
+// registry schemas, name, description and parameters, as its model receives them (`registry.get_schema`,
+// and `SEND_MESSAGE_SCHEMA` for `send_message`, which Hermes registers per platform). One word differs:
+// `cronjob.script` names "the home's scripts/" where Hermes prints its own home's path. Regenerated from
+// the pin when Hermes moves, never edited by hand.
+//
+// What serves each: `cronjob` and `send_message` are the orchestrator's (its jobs and deliveries are in
+// its state); `session_search`, `memory`, `skills_list` and `skill_view` are Hermes's own handlers
+// against the profile's home (`hermes-cli.mjs` `hermesTool`), since the sessions, memories and skills
+// they read are that home's. `session_handoff` is the orchestrator's `/handoff` as a tool; Hermes has no
+// tool for it.
+//
+// The table is shared by `server.mjs` (which publishes it over MCP) and `bridge.mjs` (which dispatches it
+// against the orchestrator's state), so a verb cannot be published without an implementation.
+
+import { readFileSync } from 'node:fs';
+
+/** MCP protocol version this server speaks — the same revision `crates/harness/src/mcp.rs` names. */
+export const PROTOCOL_VERSION = '2025-06-18';
+
+/** The name the worker's harness registers these tools under. */
+export const SERVER_NAME = 'orchestrator';
+
+const HERMES_TOOLS = JSON.parse(readFileSync(new URL('./hermes-tools.json', import.meta.url), 'utf8'));
+
+export const TOOLS = Object.freeze([
+  ...HERMES_TOOLS,
+  {
+    name: 'session_handoff',
+    // The `/handoff <platform>` chat command (§4.5), as a tool.
+    description:
+      'Hand this session off to another platform: marks the binding pending and posts a pickup notice to the '
+      + "profile's home chat on that platform.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: { type: 'string', description: 'The platform to hand off to, e.g. "telegram".' },
+        note: { type: 'string', description: 'Optional line to include in the pickup notice.' },
+      },
+      required: ['to'],
+    },
+  },
+]);
+
+/**
+ * The board's tools, for a worker a dispatch spawned for a task (docs/plans/hermes-compat.md row 14):
+ * Hermes's fourteen `kanban_*`, from the pin's registry as `hermes-tools.json` is, published only where
+ * the task is in the door's environment (`HERMES_KANBAN_TASK`), as Hermes's own gate publishes them.
+ */
+export const KANBAN_TOOLS = Object.freeze(JSON.parse(readFileSync(new URL('./hermes-kanban-tools.json', import.meta.url), 'utf8')));
+
+/** The tools Hermes's own handlers serve, against the profile's home. */
+export const HERMES_SERVED = Object.freeze(['session_search', 'memory', 'skills_list', 'skill_view']);
+
+export const TOOL_NAMES = Object.freeze(TOOLS.map((t) => t.name));

package/mcp/verbs.mjs

@@ -0,0 +1,348 @@
+// What each model-facing tool DOES, against the orchestrator's one state value
+// (docs/ORCHESTRATOR-IR.md §7). `mcp/tools.mjs` publishes the table; this
+// module is the other half — a verb cannot be published without landing here.
+//
+// Every verb runs inside the loop: it mutates the state value and returns the
+// effects (§5) the loop then performs on its own queue, so a tool call is
+// ordered against inbound messages and ticks like anything else. It performs
+// no I/O of its own except Hermes's: the tools Hermes's own handlers serve
+// (`session_search`, `memory`, `skills_list`, `skill_view`) and its schedule
+// parser, each against the profile's home.
+//
+// Every result names what it did in `ran`.
+
+import { homeChannel } from '../ir.mjs';
+import { join } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { decodeContextFrom, parseTarget, renderTarget, resolveRoute, surfaceKeyString } from '../ir.mjs';
+import { liveBinding } from '../reducer.mjs';
+import * as events from '../events.mjs';
+import { compactStamp, gateFields, homeZone, nextRunAt, parseCron, payloadError, scheduleError, scriptPathError } from '../cron.mjs';
+import { applyOperator, hermesJobArgs } from '../operator.mjs';
+import { hermesSchedule, hermesTool } from '../hermes-cli.mjs';
+import { modelError } from '../activation.mjs';
+
+/**
+ * cron/jobs.py `_normalize_workdir`, transcribed: returns the absolute,
+ * symlink-resolved path string, or null when unset/blank; throws Hermes's own
+ * messages on relative, missing, or non-directory input.
+ */
+export function normalizeWorkdir(workdir) {
+  if (workdir === undefined || workdir === null) return null;
+  const raw = String(workdir).trim();
+  if (!raw) return null;
+  const expanded = raw === '~' || raw.startsWith('~/') ? join(homedir(), raw.slice(1)) : raw;
+  if (!expanded.startsWith('/')) {
+    throw new Error(`Cron workdir must be an absolute path (got '${raw}'). Cron jobs run detached from any shell cwd, so relative paths are ambiguous.`);
+  }
+  if (!existsSync(expanded)) throw new Error(`Cron workdir does not exist: ${expanded}`);
+  const resolved = realpathSync(expanded);
+  if (!statSync(resolved).isDirectory()) throw new Error(`Cron workdir is not a directory: ${resolved}`);
+  return resolved;
+}
+
+/** Inverse of `surfaceKeyString` (`platform|kind|chat_id|thread_id|participant_id`). */
+export function keyFromString(text) {
+  if (!text) return null;
+  const p = String(text).split('|');
+  if (!p[0] || !p[1]) return null;
+  const key = { platform: p[0], kind: p[1] };
+  if (p[2]) key.chat_id = p[2];
+  if (p[3]) key.thread_id = p[3];
+  if (p[4]) key.participant_id = p[4];
+  return key;
+}
+
+/**
+ * Which profile a surface belongs to, by the same rule `handleInbound` uses
+ * (§4.1 step 2): the profile that owns the adapter resolves its routes, and an
+ * unrouted key stays with the owner. This is what makes another profile's
+ * surface refusable rather than merely undocumented.
+ */
+export function routedProfile(state, key) {
+  const profiles = Object.values(state.profiles);
+  const owner = profiles.find((p) => p.channels && p.channels[key.platform]) ?? state.profiles.default ?? profiles[0];
+  if (!owner) return null;
+  return resolveRoute(owner.routes, key) ?? owner.name;
+}
+
+const UNIT_MINUTES = { m: 1, min: 1, mins: 1, minute: 1, minutes: 1, h: 60, hr: 60, hour: 60, hours: 60, d: 1440, day: 1440, days: 1440 };
+
+/**
+ * Hermes's `schedule` string, or the IR's typed `Schedule` (§2.6), to the typed
+ * form. Four of Hermes's five documented forms are read here; any other string
+ * (natural day/time, "every monday 9am") is Hermes's own parser's
+ * (`cron.jobs.parse_schedule`, through the pinned Hermes against `home`), whose
+ * answer is one of the same three kinds. A cron without a zone runs on the
+ * home's clock (`homeZone`), as under Hermes.
+ */
+export function parseSchedule(spec, now, home = null) {
+  // a model that serializes the typed form as a JSON string (measured in
+  // ORC-8's paid run: `"{\"kind\": \"interval\", \"minutes\": 120}"`) means the
+  // typed form; parse it rather than refuse the call
+  if (typeof spec === 'string' && /^\s*\{/.test(spec)) {
+    try { spec = JSON.parse(spec); } catch { /* not JSON: fall through to the string forms */ }
+  }
+  if (spec && typeof spec === 'object') {
+    switch (spec.kind) {
+      case 'once':
+        if (!Number.isFinite(Date.parse(spec.run_at))) throw new Error('schedule.run_at must be an instant');
+        return { kind: 'once', run_at: new Date(Date.parse(spec.run_at)).toISOString() };
+      case 'interval':
+        if (!(spec.minutes > 0)) throw new Error('schedule.minutes must be a positive number');
+        return { kind: 'interval', minutes: Number(spec.minutes) };
+      case 'cron': {
+        // the expression AND the zone: a zone `Intl` does not know is refused
+        // here, by name, not discovered after the job's first run (§4.3)
+        const cron = { kind: 'cron', expr: String(spec.expr ?? ''), ...(spec.tz ? { tz: String(spec.tz) } : {}) };
+        const broken = scheduleError(cron);
+        if (broken) throw new Error(broken);
+        return cron;
+      }
+      default:
+        throw new Error(`schedule.kind must be once | interval | cron, got ${JSON.stringify(spec.kind)}`);
+    }
+  }
+  const raw = String(spec ?? '').trim();
+  const t = raw.toLowerCase();
+  const once = /^in\s+(\d+)\s*([a-z]+)$/.exec(t);
+  if (once) {
+    const minutes = Number(once[1]) * (UNIT_MINUTES[once[2]] ?? NaN);
+    if (!Number.isFinite(minutes)) throw new Error(`schedule ${JSON.stringify(raw)}: unknown unit ${JSON.stringify(once[2])}`);
+    return { kind: 'once', run_at: new Date(Date.parse(now) + minutes * 60000).toISOString() };
+  }
+  const every = /^(?:every\s+)?(\d*)\s*([a-z]+)$/.exec(t);
+  if (every && UNIT_MINUTES[every[2]] !== undefined) {
+    return { kind: 'interval', minutes: (every[1] ? Number(every[1]) : 1) * UNIT_MINUTES[every[2]] };
+  }
+  if (raw.split(/\s+/).filter(Boolean).length === 5) {
+    parseCron(raw);
+    return { kind: 'cron', expr: raw };
+  }
+  const at = Date.parse(raw);
+  if (Number.isFinite(at)) return { kind: 'once', run_at: new Date(at).toISOString() };
+  const hermes = home && raw ? hermesSchedule(home, raw) : null;
+  if (hermes) return parseSchedule({ kind: hermes.kind, run_at: hermes.run_at, minutes: hermes.minutes, expr: hermes.expr }, now);
+  throw new Error(
+    `schedule ${JSON.stringify(raw)} is not a schedule: use '30m' / 'every 2h', 'in 30m', five-field cron `
+    + "('0 9 * * *'), an ISO timestamp, or the typed {kind: once|interval|cron} form. Day/time phrasing "
+    + "such as 'every monday 9am' is read by Hermes's parser, and none is installed here — write it as cron.",
+  );
+}
+
+/** A chat key out of Hermes's `deliver`/`target` grammar, resolved against this profile. */
+function targetKey(profile, word, origin) {
+  const parsed = parseTarget('mcp/send_message', 'target', word);
+  if (!parsed || parsed.kind === 'origin') {
+    if (!origin) throw new Error('this session has no surface to answer; name a target');
+    return { ...origin };
+  }
+  if (parsed.kind === 'home') {
+    const home = homeChannel(profile);
+    if (!home) throw new Error(`profile ${profile.name} has no home channel (/sethome)`);
+    return home;
+  }
+  if (parsed.kind === 'local') throw new Error("send_message does not write files; use a cron job's deliver: 'local'");
+  if (!parsed.chat_id) {
+    const home = homeChannel(profile, parsed.platform);
+    if (home) return home;
+    throw new Error(`no home chat on ${parsed.platform}; name it as ${parsed.platform}:<chat_id>`);
+  }
+  const key = { platform: parsed.platform, kind: 'dm', chat_id: parsed.chat_id };
+  if (parsed.thread_id) key.thread_id = parsed.thread_id;
+  return key;
+}
+
+/** Where `send_message` can reach from this profile, in its target grammar: each home chat, each live conversation. */
+function sendTargets(state, profile) {
+  const rows = new Map();
+  for (const [platform, channel] of Object.entries(profile.channels ?? {})) {
+    const home = channel?.extra?.home_channel;
+    if (home?.chat_id) rows.set(platform, { target: platform, platform, chat_id: String(home.chat_id), name: home.name ?? null, home: true });
+  }
+  for (const b of Object.values(profile.bindings)) {
+    const k = b.key;
+    if (b.ended_at || !k?.chat_id || ['cron', 'webhook', 'local'].includes(k.platform)) continue;
+    const target = [k.platform, k.chat_id, k.thread_id].filter(Boolean).join(':');
+    if (!rows.has(target) && routedProfile(state, k) === profile.name) rows.set(target, { target, platform: k.platform, chat_id: k.chat_id, kind: k.kind, home: false });
+  }
+  return [...rows.values()];
+}
+
+function jobId(profile, now) {
+  const stem = `job_${compactStamp(now)}`;
+  if (!profile.jobs[stem]) return stem;
+  for (let n = 2; ; n++) if (!profile.jobs[`${stem}_${n}`]) return `${stem}_${n}`;
+}
+
+/** The per-profile harness home the loop activates a worker with (`activationEnv`). */
+export function harnessHomes(profile) {
+  const harness = profile.worker?.harness;
+  if (!harness) return undefined;
+  const home = join(profile.dir, harness);
+  // `HarnessHomes`/`SkillHomes` key each harness by its snake_case id; hermes
+  // is keyed by its state.db path, whose parent is the HERMES_HOME.
+  return { [harness.replace(/-/g, '_')]: harness === 'hermes' ? join(home, 'state.db') : home };
+}
+
+// ---------------------------------------------------------------- the verbs
+
+/**
+ * @param {object} orch          the running Orchestrator
+ * @param {object} call          { verb, args, profile, surface }
+ * @returns {Promise<{result: object, effects: object[]}>}
+ */
+export async function runVerb(orch, { verb, args = {}, profile: profileName, surface }) {
+  const state = orch.state;
+  const profile = state.profiles[profileName];
+  if (!profile) throw new Error(`unknown profile ${profileName}`);
+  const now = orch.clock();
+  const binding = surface ? profile.bindings[surface] ?? null : null;
+  const key = binding?.key ?? keyFromString(surface);
+  const effects = [];
+
+  switch (verb) {
+    case 'cronjob': {
+      // Hermes's one cron tool (tools/cronjob_tools.py `cronjob`), its actions on the orchestrator's jobs
+      const action = String(args.action ?? '').trim().toLowerCase();
+      if (action === 'create') {
+        args = hermesJobArgs(args);
+        // the model's door: Hermes's path rule for scripts, then its payload rule
+        for (const key of ['script', 'monitor_script']) { const bad = scriptPathError(args[key]); if (bad) throw new Error(bad); }
+        const gate = gateFields(args);
+        const empty = payloadError(args, gate);
+        if (empty) throw new Error(empty);
+        // Hermes's tool, stricter than create_job: an agent job needs a prompt or skills
+        const prompt = typeof args.prompt === 'string' && args.prompt.trim();
+        const skilled = Array.isArray(args.skills) && args.skills.some((x) => String(x).trim());
+        if (!gate.no_agent && !prompt && !skilled) throw new Error('an agent job needs a prompt or skills (a script alone needs no_agent)');
+        const schedule = parseSchedule(args.schedule, now, profile.dir);
+        // Hermes's tool contract (cron/jobs.py `_normalize_workdir`, measured in
+        // ORC-8's week): the workdir is trimmed, `~`-expanded, refused when
+        // relative (jobs run detached from any shell cwd), symlink-RESOLVED, and
+        // must be an existing directory. The same model call must store the same
+        // string here, or the two worlds' jobs.json disagree on `/tmp` vs
+        // `/private/tmp`. Only an operator-authored job (config/jobs.json) may be
+        // profile-relative.
+        const workdir = normalizeWorkdir(args.workdir);
+        const unusable = modelError(profile.worker?.harness, args.model ? String(args.model) : null);
+        if (unusable) throw new Error(unusable);
+        const id = jobId(profile, now);
+        const job = {
+          id,
+          schedule,
+          prompt: typeof args.prompt === 'string' ? args.prompt : '',
+          workdir,
+          model: args.model ? String(args.model) : null,
+          skills: Array.isArray(args.skills) ? args.skills.map(String) : [],
+          context_from: decodeContextFrom('cronjob', 'context_from', args.context_from),
+          deliver: parseTarget('mcp/cronjob', 'deliver', args.deliver) ?? { kind: 'origin' },
+          failure_deliver: parseTarget('mcp/cronjob', 'failure_deliver', args.failure_deliver),
+          // `origin` is captured from the binding, never from an argument: a job
+          // created in this conversation delivers back to this conversation.
+          origin: key ? { platform: key.platform, chat_type: key.kind ?? null, chat_id: key.chat_id ?? null, thread_id: key.thread_id ?? null } : null,
+          attach_to_session: typeof args.attach_to_session === 'boolean' ? args.attach_to_session : null,
+          // Hermes's `repeat`: an integer is "run N times", "forever"/absent is unlimited (`cron/jobs.py:812-830`)
+          repeat: Number.isInteger(args.repeat) && args.repeat > 0 ? { times: args.repeat, completed: 0 } : null,
+          enabled: true,
+          next_run_at: nextRunAt(schedule, now, homeZone(profile)),
+          last_run_at: null,
+          last_status: null,
+          created_at: now,
+          // Hermes's `name` has no IR field; it rides the residue channel verbatim (§1 rule 6).
+          residue: { ...(args.name ? { name: String(args.name) } : {}), ...(Array.isArray(args.enabled_toolsets) && args.enabled_toolsets.length ? { enabled_toolsets: args.enabled_toolsets.map(String) } : {}), ...gate },
+        };
+        await orch.dispatch(events.operator({ verb: 'jobs_create', profile: profile.name, args: { job }, at: now }));
+        return {
+          effects,
+          result: {
+            ran: `created cron job ${id} (${describeSchedule(schedule)}) in profile ${profile.name}, delivering to ${renderTarget(job.deliver)}`,
+            job_id: id,
+            next_run_at: job.next_run_at,
+            origin: job.origin,
+          },
+        };
+      }
+      if (action === 'list') {
+        const jobs = Object.values(profile.jobs).map((j) => ({
+          job_id: j.id,
+          name: j.residue?.name ?? null,
+          schedule: describeSchedule(j.schedule),
+          enabled: j.enabled,
+          deliver: renderTarget(j.deliver),
+          next_run_at: j.next_run_at,
+          last_status: j.last_status,
+          prompt: j.prompt,
+        }));
+        return { effects, result: { ran: `listed ${jobs.length} cron job(s) in profile ${profile.name}`, jobs } };
+      }
+      const op = { update: 'jobs.update', pause: 'jobs.pause', resume: 'jobs.resume', run: 'jobs.run', remove: 'jobs.delete' }[action];
+      if (!op) throw new Error(`action must be one of create, list, update, pause, resume, remove, run (got ${JSON.stringify(args.action ?? '')})`);
+      const id = String(args.job_id ?? '').trim();
+      if (!id) throw new Error(`job_id is required for ${action}; list first — never guess job IDs`);
+      if (!profile.jobs[id]) throw new Error(`no job ${JSON.stringify(id)} in profile ${profile.name}; list first`);
+      if (action === 'run' && typeof args.prompt === 'string' && args.prompt.trim()) {
+        throw new Error("run's transient prompt is not served here; run the job as it stands, or update its prompt");
+      }
+      const opArgs = action === 'update' ? { ...hermesJobArgs(args, profile.jobs[id]), id } : { id };
+      if (action === 'update') {
+        delete opArgs.action; delete opArgs.job_id;
+        if (typeof opArgs.workdir === 'string' && opArgs.workdir.trim()) opArgs.workdir = normalizeWorkdir(opArgs.workdir);
+        for (const key of ['script', 'monitor_script']) { const bad = opArgs[key] ? scriptPathError(opArgs[key]) : null; if (bad) throw new Error(bad); }
+      }
+      const answer = await applyOperator(state, op, opArgs, profile.name, now, (event) => orch.dispatch(event));
+      if (!answer.ok) throw new Error(answer.error);
+      return { effects, result: answer.result };
+    }
+
+    case 'send_message': {
+      // Hermes's send_message: `send` (the default) and `list`; reactions are not a door these adapters have
+      const action = String(args.action ?? 'send').trim().toLowerCase() || 'send';
+      if (action === 'list') {
+        const targets = sendTargets(state, profile);
+        return { effects, result: { ran: `listed ${targets.length} target(s) for profile ${profile.name}`, targets } };
+      }
+      if (action === 'react' || action === 'unreact') throw new Error(`send_message action ${action} is not served by this orchestrator's platform adapters`);
+      if (action !== 'send') throw new Error(`action must be one of send, list, react, unreact (got ${JSON.stringify(args.action)})`);
+      if (typeof args.message !== 'string' || !args.message) throw new Error('message is required');
+      const target = targetKey(profile, args.target, key);
+      const owner = routedProfile(state, target);
+      if (owner && owner !== profile.name) {
+        throw new Error(`${surfaceKeyString(target)} belongs to profile ${owner}, not ${profile.name}; a session may only message its own profile's surfaces`);
+      }
+      const fx = await orch.dispatch(events.operator({ verb: 'send_message', profile: profile.name, args: { key: target, text: args.message }, at: now }));
+      const obligationId = fx.find((e) => e.type === 'deliver')?.obligation_id ?? null;
+      return { effects, result: { ran: `queued a message to ${surfaceKeyString(target)}`, obligation_id: obligationId } };
+    }
+
+    case 'session_search':
+    case 'memory':
+    case 'skills_list':
+    case 'skill_view': {
+      // Hermes's own handler against this profile's home: its sessions (the workers' mirrored beside
+      // Hermes's), its memories, its skills; answered in Hermes's words
+      const verbatim = await hermesTool(profile.dir, verb, args, { sessionId: binding?.worker?.session_id ?? null });
+      return { effects, result: { ran: `${verb} in profile ${profile.name}`, verbatim: typeof verbatim === 'string' ? verbatim : JSON.stringify(verbatim) } };
+    }
+
+    case 'session_handoff': {
+      const to = args.to ? String(args.to) : '';
+      if (!to) throw new Error('to is required');
+      const b = surface ? liveBinding(profile, surface) : null;
+      if (!b) throw new Error('No live session to hand off.');
+      await orch.dispatch(events.operator({ verb: 'session_handoff', profile: profile.name, args: { keyString: surface, to, note: args.note ? String(args.note) : null }, at: now }));
+      if (b.handoff?.state !== 'pending') return { effects, error: `Cannot hand off: ${b.handoff?.error ?? 'unknown reason'}.` };
+      return { effects, result: { ran: `handed off to ${to}; the binding is pending pickup`, session_id: b.worker.session_id } };
+    }
+
+    default:
+      throw new Error(`unknown verb ${verb}`);
+  }
+}
+
+function describeSchedule(s) {
+  if (s.kind === 'once') return `once at ${s.run_at}`;
+  if (s.kind === 'interval') return `every ${s.minutes} min`;
+  return `cron ${s.expr}${s.tz ? ` ${s.tz}` : ''}`;
+}