copilot-flow 0.3.0

package/README.md

@@ -0,0 +1,300 @@
+# copilot-flow
+
+Multi-agent orchestration framework for **GitHub Copilot CLI** — inspired by [Ruflo (claude-flow)](https://github.com/ruvnet/claude-flow).
+
+copilot-flow brings the same multi-agent swarm patterns as Ruflo to the GitHub Copilot ecosystem, using the official [`@github/copilot-sdk`](https://github.com/github/copilot-sdk) to programmatically control the `copilot` CLI.
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 20
+- **GitHub Copilot CLI** (`copilot`) installed and authenticated
+- A GitHub account with Copilot access
+
+```bash
+# Install and authenticate Copilot CLI
+# Follow instructions at https://github.com/github/copilot
+copilot login
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g copilot-flow
+# or run without installing:
+npx copilot-flow <command>
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialise in your project
+copilot-flow init
+
+# 2. Run a single agent
+copilot-flow agent spawn --type coder --task "Write a REST API endpoint for user registration" --stream
+
+# 3. Run a multi-agent swarm
+copilot-flow swarm start --task "Build a JWT authentication module" --stream
+
+# 4. Check system health
+copilot-flow doctor
+```
+
+---
+
+## Commands
+
+### `init`
+Scaffold a `.copilot-flow/config.json` configuration file.
+
+```bash
+copilot-flow init
+copilot-flow init --model gpt-4o --topology hierarchical --max-agents 6
+```
+
+### `agent`
+
+```bash
+# Spawn an agent for a task (auto-routes to best agent type)
+copilot-flow agent spawn --task "Fix the authentication bug" --stream
+
+# Specify the agent type explicitly
+copilot-flow agent spawn --type security-auditor --task "Audit the auth module"
+
+# With custom retry settings
+copilot-flow agent spawn --type coder --task "..." \
+  --max-retries 5 \
+  --retry-delay 2000 \
+  --retry-strategy exponential
+
+# Disable retries entirely
+copilot-flow agent spawn --type coder --task "..." --no-retry
+
+# List agent states
+copilot-flow agent list
+copilot-flow agent types
+```
+
+### `swarm`
+
+```bash
+# Run a hierarchical swarm (researcher → coder → reviewer pipeline by default)
+copilot-flow swarm start --task "Implement OAuth2 login flow" --stream
+
+# Specify agent pipeline manually
+copilot-flow swarm start --task "..." --agents researcher,coder,tester,reviewer
+
+# Choose topology
+copilot-flow swarm start --task "..." --topology mesh
+copilot-flow swarm start --task "..." --topology sequential
+
+# Configure swarm defaults
+copilot-flow swarm init --topology hierarchical --max-agents 8
+copilot-flow swarm status
+```
+
+### `memory`
+
+```bash
+copilot-flow memory store --namespace project --key architecture --value "microservices"
+copilot-flow memory retrieve --namespace project --key architecture
+copilot-flow memory search --namespace project --query "auth"
+copilot-flow memory list --namespace project
+copilot-flow memory delete --namespace project --key architecture
+copilot-flow memory clear --namespace project
+
+# With TTL (entry expires after 1 hour)
+copilot-flow memory store --namespace project --key temp --value "..." --ttl 3600000
+```
+
+### `hooks`
+
+```bash
+copilot-flow hooks fire pre-task --data '{"task":"implement login"}'
+copilot-flow hooks fire post-task --data '{"success":true}'
+copilot-flow hooks pre-task
+copilot-flow hooks post-task
+copilot-flow hooks session-start
+copilot-flow hooks session-end
+copilot-flow hooks list
+```
+
+### `route`
+
+```bash
+# Find the best agent type for a task
+copilot-flow route task --task "Fix a null pointer exception in authentication"
+# → suggests: debugger
+
+copilot-flow route list-agents
+```
+
+### `status` / `doctor`
+
+```bash
+copilot-flow status
+copilot-flow doctor
+```
+
+---
+
+## Retry System
+
+Every command that makes Copilot API calls supports configurable retry with multiple backoff strategies:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-retries <n>` | 3 | Maximum retry attempts |
+| `--retry-delay <ms>` | 1000 | Initial delay before first retry |
+| `--retry-strategy <type>` | `exponential` | `exponential` \| `linear` \| `constant` \| `fibonacci` |
+| `--no-retry` | — | Disable retries entirely |
+
+**Backoff strategies:**
+- `exponential`: `delay = initialDelay × 2^(attempt-1)` — doubles each time
+- `linear`: `delay = initialDelay × attempt` — grows linearly
+- `constant`: `delay = initialDelay` — fixed interval
+- `fibonacci`: `delay = initialDelay × fib(attempt)` — Fibonacci sequence
+
+All strategies apply ±10% jitter by default to prevent thundering herd.
+
+**Retried automatically:** network errors (`ECONNRESET`, `ETIMEDOUT`), rate limits (429), server errors (5xx), session crashes, timeouts.
+
+**Not retried:** authentication errors (401), authorization errors (403), not found (404), validation errors.
+
+---
+
+## Agent Types
+
+| Agent | Best For |
+|-------|---------|
+| `coder` | Implementation, refactoring |
+| `researcher` | Investigation, information gathering |
+| `tester` | Unit/integration tests, TDD |
+| `reviewer` | Code review, quality analysis |
+| `architect` | System design, architecture decisions |
+| `coordinator` | Multi-agent workflow decomposition |
+| `analyst` | Requirements, specifications |
+| `debugger` | Bug diagnosis, root cause analysis |
+| `documenter` | README, API docs, inline comments |
+| `optimizer` | Performance, memory efficiency |
+| `security-auditor` | Vulnerability scanning, OWASP |
+| `performance-engineer` | Benchmarking, scalability |
+
+If you don't specify `--type`, copilot-flow automatically routes based on keywords in your task description.
+
+---
+
+## Swarm Topologies
+
+| Topology | Behaviour |
+|----------|-----------|
+| `hierarchical` | Independent tasks run in parallel; tasks with dependencies wait. Best for most workloads. |
+| `mesh` | All tasks run concurrently with shared memory. Best for independent parallel work. |
+| `sequential` | Tasks run one at a time in order. Best for strictly ordered pipelines. |
+
+---
+
+## Programmatic API
+
+```typescript
+import {
+  runAgentTask,
+  runSwarm,
+  withRetry,
+  RetryPredicates,
+  getMemoryStore,
+  globalHooks,
+} from 'copilot-flow';
+
+// Run a single agent
+const result = await runAgentTask('coder', 'Write a binary search function', {
+  retryConfig: {
+    maxAttempts: 3,
+    backoffStrategy: 'exponential',
+    onRetry: (err, attempt) => console.log(`Retry ${attempt}: ${err.message}`),
+  },
+  onChunk: chunk => process.stdout.write(chunk),
+});
+
+// Run a swarm
+const results = await runSwarm([
+  { id: 'research', agentType: 'researcher', prompt: 'Research OAuth2 best practices' },
+  { id: 'implement', agentType: 'coder', prompt: 'Implement OAuth2 login', dependsOn: ['research'] },
+  { id: 'test', agentType: 'tester', prompt: 'Write tests for OAuth2 flow', dependsOn: ['implement'] },
+], 'hierarchical');
+
+// Use memory between runs
+const mem = getMemoryStore();
+mem.store('project', 'context', 'e-commerce platform with React + Node.js');
+
+// Register hooks
+globalHooks.on('post-task', async ctx => {
+  console.log('Task completed:', ctx.data);
+});
+
+// Use retry directly
+const result2 = await withRetry(
+  () => fetch('https://api.example.com/data').then(r => r.json()),
+  { maxAttempts: 5, backoffStrategy: 'fibonacci', retryOn: RetryPredicates.networkErrors }
+);
+```
+
+---
+
+## Configuration
+
+`.copilot-flow/config.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "defaultModel": "gpt-4o",
+  "swarm": {
+    "topology": "hierarchical",
+    "maxAgents": 8
+  },
+  "memory": {
+    "backend": "sqlite",
+    "path": ".copilot-flow/memory.db"
+  },
+  "retry": {
+    "maxAttempts": 3,
+    "initialDelayMs": 1000,
+    "maxDelayMs": 30000,
+    "backoffStrategy": "exponential",
+    "multiplier": 2,
+    "jitter": true
+  },
+  "hooks": {
+    "enabled": true,
+    "timeoutMs": 5000
+  }
+}
+```
+
+Environment variable overrides:
+```bash
+GITHUB_TOKEN=ghp_...          # GitHub token (uses logged-in user by default)
+COPILOT_FLOW_DEFAULT_MODEL=gpt-4o
+COPILOT_FLOW_MAX_RETRIES=3
+COPILOT_FLOW_RETRY_DELAY_MS=1000
+COPILOT_FLOW_LOG_LEVEL=info   # debug | info | warn | error | silent
+```
+
+---
+
+## Attribution
+
+> copilot-flow is inspired by **[Ruflo (claude-flow)](https://github.com/ruvnet/claude-flow)** — the multi-agent orchestration framework for Claude. copilot-flow brings the same swarm coordination patterns, memory system, hooks, and retry engine to the GitHub Copilot ecosystem using the official `@github/copilot-sdk`.
+
+---
+
+## License
+
+MIT

package/bin/copilot-flow.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+require('dotenv/config');
+
+// Register ts-node for development (no-op in production with compiled dist/)
+try {
+  require('../dist/commands/index.js');
+} catch {
+  // Fallback to ts-node in dev
+  require('ts-node/register');
+  require('../src/commands/index.ts');
+}

package/dist/agents/executor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent executor — creates a Copilot session for an agent type and runs a task,
+ * wrapping everything with retry logic and streaming support.
+ */
+import type { AgentType, AgentResult } from '../types.js';
+import type { RetryConfig } from '../core/retry.js';
+export type { AgentType, AgentResult };
+export interface RunTaskOptions {
+    /** Override the model from the agent registry. */
+    model?: string;
+    /** Session timeout in ms. Default: 120_000 (2 minutes). */
+    timeoutMs?: number;
+    /** Retry configuration override. */
+    retryConfig?: Partial<RetryConfig>;
+    /** Called with each streamed text delta (for live output). */
+    onChunk?: (text: string) => void;
+}
+/**
+ * Run a task using a specific agent type.
+ * Creates a fresh Copilot session, sends the prompt, collects the response,
+ * and disconnects. Retries on transient failures.
+ */
+export declare function runAgentTask(agentType: AgentType, task: string, options?: RunTaskOptions): Promise<AgentResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/agents/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/agents/executor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAmFtB"}

package/dist/agents/executor.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Agent executor — creates a Copilot session for an agent type and runs a task,
+ * wrapping everything with retry logic and streaming support.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgentTask = runAgentTask;
+const copilot_sdk_1 = require("@github/copilot-sdk");
+const client_manager_js_1 = require("../core/client-manager.js");
+const retry_js_1 = require("../core/retry.js");
+const error_handler_js_1 = require("../core/error-handler.js");
+const output_js_1 = require("../output.js");
+const registry_js_1 = require("./registry.js");
+/**
+ * Run a task using a specific agent type.
+ * Creates a fresh Copilot session, sends the prompt, collects the response,
+ * and disconnects. Retries on transient failures.
+ */
+async function runAgentTask(agentType, task, options = {}) {
+    const def = (0, registry_js_1.getAgentDefinition)(agentType);
+    const model = options.model ?? def.model;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    const startTime = Date.now();
+    let attempts = 0;
+    const onRetry = (err, attempt, nextDelay) => {
+        output_js_1.output.warn(`[${agentType}] Retry ${attempt} in ${nextDelay}ms — ${err.message.slice(0, 80)}`);
+    };
+    let sessionId = '';
+    try {
+        const output_text = await (0, retry_js_1.withRetry)(async () => {
+            attempts++;
+            const client = await client_manager_js_1.clientManager.getClient();
+            const session = await client.createSession({
+                model,
+                systemMessage: { content: def.systemMessage },
+                onPermissionRequest: copilot_sdk_1.approveAll,
+            });
+            sessionId = session.sessionId;
+            output_js_1.output.debug(`[${agentType}] Session started: ${sessionId}`);
+            let collected = '';
+            if (options.onChunk) {
+                session.on('assistant.message_delta', (e) => {
+                    const chunk = e.data.deltaContent ?? '';
+                    options.onChunk(chunk);
+                    collected += chunk;
+                });
+            }
+            const result = await session.sendAndWait({ prompt: task }, timeoutMs);
+            // Prefer the full message from sendAndWait; fall back to streamed text
+            const finalText = result?.data?.content ??
+                collected;
+            await session.disconnect();
+            output_js_1.output.debug(`[${agentType}] Session completed: ${sessionId}`);
+            return finalText;
+        }, {
+            ...options.retryConfig,
+            retryOn: options.retryConfig?.retryOn ?? retry_js_1.RetryPredicates.copilotErrors,
+            onRetry: options.retryConfig?.onRetry ?? onRetry,
+        });
+        return {
+            agentType,
+            agentId: `${agentType}-${Date.now()}`,
+            sessionId,
+            output: output_text,
+            durationMs: Date.now() - startTime,
+            attempts,
+            success: true,
+        };
+    }
+    catch (err) {
+        const classified = (0, error_handler_js_1.classifyError)(err);
+        output_js_1.output.error(`[${agentType}] Failed after ${attempts} attempt(s): ${classified.message}`);
+        return {
+            agentType,
+            agentId: `${agentType}-${Date.now()}`,
+            sessionId,
+            output: '',
+            durationMs: Date.now() - startTime,
+            attempts,
+            success: false,
+            error: classified.message,
+        };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/agents/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/agents/executor.ts"],"names":[],"mappings":"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"}

package/dist/agents/pool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent pool — tracks active agent states in memory and persists them to disk.
+ */
+import type { AgentState, AgentType } from '../types.js';
+export declare const agentPool: {
+    /** Register a new agent state. */
+    register(state: AgentState): void;
+    /** Update an existing agent state (partial). */
+    update(id: string, patch: Partial<AgentState>): void;
+    /** Get a single agent state by ID. */
+    get(id: string): AgentState | null;
+    /** List all agent states. */
+    list(filter?: {
+        type?: AgentType;
+        status?: AgentState["status"];
+    }): AgentState[];
+    /** Remove an agent state from disk. */
+    remove(id: string): void;
+    /** Remove all terminated/errored agents older than maxAgeMs. */
+    gc(maxAgeMs?: number): void;
+};
+//# sourceMappingURL=pool.d.ts.map

package/dist/agents/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/agents/pool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAczD,eAAO,MAAM,SAAS;IACpB,kCAAkC;oBAClB,UAAU,GAAG,IAAI;IAKjC,gDAAgD;eACrC,MAAM,SAAS,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAOpD,sCAAsC;YAC9B,MAAM,GAAG,UAAU,GAAG,IAAI;IAUlC,6BAA6B;kBACf;QAAE,IAAI,CAAC,EAAE,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;KAAE,GAAG,UAAU,EAAE;IAkBhF,uCAAuC;eAC5B,MAAM,GAAG,IAAI;IAKxB,gEAAgE;2BAC3B,IAAI;CAW1C,CAAC"}

package/dist/agents/pool.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Agent pool — tracks active agent states in memory and persists them to disk.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentPool = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const AGENTS_DIR = path_1.default.join('.copilot-flow', 'agents');
+function ensureDir() {
+    if (!fs_1.default.existsSync(AGENTS_DIR)) {
+        fs_1.default.mkdirSync(AGENTS_DIR, { recursive: true });
+    }
+}
+function agentPath(id) {
+    return path_1.default.join(AGENTS_DIR, `${id}.json`);
+}
+exports.agentPool = {
+    /** Register a new agent state. */
+    register(state) {
+        ensureDir();
+        fs_1.default.writeFileSync(agentPath(state.id), JSON.stringify(state, null, 2));
+    },
+    /** Update an existing agent state (partial). */
+    update(id, patch) {
+        const existing = exports.agentPool.get(id);
+        if (!existing)
+            return;
+        const updated = { ...existing, ...patch };
+        fs_1.default.writeFileSync(agentPath(id), JSON.stringify(updated, null, 2));
+    },
+    /** Get a single agent state by ID. */
+    get(id) {
+        const p = agentPath(id);
+        if (!fs_1.default.existsSync(p))
+            return null;
+        try {
+            return JSON.parse(fs_1.default.readFileSync(p, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    },
+    /** List all agent states. */
+    list(filter) {
+        ensureDir();
+        const files = fs_1.default.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.json'));
+        const agents = files.flatMap(f => {
+            try {
+                return [JSON.parse(fs_1.default.readFileSync(path_1.default.join(AGENTS_DIR, f), 'utf-8'))];
+            }
+            catch {
+                return [];
+            }
+        });
+        return agents.filter(a => {
+            if (filter?.type && a.type !== filter.type)
+                return false;
+            if (filter?.status && a.status !== filter.status)
+                return false;
+            return true;
+        });
+    },
+    /** Remove an agent state from disk. */
+    remove(id) {
+        const p = agentPath(id);
+        if (fs_1.default.existsSync(p))
+            fs_1.default.unlinkSync(p);
+    },
+    /** Remove all terminated/errored agents older than maxAgeMs. */
+    gc(maxAgeMs = 24 * 60 * 60 * 1_000) {
+        const now = Date.now();
+        for (const agent of exports.agentPool.list()) {
+            if ((agent.status === 'terminated' || agent.status === 'error') &&
+                now - agent.startedAt > maxAgeMs) {
+                exports.agentPool.remove(agent.id);
+            }
+        }
+    },
+};
+//# sourceMappingURL=pool.js.map

package/dist/agents/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/agents/pool.ts"],"names":[],"mappings":"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"}

package/dist/agents/registry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agent type registry — defines system prompts and capabilities for each
+ * built-in agent type. Inspired by Ruflo's 12 agent types.
+ */
+import type { AgentDefinition, AgentType } from '../types.js';
+export declare const AGENT_REGISTRY: Record<AgentType, AgentDefinition>;
+/** Get the definition for an agent type, or throw if unknown. */
+export declare function getAgentDefinition(type: AgentType): AgentDefinition;
+/** Return all agent types as an array. */
+export declare function listAgentTypes(): AgentType[];
+/**
+ * Suggest the best agent type for a given task description.
+ * Simple keyword-based routing — no ML required.
+ */
+export declare function routeTask(task: string): AgentType;
+//# sourceMappingURL=registry.d.ts.map

package/dist/agents/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,SAAS,EAAE,eAAe,CA8G7D,CAAC;AAEF,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAInE;AAED,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,SAAS,EAAE,CAE5C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAgBjD"}