@volter/supercode-orchestrator 0.4.4

package/adapters/rh2.mjs

@@ -0,0 +1,349 @@
+// The RH2 adapter: a Runhuman Room conversation as an ordinary channel, the
+// same three-method trait as every adapter — connect(emit) / send(target,
+// content) / close(). The orchestrator holds an RH2 session (the bot
+// principal's automation token), is a member of the Rooms it follows and a
+// participant of their conversations, and reads and answers there the way it
+// does in a Slack channel. RH2's own rule keeps a coding seat and this loop
+// from answering each other: a seat is never woken by an agent's message, and
+// this adapter turns only a person's line (kind `human`, or a trigger's
+// `automation`) into an `inbound`.
+//
+// Doors (RH2 `/api/v3`, bearer + `x-rh2-organization`):
+//   GET  /rooms                                            the Rooms to follow
+//   GET  /rooms/:room/view                                 members (names), conversations (permissions, nextSequence)
+//   GET  /rooms/:room/conversations/:c/messages?after=&limit=
+//   POST /rooms/:room/conversations/:c/messages            {body, correlationId, kind: "agent", parentMessageId?}
+//   PATCH /rooms/:room/conversations/:c/messages/:id        {body} — a streamed reply grows, a progress line updates, by edit
+//   POST /rooms/:room/conversations/:c/presence            {state: "typing"} — best effort, forgotten on 404
+//
+// The block:
+//   platforms:
+//     rh2:
+//       enabled: true
+//       token: ${RH2_SESSION_TOKEN}                      # the bot principal's session (loads as credentials.token;
+//                                                        # a nested `credentials:` block is not read as one)
+//       extra:
+//         api_url: https://pilot.runhuman.com            # or the boundary's RH2 route
+//         organization: peakhealth
+//         headers: '{"x-twins-key":"…"}'                 # optional extra request headers (JSON)
+//         rooms: room_a,room_b                           # optional; default every active Room the bot is in
+//         principal_id: prn_…                            # the bot's own principal (is_me / mentions)
+//         poll_seconds: 2
+//
+// The surface key is `{platform: 'rh2', kind: 'channel', chat_id: '<roomId>'}`: a Room is one surface, so the agent it
+// seats is one session however many of the Room's conversations it takes part in. A line wakes it where RH2 says the bot
+// answers every line (its participation, `answers: all`) or where the line mentions it; the line arrives labelled with its
+// conversation, and a reply goes back to the conversation of the Room's last line (`<roomId>/<conversationId>` names one)
+// unless the agent begins it with a conversation's label, `[Work]`, which sends it there.
+import { chunks } from './chunks.mjs';
+
+const DEFAULT_POLL_MS = 2000;
+const ROOM_REFRESH_MS = 30_000;
+const MAX_BODY = 4000;
+const MESSAGE_PAGE = 100;
+const CLOCK_SKEW_MS = 60_000;
+const ECHO_MEMORY = 500;
+
+export class Rh2Adapter {
+  constructor({ platform = 'rh2', profile = 'default', channel = null, vault = new Map(), log = () => {}, fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+    this.platform = platform;
+    this.profile = profile;
+    this.channel = channel;
+    this.vault = vault;
+    this.log = log;
+    this.fetch = fetchImpl;
+    this.sleep = sleep;
+    this.emit = null;
+    this.running = false;
+    /** conversation id -> { roomId, after } */
+    this.cursors = new Map();
+    /** room id -> { name, names: Map<principalId, displayName>, conversations: Map<id, name> } */
+    this.rooms = new Map();
+    /** roomId -> the conversation of the last line that woke the Room's session: where a reply goes. */
+    this.replyTo = new Map();
+    this.roomsRefreshedAt = 0;
+    this.ownMessageIds = [];
+    this.postedIn = new Map(); // message id -> the conversation it was posted in, for its edits
+    this.presenceDoor = null; // unknown until the first try
+    this.loop = null;
+    /** chat_id -> typing heartbeat timer: from a person's line until this adapter's reply (or three minutes). */
+    this.typingTimers = new Map();
+  }
+
+  /** The block's `extra:` map, whose keys the loader prefixes with `extra.`. */
+  extra(name, fallback = undefined) {
+    const e = this.channel?.extra ?? {};
+    return e[`extra.${name}`] ?? e[name] ?? fallback;
+  }
+
+  /** The bearer: `credentials.token` resolved from the vault (a ref, never a value in the model). */
+  token() {
+    const ref = this.channel?.credentials?.token ?? this.channel?.credentials?.['extra.token'];
+    if (ref) {
+      const name = ref.dotenv ?? ref.env;
+      const value = this.vault.get(name) ?? (ref.env ? process.env[ref.env] : undefined);
+      if (value === undefined) throw new Error(`platforms.${this.platform}.token: ref ${name} is not in the vault`);
+      return value;
+    }
+    const direct = this.extra('token') ?? process.env.RH2_SESSION_TOKEN;
+    if (!direct) throw new Error(`platforms.${this.platform}: no token (credentials.token or RH2_SESSION_TOKEN)`);
+    return direct;
+  }
+
+  apiUrl() { return String(this.extra('api_url') ?? process.env.RH2_API_URL ?? '').replace(/\/+$/, ''); }
+  organization() { return String(this.extra('organization') ?? process.env.RH2_ORGANIZATION ?? ''); }
+  principalId() { return String(this.extra('principal_id') ?? process.env.RH2_PRINCIPAL_ID ?? ''); }
+  pollMs() { const n = Number(this.extra('poll_seconds', process.env.RH2_POLL_SECONDS)); return Number.isFinite(n) && n > 0 ? Math.max(500, n * 1000) : DEFAULT_POLL_MS; }
+  followedRooms() {
+    const raw = this.extra('rooms') ?? process.env.RH2_ROOMS ?? '';
+    return (Array.isArray(raw) ? raw : String(raw).split(',')).map((s) => String(s).trim()).filter(Boolean);
+  }
+  headers() {
+    let extra = {};
+    const raw = this.extra('headers') ?? process.env.RH2_API_HEADERS;
+    if (raw) {
+      try { extra = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch { this.log('warn', `${this.platform}: headers is not a JSON object; ignored`); }
+    }
+    return { authorization: `Bearer ${this.token()}`, 'x-rh2-organization': this.organization(), 'content-type': 'application/json', ...extra };
+  }
+
+  async get(path, params = {}) {
+    const url = new URL(`${this.apiUrl()}/api/v3${path}`);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+    const res = await this.fetch(url, { headers: this.headers() });
+    if (!res.ok) {
+      const error = new Error(`GET ${path} -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+      error.status = res.status;
+      throw error;
+    }
+    return (await res.json()).data ?? {};
+  }
+
+  async post(path, body) {
+    const res = await this.fetch(`${this.apiUrl()}/api/v3${path}`, { method: 'POST', headers: this.headers(), body: JSON.stringify(body) });
+    return res;
+  }
+
+  // ---------------------------------------------------------------- lifecycle
+
+  async connect(emit) {
+    this.emit = emit;
+    if (!this.apiUrl() || !this.organization()) throw new Error(`platforms.${this.platform}: api_url and organization are required`);
+    this.token();
+    await this.refreshRooms();
+    this.running = true;
+    this.loop = this.pollLoop();
+    this.log('info', `${this.platform}: following ${this.cursors.size} conversation(s) in ${this.organization()}`);
+    return { state: 'up' };
+  }
+
+  async close() {
+    this.running = false;
+    this.emit = null;
+    for (const chatId of [...this.typingTimers.keys()]) this.stopTyping(chatId);
+    if (this.loop) { try { await this.loop; } catch { /* stopping */ } this.loop = null; }
+  }
+
+  // ---------------------------------------------------------------- reads
+
+  async refreshRooms() {
+    const previous = this.roomsRefreshedAt || undefined;
+    this.roomsRefreshedAt = Date.now();
+    let roomIds = this.followedRooms();
+    if (roomIds.length === 0) {
+      const listing = await this.get('/rooms');
+      const rooms = Array.isArray(listing) ? listing : listing.rooms ?? [];
+      roomIds = rooms.map((entry) => entry.room ?? entry).filter((room) => room?.state === 'active' && room.roomId).map((room) => String(room.roomId));
+    }
+    const live = new Set();
+    for (const roomId of roomIds) {
+      let view;
+      try { view = await this.get(`/rooms/${roomId}/view`); } catch (error) {
+        // A refused credential is the bot's, not the Room's: following nothing while reporting up would hide it.
+        if (error.status === 401) throw error;
+        this.log('debug', `${this.platform}: Room ${roomId} not readable: ${error.message}`);
+        continue;
+      }
+      const room = view.room ?? {};
+      if (room.state && room.state !== 'active') continue;
+      const names = new Map((view.members ?? []).filter((m) => m.principalId).map((m) => [String(m.principalId), String(m.displayName ?? m.principalId)]));
+      const conversations = new Map();
+      for (const conversation of view.conversations ?? []) {
+        if (!conversation.conversationId || !(conversation.permissions ?? []).includes('conversation.read')) continue;
+        const participation = (conversation.agentParticipants ?? []).find((p) => String(p.principalId) === this.principalId());
+        conversations.set(conversation.conversationId, { name: String(conversation.name ?? conversation.conversationId), answers: participation?.answers ?? null });
+        live.add(conversation.conversationId);
+        if (!this.cursors.has(conversation.conversationId)) {
+          // At start, a conversation is read from its current end: no backlog is answered. One that becomes
+          // readable later is one the bot was just brought into, and whoever brought it in may already have
+          // spoken (a brief posted right after the join): it is read from the start, and a line counts from
+          // the previous refresh on, less a margin for this clock against RH2's.
+          this.cursors.set(conversation.conversationId, previous === undefined
+            ? { roomId, after: Math.max(0, Number(conversation.nextSequence ?? 1) - 1) }
+            : { roomId, after: 0, since: previous - CLOCK_SKEW_MS });
+        }
+      }
+      this.rooms.set(roomId, { name: String(room.name ?? roomId), names, conversations });
+    }
+    for (const id of [...this.cursors.keys()]) if (!live.has(id)) this.cursors.delete(id);
+  }
+
+  async pollLoop() {
+    let failures = 0;
+    while (this.running) {
+      try {
+        if (Date.now() - this.roomsRefreshedAt >= ROOM_REFRESH_MS) await this.refreshRooms();
+        for (const [conversationId, cursor] of [...this.cursors.entries()]) {
+          const data = await this.get(`/rooms/${cursor.roomId}/conversations/${conversationId}/messages`, { after: cursor.after, limit: MESSAGE_PAGE });
+          const messages = data.messages ?? [];
+          let after = cursor.after;
+          for (const message of messages) {
+            const sequence = Number(message.sequence ?? 0);
+            if (sequence > after) after = sequence;
+            if (cursor.since !== undefined && !(Date.parse(message.createdAt ?? '') >= cursor.since)) continue;
+            this.onMessage(cursor.roomId, conversationId, message);
+          }
+          // The catch-up bound holds until the history is read through.
+          const since = cursor.since !== undefined && messages.length === MESSAGE_PAGE ? cursor.since : undefined;
+          this.cursors.set(conversationId, { roomId: cursor.roomId, after, ...(since === undefined ? {} : { since }) });
+        }
+        failures = 0;
+        await this.sleep(this.pollMs());
+      } catch (error) {
+        if (!this.running) return;
+        failures += 1;
+        const delay = Math.min(60_000, 2000 * 2 ** Math.min(failures, 5));
+        this.log('warn', `${this.platform}: poll error ${error.message}; retrying in ${delay / 1000}s`);
+        await this.sleep(delay);
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------- inbound
+
+  onMessage(roomId, conversationId, message) {
+    if (!this.emit) return;
+    const messageId = message.messageId === undefined ? null : String(message.messageId);
+    const author = String(message.authorPrincipalId ?? '');
+    const me = this.principalId();
+    const isMe = (messageId !== null && this.ownMessageIds.includes(messageId)) || (me !== '' && author === me);
+    const kind = String(message.kind ?? '');
+    // A person's line (or a trigger's) is a turn; an agent's or the Room's own notice is not.
+    if (!isMe && kind !== 'human' && kind !== 'automation') return;
+    const text = String(message.body ?? '');
+    if (!isMe && text.trim() === '') return;
+    const room = this.rooms.get(roomId);
+    const conversation = room?.conversations.get(conversationId);
+    const mentions = Array.isArray(message.mentions) ? message.mentions.map(String) : [];
+    const mentioned = me !== '' && mentions.includes(me);
+    // RH2 decides who hears a line: the bot answers where it takes every line, and elsewhere only when named.
+    if (!isMe && conversation?.answers !== 'all' && !mentioned) return;
+    if (!isMe) this.replyTo.set(roomId, conversationId);
+    // A person's line opens a turn: show typing here until the reply lands (the loop has no
+    // typing effect by design — the adapter, which knows both ends of the turn, carries it).
+    if (!isMe) this.startTyping(`${roomId}/${conversationId}`);
+    const labelled = room && room.conversations.size > 1 && conversation ? `[${conversation.name}] ${text}` : text;
+    this.emit({
+      profile: this.profile,
+      key: { platform: this.platform, kind: 'channel', chat_id: roomId },
+      sender: author || 'unknown',
+      sender_name: room?.names.get(author) ?? null,
+      text: labelled,
+      at: typeof message.createdAt === 'string' ? message.createdAt : new Date().toISOString(),
+      message_id: messageId,
+      is_me: isMe,
+      is_bot: kind === 'agent' || kind === 'automation',
+      mention: mentioned,
+    });
+  }
+
+  // ---------------------------------------------------------------- outbound
+
+  split(chatId) {
+    const [roomId, conversationId] = String(chatId).split('/');
+    if (conversationId) return { roomId, conversationId };
+    const last = this.replyTo.get(roomId);
+    if (last) return { roomId, conversationId: last };
+    for (const [id, cursor] of this.cursors) if (cursor.roomId === roomId) return { roomId, conversationId: id };
+    return { roomId, conversationId: undefined };
+  }
+
+  startTyping(chatId) {
+    this.stopTyping(chatId);
+    const target = { platform: this.platform, kind: 'channel', chat_id: chatId };
+    const startedAt = Date.now();
+    const tick = () => { if (Date.now() - startedAt > 180_000) { this.stopTyping(chatId); return; } void this.typing(target); };
+    tick();
+    this.typingTimers.set(chatId, setInterval(tick, 5000));
+  }
+
+  stopTyping(chatId) {
+    const timer = this.typingTimers.get(chatId);
+    if (timer) { clearInterval(timer); this.typingTimers.delete(chatId); }
+  }
+
+  /**
+   * Where a message goes: the conversation the agent names by beginning it with `[<name>]`, as each line reaches it
+   * labelled, or else the one it last answered. A turn a tester's line opened is still the agent's to narrate in Work.
+   */
+  addressed(roomId, conversationId, text) {
+    const named = /^\[([^\]\n]{1,64})\]\s*/.exec(text);
+    const room = this.rooms.get(roomId);
+    if (!named || !room) return { conversationId, text };
+    for (const [id, conversation] of room.conversations) {
+      if (conversation.name.toLowerCase() === named[1].trim().toLowerCase()) return { conversationId: id, text: text.slice(named[0].length) };
+    }
+    return { conversationId, text };
+  }
+
+  async send(target, content) {
+    this.stopTyping(String(target.chat_id));
+    const split = this.split(target.chat_id);
+    if (!split.conversationId) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
+    const { roomId } = split;
+    const { conversationId, text } = this.addressed(roomId, split.conversationId, String(content.text ?? ''));
+    // A reply longer than one line holds goes out as consecutive lines, split where a paragraph (or a line) ends.
+    let messageId;
+    for (const [index, part] of chunks(text, MAX_BODY).entries()) {
+      const body = { body: part, correlationId: `orchestrator:${crypto.randomUUID()}`, kind: 'agent' };
+      if (content.reply_to && index === 0) body.parentMessageId = String(content.reply_to);
+      const res = await this.post(`/rooms/${roomId}/conversations/${conversationId}/messages`, body);
+      if (!res.ok) throw new Error(`${this.platform}: post -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+      const posted = (await res.json()).data ?? {};
+      messageId = String(posted.messageId ?? crypto.randomUUID());
+      this.ownMessageIds.push(messageId);
+      this.postedIn.set(messageId, conversationId);
+      if (this.postedIn.size > ECHO_MEMORY) this.postedIn.delete(this.postedIn.keys().next().value);
+      if (this.ownMessageIds.length > ECHO_MEMORY) this.ownMessageIds.splice(0, this.ownMessageIds.length - ECHO_MEMORY);
+      const cursor = this.cursors.get(conversationId);
+      const sequence = Number(posted.sequence ?? 0);
+      if (cursor && sequence > cursor.after) this.cursors.set(conversationId, { roomId: cursor.roomId, after: sequence });
+    }
+    return { ok: true, message_id: messageId };
+  }
+
+  /** Replace one of this adapter's own messages in place (RH2 `PATCH …/messages/:id`): a streamed reply grows, a progress line is updated. */
+  async edit(target, messageId, content) {
+    const split = this.split(target.chat_id);
+    // An edit goes to the conversation the message was posted in, whichever the agent named then.
+    const posted = this.postedIn.get(String(messageId)) ?? split.conversationId;
+    if (!posted) throw new Error(`${this.platform}: no conversation for ${target.chat_id}`);
+    const { roomId } = split;
+    const { conversationId, text } = { conversationId: posted, text: this.addressed(roomId, posted, String(content.text ?? '')).text };
+    const res = await this.fetch(`${this.apiUrl()}/api/v3/rooms/${roomId}/conversations/${conversationId}/messages/${encodeURIComponent(messageId)}`, { method: 'PATCH', headers: this.headers(), body: JSON.stringify({ body: text.slice(0, MAX_BODY) }) });
+    if (!res.ok) throw new Error(`${this.platform}: edit -> HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+    return { ok: true, message_id: messageId };
+  }
+
+  /** Presence `typing` on the conversation; the door is tried once and forgotten on 404. */
+  async typing(target) {
+    if (this.presenceDoor === false) return;
+    const { roomId, conversationId } = this.split(target.chat_id);
+    if (!conversationId) return;
+    try {
+      const res = await this.post(`/rooms/${roomId}/conversations/${conversationId}/presence`, { state: 'typing' });
+      if (res.status === 404) { this.presenceDoor = false; this.log('info', `${this.platform}: RH2 has no conversation presence door; typing disabled`); }
+      else if (res.ok) this.presenceDoor = true;
+    } catch (error) { this.log('debug', `${this.platform}: typing: ${error.message}`); }
+  }
+}

package/apply/doors.d.ts

@@ -0,0 +1,2 @@
+// The applier's doors: the root's declarations (index.d.ts) for the functions this module exports.
+export { hermesDoor, orchestratorDoor, locateHermes, localRunner, containerRunner } from '@volter/supercode-orchestrator';

package/apply/doors.mjs

@@ -0,0 +1,292 @@
+// The applier's doors (docs/plans/content-spec-status.md §7 "The door"): every change goes through
+// the harness's own functions, never its files. One shape per gateway:
+//
+//   list()                     -> [{ id, name, managed, lifecycle, created_at }]   managed: the fields apply
+//                                 owns, in the harness's own names, read raw from its store
+//   fields(spec, inference)    -> the declaration in those names (throws when the record cannot be expressed)
+//   differs(want, live)        -> the names whose declared value differs from the live one, compared by
+//                                 meaning (a schedule by kind and period, never by its display text)
+//   create(key, want) / update(id, patch) / pause(id) / remove(id) / capture(id)
+//   readInference(keys) / writeInference(values)   (Hermes only)
+//
+// Hermes: `hermes_door.py` under Hermes's own interpreter (its cron module, notepad, config save), locally
+// or inside a container. The orchestrator: its operator verbs, through the running daemon's socket when it
+// is up and the package's cold path when it is not; its folder is read through the package's own `load`.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MARK = '@@supercode-apply@@';
+/** A door call's ceiling: Hermes's own functions answer in well under this. */
+const DOOR_TIMEOUT_MS = 60_000;
+
+/** Hermes's schedule string for a declared schedule. */
+export function hermesSchedule(schedule) {
+  switch (schedule?.kind) {
+    case 'interval': return `every ${schedule.minutes}m`;
+    case 'cron': return String(schedule.expr);
+    case 'once': return String(schedule.run_at);
+    default: throw new Error(`schedule.kind ${JSON.stringify(schedule?.kind)} is not interval | cron | once`);
+  }
+}
+
+/** Two schedules are the same when they fire the same way, whatever text made them. */
+export function sameSchedule(want, live) {
+  if (!want || !live || typeof live !== 'object') return false;
+  if (want.kind !== live.kind) return false;
+  if (want.kind === 'interval') return Number(want.minutes) === Number(live.minutes);
+  if (want.kind === 'cron') return String(want.expr).trim() === String(live.expr ?? '').trim();
+  if (want.kind === 'once') return Date.parse(want.run_at) === Date.parse(live.run_at ?? '');
+  return false;
+}
+
+/** The declared model name resolved through Inference to (provider, model), or refused. */
+export function namedModel(spec, inference) {
+  if (!spec.model) return { model: null, provider: null };
+  const m = inference?.models?.[spec.model];
+  if (!m) throw new Error(`model ${JSON.stringify(spec.model)} is not a named model in inference.models`);
+  return { model: m.model, provider: m.provider ?? null };
+}
+
+// empty and absent are one value in both stores (Hermes keeps '' and null interchangeably for text)
+const norm = (v) => (v === '' || v === undefined ? null : Array.isArray(v) && v.length === 0 ? null : v);
+const sameValue = (a, b) => JSON.stringify(norm(a)) === JSON.stringify(norm(b));
+
+export function differs(want, live) {
+  const out = [];
+  for (const [field, value] of Object.entries(want)) {
+    const same = field === 'schedule' ? sameSchedule(value, live.schedule) : sameValue(value, live[field]);
+    if (!same) out.push(field);
+  }
+  return out;
+}
+
+/**
+ * The declaration in a door's field names: only what the job declares is
+ * managed (an undeclared delivery, workdir or model stays the harness's
+ * default and is never overwritten); the schedule always is.
+ */
+function declaredOnly(spec, inference, rename) {
+  const want = { schedule: spec.schedule };
+  for (const field of ['prompt', 'skills', 'deliver', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'toolsets', 'context_from']) {
+    if (spec[field] !== undefined) want[rename[field] ?? field] = spec[field];
+  }
+  if (spec.model !== undefined) Object.assign(want, namedModel(spec, inference));
+  return want;
+}
+
+/**
+ * Where a Hermes install's interpreter and source are: given, else read off the
+ * `hermes` on PATH — the one the gateway runs. Two launcher shapes exist: the
+ * installer's shell script (`exec "<python>" "<source>/hermes"`) and pip's
+ * console script (a `#!<python>` shebang), whose interpreter is asked where the
+ * `cron` package it imports lives.
+ */
+export function locateHermes({ python = null, source = null, env = process.env } = {}) {
+  if (python && source) return { python, source };
+  // every `hermes` on PATH, in order: an image may put a shell shim first (Hermes's own image drops privileges for
+  // `docker exec` callers in /opt/hermes/bin/hermes) ahead of the Python launcher it hands to
+  const launchers = [];
+  for (const dir of (env.PATH ?? '').split(':')) {
+    const candidate = dir ? join(dir, 'hermes') : null;
+    if (candidate && existsSync(candidate) && !launchers.includes(candidate)) launchers.push(candidate);
+  }
+  if (!launchers.length) throw new Error('no hermes on PATH; pass the install (python and source) explicitly');
+  const reasons = [];
+  for (const launcher of launchers) {
+    let text;
+    try { text = readFileSync(launcher, 'utf8'); } catch (error) { reasons.push(`${launcher}: ${error.message}`); continue; }
+    const exec = /exec\s+"([^"]+python[^"]*)"\s+"([^"]+)"/.exec(text);
+    if (exec) return { python: exec[1], source: dirname(exec[2]) };
+    const shebang = /^#!\s*(\S*python[^\s]*)/.exec(text);
+    if (shebang) {
+      const where = spawnSync(shebang[1], ['-c', 'import os, cron.jobs; print(os.path.dirname(os.path.dirname(os.path.abspath(cron.jobs.__file__))))'], { encoding: 'utf8', timeout: DOOR_TIMEOUT_MS });
+      const found = where.stdout?.trim();
+      if (where.status === 0 && found) return { python: shebang[1], source: found };
+      reasons.push(`${launcher}: its interpreter ${shebang[1]} cannot import Hermes's cron package: ${(where.stderr || where.error?.message || '').trim().slice(-300)}`);
+      continue;
+    }
+    reasons.push(`${launcher} is not a Hermes launcher this applier can read`);
+  }
+  throw new Error(`${reasons.join('; ')}; pass the install explicitly`);
+}
+
+/**
+ * Where the door's Python runs. Locally: Hermes's interpreter with its source
+ * on the path. In a container (Open Autonomy's executor): `docker exec` into
+ * it, the door script passed with `-c`, the request on stdin, HERMES_HOME the
+ * container's path. Either way the applier and its state stay on the host.
+ */
+export function localRunner({ python, source, prefix = [] }) {
+  // `prefix` runs the door as another user (a privilege drop such as setpriv), so what Hermes writes stays the agent's
+  const argv = [...prefix, python, join(HERE, 'hermes_door.py')];
+  return (home, input) => spawnSync(argv[0], argv.slice(1), {
+    input, encoding: 'utf8', timeout: DOOR_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024, cwd: source,
+    env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '', HERMES_HOME: resolve(home), PYTHONPATH: source },
+  });
+}
+
+export function containerRunner({ container, user = 'hermes', python = '/opt/hermes/.venv/bin/python', source = '/opt/hermes', docker = 'docker' }) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(String(container ?? ''))) throw new Error('a container name or id is required');
+  const script = readFileSync(join(HERE, 'hermes_door.py'), 'utf8');
+  return (home, input) => spawnSync(docker, ['exec', '-i', '--user', user, '-e', `HERMES_HOME=${home}`, '-e', `PYTHONPATH=${source}`, '-w', source, container, python, '-c', script], {
+    input, encoding: 'utf8', timeout: DOOR_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
+  });
+}
+
+export function hermesDoor({ home, python = null, source = null, runner = null, prefix = [] }) {
+  const run = runner ?? localRunner({ python, source, prefix });
+  const call = (op, args = {}) => {
+    const out = run(home, JSON.stringify({ op, args }));
+    const line = (out.stdout ?? '').split('\n').find((l) => l.startsWith(MARK));
+    if (!line) throw new Error(`Hermes answered nothing for ${op}: ${(out.stderr || out.error?.message || '').trim().slice(-400)}`);
+    const answer = JSON.parse(line.slice(MARK.length));
+    if (!answer.ok) throw new Error(answer.error);
+    return answer.result;
+  };
+  const read = (job) => ({
+    id: job.id,
+    name: job.name ?? null,
+    managed: {
+      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: job.deliver ?? null,
+      model: job.model ?? null, provider: job.provider ?? null, workdir: job.workdir ?? null, repeat: job.repeat?.times ?? null,
+      script: job.script ?? null, no_agent: Boolean(job.no_agent), monitor_script: job.monitor_script ?? null,
+      monitor_url: job.monitor_url ?? null, enabled_toolsets: job.enabled_toolsets ?? null, context_from: job.context_from ?? null,
+    },
+    lifecycle: job.state === 'completed' ? 'completed' : job.state === 'error' ? 'error' : job.state === 'paused' || job.enabled === false ? 'paused' : 'scheduled',
+    created_at: job.created_at ?? null,
+  });
+  const list = () => call('list').map(read);
+  // every answer is read back the way list() reads, so a read-back never differs from a later list by form
+  const one = (id) => {
+    const row = list().find((r) => r.id === id);
+    if (!row) throw new Error(`Hermes no longer has job ${id}`);
+    return row;
+  };
+  return {
+    target: 'hermes',
+    list,
+    fields(spec, inference) {
+      // Hermes evaluates cron in one zone per home: a trigger's own zone cannot be honoured (plan §3.2)
+      if (spec.schedule?.kind === 'cron' && spec.schedule.tz) throw new Error('Hermes evaluates cron in the home\'s one zone; a per-trigger tz is refused');
+      hermesSchedule(spec.schedule);
+      return declaredOnly(spec, inference, { toolsets: 'enabled_toolsets' });
+    },
+    differs,
+    create(key, want) {
+      const kwargs = { ...want, name: key, schedule: hermesSchedule(want.schedule), repeat: want.repeat };
+      return one(call('create', { kwargs }).id);
+    },
+    update(id, patch) {
+      const updates = { ...patch };
+      if ('schedule' in updates) updates.schedule = hermesSchedule(updates.schedule);
+      if ('repeat' in updates) updates.repeat = updates.repeat ?? 'forever';
+      if ('prompt' in updates) updates.prompt = updates.prompt ?? '';
+      // null skills make Hermes rebuild the list from the legacy `skill` field (_apply_skill_fields): [] clears it
+      if ('skills' in updates && updates.skills === null) updates.skills = [];
+      call('update', { id, updates });
+      return one(id);
+    },
+    pause(id) { call('pause', { id, reason: 'declared paused' }); return one(id); },
+    remove: (id) => call('remove', { id }),
+    capture: (id) => call('capture', { id }),
+    readInference: (keys) => call('config_read', { keys }),
+    writeInference: (values) => call('config_write', { values }),
+  };
+}
+
+/** One operator line to a running daemon's socket: null when no daemon listens, the answer otherwise. */
+function viaSocket(socket, line) {
+  if (!existsSync(socket)) return Promise.resolve(null);
+  return new Promise((done, fail) => {
+    const client = createConnection(socket);
+    let buffer = '';
+    let connected = false;
+    const timer = setTimeout(() => { client.destroy(); fail(new Error(`the orchestrator daemon did not answer ${line.op} in ${DOOR_TIMEOUT_MS / 1000}s; not retried on the cold path, which could apply it twice`)); }, DOOR_TIMEOUT_MS);
+    client.on('connect', () => { connected = true; client.write(`${JSON.stringify(line)}\n`); });
+    client.on('data', (d) => { buffer += d; });
+    client.on('end', () => {
+      clearTimeout(timer);
+      try { done(JSON.parse(buffer.trim().split('\n').pop())); } catch { fail(new Error(`the orchestrator daemon's answer to ${line.op} is unreadable; not retried`)); }
+    });
+    // a socket file with nobody behind it is a daemon that is down: the cold path is safe then
+    client.on('error', (error) => { clearTimeout(timer); if (connected) fail(error); else done(null); });
+  });
+}
+
+export async function orchestratorDoor({ root, profile = 'default', load, socket = null }) {
+  const bin = join(HERE, '..', 'bin', 'orchestrator.mjs');
+  const op = async (name, args) => {
+    const live = await viaSocket(socket ?? join(root, 'orchestrator.sock'), { op: name, args, profile });
+    const answer = live ?? (() => {
+      const run = spawnSync(process.execPath, [bin, name, '--root', root, '--profile', profile, '--json', JSON.stringify(args)], { encoding: 'utf8', timeout: DOOR_TIMEOUT_MS });
+      return JSON.parse((run.stdout ?? '').trim().split('\n').pop() || '{"ok":false,"error":"the orchestrator answered nothing"}');
+    })();
+    if (!answer.ok) throw new Error(answer.error);
+    return answer.result;
+  };
+  const deliver = (target) => (target?.kind === 'explicit' ? [target.platform, target.chat_id, target.thread_id].filter(Boolean).join(':') : target?.kind ?? null);
+  const read = (job) => ({
+    id: job.id,
+    name: job.residue?.name ?? null,
+    managed: {
+      schedule: job.schedule ?? null, prompt: job.prompt ?? null, skills: job.skills ?? null, deliver: deliver(job.deliver),
+      model: job.model ?? null, workdir: job.workdir ?? null, repeat: job.repeat?.times ?? null,
+      script: job.residue?.script ?? null, no_agent: job.residue?.no_agent === true, monitor_script: job.residue?.monitor_script ?? null,
+      monitor_url: job.residue?.monitor_url ?? null, context_from: job.context_from ?? null,
+    },
+    lifecycle: !job.enabled ? (job.schedule?.kind === 'once' && !job.next_run_at && job.last_run_at ? 'completed' : 'paused') : 'scheduled',
+    created_at: job.created_at ?? null,
+  });
+  const list = async () => {
+    const { state } = await load(root);
+    const p = state.profiles[profile];
+    if (!p) throw new Error(`the orchestrator at ${root} has no profile ${profile}`);
+    return Object.values(p.jobs).map(read);
+  };
+  const one = async (id) => {
+    const row = (await list()).find((r) => r.id === id);
+    if (!row) throw new Error(`the orchestrator no longer has job ${id}`);
+    return row;
+  };
+  /** What jobs.update can change; a change to anything else is refused per record, never dropped. */
+  const UPDATABLE = new Set(['schedule', 'prompt', 'deliver', 'model', 'workdir', 'script', 'no_agent', 'monitor_script', 'monitor_url']);
+  return {
+    target: 'orchestrator',
+    list,
+    fields(spec, inference) {
+      if (spec.toolsets) throw new Error('the orchestrator has no per-job toolsets; a restriction it cannot honour refuses the record');
+      const want = declaredOnly(spec, inference, {});
+      delete want.provider; // the orchestrator's worker takes the model alone
+      return want;
+    },
+    differs,
+    async create(key, want) {
+      const made = await op('jobs.create', { ...want, name: key, enabled: true });
+      return one(made.job.id);
+    },
+    async update(id, patch) {
+      const refused = Object.keys(patch).filter((f) => !UPDATABLE.has(f));
+      if (refused.length) throw new Error(`the orchestrator's jobs.update cannot change ${refused.join(', ')}; the record is refused, not half-applied`);
+      const args = { id, ...patch };
+      for (const k of ['script', 'monitor_script', 'monitor_url']) if (k in args && args[k] === null) args[k] = '';
+      await op('jobs.update', args);
+      return one(id);
+    },
+    async pause(id) { await op('jobs.pause', { id }); return one(id); },
+    remove: (id) => op('jobs.delete', { id }),
+    capture: async (id) => {
+      const { state } = await load(root);
+      return { fires: (state.profiles[profile]?.fires ?? []).filter((f) => f.job_id === id) };
+    },
+    readInference: null,
+    writeInference: null,
+  };
+}
+
+/** The job fields the applier owns: the union both doors read (a door that has no such field reads null). */
+export const MANAGED_JOB_FIELDS = Object.freeze(['schedule', 'prompt', 'skills', 'deliver', 'model', 'provider', 'workdir', 'repeat', 'script', 'no_agent', 'monitor_script', 'monitor_url', 'enabled_toolsets', 'context_from']);