ac-framework 1.9.7 → 1.9.9

package/README.md

@@ -6,7 +6,7 @@ It combines three layers in one CLI:
 - template-based assistant configurations for multiple IDEs and AI CLIs
 - a built-in spec-driven workflow inspired by OpenSpec / spec-driven development
 - a persistent local memory system with MCP integration for supported assistants
-- an optional collaborative multi-agent runtime powered by OpenCode + tmux
+- an optional collaborative multi-agent runtime powered by OpenCode + zellij (tmux fallback)
 
 ## Why AC Framework
 
@@ -26,7 +26,7 @@ The goal is simple: help AI write better code, with more context, more disciplin
 - `Spec-driven workflow` - use `acfm spec` to initialize, create, validate, continue, and archive structured changes.
 - `Persistent memory` - store architectural decisions, bugfixes, refactors, conventions, and context in a local SQLite memory database.
 - `MCP integration` - connect the memory system to supported assistants through MCP so they can recall and save context directly.
-- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated tmux panes with shared context.
+- `Collaborative agents (optional)` - enable SynapseGrid to run planner/critic/coder/reviewer in coordinated zellij panes (tmux fallback) with shared context.
 - `GitHub sync` - use `acfm init --latest` or `acfm update` to pull the latest framework content from GitHub.
 - `Legacy compatibility` - `.acfm/` is the new default, but existing `openspec/` directories still work.
 
@@ -57,7 +57,7 @@ The CLI now guides you through:
 2. choose one or more assistants from that template
 3. install the matching root instruction files like `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `copilot-instructions.md`
 4. optionally initialize NexusVault persistent memory and MCP connections
-5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + tmux)
+5. optionally enable SynapseGrid collaborative agents (auto-installs OpenCode + zellij/tmux)
 
 If enabled, `acfm init` also auto-installs the optional SynapseGrid MCP server into detected assistants.
 
@@ -130,7 +130,7 @@ Some assistants include bundled companions automatically:
 
 ### Collaborative Agents (Optional)
 
-SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in tmux panes:
+SynapseGrid is an optional collaborative runtime that coordinates 4 OpenCode-backed roles in multiplexer panes (zellij preferred, tmux fallback):
 - planner
 - critic
 - coder
@@ -140,34 +140,60 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 
 | Command | Description |
 |---|---|
-| `acfm agents setup` | Install optional dependencies (`opencode` and `tmux`) |
-| `acfm agents doctor` | Validate OpenCode/tmux/model preflight before start |
+| `acfm agents setup` | Install optional dependencies (`opencode` and `zellij`/`tmux`) |
+| `acfm agents doctor` | Validate OpenCode/multiplexer/model preflight before start |
 | `acfm agents install-mcps` | Install SynapseGrid MCP server for detected assistants |
 | `acfm agents uninstall-mcps` | Remove SynapseGrid MCP server from assistants |
 | `acfm agents start --task "..." --model-coder provider/model` | Start session with optional per-role models |
+| `acfm agents start --task "..." --mux zellij` | Start session forcing zellij backend (`auto`/`tmux` also supported) |
+| `acfm agents runtime get` | Show configured multiplexer backend (`auto`, `zellij`, `tmux`) |
+| `acfm agents runtime set zellij` | Persist preferred multiplexer backend |
 | `acfm agents resume` | Resume a previous session and recreate workers if needed |
 | `acfm agents list` | List recent SynapseGrid sessions |
-| `acfm agents attach` | Attach directly to the SynapseGrid tmux session |
-| `acfm agents live` | Attach to full live tmux view (all agents) |
+| `acfm agents attach` | Attach directly to the active SynapseGrid multiplexer session |
+| `acfm agents live` | Attach to full live multiplexer view (all agents) |
 | `acfm agents logs` | Show recent worker logs (all roles or one role) |
+| `acfm agents transcript --role all --limit 40` | Show captured cross-agent transcript |
+| `acfm agents summary` | Show generated collaboration meeting summary |
 | `acfm agents export --format md --out file.md` | Export transcript in Markdown or JSON |
 | `acfm agents send "..."` | Send a new user message into the active session |
 | `acfm agents status` | Show current collaborative session state |
+| `acfm agents model list` | List available models grouped by provider |
+| `acfm agents model choose` | Interactively pick provider/model and save target role |
 | `acfm agents model get` | Show default model config (global and per-role) |
 | `acfm agents model set --role coder provider/model` | Persist a default model for one role |
 | `acfm agents model clear --role all` | Clear persisted model defaults |
 | `acfm agents stop` | Stop the active collaborative session |
 
+### MCP collaborative run mode (recommended)
+
+When driving SynapseGrid from another agent via MCP, prefer asynchronous run tools over role-by-role stepping:
+
+- `collab_start_session` to initialize session and optional zellij/tmux workers
+- `collab_invoke_team` to launch full 4-role collaboration run
+- `collab_wait_run` to wait for completion/failure with bounded timeout
+- `collab_get_result` to fetch final consolidated output and run diagnostics
+- `collab_cancel_run` to cancel a running collaboration safely
+
+`collab_step` remains available for manual/debug control, but is less robust for long tasks.
+
 ### SynapseGrid troubleshooting
 
 - If transcript entries show `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` to install dependencies and then retry.
 - Attach to worker panes with `acfm agents live` (or `acfm agents attach`) to see real-time role discussion.
 - Inspect worker errors quickly with `acfm agents logs --role all --lines 120`.
-- MCP starts can now create tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
-- Configure role models directly at start (for example `--model-planner`, `--model-coder`) or persist defaults via `acfm agents model set`.
-- Default SynapseGrid model fallback is `opencode/minimax-m2.5-free`.
+- Inspect collaborative discussion with `acfm agents transcript` and `acfm agents summary`.
+- MCP starts can now create zellij/tmux workers directly; if your assistant used headless steps before, start a new session and ensure worker spawning is enabled.
+- Configure role models directly at start (for example `--model-planner`, `--model-coder`) or persist defaults via `acfm agents model choose` / `acfm agents model set`.
+- Default SynapseGrid model fallback is `opencode/mimo-v2-pro-free`.
 - Run `acfm agents doctor` when panes look idle to confirm model/provider preflight health.
 
+Each collaborative session now keeps human-readable artifacts under `~/.acfm/synapsegrid/<sessionId>/`:
+- `transcript.jsonl`: full chronological message stream
+- `turns/*.json`: one file per round/role turn with captured output metadata
+- `meeting-log.md`: incremental meeting notes generated per turn
+- `meeting-summary.md`: final consolidated summary (roles, decisions, open issues, risks, action items)
+
 ### Spec Workflow
 
 | Command | Description |

package/package.json

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

package/src/agents/collab-summary.js

@@ -0,0 +1,120 @@
+export function summarizeText(text, maxLen = 700) {
+  if (typeof text !== 'string') return '';
+  const normalized = text.replace(/\r\n/g, '\n').trim();
+  if (!normalized) return '';
+  if (normalized.length <= maxLen) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxLen - 3)).trimEnd()}...`;
+}
+
+export function extractBulletLines(text, limit = 5) {
+  if (typeof text !== 'string') return [];
+  const bullets = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /^[-*]\s+/.test(line) || /^\d+\)\s+/.test(line));
+  return bullets.slice(0, Math.max(0, limit));
+}
+
+export function createTurnRecord({ round, role, model, content, events }) {
+  const snippet = summarizeText(content, 1000);
+  const keyPoints = extractBulletLines(content, 6);
+  return {
+    round,
+    role,
+    model: model || null,
+    timestamp: new Date().toISOString(),
+    snippet,
+    keyPoints,
+    eventCount: Array.isArray(events) ? events.length : 0,
+  };
+}
+
+export function updateSharedContext(prev, turn) {
+  const base = prev && typeof prev === 'object'
+    ? prev
+    : { decisions: [], openIssues: [], risks: [], actionItems: [], notes: [] };
+
+  const next = {
+    decisions: [...(base.decisions || [])],
+    openIssues: [...(base.openIssues || [])],
+    risks: [...(base.risks || [])],
+    actionItems: [...(base.actionItems || [])],
+    notes: [...(base.notes || [])],
+  };
+
+  const summary = summarizeText(turn?.snippet || turn?.content || '', 300);
+  if (summary) {
+    next.notes.push(`[r${turn.round}] ${turn.role}: ${summary}`);
+  }
+
+  const lines = String(turn?.snippet || turn?.content || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    if (lower.includes('risk') || lower.includes('failure') || lower.includes('blind spot')) {
+      next.risks.push(`[r${turn.round}] ${turn.role}: ${line}`);
+    }
+    if (lower.includes('open issue') || lower.includes('blocker') || lower.includes('unresolved')) {
+      next.openIssues.push(`[r${turn.round}] ${turn.role}: ${line}`);
+    }
+    if (lower.includes('action') || lower.includes('next step') || lower.includes('implement')) {
+      next.actionItems.push(`[r${turn.round}] ${turn.role}: ${line}`);
+    }
+    if (lower.includes('decision') || lower.includes('agreed') || lower.includes('approve')) {
+      next.decisions.push(`[r${turn.round}] ${turn.role}: ${line}`);
+    }
+  }
+
+  const dedupe = (arr) => [...new Set(arr)].slice(-30);
+  return {
+    decisions: dedupe(next.decisions),
+    openIssues: dedupe(next.openIssues),
+    risks: dedupe(next.risks),
+    actionItems: dedupe(next.actionItems),
+    notes: dedupe(next.notes),
+  };
+}
+
+export function buildMeetingSummary(messages = [], run = null, sharedContext = null) {
+  const byRole = new Map();
+  for (const msg of messages) {
+    if (!msg?.from || msg.from === 'user') continue;
+    if (!byRole.has(msg.from)) byRole.set(msg.from, []);
+    byRole.get(msg.from).push(msg.content || '');
+  }
+
+  const roles = ['planner', 'critic', 'coder', 'reviewer'];
+  const lines = [];
+  lines.push('# SynapseGrid Meeting Summary');
+  if (run?.runId) lines.push(`Run: ${run.runId}`);
+  if (run?.status) lines.push(`Status: ${run.status}`);
+  lines.push('');
+  lines.push('## Per-role recap');
+
+  for (const role of roles) {
+    const items = byRole.get(role) || [];
+    const last = items.length > 0 ? items[items.length - 1] : '';
+    lines.push(`- ${role}: ${summarizeText(last, 500) || '(no contribution captured)'}`);
+  }
+
+  const ctx = sharedContext && typeof sharedContext === 'object' ? sharedContext : null;
+  if (ctx) {
+    lines.push('');
+    lines.push('## Decisions');
+    for (const entry of (ctx.decisions || []).slice(-8)) lines.push(`- ${entry}`);
+    lines.push('');
+    lines.push('## Open issues');
+    for (const entry of (ctx.openIssues || []).slice(-8)) lines.push(`- ${entry}`);
+    lines.push('');
+    lines.push('## Risks');
+    for (const entry of (ctx.risks || []).slice(-8)) lines.push(`- ${entry}`);
+    lines.push('');
+    lines.push('## Action items');
+    for (const entry of (ctx.actionItems || []).slice(-8)) lines.push(`- ${entry}`);
+  }
+
+  return lines.join('\n').trim() + '\n';
+}

package/src/agents/config-store.js

@@ -10,10 +10,13 @@ const CONFIG_PATH = join(ACFM_DIR, 'config.json');
 
 function normalizeConfig(raw) {
   const agents = raw?.agents && typeof raw.agents === 'object' ? raw.agents : {};
+  const configuredMultiplexer = typeof agents.multiplexer === 'string' ? agents.multiplexer.trim().toLowerCase() : '';
+  const multiplexer = ['auto', 'zellij', 'tmux'].includes(configuredMultiplexer) ? configuredMultiplexer : 'auto';
   return {
     agents: {
       defaultModel: normalizeModelId(agents.defaultModel) || DEFAULT_SYNAPSE_MODEL,
       defaultRoleModels: sanitizeRoleModels(agents.defaultRoleModels),
+      multiplexer,
     },
   };
 }

package/src/agents/constants.js

@@ -4,6 +4,8 @@ import { join } from 'node:path';
 export const COLLAB_SYSTEM_NAME = 'SynapseGrid';
 export const COLLAB_ROLES = ['planner', 'critic', 'coder', 'reviewer'];
 export const DEFAULT_MAX_ROUNDS = 3;
-export const DEFAULT_SYNAPSE_MODEL = 'opencode/minimax-m2.5-free';
+export const DEFAULT_SYNAPSE_MODEL = 'opencode/mimo-v2-pro-free';
+export const DEFAULT_ROLE_TIMEOUT_MS = 180000;
+export const DEFAULT_ROLE_RETRIES = 1;
 export const SESSION_ROOT_DIR = join(homedir(), '.acfm', 'synapsegrid');
 export const CURRENT_SESSION_FILE = join(SESSION_ROOT_DIR, 'current-session.json');

package/src/agents/opencode-client.js

@@ -42,7 +42,24 @@ function parseOpenCodeRunOutput(stdout) {
   return stdout.trim();
 }
 
-export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs = 180000, binaryPath }) {
+function parseOpenCodeEvents(stdout) {
+  const lines = stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // ignore malformed event lines
+    }
+  }
+  return events;
+}
+
+export async function runOpenCodePromptDetailed({ prompt, cwd, model, agent, timeoutMs = 180000, binaryPath }) {
   const binary = binaryPath || process.env.ACFM_OPENCODE_BIN || 'opencode';
   const args = ['run', '--format', 'json'];
   if (model) {
@@ -97,9 +114,88 @@ export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs =
     });
   });
 
-  const parsed = parseOpenCodeRunOutput(stdout);
-  if (!parsed && stderr?.trim()) {
-    return stderr.trim();
+  const text = parseOpenCodeRunOutput(stdout);
+  const events = parseOpenCodeEvents(stdout);
+
+  return {
+    text: text || (stderr?.trim() || ''),
+    stdout,
+    stderr,
+    events,
+  };
+}
+
+export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs = 180000, binaryPath }) {
+  const detailed = await runOpenCodePromptDetailed({
+    prompt,
+    cwd,
+    model,
+    agent,
+    timeoutMs,
+    binaryPath,
+  });
+  return detailed.text;
+}
+
+export async function listOpenCodeModels({ provider = null, binaryPath, refresh = false, timeoutMs = 45000 }) {
+  const binary = binaryPath || process.env.ACFM_OPENCODE_BIN || 'opencode';
+  const args = ['models'];
+  if (provider) {
+    args.push(provider);
+  }
+  if (refresh) {
+    args.push('--refresh');
   }
-  return parsed;
+
+  const stdout = await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(binary, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let out = '';
+    let err = '';
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 1500).unref();
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      out += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      err += chunk.toString();
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      rejectPromise(error);
+    });
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        rejectPromise(new Error(`opencode models timed out after ${timeoutMs}ms`));
+        return;
+      }
+      if (code !== 0) {
+        const details = [err.trim(), out.trim()].filter(Boolean).join(' | ');
+        rejectPromise(new Error(details || `opencode models exited with code ${code}${signal ? ` (${signal})` : ''}`));
+        return;
+      }
+      resolvePromise(out);
+    });
+  });
+
+  const models = stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => line.includes('/'));
+
+  return [...new Set(models)].sort((a, b) => a.localeCompare(b));
 }