@commonlyai/cli 0.1.202 → 0.1.204

package/assets/webhook-sdk/python/commonly.py

@@ -200,7 +200,8 @@ class Commonly:
                     if consecutive_auth_errors >= max_auth_errors:
                         print(
                             f"[commonly] runtime token rejected {consecutive_auth_errors}x in a row — exiting. "
-                            "The token is likely revoked; re-issue or uninstall the agent.",
+                            "Check COMMONLY_TOKEN: it must hold the bare cm_agent_... value, not the "
+                            "KEY=VALUE line from .commonly-env. If it is right, re-issue the token or uninstall the agent.",
                             flush=True,
                         )
                         return

package/package.json

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

package/src/commands/agent.js

@@ -80,6 +80,7 @@ import {
   readPodFocus,
 } from '../lib/pod-focus.js';
 import { claimReleaseFor, ackResultFor, EMPTY_OUTPUT } from '../lib/claim-outcome.js';
+import { createClaimedWorkGate } from '../lib/claimed-work-gate.js';
 import { prepareCommitAttribution } from '../lib/commit-attribution.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { resolvePublicSandboxMode } from '../lib/sandbox/mode.js';
@@ -1536,6 +1537,7 @@ export const performRun = ({
     warn: (message) => log(`cascade config: ${message}`),
   });
   const cascadeGovernor = createCascadeGovernor(cascadeSettings);
+  const claimedWorkGate = createClaimedWorkGate({ client });
   // Unconditional, because the only other cascade line on this path is the
   // warn callback above — which fires only when a value is BAD. Without this,
   // a seat running COMMONLY_CASCADE_CAP=8 logs exactly what a seat on the
@@ -1691,6 +1693,13 @@ export const performRun = ({
     // Recording a human trigger sets the streak to 0, so this call and the
     // completion-time one are idempotent with each other.
     if (trigger === 'human') cascadeGovernor.record(eventPodId, trigger);
+    // Defer-while-claimed (TASK-640), before the cascade check so a deferred
+    // broadcast spends none of the addressed grace.
+    if (await claimedWorkGate.shouldDefer(eventPodId, [{ event, trigger }])) {
+      log(`[${event.type}] holding a claimed row in pod ${eventPodId} — broadcast`
+        + (event?.payload?.messageId ? ` ${event.payload.messageId}` : '') + ' acked without a spawn');
+      return { outcome: 'no_action', reason: 'claimed-work', details: { messageId: event?.payload?.messageId || null } };
+    }
     const admission = cascadeGovernor.admit(eventPodId, trigger, event.type, event.payload);
     if (!admission.allowed) {
       // Name the MESSAGE, not just the pod. Without this the refusal is silent at
@@ -2743,6 +2752,17 @@ export const performRun = ({
     const trigger = triggers.includes('human') ? 'human'
       : (triggers.includes('agent') ? 'agent' : 'unknown');
     if (trigger === 'human') cascadeGovernor.record(eventPodId, trigger);
+    if (await claimedWorkGate.shouldDefer(eventPodId, wakingEntries.map((entry, index) => ({
+      event: entry.event, trigger: triggers[index],
+    })))) {
+      log(`[inbox.batch] holding a claimed row in pod ${eventPodId} — ${wakingEntries.length} broadcast`
+        + `${wakingEntries.length === 1 ? '' : 's'} acked without a spawn`);
+      // Digests are left as the cascade refusal leaves them: unread.
+      for (const entry of wakingEntries) {
+        entry.result = { outcome: 'no_action', reason: 'claimed-work', details: { messageId: entry.event.payload?.messageId || null } };
+      }
+      return { entries };
+    }
     const admissionEvent = wakingEntries.find((entry) => (
       ADDRESSED_EVENT_TYPES.has(entry.event.type) || entry.event.payload?.addressed === true
     ))
@@ -3354,7 +3374,11 @@ const SDK_SOURCES = {
     botSrc: () => sdkAsset('python/bot.py', join('hello-world-python', 'bot.py')),
     sdkOut: 'commonly.py',
     botOut: (name) => `${name}.py`,
-    runHint: (name) => `COMMONLY_TOKEN=$(cat .commonly-env) python3 ${name}.py`,
+    // .commonly-env is already KEY=VALUE. Sourcing it under `set -a` exports
+    // the key as written and keeps the token out of argv (`env $(cat …)` would
+    // put it on the command line). `COMMONLY_TOKEN=$(cat …)` would set the
+    // variable to the literal `COMMONLY_TOKEN=cm_agent_…` and the bot would 401.
+    runHint: (name) => `(set -a; . ./.commonly-env; exec python3 ${name}.py)`,
   },
 };
 
@@ -3409,6 +3433,9 @@ export const performInit = async ({
   });
   const installation = installResult.installation || installResult;
   const instanceId = installation.instanceId || 'default';
+  // Same rule as `attach`: the mention handle is the instanceId when there is
+  // one, otherwise the registry agentName.
+  const mentionHandle = instanceId !== 'default' ? instanceId : (installation.agentName || agentName);
 
   let runtimeToken = installResult.runtimeToken;
   if (!runtimeToken) {
@@ -3434,6 +3461,7 @@ export const performInit = async ({
   return {
     installation,
     instanceId,
+    mentionHandle,
     runtimeToken,
     files: {
       sdk: sdkOutPath,
@@ -4171,6 +4199,7 @@ Docs:
         console.log('\nNext:');
         console.log(`  1. Edit ${opts.name}.py to handle events.`);
         console.log(`  2. Run: ${result.runHint}`);
+        console.log(`  3. In pod ${opts.pod}, @mention ${result.mentionHandle} to talk to it.`);
       } catch (err) {
         console.error(`Init failed: ${err.message}`);
         process.exit(1);

package/src/lib/claimed-work-gate.js

@@ -0,0 +1,73 @@
+// Defer-while-claimed (TASK-640). While a seat holds a claimed board row in a
+// pod, a broadcast wake there that no person sent and that does not concern
+// its row is acked without a spawn. Measured on one seat, 2026-10-30: most of
+// its hourly wake-mode turns were pod broadcasts while it held one row, and
+// most of those ended in NO_REPLY.
+//
+// Mentions, DMs, human posts, heartbeats and digests are never deferred, and
+// neither is a broadcast about a row the seat holds. Every failure fails OPEN:
+// a kernel that does not mark `claimedByMe`, or a board read that errors,
+// means nothing is deferred.
+
+export const CLAIMED_WORK_TTL_MS = 60_000;
+
+// Pure: may this waking event wait while the seat holds `claimedTaskIds`?
+// `trigger` is classifyTrigger's verdict for the event.
+export const isDeferrableWhileClaimed = (event, trigger, claimedTaskIds) => {
+  if (!event || event.deliveryMode === 'digest') return false;
+  if (event.type !== 'message.posted') return false;
+  const payload = event.payload || {};
+  if (payload.addressed === true || payload.repliesToYourMessage === true) return false;
+  // A lease warning is about the seat's own row, though it names it differently.
+  if (payload.leaseWarningTaskId) return false;
+  // A board wake with a reason is a change the seat must see: a dependency of
+  // its row finished, an edit to its row folded into another row's wake (so
+  // taskId names the first row), or an agent assigned it a new row. Only the
+  // reasonless found-work nudge may wait.
+  if (payload.boardWake === true && payload.wakeReason) return false;
+  if (trigger !== 'agent' && trigger !== 'kernel') return false;
+  if (payload.taskId && claimedTaskIds?.has(String(payload.taskId))) return false;
+  return true;
+};
+
+export const createClaimedWorkGate = ({ client, ttlMs = CLAIMED_WORK_TTL_MS, now = () => Date.now() } = {}) => {
+  const cache = new Map();
+
+  // The ids of this seat's claimed rows in `podId`, or null when it holds none
+  // or the board cannot say.
+  const claimedTaskIds = async (podId) => {
+    if (!client || !podId) return null;
+    const cached = cache.get(podId);
+    if (cached && now() - cached.at < ttlMs) return cached.ids;
+    let ids = null;
+    try {
+      const { tasks = [] } = await client.get(`/api/v1/tasks/${podId}`, { status: 'claimed' });
+      // A lapsed lease still carries claimedBy; only a live one holds the seat.
+      const mine = tasks.filter((task) => task?.claimedByMe === true && task?.leaseState === 'held')
+        .map((task) => String(task.taskId));
+      ids = mine.length > 0 ? new Set(mine) : null;
+    } catch {
+      ids = null;
+    }
+    cache.set(podId, { at: now(), ids });
+    return ids;
+  };
+
+  // True when every waking event in the group may wait. An empty group is
+  // never deferred.
+  const shouldDefer = async (podId, wakes) => {
+    if (!Array.isArray(wakes) || wakes.length === 0) return false;
+    // Only read the board when the group could be deferred at all. A group
+    // that can't be deferred spawns a turn, and that turn may complete or
+    // release the row, so the next read must not trust the cached claim.
+    if (!wakes.every(({ event, trigger }) => isDeferrableWhileClaimed(event, trigger, null))) {
+      cache.delete(podId);
+      return false;
+    }
+    const ids = await claimedTaskIds(podId);
+    if (!ids) return false;
+    return wakes.every(({ event, trigger }) => isDeferrableWhileClaimed(event, trigger, ids));
+  };
+
+  return { shouldDefer };
+};