bare-agent 0.11.0 → 0.12.1

package/bin/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export type Provider = import("../types").Provider;
+export type ToolDef = import("../types").ToolDef;
+export type Ctx = import("../types").Ctx;

package/bin/cli.js

@@ -36,7 +36,12 @@ const { Loop } = require('../src/loop');
 const { Stream } = require('../src/stream');
 const { JsonlTransport } = require('../src/transport-jsonl');
 
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').Ctx} Ctx */
+
 const args = process.argv.slice(2);
+/** @param {string} name */
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? args[i + 1] : undefined;
@@ -45,7 +50,7 @@ const flag = (name) => {
 const configPath = flag('config');
 
 if (configPath) {
-  runConfigMode(configPath).catch((err) => {
+  runConfigMode(configPath).catch((/** @type {any} */ err) => {
     process.stdout.write(JSON.stringify({ type: 'loop:error', data: { source: 'cli', error: err.message } }) + '\n');
     process.exit(1);
   });
@@ -55,6 +60,7 @@ if (configPath) {
 
 // ─── Mode 2: config-driven ────────────────────────────────────────────────
 
+/** @param {string} cfgPath */
 async function runConfigMode(cfgPath) {
   const cfg = readConfig(cfgPath);
   const stream = new Stream({ transport: new JsonlTransport() });
@@ -68,9 +74,12 @@ async function runConfigMode(cfgPath) {
   // Bareguard Gate (optional but strongly recommended for spawn children).
   // Fail-closed: if the config asks for a gate but wiring fails, exit non-zero
   // rather than run an ungoverned child agent.
-  let policy = null;
-  let onLlmResult = null;
-  let onToolResult = null;
+  /** @type {Function | undefined} */
+  let policy;
+  /** @type {Function | undefined} */
+  let onLlmResult;
+  /** @type {Function | undefined} */
+  let onToolResult;
   let gatedTools = tools;
   if (cfg.gate) {
     try {
@@ -97,7 +106,7 @@ async function runConfigMode(cfgPath) {
       }
       if (typeof humanChannel !== 'function') {
         let warned = false;
-        humanChannel = async (event) => {
+        humanChannel = async (/** @type {any} */ event) => {
           if (!warned) {
             process.stderr.write(`[cli] no humanChannel configured — ${event.kind} on ${event.rule} auto-denying.\n`);
             warned = true;
@@ -148,7 +157,7 @@ async function runConfigMode(cfgPath) {
     policy,
     onLlmResult,
     onToolResult,
-    onError: (err, meta) => {
+    onError: (/** @type {any} */ err, /** @type {any} */ meta) => {
       process.stderr.write(`[loop:error ${meta.source}] ${err.message}\n`);
     },
   });
@@ -158,6 +167,7 @@ async function runConfigMode(cfgPath) {
   process.exit(0);
 }
 
+/** @param {string} cfgPath */
 function readConfig(cfgPath) {
   const abs = path.resolve(cfgPath);
   let raw;
@@ -179,6 +189,10 @@ function readStdin() {
   });
 }
 
+/**
+ * @param {any} cfg
+ * @param {string} stdin
+ */
 function buildInitialMessage(cfg, stdin) {
   if (!stdin) {
     return { role: 'user', content: cfg.defaultPrompt || 'Begin.' };
@@ -195,7 +209,13 @@ function buildInitialMessage(cfg, stdin) {
   return { role: 'user', content: stdin };
 }
 
+/**
+ * @param {string[]} names
+ * @param {{ stream: InstanceType<typeof Stream> }} ctx
+ * @returns {Promise<ToolDef[]>}
+ */
 async function resolveTools(names, ctx) {
+  /** @type {ToolDef[]} */
   const tools = [];
   for (const name of names) {
     const resolved = await resolveOneTool(name, ctx);
@@ -204,6 +224,11 @@ async function resolveTools(names, ctx) {
   return tools;
 }
 
+/**
+ * @param {string} name
+ * @param {{ stream: InstanceType<typeof Stream> }} ctx
+ * @returns {Promise<ToolDef | ToolDef[] | null>}
+ */
 async function resolveOneTool(name, ctx) {
   switch (name) {
     case 'shell_read':
@@ -215,16 +240,16 @@ async function resolveOneTool(name, ctx) {
       return tools.find(t => t.name === name) || null;
     }
     case 'shell_*': {
-      const { createShellTools } = require('../tools/shell');
-      return createShellTools().tools;
+      const { createShellTools: createShellToolsAll } = require('../tools/shell');
+      return createShellToolsAll().tools;
     }
     case 'spawn': {
       const { createSpawnTool } = require('../tools/spawn');
-      return createSpawnTool({ stream: ctx.stream }).tool;
+      return /** @type {ToolDef} */ (createSpawnTool({ stream: ctx.stream }).tool);
     }
     case 'defer': {
       const { createDeferTool } = require('../tools/defer');
-      return createDeferTool().tool;
+      return /** @type {ToolDef} */ (createDeferTool().tool);
     }
     default:
       process.stderr.write(`[cli] unknown tool name in config: ${name}\n`);
@@ -269,6 +294,11 @@ function runStdioMode() {
 
 // ─── Shared: provider construction ────────────────────────────────────────
 
+/**
+ * @param {string} name
+ * @param {string} [model]
+ * @returns {Provider}
+ */
 function createProvider(name, model) {
   if (name === 'openai') {
     const { OpenAIProvider } = require('../src/provider-openai');

package/bin/test-provider.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export type Provider = import("../types").Provider;

package/bin/test-provider.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 
+/** @typedef {import('../types').Provider} Provider */
+
 const args = process.argv.slice(2);
+/** @param {string} name */
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? args[i + 1] : undefined;
@@ -10,6 +13,7 @@ const flag = (name) => {
 const providerName = flag('provider') || 'openai';
 const model = flag('model');
 
+/** @returns {Provider} */
 function createProvider() {
   if (providerName === 'openai') {
     const { OpenAIProvider } = require('../src/provider-openai');
@@ -21,7 +25,7 @@ function createProvider() {
   if (providerName === 'anthropic') {
     const { AnthropicProvider } = require('../src/provider-anthropic');
     return new AnthropicProvider({
-      apiKey: process.env.ANTHROPIC_API_KEY,
+      apiKey: process.env.ANTHROPIC_API_KEY || '',
       ...(model && { model }),
     });
   }

package/index.d.ts

@@ -0,0 +1,20 @@
+import { Loop } from "./src/loop";
+import { Planner } from "./src/planner";
+import { StateMachine } from "./src/state";
+import { Scheduler } from "./src/scheduler";
+import { Checkpoint } from "./src/checkpoint";
+import { Memory } from "./src/memory";
+import { Stream } from "./src/stream";
+import { Retry } from "./src/retry";
+import { runPlan } from "./src/run-plan";
+import { CircuitBreaker } from "./src/circuit-breaker";
+import { wireGate } from "./src/bareguard-adapter";
+import { defaultActionTranslator } from "./src/bareguard-adapter";
+import { BareAgentError } from "./src/errors";
+import { ProviderError } from "./src/errors";
+import { ToolError } from "./src/errors";
+import { TimeoutError } from "./src/errors";
+import { ValidationError } from "./src/errors";
+import { CircuitOpenError } from "./src/errors";
+import { HaltError } from "./src/errors";
+export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "bare-agent",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "files": [
     "index.js",
+    "index.d.ts",
+    "bareagent.context.md",
     "src/",
     "bin/",
     "tools/",
+    "types/",
     "LICENSE",
     "NOTICE"
   ],
@@ -17,18 +20,43 @@
     "url": "git+https://github.com/hamr0/bareagent.git"
   },
   "main": "index.js",
+  "types": "./index.d.ts",
   "bin": {
     "bare-agent": "bin/cli.js"
   },
   "exports": {
-    ".": "./index.js",
-    "./errors": "./src/errors.js",
-    "./providers": "./src/providers.js",
-    "./stores": "./src/stores.js",
-    "./transports": "./src/transports.js",
-    "./tools": "./src/tools.js",
-    "./mcp": "./src/mcp.js",
-    "./bareguard": "./src/bareguard-adapter.js",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./errors": {
+      "types": "./src/errors.d.ts",
+      "default": "./src/errors.js"
+    },
+    "./providers": {
+      "types": "./src/providers.d.ts",
+      "default": "./src/providers.js"
+    },
+    "./stores": {
+      "types": "./src/stores.d.ts",
+      "default": "./src/stores.js"
+    },
+    "./transports": {
+      "types": "./src/transports.d.ts",
+      "default": "./src/transports.js"
+    },
+    "./tools": {
+      "types": "./src/tools.d.ts",
+      "default": "./src/tools.js"
+    },
+    "./mcp": {
+      "types": "./src/mcp.d.ts",
+      "default": "./src/mcp.js"
+    },
+    "./bareguard": {
+      "types": "./src/bareguard-adapter.d.ts",
+      "default": "./src/bareguard-adapter.js"
+    },
     "./package.json": "./package.json"
   },
   "engines": {
@@ -62,6 +90,14 @@
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/**/*.test.js"
+    "test": "node --test --test-force-exit test/**/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "prebuild:types": "node scripts/clean-types.js",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.7.0"
   }
 }

package/src/bareguard-adapter.d.ts

@@ -0,0 +1,118 @@
+export type Ctx = import("../types").Ctx;
+export type ToolDef = import("../types").ToolDef;
+export type Usage = import("../types").Usage;
+/**
+ * A bareguard Gate instance. Comes from the ambient `bareguard` module, so its
+ * methods are accessed structurally here.
+ */
+export type Gate = {
+    check: (action: any) => (GateDecision | Promise<GateDecision>);
+    record: (action: any, outcome?: any) => any;
+    allows?: ((toolName: string) => (boolean | Promise<boolean>)) | undefined;
+};
+/**
+ * A decision returned by `gate.check`.
+ */
+export type GateDecision = {
+    /**
+     * - 'allow' when permitted.
+     */
+    outcome?: string | undefined;
+    /**
+     * - 'halt' for halt-severity denials.
+     */
+    severity?: string | undefined;
+    /**
+     * - The matched rule name.
+     */
+    rule?: string | undefined;
+    /**
+     * - Human-readable reason.
+     */
+    reason?: string | undefined;
+    /**
+     * - Arbitrary structured context.
+     */
+    context?: Record<string, any> | undefined;
+};
+/**
+ * Wire a bareguard Gate into bareagent's Loop.
+ *
+ * Returns:
+ *   - `policy`        — async (toolName, args, ctx) closure for `new Loop({ policy })`.
+ *                       Allow → true; deny → tagged reason string; halt → throws HaltError.
+ *   - `onLlmResult`   — callback for `new Loop({ onLlmResult })`. Forwards every
+ *                       provider.generate result to gate.record as a `{type:'llm'}` action
+ *                       so `budget.maxCostUsd` covers token-only workloads.
+ *   - `onToolResult`  — callback for `new Loop({ onToolResult })`. Forwards every
+ *                       tool.execute result to gate.record with ctx in scope.
+ *   - `filterTools`   — async (tools) => filtered. Drops tools denied by gate.allows
+ *                       so the LLM never sees them. No audit, no record. Bulk-only:
+ *                       when MCP tools are exposed via `mcp_discover`+`mcp_invoke`
+ *                       meta-tools, filterTools cannot drop the inner names (they
+ *                       are not in the tool list). Gate those via bareguard's
+ *                       `tools.denyArgPatterns: { mcp_invoke: [/"name":"…"/] }`
+ *                       — see src/mcp-bridge.js (Gov shape).
+ *   - `wrapTool` / `wrapTools` — DEPRECATED. Pre-BA1 shim that wraps execute() to
+ *                       call gate.record post-hoc. Loses _ctx and never sees LLM cost.
+ *                       Prefer `onToolResult` (and `onLlmResult` for budget correctness).
+ *
+ * Halt-severity decisions (budget exhausted, limits.maxTurns hit, gate terminated)
+ * throw HaltError from the policy closure; Loop catches it and exits cleanly with
+ * loop:error{source:'halt'} + loop:done — the deny is NOT fed back to the LLM.
+ *
+ * @param {Gate} gate - A bareguard Gate instance (must have .check, .record, .allows).
+ * @param {object} [options]
+ * @param {Function} [options.formatDeny] - (decision, toolName) => string. Transforms
+ *   the deny string fed to the LLM. The second arg is the bareagent tool name (handy
+ *   for tool-specific deny copy). Default: "[deny: <rule>] <reason>" or
+ *   "[deny: <rule>] <toolName> denied" when bareguard omits a reason. Halt bypasses
+ *   this (HaltError doesn't reach the LLM).
+ * @param {Function} [options.actionTranslator] - (toolName, args, ctx) => action.
+ *   Builds the action object passed to `gate.check` and `gate.record`. Default:
+ *   `{ type: toolName, args, _ctx: ctx }`. Override when bareguard's primitives
+ *   need a specific shape — e.g. `bashCheck` requires `{type:'bash', cmd:...}`,
+ *   `fsCheck` requires `{type:'read'|'write'|'edit', path:...}`. The default shape
+ *   matches `tools.denylist` / `tools.allowlist` (which read `action.type`) but
+ *   does NOT activate `bash`/`fs`/`net` primitives — those need their own
+ *   `action.type` value. Adopters using those primitives must translate.
+ * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
+ *
+ * @example
+ *   const { Gate } = require('bareguard');
+ *   const { Loop } = require('bare-agent');
+ *   const { wireGate } = require('bare-agent/bareguard');
+ *
+ *   const gate = new Gate({
+ *     budget: { maxCostUsd: 0.50 },
+ *     limits: { maxTurns: 20 },
+ *     audit:  { path: './audit.jsonl' },
+ *   });
+ *   await gate.init();
+ *
+ *   const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate);
+ *   const loop = new Loop({ provider, policy, onLlmResult, onToolResult });
+ *   const tools = await filterTools(myTools);
+ *   await loop.run(messages, tools);
+ */
+export function wireGate(gate: Gate, options?: {
+    formatDeny?: Function | undefined;
+    actionTranslator?: Function | undefined;
+}): {
+    policy: Function;
+    onLlmResult: Function;
+    onToolResult: Function;
+    filterTools: Function;
+    wrapTool: Function;
+    wrapTools: Function;
+};
+/**
+ * @param {string} toolName
+ * @param {any} args
+ * @param {Ctx} ctx
+ */
+export function defaultActionTranslator(toolName: string, args: any, ctx: Ctx): {
+    type: string;
+    args: any;
+    _ctx: any;
+};

package/src/bareguard-adapter.js

@@ -2,10 +2,34 @@
 
 const { HaltError } = require('./errors');
 
+/** @typedef {import('../types').Ctx} Ctx */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').Usage} Usage */
+
+/**
+ * A bareguard Gate instance. Comes from the ambient `bareguard` module, so its
+ * methods are accessed structurally here.
+ * @typedef {object} Gate
+ * @property {(action: any) => (GateDecision | Promise<GateDecision>)} check
+ * @property {(action: any, outcome?: any) => any} record
+ * @property {(toolName: string) => (boolean | Promise<boolean>)} [allows]
+ */
+
+/**
+ * A decision returned by `gate.check`.
+ * @typedef {object} GateDecision
+ * @property {string} [outcome] - 'allow' when permitted.
+ * @property {string} [severity] - 'halt' for halt-severity denials.
+ * @property {string} [rule] - The matched rule name.
+ * @property {string} [reason] - Human-readable reason.
+ * @property {Record<string, any>} [context] - Arbitrary structured context.
+ */
+
 // Safe-stringify for tool results: tools can return circular structures or
 // values that include functions / undefined / bigints. Falling back to String()
 // keeps gate.record from throwing inside onToolResult (which would surface as a
 // loop:error{source:'onToolResult'} for what is really a serialization quirk).
+/** @param {any} value */
 function safeStringify(value) {
   if (typeof value === 'string') return value;
   try {
@@ -46,7 +70,7 @@ let warnedWrap = false;
  * throw HaltError from the policy closure; Loop catches it and exits cleanly with
  * loop:error{source:'halt'} + loop:done — the deny is NOT fed back to the LLM.
  *
- * @param {object} gate - A bareguard Gate instance (must have .check, .record, .allows).
+ * @param {Gate} gate - A bareguard Gate instance (must have .check, .record, .allows).
  * @param {object} [options]
  * @param {Function} [options.formatDeny] - (decision, toolName) => string. Transforms
  *   the deny string fed to the LLM. The second arg is the bareagent tool name (handy
@@ -93,6 +117,11 @@ function wireGate(gate, options = {}) {
   const formatDeny = options.formatDeny || defaultFormatDeny;
   const translate = options.actionTranslator || defaultActionTranslator;
 
+  /**
+   * @param {string} toolName
+   * @param {any} args
+   * @param {Ctx} ctx
+   */
   const policy = async (toolName, args, ctx) => {
     const decision = await gate.check(translate(toolName, args, ctx));
     if (decision.outcome === 'allow') return true;
@@ -105,6 +134,15 @@ function wireGate(gate, options = {}) {
     return formatDeny(decision, toolName);
   };
 
+  /**
+   * @param {object} arg
+   * @param {string|null} [arg.model]
+   * @param {string|null} [arg.provider]
+   * @param {Usage} [arg.usage]
+   * @param {number} [arg.costUsd]
+   * @param {number|null} [arg.durationMs]
+   * @param {Ctx} [arg.ctx]
+   */
   const onLlmResult = async ({ model, provider, usage, costUsd, durationMs, ctx }) => {
     // LLM rounds bypass actionTranslator — they always use the canonical
     // {type:'llm'} action so budget rules can match without translator collusion.
@@ -118,6 +156,15 @@ function wireGate(gate, options = {}) {
     );
   };
 
+  /**
+   * @param {object} arg
+   * @param {string} arg.name
+   * @param {any} [arg.args]
+   * @param {any} [arg.result]
+   * @param {Error|null} [arg.error]
+   * @param {number|null} [arg.durationMs]
+   * @param {Ctx} [arg.ctx]
+   */
   const onToolResult = async ({ name, args, result, error, durationMs, ctx }) => {
     const action = translate(name, args, ctx);
     if (error) {
@@ -133,6 +180,10 @@ function wireGate(gate, options = {}) {
     }
   };
 
+  /**
+   * @param {ToolDef[]} tools
+   * @returns {Promise<ToolDef[]>}
+   */
   const filterTools = async (tools) => {
     if (!Array.isArray(tools)) {
       throw new Error('[wireGate.filterTools] expects an array of tools');
@@ -140,13 +191,20 @@ function wireGate(gate, options = {}) {
     if (typeof gate.allows !== 'function') {
       throw new Error('[wireGate.filterTools] gate must have .allows (bareguard >= 0.2)');
     }
+    // Bind to the Gate so `this` stays correct (bareguard's allows reads
+    // this._initialized) — extracting the method unbound would crash.
+    const allows = gate.allows.bind(gate);
     // Parallel: gate.allows is config-driven and pure, so concurrent calls are
     // safe. Matters for large MCP catalogs (50+ tools) where sequential awaits
     // were noticeable overhead on every startup.
-    const verdicts = await Promise.all(tools.map(t => gate.allows(t.name)));
+    const verdicts = await Promise.all(tools.map(t => allows(t.name)));
     return tools.filter((_, i) => verdicts[i]);
   };
 
+  /**
+   * @param {ToolDef} tool
+   * @returns {ToolDef}
+   */
   function wrapTool(tool) {
     if (!warnedWrap) {
       warnedWrap = true;
@@ -161,7 +219,7 @@ function wireGate(gate, options = {}) {
     const original = tool.execute;
     return {
       ...tool,
-      execute: async (args) => {
+      execute: async (/** @type {any} */ args) => {
         const action = { type: tool.name, args };
         const startedAt = Date.now();
         try {
@@ -182,6 +240,10 @@ function wireGate(gate, options = {}) {
     };
   }
 
+  /**
+   * @param {ToolDef[]} tools
+   * @returns {ToolDef[]}
+   */
   function wrapTools(tools) {
     if (!Array.isArray(tools)) {
       throw new Error('[wireGate.wrapTools] expects an array of tools');
@@ -192,6 +254,11 @@ function wireGate(gate, options = {}) {
   return { policy, onLlmResult, onToolResult, filterTools, wrapTool, wrapTools };
 }
 
+/**
+ * @param {GateDecision} decision
+ * @param {string} toolName
+ * @returns {string}
+ */
 function defaultFormatDeny(decision, toolName) {
   const tag = `[deny: ${decision.rule}]`;
   return decision.reason ? `${tag} ${decision.reason}` : `${tag} ${toolName} denied`;
@@ -202,6 +269,11 @@ function defaultFormatDeny(decision, toolName) {
 // does NOT activate `bash`/`fs`/`net` primitives — those require `action.type`
 // to be `bash`/`read`/`write`/etc. and read fields like `action.cmd` /
 // `action.path` at the top level. Override via `wireGate(gate, { actionTranslator })`.
+/**
+ * @param {string} toolName
+ * @param {any} args
+ * @param {Ctx} ctx
+ */
 function defaultActionTranslator(toolName, args, ctx) {
   return { type: toolName, args, _ctx: ctx ?? null };
 }

package/src/checkpoint.d.ts

@@ -0,0 +1,61 @@
+export type CheckpointOptions = {
+    /**
+     * - Tool names that require approval (exact match).
+     */
+    tools?: string[] | undefined;
+    /**
+     * - Custom predicate — overrides tools list if set.
+     */
+    shouldAsk?: ((toolName: string, args: any) => boolean) | undefined;
+    /**
+     * - Async `(question, context) => void` to deliver the question.
+     */
+    send?: ((question: string, context: any) => any) | undefined;
+    /**
+     * - Async `(context) => string` that resolves with the user's reply.
+     */
+    waitForReply?: ((context: any) => any) | undefined;
+    /**
+     * - Ms to wait before auto-denying. 0 disables.
+     */
+    timeout?: number | undefined;
+};
+/**
+ * @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.
+ */
+export class Checkpoint {
+    /**
+     * @param {CheckpointOptions} [options={}]
+     */
+    constructor(options?: CheckpointOptions);
+    tools: Set<string>;
+    send: ((question: string, context: any) => any) | null;
+    waitForReply: ((context: any) => any) | null;
+    shouldAskFn: ((toolName: string, args: any) => boolean) | null;
+    timeout: number;
+    /**
+     * @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: string, args: any): boolean;
+    /**
+     * Send a question and wait for a reply. Rejects with TimeoutError if `timeout` ms elapse
+     * 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 {{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.
+     */
+    ask(question: string, context?: {
+        tool?: string;
+        [key: string]: any;
+    }): Promise<string | null>;
+}

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.