bare-agent 0.11.0 → 0.12.1

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;
+}

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) },
@@ -381,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 },
@@ -421,6 +469,7 @@ class Loop {
     }
 
     // Tools check
+    /** @type {string[]} */
     const toolErrors = [];
     for (const tool of tools) {
       if (typeof tool.name !== 'string' || !tool.name) {
@@ -442,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);