@commonlyai/cli 0.1.36 → 0.1.37

package/package.json

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

package/src/commands/agent.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from 'url';
 
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
-import { startPoller } from '../lib/poller.js';
+import { startPoller, terminalDeliveryAckError } from '../lib/poller.js';
 import { startWebhookServer, forwardToLocalWebhook } from '../lib/webhook-server.js';
 import { getAdapter, listAdapterNames } from '../lib/adapters/index.js';
 import {
@@ -32,7 +32,7 @@ import { readLongTerm, syncBack } from '../lib/memory-bridge.js';
 import { pollRetryPolicy } from '../lib/poll-retry.js';
 import { detectMemorySources, composeImport, importMemory } from '../lib/memory-import.js';
 import { detectSkills, importSkills } from '../lib/skills-import.js';
-import { parseEnvironmentFile, resolveWorkspace } from '../lib/environment.js';
+import { parseEnvironmentFile, resolveWorkspace, validateEnvironmentSpec } from '../lib/environment.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import {
@@ -376,6 +376,73 @@ export const setWakeOnMessage = async ({ client, record, enabled }) => {
   return { agentName: record.agentName, podId: record.podId, instanceId, enabled: Boolean(enabled) };
 };
 
+/**
+ * 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,
+  model = null,
+  effort = null,
+  envPath = null,
+  parseEnv = parseEnvironmentFile,
+}) => {
+  if (!record?.podId || !record?.agentName) {
+    throw new Error('token record is missing podId/agentName — re-attach the agent');
+  }
+  const instanceId = record.instanceId || 'default';
+  const runtime = {};
+  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;
+  }
+  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;
+  }
+  const config = {};
+  if (Object.keys(runtime).length) config.runtime = runtime;
+  let environment = null;
+  if (envPath) {
+    environment = await parseEnv(envPath);
+  } 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(runtime).length) {
+    environment = { ...environment, ...runtime };
+  }
+  if (!environment && Object.keys(runtime).length) {
+    environment = { ...runtime };
+  }
+  if (environment) config.environment = environment;
+  if (!Object.keys(config).length) {
+    throw new Error('provide at least one of --model, --effort, or --env');
+  }
+
+  await client.patch(
+    `/api/registry/pods/${record.podId}/agents/${record.agentName}`,
+    { instanceId, config },
+  );
+  return {
+    agentName: record.agentName,
+    podId: record.podId,
+    instanceId,
+    changed: Object.keys(config),
+    ...(environment ? { environment } : {}),
+  };
+};
+
 // ── attach: register a local-CLI-wrapped agent (ADR-005) ────────────────────
 
 /**
@@ -1586,6 +1653,12 @@ export const performRun = ({
                 ...(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}`));
             }
           }
@@ -1670,6 +1743,12 @@ export const performRun = ({
             ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
           });
         } catch (ackErr) {
+          const terminalError = terminalDeliveryAckError(ackErr, event._id, 'agent run');
+          if (terminalError) {
+            running = false;
+            onError?.(terminalError);
+            return;
+          }
           onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
         }
       }
@@ -1946,6 +2025,7 @@ Examples:
 
   # List installed agents
   $ commonly agent list
+  $ commonly 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
@@ -2357,11 +2437,15 @@ Docs:
         onError: (err) => console.error(`${stamp()} [${name}] ${err.message}`),
       });
 
-      process.on('SIGINT', () => {
-        console.log(`\n${stamp()} [${name}] stopping...`);
+      // 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.
+      const requestStop = () => {
+        console.log(`\n${stamp()} [${name}] stopping after the current turn...`);
         stop();
-        process.exit(0);
-      });
+      };
+      process.on('SIGINT', requestStop);
+      process.on('SIGTERM', requestStop);
     });
 
   // ── detach (ADR-005) ──────────────────────────────────────────────────────
@@ -2564,6 +2648,43 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
       }
     });
 
+  // ── config (existing-agent edit) ─────────────────────────────────────────
+  agent
+    .command('config <name>')
+    .description('Update an attached agent\'s server-side runtime configuration')
+    .option('--model <id>', 'Model identifier to use on the next daemon restart')
+    .option('--effort <level>', 'Reasoning effort (low|medium|high|xhigh|max)')
+    .option('--env <path>', 'Replace the ADR-008 environment spec with this JSON file')
+    .option('--instance <url>', '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? (commonly agent list --local)`);
+        process.exit(1);
+      }
+      const instance = opts.instance || record.instanceUrl;
+      const token = getToken(instance);
+      if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
+      const client = createClient({ instance: resolveInstanceUrl(instance), token });
+      try {
+        const result = await updateAgentConfiguration({
+          client,
+          record,
+          model: opts.model,
+          effort: opts.effort,
+          envPath: opts.env ? pathResolve(opts.env) : null,
+        });
+        if (result.environment) {
+          saveAgentToken(name, { ...record, environment: result.environment });
+        }
+        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 <name> <on|off>')

package/src/commands/daemon.js

@@ -14,7 +14,7 @@ import {
 import { join } from 'path';
 import { createClient } from '../lib/api.js';
 import { getToken, resolveInstanceUrl } from '../lib/config.js';
-import { loadDaemonRecord, saveDaemonRecord } from '../lib/daemon-store.js';
+import { loadDaemonRecord, removeDaemonRecord, saveDaemonRecord } from '../lib/daemon-store.js';
 import {
   createDaemonSupervisor,
   DEFAULT_HEARTBEAT_MS,
@@ -78,7 +78,7 @@ export const registerDaemonMachine = async ({
       await client.del(`/api/machines/${machine.id}`);
     } catch (revokeError) {
       throw new Error(
-        `Could not store the daemon credential and could not revoke machine ${machine.name}: ${revokeError.message}`,
+        `Could not store the daemon credential and could not revoke machine ${machine.name} (${machine.id}): ${revokeError.message}`,
       );
     }
     throw new Error(`Could not store the daemon credential securely: ${error.message}. Machine registration was revoked.`);
@@ -96,6 +96,18 @@ export const getDaemonMachineStatus = async ({ client }) => {
   return response?.machine || null;
 };
 
+// Revoke remotely before unlinking locally. A failed network call must leave
+// the bearer record intact so the operator can retry rather than orphaning a
+// year-long daemon credential they can no longer address from the CLI.
+export const unregisterDaemonMachine = async ({ client, record, remove = removeDaemonRecord }) => {
+  try {
+    await client.del(`/api/machines/${record.machineDbId}`);
+  } catch (error) {
+    if (error?.status !== 404) throw error;
+  }
+  remove();
+};
+
 // The adapter names a binary on THIS machine — the one fact the server cannot
 // know (same reasoning as `agent run`'s env bootstrap). A server-declared
 // preference is honored when that CLI is installed; otherwise probe the known
@@ -121,6 +133,7 @@ Examples:
   $ commonly daemon register --name "Sam's MacBook"
   $ commonly daemon heartbeat
   $ commonly daemon status
+  $ commonly daemon unregister
 `);
 
   daemon
@@ -160,6 +173,24 @@ Examples:
       }
     });
 
+  daemon
+    .command('unregister')
+    .description('Revoke this machine on the server and remove its local daemon credential')
+    .action(async () => {
+      try {
+        const record = requireDaemonRecord();
+        const client = createClient({
+          instance: record.instanceUrl,
+          token: requireUserToken(record.instanceUrl),
+        });
+        await unregisterDaemonMachine({ client, record });
+        console.log(`Unregistered ${record.machineName} and removed its local daemon credential.`);
+      } catch (error) {
+        console.error(`Daemon unregister failed: ${error.message}`);
+        process.exitCode = 1;
+      }
+    });
+
   daemon
     .command('heartbeat')
     .description('Send a machine liveness heartbeat using the stored daemon credential')

package/src/lib/adapters/codex.js

@@ -267,6 +267,8 @@ const buildArgs = ({
   outputFile,
   mcpFlags = [],
   publicSandboxMode = null,
+  model = null,
+  effort = null,
 }) => {
   const publicSandbox = publicSandboxMode !== null;
   // `--dangerously-bypass-approvals-and-sandbox` disables codex CLI's
@@ -293,6 +295,8 @@ const buildArgs = ({
     '--json',
     '--skip-git-repo-check',
     ...executionPolicy,
+    ...(model ? ['--model', String(model)] : []),
+    ...(effort ? ['-c', 'model_reasoning_effort=' + toml(effort)] : []),
     ...mcpFlags,
     '-o',
     outputFile,
@@ -444,6 +448,8 @@ export default {
         outputFile,
         mcpFlags: mcp.flags,
         publicSandboxMode,
+        model: ctx.environment?.model,
+        effort: ctx.environment?.effort,
       });
       const childEnv = { ...(ctx.env || process.env), ...mcp.forwardedEnv };
       if (publicSandboxMode !== null) {

package/src/lib/daemon-store.js

@@ -73,3 +73,13 @@ export const saveDaemonRecord = (record) => {
     throw error;
   }
 };
+
+// Call this only after the owner has revoked the matching server-side machine.
+// Local deletion first would strand a live credential with no CLI path to
+// revoke it, which is exactly the failure this command exists to prevent.
+export const removeDaemonRecord = () => {
+  const path = daemonRecordPath();
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+};

package/src/lib/daemon-supervisor.js

@@ -1,3 +1,7 @@
+import { isDeepStrictEqual } from 'node:util';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve as pathResolve } from 'node:path';
+
 /**
  * ADR-026 Phase 2, slice 2: the resident supervision loop behind
  * `commonly daemon run`.
@@ -22,6 +26,15 @@ export const DEFAULT_HEARTBEAT_MS = 30_000;
 export const BACKOFF_BASE_MS = 5_000;
 export const BACKOFF_MAX_MS = 60_000;
 
+const workspacePathFor = (environment) => {
+  const declared = environment?.workspace?.path;
+  if (typeof declared !== 'string' || !declared.trim()) return null;
+  const expanded = declared === '~'
+    ? homedir()
+    : (declared.startsWith('~/') ? `${homedir()}/${declared.slice(2)}` : declared);
+  return isAbsolute(expanded) ? expanded : pathResolve(expanded);
+};
+
 export const backoffMs = (restarts) => Math.min(
   BACKOFF_MAX_MS,
   BACKOFF_BASE_MS * 2 ** Math.max(0, Math.min(restarts, 10)),
@@ -87,11 +100,24 @@ export const createDaemonSupervisor = ({
     }
   };
 
-  // The server-declared runtime config carries the owner's model choice; the
-  // adapter reads it from the token record's environment (claude: --model).
-  const environmentFor = (row) => (
-    row.runtime?.model ? { model: String(row.runtime.model) } : null
-  );
+  // Preserve the complete ADR-008 environment when the daemon receives it.
+  // Older installs only expose runtime.model/effort; those fields are a
+  // compatibility overlay and must merge into an existing local environment
+  // rather than erasing its workspace, skills, or MCP declarations.
+  const environmentFor = (row) => {
+    const declared = row.environment && typeof row.environment === 'object'
+      && !Array.isArray(row.environment) ? { ...row.environment } : null;
+    const runtime = row.runtime && typeof row.runtime === 'object' ? row.runtime : {};
+    if (declared) {
+      if (runtime.model && declared.model === undefined) declared.model = String(runtime.model);
+      if (runtime.effort && declared.effort === undefined) declared.effort = String(runtime.effort);
+      return { value: declared, declared: true };
+    }
+    const fallback = {};
+    if (runtime.model) fallback.model = String(runtime.model);
+    if (runtime.effort) fallback.effort = String(runtime.effort);
+    return Object.keys(fallback).length ? { value: fallback, declared: false } : null;
+  };
 
   // Ensure ~/.commonly/tokens/<name>.json exists so `agent run` can boot.
   // The mint refuses to clobber an existing token (409 token_exists); the
@@ -107,10 +133,22 @@ export const createDaemonSupervisor = ({
       // once at boot). A row with NO declared model leaves the record alone —
       // never strip an operator's hand-set environment.
       const wanted = environmentFor(row);
-      if (wanted && existing.environment?.model !== wanted.model) {
-        saveToken(row.agentName, { ...existing, environment: { ...(existing.environment || {}), ...wanted } });
-        log(`[${row.agentName}] model changed to ${wanted.model} — restarting the seat to load it`);
-        return 'changed';
+      if (wanted) {
+        const nextEnvironment = wanted.declared
+          ? wanted.value
+          : { ...(existing.environment || {}), ...wanted.value };
+        const workspacePath = workspacePathFor(nextEnvironment);
+        const nextRecord = {
+          ...existing,
+          environment: nextEnvironment,
+          ...(workspacePath ? { workspacePath } : {}),
+        };
+        if (!isDeepStrictEqual(existing.environment || null, nextEnvironment)
+          || (workspacePath && existing.workspacePath !== workspacePath)) {
+          saveToken(row.agentName, nextRecord);
+          log('runtime config changed — restarting the seat to load it');
+          return 'changed';
+        }
       }
       return 'ready';
     }
@@ -149,9 +187,13 @@ export const createDaemonSupervisor = ({
       instanceUrl: record.instanceUrl,
       podId: row.podIds?.[0] || null,
       adapter,
-      ...(environment ? { environment } : {}),
+      ...(environment ? { environment: environment.value } : {}),
+      ...(environment?.value ? (() => {
+        const workspacePath = workspacePathFor(environment.value);
+        return workspacePath ? { workspacePath } : {};
+      })() : {}),
     });
-    log(`[${row.agentName}] provisioned runtime token (adapter: ${adapter}${environment ? `, model: ${environment.model}` : ''})`);
+    log(`[${row.agentName}] provisioned runtime token (adapter: ${adapter}${environment?.value?.model ? `, model: ${environment.value.model}` : ''})`);
     return 'ready';
   };
 

package/src/lib/poller.js

@@ -8,6 +8,26 @@
 
 import { createClient } from './api.js';
 
+// Delivery failures that must stop a consumer rather than fall through to the
+// normal at-least-once retry path. A stale delivery belongs to a replacement
+// runner; a missing required nonce means this runner is misconfigured. Neither
+// can become healthy by immediately fetching and retrying more work.
+export const terminalDeliveryAckError = (ackErr, eventId, runner = 'poller') => {
+  if (ackErr?.status === 409 && ackErr?.body?.code === 'stale_delivery') {
+    return Object.assign(
+      new Error(`Delivery ${eventId} was superseded — stopping ${runner}.`),
+      { code: 'stale_delivery' },
+    );
+  }
+  if (ackErr?.status === 400 && ackErr?.body?.code === 'delivery_id_required') {
+    return Object.assign(
+      new Error(`Delivery ${eventId} requires deliveryId — stopping ${runner}; update its configuration.`),
+      { code: 'delivery_id_required' },
+    );
+  }
+  return null;
+};
+
 export const startPoller = ({
   instanceUrl,
   token,
@@ -53,6 +73,12 @@ export const startPoller = ({
             ...(typeof deliveryId === 'string' && deliveryId ? { deliveryId } : {}),
           });
         } catch (ackErr) {
+          const terminalError = terminalDeliveryAckError(ackErr, event._id);
+          if (terminalError) {
+            running = false;
+            onError?.(terminalError);
+            return;
+          }
           // Non-fatal — event will be retried
           onError?.(new Error(`Ack failed for ${event._id}: ${ackErr.message}`));
         }