bare-agent 0.11.0 → 0.12.0

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 {

package/tools/defer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @param {object} [options]
+ * @param {string} [options.queuePath] - Override queue file path.
+ * @returns {{tool: import('../types').ToolDef, readQueue: () => Promise<Record<string, any>[]>, queuePath: string}}
+ */
+export function createDeferTool(options?: {
+    queuePath?: string | undefined;
+}): {
+    tool: import("../types").ToolDef;
+    readQueue: () => Promise<Record<string, any>[]>;
+    queuePath: string;
+};
+/**
+ * Read the queue and reconstruct the live status of each id by folding
+ * append-only status lines (latest wins). Exposed for tests + library
+ * users; the wake script does its own jq-based fold.
+ */
+/** @param {string} [queuePath] */
+export function readQueue(queuePath?: string): Promise<Record<string, any>[]>;
+/**
+ * Generate a sortable, unique id. 9-char base36 timestamp + 20-char hex
+ * random. Lexicographically sortable by emit time; unique enough for any
+ * realistic defer rate. Same shape as the PRD's `def_01J...` sketch.
+ */
+export function generateId(): string;
+/**
+ * Resolve the active queue path. Precedence:
+ *   1. Caller-supplied option (createDeferTool({ queuePath: '...' }))
+ *   2. BAREAGENT_DEFER_QUEUE env var
+ *   3. ./bareagent-defers.jsonl
+ */
+/** @param {string} [option] */
+export function resolveQueuePath(option?: string): string;

package/tools/defer.js

@@ -54,6 +54,7 @@ function generateId() {
  *   2. BAREAGENT_DEFER_QUEUE env var
  *   3. ./bareagent-defers.jsonl
  */
+/** @param {string} [option] */
 function resolveQueuePath(option) {
   return option
     || process.env.BAREAGENT_DEFER_QUEUE
@@ -68,6 +69,7 @@ function resolveQueuePath(option) {
  *
  * Returns { ok: true, iso } on success, { ok: false, error } on failure.
  */
+/** @param {*} when */
 function validateWhen(when) {
   if (typeof when !== 'string' || !when) {
     return { ok: false, error: 'when must be an ISO 8601 timestamp string' };
@@ -88,6 +90,7 @@ function validateWhen(when) {
  * Anything else is the LLM either confused or trying to defer something
  * meaningless.
  */
+/** @param {*} action */
 function validateAction(action) {
   if (!action || typeof action !== 'object' || Array.isArray(action)) {
     return { ok: false, error: 'action must be an object' };
@@ -103,6 +106,10 @@ function validateAction(action) {
  * atomic for writes < PIPE_BUF on POSIX (4KB on Linux); a JSON record
  * with a small action is well under that.
  */
+/**
+ * @param {string} queuePath
+ * @param {Record<string, any>} record
+ */
 async function appendRecord(queuePath, record) {
   const dir = path.dirname(path.resolve(queuePath));
   // Best-effort dir creation; ignore "already exists".
@@ -121,10 +128,12 @@ async function appendRecord(queuePath, record) {
  * append-only status lines (latest wins). Exposed for tests + library
  * users; the wake script does its own jq-based fold.
  */
+/** @param {string} [queuePath] */
 async function readQueue(queuePath) {
   const path = resolveQueuePath(queuePath);
   try {
     const text = await fsp.readFile(path, 'utf8');
+    /** @type {Record<string, Record<string, any>>} */
     const records = {};
     for (const line of text.split('\n')) {
       if (!line.trim()) continue;
@@ -134,7 +143,7 @@ async function readQueue(queuePath) {
       records[r.id] = { ...records[r.id], ...r };
     }
     return Object.values(records);
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     if (err.code === 'ENOENT') return [];
     throw err;
   }
@@ -143,7 +152,7 @@ async function readQueue(queuePath) {
 /**
  * @param {object} [options]
  * @param {string} [options.queuePath] - Override queue file path.
- * @returns {{tool: object, readQueue: Function}}
+ * @returns {{tool: import('../types').ToolDef, readQueue: () => Promise<Record<string, any>[]>, queuePath: string}}
  */
 function createDeferTool(options = {}) {
   const queuePath = resolveQueuePath(options.queuePath);
@@ -166,7 +175,7 @@ function createDeferTool(options = {}) {
       },
       required: ['action', 'when'],
     },
-    execute: async ({ action, when }) => {
+    execute: async (/** @type {{action: *, when: *}} */ { action, when }) => {
       const a = validateAction(action);
       if (!a.ok) throw new Error(`[defer] ${a.error}`);
       const w = validateWhen(when);

package/tools/mobile.d.ts

@@ -0,0 +1,34 @@
+export type ToolDef = import("../types").ToolDef;
+/**
+ * A connected baremobile page/device handle. baremobile ships no types, so the
+ * surface used here is described structurally; all calls resolve to `any`.
+ */
+export type MobilePage = any;
+/** @typedef {import('../types').ToolDef} ToolDef */
+/**
+ * A connected baremobile page/device handle. baremobile ships no types, so the
+ * surface used here is described structurally; all calls resolve to `any`.
+ * @typedef {any} MobilePage
+ */
+/**
+ * Creates mobile control tools via baremobile (optional dep).
+ * Returns { tools, close } or null if baremobile is not installed.
+ *
+ * Tools follow the snapshot() → tap(ref) observe-act pattern.
+ * Action tools auto-return a fresh snapshot so the LLM sees the result.
+ * Supports dual platform: Android (default) and iOS via platform option.
+ *
+ * @param {object} [opts] - Options passed to baremobile connect()
+ * @param {string} [opts.platform] - 'android' (default) or 'ios'
+ * @param {string} [opts.device] - Device serial or 'auto'
+ * @param {boolean} [opts.termux] - Use Termux ADB on-device mode
+ * @returns {Promise<{tools: ToolDef[], close: Function}|null>}
+ */
+export function createMobileTools(opts?: {
+    platform?: string | undefined;
+    device?: string | undefined;
+    termux?: boolean | undefined;
+}): Promise<{
+    tools: ToolDef[];
+    close: Function;
+} | null>;

package/tools/mobile.js

@@ -1,5 +1,13 @@
 'use strict';
 
+/** @typedef {import('../types').ToolDef} ToolDef */
+
+/**
+ * A connected baremobile page/device handle. baremobile ships no types, so the
+ * surface used here is described structurally; all calls resolve to `any`.
+ * @typedef {any} MobilePage
+ */
+
 /**
  * Creates mobile control tools via baremobile (optional dep).
  * Returns { tools, close } or null if baremobile is not installed.
@@ -12,14 +20,16 @@
  * @param {string} [opts.platform] - 'android' (default) or 'ios'
  * @param {string} [opts.device] - Device serial or 'auto'
  * @param {boolean} [opts.termux] - Use Termux ADB on-device mode
- * @returns {Promise<{tools: Array, close: Function}|null>}
+ * @returns {Promise<{tools: ToolDef[], close: Function}|null>}
  */
 async function createMobileTools(opts = {}) {
   const platform = opts.platform || 'android';
 
+  /** @type {(opts: object) => Promise<MobilePage>} */
   let connectFn;
   try {
     if (platform === 'ios') {
+      // baremobile/ios is declared as an ambient `any` module in types/shims.d.ts.
       ({ connect: connectFn } = await import('baremobile/ios'));
     } else {
       ({ connect: connectFn } = await import('baremobile'));
@@ -31,6 +41,7 @@ async function createMobileTools(opts = {}) {
   const SETTLE_MS = 1000;
   const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
 
+  /** @type {MobilePage|null} */
   let _page = null;
 
   async function getPage() {
@@ -38,6 +49,7 @@ async function createMobileTools(opts = {}) {
     return _page;
   }
 
+  /** @param {(page: MobilePage) => any} fn */
   async function actionAndSnapshot(fn) {
     const page = await getPage();
     await fn(page);
@@ -45,6 +57,7 @@ async function createMobileTools(opts = {}) {
     return await page.snapshot();
   }
 
+  /** @type {ToolDef[]} */
   const tools = [
     {
       name: 'mobile_snapshot',
@@ -65,7 +78,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['ref'],
       },
-      execute: async ({ ref }) => actionAndSnapshot((page) => page.tap(ref)),
+      execute: async (/** @type {{ ref: number }} */ { ref }) => actionAndSnapshot((page) => page.tap(ref)),
     },
     {
       name: 'mobile_type',
@@ -79,7 +92,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['ref', 'text'],
       },
-      execute: async ({ ref, text, clear }) => actionAndSnapshot((page) => page.type(ref, text, { clear })),
+      execute: async (/** @type {{ ref: number, text: string, clear?: boolean }} */ { ref, text, clear }) => actionAndSnapshot((page) => page.type(ref, text, { clear })),
     },
     {
       name: 'mobile_press',
@@ -91,7 +104,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['key'],
       },
-      execute: async ({ key }) => actionAndSnapshot((page) => page.press(key)),
+      execute: async (/** @type {{ key: string }} */ { key }) => actionAndSnapshot((page) => page.press(key)),
     },
     {
       name: 'mobile_scroll',
@@ -104,7 +117,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['ref', 'direction'],
       },
-      execute: async ({ ref, direction }) => actionAndSnapshot((page) => page.scroll(ref, direction)),
+      execute: async (/** @type {{ ref: number, direction: string }} */ { ref, direction }) => actionAndSnapshot((page) => page.scroll(ref, direction)),
     },
     {
       name: 'mobile_swipe',
@@ -120,7 +133,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['x1', 'y1', 'x2', 'y2'],
       },
-      execute: async ({ x1, y1, x2, y2, duration }) => actionAndSnapshot((page) => page.swipe(x1, y1, x2, y2, duration)),
+      execute: async (/** @type {{ x1: number, y1: number, x2: number, y2: number, duration?: number }} */ { x1, y1, x2, y2, duration }) => actionAndSnapshot((page) => page.swipe(x1, y1, x2, y2, duration)),
     },
     {
       name: 'mobile_long_press',
@@ -132,7 +145,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['ref'],
       },
-      execute: async ({ ref }) => actionAndSnapshot((page) => page.longPress(ref)),
+      execute: async (/** @type {{ ref: number }} */ { ref }) => actionAndSnapshot((page) => page.longPress(ref)),
     },
     {
       name: 'mobile_launch',
@@ -144,7 +157,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['pkg'],
       },
-      execute: async ({ pkg }) => {
+      execute: async (/** @type {{ pkg: string }} */ { pkg }) => {
         const page = await getPage();
         await page.launch(pkg);
         await new Promise((r) => setTimeout(r, 2000));
@@ -184,7 +197,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['x', 'y'],
       },
-      execute: async ({ x, y }) => actionAndSnapshot((page) => page.tapXY(x, y)),
+      execute: async (/** @type {{ x: number, y: number }} */ { x, y }) => actionAndSnapshot((page) => page.tapXY(x, y)),
     },
   ];
 
@@ -202,7 +215,7 @@ async function createMobileTools(opts = {}) {
           },
           required: ['action'],
         },
-        execute: async ({ action, extras }) => actionAndSnapshot((page) => page.intent(action, extras || {})),
+        execute: async (/** @type {{ action: string, extras?: object }} */ { action, extras }) => actionAndSnapshot((page) => page.intent(action, extras || {})),
       },
       {
         name: 'mobile_tap_grid',
@@ -214,7 +227,7 @@ async function createMobileTools(opts = {}) {
           },
           required: ['cell'],
         },
-        execute: async ({ cell }) => actionAndSnapshot((page) => page.tapGrid(cell)),
+        execute: async (/** @type {{ cell: string }} */ { cell }) => actionAndSnapshot((page) => page.tapGrid(cell)),
       },
       {
         name: 'mobile_grid',
@@ -241,7 +254,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['passcode'],
       },
-      execute: async ({ passcode }) => actionAndSnapshot((page) => page.unlock(passcode)),
+      execute: async (/** @type {{ passcode: string }} */ { passcode }) => actionAndSnapshot((page) => page.unlock(passcode)),
     });
   }
 
@@ -256,7 +269,7 @@ async function createMobileTools(opts = {}) {
       },
       required: ['text'],
     },
-    execute: async ({ text }) => {
+    execute: async (/** @type {{ text: string }} */ { text }) => {
       const page = await getPage();
       const ref = page.findByText(text);
       return ref !== null && ref !== undefined ? ref : null;
@@ -276,7 +289,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['text'],
       },
-      execute: async ({ text, timeout }) => {
+      execute: async (/** @type {{ text: string, timeout?: number }} */ { text, timeout }) => {
         const page = await getPage();
         return await page.waitForText(text, timeout || 10000);
       },
@@ -293,7 +306,7 @@ async function createMobileTools(opts = {}) {
         },
         required: ['ref', 'state'],
       },
-      execute: async ({ ref, state, timeout }) => {
+      execute: async (/** @type {{ ref: number, state: string, timeout?: number }} */ { ref, state, timeout }) => {
         const page = await getPage();
         return await page.waitForState(ref, state, timeout || 10000);
       },

package/tools/shell.d.ts

@@ -0,0 +1,31 @@
+export type GrepArgs = {
+    pattern: string;
+    path: string;
+    recursive?: boolean | undefined;
+    maxMatches?: number | undefined;
+    flags?: string | undefined;
+};
+export type RunArgvArgs = {
+    argv: string[];
+    cwd?: string | undefined;
+    timeout?: number | undefined;
+    maxBuffer?: number | undefined;
+    env?: Record<string, string> | undefined;
+};
+export type ExecCommandArgs = {
+    command: string;
+    cwd?: string | undefined;
+    timeout?: number | undefined;
+    maxBuffer?: number | undefined;
+    env?: Record<string, string> | undefined;
+};
+export type ToolDef = import("../types").ToolDef;
+/**
+ * Create the three shell tools. No options — configuration is per-call via tool args,
+ * gating is the caller's responsibility via `new Loop({ policy })`.
+ *
+ * @returns {{tools: ToolDef[]}}
+ */
+export function createShellTools(): {
+    tools: ToolDef[];
+};

package/tools/shell.js

@@ -12,6 +12,8 @@
  * Library ships zero baked-in allowlist — gating is the agent author's responsibility.
  */
 
+/** @typedef {import('../types').ToolDef} ToolDef */
+
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { exec, execFile } = require('node:child_process');
@@ -21,6 +23,10 @@ const DEFAULT_GREP_MAX_MATCHES = 200;
 const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
 const DEFAULT_EXEC_MAX_BUFFER = 1024 * 1024;     // 1 MB
 
+/**
+ * @param {string} p
+ * @returns {string}
+ */
 function expandHome(p) {
   if (!p) return p;
   if (p.startsWith('~/') || p === '~') {
@@ -30,6 +36,10 @@ function expandHome(p) {
   return p;
 }
 
+/**
+ * @param {string} rawPath
+ * @param {number} [maxBytes]
+ */
 async function readEntry(rawPath, maxBytes) {
   const resolved = path.resolve(expandHome(rawPath));
   const stat = await fs.stat(resolved);
@@ -56,6 +66,7 @@ async function readEntry(rawPath, maxBytes) {
 }
 
 // Probe the first 1KB for NUL bytes to skip binary files in grep walks.
+/** @param {string} filePath */
 async function isProbablyText(filePath) {
   try {
     const fh = await fs.open(filePath, 'r');
@@ -74,6 +85,11 @@ async function isProbablyText(filePath) {
   }
 }
 
+/**
+ * @param {string} dir
+ * @param {boolean} recursive
+ * @returns {AsyncGenerator<string>}
+ */
 async function* walk(dir, recursive) {
   let entries;
   try {
@@ -99,6 +115,7 @@ async function* walk(dir, recursive) {
 // rejection; the agent simply rephrases. (Single-level nesting only — does not
 // detect deeply nested groups or overlapping alternation like (a|a)*.)
 const UNBOUNDED_QUANT = /[*+]|\{\d+,\}/;
+/** @param {string} pattern */
 function looksCatastrophic(pattern) {
   // A quantifier binds to the atom immediately before it — no whitespace between
   // `)` and the quantifier in a real regex.
@@ -113,6 +130,16 @@ function looksCatastrophic(pattern) {
   return false;
 }
 
+/**
+ * @typedef {object} GrepArgs
+ * @property {string} pattern
+ * @property {string} path
+ * @property {boolean} [recursive]
+ * @property {number} [maxMatches]
+ * @property {string} [flags]
+ */
+
+/** @param {GrepArgs} args */
 async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
   const resolved = path.resolve(expandHome(rawPath));
   const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
@@ -125,10 +152,11 @@ async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches,
   let re;
   try {
     re = new RegExp(pattern, flags);
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     throw new Error(`shell_grep: invalid regex — ${err.message}`);
   }
 
+  /** @type {{file: string, line: number, text: string}[]} */
   const hits = [];
   const stat = await fs.stat(resolved).catch(() => null);
   if (!stat) throw new Error(`shell_grep: path not found — ${rawPath}`);
@@ -162,6 +190,16 @@ async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches,
   return { hits, truncated, fileCount: files.length };
 }
 
+/**
+ * @typedef {object} RunArgvArgs
+ * @property {string[]} argv
+ * @property {string} [cwd]
+ * @property {number} [timeout]
+ * @property {number} [maxBuffer]
+ * @property {Record<string, string>} [env]
+ */
+
+/** @param {RunArgvArgs} args */
 function runArgv({ argv, cwd, timeout, maxBuffer, env }) {
   if (!Array.isArray(argv) || argv.length === 0 || typeof argv[0] !== 'string') {
     return Promise.reject(new Error('shell_run: argv must be a non-empty array of strings, starting with the command'));
@@ -203,6 +241,16 @@ function runArgv({ argv, cwd, timeout, maxBuffer, env }) {
   });
 }
 
+/**
+ * @typedef {object} ExecCommandArgs
+ * @property {string} command
+ * @property {string} [cwd]
+ * @property {number} [timeout]
+ * @property {number} [maxBuffer]
+ * @property {Record<string, string>} [env]
+ */
+
+/** @param {ExecCommandArgs} args */
 function execCommand({ command, cwd, timeout, maxBuffer, env }) {
   return new Promise((resolve) => {
     exec(
@@ -238,9 +286,10 @@ function execCommand({ command, cwd, timeout, maxBuffer, env }) {
  * Create the three shell tools. No options — configuration is per-call via tool args,
  * gating is the caller's responsibility via `new Loop({ policy })`.
  *
- * @returns {{tools: Array}}
+ * @returns {{tools: ToolDef[]}}
  */
 function createShellTools() {
+  /** @type {ToolDef[]} */
   const tools = [
     {
       name: 'shell_read',
@@ -253,7 +302,7 @@ function createShellTools() {
         },
         required: ['path'],
       },
-      execute: async ({ path: p, maxBytes }) => readEntry(p, maxBytes),
+      execute: async (/** @type {{path: string, maxBytes?: number}} */ { path: p, maxBytes }) => readEntry(p, maxBytes),
     },
     {
       name: 'shell_grep',
@@ -269,7 +318,7 @@ function createShellTools() {
         },
         required: ['pattern', 'path'],
       },
-      execute: async (args) => grepPath(args),
+      execute: async (/** @type {GrepArgs} */ args) => grepPath(args),
     },
     {
       name: 'shell_run',
@@ -289,7 +338,7 @@ function createShellTools() {
         },
         required: ['argv'],
       },
-      execute: async (args) => runArgv(args),
+      execute: async (/** @type {RunArgvArgs} */ args) => runArgv(args),
     },
     {
       name: 'shell_exec',
@@ -305,7 +354,7 @@ function createShellTools() {
         },
         required: ['command'],
       },
-      execute: async (args) => execCommand(args),
+      execute: async (/** @type {ExecCommandArgs} */ args) => execCommand(args),
     },
   ];
   return { tools };