@causyne/agent 0.0.0-stage → 1.10.0

package/src/gitSnapshot.js

@@ -0,0 +1,378 @@
+// Shadow-git checkpoint backend.
+//
+// The file-copy store (checkpoints.js) works, but it copies bytes and therefore
+// has to cap what it will look at — MAX_TREE_FILES is 5000, and a real home
+// directory blows past that, which is how a user ended up with a workspace root
+// silently marked `too_many_files` and NOT covered by any rollback.
+//
+// Git already solves this problem properly, so this backend borrows opencode's
+// design (packages/core/src/snapshot.ts):
+//
+//   * The repository lives in ~/.causyne/snapshot/<project>/<hash(worktree)>.
+//     The user's own .git is NEVER touched — no stash, no commit, no index
+//     mutation, no HEAD movement. Their history is theirs.
+//   * objects/info/alternates points at the user's object database, and their
+//     index is copied in, so blobs the project already stores are never
+//     re-hashed. This is what makes a checkpoint instant on a large tree
+//     instead of a minutes-long walk.
+//   * A checkpoint id IS a `write-tree` SHA. No commits, no refs, nothing to
+//     garbage collect by hand.
+//
+// ZERO-MALWARE: every git invocation goes through runGit(), which uses execFile
+// with an ARRAY of arguments. There is no shell anywhere in this file, and no
+// argument is ever built by string concatenation, so there is nothing for an
+// injected filename to escape into. This is the same hardening applied to
+// printer.js in v1.1.44 after its exec() shell-injection hole.
+
+import { execFileSync, execFile } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import crypto from 'crypto';
+import { causyneHome } from './utils/paths.js';
+
+/** A git call that hangs must not hang a task. */
+const GIT_TIMEOUT_MS = 20000;
+
+/** Untracked files above this are excluded rather than stored (opencode uses 2 MB). */
+const MAX_UNTRACKED_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Run git.
+ *
+ * `args` is an ARRAY — execFile passes it straight to execve, so no shell ever
+ * parses it and a path containing a space, a quote or `$(...)` is just a path.
+ * Never change this to exec() or add `shell: true`.
+ */
+function runGit(args, options = {}) {
+  if (!Array.isArray(args) || args.some((a) => typeof a !== 'string')) {
+    throw new Error('git arguments must be an array of strings');
+  }
+  // Synchronous on purpose. Everything in checkpoints.js is synchronous, and a
+  // checkpoint MUST complete before the agent is allowed to touch a file — an
+  // asynchronous capture would race the task's own writes and snapshot a state
+  // that already includes the edits it is supposed to protect against. The cost
+  // is nothing next to what this replaces: the native store walks and hashes
+  // every file in the tree, where git reuses its index and writes one object.
+  return execFileSync('git', args, {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: 32 * 1024 * 1024,
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    ...options
+  });
+}
+
+const execFileAsync = promisify(execFile);
+
+
+async function runGitAsync(args, options = {}) {
+  if (!Array.isArray(args) || args.some((a) => typeof a !== 'string')) {
+    throw new Error('git arguments must be an array of strings');
+  }
+  const { stdout } = await execFileAsync('git', args, {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: 32 * 1024 * 1024,
+    windowsHide: true,
+    ...options
+  });
+  return stdout;
+}
+
+/**
+ * Capture without blocking — the form the task hot path must use.
+ *
+ * beginTask runs at the START of every task, so it is the one capture that can
+ * never be synchronous. Preview and restore stay
+ * synchronous: they run only when the user has explicitly asked for an undo and
+ * is waiting for the answer.
+ */
+export async function captureTreeAsync(worktree) {
+  try {
+    const gitDir = initShadow(worktree);
+    excludeOversizedUntracked(gitDir, worktree);
+    await runGitAsync(
+      ['--git-dir', gitDir, '--work-tree', worktree, 'add', '--all'],
+      { cwd: worktree }
+    );
+    const sha = (await runGitAsync(['--git-dir', gitDir, 'write-tree'])).trim();
+    return sha || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/** Is a usable git binary on PATH? Cached — the answer cannot change mid-run. */
+let gitAvailable = null;
+export function isGitAvailable() {
+  if (gitAvailable !== null) return gitAvailable;
+  try {
+    runGit(['--version']);
+    gitAvailable = true;
+  } catch (e) {
+    gitAvailable = false;
+  }
+  return gitAvailable;
+}
+
+/** The worktree root for `dir`, or null when it is not inside a git repository. */
+export function resolveWorktree(dir) {
+  try {
+    const out = runGit(['rev-parse', '--show-toplevel'], { cwd: dir });
+    const root = out.trim();
+    return root ? path.resolve(root) : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/** Where this worktree's shadow repository lives. */
+export function shadowDirFor(worktree) {
+  const hash = crypto.createHash('sha256').update(path.resolve(worktree)).digest('hex').slice(0, 16);
+  return path.join(causyneHome(), 'snapshot', path.basename(worktree), hash);
+}
+
+/**
+ * Create (or reuse) the shadow repository for a worktree.
+ *
+ * Returns the --git-dir path. Safe to call repeatedly.
+ */
+export function initShadow(worktree) {
+  const gitDir = shadowDirFor(worktree);
+  const alreadyInitialised = fs.existsSync(path.join(gitDir, 'HEAD'));
+
+  if (!alreadyInitialised) {
+    fs.mkdirSync(gitDir, { recursive: true });
+    runGit(['--git-dir', gitDir, 'init', '--bare', '--quiet']);
+
+    // Tuning that matters on large trees, applied once at creation.
+    for (const [key, value] of [
+      ['feature.manyFiles', 'true'],
+      ['index.version', '4'],
+      ['index.threads', 'true'],
+      ['core.untrackedCache', 'true']
+    ]) {
+      try {
+        runGit(['--git-dir', gitDir, 'config', key, value]);
+      } catch (e) {
+        // Tuning is an optimisation; an older git that rejects a key must not
+        // stop the checkpoint from being taken.
+      }
+    }
+  }
+
+  // Point at the user's object database so blobs are never re-hashed, and adopt
+  // their index so already-hashed entries are reused. Both are best-effort: a
+  // missing or incompatible source just means a full, slower add.
+  const sourceObjects = path.join(worktree, '.git', 'objects');
+  if (fs.existsSync(sourceObjects)) {
+    try {
+      const infoDir = path.join(gitDir, 'objects', 'info');
+      fs.mkdirSync(infoDir, { recursive: true });
+      fs.writeFileSync(path.join(infoDir, 'alternates'), `${sourceObjects}\n`, 'utf8');
+    } catch (e) {}
+  }
+
+  if (!alreadyInitialised) {
+    const sourceIndex = path.join(worktree, '.git', 'index');
+    if (fs.existsSync(sourceIndex)) {
+      try {
+        fs.copyFileSync(sourceIndex, path.join(gitDir, 'index'));
+      } catch (e) {}
+    }
+  }
+
+  return gitDir;
+}
+
+/**
+ * Exclude untracked files too large to be worth storing.
+ *
+ * Written into the SHADOW repo's info/exclude, never the user's .gitignore.
+ */
+function excludeOversizedUntracked(gitDir, worktree) {
+  let listing = '';
+  try {
+    listing = runGit(
+      ['--git-dir', gitDir, '--work-tree', worktree, 'ls-files', '--others', '--exclude-standard', '-z'],
+      { cwd: worktree }
+    );
+  } catch (e) {
+    return;
+  }
+
+  const oversized = [];
+  for (const rel of listing.split('\0')) {
+    if (!rel) continue;
+    try {
+      const stat = fs.statSync(path.join(worktree, rel));
+      if (stat.isFile() && stat.size > MAX_UNTRACKED_BYTES) oversized.push(rel);
+    } catch (e) {}
+  }
+  if (oversized.length === 0) return;
+
+  try {
+    const infoDir = path.join(gitDir, 'info');
+    fs.mkdirSync(infoDir, { recursive: true });
+    fs.writeFileSync(path.join(infoDir, 'exclude'), `${oversized.join('\n')}\n`, 'utf8');
+  } catch (e) {}
+}
+
+/**
+ * Capture the worktree's current state.
+ *
+ * @returns {string|null} a tree SHA, or null if the capture failed —
+ *   a checkpoint is best-effort and must never fail the task it belongs to.
+ */
+export function captureTree(worktree) {
+  try {
+    const gitDir = initShadow(worktree);
+    excludeOversizedUntracked(gitDir, worktree);
+
+    // The user's ignore rules decide what is worth keeping. --no-index keeps it
+    // pattern-based rather than dependent on what their index happens to track.
+    // NO --force here, deliberately.
+    //
+    // `--force` means "add otherwise ignored files". It was doing exactly that:
+    // node_modules, build outputs, caches — everything .gitignore exists to keep
+    // out. The first capture of this repository took 23 seconds and stalled task
+    // startup. The user's own ignore rules are the correct definition of "files
+    // worth being able to restore".
+    runGit(['--git-dir', gitDir, '--work-tree', worktree, 'add', '--all'], { cwd: worktree });
+
+    const sha = (runGit(['--git-dir', gitDir, 'write-tree'])).trim();
+    return sha || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * What restoring `files` would change — WITHOUT touching the worktree.
+ *
+ * The technique is opencode's (packages/core/src/git.ts), which built it and
+ * never wired it to a UI: point GIT_INDEX_FILE at a throwaway index, read-tree
+ * the current state into it, update-index the planned blobs over the top,
+ * write-tree that hypothetical, and diff it against now. Nothing anywhere near
+ * the user's files is written, and the temp index is removed in a finally.
+ *
+ * @param {string} worktree
+ * @param {string} fromTree tree SHA to restore from
+ * @returns {Array<{path,status,additions,deletions,patch}>}
+ */
+export function previewRestore(worktree, fromTree) {
+  const gitDir = initShadow(worktree);
+  const tempIndex = path.join(gitDir, `preview-${crypto.randomUUID()}.index`);
+  const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
+
+  try {
+    const current = captureTree(worktree);
+    if (!current) return [];
+
+    runGit(['--git-dir', gitDir, 'read-tree', current], { env });
+    const raw = runGit(
+      ['--git-dir', gitDir, 'diff', '--numstat', '--find-renames', current, fromTree],
+      { env }
+    );
+
+    const changes = [];
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      const [added, removed, file] = line.split('\t');
+      if (!file) continue;
+
+      let patch = '';
+      try {
+        patch = runGit(
+          ['--git-dir', gitDir, 'diff', '--unified=3', current, fromTree, '--', file],
+          { env }
+        );
+      } catch (e) {
+        // A binary file has no textual patch; the counts still describe it.
+      }
+
+      changes.push({
+        path: file,
+        // Restoring runs backwards: a file absent from the OLD tree was created
+        // by the task and would be deleted, and vice versa.
+        status: added === '-' && removed === '-' ? 'binary' : classify(added, removed),
+        additions: added === '-' ? 0 : Number(added) || 0,
+        deletions: removed === '-' ? 0 : Number(removed) || 0,
+        patch
+      });
+    }
+    return changes;
+  } finally {
+    try { fs.rmSync(tempIndex, { force: true }); } catch (e) {}
+  }
+}
+
+function classify(added, removed) {
+  const a = Number(added) || 0;
+  const d = Number(removed) || 0;
+  if (a > 0 && d === 0) return 'added';
+  if (d > 0 && a === 0) return 'deleted';
+  return 'modified';
+}
+
+/**
+ * Restore the worktree to `fromTree`.
+ *
+ * Only called after the user has approved a preview built from the same pair of
+ * trees, so what they were shown is what happens.
+ */
+export function restoreTree(worktree, fromTree) {
+  const gitDir = initShadow(worktree);
+  const current = captureTree(worktree);
+
+  // Files the agent CREATED must be removed, not merely left behind.
+  //
+  // `git checkout <tree> -- .` restores every path the tree contains and is
+  // silent about every path it does not — so a file created after the
+  // checkpoint survived the rollback, and "restored to the previous state"
+  // quietly meant "mostly". Deletions are computed first, because the checkout
+  // below rewrites the index this diff is read from.
+  const toRemove = [];
+  if (current) {
+    let raw = '';
+    try {
+      raw = runGit(['--git-dir', gitDir, 'diff', '--name-status', '-z', current, fromTree]);
+    } catch (e) {
+      raw = '';
+    }
+    // -z output is NUL separated: status, path, status, path…
+    const parts = raw.split('\0').filter(Boolean);
+    for (let i = 0; i + 1 < parts.length; i += 2) {
+      const status = parts[i];
+      const rel = parts[i + 1];
+      // 'D' going current -> target means: present now, absent then.
+      if (status[0] !== 'D') continue;
+
+      // A path must never climb out of the worktree it belongs to.
+      const absolute = path.resolve(worktree, rel);
+      const root = path.resolve(worktree);
+      if (absolute !== root && !absolute.startsWith(root + path.sep)) continue;
+      toRemove.push(absolute);
+    }
+  }
+
+  runGit(
+    ['--git-dir', gitDir, '--work-tree', worktree, 'checkout', fromTree, '--', '.'],
+    { cwd: worktree }
+  );
+
+  for (const absolute of toRemove) {
+    try { fs.rmSync(absolute, { force: true }); } catch (e) {}
+  }
+}
+
+/** Retention: the shadow repo prunes itself rather than growing forever. */
+export function pruneShadow(worktree) {
+  try {
+    const gitDir = initShadow(worktree);
+    runGit(['--git-dir', gitDir, 'gc', '--prune=7.days', '--quiet']);
+  } catch (e) {}
+}

package/src/mcp/jsonRpc.js

@@ -0,0 +1,165 @@
+
+
+import { spawn } from 'child_process';
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * A JSON-RPC channel over a child process's stdin/stdout.
+ *
+ * MCP frames stdio traffic as newline-delimited JSON. stderr is deliberately
+ * NOT parsed — servers use it for human-readable logging, and treating it as
+ * protocol is how a chatty server becomes a hang.
+ */
+export class StdioChannel {
+  constructor({ command, args = [], env = {}, cwd }) {
+    this.command = command;
+    this.args = args;
+    this.env = env;
+    this.cwd = cwd;
+    this.child = null;
+    this.buffer = '';
+    this.pending = new Map();
+    this.nextId = 1;
+    this.notificationHandler = null;
+    this.stderrTail = [];
+  }
+
+  async open() {
+    this.child = spawn(this.command, this.args, {
+      cwd: this.cwd || process.cwd(),
+      env: { ...process.env, ...this.env },
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    this.child.stdout.setEncoding('utf-8');
+    this.child.stdout.on('data', chunk => this.#ingest(chunk));
+
+    // Kept only so a failure can be explained. Bounded, because a server that
+    
+    this.child.stderr.setEncoding('utf-8');
+    this.child.stderr.on('data', chunk => {
+      this.stderrTail.push(String(chunk));
+      if (this.stderrTail.length > 20) this.stderrTail.shift();
+    });
+
+    this.child.on('exit', code => this.#failAll(new Error(`server exited (code ${code})${this.lastError()}`)));
+    this.child.on('error', err => this.#failAll(err));
+
+    // Surface a command that does not exist as an error rather than a timeout.
+    await new Promise((resolve, reject) => {
+      const onError = (err) => reject(err);
+      this.child.once('error', onError);
+      setTimeout(() => { this.child.removeListener('error', onError); resolve(); }, 150);
+    });
+  }
+
+  lastError() {
+    const tail = this.stderrTail.join('').trim();
+    return tail ? `: ${tail.slice(-400)}` : '';
+  }
+
+  #ingest(chunk) {
+    this.buffer += chunk;
+    let newline;
+    while ((newline = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, newline).trim();
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      let frame;
+      try { frame = JSON.parse(line); } catch (e) { continue; }
+      this.#dispatch(frame);
+    }
+  }
+
+  #dispatch(frame) {
+    if (frame.id !== undefined && this.pending.has(frame.id)) {
+      const { resolve, reject, timer } = this.pending.get(frame.id);
+      this.pending.delete(frame.id);
+      clearTimeout(timer);
+      if (frame.error) reject(new Error(frame.error.message || 'JSON-RPC error'));
+      else resolve(frame.result);
+      return;
+    }
+    if (frame.method && this.notificationHandler) {
+      try { this.notificationHandler(frame); } catch (e) {}
+    }
+  }
+
+  #failAll(error) {
+    for (const [, { reject, timer }] of this.pending) {
+      clearTimeout(timer);
+      reject(error);
+    }
+    this.pending.clear();
+  }
+
+  send(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (!this.child || this.child.killed) return Promise.reject(new Error('channel is closed'));
+    const id = this.nextId++;
+    const frame = { jsonrpc: '2.0', id, method, params: params ?? {} };
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out after ${timeoutMs} ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        this.child.stdin.write(JSON.stringify(frame) + '\n');
+      } catch (e) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  notify(method, params) {
+    if (!this.child || this.child.killed) return;
+    try {
+      this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params: params ?? {} }) + '\n');
+    } catch (e) {}
+  }
+
+  close() {
+    this.#failAll(new Error('channel closed'));
+    try { if (this.child) this.child.kill('SIGTERM'); } catch (e) {}
+    this.child = null;
+  }
+}
+
+/** A JSON-RPC channel over HTTP POST. One request, one response, no session. */
+export class HttpChannel {
+  constructor({ url, headers = {} }) {
+    this.url = url;
+    this.headers = headers;
+    this.nextId = 1;
+    this.notificationHandler = null;
+  }
+
+  async open() {
+    // Nothing to open. Validate the URL now so a typo fails at connect time
+    // rather than on the first tool call.
+    const parsed = new URL(this.url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(`unsupported transport protocol: ${parsed.protocol}`);
+    }
+  }
+
+  async send(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const response = await fetch(this.url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', ...this.headers },
+      body: JSON.stringify({ jsonrpc: '2.0', id: this.nextId++, method, params: params ?? {} }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status} from ${this.url}`);
+    const frame = await response.json();
+    if (frame.error) throw new Error(frame.error.message || 'JSON-RPC error');
+    return frame.result;
+  }
+
+  notify() { /* HTTP transport has no notification channel */ }
+  close() { /* nothing to close */ }
+}

package/src/mcp/mcpClient.js

@@ -0,0 +1,136 @@
+// Model Context Protocol client.
+//
+// WHY THIS EXISTS
+//
+// `src/tools/deferredMcpSearch.js` carries "mcp" in its name and is not an MCP
+// client — it searches Causyne's own tool registry. The only code in the tree
+// that spoke JSON-RPC was `palmierAutomator.js`, against one hardcoded server.
+// So the single largest extensibility lever every competing agent has was
+// missing, while the name suggested it was present.
+//
+// SECURITY POSTURE — read before changing anything here
+//
+// A client that launches third-party servers is the highest-risk pattern in
+// this codebase, so the boundary is drawn in exactly one place and stated
+// plainly:
+//
+//   * A server command NEVER comes from model output. Servers are read from
+//     `config.mcpServers`, which only the user writes. The model can ask for a
+//     configured server to be enabled; it cannot name a new one, cannot alter a
+//     command, and cannot pass arguments to a process launch.
+//   * Enabling a server requires the same human approval as any other
+//     consent-gated action (`sandbox.js` classifies `grant_mcp_server` with the
+//     download actions).
+//   * What the model DOES control is tool arguments, which is the entire point
+//     of the protocol — the same trust boundary as any other tool call.
+//
+// If a future change lets a server command originate anywhere other than user
+// config, that is a remote-code-execution hole, not a feature.
+
+import { StdioChannel, HttpChannel } from './jsonRpc.js';
+import { getPackageVersion } from '../version.js';
+
+const PROTOCOL_VERSION = '2025-06-18';
+const CLIENT_INFO = { name: 'causyne-agent', version: getPackageVersion() };
+
+export class McpClient {
+  /**
+   * @param {object} definition a user-configured server entry:
+   *   stdio: { name, command, args?, env?, cwd? }
+   *   http:  { name, url, headers? }
+   */
+  constructor(definition) {
+    this.name = definition.name;
+    this.definition = definition;
+    this.channel = null;
+    this.tools = [];
+    this.serverInfo = null;
+  }
+
+  static validateDefinition(definition) {
+    if (!definition || typeof definition !== 'object') return 'not an object';
+    if (typeof definition.name !== 'string' || !/^[a-z0-9_-]{1,48}$/i.test(definition.name)) {
+      return 'name must be 1-48 characters of [A-Za-z0-9_-]';
+    }
+    const hasStdio = typeof definition.command === 'string' && definition.command.length > 0;
+    const hasHttp = typeof definition.url === 'string' && definition.url.length > 0;
+    if (hasStdio === hasHttp) return 'exactly one of `command` (stdio) or `url` (http) is required';
+    if (hasStdio && !Array.isArray(definition.args || [])) return '`args` must be an array';
+    return null;
+  }
+
+  async connect() {
+    const problem = McpClient.validateDefinition(this.definition);
+    if (problem) throw new Error(`invalid server definition: ${problem}`);
+
+    this.channel = this.definition.url
+      ? new HttpChannel({ url: this.definition.url, headers: this.definition.headers })
+      : new StdioChannel({
+          command: this.definition.command,
+          args: this.definition.args || [],
+          env: this.definition.env || {},
+          cwd: this.definition.cwd
+        });
+
+    await this.channel.open();
+
+    const result = await this.channel.send('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      clientInfo: CLIENT_INFO
+    });
+    this.serverInfo = result?.serverInfo || null;
+
+    // Required by the protocol: the server may not serve requests until it has
+    // seen this.
+    this.channel.notify('notifications/initialized');
+
+    await this.listTools();
+    return this;
+  }
+
+  async listTools() {
+    const result = await this.channel.send('tools/list', {});
+    const raw = Array.isArray(result?.tools) ? result.tools : [];
+
+    // Only keep entries that are actually callable. A malformed advertisement
+    // reaching the model produces a tool it can call and we cannot dispatch —
+    // the exact failure mode D-6 was about, arriving from someone else's code.
+    this.tools = raw
+      .filter(t => t && typeof t.name === 'string' && t.name.length > 0)
+      .map(t => ({
+        name: t.name,
+        description: typeof t.description === 'string' ? t.description : '',
+        inputSchema: (t.inputSchema && typeof t.inputSchema === 'object')
+          ? t.inputSchema
+          : { type: 'object', properties: {} }
+      }));
+    return this.tools;
+  }
+
+  async callTool(toolName, args) {
+    const result = await this.channel.send('tools/call', { name: toolName, arguments: args ?? {} });
+
+    // MCP returns content blocks. Flatten text for the agent loop, and report an
+    // error result as an error rather than as successful output.
+    const blocks = Array.isArray(result?.content) ? result.content : [];
+    const text = blocks
+      .map(b => (b?.type === 'text' && typeof b.text === 'string') ? b.text : '')
+      .filter(Boolean)
+      .join('\n');
+
+    if (result?.isError) {
+      return { success: false, error: text || 'the MCP server reported an error' };
+    }
+    return {
+      success: true,
+      output: text || JSON.stringify(result ?? {}, null, 2)
+    };
+  }
+
+  close() {
+    try { if (this.channel) this.channel.close(); } catch (e) {}
+    this.channel = null;
+    this.tools = [];
+  }
+}