bare-agent 0.12.2 → 0.13.1

package/src/context-units.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// RT-1 — the msgs⇄units adapter for the `assemble` context-assembly seam (src/loop.js).
+//
+// Division of labour (litectx CE-PRD §8.2, line 321 — the frozen contract):
+//   - bareagent owns GRAMMAR: msgs→units, units→msgs, atomic bundling of a tool-call + its result(s),
+//     `pinned` flags, the pairing seatbelt, and fail-open. Broken tool-pairing and a dropped system
+//     prompt are UNREPRESENTABLE here, by construction — not by trusting the consumer.
+//   - litectx owns CONTENT + RELEVANCE: a single verb `assemble(units, ctx) → { units, dropped, tokens }`
+//     (the AssembleResult envelope — `dropped[]` is load-bearing, ships in the same slice, never silent)
+//     that does SELECT (keep / drop / reorder / recall-inject) + COMPRESS (rewrite a unit's `content`) +
+//     fit-to-`ctx.budget`, best-effort. It never learns the message grammar. `unitAssembler` unwraps `.units`.
+//
+// The neutral unit (the SOCKET litectx codes against — exactly these 7 enumerable fields):
+//   { id, role, content, kind, pinned, atomic, tokensApprox }
+//     id           — stable within one assemble() call; litectx references units by it.
+//     role         — 'system' | 'user' | 'assistant' | 'tool' (the message grammar role).
+//     content      — flat string view litectx reads to score and MAY rewrite to COMPRESS.
+//     kind         — litectx's memory-node kind ('code'|'doc'|'fact'|'episode') on units litectx
+//                    INJECTS from recall. Transcript-derived units carry `null` — and that is the
+//                    CORRECT value, not a placeholder. `role` and `kind` are orthogonal: `role`
+//                    (user/assistant/tool/system) carries conversational position = bareagent's
+//                    grammar, present on every unit; `kind` carries litectx's graph-node type, present
+//                    only on units litectx owns. Typing a live turn would force litectx to learn the
+//                    provider's conversation structure — the exact coupling the keystone boundary
+//                    forbids (PRD §1.2 / litectx CE-PRD §8.2). RATIFIED by litectx (2026-06-12): do
+//                    NOT define transcript-kinds. injected = kinded, transcript = null.
+//     pinned       — true ⇒ bareagent guarantees the unit is never dropped and never reordered
+//                    (system prompt, first user/task turn). litectx still sees its tokensApprox so the
+//                    pin counts against the budget: pin-don't-hide.
+//     atomic       — group-id (string) | null. litectx keeps/drops units sharing one group-id WHOLE,
+//                    never split. bareagent pre-bundles an assistant tool-call + ALL its result(s) into
+//                    one unit, so each bundle is its OWN group (group-id = the unit's id); everything
+//                    else is null. NOTE: string|null, not boolean — a boolean collapses every bundle
+//                    under one key and litectx would fit them all-or-nothing (test/context-units.test.js (real-litectx sweep)).
+//     tokensApprox — chars/4 estimate over the unit's backing messages, for litectx's budget math.
+//
+// `_msgs` (the verbatim backing messages) is attached NON-ENUMERABLE: it does not appear in the 7-field
+// view, JSON, or iteration. It is bareagent's reconstruction backing — litectx must not read it. A unit
+// with no backing (one litectx minted via recall-inject) is synthesised into a single message on the
+// way out.
+
+/** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */
+function approxTokens(msgs) {
+  let c = 0;
+  for (const m of msgs) {
+    if (m.content != null) c += String(m.content).length;
+    if (m.tool_calls) c += JSON.stringify(m.tool_calls).length;
+  }
+  return Math.ceil(c / 4);
+}
+
+/** Flat string view of a unit's backing messages — what litectx scores on and may rewrite. */
+function renderContent(msgs) {
+  const parts = [];
+  for (const m of msgs) {
+    if (m.content != null && String(m.content).length) parts.push(String(m.content));
+  }
+  return parts.join('\n');
+}
+
+let _seq = 0;
+/** Attach the verbatim backing + original-content fingerprint as non-enumerable carry. */
+function withBacking(unit, msgs) {
+  Object.defineProperty(unit, '_msgs', { value: msgs, enumerable: false, writable: true });
+  Object.defineProperty(unit, '_origContent', { value: unit.content, enumerable: false, writable: true });
+  return unit;
+}
+
+/**
+ * msgs → neutral units. Bundles each assistant-tool-call message with the contiguous tool result(s)
+ * that answer its ids into ONE atomic unit (so pairing can never be split). system + first user turn
+ * are pinned.
+ * @param {Array<Record<string, any>>} msgs
+ * @returns {Array<Record<string, any>>}
+ */
+function toUnits(msgs) {
+  const units = [];
+  let seenUser = false;
+  for (let i = 0; i < msgs.length; i++) {
+    const m = msgs[i];
+
+    if (m.role === 'system') {
+      units.push(withBacking({ id: `u${_seq++}`, role: 'system', content: renderContent([m]), kind: null, pinned: true, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+      continue;
+    }
+    if (m.role === 'user') {
+      const pinned = !seenUser; // first user turn = the task; pin it
+      seenUser = true;
+      units.push(withBacking({ id: `u${_seq++}`, role: 'user', content: renderContent([m]), kind: null, pinned, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+      continue;
+    }
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      // bundle this assistant message with the contiguous tool results answering its ids
+      const ids = new Set(m.tool_calls.map((t) => t.id));
+      const group = [m];
+      let j = i + 1;
+      while (j < msgs.length && msgs[j].role === 'tool' && ids.has(msgs[j].tool_call_id)) {
+        group.push(msgs[j]);
+        j++;
+      }
+      // `atomic` is litectx's group-id (string|null), NOT a boolean: units sharing one are kept/dropped
+      // whole. bareagent already pre-bundles a tool-call + its result(s) into ONE unit, so each bundle is
+      // its OWN group — group-id = the unit's id. (A boolean would collapse every bundle under one key,
+      // making litectx fit them all-or-nothing — see test/context-units.test.js (real-litectx sweep).)
+      const gid = `u${_seq++}`;
+      units.push(withBacking({ id: gid, role: 'assistant', content: renderContent(group.slice(1)), kind: null, pinned: false, atomic: gid, tokensApprox: approxTokens(group) }, group));
+      i = j - 1;
+      continue;
+    }
+    // plain assistant text, or a stray tool message (handled by the seatbelt on the way out)
+    units.push(withBacking({ id: `u${_seq++}`, role: m.role, content: renderContent([m]), kind: null, pinned: false, atomic: null, tokensApprox: approxTokens([m]) }, [m]));
+  }
+  return units;
+}
+
+/**
+ * Drop any tool-result whose tool_call_id has no open assistant tool-call before it, and any assistant
+ * tool-call message left with zero surviving results. The final grammar guard: even if litectx hands
+ * back something that would orphan a pair, the wire is always valid. Returns a fresh array.
+ */
+function pairingSeatbelt(msgs) {
+  // pass 1: which tool_call ids actually have a result present?
+  const resultIds = new Set();
+  for (const m of msgs) if (m.role === 'tool' && m.tool_call_id != null) resultIds.add(m.tool_call_id);
+
+  const out = [];
+  const open = new Set();
+  for (const m of msgs) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+      const surviving = m.tool_calls.filter((tc) => resultIds.has(tc.id));
+      if (!surviving.length) continue; // assistant tool-call with no results at all → drop the message
+      for (const tc of surviving) open.add(tc.id);
+      out.push(surviving.length === m.tool_calls.length ? m : { ...m, tool_calls: surviving });
+      continue;
+    }
+    if (m.role === 'tool') {
+      if (!open.has(m.tool_call_id)) continue; // orphan result → drop
+      open.delete(m.tool_call_id);
+      out.push(m);
+      continue;
+    }
+    out.push(m);
+  }
+  return out;
+}
+
+/**
+ * units → msgs. Honors drop (absent units), reorder (order of the returned array), recall-inject
+ * (units with no backing → one synthesised message), and COMPRESS (a unit whose `content` was rewritten
+ * is reconstructed from the new content). Atomic units keep their assistant tool-call message verbatim
+ * so pairing holds; a content rewrite lands on the tool RESULT. A multi-result atomic bundle whose
+ * content was rewritten is kept VERBATIM — a flat string can't be faithfully split back into N
+ * results, and splitting is grammar (bareagent's), not litectx's to attempt. This isn't a special
+ * case: litectx's compress() is a pure text→text render that returns verbatim when handed no single
+ * parseable format (compress.js — "never returns less than the body losslessly"), so a flattened
+ * multi-result unit round-trips unchanged on both sides. RATIFIED by litectx (2026-06-12). The pairing
+ * seatbelt is the final guard.
+ * @param {Array<Record<string, any>>} units
+ * @returns {Array<Record<string, any>>}
+ */
+function fromUnits(units) {
+  const msgs = [];
+  for (const u of units) {
+    if (!u || typeof u !== 'object') continue;
+    const backing = u._msgs;
+
+    if (!Array.isArray(backing)) {
+      // litectx-minted (recall-inject): synthesise one message from role + content
+      msgs.push({ role: u.role || 'user', content: u.content == null ? '' : String(u.content) });
+      continue;
+    }
+
+    const edited = u.content !== u._origContent;
+    if (!edited) {
+      for (const m of backing) msgs.push(m); // verbatim — preserves tool_call_id pairing exactly
+      continue;
+    }
+
+    if (!u.atomic) {
+      // single backing message, content rewritten
+      msgs.push({ ...backing[0], content: u.content == null ? '' : String(u.content) });
+      continue;
+    }
+
+    // atomic + content rewritten: assistant message stays verbatim (pairing); rewrite lands on the
+    // single result. Multi-result bundle → keep verbatim (unsplittable).
+    const results = backing.slice(1);
+    if (results.length === 1) {
+      msgs.push(backing[0]);
+      msgs.push({ ...results[0], content: u.content == null ? '' : String(u.content) });
+    } else {
+      for (const m of backing) msgs.push(m);
+    }
+  }
+  return pairingSeatbelt(msgs);
+}
+
+/**
+ * Wrap litectx's `assemble(units, ctx)` verb into the Loop's msgs-level `assemble(msgs, ctx)` seam.
+ * litectx ships the **`AssembleResult` envelope** `{ units, dropped, tokens }` (CE-PRD §8.2: `dropped[]`
+ * is load-bearing — it ships in the same slice, never silently truncated). This wrapper accepts that
+ * envelope (uses `.units`) OR a bare `units` array (a simpler consumer). `dropped`/`tokens` are litectx's
+ * accounting; the Loop's seam is msgs-in/msgs-out, so they're not threaded onward here (the canonical
+ * transcript already holds every dropped unit by id — restorable on demand).
+ * Fail-OPEN at this layer too: any other return shape → the original msgs are sent unchanged. A thrown
+ * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
+ * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
+ * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ */
+function unitAssembler(assembleUnits) {
+  if (typeof assembleUnits !== 'function') {
+    throw new Error('[context-units] unitAssembler(fn): fn must be (units, ctx) => units');
+  }
+  return async (msgs, ctx) => {
+    const units = toUnits(msgs);
+    const out = await assembleUnits(units, ctx);
+    // litectx returns { units, dropped, tokens }; a bare array is also accepted. Anything else → fail-open.
+    const view = Array.isArray(out) ? out : (out && Array.isArray(out.units) ? out.units : null);
+    if (!view) return msgs; // fail-open: unrecognised return → full context
+    return fromUnits(view);
+  };
+}
+
+module.exports = { toUnits, fromUnits, unitAssembler, approxTokens, pairingSeatbelt };

package/src/loop.d.ts

@@ -20,6 +20,16 @@ export type LoopOptions = {
     onError?: Function | undefined;
     throwOnError?: boolean | undefined;
     policy?: Function | undefined;
+    /**
+     * - async (msgs, ctx) => msgs. Context-assembly chokepoint: shape the
+     * window sent to the provider each round (e.g. a context-engineering library). Returns a VIEW — the
+     * canonical transcript is never mutated. Fail-open (a thrown error degrades to full context); a
+     * thrown HaltError propagates. `ctx` is the per-run opaque blob (`run(msgs, tools, { ctx })`), the
+     * same object forwarded to `policy`; litectx reads `ctx.task` (intent) and `ctx.budget`. The
+     * neutral-unit signature `assemble(units, ctx)` is provided by bareagent's msgs⇄units adapter
+     * (src/context-units.js), which composes over this msgs-level seam.
+     */
+    assemble?: Function | undefined;
     onLlmResult?: Function | undefined;
     onToolResult?: Function | undefined;
     /**
@@ -49,6 +59,7 @@ export class Loop {
     throwOnError: boolean;
     store: import("../types").Store | null;
     policy: Function | null;
+    assemble: Function | null;
     onLlmResult: Function | null;
     onToolResult: Function | null;
     _stopped: boolean;

package/src/loop.js

@@ -26,6 +26,13 @@ const { ToolError, HaltError } = require('./errors');
  * @property {Function} [onError]
  * @property {boolean} [throwOnError]
  * @property {Function} [policy]
+ * @property {Function} [assemble] - async (msgs, ctx) => msgs. Context-assembly chokepoint: shape the
+ *   window sent to the provider each round (e.g. a context-engineering library). Returns a VIEW — the
+ *   canonical transcript is never mutated. Fail-open (a thrown error degrades to full context); a
+ *   thrown HaltError propagates. `ctx` is the per-run opaque blob (`run(msgs, tools, { ctx })`), the
+ *   same object forwarded to `policy`; litectx reads `ctx.task` (intent) and `ctx.budget`. The
+ *   neutral-unit signature `assemble(units, ctx)` is provided by bareagent's msgs⇄units adapter
+ *   (src/context-units.js), which composes over this msgs-level seam.
  * @property {Function} [onLlmResult]
  * @property {Function} [onToolResult]
  * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
@@ -132,6 +139,10 @@ class Loop {
       throw new Error('[Loop] options.policy must be a function (toolName, args, ctx) => true | string');
     }
     this.policy = options.policy || null;
+    if (options.assemble != null && typeof options.assemble !== 'function') {
+      throw new Error('[Loop] options.assemble must be a function (msgs, info) => msgs');
+    }
+    this.assemble = options.assemble || null;
     if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
       throw new Error('[Loop] options.onLlmResult must be a function');
     }
@@ -243,10 +254,29 @@ class Loop {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
+      // RT-1: context-assembly chokepoint. Let a caller (e.g. a context-engineering library) shape
+      // the window sent to the provider this round. Returns a VIEW — the canonical `msgs` transcript
+      // is never mutated, so result.msgs stays complete and correct. Fail-OPEN: an assembly error
+      // degrades to sending full context (a context-optimizer bug must not halt the agent); a thrown
+      // HaltError is a governance exit and propagates (same contract as onLlmResult).
+      let toSend = msgs;
+      if (this.assemble) {
+        try {
+          const view = await this.assemble(msgs, ctx);
+          if (Array.isArray(view)) {
+            toSend = view;
+            this._safeEmit({ type: 'loop:assemble', data: { round, before: msgs.length, after: toSend.length } });
+          }
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('assemble', err, { round });
+        }
+      }
+
       let result;
       const llmStartedAt = Date.now();
       try {
-        const generate = () => this.provider.generate(msgs, tools, options);
+        const generate = () => this.provider.generate(toSend, tools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
         this._reportError('provider', err, { round });

package/src/mcp-bridge.d.ts

@@ -52,7 +52,7 @@ export type DeniedTool = {
  * JSON-RPC stdio client over a spawned MCP server.
  */
 export type RpcClient = {
-    rpc: (method: string, params?: object) => Promise<any>;
+    rpc: (method: string, params?: object, timeoutMs?: number) => Promise<any>;
     notify: (method: string, params?: object) => void;
     child: import("node:child_process").ChildProcessWithoutNullStreams;
     stderr: string;
@@ -76,7 +76,9 @@ export type RpcClient = {
  * @param {string} [opts.bridgePath] - Path to .mcp-bridge.json. Default: .mcp-bridge.json in cwd.
  * @param {string[]} [opts.configPaths] - IDE config paths for discovery.
  * @param {string[]} [opts.servers] - Limit to these server names.
- * @param {number} [opts.timeout=15000] - Per-server init timeout in ms.
+ * @param {number} [opts.timeout=15000] - Per-server handshake timeout in ms (initialize + tools/list).
+ * @param {number} [opts.callTimeout=120000] - Per-invocation timeout in ms for tools/call. Bounds a
+ *   server that accepts a tool call but never responds. Set 0 to disable (unbounded).
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
  * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer]
  *   Vet each discovered server BEFORE its `command` is spawned. Connecting to an
@@ -92,6 +94,7 @@ export function createMCPBridge(opts?: {
     configPaths?: string[] | undefined;
     servers?: string[] | undefined;
     timeout?: number | undefined;
+    callTimeout?: number | undefined;
     refresh?: boolean | undefined;
     confirmServer?: ((name: string, def: ServerDef) => boolean | Promise<boolean>) | undefined;
 }): Promise<{

package/src/mcp-bridge.js

@@ -54,7 +54,7 @@ const { ToolError } = require('./errors');
 /**
  * JSON-RPC stdio client over a spawned MCP server.
  * @typedef {object} RpcClient
- * @property {(method: string, params?: object) => Promise<any>} rpc
+ * @property {(method: string, params?: object, timeoutMs?: number) => Promise<any>} rpc
  * @property {(method: string, params?: object) => void} notify
  * @property {import('node:child_process').ChildProcessWithoutNullStreams} child
  * @property {string} stderr
@@ -215,11 +215,25 @@ function createRpcClient(name, def) {
     ...(cwd && { cwd }),
   });
 
-  /** @type {Map<number, {resolve: (v: any) => void, reject: (e: any) => void}>} */
+  /** @type {Map<number, {resolve: (v: any) => void, reject: (e: any) => void, timer: NodeJS.Timeout | null}>} */
   const pending = new Map();
   let nextId = 1;
   let buffer = '';
 
+  // Settle a pending request exactly once, clearing its timeout timer. Returns
+  // false if the id was already settled (response/close/timeout raced) so callers
+  // can avoid double-settling. Every settle path (response, close, write error,
+  // timeout) funnels through here.
+  /** @param {number} id @param {boolean} ok @param {any} payload @returns {boolean} */
+  function settle(id, ok, payload) {
+    const p = pending.get(id);
+    if (!p) return false;
+    pending.delete(id);
+    if (p.timer) clearTimeout(p.timer);
+    if (ok) p.resolve(payload); else p.reject(payload);
+    return true;
+  }
+
   child.stdout.setEncoding('utf8');
   child.stdout.on('data', (chunk) => {
     buffer += chunk;
@@ -231,15 +245,12 @@ function createRpcClient(name, def) {
       let msg;
       try { msg = JSON.parse(line); } catch { continue; }
       if (!msg.id) continue;
-      const p = pending.get(msg.id);
-      if (!p) continue;
-      pending.delete(msg.id);
       if (msg.error) {
-        p.reject(new ToolError(`MCP server "${name}": ${msg.error.message}`, {
+        settle(msg.id, false, new ToolError(`MCP server "${name}": ${msg.error.message}`, {
           context: { code: msg.error.code },
         }));
       } else {
-        p.resolve(msg.result);
+        settle(msg.id, true, msg.result);
       }
     }
   });
@@ -248,24 +259,49 @@ function createRpcClient(name, def) {
   child.stderr?.setEncoding('utf8');
   child.stderr?.on('data', (chunk) => { stderrBuf += chunk; });
 
+  // A child can exit (crash, fast-exit before init, killed) at any moment.
+  // Writing to its stdin then emits an 'error' on the pipe; with NO listener,
+  // Node re-throws it as an uncaught exception and takes down the HOST process.
+  // Swallow it here — pending rpc()s are rejected by the 'close' handler below,
+  // and rpc()/notify() guard writability before writing.
+  child.stdin.on('error', () => { /* child gone; surfaced via close + write guards */ });
+
   child.on('close', (code) => {
-    for (const [id, { reject }] of pending) {
-      reject(new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
+    for (const id of [...pending.keys()]) {
+      settle(id, false, new ToolError(`MCP server "${name}" exited (code ${code}). stderr: ${stderrBuf.slice(-500)}`));
     }
-    pending.clear();
   });
 
   /**
+   * Send a JSON-RPC request and await its response. Bounded by `timeoutMs`: a
+   * server that accepts the write but never answers (or answers a different id)
+   * would otherwise hang the caller forever — only `initialize` used to be
+   * bounded, leaving `tools/list` and `tools/call` open-ended. Pass 0 to disable.
    * @param {string} method
    * @param {object} [params]
+   * @param {number} [timeoutMs=0] - Reject if no response arrives within this many ms (0 = no limit).
    * @returns {Promise<any>}
    */
-  function rpc(method, params = {}) {
+  function rpc(method, params = {}, timeoutMs = 0) {
     const id = nextId++;
     return new Promise((resolve, reject) => {
-      pending.set(id, { resolve, reject });
+      if (!child.stdin.writable) {
+        return reject(new ToolError(`MCP server "${name}" stdin is not writable (process exited or pipe closed). stderr: ${stderrBuf.slice(-500)}`));
+      }
+      /** @type {NodeJS.Timeout | null} */
+      let timer = null;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          settle(id, false, new ToolError(`MCP server "${name}" "${method}" timed out after ${timeoutMs}ms. stderr: ${stderrBuf.slice(-500)}`));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+      pending.set(id, { resolve, reject, timer });
       const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
-      child.stdin.write(msg);
+      child.stdin.write(msg, (err) => {
+        // settle() no-ops if 'close'/timeout already settled this id.
+        if (err) settle(id, false, new ToolError(`MCP server "${name}" write failed: ${err.message}. stderr: ${stderrBuf.slice(-500)}`));
+      });
     });
   }
 
@@ -274,8 +310,9 @@ function createRpcClient(name, def) {
    * @param {object} [params]
    */
   function notify(method, params = {}) {
+    if (!child.stdin.writable) return;
     const msg = JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n';
-    child.stdin.write(msg);
+    child.stdin.write(msg, () => { /* write errors swallowed via stdin 'error' handler */ });
   }
 
   return { rpc, notify, child, get stderr() { return stderrBuf; } };
@@ -301,16 +338,17 @@ function unwrapContent(content) {
 /**
  * @param {string} serverName
  * @param {McpTool[]} mcpTools
- * @param {(method: string, params?: object) => Promise<any>} rpc
+ * @param {(method: string, params?: object, timeoutMs?: number) => Promise<any>} rpc
+ * @param {number} [callTimeout=0] - Per-invocation timeout (ms) for tools/call; 0 = no limit.
  * @returns {ToolDef[]}
  */
-function wrapTools(serverName, mcpTools, rpc) {
+function wrapTools(serverName, mcpTools, rpc, callTimeout = 0) {
   return mcpTools.map(t => ({
     name: `${serverName}_${t.name}`,
     description: t.description || '',
     parameters: t.inputSchema || { type: 'object', properties: {} },
     execute: async (args) => {
-      const result = await rpc('tools/call', { name: t.name, arguments: args });
+      const result = await rpc('tools/call', { name: t.name, arguments: args }, callTimeout);
       if (result.isError) {
         throw new ToolError(unwrapContent(result.content) || 'MCP tool error', {
           context: { server: serverName, tool: t.name },
@@ -374,21 +412,17 @@ async function connectAndListTools(name, def, timeout = 15000) {
   const client = createRpcClient(name, def);
 
   try {
-    const init = client.rpc('initialize', {
+    // Both handshake round-trips are bounded by `timeout`. tools/list used to be
+    // unbounded — a server that answered initialize but never replied to
+    // tools/list would hang discovery (and the whole bridge) indefinitely.
+    await client.rpc('initialize', {
       protocolVersion: '2024-11-05',
       capabilities: {},
       clientInfo: { name: 'bare-agent', version: '0.5.0' },
-    });
-
-    let timerId;
-    const timer = new Promise((_, reject) => {
-      timerId = setTimeout(() => reject(new ToolError(`MCP server "${name}" init timed out after ${timeout}ms`)), timeout);
-    });
-
-    try { await Promise.race([init, timer]); } finally { clearTimeout(timerId); }
+    }, timeout);
     client.notify('notifications/initialized');
 
-    const { tools: mcpTools } = await client.rpc('tools/list');
+    const { tools: mcpTools } = await client.rpc('tools/list', {}, timeout);
 
     return { mcpTools, client };
   } catch (err) {
@@ -562,7 +596,9 @@ function buildMetaTools(tools, discoveredAt) {
  * @param {string} [opts.bridgePath] - Path to .mcp-bridge.json. Default: .mcp-bridge.json in cwd.
  * @param {string[]} [opts.configPaths] - IDE config paths for discovery.
  * @param {string[]} [opts.servers] - Limit to these server names.
- * @param {number} [opts.timeout=15000] - Per-server init timeout in ms.
+ * @param {number} [opts.timeout=15000] - Per-server handshake timeout in ms (initialize + tools/list).
+ * @param {number} [opts.callTimeout=120000] - Per-invocation timeout in ms for tools/call. Bounds a
+ *   server that accepts a tool call but never responds. Set 0 to disable (unbounded).
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
  * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer]
  *   Vet each discovered server BEFORE its `command` is spawned. Connecting to an
@@ -583,6 +619,8 @@ async function createMCPBridge(opts = {}) {
   }
   const bridgePath = opts.bridgePath || DEFAULT_BRIDGE_PATH();
   const timeout = opts.timeout || 15000;
+  // 0 is a valid explicit "unbounded"; only undefined falls back to the default.
+  const callTimeout = opts.callTimeout ?? 120000;
 
   // Vet a server before spawning its command. Fail-closed: an undefined hook
   // trusts all (unchanged behavior); a throw denies.
@@ -594,6 +632,24 @@ async function createMCPBridge(opts = {}) {
     catch { return false; }
   };
 
+  // Connecting to a server EXECUTES its `command`, which can originate from a
+  // cwd-relative .mcp.json in an untrusted repo (discoverServers reads project
+  // configs). With no confirmServer hook, every discovered command runs unvetted.
+  // Warn ONCE per call, BEFORE the first spawn — and the first spawn is the
+  // discovery phase on a cold/refresh run, not the main-connect phase below.
+  let warnedUnvetted = false;
+  /** @param {Array<{name: string, command: string, args?: string[]}>} specs */
+  const warnUnvettedSpawn = (specs) => {
+    if (confirmServer || warnedUnvetted || specs.length === 0) return;
+    warnedUnvetted = true;
+    const cmds = specs.map(s => `${s.name} → ${s.command} ${(s.args || []).join(' ')}`.trim());
+    console.warn(
+      `[MCP Bridge] spawning ${specs.length} server command(s) without a confirmServer hook:\n  ` +
+      cmds.join('\n  ') +
+      `\n  Pass { confirmServer } to vet each command before it runs.`,
+    );
+  };
+
   let config = readBridgeConfig(bridgePath);
   const needsRefresh = opts.refresh || !config || isExpired(config);
 
@@ -621,6 +677,8 @@ async function createMCPBridge(opts = {}) {
         ? [...discovered.entries()].filter(([n]) => reqServers.includes(n))
         : [...discovered.entries()];
 
+      warnUnvettedSpawn(toDiscover.map(([name, def]) => ({ name, command: def.command, args: def.args })));
+
       await Promise.all(toDiscover.map(async ([name, def]) => {
         try {
           // Denied by confirmServer: skip silently — this is the caller's own
@@ -674,6 +732,11 @@ async function createMCPBridge(opts = {}) {
     return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
   }
 
+  // Warn before the main-connect spawn too. On a warm run (config exists, no
+  // refresh) this is the first and only spawn; on a cold run the discovery phase
+  // already warned, so the once-flag makes this a no-op.
+  warnUnvettedSpawn(serverNames.map(n => ({ name: n, command: cfg.servers[n].command, args: cfg.servers[n].args })));
+
   // Connect to servers and wrap only allowed tools
   /** @type {ToolDef[]} */
   const tools = [];
@@ -702,7 +765,7 @@ async function createMCPBridge(opts = {}) {
 
       // Only wrap tools that are allowed in config
       const allowed = mcpTools.filter(t => allowedToolNames.includes(t.name));
-      const wrapped = wrapTools(name, allowed, client.rpc);
+      const wrapped = wrapTools(name, allowed, client.rpc, callTimeout);
 
       tools.push(...wrapped);
       children.push(client.child);

package/src/provider-openai.d.ts

@@ -15,10 +15,6 @@ export type OpenAIOptions = {
      */
     exposeErrorBody?: boolean | undefined;
 };
-/** @typedef {import('../types').Message} Message */
-/** @typedef {import('../types').ToolDef} ToolDef */
-/** @typedef {import('../types').ToolCall} ToolCall */
-/** @typedef {import('../types').GenerateResult} GenerateResult */
 /**
  * @typedef {object} OpenAIOptions
  * @property {string} [apiKey]
@@ -54,4 +50,5 @@ export class OpenAIProvider {
      * @returns {Promise<any>}
      */
     _request(path: string, body: Record<string, any>): Promise<any>;
+    _warnedInsecure: boolean | undefined;
 }

package/src/provider-openai.js

@@ -9,6 +9,12 @@ const { ProviderError } = require('./errors');
 /** @typedef {import('../types').ToolCall} ToolCall */
 /** @typedef {import('../types').GenerateResult} GenerateResult */
 
+/** @param {string} hostname @returns {boolean} */
+function isLoopbackHost(hostname) {
+  const h = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
 /**
  * @typedef {object} OpenAIOptions
  * @property {string} [apiKey]
@@ -84,6 +90,17 @@ class OpenAIProvider {
       const transport = url.protocol === 'https:' ? https : http;
       const payload = JSON.stringify(body);
 
+      // Sending a Bearer key over plaintext http to a non-loopback host exposes
+      // it to anyone on-path. Loopback (local proxies / Ollama-style endpoints)
+      // is the legitimate keyless case, so only warn for remote http. Warn once.
+      if (this.apiKey && url.protocol === 'http:' && !isLoopbackHost(url.hostname) && !this._warnedInsecure) {
+        this._warnedInsecure = true;
+        console.warn(
+          `[OpenAIProvider] sending Authorization key over PLAINTEXT http to ${url.hostname} — ` +
+          `the key is exposed on the wire. Use https, or drop the apiKey for keyless local endpoints.`,
+        );
+      }
+
       const req = transport.request(url, {
         method: 'POST',
         headers: {

package/src/tools.d.ts

@@ -5,4 +5,5 @@ import { createSpawnTool } from "../tools/spawn";
 import { spawnChild } from "../tools/spawn";
 import { createDeferTool } from "../tools/defer";
 import { readQueue as readDeferQueue } from "../tools/defer";
-export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue };
+import { liteCtxMcpBridgeConfig } from "../tools/litectx-mcp";
+export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue, liteCtxMcpBridgeConfig };

package/src/tools.js

@@ -5,6 +5,7 @@ const { createMobileTools } = require('../tools/mobile');
 const { createShellTools } = require('../tools/shell');
 const { createSpawnTool, spawnChild } = require('../tools/spawn');
 const { createDeferTool, readQueue: readDeferQueue } = require('../tools/defer');
+const { liteCtxMcpBridgeConfig } = require('../tools/litectx-mcp');
 
 module.exports = {
   createBrowsingTools,
@@ -14,4 +15,5 @@ module.exports = {
   spawnChild,
   createDeferTool,
   readDeferQueue,
+  liteCtxMcpBridgeConfig,
 };