@commonlyai/cli 0.1.28 → 0.1.30

package/package.json

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

package/src/lib/adapters/claude.js

@@ -3,8 +3,9 @@
  *
  * Contract: ADR-005 §Adapter pattern.
  *
- * Memory preamble: if ctx.memoryLongTerm is non-empty, the adapter prepends
- * it to the prompt as a system-context preamble (§Memory bridge).
+ * Memory preamble: the adapter prepends the kernel's long-term memory context
+ * on every turn. A fresh underlying session additionally receives the
+ * read-first and durable-state-at-boundary cues (§Memory bridge).
  *
  * Environment (ADR-008 Phase 1): if ctx.environment is present, the adapter
  * symlinks declared Claude skills into `<cwd>/.claude/skills/`, writes an MCP
@@ -476,7 +477,7 @@ export default {
     // the only two paths that build a real prompt. buildPrompt handles
     // undefined and '' as absence itself; it does not need a guard, it needs
     // the value.
-    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm);
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, { freshSession: !isResume });
     const sessionFlag = isResume ? '--resume' : '--session-id';
     // Model pin from the ADR-008 environment spec. Absent it, claude picks its
     // own default — which is how a fleet of ten agents ended up running three
@@ -488,7 +489,15 @@ export default {
     // present in one but not the other means a retry silently runs a different
     // model than the turn it is replacing — the same drifting-copy shape that
     // has bitten this codebase repeatedly.
-    const modelArgs = ctx.environment?.model ? ['--model', String(ctx.environment.model)] : [];
+    // `effort` rides in the same array for the same reason: Sam's 2026-09-01
+    // order ("flip all fable agents into fable 5.1 with high or above
+    // effort") needs both facts to reach every spawn, including the
+    // 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)] : []),
+      ...(ctx.environment?.effort ? ['--effort', String(ctx.environment.effort)] : []),
+    ];
     const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId, ...modelArgs];
 
     if (ctx.environment && ctx.cwd) {
@@ -544,7 +553,11 @@ export default {
       // session id poisons every subsequent event re-delivery.
       if (isResume && /already in use|no conversation|no session/i.test(String(err.message))) {
         const freshId = randomUUID();
-        const retryBase = ['-p', fullPrompt, '--output-format', 'text', '--session-id', freshId, ...modelArgs];
+        // The retry creates a new underlying CLI session. Rebuild its prompt
+        // as fresh too: otherwise a session-recovery path is the one fresh
+        // session that misses the durable-state cue.
+        const freshPrompt = buildPrompt(prompt, ctx.memoryLongTerm, { freshSession: true });
+        const retryBase = ['-p', freshPrompt, '--output-format', 'text', '--session-id', freshId, ...modelArgs];
         const retry = await prepareArgv(retryBase, {
           ...ctx,
           mcpConfigPath: mcpConfig?.file || null,

package/src/lib/adapters/codex.js

@@ -20,10 +20,10 @@
  * `--output-last-message` short alias) — cleaner than parsing every
  * event-type variant the model can emit.
  *
- * Memory preamble: if ctx.memoryLongTerm is non-empty, the adapter prepends
- * it to the prompt as a system-context preamble (§Memory bridge), matching
- * the claude adapter's shape so the run loop's per-event memory plumbing
- * works identically across drivers.
+ * Memory preamble: the adapter prepends the kernel's long-term memory context
+ * on every turn. A fresh underlying session additionally receives the
+ * read-first and durable-state-at-boundary cues, matching the Claude adapter
+ * so the run loop's memory plumbing works identically across drivers.
  *
  * Purity (§Load-bearing invariants #1): input = argv + env + prompt;
  * output = text + session id. No direct network, no direct CAP calls.
@@ -421,7 +421,9 @@ export default {
     // the only two paths that build a real prompt. buildPrompt handles
     // undefined and '' as absence itself; it does not need a guard, it needs
     // the value.
-    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm);
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
+      freshSession: !ctx.sessionId,
+    });
 
     // Per-spawn temp dir for --output-last-message. Cleaned up in `finally`
     // so a crash in the middle of the spawn doesn't leak files in $TMPDIR.

package/src/lib/environment.js

@@ -41,7 +41,7 @@ import { homedir } from 'os';
 // "persona and runtime are chosen separately" requires to mean anything for a
 // BYO seat, and what lets an identity card answer "what is this running".
 const ALLOWED_TOP_KEYS = new Set([
-  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model',
+  'version', 'workspace', 'sandbox', 'skills', 'mcp', 'model', 'effort',
 ]);
 const ALLOWED_SANDBOX_MODES = new Set([
   'none', 'workspace', 'read-only', 'bwrap', 'firejail', 'container', 'managed',
@@ -135,6 +135,16 @@ export const validateEnvironmentSpec = (spec) => {
     }
   }
 
+  // `effort` is the reasoning budget the claude adapter passes to `--effort`.
+  // Unlike `model` it IS a closed set — the CLI documents exactly these — so a
+  // typo fails here at attach time, not silently at the first spawn.
+  if (spec.effort !== undefined) {
+    const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+    if (typeof spec.effort !== 'string' || !EFFORTS.includes(spec.effort)) {
+      errors.push(`effort must be one of: ${EFFORTS.join(', ')}`);
+    }
+  }
+
   if (spec.workspace !== undefined) {
     if (typeof spec.workspace !== 'object' || spec.workspace === null) {
       errors.push('workspace must be an object');

package/src/lib/memory-bridge.js

@@ -39,29 +39,54 @@ export const SOURCE_RUNTIME = 'local-cli';
  * and is never seen again; the write and the silence are indistinguishable from
  * a correct round trip. Naming the section is the whole point of the cue.
  */
-export const buildMemoryPreamble = (prompt, memoryLongTerm) => {
+export const buildMemoryPreamble = (prompt, memoryLongTerm, { freshSession = false } = {}) => {
   // `null` is the UNREADABLE signal, and it is deliberately not the same value
   // as `''`. Telling a seat whose token was revoked that "nothing has ever been
   // saved here" is a false claim about its own history, and it is the same
   // defect this cue exists to fix — one state over. When we could not read, say
   // that, and say nothing about what is stored.
+  let context;
   if (memoryLongTerm === null) {
-    return `=== Context (your persistent memory) ===\n`
+    context = `=== Context (your persistent memory) ===\n`
       + `(unreadable this turn — the memory read failed, so this says NOTHING `
       + `about what you have saved. Do not treat it as empty and do not re-save `
-      + `state you may already hold.)\n`
-      + `=== Current turn ===\n${prompt}`;
+      + `state you may already hold.)`;
+  } else if (memoryLongTerm) {
+    context = `=== Context (your persistent memory) ===\n${memoryLongTerm}`;
+  } else {
+    context = `=== Context (your persistent memory) ===\n`
+      + `(empty — nothing has ever been saved here)\n`
+      + `Only the \`long_term\` section is read back into this prompt. To make `
+      + `something survive your next session, call commonly_save_my_memory({ `
+      + `section: 'long_term', content: '...' }). A write to any other section `
+      + `succeeds and is never shown to you again.`;
   }
-  if (memoryLongTerm) {
-    return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
+
+  if (!freshSession) return `${context}\n=== Current turn ===\n${prompt}`;
+
+  // This belongs on a fresh underlying CLI session, rather than every turn:
+  // a resumed session already carries the earlier instruction in its own
+  // transcript. Repeating it on each wake spends prompt budget while making
+  // the cue easier to ignore. The wrapper cannot know the final event of a
+  // session in advance, so it gives the end-of-session reminder while the
+  // agent can still act on it.
+  const freshReadCue = '=== Fresh session ===\n'
+    + 'This is a fresh session. Read the persistent memory context above before acting; '
+    + 'it carries durable state from prior sessions.\n';
+  let sessionEndCue = '=== Before this session ends ===\n';
+  if (memoryLongTerm === null) {
+    sessionEndCue += 'Memory was unreadable on this fresh session. Do not treat it as empty or '
+      + 'write a replacement based on this cue.';
+  } else if (memoryLongTerm) {
+    sessionEndCue += 'At a natural end to meaningful work, save durable working state — '
+      + 'gates held, decisions pending, and task context, not a transcript — with '
+      + "commonly_save_my_memory({ section: 'long_term', content: '...' }).";
+  } else {
+    sessionEndCue += 'At a natural end to meaningful work, save durable working state — '
+      + 'gates held, decisions pending, and task context, not a transcript — using '
+      + 'the long_term write above.';
   }
-  return `=== Context (your persistent memory) ===\n`
-    + `(empty — nothing has ever been saved here)\n`
-    + `Only the \`long_term\` section is read back into this prompt. To make `
-    + `something survive your next session, call commonly_save_my_memory({ `
-    + `section: 'long_term', content: '...' }). A write to any other section `
-    + `succeeds and is never shown to you again.\n`
-    + `=== Current turn ===\n${prompt}`;
+  return `${context}\n${freshReadCue}\n=== Current turn ===\n${prompt}\n${sessionEndCue}`;
 };
 
 export const readLongTerm = async (client, { onError } = {}) => {