@commonlyai/cli 0.1.164 → 0.1.166

package/package.json

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

package/src/commands/agent.js

@@ -17,6 +17,7 @@ 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 { copyHandoffMemory } from '../lib/handoff-memory.js';
 import {
@@ -666,12 +667,29 @@ export const updateAgentConfiguration = async ({
   model = null,
   effort = null,
   envPath = null,
+  runtimeKey = false,
   parseEnv = parseEnvironmentFile,
   adapterRegistry = { getAdapter, listAdapterNames },
 }) => {
   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 commonly 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 = {};
@@ -1253,6 +1271,7 @@ export const performRun = ({
   const effectiveTurnTimeoutMs = Number.isFinite(requestedTurnTimeout) && requestedTurnTimeout > 0
     ? Math.min(requestedTurnTimeout, 2_147_483_647) : 15 * 60 * 1000;
   const client = createClient({ instance: instanceUrl, token });
+  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`);
@@ -1677,6 +1696,30 @@ export const performRun = ({
       ? `${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 deliverChatReply({
+              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
@@ -3748,13 +3791,21 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
         process.exit(1);
       }
       const instance = opts.instance || record.instanceUrl;
-      const token = getToken(instance);
+      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: commonly login'); process.exit(1); }
-      const client = createClient({ instance: resolveInstanceUrl(instance), token });
       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 commonly login');
+        }
+        const client = createClient({ instance: instanceUrl, token });
         const result = await updateAgentConfiguration({
           client,
           record,
+          runtimeKey,
           adapter: opts.adapter,
           model: opts.model,
           effort: opts.effort,

package/src/lib/adapters/claude.js

@@ -43,6 +43,7 @@
  * SIGKILL escalation is a post-v1 concern (ADR-005 §Spawning semantics).
  */
 
+import { requireSeatModel, seatModelRequired } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash, randomUUID } from 'crypto';
 import { accessSync, constants, realpathSync } from 'fs';
@@ -725,6 +726,7 @@ const prepareArgv = async (innerArgv, ctx) => {
 };
 
 export default {
+  get requiresModel() { return seatModelRequired(); },
   name: 'claude',
   // Identity-bearing runtime tag written into AgentInstallation.config.runtime
   // by `commonly agent attach`. The CLI command stays `commonly agent attach
@@ -759,6 +761,7 @@ export default {
   },
 
   async spawn(prompt, rawCtx = {}) {
+    const seatModel = requireSeatModel(rawCtx.environment, 'claude');
     // `sandbox.trust: 'internal'` is refused for new declarations and read as
     // `public` for a record that already carries it; such a seat is confined
     // where it can be and refuses to derive where it cannot (Wren 69585).
@@ -809,7 +812,7 @@ export default {
     // session-recovery retry, or a retry runs at a different effort than the
     // turn it replaces.
     const modelArgs = [
-      ...(ctx.environment?.model ? ['--model', String(ctx.environment.model)] : []),
+      ...(seatModel ? ['--model', seatModel] : []),
       ...(ctx.environment?.effort ? ['--effort', String(ctx.environment.effort)] : []),
     ];
     const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId, ...modelArgs];

package/src/lib/adapters/codex.js

@@ -37,6 +37,7 @@
  * SIGKILL escalation is a post-v1 concern (ADR-005 §Spawning semantics).
  */
 
+import { requireSeatModel, seatModelRequired } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { accessSync, constants } from 'fs';
@@ -616,6 +617,7 @@ const runCodex = ({ args, cwd, env, timeoutMs, credentials = [], spawnImpl = chi
 });
 
 export default {
+  get requiresModel() { return seatModelRequired(); },
   name: 'codex',
   // See claude.js for the rationale — identity-bearing runtime tag persisted
   // to AgentInstallation.config.runtime (paired with host:'byo') so a CLI-
@@ -642,6 +644,7 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'codex');
     // Passed through UNCOALESCED. `ctx.memoryLongTerm || ''` was here, and
     // `null || ''` is `''` — which routed the unreadable case straight into
     // the empty-memory branch and made the whole distinction unreachable from
@@ -698,7 +701,7 @@ export default {
         mcpFlags: mcp.flags,
         mcpReadDirectories: mcp.mcpReadDirectories,
         publicSandboxMode,
-        model: ctx.environment?.model,
+        model: seatModel,
         effort: ctx.environment?.effort,
         commitAttributionEnv: ctx.commitAttributionEnv,
       });

package/src/lib/adapters/dsh.js

@@ -1,4 +1,5 @@
 /** DeepSeek Harness 0.2.1-rc.2, private seats only. Configuration is per spawn. */
+import { requireSeatModel } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { existsSync } from 'fs';
@@ -218,6 +219,7 @@ export const runDsh = ({ binary, args, cwd, env, timeoutMs, credentials, spawnIm
 });
 
 export default {
+  requiresModel: true,
   name: 'dsh', runtimeType: 'dsh', supportsProvider: true,
 
   async validateEnvironment(environment, workspacePath) {
@@ -246,6 +248,7 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'dsh', true);
     assertPrivateDsh(ctx.environment);
     if (!ctx.environment?.provider || !ctx.environment?.model) {
       throw new Error('dsh requires environment.provider and environment.model');
@@ -275,7 +278,7 @@ export default {
         credentialFile: credential.path, instanceUrl: ctx.instanceUrl,
       });
       const patch = JSON.stringify(buildPatch({
-        proxyBaseURL: proxy.baseURL, model: ctx.environment.model,
+        proxyBaseURL: proxy.baseURL, model: seatModel,
         cwd: ctx.cwd, mcp, effort: ctx.environment.effort,
         deepseekOfficial: new URL(ctx.environment.provider.baseURL).hostname === 'api.deepseek.com',
       }), null, 2);

package/src/lib/adapters/goose.js

@@ -1,4 +1,5 @@
 /** Goose 1.54.0 wrapper. Public seats wait for TASK-236's deny-by-default proof. */
+import { requireSeatModel } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'node:child_process';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -16,7 +17,6 @@ import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
 export const TESTED_GOOSE_VERSIONS = Object.freeze(['1.54.0']);
 const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
 const TERMINATION_GRACE_MS = 5000;
-const DEFAULT_MODEL = 'deepseek-v4-flash';
 const DEFAULT_PROVIDER_HOST = 'https://litellm.commonly.me';
 const DEFAULT_PROVIDER_KEY = 'COMMONLY_LITELLM_KEY';
 const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
@@ -174,6 +174,7 @@ const runGoose = ({ binary, args, cwd, env, timeoutMs, credentials, spawnImpl =
 });
 
 export default {
+  requiresModel: true,
   name: 'goose',
   providerKeyEnv: DEFAULT_PROVIDER_KEY,
   supportsProvider: true,
@@ -193,6 +194,7 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'goose', true);
     const keyFile = await this.validateEnvironment(ctx.environment, ctx.cwd);
     const sourceEnv = ctx.env || process.env;
     const configured = ctx.environment?.provider;
@@ -203,7 +205,7 @@ export default {
     if (!/^https?:$/.test(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash) {
       throw new Error('goose adapter: provider.baseURL must be a plain HTTP(S) URL');
     }
-    const model = ctx.environment?.model || DEFAULT_MODEL;
+    const model = seatModel;
     const binary = ctx._binaryPath || 'goose';
     const version = ctx._version || versionOf(spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 5000 }).stdout);
     if (!TESTED_GOOSE_VERSIONS.includes(version)) {

package/src/lib/adapters/hermes.js

@@ -1,4 +1,5 @@
 /** Hermes 0.22.2 local CLI wrapper. Hermes owns provider I/O; this file only spawns it. */
+import { requireSeatModel, seatModelRequired } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { mkdir } from 'fs/promises';
@@ -137,6 +138,7 @@ const runHermes = ({ args, prompt, cwd, env, timeoutMs, spawnImpl, credentials }
 });
 
 export default {
+  get requiresModel() { return seatModelRequired(); },
   name: 'hermes',
   runtimeType: 'hermes',
   supportsProvider: false,
@@ -161,6 +163,7 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'hermes');
     await this.validateEnvironment(ctx.environment);
     // Keep Hermes away from the operator's default profile, including any
     // Nous Portal/Cloud credentials there. The wrapper provides the sole key.
@@ -177,7 +180,7 @@ export default {
     }
     const args = ['chat', '--oneshot', '--query-file', '-', '--format', 'stream-json',
       '--provider', 'openrouter', '--source', 'tool', '--no-restore-cwd'];
-    if (ctx.environment?.model) args.push('--model', ctx.environment.model);
+    if (seatModel) args.push('--model', seatModel);
     if (ctx.sessionId) args.push('--resume', ctx.sessionId);
     const fullPrompt = buildMemoryPreamble(prompt, ctx.memoryLongTerm, {
       freshSession: !ctx.sessionId,

package/src/lib/adapters/opencode.js

@@ -19,6 +19,7 @@
  * `text.part.text`, and token counts in `step_finish.part.tokens`.
  */
 
+import { requireSeatModel, seatModelRequired } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { realpathSync } from 'fs';
@@ -622,6 +623,7 @@ const describeOpenCodeVersionMismatch = (installedVersion) => {
 };
 
 export default {
+  get requiresModel() { return seatModelRequired(); },
   name: 'opencode',
   runtimeType: 'opencode',
   supportsProvider: true,
@@ -645,6 +647,7 @@ export default {
   },
 
   async spawn(prompt, rawCtx = {}) {
+    const seatModel = requireSeatModel(rawCtx.environment, 'opencode');
     const sandbox = normalizeSandboxTrust(rawCtx.environment?.sandbox);
     const ctx = rawCtx.environment
       ? { ...rawCtx, environment: { ...rawCtx.environment, sandbox } }
@@ -805,7 +808,7 @@ export default {
         prompt: fullPrompt,
         sessionId: ctx.sessionId,
         cwd: ctx.cwd,
-        model: qualifiedProviderModel(provider, ctx.environment?.model),
+        model: qualifiedProviderModel(provider, seatModel),
         effort: ctx.environment?.effort,
         title: ctx.agentName,
       });

package/src/lib/adapters/pi.js

@@ -32,6 +32,7 @@
  * Contract (see stub.js): detect() and spawn(prompt, ctx) → { text, newSessionId }.
  */
 
+import { requireSeatModel } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { createHash, randomUUID } from 'crypto';
 import { mkdir, readdir, writeFile } from 'fs/promises';
@@ -65,7 +66,6 @@ export const DEFAULT_PROVIDER = Object.freeze({
   api: 'openai-completions',
   apiKeyEnv: 'COMMONLY_LITELLM_KEY',
 });
-export const DEFAULT_MODEL = 'deepseek-v4-flash';
 
 // ADR-008 `effort` → pi `--thinking`. pi's ladder is off/minimal/low/medium/high/xhigh/max.
 const THINKING = { none: 'off', off: 'off', minimal: 'minimal', low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max' };
@@ -390,6 +390,7 @@ const runPi = ({ args, cwd, env, payload, timeoutMs, credentials = [], spawnImpl
 });
 
 export default {
+  requiresModel: true,
   name: 'pi',
 
   // TASK-049: the variable this adapter needs from the environment of whatever
@@ -409,12 +410,13 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'pi', true);
     // pi has no enforced sandbox. claude.js and codex.js refuse a public-trust
     // seat they cannot confine; so does this adapter, and it refuses any declared
     // sandbox mode rather than run unconfined under a spec that promised one.
     assertNoSandboxDeclared(ctx.environment);
     const provider = resolveProvider(ctx.environment);
-    const model = ctx.environment?.model || DEFAULT_MODEL;
+    const model = seatModel;
     const thinking = thinkingFor(ctx.environment?.effort);
     const baseEnv = ctx.env || process.env;
     if (!baseEnv[provider.apiKeyEnv]) {

package/src/lib/adapters/qwen.js

@@ -1,4 +1,5 @@
 /** Qwen Code 0.25.1 wrapper. Public turns have fresh HOME, config and keys. */
+import { requireSeatModel } from './seat-model.js';
 import { spawn as childSpawn, spawnSync } from 'child_process';
 import { lstatSync, realpathSync } from 'fs';
 import { chmod, mkdtemp, readFile, rm, writeFile } from 'fs/promises';
@@ -208,6 +209,7 @@ const runQwen = ({ cmd, args, cwd, env, timeoutMs, spawnImpl, credentials }) =>
 });
 
 export default {
+  requiresModel: true,
   name: 'qwen',
   runtimeType: 'qwen',
   supportsProvider: true,
@@ -230,6 +232,7 @@ export default {
   },
 
   async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'qwen', true);
     const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
     const isPublic = sandbox?.trust === 'public';
     const mode = isPublic ? resolvePublicSandboxMode(sandbox) : null;
@@ -304,7 +307,7 @@ export default {
         freshSession: true,
       });
       const args = [
-        '--bare', '--safe-mode', '--auth-type', 'openai', '-m', ctx.environment.model,
+        '--bare', '--safe-mode', '--auth-type', 'openai', '-m', seatModel,
         '--mcp-config', mcpPath, '--exclude-tools', [
           ...EXCLUDED_TOOLS, ...(isPublic ? PUBLIC_READ_TOOLS : []),
         ].join(','),

package/src/lib/adapters/seat-model.js

@@ -0,0 +1,15 @@
+/** Fleet runners opt in; BYO users retain their own CLI's model default. */
+export const seatModelRequired = () => process.env.COMMONLY_REQUIRE_SEAT_MODEL === '1';
+
+export const requireSeatModel = (environment, adapterName, required = seatModelRequired()) => {
+  const model = environment?.model;
+  if (typeof model !== 'string' || !model.trim()) {
+    if (!required) return undefined;
+    const error = new Error(
+      `${adapterName} requires environment.model; set the seat model with commonly agent config <name> --model <model> before running`,
+    );
+    error.code = 'seat_model_missing';
+    throw error;
+  }
+  return model.trim();
+};