bare-agent 0.11.0 → 0.12.1

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;
+};

package/tools/spawn.js

@@ -31,6 +31,8 @@
  *   per-family.
  */
 
+/** @typedef {import('../src/stream').Stream} Stream */
+
 const { spawn: cpSpawn } = require('node:child_process');
 const path = require('node:path');
 const readline = require('node:readline');
@@ -57,6 +59,17 @@ function resolveCliPath() {
  * }
  *
  * 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]
  */
 function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   if (typeof config !== 'string' || !config) {
@@ -81,8 +94,11 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   }
   child.stdin.end();
 
+  /** @type {ChildEvent[]} */
   const events = [];
+  /** @type {((event: ChildEvent) => void)[]} */
   const lineSubscribers = [];
+  /** @param {(event: ChildEvent) => void} fn */
   const onLine = (fn) => { lineSubscribers.push(fn); return () => {
     const i = lineSubscribers.indexOf(fn);
     if (i >= 0) lineSubscribers.splice(i, 1);
@@ -100,7 +116,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
     }
     events.push(event);
     for (const fn of lineSubscribers) {
-      try { fn(event); } catch (err) {
+      try { fn(event); } catch (/** @type {any} */ err) {
         // never let a subscriber kill the read loop
         process.stderr.write(`[spawn] onLine subscriber threw: ${err.message}\n`);
       }
@@ -165,7 +181,9 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
       };
     }
     // Pluck the final loop:done event — that's the canonical child result.
-    const done = events.findLast?.(e => e.type === 'loop:done')
+    // `findLast` is es2023; the lib target may not declare it, so reach it via
+    // `any` while keeping the runtime fallback for older Node versions.
+    const done = /** @type {any} */ (events).findLast?.((/** @type {ChildEvent} */ e) => e.type === 'loop:done')
       || [...events].reverse().find(e => e.type === 'loop:done');
     if (done) {
       return {
@@ -191,6 +209,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
     };
   }
 
+  /** @param {NodeJS.Signals} [sig] */
   function kill(sig = 'SIGTERM') {
     try { child.kill(sig); } catch { /* already dead */ }
   }
@@ -204,8 +223,8 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
  * @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 {object} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
- * @returns {{tool: object, spawnChild: Function}}
+ * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
+ * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
  */
 function createSpawnTool(options = {}) {
   const tool = {
@@ -225,7 +244,7 @@ function createSpawnTool(options = {}) {
       },
       required: ['config'],
     },
-    execute: async ({ config, input }) => {
+    execute: async (/** @type {{config: string, input?: *}} */ { config, input }) => {
       const handle = spawnChild({
         config,
         input,

package/types/index.d.ts

@@ -0,0 +1,66 @@
+// Shared, cross-cutting type shapes for bare-agent, consumed from JSDoc via
+//   /** @typedef {import('../types').Provider} Provider */  (path is relative to the .js file)
+// These describe the structural contracts that flow between components (provider
+// <-> loop <-> tools). Per-file option bags live as local @typedef blocks in
+// each module; only the genuinely shared shapes belong here.
+
+/** Token accounting returned by a provider's generate(). */
+export interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** A single tool invocation requested by the model. `arguments` is parsed JSON. */
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: any;
+}
+
+/** Normalized result every provider.generate() resolves to. */
+export interface GenerateResult {
+  text: string;
+  toolCalls: ToolCall[];
+  usage: Usage;
+}
+
+/** A conversation message in OpenAI chat format. */
+export interface Message {
+  role: string;
+  content?: string | null;
+  tool_calls?: any[];
+  tool_call_id?: string;
+  [key: string]: any;
+}
+
+/** A callable tool exposed to the loop/provider. */
+export interface ToolDef {
+  name: string;
+  description?: string;
+  parameters?: Record<string, any>;
+  execute(args: any): any | Promise<any>;
+}
+
+/** Minimal LLM provider contract the Loop and Planner depend on. */
+export interface Provider {
+  /** Model id, surfaced for cost estimation. */
+  model?: string | null;
+  /** Provider name, surfaced in onLlmResult. */
+  name?: string | null;
+  generate(
+    messages: Message[],
+    tools?: ToolDef[],
+    options?: Record<string, any>,
+  ): Promise<GenerateResult>;
+}
+
+/** Swappable persistence backend for Memory. */
+export interface Store {
+  store(content: any, metadata?: Record<string, any>): any;
+  search(query: string, options?: Record<string, any>): any;
+  get(id: any): any;
+  delete(id: any): any;
+}
+
+/** Opaque per-run blob forwarded to policy/record callbacks. */
+export type Ctx = any;

package/types/shims.d.ts

@@ -0,0 +1,16 @@
+// Ambient module declarations for dependencies that ship no TypeScript types.
+//
+// `bareguard` is a required dependency but publishes plain JS with no .d.ts; the
+// others are optional/peer deps that may not be installed in every environment
+// (and aren't installed in CI). Declaring them here lets `tsc --checkJs` run
+// without `npm i`-ing native modules, while keeping our own JSDoc fully checked.
+// Each `require()` of these modules resolves to `any`, so our code is responsible
+// for documenting the shapes it relies on via local @typedef/@param JSDoc.
+
+declare module 'bareguard';
+declare module 'better-sqlite3';
+declare module 'barebrowse';
+declare module 'barebrowse/bareagent';
+declare module 'baremobile';
+declare module 'baremobile/ios';
+declare module 'cron-parser';