bare-agent 0.10.4 → 0.12.0

package/src/loop.js

@@ -2,8 +2,38 @@
 
 const { ToolError, HaltError } = require('./errors');
 
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').ToolCall} ToolCall */
+/** @typedef {import('../types').Usage} Usage */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+/** @typedef {import('../types').Store} Store */
+/** @typedef {import('./checkpoint').Checkpoint} Checkpoint */
+/** @typedef {import('./retry').Retry} Retry */
+/** @typedef {import('./stream').Stream} Stream */
+
+/**
+ * @typedef {object} LoopOptions
+ * @property {Provider} provider
+ * @property {string} [system]
+ * @property {Checkpoint} [checkpoint]
+ * @property {Retry} [retry]
+ * @property {Stream} [stream]
+ * @property {Store} [store]
+ * @property {Function} [onToolCall]
+ * @property {Function} [onText]
+ * @property {Function} [onError]
+ * @property {boolean} [throwOnError]
+ * @property {Function} [policy]
+ * @property {Function} [onLlmResult]
+ * @property {Function} [onToolResult]
+ * @property {number} [maxRounds] - Removed in v0.8; presence throws a migration error.
+ */
+
 // Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
 // Last updated: 2026-05-18. Source: public provider pricing pages.
+/** @type {Record<string, {in: number, out: number}>} */
 const COST_PER_1K = {
   // OpenAI
   'gpt-4o': { in: 0.0025, out: 0.01 },
@@ -33,6 +63,10 @@ const HARD_ROUND_LIMIT = 100;
 // synthetic `role:'tool'` reply for every tool_call_id that has no matching
 // reply. Halt-path only — keeps msgs a valid OpenAI transcript when the loop
 // exits between pushing assistant.tool_calls and finishing the per-tool loop.
+/**
+ * @param {Message[]} msgs
+ * @param {string} rule
+ */
 function sealDanglingToolCalls(msgs, rule) {
   for (let i = msgs.length - 1; i >= 0; i--) {
     const m = msgs[i];
@@ -50,6 +84,11 @@ function sealDanglingToolCalls(msgs, rule) {
   }
 }
 
+/**
+ * @param {string|null} model
+ * @param {Usage|null} usage
+ * @returns {number|null}
+ */
 function estimateCost(model, usage) {
   if (!usage || !model) return null;
   const rates = COST_PER_1K[model] || COST_PER_1K['_default'];
@@ -61,19 +100,15 @@ function estimateCost(model, usage) {
 
 class Loop {
   /**
-   * @param {object} options
-   * @param {object} options.provider - LLM provider (must implement generate()).
-   * @param {string} [options.system] - System prompt prepended to messages.
-   * @param {object} [options.checkpoint] - Checkpoint instance for human-in-the-loop.
-   * @param {object} [options.retry] - Retry instance for backoff on failures.
-   * @param {object} [options.stream] - Stream instance for event emission.
-   * @param {object} [options.store] - Store instance for validate() health check.
-   * @param {Function} [options.policy] - Async (toolName, args, ctx) => true | string. Recommended wiring: closure that delegates to a bareguard Gate (`require('bare-agent/bareguard').wireGate(gate).policy`). Anything other than `true` denies; a string is fed to the LLM verbatim as the deny reason. A throw of `HaltError` exits the loop cleanly. All policy/budget/audit decisions live in bareguard — Loop just calls the closure and respects the verdict.
-   * @param {Function} [options.onLlmResult] - Async ({model, provider, usage, costUsd, durationMs, ctx}) called after every successful provider.generate. Wire via `wireGate(gate).onLlmResult` so `budget.maxCostUsd` covers token-only workloads. Errors route through `_reportError` but never kill the loop.
-   * @param {Function} [options.onToolResult] - Async ({name, args, result, error, durationMs, ctx}) called after every tool.execute (success and failure). Wire via `wireGate(gate).onToolResult` so `gate.record` sees `ctx`. Errors route through `_reportError` but never kill the loop.
+   * `policy` is async `(toolName, args, ctx) => true | string`. Recommended wiring: a closure
+   * that delegates to a bareguard Gate (`require('bare-agent/bareguard').wireGate(gate).policy`).
+   * Anything other than `true` denies; a string is fed to the LLM verbatim as the deny reason.
+   * A throw of `HaltError` exits the loop cleanly. `onLlmResult`/`onToolResult` forward usage and
+   * tool outcomes to `gate.record` (via wireGate) and never kill the loop on error.
+   * @param {LoopOptions} options
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
    */
-  constructor(options = {}) {
+  constructor(options = /** @type {LoopOptions} */ ({})) {
     if (!options.provider) throw new Error('[Loop] requires a provider');
     if (options.maxRounds !== undefined) {
       throw new Error(
@@ -106,12 +141,18 @@ class Loop {
     this.onLlmResult = options.onLlmResult || null;
     this.onToolResult = options.onToolResult || null;
     this._stopped = false;
+    /** @type {Message[]} */
     this._history = []; // for chat() stateful mode
   }
 
   // Unified error emitter — every silent-ish failure path routes through here so
   // operators see callback throws, checkpoint timeouts, stream listener errors
   // in one place: loop:error stream event + onError callback.
+  /**
+   * @param {string} source
+   * @param {any} err
+   * @param {Record<string, any>} [extra]
+   */
   _reportError(source, err, extra = {}) {
     const message = err?.message || String(err);
     this._safeEmit({ type: 'loop:error', data: { source, error: message, ...extra } });
@@ -125,6 +166,7 @@ class Loop {
   }
 
   // Swallow-proof stream emit: a throwing listener must not corrupt Loop state.
+  /** @param {{type: string, data?: any, ts?: string}} event */
   _safeEmit(event) {
     if (!this.stream) return;
     try {
@@ -138,6 +180,11 @@ class Loop {
   }
 
   // Fire a user callback without letting its throw kill the loop.
+  /**
+   * @param {string} name
+   * @param {Function|null} fn
+   * @param {...any} args
+   */
   _safeCall(name, fn, ...args) {
     if (!fn) return;
     try {
@@ -149,10 +196,10 @@ class Loop {
 
   /**
    * Run the think/act/observe loop.
-   * @param {Array<object>} messages - Conversation messages in OpenAI format.
-   * @param {Array<object>} [tools=[]] - Tool definitions with name, execute, description, parameters.
-   * @param {object} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object, cost: number, error: string|null, msgs: Array<object>}>}
+   * @param {Message[]} messages - Conversation messages in OpenAI format.
+   * @param {ToolDef[]} [tools=[]] - Tool definitions with name, execute, description, parameters.
+   * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[]}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -244,7 +291,7 @@ class Loop {
       msgs.push({
         role: 'assistant',
         content: result.text || null,
-        tool_calls: result.toolCalls.map(tc => ({
+        tool_calls: result.toolCalls.map((/** @type {ToolCall} */ tc) => ({
           id: tc.id,
           type: 'function',
           function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
@@ -279,7 +326,13 @@ class Loop {
             continue;
           }
           this._safeEmit({ type: 'checkpoint:reply', data: { reply } });
-          if (!reply || reply.toLowerCase() === 'no' || reply.toLowerCase() === 'n') {
+          // Fail-closed: approve ONLY on an explicit affirmative. Any other reply —
+          // an unrecognized string ("denied", "wait"), empty, or a non-string — denies.
+          // A human approval gate must never approve on ambiguous input, and reading
+          // .toLowerCase() off a non-string here used to throw out of run().
+          const approved = typeof reply === 'string'
+            && ['yes', 'y', 'approve', 'approved'].includes(reply.trim().toLowerCase());
+          if (!approved) {
             msgs.push({ role: 'tool', tool_call_id: tc.id, content: 'User denied this action.' });
             continue;
           }
@@ -375,11 +428,12 @@ class Loop {
 
   /**
    * Health check — validates provider, store, and tools without throwing.
-   * @param {Array<object>} [tools=[]] - Tool definitions to validate.
+   * @param {ToolDef[]} [tools=[]] - Tool definitions to validate.
    * @returns {Promise<{provider: {ok: boolean, error?: string}, store: {ok: boolean, error?: string, skipped: boolean}, tools: {ok: boolean, errors?: string[]}}>}
    * Never throws — all failures captured in return value.
    */
   async validate(tools = []) {
+    /** @type {{provider: {ok: boolean, error?: string}, store: {ok: boolean, error?: string, skipped: boolean}, tools: {ok: boolean, errors?: string[]}}} */
     const result = {
       provider: { ok: false },
       store: { ok: false, skipped: false },
@@ -415,6 +469,7 @@ class Loop {
     }
 
     // Tools check
+    /** @type {string[]} */
     const toolErrors = [];
     for (const tool of tools) {
       if (typeof tool.name !== 'string' || !tool.name) {
@@ -436,6 +491,13 @@ class Loop {
     return result;
   }
 
+  /**
+   * Stateful single-turn chat that maintains conversation history across calls.
+   * @param {string} text - User message.
+   * @param {ToolDef[]} [tools=[]] - Tool definitions.
+   * @param {Record<string, any>} [options={}] - Per-run overrides.
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, msgs: Message[]}>}
+   */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });
     const result = await this.run(this._history, tools, options);

package/src/mcp-bridge.d.ts

@@ -0,0 +1,133 @@
+export type ToolDef = import("../types").ToolDef;
+/**
+ * A server definition as found in an IDE/MCP config file.
+ */
+export type ServerDef = {
+    command: string;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+};
+/**
+ * Raw tool descriptor as returned by an MCP server's tools/list.
+ */
+export type McpTool = {
+    name: string;
+    description?: string | undefined;
+    inputSchema?: Record<string, any> | undefined;
+};
+/**
+ * Per-server entry persisted in .mcp-bridge.json.
+ */
+export type BridgeServerEntry = {
+    command: string;
+    args: string[];
+    env?: Record<string, string> | undefined;
+    cwd?: string | undefined;
+    /**
+     * - tool name -> "allow" | "deny"
+     */
+    tools: Record<string, string>;
+};
+/**
+ * Persisted bridge config (.mcp-bridge.json).
+ */
+export type BridgeConfig = {
+    /**
+     * - ISO timestamp
+     */
+    discovered: string;
+    ttl: string;
+    servers: Record<string, BridgeServerEntry>;
+};
+/**
+ * A denied-tool descriptor surfaced to the LLM.
+ */
+export type DeniedTool = {
+    server: string;
+    tool: string;
+    description: string;
+};
+/**
+ * JSON-RPC stdio client over a spawned MCP server.
+ */
+export type RpcClient = {
+    rpc: (method: string, params?: object) => Promise<any>;
+    notify: (method: string, params?: object) => void;
+    child: import("node:child_process").ChildProcessWithoutNullStreams;
+    stderr: string;
+};
+/**
+ * Create an MCP bridge. On first run, discovers MCP servers from IDE configs,
+ * connects, lists tools, and writes .mcp-bridge.json with all tools set to "allow".
+ * On subsequent runs, reads .mcp-bridge.json and respects allow/deny per tool.
+ * Re-discovers when TTL expires (default: 24h).
+ *
+ * Returns BOTH surfaces (v0.9+):
+ *   - `tools`     — bulk-loaded array of name-prefixed tools (small catalogs;
+ *                   LLM sees them upfront).
+ *   - `metaTools` — [mcp_discover, mcp_invoke] LLM-callable pair (large catalogs;
+ *                   LLM picks tools dynamically). Shares the same RPC connections.
+ *
+ * Wire one or the other into Loop's tool array; never both (the LLM would see
+ * the same MCP tool twice). Pick by catalog size and token budget.
+ *
+ * @param {object} [opts]
+ * @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 {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
+ *   MCP server runs its command, and discovery reads configs from the cwd (a
+ *   `.mcp.json` in an untrusted repo) as well as the user's home/IDE configs.
+ *   Return false to skip a server (its command is never executed). A throw is
+ *   treated as a deny (fail-closed). Default: every discovered server is trusted
+ *   (unchanged behavior) — pass this to gate command execution.
+ * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
+ */
+export function createMCPBridge(opts?: {
+    bridgePath?: string | undefined;
+    configPaths?: string[] | undefined;
+    servers?: string[] | undefined;
+    timeout?: number | undefined;
+    refresh?: boolean | undefined;
+    confirmServer?: ((name: string, def: ServerDef) => boolean | Promise<boolean>) | undefined;
+}): Promise<{
+    tools: ToolDef[];
+    metaTools?: ToolDef[];
+    servers: string[];
+    systemContext: string;
+    denied: DeniedTool[];
+    errors?: Array<{
+        server: string;
+        error: string;
+    }>;
+    close: Function;
+}>;
+/**
+ * @param {string[]} [configPaths]
+ * @returns {Map<string, ServerDef>}
+ */
+export function discoverServers(configPaths?: string[]): Map<string, ServerDef>;
+/**
+ * Build the LLM-callable meta-tool surface from a fully-connected bridge.
+ * Shares the underlying tool array and RPC clients with the bulk surface —
+ * one set of connections, one factory, two output forms. The user picks
+ * `bridge.tools` (bulk) for small catalogs the LLM should see upfront, or
+ * `bridge.metaTools` for large catalogs the LLM should discover on demand.
+ *
+ * Gov shape: when the LLM calls mcp_invoke, the action sent to gate.check
+ * is `{ type: 'mcp_invoke', args: { name, args }, _ctx }` — bareguard sees
+ * `mcp_invoke` as the type. To deny specific MCP tools, use bareguard's
+ * `tools.denyArgPatterns: { mcp_invoke: [/"name":"linear_admin_.*"/] }`
+ * or `content.denyPatterns` over the JSON-serialized form. The inner MCP
+ * tool name doesn't travel as `action.type` — that's a deliberate v0.9
+ * trade for one consistent gate-check call per LLM tool invocation.
+ *
+ * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
+ * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
+ * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
+ */
+export function buildMetaTools(tools: ToolDef[], discoveredAt?: string): ToolDef[];