bare-agent 0.10.4 → 0.12.0

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

@@ -2,60 +2,102 @@
 
 const { readFileSync, writeFileSync, existsSync } = require('node:fs');
 
+// Past this many entries, the O(n) scan + whole-file rewrite per write becomes a
+// real latency/availability concern. Warn once (per instance) and point at SQLiteStore.
+const LARGE_STORE_THRESHOLD = 10000;
+
 /**
  * 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
  */
+
 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;
   }
 
   _save() {
     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() });
     this._save();
+    if (!this._warnedLarge && this._data.length > LARGE_STORE_THRESHOLD) {
+      this._warnedLarge = true;
+      console.warn(
+        `[JsonFileStore] ${this._data.length} entries — search is O(n) and every write rewrites ` +
+        `the whole file. Switch to SQLiteStore for memory this size.`,
+      );
+    }
     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 };

package/src/transport-jsonl.d.ts

@@ -0,0 +1,30 @@
+export type JsonlTransportOptions = {
+    /**
+     * - Writable stream to write JSONL lines to. Defaults to process.stdout.
+     */
+    output?: NodeJS.WritableStream | undefined;
+};
+/**
+ * JSONL transport: one JSON object per line to a writable stream.
+ * Default: process.stdout. Pipe-friendly, parseable by any language.
+ *
+ * Debug output goes to stderr (never pollutes stdout).
+ */
+/**
+ * @typedef {object} JsonlTransportOptions
+ * @property {NodeJS.WritableStream} [output] - Writable stream to write JSONL lines to. Defaults to process.stdout.
+ */
+export class JsonlTransport {
+    /**
+     * @param {JsonlTransportOptions} [options={}]
+     */
+    constructor(options?: JsonlTransportOptions);
+    _output: NodeJS.WritableStream | (NodeJS.WriteStream & {
+        fd: 1;
+    });
+    /**
+     * @param {*} event - Event object to serialize as one JSON line.
+     * @returns {void}
+     */
+    write(event: any): void;
+}

package/src/transport-jsonl.js

@@ -6,11 +6,24 @@
  *
  * Debug output goes to stderr (never pollutes stdout).
  */
+
+/**
+ * @typedef {object} JsonlTransportOptions
+ * @property {NodeJS.WritableStream} [output] - Writable stream to write JSONL lines to. Defaults to process.stdout.
+ */
+
 class JsonlTransport {
+  /**
+   * @param {JsonlTransportOptions} [options={}]
+   */
   constructor(options = {}) {
     this._output = options.output || process.stdout;
   }
 
+  /**
+   * @param {*} event - Event object to serialize as one JSON line.
+   * @returns {void}
+   */
   write(event) {
     this._output.write(JSON.stringify(event) + '\n');
   }

package/src/transports.d.ts

@@ -0,0 +1,2 @@
+export { JsonlTransport };
+import { JsonlTransport } from "./transport-jsonl";

package/tools/browse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates browsing tools via barebrowse (optional dep).
+ * Returns { tools, close } or null if barebrowse is not installed.
+ * @param {object} [opts] - Options passed to barebrowse createBrowseTools
+ * @returns {Promise<{tools: Array, close: Function}|null>}
+ */
+export function createBrowsingTools(opts?: object): Promise<{
+    tools: any[];
+    close: Function;
+} | null>;

package/tools/browse.js

@@ -8,6 +8,8 @@
  */
 async function createBrowsingTools(opts = {}) {
   try {
+    // barebrowse is an optional dep; the subpath is declared as an ambient `any`
+    // module in types/shims.d.ts and resolves to `any` at runtime.
     const { createBrowseTools } = await import('barebrowse/bareagent');
     return createBrowseTools(opts);
   } catch {