@commonlyai/cli 0.1.211 → 0.1.213

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.211",
+  "version": "0.1.213",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -16,6 +16,7 @@ import { createRuntimeReporter } from '../lib/runtime-observation.js';
  * heartbeat  — manually trigger an agent's heartbeat
  */
 
+import { refreshMcpTokenCopy, removeMcpTokenCopy } from '../lib/mcp-token.js';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'fs';
 import { join, dirname, basename, resolve as pathResolve } from 'path';
 import { homedir, tmpdir } from 'os';
@@ -147,6 +148,12 @@ export const saveAgentToken = (name, record) => {
     JSON.stringify({ ...record, savedAt: new Date().toISOString() }, null, 2),
     { encoding: 'utf8', mode: 0o600 },
   );
+  // After the record is durable, so a failed refresh never loses a freshly minted token.
+  try {
+    refreshMcpTokenCopy(name, record?.runtimeToken);
+  } catch (err) {
+    console.warn(`Could not refresh the MCP token copy for '${name}': ${err.message}. Run: commonly mcp config --agent ${name}`);
+  }
 };
 
 export const loadAgentToken = (name) => {
@@ -162,6 +169,7 @@ export const loadAgentToken = (name) => {
 export const deleteAgentToken = (name) => {
   const file = tokenFile(name);
   if (existsSync(file)) rmSync(file);
+  removeMcpTokenCopy(name);
 };
 
 // ── env-var bootstrap for `agent run` (#913) ────────────────────────────────
@@ -1386,6 +1394,15 @@ const extractPrompt = (event) => {
 // cancel grace, and the wall-clock backstop past the adapter's own timeout.
 export { supervisedRunPolicy };
 
+// Codex turns are supervised by default (D211): a turn that stops making
+// progress is named and killed instead of holding the seat. COMMONLY_SUPERVISE_RUNS=0
+// opts out. Every other adapter stays off unless COMMONLY_SUPERVISE_RUNS=1.
+export const superviseRunsByDefault = (adapterName, env = process.env) => {
+  if (env.COMMONLY_SUPERVISE_RUNS === '0') return false;
+  if (adapterName === 'codex') return true;
+  return env.COMMONLY_SUPERVISE_RUNS === '1';
+};
+
 /**
  * Start the run loop. Polls /events, spawns the adapter per event, posts the
  * result into the pod, acks.
@@ -1461,14 +1478,15 @@ export const performRun = ({
   resolveOwnProviderKey = null,
   runtimeReportClient = null,
   refusalHandoff = null,
-  // Off unless COMMONLY_SUPERVISE_RUNS=1: each spawn runs under the seats
-  // supervisor (stall window, wall-clock backstop, a named failure on every
-  // settle). The CLI still talks to its provider directly, and one metadata
-  // line per turn goes to ~/.commonly/state/turns/<agent>.jsonl once
-  // delivery settles. Off, the spawn path is the plain adapter call it has
-  // always been, and nothing is written.
-  superviseRuns = process.env.COMMONLY_SUPERVISE_RUNS === '1',
+  // Each spawn runs under the seats supervisor (stall window, wall-clock
+  // backstop, a named failure on every settle) when superviseRuns is true.
+  // Unset, the default comes from superviseRunsByDefault. The CLI still talks
+  // to its provider directly, and one metadata line per turn goes to
+  // ~/.commonly/state/turns/<agent>.jsonl once delivery settles. Off, the spawn
+  // path is the plain adapter call it has always been, and nothing is written.
+  superviseRuns,
 }) => {
+  const supervising = superviseRuns ?? superviseRunsByDefault(adapter?.name);
   reportRuntime = reportRuntime && WALKED_HARNESSES.includes(adapter?.name);
   if (environment?.provider !== undefined && !adapter?.supportsProvider) {
     throw new Error('environment.provider requires a provider-capable adapter');
@@ -1480,9 +1498,9 @@ export const performRun = ({
   // The supervised run keeps its trace in memory, metadata only; no record of
   // a run is written to disk (lib/supervised-turn.js).
   const turnRunner = createTurnRunner({
-    seat: agentName, turnTimeoutMs: effectiveTurnTimeoutMs, supervise: superviseRuns, log,
+    seat: agentName, turnTimeoutMs: effectiveTurnTimeoutMs, supervise: supervising, log,
   });
-  if (superviseRuns) log(turnRunner.describe(adapter?.name));
+  if (supervising) log(turnRunner.describe(adapter?.name));
   const runtimeReporter = createRuntimeReporter({
     client: runtimeReportClient || { post: async () => {} },
     harness: adapter.name, detect: () => adapter.detect(),
@@ -1895,7 +1913,7 @@ export const performRun = ({
 
   // The spawn → post-decision half of a turn, split out so the claim release
   // above is a plain finally instead of threading through every return path.
-  // With superviseRuns, the turn's log line is written once delivery has
+  // With supervising, the turn's log line is written once delivery has
   // settled; anything thrown after a spawn that resolved means the reply never
   // reached the pod. Off, `turn` writes nothing.
   const runTurn = async (args) => {

package/src/commands/mcp.js

@@ -0,0 +1,55 @@
+/**
+ * commonly mcp config — print an MCP server config for a locally attached agent (TASK-666).
+ * The MCP server only accepts a cm_agent_* runtime token, so the config points
+ * COMMONLY_TOKEN_FILE at a 0600 copy of that token and never prints the token.
+ */
+import { listLocalAgents, loadAgentToken } from './agent.js';
+import { validMcpTokenName, writeMcpTokenCopy } from '../lib/mcp-token.js';
+
+const NO_AGENT_HINT = 'Attach one first: commonly agent attach <adapter> --pod <podId> --name <name>';
+
+export const buildMcpConfig = ({ agent } = {}) => {
+  let name = agent;
+  if (!name) {
+    const local = listLocalAgents();
+    if (local.length === 0) throw new Error(`No local agent has a runtime token on this computer. ${NO_AGENT_HINT}`);
+    if (local.length > 1) {
+      throw new Error(`More than one local agent (${local.map((a) => a.name).join(', ')}). Pick one with --agent <name>.`);
+    }
+    name = local[0].name;
+  }
+  if (!validMcpTokenName(name)) throw new Error(`Invalid agent name '${name}'`);
+  const record = loadAgentToken(name);
+  const token = String(record?.runtimeToken || '').trim();
+  if (!token) throw new Error(`No runtime token saved for agent '${name}'. ${NO_AGENT_HINT}`);
+  if (!token.startsWith('cm_agent_')) throw new Error(`The saved token for '${name}' is not a cm_agent_* runtime token. Re-attach it: commonly agent attach`);
+  if (!record.instanceUrl) throw new Error(`Agent '${name}' has no saved instance URL. Re-attach it.`);
+
+  const tokenPath = writeMcpTokenCopy(name, token);
+
+  return {
+    mcpServers: {
+      commonly: {
+        command: 'npx',
+        args: ['-y', '@commonlyai/mcp@latest'],
+        env: { COMMONLY_API_URL: record.instanceUrl, COMMONLY_TOKEN_FILE: tokenPath },
+      },
+    },
+  };
+};
+
+export const registerMcp = (program) => {
+  const mcp = program.command('mcp').description('Connect an MCP client (Claude Code, Codex, Cursor) to Commonly');
+  mcp
+    .command('config')
+    .description('Print an MCP server config for a locally attached agent; the token stays in a 0600 file')
+    .option('--agent <name>', 'Local agent to use (default: the only one)')
+    .action((opts) => {
+      try {
+        console.log(JSON.stringify(buildMcpConfig({ agent: opts.agent }), null, 2));
+      } catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+      }
+    });
+};

package/src/index.js

@@ -22,6 +22,7 @@ import { registerPod } from './commands/pod.js';
 import { registerDev } from './commands/dev.js';
 import { registerVerify } from './commands/verify.js';
 import { registerDoctor } from './commands/doctor.js';
+import { registerMcp } from './commands/mcp.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
@@ -57,6 +58,7 @@ registerVerify(program);
 
 // Install health: one line per check (TASK-660)
 registerDoctor(program);
+registerMcp(program);
 
 // Each subcommand owns its own `--instance <url>` flag; a program-level
 // duplicate shadowed the subcommand value on commander v12, causing

package/src/lib/adapters/codex.js

@@ -897,6 +897,13 @@ export default {
         await writePublicCodexInstructions(childEnv.CODEX_HOME, ctx);
       }
 
+      // The awaits above can outlast a supervisor stall window. Once it has
+      // aborted, the attempt has already settled and a retry may be running,
+      // so no process is created for this one. Checked synchronously before
+      // runCodex, so the spawn itself cannot race the abort.
+      if (ctx.signal?.aborted) {
+        throw ctx.signal.reason || new Error('codex spawn cancelled before the process started');
+      }
       const { threadId } = await runCodex({
         args,
         cwd: ctx.cwd,

package/src/lib/mcp-token.js

@@ -0,0 +1,36 @@
+/**
+ * The 0600 copy of an agent's runtime token that `commonly mcp config` points
+ * COMMONLY_TOKEN_FILE at (TASK-666). It is a second live secret, so the agent
+ * token's lifecycle owns it: save refreshes it, delete removes it.
+ */
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const validMcpTokenName = (name) => typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name) && !name.startsWith('.');
+
+export const mcpTokenPath = (name) => {
+  if (!validMcpTokenName(name)) throw new Error(`Invalid agent name '${name}'`);
+  return join(homedir(), '.commonly', 'mcp', `${name}.token`);
+};
+
+// Remove first, then create exclusively at 0600: no write into a looser-mode file or through a symlink.
+export const writeMcpTokenCopy = (name, token) => {
+  const dir = join(homedir(), '.commonly', 'mcp');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = mcpTokenPath(name);
+  rmSync(path, { force: true });
+  writeFileSync(path, `${token}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  return path;
+};
+
+// A bad name never has a copy, so remove and refresh are no-ops for it and cannot block detach or save.
+export const removeMcpTokenCopy = (name) => {
+  if (validMcpTokenName(name)) rmSync(mcpTokenPath(name), { force: true });
+};
+
+// Reattach mints a new token; a copy that already exists must follow it.
+export const refreshMcpTokenCopy = (name, token) => {
+  if (token && validMcpTokenName(name) && existsSync(mcpTokenPath(name))) writeMcpTokenCopy(name, token);
+};

package/src/lib/supervised-turn.js

@@ -3,7 +3,8 @@
  * path also writes one metadata line per turn (the turn log), once the
  * turn's outcome has reached the pod or failed to.
  *
- *   COMMONLY_SUPERVISE_RUNS=1  (read by performRun as `superviseRuns`)
+ *   codex by default, or COMMONLY_SUPERVISE_RUNS=1 (superviseRunsByDefault in
+ *     commands/agent.js; COMMONLY_SUPERVISE_RUNS=0 opts codex out)
  *     the turn runs under `superviseRun` from @commonlyai/seats: a stall
  *     window, a wall-clock backstop, and a guarantee the turn settles with a
  *     named failure. No provider relay: the CLI talks to its provider directly,