bare-agent 0.10.4 → 0.12.0

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 {
@@ -91,16 +107,56 @@ async function* walk(dir, recursive) {
   }
 }
 
+// Conservative ReDoS guard. Rejects the classic catastrophic-backtracking shape:
+// a quantifier (* + {n,}) applied to a group whose body itself contains an
+// unbounded quantifier — e.g. (a+)+, (a*)*, (.+)* . JS RegExp has no execution
+// timeout, and grep runs the pattern against attacker-influenceable file content
+// on the main thread, so one such pattern blocks the whole event loop. Errs toward
+// 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.
+  const groupQuant = /\(([^()]*)\)(?:[*+]|\{\d+,\})/g;
+  let m;
+  while ((m = groupQuant.exec(pattern)) !== null) {
+    // Drop escaped literals (\+ \* \{ …) so a group like (\+)+ — one-or-more
+    // literal plus signs, which is linear — isn't mistaken for a nested quantifier.
+    const body = m[1].replace(/\\./g, '');
+    if (UNBOUNDED_QUANT.test(body)) return true;
+  }
+  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;
+  if (looksCatastrophic(pattern)) {
+    throw new Error(
+      `shell_grep: pattern rejected — nested unbounded quantifier (e.g. "(a+)+") risks catastrophic ` +
+      `backtracking that would block the process. Simplify the regex.`,
+    );
+  }
   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}`);
@@ -134,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'));
@@ -175,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(
@@ -210,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',
@@ -225,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',
@@ -241,7 +318,7 @@ function createShellTools() {
         },
         required: ['pattern', 'path'],
       },
-      execute: async (args) => grepPath(args),
+      execute: async (/** @type {GrepArgs} */ args) => grepPath(args),
     },
     {
       name: 'shell_run',
@@ -261,7 +338,7 @@ function createShellTools() {
         },
         required: ['argv'],
       },
-      execute: async (args) => runArgv(args),
+      execute: async (/** @type {RunArgvArgs} */ args) => runArgv(args),
     },
     {
       name: 'shell_exec',
@@ -277,7 +354,7 @@ function createShellTools() {
         },
         required: ['command'],
       },
-      execute: async (args) => execCommand(args),
+      execute: async (/** @type {ExecCommandArgs} */ args) => execCommand(args),
     },
   ];
   return { tools };

package/tools/spawn.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Library-level: spawn a child and return a handle.
+ *
+ * Returns: {
+ *   wait()      — Promise<{ text, usage, cost, error, events }>
+ *   onLine(fn)  — subscribe to every JSONL event from child stdout
+ *   kill(sig?)  — terminate the child
+ *   pid         — child process id
+ * }
+ *
+ * Use this from library code; the LLM-callable tool below wraps it with blocking semantics.
+ */
+export type ChildEvent = Record<string, any> & {
+    type?: string;
+    text?: string;
+    ts?: string;
+    data?: any;
+};
+/**
+ * Library-level: spawn a child and return a handle.
+ *
+ * Returns: {
+ *   wait()      — Promise<{ text, usage, cost, error, events }>
+ *   onLine(fn)  — subscribe to every JSONL event from child stdout
+ *   kill(sig?)  — terminate the child
+ *   pid         — child process id
+ * }
+ *
+ * Use this from library code; the LLM-callable tool below wraps it with blocking semantics.
+ */
+export type SpawnChildOptions = {
+    /**
+     * - Path to a bareagent config JSON file.
+     */
+    config?: string | undefined;
+    /**
+     * - Optional JSON input passed to the child on stdin.
+     */
+    input?: any;
+    /**
+     * - Override the bareagent CLI path.
+     */
+    cliPath?: string | undefined;
+    /**
+     * - Force-kill child after this many ms.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * - bareagent Stream — child:stderr events get re-emitted here.
+     */
+    stream?: import("../src/stream").Stream | undefined;
+};
+export type Stream = import("../src/stream").Stream;
+/**
+ * LLM-callable spawn tool. Blocks; returns the child's final result.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
+ * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
+ */
+export function createSpawnTool(options?: {
+    cliPath?: string | undefined;
+    timeoutMs?: number | undefined;
+    stream?: import("../src/stream").Stream | undefined;
+}): {
+    tool: import("../types").ToolDef;
+    spawnChild: typeof spawnChild;
+};
+/**
+ * Library-level: spawn a child and return a handle.
+ *
+ * Returns: {
+ *   wait()      — Promise<{ text, usage, cost, error, events }>
+ *   onLine(fn)  — subscribe to every JSONL event from child stdout
+ *   kill(sig?)  — terminate the child
+ *   pid         — child process id
+ * }
+ *
+ * Use this from library code; the LLM-callable tool below wraps it with blocking semantics.
+ *
+ * @typedef {Record<string, any> & {type?: string, text?: string, ts?: string, data?: any}} ChildEvent
+ *
+ * @typedef {object} SpawnChildOptions
+ * @property {string} [config] - Path to a bareagent config JSON file.
+ * @property {*} [input] - Optional JSON input passed to the child on stdin.
+ * @property {string} [cliPath] - Override the bareagent CLI path.
+ * @property {number} [timeoutMs] - Force-kill child after this many ms.
+ * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
+ *
+ * @param {SpawnChildOptions} [opts]
+ */
+export function spawnChild({ config, input, cliPath, timeoutMs, stream }?: SpawnChildOptions): {
+    wait: () => Promise<{
+        text: any;
+        usage: any;
+        cost: any;
+        error: any;
+        events: ChildEvent[];
+        exitCode: any;
+        signal: any;
+    }>;
+    onLine: (fn: (event: ChildEvent) => void) => () => void;
+    kill: (sig?: NodeJS.Signals) => void;
+    pid: number | undefined;
+};