@commonlyai/cli 0.1.172 → 0.1.174

package/src/lib/adapters/codex.js

@@ -1,5 +1,6 @@
 import { codexRuntimeInventory } from '../native-runtime-inventory.js';
 import { observeSpawn, controlsFromArguments } from '../runtime-observation.js';
+import { spawnInOwnGroup, wantsOwnProcessGroup } from '@commonlyai/seats/process-group';
 /**
  * codex adapter — wraps the local `codex` CLI as a Commonly agent.
  *
@@ -572,14 +573,15 @@ const CODEX_PROVIDER_KEY_ENVS = [
   'CODEX_API_KEY',
 ];
 
-const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {} }) => new Promise((resolve, reject) => {  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
+// `ownGroup`: see runClaude in claude.js.
+const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = childSpawn, onSpawn, controls = {}, ownGroup = false }) => new Promise((resolve, reject) => {  // stdio: ['ignore', 'pipe', 'pipe'] — without this, child_process.spawn
   // defaults stdin to a fresh pipe. Codex 0.125.0's `exec` then blocks on
   // `Reading additional input from stdin...` because it sees an open pipe
   // and waits for input that never arrives. Interactive runs are fine because
   // codex detects a TTY and uses the argv prompt directly. Setting stdin to
   // `'ignore'` gives codex /dev/null → immediate EOF → it falls back to the
   // argv prompt as intended. Surfaced live during ADR-005 Phase 2 smoke.
-  const proc = spawnImpl('codex', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+  const proc = spawnInOwnGroup(spawnImpl, 'codex', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }, { ownGroup });
   observeSpawn(proc, onSpawn, controls);
   let stderr = '';
   let timedOut = false;
@@ -745,6 +747,7 @@ export default {
         // nothing left to compare a tail against.
         credentials: spawnCredentials(ctx, CODEX_PROVIDER_KEY_ENVS),
         spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(args.slice(args.indexOf('exec') + (args[args.indexOf('exec') + 1] === 'resume' ? 3 : 1), -1), { modelFlag: '--model', valueFlags: ['-c', '-o', '--permission-profile'], codex: true }), // test seam only — do not use in production
+        ownGroup: wantsOwnProcessGroup(ctx),
       });
 
       let text = '';

package/src/lib/adapters/hermes.js

@@ -1,199 +1,18 @@
-import { observeSpawn, controlsFromArguments } from '../runtime-observation.js';
-/** Hermes 0.22.2 local CLI wrapper. Hermes owns provider I/O; this file only spawns it. */
-import { requireSeatModel, seatModelRequired } from './seat-model.js';
-import { spawn as childSpawn, spawnSync } from 'child_process';
-import { createHash } from 'crypto';
-import { mkdir } from 'fs/promises';
 import { homedir } from 'os';
 import { join } from 'path';
-import { StringDecoder } from 'string_decoder';
+import { createHermesAdapter } from '@commonlyai/seats/adapters/hermes';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { effectiveSandboxTrust } from '../environment.js';
-import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
-
-export const TESTED_HERMES_VERSION = '0.22.2';
-const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
-const VERSION_TIMEOUT_MS = 15000;
-const MAX_STDERR_CHARS = 4096;
-const MAX_LINE_CHARS = 1024 * 1024;
-
-const readVersion = (env, spawnSyncImpl = spawnSync) => {
-  let probe;
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    probe = spawnSyncImpl('hermes', ['--version'], {
-      encoding: 'utf8', env, timeout: VERSION_TIMEOUT_MS,
-    });
-    if (probe.error?.code === 'ENOENT') return null;
-    if (probe.error || probe.status !== 0) continue;
-    const version = String(probe.stdout || '').match(/Hermes Agent v([^\s]+)/i)?.[1];
-    if (version !== TESTED_HERMES_VERSION) {
-      throw new Error(`Hermes ${version || 'unknown'} is unsupported; this adapter requires ${TESTED_HERMES_VERSION}`);
-    }
-    return version;
-  }
-  const status = probe.status ?? 'none';
-  const signal = probe.signal ?? 'none';
-  const code = probe.error?.code ?? 'none';
-  throw new Error(`Hermes version probe failed after 2 attempts (status=${status}, signal=${signal}, code=${code}, timeout=${VERSION_TIMEOUT_MS}ms); check the Hermes installation or startup log`);
-};
-
-export const readHermesJsonl = (line, state) => {
-  let event;
-  try { event = JSON.parse(line); } catch { throw new Error('Hermes emitted invalid JSONL'); }
-  if (state.result) throw new Error('Hermes emitted data after its terminal result');
-  if (event?.type === 'system' && event.subtype === 'init') {
-    state.started = true;
-  } else if (event?.type === 'result') {
-    state.result = event;
-  } else if (!state.started) {
-    throw new Error('Hermes emitted an event before init');
-  }
-};
-
-const runHermes = ({ args, prompt, cwd, env, timeoutMs, spawnImpl, credentials, onSpawn, controls = {} }) => new Promise((resolve, reject) => {
-  const child = (spawnImpl || childSpawn)('hermes', args, {
-    cwd, env, stdio: ['pipe', 'pipe', 'pipe'],
-  });
-  observeSpawn(child, onSpawn, controls);
-  const state = { started: false, result: null };
-  const decoder = new StringDecoder('utf8');
-  let buffer = '';
-  let stderr = '';
-  let timedOut = false;
-  let settled = false;
-  let closed = false;
-  let stopping = false;
-  let killTimer;
-  const finish = (error, result) => {
-    if (settled) return;
-    settled = true;
-    clearTimeout(timer);
-    if (error) reject(error); else resolve(result);
-  };
-  const stop = () => {
-    if (stopping || closed) return;
-    stopping = true;
-    child.kill('SIGTERM');
-    killTimer = setTimeout(() => {
-      if (!closed) child.kill('SIGKILL');
-    }, 5000);
-  };
-  const failAndStop = (error) => {
-    stop();
-    finish(error);
-  };
-  const timer = setTimeout(() => {
-    timedOut = true;
-    stop();
-  }, timeoutMs);
-  child.on('error', (error) => failAndStop(adapterFailure('Hermes', error?.message || 'spawn failed', { credentials })));
-  child.stdout.on('data', (chunk) => {
-    if (settled) return;
-    buffer += decoder.write(chunk);
-    let newline = buffer.indexOf('\n');
-    while (newline !== -1) {
-      if (newline > MAX_LINE_CHARS) {
-        failAndStop(new Error('Hermes JSONL line exceeded 1 MiB'));
-        return;
-      }
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      if (line) {
-        try { readHermesJsonl(line, state); } catch (error) {
-          failAndStop(error);
-          return;
-        }
-      }
-      newline = buffer.indexOf('\n');
-    }
-    if (buffer.length > MAX_LINE_CHARS) {
-      failAndStop(new Error('Hermes JSONL line exceeded 1 MiB'));
-    }
-  });
-  child.stdout.on('error', (error) => failAndStop(adapterFailure('Hermes stdout', error?.message || 'read failed', { credentials })));
-  child.stderr.on('data', (chunk) => {
-    stderr = `${stderr}${chunk.toString()}`.slice(-MAX_STDERR_CHARS);
-  });
-  child.on('close', (code) => {
-    closed = true;
-    clearTimeout(killTimer);
-    if (settled) return;
-    if (timedOut) return finish(new Error(`Hermes timed out after ${timeoutMs}ms`));
-    buffer += decoder.end();
-    if (buffer.trim()) {
-      try { readHermesJsonl(buffer.trim(), state); } catch (error) { return finish(error); }
-    }
-    const result = state.result;
-    if (!result || !state.started) return finish(new Error('Hermes exited without a complete JSONL result'));
-    if (code !== 0 || result.exit_code !== 0) {
-      return finish(adapterFailure('Hermes', result.error || stderr || `exit ${code}`, {
-        credentials, exitCode: code,
-      }));
-    }
-    if (typeof result.text !== 'string' || !result.session_id) {
-      return finish(new Error('Hermes result omitted text or session_id'));
-    }
-    return finish(null, { text: result.text, newSessionId: result.session_id });
-  });
-  child.stdin.on('error', (error) => failAndStop(adapterFailure('Hermes stdin', error?.message || 'write failed', { credentials })));
-  child.stdin.end(prompt);
+import { seatModelRequired } from './seat-model.js';
+
+export { TESTED_HERMES_VERSION, readHermesJsonl } from '@commonlyai/seats/adapters/hermes';
+
+// Commonly's policy for the generic Hermes adapter: its memory preamble, its
+// legacy sandbox-trust names, the fleet seat-model switch, and the profile
+// directory seats have always used.
+export default createHermesAdapter({
+  memoryPreamble: buildMemoryPreamble,
+  effectiveTrust: effectiveSandboxTrust,
+  seatModelRequired,
+  profileRoot: join(homedir(), '.commonly', 'hermes', 'profiles'),
 });
-
-export default {
-  get requiresModel() { return seatModelRequired(); },
-  name: 'hermes',
-  runtimeType: 'hermes',
-  supportsProvider: false,
-  providerKeyEnv: 'OPENROUTER_API_KEY',
-
-  async validateEnvironment(environment) {
-    if (environment?.provider !== undefined) {
-      throw new Error('Hermes adapter does not consume environment.provider; supply OPENROUTER_API_KEY in the host environment');
-    }
-    if (environment?.mcp?.length) {
-      throw new Error('Hermes adapter does not yet consume environment.mcp declarations');
-    }
-    if (effectiveSandboxTrust(environment?.sandbox?.trust) === 'public'
-      || (environment?.sandbox?.mode && environment.sandbox.mode !== 'none')) {
-      throw new Error('Hermes public or sandbox-declared seats are unsupported: no enforced confinement adapter exists');
-    }
-  },
-
-  async detect() {
-    const version = readVersion(process.env);
-    return version ? { path: 'hermes', version } : null;
-  },
-
-  async spawn(prompt, ctx = {}) {
-    const seatModel = requireSeatModel(ctx.environment, 'hermes');
-    await this.validateEnvironment(ctx.environment);
-    // Keep Hermes away from the operator's default profile, including any
-    // Nous Portal/Cloud credentials there. The wrapper provides the sole key.
-    const seat = `${ctx.agentName || ''}\0${ctx.cwd || ''}`;
-    const home = ctx._hermesHome || join(homedir(), '.commonly', 'hermes', 'profiles',
-      createHash('sha256').update(seat).digest('hex').slice(0, 24));
-    await mkdir(home, { recursive: true, mode: 0o700 });
-    const env = { ...(ctx.env || process.env), HERMES_HOME: home };
-    if (!readVersion(env, ctx._spawnSyncImpl)) {
-      throw new Error('Hermes Agent 0.22.2 is not on PATH');
-    }
-    if (!env.OPENROUTER_API_KEY) {
-      throw new Error('Supply the operator OPENROUTER_API_KEY through Secret Manager before running Hermes');
-    }
-    const args = ['chat', '--oneshot', '--query-file', '-', '--format', 'stream-json',
-      '--provider', 'openrouter', '--source', 'tool', '--no-restore-cwd'];
-    if (seatModel) args.push('--model', seatModel);
-    if (ctx.sessionId) args.push('--resume', ctx.sessionId);
-    const fullPrompt = buildMemoryPreamble(prompt, ctx.memoryLongTerm, {
-      freshSession: !ctx.sessionId,
-    });
-    const requestedTimeout = Number(ctx.timeoutMs);
-    const timeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
-      ? Math.min(requestedTimeout, DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
-    return runHermes({
-      args, prompt: fullPrompt, cwd: ctx.cwd, env, timeoutMs,
-      spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(args, { modelFlag: '--model', valueFlags: ['--query-file', '--format', '--provider', '--source', '--resume'] }),
-      credentials: spawnCredentials(ctx, ['OPENROUTER_API_KEY']),
-    });
-  },
-};

package/src/lib/adapters/seat-model.js

@@ -1,15 +1,8 @@
+import { requireSeatModel as requireDeclaredModel } from '@commonlyai/seats/seat-model';
+
 /** Fleet runners opt in; BYO users retain their own CLI's model default. */
 export const seatModelRequired = () => process.env.COMMONLY_REQUIRE_SEAT_MODEL === '1';
 
-export const requireSeatModel = (environment, adapterName, required = seatModelRequired()) => {
-  const model = environment?.model;
-  if (typeof model !== 'string' || !model.trim()) {
-    if (!required) return undefined;
-    const error = new Error(
-      `${adapterName} requires environment.model; set the seat model with commonly agent config <name> --model <model> before running`,
-    );
-    error.code = 'seat_model_missing';
-    throw error;
-  }
-  return model.trim();
-};
+export const requireSeatModel = (environment, adapterName, required = seatModelRequired()) => (
+  requireDeclaredModel(environment, adapterName, required)
+);

package/src/lib/adapters/stub.js

@@ -1,24 +1 @@
-/**
- * Stub adapter — the no-op reference implementation of the ADR-005 adapter
- * contract. Used by `commonly agent attach stub` and the Phase-1a test
- * harness so the run loop can be reviewed end-to-end without a real CLI
- * on PATH.
- *
- * Contract (ADR-005 §Adapter pattern):
- *   detect(): Promise<{ path, version } | null>
- *   spawn(prompt, ctx): Promise<{ text, newSessionId?, memorySummary? }>
- *
- * The adapter MUST be pure: input (argv + env + prompt) → output (text + optional
- * next session-id + optional memory summary). No direct network, no direct API
- * calls, no hidden state. The run loop handles all Commonly-facing I/O.
- */
-
-export default {
-  name: 'stub',
-  async detect() {
-    return { path: '(builtin)', version: '0.0.0' };
-  },
-  async spawn(prompt, _ctx) {
-    return { text: `(stub) received: ${String(prompt ?? '').slice(0, 200)}` };
-  },
-};
+export { default } from '@commonlyai/seats/adapters/stub';

package/src/lib/runtime-observation.js

@@ -1,30 +1,6 @@
-// Read only adapter-owned control arguments. Callers exclude prompt/stdin and
-// provide every value-taking option, so a flag-shaped model/session value is
-// never reinterpreted as a second option. Raw arguments never leave the runner.
-export const controlsFromArguments = (args, { modelFlag, effortFlag, valueFlags = [], codex = false }) => {
-  const controls = { model: null, effort: null };
-  const flags = new Set([modelFlag, effortFlag, ...valueFlags].filter(Boolean));
-  for (let index = 0; index < args.length; index += 1) {
-    const flag = args[index];
-    if (!flags.has(flag)) continue;
-    const value = args[++index];
-    if (flag === modelFlag) controls.model = value || null;
-    if (flag === effortFlag) controls.effort = value || null;
-    if (codex && flag === '-c' && value?.startsWith('model_reasoning_effort=')) {
-      try { controls.effort = JSON.parse(value.slice('model_reasoning_effort='.length)); } catch { /* unknown encoding */ }
-    }
-  }
-  return controls;
-};
-
-// Called at the child's successful OS spawn event, not when a requested
-// configuration is saved or when a turn is merely queued. Never send argv.
-export const observeSpawn = (child, onSpawn, controls) => {
-  if (typeof onSpawn !== 'function') return;
-  child.once('spawn', () => {
-    try { onSpawn({ model: controls.model || null, effort: controls.effort || null, at: new Date().toISOString() }); } catch { /* diagnostic only */ }
-  });
-};
+// controlsFromArguments and observeSpawn live in the seats runtime package;
+// the reporter below posts to a Commonly instance, so it stays in the CLI.
+export { controlsFromArguments, observeSpawn } from '@commonlyai/seats/runtime-observation';
 
 export const createRuntimeReporter = ({ client, harness, detect }) => {
   let queue = Promise.resolve();

package/src/lib/seat-stop.js

@@ -0,0 +1,96 @@
+/**
+ * How `agent run` stops on a signal while supervised process groups may be
+ * live (see @commonlyai/seats/process-group).
+ *
+ * SIGTERM keeps the in-flight turn: the run loop stops polling and lets the
+ * turn finish. A launchd seat is SIGKILLed ExitTimeOut seconds after SIGTERM,
+ * and that SIGKILL cannot be caught, so a supervised group (outside the seat's
+ * own group, which launchd kills) would outlive the seat. So on a launchd
+ * seat, SIGTERM also arms a deadline a margin before ExitTimeOut, and the exit
+ * path kills whatever groups are left when the turn ends first.
+ *
+ * The deadline is armed only when the seat's plist exists. A seat without one
+ * (the daemon spawns it) is stopped with SIGTERM and never SIGKILLed, so it
+ * relies on the exit path alone, and a reassignment or config change does not
+ * cut the in-flight turn.
+ *
+ * ExitTimeOut is read from the seat's plist and never written. In a plist that
+ * exists, an unset, zero or unreadable value is launchd's default of 20 s,
+ * because launchd will SIGKILL that seat.
+ */
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { armSupervisedGroupDeadline, killSupervisedGroups } from '@commonlyai/seats/process-group';
+
+export const DEFAULT_EXIT_TIMEOUT_S = 20;
+const MAX_MARGIN_MS = 5000;
+const SEAT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** The seat's launchd plist path, or null for a name that cannot be a file name. */
+export const seatPlistPath = (name, home = homedir()) => (typeof name === 'string' && SEAT_NAME.test(name)
+  ? join(home, 'Library', 'LaunchAgents', `me.commonly.seat-${name}.plist`)
+  : null);
+
+const positive = (value) => (Number.isFinite(value) && value > 0 ? value : null);
+
+/**
+ * ExitTimeOut in seconds, or null when the plist is missing, has none, or
+ * holds a value launchd would not use as a timeout. An XML plist is read
+ * directly; a binary one through `plutil -extract` (read-only).
+ */
+export const readExitTimeOut = (path, { readFile = readFileSync, run = spawnSync } = {}) => {
+  if (!path) return null;
+  let raw;
+  try { raw = readFile(path); } catch { return null; }
+  const text = Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw);
+  if (text.startsWith('bplist')) {
+    try {
+      const out = run('plutil', ['-extract', 'ExitTimeOut', 'raw', '-o', '-', path], { encoding: 'utf8', timeout: 5000 });
+      return out.status === 0 ? positive(Number(String(out.stdout).trim())) : null;
+    } catch { return null; }
+  }
+  const match = /<key>\s*ExitTimeOut\s*<\/key>\s*<(integer|real)>\s*([0-9.]+)\s*<\/\1>/.exec(text);
+  return match ? positive(Number(match[2])) : null;
+};
+
+/**
+ * Whether the seat's plist exists, and its ExitTimeOut (null when unset or
+ * unreadable). Only an existing plist means launchd will SIGKILL this seat.
+ */
+export const readSeatPlist = (path, { exists = existsSync, ...deps } = {}) => {
+  if (!path || !exists(path)) return { present: false, exitTimeOut: null };
+  return { present: true, exitTimeOut: readExitTimeOut(path, deps) };
+};
+
+/** Milliseconds after SIGTERM to kill the groups: ExitTimeOut less a margin of 5 s or a quarter, whichever is less. */
+export const groupKillDeadlineMs = (exitTimeOutS) => {
+  const totalMs = (positive(exitTimeOutS) ?? DEFAULT_EXIT_TIMEOUT_S) * 1000;
+  return Math.floor(totalMs - Math.min(MAX_MARGIN_MS, totalMs / 4));
+};
+
+/**
+ * `requestStop(signal)` stops the run loop and, on SIGTERM to a seat with a
+ * plist, arms the group deadline; `onExit` kills the groups left at exit.
+ * `deps` is a test seam.
+ */
+export const createSeatStop = ({ name, stop, home, deps = {} } = {}) => {
+  const {
+    arm = armSupervisedGroupDeadline,
+    kill = killSupervisedGroups,
+    readPlist = readSeatPlist,
+  } = deps;
+  return {
+    requestStop(signal) {
+      stop();
+      if (signal !== 'SIGTERM') return null;
+      const plist = readPlist(seatPlistPath(name, home));
+      if (!plist.present) return null;
+      const deadlineMs = groupKillDeadlineMs(plist.exitTimeOut);
+      arm(deadlineMs);
+      return deadlineMs;
+    },
+    onExit() { kill(); },
+  };
+};