ac-framework 1.9.6 → 1.9.8

package/README.md

@@ -141,6 +141,7 @@ 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 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 |
@@ -149,21 +150,46 @@ Each role runs in turn against a shared, accumulating context so outputs from on
 | `acfm agents attach` | Attach directly to the SynapseGrid tmux session |
 | `acfm agents live` | Attach to full live tmux 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 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`.
+- Inspect collaborative discussion with `acfm agents transcript` and `acfm agents summary`.
 - 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`.
+- 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-framework",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "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

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { DEFAULT_SYNAPSE_MODEL } from './constants.js';
 import { sanitizeRoleModels, normalizeModelId } from './model-selection.js';
 
 const ACFM_DIR = join(homedir(), '.acfm');
@@ -11,7 +12,7 @@ function normalizeConfig(raw) {
   const agents = raw?.agents && typeof raw.agents === 'object' ? raw.agents : {};
   return {
     agents: {
-      defaultModel: normalizeModelId(agents.defaultModel) || null,
+      defaultModel: normalizeModelId(agents.defaultModel) || DEFAULT_SYNAPSE_MODEL,
       defaultRoleModels: sanitizeRoleModels(agents.defaultRoleModels),
     },
   };

package/src/agents/constants.js

@@ -4,5 +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/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

@@ -1,9 +1,29 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-
-const execFileAsync = promisify(execFile);
+import { spawn } from 'node:child_process';
 
 function parseOpenCodeRunOutput(stdout) {
+  const ndjsonLines = stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  if (ndjsonLines.length > 0) {
+    const textChunks = [];
+    for (const line of ndjsonLines) {
+      try {
+        const event = JSON.parse(line);
+        const text = event?.part?.text;
+        if (typeof text === 'string' && text.trim()) {
+          textChunks.push(text.trim());
+        }
+      } catch {
+        // ignore malformed lines and continue
+      }
+    }
+    if (textChunks.length > 0) {
+      return textChunks.join('\n\n');
+    }
+  }
+
   try {
     const parsed = JSON.parse(stdout);
     if (Array.isArray(parsed)) {
@@ -22,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) {
@@ -33,15 +70,132 @@ export async function runOpenCodePrompt({ prompt, cwd, model, agent, timeoutMs =
   }
   args.push('--', prompt);
 
-  const { stdout, stderr } = await execFileAsync(binary, args, {
+  const { stdout, stderr } = await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(binary, args, {
+      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 timed out after ${timeoutMs}ms`));
+        return;
+      }
+      if (code !== 0) {
+        const details = [err.trim(), out.trim()].filter(Boolean).join(' | ');
+        rejectPromise(new Error(details || `opencode exited with code ${code}${signal ? ` (${signal})` : ''}`));
+        return;
+      }
+      resolvePromise({ stdout: out, stderr: err });
+    });
+  });
+
+  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,
-    timeout: timeoutMs,
-    maxBuffer: 10 * 1024 * 1024,
+    model,
+    agent,
+    timeoutMs,
+    binaryPath,
   });
+  return detailed.text;
+}
 
-  const parsed = parseOpenCodeRunOutput(stdout);
-  if (!parsed && stderr?.trim()) {
-    return stderr.trim();
+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);
   }
-  return parsed;
+  if (refresh) {
+    args.push('--refresh');
+  }
+
+  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));
 }