ineedcodes 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/salsabila2507/ineedcodes/main/assets/logo.svg" alt="ineed" width="320">
+<img src="https://raw.githubusercontent.com/salsabila2507/ineedcodes/main/assets/logo.svg" alt="ineed" width="480">
 
 **Your terminal, now autonomous.**
 
@@ -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.1",
+  "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

@@ -3,6 +3,7 @@
 import { chat } from './provider.js';
 import { TOOLS, runTool, shellRun, isDestructive } from './tools.js';
 import { trunc, gray, cyan, dim } from './ui.js';
+import { getMemoryProvider } from './memory.js';
 
 export const MAX_STEPS = 30;
 export const MAX_HISTORY_CHARS = 30_000;
@@ -13,7 +14,9 @@ Rules:
 - Use the tools to do real work. Never invent output. Every success claim needs evidence from a tool result.
 - Prefer targeted edits (edit_file) over full rewrites (write_file). Work only inside the current folder.
 - Never push to remotes or delete data without being asked.
-- Destructive commands are blocked. Ask the user to run those themselves.
+- Destructive commands are always blocked. Ask the user to run those themselves.
+- Some actions need user approval. A tool result starting with "Denied" means the user said no: do not retry the same call, explain what you wanted instead.
+- For objectives with 3 or more steps, keep a checklist with the todo tool and update statuses as you go (in_progress for what you are doing now).
 - When the objective is done, verify it (run the tests, read the file back, whatever proves it), then reply with the final result in this shape:
   What changed, what you ran, the evidence you saw.`;
 
@@ -27,21 +30,126 @@ 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 = extra.skipMemory ? null : getMemoryProvider(cfg);
+  let recalled = '';
+  if (memory) {
+    hooks.onMemoryStart?.();
+    try { recalled = await memory.recall(objective); } catch { recalled = ''; }
+    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),
     { role: 'user', content: objective }
   ];
   const changed = new Set();
   const ran = [];
+  const todos = [];
   let answer = '';
   let lastShown = '';
   try {
@@ -49,8 +157,11 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
       if (ctrl.signal.aborted) break;
       let msg;
       try {
+        hooks.onThinkingStart?.();
         msg = await chat(cfg, messages, tools, ctrl.signal);
+        hooks.onThinkingEnd?.();
       } catch (err) {
+        hooks.onThinkingEnd?.();
         if (ctrl.signal.aborted) break;
         throw err;
       }
@@ -62,28 +173,91 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
       }
       const calls = msg.tool_calls ?? [];
       if (calls.length === 0) {
-        return { answer, changed: [...changed], ran, aborted: false };
+        // task finished: store durable knowledge only when something actually changed
+        if (memory && answer && (changed.size > 0 || ran.length > 0) && !ctrl.signal.aborted) {
+          try {
+            await memory.store(`project ${cwd}: ${objective.slice(0, 150)} -> ${answer.slice(0, 300)}`);
+          } catch {}
+        }
+        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.' };
-          } else {
+          } else if (cfg.permShell !== 'allow' && !hooks.approved?.has('shell')) {
+            const verdict = canAsk ? await hooks.onApprove('shell', 'shell', input) : true; // cannot ask: CI-style allow
+            if (verdict === 'always') hooks.approved?.add('shell');
+            if (!verdict) {
+              result = { output: 'Denied: the user did not approve this shell command.' };
+            }
+          }
+          if (!result) {
+            hooks.onWorkStart?.(`running: ${trunc(String(input.command ?? ''), 60)}`);
             result = await shellRun(String(input.command ?? ''), cwd, ctrl.signal);
+            hooks.onWorkEnd?.();
             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 : [];
+            todos.splice(0, todos.length, ...list.slice(0, 50).map(t => ({
+              content: String(t.content ?? '').slice(0, 200),
+              status: ['pending', 'in_progress', 'completed'].includes(t.status) ? t.status : 'pending'
+            })));
+            hooks.onTodos?.([...todos]);
+            result = { output: `Todo list updated (${todos.filter(t => t.status === 'completed').length}/${todos.length} done).` };
           } else {
-            result = runTool(call.function?.name, input, cwd);
-            if (!plan && ['write_file', 'edit_file', 'delete_file'].includes(call.function?.name)
-              && !/^(Refused|Error)/.test(String(result.output))) {
+            const name = call.function?.name;
+            const isEdit = ['write_file', 'edit_file', 'delete_file'].includes(name);
+            let allowedNow = true;
+            if (isEdit && cfg.permEdit !== 'allow' && !hooks.approved?.has('edit')) {
+              const verdict = canAsk ? await hooks.onApprove('edit', name, input) : true; // cannot ask: CI-style allow
+              if (verdict === 'always') hooks.approved?.add('edit');
+              allowedNow = Boolean(verdict);
+            }
+            result = allowedNow ? runTool(name, input, cwd) : { output: `Denied: the user did not approve ${name}.` };
+            if (allowedNow && !plan && isEdit
+              && !/^(Refused|Error|Denied)/.test(String(result.output))) {
               changed.add(String(input.path ?? ''));
             }
           }
@@ -96,7 +270,7 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
     hooks.onRunEnd?.();
   }
   const stopped = ctrl.signal.aborted;
-  return { answer, changed: [...changed], ran, aborted: true, stopped };
+  return { answer, changed: [...changed], ran, todos: [...todos], aborted: true, stopped };
 }
 
 export function pushTurn(history, objective, result) {

package/src/cli.js

@@ -2,7 +2,6 @@
 // ineed: your terminal, now autonomous.
 // First open asks for provider setup. After that, just say what you want.
 
-import * as fs from 'node:fs';
 import { spawn } from 'node:child_process';
 
 const [MAJOR] = process.versions.node.split('.').map(Number);
@@ -13,7 +12,7 @@ if (!(MAJOR >= 20)) {
 }
 
 const { loadConfig } = await import('./config.js');
-const { VERSION, bold, dim, red, green, yellow } = await import('./ui.js');
+const { VERSION, bold, dim, red, green, yellow, cyan, box } = await import('./ui.js');
 
 const args = process.argv.slice(2);
 
@@ -46,7 +45,12 @@ if (args[0] === '--child') {
     process.exit(1);
   }
   try {
-    const res = await runObjective(cfg, task, process.cwd(), []);
+    const res = await runObjective(cfg, task, process.cwd(), [], {
+      onTodos: list => {
+        const mark = s => s === 'completed' ? green('✔') : s === 'in_progress' ? cyan('▸') : dim('○');
+        console.log(box([bold('To-do'), ...list.map(t => '  ' + mark(t.status) + ' ' + t.content)]));
+      }
+    });
     if (res.aborted) {
       console.log('\n' + yellow('Stopped.') + dim(' Task did not finish (step limit or Ctrl+C). Re-run to continue.'));
       process.exit(2);
@@ -69,7 +73,6 @@ if (args.length > 0 && args[0] !== '--reset') {
   const readline = await import('node:readline');
   const { makeInput } = await import('./ui.js');
   const { wizard } = await import('./wizard.js');
-  const { startSession } = await import('./session.js');
   const { clearConfig } = await import('./config.js');
 
   if (args[0] === '--reset') {
@@ -78,6 +81,7 @@ if (args.length > 0 && args[0] !== '--reset') {
   }
 
   let cfg = loadConfig();
+  const fresh = !cfg;
   if (!cfg) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = makeInput(rl);
@@ -89,5 +93,7 @@ if (args.length > 0 && args[0] !== '--reset') {
     }
     rl.close();
   }
-  await startSession(cfg);
+  const { startSession } = await import('./session.js');
+  const wasFresh = fresh || process.env.INEED_FRESH === '1';
+  await startSession(cfg, { fresh: wasFresh });
 }

package/src/config.js

@@ -22,7 +22,11 @@ export function normalize(c) {
     apiKey: String(c.apiKey ?? ''),
     model: String(c.model),
     reasoning: c.reasoning === 'high' ? 'high' : 'low',
-    mode: c.mode === 'plan' ? 'plan' : 'build'
+    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/memory.js

@@ -0,0 +1,61 @@
+// memory.js: MemoryProvider abstraction. Default adapter shells out to the `icm` CLI.
+// The agent never depends on icm internals; if icm is missing or slow, memory is silently empty.
+
+import { spawn } from 'node:child_process';
+
+function icm(args, timeoutMs = 10_000) {
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = spawn('icm', args, { stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
+    } catch {
+      resolve(null);
+      return;
+    }
+    let out = '';
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} resolve(null); }, timeoutMs);
+    child.stdout.on('data', c => {
+      out += c.toString();
+      if (out.length > 20_000) { try { child.kill('SIGKILL'); } catch {} }
+    });
+    child.stderr.on('data', () => {});
+    child.on('error', () => { clearTimeout(timer); resolve(null); });
+    child.on('close', code => {
+      clearTimeout(timer);
+      resolve(code === 0 ? out.slice(0, 8_000) : null);
+    });
+  });
+}
+
+export const ICMAdapter = {
+  name: 'icm',
+
+  // recall relevant durable memory for an objective. Returns '' when nothing/no icm.
+  async recall(query) {
+    if (!query?.trim()) return '';
+    const out = await icm(['recall', query.slice(0, 200), '--limit', '3', '--read-only']);
+    if (!out) return '';
+    const lines = out.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('memories['));
+    const text = lines.join('\n').slice(0, 2_000);
+    return /no (memories|results)|\(empty\)/i.test(text) ? '' : text;
+  },
+
+  // store durable knowledge. Fire-and-forget friendly. Never stores secrets (caller filters).
+  async store(content) {
+    if (!content?.trim()) return false;
+    const out = await icm(['remember', content.trim().slice(0, 1_000)]);
+    return out !== null;
+  },
+
+  async available() {
+    return (await icm(['--help'], 5_000)) !== null;
+  }
+};
+
+// pick the provider. Only icm exists today; the abstraction keeps that swappable.
+// Disable with config memory:false or env INEED_NO_MEMORY=1 (used by the test suite).
+export function getMemoryProvider(cfg) {
+  if (cfg?.memory === false) return null;
+  if (process.env.INEED_NO_MEMORY === '1') return null;
+  return ICMAdapter;
+}