ac-framework 1.9.7 → 1.9.8

package/README.md

@@ -150,24 +150,47 @@ 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`.
-- Default SynapseGrid model fallback is `opencode/minimax-m2.5-free`.
+- 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.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/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));
 }

package/src/agents/orchestrator.js

@@ -1,12 +1,21 @@
 import { buildAgentPrompt, ROLE_SYSTEM_PROMPTS } from './role-prompts.js';
-import { runOpenCodePrompt } from './opencode-client.js';
+import { runOpenCodePromptDetailed } from './opencode-client.js';
 import { nextRole, shouldStop } from './scheduler.js';
 import { resolveRoleModel } from './model-selection.js';
+import { buildMeetingSummary, createTurnRecord, updateSharedContext } from './collab-summary.js';
+import {
+  appendRunEvent,
+  extractFinalSummary,
+  incrementRoleRetry,
+  roleRetryCount,
+} from './run-state.js';
 import {
   addAgentMessage,
+  appendMeetingTurn,
   loadSessionState,
   saveSessionState,
   stopSession,
+  writeMeetingSummary,
   withSessionLock,
 } from './state-store.js';
 
@@ -17,11 +26,115 @@ function buildRuntimePrompt({ state, role }) {
     task: state.task,
     round: state.round,
     messages: state.messages,
+    sharedContext: state.run?.sharedContext || null,
   });
 
   return [roleContext, '', collaborativePrompt].join('\n');
 }
 
+function ensureRunState(state) {
+  if (state.run && typeof state.run === 'object') {
+    return {
+      ...state.run,
+      sharedContext: state.run.sharedContext && typeof state.run.sharedContext === 'object'
+        ? {
+            decisions: Array.isArray(state.run.sharedContext.decisions) ? state.run.sharedContext.decisions : [],
+            openIssues: Array.isArray(state.run.sharedContext.openIssues) ? state.run.sharedContext.openIssues : [],
+            risks: Array.isArray(state.run.sharedContext.risks) ? state.run.sharedContext.risks : [],
+            actionItems: Array.isArray(state.run.sharedContext.actionItems) ? state.run.sharedContext.actionItems : [],
+            notes: Array.isArray(state.run.sharedContext.notes) ? state.run.sharedContext.notes : [],
+          }
+        : {
+            decisions: [],
+            openIssues: [],
+            risks: [],
+            actionItems: [],
+            notes: [],
+          },
+    };
+  }
+  return {
+    runId: null,
+    status: 'idle',
+    startedAt: null,
+    finishedAt: null,
+    currentRole: null,
+    retriesUsed: {},
+    round: state.round || 1,
+    events: [],
+    finalSummary: null,
+    lastError: null,
+    policy: {
+      timeoutPerRoleMs: 180000,
+      retryOnTimeout: 1,
+      fallbackOnFailure: 'abort',
+      maxRounds: state.maxRounds,
+    },
+  };
+}
+
+function applyRoleFailurePolicy(state, role, errorMessage) {
+  let run = ensureRunState(state);
+  const policy = run.policy || {};
+  const currentRetries = roleRetryCount(run, role);
+  const canRetry = currentRetries < (policy.retryOnTimeout ?? 0);
+
+  run = appendRunEvent(run, 'role_failed', {
+    role,
+    retry: canRetry,
+    error: errorMessage,
+  });
+
+  if (canRetry) {
+    run = incrementRoleRetry(run, role);
+    return {
+      ...state,
+      run: {
+        ...run,
+        currentRole: role,
+        status: 'running',
+        lastError: null,
+      },
+      activeAgent: null,
+      // retry same role by rewinding index
+      nextRoleIndex: state.roles.indexOf(role),
+    };
+  }
+
+  const fallback = policy.fallbackOnFailure || 'abort';
+  if (fallback === 'skip') {
+    const skipped = appendRunEvent(run, 'role_skipped', { role, error: errorMessage });
+    return {
+      ...state,
+      run: {
+        ...skipped,
+        currentRole: null,
+        status: 'running',
+        lastError: null,
+      },
+      activeAgent: null,
+    };
+  }
+
+  const failed = appendRunEvent(run, 'run_failed', { role, error: errorMessage });
+  return {
+    ...state,
+    status: 'failed',
+    activeAgent: null,
+    run: {
+      ...failed,
+      status: 'failed',
+      currentRole: null,
+      finishedAt: new Date().toISOString(),
+      lastError: {
+        code: 'ROLE_FAILURE',
+        message: errorMessage,
+        role,
+      },
+    },
+  };
+}
+
 export async function runTurn(sessionId, options = {}) {
   return withSessionLock(sessionId, async () => {
     let state = await loadSessionState(sessionId);
@@ -44,7 +157,7 @@ export async function runTurn(sessionId, options = {}) {
     let content;
     try {
       const effectiveModel = resolveRoleModel(state, scheduled.role, options.model);
-      content = await runOpenCodePrompt({
+      const output = await runOpenCodePromptDetailed({
         prompt,
         cwd: options.cwd || process.cwd(),
         model: effectiveModel,
@@ -52,6 +165,7 @@ export async function runTurn(sessionId, options = {}) {
         binaryPath: options.opencodeBin,
         timeoutMs: options.timeoutMs,
       });
+      content = output.text;
     } catch (error) {
       content = `Agent failed: ${error.message}`;
     }
@@ -109,7 +223,7 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
     let content;
     try {
       const effectiveModel = resolveRoleModel(state, role, options.model);
-      content = await runOpenCodePrompt({
+      const output = await runOpenCodePromptDetailed({
         prompt,
         cwd: options.cwd || process.cwd(),
         model: effectiveModel,
@@ -117,6 +231,7 @@ export async function executeActiveTurn(sessionId, role, options = {}) {
         binaryPath: options.opencodeBin,
         timeoutMs: options.timeoutMs,
       });
+      content = output.text;
     } catch (error) {
       content = `Agent failed: ${error.message}`;
     }
@@ -141,13 +256,33 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
     if (state.status !== 'running') return state;
     if (!state.roles.includes(role)) return state;
 
+    const run = ensureRunState(state);
+    if (run.status === 'cancelled' || run.status === 'failed' || run.status === 'completed') {
+      return state;
+    }
+
     if (!state.activeAgent) {
       const scheduled = nextRole(state);
+      const startedRun = run.status === 'idle'
+        ? appendRunEvent({
+          ...run,
+          status: 'running',
+          startedAt: new Date().toISOString(),
+          currentRole: scheduled.role,
+          round: scheduled.round,
+        }, 'run_started', { round: scheduled.round })
+        : appendRunEvent({
+          ...run,
+          currentRole: scheduled.role,
+          round: scheduled.round,
+        }, 'role_scheduled', { role: scheduled.role, round: scheduled.round });
+
       state = await saveSessionState({
         ...state,
         activeAgent: scheduled.role,
         nextRoleIndex: scheduled.nextRoleIndex,
         round: scheduled.round,
+        run: startedRun,
       });
     }
 
@@ -157,28 +292,86 @@ export async function runWorkerIteration(sessionId, role, options = {}) {
 
     const prompt = buildRuntimePrompt({ state, role });
     let content;
+    let outputEvents = [];
+    let effectiveModel = null;
+    let failed = false;
+    let errorMessage = '';
     try {
-      const effectiveModel = resolveRoleModel(state, role, options.model);
-      content = await runOpenCodePrompt({
+      effectiveModel = resolveRoleModel(state, role, options.model);
+      state = await saveSessionState({
+        ...state,
+        run: appendRunEvent({
+          ...ensureRunState(state),
+          currentRole: role,
+          status: 'running',
+        }, 'role_started', { role, model: effectiveModel }),
+      });
+      const output = await runOpenCodePromptDetailed({
         prompt,
         cwd: options.cwd || process.cwd(),
         model: effectiveModel,
         agent: options.agent,
         binaryPath: options.opencodeBin,
-        timeoutMs: options.timeoutMs,
+        timeoutMs: options.timeoutMs || ensureRunState(state).policy?.timeoutPerRoleMs || 180000,
       });
+      content = output.text;
+      outputEvents = output.events || [];
     } catch (error) {
+      failed = true;
+      errorMessage = error.message;
       content = `Agent failed: ${error.message}`;
     }
 
     state = await addAgentMessage(state, role, content);
+    if (failed) {
+      await appendMeetingTurn(sessionId, createTurnRecord({
+        round: state.round,
+        role,
+        model: effectiveModel,
+        content,
+        events: outputEvents,
+      }));
+      state = await saveSessionState(applyRoleFailurePolicy(state, role, errorMessage));
+      return state;
+    }
+
+    const turnRecord = createTurnRecord({
+      round: state.round,
+      role,
+      model: effectiveModel,
+      content,
+      events: outputEvents,
+    });
+    await appendMeetingTurn(sessionId, turnRecord);
+
+    const updatedShared = updateSharedContext(ensureRunState(state).sharedContext, turnRecord);
+    const succeededRun = appendRunEvent({
+      ...ensureRunState(state),
+      currentRole: null,
+      lastError: null,
+      sharedContext: updatedShared,
+    }, 'role_succeeded', { role, chars: content.length, events: outputEvents.length });
+
     state = await saveSessionState({
       ...state,
       activeAgent: null,
+      run: succeededRun,
     });
 
     if (shouldStop(state)) {
       state = await stopSession(state, 'completed');
+      const summaryMd = buildMeetingSummary(state.messages, ensureRunState(state), ensureRunState(state).sharedContext);
+      await writeMeetingSummary(sessionId, summaryMd);
+      const finalRun = appendRunEvent({
+        ...ensureRunState(state),
+        status: 'completed',
+        finishedAt: new Date().toISOString(),
+        finalSummary: extractFinalSummary(state.messages, ensureRunState(state)),
+      }, 'run_completed', { round: state.round });
+      state = await saveSessionState({
+        ...state,
+        run: finalRun,
+      });
     }
 
     return state;

package/src/agents/role-prompts.js

@@ -25,11 +25,41 @@ export const ROLE_SYSTEM_PROMPTS = {
   ].join(' '),
 };
 
-export function buildAgentPrompt({ role, task, round, messages, maxMessages = 24 }) {
+function formatSharedContext(sharedContext) {
+  if (!sharedContext || typeof sharedContext !== 'object') {
+    return 'No shared summary yet.';
+  }
+
+  const sections = [
+    ['Decisions', sharedContext.decisions],
+    ['Open issues', sharedContext.openIssues],
+    ['Risks', sharedContext.risks],
+    ['Action items', sharedContext.actionItems],
+    ['Notes', sharedContext.notes],
+  ];
+
+  const lines = [];
+  for (const [name, list] of sections) {
+    const items = Array.isArray(list) ? list.slice(-6) : [];
+    lines.push(`${name}:`);
+    if (items.length === 0) {
+      lines.push('- (none)');
+    } else {
+      for (const item of items) {
+        lines.push(`- ${item}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function buildAgentPrompt({ role, task, round, messages, sharedContext = null, maxMessages = 18 }) {
   const recent = messages.slice(-maxMessages);
   const transcript = recent.length
     ? recent.map((msg, idx) => `${idx + 1}. [${msg.from}] ${msg.content}`).join('\n')
     : 'No previous messages.';
+  const shared = formatSharedContext(sharedContext);
 
   return [
     `ROLE: ${role}`,
@@ -37,6 +67,9 @@ export function buildAgentPrompt({ role, task, round, messages, maxMessages = 24
     '',
     `TASK: ${task}`,
     '',
+    'SHARED CONTEXT SUMMARY:',
+    shared,
+    '',
     'TEAM TRANSCRIPT (latest first-order history):',
     transcript,
     '',