ac-framework 1.9.4 → 1.9.5

package/framework/new_project/.opencode/command/ac.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/framework/new_project/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/framework/web_development/.opencode/command/ac.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/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.5",
   "description": "Agentic Coding Framework - Multi-assistant configuration system with OpenSpec workflows",
   "main": "src/index.js",
   "exports": {

package/src/commands/agents.js

@@ -163,18 +163,87 @@ export function agentsCommand() {
     .command('setup')
     .description('Install optional collaboration dependencies (OpenCode + tmux)')
     .option('--json', 'Output as JSON')
-    .action((opts) => {
+    .action(async (opts) => {
       const result = ensureCollabDependencies();
-      output(result, opts.json);
+      let collabMcp = null;
+
+      if (result.success) {
+        const { detectAndInstallMCPs } = await import('../services/mcp-installer.js');
+        collabMcp = detectAndInstallMCPs({ target: 'collab' });
+      }
+
+      const payload = { ...result, collabMcp };
+      output(payload, opts.json);
       if (!opts.json) {
         const oLabel = result.opencode.success ? chalk.green('ok') : chalk.red('failed');
         const tLabel = result.tmux.success ? chalk.green('ok') : chalk.red('failed');
         console.log(`OpenCode: ${oLabel} - ${result.opencode.message}`);
         console.log(`tmux:     ${tLabel} - ${result.tmux.message}`);
+        if (collabMcp) {
+          console.log(`Collab MCP: ${chalk.green('ok')} - installed ${collabMcp.success}/${collabMcp.installed} on detected assistants`);
+        }
       }
       if (!result.success) process.exit(1);
     });
 
+  agents
+    .command('install-mcps')
+    .description('Install SynapseGrid MCP server into detected AI assistants')
+    .option('--all', 'Install for all supported assistants, without detection', false)
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const { detectAndInstallMCPs, installAllMCPs, ASSISTANTS, isAssistantInstalled } = await import('../services/mcp-installer.js');
+        const result = opts.all
+          ? installAllMCPs({ target: 'collab' })
+          : detectAndInstallMCPs({ target: 'collab' });
+
+        output({ total: result.total ?? result.installed, success: result.success, target: 'collab' }, opts.json);
+
+        if (!opts.json) {
+          if (!opts.all) {
+            if (result.installed === 0) {
+              console.log(chalk.yellow('No AI assistants detected.'));
+              console.log(chalk.dim('Use --all to install for all supported assistants.'));
+              return;
+            }
+            for (const assistant of ASSISTANTS) {
+              if (isAssistantInstalled(assistant)) {
+                console.log(
+                  chalk.hex('#00B894')('◆ ') + chalk.bold(assistant.name) +
+                  chalk.dim(` → ${assistant.configPath}`)
+                );
+              }
+            }
+          }
+          console.log(chalk.green(`\n✓ SynapseGrid MCP installed (${result.success}/${result.total ?? result.installed})`));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
+  agents
+    .command('uninstall-mcps')
+    .description('Uninstall SynapseGrid MCP server from detected AI assistants')
+    .option('--json', 'Output as JSON')
+    .action(async (opts) => {
+      try {
+        const { uninstallAllMCPs } = await import('../services/mcp-installer.js');
+        const result = uninstallAllMCPs({ target: 'collab' });
+        output({ success: result.success, target: 'collab' }, opts.json);
+        if (!opts.json) {
+          console.log(chalk.green(`✓ SynapseGrid MCP uninstalled (${result.success})`));
+        }
+      } catch (error) {
+        output({ error: error.message }, opts.json);
+        if (!opts.json) console.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+
   agents
     .command('list')
     .description('List SynapseGrid sessions from local storage')

package/src/commands/init.js

@@ -190,9 +190,41 @@ async function setupCollaborativeSystem() {
     return;
   }
 
+  async function installCollabMcpConnections() {
+    console.log();
+    console.log(chalk.hex('#B2BEC3')(`  Connecting ${COLLAB_SYSTEM_NAME} MCP tools to detected assistants...`));
+    console.log();
+
+    const { detectAndInstallMCPs, ASSISTANTS, isAssistantInstalled } = await import('../services/mcp-installer.js');
+    const { installed, success } = detectAndInstallMCPs({ target: 'collab' });
+
+    if (installed === 0) {
+      console.log(chalk.hex('#636E72')('  No AI assistants detected yet.'));
+      console.log(chalk.hex('#636E72')('  Run ') + chalk.hex('#DFE6E9')('acfm agents install-mcps') + chalk.hex('#636E72')(' after installing an assistant.'));
+      console.log();
+      return;
+    }
+
+    for (const assistant of ASSISTANTS) {
+      if (isAssistantInstalled(assistant)) {
+        console.log(
+          chalk.hex('#00B894')('  ◆ ') +
+          chalk.hex('#DFE6E9').bold(assistant.name) +
+          chalk.hex('#636E72')(` · MCP config → ${assistant.configPath}`)
+        );
+      }
+    }
+
+    console.log();
+    const successBadge = chalk.hex('#2D3436').bgHex('#00B894').bold(` ${success}/${installed} `);
+    console.log(`  ${successBadge} ${chalk.hex('#B2BEC3')(`${COLLAB_SYSTEM_NAME} MCP connections installed`)}`);
+    console.log();
+  }
+
   if (alreadyReady) {
     console.log();
     console.log(chalk.hex('#00B894')('  ◆ OpenCode and tmux are already available.'));
+    await installCollabMcpConnections();
     console.log(chalk.hex('#636E72')('  Run `acfm agents start --task "..."` to launch collaboration.'));
     console.log();
     return;
@@ -211,6 +243,7 @@ async function setupCollaborativeSystem() {
   console.log();
 
   if (result.success) {
+    await installCollabMcpConnections();
     console.log(chalk.hex('#00B894').bold(`  ${COLLAB_SYSTEM_NAME} is active.`));
     console.log(chalk.hex('#636E72')('  Run acfm agents start --task "..." to open the war-room.'));
   } else {

package/src/mcp/collab-server.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for AC Framework SynapseGrid Collaboration System
+ * Exposes collaborative multi-agent session controls via MCP.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { COLLAB_ROLES } from '../agents/constants.js';
+import { runWorkerIteration } from '../agents/orchestrator.js';
+import {
+  addUserMessage,
+  createSession,
+  loadCurrentSessionId,
+  loadSessionState,
+  loadTranscript,
+  saveSessionState,
+  setCurrentSession,
+  stopSession,
+} from '../agents/state-store.js';
+
+class MCPCollabServer {
+  constructor() {
+    this.server = new McpServer({
+      name: 'ac-framework-collab',
+      version: '1.0.0',
+    });
+
+    this.setupTools();
+  }
+
+  setupTools() {
+    this.server.tool(
+      'collab_start_session',
+      'Start a SynapseGrid collaborative session',
+      {
+        task: z.string().describe('Initial collaborative task'),
+        maxRounds: z.number().int().positive().default(3).describe('Maximum collaboration rounds'),
+        model: z.string().optional().describe('Model id (provider/model) for opencode run'),
+      },
+      async ({ task, maxRounds, model }) => {
+        try {
+          const state = await createSession(task, {
+            roles: COLLAB_ROLES,
+            maxRounds,
+            model: model || null,
+            workingDirectory: process.cwd(),
+          });
+          await setCurrentSession(state.sessionId);
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ success: true, sessionId: state.sessionId, status: state.status }, null, 2),
+            }],
+          };
+        } catch (error) {
+          return { content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+      }
+    );
+
+    this.server.tool(
+      'collab_send_message',
+      'Send a user message to the active collaborative session',
+      {
+        message: z.string().describe('User message to add to shared context'),
+        sessionId: z.string().optional().describe('Session ID (defaults to current session)'),
+      },
+      async ({ message, sessionId }) => {
+        try {
+          const id = sessionId || await loadCurrentSessionId();
+          if (!id) {
+            throw new Error('No active session found');
+          }
+          let state = await loadSessionState(id);
+          state = await addUserMessage(state, message);
+          state = await saveSessionState(state);
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ success: true, sessionId: id, messages: state.messages.length }, null, 2),
+            }],
+          };
+        } catch (error) {
+          return { content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+      }
+    );
+
+    this.server.tool(
+      'collab_step',
+      'Execute one collaborative worker turn by role',
+      {
+        role: z.enum(COLLAB_ROLES).describe('Role to execute for one step'),
+        sessionId: z.string().optional().describe('Session ID (defaults to current session)'),
+      },
+      async ({ role, sessionId }) => {
+        try {
+          const id = sessionId || await loadCurrentSessionId();
+          if (!id) {
+            throw new Error('No active session found');
+          }
+
+          const state = await runWorkerIteration(id, role, {
+            cwd: process.cwd(),
+          });
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: true,
+                sessionId: id,
+                status: state.status,
+                round: state.round,
+                activeAgent: state.activeAgent,
+                messageCount: state.messages.length,
+              }, null, 2),
+            }],
+          };
+        } catch (error) {
+          return { content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+      }
+    );
+
+    this.server.tool(
+      'collab_status',
+      'Get current collaborative session state',
+      {
+        sessionId: z.string().optional().describe('Session ID (defaults to current session)'),
+        includeTranscript: z.boolean().default(false).describe('Include transcript JSONL messages'),
+      },
+      async ({ sessionId, includeTranscript }) => {
+        try {
+          const id = sessionId || await loadCurrentSessionId();
+          if (!id) {
+            throw new Error('No active session found');
+          }
+          const state = await loadSessionState(id);
+          const transcript = includeTranscript ? await loadTranscript(id) : undefined;
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ state, transcript }, null, 2),
+            }],
+          };
+        } catch (error) {
+          return { content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+      }
+    );
+
+    this.server.tool(
+      'collab_stop_session',
+      'Stop current collaborative session',
+      {
+        sessionId: z.string().optional().describe('Session ID (defaults to current session)'),
+      },
+      async ({ sessionId }) => {
+        try {
+          const id = sessionId || await loadCurrentSessionId();
+          if (!id) {
+            throw new Error('No active session found');
+          }
+          const state = await loadSessionState(id);
+          const updated = await stopSession(state, 'stopped');
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ success: true, sessionId: id, status: updated.status }, null, 2),
+            }],
+          };
+        } catch (error) {
+          return { content: [{ type: 'text', text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+      }
+    );
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('AC Framework SynapseGrid MCP Server running on stdio');
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const server = new MCPCollabServer();
+  server.run().catch((error) => {
+    console.error('Failed to start SynapseGrid MCP server:', error);
+    process.exit(1);
+  });
+}
+
+export default MCPCollabServer;