@commonlyai/cli 0.1.55 → 0.1.57

package/package.json

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

package/src/lib/adapters/pi-commonly-mcp.mjs

@@ -1,8 +1,9 @@
 /**
  * pi extension: Commonly's tools for a pi seat, over MCP.
  *
- * Loaded by adapters/pi.js with `-e`. Reads COMMONLY_PI_MCP — a JSON list of
- * `{ name, command: [...], env: {...} }` for stdio servers and
+ * Loaded by adapters/pi.js with `-e`. Reads fd 3 — a pipe the adapter writes the
+ * JSON into and ends at spawn, never the environment (see takeServers) — a JSON
+ * list of `{ name, command: [...], env: {...} }` for stdio servers and
  * `{ name, url, headers: {...} }` for Streamable HTTP ones — connects to each,
  * asks it for its tools, and registers every one with pi under its own name, so
  * a pi seat calls `commonly_post_message` exactly as a claude or codex seat
@@ -20,9 +21,16 @@ import { Type } from 'typebox';
 import { connectMcp, takeServers, toPiResult } from './pi-mcp-client.mjs';
 
 export default async function commonlyMcpBridge(pi) {
-  // Read once and remove: the list carries the seat token, and pi's bash tool
-  // inherits this process's env (see takeServers).
-  const servers = takeServers(process.env);
+  // Read once and consume: the read drains the pipe, so the list (which carries
+  // the seat token) does not survive anywhere in this process that a child could
+  // reach — not the environment, which is why it does not arrive that way.
+  const servers = takeServers();
+  // The adapter loads this extension only when it has a list to hand over, so an
+  // empty read means the channel itself failed. Say so: the symptom otherwise is
+  // a seat that silently has no commonly_* tools at all.
+  if (!servers.length) {
+    process.stderr.write('[commonly-pi-bridge] no server list on fd 3 — this seat has no commonly_* tools\n');
+  }
   const clients = [];
   for (const server of servers) {
     const client = connectMcp(server);

package/src/lib/adapters/pi-mcp-client.mjs

@@ -18,6 +18,7 @@
  */
 
 import { spawn } from 'node:child_process';
+import { closeSync, readFileSync } from 'node:fs';
 
 /**
  * The grant broker's path. wren's ruling for the daemon-side half of TASK-063:
@@ -166,14 +167,10 @@ const parseMessages = (text, contentType) => {
  *
  * `headers` is where a declared `Authorization` arrives, already substituted
  * with the seat's runtime token by the adapter. The token therefore rides in an
- * HTTP header built from the JSON list the bridge takes out of its own
- * environment (see takeServers) and never on argv. NOT on argv is the whole of
- * that guarantee: deleting the variable from the bridge's own process scrubs
- * Node's copy, not the kernel's, so a same-user child of this process can still
- * read the parent's environment (`ps eww $PPID`, `/proc/$PPID/environ`) and find
- * both the token and the server list. Treat this as "not in argv" and not as a
- * secrecy boundary; the fix is to hand the list over a 0600 file the bridge
- * unlinks on load (row filed against the bridge's env channel, Vera, Connectors).
+ * HTTP header built from the JSON list the bridge reads off its own fd 3 (see
+ * takeServers) — never on argv, and never in this process's environment, which a
+ * same-user child of this process can read back whole (`ps eww $PPID`,
+ * `/proc/$PPID/environ`) no matter what this process deletes from its own copy.
  */
 export const connectHttpMcp = ({ name, url, headers }, { fetchImpl = globalThis.fetch, timeoutMs = 60_000 } = {}) => {
   if (typeof fetchImpl !== 'function') throw new Error(`${name}: no fetch implementation for the HTTP MCP transport`);
@@ -278,23 +275,58 @@ export const toPiResult = (result) => {
 };
 
 /**
- * Read the server list and REMOVE it from the environment. The list carries every
- * server's substituted secrets — a stdio server's env and an HTTP server's
- * `Authorization` header, the seat's bearer token among them — and pi's `bash`
- * tool spawns with `{ ...process.env }` (pi's getShellEnv), so leaving it in place
- * lets one `env` from the model print the token. The clients already hold what
- * they need from spawn time; nothing else reads this variable.
+ * Read the server list off the inherited pipe on `fd` and CONSUME it.
  *
- * What this does NOT do is hide the value from a process that reads the parent's
- * environment directly: `delete` removes the key from this process's own copy,
- * while the kernel keeps the copy this process was started with, so
- * `ps eww $PPID` on macOS and `/proc/$PPID/environ` on Linux still show it to a
- * same-user child. This closes the accidental vector, not a determined one.
+ * The list carries every server's substituted secrets — a stdio server's env and
+ * an HTTP server's `Authorization` header, the seat's bearer token among them —
+ * and pi's `bash` tool spawns with `{ ...process.env }` (pi's getShellEnv), so it
+ * has to arrive by a channel pi's children do not inherit and must not outlive
+ * the read. It arrives here as fd 3: a pipe the adapter writes the JSON into and
+ * ends at spawn (pi.js runPi). This reads it to EOF and closes the descriptor.
+ *
+ * WHY NOT THE ENVIRONMENT, which is what this replaced: deleting the variable
+ * scrubbed Node's copy only, while the kernel keeps the environment this process
+ * was STARTED with, so a same-user child still read the token back with
+ * `ps eww $PPID` on macOS and `/proc/$PPID/environ` on Linux. Unsetting it at
+ * spawn cannot help either, because this runs inside the pi process that holds
+ * it. WHY NOT a 0600 file the bridge unlinks on load: the mode protects nothing
+ * against a same-user reader, and that shape needs both the unlink and a close
+ * to leave no window, since `/proc/<pid>/fd` on Linux still reaches an unlinked
+ * inode. A pipe has neither a path nor a stored copy.
+ *
+ * THE READ IS WHAT REMOVES THE SECRET, not the close: a pipe is consumed, so a
+ * second reader gets nothing. Measured against pi 0.84.1 — after a read to EOF
+ * a second read of the same descriptor returned zero bytes, while a 5-byte
+ * partial read left the remainder readable. Closing afterwards is hygiene.
+ *
+ * Two further measurements this rests on, both against pi 0.84.1: pi does not
+ * close inherited descriptors before loading extensions, so fd 3 is still open
+ * here (this runs at extension load, before the first model turn — and before
+ * any bash tool can run); and pi's own spawns (`dist/core/tools/bash.js`,
+ * `dist/core/exec.js`) pass a THREE-element stdio list, so a shell tool child
+ * does not inherit fd 3 at all.
+ *
+ * An unreadable descriptor yields no servers rather than throwing: a seat whose
+ * bridge cannot read its list should run without Commonly tools, not fail to
+ * start. The bridge logs that empty result (pi-commonly-mcp.mjs).
+ *
+ * The descriptor is closed only after a successful read, and that is not
+ * tidiness: on macOS, `closeSync` on the descriptor Node opens for an `'ignore'`
+ * stdio entry aborts the process — measured 2026-09-19, Node 20 — with
+ * `Assertion failed: (errno == EINTR), function uv__io_poll, file kqueue.c`,
+ * where the read itself had already failed harmlessly with `ENXIO`. A close in
+ * `finally` therefore turns "no channel" into a SIGABRT in the seat.
  */
-export const takeServers = (env = process.env) => {
-  const servers = readServers(env.COMMONLY_PI_MCP);
-  delete env.COMMONLY_PI_MCP;
-  return servers;
+export const takeServers = (fd = 3) => {
+  let raw = null;
+  try {
+    raw = readFileSync(fd, 'utf8');
+  } catch {
+    // Nothing to close: the read failed, so this was not a descriptor we consumed.
+    return [];
+  }
+  try { closeSync(fd); } catch { /* already closed */ }
+  return readServers(raw);
 };
 
 /**

package/src/lib/adapters/pi.js

@@ -110,15 +110,13 @@ const originOf = (value) => {
  * is a Streamable HTTP server (`agentBinding.ts` grantBrokerServer), so before
  * this pi dropped the one entry that carries a grant to a seat, silently.
  * Filling the headers here reuses the same substitution as the stdio env, and
- * the result rides in COMMONLY_PI_MCP — which the bridge removes from its own
- * process environment at load (see takeServers). That closes the direct vector
- * (pi's `bash` spawns with `{ ...process.env }`, so a bare `env` used to print
- * the token); it is not a secrecy boundary, because deleting the variable
- * scrubs Node's copy and not the kernel's — a same-user child of the bridge can
- * still read this process's environment via `ps eww` / `/proc/$PPID/environ`.
- * The durable fix is to hand the list over a 0600 file the bridge unlinks on
- * load, which is a row against this env channel, not against this PR (Vera,
- * Connectors).
+ * the result is written into pi's fd 3 at spawn — a pipe the bridge reads to EOF
+ * and closes (see takeServers), never the child's environment and never argv. The
+ * environment is not usable for this: the kernel keeps the copy the process was
+ * started with, so a same-user child could read the token back with
+ * `ps eww $PPID` / `/proc/$PPID/environ` even after the bridge deleted its own
+ * copy — which is what the previous channel did, and the row this closes
+ * (Vera, Connectors).
  *
  * WHICH shape an entry becomes is decided by `transport` — the same field, read
  * with the same default and the same exact comparison the daemon's
@@ -314,11 +312,24 @@ export const extractReply = (stdout) => {
   return { text, sawAssistant, errors };
 };
 
-const runPi = ({ args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
+const runPi = ({ args, cwd, env, payload, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
   let stdout = '';
   let stderr = '';
   let timedOut = false;
-  const proc = spawnImpl('pi', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+  // fd 3 carries the MCP server list, so the 4th pipe exists exactly when there
+  // is a list to hand over. The bridge reads it at extension load (takeServers).
+  const withList = typeof payload === 'string';
+  const proc = spawnImpl('pi', args, { cwd, env, stdio: withList ? ['ignore', 'pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'] });
+  if (withList) {
+    const channel = proc.stdio && proc.stdio[3];
+    // A missing pipe is an invariant break, not a degraded mode: the bridge would
+    // read EBADF and the seat would silently have no commonly_* tools.
+    if (!channel) { reject(new Error('pi adapter: no fd 3 pipe to carry the MCP server list')); return; }
+    // The child may exit before draining; that surfaces on 'close', so a write
+    // error here must not become an unhandled error event.
+    channel.on('error', () => {});
+    channel.end(payload);
+  }
   const timer = setTimeout(() => { timedOut = true; proc.kill('SIGTERM'); }, timeoutMs);
   proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
   proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
@@ -378,7 +389,6 @@ export default {
       ...baseEnv,
       PI_CODING_AGENT_DIR: agentDir,
       PI_SKIP_VERSION_CHECK: '1',
-      ...(servers.length ? { COMMONLY_PI_MCP: JSON.stringify(servers) } : {}),
     };
     const args = buildArgs({
       prompt: fullPrompt, provider: provider.name, model, thinking, sessionId, isResume, sessionDir,
@@ -389,6 +399,7 @@ export default {
       args,
       cwd: ctx.cwd,
       env: childEnv,
+      payload: servers.length ? JSON.stringify(servers) : undefined,
       timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
       spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
     });

package/src/lib/daemon-supervisor.js

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from 'node:util';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve as pathResolve } from 'node:path';
+import { auditDeclaredMcp, installedStdioEntries } from './declared-mcp-guard.js';
 
 import { seatBaseline } from './default-environment.js';
 
@@ -148,7 +149,23 @@ export const createDaemonSupervisor = ({
     return Object.keys(fallback).length ? { value: fallback, declared: false } : null;
   };
 
-  // Ensure ~/.commonly/tokens/<name>.json exists so `agent run` can boot.
+  // A declared environment runs on THIS machine as the operator. Refuse any
+  // declared stdio command that is not the shipped commonly MCP server or one
+  // the operator already installed here, and any http server that would be
+  // handed the seat token off the instance's origin. Refusal keeps the current
+  // seat (or skips the mint) and says which server was kept off the machine;
+  // it never adopts a partial environment.
+  const admitDeclared = (row, environment, existing) => {
+    const audit = auditDeclaredMcp(environment, {
+      instanceUrl: existing?.instanceUrl || record.instanceUrl,
+      allowedStdioEntries: installedStdioEntries(existing),
+    });
+    if (audit.ok) return true;
+    log(`[${row.agentName}] refusing the declared environment — it would not stay on this machine's terms:`);
+    for (const refusal of audit.refusals) log(`[${row.agentName}]   ${refusal}`);
+    return false;
+  };
+
   // The mint refuses to clobber an existing token (409 token_exists); the
   // binding to THIS machine is the owner's explicit takeover choice (D3), so
   // that refusal is answered with rotate:true — loudly.
@@ -162,6 +179,7 @@ export const createDaemonSupervisor = ({
       // once at boot). A row with NO declared model leaves the record alone —
       // never strip an operator's hand-set environment.
       const wanted = environmentFor(row);
+      if (wanted?.declared && !admitDeclared(row, wanted.value, existing)) return false;
       const declaredAdapter = row.runtime && typeof row.runtime === 'object'
         && typeof row.runtime.adapter === 'string'
         ? row.runtime.adapter.trim().toLowerCase()
@@ -259,6 +277,8 @@ export const createDaemonSupervisor = ({
         return false;
       }
     }
+    const declaredAtMint = environmentFor(row);
+    if (declaredAtMint?.declared && !admitDeclared(row, declaredAtMint.value, null)) return false;
     const body = { agentName: row.agentName, instanceId: row.instanceId };
     let minted;
     try {

package/src/lib/declared-mcp-guard.js

@@ -0,0 +1,179 @@
+/**
+ * Guard for a server-declared `environment.mcp` before the daemon adopts it.
+ *
+ * The daemon projects `AgentInstallation.config.environment` onto the OWNER's
+ * machine: every declared stdio server is spawned as the operator, and every
+ * declared http server is handed the seat token wherever the declaration puts
+ * the `${COMMONLY_AGENT_TOKEN}` placeholder. The registry PATCH that writes
+ * that declaration was pod-member gated (Vera, Connectors 69500, 2026-09-18),
+ * so a plain member could run a command on the owner's laptop or ship the
+ * token to a host they control. The server fix is owner/admin gating; this is
+ * the daemon's own layer, which must hold even if the server is wrong again.
+ *
+ * Two rules, both fail-closed:
+ *   stdio — the ENTRY must be the shipped commonly MCP server — command
+ *           `npx -y @commonlyai/mcp@<tag>`, env limited to the two canonical
+ *           placeholders, no args/cwd — or equal, as a whole entry, to one
+ *           the operator already installed by hand in the local token record.
+ *           Command alone is not enough: the shipped command with
+ *           `NODE_OPTIONS=--import=data:…` executes code, with
+ *           `npm_config_registry` fetches the package from an attacker, and
+ *           with a literal `COMMONLY_API_URL=https://attacker…` posts the
+ *           token there (sprint-review, Sharpen 69526/69534).
+ *   http  — the url, with ONLY the two instance placeholders resolved and
+ *           nothing else expanded, must parse to the instance's own origin
+ *           (scheme + host + port). The grant broker declares
+ *           `${COMMONLY_API_URL}/api/mcp/grants/…`, so it passes.
+ * The rule is origin-based, not placeholder-based, because the claude CLI
+ * expands `${VAR}` and `${VAR:-default}` in url and headers from its own
+ * environment: `?t=${COMMONLY_AGENT_TOKEN:-}` is not the literal placeholder
+ * and still becomes the token, and outside the public sandbox that
+ * environment is the operator's, so `?k=${GITHUB_TOKEN}` leaks too (Vera,
+ * Connectors 69519). So any `${` other than the three known placeholders,
+ * anywhere in an entry — url, headers, command, env — is refused outright.
+ */
+
+const URL_PLACEHOLDERS = ['${COMMONLY_API_URL}', '${COMMONLY_INSTANCE_URL}'];
+const KNOWN_PLACEHOLDERS = [...URL_PLACEHOLDERS, '${COMMONLY_AGENT_TOKEN}'];
+const SHIPPED_PACKAGE = /^@commonlyai\/mcp(@[A-Za-z0-9._-]+)?$/;
+
+export const isShippedCommonlyMcpCommand = (command) => (
+  Array.isArray(command)
+  && command.length === 3
+  && command[0] === 'npx'
+  && command[1] === '-y'
+  && typeof command[2] === 'string'
+  && SHIPPED_PACKAGE.test(command[2])
+);
+
+const CANONICAL_STDIO_ENV = {
+  COMMONLY_API_URL: '${COMMONLY_API_URL}',
+  COMMONLY_AGENT_TOKEN: '${COMMONLY_AGENT_TOKEN}',
+};
+
+// The execution-relevant shape of a stdio entry: everything that decides what
+// runs and with what. `name` and `transport` are identity, not execution.
+const executionShape = (server) => JSON.stringify({
+  command: Array.isArray(server.command) ? server.command : null,
+  args: Array.isArray(server.args) && server.args.length ? server.args : null,
+  cwd: typeof server.cwd === 'string' ? server.cwd : null,
+  env: server.env && typeof server.env === 'object'
+    ? Object.fromEntries(Object.entries(server.env).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+    : null,
+});
+
+// The shipped server exactly: its command, only its own env keys at their
+// canonical placeholder values, nothing else that changes what executes.
+export const isShippedCommonlyMcpEntry = (server) => {
+  if (!server || typeof server !== 'object') return false;
+  if (!isShippedCommonlyMcpCommand(server.command)) return false;
+  if (Array.isArray(server.args) && server.args.length) return false;
+  if (server.cwd !== undefined) return false;
+  const env = server.env && typeof server.env === 'object' ? server.env : {};
+  return Object.entries(env).every(([key, value]) => CANONICAL_STDIO_ENV[key] === value);
+};
+
+// True when a string still contains `${` after the known placeholders are
+// removed — a `${VAR}`, `${VAR:-default}` or any other expansion the CLI
+// would resolve from an environment this declaration does not own.
+const hasForeignExpansion = (value) => {
+  if (typeof value !== 'string') return false;
+  let rest = value;
+  for (const placeholder of KNOWN_PLACEHOLDERS) rest = rest.split(placeholder).join('');
+  return rest.includes('${');
+};
+
+const stringsOf = (server) => {
+  const out = [];
+  if (typeof server.url === 'string') out.push(server.url);
+  for (const bag of [server.headers, server.env]) {
+    if (bag && typeof bag === 'object') out.push(...Object.values(bag));
+  }
+  if (Array.isArray(server.command)) out.push(...server.command);
+  if (Array.isArray(server.args)) out.push(...server.args);
+  return out.filter((v) => typeof v === 'string');
+};
+
+const originOf = (url, instanceUrl) => {
+  let expanded = String(url);
+  for (const placeholder of URL_PLACEHOLDERS) expanded = expanded.split(placeholder).join(instanceUrl);
+  try {
+    return new URL(expanded).origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * @returns {{ ok: boolean, refusals: string[] }} — one refusal line per
+ * offending server, naming it, so the daemon log says exactly what was kept
+ * off the machine.
+ */
+export const auditDeclaredMcp = (environment, { instanceUrl, allowedStdioEntries = [] } = {}) => {
+  const refusals = [];
+  const servers = environment && typeof environment === 'object' && Array.isArray(environment.mcp)
+    ? environment.mcp : [];
+  let instanceOrigin = null;
+  try {
+    instanceOrigin = new URL(instanceUrl).origin;
+  } catch {
+    instanceOrigin = null;
+  }
+
+  servers.forEach((server, index) => {
+    if (!server || typeof server !== 'object') {
+      refusals.push(`mcp[${index}] is not an object`);
+      return;
+    }
+    const name = typeof server.name === 'string' && server.name ? server.name : `mcp[${index}]`;
+    const transport = server.transport || 'stdio';
+    // One shape per entry. The adapters classified by which field was present,
+    // so `{transport:'http', url:<instance>, command:['sh','-c',…]}` passed an
+    // origin check here and ran as stdio there with the token substituted
+    // (#1764 fixes the adapters; the guard refuses the shape outright).
+    if (server.command !== undefined && server.url !== undefined) {
+      refusals.push(`'${name}': declares both a command and a url; one entry is one transport`);
+      return;
+    }
+    if (transport === 'stdio' && server.url !== undefined) {
+      refusals.push(`'${name}': stdio entry carries a url`);
+      return;
+    }
+    if ((transport === 'http' || transport === 'sse') && server.command !== undefined) {
+      refusals.push(`'${name}': ${transport} entry carries a command`);
+      return;
+    }
+    const foreign = stringsOf(server).find(hasForeignExpansion);
+    if (foreign !== undefined) {
+      refusals.push(`'${name}': ${JSON.stringify(foreign)} contains an expansion other than the instance placeholders; the CLI would resolve it from this machine's environment`);
+      return;
+    }
+    if (transport === 'stdio') {
+      if (isShippedCommonlyMcpEntry(server)) return;
+      const shape = executionShape(server);
+      if (allowedStdioEntries.some((allowed) => executionShape(allowed) === shape)) return;
+      const why = isShippedCommonlyMcpCommand(server.command)
+        ? `carries env/args/cwd beyond the shipped server's own (${Object.keys(server.env || {}).filter((k) => CANONICAL_STDIO_ENV[k] !== server.env[k]).join(', ') || 'args/cwd'})`
+        : `command ${JSON.stringify(server.command)} is not the shipped commonly MCP server`;
+      refusals.push(`'${name}': declared stdio entry ${why}, and no entry installed on this machine matches it as a whole`);
+      return;
+    }
+    if (transport === 'http' || transport === 'sse') {
+      const origin = originOf(server.url, instanceUrl);
+      if (origin && instanceOrigin && origin === instanceOrigin) return;
+      refusals.push(`'${name}': ${transport} server ${JSON.stringify(server.url)} resolves to origin ${origin || '(unparseable)'}, not this instance (${instanceOrigin || instanceUrl}); a declared http server may only be the instance itself`);
+      return;
+    }
+    refusals.push(`'${name}': unknown transport ${JSON.stringify(transport)}`);
+  });
+
+  return { ok: refusals.length === 0, refusals };
+};
+
+/** The stdio entries an operator has already placed in a local token record. */
+export const installedStdioEntries = (record) => (
+  Array.isArray(record?.environment?.mcp)
+    ? record.environment.mcp
+      .filter((s) => s && typeof s === 'object' && (s.transport || 'stdio') === 'stdio' && Array.isArray(s.command))
+    : []
+);