bare-agent 0.10.4 → 0.12.0

package/src/checkpoint.js

@@ -4,16 +4,20 @@ const { TimeoutError } = require('./errors');
 
 const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 
+/**
+ * @typedef {object} CheckpointOptions
+ * @property {Array<string>} [tools] - Tool names that require approval (exact match).
+ * @property {(toolName: string, args: any) => boolean} [shouldAsk] - Custom predicate — overrides tools list if set.
+ * @property {(question: string, context: any) => any} [send] - Async `(question, context) => void` to deliver the question.
+ * @property {(context: any) => any} [waitForReply] - Async `(context) => string` that resolves with the user's reply.
+ * @property {number} [timeout=300000] - Ms to wait before auto-denying. 0 disables.
+ */
+
 class Checkpoint {
   /**
-   * @param {object} options
-   * @param {Array<string>} [options.tools] - Tool names that require approval (exact match).
-   * @param {Function} [options.shouldAsk] - Custom predicate `(toolName, args) => bool` — overrides tools list if set.
-   * @param {Function} options.send - Async `(question, context) => void` to deliver the question.
-   * @param {Function} options.waitForReply - Async `(context) => string` that resolves with the user's reply.
-   * @param {number} [options.timeout=300000] - Ms to wait before auto-denying. 0 disables.
+   * @param {CheckpointOptions} [options={}]
    */
-  constructor(options = {}) {
+  constructor(options = /** @type {CheckpointOptions} */ ({})) {
     this.tools = new Set(options.tools || []);
     this.send = options.send || null;
     this.waitForReply = options.waitForReply || null;
@@ -21,6 +25,11 @@ class Checkpoint {
     this.timeout = options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS;
   }
 
+  /**
+   * @param {string} toolName - Name of the tool being invoked.
+   * @param {any} args - Arguments passed to the tool.
+   * @returns {boolean} Whether approval should be requested.
+   */
   shouldAsk(toolName, args) {
     if (this.shouldAskFn) return this.shouldAskFn(toolName, args);
     return this.tools.has(toolName);
@@ -31,7 +40,7 @@ class Checkpoint {
    * without a reply — the Loop catches this, auto-denies the tool call, and routes the
    * error through loop:error + onError. No silent hangs.
    * @param {string} question - The approval question to send.
-   * @param {object} [context={}] - Context passed to send and waitForReply.
+   * @param {{tool?: string, [key: string]: any}} [context={}] - Context passed to send and waitForReply.
    * @returns {Promise<string|null>} The user's reply, or null.
    * @throws {Error} `[Checkpoint] send and waitForReply callbacks required` — when callbacks are missing.
    * @throws {TimeoutError} When no reply arrives within `timeout` ms.

package/src/circuit-breaker.d.ts

@@ -0,0 +1,70 @@
+export type CircuitState = "closed" | "open" | "half-open";
+export type CircuitEntry = {
+    state: CircuitState;
+    failures: number;
+    openedAt: number;
+    generation: number;
+};
+/**
+ * @typedef {'closed'|'open'|'half-open'} CircuitState
+ * @typedef {{ state: CircuitState, failures: number, openedAt: number, generation: number }} CircuitEntry
+ */
+export class CircuitBreaker {
+    /**
+     * @param {object} [options={}]
+     * @param {number} [options.threshold=5] - Failures before opening.
+     * @param {number} [options.resetAfter=60000] - Ms before half-open probe.
+     * @param {((key: string, from: CircuitState, to: CircuitState) => void)} [options.onStateChange] - Callback(key, from, to).
+     */
+    constructor(options?: {
+        threshold?: number | undefined;
+        resetAfter?: number | undefined;
+        onStateChange?: ((key: string, from: CircuitState, to: CircuitState) => void) | undefined;
+    });
+    threshold: number;
+    resetAfter: number;
+    onStateChange: ((key: string, from: CircuitState, to: CircuitState) => void) | null;
+    /** @type {Map<string, CircuitEntry>} */
+    _keys: Map<string, CircuitEntry>;
+    /**
+     * @param {string} key
+     * @returns {CircuitEntry}
+     */
+    _getEntry(key: string): CircuitEntry;
+    /**
+     * @param {CircuitEntry} entry
+     * @param {string} key
+     * @param {CircuitState} newState
+     */
+    _setState(entry: CircuitEntry, key: string, newState: CircuitState): void;
+    /**
+     * Execute fn through the circuit breaker.
+     * @param {function} fn - Async function to call.
+     * @param {string} [key='default'] - Circuit key for per-key isolation.
+     * @returns {Promise<*>}
+     * @throws {CircuitOpenError} When circuit is open.
+     */
+    call(fn: Function, key?: string): Promise<any>;
+    /**
+     * Get current state for a key.
+     * @param {string} [key='default']
+     * @returns {'closed'|'open'|'half-open'}
+     */
+    getState(key?: string): "closed" | "open" | "half-open";
+    /**
+     * Force reset a key to closed.
+     * @param {string} [key='default']
+     */
+    reset(key?: string): void;
+    /**
+     * Wrap a provider so generate() goes through the circuit breaker.
+     * @param {{ generate: (...args: any[]) => Promise<any> }} provider - Provider with generate().
+     * @param {string} [key] - Circuit key.
+     * @returns {{ generate: (...args: any[]) => Promise<any> }} Wrapped provider with generate().
+     */
+    wrapProvider(provider: {
+        generate: (...args: any[]) => Promise<any>;
+    }, key?: string): {
+        generate: (...args: any[]) => Promise<any>;
+    };
+}

package/src/circuit-breaker.js

@@ -2,27 +2,42 @@
 
 const { CircuitOpenError } = require('./errors');
 
+/**
+ * @typedef {'closed'|'open'|'half-open'} CircuitState
+ * @typedef {{ state: CircuitState, failures: number, openedAt: number, generation: number }} CircuitEntry
+ */
+
 class CircuitBreaker {
   /**
    * @param {object} [options={}]
    * @param {number} [options.threshold=5] - Failures before opening.
    * @param {number} [options.resetAfter=60000] - Ms before half-open probe.
-   * @param {function} [options.onStateChange] - Callback(key, from, to).
+   * @param {((key: string, from: CircuitState, to: CircuitState) => void)} [options.onStateChange] - Callback(key, from, to).
    */
   constructor(options = {}) {
     this.threshold = options.threshold || 5;
     this.resetAfter = options.resetAfter || 60000;
     this.onStateChange = options.onStateChange || null;
+    /** @type {Map<string, CircuitEntry>} */
     this._keys = new Map();
   }
 
+  /**
+   * @param {string} key
+   * @returns {CircuitEntry}
+   */
   _getEntry(key) {
     if (!this._keys.has(key)) {
       this._keys.set(key, { state: 'closed', failures: 0, openedAt: 0, generation: 0 });
     }
-    return this._keys.get(key);
+    return /** @type {CircuitEntry} */ (this._keys.get(key));
   }
 
+  /**
+   * @param {CircuitEntry} entry
+   * @param {string} key
+   * @param {CircuitState} newState
+   */
   _setState(entry, key, newState) {
     const from = entry.state;
     if (from === newState) return;
@@ -98,12 +113,13 @@ class CircuitBreaker {
 
   /**
    * Wrap a provider so generate() goes through the circuit breaker.
-   * @param {object} provider - Provider with generate().
+   * @param {{ generate: (...args: any[]) => Promise<any> }} provider - Provider with generate().
    * @param {string} [key] - Circuit key.
-   * @returns {object} Wrapped provider with generate().
+   * @returns {{ generate: (...args: any[]) => Promise<any> }} Wrapped provider with generate().
    */
   wrapProvider(provider, key) {
     return {
+      /** @param {...any} args */
       generate: (...args) => this.call(() => provider.generate(...args), key),
     };
   }

package/src/errors.d.ts

@@ -0,0 +1,106 @@
+export type BareAgentErrorOptions = {
+    /**
+     * - Stable error code (e.g. 'PROVIDER_ERROR').
+     */
+    code?: string | undefined;
+    /**
+     * - Whether the operation may be safely retried.
+     */
+    retryable?: boolean | undefined;
+    /**
+     * - Arbitrary structured context.
+     */
+    context?: Record<string, any> | undefined;
+};
+export type ProviderErrorOptions = {
+    /**
+     * - HTTP status from the provider.
+     */
+    status?: number | undefined;
+    /**
+     * - Raw response body.
+     */
+    body?: any;
+    /**
+     * - Arbitrary structured context.
+     */
+    context?: Record<string, any> | undefined;
+};
+export type HaltErrorOptions = {
+    /**
+     * - The bareguard rule that triggered the halt.
+     */
+    rule?: string | undefined;
+    /**
+     * - The full bareguard decision object.
+     */
+    decision?: any;
+    /**
+     * - Arbitrary structured context.
+     */
+    context?: Record<string, any> | undefined;
+};
+/**
+ * @typedef {object} BareAgentErrorOptions
+ * @property {string} [code] - Stable error code (e.g. 'PROVIDER_ERROR').
+ * @property {boolean} [retryable] - Whether the operation may be safely retried.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+/**
+ * @typedef {object} ProviderErrorOptions
+ * @property {number} [status] - HTTP status from the provider.
+ * @property {any} [body] - Raw response body.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+/**
+ * @typedef {object} HaltErrorOptions
+ * @property {string} [rule] - The bareguard rule that triggered the halt.
+ * @property {any} [decision] - The full bareguard decision object.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+export class BareAgentError extends Error {
+    /**
+     * @param {string} message
+     * @param {BareAgentErrorOptions} [options]
+     */
+    constructor(message: string, { code, retryable, context }?: BareAgentErrorOptions);
+    code: string | undefined;
+    retryable: boolean;
+    context: Record<string, any>;
+}
+export class ProviderError extends BareAgentError {
+    /**
+     * @param {string} message
+     * @param {ProviderErrorOptions} [options]
+     */
+    constructor(message: string, { status, body, context }?: ProviderErrorOptions);
+    status: number | undefined;
+    body: any;
+}
+export class ToolError extends BareAgentError {
+}
+export class TimeoutError extends BareAgentError {
+    /**
+     * @param {string} [message]
+     * @param {BareAgentErrorOptions} [opts]
+     */
+    constructor(message?: string, opts?: BareAgentErrorOptions);
+}
+export class ValidationError extends BareAgentError {
+}
+export class CircuitOpenError extends BareAgentError {
+    /**
+     * @param {string} [message]
+     * @param {BareAgentErrorOptions} [opts]
+     */
+    constructor(message?: string, opts?: BareAgentErrorOptions);
+}
+export class HaltError extends BareAgentError {
+    /**
+     * @param {string} [message]
+     * @param {HaltErrorOptions} [options]
+     */
+    constructor(message?: string, { rule, decision, context }?: HaltErrorOptions);
+    rule: string | null;
+    decision: any;
+}

package/src/errors.js

@@ -1,6 +1,31 @@
 'use strict';
 
+/**
+ * @typedef {object} BareAgentErrorOptions
+ * @property {string} [code] - Stable error code (e.g. 'PROVIDER_ERROR').
+ * @property {boolean} [retryable] - Whether the operation may be safely retried.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+
+/**
+ * @typedef {object} ProviderErrorOptions
+ * @property {number} [status] - HTTP status from the provider.
+ * @property {any} [body] - Raw response body.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+
+/**
+ * @typedef {object} HaltErrorOptions
+ * @property {string} [rule] - The bareguard rule that triggered the halt.
+ * @property {any} [decision] - The full bareguard decision object.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+
 class BareAgentError extends Error {
+  /**
+   * @param {string} message
+   * @param {BareAgentErrorOptions} [options]
+   */
   constructor(message, { code, retryable = false, context = {} } = {}) {
     super(message);
     this.name = this.constructor.name;
@@ -11,8 +36,12 @@ class BareAgentError extends Error {
 }
 
 class ProviderError extends BareAgentError {
+  /**
+   * @param {string} message
+   * @param {ProviderErrorOptions} [options]
+   */
   constructor(message, { status, body, context = {} } = {}) {
-    const retryable = status === 429 || (status >= 500 && status <= 504);
+    const retryable = status === 429 || (status != null && status >= 500 && status <= 504);
     super(message, { code: 'PROVIDER_ERROR', retryable, context });
     this.status = status;
     this.body = body;
@@ -20,24 +49,40 @@ class ProviderError extends BareAgentError {
 }
 
 class ToolError extends BareAgentError {
+  /**
+   * @param {string} message
+   * @param {BareAgentErrorOptions} [opts]
+   */
   constructor(message, opts = {}) {
     super(message, { code: 'TOOL_ERROR', retryable: false, ...opts });
   }
 }
 
 class TimeoutError extends BareAgentError {
+  /**
+   * @param {string} [message]
+   * @param {BareAgentErrorOptions} [opts]
+   */
   constructor(message, opts = {}) {
     super(message || 'Operation timed out', { code: 'ETIMEDOUT', retryable: true, ...opts });
   }
 }
 
 class ValidationError extends BareAgentError {
+  /**
+   * @param {string} message
+   * @param {BareAgentErrorOptions} [opts]
+   */
   constructor(message, opts = {}) {
     super(message, { code: 'VALIDATION_ERROR', retryable: false, ...opts });
   }
 }
 
 class CircuitOpenError extends BareAgentError {
+  /**
+   * @param {string} [message]
+   * @param {BareAgentErrorOptions} [opts]
+   */
   constructor(message, opts = {}) {
     super(message || 'Circuit breaker is open', { code: 'CIRCUIT_OPEN', retryable: true, ...opts });
   }
@@ -48,6 +93,10 @@ class CircuitOpenError extends BareAgentError {
 // Loop's outer handler — does NOT propagate to the LLM as a tool result.
 // Loop exits cleanly: emits loop:error{source:'halt'} + loop:done, calls onError.
 class HaltError extends BareAgentError {
+  /**
+   * @param {string} [message]
+   * @param {HaltErrorOptions} [options]
+   */
   constructor(message, { rule, decision, context = {} } = {}) {
     super(message || `[HALT: ${rule || 'unknown'}]`, {
       code: 'HALT',

package/src/loop.d.ts

@@ -0,0 +1,135 @@
+export type Provider = import("../types").Provider;
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type ToolCall = import("../types").ToolCall;
+export type Usage = import("../types").Usage;
+export type GenerateResult = import("../types").GenerateResult;
+export type Store = import("../types").Store;
+export type Checkpoint = import("./checkpoint").Checkpoint;
+export type Retry = import("./retry").Retry;
+export type Stream = import("./stream").Stream;
+export type LoopOptions = {
+    provider: Provider;
+    system?: string | undefined;
+    checkpoint?: import("./checkpoint").Checkpoint | undefined;
+    retry?: import("./retry").Retry | undefined;
+    stream?: import("./stream").Stream | undefined;
+    store?: import("../types").Store | undefined;
+    onToolCall?: Function | undefined;
+    onText?: Function | undefined;
+    onError?: Function | undefined;
+    throwOnError?: boolean | undefined;
+    policy?: Function | undefined;
+    onLlmResult?: Function | undefined;
+    onToolResult?: Function | undefined;
+    /**
+     * - Removed in v0.8; presence throws a migration error.
+     */
+    maxRounds?: number | undefined;
+};
+export class 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?: LoopOptions);
+    provider: import("../types").Provider;
+    system: string | null;
+    checkpoint: import("./checkpoint").Checkpoint | null;
+    retry: import("./retry").Retry | null;
+    stream: import("./stream").Stream | null;
+    onToolCall: Function | null;
+    onText: Function | null;
+    onError: Function | null;
+    throwOnError: boolean;
+    store: import("../types").Store | null;
+    policy: Function | null;
+    onLlmResult: Function | null;
+    onToolResult: Function | null;
+    _stopped: boolean;
+    /** @type {Message[]} */
+    _history: Message[];
+    /**
+     * @param {string} source
+     * @param {any} err
+     * @param {Record<string, any>} [extra]
+     */
+    _reportError(source: string, err: any, extra?: Record<string, any>): void;
+    /** @param {{type: string, data?: any, ts?: string}} event */
+    _safeEmit(event: {
+        type: string;
+        data?: any;
+        ts?: string;
+    }): void;
+    /**
+     * @param {string} name
+     * @param {Function|null} fn
+     * @param {...any} args
+     */
+    _safeCall(name: string, fn: Function | null, ...args: any[]): void;
+    /**
+     * Run the think/act/observe loop.
+     * @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
+     *   synthetic `[halted]` tool replies — safe to feed back into another
+     *   provider call without violating OpenAI's tool-call/tool-result pairing.
+     * @throws {Error} `[Loop] Tool is missing a name` — when a tool has no name or a non-string name.
+     * @throws {Error} `[Loop] Tool "X" is missing an execute() function` — when execute is not a function.
+     * @throws {Error} `[Loop] Tool "X" has invalid parameters` — when parameters is not an object.
+     */
+    run(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<{
+        text: string;
+        toolCalls: ToolCall[];
+        usage: Usage;
+        cost: number;
+        error: string | null;
+        msgs: Message[];
+    }>;
+    /**
+     * Health check — validates provider, store, and tools without throwing.
+     * @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.
+     */
+    validate(tools?: ToolDef[]): Promise<{
+        provider: {
+            ok: boolean;
+            error?: string;
+        };
+        store: {
+            ok: boolean;
+            error?: string;
+            skipped: boolean;
+        };
+        tools: {
+            ok: boolean;
+            errors?: string[];
+        };
+    }>;
+    /**
+     * 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[]}>}
+     */
+    chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
+        text: string;
+        toolCalls: ToolCall[];
+        usage: Usage;
+        cost: number;
+        error: string | null;
+        msgs: Message[];
+    }>;
+    stop(): void;
+}