@commonlyai/cli 0.1.64 → 0.1.66

package/package.json

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

package/src/commands/agent.js

@@ -42,6 +42,7 @@ import {
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
+import { describeUpstreamRefusal } from '../lib/upstream-refusal.js';
 import {
   DEFAULT_HOOK_TIMEOUT_MS,
   clampHookTimeoutMs,
@@ -1249,13 +1250,22 @@ export const performRun = ({
     const heartbeatControlReply = (event.type === 'heartbeat' || event.payload?.hasHeartbeat === true)
       && /^(HEARTBEAT_OK|HEARTBEAT_NOOP)$/i.test(replyText);
     const silentReply = !replyText || replyText === 'NO_REPLY' || heartbeatControlReply;
+    // A refused model route is not a silent turn. pi reports the refusal on its
+    // own JSON stream and exits 0 with no text, so before this the seat log read
+    // `no wrapper-post (empty output)` and the cause — a 429 budget message — was
+    // nowhere (TASK-096; two and a half days of this on one seat).
+    const upstream = result.upstream || null;
     let delivered = agentPostedItself;
     let deliveryRefusal = null;
 
     if (event.type === 'agent.ask') {
       if (silentReply) {
         const reason = heartbeatControlReply ? replyText : (replyText || 'empty output');
-        log(`[${event.type}] no private response (${reason})`);
+        // The same naming rule as the chat path below: an ask that went
+        // unanswered because the route refused must not read as the agent
+        // having nothing to say.
+        if (upstream) log(`[${event.type}] ${describeUpstreamRefusal(upstream)} — no private response`);
+        else log(`[${event.type}] no private response (${reason})`);
       } else {
         try {
           await client.post(
@@ -1304,6 +1314,11 @@ export const performRun = ({
           + `(matched message ${suppressedBy.id} by ${suppressedBy.author} `
           + `via ${suppressedBy.basis})`,
         );
+      } else if (upstream) {
+        // The status is always named; the body only when the keep-list kept one.
+        // No retry is added: the adapter's own ladder has already run, and a
+        // refused route is refused on the next attempt too.
+        log(`[${event.type}] ${describeUpstreamRefusal(upstream)} — nothing posted this turn`);
       } else {
         log(`[${event.type}] no wrapper-post (${reason}) — nothing posted this turn`);
       }
@@ -1394,6 +1409,21 @@ export const performRun = ({
         },
       };
     }
+    // A refusal is not a decline. `no_action` with no reason means "the agent
+    // chose not to answer" and hands a human wake to one remaining listener;
+    // nothing about the agent's choice happened here — the model never ran — so
+    // say what did happen, and let the event close rather than fan a
+    // route-wide refusal out across the rest of the fleet.
+    if (!delivered && upstream) {
+      return {
+        outcome: 'no_action',
+        reason: `upstream-refused-${upstream.status}`,
+        details: {
+          status: upstream.status,
+          ...(upstream.detail ? { detail: upstream.detail } : {}),
+        },
+      };
+    }
     return { outcome: delivered ? 'posted' : 'no_action' };
   };
 

package/src/lib/adapters/pi.js

@@ -38,6 +38,10 @@ import { mkdir, readdir, writeFile } from 'fs/promises';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import {
+  readUpstreamRefusal,
+  spawnCredentials,
+} from '../upstream-refusal.js';
 import { buildMemoryPreamble } from '../memory-bridge.js';
 import { GRANT_BROKER_REFUSAL, isGrantBrokerUrl } from './pi-mcp-client.mjs';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
@@ -326,7 +330,7 @@ export const extractReply = (stdout) => {
   return { text, sawAssistant, errors };
 };
 
-const runPi = ({ args, cwd, env, payload, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
+const runPi = ({ args, cwd, env, payload, timeoutMs, credentials = [], spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
   let stdout = '';
   let stderr = '';
   let timedOut = false;
@@ -352,6 +356,11 @@ const runPi = ({ args, cwd, env, payload, timeoutMs, spawnImpl = childSpawn }) =
     clearTimeout(timer);
     if (timedOut) return reject(new Error(`pi timed out after ${timeoutMs}ms`));
     const reply = extractReply(stdout);
+    // A refused model route is NOT an error event: pi retries the ladder itself
+    // and exits 0 with no assistant text, which is why this read has to happen
+    // on the stream rather than on the exit code (TASK-096, measured 2026-09-22).
+    const upstream = readUpstreamRefusal(stdout, { credentials });
+    if (upstream) reply.upstream = upstream;
     if (code !== 0 && !reply.sawAssistant) {
       const tail = (reply.errors.join(' | ') || stderr).trim().slice(-600);
       return reject(new Error(`pi exited ${code}: ${tail}`));
@@ -383,6 +392,12 @@ export default {
     if (!baseEnv[provider.apiKeyEnv]) {
       throw new Error(`pi adapter: ${provider.apiKeyEnv} is not set — the seat's environment must carry the provider key (LiteLLM virtual key)`);
     }
+    // The values this spawn is handed, for the refusal log's exact-match check:
+    // the provider key the route authenticates with, and the seat credential the
+    // bridge carries. Snapshot them HERE — `withholdRuntimeCredential` removes
+    // the token from the child copy below, and after that there is nothing left
+    // to compare a refusal against.
+    const credentials = spawnCredentials(ctx, [provider.apiKeyEnv]);
 
     // Per-seat pi home: models.json holds the provider by env reference.
     const home = seatHome(ctx);
@@ -437,11 +452,13 @@ export default {
         env: childEnv,
         payload: servers.length ? JSON.stringify(servers) : undefined,
         timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        credentials,
         spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
       });
       // Empty text with a clean exit is a silent turn; the run loop treats it
-      // as NO_REPLY-shaped and re-delivers on its own rules.
-      return { text: reply.text, newSessionId: sessionId };
+      // as NO_REPLY-shaped and re-delivers on its own rules. Empty text that
+      // came with a refusal is named instead — see upstream-refusal.js.
+      return { text: reply.text, newSessionId: sessionId, upstream: reply.upstream ?? null };
     } finally {
       // Best effort: the bridge has already read what it needs by the time the
       // turn ends, and a token file that outlives its turn is a token file that

package/src/lib/credential-file.js

@@ -17,13 +17,15 @@
  * fixed path would widen the window to "since the first spawn" and would let two
  * concurrent seats share one credential by accident.
  *
+ * The caller names the root; this module never invents one, because the only
+ * root it could invent is a directory no adapter cleans up.
+ *
  * The reader side is `readToken` in `commonly-mcp/src/client.js`, which resolves
  * fd, then file, then environment — by declaration, and refuses to fall through
  * from a declared source that cannot be read.
  */
 import { chmodSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
 
 /** The variable a child reads to find the credential. Never carries the token. */
@@ -36,25 +38,37 @@ export const CREDENTIAL_FILE_VAR = 'COMMONLY_TOKEN_FILE';
  */
 export const CREDENTIAL_KEY = 'COMMONLY_AGENT_TOKEN';
 
-/** Default root: inside the CLI's own state directory, not a world-readable /tmp. */
-export const credentialRoot = () => join(homedir(), '.commonly', 'credentials');
-
 /**
- * Write `token` to a fresh 0600 file and return its path, or null when there is
- * no token to write (a seat bootstrapping without one).
+ * Write `token` to a fresh 0600 file under `root` and return its path, or null
+ * when there is no token to write (a seat bootstrapping without one).
+ *
+ * `root` is REQUIRED. It used to default to the CLI's own state directory, which
+ * meant a caller that forgot it wrote a live credential into
+ * `~/.commonly/credentials` — a directory no adapter cleans, because that is not
+ * where adapters put theirs. Measured 2026-09-20: 32 such directories on the
+ * fleet host, 24 of them written by this repo's own harnesses, all holding a
+ * seat credential. A missing root is now an error instead of a silent write into
+ * the operator's home. The token check stays first, so "no token, nothing
+ * written" remains true without a root.
  *
  * `fs` is injectable so tests can assert the mode and the path shape without
  * writing into the operator's home.
  */
 export const writeCredentialFile = (token, {
   agentName = 'agent',
-  root = credentialRoot(),
+  root,
   fs = { mkdirSync, writeFileSync, chmodSync, rmSync },
   now = () => Date.now(),
   random = () => randomBytes(4).toString('hex'),
 } = {}) => {
   const value = typeof token === 'string' ? token.trim() : '';
   if (!value) return null;
+  if (typeof root !== 'string' || !root.trim()) {
+    throw new Error(
+      'writeCredentialFile requires an explicit root: an omitted root used to fall back to '
+      + '~/.commonly/credentials, where nothing sweeps the credential files it writes',
+    );
+  }
   const dir = join(root, `${agentName}-${now()}-${random()}`);
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   const path = join(dir, 'token');

package/src/lib/mcp-credential-delivery.js

@@ -44,9 +44,20 @@ export const CREDENTIAL_FILE_PLACEHOLDER = '${COMMONLY_TOKEN_FILE}';
  * a field the adapter substitutes LITERALLY has no file channel, so `keepsValue`
  * is passed in by the adapter rather than inferred, and the spawn that keeps a
  * secret says so in its own warning.
+ *
+ * The PATH comes out too when there is no file for THIS spawn. The runtime
+ * environment is derived from `process.env`, so a launcher whose own process was
+ * spawned by another seat inherits that seat's `COMMONLY_TOKEN_FILE` and hands
+ * it to the runtime and every MCP child below it — a path to a credential this
+ * launcher did not mint. The value was already deleted here for that reason; the
+ * path is the same leak with a smaller blast radius.
  */
 export const withholdRuntimeCredential = (env, { credentialFile = null, keepsValue = false } = {}) => {
-  if (credentialFile) env[CREDENTIAL_FILE_VAR] = credentialFile;
+  if (credentialFile) {
+    env[CREDENTIAL_FILE_VAR] = credentialFile;
+  } else {
+    delete env[CREDENTIAL_FILE_VAR];
+  }
   if (!keepsValue) delete env[CREDENTIAL_KEY];
   return env;
 };

package/src/lib/upstream-refusal.js

@@ -0,0 +1,185 @@
+/**
+ * TASK-096 — name a refused model route, instead of reporting the silence it
+ * causes.
+ *
+ * Measured 2026-09-22 against pi 0.84.1 with a route answering 429 (the shape
+ * that made a seat look broken for two and a half days): pi runs its own retry
+ * ladder, reports the refusal on `message_end`/`auto_retry_end` JSON events, and
+ * EXITS 0 with no assistant text. `extractReply` in the pi adapter collected only
+ * `type: "error"` events — of which this produces none — so the wrapper logged
+ * `no wrapper-post (empty output)` and the cause sat unread in the stream.
+ *
+ * Two rules govern the text that reaches a seat log:
+ *
+ *  1. KEEP-LIST, not strip-list (Vera 70876, Wren 70877). A strip-list removes
+ *     only the shapes we thought of, and a 401 can echo the key back. So a body
+ *     contributes one NAMED field or nothing at all.
+ *  2. Exact-match refusal for credentials. If the kept text contains a value
+ *     this spawn was handed, the text is dropped — a known value, not a guessed
+ *     shape (Wren 70877).
+ */
+
+/** The kept detail is truncated, ellipsis included, to this many characters. */
+export const MAX_REFUSAL_DETAIL = 256;
+
+/**
+ * The status an adapter prefixes to its error text: `"429: {…}"` -> `429`.
+ * Null for anything that is not a 4xx/5xx, so a message that merely starts with
+ * a number ("4040 tokens over budget") is not read as a status.
+ *
+ * The separator pi uses is NOT fixed — measured 2026-09-22, the same pi 0.84.1
+ * emits `"429: {"message":…}"` for a JSON body and `"502 <html>…"` for an
+ * HTML one. Both forms are matched here; a parser that required the colon would
+ * have kept `502 <html>…` as the whole "body" and then dropped it as non-JSON,
+ * reporting the status alone with no sign that the body was never read.
+ */
+const STATUS_PREFIX = /^\s*(\d{3})(?!\d)\s*:?\s*/;
+
+export const statusFromError = (value) => {
+  const match = STATUS_PREFIX.exec(String(value ?? ''));
+  if (!match) return null;
+  const status = Number(match[1]);
+  return status >= 400 && status <= 599 ? status : null;
+};
+
+/**
+ * The body the adapter carried after its status prefix, or the whole text when
+ * there is no status to strip. `"429: {"message":"a: b"}"` -> `{"message":"a: b"}`;
+ * `"502 <html>"` -> `<html>`.
+ */
+export const bodyFromError = (value) => {
+  const text = String(value ?? '');
+  if (statusFromError(text) === null) return text.trim();
+  return text.replace(STATUS_PREFIX, '').trim();
+};
+
+/**
+ * Replace credential values this spawn was handed with a marker.
+ *
+ * This is the exact-match half, for text that is kept for its whole shape rather
+ * than filtered to one field — an adapter's stderr tail, say, whose diagnostic
+ * value is in the lines around the secret. Values shorter than eight characters
+ * are ignored: redacting a one-character "credential" would corrupt ordinary
+ * prose, and no issued credential is that short.
+ */
+export const redactKnownCredentials = (text, credentials = []) => {
+  let out = String(text ?? '');
+  for (const value of credentials) {
+    if (typeof value !== 'string' || value.length < 8) continue;
+    out = out.split(value).join('[redacted]');
+  }
+  return out;
+};
+
+/**
+ * The keep-list. Given the raw body an adapter captured, keep at most one named
+ * field of it and only when that field is a string:
+ *
+ *   `error.message` first (the OpenAI-shaped error), then a top-level `message`
+ *   (which is the shape LiteLLM's budget refusal actually uses — the motivating
+ *   case; a keep-list that kept only `error.message` would name the status and
+ *   still hide the budget line that started this row).
+ *
+ * Everything else — HTML, a non-JSON body, a JSON body with neither field, a
+ * body echoing a known credential — contributes nothing. Returns null rather
+ * than a partial guess.
+ */
+export const keptRefusalDetail = (raw, { credentials = [] } = {}) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(raw ?? ''));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+
+  const candidate = parsed?.error?.message ?? parsed?.message;
+  if (typeof candidate !== 'string') return null;
+
+  const text = candidate.replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+
+  const redacted = redactKnownCredentials(text, credentials);
+  // `[redacted]` appearing is the signal that the body echoed something this
+  // spawn was handed. The status is still worth keeping; the text is not.
+  if (redacted !== text) return null;
+
+  return text.length > MAX_REFUSAL_DETAIL
+    ? `${text.slice(0, MAX_REFUSAL_DETAIL - 1)}…`
+    : text;
+};
+
+/**
+ * Read a pi JSON stream and return the refusal it ended on, or null.
+ *
+ * `auto_retry_end` is the terminal word — it names the status and the body after
+ * the ladder has finished — so it wins over the per-attempt `message_end`
+ * events that precede it. A run that refused on its first attempt and never
+ * retried still reports through `message_end`.
+ */
+export const readUpstreamRefusal = (stdout, { credentials = [] } = {}) => {
+  let status = null;
+  let raw = null;
+
+  for (const line of String(stdout ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (event?.type === 'auto_retry_end' && event.success === false) {
+      const candidate = event.finalError ?? event.errorMessage;
+      const attemptStatus = statusFromError(candidate);
+      if (attemptStatus) {
+        status = attemptStatus;
+        raw = bodyFromError(candidate);
+      }
+      continue;
+    }
+
+    const message = event?.message;
+    if (
+      event?.type === 'message_end'
+      && message?.role === 'assistant'
+      && message.stopReason === 'error'
+      && status === null
+    ) {
+      const attemptStatus = statusFromError(message.errorMessage);
+      if (attemptStatus) {
+        status = attemptStatus;
+        raw = bodyFromError(message.errorMessage);
+      }
+    }
+  }
+
+  if (status === null) return null;
+  return { status, detail: keptRefusalDetail(raw, { credentials }) };
+};
+
+/**
+ * The seat-log clause. The status is always present; the detail only when the
+ * keep-list kept one. `grep 'upstream refused'` finds every refusal, which is
+ * the property the old `no wrapper-post (empty output)` line did not have.
+ */
+export const describeUpstreamRefusal = (refusal) => {
+  if (!refusal || typeof refusal.status !== 'number') return null;
+  return refusal.detail
+    ? `upstream refused ${refusal.status}: ${refusal.detail}`
+    : `upstream refused ${refusal.status}`;
+};
+
+/**
+ * The credential values this spawn was handed, for the exact-match check in
+ * `redactKnownCredentials`. `envNames` are the adapter's own provider keys; the
+ * caller supplies them because only the adapter knows which key its route uses.
+ */
+export const spawnCredentials = (ctx = {}, envNames = []) => {
+  const env = ctx.env || process.env || {};
+  return [
+    ctx.runtimeToken,
+    ...envNames.map((name) => env[name]),
+  ].filter((value) => typeof value === 'string' && value.length >= 8);
+};