bare-agent 0.10.4 → 0.12.0

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';