@commonlyai/cli 0.1.220 → 0.1.222

package/package.json

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

package/src/commands/inbox.js

@@ -188,22 +188,58 @@ export const runInboxAck = async (itemId, opts = {}, deps = {}) => {
   }
 };
 
+// `value` is either a 1-based option index (position in the decision's options,
+// shown on refusal) or an option label. The server stores whatever string it is sent, so
+// the label is resolved here against the open queue and only the label is posted:
+// a bare "2" recorded in the ruling would mean nothing to anyone reading it later.
+export const resolveDecisionChoice = (options, value) => {
+  const choices = (Array.isArray(options) ? options : [])
+    .map((option) => String(option?.label ?? '').trim())
+    .filter(Boolean);
+  const listing = choices.map((label, i) => `  ${i + 1}. ${label}`).join('\n');
+  const raw = String(value).trim();
+  if (/^\d+$/.test(raw)) {
+    const index = Number(raw);
+    const labelled = choices.findIndex((label) => label === raw);
+    // A digit-only label is also a position in the list. When the two point at
+    // different options, neither reading is safe to guess, so refuse.
+    if (labelled !== -1 && labelled !== index - 1) {
+      throw new InboxRefusal(`"${raw}" is both option ${labelled + 1}'s label and position ${raw}; refusing to guess. Choose by position (1-${choices.length}) or by a label that is not a number:\n${listing}`);
+    }
+    if (index < 1 || index > choices.length) {
+      throw new InboxRefusal(`option ${raw} is out of range; choose 1-${choices.length}:\n${listing}`);
+    }
+    return choices[index - 1];
+  }
+  const match = choices.find((label) => label.toLocaleLowerCase() === raw.toLocaleLowerCase());
+  if (!match) throw new InboxRefusal(`"${raw}" is not an option; the options are:\n${listing}`);
+  return match;
+};
+
 export const runInboxChoose = async (decisionId, value, opts = {}, deps = {}) => {
   const {
     env = process.env, fetchImpl = fetch, log = console.log, error = console.error, sleep = undefined,
   } = deps;
   try {
-    if (!decisionId) throw new InboxRefusal('a decision id is required: commonly inbox choose <decisionId> <value>');
-    if (value === undefined) throw new InboxRefusal('a value is required: commonly inbox choose <decisionId> <value>');
+    if (!decisionId) throw new InboxRefusal('a decision id is required: commonly inbox choose <decisionId> <n|label>');
+    if (value === undefined) throw new InboxRefusal('a value is required: commonly inbox choose <decisionId> <n|label>');
     const {
       baseUrl, request, account,
     } = await connect(opts, { env, fetchImpl, sleep });
     log(formatAccountLine({ account, baseUrl }));
+    // The options live on the open queue, not on the decision route, so the
+    // choice is resolved against the same queue this account would see in `list`.
+    const { items } = await fetchQueue(request);
+    const open = items.find((item) => String(item?.id) === String(decisionId) && item?.kind === 'decision');
+    if (!open) {
+      throw new InboxRefusal(`decision ${decisionId} is not open on this account's queue; nothing to choose`);
+    }
+    const label = resolveDecisionChoice(open.options, value);
     const result = await request(`/api/activity/decisions/${encodeURIComponent(decisionId)}/choose`, {
       method: 'POST',
-      body: { value },
+      body: { value: label },
     });
-    log(`chose ${decisionId} = ${value}`);
+    log(`chose ${decisionId} = ${label}`);
     log(`-> ${JSON.stringify(result)}`);
     return 0;
   } catch (err) {
@@ -237,7 +273,8 @@ Examples:
   $ commonly inbox list --cursor-file ~/.commonly/inbox/connector-ops.cursor   # only what is new
   $ commonly inbox list --cursor-file ~/.commonly/inbox/c.cursor --window 300  # widen the re-read to 5m
   $ commonly inbox ack <attentionItemId>
-  $ commonly inbox choose <decisionId> 2
+  $ commonly inbox choose <decisionId> 2          # second option of the card, by position
+  $ commonly inbox choose <decisionId> "Ship it"  # or by its label
 
 Cost: with no cursor, \`list\` reads the WHOLE queue, one request per 50 items —
 550 open items is 11 requests. /api/activity is limited to 60 a minute **keyed on
@@ -285,7 +322,7 @@ their attention as runtime events, not from this queue.
 
   inbox
     .command('choose <decisionId> <value>')
-    .description('Rule a decision card (the source= id from `list`)')
+    .description('Rule a decision card (the source= id from `list`). <value> is an option number (1-based) or its label')
     .option('--token-file <path>', INBOX_TOKEN_HELP)
     .option('--instance <url>', 'Target Commonly instance')
     .action(async (decisionId, value, opts) => { process.exit(await runInboxChoose(decisionId, value, opts)); });

package/src/lib/adapters/claude.js

@@ -97,6 +97,8 @@ import { claudeConfigDirFor, claudeContextTokens, claudeTranscriptPath } from '.
 import { skillsAsText } from '../skill-prompt.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 import { PUBLIC_WITHHELD_TOOLS } from '../public-withheld-tools.js';
+import { isShippedCommonlyMcpCommand } from '../declared-mcp-guard.js';
+import { isAnswerableToolError, PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE } from '../public-tool-error.js';
 
 // See codex.js for the rationale on bumping the default + env override.
 // Keeping both adapters in lockstep so any wrapper agent runtime has the
@@ -533,6 +535,87 @@ export const claudeResultText = (stdout, { credentials = [] } = {}) => {
     .trim();
 };
 
+// TASK-256: what a public seat's own stream says about its Commonly MCP server.
+// Claude Code reports each server's state in the init event (`connected` or
+// `failed`), and a failed tool call as a `tool_result` with `is_error: true`
+// whose content is the server's text, the shipped MCP's `{status, body,
+// message}` JSON (both measured on Claude Code 2.1.314; `-p` waits for a slow
+// server, so init reports it connected rather than pending). Ready is a positive
+// witness: `connected` in init, or `pending` followed by a Commonly call that
+// returned, since a server may finish starting during the turn. A stream with no
+// init event, or with a Commonly server in any other state, never showed the
+// server working, so the turn is withheld. A failed
+// Commonly call withholds it unless `isAnswerableToolError` names an answer the
+// person can be given (the predicate the OpenCode adapter uses). Only servers
+// that run the shipped Commonly MCP count. Returns the failure, or null.
+const toolResultText = (content) => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((part) => part?.type === 'text').map((part) => String(part.text ?? '')).join('');
+};
+
+export const claudePublicMcpWitness = (stdout, mcpServers) => {
+  const names = (Array.isArray(mcpServers) ? mcpServers : [])
+    .filter((server) => server?.name && isShippedCommonlyMcpCommand(server.command))
+    .map((server) => String(server.name));
+  if (!names.length) return null;
+  const events = String(stdout || '').split('\n').map(parseEvent).filter(Boolean);
+  const init = events.find((event) => event.type === 'system' && event.subtype === 'init');
+  const servers = Array.isArray(init?.mcp_servers) ? init.mcp_servers : [];
+  const toolNames = new Map();
+  for (const event of events) {
+    if (event.type !== 'assistant') continue;
+    for (const block of event.message?.content || []) {
+      if (block?.type === 'tool_use' && block.id) toolNames.set(block.id, String(block.name || ''));
+    }
+  }
+  const results = events
+    .filter((event) => event.type === 'user' && Array.isArray(event.message?.content))
+    .flatMap((event) => event.message.content)
+    .filter((block) => block?.type === 'tool_result')
+    .map((block) => ({ block, tool: toolNames.get(block.tool_use_id) || '' }));
+  // Init names a server as declared; tool names carry it with every character
+  // outside [A-Za-z0-9_-] turned to `_` (`commonly.me` → `mcp__commonly_me__`,
+  // measured on 2.1.314).
+  const prefixOf = (name) => `mcp__${name.replace(/[^A-Za-z0-9_-]/g, '_')}__`;
+  for (const name of names) {
+    const status = servers.find((server) => server?.name === name)?.status;
+    const returned = status === 'pending'
+      && results.some(({ block, tool }) => block.is_error !== true && tool.startsWith(prefixOf(name)));
+    if (status !== 'connected' && !returned) {
+      return { code: PUBLIC_MCP_NOT_READY_CODE, tool: name, error: init ? `status ${status || 'absent'}` : 'no init event' };
+    }
+  }
+  const prefixes = names.map(prefixOf);
+  for (const { block, tool } of results) {
+    if (block.is_error !== true || !prefixes.some((prefix) => tool.startsWith(prefix))) continue;
+    const error = toolResultText(block.content);
+    if (!isAnswerableToolError(error)) return { code: PUBLIC_TOOL_FAILED_CODE, tool, error };
+  }
+  return null;
+};
+
+const publicWitnessError = ({ code, tool, error }) => {
+  const reason = String(error).replace(/\s+/g, ' ').slice(0, 160) || '(empty error)';
+  const what = code === PUBLIC_MCP_NOT_READY_CODE
+    ? `Commonly MCP server ${tool} was not shown connected`
+    : `Commonly tool ${tool} failed in a way the model must not narrate`;
+  const failure = new Error(
+    `public seat withheld this turn's reply: ${what} (${reason}), so nothing was posted and the event stays unacked for retry`,
+  );
+  failure.code = code;
+  return failure;
+};
+
+// The reply a turn posts. A public seat's turn is witnessed first (TASK-256).
+const turnReply = (stdout, { credentials, publicMcp }) => {
+  if (publicMcp) {
+    const failure = claudePublicMcpWitness(stdout, publicMcp);
+    if (failure) throw publicWitnessError(failure);
+  }
+  return claudeResultText(stdout, { credentials });
+};
+
 // The failure tail for a non-zero exit. Stream events are mostly system init
 // and status lines, which would push the terminal error past the 2000-char cut,
 // so keep the result text, or the lines that are not system or stream events.
@@ -1191,6 +1274,10 @@ export default {
     // undefined and '' as absence itself; it does not need a guard, it needs
     // the value.
     const publicTrust = isConfinedTrust(ctx.environment?.sandbox?.trust);
+    // Only a stranger-facing seat is witnessed (TASK-256). A workspace seat is
+    // confined too, but it answers its own team, and an outage it narrates
+    // there is a signal, not a leak.
+    const witnessedMcp = ctx.environment?.sandbox?.trust === 'public' ? ctx.environment?.mcp : null;
     const workCues = publicTrust ? [] : WORK_CUES;
     const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
       freshSession: !isResume,
@@ -1330,12 +1417,16 @@ export default {
       const contextTokens = claudeContextTokens({
         cwd: physicalPath(ctx.cwd), sessionId, configDir: claudeConfigDirFor({ ...env, HOME: childHome || env?.HOME }),
       });
-      return { text: claudeResultText(stdout, { credentials: spawnCredentials(spawnCtx) }), newSessionId: sessionId, contextTokens };
+      return {
+        text: turnReply(stdout, { credentials: spawnCredentials(spawnCtx), publicMcp: witnessedMcp }),
+        newSessionId: sessionId,
+        contextTokens,
+      };
     } catch (err) {
       // A public seat's refusal is not a session-store failure, whatever its
       // message happens to contain: it must reach the run loop, never the
       // fresh-session retry below (#2247).
-      if (err?.code === PUBLIC_MCP_UNAVAILABLE_CODE) throw err;
+      if ([PUBLIC_MCP_UNAVAILABLE_CODE, PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE].includes(err?.code)) throw err;
       // Self-heal against a corrupted session store. If the persisted id is
       // already in use (or claude has forgotten about it), discard it and
       // restart the turn with a fresh UUID. Without this, a single bad
@@ -1393,7 +1484,11 @@ export default {
           cwd: physicalPath(ctx.cwd), sessionId: freshId,
           configDir: claudeConfigDirFor({ ...retry.env, HOME: retry.childHome || retry.env?.HOME }),
         });
-        return { text: claudeResultText(stdout, { credentials: spawnCredentials(retryCtx) }), newSessionId: freshId, contextTokens };
+        return {
+          text: turnReply(stdout, { credentials: spawnCredentials(retryCtx), publicMcp: witnessedMcp }),
+          newSessionId: freshId,
+          contextTokens,
+        };
       }
       throw err;
     } finally {

package/src/lib/adapters/opencode.js

@@ -56,7 +56,7 @@ import { wrapArgvWithSeatbelt } from '../sandbox/seatbelt.js';
 import { resolvePublicSandboxMode } from '../sandbox/mode.js';
 import { resolveProviderKeyFile, startProviderProxy } from '../provider-proxy.js';
 import { isShippedCommonlyMcpCommand } from '../declared-mcp-guard.js';
-import { isAnswerableToolError } from '../public-tool-error.js';
+import { isAnswerableToolError, PUBLIC_TOOL_FAILED_CODE } from '../public-tool-error.js';
 import { startInstanceProxy } from '../instance-proxy.js';
 import { PUBLIC_WITHHELD_TOOLS } from '../public-withheld-tools.js';
 
@@ -390,7 +390,7 @@ const makeEventParser = () => {
 // stays beside the adapter-agnostic readiness witness (TASK-256): it sees the
 // runtime's own view of each call, and the witness sees a server that never
 // started, so each catches what the other cannot.
-export const PUBLIC_TOOL_FAILED_CODE = 'public_tool_failed';
+export { PUBLIC_TOOL_FAILED_CODE };
 
 export const publicToolFailure = (toolErrors, mcpServers) => {
   const prefixes = (Array.isArray(mcpServers) ? mcpServers : [])

package/src/lib/public-tool-error.js

@@ -33,6 +33,12 @@
 
 export const ANSWERABLE_API_STATUSES = new Set([400, 403, 404, 409, 410, 413, 422]);
 
+// The two ways a public turn is withheld over its Commonly MCP server: a tool
+// call failed in a way the model must not narrate, or the server was never shown
+// working. Both leave the event unacked for retry.
+export const PUBLIC_TOOL_FAILED_CODE = 'public_tool_failed';
+export const PUBLIC_MCP_NOT_READY_CODE = 'public_mcp_not_ready';
+
 const INVALID_ARGUMENTS_RE = /^The \S+ tool was called with invalid arguments: /;
 
 const parsePayload = (text) => {

package/src/lib/spawn-retry.js

@@ -7,6 +7,8 @@
  * retry policy here so every adapter gets the same bounded behavior.
  */
 
+import { PUBLIC_MCP_NOT_READY_CODE, PUBLIC_TOOL_FAILED_CODE } from './public-tool-error.js';
+
 export const SPAWN_FAILURE_CLASS = Object.freeze({
   // The provider refused the request's CONTENT. Re-sending the same content
   // can only be refused again, so this class is never retried: the run loop
@@ -121,6 +123,15 @@ const errorText = (error) => [
 
 export const classifySpawnFailure = (error) => {
   const text = errorText(error);
+  // A public seat's withheld turn (TASK-256) quotes the tool's own error, which
+  // is vendor text: the code decides, so the event stays unacked for retry and
+  // is never acked as refused or parked behind a quota or configuration
+  // cooldown by that text. A throttle keeps its backoff, which also retries.
+  if (error?.code === PUBLIC_TOOL_FAILED_CODE || error?.code === PUBLIC_MCP_NOT_READY_CODE) {
+    return error?.status === 429 || RATE_LIMIT_RE.test(text)
+      ? SPAWN_FAILURE_CLASS.RATE_LIMIT
+      : SPAWN_FAILURE_CLASS.RUNTIME;
+  }
   // First: the refusal text carries none of the words below today, but a
   // refusal must never be read as a transient condition and retried.
   if (CONTENT_REFUSED_RE.test(text)) return SPAWN_FAILURE_CLASS.CONTENT_REFUSED;