@commonlyai/cli 0.1.0

package/src/lib/adapters/codex.js

@@ -0,0 +1,251 @@
+/**
+ * codex adapter — wraps the local `codex` CLI as a Commonly agent.
+ *
+ * Contract: ADR-005 §Adapter pattern.
+ *
+ * Tested against codex-cli 0.125.0. The argv shape diverges from the
+ * ADR-005 §Adapters-shipped-in-v1 table (which was written against an
+ * earlier codex-acp variant): modern codex uses `codex exec resume <id>`
+ * as a subcommand to continue a session, NOT a `--session <id>` flag.
+ * If a future codex bumps the surface again, this adapter is the single
+ * file to update.
+ *
+ * Output shape:
+ *   - stdout = JSONL events: `{"type":"thread.started","thread_id":"<uuid>"}`,
+ *     `{"type":"turn.started"}`, `{"type":"turn.failed","error":{...}}`, etc.
+ *   - stderr = Rust tracing logs (timestamped), unrelated to model output.
+ *
+ * We capture session id from the `thread.started` event and read the agent's
+ * final reply from the file written via `-o <FILE>` (codex's
+ * `--output-last-message` short alias) — cleaner than parsing every
+ * event-type variant the model can emit.
+ *
+ * Memory preamble: if ctx.memoryLongTerm is non-empty, the adapter prepends
+ * it to the prompt as a system-context preamble (§Memory bridge), matching
+ * the claude adapter's shape so the run loop's per-event memory plumbing
+ * works identically across drivers.
+ *
+ * Purity (§Load-bearing invariants #1): input = argv + env + prompt;
+ * output = text + session id. No direct network, no direct CAP calls.
+ *
+ * Test seam: `ctx._spawnImpl` is the sanctioned way for any adapter in this
+ * codebase to swap `child_process.spawn` out for a mock. Same convention as
+ * claude.js so future adapters stay uniform.
+ *
+ * Timeout caveat: SIGTERM at `timeoutMs`, then wait for `close`. If codex
+ * ignores SIGTERM the promise never resolves — same caveat as claude.js;
+ * SIGKILL escalation is a post-v1 concern (ADR-005 §Spawning semantics).
+ */
+
+import { spawn as childSpawn, spawnSync } from 'child_process';
+import { mkdtemp, readFile, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+// Default timeout for a single codex spawn (exec mode).
+//
+// 2026-05-20 smoke surface: Cody's cycle-0 research task ran 15+ web
+// searches across openai/codex release notes (a legitimate research
+// workload) and was SIGTERM'd at exactly 300_000ms — the adapter killed
+// her before she could synthesize the final reply. 5 minutes is too
+// tight for codex `exec` mode under real tool-use; the bigger model
+// (gpt-5.4) + web.run + reasoning is just slower than a chat turn.
+// Bumping to 15 minutes gives multi-step research / repo investigation
+// room to finish without disabling the cap (pathological hangs still
+// SIGTERM).
+//
+// Operators can override via the COMMONLY_AGENT_RUN_TIMEOUT_MS env var
+// without rebuilding (caller-supplied `ctx.timeoutMs` still wins).
+// Invalid / non-positive values fall through to the default rather
+// than disabling the timeout entirely.
+const DEFAULT_TIMEOUT_MS = (() => {
+  const fallback = 15 * 60 * 1000;
+  const raw = process.env.COMMONLY_AGENT_RUN_TIMEOUT_MS;
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+})();
+
+const buildPrompt = (prompt, memoryLongTerm) => {
+  if (!memoryLongTerm) return prompt;
+  return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
+};
+
+// Build the argv after the `codex` binary. Resume vs new turn is a
+// subcommand-level distinction in modern codex, not an option flag — keep
+// that detail isolated here so the spawn path stays linear.
+const buildArgs = ({ sessionId, prompt, outputFile }) => {
+  // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
+  // bubblewrap (bwrap) sandbox + approval prompts. bwrap needs CAP_SYS_ADMIN
+  // or unprivileged user-namespaces — neither available to standard k8s
+  // containers without elevated securityContext. Without this flag, every
+  // shell tool call (git, ls, pwd, ...) fails with "bwrap: Failed to make /
+  // slave: Permission denied" inside cloud-codex pods (verified 2026-05-15).
+  // The pod is the security perimeter — agent identity is isolated, workspace
+  // is PVC-scoped, no host mounts. bwrap inside the pod is redundant.
+  // On a laptop wrapper run (sam-local-codex etc.) the same flag is fine: the
+  // operator's machine is already the security boundary they signed up for
+  // when running `commonly agent run`.
+  const common = [
+    '--json',
+    '--skip-git-repo-check',
+    '--dangerously-bypass-approvals-and-sandbox',
+    '-o',
+    outputFile,
+  ];
+  if (sessionId) {
+    // Place <sessionId> immediately after the `exec resume` subcommand so a
+    // future codex parser change can't accidentally consume it as the value
+    // of a preceding flag (e.g. -o). Codex's CLI signature is documented as
+    // `codex exec resume [OPTIONS] [SESSION_ID] [PROMPT]`, and this ordering
+    // matches that intent unambiguously regardless of clap version.
+    return ['exec', 'resume', sessionId, ...common, prompt];
+  }
+  return ['exec', ...common, prompt];
+};
+
+// Stream-parse JSONL stdout. Codex emits one event per line; partial lines
+// across chunk boundaries are buffered and flushed on the next newline.
+const makeEventParser = () => {
+  let buffer = '';
+  let threadId = null;
+  let turnFailedMessage = null;
+
+  const consume = (chunk) => {
+    buffer += chunk.toString();
+    let nl;
+    // eslint-disable-next-line no-cond-assign
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      try {
+        const evt = JSON.parse(line);
+        if (evt.type === 'thread.started' && evt.thread_id && !threadId) {
+          threadId = evt.thread_id;
+        } else if (evt.type === 'turn.failed') {
+          // Capture the most recent — codex may emit multiple before exit.
+          turnFailedMessage = evt.error?.message || 'codex turn failed';
+        }
+      } catch {
+        // Non-JSON lines on stdout are unexpected but not fatal — skip.
+      }
+    }
+  };
+
+  return {
+    consume,
+    get threadId() { return threadId; },
+    get turnFailedMessage() { return turnFailedMessage; },
+  };
+};
+
+const runCodex = ({ args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => 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'] });
+  let stderr = '';
+  let timedOut = false;
+  const events = makeEventParser();
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill('SIGTERM');
+  }, timeoutMs);
+
+  proc.stdout?.on('data', (chunk) => events.consume(chunk));
+  proc.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+  proc.on('error', (err) => {
+    clearTimeout(timer);
+    reject(err);
+  });
+  proc.on('close', (code) => {
+    clearTimeout(timer);
+    if (timedOut) return reject(new Error(`codex timed out after ${timeoutMs}ms`));
+    if (events.turnFailedMessage) {
+      // Surface the model-side failure message verbatim — the run loop posts
+      // it as the agent's reply so the user sees what went wrong rather than
+      // a generic "non-zero exit" error.
+      return reject(new Error(`codex turn failed: ${events.turnFailedMessage}`));
+    }
+    if (code !== 0) {
+      return reject(new Error(`codex exited with code ${code}: ${stderr.trim().slice(0, 500)}`));
+    }
+    resolve({ threadId: events.threadId });
+  });
+});
+
+export default {
+  name: 'codex',
+  // See claude.js for the rationale — identity-bearing runtime tag persisted
+  // to AgentInstallation.config.runtime (paired with host:'byo') so a CLI-
+  // attached Codex agent and a cloud-hosted Codex agent share the same
+  // `runtimeType` and differ only on `host`.
+  runtimeType: 'codex',
+
+  async detect() {
+    try {
+      const res = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+      if (res.error || res.status !== 0) return null;
+      // `codex --version` prints e.g. "codex-cli 0.125.0" — last token is
+      // the version. Defensive against future format tweaks: if no
+      // dotted-numeric token is found, fall back to the raw stdout.
+      const stdout = (res.stdout || '').trim();
+      const versionMatch = stdout.match(/(\d+\.\d+(?:\.\d+)?)/);
+      const version = versionMatch ? versionMatch[1] : (stdout || 'unknown');
+      const where = spawnSync('which', ['codex'], { encoding: 'utf8' });
+      const path = where.status === 0 ? (where.stdout || '').trim() || 'codex' : 'codex';
+      return { path, version };
+    } catch {
+      return null;
+    }
+  },
+
+  async spawn(prompt, ctx = {}) {
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm || '');
+
+    // Per-spawn temp dir for --output-last-message. Cleaned up in `finally`
+    // so a crash in the middle of the spawn doesn't leak files in $TMPDIR.
+    const dir = await mkdtemp(join(tmpdir(), 'commonly-codex-'));
+    const outputFile = join(dir, 'last-message.txt');
+
+    try {
+      const args = buildArgs({
+        sessionId: ctx.sessionId || null,
+        prompt: fullPrompt,
+        outputFile,
+      });
+
+      const { threadId } = await runCodex({
+        args,
+        cwd: ctx.cwd,
+        env: ctx.env,
+        timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
+      });
+
+      let text = '';
+      try {
+        text = (await readFile(outputFile, 'utf8')).trim();
+      } catch {
+        // codex didn't write the file — empty turn or stream parsing edge.
+        // Caller (run loop) treats empty text as a failed spawn and re-delivers.
+        text = '';
+      }
+
+      // newSessionId precedence: thread_id from this turn (always emitted on
+      // a new session, often re-emitted on resume) > the persisted id we
+      // came in with > null. The wrapper persists whichever non-null value
+      // we return so subsequent turns hit `codex exec resume <id>`.
+      const newSessionId = threadId || ctx.sessionId || null;
+      return { text, newSessionId };
+    } finally {
+      try { await rm(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  },
+};

package/src/lib/adapters/index.js

@@ -0,0 +1,22 @@
+/**
+ * Adapter registry — ADR-005 §Adapter pattern.
+ *
+ * `attach <adapter>` and `run <name>` both resolve an adapter by its string
+ * name through this single registry. Adding a new CLI (claude, codex, cursor,
+ * gemini, …) is a one-file PR that exports a default adapter and adds an
+ * entry below.
+ */
+
+import stub from './stub.js';
+import claude from './claude.js';
+import codex from './codex.js';
+
+const ADAPTERS = {
+  [stub.name]: stub,
+  [claude.name]: claude,
+  [codex.name]: codex,
+};
+
+export const listAdapterNames = () => Object.keys(ADAPTERS);
+
+export const getAdapter = (name) => ADAPTERS[name] || null;

package/src/lib/adapters/stub.js

@@ -0,0 +1,24 @@
+/**
+ * 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)}` };
+  },
+};

package/src/lib/api.js

@@ -0,0 +1,62 @@
+/**
+ * CAP HTTP client — thin wrapper over fetch.
+ *
+ * Every method reads the active instance URL and token from config
+ * unless overridden. This is the only place that makes HTTP calls.
+ */
+
+import { resolveInstanceUrl, getToken } from './config.js';
+
+const headers = (token, extra = {}) => ({
+  'Content-Type': 'application/json',
+  ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  ...extra,
+});
+
+const handleResponse = async (res) => {
+  const text = await res.text();
+  let body;
+  try { body = JSON.parse(text); } catch { body = { message: text }; }
+  if (!res.ok) {
+    const msg = body?.error || body?.message || `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+  return body;
+};
+
+export const createClient = ({ instance = null, token = null } = {}) => {
+  const baseUrl = resolveInstanceUrl(instance);
+  const authToken = token || getToken(instance);
+
+  const get = (path, params = {}) => {
+    const url = new URL(`${baseUrl}${path}`);
+    Object.entries(params).forEach(([k, v]) => v != null && url.searchParams.set(k, v));
+    return fetch(url.toString(), { headers: headers(authToken) }).then(handleResponse);
+  };
+
+  const post = (path, body = {}) => fetch(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: headers(authToken),
+    body: JSON.stringify(body),
+  }).then(handleResponse);
+
+  const del = (path) => fetch(`${baseUrl}${path}`, {
+    method: 'DELETE',
+    headers: headers(authToken),
+  }).then(handleResponse);
+
+  return { get, post, del, baseUrl };
+};
+
+// Convenience: login doesn't need a token
+export const login = async (instanceUrl, email, password) => {
+  const res = await fetch(`${instanceUrl}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+  return handleResponse(res);
+};

package/src/lib/config.js

@@ -0,0 +1,138 @@
+/**
+ * Config management — ~/.commonly/config.json
+ *
+ * Stores auth tokens and instance URLs across sessions.
+ * Multiple instances supported (default, local, custom).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CONFIG_DIR = join(homedir(), '.commonly');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_INSTANCE_URL = 'https://api.commonly.me';
+const LOCAL_INSTANCE_URL = 'http://localhost:5000';
+
+const read = () => {
+  if (!existsSync(CONFIG_FILE)) return { instances: {}, active: 'default' };
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return { instances: {}, active: 'default' };
+  }
+};
+
+const write = (config) => {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+};
+
+export const getConfig = () => read();
+
+const normalizeUrl = (value) => (value || '').replace(/\/$/, '').toLowerCase();
+
+/**
+ * Resolve an instance identifier to the saved instance record.
+ *
+ * Accepts either form:
+ *   - A saved key:  'dev', 'default', 'local'
+ *   - A URL:        'https://api.commonly.me' (any case; trailing / ok)
+ *   - null:         falls back to config.active
+ *
+ * Historically `resolveInstanceUrl` treated the arg as a URL and `getToken`
+ * treated it as a key — so `--instance dev` and `--instance <url>` each
+ * worked for exactly one of URL-resolution or token-lookup and broke the
+ * other. Funneling both through this helper closes that asymmetry.
+ *
+ * URL-shaped inputs (http[s]://) go through URL resolution first so a
+ * hypothetical key named `"https-backup"` can't collide with a real URL.
+ * For an unknown URL (no saved match) we return the URL with a null token,
+ * which is needed for login bootstrap (there is no saved instance yet) and
+ * for unauthenticated probe calls.
+ */
+export const resolveInstance = (identifier = null) => {
+  const config = read();
+
+  if (!identifier) {
+    const key = config.active || 'default';
+    const inst = config.instances[key];
+    return inst ? { key, ...inst } : null;
+  }
+
+  // URL-shaped inputs: resolve by URL first. Case-insensitive match so that
+  // `HTTPS://API-DEV.commonly.me/` finds a record saved as the lowercased
+  // `https://api.commonly.me`.
+  const looksLikeUrl = /^https?:\/\//i.test(identifier);
+  if (looksLikeUrl) {
+    const normalized = normalizeUrl(identifier);
+    const urlEntry = Object.entries(config.instances)
+      .find(([, v]) => normalizeUrl(v.url) === normalized);
+    if (urlEntry) {
+      const [key, value] = urlEntry;
+      return { key, ...value };
+    }
+    // Unknown URL — still usable for bootstrapping. Preserve the caller's
+    // original case in the returned URL (some servers are case-sensitive on
+    // paths; we only lowercase for match comparison above).
+    return { key: null, url: identifier.replace(/\/$/, ''), token: null };
+  }
+
+  // Key-shaped inputs: exact lookup only.
+  if (config.instances[identifier]) {
+    return { key: identifier, ...config.instances[identifier] };
+  }
+
+  // Unknown key — caller falls back to defaults.
+  return null;
+};
+
+// Alias kept for existing imports (login.js). Functionally identical to
+// resolveInstance; callers using this name pre-date the refactor.
+export const getActiveInstance = (instanceOverride = null) => resolveInstance(instanceOverride);
+
+export const resolveInstanceUrl = (instanceArg = null) => {
+  const inst = resolveInstance(instanceArg);
+  if (inst?.url) return inst.url.replace(/\/$/, '');
+  return DEFAULT_INSTANCE_URL;
+};
+
+export const saveInstance = ({ key = 'default', url, token, userId, username }) => {
+  const config = read();
+  config.instances[key] = {
+    url: url.replace(/\/$/, ''),
+    token,
+    userId,
+    username,
+    savedAt: new Date().toISOString(),
+  };
+  config.active = key;
+  write(config);
+};
+
+export const setActive = (key) => {
+  const config = read();
+  if (!config.instances[key]) throw new Error(`Instance '${key}' not found in config`);
+  config.active = key;
+  write(config);
+};
+
+export const getToken = (instanceOverride = null) => {
+  // Env var takes precedence (CI, scripts)
+  if (process.env.COMMONLY_TOKEN) return process.env.COMMONLY_TOKEN;
+  const inst = resolveInstance(instanceOverride);
+  return inst?.token || null;
+};
+
+export const listInstances = () => {
+  const config = read();
+  return Object.entries(config.instances).map(([key, val]) => ({
+    key,
+    ...val,
+    active: key === config.active,
+  }));
+};
+
+export const LOCAL_URL = LOCAL_INSTANCE_URL;
+export const DEFAULT_URL = DEFAULT_INSTANCE_URL;