@volter/supercode-orchestrator 0.4.4

package/activation.mjs

@@ -0,0 +1,270 @@
+// Profile activation: the env and cwd a worker process gets (docs/ORCHESTRATOR-IR.md §2.2).
+// The profile folder is a complete home; each harness's config home is a
+// subfolder named by its id, pointed at through the harness's own env var.
+
+import { join, relative, resolve } from 'node:path';
+import { mkdirSync, readFileSync, readdirSync, lstatSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { CLAUDE_BRIDGE, linkTo, skillSources } from './hermes-home.mjs';
+
+/** Which env var each harness reads its config home from (supercode registry evidence). */
+export const HOME_ENV = Object.freeze({
+  'claude-code': 'CLAUDE_CONFIG_DIR',
+  codex: 'CODEX_HOME',
+  opencode: 'OPENCODE_CONFIG_DIR',
+  pi: 'PI_CODING_AGENT_DIR',
+  hermes: 'HERMES_HOME',
+  openclaw: 'OPENCLAW_STATE_DIR',
+});
+
+export const ORCH_ENV = Object.freeze({
+  root: 'SUPERCODE_ORCHESTRATOR_ROOT',
+  profile: 'SUPERCODE_ORCHESTRATOR_PROFILE',
+  surface: 'SUPERCODE_ORCHESTRATOR_SURFACE',
+});
+
+function resolveRef(value, vault) {
+  if (typeof value === 'string') return value;
+  // `${NAME}`, as Hermes expands it: the home's `.env` (the vault), then the process environment
+  const name = value.dotenv ?? value.env;
+  if (vault?.has(name)) return vault.get(name);
+  if (process.env[name] !== undefined) return process.env[name];
+  throw new Error(`secret ${name} is in neither the home's .env nor the environment`);
+}
+
+/**
+ * The launch env for one worker session. Never inherits the parent's whole
+ * environment: only the harness home, the profile's declared env (refs
+ * resolved), and the orchestrator's own three variables.
+ */
+export function activationEnv({ root, profile, surfaceKey, vault }) {
+  const env = {};
+  const worker = profile.worker;
+  const homeVar = HOME_ENV[worker.harness];
+  if (homeVar) env[homeVar] = join(profile.dir, worker.harness);
+  for (const [k, v] of Object.entries(worker.env ?? {})) env[k] = resolveRef(v, vault);
+  env[ORCH_ENV.root] = root;
+  env[ORCH_ENV.profile] = profile.name;
+  if (surfaceKey) env[ORCH_ENV.surface] = surfaceKey;
+  return env;
+}
+
+export function activationCwd(profile, workdir) {
+  return resolve(profile.dir, workdir ?? profile.worker?.cwd ?? '.');
+}
+
+/**
+ * Where each harness reads a persona from any cwd, and in what form: its config home's own instruction
+ * file. A worker often runs in a project checkout outside the home, where the project walk never reaches
+ * the profile's `AGENTS.md` (Codex's walk also stops at the innermost git root, ORC-1 F1), so the
+ * persona is linked into the config home: Codex reads `$CODEX_HOME/AGENTS.md`; Claude Code reads
+ * `$CLAUDE_CONFIG_DIR/CLAUDE.md`, whose `@AGENTS.md` import resolves beside it, so an `AGENTS.md` link
+ * sits there too (docs/plans/hermes-compat.md row 2).
+ */
+export const HOME_PERSONA = Object.freeze({
+  codex: { 'AGENTS.md': 'link' },
+  'claude-code': { 'CLAUDE.md': 'bridge', 'AGENTS.md': 'link' },
+});
+
+/**
+ * Put the profile's persona where the worker's harness reads it from any cwd: links to the profile's
+ * own `AGENTS.md` (the source), never a copy to keep in step. Idempotent.
+ */
+export function materializePersona(profile) {
+  const worker = profile.worker;
+  const files = worker && HOME_PERSONA[worker.harness];
+  if (!files || !profile.persona) return null;
+  const home = join(profile.dir, worker.harness);
+  mkdirSync(home, { recursive: true });
+  for (const [file, form] of Object.entries(files)) {
+    const target = join(home, file);
+    if (form === 'link') linkTo(target, '../AGENTS.md');
+    else if (!existsSync(target) || readFileSync(target, 'utf8') !== CLAUDE_BRIDGE) writeFileSync(target, CLAUDE_BRIDGE);
+  }
+  return home;
+}
+
+/**
+ * Where each harness reads skills from any cwd: its config home's `skills/` (Codex's user root there, the
+ * one Supercode's loader and Codex both read; Claude Code's user root). Each skill a profile has — its
+ * workers' form and the skills Hermes manages — is linked in flat by name (docs/plans/hermes-compat.md
+ * row 3); a link whose skill is gone is removed; nothing else in the folder is touched.
+ */
+export const HOME_SKILLS = Object.freeze({ codex: 'skills', 'claude-code': 'skills' });
+
+export function materializeSkills(profile) {
+  const worker = profile.worker;
+  const sub = worker && HOME_SKILLS[worker.harness];
+  if (!sub) return null;
+  const sources = skillSources(profile.dir);
+  const into = join(profile.dir, worker.harness, sub);
+  mkdirSync(into, { recursive: true });
+  for (const [name, from] of sources) linkTo(join(into, name), relative(into, from));
+  for (const entry of readdirSync(into)) {
+    const path = join(into, entry);
+    if (lstatSync(path).isSymbolicLink() && !sources.has(entry) && !existsSync(path)) rmSync(path, { force: true });
+  }
+  return into;
+}
+
+/**
+ * How each worker CLI takes a model at launch, measured on each CLI's own
+ * `--help` (claude 2.1.280, codex-cli 0.156.1, gemini). A model set for a
+ * harness not listed here is refused where it is set (`/model`, the job
+ * doors) and again at launch: running on the harness's default instead would
+ * spend on a model nobody chose.
+ */
+export const MODEL_ARGUMENTS = Object.freeze({
+  'claude-code': (model) => ['--model', model],
+  codex: (model) => ['-c', `model=${JSON.stringify(model)}`],
+  gemini: (model) => ['-m', model],
+});
+
+/**
+ * The launch arguments that put text in a worker's system prompt, as Hermes's agent puts the home's memory in
+ * its own at session start (docs/plans/hermes-compat.md row 13): Claude Code appends to its system prompt;
+ * Codex takes developer instructions (a `developer_instructions` in the Codex home's `config.toml` is
+ * overridden for the session).
+ */
+/**
+ * The launch flag that names a worker's session, where the harness has one. A worker carries its orchestrator's
+ * name (its home's), so the orchestrator stays addressable by that name as it replaces its workers.
+ */
+export const NAME_ARGUMENTS = Object.freeze({
+  'claude-code': (name) => ['--name', name],
+});
+
+export const INSTRUCTION_ARGUMENTS = Object.freeze({
+  'claude-code': (text) => ['--append-system-prompt', text],
+  codex: (text) => ['-c', `developer_instructions=${JSON.stringify(text)}`],
+});
+
+/** Why `model` cannot reach a `harness` worker, or null when it can (or none is set). */
+export function modelError(harness, model) {
+  if (!model || !harness) return null;
+  return MODEL_ARGUMENTS[harness] ? null : `the orchestrator has no launch flag to give ${harness} a model; model ${model} cannot be honoured`;
+}
+
+/** The launch arguments that carry a worker's model. */
+export function modelArguments(worker) {
+  const broken = modelError(worker.harness, worker.model);
+  if (broken) throw new Error(broken);
+  return worker.model ? MODEL_ARGUMENTS[worker.harness](worker.model) : [];
+}
+
+/**
+ * Where each harness takes an approval policy at start (the harness SDK's `approval_policy`, Codex's
+ * `approvalPolicy` on `thread/start` and `thread/resume`): `untrusted` asks before every command, and the
+ * orchestrator answers each ask with Hermes's approval rule (loop.mjs `onWorkerEvent`). Codex takes no such
+ * policy from its config (`approval_policy = "untrusted"` in `config.toml` stops its app server: measured).
+ */
+export const APPROVAL_POLICY = Object.freeze({ codex: 'untrusted' });
+
+/**
+ * Where the owner turned a profile's approvals off, its worker runs as a container's does: nothing asks, and the
+ * harness's own sandbox is off. Codex's default (workspace-write, no network) otherwise asks to reach GitHub and, with
+ * nobody attending, is denied (measured: the organization cycle could not read its own Discussion). Codex takes the
+ * policy on `thread/start` and its sandbox as a launch override.
+ */
+export const OPEN_POLICY = Object.freeze({ codex: 'never' });
+export const OPEN_ARGUMENTS = Object.freeze({ codex: ['-c', 'sandbox_mode="danger-full-access"'] });
+
+const approvalsOff = (profile) => String(profile?.residue?.config?.approvals?.mode ?? 'manual').trim().toLowerCase() === 'off';
+
+/**
+ * The approval policy a worker starts with: its harness's asking policy where the profile keeps Hermes's
+ * approvals (`approvals.mode`, `manual` when unset, as Hermes reads it), its open policy where the owner turned them off.
+ */
+export function approvalPolicy(profile, harness) {
+  return approvalsOff(profile) ? OPEN_POLICY[harness] : APPROVAL_POLICY[harness];
+}
+
+/** The launch arguments that turn a harness's own sandbox off, for a profile whose approvals are off. */
+export function sandboxArguments(profile, harness) {
+  return approvalsOff(profile) ? [...(OPEN_ARGUMENTS[harness] ?? [])] : [];
+}
+
+/**
+ * Hermes `resolve_turn_limit`: the profile's `agent.max_turns` as a positive
+ * cap, or null for unlimited (Hermes's default; `none`, `inf`, 0, -1 and
+ * anything unparseable included).
+ */
+export function turnLimit(profile) {
+  const config = profile?.residue?.config ?? {};
+  // Hermes reads agent.max_turns, then a root-level max_turns
+  const raw = config.agent?.max_turns ?? config.max_turns;
+  if (raw === null || raw === undefined || typeof raw === 'boolean') return null;
+  const n = Math.trunc(Number(String(raw).trim()));
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * How each worker CLI takes a turn cap at launch. Claude Code takes `--max-turns`, which its --help does not
+ * list (the flag is in the binary and is the SDK's `maxTurns`); codex-cli 0.156.1 takes none.
+ */
+export const TURN_ARGUMENTS = Object.freeze({
+  // Claude Code's own turn cap in print mode (`--max-turns`, the SDK's `maxTurns`)
+  'claude-code': (turns) => ['--max-turns', String(turns)],
+});
+
+/**
+ * For a worker that takes no turn cap at launch, the event it reports once per model round trip, which the
+ * orchestrator counts against `agent.max_turns` (loop.mjs `holdTurnLimit`). Measured on codex-cli through the
+ * app server: a turn of three commands and a reply reports `thread/tokenUsage/updated` four times, once per
+ * model call, and reports no `tool` events at all.
+ */
+export const ROUND_TRIP_EVENTS = Object.freeze({
+  codex: (ev) => ev.type === 'native' && ev.kind === 'thread/tokenUsage/updated',
+});
+
+/**
+ * One worker's count of a turn's round trips against `agent.max_turns`, or null where the cap is rendered at launch,
+ * there is none, or the worker reports no round trip. `count(ev)` is true once, on the call past the cap, when the
+ * caller interrupts the turn. A turn the cap stopped is not a success: Codex reports it as `interrupted`, which the
+ * SDK reads as completed, so `settle(w)` turns that turn's final into a failure that names the cap.
+ */
+export function turnCounter(profile, harness) {
+  const roundTrip = ROUND_TRIP_EVENTS[harness];
+  const cap = turnLimit(profile);
+  if (!roundTrip || TURN_ARGUMENTS[harness] || cap === null) return null;
+  let n = 0;
+  return {
+    cap,
+    start() { n = 0; },
+    count(ev) {
+      if (!roundTrip(ev)) return false;
+      n += 1;
+      return n === cap + 1;
+    },
+    settle(w) {
+      const capped = n > cap;
+      n = 0;
+      return capped ? { ...w, outcome: 'error', message: `${cap + 1} model calls passed agent.max_turns ${cap}; the turn was interrupted` } : w;
+    },
+  };
+}
+
+/**
+ * A folder's `agent.max_turns` is Hermes's config carried over, not a limit
+ * the setup declared: `hermes setup` writes one by default (150, or 90), so
+ * refusing on it would stop every imported home. It is rendered where a
+ * worker takes it and otherwise reported, once per start, as not enforced.
+ * A turn limit the package declares is the applier's to refuse (plan §7).
+ */
+/** Said once per (profile, harness, cap) for the life of the process. */
+const UNENFORCED = new Set();
+
+export function limitArguments(profile, worker, log = () => {}) {
+  const turns = turnLimit(profile);
+  if (turns === null) return [];
+  const render = TURN_ARGUMENTS[worker.harness];
+  if (!render && ROUND_TRIP_EVENTS[worker.harness]) return [];
+  if (!render) {
+    const said = `${profile.name}|${worker.harness}|${turns}`;
+    if (!UNENFORCED.has(said)) {
+      UNENFORCED.add(said);
+      log('warn', `profile ${profile.name}: agent.max_turns ${turns} is not enforced: ${worker.harness} takes no turn limit at launch`);
+    }
+    return [];
+  }
+  return render(turns);
+}