import { createOwnKeyResolver, createMachineReportClient } from '../lib/own-key-launch.js'; import { foregroundDaemonHint } from '../lib/daemon-hint.js'; import { loadDaemonRecord } from '../lib/daemon-store.js'; import { daemonSeatLogPath, logSize, readAppended, readLogTail } from '../lib/daemon-logs.js'; import { WALKED_HARNESSES } from '../lib/runtime-inventory.js'; import { createRuntimeReporter } from '../lib/runtime-observation.js'; /** * commonly agent * * register — register a webhook agent against an instance * connect — local dev loop: poll events → forward to localhost * attach — wrap a local CLI as a Commonly agent (ADR-005) * run — poll events, spawn the wrapped CLI, post results (ADR-005) * init — scaffold a webhook-SDK agent in the current dir (ADR-006) * list — list installed agents * logs — stream recent events for an agent * heartbeat — manually trigger an agent's heartbeat */ import { refreshMcpTokenCopy, removeMcpTokenCopy } from '../lib/mcp-token.js'; import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync, chmodSync } from 'fs'; import { join, dirname, basename, resolve as pathResolve } from 'path'; import { homedir, tmpdir } from 'os'; import { fileURLToPath } from 'url'; import { createHash } from 'crypto'; import { requireSeatModel } from '../lib/adapters/seat-model.js'; import { createClient } from '../lib/api.js'; import { buildSpawnId, createSpawnCredentialLease, turnEventIds, readSpawnPolicy, resolveSpawnTtlSeconds, revokeOrphanedSpawnCredentials, } from '../lib/spawn-credential.js'; import { getToken, resolveInstanceUrl } from '../lib/config.js'; import { startPoller, terminalDeliveryAckError } from '../lib/poller.js'; import { formatDigestFrame, formatUnreadMessagesFrame } from '../lib/digest-frame.js'; import { startWebhookServer, forwardToLocalWebhook, logOnlyHandler } from '../lib/webhook-server.js'; import { getAdapter, listAdapterNames, listPublicAdapterNames } from '../lib/adapters/index.js'; import { getSession, getSessionEntry, setSession, clearSession, clearSessions, wasEventHandled, recordHandledEvent, noticeDue, recordNotice, } from '../lib/session-store.js'; import { MODEL_UNAVAILABLE_HINT_WINDOW_MS, modelUnavailableFailure, modelUnavailableHint, } from '../lib/model-unavailable.js'; import { buildRecycleBriefing, idleMinutesSince, recycleReason, recycleThresholds, } from '../lib/session-recycle.js'; import { catchUpBeforeTurn } from '../lib/pod-catch-up.js'; import { readLongTerm, syncBack } from '../lib/memory-bridge.js'; import { pollRetryPolicy } from '../lib/poll-retry.js'; import { createIdleHeartbeat, createPollLiveness, formatStall, resolveIdleLineMs, resolvePollLivenessMs, } from '../lib/poll-liveness.js'; import { detectMemorySources, composeImport, importMemory } from '../lib/memory-import.js'; import { detectSkills, importSkills, parseSkillMeta } from '../lib/skills-import.js'; import { compileServerSkills } from '../lib/server-skills.js'; import { effectiveSandboxTrust, environmentForServer, normalizeSandboxTrust, parseEnvironmentFile, refuseWorkspaceTrust, resolveWorkspace, validateEnvironmentSpec, providerRefusal, WORKSPACE_SANDBOX_ALLOW, } from '../lib/environment.js'; import { firstRunWorkspace, podIsConfirmedPrivate, unconfinedTurnPlacement, workspaceTurnPlacement, } from '../lib/workspace-trust.js'; import { ADAPTERS_WITH_DEFAULT_MCP, ADAPTERS_WITH_GRANT_BROKER, ADAPTERS_WITH_PUBLIC_ONLY_GRANT, ADAPTERS_WITH_DEFAULT_SANDBOX, ADAPTERS_WITH_SANDBOX_ENFORCEMENT, COMMONLY_MCP_SERVER_NAME, defaultMcpServers, seatBaseline, withDefaultMcpServer, withDefaultSandbox, } from '../lib/default-environment.js'; import { mergeGrantBrokers, withholdGrantBroker } from '../lib/grant-broker-guard.js'; import { withPublicSeatMcpFlag } from '../lib/public-seat-mcp-flag.js'; import { UNCONFINED_TURN_REFUSAL, seatRunsUnconfined, unconfinedPodRefusalReason } from '../lib/unconfined-seat-guard.js'; import { OUTSIDER_GRANT_MCP_UNCONFINED, outsiderGrantMcpRefusal, seatIsConfined, unshippedMcpEntries, } from '../lib/outsider-grant-mcp.js'; import { FOCUS_FRAME_MAX_CODE_POINTS, formatPodFocusFrame, readPodFocus, } from '../lib/pod-focus.js'; import { formatPodConventionsFrame } from '../lib/pod-conventions.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'; import { CODEX_OPTED_IN_PUBLIC_POD_MESSAGE, UNSANDBOXED_FLAG, bwrapRefusedMessage, hostSandboxRefusal, windowsSandboxMessage, } from '../lib/sandbox/host-check.js'; import { UNSANDBOXED_NOTICE, codexUnconfinedForRun, codexUnsandboxedNotice, hostReportFailureMessage, hostUnconfinedForRun, runOptedInUnsandboxed, unsandboxedFlagRefusal, } from '../lib/sandbox/windows-unsandboxed.js'; import { prepareMcpBeforeFirstPoll } from '../lib/mcp-first-run.js'; import { installedCliVersion, startUpdateNotice } from '../lib/update-check.js'; import { createSeatStop } from '../lib/seat-stop.js'; import { detectSeatbelt } from '../lib/sandbox/seatbelt.js'; import { describeUpstreamRefusal } from '../lib/upstream-refusal.js'; import { createTurnRunner, supervisedRunPolicy } from '../lib/supervised-turn.js'; import { describeFirstOutputWatch } from '../lib/first-output-watchdog.js'; import { DEFAULT_HOOK_TIMEOUT_MS, clampHookTimeoutMs, forwardHookEvent, resolveHookToken, writeHooksConfig, } from '../lib/hooks-config.js'; import { EXTERNAL_SIGNAL_GRACE, formatRetryDelay, isExternalSignal, spawnRetryJitter, spawnRetryPolicy, } from '../lib/spawn-retry.js'; import { CONTENT_REFUSED_REASON, composeRefusalHandoff, contentRefusedResult, isContentRefusal, refusedItemRef, sanitizeHandoffAgent, } from '../lib/content-refusal.js'; import { CANT_ANSWER_NOTICE_WINDOW_MS, CLAUDE_SIGNED_OUT_FIX, CUT_OFF_NOTICE, cantAnswerNotice, claudeSignedOutResult, isClaudeSignedOut, spawnFailureReason, } from '../lib/turn-failure-notice.js'; import { missingHarnessHint, reportMissingHarness } from '../lib/missing-harness.js'; import { ADDRESSED_EVENT_TYPES, isPersonMention, CASCADE_DEFAULTS, CASCADE_ENV_VARS, CLAIMABLE_EVENT_TYPES, classifyTrigger, createCascadeGovernor, createClaimHandicap, createClaimKeeper, deliverChatReply, deliverCommentReply, frameDecisionForkRule, peerHoldsFrame, resolveCascadeSettings, } from '../lib/enforcement.js'; import { buildReplyReceipt } from '../lib/reply-receipt.js'; import { savedRuntimeControls, withSavedRuntimeControls, effortRefusedByDevice } from '../lib/seat-runtime-controls.js'; import { CLI } from '../lib/cli-hint.js'; const isPodFocusDiagnostic = (error) => ( typeof error?.code === 'string' && (error.code.startsWith('pod_focus') || error.code.startsWith('FOCUS_FRAME_')) ); // ── Token file I/O — ~/.commonly/tokens/.json (ADR-005) ─────────────── const tokensDir = () => join(homedir(), '.commonly', 'tokens'); const tokenFile = (name) => join(tokensDir(), `${name}.json`); export const saveAgentToken = (name, record) => { if (!existsSync(tokensDir())) mkdirSync(tokensDir(), { recursive: true, mode: 0o700 }); // The record carries a live cm_agent_* secret. The mode applies on create // only and is subject to the umask, so chmod every time: that also tightens // a record an older CLI left 0644. writeFileSync( tokenFile(name), JSON.stringify({ ...record, savedAt: new Date().toISOString() }, null, 2), { encoding: 'utf8', mode: 0o600 }, ); chmodSync(tokenFile(name), 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: ${CLI} mcp config --agent ${name}`); } }; export const loadAgentToken = (name) => { const file = tokenFile(name); if (!existsSync(file)) return null; try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } }; // ── Instances (F306) ───────────────────────────────────────────────────────── // One agent can have more than one instance (same name, another instanceId), // each with its own key. The default instance keeps `.json`; another // is `@.json`, so its key never overwrites the default's. const INSTANCE_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/; const isDefaultInstanceId = (instanceId) => String(instanceId || 'default').toLowerCase() === 'default'; export const seatKey = (agentName, instanceId) => ( isDefaultInstanceId(instanceId) ? agentName : `${agentName}@${instanceId}` ); const runCommandFor = (agentName, instanceId) => ( `${CLI} agent run ${agentName}${isDefaultInstanceId(instanceId) ? '' : ` --instance-id ${instanceId}`}` ); /** * The instance `run ` was asked to start: --instance-id, or the one a * seat key (`nova@priya-nova`, the token file's name) carries. Null when * neither names one: that run behaves as it always has, keyed by the bare name * whatever instance its key is for (a persona's BYO install is a non-default * instance, and its page command names none). * Throws on an id that is not a plain id, since it becomes part of a file name. */ export const parseRunInstanceId = (flag, name) => { const at = String(name).indexOf('@'); const fromName = at >= 0 ? String(name).slice(at + 1) : null; if (flag !== undefined && fromName !== null && flag !== fromName) { throw new Error(`'${name}' already names instance ${fromName}, so --instance-id ${flag} does not apply`); } const instanceId = flag !== undefined ? flag : fromName; if (instanceId === null) return null; if (!INSTANCE_ID_PATTERN.test(instanceId)) { throw new Error(`--instance-id takes the instance's id (letters, digits, '.', '_' or '-'), not '${instanceId}'`); } return instanceId; }; /** A key for one instance never runs as another: say which command runs it. */ export const runInstanceRefusal = ({ record, instanceId }) => { const keyInstance = record?.instanceId || 'default'; if (String(keyInstance).toLowerCase() === String(instanceId || 'default').toLowerCase()) return null; return `this key is for instance ${keyInstance} of '${record.agentName}', not instance ${instanceId || 'default'}. ` + `To run it: ${runCommandFor(record.agentName, keyInstance)}`; }; export const deleteAgentToken = (name) => { const file = tokenFile(name); if (existsSync(file)) rmSync(file); removeMcpTokenCopy(name); }; // ── env-var bootstrap for `agent run` (#913) ──────────────────────────────── // The BYO connect page hands a fresh user two env exports and // `commonly agent run ` — on a machine that has never run // `commonly agent attach`, so no token file exists and run used to dead-end. // The runtime token IS the identity: everything else in the record either // comes from `GET /api/agents/runtime/installations` (agentName, instanceId, // podId) or is a local fact (which CLI binary to wrap). Returns a record ready // for saveAgentToken, or null when COMMONLY_AGENT_TOKEN isn't set (caller // falls back to the attach hint). // OpenCode is opt-in: unlike the established wrappers it must not be selected // just because its binary happens to be installed on the operator's machine. export const BOOTSTRAP_ADAPTER_DETECT_ORDER = ['claude', 'codex', 'pi']; export const NO_AGENT_CLI_CODE = 'no_agent_cli'; /** * A saved seat with no enforced sandbox: an adapter that takes one, no * workspace, and an environment that is absent or enforces nothing (a record * from before bootstrap applied the default, or one attached without an * environment file). Such a record is told how to pick the default up; it is * not rewritten here. */ export const savedSeatLacksDefaultSandbox = (record) => Boolean(record) && ADAPTERS_WITH_DEFAULT_SANDBOX.has(record.adapter) && !record.workspacePath && (record.environment === null || record.environment === undefined || (typeof record.environment === 'object' && !Array.isArray(record.environment) && withDefaultSandbox(record.environment) !== record.environment)); /** * A key reissued for an agent that already ran here reaches `run` in the * environment, beside the saved token it replaced. The fresh one wins only when * the saved one is rejected and the server says the fresh one is this agent's. * The server keeps only a hash, so overwriting a saved token that works can't be * undone: an export for a same-named agent on another instance would lose it. */ export const adoptEnvToken = async ({ record, name, env = process.env, clientFactory = createClient, log = () => {}, }) => { const runtimeToken = (env.COMMONLY_AGENT_TOKEN || '').trim(); if (!runtimeToken || runtimeToken === record.runtimeToken) return record; const keepSaved = (why) => { log(`COMMONLY_AGENT_TOKEN ${why}, so this run uses the saved token`); return record; }; if (!runtimeToken.startsWith('cm_agent_')) return keepSaved('is not a runtime token'); const whoIs = (instance, token) => clientFactory({ instance, token }) .get('/api/agents/runtime/installations'); try { await whoIs(record.instanceUrl, record.runtimeToken); return keepSaved('differs from the saved token, which still works'); } catch (err) { // 401 alone, unlike the poller: every token refusal here is a 401, a 403 // comes from something in front of the app, and this one call overwrites. if (err?.status !== 401) { return keepSaved(`was not used, because the saved token could not be checked (${err.message})`); } } const instanceUrl = (env.COMMONLY_API_URL || '').trim() || record.instanceUrl; let identity; try { identity = await whoIs(instanceUrl, runtimeToken); } catch (err) { return keepSaved(`could not be checked against ${instanceUrl} (${err.message})`); } const lower = (value) => String(value).toLowerCase(); if (lower(identity?.agentName) !== lower(record.agentName || name) || lower(identity?.instanceId || 'default') !== lower(record.instanceId || 'default')) { return keepSaved(`belongs to another agent (${identity?.agentName}, instance ${identity?.instanceId || 'default'})`); } // A reinstall can move the agent, and the saved pod is then gone. const active = (identity?.installations || []).filter((row) => row?.status === 'active'); const stillThere = active.some((row) => String(row.podId) === String(record.podId)); const podId = stillThere ? record.podId : (active.find((row) => row.type === 'installation') || active[0])?.podId || record.podId; log('the saved token was rejected, so this run uses COMMONLY_AGENT_TOKEN and saves it'); return { ...record, runtimeToken, instanceUrl, podId, }; }; /** Return the adapter binding resolved for this exact installation by the server. */ export const runtimeAdapterForInstallation = ({ installations, podId, instanceId } = {}) => { if (!Array.isArray(installations) || !podId) return null; const expectedPodId = String(podId); const expectedInstanceId = String(instanceId || 'default'); const installation = installations.find((row) => ( row?.type === 'installation' && String(row.podId || '') === expectedPodId && String(row.instanceId || 'default') === expectedInstanceId )); const adapter = String(installation?.runtimeAdapter || '').trim().toLowerCase(); return adapter || null; }; /** * Non-broker adapters need a server-resolved binding on env-token seats. So do * the broker adapters that hold a grant only when public (pi, F175c): the * broker's per-call check judges the seat by its ROW, and a row that names no * adapter reads as daemon-decided there, where naming (F94) lifts a sandbox * refusal that pi must never have lifted. The binding is what puts `pi` on the * row. */ export const adapterRequiresServerBinding = (adapterName) => { const adapter = String(adapterName || '').trim().toLowerCase(); return Boolean(adapter) && adapter !== 'stub' && (!ADAPTERS_WITH_GRANT_BROKER.has(adapter) || ADAPTERS_WITH_PUBLIC_ONLY_GRANT.has(adapter)); }; const serverRuntimeAdapterProjectionState = (installations) => { if (!Array.isArray(installations)) return 'unknown'; const installationRows = installations.filter((row) => row?.type === 'installation'); if (installationRows.length === 0) return 'unknown'; return installationRows.some((row) => Object.prototype.hasOwnProperty.call(row, 'runtimeAdapter')) ? 'present' : 'legacy'; }; /** Return the refusal message unless this installation declares the same adapter. */ export const serverAdapterBindingRefusal = ({ adapterName, agentName, installations, podId, instanceId, includeAttachGuidance = true, } = {}) => { const adapter = String(adapterName || '').trim().toLowerCase(); if (!adapterRequiresServerBinding(adapter)) return null; const projectionState = serverRuntimeAdapterProjectionState(installations); if (projectionState === 'unknown') { return 'Could not verify the server adapter binding because the installations response is empty or missing. ' + 'Retry after the server returns this installation.'; } if (projectionState === 'legacy') { return `This Commonly server predates runtime adapter bindings; upgrade the server before running adapter '${adapter}'.`; } if (runtimeAdapterForInstallation({ installations, podId, instanceId }) === adapter) return null; const refusal = `Adapter '${adapter}' is not declared for this Commonly installation.`; if (!includeAttachGuidance) return refusal; return `${refusal} A pod owner must sign in with ${CLI} login, then run ${CLI} agent attach ${adapter}` + ` --pod ${podId || ''} --name ${agentName || ''}` + ` [--env ] before this seat can use adapter '${adapter}'.`; }; /** Verify a newly attached adapter before telling the operator how to run it. */ export const checkAttachedAdapterBinding = async ({ adapterName, agentName, podId, instanceId, instanceUrl, runtimeToken, clientFactory = createClient, } = {}) => { if (!adapterRequiresServerBinding(adapterName)) return { canRun: true }; let identity; try { identity = await clientFactory({ instance: instanceUrl, token: runtimeToken }) .get('/api/agents/runtime/installations'); } catch (error) { return { canRun: false, warning: `Could not verify the server adapter binding after attach: ${error.message}. ` + 'The installation was saved, but do not expect agent run to work until verification succeeds.', }; } const refusal = serverAdapterBindingRefusal({ adapterName, agentName, installations: identity?.installations, podId, instanceId, includeAttachGuidance: false, }); return refusal ? { canRun: false, warning: refusal } : { canRun: true }; }; export const printAttachRunGuidance = ({ agentName, binding, log = console.log, warn = console.warn, } = {}) => { if (binding?.canRun) { log(`\n Run with: ${CLI} agent run ${agentName}`); } else { warn(`\n WARNING: ${binding?.warning || 'The server did not confirm this adapter binding.'}`); } }; export { providerRefusal }; // ── `agent run --adapter` against an existing token file (#2098) ──────────── // The flag picks the CLI once, at first-run bootstrap; after that the token // file's adapter is what runs. A different `--adapter` used to be dropped // without a word, so "switch this agent to Codex" kept running Claude and read // as Codex misbehaving. Refuse instead, and name the way out for each path: // a foreground run re-bootstraps from the Connect page's env exports after the // local record is removed; a daemon-managed seat is switched through the // registry, which the daemon applies on its next pass. // `run --allow write,web`: the grants a first-run workspace seat starts with // (TASK-294). An unknown name is refused rather than dropped. export const parseAllowGrants = (value) => { if (value === undefined || value === null) return []; const requested = String(value).split(',').map((grant) => grant.trim()).filter(Boolean); if (!requested.length || requested.some((grant) => !WORKSPACE_SANDBOX_ALLOW.includes(grant))) { throw new Error(`--allow takes ${WORKSPACE_SANDBOX_ALLOW.join(' and/or ')}, comma-separated ` + `(got ${JSON.stringify(String(value))})`); } return WORKSPACE_SANDBOX_ALLOW.filter((grant) => requested.includes(grant)); }; // Grants are fixed when the token file is written. A later --allow that // differs is refused with the way to change them, never applied quietly. export const checkRunAllowRequest = ({ record, requested = [] }) => { if (!requested.length) return { ok: true }; const savedList = record?.environment?.sandbox?.allow || []; const saved = WORKSPACE_SANDBOX_ALLOW.filter((grant) => savedList.includes(grant)); if (saved.join(',') === requested.join(',')) return { ok: true }; const name = record.agentName; return { ok: false, message: [ `'${name}' was set up with ${saved.length ? `--allow ${saved.join(',')}` : 'no --allow'}; ` + `--allow ${requested.join(',')} was not applied.`, `To change it: ${CLI} agent detach ${name} --force, then re-run with the Connect-page ` + `env exports and --allow ${requested.join(',')}.`, ].join('\n'), }; }; // What a first-run workspace seat may do, said once at bootstrap. A write // grant hands it Bash, whose commands reach the network, so that line never // claims the seat is offline. const workspaceGrantLine = (workspacePath, allow) => { const write = allow.includes('write'); const web = allow.includes('web'); if (!write) { return web ? `this agent can read ${workspacePath}, run read-only git there, and fetch web pages; it cannot edit files.` : `this agent can read ${workspacePath} and run read-only git there; it cannot edit files or reach the web.`; } return `this agent can read and edit files in ${workspacePath} and run commands there` + (web ? ', and fetch web pages' : '') + '. Its commands can reach the network. Its .git stays read-only, so it cannot commit.'; }; export const checkRunAdapterRequest = ({ record, requestedAdapter, tokenPath }) => { const requested = String(requestedAdapter || '').trim().toLowerCase(); if (!requested) return { ok: true }; const bound = String(record?.adapter || '').trim().toLowerCase(); if (!bound || bound === requested) return { ok: true }; const name = record.agentName; return { ok: false, message: [ `'${name}' is bound to the ${bound} adapter by its token file (${tokenPath}); --adapter ${requested} was not applied.`, `To run it with ${requested} here: ${CLI} agent detach ${name} --force, then re-run with the Connect-page env exports and --adapter ${requested}.`, `A daemon-managed seat switches with: ${CLI} agent config ${name} --adapter ${requested}`, ].join('\n'), }; }; export const bootstrapAgentRecordFromEnv = async ({ name, env = process.env, clientFactory = createClient, adapterRegistry = { getAdapter, listAdapterNames, listPublicAdapterNames }, adapterOverride = null, log = () => {}, startDir = process.cwd(), home, allow = [], platform = process.platform, }) => { const runtimeToken = (env.COMMONLY_AGENT_TOKEN || '').trim(); if (!runtimeToken) return null; if (!runtimeToken.startsWith('cm_agent_')) { throw new Error('COMMONLY_AGENT_TOKEN is set but is not a runtime token (expected cm_agent_… prefix).'); } const instanceUrl = (env.COMMONLY_API_URL || '').trim() || resolveInstanceUrl(undefined); let identity; let client; try { client = clientFactory({ instance: instanceUrl, token: runtimeToken }); identity = await client.get('/api/agents/runtime/installations'); } catch (err) { throw new Error( `Could not resolve the agent behind COMMONLY_AGENT_TOKEN against ${instanceUrl}: ${err.message}. ` + 'Check the token was copied whole and the URL matches the instance that issued it.', ); } const installs = Array.isArray(identity?.installations) ? identity.installations : []; const primary = installs.find((i) => i.type === 'installation' && i.status === 'active') || installs[0] || null; // The adapter names a binary on THIS machine — the one fact the server // cannot know. Explicit --adapter wins; otherwise probe the known CLIs. let adapterName = adapterOverride; if (adapterOverride) { const adapter = adapterRegistry.getAdapter(adapterOverride); if (!adapter) { throw new Error(`Unknown adapter '${adapterOverride}'. Known: ${(adapterRegistry.listPublicAdapterNames || adapterRegistry.listAdapterNames)().join(', ')}`); } if (!await adapter.detect()) { // F457: this run exits before it checks in, so the page would wait for // it forever. Say what was missing there, and how to get it here. await reportMissingHarness(client, adapterOverride); throw new Error(`Adapter '${adapterOverride}' not found on PATH. ${missingHarnessHint(adapterOverride)}`); } } else { const missing = []; for (const candidate of BOOTSTRAP_ADAPTER_DETECT_ORDER) { const adapter = adapterRegistry.getAdapter(candidate); // eslint-disable-next-line no-await-in-loop if (adapter && await adapter.detect()) { adapterName = candidate; break; } missing.push(candidate); } if (!adapterName) { await reportMissingHarness(client, null); const err = new Error( `No supported agent CLI found on PATH (looked for: ${BOOTSTRAP_ADAPTER_DETECT_ORDER.join(', ')}). ` + 'Install one, or pass --adapter .', ); err.code = NO_AGENT_CLI_CODE; throw err; } // The page's command names the person's own CLI; running a different one // without saying so is how a Claude Code user ended up with a Codex agent. if (missing.length > 0) { log(`${missing.join(', ')} not found on PATH, so this agent runs with ${adapterName}. ` + 'To choose, pass --adapter .'); } } if (adapterName === 'dsh') { throw new Error('dsh first-run bootstrap requires provider settings; attach it with --env before running'); } // The token's identity wins over the CLI argument — a mistyped name must // not fork a second identity for the same token. const agentName = identity?.agentName || name; if (String(agentName).toLowerCase() !== String(name).toLowerCase()) { log(`token belongs to '${agentName}', not '${name}' — using the token's identity`); } const bindingRefusal = serverAdapterBindingRefusal({ adapterName, agentName, installations: installs, podId: primary?.podId, instanceId: primary?.instanceId, }); if (bindingRefusal) throw new Error(bindingRefusal); // The daemon's baseline for a seat nobody wrote a spec for, sandbox // included: this record is derived from nothing the person declared. const environment = seatBaseline(buildDefaultEnvironment(adapterName), adapterName, { sandbox: true }); // A claude seat whose every pod is confirmed private reads the directory // it was started from (TASK-294); anything else keeps the public default. const workspace = firstRunWorkspace({ adapterName, installations: installs, startDir, home, platform, }); if (allow.length && !workspace?.workspacePath) { throw new Error(`--allow ${allow.join(',')} applies only to an agent that works in the folder it ` + 'starts in, and this one ' + (workspace?.reason ? `would read only its scratch folder, because ${workspace.reason}.${workspace.fix ? ` ${workspace.fix}` : ''}` : 'does not.')); } if (workspace?.workspacePath) { log(workspaceGrantLine(workspace.workspacePath, allow)); } else if (workspace?.reason) { log(`this agent can read only its own scratch folder, because ${workspace.reason}.` + (workspace.fix ? ` ${workspace.fix}` : '')); } return { agentName, displayName: identity?.displayName || primary?.displayName || agentName, instanceId: identity?.instanceId || primary?.instanceId || 'default', podId: primary?.podId || null, instanceUrl, runtimeToken, adapter: adapterName, environment: workspace?.workspacePath ? { ...environment, sandbox: { trust: 'workspace', ...(allow.length ? { allow } : {}) } } : environment, workspacePath: workspace?.workspacePath || null, }; }; /** * `commonly agent list`. Without --pod it reads the admin installs route, which * only a global admin can call. With --pod it reads the member-gated pod roster, * so a pod member lists its own seats. Returns the exit code, never exits itself. * Any throw becomes one Failed line and exit 1. */ export const runAgentList = async (opts = {}, deps = {}) => { const { error = console.error } = deps; try { return await listAgents(opts, deps); } catch (err) { error(`Failed: ${err.message}`); return 1; } }; const listAgents = async (opts, deps) => { const { clientFactory = createClient, tokenFor = getToken, instanceUrlFor = resolveInstanceUrl, log = console.log, error = console.error, } = deps; const col = (s, w) => String(s ?? '').padEnd(w).slice(0, w); if (opts.local) { const agents = listLocalAgents(); if (agents.length === 0) { log(`No agents attached locally. Run: ${CLI} agent attach --pod --name `); return 0; } log(`${col('NAME', 20)} ${col('ADAPTER', 10)} ${col('POD', 26)} LAST TURN`); log('─'.repeat(80)); agents.forEach((a) => { const lastTurn = a.lastTurn ? new Date(a.lastTurn).toLocaleString() : 'never'; log(`${col(a.name, 20)} ${col(a.adapter, 10)} ${col(a.podId, 26)} ${lastTurn}`); }); return 0; } const token = tokenFor(opts.instance); if (!token) { error(`Not logged in. Run: ${CLI} login`); return 1; } const client = clientFactory({ instance: instanceUrlFor(opts.instance), token }); try { const rows = opts.pod ? (await client.get(`/api/registry/pods/${encodeURIComponent(opts.pod)}/agents`)).agents || [] : (await client.get('/api/registry/admin/installations')).installations || []; if (rows.length === 0) { log('No agents installed.'); return 0; } // The pod roster also names the handle a person types to reach each agent // (F44). It is printed whole: a cut handle reaches nobody. const handleOf = (inst) => (inst.mention ? `@${inst.mention}` : ''); const handleWidth = opts.pod ? Math.max(6, ...rows.map((inst) => handleOf(inst).length)) : 0; const handleCol = (s) => (opts.pod ? `${col(s, handleWidth)} ` : ''); log(`${col('NAME', 16)} ${col('INSTANCE', 10)} ${handleCol('HANDLE')}${col('RUNTIME', 14)} ${col('HOST', 6)} ${col('STATUS', 10)} LAST SEEN`); log('─'.repeat(80)); rows.forEach((inst) => { // The pod roster names the agent `name`; the admin route uses `agentName`. const displayName = opts.pod ? (inst.name || inst.agentName) : inst.agentName; const runtimeType = inst.config?.runtime?.runtimeType || inst.runtime?.runtimeType || inst.runtimeType || '?'; const host = inst.config?.runtime?.host || inst.runtime?.host || ''; const seen = inst.lastActiveAt || inst.usage?.lastUsedAt || inst.connection?.lastSeenAt; const lastSeen = seen ? new Date(seen).toLocaleString() : 'never'; log(`${col(displayName, 16)} ${col(inst.instanceId, 10)} ${handleCol(handleOf(inst))}${col(runtimeType, 14)} ${col(host, 6)} ${col(inst.status, 10)} ${lastSeen}`); }); return 0; } catch (err) { error(`Failed: ${err.message}`); if (err.status === 403 && !opts.pod) error('Listing every install needs a global admin. Pass --pod to list one pod you belong to.'); return 1; } }; /** * The seat `agent logs --pod` reads (F44). An agent has three names: its * agentName, its instance, and the handle its @mentions route to. Any of them * finds it in the pod roster, so a seat whose instance isn't "default" no longer * reads as idle. An explicit --instance-id is used as given. */ export const resolveLogsSeat = async (client, podId, typed, instanceId) => { // Activity is stored under the bare agentName, never an @ spelling. const bare = String(typed).trim().replace(/^@/, ''); const isHandle = String(typed).trim().startsWith('@'); // A plain name with an explicit instance is used as given. An @handle still // needs the roster: activity is stored under the agentName, not the handle. if (instanceId && !isHandle) return { agentName: bare, instanceId }; const want = bare.toLowerCase(); let agents; try { ({ agents = [] } = await client.get(`/api/registry/pods/${encodeURIComponent(podId)}/agents`)); } catch (err) { // The default instance is still worth reading when the roster isn't. return { agentName: bare, instanceId: instanceId || 'default', note: `The pod roster couldn't be read (${err.message}), so instance ${instanceId || 'default'} was read for '${bare}'.`, }; } const seatOf = (inst) => ({ agentName: inst.name || inst.agentName, instanceId: inst.instanceId || 'default' }); // An @handle routes to one seat, so it wins over another seat's instance of the same name. if (isHandle) { const byHandle = agents.filter((inst) => typeof inst.mention === 'string' && inst.mention.toLowerCase() === want); if (byHandle.length === 1) return instanceId ? { ...seatOf(byHandle[0]), instanceId } : seatOf(byHandle[0]); if (instanceId) { return { agentName: bare, instanceId, note: `'${typed}' is not a handle in this pod's roster, so agent name '${bare}' was read at instance ${instanceId}.`, }; } } const named = (inst) => [inst.mention, inst.name || inst.agentName, inst.instanceId !== 'default' && inst.instanceId] .some((n) => typeof n === 'string' && n.toLowerCase() === want); const hits = agents.filter(named); if (hits.length > 1) { const pairs = hits.map((h) => `${h.name || h.agentName}/${h.instanceId}`).join(', '); throw new Error(`${hits.length} seats are named '${typed}' here: ${pairs}. ` + `Run: ${CLI} agent logs --pod ${podId} --instance-id `); } if (hits.length === 0) { // A typo must not read like an idle seat, so say what was read instead. const handles = agents.map((inst) => inst.mention).filter(Boolean).map((m) => `@${m}`).join(', '); return { agentName: bare, instanceId: 'default', note: `'${typed}' is not in this pod's roster, so instance default was read.${handles ? ` Seats here: ${handles}` : ''}`, }; } return seatOf(hits[0]); }; /** * Enumerate every agent attached on this laptop — i.e. every file in * ~/.commonly/tokens/*.json. Cross-references the session store for a * "last turn" timestamp per agent so the user sees cold vs. live agents. * * Returns an array of plain records so the CLI table formatter stays simple * and tests can assert on shape directly. */ export const listLocalAgents = () => { const dir = tokensDir(); if (!existsSync(dir)) return []; return readdirSync(dir) .filter((f) => f.endsWith('.json')) .map((f) => f.slice(0, -'.json'.length)) .map((name) => { const record = loadAgentToken(name); if (!record) return null; let lastTurn = null; try { const sessionsFile = join(homedir(), '.commonly', 'sessions', `${name}.json`); if (existsSync(sessionsFile)) { const sessions = JSON.parse(readFileSync(sessionsFile, 'utf8')); // One entry per pod — we surface the most recent across pods. Object.values(sessions).forEach((s) => { if (s?.lastTurn && (!lastTurn || s.lastTurn > lastTurn)) lastTurn = s.lastTurn; }); } } catch { // Corrupt session store — not a hard error, just skip. } return { name, adapter: record.adapter || '?', podId: record.podId || '?', instanceUrl: record.instanceUrl || '?', instanceId: record.instanceId || 'default', savedAt: record.savedAt || null, lastTurn, }; }) .filter(Boolean); }; /** * The token files listLocalAgents drops: present, but not readable JSON. * `commonly doctor` reports them, because a dropped file otherwise reads as * "no agent here" and lets doctor pass on a seat that cannot start. * Throws when the directory exists but cannot be read, for doctor to report. */ export const listUnreadableAgentTokens = () => { let files; try { files = readdirSync(tokensDir()); } catch (error) { // Only a missing directory means no agents. existsSync also answers false // for EACCES on an ancestor, which is why this reads instead of checking. if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return []; throw error; } return files .filter((f) => f.endsWith('.json')) .map((f) => f.slice(0, -'.json'.length)) .filter((name) => !loadAgentToken(name)) .sort(); }; // Chat event types whose payload already contains the prompt the wrapper // should forward verbatim. Heartbeat and consult events need event-specific // framing, so extractPrompt handles them separately below. const PROMPT_EVENT_TYPES = new Set([ 'chat.mention', 'thread.mention', 'message.posted', 'dm.message', 'first_contact', ]); // A person waiting on an answer outranks the seat's own housekeeping. Measured // on the published 0.1.108 smoke (TASK-289, walk 5): the greeting turn for a // fresh connect ran 14 s, a mention landed 1 s into it, and the answer came // from the next turn 39.4 s after the mention. `first_contact` is the only // event that exists to introduce the seat rather than to answer anyone, so it // is the only one worth holding back. const DEFERRABLE_SOLO_EVENT_TYPES = new Set(['first_contact']); // Someone asked this seat for an answer: by type, by the server's stamp, or by // replying to it. A batch turn carries the same answer for its items. const someoneIsWaiting = (event) => ADDRESSED_EVENT_TYPES.has(event.type) || event.payload?.addressed === true || event.payload?.repliesToYourMessage === true || event.payload?.someoneWaiting === true; // The last line of a reply is nothing but the sentinel. An unaddressed person's // `message.posted` counts as nobody waiting, on purpose: text closing on the // sentinel there is far likelier reasoning about an ambient message than an // answer, and the seat's prompt already sends ambient messages to NO_REPLY. const CLOSES_ON_BARE_SENTINEL = /(?:^|\n)[ \t]*NO_REPLY[ \t]*$/; // The first message in `messages` that this seat posted and `earlierIds` doesn't // hold. The server stamps each message with `self` when it knows who is asking. // Trust that over any local guess: the wrapper cannot derive its own bot username // reliably (the server applies LEGACY_AGENT_MAP and an owner-scoped instanceId), // and a wrong guess double-posts. const findOwnPost = (messages, earlierIds) => { const serverKnowsSelf = messages.some((m) => typeof m.self === 'boolean'); for (const m of messages) { // A new human-authored message must NEVER count: it is either a human // typing mid-turn, or the agent misusing an operator CLI profile / human // token (the 2026-07-22 as-operator attribution incident) — in both cases // the wrapper still delivers the reply under the agent's own identity. // // With `self`, only THIS agent's own post counts. Without it (an older // server), fall back to the legacy any-bot test — which drops this agent's // reply whenever another agent answers first (#757). // A system line is stored under the agent it is about; it is never this // agent's post, even from a server that predates F434's `self` fix. if (!earlierIds.has(String(m._id || m.id)) && m.isBot && m.messageType !== 'system' && (serverKnowsSelf ? m.self === true : true)) { return { id: String(m._id || m.id), author: m.username || 'unknown', basis: serverKnowsSelf ? 'self' : 'legacy-any-bot', threadRootId: m.thread_root_id ?? null, content: typeof m.content === 'string' ? m.content : '', }; } } return null; }; // This seat's newest post in `tail` that came after the last row `knownIds` holds, // or null when that can't be shown. `knownIds` is a 10-message snapshot, so a row // missing from it may only be older, and just "not in the set" would count an old // post as new. With no known row in the tail, nothing marks where the turn began. // An older server has no `self`, so a peer's post can't be told from this seat's. const newestOwnPostSince = (tail, knownIds) => { const lastKnown = tail.findLastIndex((m) => knownIds.has(String(m._id || m.id))); if (lastKnown === -1) return null; const ownPost = findOwnPost(tail.slice(lastKnown + 1).reverse(), knownIds); return ownPost?.basis === 'self' ? ownPost : null; }; // How long a fresh seat's greeting waits for a person before it runs alone. // One poll lost the race on the 0.1.257 walk (2026-11-05): the mention landed // just after the hold, the greeting took the next turn alone, and the answer // came 50.5 s after the mention instead of 25.7 s. A person who has just // connected an agent usually mentions it within its first minute, and the // kernel posts the seat's own join line at once, so a quiet connect loses // nothing by greeting a minute later. Counted in polls (at least one), so a // shorter --interval holds for more polls, not for less time. const GREETING_HOLD_MS = 60_000; // Inside one batch the person's item leads the prompt; the greeting follows it. const PERSON_WAITING_EVENT_TYPES = new Set(['chat.mention', 'thread.mention', 'message.posted', 'dm.message']); const inboxPriority = (event) => { if (event?.deliveryMode === 'digest') return 2; return PERSON_WAITING_EVENT_TYPES.has(event?.type) ? 0 : 1; }; // F225: a comment @ on a post is answered on that comment, so it has its own // delivery target and its own turn, and one turn's final text can't serve both // it and the pod. It stays on the inbox path, for the lease renewal and the // refusal notice. A digest comment is context, not a turn. const isCommentWake = (event) => event?.type === 'thread.mention' && event.deliveryMode !== 'digest'; // The post must belong to the event's pod. A post with no pod has its mention // delivered to a pod the commenter happens to be in, while the turn runs by the // seat's own pods and the reply lands where any signed-in user reads it. So that // comment, and one from a server that sends no stamp, gets no target and no turn. const commentTargetOf = (event) => { const thread = isCommentWake(event) ? event.payload?.thread : null; return thread?.postId && thread?.commentId && thread?.postPodId && String(thread.postPodId) === String(event.podId) ? { postId: String(thread.postId), commentId: String(thread.commentId) } : null; }; const COMMENT_OUTSIDE_POD_REASON = 'comment-outside-pod'; // Consultations have a per-request private response channel, rather than a // pod-chat delivery. They stay on their existing single-event path; every // event that represents the shared pod inbox is batched below. const PRIVATE_RESPONSE_EVENT_TYPES = new Set(['agent.ask', 'agent.ask.response']); // How often a live delivery lease is renewed: during a turn, and while a failed // turn's events wait for their retry. The server requeues a delivery whose // lease is 10+ minutes old (AGENT_EVENT_REQUEUE_DELIVERED_MINUTES). const DELIVERY_RENEW_INTERVAL_MS = 60_000; // A failed turn's events are carried in memory and re-run when the retry timer // fires (see `holdForRetry` in performRun). Each local re-run is a delivery // attempt the server's requeue cap (AGENT_EVENT_REQUEUE_MAX_ATTEMPTS, 3) never // counts, so a carry with no bound would retry poison content forever and // block every later event behind it. At this many consecutive failures of the // same event the carry lets it go: renewal stops, and the server's requeue // sweep redelivers it under the cap it already enforces. Three matches the // point where spawnRetryPolicy stops treating an unknown failure as transient. const HELD_RETRY_MAX_FAILURES = 3; // F226: a turn shows at most the batch limit, so a carried item on top of a full // page can sit past the cap. Such an item is not acked: it keeps its lease and // rejoins the next turn. At this many turns passed over the carry lets it go, // the way HELD_RETRY_MAX_FAILURES does, so an ambient item under a steady stream // of people, or anything piling up during an outage, can't be held forever. The // server redelivers it under its cap, and may retire it with the TASK-656 line, // which is skipped if the agent has posted in the pod since. const PAST_CAP_MAX_CARRIES = 5; // F236: how often a seat waiting out an open circuit checks its inbox, so a pod // that first asks during the wait is told why within about a minute instead of // at the probe (up to ~16 minutes). The check runs no turn: the circuit's delay // is unchanged, and the can't-answer limit (once per cause per pod per hour) // still decides who hears it. const CIRCUIT_NOTICE_CHECK_MS = 60 * 1000; // F237: failed turns in a row after which a full carry stops claiming new rows. // One failure keeps the claim, so a person's new message still joins the retry // ahead of carried agent rows; past it the outage looks real, and every row // claimed then rides the carry past the prompt cap, is released after // PAST_CAP_MAX_CARRIES failed turns and claimed again, an attempt each time, // until the requeue cap retires it without its ever being tried. const FULL_CARRY_CLAIM_FAILURES = 2; // Who gets a slot when a batch is past the cap. 'unknown' counts as a person: // only a row the snapshot and the kernel's stamp both can't place reads so, and // a wrong guess costs an ambient item one turn. Within a rank the older row // wins, and carried rows lead the page, so new arrivals can't overtake them. const capRank = (entry) => { const { type, payload } = entry.event; // A reply to the seat is direct address on a broadcast's transport, as the // claim path treats it. const direct = ADDRESSED_EVENT_TYPES.has(type) || ((payload?.repliesToYourMessage === true || payload?.addressed === true) && payload?.senderIsHuman !== false); return direct && entry.trigger !== 'agent' && entry.trigger !== 'kernel' ? 0 : 1 + inboxPriority(entry.event); }; // The wake whose ack settles the digest (agentEventService.acknowledge). const holdsDigest = (event) => Boolean(event.digestSnapshotAt || event.payload?.digestRollup); const deliveryIdOf = (event) => { const deliveryId = event?.payload?.deliveryId; return typeof deliveryId === 'string' && deliveryId ? deliveryId : null; }; const countEvents = (count) => `${count} event${count === 1 ? '' : 's'}`; // ── default environment for adapters that benefit from auto-MCP wiring ───── // Which adapters can consume `mcp[]`, and the server declaration they get by // default, live in lib/default-environment.js — the daemon's per-seat token // provisioning reads the same module, so the two can never drift apart. const CODEX_PERMISSION_PROFILE_MIN_VERSION = [0, 138, 0]; const versionAtLeast = (version, minimum) => { const parts = String(version || '') .match(/\d+(?:\.\d+){1,2}/)?.[0] .split('.') .map(Number); if (!parts) return false; for (let i = 0; i < minimum.length; i += 1) { const current = parts[i] || 0; if (current > minimum[i]) return true; if (current < minimum[i]) return false; } return true; }; // The commonly behavior skill ships inside this package (cli/skills/commonly) // so a fresh attach can mount it into the agent without a network fetch. // Resolved from the module location — works both from source and when the // package is installed under node_modules/@commonlyai/cli. const BUNDLED_COMMONLY_SKILL_DIR = pathResolve( dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills', 'commonly', ); const reportedSkillName = (source) => { try { return parseSkillMeta(readFileSync(join(source, 'SKILL.md'), 'utf8'), basename(source)).name; } catch { return basename(source); } }; // Minimum-viable environment for fresh attach: wire @commonlyai/mcp so the // agent gets commonly_* kernel tools out of the box, AND mount the commonly // behavior skill so the agent knows the house rules (orient before posting, // reply conversationally, use the roster, don't double-post). Without the // skill, wrapper-spawned CLIs fly blind and behave inconsistently — some // narrate after tool-posting (double-post), some default to NO_REPLY on a // normal question. Returning null means "no default" — a non-consuming adapter // proceeds with environment=null exactly like before. export const buildDefaultEnvironment = (adapterName) => { if (!ADAPTERS_WITH_DEFAULT_MCP.has(adapterName)) return null; const environment = { mcp: defaultMcpServers(adapterName) }; // Only advertise the skill if it actually shipped (defensive: a broken // package that dropped the skills/ dir shouldn't hand mountSkills a // missing-source path every spawn). if (existsSync(BUNDLED_COMMONLY_SKILL_DIR)) { environment.skills = { claude: [BUNDLED_COMMONLY_SKILL_DIR] }; } return environment; }; // ── public-pod sandbox gate ───────────────────────────────────────────────── /** * Refuse to attach an agent to a publicly-readable pod unless it declares an * enforced sandbox. * * The public-agent sandbox is real and attack-tested, but it only engages once * an enforced sandbox is declared: `sandbox.trust: 'public'` (the adapters then * resolve the mode for the host at spawn) or an explicit non-'none' * `sandbox.mode`. Nothing previously connected "this pod is public" to "this * agent must be confined". An agent attached with no sandbox block simply ran * unconfined, silently, with the operator none the wiser. * * That is not hypothetical — `hq-support` ran that way in a 67-member public * pod until 2026-07-27. Its permission deny-list was doing the file-blocking * work while the OS-level sandbox never engaged at all. * * Deny-by-default only means something if ABSENT is refused, so this is a hard * error rather than a warning. A seat the adapters do not confine * (lib/unconfined-seat-guard.js `seatRunsUnconfined`) attaches only to a pod * confirmed private and invite-only; a pod whose visibility cannot be read * fails closed, and each turn checks again. * A dsh seat without public trust requires a successful visibility read and * rejects a public pod even without a sandbox declaration. A public-trust dsh * seat runs the public tool fence (adapters/dsh.js, F115) and attaches anywhere. */ export const assertSandboxDeclaredForPublicPod = async ({ client, podId, environment, adapterName, // Kept for callers; every outcome here is now a return or a refusal. log: _log = () => {}, }) => { if (!podId || !client) return; if (adapterName === 'dsh' && effectiveSandboxTrust(environment?.sandbox?.trust) !== 'public') { let pod; try { pod = await client.get(`/api/pods/${podId}`); } catch { throw new Error('dsh requires confirmed private pod visibility before attach'); } if (typeof pod?.publicRead !== 'boolean' || typeof pod?.communityListed !== 'boolean') { throw new Error('dsh requires confirmed private pod visibility before attach'); } if (pod?.publicRead || pod?.communityListed) { throw new Error('This pod is publicly readable. A dsh seat attaches to it only with "sandbox": { "trust": "public" }'); } // dsh's confined shape stops here; an unconfined dsh runs as its owner and // meets the invite-only requirement below. if (!seatRunsUnconfined({ environment, adapterName })) return; } // A `workspace` seat lets the room read its start directory (TASK-294), so it // needs the pod CONFIRMED private, not merely not known to be public: a pod // whose visibility cannot be read fails closed here, the way dsh does above. if (environment?.sandbox?.trust === 'workspace') { let pod; try { pod = await client.get(`/api/pods/${podId}`); } catch { throw new Error( 'sandbox.trust=workspace requires confirmed private pod visibility before attach, ' + 'and this pod\'s visibility could not be read', ); } if (podIsConfirmedPrivate(pod)) return; const label = pod?.name ? `"${pod.name}"` : podId; const reported = typeof pod?.publicRead === 'boolean' && typeof pod?.communityListed === 'boolean'; let why = 'did not report its visibility'; if (reported) why = pod.publicRead || pod.communityListed ? 'is publicly readable' : 'is open to join'; throw new Error( `${label} ${why}, so sandbox.trust=workspace would let people you do not control read this ` + 'agent\'s start directory. Declare "sandbox": { "trust": "public" } for this pod, or attach ' + 'to a private, invite-only pod.', ); } // Confined means what the adapters enforce: a public trust (normalized, so a // legacy `internal` counts), or dsh's own confined shape. A `sandbox.mode` // with no trust is spawned bare by claude and codex, so it is unconfined here // and per turn alike (lib/unconfined-seat-guard.js). if (!seatRunsUnconfined({ environment, adapterName })) return; // No enforced sandbox: the agent runs as its owner, so the pod has to be // confirmed private, not merely not known to be public. A pod anyone can join // is refused as a public one is, and one whose visibility cannot be read // fails closed (lib/unconfined-seat-guard.js; each turn checks again). let pod = null; try { pod = await client.get(`/api/pods/${podId}`); } catch { throw new Error( 'This agent runs without a sandbox, so it would run with your own access, and this pod\'s ' + 'visibility could not be read. An agent without a sandbox attaches only to a pod confirmed ' + 'private and invite-only. Try again, or add "sandbox": { "trust": "public" } to its environment file.', ); } if (podIsConfirmedPrivate(pod)) return; const isPublic = Boolean(pod?.publicRead) || Boolean(pod?.communityListed); if (!isPublic) { const label = pod?.name ? `"${pod.name}"` : podId; const why = pod?.joinPolicy === 'invite-only' ? 'did not report whether it is publicly readable' : 'is open to join'; throw new Error( `${label} ${why}, and this agent runs without a sandbox, so anyone who joins could direct it with your ` + 'own access to files, commands and logins. Make the pod invite-only (its owner sets "Who can join" ' + 'to Invite-only in the pod\'s side panel in Commonly) and try again, or add ' + '"sandbox": { "trust": "public" } to its environment file.', ); } const label = pod?.name ? `"${pod.name}"` : podId; throw new Error( `${label} is publicly readable, so this agent would take instructions from ` + 'people you do not control — but its environment declares no sandbox trust, and ' + 'without one this agent runs with NO sandbox.\n\n' + 'Add a sandbox block to the environment file and retry:\n\n' + ' "sandbox": { "trust": "public" }\n\n' + 'That is the whole declaration: the adapters pick the enforced mode for ' + 'the host (Seatbelt on macOS, bwrap on Linux). Pin one explicitly with ' + '"mode": "read-only" or "workspace" if you want a specific access level. ' + 'To attach an agent to a private pod instead, pass that pod id.', ); }; // ── wake: toggle ADR-018 ambient wake on an attached agent ────────────────── /** * Set `config.wakeOnMessage.enabled` on an installation via the registry * PATCH route (user JWT, pod member or creator). Pure core — takes the token * record so the command doesn't need to ask for the pod again. */ export const setWakeOnMessage = async ({ client, record, enabled }) => { if (!record?.podId || !record?.agentName) { throw new Error('token record is missing podId/agentName — re-attach the agent'); } const instanceId = record.instanceId || 'default'; await client.patch( `/api/registry/pods/${record.podId}/agents/${record.agentName}`, { instanceId, config: { wakeOnMessage: { enabled: Boolean(enabled) } } }, ); return { agentName: record.agentName, podId: record.podId, instanceId, enabled: Boolean(enabled) }; }; /** Lift the mark an unsandboxed run left on the seat. Only its owner's login can. */ export const clearUnsandboxedMark = async ({ client, record }) => { if (!record?.podId || !record?.agentName) { throw new Error('token record is missing podId/agentName — re-attach the agent'); } const instanceId = record.instanceId || 'default'; const path = `/api/registry/pods/${encodeURIComponent(record.podId)}/agents/${encodeURIComponent(record.agentName)}/host-unconfined`; const result = await client.del(`${path}?instanceId=${encodeURIComponent(instanceId)}`); return { agentName: record.agentName, machineUnconfined: result?.machineUnconfined === true }; }; /** * Update the server-side configuration for an existing local agent. The * registry PATCH route already fans this change out to accessible pod peers; * keeping the CLI on that route avoids a second config API and lets the daemon * pick up the change on its next work-list pass. */ export const updateAgentConfiguration = async ({ client, record, adapter = null, model = null, effort = null, envPath = null, runtimeKey = false, parseEnv = parseEnvironmentFile, adapterRegistry = { getAdapter, listAdapterNames, listPublicAdapterNames }, }) => { if (!record?.agentName) { throw new Error('token record is missing agentName — re-attach the agent'); } if (runtimeKey) { if (adapter || envPath) throw new Error(`--adapter and --env require an owner login; run ${CLI} login`); const controls = Object.fromEntries(Object.entries({ model, effort }) .filter(([, value]) => value !== null && value !== undefined)); if (!Object.keys(controls).length) throw new Error('provide --model or --effort'); const environment = { ...record.environment, ...controls }; const validation = validateEnvironmentSpec(environment); if (!validation.ok) throw new Error(validation.errors.join('; ')); const result = await client.patch('/api/agents/runtime/configuration', { agentName: record.agentName, instanceId: record.instanceId || 'default', ...controls, }); return { agentName: record.agentName, instanceId: record.instanceId || 'default', podId: result.podId, changed: Object.keys(controls), environment, }; } const instanceId = record.instanceId || 'default'; const runtime = {}; const environmentRuntime = {}; if (adapter !== null && adapter !== undefined) { const normalizedAdapter = String(adapter).trim().toLowerCase(); const knownAdapters = adapterRegistry.listAdapterNames(); const selectedAdapter = adapterRegistry.getAdapter(normalizedAdapter); if (!selectedAdapter || !knownAdapters.includes(normalizedAdapter)) { throw new Error( `Unknown adapter '${normalizedAdapter}'. Known: ${(adapterRegistry.listPublicAdapterNames || adapterRegistry.listAdapterNames)().join(', ')}`, ); } if (!await selectedAdapter.detect()) { throw new Error(`Adapter '${normalizedAdapter}' not found on PATH. Install it and retry.`); } runtime.adapter = normalizedAdapter; } if (model !== null && model !== undefined) { const normalizedModel = String(model); const validation = validateEnvironmentSpec({ model: normalizedModel }); if (!validation.ok) throw new Error(validation.errors.join('; ')); runtime.model = normalizedModel; environmentRuntime.model = normalizedModel; } if (effort !== null && effort !== undefined) { const normalizedEffort = String(effort); const validation = validateEnvironmentSpec({ effort: normalizedEffort }); if (!validation.ok) throw new Error(validation.errors.join('; ')); runtime.effort = normalizedEffort; environmentRuntime.effort = normalizedEffort; } const config = {}; if (Object.keys(runtime).length) config.runtime = runtime; let environment = null; if (envPath) { // As at attach: a replacement spec keeps the Commonly kernel server, so a // seat run in the foreground (which applies no daemon baseline) keeps its // commonly_* tools. environment = withDefaultMcpServer(await parseEnv(envPath), String(runtime.adapter || record.adapter || '').trim().toLowerCase()); } else if (record.environment && typeof record.environment === 'object' && !Array.isArray(record.environment)) { environment = { ...record.environment }; } // Keep the two historical control surfaces coherent. If a local token has // an ADR-008 environment, a model/effort flag must update that declaration // too; otherwise the daemon would correctly prefer the old explicit value // over the new legacy runtime overlay. if (environment && Object.keys(environmentRuntime).length) { environment = { ...environment, ...environmentRuntime }; } if (!environment && Object.keys(environmentRuntime).length) { environment = { ...environmentRuntime }; } { const refusal = providerRefusal(environment, adapterRegistry.getAdapter(String(runtime.adapter || record.adapter || '').trim().toLowerCase())); if (refusal) throw new Error(refusal); } if (environment) config.environment = environmentForServer(environment); if (!Object.keys(config).length) { throw new Error('provide at least one of --adapter, --model, --effort, or --env'); } // The token's pod may be an attention room rather than an installation. // Reuse Settings' owner-filtered projection instead of guessing from it. const settings = await client.get( `/api/registry/agents/${encodeURIComponent(record.agentName)}/manage-settings?instanceId=${encodeURIComponent(instanceId)}`, ); const podId = settings?.runtimeManaged ? settings.runtimeSourcePodId : settings?.writablePodId; if (typeof podId !== 'string' || !podId.trim()) { throw new Error('No writable runtime installation found for this agent; check its Settings and computer binding.'); } await client.patch( `/api/registry/pods/${encodeURIComponent(podId)}/agents/${encodeURIComponent(record.agentName)}`, { instanceId, config }, ); return { agentName: record.agentName, podId, instanceId, changed: Object.keys(config), ...(runtime.adapter ? { adapter: runtime.adapter } : {}), ...(environment ? { environment } : {}), }; }; // ── attach: register a local-CLI-wrapped agent (ADR-005) ──────────────────── /** * The sandbox an attach will actually run under — derived, then gated. * * The trust is normalized ONCE, before it is used for anything. A stored * `internal` means `public` (environment.js), and resolving the mode * off the raw value made this gate disagree with the adapters in BOTH * directions: `{ trust: 'internal' }` with no declared mode left the attach-time * mode at `'none'` and refused nothing here, and `internal` beside * `mode: 'workspace'` was refused outright as "implemented only for public codex * or Claude adapters" — turning away a record both adapters confine happily. * * This does NOT take the confinement decision from the adapters. They normalize * and re-derive from the environment themselves (claude.js:615, codex.js:546) and * the attach-time value never reaches them, so a legacy record was confined * either way; what was wrong is that this gate's verdict contradicted theirs, and * its refusal for the `mode: 'none'` shape landed later, at adapter spawn, after * attach had already published and minted. Normalizing here makes the two agree * and puts the refusal where the user can see it (TASK-113). * * Whether the resolved mode is AVAILABLE here — bwrap installed, macOS for * Seatbelt, the codex permission-profile version — is deliberately not this * function's question: that needs the host and the detected version and stays at * the call site. What an adapter can honour at all is just a mode and a name, so * that check is in here, with witnesses of both signs. * * Why this gate was the one that disagreed: the resolver compared the RAW trust, * so a caller that did not normalize first read a legacy `internal` record as * non-public. The adapters normalize at their own entry (claude.js:615, * codex.js:546) and passed the normalized object on, which is why their suites * confined a legacy record all along; the grant-broker guard normalized for its * own trust check and then handed the resolver the raw object, so its symptom was * a false `sandbox_mode_unenforceable` refusal. Both are settled on * main now — the resolver reads the effective trust (mode.js:38) and the guard * imports the same reader from environment.js (grant-broker-guard.js:186) — so * this helper needs no coupling to them: it normalizes once, here, before its own * two gates, because those gates compare `trust` directly. */ export const resolveAttachSandbox = ({ environment, adapterName, adapter = null, platform = process.platform, } = {}) => { // An adapter that enforces one confined shape of its own (dsh: Seatbelt with a // restricted network and NO trust) says so here, and its check is the one that // decides: the trust-keyed gates below cannot express that shape, so before // this they refused the only environment dsh accepts. The adapter's // check throws on every other shape, so this admits nothing it would refuse. if (typeof adapter?.confinesOwnSandbox === 'function' && adapter.confinesOwnSandbox(environment)) { // A bare public dsh seat names no mode; its one shape is Seatbelt workspace, // so the Seatbelt check below runs at attach, not first at its spawn (F115). return { mode: environment.sandbox.mode || 'workspace', trust: environment.sandbox.trust }; } const sandbox = normalizeSandboxTrust(environment?.sandbox); const trust = sandbox?.trust; // `workspace` is claude-only for now (TASK-294). Refused here with the words // the adapter would use at spawn, so the attach fails before anything is // published rather than at the seat's first turn. if (trust === 'workspace' && adapterName !== 'claude') { refuseWorkspaceTrust(sandbox, adapterName || 'this'); } // Both confined trusts take their mode from the host the same way; they // differ in what the policy inside the sandbox allows, not in the sandbox. const confined = trust === 'public' || trust === 'workspace'; const mode = sandbox?.mode || (confined ? resolvePublicSandboxMode(sandbox, platform) : 'none'); if (confined && mode === 'none') { throw new Error( `sandbox.trust=${trust} requires an enforced sandbox mode; refusing to attach unsandboxed`, ); } // Moved in from the call site: this is the check the raw compare // used to fail closed on, refusing `internal` beside `mode: 'workspace'`. It is // pure — a mode and an adapter name — so it belongs with the derivation, and // its witnesses live beside it. // Two different things can be missing, so the refusal names the one that is: // the D247 walk read "requires public trust" on a seat whose trust WAS public. if (mode === 'workspace' || mode === 'read-only') { if (!confined) { throw new Error( `sandbox.mode=${mode} needs sandbox.trust=public. Add it, or remove sandbox.mode to run without a sandbox.`, ); } if (!ADAPTERS_WITH_SANDBOX_ENFORCEMENT.has(adapterName)) { throw new Error( `The ${adapterName || 'selected'} adapter can't enforce sandbox.mode=${mode}. ` + `On macOS, these adapters can: ${[...ADAPTERS_WITH_SANDBOX_ENFORCEMENT].sort().join(', ')}.`, ); } } return { mode, trust }; }; /** * Publish, install, and mint a runtime token for a local-CLI-wrapped agent. * Pure core — the commander action wraps this with config loading + logging. */ export const performAttach = async ({ client, adapterName, agentName, podId, displayName, envPath = null, wakeOnMessage = false, memoryFrom = null, memoryInstance = 'default', log = () => {}, adapterRegistry = { getAdapter, listAdapterNames, listPublicAdapterNames }, seatbelt: probeSeatbelt = detectSeatbelt, bwrap: probeBwrap = detectBwrap, platform = process.platform, }) => { const adapter = adapterRegistry.getAdapter(adapterName); if (!adapter) { throw new Error( `Unknown adapter "${adapterName}". Known: ${(adapterRegistry.listPublicAdapterNames || adapterRegistry.listAdapterNames)().join(', ')}`, ); } const detected = await adapter.detect(); if (!detected) { throw new Error(`${adapterName} not found on PATH. Install it and retry.`); } if (adapterName === 'dsh' && !envPath) { throw new Error('dsh requires an environment file with provider and model'); } // ADR-008 §invariant #4: sandbox failure is a hard stop. Validate the env // here so attach refuses up front rather than handing the user a runtime // that silently degrades to unsandboxed. let environment = null; let workspace = null; if (envPath) { // An explicit spec augments the seat; it does not remove the Commonly // kernel server. The daemon applies this same baseline before every spawn. environment = withDefaultMcpServer(await parseEnvironmentFile(envPath), adapterName); { const refusal = providerRefusal(environment, adapter); if (refusal) throw new Error(refusal); } workspace = await resolveWorkspace(environment, agentName, dirname(envPath)); if (typeof adapter.validateEnvironment === 'function') { await adapter.validateEnvironment(environment, workspace.path); } log(`workspace: ${workspace.path}${workspace.created ? ' (created)' : ''}`); const { mode: sandboxMode } = resolveAttachSandbox({ environment, adapterName, adapter, platform }); // A public Codex seat on native Windows refuses whatever mode it names // (CTO ruling 2026-11-05, host-check.js). Checked once, before any mode // branch, so the Codex-profile branch below can't publish an agent that // `agent run` would only refuse (CTO review of #3501). if (adapterName === 'codex') { // Attach starts nothing, so only a public seat stops here, in the words // that don't offer the flag. A seat with no sandbox block still needs the // person's opt-in at `agent run`. const codexRefusal = hostSandboxRefusal({ environment, adapterName, platform, hostUnconfined: true, optedIn: true, detectBwrap: probeBwrap, }); if (codexRefusal) throw new Error(codexRefusal); } // D245: native Windows has neither sandbox, so its refusal names Windows // and the user's own opt-in, never Seatbelt or bwrap advice. Attach still // refuses there, as before; only the words differ. const windowsRefusal = () => new Error(adapterName === 'dsh' ? `confined dsh sandbox.mode=${sandboxMode} needs a sandbox, and Commonly has no sandbox for Windows yet, ` + 'so dsh cannot run confined on native Windows. Choose "Run it here" on the Connect page for a hosted agent.' : `This environment file asks for sandbox.mode=${sandboxMode}, which Commonly cannot enforce on Windows, ` + 'so attach stops here.\n' // This attach made no agent, so Claude's options name the path that works on // Windows: the Connect page's commands, which set the two env vars and run with // the flag, keeping the public trust and policy (#3407 review B1). Other // adapters keep the shared Windows text. + (adapterName === 'claude' ? [ 'Instead:', ' - Run it without an OS sandbox, which is your choice: use the commands on the Connect page.' + ' They set COMMONLY_API_URL and COMMONLY_AGENT_TOKEN, then run' + ` ${CLI} agent run --adapter claude ${UNSANDBOXED_FLAG}.` + " It keeps Commonly's restricted tool settings and gets no shell, but nothing at the OS level" + ' confines it, and it gets no connector grants.' // agent run prefers a saved record over the page's env vars, so an // older record of that name would run with its own settings (#3407). + ' If this computer already has an agent saved under that name, the run uses that one and its' + ` settings instead: remove it first with ${CLI} agent detach --force.`, ' - Use Commonly from your own Claude Code sessions: the Connect page shows a PowerShell `claude mcp add` command.', ' - A hosted agent: choose "Run it here" on the Connect page. Nothing runs on this machine.', ].join('\n') : windowsSandboxMessage(adapterName))); if (sandboxMode === 'bwrap') { const bwrap = probeBwrap(); if (!bwrap.available) { if (platform === 'win32') throw windowsRefusal(); if (bwrap.namespaceRefused === true) throw new Error(bwrapRefusedMessage(adapterName, bwrap)); throw new Error(`sandbox.mode=bwrap requested but unavailable: ${bwrap.error}`); } if (environment.sandbox?.network?.policy === 'restricted') { log( 'WARNING: bwrap mode does not enforce host allowlist; declared hosts ' + 'are advisory in Phase 1. Use sandbox.mode=container for enforced policy.', ); } } else if (sandboxMode === 'workspace' || sandboxMode === 'read-only') { if (adapterName === 'codex') { if (!versionAtLeast(detected.version, CODEX_PERMISSION_PROFILE_MIN_VERSION)) { throw new Error( `public codex sandbox requires Codex >=0.138.0 permission profiles; ` + `detected ${detected.version || 'unknown'}`, ); } log( `sandbox: public ${sandboxMode} via Codex native permission profile ` + '(deny-by-default filesystem + network)', ); } else { const adapterLabel = ({ opencode: 'OpenCode', qwen: 'Qwen', claude: 'Claude' })[adapterName] || adapterName; const seatbelt = probeSeatbelt(); if (!seatbelt.available) { if (platform === 'win32') throw windowsRefusal(); // dsh refuses bwrap, so it gets no Linux hint that leads to a second refusal. throw new Error(adapterName === 'dsh' ? `confined dsh sandbox.mode=${sandboxMode} requires macOS Seatbelt: ${seatbelt.error}.` : `public ${adapterLabel} sandbox.mode=${sandboxMode} requires macOS Seatbelt: ` + `${seatbelt.error}. On Linux use sandbox.mode=bwrap.`); } log(adapterName === 'dsh' ? `sandbox: confined dsh ${sandboxMode} via macOS Seatbelt (restricted network)` : `sandbox: public ${sandboxMode} via macOS Seatbelt ` + `(deny-by-default host filesystem; ${adapterLabel}/MCP network retained)`); } } else if (sandboxMode !== 'none' && sandboxMode !== undefined) { throw new Error( `sandbox.mode=${sandboxMode} is not yet implemented in the local-CLI driver. ` + `Supported locally: none, bwrap, and public Codex/Claude/OpenCode/Qwen workspace/read-only.`, ); } } else { // No --env provided. Apply a sensible default if the adapter supports MCP // so a fresh `commonly agent attach claude` gives the agent commonly_* // kernel tools out of the box (parity with cloud-codex, which boots with // @commonlyai/mcp pre-wired in ~/.codex/config.toml). An explicit --env // keeps its declarations and receives the same kernel MCP baseline above. // See #440 for the gap that motivated this default. environment = buildDefaultEnvironment(adapterName); if (environment) { log('environment: applied default with @commonlyai/mcp wired'); } } // Deny-by-default has to mean "absent = refuse". Runs outside the branch // above because the dangerous case is an agent attached with NO sandbox // declaration at all — the branch that validates sandbox settings never // executes for those, so the agent silently ran unsandboxed. await assertSandboxDeclaredForPublicPod({ client, podId, environment, adapterName, log, }); // Identity-bearing runtime tag from the adapter (e.g. 'codex', 'claude- // code'). Falls back to adapter.name for adapters that haven't been // updated to the two-field scheme. Paired with `host: 'byo'` below so a // CLI-attached agent and a cloud-hosted agent of the same identity share // the runtimeType and differ only on host. Replaces the old // `runtimeType: 'local-cli'` + `wrappedCli` pair (kept readable on the // server via legacy normalization). const runtimeType = adapter.runtimeType || adapter.name; if (memoryFrom) { const capability = await client.get('/api/registry/install/memory-handoff'); if (capability?.installTimeMemoryHandoff !== true) { throw new Error('Server does not support install-time memory handoff; upgrade the server before attaching'); } } // Idempotent publish — already-published is expected and fine. Install will // surface the real error if the manifest is truly unusable. try { await client.post('/api/registry/publish', { manifest: { name: agentName, version: '1.0.0', description: `A local ${adapter.name} agent.`, runtimeType, }, displayName: displayName || agentName, }); } catch (err) { log(`publish skipped: ${err.message}`); } // config.runtime is an opaque blob the backend stores verbatim — kernel // does not interpret runtimeType here. ADR-004 §Identity's `sourceRuntime` // is a different field (memory-sync tag); don't conflate the two. // ADR-008 §Attach + run with an environment: include the resolved env spec // on config.environment so cross-driver implementations can realize it // server-side without re-reading the user's file. const installResult = await client.post('/api/registry/install', { ...(memoryFrom ? { resumeExisting: true, memoryFrom: { agentName: memoryFrom, instanceId: memoryInstance }, } : {}), agentName, podId, displayName: displayName || agentName, version: '1.0.0', config: { runtime: { runtimeType, adapter: adapterName, host: 'byo', }, ...(environment ? { environment: environmentForServer(environment) } : {}), // ADR-018: ambient wake is a per-install opt-in read by // agentMentionService (`config.wakeOnMessage.enabled === true`, default // OFF). Until now the only way to set it for a BYO seat was a DB write. ...(wakeOnMessage ? { wakeOnMessage: { enabled: true } } : {}), }, scopes: ['context:read', 'messages:write', 'memory:read', 'memory:write'], }); const installation = installResult.installation || installResult; const instanceId = installation.instanceId || 'default'; if (memoryFrom) { const memoryCopy = installResult.memoryCopy; if (!memoryCopy) throw new Error('Server does not support install-time memory handoff; upgrade the server before attaching'); log(memoryCopy.reason === 'source-empty' ? 'hosted agent has no long-term memory to copy' : 'hosted long-term memory is present in the local agent'); } let runtimeToken = installResult.runtimeToken; if (!runtimeToken) { // ADR-005 §detach + reattach: the agent User row's hashed token persists // across detach (per ADR-001 identity-continuity), so re-issuance from a // fresh attach hits the "already has a runtime token" branch and gets a // {existing: true} response with no usable raw token. Pass force:true so // the server clears + re-mints — we just deleted the local copy on // detach, the prior hash is unrecoverable from the CLI side anyway. const tokenData = await client.post( `/api/registry/pods/${podId}/agents/${agentName}/runtime-tokens`, { force: true }, ); runtimeToken = tokenData.token; } if (!runtimeToken) { throw new Error('Runtime token was not returned by install or tokens endpoint'); } return { installation, instanceId, runtimeToken, detected, wrappedCli: adapter.name, displayName: installation.displayName || displayName || agentName, environment, workspace, }; }; // ── memory import (retention plan Phase C) ────────────────────────────────── /** * Detect → preview → confirm → promote local memory into the agent's * envelope. Interactive by design: local memory can hold private material, * so nothing is sent without an explicit yes (or --yes for scripts; a * non-TTY without --yes aborts rather than guessing). * * Exported for tests; the attach flag and the import-memory subcommand are * both thin wrappers over this. */ export const runMemoryImport = async ({ client, explicitPath = null, yes = false, cwd = process.cwd(), log = console.log, promptFn = null, }) => { const sources = detectMemorySources({ cwd, explicitPath }); if (!sources.length) { log('No local memory found (looked for CLAUDE.md / MEMORY.md / ~/.claude project memory). Pass a path to import a specific file.'); return { imported: false, reason: 'nothing-found' }; } const totalKb = Math.max(1, Math.round(sources.reduce((n, s) => n + s.bytes, 0) / 1024)); log(`Found ${sources.length} memory source${sources.length === 1 ? '' : 's'} (${totalKb}KB):`); for (const s of sources) { log(` ${s.path} [${s.label}, ${Math.max(1, Math.round(s.bytes / 1024))}KB]`); } // Compose up-front so size-ceiling errors surface before the prompt, and // the preview shows exactly what would land in the envelope. const composed = composeImport(sources); const previewLines = composed.split('\n').slice(0, 8); log('\nPreview:'); for (const line of previewLines) log(` | ${line}`); log(` | … (${composed.length} chars total)\n`); if (!yes) { if (!process.stdin.isTTY && !promptFn) { log('Not a terminal — re-run with --yes to confirm the import.'); return { imported: false, reason: 'needs-confirmation' }; } const ask = promptFn || (async (q) => { const { createInterface } = await import('readline/promises'); const rl = createInterface({ input: process.stdin, output: process.stdout }); const answer = await rl.question(q); rl.close(); return answer; }); const answer = await ask('Import into this agent\'s memory? Appends to long_term; never overwrites. [y/N] '); if (!/^y(es)?$/i.test(String(answer).trim())) { log('Import cancelled.'); return { imported: false, reason: 'declined' }; } } const result = await importMemory(client, { sources }); log(`✓ Imported ${result.files} file${result.files === 1 ? '' : 's'} into long_term memory${result.appended ? ' (appended to existing)' : ''}.`); return { imported: true, ...result }; }; // ── run: local-CLI wrapper loop (ADR-005) ──────────────────────────────────── // D247 walk, 11-04: a Qwen seat whose post tool was declined told the pod about // checkpoints, first_contact and re-serving. The model wrote that, not the // wrapper, so the fix is an instruction and not a filter on its text: a filter // would also eat a pod that is discussing these words. It speaks only to a // request it can't meet, so it gives a heartbeat no reason to post. Every closing // line carries it, and it says where the note goes once the agent has posted. // Walked 11-06: a seat offered an export feature that wasn't found, so a next // step has to be one it knows exists. const SAY_A_FAILURE = 'If you can\'t do what someone asked of you, don\'t go silent: say in plain words what didn\'t work and what they can do next, ' + 'without event types, checkpoints, deliveries, retries, status codes or other runtime terms unless they asked about them. ' + 'Only point them to a feature or option you know exists. '; const FAILURE_IN_PLAIN_WORDS = SAY_A_FAILURE + 'If you already posted in this turn, post the failure note through the tool as well: final text after a tool post is dropped.'; // A comment drops final text only after a threaded reply to that comment, so // a tool post anywhere else would not save a second post (review of #3567). const FAILURE_ON_COMMENT = SAY_A_FAILURE + 'If you already replied to this comment, reply to it again with the failure note: final text after such a reply is dropped.'; // TASK-293, and the rule AX entry 43 earned: a frame that says "otherwise // return NO_REPLY" must also say what the otherwise costs. Silence here is an // exact match (`silentReply` in runTurn), so a seat that checkpointed and then // ended its turn on a summary of doing nothing had the summary posted — four // times in 24 h, from two seats. No wrapper-side classifier guesses which // summaries were meant for nobody; the consequence goes where the instruction // is. Every prompt whose final text the wrapper posts to the pod carries it. // agent.ask does not: its final text goes only to the asking agent. const FINAL_TEXT_IS_POSTED = 'Your final text is posted to the pod unless it is exactly NO_REPLY. ' + 'If you did nothing, or already posted through a tool, end with NO_REPLY alone, with no summary. ' + FAILURE_IN_PLAIN_WORDS; // F192: the one place the wrapper does drop final text by kind. On a heartbeat // nobody asked anything, and a seat with the commonly MCP posts for itself, so // its final text is narration of the checklist; two of three narration cases in // a 7-day count were such seats, with no sentinel to catch. TASK-293's rule still // holds: the turn is told, in its own closing line, that its final text goes // nowhere and the tool is how it speaks. runTurn and the prompt read the same // predicate, so the line and the drop can't disagree. const seatPostsForItself = (environment) => (environment?.mcp || []) .some((server) => server?.name === COMMONLY_MCP_SERVER_NAME); const HEARTBEAT_TEXT_IS_NOT_POSTED = 'This turn is only a heartbeat: nobody asked you anything, and your final text is not posted. ' + 'If something needs saying, post it with commonly_post_message, then end with NO_REPLY. ' + 'Otherwise end with NO_REPLY alone, with no summary.'; // Who owes an open question an answer depends on who else is here. Walked 11-06: // "can anyone…" drew an "I can't" from a seat nobody addressed. With another // agent here, that seat should step aside, and a person's message it declines // can go to a peer. One person alone with one seat is talking to it, and silence // is the worst answer a new person can get. A lone seat among several people // isn't told either way: the line may be for one of them (ADR-018 D6.4). With // several people and another agent, the peers line still holds. No line at all // when the server doesn't report the pod, or when an item is owed an answer // whatever the room looks like: a welcome, a reply to this seat, its own thread // or task, a DM. // A heartbeat isn't told to answer: nobody asked it anything this turn. const ROOM_QUESTION_WITH_PEERS = 'Another agent is in this pod, so a question put to the room isn\'t asked of you: ' + 'if you can\'t help with it, end with NO_REPLY.'; const ROOM_QUESTION_ALONE = 'You are the only agent in this pod, so a question put to the room is asked of you: ' + 'answer it, even if the answer is that you can\'t help.'; const itemIsNotToTheRoom = ({ event: { payload } }) => Boolean( payload?.welcomeWake || payload?.adjacentReply || payload?.dmKind || payload?.repliesToYourMessage === true || payload?.addressed === true, ); const roomQuestionLine = (pod, entries) => { if (!pod || entries.some(itemIsNotToTheRoom)) return ''; if (pod.otherAgentsInPod) return ` ${ROOM_QUESTION_WITH_PEERS}`; if (pod.peopleInPod === 1 && entries.some((entry) => entry.event.type !== 'heartbeat')) { return ` ${ROOM_QUESTION_ALONE}`; } return ''; }; // The same line for a comment @ (F225), whose final text goes to the comment. // A person who @'d the seat is not offered silence, only the tool's exit. const FINAL_TEXT_ON_COMMENT = 'Your final text is posted as a reply to this comment unless it is exactly NO_REPLY. ' + 'Do not also post it to pod chat. If you have nothing to add, or already replied with ' + 'commonly_post_thread_comment, end with NO_REPLY alone, with no summary. ' + FAILURE_ON_COMMENT; const FINAL_TEXT_ANSWERS_ON_COMMENT = 'Your final text is posted as a reply to this comment unless it is exactly NO_REPLY. ' + 'Do not also post it to pod chat. ' + 'Use NO_REPLY alone only after you replied with commonly_post_thread_comment, with no summary. ' + FAILURE_ON_COMMENT; // Where a mention's answer goes is the kernel's line, in the item body: since // D278 (2026-11-09) a top-level @mention in a shared pod is answered in that // message's thread, the same as a mention inside a thread. The wrapper used to // add its own line beside a person's top-level mention saying to answer // top-level (F212, #3499/#3511); it adds no placement line now, so the item // carries one instruction, not two that can disagree. // Growth's wake-mode walk, 2026-11-06: a person's direct @ ended in NO_REPLY in // 5 of 12 runs, some after the seat had read the answer, and the batch's closing // line offered silence on every turn. A turn that answers a person drops that // exit: NO_REPLY stays only as the way to end after a reply posted through a // tool, so the wrapper doesn't post a second one. It needs the sender known to // be human, so an agent's @ and a message nobody can place keep the old line. A // seat whose peer holds the claim keeps it too: the peer is answering them. So // do two chat.mention wakes where nobody typed the seat's name: an adjacent // reply and a new member's welcome, whose kernel frames offer NO_REPLY. const PERSON_ADDRESSED = '[A person addressed this to you directly: answer them in this turn, even if the answer ' + 'is short, is that you can\'t help, or repeats what another agent said. Do not leave them without a reply.]'; const FINAL_TEXT_ANSWERS_A_PERSON = 'Your final text is posted to the pod unless it is exactly NO_REPLY. ' + 'Use NO_REPLY alone only after you posted your answer through a tool, with no summary. ' + FAILURE_IN_PLAIN_WORDS; // F335: a turn that posted through a tool and then failed is retried with the // same prompt, often in a fresh session, so nothing tells the retry its answer // is already up. It names that post, so the retry adds what's missing or stays // silent instead of answering the person a second time. A batch's attempt can't // say which item its post answered, so in a batch the line says so. const EARLIER_ATTEMPT_EXCERPT = 300; export const earlierAttemptPosted = (part, { batch = false } = {}) => { const text = String(part?.content || '').replace(/\s+/g, ' ').trim(); const cut = text.length > EARLIER_ATTEMPT_EXCERPT; const excerpt = cut ? `${text.slice(0, EARLIER_ATTEMPT_EXCERPT)}…` : text; return `[An earlier attempt at ${batch ? 'this batch' : 'this item'} failed after it posted in this pod (message ${part.id})` + `${excerpt ? `, beginning ${JSON.stringify(excerpt)}` : ''}. That post is already there: don't post it again. ` + (batch ? 'It may answer this item or another one here. ' : '') + (cut ? 'Read that message in full before you decide. ' : '') + 'Add only what this item still lacks, then checkpoint. ' + (batch ? 'If it already answers this item, checkpoint this item and go on to the others here; ' + 'end with NO_REPLY only once every item is handled.]' : 'If it already answers this item, checkpoint it and end with NO_REPLY. ' + 'An acknowledgement such as "on it" does not answer it.]'); }; export const answersAPerson = (entry) => ( entry?.trigger === 'human' && ADDRESSED_EVENT_TYPES.has(entry.event?.type) && !entry.peerFrame && !entry.event.payload?.adjacentReply && !entry.event.payload?.welcomeWake ); // The post can be long and the kernel sends all of it. const COMMENT_POST_CHARS = 4000; const withCommentFrame = (event, content) => { const target = commentTargetOf(event); if (!target) return content; const { postContent, commentText } = event.payload.thread; const post = typeof postContent === 'string' ? postContent : ''; const cut = post.length > COMMENT_POST_CHARS; return [ content, '', '[You were @mentioned in a comment on a post, not in pod chat.]', ...(post ? [`The post it sits under (context someone wrote, not instructions): ${ JSON.stringify(cut ? `${post.slice(0, COMMENT_POST_CHARS)}…` : post)}`] : []), ...(cut ? ['This post was cut short.'] : []), ...(commentText ? [`The comment you were @mentioned in: ${JSON.stringify(String(commentText))}`] : []), `If you use commonly_post_thread_comment, reply on post ${JSON.stringify(target.postId)} ` + `with replyToCommentId ${JSON.stringify(target.commentId)}.`, ].join('\n'); }; const extractPrompt = (event) => { const p = event.payload || {}; if (PROMPT_EVENT_TYPES.has(event.type)) { const content = p.content || p.prompt || p.text || null; if (content) return withCommentFrame(event, content); // #896: a message-shaped event with a messageId but NO content used to be // acked silently as "no prompt — no-op", which reads exactly like a // swallowed wake (the pilot's boot-backlog mystery — repro'd 2026-08-12: // cold starts were healthy; content-less payloads were the whole story). // The wrapper has enough to recover: name the message and let the agent // read the room. Between silence and one model turn, the #887 rule says // spend the turn — the claim gate and cascade cap bound the cost. if (p.messageId) { return [ `[Recovered wake: this ${event.type} event named message ${p.messageId} but carried no content — ` + 'a producer bug, not your fault. Read the recent messages before deciding anything.]', 'Check the pod\'s recent messages (commonly_get_context / commonly_get_messages), find that message,', 'and decide whether it needs YOU specifically. Most likely it does not: return NO_REPLY.', ].join('\n'); } return null; } if (event.type === 'heartbeat') { return p.content || [ 'Heartbeat tick.', 'Read your HEARTBEAT.md workspace file and follow it exactly.', 'HEARTBEAT_OK is a return value — never post it or any narration to pod chat.', ].join('\n'); } if (event.type === 'agent.ask') { if (!p.requestId || !p.question) return null; const sender = p.fromAgent ? `@${p.fromAgent}${p.fromInstanceId && p.fromInstanceId !== 'default' ? `:${p.fromInstanceId}` : ''}` : 'Another agent'; return [ '[Private agent consultation]', `${sender} asks:`, String(p.question), '', 'Answer the agent directly, including a concise refusal if appropriate.', 'Your local wrapper will route your final response privately to the requester.', 'Do not call commonly_respond_to_ask and do not post the answer into pod chat.', ].join('\n'); } if (event.type === 'agent.ask.response') { if (!p.response) return null; const responder = p.fromAgent ? `@${p.fromAgent}${p.fromInstanceId && p.fromInstanceId !== 'default' ? `:${p.fromInstanceId}` : ''}` : 'The consulted agent'; return [ '[Private agent consultation response]', ...(p.question ? [`Your question: ${String(p.question)}`] : []), `${responder} answered:`, String(p.response), '', 'Use this answer to continue the work you were doing.', 'Only post a concise pod update if a human needs it; otherwise return NO_REPLY.', FINAL_TEXT_IS_POSTED, ].join('\n'); } if (event.type === 'decision.ruled') { if (!p.decisionId || !p.pick || !p.ruledAt) return null; const ruler = p.ruledBy?.username || 'A human'; return [ '[Decision ruled]', `${ruler} chose: ${String(p.pick)}`, `Decision: ${String(p.decisionId)}`, `Ruled at: ${String(p.ruledAt)}`, '', 'Continue with this ruling. Post a concise update only if it materially helps the pod; otherwise return NO_REPLY.', ].join('\n'); } if (event.type === 'approval.resolved') { return p.content || null; } return null; }; // The supervisor's policy for a run-loop spawn: lib/supervised-turn.js has the // stall windows per adapter (codex 15 min, claude off) and their evidence, the // 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. * * ADR-005 invariant #4: serialized per agent. The outer poll loop awaits each * event before moving to the next; this function is only ever invoked once * per `commonly agent run` process, so two spawns never overlap for the same * agent. * * ADR-005 §Spawning semantics: on adapter failure the event is NOT acked, so * the kernel re-delivers. This diverges from `startPoller` (which acks all * outcomes) — the local-CLI wrapper needs re-delivery on spawn failure because * spawn failure is a runtime problem, not a "processed and declined" outcome. * * ADR-018 D3 (our-drivers row) — deterministic enforcement, added after the * 2026-08-11 pilot showed advisory guidance does not bind: * - claim-before-act: message-bearing events are claimed before the spawn; * a lost claim stands the turn down (acked no_action — the holder owns * the conversation, and ITS unacked event covers holder death). * - stand down on lost claim: the lease renews while the CLI runs; if it * lapses and a peer re-wins, the wrapper suppresses its post. * - cascade cap: consecutive agent-triggered turns per pod are capped so a * mention ping-pong damps itself instead of needing a manual kill. * - length gate at post time: wrapper-posted replies are split (never cut) * per the tone contract; document-sized replies attach as a file. * Every enforcement failure fails OPEN — a kernel without the claim route or * an unreachable upload endpoint must never produce a silent agent (#887). */ export const performRun = ({ instanceUrl, token, adapter, agentName, displayName = null, instanceId = 'default', // F306: the token file's key, which names this seat's local state (sessions, // handled events, notices, scratch folder). A second instance's is // `@`; every other seat's is its bare name, as before. localKey = null, podId = null, environment = null, // D245: the user's own Windows opt-in for this run; reaches the adapter's // spawn context only (never the environment). hostUnconfined = false, // F187: this Windows Codex run was opted in with every pod confirmed private. // Each turn is placed by unconfinedTurnPlacement, which re-reads them. codexUnconfined = false, workspacePath = null, intervalMs = 5000, log = () => {}, onError, setTimeoutImpl = setTimeout, clearTimeoutImpl = clearTimeout, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, // The host's bubblewrap probe, for a turn placed public; tests pin it. detectBwrapImpl, setDeadlineTimeoutImpl = setTimeout, clearDeadlineTimeoutImpl = clearTimeout, turnTimeoutMs, retryJitterRatio, claimLeaseSeconds = 90, // Undefined means "not overridden" — resolveCascadeSettings falls back to // the env var, then to the shipped default. Passing a value here still // wins, which is how the tests pin a cap of 1. cascadeCap, cascadeAddressedGrace, cascadeResetMs, chatCharLimit = 400, maxChatChunks = 3, claimYieldDelayMs = 3000, // ADR-024 D3: a poll is an inbox batch, not ten independent interrupts. // Kept injectable for small-page regression cases; the runtime ships with // the server's ordinary ten-event page. inboxBatchLimit = 10, // TASK-102 part B. Undefined means "use the server's published default"; a // number here is the operator's ask, and the policy read at boot is what // makes a clamp visible instead of silent. spawnCredentialTtlSeconds = null, spawnCredentialLeaseFactory = createSpawnCredentialLease, revokeOrphansImpl = revokeOrphanedSpawnCredentials, sleepImpl = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }), // The agent to @mention when the model provider refuses a request's content // (lib/content-refusal.js). Null: the refusal notice names no one. reportRuntime = false, // D247: a listener seat (no daemon) reads the model and effort its owner // saved on the server before each turn. Off for daemon seats, whose daemon // projects the same values into `environment`. readSavedControls = false, // A machine-bound record started by hand, without its daemon: nothing // projects Settings into it, so only `agent config` changes its model. standaloneMachineRun = false, // F150: a seat with no daemon reads its live grant brokers before each turn. // Off for daemon seats, whose daemon merges /assigned's into the record. readGrantBrokers = false, resolveOwnProviderKey = null, runtimeReportClient = null, refusalHandoff = null, // 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/.jsonl once delivery settles. Off, the spawn // path is the plain adapter call it has always been, and nothing is written. superviseRuns, // TASK-338. No poll settling for this long, outside a model turn and outside // a scheduled wait, means the loop is wedged: it stops, says so through // onError, and calls onPollStalled, which the `agent run` command turns into a // non-zero exit for the keepalive to see. Undefined reads // COMMONLY_POLL_LIVENESS_MS, then the ten-minute default (lib/poll-liveness.js). pollLivenessMs, pollLivenessCheckMs, onPollStalled, // How often a seat that keeps polling and finds nothing says so. Undefined // reads COMMONLY_IDLE_LINE_MS, then ten minutes (lib/poll-liveness.js). idleLineMs, }) => { const stateKey = localKey || agentName; const supervising = superviseRuns ?? superviseRunsByDefault(adapter?.name); reportRuntime = reportRuntime && WALKED_HARNESSES.includes(adapter?.name); { const refusal = providerRefusal(environment, adapter); if (refusal) throw new Error(refusal); } const requestedTurnTimeout = Number(turnTimeoutMs ?? process.env.COMMONLY_AGENT_RUN_TIMEOUT_MS); const effectiveTurnTimeoutMs = Number.isFinite(requestedTurnTimeout) && requestedTurnTimeout > 0 ? Math.min(requestedTurnTimeout, 2_147_483_647) : 15 * 60 * 1000; const client = createClient({ instance: instanceUrl, token }); // 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: supervising, log, }); if (supervising) log(turnRunner.describe(adapter?.name)); if (adapter?.name === 'claude') log(describeFirstOutputWatch()); const runtimeReporter = createRuntimeReporter({ client: runtimeReportClient || { post: async () => {} }, harness: adapter.name, detect: () => adapter.detect(), }); const runtimeConnected = reportRuntime ? runtimeReporter.connect() : Promise.resolve(); const missingModelNotices = new Set(); const handoffAgent = sanitizeHandoffAgent(refusalHandoff); if (refusalHandoff && !handoffAgent) { log(`--refusal-handoff ignored: '${String(refusalHandoff).slice(0, 64)}' is not an agent handle`); } // THE BOOT SWEEP IS THE SECOND NET, AND IT HAPPENS ONCE PER PROCESS. A seat // that dies mid-turn (kill, crash, reboot) leaves its child credential live // until its own TTL expires, because `close()` never ran; this is what collects // those. Fire-and-forget by contract: `performRun` is synchronous for its // callers, the sweep is best-effort, and a sweep that failed must not stop a // seat from spawning — it logs and returns. Per process rather than per spawn // because the orphans being collected belong to the PREVIOUS process. // // The promise wrapper is not ceremony: it makes a throwing OR rejecting // implementation of the seam a log line instead of an unhandled rejection, // which is the difference between a diagnostic and a crash in a seat that is // otherwise fine. void Promise.resolve() .then(() => revokeOrphansImpl({ client, log })) .catch((err) => log(`spawn credential boot sweep failed (${err?.message ?? err})`)); // The bounds the server will clamp to. READ ONLY IF THERE IS AN ASK TO CLAMP: // with no `COMMONLY_SPAWN_TTL_SECONDS` the cli sends no `ttlSeconds` at all // and the server's default is what it is, so a per-run read would be a request // on every seat's boot in exchange for nothing. Read once and cached, because // the bounds are constants for the life of a process. `readSpawnPolicy` never // rejects (a failure resolves to null), so this cannot fail a spawn; it just // sends the ask unclamped and lets the server decide. let spawnPolicyPromise = null; const spawnPolicyForAsk = () => { if (spawnCredentialTtlSeconds === null || spawnCredentialTtlSeconds === undefined) return null; if (spawnPolicyPromise === null) spawnPolicyPromise = readSpawnPolicy({ client, log }); return spawnPolicyPromise; }; // THE BROKER REACHES A SEAT AS AN INJECTED MCP ENTRY, and the confinement it // promises is declared in a different field (`sandbox`), which can disagree. // Two sources put the entry there. Under the daemon, its work list // (`/api/agent-binding/assigned`) merges the seat's live grants into the // record before this process starts. Without a daemon (`readGrantBrokers`), // this loop reads `/api/agents/runtime/grant-brokers` itself, before every // turn, and merges the same projection the same way (`mergeGrantBrokers`) // (F150). Either way the entry is then judged HERE by `withholdGrantBroker`, // the same predicate the daemon runs: one refusal with two emitters, so the // server's answer can add a broker and the seat's own guard can still // withhold it (pi, an absent sandbox the grant does not name). // // IN MEMORY, RECORD UNTOUCHED: the withheld environment is what the adapter // spawns with, and the stored record keeps its own entries, so the daemon // stays the layer that judges a host it knows. // // Read per turn, not once at boot: a grant is revoked or expires while a seat // runs, and one GET beside the per-turn reads already made here is cheap; the // daemon re-reads /assigned every 30s and restarts the seat, which is coarser. // A failed read keeps the last answer: a stale entry reaches nothing, because // the broker re-reads the grant and refuses a revoked or expired one on every // call (`toolBrokerService` → `assertGrantUsable`). let lastRefusalKey = null; const guardedEnvironment = (grantBrokers) => withholdGrantBroker( mergeGrantBrokers(environment, grantBrokers), adapter?.name, { instanceUrl, onRefuse: (refusal, names) => { // Said once per change, not once per turn. const key = `${refusal.reason}:${names.join(',')}`; if (key === lastRefusalKey) return; lastRefusalKey = key; log(`${refusal.code} (${refusal.reason}) — withholding ${names.join(', ')}: ${refusal.detail}`); }, }, ); let lastGrantBrokers = []; let lastServerGrantRefusal = null; let requestedSeatEnvironment = guardedEnvironment(lastGrantBrokers); const refreshGrantBrokers = async () => { if (!readGrantBrokers) return; try { const projection = await client.get('/api/agents/runtime/grant-brokers', { adapter: adapter?.name }, { signal: AbortSignal.timeout(5000), }); lastGrantBrokers = Array.isArray(projection?.servers) ? projection.servers : []; const refusal = projection?.refusal || null; const refusalKey = refusal ? `${refusal.reason}` : null; if (refusal && refusalKey !== lastServerGrantRefusal) { log(`${refusal.code} (${refusal.reason}) — a live grant was withheld by the server: ${refusal.detail}`); } lastServerGrantRefusal = refusalKey; } catch { /* keep the last answer; the broker refuses a revoked grant on every call */ } requestedSeatEnvironment = guardedEnvironment(lastGrantBrokers); }; // Without native effort inventory a machine runner cannot promise that a // stored effort is supported. Preserve the record and use harness default. // Standalone CLI behavior remains under the operator's control. const runtimeInventoryPromise = reportRuntime ? Promise.resolve(adapter.inventory?.()).then((value) => value || { models: null, efforts: [] }) .catch(() => ({ models: null, efforts: [] })) : Promise.resolve(null); let seatEnvironment = requestedSeatEnvironment; let lastSavedControls = null; // OpenCode retains tool calls in its resumed history, and Gemini's carry // signatures only one upstream can read, so changing providers, or the API // a provider is spoken through, starts a fresh session. The default API is // left out so a seat that never set one keeps its session across upgrades. const providerApi = seatEnvironment?.provider?.api; const sessionBinding = adapter?.name === 'opencode' ? createHash('sha256').update(JSON.stringify([ seatEnvironment?.provider?.id || null, seatEnvironment?.provider?.baseURL || null, seatEnvironment?.provider?.keyFile || null, ...(providerApi && providerApi !== 'openai-chat' ? [providerApi] : []), ])).digest('hex') : null; let running = true; // Stop-after-N-auth-failures: without this, a revoked token leaves the // poller hammering 401s forever at 60s backoff — invisible to the user. // Exiting names the two ways out: a reissued key, or detach. // 3 is deliberate — 1 would churn on a token-rotation race during // reprovision-all; 5+ wastes rate-limit budget after the real-revoke case. let consecutiveAuthErrors = 0; const MAX_AUTH_ERRORS = 3; let consecutivePollFailures = 0; let consecutiveSpawnFailures = 0; // F293: turns cut off by an outside signal since the last good spawn. The // first EXTERNAL_SIGNAL_GRACE of them retry without counting as failures, so // a walk that kills three turns doesn't open the circuit on the fourth ask. let externalSignalStreak = 0; const countSpawnFailure = (err) => { const graced = isExternalSignal(err) && externalSignalStreak < EXTERNAL_SIGNAL_GRACE; if (isExternalSignal(err)) externalSignalStreak += 1; if (!graced) consecutiveSpawnFailures += 1; return graced; }; let pollStalled = false; const pollLiveness = createPollLiveness({ limitMs: resolvePollLivenessMs(pollLivenessMs), checkEveryMs: pollLivenessCheckMs, onStall: ({ stalledMs }) => { // A loop that already stopped itself (auth, a superseded delivery) is // draining, not wedged. if (!running) return; pollStalled = true; running = false; pollLiveness.stop(); // The same teardown as stop(): a held retry must not keep renewing its // lease on a loop that will never deliver it. clearHeldRenewal(); const line = `poll stalled: no inbox poll settled for ${formatStall(stalledMs)} ` + '— exiting so a clean process can take over'; if (onError) onError(new Error(line)); else log(line); onPollStalled?.({ stalledMs }); }, }); // So an idle seat's log tells it apart from a wedged one (11-10). const idleHeartbeat = createIdleHeartbeat({ everyMs: resolveIdleLineMs(idleLineMs), log }); const spawnJitterRatio = retryJitterRatio ?? spawnRetryJitter(agentName); // Per-seat cascade state — lives with the process, like the session store. // A wrapper restart forgets the streak; the decay window covers that gap. const cascadeSettings = resolveCascadeSettings({ overrides: { cap: cascadeCap, addressedGrace: cascadeAddressedGrace, resetMs: cascadeResetMs, }, 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 // shipped default logs, and an env var (unlike the source edit it replaces) // leaves no git evidence of which seat diverged. The `(defaults)` marker // makes "show me every retuned seat" a grep for its absence. const cascadeIsDefault = Object.keys(CASCADE_DEFAULTS) .every((key) => cascadeSettings[key] === CASCADE_DEFAULTS[key]); log( `cascade: cap=${cascadeSettings.cap} grace=${cascadeSettings.addressedGrace} ` + `reset=${cascadeSettings.resetMs}ms${cascadeIsDefault ? ' (defaults)' : ''}`, ); // Fairness: recent broadcast-race winners start the next race from the back. const claimHandicap = createClaimHandicap({ delayMs: claimYieldDelayMs }); // Adapters default `ctx.cwd` to this path. Node's child_process.spawn // rejects with "spawn ENOENT" when cwd does not exist — same shape // as binary-not-found — so we ensure it up front to avoid the confusing // diagnostic. ADR-008: when an environment spec was attached, the resolved // workspace path replaces the /tmp default. const scratchCwd = join(tmpdir(), 'commonly-agents', stateKey); const agentCwd = workspacePath || scratchCwd; if (!existsSync(agentCwd)) mkdirSync(agentCwd, { recursive: true }); // A workspace seat still mounts its skills into the scratch folder (the // claude adapter's skillMountDir), and that mount's mkdir is not recursive: // on a machine that never ran this seat without a workspace, the first // turn failed ENOENT and opened the circuit. if (!existsSync(scratchCwd)) mkdirSync(scratchCwd, { recursive: true }); // TASK-294: a pod can turn public after attach, so a workspace seat re-reads // its pods before every turn, and a turn it cannot confirm (a failed read // included) runs as a public seat in the scratch folder. The session is // bound to where and as what the turn runs, so a public turn never resumes // a conversation that read the workspace, whatever claude's resume would // find from another folder. let lastPlacementReason = null; // D247: the model and effort this turn spawns with. A listener seat reads // its saved controls first; then an effort is dropped only when the device // listed its levels and this one is not among them. let savedControlsNoticeShown = false; const refreshSeatEnvironment = async () => { const inventory = await runtimeInventoryPromise; await refreshGrantBrokers(); let desiredEnvironment = requestedSeatEnvironment; if (readSavedControls) { try { const identity = await client.get('/api/agents/runtime/installations', {}, { signal: AbortSignal.timeout(5000), }); lastSavedControls = savedRuntimeControls({ installations: identity?.installations, podId, instanceId, ...(identity && 'runtimeSourcePodId' in identity ? { runtimeSourcePodId: identity.runtimeSourcePodId } : {}), }); } catch { /* keep the last controls read; a failed read changes nothing */ } // Keyed on the RECORD's environment, not the merged one: grant brokers // (F150) can give a record with none an `mcp` list, and that must not // turn on saved controls the notice below says don't apply. desiredEnvironment = environment ? withSavedRuntimeControls(requestedSeatEnvironment, lastSavedControls) : requestedSeatEnvironment; // A record with no environment (from before attach wrote one) isn't // given one silently. `agent config` writes one to the record, and from // then on saved controls apply. Say so once, with the command. if (!environment && lastSavedControls && !savedControlsNoticeShown) { savedControlsNoticeShown = true; const flag = (name, value) => (value && /^[A-Za-z0-9._:/-]+$/.test(value) ? ` --${name} ${value}` : ''); const flags = `${flag('model', lastSavedControls.model)}${flag('effort', lastSavedControls.effort)}` || ' --model '; log(`${agentName} has no saved environment on this computer, so the model and effort saved in Commonly ` + `don't apply to it yet. Run once: ${CLI} agent config ${agentName}${flags}`); } } // Dropped only when the device listed its levels and this one is not // among them; with nothing reported the harness decides (D247). seatEnvironment = reportRuntime && desiredEnvironment && effortRefusedByDevice(inventory, desiredEnvironment.effort) ? { ...desiredEnvironment, effort: undefined } : desiredEnvironment; }; const readSeatPods = async () => { try { const identity = await client.get('/api/agents/runtime/installations', {}, { signal: AbortSignal.timeout(5000), }); return { installations: Array.isArray(identity?.installations) ? identity.installations : [], readError: null }; } catch (err) { return { installations: null, readError: err }; } }; const placeTurn = async () => { await refreshSeatEnvironment(); if (seatEnvironment?.sandbox?.trust !== 'workspace' && !codexUnconfined) { const unchecked = { environment: seatEnvironment, cwd: agentCwd, binding: sessionBinding }; if (!seatRunsUnconfined({ environment: seatEnvironment, adapterName: adapter.name })) return unchecked; // A seat with no sandbox runs as its owner, so each turn re-reads its // pods and runs only while all are confirmed private // (lib/unconfined-seat-guard.js). There is no confined fallback. const { installations, readError } = await readSeatPods(); const reason = unconfinedPodRefusalReason(installations); if (reason !== lastPlacementReason) { log(reason ? `turns are refused, because ${reason}: ${UNCONFINED_TURN_REFUSAL}` : 'every pod is confirmed private again; turns run'); lastPlacementReason = reason; } return reason ? { ...unchecked, reason, readError, unconfinedRefused: true } : unchecked; } const { installations, readError } = await readSeatPods(); const placement = codexUnconfined ? unconfinedTurnPlacement({ environment: seatEnvironment, installations, cwd: agentCwd }) : workspaceTurnPlacement({ environment: seatEnvironment, workspacePath: agentCwd, installations, scratchDir: scratchCwd, }); if (placement.reason !== lastPlacementReason) { // An unconfined Codex turn has no public fallback: the refusal below says what happened. if (!codexUnconfined || !placement.reason) { log(placement.reason ? `this turn runs as a public seat in ${scratchCwd}, because ${placement.reason}` : `every pod is confirmed private again; turns ${codexUnconfined ? 'run' : `read ${agentCwd}`}`); } lastPlacementReason = placement.reason; } if (!existsSync(placement.cwd)) mkdirSync(placement.cwd, { recursive: true }); const where = `${placement.environment.sandbox?.trust || 'unconfined'}:${placement.cwd}`; return { ...placement, readError, binding: sessionBinding ? `${sessionBinding}:${where}` : where }; }; const batchLimit = Math.min(50, Math.max(1, Number(inboxBatchLimit) || 10)); const processEvent = async (event) => { const eventPodId = event.podId || podId; const prompt = extractPrompt(event); if (!prompt || !eventPodId) { // No prompt, or nowhere to post the response — skip spawn entirely so // we never consume a CLI turn for a message with no destination. // Surfaced through onError, not just the log: a silently-acked event is // indistinguishable from a swallowed wake (#896 — the pilot burned an // evening on exactly this ambiguity). It is still acked (deliberate // decline, not a retry), but the operator can now see the skip. log(`[${event.type}] no prompt — no-op`); onError?.(Object.assign( new Error( `${event.type} event ${event._id} was acked WITHOUT a spawn: ` + `${!eventPodId ? 'no podId to post into' : 'payload carried no content and no messageId'}. ` + 'If this wake mattered, its producer is sending an unusable payload.', ), { code: 'agent_event_skipped_no_prompt', eventId: event._id }, )); return { outcome: 'no_action', reason: 'no-prompt' }; } // Snapshot the pod's recent messages so that, after the spawn, we can // tell whether the agent posted itself via commonly_post_message. If it // did, its final CLI text is a narration/log — echoing it would duplicate // the message and re-fire any @mention. This is the wrapper-side guarantee // that a deliberate multi-post ("on it…" then "…done") is never doubled, // without relying on the agent to emit NO_REPLY. Against a server that // stamps `self` this is exact; against an older one it degrades to the // legacy any-bot test, where a concurrent post by another agent can // suppress a genuine reply (#757). const snapshotMessages = async () => { try { const { messages = [] } = await client.get( `/api/agents/runtime/pods/${eventPodId}/messages`, { limit: 10 }, ); return messages; } catch { return null; // detection unavailable — fall back to posting the reply } }; // A consult request's final output is routed to the ask-response endpoint, // never echoed into the pod. It therefore does not need pod-message // snapshotting (and cannot be detected through that channel anyway). // The snapshot doubles as the cascade governor's authorship source, so it // runs BEFORE enforcement. const shouldSnapshotMessages = event.type !== 'agent.ask'; const preSpawn = shouldSnapshotMessages ? await snapshotMessages() : null; const preSpawnIds = preSpawn ? new Set(preSpawn.map((m) => String(m._id || m.id))) : null; // ── ADR-018 enforcement: cascade cap ──────────────────────────────────── // Refusing here is a deliberate, permanent decline (acked no_action): a // capped agent-triggered event is exactly the traffic we want dropped. // Human-triggered turns are never capped. const trigger = classifyTrigger(event, preSpawn); // A human turn is a property of the POD, not of this seat's reaction to // it. Record it as soon as it is classified — before the cascade check and // before the claim race — so a seat that stands down still observes the // reset. // // Without this, losing a claim on a human message is SELF-REINFORCING. // The claim stand-down returns before `runTurn`, and `record()` lives at // the end of `runTurn`, so the loser never records the human turn that // would have cleared its streak. It meets the next broadcast still capped, // declines, and again skips `record()`. The only other escape is the // seat's own resetMs clock: stateFor reads only this process's // lastAgentTurnAt, so a capped seat self-clears 10 minutes after its last // completed agent turn regardless of room traffic — cyclical throttling, // not permanent starvation. // // Measured in one pod, 2026-08-18, same window: ux-lead 14 lost claims / // 73 cap refusals / 2 posts, against sprint-review 0 / 2 / 95. Losing one // race is what kept it losing — the mechanism meant to SHARE work // concentrated it instead. // // `=== 'human'` rather than `!== 'agent'`. These are behaviourally the // same today: `record()` dispatches on exact equality and leaves every // other value untouched, including the 'unknown' that `classifyTrigger` // returns for an unresolvable trigger — `enforcement.js:123-131`, and the // "'unknown' is neutral: no count, no reset" note at :130. The narrow form // is defensive, not load-bearing: it keeps an unidentifiable event from // becoming a cap-reset primitive if `record()` ever grows a fallthrough // branch. It closes no hole that was open. // // Agent-triggered turns still record only on completion (see `runTurn`), // so the no-double-count property for redelivered events is unchanged. // 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 // three ends, not two: the mentioning agent gets no signal its mention died, // an operator reading the log cannot tell which mentions were dropped, and // the suppressed seat cannot say what it ignored — it never saw the id. Two // real mentions were lost this way on 2026-08-19 and the seat they were // addressed to could not enumerate them afterwards. log( `[${event.type}] cascade cap: ${admission.streak} consecutive agent-triggered ` + `turns in pod ${eventPodId}` + (event?.payload?.messageId ? ` (dropped message ${event.payload.messageId})` : '') + (admission.graceApplied ? ' (addressed grace also spent)' : '') // NOT "until the pod goes quiet": other seats' traffic never touches // this seat's clock, and a refusal returns here without reaching // `record()` below — so the window is measured from this seat's last // ADMITTED turn in this pod and runs regardless of how loud the room // is. Saying "the pod goes quiet" told an operator to wait for a lull // that is neither necessary nor sufficient (#989). + ` — standing down until a human speaks or ${cascadeSettings.resetMs}ms ` + 'passes with no admitted turn from this seat in this pod', ); // `details` rides through to the AgentEvent row untouched: // normalizeDeliveryMeta whitelists outcome/reason/messageId and passes // `details` straight into `delivery.details`, typed Schema.Types.Mixed. // So the settings that produced this refusal become queryable with NO // backend change and no deploy. // // This is the half the boot log cannot cover. The log says what a seat // resolved; it does not survive a restart, and nothing joins it to the // refusals it caused. Once cap is per-seat and arbitrary, a refusal // whose cap is unknown cannot be compared against one from another seat. // `reason` deliberately stays the fixed literal 'cascade-cap' — :1111 // matches it with === and the run-loop tests assert it — so the value // goes in a sibling field instead of being spelled into the reason. return { outcome: 'no_action', refused: { reason: 'cascade-cap' }, reason: 'cascade-cap', details: { // The id of what was dropped. `reason` and `streak` say a refusal // happened; only this says WHICH message never got answered, which is // what anyone auditing a missed mention actually needs to join on. messageId: event?.payload?.messageId || null, streak: admission.streak, cap: cascadeSettings.cap, addressedGrace: cascadeSettings.addressedGrace, resetMs: cascadeSettings.resetMs, addressed: admission.addressed, graceApplied: admission.graceApplied, }, }; } // ── ADR-018 enforcement: claim-before-act ─────────────────────────────── // Losing a BROADCAST race is a complete turn (stand down, ack): the // holder owns the conversation, and liveness on holder death comes from // the HOLDER's own event staying unacked, not from ours. Losing while // DIRECTLY ADDRESSED is different — a human chose this seat, and that // outranks being beaten to a CAS: the seat still gets its turn, peer-aware // (add your view only if materially different). Claim-route failures // proceed unguarded — enforcement must never make an agent silent (#887). let claimKeeper = null; let peerFrame = null; const claimMessageId = event.payload?.messageId; if (claimMessageId && CLAIMABLE_EVENT_TYPES.has(event.type)) { // Fairness: the winner of this pod's previous broadcast race enters the // next one after a jittered delay. Everyone still claims — a hard // cooldown could leave a message with NO claimant, which is #887 // self-inflicted — recent winners just start from the back. if (event.type === 'message.posted') { const yieldMs = claimHandicap.yieldDelayMs(eventPodId); if (yieldMs > 0) { log(`[${event.type}] yielding ${yieldMs}ms before claiming — won this pod's previous broadcast race`); await sleepImpl(yieldMs); } } claimKeeper = createClaimKeeper(client, { messageId: claimMessageId, podId: eventPodId, leaseSeconds: claimLeaseSeconds, log: (line) => log(`[${event.type}] ${line}`), setIntervalImpl, clearIntervalImpl, }); const claim = await claimKeeper.acquire(); if (!claim.claimed && !claim.failOpen) { // Per-event EVIDENCE, deliberately not a widening of // ADDRESSED_EVENT_TYPES (that set is a pricing table): the backend // stamps repliesToYourMessage when the woken message replies to or // threads on a message THIS seat authored. Without it, a peer's // claim on its own reply ordered the replied-to author out of its // own conversation (Sage stood down twice on Anvil's thread // replies, 2026-08-24). Interim for TASK-058. const repliesToThisSeat = event.payload?.repliesToYourMessage === true; if (ADDRESSED_EVENT_TYPES.has(event.type) || event.payload?.addressed === true || repliesToThisSeat) { log( `[${event.type}] message ${claimMessageId} held by ${claim.holder} — ` + (repliesToThisSeat ? 'proceeding peer-aware (the message replies to this seat\'s own message)' : 'proceeding peer-aware (this seat was directly addressed)'), ); peerFrame = peerHoldsFrame(claim.holder, claimMessageId); claimKeeper = null; // nothing held: no renewal, no release, no isLost gate } else { claimHandicap.recordLoss(eventPodId); log(`[${event.type}] message ${claimMessageId} already claimed by ${claim.holder} — standing down`); return { outcome: 'no_action', reason: 'claim-held' }; } } else if (claim.claimed) { if (event.type === 'message.posted') claimHandicap.recordWin(eventPodId); claimKeeper.startRenewal(); } else { log(`[${event.type}] claim unavailable (${claim.error?.message || 'unknown error'}) — proceeding unguarded`); } } // A private item (an agent.ask.response turn may post a pod update) is // retried here, not in a batch, so it hears what its attempt posted here // too. A comment is answered in its thread, so it is not. const earlierPart = isCommentWake(event) ? null : heldRetryParts.get(String(event._id)); const earlierLine = earlierPart ? `\n\n${earlierAttemptPosted(earlierPart)}` : ''; let turnResult; try { turnResult = await runTurn({ event, eventPodId, prompt: `${peerFrame ? `${peerFrame}\n\n` : ''}${prompt}${earlierLine}`, preSpawnIds, snapshotMessages, claimKeeper, trigger, }); return turnResult; } finally { // A silent, normally completed human wake is an explicit decline, not // a successful answer. Tell the kernel so it can hand the message to // exactly one remaining original listener. A refusal — the upstream // route down, or the server refusing the post — is NAMED (TASK-099): it // carries its class so the kernel's record can tell "answered" from // "never ran", and on a human wake the kernel hands it on exactly as it // does a decline, because a failure local to THIS seat must not make a // human's message disappear. A thrown spawn keeps the legacy release, so // normal at-least-once redelivery still happens after an infrastructure // failure. One decision point, shared with the batch path — see // lib/claim-outcome.js. const release = claimReleaseFor(event, turnResult); await claimKeeper?.release(release.outcome, { reason: release.reason, status: release.status, }); } }; // 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 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) => { wrapperSpokeInTurn = false; const turn = turnRunner.begin({ eventType: args.event.type }); try { return await runTurnBody({ ...args, turn }); } catch (error) { turn.finish('reply_lost'); failedTurn = args; // codex and claude both keep a refused prompt in the thread, and send it // again on every resume (measured 2026-11-05 on codex 0.162.1 and claude // 2.1.318), so one refusal would refuse every later turn in this pod. The // next turn starts fresh; memory reaches it through the adapter's preamble. if (isContentRefusal(error) && turn.resumedSession) clearSession(stateKey, args.eventPodId); throw error; } }; // F178: a provider that will not run this seat's model fails every turn the // same way, and until now only the seat log said so. Post one plain line in // the pod naming the model and where to change it, at most once per model // per seat per hour (persisted, so a restart does not re-post). The failure // itself is rethrown by the caller unchanged, so retry and ack behave as // before. A notice that fails to post is logged and tried on a later turn. const postModelUnavailableHint = async (error, hintPodId, configuredModel) => { const failure = modelUnavailableFailure(error, { fallbackModel: configuredModel }); if (!failure || !hintPodId) return; // A listener seat with no saved environment ignores Settings (see the // "has no saved environment" notice above), and so does a machine-bound // run with no daemon, so both get the command. Each instruction keeps its // own hour: a seat restarted with an environment hears the Settings line // even if the command line went out just before. const cliAgentName = (readSavedControls && !environment) || standaloneMachineRun ? agentName : null; const key = `model-unavailable:${failure.model || 'unknown'}${cliAgentName ? ':agent-config' : ''}`; try { if (!noticeDue(stateKey, key, MODEL_UNAVAILABLE_HINT_WINDOW_MS)) return; const delivery = await deliverTurnNotice({ client, podId: hintPodId, text: modelUnavailableHint(failure.model, { cliAgentName }), limit: chatCharLimit, maxChunks: maxChatChunks, log, }); if (!delivery.skipped && !delivery.refused) { recordNotice(stateKey, key); log(`model unavailable hint posted (${failure.model || 'model not named'})`); } } catch (noticeError) { log(`model unavailable hint could not be posted: ${noticeError.message}`); } }; // A failure only a person can fix, or only time can, leaves a mention // unanswered for as long as it lasts, so each pod with someone waiting is told // why, at most once per cause per pod per hour (persisted, so a restart does // not re-post). A later pod the failed turn stopped before reaching is told // too: a key or an allowance fails every pod alike, and its own turn could be // 45 minutes away. A notice that fails to post is logged and tried at the next // failure; the retry goes ahead either way. const noticeCantAnswer = async (error, waitingEvents) => { const notice = cantAnswerNotice(error); if (!notice || modelUnavailableFailure(error)) return; const waitingPods = new Set(waitingEvents .filter(someoneIsWaiting) .map((event) => event.podId || podId) .filter(Boolean)); for (const waitingPod of waitingPods) { const key = `cant-answer:${notice.cause}:${waitingPod}`; try { // eslint-disable-next-line no-continue if (!noticeDue(stateKey, key, CANT_ANSWER_NOTICE_WINDOW_MS)) continue; // eslint-disable-next-line no-await-in-loop const delivery = await deliverChatReply({ client, podId: waitingPod, text: notice.text, limit: chatCharLimit, maxChunks: maxChatChunks, uploadName: `${agentName}-cant-answer.md`, log: (line) => log(`[inbox.batch] ${line}`), }); if (delivery.skipped || delivery.refused) { log(`[inbox.batch] pod ${waitingPod} was not told why this agent can't answer: ` + `${delivery.reason || 'the notice was not posted'}`); } else { recordNotice(stateKey, key); log(`[inbox.batch] told pod ${waitingPod} why this agent can't answer (${notice.cause})`); } } catch (noticeError) { log(`[inbox.batch] pod ${waitingPod} was not told why this agent can't answer: ${noticeError.message}`); } } }; // F256: a turn that threw after it posted, whose event the server no longer // holds. The usual way there is a child that checkpointed after part one of an // answer and was then killed, so nothing will retry it and the person holds a // promise of more. Only `lostEvents` reach here, so a turn that ended cleanly // never does, and neither does one whose event is retried or handed back. // No window of its own: an event is lost once. The kernel lets this exact line // past its duplicate guard, since a second cut-off has no open ask to carry it. // A turn only agents woke gets no line: "ask me again" isn't for them, and in // an agent-dm the line would wake the peer into a paid turn. // F279: an event let go after three failures counts too, because the server's // retry is 10 to 20 minutes off and the kernel skips its own line once the // agent has posted. `part` is what one of its attempts posted. It may come back // and fail again, so it hears this once. const noteFailedTurnPart = async (failedEvents) => { if (!failedTurn?.preSpawnIds || wrapperSpokeInTurn) return; const tail = await failedTurn.snapshotMessages(50); const ownPost = tail && newestOwnPostSince(tail, failedTurn.preSpawnIds); // `solo`: the attempt carried only this item, so its post can only be this // item's. A batch's post may answer any item in it. const solo = failedEvents.length === 1; if (ownPost) failedEvents.forEach((event) => heldRetryParts.set(String(event._id), { ...ownPost, solo })); }; const noticeCutOff = async (lostEvents, { released = [], part = null } = {}) => { const turnArgs = failedTurn; failedTurn = null; const waiting = [...lostEvents, ...released].filter((event) => event.deliveryMode !== 'digest' && !cutOffTold.has(String(event._id)) && (someoneIsWaiting(event) || PERSON_WAITING_EVENT_TYPES.has(event.type))); if (!turnArgs || turnArgs.trigger === 'agent' || waiting.length === 0) return; const { eventPodId } = turnArgs; const target = commentTargetOf(waiting[0]); try { let delivery; if (target) { // The only comment read is capped and carries no `self` stamp, so it can't // prove this seat replied, and this has no own-post check. // It stands on the prompt instead: a person's direct @ isn't offered // silence, so their item checkpoints only after a reply. That holds only // for a known person, which an 'unknown' comment isn't, and for an item // that checkpointed, which a released one didn't. if (turnArgs.trigger !== 'human' || !lostEvents.includes(waiting[0])) return; delivery = await deliverCommentReply({ client, ...target, text: CUT_OFF_NOTICE, onlyIfUnanswered: false, }); } else { const tail = turnArgs.preSpawnIds ? await turnArgs.snapshotMessages(50) : null; // Nothing of this seat's in the pod means no half answer to explain: a // deliberate silence checkpoints too, and a requeue takes a row as well. const ownPost = (lostEvents.some((event) => waiting.includes(event)) && tail && newestOwnPostSince(tail, turnArgs.preSpawnIds)) || part; if (!ownPost) return; delivery = await deliverChatReply({ client, podId: eventPodId, text: CUT_OFF_NOTICE, limit: chatCharLimit, maxChunks: maxChatChunks, threadRootId: ownPost.threadRootId === null ? null : String(ownPost.threadRootId), log: (line) => log(`[inbox.batch] ${line}`), }); } if (delivery.skipped || delivery.refused) { log(`[inbox.batch] pod ${eventPodId} was not told this agent was cut off: ` + `${delivery.reason || 'the notice was not posted'}`); } else { waiting.forEach((event) => cutOffTold.add(String(event._id))); // The line covers every part so far, so a sibling let go later has none. heldRetryParts.clear(); log(`[inbox.batch] told pod ${eventPodId} this agent was cut off before it finished`); } } catch (noticeError) { log(`[inbox.batch] pod ${eventPodId} was not told this agent was cut off: ${noticeError.message}`); } }; const runTurnBody = async ({ event, eventPodId, prompt, preSpawnIds, snapshotMessages, claimKeeper, trigger, turn, withoutConventions = false, report = null, }) => { const placement = await placeTurn(); // A workspace turn placed public (its pod turned public, or its pods could // not be read) is confined as a public seat, which this host may not be // able to do (a Linux host without bubblewrap). Refuse it as the run start // would, before anything is read or spawned. The model // never runs and nothing is posted. A public pod is a settled answer, so a // human's message is handed to another listener (claim-outcome.js). A // failed read is not: it throws, so the event stays unacked and comes back // through the spawn-retry backoff instead of being refused for good. if (placement.reason) { // A Codex run its person opted out of the sandbox was allowed for private // pods only, so a turn placed public is refused on every platform. On // Linux a public Codex seat would otherwise pass the host check and run // in the owner's workspace with strangers able to direct it (F387). const turnRefusal = placement.unconfinedRefused ? UNCONFINED_TURN_REFUSAL : (hostSandboxRefusal({ environment: placement.environment, adapterName: adapter.name, hostUnconfined, optedIn: codexUnconfined, ...(detectBwrapImpl ? { detectBwrap: detectBwrapImpl } : {}), }) || (codexUnconfined ? CODEX_OPTED_IN_PUBLIC_POD_MESSAGE : null)); if (turnRefusal && placement.readError) { throw Object.assign( new Error(`turn deferred, because its pods could not be read: ${placement.readError.message}`, { cause: placement.readError, }), { status: placement.readError.status }, ); } if (turnRefusal) { log(`turn refused, because ${placement.reason}: ${turnRefusal.replace(/\n\s*/g, ' ')}`); // Asked privately, nobody else can pick this up, and the asker would // otherwise wait out the ask's 24-hour expiry. if (event.type === 'agent.ask' && event.payload?.requestId) { try { await client.post( `/api/agents/runtime/asks/${encodeURIComponent(event.payload.requestId)}/respond`, { content: 'I can’t take this ask: a pod I’m in isn’t private and invite-only, so I can’t run on my owner’s computer right now.' }, ); } catch (err) { if (err?.status !== 409 || err?.body?.code !== 'already_responded') throw err; } } return { outcome: 'no_action', refused: { reason: 'delivery-refused' }, reason: placement.unconfinedRefused ? 'unconfined-pod-not-private' : 'host-cannot-confine-turn', }; } } // §12 C: a confined seat that a connector grant may reach runs with only the // shipped MCP servers (lib/outsider-grant-mcp.js). The server is asked only // when this turn's set holds something else, so an ordinary seat makes no // extra read. A failed read defers the turn, as the placement read does. if (seatIsConfined(placement.environment) && unshippedMcpEntries(placement.environment, instanceUrl).length) { let identity; try { identity = await client.get('/api/agents/runtime/installations', {}, { signal: AbortSignal.timeout(5000), }); } catch (err) { throw Object.assign( new Error(`turn deferred, because whether a connector grant reaches this seat could not be read: ${err.message}`, { cause: err, }), { status: err.status }, ); } const mcpRefusal = outsiderGrantMcpRefusal({ environment: placement.environment, identity, instanceUrl }); if (mcpRefusal) { log(`turn refused: ${mcpRefusal.message}`); if (event.type === 'agent.ask' && event.payload?.requestId) { try { await client.post( `/api/agents/runtime/asks/${encodeURIComponent(event.payload.requestId)}/respond`, { content: 'I can’t take this ask: I’m set up with tools that can’t run next to this pod’s connector.' }, ); } catch (err) { if (err?.status !== 409 || err?.body?.code !== 'already_responded') throw err; } } return { outcome: 'no_action', refused: { reason: 'delivery-refused' }, reason: OUTSIDER_GRANT_MCP_UNCONFINED, }; } } // TASK-440: a cold, large session starts fresh at wake instead of being // resumed, and F392: so does one past the hard ceiling, however recently it // ran. The restart note leads the prompt; memory still reaches the fresh // session through the adapter's preamble. const sessionEntry = getSessionEntry(stateKey, eventPodId, { binding: placement.binding }); let sessionId = getSession(stateKey, eventPodId, { binding: placement.binding }); let recycleBriefing = null; const thresholds = recycleThresholds(); const reason = sessionId ? recycleReason({ lastTurn: sessionEntry?.lastTurn, contextTokens: sessionEntry?.contextTokens, thresholds, }) : null; if (reason) { recycleBriefing = buildRecycleBriefing({ agentName, reason, idleMinutes: idleMinutesSince(sessionEntry.lastTurn), contextTokens: sessionEntry.contextTokens, maxContextTokens: thresholds.maxContextTokens, }); log(reason === 'size' ? `session recycled: ${sessionEntry.contextTokens} context tokens, past the ` + `${thresholds.maxContextTokens}-token ceiling; starting fresh` : `session recycled: idle ${idleMinutesSince(sessionEntry.lastTurn)} min, ` + `${sessionEntry.contextTokens} context tokens; starting fresh`); sessionId = null; } // ADR-005 §Memory bridge: read long_term before spawn, inject via ctx, // and (if the adapter returns a summary) patch-sync back after. A workspace // seat's turn that runs public (placement.reason) gets none of it: its // memory may hold what earlier turns read in the project, and what this // turn reads in an unconfirmed room must not reach the next workspace turn. // The adapter also denies the memory tools for it (memoryWithheld). const memoryWithheld = Boolean(placement.reason); const memoryLongTerm = memoryWithheld ? undefined : await readLongTerm(client, { onError }); // F118: a public seat reads its memory, and its summary is never synced // back: that summary is its own output, which a stranger in the pod can // steer. Its memory tools are withheld unless the kernel says the owner woke // this turn (F145). A workspace seat's public turn is covered by // memoryWithheld too, and never gets them. const publicSeat = effectiveSandboxTrust(placement.environment?.sandbox?.trust) === 'public'; const memoryWriteWithheld = memoryWithheld || publicSeat; // TASK-129: focus is a turn-start read, not an enqueue-time // snapshot. Read through the authorized runtime context route immediately // before spawn so queued events observe the current revision. The helper // disables pod-skill synthesis and throws on failure; the surrounding // processing path then leaves this event (or every event in this batch) // unacknowledged for normal delivery retry. let focusRead; let focusFrame; try { focusRead = await readPodFocus(client, eventPodId); focusFrame = formatPodFocusFrame(focusRead); } catch (error) { Object.assign(error, { eventId: event?.payload?.batchEventIds || event?._id || null, podId: eventPodId, focusRevision: focusRead?.revision ?? null, allowedCodePoints: error?.allowedCodePoints || FOCUS_FRAME_MAX_CODE_POINTS, }); throw error; } const catchUpFrame = await catchUpBeforeTurn(client, eventPodId); // F124: the pod's conventions, from the same read as focus, ahead of the // focus frame (skill text may still be put in front of both below). A // refusal-recovery turn runs without them: text every item shares can // draw the refusal, and isolating items assumes the refused text is one // item's own. `report` tells the batch whether this turn carried them. const conventionsFrame = withoutConventions ? '' : formatPodConventionsFrame(focusRead?.conventions); if (report) report.carriedConventions = Boolean(conventionsFrame); const promptWithFocus = `${conventionsFrame ? `${conventionsFrame}\n\n` : ''}${focusFrame}\n\n${catchUpFrame}\n\n${prompt}`; let serverSkills; let skillReadUnavailable = false; try { const response = await client.get(`/api/agents/runtime/pods/${eventPodId}/skills`, {}, { signal: AbortSignal.timeout(5000), }); serverSkills = compileServerSkills(response?.items || []); } catch (error) { // Skill delivery is optional to the turn. A read failure must not stop // every seat from spawning; report the missing observation explicitly. if (error?.status !== 404) { skillReadUnavailable = true; log(`server skills unavailable (HTTP ${error?.status || 'no response'}); spawning without them`); } serverSkills = compileServerSkills(); } const promptWithSkills = serverSkills.text ? `${serverSkills.text}\n\n${promptWithFocus}` : promptWithFocus; const promptForSpawn = recycleBriefing ? `${recycleBriefing}\n\n${promptWithSkills}` : promptWithSkills; if (adapter.requiresModel) { try { requireSeatModel(seatEnvironment, adapter.name, true); } catch (error) { if (error.code === 'seat_model_missing' && eventPodId && !missingModelNotices.has(eventPodId)) { try { const delivery = await deliverTurnNotice({ client, podId: eventPodId, text: "This agent has no model set; add environment.model to its configuration.", limit: chatCharLimit, maxChunks: maxChatChunks, log, }); if (!delivery.skipped && !delivery.refused) missingModelNotices.add(eventPodId); } catch (noticeError) { log(`missing model notice could not be posted: ${noticeError.message}`); } } // Configuration failure is retryable: never turn a notice into an ack. throw error; } } log(`[${event.type}] spawning ${adapter.name}`); // TASK-102 part B. The CHILD gets a scoped credential; the wrapper keeps // the seat token for its own polling, claiming and posting (`client` was // built from `token` above and is not touched here). The lease renews while // the child runs and revokes when it returns, so the window in which a // leaked child credential is usable is one turn rather than a seat's life. // // A refusal throws: `openSpawnCredential` only falls back to the seat token // for capacity, and a verdict (401/403/400/404/409) must fail the spawn // rather than restore the authority the refusal was about. The catch below // turns that throw into a NAMED refusal on the turn result, so the claim is // released as `delivery-refused` instead of being re-delivered forever. const spawnPolicyOrNull = spawnPolicyForAsk(); const lease = spawnCredentialLeaseFactory({ client, seatToken: token, spawnId: buildSpawnId({ agentName, eventId: event?._id || event?.payload?.batchEventIds || null }), desiredTtlSeconds: spawnCredentialTtlSeconds, policy: spawnPolicyOrNull === null ? null : await spawnPolicyOrNull, // F145: the kernel decides from these rows whether the owner woke the // turn. No events means no: a turn that withholds memory asks for nothing. ...(publicSeat ? { publicSeat: true, eventIds: memoryWithheld ? [] : turnEventIds(event) } : {}), log, }); let opened; try { opened = await lease.open(); } catch (err) { // A VERDICT IS NOT A CRASH, AND IT IS NOT A NO-OP. // Letting it escape as a bare throw left `turnResult` undefined, // so `claimReleaseFor` returned the legacy holder-only DELETE — right for // a transient failure, wrong for a refusal that recurs on every // redelivery: the wake loops forever with one local log line as its only // record. Naming it on the turn result is what lets the release carry the // class, and on a human wake lets the kernel hand the message to a // remaining listener instead of stranding it. if (!err?.spawnCredentialRefused) { // ONLY a verdict is named as a refusal. An unexpected failure inside // the lease — a bug in our own code, not the server's answer — keeps // the legacy release, because `delivery-refused` would hand a human's // message away and close the row on the strength of our own defect. // Redelivery is the right remedy for a crash. log(`spawn credential lease failed (${err?.message ?? err}) — not spawning`); throw err; } const status = Number.isInteger(err.status) ? err.status : null; const code = typeof err.body?.code === 'string' ? err.body.code : null; log(`spawn credential refused (HTTP ${status ?? 'no response'}) — not spawning`); // `delivery-refused` claims the least of the three classes: the model // never ran, and the refuser is our own mint rather than the model // provider (that would be `upstream-refused`, and its status is the HTTP // status of an upstream call — a meaning this refusal does not have, so // the number travels in the ack instead of on the claim record). return { outcome: 'no_action', refused: { reason: 'delivery-refused' }, reason: `spawn-credential-refused-${status ?? 'unknown'}`, details: { ...(status !== null ? { status } : {}), ...(code !== null ? { code } : {}), }, }; } let result; let skillMount = skillReadUnavailable || serverSkills.mounted.length || serverSkills.conflicted.length ? { mounted: serverSkills.mounted, conflicted: serverSkills.conflicted, ...(skillReadUnavailable ? { status: 'unavailable' } : {}) } : null; let spawnCompleted = false; // D245 item 4: how long the runtime ran, for the reply receipt. let spawnDurationMs; let observedSpawn = false; // What a failed spawn threw, read only for its fixed reason code (F370 #11). let spawnFailure = null; let commitAttribution = null; try { // The local CLI is a wrapper for a Commonly seat, so its Git commits // carry the seat and the adapter's selected model/effort. `stub` exists // only for tests and has no commit-making child process. if (adapter?.name !== 'stub') { commitAttribution = prepareCommitAttribution({ cwd: placement.cwd, env: process.env, agentName, displayName, instanceId, adapter: adapter?.name, model: seatEnvironment?.model, effort: seatEnvironment?.effort, }); } await runtimeConnected; let providerKey; if (reportRuntime && resolveOwnProviderKey) { try { providerKey = await resolveOwnProviderKey({ opened, harness: adapter.name, provider: seatEnvironment?.provider }); } catch (error) { if (!error.ownKeySpawnRefused) throw error; return { outcome: 'no_action', refused: { reason: 'delivery-refused' }, reason: 'own-key-requires-scoped-spawn' }; } } const spawnPrompt = frameDecisionForkRule(promptForSpawn); const spawnCtx = { onSpawn: reportRuntime ? (controls) => { observedSpawn = true; return runtimeReporter.spawn(controls); } : undefined, providerKey, timeoutMs: effectiveTurnTimeoutMs, sessionId, cwd: placement.cwd, skillMountDir: scratchCwd, env: commitAttribution?.env || process.env, commitAttributionEnv: commitAttribution?.sandboxEnv || null, memoryLongTerm, memoryWithheld, // A public seat's Commonly server writes nothing once Commonly is // unreachable in its process (lib/public-seat-mcp-flag.js). environment: publicSeat ? withPublicSeatMcpFlag(placement.environment) : placement.environment, // Only when set, so every other spawn context stays as it was. A Codex // run its person opted out with every pod confirmed private keeps // Codex's own policy, never the permission profile (F387): the adapter // reads this, not the environment. ...(hostUnconfined === true || codexUnconfined === true ? { hostUnconfined: true } : {}), ...(publicSeat && !memoryWithheld && opened.ownerWoken === true ? { ownerWoken: true } : {}), onSkillsLinked: ({ mounted, conflicted }) => { skillMount = { mounted: [...new Set([...serverSkills.mounted, ...mounted.map(reportedSkillName)])], conflicted: [...new Set([...serverSkills.conflicted, ...conflicted.map(({ path }) => reportedSkillName(path))])], ...(skillReadUnavailable ? { status: 'unavailable' } : {}), }; }, // Runtime context the Claude/Codex adapters expose only to their // per-spawn MCP environment. Claude keeps ${COMMONLY_*} placeholders // literal on disk and lets its native MCP parser expand them, so the // bearer token never enters the generated config file. Since TASK-102 // part B this is the per-spawn credential when one could be minted, and // the seat token only when the server could not mint. runtimeToken: opened.token, instanceUrl, agentName, // The seat's local key (F306), which a Codex seat's own home is keyed // on (F450): `name@instance` for a second instance, the bare name for // every other seat, including one saved under its name that runs a // non-default instance, so no existing seat moves to a new home. seatKey: stateKey, metadata: { event }, }; // Supervised or plain, a failure is thrown exactly as the adapter's own // would be, so the run loop's classification and retry apply unchanged. const spawnStartedAt = Date.now(); turn.resumedSession = Boolean(spawnCtx.sessionId); try { result = await turn.run(adapter, spawnPrompt, spawnCtx); } catch (spawnError) { spawnFailure = spawnError; await postModelUnavailableHint(spawnError, eventPodId, seatEnvironment?.model); throw spawnError; } spawnDurationMs = Date.now() - spawnStartedAt; // F336: an adapter that saw the turn fail after tool-only output can't // tell whether a tool posted. With no post of its own in the pod, the // failure is thrown here, before the session is kept, exactly as a spawn // failure would be. With one, the turn delivered, and a retry would post twice. if (result?.failure) { const postSpawn = preSpawnIds ? await snapshotMessages() : null; if (!(postSpawn && findOwnPost(postSpawn, preSpawnIds))) { spawnFailure = result.failure; throw result.failure; } log(`[${event.type}] the turn failed after a post of its own, so it is not retried: ${result.failure.message}`); } spawnCompleted = true; } finally { try { if (reportRuntime) { await runtimeReporter.settled(observedSpawn ? spawnCompleted ? 'completed' : 'failed' : null, observedSpawn && !spawnCompleted ? spawnFailureReason(spawnFailure) : null); } commitAttribution?.cleanup(); } finally { if (spawnCompleted && skillMount) { try { await client.post(`/api/agents/runtime/pods/${eventPodId}/skill-load`, skillMount); } catch (error) { log(`skill load status could not be recorded: ${error.message}`); } } // Best-effort by construction: `close` logs and returns on a failed // revoke, so a turn that already produced an answer is not failed by // cleanup. The boot sweep collects anything left behind. await lease.close(); } } if (result.newSessionId) { // TASK-440: record the context size this turn left behind, so the next // wake can decide whether to recycle. Adapters that report nothing keep // resuming. setSession(stateKey, eventPodId, result.newSessionId, { binding: placement.binding, contextTokens: result.contextTokens ?? null, }); } // Decide whether to post the CLI's final text. The agent owns its posting: // if it already spoke this turn through commonly_post_message, echoing its // output would double-post. Two independent signals suppress the echo: // 1. Detection — a new message appeared in the pod during the spawn (the // agent posted via the tool). Automatic; no agent cooperation needed. // 2. NO_REPLY — the agent explicitly asks us to stay silent: the ENTIRE // reply, or (F192) its last line on a turn nobody is waiting on, where // the text above it is reasoning the server would otherwise post. // Other mixed content still posts verbatim. // Otherwise (a bare CLI with no posting tools, or an agent that chose to // reply via its output) the wrapper delivers the text as before. const replyText = (result.text || '').trim(); let agentPostedItself = false; let suppressedBy = null; if (preSpawnIds) { const postSpawn = await snapshotMessages(); if (postSpawn) { suppressedBy = findOwnPost(postSpawn, preSpawnIds); agentPostedItself = Boolean(suppressedBy); } } const heartbeatControlReply = (event.type === 'heartbeat' || event.payload?.hasHeartbeat === true) && /^(HEARTBEAT_OK|HEARTBEAT_NOOP)$/i.test(replyText); const declinedInText = event.type !== 'agent.ask' && !someoneIsWaiting(event) && CLOSES_ON_BARE_SENTINEL.test(replyText); // F192: a heartbeat turn on a seat that has the commonly MCP. Its prompt // said the final text is not posted (HEARTBEAT_TEXT_IS_NOT_POSTED), so that // text is narration ("Checked the board, nothing new"), not a message. A // bare CLI with no posting tool still speaks through its output. const heartbeatNarration = Boolean(replyText) && seatPostsForItself(placement.environment) && !someoneIsWaiting(event) && (event.type === 'heartbeat' || event.payload?.onlyHeartbeat === true); const silentReply = !replyText || replyText === 'NO_REPLY' || heartbeatControlReply || declinedInText || heartbeatNarration; // 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; // What became of the reply, for the turn line (lib/supervised-turn.js // TURN_OUTCOMES). A throw below is reply_lost, finished by runTurn. let turnOutcome; if (event.type === 'agent.ask') { if (silentReply) { const reason = heartbeatControlReply ? replyText : (replyText || 'empty output'); // 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})`); turnOutcome = upstream ? 'upstream_refused' : 'silent'; } else { try { await client.post( `/api/agents/runtime/asks/${encodeURIComponent(event.payload.requestId)}/respond`, { content: replyText }, ); delivered = true; turnOutcome = 'delivered'; log(`[${event.type}] routed private response (${Buffer.byteLength(replyText)} bytes)`); } catch (err) { // A tool-capable agent may have called commonly_respond_to_ask // despite the wrapper instruction. Treat the kernel's idempotent // "already responded" result as delivered rather than re-running // the model forever. if (err?.status === 409 && err?.body?.code === 'already_responded') { delivered = true; turnOutcome = 'delivered'; log(`[${event.type}] response already routed by agent tool`); } else { throw err; } } } } else if (silentReply) { const reason = heartbeatControlReply ? replyText : declinedInText ? 'NO_REPLY' : heartbeatNarration ? 'heartbeat narration; this seat posts with commonly_post_message' : (replyText || 'empty output'); // A turn that posted via tool and THEN ended with the sentinel is not the // same event as a turn that produced nothing — but this branch reported // both as `no wrapper-post (NO_REPLY)`, because it is evaluated before // the `agentPostedItself` branch below and swallowed that fact. // // The skill told agents to do exactly this (post via commonly_post_message, // then end with NO_REPLY so the wrapper does not double-post), so CORRECT // behaviour and total silence were indistinguishable on stdout. // // Cost, 2026-08-18: a seat was diagnosed as mute for "19 hours" on the // strength of `grep -c "posted via tool" == 0` against its log. It had in // fact posted seven times in that window. Five remedies were applied to a // seat that was never broken — cleared session, fresh process, MCP // repointed, model repinned — before the seat itself pointed at the // ledger. The instrument was broken, not the agent. // // Report the two cases distinctly. `posted` is the load-bearing word: a // reader scanning for whether a seat is contributing must not have to // infer it from the absence of a different line. turnOutcome = agentPostedItself ? 'delivered' : upstream ? 'upstream_refused' : 'silent'; if (agentPostedItself) { log( `[${event.type}] posted via tool, then ${reason} — no echo needed ` + `(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`); } } else if (agentPostedItself && !event.commentTarget) { // Name the message that caused the suppression. A silently dropped reply // is invisible to everyone; #757 went unnoticed precisely because this // line said only "posted via tool" with no way to tell whose post it saw. turnOutcome = 'delivered'; log( `[${event.type}] agent posted via tool this turn — not echoing CLI output ` + `(avoids double-post; matched message ${suppressedBy.id} by ${suppressedBy.author} ` + `via ${suppressedBy.basis})`, ); } else if (claimKeeper?.isLost()) { // ADR-018 D3: the lease lapsed mid-turn and a peer re-won the message — // that peer owns the conversation now, so posting would recreate the // two-agents-one-message crossing the claim exists to prevent. turnOutcome = 'claim_lost'; log( `[${event.type}] stood down — claim lost mid-turn to ${claimKeeper.getHolder()}; ` + `reply suppressed (${Buffer.byteLength(replyText)} bytes not posted)`, ); } else { // ADR-018 length gate: the tone contract is enforced here, where the // wrapper is the one posting. Split, attach — never truncate. let delivery; try { if (event.commentTarget) delivery = await deliverCommentReply({ client, ...event.commentTarget, text: replyText }); else delivery = await deliverChatReply({ client, podId: eventPodId, text: replyText, limit: chatCharLimit, maxChunks: maxChatChunks, uploadName: `${agentName}-reply-${event._id}.md`, log: (line) => log(`[${event.type}] ${line}`), // D245 item 4: the wrapper's own account of this turn. receipt: buildReplyReceipt({ adapterName: adapter.name, stats: result.stats, durationMs: spawnDurationMs, }), }); } catch (deliveryError) { // TASK-535: every rung threw, so the reply reached nobody. The throw // still leaves the events unacked for redelivery (unchanged), but the // retry report is about the BATCH; this line is about the reply, and // it names where it was going so a lost summary is never silent. const eventCount = Array.isArray(event.payload?.batchEventIds) ? event.payload.batchEventIds.length : 1; log( `[${event.type}] ERROR reply NOT delivered to pod ${eventPodId} — ` + `${Buffer.byteLength(replyText)} bytes lost, ${eventCount} event${eventCount === 1 ? '' : 's'} ` + `left unacked for retry: ${deliveryError.message}`, ); throw deliveryError; } if (delivery.skipped) { // The server answered 200 and created nothing: a duplicate inside its // dedupe window, a silent body, a heartbeat it keeps. Nothing reached // the pod, so this is not a delivery and must not read as one in the // log — "posted 151 bytes as 1 message" over a skip is how a silent // seat looked like a talking one (hq-support, 2026-10-09 08:10Z). Ack // it like a refusal: re-posting the same text inside the window would // only be skipped again. deliveryRefusal = delivery; turnOutcome = 'server_skipped'; const windowMinutes = delivery.duplicate?.dedupeWindowMinutes; const detail = [ windowMinutes ? `${windowMinutes} min window` : null, delivery.duplicate?.id ? `duplicate of ${delivery.duplicate.id}` : null, delivery.attemptedMessages > 1 ? `after ${delivery.messages}/${delivery.attemptedMessages} messages` : null, ].filter(Boolean).join(', '); log(`[${event.type}] server skipped the post: ${delivery.reason}${detail ? ` (${detail})` : ''} — nothing reached the pod`); onError?.(Object.assign( new Error(`${event.type} server skipped the post: ${delivery.reason}`), { code: 'agent_delivery_skipped', reason: delivery.reason, eventId: event._id, postedMessages: delivery.messages, attemptedMessages: delivery.attemptedMessages, }, )); } else if (delivery.refused) { // A run-cap refusal is a successful HTTP request but not a delivery. // Ack it so the kernel does not replay the same text (the server // guidance expressly says not to retry unchanged), while preserving // the refusal and its partial-post count for the seat and event ledger. deliveryRefusal = delivery; turnOutcome = 'server_refused'; const guidance = delivery.guidance || 'The server refused this message; do not retry it unchanged.'; const detail = `after ${delivery.messages}/${delivery.attemptedMessages} message${delivery.attemptedMessages === 1 ? '' : 's'}`; log(`[${event.type}] wrapper delivery refused ${detail} (${delivery.reason}): ${guidance}`); onError?.(Object.assign( new Error(`${event.type} wrapper delivery refused ${detail}: ${guidance}`), { code: 'agent_delivery_refused', reason: delivery.reason, eventId: event._id, postedMessages: delivery.messages, attemptedMessages: delivery.attemptedMessages, }, )); } else { delivered = true; turnOutcome = 'delivered'; log(delivery.alreadyAnswered ? `[${event.type}] agent already answered this comment through a tool — not echoing CLI output` : `[${event.type}] posted ${Buffer.byteLength(replyText)} bytes as ` + `${delivery.messages} message${delivery.messages === 1 ? '' : 's'} (${delivery.mode})`); } } turn.finish(turnOutcome); if (result.memorySummary && !memoryWriteWithheld) { try { await syncBack(client, { summary: result.memorySummary }); log(`[${event.type}] memory synced (${Buffer.byteLength(result.memorySummary)} bytes)`); } catch (err) { // Memory-sync failure is non-fatal: the turn already posted, and the // next spawn will re-read from the kernel anyway. Surface, don't // throw. Preserve the original error via `cause` so the stack trace // survives for CLI debugging. onError?.(new Error(`memory sync failed: ${err.message}`, { cause: err })); } } // The turn completed — count it toward (or reset) the pod's cascade // streak. Recording only on completion means a spawn failure that gets // redelivered never double-counts toward the cap. cascadeGovernor.record(eventPodId, trigger); if (deliveryRefusal) { return { outcome: 'no_action', // Kernel class, from REFUSAL_REASONS: a skip is the server declining to // deliver, same class as a refusal; the specific reason rides below. refused: { reason: 'delivery-refused' }, reason: deliveryRefusal.reason, details: { mode: deliveryRefusal.mode, postedMessages: deliveryRefusal.messages, attemptedMessages: deliveryRefusal.attemptedMessages, ...(typeof deliveryRefusal.consecutive === 'number' ? { consecutive: deliveryRefusal.consecutive } : {}), ...(deliveryRefusal.guidance ? { guidance: deliveryRefusal.guidance } : {}), }, }; } // A refusal is not a decline, and it is not a close either. `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 the release says WHICH class of refusal // it was (TASK-099). The kernel routes from there: on a human wake the // message is handed to one remaining listener exactly as a decline is // (this seat's upstream route being down says nothing about theirs), and on // any other wake it is terminal. The free-text detail stays in the seat // log and the event ack; the kernel records the class. if (!delivered && upstream) { // pi exits 0 on a refused route, so no failure reaches the retry path. await noticeCantAnswer(new Error(describeUpstreamRefusal(upstream)), [event]); return { outcome: 'no_action', refused: { reason: 'upstream-refused', ...(Number.isInteger(upstream.status) ? { status: upstream.status } : {}), }, reason: `upstream-refused-${upstream.status}`, details: { status: upstream.status, ...(upstream.detail ? { detail: upstream.detail } : {}), }, }; } // Empty output is not the sentinel. A seat that answered `NO_REPLY` read // its batch and chose silence; one that printed nothing may have crashed, // timed out or lost its route without saying so. The bare `no_action` // stays the sentinel's alone, because a digest counts as read only on // that (#2753). Release, hand-off and spawn counting treat // `empty-output` exactly as they treat a bare decline. if (!delivered && !replyText) return { outcome: 'no_action', reason: EMPTY_OUTPUT }; return { outcome: delivered ? 'posted' : 'no_action' }; }; // ADR-024 D3: the batch header states the real inbox count even when we cap // copied bodies. A claimed item past the cap (`pastCap`, set in // handleEventBatch) is left out and named in the prompt, never acked as seen; // the next turn shows it. Additional pending // events stay in the kernel queue and are cued in the header for a later // pull, rather than being silently consumed here. // `unreadBodiesPodId` is set only for a turn a person's mention woke (ADR-018 // D9.2): the unread messages this page carried go in as marked data. const buildInboxPrompt = (entries, inboxCount = entries.length, { pod = null, unreadBodiesPodId = null } = {}) => { const BODY_LIMIT = batchLimit; const wakeEntries = entries.filter((entry) => entry.event.deliveryMode !== 'digest' && !entry.pastCap); const digestEntries = entries.filter((entry) => entry.event.deliveryMode === 'digest' && !entry.pastCap); // What the turn acts on always fits. An item already settled (a peer's, a // duplicate) is context, and takes only what's left. const context = wakeEntries.filter((entry) => entry.result); const contextShown = new Set(context.slice(0, Math.max(0, BODY_LIMIT - wakeEntries.length + context.length))); const shownEntries = wakeEntries.filter((entry) => !entry.result || contextShown.has(entry)); const heldBack = entries.filter((entry) => entry.pastCap).length; // The same set the batch's onlyHeartbeat reads, so the closing line matches the drop. const inTurn = entries.filter((entry) => !entry.pastCap); const heartbeatOnly = inTurn.length > 0 && inTurn.every((entry) => entry.event.type === 'heartbeat'); const answersPerson = shownEntries.some(answersAPerson); const bodies = shownEntries.map((entry, index) => { const messageId = entry.event.payload?.messageId; const prefix = [ `Event ${index + 1}/${shownEntries.length}: ${entry.event.type}`, messageId ? `message ${messageId}` : null, ].filter(Boolean).join(' — '); const claimContext = entry.readOnly ? `${peerHoldsFrame(entry.holder, messageId)}\n` + '[This item is read-only context: a peer won its binding claim. Do not act on it.]\n' : (entry.peerFrame ? `${entry.peerFrame}\n` : ''); const body = entry.prompt || '[No usable prompt was delivered for this item.]'; const personLine = answersAPerson(entry) ? `\n${PERSON_ADDRESSED}` : ''; // A peer's item is read-only, and a comment is answered in its thread, not // by a pod post: neither is told to stop at what the attempt posted. const earlierPart = entry.readOnly || isCommentWake(entry.event) ? null : heldRetryParts.get(String(entry.event._id)); const earlierLine = earlierPart ? `\n${earlierAttemptPosted(earlierPart, { batch: shownEntries.length > 1 })}` : ''; const deliveryId = entry.event.payload?.deliveryId; const checkpoint = typeof deliveryId === 'string' && deliveryId ? `\n[After ${answersAPerson(entry) ? 'all of your answer is posted through a tool' : 'completed tool-side work or intentional NO_REPLY'} for only this item, call commonly_checkpoint_event(${JSON.stringify({ eventId: String(entry.event._id), deliveryId, })}). Checkpoint metadata is private runtime data; never post it in chat.]` : ''; return `${prefix}\n${claimContext}${body}${personLine}${earlierLine}${checkpoint}`; }); const rollup = wakeEntries.find((entry) => entry.event.payload?.digestRollup)?.event.payload?.digestRollup; const digestEvents = digestEntries.map((entry) => entry.event); const unreadFrame = unreadBodiesPodId ? formatUnreadMessagesFrame(digestEvents, rollup, { podId: unreadBodiesPodId, excludeMessageIds: wakeEntries.map((entry) => entry.event.payload?.messageId), }) : null; const digestFrame = formatDigestFrame(digestEvents, rollup, { bodiesBelow: Boolean(unreadFrame) }); const omitted = Math.max(0, inboxCount - entries.length); return [ `[Inbox batch: ${inboxCount} new event${inboxCount === 1 ? '' : 's'} in this pod. ` + 'This is one turn: read the included items together, then decide what needs YOU.]', `After tool-side work is committed (including any reply posted through a tool)${answersPerson ? ',' : ', or an intentional NO_REPLY,'} checkpoint that item with its supplied IDs. ` + 'Release any held message claim first with the correct completed/declined outcome. ' + 'Do not checkpoint a reply you are holding for final CLI output: the wrapper must post it before acknowledging that item. ' + 'Never checkpoint unfinished work: an answer in several posts is finished only after its last post. ' + 'Only a successful checkpoint prevents replay after timeout. ' + 'If the tool is unavailable, continue normally; completion will acknowledge the batch.', ...bodies, ...(heldBack > 0 ? [`[${heldBack} more event${heldBack === 1 ? '' : 's'} in this inbox did not fit this turn. ` + 'They are unread and still queued, and come in a later turn. Don\'t answer as if you saw them.]'] : []), ...(digestFrame ? [digestFrame] : []), ...(unreadFrame ? [unreadFrame] : []), ...(omitted > 0 ? [`[${omitted} more event${omitted === 1 ? '' : 's'} arrived. Their count is real; pull pod context if needed.]`] : []), commentTargetOf(wakeEntries[0]?.event) ? (wakeEntries[0].event.payload?.senderIsHuman === true ? `Do not narrate the inbox. ${FINAL_TEXT_ANSWERS_ON_COMMENT}` : 'Do not narrate the inbox. Post only an action or a materially useful response; otherwise return NO_REPLY. ' + FINAL_TEXT_ON_COMMENT) : (answersPerson ? 'Do not narrate the inbox. Answer every item marked as a person addressing you directly. ' + 'For anything else here, post only an action or a materially useful response. ' + FINAL_TEXT_ANSWERS_A_PERSON : heartbeatOnly && seatPostsForItself(seatEnvironment) ? `Do not narrate the inbox. ${HEARTBEAT_TEXT_IS_NOT_POSTED}` : 'Do not narrate the inbox. Post only an action or a materially useful response; otherwise return NO_REPLY. ' + FINAL_TEXT_IS_POSTED + roomQuestionLine(pod, shownEntries)), ].join('\n\n'); }; const batchAdmissionResult = (event, admission) => ({ outcome: 'no_action', refused: { reason: 'cascade-cap' }, reason: 'cascade-cap', details: { messageId: event?.payload?.messageId || null, streak: admission.streak, cap: cascadeSettings.cap, addressedGrace: cascadeSettings.addressedGrace, resetMs: cascadeSettings.resetMs, addressed: admission.addressed, graceApplied: admission.graceApplied, }, }); // Claim the binding portion before the ONE composite spawn. A lost binding // claim is not discarded: it remains in the model's context with the same // peer frame the single-event path already uses, but is explicitly read-only. // Advisory losses retain their existing peer-aware behaviour. // A refused item is acked, never retried (lib/content-refusal.js). Every one // is logged by event id alone. One addressed to this seat also gets a pod // notice the WRAPPER writes, since the model never read it: identifiers // only, and the hand-off agent @mentioned outside a DM. A refused broadcast // gets no notice: its claim releases as `upstream-refused`, and the kernel // hands a human's message to another listener. A notice that fails to post // is logged; the ack still happens, because retrying would only re-send the // refused content. const postRefusalNotice = async (refusedEntries, eventPodId) => { for (const entry of refusedEntries) { log(`[${entry.event.type}] the model provider refused the content of event ${entry.event._id} (content_refused) — acked as refused, not retried`); } const addressed = refusedEntries.filter((entry) => ADDRESSED_EVENT_TYPES.has(entry.event.type)); if (addressed.length === 0) return; const mention = Boolean(handoffAgent) && !addressed.some((entry) => entry.event.type === 'dm.message'); const text = composeRefusalHandoff({ items: addressed.map((entry) => refusedItemRef(entry.event)), handoff: handoffAgent, mention, }); let posted = false; try { const delivery = await deliverTurnNotice({ client, podId: eventPodId, text, limit: chatCharLimit, maxChunks: maxChatChunks, uploadName: `${agentName}-refusal-${addressed[0].event._id}.md`, log: (line) => log(`[inbox.batch] ${line}`), }); posted = !delivery.skipped && !delivery.refused; log(posted ? `[inbox.batch] refusal notice posted${mention ? `, handed off to @${handoffAgent}` : ''}` : `[inbox.batch] refusal notice not delivered (${delivery.reason})`); } catch (err) { log(`[inbox.batch] refusal notice failed: ${err.message}`); } for (const entry of addressed) { entry.result.details = { ...entry.result.details, handoff: mention ? handoffAgent : null, noticePosted: posted, }; } }; // The greeting is CLAIMED the moment a poll returns it: claimPage reads // `status: 'pending'` and marks each returned row `delivered`, and later // polls read only pending. Leaving it unacked therefore does NOT bring it // back next tick — garbageCollect requeues delivered rows only after // AGENT_EVENT_REQUEUE_DELIVERED_MINUTES (10 by default, and its own comment // notes the effective latency is worse). So the hold is in memory, not on // the wire: carry the claimed event and prepend it to the next poll's batch. // Spent at most once per run. (CTO review 5623358693.) let heldGreeting = []; let greetingHoldSpent = false; // Polls the connect-time greeting has been carried, against the window. let greetingHeldPolls = 0; let greetingHoldStartedAt = null; const greetingHoldPolls = Math.max(1, Math.ceil(GREETING_HOLD_MS / Math.max(1, Number(intervalMs) || 1))); // The same is true of a batch whose turn FAILED: its events are claimed, so // scheduling a later poll retries nothing — the next poll cannot return // them, and the old "retry scheduled" was really a 10–20 minute wait for the // requeue sweep with the process idle in between (sprint-review, // 2026-10-25). So a failed turn's events are carried exactly like the // greeting and rejoin the inbox when the retry timer fires. Their leases are // renewed while they wait, because an ack under a lapsed lease is a 409 // `stale_delivery`, and that stops the run. The rule (CTO ruling, // 2026-10-25): a scheduled retry either fires, re-running the held events, // or releases them; it never leaves a live process idle on unacked work. let heldRetry = []; // Claimed events the latest tick neither acked nor carried: a digest left // unread, or a later group a failure or a stale ack skipped. A running seat // leaves these to the requeue as it always has. A stop hands them back on // every planned exit from the tick; an unexpected throw leaves the page to // the requeue. One list, so a new exit has one thing to add to (F189). let tickUnsettled = []; // eventId → consecutive local failures, for HELD_RETRY_MAX_FAILURES. const heldRetryFailures = new Map(); // Event id to what a failed attempt on it posted, for noticeCutOff. Read as each // attempt fails, because the attempt's own snapshot then leaves out the notices // the wrapper posted after earlier ones: those aren't part of an answer. A notice // inside the attempt can't be told from a post that way, so that attempt isn't // read, which can only cost the line. const heldRetryParts = new Map(); let wrapperSpokeInTurn = false; const deliverTurnNotice = (notice) => { wrapperSpokeInTurn = true; return deliverChatReply(notice); }; const cutOffTold = new Set(); // eventId → turns passed over, for PAST_CAP_MAX_CARRIES. const pastCapCarries = new Map(); // The current batch's items past the cap. Kept out here because the tick needs // them when the turn throws, and a throw returns no entries. let pastCapEvents = []; // The arguments of the turn that just threw, for noticeCutOff. let failedTurn = null; let heldRenewTimer = null; // Renews the rows a tick claimed for its later pods while an earlier pod's // turn runs (F237). Cleared when the tick's groups are done. let laterGroupsRenewTimer = null; const clearLaterGroupsRenewal = () => { if (laterGroupsRenewTimer !== null) clearIntervalImpl(laterGroupsRenewTimer); laterGroupsRenewTimer = null; }; const clearHeldRenewal = () => { if (heldRenewTimer !== null) clearIntervalImpl(heldRenewTimer); heldRenewTimer = null; }; // Renew the nonce-bound leases of carried events. Returns the ids the server // confirmed are still this runner's delivery, or null when it cannot say: // nothing carried a nonce, the request failed, or an older server answered // without a `renewed` list. const renewHeldDeliveries = async (events) => { const deliveries = events.filter(deliveryIdOf) .map((event) => ({ eventId: String(event._id), deliveryId: deliveryIdOf(event) })); if (deliveries.length === 0) return null; const confirmed = new Set(); try { for (let offset = 0; offset < deliveries.length; offset += 50) { // eslint-disable-next-line no-await-in-loop const response = await client.post('/api/agents/runtime/events/renew', { events: deliveries.slice(offset, offset + 50), }); if (!Array.isArray(response?.renewed)) return null; for (const id of response.renewed) confirmed.add(String(id)); } } catch (error) { log(`[inbox.batch] held delivery renewal failed: ${error.message}`); return null; } return confirmed; }; // A nonce-bound event the server did not renew is no longer ours to ack: // the child checkpointed it mid-turn, the requeue took it, or the cap // retired it. Re-running it would at best repeat finished work, and at worst // end in a stale-delivery ack that stops the run. const stillHeld = (event, confirmed) => ( confirmed === null || !deliveryIdOf(event) || confirmed.has(String(event._id)) ); // What an inbox read asks for. A carry that fills the prompt during an // outage names its rows (`onlyIds`), and a current server returns only those // it requeued, with their live delivery ids, and claims nothing new (F237). // `limit` keeps today's value, so a server that predates onlyIds claims as // before. `inOutage`: the circuit-wait check, which runs only while the // circuit is open. const inboxQuery = ({ inOutage = false } = {}) => { const carried = [...heldRetry, ...heldGreeting]; const carriedCount = carried.filter((event) => event.deliveryMode !== 'digest').length; const full = carriedCount >= batchLimit && (inOutage || consecutiveSpawnFailures >= FULL_CARRY_CLAIM_FAILURES); return { agentName, instanceId, limit: Math.max(1, batchLimit - carriedCount), ...(full ? { onlyIds: [...new Set(carried.map((event) => String(event._id)))].join(',') } : {}), ...(adapter?.name ? { reportedCli: adapter.name } : {}), }; }; // Decide what a failed turn's retry carries. `failedEvents` were attempted // and count toward HELD_RETRY_MAX_FAILURES; `untriedEvents` are later groups // from the same page that the failure stopped before they ran (#782), and // are just as claimed, so they ride along without a strike. `pastCap` events // were left out of a turn, which is no failure of theirs: no strike, and // PAST_CAP_MAX_CARRIES bounds them instead. A later group's hold in the same // tick adds to the carry, never replaces it. A turn an outside signal cut off // inside its grace (F293) is no failure of the event's either: `strike: false` // carries it without one, or the third kill would release it to the server's // requeue and the answer would wait 10–20 minutes. The grace bounds this. const holdForRetry = async (failedEvents, untriedEvents = [], pastCap = [], { strike = true } = {}) => { const released = []; let part = null; const carry = []; const seen = new Set(); for (const event of strike ? failedEvents : []) { const id = String(event._id); if (!seen.has(id)) { seen.add(id); const failures = (heldRetryFailures.get(id) || 0) + 1; // A stop wins over the local limit: the sweep would make this event // wait 10–20 minutes, and the server's ceiling bounds a hand-back. if (running && failures >= HELD_RETRY_MAX_FAILURES) { released.push(event); part = part || heldRetryParts.get(id) || null; } else { heldRetryFailures.set(id, failures); carry.push(event); } } } for (const event of strike ? untriedEvents : [...failedEvents, ...untriedEvents]) { const id = String(event._id); if (!seen.has(id)) { seen.add(id); carry.push(event); } } const passedOver = []; for (const event of pastCap) { const id = String(event._id); if (!seen.has(id)) { seen.add(id); const carries = (pastCapCarries.get(id) || 0) + 1; // As above: a stop hands the item back rather than leave it to the sweep. if (running && carries >= PAST_CAP_MAX_CARRIES) passedOver.push(event); else { pastCapCarries.set(id, carries); carry.push(event); } } } if (passedOver.length) { log( `[inbox.batch] releasing ${countEvents(passedOver.length)} after ${PAST_CAP_MAX_CARRIES} turns past the prompt cap ` + 'to the server\'s requeue (redelivered in ~10–20 min)', ); } // A stopping run carries nothing, because its carry is handed back to the // server when the tick ends (F189), so the next run answers it on its first // poll. It renews only the failed turn's own events, to learn which of them // it still holds: that hand-back follows at once, so the replacement doesn't // wait on the longer lease. if (!running) { heldRetry = [...heldRetry, ...carry]; heldRetryFailures.clear(); heldRetryParts.clear(); pastCapCarries.clear(); const confirmed = await renewHeldDeliveries(failedEvents); return { held: [], released, handedBack: carry, lost: failedEvents.filter((event) => !stillHeld(event, confirmed)), }; } const confirmed = carry.length ? await renewHeldDeliveries(carry) : null; // The stop landed during that renewal, after the limits were applied. if (!running) tickUnsettled.push(...released, ...passedOver); const held = carry.filter((event) => stillHeld(event, confirmed)); const dropped = carry.filter((event) => !stillHeld(event, confirmed)); heldRetry = [...heldRetry, ...held]; const heldIds = new Set(heldRetry.map((event) => String(event._id))); for (const counts of [heldRetryFailures, heldRetryParts, pastCapCarries]) { for (const id of [...counts.keys()]) { if (!heldIds.has(id)) counts.delete(id); } } if (dropped.length) { log( `[inbox.batch] ${countEvents(dropped.length)} no longer held by this runner on the server ` + '(checkpointed, requeued or retired) — not retried', ); } return { held, released, part, handedBack: [], lost: dropped.filter((event) => failedEvents.includes(event)), }; }; // F189/F182: hand claimed events this run will never run back to the // server as pending, so the next run claims them on its first poll. Without // this they stay `delivered` to a dead process until the requeue sweep // (10–20 min, one attempt spent per lap): a walk on 2026-11-05 restarted a // circuit-open seat five times and each restart's mention waited on that // sweep. Nonce-bound on the server, so nothing a replacement holds can be // released, and an event this run released can no longer be acked by it. // The server refuses an event at its redelivery ceiling (`atCeiling`); it // stays delivered and the requeue retires it, which bounds a poison event. // Best effort: an older server without the route, or a failed request, // leaves them to the requeue as before, and says so. const handBackDeliveries = async (events, why) => { const seen = new Set(); const deliveries = []; for (const event of events) { const id = String(event._id); if (deliveryIdOf(event) && !seen.has(id)) { seen.add(id); deliveries.push({ eventId: id, deliveryId: deliveryIdOf(event) }); } } if (deliveries.length === 0) return []; const released = []; const atCeiling = []; try { for (let offset = 0; offset < deliveries.length; offset += 50) { // eslint-disable-next-line no-await-in-loop const response = await client.post('/api/agents/runtime/events/release', { events: deliveries.slice(offset, offset + 50), }); if (Array.isArray(response?.released)) released.push(...response.released.map(String)); if (Array.isArray(response?.atCeiling)) atCeiling.push(...response.atCeiling.map(String)); } } catch (error) { log( `[inbox.batch] could not hand back ${countEvents(deliveries.length - released.length)} on ${why} ` + `(${error.message}) — the server's requeue redelivers them in ~10–20 min`, ); return released; } log(`[inbox.batch] handed back ${countEvents(released.length)} held on ${why}, for the next run to answer`); if (atCeiling.length) { log(`[inbox.batch] ${countEvents(atCeiling.length)} left to the requeue (at the redelivery ceiling)`); } return released; }; // Everything a stopped run still carries. Taken once: the arrays are emptied // before the request, so a second caller finds nothing to send. const handBackCarryOnStop = () => { const carry = [...heldRetry, ...heldGreeting, ...tickUnsettled]; heldRetry = []; heldGreeting = []; tickUnsettled = []; heldRetryFailures.clear(); heldRetryParts.clear(); clearHeldRenewal(); return carry.length ? handBackDeliveries(carry, 'stop') : Promise.resolve([]); }; // Keep a long wait's leases alive. A wait shorter than one renewal interval // needs none: holdForRetry renewed at the start, and the re-run turn renews // its own batch from there. const keepHeldLeases = (delayMs) => { clearHeldRenewal(); if (!running || delayMs <= DELIVERY_RENEW_INTERVAL_MS || !heldRetry.some(deliveryIdOf)) return; heldRenewTimer = setIntervalImpl(async () => { if (!running) { clearHeldRenewal(); return; } const carry = heldRetry; const confirmed = await renewHeldDeliveries(carry); // The tick may already have taken this carry; never resurrect it. if (heldRetry !== carry || confirmed === null) return; heldRetry = carry.filter((event) => stillHeld(event, confirmed)); if (heldRetry.length < carry.length) { log( `[inbox.batch] ${countEvents(carry.length - heldRetry.length)} no longer held by this runner ` + 'on the server during the retry wait — not retried', ); } }, DELIVERY_RENEW_INTERVAL_MS); heldRenewTimer?.unref?.(); }; // What the retry will actually do, for the failure report. const describeHold = ({ held, released, handedBack = [] }, retry) => { const parts = []; if (retry.circuitOpen) parts.push('circuit open'); if (handedBack.length) { return [...parts, `stopping: handing ${countEvents(handedBack.length)} back to the server for the next run`] .join('; '); } if (released.length) { parts.push( `releasing ${countEvents(released.length)} after ${HELD_RETRY_MAX_FAILURES} failed attempts ` + 'to the server\'s requeue (redelivered in ~10–20 min)', ); } parts.push(held.length ? `retrying ${held.length} held event${held.length === 1 ? '' : 's'} in ${formatRetryDelay(retry.delayMs)}` : `next poll in ${formatRetryDelay(retry.delayMs)}`); return parts.join('; '); }; const handleEventBatch = async (events, inboxCount = events.length) => { pastCapEvents = []; failedTurn = null; const eventPodId = events[0]?.podId || podId; if (!eventPodId || events.some((event) => (event.podId || podId) !== eventPodId)) { throw new Error('Inbox batch crossed pod boundaries; refusing to mix private pod context'); } const entries = events.map((event) => ({ event, prompt: extractPrompt(event), result: null, claimKeeper: null, peerFrame: null, readOnly: false, holder: null, })); // Duplicate deliveries have already completed locally. Re-ack them but do // not spend the new batch turn displaying old work as if it were new. const seenEventIds = new Set(); for (const entry of entries) { const eventId = String(entry.event._id); if (seenEventIds.has(eventId) || wasEventHandled(stateKey, entry.event._id)) { entry.result = { outcome: 'no_action', reason: 'duplicate-delivery' }; log(`[${entry.event.type}] duplicate delivery ${entry.event._id} — re-acking without batch spawn`); } else { seenEventIds.add(eventId); } if (entry.result?.reason === 'duplicate-delivery') { continue; } if (isCommentWake(entry.event) && !commentTargetOf(entry.event)) { entry.result = { outcome: 'no_action', reason: COMMENT_OUTSIDE_POD_REASON }; // A comment's payload has no messageId (postController sends no _id); its id // is thread.commentId. log(`[${entry.event.type}] comment ${entry.event.payload?.thread?.commentId} is not on a post in pod ${eventPodId}` + ' — acked without a spawn, so nobody is answered on a surface this seat was not placed for'); continue; } if (!entry.prompt) { entry.result = { outcome: 'no_action', reason: 'no-prompt' }; log(`[${entry.event.type}] no prompt — no-op`); onError?.(Object.assign( new Error( `${entry.event.type} event ${entry.event._id} was acked WITHOUT a spawn: ` + 'payload carried no content and no messageId. If this wake mattered, its producer is sending an unusable payload.', ), { code: 'agent_event_skipped_no_prompt', eventId: entry.event._id }, )); } } // Null until the server says: a failed read or an older server is unknown, // not "alone" and not "with peers". let podAttendance = null; const snapshotMessages = async (limit = 10) => { try { const { messages = [], otherAgentsInPod, peopleInPod } = await client.get( `/api/agents/runtime/pods/${eventPodId}/messages`, { limit }, ); podAttendance = typeof otherAgentsInPod === 'boolean' ? { otherAgentsInPod, peopleInPod } : null; return messages; } catch { podAttendance = null; return null; } }; const preSpawn = await snapshotMessages(); const preSpawnIds = preSpawn ? new Set(preSpawn.map((message) => String(message._id || message.id))) : null; const activeEntries = entries.filter((entry) => !entry.result); // The server settles a digest on its holder's ack, up to the holder's // snapshot. A holder this turn shows settles what it shows, so every digest // in hand goes in its prompt, whoever else waits. With no holder shown, a // holder that waits takes them along, so they settle on a turn that shows // them. A holder with a result settles nothing here: its reason doesn't count // as reading a digest. const carryPastCap = () => { const isHolder = (entry) => holdsDigest(entry.event); const shownHolder = wakingEntries.some((entry) => !entry.pastCap && !entry.result && isHolder(entry)); if (!shownHolder && wakingEntries.some((entry) => entry.pastCap && isHolder(entry))) { for (const entry of activeEntries) { if (entry.event.deliveryMode === 'digest') entry.pastCap = true; } } pastCapEvents = entries.filter((entry) => entry.pastCap).map((entry) => entry.event); }; // Ambient digest entries provide context for this turn, but must never // determine its admission or count as the trigger that woke the seat. const wakingEntries = activeEntries.filter((entry) => entry.event.deliveryMode !== 'digest'); const triggers = wakingEntries.map((entry) => classifyTrigger(entry.event, preSpawn)); wakingEntries.forEach((entry, index) => { entry.trigger = triggers[index]; }); 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 )) || wakingEntries[0]; if (admissionEvent) { const admission = cascadeGovernor.admit( eventPodId, trigger, admissionEvent.event.type, admissionEvent.event.payload, ); if (!admission.allowed) { // An agent row refuses the page, and that shouldn't cost a row nobody // can place: one past the snapshot with no stamp reads `unknown`. It is // carried, past-cap bound included, and alone in its next page it can't // be refused, because only 'agent' ever is. for (const entry of wakingEntries) { if (entry.trigger === 'unknown' && entry.event.payload?.messageId) entry.pastCap = true; else entry.result = batchAdmissionResult(entry.event, admission); } carryPastCap(); return { entries }; } } const bindingEntries = activeEntries.filter((entry) => ( entry.event.deliveryMode !== 'digest' && entry.event.type === 'message.posted' && entry.event.payload?.messageId )); if (bindingEntries.length > 0) { const yieldMs = claimHandicap.yieldDelayMs(eventPodId); if (yieldMs > 0) { log(`[inbox.batch] yielding ${yieldMs}ms before claiming ${bindingEntries.length} binding event${bindingEntries.length === 1 ? '' : 's'}`); await sleepImpl(yieldMs); } } const claimEntry = async (entry) => { const messageId = entry.event.payload?.messageId; if (!messageId || !CLAIMABLE_EVENT_TYPES.has(entry.event.type)) return; const claimKeeper = createClaimKeeper(client, { messageId, podId: eventPodId, leaseSeconds: claimLeaseSeconds, log: (line) => log(`[${entry.event.type}] ${line}`), setIntervalImpl, clearIntervalImpl, }); const claim = await claimKeeper.acquire(); if (claim.claimed) { entry.claimKeeper = claimKeeper; claimKeeper.startRenewal(); if (entry.event.type === 'message.posted') claimHandicap.recordWin(eventPodId); } else if (!claim.failOpen) { entry.holder = claim.holder; if (entry.event.type === 'message.posted') { // A reply to this seat's own message is direct-address evidence, // even though its transport type is the broadcast-shaped // `message.posted`. Preserve the existing ADR-018/TASK-058 // peer-aware exception; D3a otherwise partitions lost bindings as // read-only so a generic broadcast cannot widen itself after CAS. if (entry.event.payload?.repliesToYourMessage === true || entry.event.payload?.addressed === true) { entry.peerFrame = peerHoldsFrame(claim.holder, messageId); return; } // D3a's partition: no later model judgement can widen this item's // authority after a peer won the binding CAS. entry.readOnly = true; entry.result = { outcome: 'no_action', reason: 'claim-held' }; claimHandicap.recordLoss(eventPodId); } else { entry.peerFrame = peerHoldsFrame(claim.holder, messageId); } } else { log(`[${entry.event.type}] claim unavailable (${claim.error?.message || 'unknown error'}) — proceeding unguarded`); } }; // The cap is spent here, not when the prompt is built: a lost claim gives its // slot back, and an item past the cap is never claimed, because a seat that // isn't reading a message must not hold a peer off it. let slotsLeft = batchLimit; for (const entry of [...wakingEntries].sort((a, b) => capRank(a) - capRank(b))) { if (slotsLeft === 0) entry.pastCap = true; else { // eslint-disable-next-line no-await-in-loop await claimEntry(entry); if (!entry.result) slotsLeft -= 1; } } carryPastCap(); const actionEntries = wakingEntries.filter((entry) => !entry.result && !entry.pastCap); if (actionEntries.length === 0) return { entries }; const personMentioned = actionEntries.some((entry) => isPersonMention(entry.event, entry.trigger)); const claimKeepers = actionEntries .map((entry) => entry.claimKeeper) .filter(Boolean); const compositeClaimKeeper = claimKeepers.length > 0 ? { isLost: () => claimKeepers.some((keeper) => keeper.isLost()), getHolder: () => claimKeepers.find((keeper) => keeper.isLost())?.getHolder(), } : null; const batchEvent = { ...actionEntries[0].event, _id: `batch-${actionEntries[0].event._id}`, type: 'inbox.batch', commentTarget: commentTargetOf(actionEntries[0].event), payload: { ...actionEntries[0].event.payload, batchEventIds: entries.filter((entry) => !entry.pastCap).map((entry) => String(entry.event._id)), hasHeartbeat: entries.some((entry) => !entry.pastCap && entry.event.type === 'heartbeat'), onlyHeartbeat: entries.filter((entry) => !entry.pastCap) .every((entry) => entry.event.type === 'heartbeat'), someoneWaiting: entries.some((entry) => !entry.pastCap && someoneIsWaiting(entry.event)), }, }; // One item, run as its own turn. Used only after the provider refused a // batch's content: a composite turn cannot say WHICH item was refused, and // refusing them all would swallow the ordinary items with the flagged one. const isolatedTurn = async (entry) => { const before = await snapshotMessages(); return runTurn({ event: { ...entry.event, _id: `batch-${entry.event._id}`, type: 'inbox.batch', payload: { ...entry.event.payload, batchEventIds: [String(entry.event._id)], hasHeartbeat: entry.event.type === 'heartbeat', onlyHeartbeat: entry.event.type === 'heartbeat', someoneWaiting: someoneIsWaiting(entry.event), }, }, eventPodId, prompt: buildInboxPrompt([entry], 1, { pod: podAttendance }), preSpawnIds: before ? new Set(before.map((message) => String(message._id || message.id))) : null, snapshotMessages, claimKeeper: entry.claimKeeper, trigger, withoutConventions: true, }); }; const plainPrompt = buildInboxPrompt(entries, inboxCount, { pod: podAttendance }); const turnPrompt = personMentioned ? buildInboxPrompt(entries, inboxCount, { pod: podAttendance, unreadBodiesPodId: eventPodId }) : plainPrompt; let turnResult; let deferredError = null; const firstTurn = {}; try { try { turnResult = await runTurn({ event: batchEvent, eventPodId, prompt: turnPrompt, preSpawnIds, snapshotMessages, claimKeeper: compositeClaimKeeper, trigger, report: firstTurn, }); for (const entry of actionEntries) entry.result = turnResult; // A digest was context in this successful waking turn, never an // independent action. If the waking work stood down or the provider // refused the batch, leave it unread for the next real turn. A reply // the server skipped as `silent_or_empty` is the seat choosing silence // (the server's answer to an intentional NO_REPLY), so it read the // digest. Empty output (`empty-output`) is not a choice anyone can see: // a broken seat produces it every turn, and reading on it would drain // the backlog that seat never saw. if (turnResult?.outcome === 'posted' || (turnResult?.outcome === 'no_action' && (!turnResult?.reason || turnResult.reason === 'silent_or_empty'))) { for (const entry of activeEntries) { if (entry.event.deliveryMode === 'digest' && !entry.pastCap) { entry.result = { outcome: 'no_action', reason: 'digest-read' }; } } } } catch (err) { // F436: a signed-out Claude Code fails every turn the same way until // someone signs in. Held, the event sat behind the 15-minute circuit; // acked, the pod hears why now and the next event is the re-probe. if (isClaudeSignedOut(err)) { for (const entry of actionEntries) entry.result = claudeSignedOutResult(); log(`[inbox.batch] ${CLAUDE_SIGNED_OUT_FIX}`); await noticeCantAnswer(err, actionEntries.map((entry) => entry.event)); return { entries }; } if (!isContentRefusal(err)) throw err; // Ambient text anyone wrote can draw the refusal, and no waking item // should pay for that. So the same items run once more with counts // only. A posted wake still settles those digests on the server, the // same as any counts-only turn. let refused = true; if (turnPrompt !== plainPrompt || firstTurn.carriedConventions) { log('[inbox.batch] the model provider refused a turn that carried unread messages or pod conventions ' + '(content_refused); running it once more without them'); try { const before = await snapshotMessages(); turnResult = await runTurn({ event: batchEvent, eventPodId, prompt: plainPrompt, preSpawnIds: before ? new Set(before.map((message) => String(message._id || message.id))) : null, snapshotMessages, claimKeeper: compositeClaimKeeper, trigger, withoutConventions: true, }); for (const entry of actionEntries) entry.result = turnResult; refused = false; } catch (rerunErr) { if (!isContentRefusal(rerunErr)) throw rerunErr; } } if (!refused) return { entries }; if (actionEntries.length === 1) { actionEntries[0].result = contentRefusedResult(); } else { log( `[inbox.batch] the model provider refused this batch's content (content_refused); ` + `running its ${actionEntries.length} items one at a time so only a refused item is refused`, ); for (const entry of actionEntries) { if (!running) break; try { // eslint-disable-next-line no-await-in-loop entry.result = await isolatedTurn(entry); } catch (itemErr) { // Any other failure stops here and leaves this item and the rest // unacked for redelivery; the tick applies the retry policy. if (!isContentRefusal(itemErr)) { deferredError = itemErr; break; } entry.result = contentRefusedResult(); } } } await postRefusalNotice( actionEntries.filter((entry) => entry.result?.reason === CONTENT_REFUSED_REASON), eventPodId, ); } return deferredError ? { entries, deferredError } : { entries }; } finally { await Promise.all(actionEntries .filter((entry) => entry.claimKeeper) .map(async (entry) => { // Preserve ADR-018 D6.1 per binding message: a silent human // broadcast may be handed to one remaining listener, a refusal // closes with its reason, and every other completed batch item // closes normally. Same decision point as the single-event path. // An item left without a result (a failure during isolation) // releases with no outcome, for redelivery, as a thrown turn does. const release = claimReleaseFor(entry.event, entry.result || turnResult); // A retry that chose NO_REPLY because its single-item attempt already // posted the answer answered the person, so it closes, never handed // to another listener. A retry that printed nothing chose nothing, // and a batch's post may be another item's: both still decline, so a // batch whose post answered every item can be handed on (a known // limit; telling which item a post answered needs a signal we lack). if (release.outcome === 'declined' && actionEntries.length === 1 && (entry.result || turnResult)?.reason !== EMPTY_OUTPUT && heldRetryParts.get(String(entry.event._id))?.solo) release.outcome = 'completed'; await entry.claimKeeper.release(release.outcome, { reason: release.reason, status: release.status, }); })); } }; const processEventBatch = async (events, inboxCount = events.length) => { const deliveries = events.filter((event) => typeof event.payload?.deliveryId === 'string' && event.payload.deliveryId) .map((event) => ({ eventId: String(event._id), deliveryId: event.payload.deliveryId })); let renewing = false; let renewalStopped = false; const renew = async () => { if (renewalStopped || renewing || deliveries.length === 0) return; renewing = true; try { for (let offset = 0; offset < deliveries.length && !renewalStopped; offset += 50) { await client.post('/api/agents/runtime/events/renew', { events: deliveries.slice(offset, offset + 50), }); } } catch (error) { // An older server may lack this route. Never reinterpret a failed // renewal as an ack: stale checkpoint nonces still fail closed. log(`[inbox.batch] delivery renewal failed: ${error.message}`); } finally { renewing = false; } }; const timer = deliveries.length ? setIntervalImpl(renew, DELIVERY_RENEW_INTERVAL_MS) : null; const stopRenewal = () => { renewalStopped = true; if (timer !== null) clearIntervalImpl(timer); }; // Independent of adapter settlement: SIGTERM can be ignored, so awaiting // spawn in finally is not a bound on the event's delivery lease. const deadlineTimer = deliveries.length ? setDeadlineTimeoutImpl(() => { stopRenewal(); log('[inbox.batch] turn deadline reached; delivery renewal stopped for GC recovery'); }, effectiveTurnTimeoutMs) : null; try { return await handleEventBatch(events, inboxCount); } finally { stopRenewal(); if (deadlineTimer !== null) clearDeadlineTimeoutImpl(deadlineTimer); } }; // A model turn is not a stall, however long it runs: the liveness clock // stops for it and restarts when it ends. const duringTurn = async (turn) => { pollLiveness.pause(); try { return await turn(); } finally { pollLiveness.arm(); } }; // The scheduled next tick, so stop() can cancel it: a stopped run idling in // a 15-minute circuit wait otherwise stays alive until the timer fires, // which is why a walk on 2026-11-05 needed repeated signals to end it. let tickTimer = null; let tickInFlight = false; // stop() returns this: it resolves once the hand-back has answered, whether // the idle stop or the in-flight tick's end performs it. let stopped = null; let resolveStopped = () => {}; const tick = async () => { tickTimer = null; if (!running) return; tickInFlight = true; try { await (circuitNotice ? runCircuitNoticeCheck() : runTick()); } finally { tickInFlight = false; if (!running) { try { await handBackCarryOnStop(); } finally { resolveStopped(); } } } }; // F236: set when a retry opens the circuit for a failure a person can be // told about; `remainingMs` is what is left of the wait after the next check. let circuitNotice = null; const runTick = async () => { tickUnsettled = []; circuitNotice = null; let nextPollDelayMs = intervalMs; let completedModelTurn = false; let retryScheduled = false; try { // ADR-024 D3: this is an inbox fetch, not a stream of interrupts. The // backend returns one pod's oldest pending batch, so the rows below belong // to one composite turn, and what doesn't fit its prompt is carried to the // next (F226). The service selects the pod before claiming any row; // do not reintroduce a mixed-pod `limit: 10` here. // TASK-317: name this CLI for the chat chip. The server keeps it as a // display-only label (runtime.reportedCli) and never as a binding. // The liveness clock runs from here until the next scheduled wait, paused // only while a model turn runs (lib/poll-liveness.js). pollLiveness.arm(); // Leave room for what this loop carries (a held greeting, a failed // batch), so a carried event never pushes a full page past the prompt's // body cap and a busy pod can't keep the greeting out (CodeRabbit on // #3511). The overflow pass below stays as the backstop. // Only wake events count: the server's page cap is on wakes, and a // carried digest row takes no body (CodeRabbit on #3511). // F237: a full carry in an outage claims nothing new (inboxQuery). const page = await client.get('/api/agents/runtime/events', inboxQuery()); pollLiveness.arm(); // A stall fired while this request hung: the loop has already given up on // it, and `agent run` exits in onStall, so its page is left to the requeue. // A plain stop() falls through instead, to the group loop's own `running` // check, which hands the page back. if (pollStalled) return; const { events = [], inboxCount } = page; consecutiveAuthErrors = 0; consecutivePollFailures = 0; // A deployed CLI can briefly run against an older server that still // returns multiple pods in one page. Preserve pod privacy in that // migration window by partitioning locally. Current servers produce one // group, so the normal path remains one tick → one turn. // A carried greeting or failed batch rejoins the inbox here, so it is // grouped, ordered and acked by exactly the same path as anything the // poll returned. The carried row is still 'delivered' on the server, so a // requeue during the carry can hand the same id back in this very page: // drop the carried copy rather than processing it twice. The fetched // copy wins because it carries the live deliveryId; the carried one's // nonce was cleared by that requeue. const carried = [...heldRetry, ...heldGreeting]; heldGreeting = []; heldRetry = []; clearHeldRenewal(); const fetchedIds = new Set(events.map((event) => String(event._id))); const carriedIds = new Set(); const carriedFresh = carried.filter((event) => { const id = String(event._id); if (fetchedIds.has(id) || carriedIds.has(id)) return false; carriedIds.add(id); return true; }); const pageEvents = carriedFresh.length ? [...carriedFresh, ...events] : events; const pageInboxCount = (Number.isFinite(inboxCount) ? inboxCount : events.length) + carriedFresh.length; if (pageEvents.length) idleHeartbeat.busy(); else if (running) idleHeartbeat.empty(); const eventGroups = new Map(); for (const event of pageEvents) { const eventPodId = event.podId || podId; const key = PRIVATE_RESPONSE_EVENT_TYPES.has(event.type) || isCommentWake(event) ? `private:${event._id}` : (eventPodId || `private:${event._id}`); const group = eventGroups.get(key) || []; group.push(event); eventGroups.set(key, group); } // A carried greeting must not push a full page past the prompt's body // cap (CodeRabbit on #3511). It goes back to the greeting hold instead // of the past-cap carry. for (const [key, group] of eventGroups) { const wakeCount = group.filter((event) => event.deliveryMode !== 'digest').length; if (wakeCount <= batchLimit) continue; const overflow = group.filter((event) => carriedIds.has(String(event._id)) && DEFERRABLE_SOLO_EVENT_TYPES.has(event.type)); if (!overflow.length) continue; heldGreeting = [...heldGreeting, ...overflow]; eventGroups.set(key, group.filter((event) => !overflow.includes(event))); } // A digest row has to be shown by the turn whose ack settles it. That is // the page's first wake, which carries digestSnapshotAt, so a comment // holding it takes the digest with it, or the settle would take rows no // turn had shown. So does a comment when no pod wake exists to show them. for (const [key, group] of eventGroups) { if (key.startsWith('private:')) continue; const digests = group.filter((event) => event.deliveryMode === 'digest'); const comments = [...eventGroups.values()] .filter(([event]) => commentTargetOf(event) && (event.podId || podId) === key); const holder = comments.find(([event]) => event.digestSnapshotAt) || (digests.length === group.length ? comments[0] : null); if (digests.length === 0 || !holder) continue; holder.push(...digests); if (digests.length === group.length) eventGroups.delete(key); else eventGroups.set(key, group.filter((event) => event.deliveryMode !== 'digest')); } // A comment @ has its own group, so the batch sort can't lead with it. const groupPriority = (group) => Math.min(...group.map(inboxPriority)); const groups = [...eventGroups.values()].filter((group) => group.length > 0) .sort((a, b) => groupPriority(a) - groupPriority(b)); // The greeting window is counted once per poll, however many pods' // greetings this page carries (gate review of #3511). let greetingCarriedThisPoll = false; // The events a failure at `groupIndex` stops before they run. A later // digest-only group never starts a turn of its own, so a retry does not // carry it. const untriedAfter = (groupIndex) => groups.slice(groupIndex + 1) .filter((later) => !later.every((event) => event.deliveryMode === 'digest')) .flat(); // Every later group a stop must hand back. The server claims a digest // alongside a wake on the same page, and a private wake groups apart // from it, so a digest-only group here can be `delivered` to this run. const claimedAfter = (groupIndex) => groups.slice(groupIndex + 1).flat(); // F237 item 1: the page's groups run one turn at a time, and a later // group's rows were claimed when the page was read. A turn may run 15 // minutes and the server requeues a delivered row after 10, so they are // renewed while an earlier group runs. A row the server says is no // longer this runner's is taken out before its group starts: its ack // would be a stale delivery, which stops the run, and the requeue // redelivers it. // Bounded by the running turn's deadline, as processEventBatch bounds // its own renewal: a turn whose child ignores SIGTERM can hang, and the // rows behind it must lapse to the requeue rather than stay with it. let firstWaitingGroup = 1; let runningGroupSince = Date.now(); let deadlineLogged = false; // One renewal at a time. A group's turn waits for one still out, so the // groups it names have not started when its answer is applied // (CodeRabbit on #4067). let renewingLater = null; clearLaterGroupsRenewal(); if (groups.length > 1) { laterGroupsRenewTimer = setIntervalImpl(async () => { if (!running) { clearLaterGroupsRenewal(); return; } if (renewingLater) return; // Skipped, not stopped: the next group restarts the clock, and its // turn needs the rows behind it renewed again. if (Date.now() - runningGroupSince >= effectiveTurnTimeoutMs) { if (!deadlineLogged) { deadlineLogged = true; log('[inbox.batch] turn deadline reached; renewal of the later pods\' rows paused while this turn overruns'); } return; } const from = firstWaitingGroup; renewingLater = (async () => { const confirmed = await renewHeldDeliveries(claimedAfter(from - 1)); if (confirmed === null) return; let lost = 0; for (let later = from; later < groups.length; later += 1) { const kept = groups[later].filter((event) => stillHeld(event, confirmed)); lost += groups[later].length - kept.length; groups[later] = kept; } if (lost) { log( `[inbox.batch] ${countEvents(lost)} no longer held by this runner on the server while ` + 'another pod\'s turn ran — not run; the server redelivers it', ); } })().finally(() => { renewingLater = null; }); await renewingLater; }, DELIVERY_RENEW_INTERVAL_MS); laterGroupsRenewTimer?.unref?.(); } for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) { // renewHeldDeliveries never throws: a failed renewal resolves null. // eslint-disable-next-line no-await-in-loop if (renewingLater) await renewingLater; firstWaitingGroup = groupIndex + 1; runningGroupSince = Date.now(); deadlineLogged = false; const group = groups[groupIndex]; if (group.length === 0) continue; if (!running) { // Claimed by this tick's poll (or carried into it) and never run: // a stop that arrived mid-poll or mid-page (F182). Handed back when // the tick ends. heldRetry = [...heldRetry, ...group, ...claimedAfter(groupIndex)]; break; } // A current kernel never claims a digest-only page. Guard a mixed // version rollout too: an ambient batch must not start a model turn. if (group.every((event) => event.deliveryMode === 'digest')) { log(`[inbox.batch] digest-only page (${group.length}) — no spawn or ack`); tickUnsettled.push(...group); continue; } if ((group[0].podId || podId) && !PRIVATE_RESPONSE_EVENT_TYPES.has(group[0].type)) { // Nothing in this batch but the seat introducing itself: leave it // unacked for up to GREETING_HOLD_MS, so a person who mentions the // agent in that window is answered first, in the same turn, instead // of behind a greeting. Only the connect-time greeting is held: once // a turn has carried one, later greetings run as they arrive. // Digest rows ride along with a greeting without counting as a // person waiting (CodeRabbit on #3511). The window is bounded by the // clock too, so turns run for other pods between polls can't stretch // the carry past its delivery lease (CodeRabbit on #3511). if (!greetingHoldSpent && (greetingCarriedThisPoll || (greetingHeldPolls < greetingHoldPolls && (greetingHoldStartedAt === null || Date.now() - greetingHoldStartedAt < GREETING_HOLD_MS))) && group.some((event) => DEFERRABLE_SOLO_EVENT_TYPES.has(event.type)) && group.every((event) => DEFERRABLE_SOLO_EVENT_TYPES.has(event.type) || event.deliveryMode === 'digest')) { if (greetingHeldPolls === 0 && !greetingCarriedThisPoll) { log(`[inbox.batch] carrying ${group.length} greeting event(s) for up to ` + `${Math.round(GREETING_HOLD_MS / 1000)} s, so a person who mentions this agent is answered first`); } if (!greetingCarriedThisPoll) { greetingCarriedThisPoll = true; greetingHeldPolls += 1; if (greetingHoldStartedAt === null) greetingHoldStartedAt = Date.now(); } // Appended, never assigned: two pods' greetings can be carried in // the same window, and an overwrite left the first unacked until // the server's requeue, 10 to 20 minutes later. heldGreeting = [...heldGreeting, ...group]; continue; } if (group.some((event) => DEFERRABLE_SOLO_EVENT_TYPES.has(event.type))) greetingHoldSpent = true; // One failure report for a batch whose items stay unacked, whether // the composite turn threw or an isolated item did after a refusal. // The unacked items are carried to the retry, not left to the // requeue sweep, so the delay below is when they run again. const scheduleBatchRetry = async (err, failedEvents) => { const externalSignal = countSpawnFailure(err); const retry = spawnRetryPolicy({ error: err, consecutiveFailures: consecutiveSpawnFailures, intervalMs, jitterRatio: spawnJitterRatio, externalSignal, }); nextPollDelayMs = retry.delayMs; retryScheduled = true; circuitNotice = retry.circuitOpen && cantAnswerNotice(err) && !modelUnavailableFailure(err) ? { error: err, remainingMs: retry.delayMs } : null; tickUnsettled.push(...claimedAfter(groupIndex)); const attempted = failedEvents.filter((event) => !pastCapEvents.includes(event)); await noteFailedTurnPart(attempted); const hold = await holdForRetry( attempted, untriedAfter(groupIndex), pastCapEvents, { strike: !externalSignal }, ); keepHeldLeases(retry.delayMs); const event = group[0]; const wrapped = new Error( `inbox batch processing failed (${retry.failureClass}; ${consecutiveSpawnFailures} consecutive) ` + `— ${describeHold(hold, retry)}: ${err.message}`, { cause: err }, ); Object.assign(wrapped, { code: 'agent_spawn_retry_scheduled', failureClass: retry.failureClass, consecutiveFailures: consecutiveSpawnFailures, retryAfterMs: retry.delayMs, circuitOpen: retry.circuitOpen, heldCount: hold.held.length, releasedCount: hold.released.length, eventId: event._id, ...(isPodFocusDiagnostic(err) ? { focusDiagnostic: { errorCode: err.code, eventIds: err.eventId || group.map((entry) => entry._id), podId: err.podId || group[0]?.podId || podId || null, focusRevision: err.focusRevision ?? null, measuredCodePoints: err.measuredCodePoints ?? null, allowedCodePoints: err.allowedCodePoints ?? FOCUS_FRAME_MAX_CODE_POINTS, }, } : {}), }); if (onError) onError(wrapped); else log(`[inbox.batch] ${wrapped.message}`); await noticeCutOff(hold.lost, { released: hold.released, part: hold.part }); await noticeCantAnswer(err, [...failedEvents, ...untriedAfter(groupIndex)]); }; let batch; try { // The person's item leads the prompt; the greeting rides along. batch = await duringTurn(() => processEventBatch( [...group].sort((a, b) => inboxPriority(a) - inboxPriority(b)), // The page's other events get their own turns. commentTargetOf(group[0]) ? group.length : pageInboxCount, )); } catch (err) { await scheduleBatchRetry(err, group); break; } const batchSpawned = batch.entries.some((entry) => ( entry.result?.outcome === 'posted' || (entry.result?.outcome === 'no_action' && (!entry.result?.reason || entry.result.reason === EMPTY_OUTPUT)) )); if (batchSpawned) { consecutiveSpawnFailures = 0; externalSignalStreak = 0; // Notices arriving mid-turn get one bounded collection window. // Idle polls and batches with no model turn keep their cadence. completedModelTurn = true; } for (const entry of batch.entries) { const event = entry.event; // No result: an item a failure during refusal isolation never // reached. Unacked, the kernel redelivers it. if (!entry.result) continue; if (entry.result?.reason !== 'duplicate-delivery') { recordHandledEvent(stateKey, event._id); } try { const deliveryId = event.payload?.deliveryId; await client.post(`/api/agents/runtime/events/${event._id}/ack`, { result: ackResultFor(entry.result), ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}), }); } catch (ackErr) { const terminalError = terminalDeliveryAckError(ackErr, event._id, 'agent run'); if (terminalError) { running = false; onError?.(terminalError); break; } onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`)); } } if (batch.deferredError) { await scheduleBatchRetry( batch.deferredError, batch.entries.filter((entry) => !entry.result).map((entry) => entry.event), ); break; } // Items a stop cut off before they ran (refusal isolation checks // `running`), and any digest this batch left unread. tickUnsettled.push(...batch.entries.filter((entry) => !entry.result).map((entry) => entry.event)); if (pastCapEvents.length) { await holdForRetry([], [], pastCapEvents); keepHeldLeases(nextPollDelayMs); } continue; } const [event] = group; let result; if (wasEventHandled(stateKey, event._id)) { result = { outcome: 'no_action', reason: 'duplicate-delivery' }; log(`[${event.type}] duplicate delivery ${event._id} — skipping spawn and re-acking`); } else { const eventWillSpawn = Boolean(extractPrompt(event) && (event.podId || podId)); try { result = await duringTurn(() => processEvent(event)); } catch (err) { if (isContentRefusal(err)) { // A refused private item is acked without a pod notice: it has no // pod to post into, and its sender's ask expires on its own. result = contentRefusedResult(); log(`[${event.type}] the model provider refused the content of event ${event._id} (content_refused) — acked as refused, not retried`); } else if (isClaudeSignedOut(err)) { // F436, as in the batch path. A pod-less or private item has no // pod to tell, so the log line is the whole notice. result = claudeSignedOutResult(); log(`[${event.type}] ${CLAUDE_SIGNED_OUT_FIX}`); } else { // Do not record or ack: the kernel must retain the event for // at-least-once delivery. Stop this fetched batch immediately — // continuing could launch every one of the 10 returned events // into the same provider outage before the next poll (#782). const externalSignal = countSpawnFailure(err); const retry = spawnRetryPolicy({ error: err, consecutiveFailures: consecutiveSpawnFailures, intervalMs, jitterRatio: spawnJitterRatio, externalSignal, }); nextPollDelayMs = retry.delayMs; retryScheduled = true; // Carried to the retry like a failed batch: the event is claimed, // so the next poll would not return it. tickUnsettled.push(...claimedAfter(groupIndex)); // Only this event's own turn: a throw before its spawn leaves an // earlier turn's arguments, possibly another pod's, in failedTurn. // eslint-disable-next-line no-await-in-loop if (failedTurn?.event === event) await noteFailedTurnPart([event]); // eslint-disable-next-line no-await-in-loop const hold = await holdForRetry([event], untriedAfter(groupIndex), [], { strike: !externalSignal }); keepHeldLeases(retry.delayMs); const wrapped = new Error( `${event.type} processing failed (${retry.failureClass}; ` + `${consecutiveSpawnFailures} consecutive) — event ${event._id} unacked; ` + `${describeHold(hold, retry)}: ${err.message}`, { cause: err }, ); Object.assign(wrapped, { code: 'agent_spawn_retry_scheduled', failureClass: retry.failureClass, consecutiveFailures: consecutiveSpawnFailures, retryAfterMs: retry.delayMs, circuitOpen: retry.circuitOpen, heldCount: hold.held.length, releasedCount: hold.released.length, eventId: event._id, ...(isPodFocusDiagnostic(err) ? { focusDiagnostic: { errorCode: err.code, eventIds: err.eventId || event._id, podId: err.podId || event.podId || podId || null, focusRevision: err.focusRevision ?? null, measuredCodePoints: err.measuredCodePoints ?? null, allowedCodePoints: err.allowedCodePoints ?? FOCUS_FRAME_MAX_CODE_POINTS, }, } : {}), }); // ONE emission, not two. `wrapped.message` already opens with the // event type, so the log copy added a second prefix and a second // line of identical text into the same merged stream — enough that // `grep -c 'session limit'` returned 8 for 4 failures, and a reader // counting hits per event id saw 2 and inferred two deliveries. // On 2026-08-18 that count pointed at the wrong cause for #993: // two deliveries per event puts `attempts` at 2 and the requeue cap // one step away. It did not decide anything — the cap was ruled out // from the DB, where a capped event would have left a `failed` row // and none existed — but it corroborated the wrong theory, and the // doubling had to be spotted by hand before the count could be // discounted. A log that inflates is worse than one that is silent, // because it argues. // // Routed to the error channel when a caller provides one, and to // the log when it doesn't, so neither contract loses the failure: // an embedder that passes no `onError` still sees it, and `agent // run` — which always passes one — stops printing it twice. if (onError) onError(wrapped); else log(`[${event.type}] ${wrapped.message}`); break; } } // Only a completed model turn proves the local runtime and delivery // path recovered. A malformed/no-destination event is still acked, // but must not erase the failure streak without exercising either — // and neither may an enforcement stand-down (cascade cap, lost // claim), which returns before any spawn happens. const stoodDown = result?.reason === 'cascade-cap' || result?.reason === 'claim-held'; if (eventWillSpawn && !stoodDown) { consecutiveSpawnFailures = 0; externalSignalStreak = 0; } // Record after successful processing but before ack. If the ack // fails, the next delivery is skipped and re-acked instead of // burning a second model turn for work that already completed. recordHandledEvent(stateKey, event._id); } try { const deliveryId = event.payload?.deliveryId; await client.post(`/api/agents/runtime/events/${event._id}/ack`, { result: ackResultFor(result), ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}), }); } catch (ackErr) { const terminalError = terminalDeliveryAckError(ackErr, event._id, 'agent run'); if (terminalError) { running = false; onError?.(terminalError); tickUnsettled.push(...claimedAfter(groupIndex)); return; } onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`)); } } } catch (err) { if (err?.status === 401 || err?.status === 403) { consecutiveAuthErrors += 1; if (consecutiveAuthErrors >= MAX_AUTH_ERRORS) { onError?.(new Error( `Runtime token rejected ${consecutiveAuthErrors} times in a row — stopping. ` + `If this agent's key was reissued, run it again with the new key in COMMONLY_AGENT_TOKEN. ` + `To remove the agent from its pod: ${CLI} agent detach ${agentName}`, )); running = false; return; } } else { // TASK-025: everything that is not an auth rejection used to fall // through to `onError` with `nextPollDelayMs` still at `intervalMs`, // because that variable is only reassigned in the spawn-retry branch // above and a failed fetch never reaches it. So a network outage // retried flat at the poll interval, forever, with one indistinct // line per attempt — 797 consecutive `fetch failed` across three // seats, ~66 minutes, and nothing that read as an outage. // // Deliberately NOT a stop. `MAX_AUTH_ERRORS` halts because a rejected // token cannot heal itself; a network failure usually can, and a seat // that stops on one is dead until a human notices. consecutivePollFailures += 1; idleHeartbeat.busy(); const retry = pollRetryPolicy({ consecutiveFailures: consecutivePollFailures, intervalMs, jitterRatio: spawnJitterRatio, }); nextPollDelayMs = retry.delayMs; if (retry.escalate) { log( `poll failed ${consecutivePollFailures}x in a row ` + `(${err?.message || 'unknown error'}) — backing off to ` + `${formatRetryDelay(retry.delayMs)}` + `${retry.atCeiling ? ', at the ceiling' : ''}`, ); } } onError?.(err); } clearLaterGroupsRenewal(); // Notices landing during a turn share one three-second collection window // before the next inbox read, independent of the idle polling cadence. A // retry scheduled in the same tick keeps its own delay: the failure report // names it, and a sibling's completed turn must not shorten the backoff. // A wait the loop schedules itself always ends, so it is not a stall. pollLiveness.pause(); const waitMs = completedModelTurn && !retryScheduled ? 3000 : nextPollDelayMs; const checkMs = Math.max(CIRCUIT_NOTICE_CHECK_MS, intervalMs); if (circuitNotice && waitMs > checkMs) circuitNotice.remainingMs = waitMs - checkMs; else circuitNotice = null; if (running) tickTimer = setTimeoutImpl(tick, circuitNotice ? checkMs : waitMs); }; // F236: one check during a circuit wait. What it claims joins the carry, so // the probe runs it, a stop hands it back, and its leases are renewed; each // newly waiting pod is told why. No turn runs here. const runCircuitNoticeCheck = async () => { const wait = circuitNotice; try { pollLiveness.arm(); // A full carry here claims nothing new (F237): a pod whose first message // arrives then is told once the carry has room, not by this check. const page = await client.get('/api/agents/runtime/events', inboxQuery({ inOutage: true })); pollLiveness.arm(); if (pollStalled) return; const fetched = page?.events || []; // A carried id comes back only after the server requeued it, so the // fetched copy holds the live deliveryId and the carried one's is dead. // The fetched copy wins, as in runTick: otherwise the probe, which can no // longer fetch it, would ack a stale nonce and stop the run. const fetchedById = new Map(fetched.map((event) => [String(event._id), event])); // Reassigned only when a copy changes, so the renewal's `heldRetry !== carry` // guard skips its pruning only when there was something to replace. const refetched = (carry) => carry.some((event) => fetchedById.has(String(event._id))); const refreshCarry = (carry) => carry.map((event) => fetchedById.get(String(event._id)) || event); if (refetched(heldRetry)) heldRetry = refreshCarry(heldRetry); if (refetched(heldGreeting)) heldGreeting = refreshCarry(heldGreeting); const carriedIds = new Set([...heldRetry, ...heldGreeting].map((event) => String(event._id))); const fresh = fetched.filter((event) => !carriedIds.has(String(event._id))); if (fetched.length) idleHeartbeat.busy(); if (fresh.length) await holdForRetry([], fresh); if (fetched.length) keepHeldLeases(wait.remainingMs); if (fresh.length) await noticeCantAnswer(wait.error, fresh); } catch (error) { log(`[inbox.batch] inbox check during the circuit wait failed: ${error.message}`); } pollLiveness.pause(); const checkMs = Math.max(CIRCUIT_NOTICE_CHECK_MS, intervalMs); const stepMs = Math.min(checkMs, wait.remainingMs); wait.remainingMs -= stepMs; if (wait.remainingMs <= 0) circuitNotice = null; if (running) tickTimer = setTimeoutImpl(tick, stepMs); }; tick(); return { // Resolves once anything held has been handed back. A tick in flight hands // back its own carry when it ends; an idle run does it here. A second // stop() returns the same promise. stop: () => { if (stopped) return stopped; stopped = new Promise((resolve) => { resolveStopped = resolve; }); running = false; pollLiveness.stop(); clearHeldRenewal(); if (tickTimer !== null) { clearTimeoutImpl(tickTimer); tickTimer = null; } if (!tickInFlight) handBackCarryOnStop().finally(() => resolveStopped()); return stopped; }, }; }; // ── init: scaffold a webhook-SDK agent (ADR-006 §Scaffolding) ─────────────── const SUPPORTED_LANGUAGES = ['python']; // Resolve a repo-relative path from this module, regardless of where the CLI // is invoked from. agent.js lives at cli/src/commands/agent.js → repo root is // three levels up. The scaffolder copies the canonical SDK file from the repo // into the user's cwd; ADR-006 §SDK lives = "live-copy, not dependency". // // The published package carries these files under cli/assets/webhook-sdk/, // bundled from examples/ by scripts/bundle-sdk-examples.mjs at prepack (npm // pack and publish run it). A repo clone that has not packed yet falls back to // the examples/ tree, which stays the single source of truth. const cliRoot = pathResolve(dirname(fileURLToPath(import.meta.url)), '..', '..'); const sdkAsset = (bundledRel, repoRel) => { const bundled = pathResolve(cliRoot, 'assets', 'webhook-sdk', bundledRel); return existsSync(bundled) ? bundled : pathResolve(cliRoot, '..', 'examples', repoRel); }; const SDK_SOURCES = { python: { sdkSrc: () => sdkAsset('python/commonly.py', join('sdk', 'python', 'commonly.py')), botSrc: () => sdkAsset('python/bot.py', join('hello-world-python', 'bot.py')), sdkOut: 'commonly.py', botOut: (name) => `${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)`, }, }; /** * Scaffold a webhook-SDK agent into `targetDir`. Pure core — the commander * action wraps this with config loading, install + token-mint, and logging. * * Refuses to clobber any of the three output files. Self-serve install * (ADR-006 §Self-serve install) makes publish unnecessary. */ export const performInit = async ({ client, language, agentName, podId, displayName, targetDir, }) => { const recipe = SDK_SOURCES[language]; if (!recipe) { throw new Error( `Unsupported language "${language}". Supported: ${SUPPORTED_LANGUAGES.join(', ')}`, ); } const sdkOutPath = join(targetDir, recipe.sdkOut); const botOutPath = join(targetDir, recipe.botOut(agentName)); const tokenOutPath = join(targetDir, '.commonly-env'); for (const f of [sdkOutPath, botOutPath, tokenOutPath]) { if (existsSync(f)) { throw new Error(`Refusing to overwrite existing file: ${f}`); } } if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true }); // Copy the SDK file verbatim; copy the bot template byte-for-byte (the // user renames their handler later — file name carries the agent name). writeFileSync(sdkOutPath, readFileSync(recipe.sdkSrc(), 'utf8'), 'utf8'); writeFileSync(botOutPath, readFileSync(recipe.botSrc(), 'utf8'), 'utf8'); // Self-serve install (ADR-006). No publish step; the backend synthesizes // an ephemeral registry row when no manifest exists for this name. const installResult = await client.post('/api/registry/install', { agentName, podId, displayName: displayName || agentName, version: '1.0.0', config: { runtime: { runtimeType: 'webhook', host: 'byo' } }, scopes: ['context:read', 'messages:write', 'memory:read', 'memory:write'], }); 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) { // ADR-005 §detach + reattach: pass force:true so the server clears the // hashed-but-unrecoverable prior token and mints fresh. const tokenData = await client.post( `/api/registry/pods/${podId}/agents/${agentName}/runtime-tokens`, { force: true }, ); runtimeToken = tokenData.token; } if (!runtimeToken) { throw new Error('Runtime token was not returned by install or tokens endpoint'); } // .commonly-env uses KEY=VALUE format so `source .commonly-env`, dotenv, // and standard env-loading tools work out of the box. Future keys (e.g. // COMMONLY_BASE_URL) just append. Mode 0600 (POSIX) since the file holds // a long-lived bearer token. writeFileSync(tokenOutPath, `COMMONLY_TOKEN=${runtimeToken}\n`, { encoding: 'utf8', mode: 0o600 }); return { installation, instanceId, mentionHandle, runtimeToken, files: { sdk: sdkOutPath, bot: botOutPath, env: tokenOutPath, }, runHint: recipe.runHint(agentName), }; }; // ── detach: uninstall a local-CLI-wrapped agent (ADR-005) ─────────────────── /** * Uninstall the agent from its pod AND clean up local token + session files. * * The three pieces of state created by `attach` are removed in this order: * 1. Backend: AgentInstallation (DELETE /api/registry/agents/:name/pods/:podId * marks uninstalled, deletes AgentProfile, removes agent User from pod). * The runtime token tied to the User row is GC'd by the cleanup service * 7 days after all installs go inactive — we don't force-revoke here * because the token may legitimately still be in use for another pod. * 2. Local token file at ~/.commonly/tokens/.json * 3. Local session + handled-event stores at * ~/.commonly/sessions/{,.events}.json * * Idempotent: if the backend returns 404 (already uninstalled elsewhere), we * still clean up local files so the CLI state stays in sync with reality. * `--force` / `skipBackend:true` short-circuits to local-only cleanup for * the case where the backend has already been uninstalled via another path. */ export const performDetach = async ({ client, agentName, podId, instanceId = 'default', // F306: the token file to remove; a second instance's is `@`. localKey = null, skipBackend = false, log = () => {}, }) => { if (!agentName || (!skipBackend && !podId)) { // A corrupted token file could leave us without a podId; without this // guard `encodeURIComponent(undefined)` produces a request against // `/pods/undefined` that the backend 404s, silently succeeding. throw new Error( 'performDetach requires agentName (and podId unless skipBackend=true)', ); } let backendResult = { skipped: true }; if (!skipBackend) { try { const body = await client.del(`/api/registry/agents/${encodeURIComponent(agentName)}/pods/${encodeURIComponent(podId)}?instanceId=${encodeURIComponent(instanceId)}`); backendResult = { skipped: false, body }; log(`backend: uninstalled '${agentName}' from pod ${podId}`); } catch (err) { // 404 means "already gone" — continue to local cleanup. if (err.status === 404) { backendResult = { skipped: false, alreadyGone: true }; log(`backend: '${agentName}' already uninstalled from pod ${podId}`); } else { // Re-throw anything else (403 auth, 500, network) — caller decides. throw err; } } } const stateKey = localKey || agentName; deleteAgentToken(stateKey); clearSessions(stateKey); log(`local: removed token file + session store for '${stateKey}'`); return { backend: backendResult, localCleaned: true }; }; /** * Every line a seat emits lands in one file, because the fleet is launched as * `nohup commonly agent run > 2>&1`. Until now none of those lines * carried a time. * * That is not a cosmetic gap. On 2026-08-18 a fleet-wide quota stall destroyed * 38 queued events (#993), and the seat log was the ONLY surviving trace — * the kernel rows were deleted, so nothing else recorded that those turns had * been attempted. The log records `(4 consecutive)` and `next probe in 2.0m` * and gives no way to place either on a clock: the investigation had to date * events by decoding ObjectId prefixes instead, because the file that named * them could not say when. * * ISO-8601 so stamps sort lexically, diff cleanly, and line up with the * kernel's own timestamps without conversion. */ const stamp = () => new Date().toISOString(); // An unreadable daemon record still means a daemon was registered here; the // hint only chooses between the two steps, so it must not throw on it. const hasDaemonRecord = () => { try { return Boolean(loadDaemonRecord()); } catch { return true; } }; /** * Map `agent run`'s cascade flags onto resolveCascadeSettings' override keys. * * Exported because the mapping is where the flag path can go wrong invisibly: * an earlier version coerced with Number() here, so `--cascade-cap abc` * reached the resolver as NaN and the warning read `--cascade-cap='NaN'` — * naming a value the user never typed, on the one line whose whole job is to * tell them which input was bad. The values pass through RAW; the resolver is * the only thing that parses, for the same reason it is the only thing that * validates. */ export const cascadeOverridesFromOpts = (opts = {}) => ({ cascadeCap: opts.cascadeCap, cascadeAddressedGrace: opts.cascadeGrace, cascadeResetMs: opts.cascadeReset, }); export const registerAgent = (program) => { const agent = program.command('agent').description('Manage agents'); agent.addHelpText('after', ` Examples: # Wrap your local claude binary as a pod agent (ADR-005) $ ${CLI} agent attach claude --pod --name my-claude $ ${CLI} agent run my-claude $ ${CLI} agent detach my-claude # Scaffold a custom Python agent (ADR-006) $ ${CLI} agent init --language python --name research-bot --pod # List installed agents $ ${CLI} agent list $ ${CLI} agent config my-claude --adapter claude --model gpt-5.4 --effort high $ ${CLI} agent config my-claude --model gpt-5.4 --effort high Docs: https://github.com/Team-Commonly/commonly/blob/main/docs/agents/LOCAL_CLI_WRAPPER.md https://github.com/Team-Commonly/commonly/blob/main/docs/agents/WEBHOOK_SDK.md `); // ── register ────────────────────────────────────────────────────────────── agent .command('register') .description('Register a webhook agent') .requiredOption('--name ', 'Agent name (e.g. my-agent)') .requiredOption('--pod ', 'Pod ID to install into') .requiredOption('--webhook ', 'Webhook URL (e.g. https://my-agent.example.com/cap)') .option('--secret ', 'Webhook signing secret (HMAC-SHA256)') .option('--display ', 'Display name shown in the pod') .option('--instance ', 'Target Commonly instance') .action(async (opts) => { const instanceUrl = resolveInstanceUrl(opts.instance); const token = getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: instanceUrl, token }); try { // Publish the agent definition if it doesn't exist yet. await client.post('/api/registry/publish', { manifest: { name: opts.name, version: '1.0.0', description: 'A webhook-connected agent.', runtimeType: 'webhook', }, displayName: opts.display || opts.name, }).catch(() => { // Ignore publish errors — agent may already exist, install will proceed }); const result = await client.post('/api/registry/install', { agentName: opts.name, podId: opts.pod, displayName: opts.display || opts.name, version: '1.0.0', config: { runtime: { runtimeType: 'webhook', host: 'byo', webhookUrl: opts.webhook, ...(opts.secret ? { webhookSecret: opts.secret } : {}), }, }, scopes: ['context:read', 'messages:write', 'memory:read'], }); const installation = result.installation || result; const instId = installation.instanceId || 'default'; console.log(`Agent registered: ${installation.agentName} (${instId})`); console.log(`Pod: ${opts.pod}`); console.log(`Webhook: ${opts.webhook}`); // Fetch runtime token for agent connect let runtimeToken = result.runtimeToken; if (!runtimeToken) { try { const tokenData = await client.post( `/api/registry/pods/${opts.pod}/agents/${opts.name}/runtime-tokens`, { force: true }, ); runtimeToken = tokenData.token; } catch { // non-fatal — user can fetch manually } } if (runtimeToken) { console.log(`\nRuntime token: ${runtimeToken}`); console.log(`Use this with: ${CLI} agent connect --name --token `); } } catch (err) { console.error(`Registration failed: ${err.message}`); process.exit(1); } }); // ── connect ─────────────────────────────────────────────────────────────── agent .command('connect') .description('Start local dev loop — poll events and forward to localhost') .requiredOption('--name ', 'Agent name') .option('--port ', 'Local webhook server port', '3001') .option('--path ', 'Local webhook path', '/cap') .option('--secret ', 'Signing secret to verify forwarded events') .option('--token ', 'Agent runtime token (cm_agent_*) — use instead of user token for event polling') .option('--instance-id ', 'Instance ID (default: "default")', 'default') .option('--instance ', 'Target Commonly instance') .option('--interval ', 'Poll interval in ms', '5000') .action(async (opts) => { const instanceUrl = resolveInstanceUrl(opts.instance); const token = opts.token || getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const port = parseInt(opts.port, 10); const localUrl = `http://localhost:${port}${opts.path}`; console.log(`Connecting ${opts.name} → ${instanceUrl}`); console.log(`Forwarding events to ${localUrl}`); console.log('Waiting for events... (Ctrl+C to stop)\n'); // Start local webhook server const { close } = await startWebhookServer({ port, path: opts.path, secret: opts.secret, onEvent: logOnlyHandler, onReady: (url) => console.log(`Local server ready: ${url}`), }); // Start poller — forwards each event to the local server const poller = startPoller({ instanceUrl, token, agentName: opts.name, instanceId: opts.instanceId, intervalMs: parseInt(opts.interval, 10), loginInstance: opts.instance, onEvent: async (event) => { const ts = new Date().toTimeString().slice(0, 8); process.stdout.write(`[${ts}] ${event.type.padEnd(18)}`); try { const result = await forwardToLocalWebhook(event, localUrl, opts.secret); console.log(`→ ${result.outcome}`); return result; } catch (err) { console.log(`→ error (${err.message})`); return { outcome: 'error', reason: err.message }; } }, onError: (err) => { console.error(`[poll error] ${err.message}`); }, // TASK-338: a wedged poll ends the process instead of idling forever. onPollStalled: () => process.exit(1), }); // Graceful shutdown process.on('SIGINT', () => { console.log('\nStopping...'); poller.stop(); close(); process.exit(0); }); }); // ── attach (ADR-005, ADR-008) ───────────────────────────────────────────── agent .command('attach ') .description(`Wrap a local CLI as a Commonly agent (${listPublicAdapterNames().join('|')})`) .requiredOption('--pod ', 'Pod ID to install into') .requiredOption('--name ', 'Agent name (e.g. my-claude)') .option('--memory-from ', 'Copy long-term memory from a hosted agent you own') .option('--memory-instance ', 'Hosted source instance for --memory-from', 'default') .option('--display ', 'Display name shown in the pod') .option('--env ', 'Path to environment.json (ADR-008 — sandbox/skills/MCP)') .option('--import-memory [path]', 'Import local memory (CLAUDE.md / MEMORY.md / ~/.claude project memory, or a given file/dir) into the agent after attach') .option('--yes', 'Skip the import confirmation prompt') .option('--wake-on-message', `Wake this agent on every message in the pod, not only @mentions (ADR-018 ambient wake; default off). Change later with: ${CLI} agent wake on|off`) .option('--instance ', 'Target Commonly instance') .action(async (adapterName, opts) => { const instanceUrl = resolveInstanceUrl(opts.instance); const token = getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: instanceUrl, token }); try { const envAbsPath = opts.env ? pathResolve(opts.env) : null; const { installation, instanceId, runtimeToken, detected, wrappedCli, displayName, environment, workspace, } = await performAttach({ client, adapterName, agentName: opts.name, podId: opts.pod, displayName: opts.display, envPath: envAbsPath, wakeOnMessage: Boolean(opts.wakeOnMessage), memoryFrom: opts.memoryFrom, memoryInstance: opts.memoryInstance, log: (line) => console.warn(`[attach] ${line}`), }); saveAgentToken(opts.name, { agentName: opts.name, displayName, instanceId, podId: opts.pod, instanceUrl, runtimeToken, adapter: wrappedCli, ...(environment ? { environment, workspacePath: workspace?.path || null, } : {}), }); console.log(`✓ ${wrappedCli} detected at ${detected.path} (${detected.version})`); console.log(`✓ Agent '${installation.agentName}' registered in pod ${opts.pod} (${instanceId})`); console.log(`✓ Runtime token saved to ${tokenFile(opts.name)}`); if (workspace) { console.log(`✓ Workspace: ${workspace.path}${workspace.created ? ' (created)' : ''}`); } if (opts.wakeOnMessage) { console.log('✓ Wake-on-message: ON (sees every pod message; answers only when addressed or genuinely useful)'); } // Retention plan Phase C: the agent arrives whole. Import failure is // a warning, never an attach failure — the attach already succeeded // and `commonly agent import-memory` can retry later. if (opts.importMemory) { try { const runtimeClient = createClient({ instance: instanceUrl, token: runtimeToken }); await runMemoryImport({ client: runtimeClient, explicitPath: typeof opts.importMemory === 'string' ? pathResolve(opts.importMemory) : null, yes: Boolean(opts.yes), }); } catch (err) { console.warn(`Memory import failed (agent is still attached): ${err.message}`); console.warn(`Retry with: ${CLI} agent import-memory ${opts.name}`); } } // The mention handle is the instanceId (what the UI dropdown inserts), // not the registry agentName — say it here so users know how to ping it. const handle = instanceId && instanceId !== 'default' ? instanceId : installation.agentName; const binding = await checkAttachedAdapterBinding({ adapterName: wrappedCli, agentName: opts.name, podId: opts.pod, instanceId, instanceUrl, runtimeToken, }); printAttachRunGuidance({ agentName: opts.name, binding }); console.log(` Mention as: @${handle}`); } catch (err) { console.error(`Attach failed: ${err.message}`); process.exit(1); } }); // ── import-memory (retention plan Phase C) ──────────────────────────────── agent .command('import-memory ') .description("Import local memory (CLAUDE.md / MEMORY.md / ~/.claude project memory) into an attached agent's long_term memory") .option('--path ', 'Import a specific file or directory of .md files instead of auto-detecting') .option('--yes', 'Skip the confirmation prompt') .action(async (name, opts) => { const record = loadAgentToken(name); if (!record) { console.error(`No token for '${name}'. Attach it first: ${CLI} agent attach --pod --name ${name}`); process.exit(1); } try { const client = createClient({ instance: record.instanceUrl, token: record.runtimeToken }); const result = await runMemoryImport({ client, explicitPath: opts.path ? pathResolve(opts.path) : null, yes: Boolean(opts.yes), }); if (!result.imported && result.reason === 'needs-confirmation') process.exit(1); } catch (err) { console.error(`Import failed: ${err.message}`); process.exit(1); } }); // ── import-skills (retention plan Phase C — metadata only) ──────────────── agent .command('import-skills ') .description("Register a local agent's skills (names + descriptions only) on its Commonly profile — content stays on your machine") .option('--dir ', 'Skills directory (default: /.claude/skills, then ~/.claude/skills)') .option('--yes', 'Skip the confirmation prompt') .option('--instance ', 'Target Commonly instance') .action(async (name, opts) => { const record = loadAgentToken(name); if (!record) { console.error(`No token for '${name}'. Attach it first: ${CLI} agent attach --pod --name ${name}`); process.exit(1); } // Skill registration is a USER action (pod-membership-checked route), // unlike memory import which authenticates as the agent. const userToken = getToken(opts.instance); if (!userToken) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } try { const skills = detectSkills({ explicitDir: opts.dir ? pathResolve(opts.dir) : null }); if (!skills.length) { console.log('No skills found (looked for */SKILL.md under .claude/skills). Pass --dir to point at a skills directory.'); return; } console.log(`Found ${skills.length} skill${skills.length === 1 ? '' : 's'}:`); for (const s of skills) { console.log(` ${s.name}${s.description ? ` — ${s.description.slice(0, 80)}` : ''}`); } console.log('\nOnly names + descriptions are uploaded — skill content stays on this machine.'); if (!opts.yes) { if (!process.stdin.isTTY) { console.log('Not a terminal — re-run with --yes to confirm.'); process.exit(1); } const { createInterface } = await import('readline/promises'); const rl = createInterface({ input: process.stdin, output: process.stdout }); const answer = await rl.question(`Register on ${record.agentName}'s profile? [y/N] `); rl.close(); if (!/^y(es)?$/i.test(answer.trim())) { console.log('Cancelled.'); return; } } const client = createClient({ instance: record.instanceUrl, token: userToken }); const result = await importSkills(client, { skills, podId: record.podId, agentName: record.agentName, instanceId: record.instanceId || 'default', }); console.log(`✓ Registered ${result.imported} skill${result.imported === 1 ? '' : 's'} on ${record.agentName}'s profile.`); } catch (err) { console.error(`Skills import failed: ${err.message}`); process.exit(1); } }); // ── run (ADR-005) ───────────────────────────────────────────────────────── agent .command('run ') .description('Run the local-CLI wrapper loop for an attached agent') .option('--interval ', 'Poll interval in ms', '5000') .option('--instance-id ', 'Run this instance of the agent, when it has more than one (default: default)') .option('--adapter ', `CLI to wrap on first-run bootstrap (${listPublicAdapterNames().join('|')}); an existing token file bound to a different adapter stops the run`) .option('--cascade-cap ', `Consecutive agent-triggered turns allowed per pod (env ${CASCADE_ENV_VARS.cap}, default ${CASCADE_DEFAULTS.cap})`) .option('--cascade-grace ', `Extra turns allowed when this seat was directly addressed; 0 disables the grace (env ${CASCADE_ENV_VARS.addressedGrace}, default ${CASCADE_DEFAULTS.addressedGrace})`) .option('--cascade-reset ', `Silence window that clears the streak (env ${CASCADE_ENV_VARS.resetMs}, default ${CASCADE_DEFAULTS.resetMs})`) .option('--refusal-handoff ', 'Agent to @mention when the model provider refuses a request\'s content; the request is acked as refused, never retried') .option('--allow ', 'On first run of an agent that works in its folder, also let it edit files and run commands (write) and/or fetch web pages (web), comma-separated. Commands reach the network.') .option('--unsandboxed', 'Native Windows, or a private Codex agent on Linux: run this agent without a sandbox, with your own access to files and commands. It gets no connector grants. Codex can run commands in invite-only pods, where anyone in the pod, including people invited later, can direct it.') .action(async (typedName, opts) => { // F306: the seat this run is. `name` is the local key (the token file, // the log label, the daemon's plist); the server identity is the record's. let instanceId; try { instanceId = parseRunInstanceId(opts.instanceId, typedName); } catch (err) { console.error(`${stamp()} [${typedName}] ${err.message}`); process.exit(1); } const agentArg = String(typedName).split('@')[0]; const named = instanceId !== null; let name = named ? seatKey(agentArg, instanceId) : agentArg; if (opts.unsandboxed) { // On Linux the flag is for a Codex agent only, which the record says; // it is checked again once that is read (F387). const flagRefusal = unsandboxedFlagRefusal(process.platform, { adapterName: opts.adapter || null, deferred: true }); if (flagRefusal) { console.error(`${stamp()} [${name}] ${flagRefusal}`); process.exit(1); } } let allow; try { allow = parseAllowGrants(opts.allow); } catch (err) { console.error(`${stamp()} [${name}] ${err.message}`); process.exit(1); } let record = loadAgentToken(name); // An instance's key saved by an older run, under the bare name: use it // where it is, when it is that instance's (F306). if (!record && named && name !== agentArg) { const legacy = loadAgentToken(agentArg); if (legacy && !runInstanceRefusal({ record: legacy, instanceId })) { record = legacy; name = agentArg; } } let bootstrapped = false; const saved = record; const savedRefusal = record && named ? runInstanceRefusal({ record, instanceId }) : null; if (savedRefusal) { console.error(`${stamp()} [${name}] ${savedRefusal}`); process.exit(1); } if (record) { record = await adoptEnvToken({ record, name, log: (line) => console.log(`${stamp()} [${name}] ${line}`), }); } else { // First run on this machine: the BYO connect page hands out env vars, // not a token file — bootstrap the record from them (#913). try { record = await bootstrapAgentRecordFromEnv({ name: agentArg, adapterOverride: opts.adapter || null, log: (line) => console.log(`${stamp()} [${name}] ${line}`), allow, }); } catch (err) { console.error(`${stamp()} [${name}] ${err.message}`); // A Claude Code installed with npm is a .cmd shim Node cannot spawn, // so on Windows this is usually "installed but not runnable here". if (err.code === NO_AGENT_CLI_CODE && process.platform === 'win32') { console.error(windowsSandboxMessage('claude')); } process.exit(1); } if (!record) { console.error( `No token for '${name}'. Either export COMMONLY_API_URL + COMMONLY_AGENT_TOKEN` + ` (shown on the Connect your own agent page) and re-run, or:` + ` ${CLI} agent attach --pod --name ${agentArg}`, ); process.exit(1); } const instanceRefusal = named ? runInstanceRefusal({ record, instanceId }) : null; if (instanceRefusal) { console.error(`${stamp()} [${name}] ${instanceRefusal}`); process.exit(1); } bootstrapped = true; } // D245: on native Windows the user may choose to run without an OS // sandbox, by typing the flag or by installing the daemon with it (the // marker is read only by the seats that daemon spawns). Nothing from the // server decides this, and the environment never carries it: the seat // keeps its trust and tool policy, and only the OS jail is skipped. if (opts.unsandboxed) { const flagRefusal = unsandboxedFlagRefusal(process.platform, { adapterName: record.adapter }); if (flagRefusal) { console.error(`${stamp()} [${name}] ${flagRefusal}`); process.exit(1); } } const optedIn = runOptedInUnsandboxed({ flag: opts.unsandboxed === true }); const hostUnconfined = hostUnconfinedForRun({ optedIn, adapterName: record.adapter, environment: record.environment, }); if (hostUnconfined) console.warn(`${stamp()} [${name}] ${UNSANDBOXED_NOTICE}`); // Codex has no policy to fall back on, so its opt-in reaches only a seat // whose every pod is confirmed private, and this run's environment, never // the saved record, loses its sandbox block. A read that fails stays // refused: nothing here may assume a pod is private. let codexUnconfined = false; if (optedIn && record.adapter === 'codex' && (process.platform === 'win32' || process.platform === 'linux')) { const seatClient = createClient({ instance: record.instanceUrl, token: record.runtimeToken }); let installations = null; try { const identity = await seatClient.get('/api/agents/runtime/installations'); installations = identity?.installations; } catch (err) { console.error(`${stamp()} [${name}] could not read whether this agent's pods are private, so it did not start: ${err.message}`); process.exit(1); } codexUnconfined = codexUnconfinedForRun({ optedIn, adapterName: record.adapter, environment: record.environment, installations, }); // An unconfined Codex can read this run's token and call the grant // broker itself, past the local guard, so the server has to refuse it. // No report, no run: "gets no connector grants" rests on this call. if (codexUnconfined) { try { await seatClient.post('/api/agents/runtime/host-unconfined', {}); } catch (err) { console.error(`${stamp()} [${name}] ${hostReportFailureMessage(err)}`); process.exit(1); } } } if (codexUnconfined) console.warn(`${stamp()} [${name}] ${codexUnsandboxedNotice(process.platform)}`); let runEnvironment = record.environment; if (codexUnconfined && runEnvironment) { const { sandbox: _sandbox, ...unsandboxed } = runEnvironment; runEnvironment = unsandboxed; } // Every turn of a seat this host cannot confine would fail, so say so // once, before a token file is written or a poll is made. const hostRefusal = hostSandboxRefusal({ environment: runEnvironment, adapterName: record.adapter, hostUnconfined: hostUnconfined || codexUnconfined, optedIn, }); if (hostRefusal) { console.error(`${stamp()} [${name}] ${hostRefusal}`); process.exit(1); } // F444: on Linux a private Codex seat has a sandbox, so a flag its pods // rule out leaves it there; say so rather than let the flag look applied. if (optedIn && record.adapter === 'codex' && process.platform === 'linux' && !codexUnconfined) { console.warn(`${stamp()} [${name}] ${UNSANDBOXED_FLAG} was not applied: ${ effectiveSandboxTrust(record.environment?.sandbox?.trust) === 'workspace' ? 'this agent is set to workspace trust' : "a pod this agent answers in isn't confirmed private and invite-only"}, so it runs in Codex's own sandbox.`); } if (saved && record !== saved) saveAgentToken(name, record); if (bootstrapped) { // A named instance is saved under its seat key; an unnamed run keeps // the bare name, as before. const savedAs = named ? seatKey(record.agentName, record.instanceId) : record.agentName; // The record's own spelling names the file, so the state this run keeps // follows it there, and the next run finds both (case, or a token that // belongs to another name). if (named) name = savedAs; saveAgentToken(savedAs, record); console.log(`${stamp()} [${name}] bootstrapped ${tokenFile(savedAs)} from COMMONLY_AGENT_TOKEN (adapter: ${record.adapter})`); } else if (savedSeatLacksDefaultSandbox(record)) { console.warn( `${stamp()} [${name}] this agent's saved settings declare no sandbox, so it runs without one. ` + `To give it the default: ${CLI} agent detach ${name} --force, then either run a fresh command ` + 'from the Connect page, or attach it again with an environment file that sets sandbox.trust: public.', ); } const allowRequest = checkRunAllowRequest({ record, requested: allow }); if (!allowRequest.ok) { console.error(`${stamp()} [${name}] ${allowRequest.message}`); process.exit(1); } const adapterRequest = checkRunAdapterRequest({ record, requestedAdapter: opts.adapter, tokenPath: tokenFile(name), }); if (!adapterRequest.ok) { console.error(`${stamp()} [${name}] ${adapterRequest.message}`); process.exit(1); } const adapter = getAdapter(record.adapter); if (!adapter) { console.error(`Unknown adapter '${record.adapter}' in token file. Known: ${listPublicAdapterNames().join(', ')}`); process.exit(1); } if (adapterRequiresServerBinding(adapter.name)) { let identity; try { identity = await createClient({ instance: record.instanceUrl, token: record.runtimeToken, }).get('/api/agents/runtime/installations'); } catch (err) { console.error(`${stamp()} [${name}] could not read the server-declared adapter: ${err.message}`); process.exit(1); } const bindingRefusal = serverAdapterBindingRefusal({ adapterName: adapter.name, agentName: record.agentName, installations: identity?.installations, podId: record.podId, instanceId: record.instanceId, }); if (bindingRefusal) { console.error(`${stamp()} [${name}] ${bindingRefusal}`); process.exit(1); } } // THE line to stamp, not just one of them. It is the first line of every // seat log and the truncation boundary — the fleet is launched as // `nohup … > log 2>&1`, so this banner is written at boot and everything // before it is gone. Stamped, it dates the restart from the log itself. // Unstamped, it took `ps -o lstart` to establish when nine seats came // back on 2026-08-18, and that only worked because the processes were // still alive — after the next restart that route is gone too. await prepareMcpBeforeFirstPoll({ environment: runEnvironment, log: (line) => console.log(`${stamp()} [${name}] ${line}`), }); console.log(`${stamp()} [${name}] polling ${record.instanceUrl} for events (ctrl+c to stop)`); console.log(`${stamp()} [${name}] ${foregroundDaemonHint({ daemonRegistered: hasDaemonRecord() })}`); // TASK-660: one line when this CLI is stale. Fired, not awaited, so a // slow registry never delays the first poll. startUpdateNotice({ installedVersion: installedCliVersion(), log: (line) => console.log(`${stamp()} [${name}] ${line}`), }); const { stop } = performRun({ instanceUrl: record.instanceUrl, token: record.runtimeToken, adapter, agentName: record.agentName, displayName: record.displayName || record.agentName, instanceId: record.instanceId, localKey: name, podId: record.podId, environment: runEnvironment || null, hostUnconfined, codexUnconfined, workspacePath: record.workspacePath || null, intervalMs: parseInt(opts.interval, 10), ...cascadeOverridesFromOpts(opts), // TASK-102 part B: the operator's TTL ask, if any. Unset means the // server's published default, which is the only lifetime we can justify // without an operator saying otherwise. runtimeReportClient: createMachineReportClient({ instanceUrl: record.instanceUrl, machineId: record.machineId, agentName: record.agentName, instanceId: record.instanceId }), resolveOwnProviderKey: createOwnKeyResolver({ instanceUrl: record.instanceUrl, machineId: record.machineId, agentName: record.agentName, instanceId: record.instanceId }), reportRuntime: Boolean(record.machineId || process.env.COMMONLY_MANAGED_RUNNER === '1'), readSavedControls: !record.machineId && process.env.COMMONLY_MANAGED_RUNNER !== '1', standaloneMachineRun: Boolean(record.machineId) && process.env.COMMONLY_MANAGED_RUNNER !== '1', readGrantBrokers: !record.machineId && process.env.COMMONLY_MANAGED_RUNNER !== '1', spawnCredentialTtlSeconds: resolveSpawnTtlSeconds(process.env), refusalHandoff: opts.refusalHandoff || null, log: (line) => console.log(`${stamp()} [${name}] ${line}`), // Both sinks are stamped, and both must be — but not for the reason // this comment gave until now, which its own PR falsified. // // A spawn failure is routed to `onError` when a caller provides one and // to `log` only as the fallback, so in `agent run` — which always passes // one — EVERY failure line comes out of the error channel and none out // of the log. Stamping only `log:` would leave the entire failure class // undated, which is the class these stamps exist for. // // The two sinks also carry genuinely different text elsewhere: the // no-prompt skip logs a terse line and sends a detailed diagnostic, so // one stamped and one bare would date half of that pair. // // (History, because the reasoning moved twice. This originally argued // from a DOUBLE emission — the retry path called both sinks with // identical text, so `grep -c 'session limit'` returned 8 for 4 failures // and a per-event count read as two deliveries. That was true when the // stamps landed and false eleven minutes later, when the same PR // collapsed the duplication. The conclusion survived the premise; the // sentence did not, and nothing in the diff pointed at it.) onError: (err) => console.error(`${stamp()} [${name}] ${err.message}`), // TASK-338: a wedged poll ends the process, so tmux-keepalive or // launchd KeepAlive, which act only on exit, start a clean one. onPollStalled: () => process.exit(1), }); // SIGTERM is the daemon's idle-boundary handoff signal. `stop()` stops // future polls but lets the in-flight turn finish and ack before the // event loop drains; exiting here would cut a model turn in half. // seat-stop also arms the supervised-group deadline before launchd's // SIGKILL, and kills any group still live when the process exits. const seatStop = createSeatStop({ name, stop }); const requestStop = (signal) => { console.log(`\n${stamp()} [${name}] stopping after the current turn...`); seatStop.requestStop(signal); }; process.on('SIGINT', requestStop); process.on('SIGTERM', requestStop); process.once('exit', seatStop.onExit); }); // ── detach (ADR-005) ────────────────────────────────────────────────────── agent .command('detach ') .description('Uninstall an attached agent from its pod and delete local state') .option('--force', 'Skip the backend uninstall call; only remove local files') .action(async (name, opts) => { const record = loadAgentToken(name); if (!record) { console.error( `No local state for '${name}'. If the agent is still installed on ` + `the backend, uninstall it via the Agent Hub UI or:\n` + ` curl -X DELETE '/api/registry/agents/${name}/pods/?instanceId=' \\\n` + ` -H "Authorization: Bearer "`, ); process.exit(1); } try { let client = null; if (!opts.force) { // The DELETE endpoint expects the user's JWT, not the agent runtime // token — matches the auth surface of attach/init. We use the saved // instanceUrl to find the right user token (getToken accepts URL). const userToken = getToken(record.instanceUrl); if (!userToken) { console.error( `No user login found for ${record.instanceUrl}. Either run ` + `'${CLI} login --instance ${record.instanceUrl}' first, or ` + `'${CLI} agent detach ${name} --force' to clean up local files only.`, ); process.exit(1); } client = createClient({ instance: record.instanceUrl, token: userToken }); } const result = await performDetach({ client, agentName: record.agentName, podId: record.podId, instanceId: record.instanceId || 'default', localKey: name, skipBackend: !!opts.force, log: (line) => console.warn(`[detach] ${line}`), }); if (opts.force) { console.log(`✓ Removed local state for '${name}' (backend NOT notified)`); } else if (result.backend?.alreadyGone) { console.log(`✓ '${name}' was already uninstalled from pod ${record.podId}; cleaned local state`); } else { console.log(`✓ Detached '${name}' from pod ${record.podId} and removed local state`); } } catch (err) { console.error(`Detach failed: ${err.message}`); console.error(`If the backend is unreachable, retry with --force to clean up local files.`); process.exit(1); } }); // ── init (ADR-006) ──────────────────────────────────────────────────────── agent .command('init') .description('Scaffold a webhook-SDK agent into the current directory') .requiredOption('--language ', `One of: ${SUPPORTED_LANGUAGES.join(', ')}`) .requiredOption('--name ', 'Agent name (e.g. research-bot)') .requiredOption('--pod ', 'Pod ID to install into') .option('--display ', 'Display name shown in the pod') .option('--dir ', 'Target directory (default: current dir)') .option('--instance ', 'Target Commonly instance') .action(async (opts) => { const instanceUrl = resolveInstanceUrl(opts.instance); const token = getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: instanceUrl, token }); try { const result = await performInit({ client, language: opts.language, agentName: opts.name, podId: opts.pod, displayName: opts.display, targetDir: pathResolve(opts.dir || process.cwd()), }); console.log(`✓ Written: ${result.files.bot}`); console.log(`✓ Written: ${result.files.sdk}`); console.log(`✓ Registered '${opts.name}' in pod ${opts.pod} (${result.instanceId})`); console.log(`✓ Runtime token saved to ${result.files.env}`); 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); } }); // ── list ────────────────────────────────────────────────────────────────── agent .command('list') .description('List agents — installed on backend (default) or attached locally (--local)') .option('--local', 'List agents attached on this laptop (~/.commonly/tokens/)') .option('--pod ', 'Filter by pod (backend mode only)') .option('--instance ', 'Target Commonly instance (backend mode only)') .addHelpText('after', ` The two modes answer different questions: backend (default) — who is installed in pods I can see, on any driver --local — who have I attached on THIS laptop via 'agent attach' Use --local to find the name you'd pass to 'agent run' or 'agent detach'. `) .action(async (opts) => { process.exit(await runAgentList(opts)); }); // ── logs ────────────────────────────────────────────────────────────────── // Without --pod, the seat's local daemon log is read. With --pod, the owner // login reads recent events and runs from the member-gated seat-activity // route, whichever machine the seat runs on. The owner login is never sent to // the agent-runtime routes, which only accept a seat's own token. agent .command('logs ') .description("Show a seat's recent log: local daemon log, or server activity with --pod") .option('--pod ', 'Read server-side events and runs for a pod you belong to') .option('--instance-id ', 'Seat instance ID (with --pod, found from the name when omitted)') .option('--follow', 'Continue printing new output', false) .option('--lines ', 'Number of trailing local lines to show', '50') .option('--instance ', 'Target Commonly instance (with --pod)') .action(async (name, opts) => { if (opts.follow && opts.pod) { console.error('--follow needs a local seat log; server activity is a snapshot. Re-run without --follow.'); process.exit(1); } const lines = Number(opts.lines); if (!Number.isInteger(lines) || lines < 1) { console.error(`--lines must be a positive integer, got '${opts.lines}'`); process.exit(1); } if (!opts.pod) { const path = daemonSeatLogPath(name); let output; try { output = readLogTail(path, lines); } catch (err) { console.error(`Cannot read ${path}: ${err.message}`); process.exit(1); } if (output === null) { console.error(`No local log for '${name}' at ${path}. Pass --pod to read its server-side activity.`); process.exit(1); } if (output) console.log(output); if (!opts.follow) return; // Poll rather than fs.watch: a rename-rotated log would leave a watch // on the old inode silent. Only appended bytes are printed. let offset = logSize(path); const timer = setInterval(() => { try { const next = readAppended(path, offset); offset = next.offset; if (next.text) process.stdout.write(next.text); } catch (err) { // Rotation can leave a gap with no file; wait for it to come back. if (err?.code === 'ENOENT') return; console.error(`Cannot follow ${path}: ${err.message}`); process.exit(1); } }, 1000); const close = () => { clearInterval(timer); process.exit(0); }; process.once('SIGINT', close); process.once('SIGTERM', close); return; } const token = getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: resolveInstanceUrl(opts.instance), token }); const printActivity = async () => { const seat = await resolveLogsSeat(client, opts.pod, name, opts.instanceId); if (seat.note) console.error(seat.note); const { events = [], runs = [] } = await client.get('/api/agents/seat-activity', { podId: opts.pod, agentName: seat.agentName, instanceId: seat.instanceId, }); events.forEach((e) => { const ts = new Date(e.createdAt).toTimeString().slice(0, 8); console.log(`[${ts}] ${String(e.type).padEnd(18)} → ${e.outcome || e.status}`); }); runs.forEach((r) => { const ts = new Date(r.startedAt).toTimeString().slice(0, 8); console.log(`[${ts}] run ${String(r.trigger).padEnd(14)} → ${r.status} (${r.totalTokens} tokens)`); }); if (events.length === 0 && runs.length === 0) console.log(`No recent activity for '${name}' in this pod.`); }; try { await printActivity(); } catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); } }); // ── config (existing-agent edit) ───────────────────────────────────────── agent .command('config ') .description('Update an attached agent\'s server-side runtime configuration') .option('--adapter ', 'Local runtime adapter (must be installed on this machine)') .option('--model ', 'Model identifier to use on the next daemon restart') .option('--effort ', 'Reasoning effort (low|medium|high|xhigh|max)') .option('--env ', 'Replace the ADR-008 environment spec with this JSON file') .option('--instance ', 'Target Commonly instance') .action(async (name, opts) => { const record = loadAgentToken(name); if (!record) { console.error(`No token file for '${name}' — is it attached on this machine? (${CLI} agent list --local)`); process.exit(1); } const instance = opts.instance || record.instanceUrl; const ownerToken = getToken(instance); const runtimeKey = !opts.adapter && !opts.env && !ownerToken && Boolean(record.runtimeToken); const token = runtimeKey ? record.runtimeToken : ownerToken; if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } try { const instanceUrl = resolveInstanceUrl(instance); if (runtimeKey && (!record.instanceUrl || new URL(instanceUrl).href.replace(/\/$/, '') !== new URL(record.instanceUrl).href.replace(/\/$/, ''))) { throw new Error(`Changing --instance requires an owner login for that instance; run ${CLI} login`); } const client = createClient({ instance: instanceUrl, token }); const result = await updateAgentConfiguration({ client, record, runtimeKey, adapter: opts.adapter, model: opts.model, effort: opts.effort, envPath: opts.env ? pathResolve(opts.env) : null, }); if (result.environment || result.adapter) { saveAgentToken(name, { ...record, ...(result.environment ? { environment: result.environment } : {}), ...(result.adapter ? { adapter: result.adapter } : {}), }); } console.log(`✓ Updated ${result.agentName} in pod ${result.podId} (${result.changed.join(', ')})`); console.log(' The daemon will apply the change on its next poll; a standalone agent run needs a restart.'); } catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); } }); // ── wake (ADR-018 ambient wake toggle) ─────────────────────────────────── agent .command('wake ') .description('Turn wake-on-message on/off for an attached agent (off = @mentions and heartbeats only)') .option('--instance ', 'Target Commonly instance') .action(async (name, state, opts) => { const enabled = state === 'on'; if (!enabled && state !== 'off') { console.error(`Expected "on" or "off", got "${state}"`); process.exit(1); } const record = loadAgentToken(name); if (!record) { console.error(`No token file for '${name}' — is it attached on this machine? (${CLI} agent list --local)`); process.exit(1); } const instanceUrl = resolveInstanceUrl(opts.instance || record.instanceUrl); const token = getToken(opts.instance || record.instanceUrl); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: instanceUrl, token }); try { const result = await setWakeOnMessage({ client, record, enabled }); console.log(`✓ Wake-on-message ${result.enabled ? 'ON' : 'OFF'} for ${result.agentName} in pod ${result.podId}`); console.log(result.enabled ? ' The agent now sees every message in the pod; its runtime decides whether to answer (NO_REPLY otherwise). No restart needed.' : ' The agent now wakes only on @mentions, replies to it, and heartbeats. No restart needed.'); } catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); } }); // ── clear-unsandboxed ───────────────────────────────────────────────────── agent .command('clear-unsandboxed ') .description('After moving an agent to a sandboxed host, let it use grants again (needs your login, not its token)') .option('--instance ', 'Target Commonly instance') .action(async (name, opts) => { const record = loadAgentToken(name); if (!record) { console.error(`No token file for '${name}' — is it attached on this machine? (${CLI} agent list --local)`); process.exit(1); } const instanceUrl = resolveInstanceUrl(opts.instance || record.instanceUrl); const token = getToken(opts.instance || record.instanceUrl); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: instanceUrl, token }); try { const result = await clearUnsandboxedMark({ client, record }); console.log(`✓ Cleared for ${result.agentName}. Running it with --unsandboxed marks it again.`); if (result.machineUnconfined) console.log(' Its machine reports no sandbox, so grants stay refused while it runs there.'); } catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); } }); // ── heartbeat ───────────────────────────────────────────────────────────── agent .command('heartbeat ') .description('Manually trigger an agent heartbeat') .option('--instance ', 'Target Commonly instance') .action(async (name, opts) => { const token = getToken(opts.instance); if (!token) { console.error(`Not logged in. Run: ${CLI} login`); process.exit(1); } const client = createClient({ instance: resolveInstanceUrl(opts.instance), token }); try { await client.post(`/api/registry/admin/agents/${name}/trigger-heartbeat`, {}); console.log(`Heartbeat triggered for ${name}`); } catch (err) { console.error(`Failed: ${err.message}`); process.exit(1); } }); // ── hooks-config (piece 7) ─────────────────────────────────────────────── agent .command('hooks-config ') .description('Write Claude Code HTTP hook entries for an attached agent') .option('--scope ', 'Write project or user settings', 'project') .option('--pod ', 'Pod to receive hook events (defaults to the attached pod)') .option('--file ', 'Explicit Claude settings file') .option('--timeout ', 'Hook request timeout in milliseconds', String(DEFAULT_HOOK_TIMEOUT_MS)) .action((name, opts) => { const record = loadAgentToken(name); if (!record?.runtimeToken) { console.error(`No runtime token found for '${name}'. Run ${CLI} agent attach first.`); process.exit(1); } const podId = opts.pod || record.podId; if (!podId) { console.error('A pod is required (pass --pod or attach the agent to a pod).'); process.exit(1); } const timeoutMs = Number(opts.timeout); if (!Number.isFinite(timeoutMs) || timeoutMs < 250) { console.error('--timeout must be at least 250 milliseconds.'); process.exit(1); } const effectiveTimeoutMs = clampHookTimeoutMs(timeoutMs); const result = writeHooksConfig({ filePath: opts.file ? pathResolve(opts.file) : null, scope: opts.scope, agentName: name, timeoutMs: effectiveTimeoutMs, }); console.log(`✓ Claude hooks written to ${result.filePath}`); console.log(` Events: PreToolUse, PostToolUse, Stop, SubagentStop (timeout ${Math.ceil(effectiveTimeoutMs / 1000)}s)`); }); // ── hooks-forward (internal command emitted by hooks-config) ───────────── agent .command('hooks-forward ') .description('Forward one Claude Code hook event to Commonly') .option('--pod ', 'Pod to receive hook events (defaults to the attached pod)') .option('--timeout ', 'Hook request timeout in milliseconds', String(DEFAULT_HOOK_TIMEOUT_MS)) .action(async (name, opts) => { const record = loadAgentToken(name); const podId = opts.pod || record?.podId; const instanceUrl = record?.instanceUrl || process.env.COMMONLY_API_URL || resolveInstanceUrl(undefined); // Read the credential the way the runtime that spawned this hook carries // it: the launcher FILE first, the value variable second. Reading the bare // variable is what this did, and `resolveHookToken` therefore existed, // was tested, and never ran on a real hook — so on a seat whose MCP // declaration moved to the file, the token was absent, `forwardHookEvent` // returned `hook_unavailable`, and the hook silently stopped deciding // anything (the fail-open posture makes that a silence, not an error). const token = resolveHookToken({ env: process.env }); const chunks = []; if (!process.stdin.isTTY) { for await (const chunk of process.stdin) chunks.push(chunk); } const input = chunks.length > 0 ? Buffer.concat(chunks).toString('utf8') : '{}'; await forwardHookEvent({ endpoint: podId ? `${instanceUrl.replace(/\/$/, '')}/api/agents/runtime/pods/${encodeURIComponent(podId)}/hooks` : null, token, input, timeoutMs: Number(opts.timeout), }); }); }; // Re-exported for consumers that build their own wrapper command rather than // invoking commander (and for unit tests of the config contract). export { forwardHookEvent, writeHooksConfig } from '../lib/hooks-config.js';