ac-framework 1.9.4 → 1.9.6

package/framework/web_development/.opencode/command/ac.md

@@ -98,6 +98,45 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ### OpenSpec Skills (The heart of the framework)
 

package/framework/web_development/.qoder/commands/opsx/ac.md

@@ -98,6 +98,45 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ### OpenSpec Skills (The heart of the framework)
 

package/framework/web_development/.qwen/commands/ac.md

@@ -98,6 +98,45 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ### OpenSpec Skills (The heart of the framework)
 

package/framework/web_development/.roo/commands/ac.md

@@ -98,6 +98,45 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ### OpenSpec Skills (The heart of the framework)
 

package/framework/web_development/.windsurf/workflows/ac.md

@@ -98,6 +98,45 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
 
 ### OpenSpec Skills (The heart of the framework)
 

package/framework/web_development/AGENTS.md

@@ -98,6 +98,33 @@ acfm memory stats
 
 **User communication:** "Memory saved: [brief description]" when auto-saving occurs.
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Optional install/reinstall of collaborative MCP servers
+acfm agents install-mcps
+
+# Start collaborative runtime manually
+acfm agents start --task "design and implement feature X"
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+```
+
 
 ### OpenSpec Skills (The heart of the framework)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-framework",
-  "version": "1.9.4",
+  "version": "1.9.6",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {

package/src/agents/config-store.js

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { sanitizeRoleModels, normalizeModelId } from './model-selection.js';
+
+const ACFM_DIR = join(homedir(), '.acfm');
+const CONFIG_PATH = join(ACFM_DIR, 'config.json');
+
+function normalizeConfig(raw) {
+  const agents = raw?.agents && typeof raw.agents === 'object' ? raw.agents : {};
+  return {
+    agents: {
+      defaultModel: normalizeModelId(agents.defaultModel) || null,
+      defaultRoleModels: sanitizeRoleModels(agents.defaultRoleModels),
+    },
+  };
+}
+
+export async function loadAgentsConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    return normalizeConfig({});
+  }
+
+  try {
+    const raw = JSON.parse(await readFile(CONFIG_PATH, 'utf8'));
+    return normalizeConfig(raw);
+  } catch {
+    return normalizeConfig({});
+  }
+}
+
+export async function saveAgentsConfig(config) {
+  const normalized = normalizeConfig(config);
+  await mkdir(ACFM_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(normalized, null, 2) + '\n', 'utf8');
+  return normalized;
+}
+
+export async function updateAgentsConfig(mutator) {
+  const current = await loadAgentsConfig();
+  const next = await mutator(current);
+  return saveAgentsConfig(next);
+}
+
+export function getAgentsConfigPath() {
+  return CONFIG_PATH;
+}

package/src/agents/model-selection.js

@@ -0,0 +1,38 @@
+import { COLLAB_ROLES } from './constants.js';
+
+export function normalizeModelId(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function isValidModelId(value) {
+  const normalized = normalizeModelId(value);
+  if (!normalized) return false;
+  return normalized.includes('/');
+}
+
+export function sanitizeRoleModels(input) {
+  const out = {};
+  if (!input || typeof input !== 'object') return out;
+  for (const role of COLLAB_ROLES) {
+    const normalized = normalizeModelId(input[role]);
+    if (normalized) out[role] = normalized;
+  }
+  return out;
+}
+
+export function resolveRoleModel(state, role, fallbackModel = null) {
+  const roleModels = sanitizeRoleModels(state?.roleModels);
+  const roleModel = roleModels[role] || null;
+  const globalModel = normalizeModelId(state?.model) || normalizeModelId(fallbackModel);
+  return roleModel || globalModel || null;
+}
+
+export function buildEffectiveRoleModels(state, fallbackModel = null) {
+  const effective = {};
+  for (const role of COLLAB_ROLES) {
+    effective[role] = resolveRoleModel(state, role, fallbackModel);
+  }
+  return effective;
+}

package/src/agents/opencode-client.js

@@ -22,7 +22,8 @@ function parseOpenCodeRunOutput(stdout) {
   return stdout.trim();
 }
 
-export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs = 180000 }) {
+export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs = 180000, binaryPath }) {
+  const binary = binaryPath || process.env.ACFM_OPENCODE_BIN || 'opencode';
   const args = ['run', '--format', 'json'];
   if (model) {
     args.push('--model', model);
@@ -32,7 +33,7 @@ export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs =
   }
   args.push('--', prompt);
 
-  const { stdout, stderr } = await execFileAsync('opencode', args, {
+  const { stdout, stderr } = await execFileAsync(binary, args, {
     cwd,
     timeout: timeoutMs,
     maxBuffer: 10 * 1024 * 1024,

package/src/agents/orchestrator.js

@@ -1,6 +1,7 @@
 import { buildAgentPrompt, ROLE_SYSTEM_PROMPTS } from './role-prompts.js';
 import { runOpenCodePrompt } from './opencode-client.js';
 import { nextRole, shouldStop } from './scheduler.js';
+import { resolveRoleModel } from './model-selection.js';
 import {
   addAgentMessage,
   loadSessionState,
@@ -42,11 +43,13 @@ export async function runTurn(sessionId, options = {}) {
     const prompt = buildRuntimePrompt({ state, role: scheduled.role });
     let content;
     try {
+      const effectiveModel = resolveRoleModel(state, scheduled.role, options.model);
       content = await runOpenCodePrompt({
         prompt,
         cwd: options.cwd || process.cwd(),
-        model: options.model,
+        model: effectiveModel,
         agent: options.agent,
+        binaryPath: options.opencodeBin,
         timeoutMs: options.timeoutMs,
       });
     } catch (error) {
@@ -105,11 +108,13 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
     const prompt = buildRuntimePrompt({ state, role });
     let content;
     try {
+      const effectiveModel = resolveRoleModel(state, role, options.model);
       content = await runOpenCodePrompt({
         prompt,
         cwd: options.cwd || process.cwd(),
-        model: options.model,
+        model: effectiveModel,
         agent: options.agent,
+        binaryPath: options.opencodeBin,
         timeoutMs: options.timeoutMs,
       });
     } catch (error) {
@@ -153,11 +158,13 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
     const prompt = buildRuntimePrompt({ state, role });
     let content;
     try {
+      const effectiveModel = resolveRoleModel(state, role, options.model);
       content = await runOpenCodePrompt({
         prompt,
         cwd: options.cwd || process.cwd(),
-        model: options.model,
+        model: effectiveModel,
         agent: options.agent,
+        binaryPath: options.opencodeBin,
         timeoutMs: options.timeoutMs,
       });
     } catch (error) {

package/src/agents/runtime.js

@@ -0,0 +1,80 @@
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { COLLAB_ROLES } from './constants.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const runnerPath = resolve(__dirname, '../../bin/acfm.js');
+
+export function roleLogPath(sessionDir, role) {
+  return resolve(sessionDir, `${role}.log`);
+}
+
+export function runTmux(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      stdio: options.stdio || 'pipe',
+      env: process.env,
+    });
+
+    let stderr = '';
+    let stdout = '';
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+    if (child.stdout) {
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+    }
+
+    child.on('error', rejectPromise);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr });
+        return;
+      }
+      rejectPromise(new Error(stderr.trim() || `${command} exited with code ${code}`));
+    });
+  });
+}
+
+export async function spawnTmuxSession({ sessionName, sessionDir, sessionId }) {
+  const role0 = COLLAB_ROLES[0];
+  await runTmux('tmux', [
+    'new-session',
+    '-d',
+    '-s',
+    sessionName,
+    '-n',
+    role0,
+    `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role0} >> "${roleLogPath(sessionDir, role0)}" 2>&1'`,
+  ]);
+
+  for (let idx = 1; idx < COLLAB_ROLES.length; idx += 1) {
+    const role = COLLAB_ROLES[idx];
+    await runTmux('tmux', [
+      'split-window',
+      '-t',
+      sessionName,
+      '-v',
+      `bash -lc 'node "${runnerPath}" agents worker --session ${sessionId} --role ${role} >> "${roleLogPath(sessionDir, role)}" 2>&1'`,
+    ]);
+  }
+
+  await runTmux('tmux', ['select-layout', '-t', sessionName, 'tiled']);
+  await runTmux('tmux', ['set-option', '-t', sessionName, 'pane-border-status', 'top']);
+  await runTmux('tmux', ['set-option', '-t', sessionName, 'pane-border-format', '#{pane_index}:#{pane_title}']);
+}
+
+export async function tmuxSessionExists(sessionName) {
+  try {
+    await runTmux('tmux', ['has-session', '-t', sessionName]);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/agents/state-store.js

@@ -8,6 +8,7 @@ import {
   SESSION_ROOT_DIR,
   CURRENT_SESSION_FILE,
 } from './constants.js';
+import { sanitizeRoleModels } from './model-selection.js';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -53,6 +54,8 @@ function initialState(task, options = {}) {
     roles: options.roles?.length ? options.roles : COLLAB_ROLES,
     workingDirectory: options.workingDirectory || process.cwd(),
     model: options.model || null,
+    roleModels: sanitizeRoleModels(options.roleModels),
+    opencodeBin: options.opencodeBin || null,
     tmuxSessionName: options.tmuxSessionName || null,
     messages: [
       {