ineedcodes 1.0.2 → 1.1.0

package/README.md

@@ -64,8 +64,12 @@ The agent decides what it needs: list files, read code, search, edit, run shell
 | `/plan` | read-only mode, the agent suggests but changes nothing |
 | `/build` | default mode, the agent makes real changes |
 | `/reason` | toggle reasoning effort low/high |
-| `/clear` | forget the current conversation |
+| `/perm` | permission modes: `/perm auto`, `/perm safe` |
+| `/memory` | durable memory status, `/memory on\|off` |
+| `/mcp` | list MCP servers and their tools |
 | `/setup` | redo provider setup |
+| `/config` | show provider config, API key hidden |
+| `/clear` | forget the current conversation |
 | `/exit` | quit |
 
 Shortcuts are optional. Normal language always works.
@@ -94,13 +98,42 @@ Not a chatbot that prints code. A loop that does the work, checks the results, a
 | `write_file` | create files |
 | `edit_file` | targeted patch, not a rewrite |
 | `delete_file` | remove a file |
+| `todo` | visible checklist for multi-step work |
+| `spawn_agent` | delegate to a focused sub-agent |
 | `shell` | build, test, install, git, anything |
 
+### Multi-agent
+
+Big tasks get delegated. The lead agent spawns workers with a role that fits:
+
+| role | can |
+|---|---|
+| `research` | read and report, nothing else, runs in parallel |
+| `review` | inspect code, report findings, runs in parallel |
+| `test` | run tests and commands, no source edits |
+| `implement` | make the change, verify it |
+| `debug` | find the root cause, fix it |
+
+Workers report back with status, summary, evidence, files changed, and commands run. The lead reconciles everything and answers you.
+
+### MCP (Model Context Protocol)
+
+Connect any MCP server and its tools appear in the agent automatically. Create `~/.ineedcodes/mcp.json`:
+
+```json
+{
+  "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] }
+}
+```
+
+Restart ineed, and every tool from that server is callable. Check what is loaded with `/mcp` inside a session.
+
 ### Safety
 
 - Secrets (.env, ssh keys, pem files) never enter the model context.
 - Destructive shell commands are refused.
 - Everything is jailed to your working directory.
+- Edits and shell commands ask for your approval first (`/perm auto` relaxes this).
 - Plan mode lets you preview intent before any change.
 
 ## Works with any provider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ineedcodes",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Your terminal, now autonomous. Just say what you want, ineed does the rest.",
   "license": "MIT",
   "type": "module",

package/src/agent.js

@@ -30,15 +30,106 @@ export function trimHistory(history) {
   return history.slice(start);
 }
 
-export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
+// ── multi-agent: roles, task packets, worker execution ──
+const ROLES = {
+  research: {
+    readonly: true,
+    tools: ['list_files', 'read_file', 'search_text', 'todo'],
+    prompt: 'You are a research worker. Gather facts and report them. Change nothing.'
+  },
+  review: {
+    readonly: true,
+    tools: ['list_files', 'read_file', 'search_text', 'todo'],
+    prompt: 'You are a review worker. Inspect the code for correctness, bugs, and quality. Report findings, change nothing.'
+  },
+  test: {
+    readonly: false,
+    tools: ['list_files', 'read_file', 'search_text', 'shell', 'todo'],
+    prompt: 'You are a test worker. Run the relevant tests or commands and report the evidence. Do not modify source files.'
+  },
+  implement: {
+    readonly: false,
+    tools: null, // all tools
+    prompt: 'You are an implementation worker. Make the change the lead asked for, verify it works, and report what you did.'
+  },
+  debug: {
+    readonly: false,
+    tools: null, // all tools
+    prompt: 'You are a debugging worker. Find the root cause, fix it if you can, and report cause plus evidence.'
+  }
+};
+
+let workerSeq = 0;
+
+function workerResultText(r) {
+  const files = r.files?.length ? ` files: ${r.files.join(', ')};` : '';
+  const cmds = r.commands?.length ? ` ran ${r.commands.length} command(s);` : '';
+  return `Worker ${r.id} [${r.status}]: ${String(r.summary).slice(0, 800)}.${files}${cmds}`;
+}
+
+async function runWorker(cfg, spec, cwd, depth, hooks) {
+  const roleName = ROLES[spec.input.role] ? spec.input.role : 'research';
+  const role = ROLES[roleName];
+  const objective = String(spec.input.objective ?? '')
+    + (spec.input.context ? `\nContext from lead agent: ${String(spec.input.context).slice(0, 1_000)}` : '');
+  try {
+    const res = await runObjective(cfg, objective, cwd, [], {}, {
+      depth: depth + 1,
+      toolFilter: role.tools,
+      worker: { id: spec.id, role: roleName, prompt: role.prompt }
+    });
+    return { id: spec.id, role: roleName, status: res.aborted ? 'incomplete' : 'completed', summary: res.answer || '(no output)', files: res.changed, commands: res.ran };
+  } catch (err) {
+    return { id: spec.id, role: roleName, status: 'failed', summary: err.message, files: [], commands: [] };
+  }
+}
+
+const SPAWN_TOOL = {
+  name: 'spawn_agent',
+  description: 'Spawn a focused sub-agent worker. Roles: research (read only), review (read only), test (runs commands, does not edit), implement (edits), debug (finds and fixes). Read-only workers can run in parallel.',
+  parameters: {
+    type: 'object',
+    properties: {
+      role: { type: 'string', enum: Object.keys(ROLES) },
+      objective: { type: 'string', description: 'the exact task for this worker' },
+      context: { type: 'string', description: 'relevant context: files, errors, constraints' }
+    },
+    required: ['role', 'objective']
+  },
+  allowedInPlan: true
+};
+
+export async function runObjective(cfg, objective, cwd, history, hooks = {}, extra = {}) {
   const ctrl = new AbortController();
   hooks.onRunStart?.(ctrl);
   const plan = cfg.mode === 'plan';
-  const tools = plan ? TOOLS.filter(t => t.allowedInPlan) : TOOLS;
+  const depth = extra.depth ?? 0;
+  let tools = plan ? TOOLS.filter(t => t.allowedInPlan) : [...TOOLS, SPAWN_TOOL];
+  if (extra.toolFilter) tools = tools.filter(t => (extra.toolFilter).includes(t.name));
   const canAsk = typeof hooks.onApprove === 'function';
 
+  // MCP: load configured servers once per top-level objective, expose their tools
+  let mcpManager = null;
+  const mcpMap = new Map();
+  if (depth === 0 && !plan && cfg.mcp !== false) {
+    try {
+      const { McpManager, mcpConfigured } = await import('./mcp.js');
+      if (mcpConfigured()) {
+        mcpManager = new McpManager();
+        const errors = await mcpManager.loadFromConfig();
+        errors.forEach(e => hooks.onText?.(dim(e)));
+        const mcpTools = await mcpManager.allTools();
+        const names = new Set(tools.map(t => t.name));
+        for (const t of mcpTools) {
+          if (!names.has(t.name)) { tools.push(t); mcpMap.set(t.name, t.mcp); names.add(t.name); }
+        }
+        hooks.onMCP?.(mcpTools.map(t => t.name));
+      }
+    } catch {}
+  }
+
   // recall durable memory before meaningful work (rule 12/15: MemoryProvider abstraction)
-  const memory = getMemoryProvider(cfg);
+  const memory = extra.skipMemory ? null : getMemoryProvider(cfg);
   let recalled = '';
   if (memory) {
     hooks.onMemoryStart?.();
@@ -46,10 +137,11 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
     hooks.onMemoryEnd?.(recalled);
   }
 
+  const workerPrefix = extra.worker ? `You are ${extra.worker.id} (${extra.worker.role} worker) spawned by the lead agent. ${extra.worker.prompt}\n` : '';
   const messages = [
     {
       role: 'system',
-      content: `${SYSTEM}\nWorking directory: ${cwd}\nMode: ${plan ? 'plan (read only, suggest what to change, do not change anything)' : 'build'}`
+      content: `${workerPrefix ? workerPrefix + '\n' : ''}${SYSTEM}\nWorking directory: ${cwd}\nMode: ${plan ? 'plan (read only, suggest what to change, do not change anything)' : 'build'}`
         + (recalled ? `\nRelevant memory from previous sessions with this user (durable facts, may be stale):\n${recalled}` : '')
     },
     ...trimHistory(history),
@@ -89,12 +181,44 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
         }
         return { answer, changed: [...changed], ran, todos: [...todos], aborted: false };
       }
+      // spawn_agent pre-pass: read-only workers run in parallel (max 4), writers sequentially
+      const spawnResults = new Map();
+      const spawnCalls = calls.filter(c => c.function?.name === 'spawn_agent');
+      if (spawnCalls.length && depth === 0) {
+        const specs = spawnCalls.map(c => {
+          let input = {};
+          try { input = JSON.parse(c.function?.arguments || '{}'); } catch {}
+          const role = ROLES[input.role] ? input.role : 'research';
+          return { call: c, input, role, id: `${role}-${++workerSeq}` };
+        });
+        const runOne = async s => {
+          hooks.onAgentStart?.(s.id, s.input);
+          const r = await runWorker(cfg, s, cwd, depth, hooks);
+          hooks.onAgentEnd?.(s.id, r);
+          spawnResults.set(s.call.id, r);
+        };
+        const readonly = specs.filter(s => ROLES[s.role].readonly).slice(0, 4);
+        const writers = specs.filter(s => !ROLES[s.role].readonly);
+        for (let i = 0; i < readonly.length; i += 4) {
+          await Promise.all(readonly.slice(i, i + 4).map(runOne));
+        }
+        for (const s of writers) await runOne(s);
+      }
+
       for (const call of calls) {
         let input = {};
         try { input = JSON.parse(call.function?.arguments || '{}'); } catch {}
         hooks.onTool?.(call.function?.name, input);
         let result;
-        if (call.function?.name === 'shell') {
+        if (spawnResults.has(call.id)) {
+          result = { output: workerResultText(spawnResults.get(call.id)) };
+        } else if (call.function?.name === 'spawn_agent') {
+          result = { output: 'Refused: workers cannot spawn more agents.' };
+        } else if (mcpMap.has(call.function?.name)) {
+          const m = mcpMap.get(call.function?.name);
+          result = await mcpManager.call(m.server, m.tool, input);
+          hooks.onMCPResult?.(call.function?.name, result.output);
+        } else if (call.function?.name === 'shell') {
           if (plan) result = { output: 'Refused: plan mode is read only. Switch to build mode with /build.' };
           else if (isDestructive(String(input.command ?? ''))) {
             result = { output: 'Refused: that command is destructive. Run it yourself if you are sure.' };
@@ -112,7 +236,7 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
             ran.push(String(input.command ?? '').slice(0, 120));
           }
         } else {
-          if (plan && !TOOLS.find(t => t.name === call.function?.name)?.allowedInPlan) {
+          if (plan && !tools.find(t => t.name === call.function?.name)) {
             result = { output: 'Refused: plan mode is read only. Switch to build mode with /build.' };
           } else if (call.function?.name === 'todo') {
             const list = Array.isArray(input.todos) ? input.todos : [];

package/src/config.js

@@ -24,6 +24,7 @@ export function normalize(c) {
     reasoning: c.reasoning === 'high' ? 'high' : 'low',
     mode: c.mode === 'plan' ? 'plan' : 'build',
     memory: c.memory !== false,
+    mcp: c.mcp !== false,
     permEdit: c.permEdit === 'allow' ? 'allow' : 'ask',
     permShell: c.permShell === 'allow' ? 'allow' : 'ask'
   };

package/src/mcp.js

@@ -0,0 +1,203 @@
+// mcp.js: minimal MCP client. Connects MCP servers over stdio using JSON-RPC 2.0,
+// lists their tools, and lets the agent call them like native tools.
+// Servers are configured in ~/.ineedcodes/mcp.json: { "name": { "command": "...", "args": ["..."] } }
+
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+export const MCP_CONFIG_FILE = process.env.INEED_MCP_CONFIG
+  || path.join(os.homedir(), '.ineedcodes', 'mcp.json');
+
+let nextId = 1;
+
+class McpServer {
+  constructor(name, spec) {
+    this.name = name;
+    this.spec = spec;
+    this.child = null;
+    this.buffer = '';
+    this.pending = new Map(); // id -> resolve
+    this.tools = [];
+    this.dead = false;
+  }
+
+  start() {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let child;
+      try {
+        child = spawn(this.spec.command, this.spec.args ?? [], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: { ...process.env, NO_COLOR: '1' }
+        });
+      } catch (err) {
+        this.dead = true;
+        return reject(new Error(`cannot start MCP server ${this.name}: ${err.message}`));
+      }
+      this.child = child;
+      child.stdout.on('data', chunk => {
+        this.buffer += chunk.toString();
+        let idx;
+        while ((idx = this.buffer.indexOf('\n')) >= 0) {
+          const line = this.buffer.slice(0, idx).trim();
+          this.buffer = this.buffer.slice(idx + 1);
+          if (!line) continue;
+          let msg;
+          try { msg = JSON.parse(line); } catch { continue; }
+          if (msg.id && this.pending.has(msg.id)) {
+            const r = this.pending.get(msg.id);
+            this.pending.delete(msg.id);
+            r(msg);
+          }
+        }
+      });
+      child.stderr.on('data', () => {}); // servers log freely; never leaks into the model
+      child.on('error', err => {
+        this.dead = true;
+        if (!settled) { settled = true; reject(new Error(`MCP server ${this.name}: ${err.message}`)); }
+      });
+      child.on('close', code => {
+        this.dead = true;
+        for (const r of this.pending.values()) r({ error: { message: `MCP server ${this.name} exited (code ${code})` } });
+        this.pending.clear();
+      });
+      const fail = setTimeout(() => {
+        if (!settled) { settled = true; reject(new Error(`MCP server ${this.name} did not answer initialize (10s)`)); }
+      }, 10_000);
+      this.request('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'ineed', version: '1.1.0' }
+      }).then(init => {
+        if (init.error) throw new Error(init.error.message ?? 'initialize failed');
+        this.notify('notifications/initialized', {});
+        clearTimeout(fail);
+        settled = true;
+        resolve(this);
+      }).catch(err => {
+        clearTimeout(fail);
+        settled = true;
+        this.kill();
+        reject(err);
+      });
+    });
+  }
+
+  request(method, params) {
+    if (this.dead) return Promise.resolve({ error: { message: `MCP server ${this.name} is not running` } });
+    const id = nextId++;
+    return new Promise(resolve => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        resolve({ error: { message: `MCP server ${this.name} timed out on ${method}` } });
+      }, 60_000);
+      this.pending.set(id, msg => { clearTimeout(timer); resolve(msg); });
+      try {
+        this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        resolve({ error: { message: `MCP write failed: ${err.message}` } });
+      }
+    });
+  }
+
+  notify(method, params) {
+    try { this.child?.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); } catch {}
+  }
+
+  async listTools() {
+    const res = await this.request('tools/list', {});
+    if (res.error) return [];
+    this.tools = (res.result?.tools ?? []).map(t => ({
+      name: t.name,
+      description: t.description ?? '',
+      inputSchema: t.inputSchema ?? { type: 'object', properties: {} }
+    }));
+    return this.tools;
+  }
+
+  async callTool(name, args) {
+    const res = await this.request('tools/call', { name, arguments: args ?? {} });
+    if (res.error) return { output: `Error: MCP ${this.name}/${name}: ${res.error.message}` };
+    const parts = res.result?.content ?? [];
+    const text = parts.filter(p => p.type === 'text').map(p => p.text).join('\n');
+    return { output: (res.result?.isError ? 'Error: ' : '') + (text || '(empty result)') };
+  }
+
+  kill() {
+    this.dead = true;
+    try { this.child?.kill('SIGKILL'); } catch {}
+  }
+}
+
+export class McpManager {
+  constructor() {
+    this.servers = new Map();
+  }
+
+  async loadFromConfig() {
+    let cfg;
+    try { cfg = JSON.parse(fs.readFileSync(MCP_CONFIG_FILE, 'utf8')); } catch { return []; }
+    const errors = [];
+    for (const [name, spec] of Object.entries(cfg)) {
+      if (!spec?.command) { errors.push(`mcp: ${name} has no command`); continue; }
+      if (this.servers.has(name)) continue;
+      try {
+        const server = new McpServer(name, spec);
+        await server.start();
+        this.servers.set(name, server);
+      } catch (err) {
+        errors.push(err.message);
+      }
+    }
+    return errors;
+  }
+
+  // native-style tool descriptors, namespaced mcp_<server>_<tool>
+  async allTools() {
+    const out = [];
+    for (const [serverName, server] of this.servers) {
+      for (const t of await server.listTools()) {
+        out.push({
+          name: `mcp_${serverName}_${t.name}`.slice(0, 64).replace(/[^a-zA-Z0-9_]/g, '_'),
+          description: `[MCP ${serverName}] ${t.description}`.trim(),
+          parameters: jsonSchemaToParameters(t.inputSchema),
+          mcp: { server: serverName, tool: t.name },
+          allowedInPlan: false
+        });
+      }
+    }
+    return out;
+  }
+
+  hasTools() {
+    for (const s of this.servers.values()) if (!s.dead && s.tools.length) return true;
+    return this.servers.size > 0;
+  }
+
+  async call(serverName, toolName, args) {
+    const server = this.servers.get(serverName);
+    if (!server) return { output: `Error: unknown MCP server ${serverName}` };
+    if (server.dead) return { output: `Error: MCP server ${serverName} is not running` };
+    return server.callTool(toolName, args);
+  }
+
+  killAll() {
+    for (const s of this.servers.values()) s.kill();
+    this.servers.clear();
+  }
+}
+
+function jsonSchemaToParameters(schema) {
+  // OpenAI function parameters are JSON Schema; pass through with light sanitation
+  const s = schema && typeof schema === 'object' ? schema : { type: 'object' };
+  if (s.type !== 'object') return { type: 'object', properties: {} };
+  return { type: 'object', properties: s.properties ?? {}, required: s.required ?? [] };
+}
+
+export function mcpConfigured() {
+  try { return Object.keys(JSON.parse(fs.readFileSync(MCP_CONFIG_FILE, 'utf8'))).length > 0; } catch { return false; }
+}

package/src/session.js

@@ -8,6 +8,7 @@ import { fetchModels } from './provider.js';
 import { makeInput, bold, dim, red, green, yellow, cyan, gray, trunc, BANNER, logo, box, startSpinner, VERSION, RULE, userBubble, screen } from './ui.js';
 import { wizard } from './wizard.js';
 import { getMemoryProvider, ICMAdapter } from './memory.js';
+import { mcpConfigured } from './mcp.js';
 
 const plain = s => String(s).replace(/\x1b\[[0-9;]*m/g, '');
 
@@ -99,6 +100,10 @@ export async function startSession(cfg, { fresh = false } = {}) {
           const mark = s => s === 'completed' ? green('✔') : s === 'in_progress' ? cyan('▸') : dim('○');
           say(box([bold('To-do'), ...list.map(t => '  ' + mark(t.status) + ' ' + t.content)]));
         },
+        onAgentStart: (id, input) => { stopSpinner(); say(cyan('  ◆ spawn ' + id) + gray(` role=${input.role ?? '?'} task=${trunc(String(input.objective ?? ''), 70)}`)); },
+        onAgentEnd: (id, r) => { stopSpinner(); say((r.status === 'completed' ? green('  ◆ ' + id + ' done') : yellow('  ◆ ' + id + ' ' + r.status)) + gray(' ' + trunc(String(r.summary ?? '').replaceAll('\n', ' '), 90))); },
+        onMCP: names => { if (names.length) say(dim('  MCP tools available: ' + names.join(', '))); },
+        onMCPResult: (name, out) => { say(gray('    mcp result: ' + trunc(out, 100))); },
         onApprove: async (cat, name, input2) => {
           stopSpinner();
           say(yellow('  ⚠ approval needed') + ' ' + cyan(name) + gray(' ' + trunc(JSON.stringify(input2), 80)));
@@ -156,6 +161,7 @@ export async function startSession(cfg, { fresh = false } = {}) {
       say('  ' + cyan('/perm') + '     permissions: /perm auto | /perm safe | /perm');
       say('  ' + cyan('/config') + '   show provider config (key hidden)');
       say('  ' + cyan('/memory') + '   memory status, /memory on|off to toggle');
+      say('  ' + cyan('/mcp') + '     list MCP servers and their tools');
       say('  ' + cyan('/clear') + '    forget this conversation');
       say('  ' + cyan('/setup') + '    redo provider setup');
       say('  ' + cyan('/reset') + '    clear saved config');
@@ -241,6 +247,29 @@ export async function startSession(cfg, { fresh = false } = {}) {
       busy = false;
       return afterTask();
     }
+    if (input === '/mcp' || input === '/mcp reload') {
+      if (!mcpConfigured()) {
+        say(yellow('No MCP servers configured.') + dim(' Add them to ~/.ineedcodes/mcp.json, e.g.: {"context7":{"command":"npx","args":["-y","@upstash/context7-mcp"]}}'));
+        return;
+      }
+      busy = true;
+      try {
+        const { McpManager } = await import('./mcp.js');
+        const mgr = new McpManager();
+        const errors = await mgr.loadFromConfig();
+        for (const e of errors) say(red('  ✗ ' + e));
+        const tools = await mgr.allTools();
+        if (tools.length) {
+          say(green(`  ${mgr.servers.size} MCP server(s), ${tools.length} tool(s):`));
+          for (const t of tools) say('  ' + cyan(t.name) + gray(' ' + trunc(t.description, 90)));
+        } else if (!errors.length) {
+          say(yellow('  Servers connected but exposed no tools.'));
+        }
+        mgr.killAll();
+      } catch (err) { say(red('  ✗ ' + err.message)); }
+      busy = false;
+      return afterTask();
+    }
     if (input === '/setup' || input === '/reset') {
       clearConfig();
       say(dim('Config cleared. Running setup...'));

package/src/ui.js

@@ -1,6 +1,6 @@
 // ui.js: terminal helpers. No dependencies, respects NO_COLOR and non-TTY.
 
-export const VERSION = '1.0.2';
+export const VERSION = '1.1.0';
 
 const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
 const wrap = (code, t) => USE_COLOR ? `\x1b[${code}m${t}\x1b[0m` : String(t);