@volter/supercode-orchestrator 0.4.4

package/webhook.mjs

@@ -0,0 +1,263 @@
+// Webhooks: `POST /webhooks/<name>` (docs/ORCHESTRATOR-IR.md §4.4).
+//
+//   handleWebhook(state, ev, effects)   the reducer half: verified, subscribed, new -> a turn
+//   renderTemplate(template, payload)   `{field}` / `{a.b}` substitution
+//   verifySignature(secret, body, sig)  HMAC-SHA256, `sha256=<hex>`
+//   startWebhookListener(...)           node:http, no framework
+//
+// Nothing here is imported statically from `node:`: `handleWebhook` runs
+// inside the pure reducer, so the two I/O-bearing functions load `node:crypto`
+// and `node:http` at call time instead.
+
+import { surfaceKeyString, sessionReset } from './ir.mjs';
+import { endBinding, ensureRuntime, expired, leaseId, liveBinding, newObligation } from './reducer.mjs';
+import { compactStamp, resolveTarget } from './cron.mjs';
+import * as events from './events.mjs';
+
+/** The synthetic surface a subscription's turns run on (§4.4). */
+export function webhookKey(name) {
+  return { platform: 'webhook', kind: 'dm', chat_id: name };
+}
+
+/** `{field}` and `{a.b.c}` from the JSON payload; an unknown field is left as written. */
+export function renderTemplate(template, payload) {
+  return String(template ?? '').replace(/\{([A-Za-z0-9_][A-Za-z0-9_.]*)\}/g, (whole, path) => {
+    let v = payload;
+    for (const seg of path.split('.')) {
+      if (v === null || typeof v !== 'object') return whole;
+      v = v[seg];
+    }
+    if (v === undefined || v === null) return whole;
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+  });
+}
+
+/** A body that names its own event, for senders with no event header. */
+function eventType(payload) {
+  if (payload === null || typeof payload !== 'object') return null;
+  const v = payload.event ?? payload.type ?? payload.action ?? null;
+  return typeof v === 'string' ? v : null;
+}
+
+/**
+ * Where a source names the event and the delivery, first match wins: GitHub,
+ * GitLab, Bitbucket (`X-Event-Key`), then the generic spellings. Hermes's
+ * webhook adapter reads the same headers (`gateway/platforms/webhook.py`).
+ */
+export const EVENT_HEADERS = Object.freeze(['x-github-event', 'x-gitlab-event', 'x-event-key', 'x-event-type']);
+export const DELIVERY_HEADERS = Object.freeze(['x-github-delivery', 'x-gitlab-event-uuid', 'webhook-id', 'x-request-id']);
+
+/** Delivery ids remembered per subscription; a redelivery inside this window is dropped. */
+export const DELIVERY_MEMORY = 200;
+
+function firstHeader(headers, names) {
+  for (const name of names) {
+    const v = Array.isArray(headers?.[name]) ? headers[name][0] : headers?.[name];
+    if (typeof v === 'string' && v.trim()) return v.trim();
+  }
+  return null;
+}
+
+/**
+ * `events` entries are event types (`pull_request`); one with a dot names an
+ * action too (`pull_request.opened` matches `<event>.<payload.action>`).
+ */
+export function subscribedTo(events, kind, payload) {
+  if (!kind) return false;
+  const action = payload && typeof payload === 'object' && typeof payload.action === 'string' ? payload.action : null;
+  return events.some((e) => e === kind || (action !== null && e.includes('.') && e === `${kind}.${action}`));
+}
+
+/** The profile that owns a subscription, and the subscription itself. */
+export function findSubscription(state, name) {
+  for (const profile of Object.values(state.profiles)) {
+    const sub = profile.subscriptions[name];
+    if (sub) return { profile, sub };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------- the reducer half
+
+/**
+ * §4.4. Unverified is dropped and logged. Verified renders the template, opens
+ * or reuses the subscription profile's conversation on
+ * `{platform:'webhook', kind:'dm', chat_id:name}`, and sends. The turn's
+ * `final` is delivered per `subscription.deliver` by `cron.mjs`'s `fireFinal`,
+ * which recognises the binding by its `residue.webhook` mark.
+ */
+export function handleWebhook(state, ev, effects) {
+  const now = ev.at;
+  if (!ev.verified) {
+    effects.push({ type: 'log', level: 'warn', message: `webhook ${ev.name}: signature not verified, dropped` });
+    return;
+  }
+  const found = findSubscription(state, ev.name);
+  if (!found) {
+    effects.push({ type: 'log', level: 'warn', message: `webhook ${ev.name}: no subscription, dropped` });
+    return;
+  }
+  const { profile, sub } = found;
+  if (sub.events?.length) {
+    // the source's header names the event (`X-GitHub-Event: pull_request`);
+    // a body's own `action` is not the event. A call naming none is not one
+    // of the subscribed events, as in Hermes.
+    const kind = ev.event ?? eventType(ev.payload);
+    if (!subscribedTo(sub.events, kind, ev.payload)) {
+      const action = typeof ev.payload?.action === 'string' ? `.${ev.payload.action}` : '';
+      effects.push({ type: 'log', level: 'info', message: `webhook ${ev.name}: ${kind ? `${kind}${action}` : 'an unnamed event'} is not subscribed, dropped` });
+      return;
+    }
+  }
+  if (ev.delivery_id) {
+    // a redelivery (GitHub's "Redeliver", a sender's retry) is the same event:
+    // it runs once. The memory is runtime state (§2.8), as Hermes's is: a
+    // restart forgets it.
+    const seen = ((ensureRuntime(state).webhook_deliveries ??= {})[ev.name] ??= []);
+    if (seen.includes(ev.delivery_id)) {
+      effects.push({ type: 'log', level: 'info', message: `webhook ${ev.name}: delivery ${ev.delivery_id} already handled, dropped` });
+      return;
+    }
+    seen.push(ev.delivery_id);
+    if (seen.length > DELIVERY_MEMORY) seen.splice(0, seen.length - DELIVERY_MEMORY);
+  }
+  // Hermes `deliver_only` (`gateway/platforms/webhook.py`): no agent — the
+  // rendered prompt IS the message, delivered to the subscription's target.
+  // A subscription with nowhere real to deliver is refused, as Hermes refuses
+  // it at startup.
+  if (sub.residue?.deliver_only === true) {
+    const target = resolveTarget(null, profile, sub.deliver ?? null);
+    if (target.kind === 'local') {
+      effects.push({ type: 'log', level: 'warn', message: `webhook ${ev.name}: deliver_only needs a real delivery target, not local` });
+      return;
+    }
+    const o = newObligation(profile, target, renderTemplate(sub.prompt_template, ev.payload), { kind: 'webhook', name: ev.name }, now);
+    effects.push({ type: 'log', level: 'info', message: `webhook ${ev.name}: direct delivery to ${target.platform}` });
+    effects.push({ type: 'deliver', profile: profile.name, obligation_id: o.id });
+    effects.push({ type: 'save' });
+    return;
+  }
+  if (!profile.worker) {
+    effects.push({ type: 'log', level: 'warn', message: `webhook ${ev.name}: profile ${profile.name} has no worker configured` });
+    return;
+  }
+
+  const key = webhookKey(ev.name);
+  const keyString = surfaceKeyString(key);
+  let b = liveBinding(profile, keyString);
+  if (b) {
+    const reason = expired(b, sessionReset(profile), now);
+    if (reason) { endBinding(state, profile.name, keyString, reason, now, effects); b = null; }
+  }
+  if (!b) {
+    b = {
+      key,
+      worker: { harness: profile.worker.harness, session_id: `webhook_${ev.name}_${compactStamp(now)}`, locator: null },
+      started_at: now, last_activity_at: now, ended_at: null, end_reason: null,
+      handoff: null, recurrence: null, residue: { webhook: ev.name },
+    };
+    profile.bindings[keyString] = b;
+    effects.push({ type: 'runtime_start', profile: profile.name, keyString, worker: profile.worker, prompt: null });
+  }
+  b.residue.webhook = ev.name;
+  b.last_activity_at = now;
+
+  const text = renderTemplate(sub.prompt_template, ev.payload);
+  const rt = ensureRuntime(state);
+  const lid = leaseId(profile.name, keyString);
+  if (rt.turns[lid] || !rt.leases[lid]) (rt.queues[lid] ??= []).push({ text, at: now });
+  else {
+    rt.turns[lid] = { started_at: now, buffer: '' };
+    effects.push({ type: 'send_input', profile: profile.name, keyString, text });
+  }
+  effects.push({ type: 'save' });
+}
+
+// ---------------------------------------------------------------- signatures
+
+/** `sha256=<hex>` of the raw body under `secret`. */
+export async function signBody(secret, body) {
+  const { createHmac } = await import('node:crypto');
+  return `sha256=${createHmac('sha256', String(secret)).update(body).digest('hex')}`;
+}
+
+/** Fail-closed: no secret, no header, or a mismatch is unverified. */
+export async function verifySignature(secret, body, header) {
+  if (!secret || !header) return false;
+  const { timingSafeEqual } = await import('node:crypto');
+  const expected = Buffer.from(await signBody(secret, body));
+  const given = Buffer.from(String(header));
+  return expected.length === given.length && timingSafeEqual(expected, given);
+}
+
+/** The subscription's secret, resolved out of the vault (never out of `state`). */
+export function subscriptionSecret(sub, vault) {
+  const ref = sub?.secret;
+  if (!ref) return null;
+  const name = ref.dotenv ?? ref.env;
+  return vault?.get(name) ?? null;
+}
+
+// ---------------------------------------------------------------- the listener
+
+const MAX_BODY = 1024 * 1024;
+
+/**
+ * `POST /webhooks/<name>`. Reads the raw body (a signature is over bytes, not
+ * over a re-serialized object), verifies it, and hands the loop a `webhook`
+ * event either way — the reducer decides what a bad signature means. Binds on
+ * 127.0.0.1; `port` 0 lets the OS choose (tests read `.port`).
+ */
+export async function startWebhookListener({ state, vault, port = 0, host = '127.0.0.1', dispatch, clock, log = () => {} }) {
+  const { createServer } = await import('node:http');
+  const server = createServer((req, res) => {
+    const match = /^\/webhooks\/([^/?#]+)/.exec(req.url ?? '');
+    if (req.method !== 'POST' || !match) { res.writeHead(404, { 'content-type': 'application/json' }); res.end('{"error":"not found"}'); return; }
+    let name;
+    try { name = decodeURIComponent(match[1]); } catch {
+      res.writeHead(400, { 'content-type': 'application/json' }); res.end('{"error":"bad subscription name"}'); return;
+    }
+    const chunks = [];
+    let size = 0;
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > MAX_BODY) { res.writeHead(413); res.end(); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf8');
+      void handleRequest({ state, vault, name, body, headers: req.headers, dispatch, clock, log, res });
+    });
+    req.on('error', (error) => log('warn', `webhook ${name}: ${error.message}`));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => { server.removeListener('error', reject); resolve(); });
+  });
+  server.unref?.();
+  return {
+    server,
+    port: server.address().port,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}
+
+async function handleRequest({ state, vault, name, body, headers, dispatch, clock, log, res }) {
+  const found = findSubscription(state, name);
+  if (!found) {
+    log('warn', `webhook ${name}: no subscription`);
+    res.writeHead(404, { 'content-type': 'application/json' });
+    res.end('{"error":"unknown subscription"}');
+    return;
+  }
+  const header = headers['x-signature-256'] ?? headers['x-hub-signature-256'] ?? null;
+  const verified = await verifySignature(subscriptionSecret(found.sub, vault), body, header);
+  let payload;
+  try { payload = JSON.parse(body); } catch { payload = { body }; }
+  const at = clock();
+  res.writeHead(verified ? 202 : 401, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ ok: verified, name }));
+  const event = firstHeader(headers, EVENT_HEADERS) ?? eventType(payload);
+  const delivery_id = firstHeader(headers, DELIVERY_HEADERS);
+  await dispatch(events.webhook({ name, payload, verified, at, event, delivery_id }));
+}

package/worker-route.mjs

@@ -0,0 +1,122 @@
+// The worker's model and route from the home's own `model:` block (docs/plans/hermes-compat.md row 6).
+// A Hermes home names its model as Hermes reads it: `model.default`, `model.provider`, and for a custom
+// endpoint `model.base_url`, `model.api_key` and `model.api_mode`, secrets as `${NAME}`. The worker gets
+// the same model on the same endpoint, through its own configuration:
+//
+//   codex   `-c model=…` and `-c model_provider=…` at launch, and `[model_providers.<id>]` in the Codex
+//           home's `config.toml` with the endpoint resolved, `env_key` naming the key's variable (carried
+//           in the worker's launch environment) and `wire_api = "responses"`. Codex has no
+//           chat-completions wire, so `api_mode: chat_completions` is served on the endpoint's Responses
+//           API; an endpoint without one fails the worker's first call by name. Measured: Open Autonomy's
+//           model rail answers `/v1/responses` in its gateway's own stream (`response.stream`, no
+//           `response.completed`), which Codex cannot read; a Codex worker there needs an endpoint that
+//           speaks OpenAI's Responses stream.
+//
+//           `provider: openai-codex` (Hermes's word for the owner's ChatGPT subscription) is the same table
+//           pointed at the valve's Codex forward, `HERMES_CODEX_BASE_URL` in the home's `.env` (the address
+//           Hermes's own pool uses), with the stand-in key `valve`: the forward holds no login and fetches the
+//           host Codex's current one per call, so the worker never holds it (Open Autonomy ADR 0001). Measured:
+//           a Codex with a login-free home answers through it, tool calls and MCP tools included.
+//
+//   claude-code  its own environment: `ANTHROPIC_BASE_URL` (the endpoint without its `/v1`, since Claude
+//           Code appends `/v1/messages`), the key as `ANTHROPIC_AUTH_TOKEN`, and the model as every alias
+//           Claude Code resolves (`ANTHROPIC_MODEL`, `ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL`), so no
+//           background call reaches for a model nobody chose; `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`
+//           keeps it off Anthropic's own services, which hold no credential here. The endpoint serves the
+//           Anthropic Messages wire (Open Autonomy's rail does, streamed, tools included: measured).
+//
+// A route this table does not have is refused by name at launch, never run on the worker's default:
+// that would spend on a model nobody chose.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MODEL_ARGUMENTS } from './activation.mjs';
+
+/** The Codex provider id a Hermes provider is served under. */
+const PROVIDER_ID = { custom: 'hermes_custom', openai: 'openai', 'openai-codex': 'hermes_codex' };
+
+/** The variable a literal key is carried under, when the home names none. */
+export const LITERAL_KEY_ENV = 'SUPERCODE_MODEL_API_KEY';
+
+const REF = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+
+function resolve(value, vault) {
+  const ref = typeof value === 'string' ? REF.exec(value.trim()) : null;
+  if (!ref) return { value, name: null };
+  const got = vault?.get?.(ref[1]) ?? process.env[ref[1]];
+  if (got === undefined) throw new Error(`model: \${${ref[1]}} is in neither the home's .env nor the environment`);
+  return { value: got, name: ref[1] };
+}
+
+/** The Hermes `model:` block as a route: `{ model, provider, base_url?, api_key?, api_mode? }`, or null. */
+export function hermesModel(profile) {
+  const block = profile?.residue?.config?.model;
+  if (!block) return null;
+  if (typeof block === 'string') return { model: block };
+  return { model: block.default ?? block.model ?? null, provider: block.provider ?? null, base_url: block.base_url ?? null, api_key: block.api_key ?? null, api_mode: block.api_mode ?? null };
+}
+
+/**
+ * The worker's route for one launch: `{ model, args, env }` (launch arguments and launch environment),
+ * writing the provider table into the worker's config home. The launch's `worker.model` (a job's own
+ * model, or the `worker:` block's) wins over `model.default`.
+ */
+export function workerRoute(profile, worker, vault) {
+  const route = hermesModel(profile);
+  // `model.default` reaches only a worker that takes a model at launch; one that reads the home's own
+  // `model:` itself (Hermes over ACP) keeps it there
+  const model = worker?.model ?? (MODEL_ARGUMENTS[worker?.harness] ? route?.model ?? null : null);
+  if (route?.provider && worker?.harness === 'claude-code') return claudeRoute(profile, route, model, vault);
+  if (!route?.provider || worker?.harness !== 'codex') return { model, args: [], env: {} };
+  const id = PROVIDER_ID[route.provider];
+  if (!id) throw new Error(`model.provider ${route.provider} has no Codex route in this orchestrator yet; refused rather than run on Codex's default`);
+  const env = {};
+  const table = { name: `hermes ${route.provider}`, wire_api: 'responses' };
+  if (route.provider === 'openai-codex') {
+    const forward = vault?.get?.('HERMES_CODEX_BASE_URL') ?? process.env.HERMES_CODEX_BASE_URL;
+    if (!forward) throw new Error('model.provider openai-codex needs the Codex forward (HERMES_CODEX_BASE_URL in the home\'s .env, which the kit\'s start writes); refused rather than run on a login the worker would have to hold');
+    table.base_url = forward;
+    table.env_key = LITERAL_KEY_ENV;
+    env[LITERAL_KEY_ENV] = 'valve';
+    writeProviderTable(join(profile.dir, 'codex'), id, table);
+    return { model, args: ['-c', `model_provider=${JSON.stringify(id)}`], env };
+  }
+  if (route.base_url) table.base_url = resolve(route.base_url, vault).value;
+  if (route.api_key) {
+    const key = resolve(route.api_key, vault);
+    const name = key.name ?? LITERAL_KEY_ENV;
+    env[name] = key.value;
+    table.env_key = name;
+  }
+  if (id !== 'openai' || route.base_url) writeProviderTable(join(profile.dir, 'codex'), id, table);
+  return { model, args: ['-c', `model_provider=${JSON.stringify(id)}`], env };
+}
+
+/** Claude Code's route: its own environment and the endpoint's Messages wire. */
+function claudeRoute(profile, route, model, vault) {
+  if (!['custom', 'anthropic'].includes(route.provider)) throw new Error(`model.provider ${route.provider} has no Claude Code route in this orchestrator yet; refused rather than run on Claude Code's default`);
+  if (!route.base_url) throw new Error('Claude Code runs on a model with an endpoint (model.base_url); refused rather than run on Claude Code\'s default');
+  const env = { CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
+  if (route.base_url) env.ANTHROPIC_BASE_URL = String(resolve(route.base_url, vault).value).replace(/\/v1\/?$/, '').replace(/\/$/, '');
+  if (route.api_key) env.ANTHROPIC_AUTH_TOKEN = resolve(route.api_key, vault).value;
+  if (model) for (const name of ['ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL']) env[name] = model;
+  return { model, args: [], env };
+}
+
+/** `[model_providers.<id>]` in the Codex home's `config.toml`, replaced whole, the rest of the file kept. */
+function writeProviderTable(home, id, table) {
+  mkdirSync(home, { recursive: true });
+  const file = join(home, 'config.toml');
+  const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  const header = `[model_providers.${id}]`;
+  const block = [header, ...Object.entries(table).map(([k, v]) => `${k} = ${JSON.stringify(String(v))}`)].join('\n');
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => line.trim() === header);
+  let next;
+  if (start < 0) next = `${text}${text && !text.endsWith('\n') ? '\n' : ''}${text ? '\n' : ''}${block}\n`;
+  else {
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end])) end += 1;
+    next = [...lines.slice(0, start), ...block.split('\n'), ...lines.slice(end)].join('\n');
+  }
+  if (next !== text) writeFileSync(file, next, { mode: 0o600 });
+}