bare-agent 0.11.0 → 0.12.1

package/src/scheduler.js

@@ -12,17 +12,41 @@ const { readFileSync, writeFileSync, existsSync } = require('node:fs');
  *   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.
+ */
+
 class Scheduler {
+  /** @param {SchedulerOptions} [options={}] */
   constructor(options = {}) {
     this._file = options.file || null;
     this._interval = options.interval || 60000;
     this.onError = options.onError || null;
+    /** @type {Job[]} */
     this._jobs = this._file && existsSync(this._file)
       ? JSON.parse(readFileSync(this._file, 'utf8'))
       : [];
+    /** @type {NodeJS.Timeout|null} */
     this._timer = null;
+    /** @type {Set<number>} */
+    this._running = new Set();
     this._nextId = this._jobs.length
-      ? this._jobs.reduce((max, j) => Math.max(max, j.id), 0) + 1
+      ? this._jobs.reduce((/** @type {number} */ max, /** @type {Job} */ j) => Math.max(max, j.id), 0) + 1
       : 1;
   }
 
@@ -30,6 +54,7 @@ class Scheduler {
     if (this._file) writeFileSync(this._file, JSON.stringify(this._jobs, null, 2));
   }
 
+  /** @param {{ type?: string, schedule: string, action: * }} job */
   add(job) {
     const id = this._nextId++;
     const nextRun = this._parseSchedule(job.schedule);
@@ -46,13 +71,14 @@ class Scheduler {
     return id;
   }
 
+  /** @param {number} jobId */
   remove(jobId) {
-    this._jobs = this._jobs.filter(j => j.id !== jobId);
+    this._jobs = this._jobs.filter((/** @type {Job} */ j) => j.id !== jobId);
     this._save();
   }
 
   list() {
-    return this._jobs.map(j => ({ ...j }));
+    return this._jobs.map((/** @type {Job} */ j) => ({ ...j }));
   }
 
   /**
@@ -114,7 +140,9 @@ class Scheduler {
     const rel = schedule.match(/^(\d+)(s|m|h|d)$/);
     if (rel) {
       const [, n, unit] = rel;
-      const ms = { s: 1000, m: 60000, h: 3600000, d: 86400000 }[unit];
+      /** @type {Record<string, number>} */
+      const units = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+      const ms = units[unit];
       return new Date(Date.now() + Number(n) * ms);
     }
     // Cron: try cron-parser

package/src/state.d.ts

@@ -0,0 +1,45 @@
+export type Task = {
+    status: string;
+    data: any;
+    error: any;
+    updatedAt: string;
+};
+/**
+ * @typedef {object} Task
+ * @property {string} status
+ * @property {*} data
+ * @property {*} error
+ * @property {string} updatedAt
+ */
+export class StateMachine extends EventEmitter<[never]> {
+    /** @param {{ file?: string|null }} [options={}] */
+    constructor(options?: {
+        file?: string | null;
+    });
+    file: string | null;
+    /** @type {Map<string, Task>} */
+    tasks: Map<string, Task>;
+    /**
+     * Transition a task to a new state.
+     * @param {string} taskId - Task identifier.
+     * @param {string} event - Transition event (start, complete, fail, pause, resume, cancel, retry).
+     * @param {*} [data] - Optional data to attach to the task.
+     * @returns {string} The new status.
+     * @throws {Error} `[StateMachine] Invalid transition` — when the event is not valid for the current state.
+     */
+    transition(taskId: string, event: string, data?: any): string;
+    /** @param {string} taskId */
+    getStatus(taskId: string): Task | null;
+    /** @param {(event: { taskId: string, from: string, to: string, event: string, data: * }) => void} callback */
+    onTransition(callback: (event: {
+        taskId: string;
+        from: string;
+        to: string;
+        event: string;
+        data: any;
+    }) => void): () => this;
+    getAll(): Record<string, Task>;
+    _load(): void;
+    _save(): void;
+}
+import { EventEmitter } from "events";

package/src/state.js

@@ -3,6 +3,7 @@
 const { readFileSync, writeFileSync } = require('fs');
 const { EventEmitter } = require('events');
 
+/** @type {Record<string, Record<string, string>>} */
 const TRANSITIONS = {
   pending:            { start: 'running', cancel: 'cancelled' },
   running:            { complete: 'done', fail: 'failed', pause: 'waiting_for_input', cancel: 'cancelled' },
@@ -11,10 +12,20 @@ const TRANSITIONS = {
   // done and cancelled are terminal
 };
 
+/**
+ * @typedef {object} Task
+ * @property {string} status
+ * @property {*} data
+ * @property {*} error
+ * @property {string} updatedAt
+ */
+
 class StateMachine extends EventEmitter {
+  /** @param {{ file?: string|null }} [options={}] */
   constructor(options = {}) {
     super();
     this.file = options.file || null;
+    /** @type {Map<string, Task>} */
     this.tasks = new Map();
     if (this.file) this._load();
   }
@@ -51,35 +62,40 @@ class StateMachine extends EventEmitter {
     return task.status;
   }
 
+  /** @param {string} taskId */
   getStatus(taskId) {
     return this.tasks.get(taskId) || null;
   }
 
+  /** @param {(event: { taskId: string, from: string, to: string, event: string, data: * }) => void} callback */
   onTransition(callback) {
     this.on('transition', callback);
     return () => this.off('transition', callback);
   }
 
   getAll() {
+    /** @type {Record<string, Task>} */
     const result = {};
     for (const [id, task] of this.tasks) result[id] = { ...task };
     return result;
   }
 
   _load() {
+    if (!this.file) return;
     try {
       const raw = readFileSync(this.file, 'utf8');
       const data = JSON.parse(raw);
-      for (const [id, task] of Object.entries(data)) this.tasks.set(id, task);
+      for (const [id, task] of Object.entries(data)) this.tasks.set(id, /** @type {Task} */ (task));
     } catch (e) {
       if (e.code !== 'ENOENT') throw e;
     }
   }
 
   _save() {
+    /** @type {Record<string, Task>} */
     const obj = {};
     for (const [id, task] of this.tasks) obj[id] = task;
-    writeFileSync(this.file, JSON.stringify(obj, null, 2) + '\n');
+    if (this.file) writeFileSync(this.file, JSON.stringify(obj, null, 2) + '\n');
   }
 }
 

package/src/store-jsonfile.d.ts

@@ -0,0 +1,85 @@
+/**
+ * JSON file memory store. Zero deps, case-insensitive substring search.
+ *
+ * SCALING: intended for small memory sets. `search()` is an O(n) substring scan
+ * (no index), and every `store()`/`delete()` re-serializes and rewrites the entire
+ * file synchronously. Fine for hundreds–low-thousands of entries; for larger or
+ * write-heavy memory use SQLiteStore (FTS5 index, parameterized, incremental writes).
+ *
+ * Interface (implements Memory store contract):
+ *   store(content, metadata)   → id
+ *   search(query, options)     → [{ id, content, metadata, score }]
+ *   get(id)                    → { content, metadata }
+ *   delete(id)                 → void
+ */
+export type JsonRecord = {
+    id: number;
+    content: any;
+    metadata: Record<string, any>;
+    createdAt: string;
+};
+/**
+ * JSON file memory store. Zero deps, case-insensitive substring search.
+ *
+ * SCALING: intended for small memory sets. `search()` is an O(n) substring scan
+ * (no index), and every `store()`/`delete()` re-serializes and rewrites the entire
+ * file synchronously. Fine for hundreds–low-thousands of entries; for larger or
+ * write-heavy memory use SQLiteStore (FTS5 index, parameterized, incremental writes).
+ *
+ * Interface (implements Memory store contract):
+ *   store(content, metadata)   → id
+ *   search(query, options)     → [{ id, content, metadata, score }]
+ *   get(id)                    → { content, metadata }
+ *   delete(id)                 → void
+ *
+ * @typedef {object} JsonRecord
+ * @property {number} id
+ * @property {any} content
+ * @property {Record<string, any>} metadata
+ * @property {string} createdAt
+ */
+export class JsonFileStore {
+    /**
+     * @param {{ path?: string }} [options]
+     * @throws {Error} `[JsonFileStore] requires options.path` — when path is missing.
+     */
+    constructor(options?: {
+        path?: string;
+    });
+    _path: string;
+    /** @type {JsonRecord[]} */
+    _data: JsonRecord[];
+    _nextId: number;
+    _warnedLarge: boolean;
+    _save(): void;
+    /**
+     * @param {any} content
+     * @param {Record<string, any>} [metadata]
+     * @returns {number} id
+     */
+    store(content: any, metadata?: Record<string, any>): number;
+    /**
+     * @param {string} query
+     * @param {{ limit?: number }} [options]
+     * @returns {Array<JsonRecord & { score: number }>}
+     */
+    search(query: string, options?: {
+        limit?: number;
+    }): Array<JsonRecord & {
+        score: number;
+    }>;
+    /**
+     * @param {number} id
+     * @returns {{ id: number, content: any, metadata: Record<string, any> } | null}
+     */
+    get(id: number): {
+        id: number;
+        content: any;
+        metadata: Record<string, any>;
+    } | null;
+    /**
+     * @param {number} id
+     * @returns {void}
+     */
+    delete(id: number): void;
+}

package/src/store-jsonfile.js

@@ -19,21 +19,28 @@ const LARGE_STORE_THRESHOLD = 10000;
  *   search(query, options)     → [{ id, content, metadata, score }]
  *   get(id)                    → { content, metadata }
  *   delete(id)                 → void
+ *
+ * @typedef {object} JsonRecord
+ * @property {number} id
+ * @property {any} content
+ * @property {Record<string, any>} metadata
+ * @property {string} createdAt
  */
+
 class JsonFileStore {
   /**
-   * @param {object} options
-   * @param {string} options.path - Path to JSON file (required).
+   * @param {{ path?: string }} [options]
    * @throws {Error} `[JsonFileStore] requires options.path` — when path is missing.
    */
   constructor(options = {}) {
     if (!options.path) throw new Error('[JsonFileStore] requires options.path');
     this._path = options.path;
+    /** @type {JsonRecord[]} */
     this._data = existsSync(this._path)
       ? JSON.parse(readFileSync(this._path, 'utf8'))
       : [];
     this._nextId = this._data.length
-      ? this._data.reduce((max, d) => Math.max(max, d.id), 0) + 1
+      ? this._data.reduce((/** @type {number} */ max, /** @type {JsonRecord} */ d) => Math.max(max, d.id), 0) + 1
       : 1;
     this._warnedLarge = false;
   }
@@ -42,6 +49,11 @@ class JsonFileStore {
     writeFileSync(this._path, JSON.stringify(this._data, null, 2));
   }
 
+  /**
+   * @param {any} content
+   * @param {Record<string, any>} [metadata]
+   * @returns {number} id
+   */
   store(content, metadata = {}) {
     const id = this._nextId++;
     this._data.push({ id, content, metadata, createdAt: new Date().toISOString() });
@@ -56,23 +68,36 @@ class JsonFileStore {
     return id;
   }
 
+  /**
+   * @param {string} query
+   * @param {{ limit?: number }} [options]
+   * @returns {Array<JsonRecord & { score: number }>}
+   */
   search(query, options = {}) {
     const limit = options.limit || 10;
     const q = (query || '').toLowerCase();
-    if (!q) return this._data.slice(0, limit).map(d => ({ ...d, score: 1 }));
+    if (!q) return this._data.slice(0, limit).map((/** @type {JsonRecord} */ d) => ({ ...d, score: 1 }));
     return this._data
-      .filter(d => d.content.toLowerCase().includes(q))
+      .filter((/** @type {JsonRecord} */ d) => d.content.toLowerCase().includes(q))
       .slice(0, limit)
-      .map(d => ({ ...d, score: 1 }));
+      .map((/** @type {JsonRecord} */ d) => ({ ...d, score: 1 }));
   }
 
+  /**
+   * @param {number} id
+   * @returns {{ id: number, content: any, metadata: Record<string, any> } | null}
+   */
   get(id) {
-    const item = this._data.find(d => d.id === id);
+    const item = this._data.find((/** @type {JsonRecord} */ d) => d.id === id);
     return item ? { id: item.id, content: item.content, metadata: item.metadata } : null;
   }
 
+  /**
+   * @param {number} id
+   * @returns {void}
+   */
   delete(id) {
-    this._data = this._data.filter(d => d.id !== id);
+    this._data = this._data.filter((/** @type {JsonRecord} */ d) => d.id !== id);
     this._save();
   }
 }

package/src/store-sqlite.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SQLite FTS5 memory store. Full-text search with BM25 ranking.
+ *
+ * Interface (implements Memory store contract):
+ *   store(content, metadata)   → id
+ *   search(query, options)     → [{ id, content, metadata, score }]
+ *   get(id)                    → { content, metadata }
+ *   delete(id)                 → void
+ *
+ * Requires peer dep: better-sqlite3
+ */
+export type ChunkRow = {
+    id: number;
+    content: string;
+    /**
+     * - JSON-serialized metadata.
+     */
+    metadata: string;
+    /**
+     * - FTS5 rank (search rows only).
+     */
+    rank?: number | undefined;
+};
+/**
+ * SQLite FTS5 memory store. Full-text search with BM25 ranking.
+ *
+ * Interface (implements Memory store contract):
+ *   store(content, metadata)   → id
+ *   search(query, options)     → [{ id, content, metadata, score }]
+ *   get(id)                    → { content, metadata }
+ *   delete(id)                 → void
+ *
+ * Requires peer dep: better-sqlite3
+ *
+ * @typedef {object} ChunkRow
+ * @property {number} id
+ * @property {string} content
+ * @property {string} metadata - JSON-serialized metadata.
+ * @property {number} [rank] - FTS5 rank (search rows only).
+ */
+export class SQLiteStore {
+    /**
+     * @param {{ path?: string }} [options]
+     * @throws {Error} `[SQLiteStore] requires options.path` — when path is missing.
+     * @throws {Error} `[SQLiteStore] requires better-sqlite3` — when peer dep is not installed.
+     */
+    constructor(options?: {
+        path?: string;
+    });
+    _db: any;
+    _insertStmt: any;
+    _getStmt: any;
+    _deleteStmt: any;
+    _searchStmt: any;
+    _allStmt: any;
+    /**
+     * @param {any} content
+     * @param {Record<string, any>} [metadata]
+     * @returns {number} id
+     */
+    store(content: any, metadata?: Record<string, any>): number;
+    /**
+     * @param {string} query
+     * @param {{ limit?: number }} [options]
+     * @returns {Array<{ id: number, content: string, metadata: Record<string, any>, score: number }>}
+     */
+    search(query: string, options?: {
+        limit?: number;
+    }): Array<{
+        id: number;
+        content: string;
+        metadata: Record<string, any>;
+        score: number;
+    }>;
+    /**
+     * @param {number} id
+     * @returns {{ id: number, content: string, metadata: Record<string, any> } | null}
+     */
+    get(id: number): {
+        id: number;
+        content: string;
+        metadata: Record<string, any>;
+    } | null;
+    /**
+     * @param {number} id
+     * @returns {void}
+     */
+    delete(id: number): void;
+    close(): void;
+}

package/src/store-sqlite.js

@@ -10,11 +10,17 @@
  *   delete(id)                 → void
  *
  * Requires peer dep: better-sqlite3
+ *
+ * @typedef {object} ChunkRow
+ * @property {number} id
+ * @property {string} content
+ * @property {string} metadata - JSON-serialized metadata.
+ * @property {number} [rank] - FTS5 rank (search rows only).
  */
+
 class SQLiteStore {
   /**
-   * @param {object} options
-   * @param {string} options.path - Path to SQLite database file (required).
+   * @param {{ path?: string }} [options]
    * @throws {Error} `[SQLiteStore] requires options.path` — when path is missing.
    * @throws {Error} `[SQLiteStore] requires better-sqlite3` — when peer dep is not installed.
    */
@@ -77,6 +83,11 @@ class SQLiteStore {
     );
   }
 
+  /**
+   * @param {any} content
+   * @param {Record<string, any>} [metadata]
+   * @returns {number} id
+   */
   store(content, metadata = {}) {
     const result = this._insertStmt.run(
       content,
@@ -86,10 +97,15 @@ class SQLiteStore {
     return Number(result.lastInsertRowid);
   }
 
+  /**
+   * @param {string} query
+   * @param {{ limit?: number }} [options]
+   * @returns {Array<{ id: number, content: string, metadata: Record<string, any>, score: number }>}
+   */
   search(query, options = {}) {
     const limit = options.limit || 10;
     if (!query) {
-      return this._allStmt.all(limit).map(row => ({
+      return this._allStmt.all(limit).map((/** @type {ChunkRow} */ row) => ({
         id: row.id,
         content: row.content,
         metadata: JSON.parse(row.metadata),
@@ -100,14 +116,14 @@ class SQLiteStore {
     const ftsQuery = query
       .split(/\s+/)
       .filter(Boolean)
-      .map(w => `"${w.replace(/"/g, '""')}"`)
+      .map((/** @type {string} */ w) => `"${w.replace(/"/g, '""')}"`)
       .join(' OR ');
     try {
-      return this._searchStmt.all(ftsQuery, limit).map(row => ({
+      return this._searchStmt.all(ftsQuery, limit).map((/** @type {ChunkRow} */ row) => ({
         id: row.id,
         content: row.content,
         metadata: JSON.parse(row.metadata),
-        score: -row.rank, // FTS5 rank is negative (closer to 0 = better)
+        score: -(row.rank ?? 0), // FTS5 rank is negative (closer to 0 = better)
       }));
     } catch {
       // If FTS query fails (e.g. special characters), return empty
@@ -115,12 +131,20 @@ class SQLiteStore {
     }
   }
 
+  /**
+   * @param {number} id
+   * @returns {{ id: number, content: string, metadata: Record<string, any> } | null}
+   */
   get(id) {
-    const row = this._getStmt.get(id);
+    const row = /** @type {ChunkRow | undefined} */ (this._getStmt.get(id));
     if (!row) return null;
     return { id: row.id, content: row.content, metadata: JSON.parse(row.metadata) };
   }
 
+  /**
+   * @param {number} id
+   * @returns {void}
+   */
   delete(id) {
     this._deleteStmt.run(id);
   }

package/src/stores.d.ts

@@ -0,0 +1,3 @@
+import { SQLiteStore } from "./store-sqlite";
+import { JsonFileStore } from "./store-jsonfile";
+export { SQLiteStore as SQLite, JsonFileStore as JsonFile };

package/src/stream.d.ts

@@ -0,0 +1,79 @@
+export type StreamEvent = {
+    /**
+     * - Event type identifier.
+     */
+    type: string;
+    /**
+     * - Associated task identifier.
+     */
+    taskId?: string | undefined;
+    /**
+     * - Arbitrary event payload.
+     */
+    data?: any;
+    /**
+     * - ISO timestamp; auto-filled on emit if absent.
+     */
+    ts?: string | undefined;
+};
+export type Transport = {
+    /**
+     * - Sink for emitted events.
+     */
+    write: (event: StreamEvent) => void;
+};
+export type StreamOptions = {
+    /**
+     * - Optional transport sink for emitted events.
+     */
+    transport?: Transport | null | undefined;
+};
+/**
+ * Structured event streaming for observability and cross-process communication.
+ *
+ * Interface:
+ *   emit(event)            → void
+ *   subscribe(callback)    → unsubscribe function
+ *
+ * Event shape:
+ *   { type, taskId, data, ts }
+ *
+ * Transport:
+ *   Object with write(event) method — e.g. JsonlTransport
+ *   null — disabled (subscribers only)
+ */
+/**
+ * @typedef {object} StreamEvent
+ * @property {string} type - Event type identifier.
+ * @property {string} [taskId] - Associated task identifier.
+ * @property {*} [data] - Arbitrary event payload.
+ * @property {string} [ts] - ISO timestamp; auto-filled on emit if absent.
+ */
+/**
+ * @typedef {object} Transport
+ * @property {(event: StreamEvent) => void} write - Sink for emitted events.
+ */
+/**
+ * @typedef {object} StreamOptions
+ * @property {Transport|null} [transport] - Optional transport sink for emitted events.
+ */
+export class Stream {
+    /**
+     * @param {StreamOptions} [options={}]
+     */
+    constructor(options?: StreamOptions);
+    /** @type {Transport|null} */
+    _transport: Transport | null;
+    /** @type {Array<(e: StreamEvent) => void>} */
+    _subscribers: Array<(e: StreamEvent) => void>;
+    /**
+     * @param {StreamEvent} event - Event to broadcast to subscribers and transport.
+     * @returns {void}
+     */
+    emit(event: StreamEvent): void;
+    /**
+     * @param {(e: StreamEvent) => void} callback - Invoked with each emitted event.
+     * @returns {() => void} Unsubscribe function.
+     */
+    subscribe(callback: (e: StreamEvent) => void): () => void;
+}

package/src/stream.js

@@ -14,12 +14,40 @@
  *   Object with write(event) method — e.g. JsonlTransport
  *   null — disabled (subscribers only)
  */
+
+/**
+ * @typedef {object} StreamEvent
+ * @property {string} type - Event type identifier.
+ * @property {string} [taskId] - Associated task identifier.
+ * @property {*} [data] - Arbitrary event payload.
+ * @property {string} [ts] - ISO timestamp; auto-filled on emit if absent.
+ */
+
+/**
+ * @typedef {object} Transport
+ * @property {(event: StreamEvent) => void} write - Sink for emitted events.
+ */
+
+/**
+ * @typedef {object} StreamOptions
+ * @property {Transport|null} [transport] - Optional transport sink for emitted events.
+ */
+
 class Stream {
+  /**
+   * @param {StreamOptions} [options={}]
+   */
   constructor(options = {}) {
+    /** @type {Transport|null} */
     this._transport = options.transport || null;
+    /** @type {Array<(e: StreamEvent) => void>} */
     this._subscribers = [];
   }
 
+  /**
+   * @param {StreamEvent} event - Event to broadcast to subscribers and transport.
+   * @returns {void}
+   */
   emit(event) {
     const full = { ...event, ts: event.ts || new Date().toISOString() };
     for (const fn of this._subscribers) {
@@ -30,6 +58,10 @@ class Stream {
     }
   }
 
+  /**
+   * @param {(e: StreamEvent) => void} callback - Invoked with each emitted event.
+   * @returns {() => void} Unsubscribe function.
+   */
   subscribe(callback) {
     this._subscribers.push(callback);
     return () => {

package/src/tools.d.ts

@@ -0,0 +1,8 @@
+import { createBrowsingTools } from "../tools/browse";
+import { createMobileTools } from "../tools/mobile";
+import { createShellTools } from "../tools/shell";
+import { createSpawnTool } from "../tools/spawn";
+import { spawnChild } from "../tools/spawn";
+import { createDeferTool } from "../tools/defer";
+import { readQueue as readDeferQueue } from "../tools/defer";
+export { createBrowsingTools, createMobileTools, createShellTools, createSpawnTool, spawnChild, createDeferTool, readDeferQueue };