bare-agent 0.11.0 → 0.12.1

package/src/provider-ollama.js

@@ -3,7 +3,21 @@
 const http = require('http');
 const { ProviderError } = require('./errors');
 
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+
+/**
+ * @typedef {object} OllamaOptions
+ * @property {string} [model='llama3.2']
+ * @property {string} [url='http://localhost:11434']
+ * @property {boolean} [exposeErrorBody=false]
+ */
+
 class OllamaProvider {
+  /**
+   * @param {OllamaOptions} [options]
+   */
   constructor(options = {}) {
     this.model = options.model || 'llama3.2';
     this.url = options.url || 'http://localhost:11434';
@@ -13,13 +27,14 @@ class OllamaProvider {
 
   /**
    * Generate a response from a local Ollama instance.
-   * @param {Array<object>} messages - Conversation messages.
-   * @param {Array<object>} [tools=[]] - Tool definitions.
-   * @param {object} [options={}] - Options (temperature).
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @param {Message[]} messages - Conversation messages.
+   * @param {ToolDef[]} [tools=[]] - Tool definitions.
+   * @param {Record<string, any>} [options={}] - Options (temperature).
+   * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OllamaProvider] ...` — on HTTP errors or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
+    /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
@@ -38,7 +53,7 @@ class OllamaProvider {
 
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map(tc => ({
+      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
         id: tc.id || `call_${Date.now()}`,
         name: tc.function.name,
         arguments: typeof tc.function.arguments === 'string'
@@ -52,6 +67,11 @@ class OllamaProvider {
     };
   }
 
+  /**
+   * @param {string} path
+   * @param {Record<string, any>} body
+   * @returns {Promise<any>}
+   */
   _request(path, body) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.url + path);
@@ -69,10 +89,10 @@ class OllamaProvider {
         res.on('end', () => {
           try {
             const parsed = JSON.parse(chunks);
-            if (res.statusCode >= 400) {
+            if ((res.statusCode ?? 0) >= 400) {
               return reject(new ProviderError(
                 `[OllamaProvider] ${parsed.error || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
+                /** @type {any} */ ({ status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined })
               ));
             }
             resolve(parsed);

package/src/provider-openai.d.ts

@@ -0,0 +1,57 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type ToolCall = import("../types").ToolCall;
+export type GenerateResult = import("../types").GenerateResult;
+export type OpenAIOptions = {
+    apiKey?: string | undefined;
+    model?: string | undefined;
+    baseUrl?: string | undefined;
+    /**
+     * - Attach the full upstream
+     * response to `err.body` on HTTP errors. Off by default so an unexpected
+     * field in an error payload can't leak through logs that dump the error
+     * object; `err.message` still carries the API's error message. Turn on for
+     * debugging only.
+     */
+    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]
+ * @property {string} [model='gpt-4o-mini']
+ * @property {string} [baseUrl='https://api.openai.com/v1']
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream
+ *   response to `err.body` on HTTP errors. Off by default so an unexpected
+ *   field in an error payload can't leak through logs that dump the error
+ *   object; `err.message` still carries the API's error message. Turn on for
+ *   debugging only.
+ */
+export class OpenAIProvider {
+    /**
+     * @param {OpenAIOptions} [options]
+     */
+    constructor(options?: OpenAIOptions);
+    apiKey: string | undefined;
+    model: string;
+    baseUrl: string;
+    exposeErrorBody: boolean;
+    /**
+     * Generate a response from the OpenAI API.
+     * @param {Message[]} messages - Conversation messages.
+     * @param {ToolDef[]} [tools=[]] - Tool definitions.
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * @param {string} path
+     * @param {Record<string, any>} body
+     * @returns {Promise<any>}
+     */
+    _request(path: string, body: Record<string, any>): Promise<any>;
+}

package/src/provider-openai.js

@@ -4,17 +4,26 @@ const https = require('https');
 const http = require('http');
 const { ProviderError } = require('./errors');
 
+/** @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]
+ * @property {string} [model='gpt-4o-mini']
+ * @property {string} [baseUrl='https://api.openai.com/v1']
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream
+ *   response to `err.body` on HTTP errors. Off by default so an unexpected
+ *   field in an error payload can't leak through logs that dump the error
+ *   object; `err.message` still carries the API's error message. Turn on for
+ *   debugging only.
+ */
+
 class OpenAIProvider {
   /**
-   * @param {object} [options]
-   * @param {string} [options.apiKey]
-   * @param {string} [options.model='gpt-4o-mini']
-   * @param {string} [options.baseUrl='https://api.openai.com/v1']
-   * @param {boolean} [options.exposeErrorBody=false] - Attach the full upstream
-   *   response to `err.body` on HTTP errors. Off by default so an unexpected
-   *   field in an error payload can't leak through logs that dump the error
-   *   object; `err.message` still carries the API's error message. Turn on for
-   *   debugging only.
+   * @param {OpenAIOptions} [options]
    */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();
@@ -25,13 +34,14 @@ class OpenAIProvider {
 
   /**
    * Generate a response from the OpenAI API.
-   * @param {Array<object>} messages - Conversation messages.
-   * @param {Array<object>} [tools=[]] - Tool definitions.
-   * @param {object} [options={}] - Options (temperature, maxTokens).
-   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @param {Message[]} messages - Conversation messages.
+   * @param {ToolDef[]} [tools=[]] - Tool definitions.
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+   * @returns {Promise<GenerateResult>}
    * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
    */
   async generate(messages, tools = [], options = {}) {
+    /** @type {Record<string, any>} */
     const body = {
       model: this.model,
       messages,
@@ -51,7 +61,7 @@ class OpenAIProvider {
 
     return {
       text: msg.content || '',
-      toolCalls: (msg.tool_calls || []).map(tc => ({
+      toolCalls: (msg.tool_calls || []).map((/** @type {any} */ tc) => ({
         id: tc.id,
         name: tc.function.name,
         arguments: JSON.parse(tc.function.arguments),
@@ -63,6 +73,11 @@ class OpenAIProvider {
     };
   }
 
+  /**
+   * @param {string} path
+   * @param {Record<string, any>} body
+   * @returns {Promise<any>}
+   */
   _request(path, body) {
     return new Promise((resolve, reject) => {
       const url = new URL(this.baseUrl + path);
@@ -82,10 +97,10 @@ class OpenAIProvider {
         res.on('end', () => {
           try {
             const parsed = JSON.parse(chunks);
-            if (res.statusCode >= 400) {
+            if ((res.statusCode ?? 0) >= 400) {
               return reject(new ProviderError(
                 `[OpenAIProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
-                { status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined }
+                /** @type {any} */ ({ status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined })
               ));
             }
             resolve(parsed);

package/src/providers.d.ts

@@ -0,0 +1,6 @@
+import { OpenAIProvider } from "./provider-openai";
+import { AnthropicProvider } from "./provider-anthropic";
+import { OllamaProvider } from "./provider-ollama";
+import { CLIPipeProvider } from "./provider-clipipe";
+import { FallbackProvider } from "./provider-fallback";
+export { OpenAIProvider as OpenAI, AnthropicProvider as Anthropic, OllamaProvider as Ollama, CLIPipeProvider as CLIPipe, FallbackProvider as Fallback, OpenAIProvider, AnthropicProvider, OllamaProvider, CLIPipeProvider, FallbackProvider };

package/src/providers.js

@@ -7,9 +7,17 @@ const { CLIPipeProvider } = require('./provider-clipipe');
 const { FallbackProvider } = require('./provider-fallback');
 
 module.exports = {
+  // Short names (canonical — used throughout docs and the integration guide)
   OpenAI: OpenAIProvider,
   Anthropic: AnthropicProvider,
   Ollama: OllamaProvider,
   CLIPipe: CLIPipeProvider,
   Fallback: FallbackProvider,
+  // *Provider aliases match the class names in source/stack traces, so
+  // `const { OpenAIProvider } = require('bare-agent/providers')` also works.
+  OpenAIProvider,
+  AnthropicProvider,
+  OllamaProvider,
+  CLIPipeProvider,
+  FallbackProvider,
 };

package/src/retry.d.ts

@@ -0,0 +1,44 @@
+export type RetryOptions = {
+    /**
+     * - Maximum number of attempts.
+     */
+    maxAttempts?: number | undefined;
+    /**
+     * - Backoff strategy or fixed ms.
+     */
+    backoff?: number | "linear" | "exponential" | undefined;
+    /**
+     * - Per-attempt timeout in ms (0 to disable).
+     */
+    timeout?: number | undefined;
+    /**
+     * - Predicate deciding whether to retry an error.
+     */
+    retryOn?: ((err: any) => boolean) | undefined;
+    /**
+     * - Jitter strategy.
+     */
+    jitter?: number | boolean | "full" | "equal" | undefined;
+};
+export class Retry {
+    /** @param {RetryOptions} [options={}] */
+    constructor(options?: RetryOptions);
+    maxAttempts: number;
+    backoff: number | "linear" | "exponential";
+    timeout: number;
+    retryOn: (err: any) => boolean;
+    jitter: number | boolean | "full" | "equal";
+    /**
+     * Call a function with retry logic.
+     * @param {() => Promise<*>} fn - Async function to execute.
+     * @param {RetryOptions} [options={}] - Per-call overrides for maxAttempts, retryOn, timeout.
+     * @returns {Promise<*>} The result of fn().
+     * @throws {TimeoutError} When an individual attempt exceeds the timeout.
+     * @throws {Error} Rethrows the last error when maxAttempts is exhausted or error is not retryable.
+     */
+    call(fn: () => Promise<any>, options?: RetryOptions): Promise<any>;
+    /** @param {number} attempt */
+    _delay(attempt: number): number;
+    /** @param {number} base */
+    _applyJitter(base: number): number;
+}

package/src/retry.js

@@ -2,6 +2,16 @@
 
 const { TimeoutError } = require('./errors');
 
+/**
+ * @typedef {object} RetryOptions
+ * @property {number} [maxAttempts=3] - Maximum number of attempts.
+ * @property {number|'linear'|'exponential'} [backoff='exponential'] - Backoff strategy or fixed ms.
+ * @property {number} [timeout=60000] - Per-attempt timeout in ms (0 to disable).
+ * @property {(err: any) => boolean} [retryOn] - Predicate deciding whether to retry an error.
+ * @property {boolean|number|'full'|'equal'} [jitter=false] - Jitter strategy.
+ */
+
+/** @param {any} err */
 const DEFAULT_RETRY_ON = (err) => {
   if (err.retryable === true) return true;
   if (err.retryable === false) return false;
@@ -13,6 +23,7 @@ const DEFAULT_RETRY_ON = (err) => {
 };
 
 class Retry {
+  /** @param {RetryOptions} [options={}] */
   constructor(options = {}) {
     this.maxAttempts = options.maxAttempts !== undefined ? options.maxAttempts : 3;
     this.backoff = options.backoff || 'exponential';
@@ -24,7 +35,7 @@ class Retry {
   /**
    * Call a function with retry logic.
    * @param {() => Promise<*>} fn - Async function to execute.
-   * @param {object} [options={}] - Per-call overrides for maxAttempts, retryOn, timeout.
+   * @param {RetryOptions} [options={}] - Per-call overrides for maxAttempts, retryOn, timeout.
    * @returns {Promise<*>} The result of fn().
    * @throws {TimeoutError} When an individual attempt exceeds the timeout.
    * @throws {Error} Rethrows the last error when maxAttempts is exhausted or error is not retryable.
@@ -35,6 +46,7 @@ class Retry {
     const timeout = options.timeout !== undefined ? options.timeout : this.timeout;
 
     for (let attempt = 1; attempt <= max; attempt++) {
+      /** @type {NodeJS.Timeout|undefined} */
       let timeoutId;
       try {
         const result = await (timeout
@@ -56,6 +68,7 @@ class Retry {
     }
   }
 
+  /** @param {number} attempt */
   _delay(attempt) {
     let base;
     if (typeof this.backoff === 'number') {
@@ -68,6 +81,7 @@ class Retry {
     return this._applyJitter(base);
   }
 
+  /** @param {number} base */
   _applyJitter(base) {
     if (this.jitter === false || this.jitter === 0) return base;
     if (this.jitter === 'full') {

package/src/run-plan.d.ts

@@ -0,0 +1,126 @@
+export type StateMachine = import("./state").StateMachine;
+export type Retry = import("./retry").Retry;
+export type Step = {
+    /**
+     * - Unique step identifier.
+     */
+    id: string;
+    /**
+     * - Description of the step to execute.
+     */
+    action: string;
+    /**
+     * - Ids of steps that must complete first.
+     */
+    dependsOn?: string[] | undefined;
+};
+export type TrackingEntry = {
+    /**
+     * - The (cloned) step being tracked.
+     */
+    step: Step;
+    /**
+     * - Lifecycle status: pending/running/done/failed.
+     */
+    status: string;
+    /**
+     * - Result returned by executeFn on success.
+     */
+    result: any;
+    /**
+     * - Error message on failure.
+     */
+    error: string | undefined;
+};
+export type RunPlanOptions = {
+    /**
+     * - Max parallel steps per wave.
+     */
+    concurrency?: number | undefined;
+    /**
+     * - StateMachine instance for lifecycle tracking.
+     */
+    stateMachine?: import("./state").StateMachine | undefined;
+    /**
+     * - Callback fired when a step begins.
+     */
+    onStepStart?: ((step: Step) => void) | undefined;
+    /**
+     * - Callback fired on success.
+     */
+    onStepDone?: ((step: Step, result: any) => void) | undefined;
+    /**
+     * - Callback fired on failure.
+     */
+    onStepFail?: ((step: Step, error: Error) => void) | undefined;
+    /**
+     * - Callback fired before each wave executes.
+     */
+    onWaveStart?: ((waveNumber: number, steps: Step[]) => void) | undefined;
+    /**
+     * - Optional Retry instance wrapping each step execution.
+     */
+    stepRetry?: import("./retry").Retry | undefined;
+};
+export type StepResult = {
+    /**
+     * - Step id.
+     */
+    id: string;
+    /**
+     * - Final status.
+     */
+    status: string;
+    /**
+     * - Result value if the step succeeded.
+     */
+    result?: any;
+    /**
+     * - Error message if the step failed.
+     */
+    error?: string | undefined;
+};
+/** @typedef {import('./state').StateMachine} StateMachine */
+/** @typedef {import('./retry').Retry} Retry */
+/**
+ * @typedef {object} Step
+ * @property {string} id - Unique step identifier.
+ * @property {string} action - Description of the step to execute.
+ * @property {string[]} [dependsOn] - Ids of steps that must complete first.
+ */
+/**
+ * @typedef {object} TrackingEntry
+ * @property {Step} step - The (cloned) step being tracked.
+ * @property {string} status - Lifecycle status: pending/running/done/failed.
+ * @property {*} result - Result returned by executeFn on success.
+ * @property {string|undefined} error - Error message on failure.
+ */
+/**
+ * @typedef {object} RunPlanOptions
+ * @property {number} [concurrency=Infinity] - Max parallel steps per wave.
+ * @property {StateMachine} [stateMachine] - StateMachine instance for lifecycle tracking.
+ * @property {(step: Step) => void} [onStepStart] - Callback fired when a step begins.
+ * @property {(step: Step, result: any) => void} [onStepDone] - Callback fired on success.
+ * @property {(step: Step, error: Error) => void} [onStepFail] - Callback fired on failure.
+ * @property {(waveNumber: number, steps: Step[]) => void} [onWaveStart] - Callback fired before each wave executes.
+ * @property {Retry} [stepRetry] - Optional Retry instance wrapping each step execution.
+ */
+/**
+ * @typedef {object} StepResult
+ * @property {string} id - Step id.
+ * @property {string} status - Final status.
+ * @property {*} [result] - Result value if the step succeeded.
+ * @property {string} [error] - Error message if the step failed.
+ */
+/**
+ * Execute a step DAG with wave-based parallelism.
+ * @param {Step[]} steps - Steps from Planner.
+ * @param {(step: Step) => any} executeFn - Async function called for each step: (step) => result.
+ * @param {RunPlanOptions} [options={}]
+ * @returns {Promise<StepResult[]>}
+ * @throws {Error} `[runPlan] steps must be a non-empty array` — when steps is not a non-empty array.
+ * @throws {Error} `[runPlan] executeFn must be a function` — when executeFn is not a function.
+ * @throws {Error} `[runPlan] duplicate step id: "X"` — when two steps share an id.
+ * @throws {Error} `[runPlan] step "X" depends on unknown step "Y"` — when dependsOn references missing id.
+ */
+export function runPlan(steps: Step[], executeFn: (step: Step) => any, options?: RunPlanOptions): Promise<StepResult[]>;

package/src/run-plan.js

@@ -1,17 +1,48 @@
 'use strict';
 
+/** @typedef {import('./state').StateMachine} StateMachine */
+/** @typedef {import('./retry').Retry} Retry */
+
+/**
+ * @typedef {object} Step
+ * @property {string} id - Unique step identifier.
+ * @property {string} action - Description of the step to execute.
+ * @property {string[]} [dependsOn] - Ids of steps that must complete first.
+ */
+
+/**
+ * @typedef {object} TrackingEntry
+ * @property {Step} step - The (cloned) step being tracked.
+ * @property {string} status - Lifecycle status: pending/running/done/failed.
+ * @property {*} result - Result returned by executeFn on success.
+ * @property {string|undefined} error - Error message on failure.
+ */
+
+/**
+ * @typedef {object} RunPlanOptions
+ * @property {number} [concurrency=Infinity] - Max parallel steps per wave.
+ * @property {StateMachine} [stateMachine] - StateMachine instance for lifecycle tracking.
+ * @property {(step: Step) => void} [onStepStart] - Callback fired when a step begins.
+ * @property {(step: Step, result: any) => void} [onStepDone] - Callback fired on success.
+ * @property {(step: Step, error: Error) => void} [onStepFail] - Callback fired on failure.
+ * @property {(waveNumber: number, steps: Step[]) => void} [onWaveStart] - Callback fired before each wave executes.
+ * @property {Retry} [stepRetry] - Optional Retry instance wrapping each step execution.
+ */
+
+/**
+ * @typedef {object} StepResult
+ * @property {string} id - Step id.
+ * @property {string} status - Final status.
+ * @property {*} [result] - Result value if the step succeeded.
+ * @property {string} [error] - Error message if the step failed.
+ */
+
 /**
  * Execute a step DAG with wave-based parallelism.
- * @param {Array<{id: string, action: string, dependsOn?: string[]}>} steps - Steps from Planner.
- * @param {function} executeFn - Async function called for each step: (step) => result.
- * @param {object} [options={}]
- * @param {number} [options.concurrency=Infinity] - Max parallel steps per wave.
- * @param {object} [options.stateMachine] - StateMachine instance for lifecycle tracking.
- * @param {function} [options.onStepStart] - Callback(step) fired when a step begins.
- * @param {function} [options.onStepDone] - Callback(step, result) fired on success.
- * @param {function} [options.onStepFail] - Callback(step, error) fired on failure.
- * @param {function} [options.onWaveStart] - Callback(waveNumber, steps) fired before each wave executes.
- * @returns {Promise<Array<{id: string, status: string, result?: *, error?: string}>>}
+ * @param {Step[]} steps - Steps from Planner.
+ * @param {(step: Step) => any} executeFn - Async function called for each step: (step) => result.
+ * @param {RunPlanOptions} [options={}]
+ * @returns {Promise<StepResult[]>}
  * @throws {Error} `[runPlan] steps must be a non-empty array` — when steps is not a non-empty array.
  * @throws {Error} `[runPlan] executeFn must be a function` — when executeFn is not a function.
  * @throws {Error} `[runPlan] duplicate step id: "X"` — when two steps share an id.
@@ -26,6 +57,7 @@ async function runPlan(steps, executeFn, options = {}) {
   }
 
   // Build tracking map (don't mutate input)
+  /** @type {Map<string, TrackingEntry>} */
   const tracking = new Map();
   for (const step of steps) {
     if (tracking.has(step.id)) {
@@ -59,7 +91,7 @@ async function runPlan(steps, executeFn, options = {}) {
       if (entry.status !== 'pending') continue;
       for (const dep of (entry.step.dependsOn || [])) {
         const depEntry = tracking.get(dep);
-        if (depEntry.status === 'failed') {
+        if (depEntry && depEntry.status === 'failed') {
           entry.status = 'failed';
           entry.error = `dependency '${dep}' failed`;
           stateMachine?.transition(id, 'start');
@@ -75,7 +107,7 @@ async function runPlan(steps, executeFn, options = {}) {
     for (const [id, entry] of tracking) {
       if (entry.status !== 'pending') continue;
       const deps = entry.step.dependsOn || [];
-      const allDone = deps.every(dep => tracking.get(dep).status === 'done');
+      const allDone = deps.every(/** @param {string} dep */ dep => tracking.get(dep)?.status === 'done');
       if (allDone) ready.push(entry);
     }
 
@@ -113,7 +145,8 @@ async function runPlan(steps, executeFn, options = {}) {
 
   // Return results in original order
   return steps.map(s => {
-    const entry = tracking.get(s.id);
+    const entry = /** @type {TrackingEntry} */ (tracking.get(s.id));
+    /** @type {StepResult} */
     const out = { id: s.id, status: entry.status };
     if (entry.result !== undefined) out.result = entry.result;
     if (entry.error !== undefined) out.error = entry.error;

package/src/scheduler.d.ts

@@ -0,0 +1,102 @@
+export type Job = {
+    id: number;
+    type: string;
+    schedule: string;
+    action: any;
+    status: string;
+    nextRun: string;
+    createdAt?: string | undefined;
+};
+export type SchedulerOptions = {
+    /**
+     * - Path to JSON persistence file.
+     */
+    file?: string | null | undefined;
+    /**
+     * - Tick interval in ms.
+     */
+    interval?: number | undefined;
+    /**
+     * - Handler errors callback.
+     */
+    onError?: ((err: any, job: Job) => void) | null | undefined;
+};
+/**
+ * Time-triggered agent turns. The only way the agent acts without being messaged.
+ *
+ * Interface:
+ *   add(job)        → jobId
+ *   remove(jobId)   → void
+ *   list()          → [jobs]
+ *   start(handler)  → begin tick loop (handler receives due jobs)
+ *   stop()          → stop tick loop
+ */
+/**
+ * @typedef {object} Job
+ * @property {number} id
+ * @property {string} type
+ * @property {string} schedule
+ * @property {*} action
+ * @property {string} status
+ * @property {string} nextRun
+ * @property {string} [createdAt]
+ */
+/**
+ * @typedef {object} SchedulerOptions
+ * @property {string|null} [file] - Path to JSON persistence file.
+ * @property {number} [interval=60000] - Tick interval in ms.
+ * @property {((err: any, job: Job) => void)|null} [onError] - Handler errors callback.
+ */
+export class Scheduler {
+    /** @param {SchedulerOptions} [options={}] */
+    constructor(options?: SchedulerOptions);
+    _file: string | null;
+    _interval: number;
+    onError: ((err: any, job: Job) => void) | null;
+    /** @type {Job[]} */
+    _jobs: Job[];
+    /** @type {NodeJS.Timeout|null} */
+    _timer: NodeJS.Timeout | null;
+    /** @type {Set<number>} */
+    _running: Set<number>;
+    _nextId: number;
+    _save(): void;
+    /** @param {{ type?: string, schedule: string, action: * }} job */
+    add(job: {
+        type?: string;
+        schedule: string;
+        action: any;
+    }): number;
+    /** @param {number} jobId */
+    remove(jobId: number): void;
+    list(): {
+        id: number;
+        type: string;
+        schedule: string;
+        action: any;
+        status: string;
+        nextRun: string;
+        createdAt?: string | undefined;
+    }[];
+    /**
+     * Begin the tick loop. Calls `handler(job)` for each due job every tick interval.
+     *
+     * - `handler` is called with the full job object: `{ id, type, schedule, action, status, nextRun }`.
+     * - Jobs that are still running (handler hasn't resolved) are skipped on subsequent ticks
+     *   via the internal `_running` Set — this prevents overlapping executions of the same job.
+     * - Within a single tick, due jobs are executed sequentially (awaited one at a time).
+     * - If a handler throws, the error is passed to `onError(err, job)` if configured.
+     *   The tick loop continues to the next job — handler errors never crash the scheduler.
+     *
+     * @param {(job: object) => Promise<void>} handler - Async function called for each due job.
+     */
+    start(handler: (job: object) => Promise<void>): void;
+    stop(): void;
+    /**
+     * @param {string} schedule - Relative ('5s','30m','2h','1d') or cron expression.
+     * @returns {Date} The next run time.
+     * @throws {Error} `[Scheduler] Cannot parse schedule` — when format is not recognized.
+     * @private
+     */
+    private _parseSchedule;
+}