@commonlyai/cli 0.1.171 → 0.1.173

package/README.md

@@ -33,11 +33,21 @@ Keep active-instance precedence separate from the newest-match fallback; back-to
 A hosted agent's local handoff card includes `--memory-from <hosted-agent>` and
 `--memory-instance <hosted-instance>` on the attach command. After login, attach
 copies that source's long-term memory into the local identity before returning
-its runnable configuration. Both identities must be accessible through the
-logged-in account's owner memory API. No hosted runtime credential is moved.
+its runnable configuration. The source and target must belong to the logged-in
+owner. No hosted runtime credential is moved.
 
 This is a snapshot, not a shared identity or continuing synchronization. Attach
 refuses to replace different existing local memory or copy into a non-private
-long-term section. A failed copy stops attach; correct the error and retry before
-running the local agent. A retry resumes only your matching active local installation,
+long-term section. The install request completes memory authorization and the
+revision-checked copy before joining the pod, creating an installation or posting
+a greeting. A refused copy leaves those effects absent (an existing installation
+is preserved). A later identity-creation or pod-join refusal can leave the copied
+memory without an installation; retries recognize the snapshot as already copied.
+The server claims the registry name before copying. On copy failure it releases
+only the new, unchanged claim when no installation uses it; a claim touched by
+another in-flight handoff is retained. Memory is not rolled back across later
+identity or pod-join operations. Correct the error and
+retry before running the local agent.
+The CLI checks server support before publishing or installing; deploy the backend
+with install-time handoff support before distributing the updated CLI. A retry resumes only your matching active local installation,
 without changing its configuration or scopes. Repeating a copy with identical memory is safe.

package/package.json

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

package/src/commands/agent.js

@@ -22,7 +22,6 @@ 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 {
   buildSpawnId,
   createSpawnCredentialLease,
@@ -987,6 +986,13 @@ export const performAttach = async ({
   // 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 {
@@ -1010,7 +1016,9 @@ export const performAttach = async ({
   // 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 ? {
+      resumeExisting: true, memoryFrom: { agentName: memoryFrom, instanceId: memoryInstance },
+    } : {}),
     agentName,
     podId,
     displayName: displayName || agentName,
@@ -1034,10 +1042,8 @@ export const performAttach = async ({
   const instanceId = installation.instanceId || 'default';
 
   if (memoryFrom) {
-    const memoryCopy = await copyHandoffMemory(client, {
-      sourceAgentName: memoryFrom, sourceInstanceId: memoryInstance,
-      targetAgentName: installation.agentName, targetInstanceId: instanceId,
-    });
+    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');

package/src/lib/adapters/claude.js

@@ -81,7 +81,7 @@ import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credent
 import {
   prepareMcpSpawn, PUBLIC_MCP_UNAVAILABLE_CODE, publicMcpUnavailableError, selectedMcpVersionDir,
 } from '../mcp-home.js';
-import { buildMemoryPreamble } from '../memory-bridge.js';
+import { buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
 import { claudeConfigDirFor, claudeContextTokens } from '../session-recycle.js';
 import { skillsAsText } from '../skill-prompt.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -98,6 +98,16 @@ const DEFAULT_TIMEOUT_MS = (() => {
 })();
 
 const buildPrompt = buildMemoryPreamble;
+
+// The working habits a private claude seat is taught on a fresh session (D48,
+// TASK-545). Parallel reads live here because only this CLI has a subagent
+// tool; codex is passed row slicing alone. A public seat is passed neither: its
+// argv allows Read and the MCP under dontAsk, so it has no subagent to spawn,
+// and it answers strangers rather than working board rows.
+const PARALLEL_READS_CUE = 'Parallel reads: when a row needs several files or sources read, '
+  + 'use the Agent tool. Spawn read-only subagents in parallel, brief each one with the files '
+  + 'to read and the question to answer, and keep only their conclusions.';
+const WORK_CUES = [PARALLEL_READS_CUE, ROW_SLICING_CUE];
 const RUNTIME_CREDENTIAL_PLACEHOLDER = '${COMMONLY_AGENT_TOKEN}';
 
 const QUOTE_SHELL_ARGUMENT = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -799,7 +809,12 @@ 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, { freshSession: !isResume });
+    const publicTrust = ctx.environment?.sandbox?.trust === 'public';
+    const workCues = publicTrust ? [] : WORK_CUES;
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
+      freshSession: !isResume,
+      workCues,
+    });
     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
@@ -839,7 +854,6 @@ export default {
     let mcpConfig = null;
     let publicClaudeState = null;
     let publicSkillArgs = [];
-    const publicTrust = ctx.environment?.sandbox?.trust === 'public';
     const publicNativeSandbox = publicTrust
       && PUBLIC_SANDBOX_MODES.has(resolvePublicSandboxMode(ctx.environment?.sandbox));
     const publicBwrapSandbox = publicTrust
@@ -927,7 +941,10 @@ export default {
         // 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 freshPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
+          freshSession: true,
+          workCues,
+        });
         const retryBase = ['-p', freshPrompt,
         '--output-format', 'text', '--session-id', freshId, ...modelArgs];
         const retryCtx = {

package/src/lib/adapters/codex.js

@@ -66,7 +66,7 @@ import { CREDENTIAL_KEY, writeCredentialFile } from '../credential-file.js';
 import { supportedGitHooks } from '../commit-attribution.js';
 import { deliverSeatCredential, withholdRuntimeCredential } from '../mcp-credential-delivery.js';
 import { prepareMcpSpawn, publicMcpUnavailableError, selectedMcpVersionDir } from '../mcp-home.js';
-import { buildMemoryPreamble } from '../memory-bridge.js';
+import { buildMemoryPreamble, ROW_SLICING_CUE } from '../memory-bridge.js';
 import { resolveSkillSource, skillsAsText } from '../skill-prompt.js';
 import { isLegacySandboxTrust, normalizeSandboxTrust } from '../environment.js';
 import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
@@ -650,14 +650,20 @@ export default {
 
   async spawn(prompt, ctx = {}) {
     const seatModel = requireSeatModel(ctx.environment, 'codex');
+    const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
     // 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
     // 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.
+    //
+    // Codex has no subagent tool, so of D48's two habits (TASK-545) it is
+    // taught row slicing alone; claude.js adds parallel reads. A public seat
+    // answers strangers rather than working board rows, so it is taught neither.
     const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm, {
       freshSession: !ctx.sessionId,
+      workCues: sandbox?.trust === 'public' ? [] : [ROW_SLICING_CUE],
     });
 
     // Per-spawn temp dir for --output-last-message. Cleaned up in `finally`
@@ -674,7 +680,6 @@ export default {
     });
 
     try {
-      const sandbox = normalizeSandboxTrust(ctx.environment?.sandbox);
       const mcp = buildMcpOverrideArgs(ctx.environment?.mcp, {
         runtimeToken: ctx.runtimeToken,
         instanceUrl: ctx.instanceUrl,

package/src/lib/memory-bridge.js

@@ -22,6 +22,18 @@
 
 export const SOURCE_RUNTIME = 'local-cli';
 
+/**
+ * Row slicing, the runtime-agnostic half of D48 (TASK-545). A row too large
+ * for one turn drifts when one seat carries it whole, so the seat splits it on
+ * the board before any code. It names the exact call and field for the reason
+ * the memory cue below names `long_term`: a seat adopts a habit through a
+ * surface it can see. Each adapter decides whether to pass it.
+ */
+export const ROW_SLICING_CUE = 'Slicing: when a row is too large for one turn, split it before '
+  + 'writing any code. Post each slice as a child row (commonly_create_task with parentTask set '
+  + "to the row's taskId) with one assignee, a written file or area boundary, and its own "
+  + 'acceptance line.';
+
 /**
  * The turn preamble, shared by every adapter so the two cannot drift.
  *
@@ -39,8 +51,17 @@ export const SOURCE_RUNTIME = 'local-cli';
  * the section whose name most invites exactly this use — succeeds, returns 200,
  * 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.
+ *
+ * `workCues` are working habits an adapter teaches on a fresh session, beside
+ * the memory cues and under the same once-per-session rule. An adapter passes
+ * only the habits its CLI can act on; passing none leaves the preamble as it
+ * was.
  */
-export const buildMemoryPreamble = (prompt, memoryLongTerm, { freshSession = false } = {}) => {
+export const buildMemoryPreamble = (
+  prompt,
+  memoryLongTerm,
+  { freshSession = false, workCues = [] } = {},
+) => {
   // `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
@@ -87,7 +108,10 @@ export const buildMemoryPreamble = (prompt, memoryLongTerm, { freshSession = fal
       + 'gates held, decisions pending, and task context, not a transcript — using '
       + 'the long_term write above.';
   }
-  return `${context}\n${freshReadCue}\n=== Current turn ===\n${prompt}\n${sessionEndCue}`;
+  const workCue = workCues.length
+    ? `\n=== Working a row ===\n${workCues.map((cue) => `- ${cue}`).join('\n')}\n`
+    : '';
+  return `${context}\n${freshReadCue}${workCue}\n=== Current turn ===\n${prompt}\n${sessionEndCue}`;
 };
 
 export const readLongTerm = async (client, { onError } = {}) => {

package/src/lib/handoff-memory.js

@@ -1,23 +0,0 @@
-/** Copy only long-term memory using the logged-in owner's revision-checked API. */
-export const copyHandoffMemory = async (client, {
-  sourceAgentName, sourceInstanceId = 'default', targetAgentName, targetInstanceId = 'default',
-}) => {
-  const endpoint = (name, instance) => `/api/agent-memory/${encodeURIComponent(name)}/${encodeURIComponent(instance)}/editable`;
-  const source = await client.get(endpoint(sourceAgentName, sourceInstanceId));
-  const content = source?.sections?.long_term?.content;
-  if (typeof content !== 'string') throw new Error('Hosted memory response is missing long_term content');
-  if (!content) return { copied: false, reason: 'source-empty' };
-  const targetPath = endpoint(targetAgentName, targetInstanceId);
-  const target = await client.get(targetPath);
-  const prior = target?.sections?.long_term;
-  if (typeof prior?.content !== 'string') throw new Error('Local memory response is missing long_term content');
-  if (prior.visibility !== 'private') throw new Error('Local long-term memory must be private before copying hosted memory');
-  if (prior.content === content) return { copied: false, reason: 'already-copied' };
-  if (prior.content) throw new Error('Local agent already has different memory; choose a new local name');
-  // A concurrent first write wins rather than being overwritten by this copy.
-  await client.patch(`${targetPath}/long_term`, {
-    copyFrom: { agentName: sourceAgentName, instanceId: sourceInstanceId },
-    expectedUpdatedAt: prior.updatedAt ?? null,
-  });
-  return { copied: true };
-};