bare-agent 0.3.6 → 0.4.1

package/README.md

@@ -1,13 +1,13 @@
 ```
-                                                    ╭─────────────────────────────────╮
-                                                    │  ╔╗ ╔═╗╦═╗╔═╗ ╔═╗╔═╗╔═╗╔╗╔╔╦╗   │
-                                                    │  ╠╩╗╠═╣╠╦╝╠╣  ╠═╣║ ╦╠╣ ║║║ ║    │
-                                                    │  ╚═╝╩ ╩╩╚═╚═╝ ╩ ╩╚═╝╚═╝╝╚╝ ╩    │
-                                                    │   think ──→ act ──→ observe     │
-                                                    │     ↑                  │        │
-                                                    │     └──────────────────┘        │
-                                                    ╰──╮──────────────────────────────╯
-                                                       ╰── the brain, without the bloat
+                         ╭─────────────────────────────────╮
+                         │  ╔╗ ╔═╗╦═╗╔═╗ ╔═╗╔═╗╔═╗╔╗╔╔╦╗   │
+                         │  ╠╩╗╠═╣╠╦╝╠╣  ╠═╣║ ╦╠╣ ║║║ ║    │
+                         │  ╚═╝╩ ╩╩╚═╚═╝ ╩ ╩╚═╝╚═╝╝╚╝ ╩    │
+                         │   think ──→ act ──→ observe     │
+                         │     ↑                  │        │
+                         │     └──────────────────┘        │
+                         ╰──╮──────────────────────────────╯
+                            ╰── the brain, without the bloat
 
 ```
 
@@ -73,14 +73,15 @@ Every piece works alone — take what you need, ignore the rest.
 | **Stream** | Structured event emitter. Pipe as JSONL, subscribe in-process, or custom transport |
 | **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `MaxRoundsError`, `CircuitOpenError` |
 | **Browsing** | Web navigation, clicking, typing, reading via `barebrowse`. Two modes: library tools (inline snapshots, pass to Loop) or CLI session (disk-based snapshots, token-efficient for multi-step flows) |
+| **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely.
 
-**Tools:** Any function is a tool. REST APIs, MCP servers, CLI commands, shell scripts — if it's a function, it works. Built-in: `barebrowse` for web browsing (optional) — library tools for inline results or CLI session mode for token-efficient disk-based snapshots.
+**Tools:** Any function is a tool. REST APIs, MCP servers, CLI commands, shell scripts — if it's a function, it works. Built-in: `barebrowse` for web browsing, `baremobile` for Android + iOS device control (both optional) — library tools for inline results or CLI session mode for token-efficient disk-based snapshots.
 
 **Cross-language:** Runs as a subprocess. Communicate via JSONL on stdin/stdout from Python, Go, Rust, Ruby, Java, or anything that can spawn a process. Ready-made wrappers in [`contrib/`](contrib/README.md).
 
-**Deps:** 0 required. Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing).
+**Deps:** 0 required. Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control).
 
 ---
 
@@ -135,6 +136,28 @@ Aurora replaced ~400 lines of hand-rolled orchestration with ~60 lines of bare-a
 
 For wiring recipes and API details, see the **[Integration Guide](bareagent.context.md)** (LLM-optimized). For the full human guide — usage patterns, composition examples, and what bare-agent deliberately doesn't build in (with recipes to do it yourself), see the **[Usage Guide](docs/02-features/usage-guide.md)**. For error reference, see **[Error Guide](docs/02-features/errors.md)**. For release history, see **[CHANGELOG](CHANGELOG.md)**.
 
+## The bare ecosystem
+
+Three vanilla JS modules. Zero dependencies. Same API patterns.
+
+| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) |
+|---|---|---|---|
+| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents Android + iOS devices |
+| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out |
+| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, XCUITest |
+| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP |
+| **Solo or together** | Orchestrates both as tools | Works standalone | Works standalone |
+
+**What you can build:**
+
+- **Headless automation** — scrape sites, fill forms, extract data, monitor pages on a schedule
+- **QA & testing** — automated test suites for web and Android apps without heavyweight frameworks
+- **Personal AI assistants** — chatbots that browse the web or control your phone on your behalf
+- **Remote device control** — manage Android devices over WiFi, including on-device via Termux
+- **Agentic workflows** — multi-step tasks where an AI plans, browses, and acts across web and mobile
+
+**Why this exists:** Most automation stacks ship 200MB of opinions before you write a line of code. These don't. Install, import, go.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.3.6",
+  "version": "0.4.1",
   "files": [
     "index.js",
     "src/",
@@ -39,6 +39,7 @@
   ],
   "optionalDependencies": {
     "barebrowse": "^0.2.0",
+    "baremobile": "^0.7.0",
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {

package/src/tools.js

@@ -1,5 +1,6 @@
 'use strict';
 
 const { createBrowsingTools } = require('../tools/browse');
+const { createMobileTools } = require('../tools/mobile');
 
-module.exports = { createBrowsingTools };
+module.exports = { createBrowsingTools, createMobileTools };

package/tools/mobile.js

@@ -0,0 +1,314 @@
+'use strict';
+
+/**
+ * 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: Array, close: Function}|null>}
+ */
+async function createMobileTools(opts = {}) {
+  const platform = opts.platform || 'android';
+
+  let connectFn;
+  try {
+    if (platform === 'ios') {
+      ({ connect: connectFn } = await import('baremobile/ios'));
+    } else {
+      ({ connect: connectFn } = await import('baremobile'));
+    }
+  } catch {
+    return null;
+  }
+
+  const SETTLE_MS = 1000;
+  const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
+
+  let _page = null;
+
+  async function getPage() {
+    if (!_page) _page = await connectFn(opts);
+    return _page;
+  }
+
+  async function actionAndSnapshot(fn) {
+    const page = await getPage();
+    await fn(page);
+    await settle();
+    return await page.snapshot();
+  }
+
+  const tools = [
+    {
+      name: 'mobile_snapshot',
+      description: 'Get the current mobile screen as a pruned accessibility snapshot. Returns a YAML-like tree with [ref=N] markers on interactive elements. Always call after actions to observe the result.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        return await page.snapshot();
+      },
+    },
+    {
+      name: 'mobile_tap',
+      description: 'Tap a mobile screen element by its ref from the snapshot. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'number', description: 'Element ref number from snapshot' },
+        },
+        required: ['ref'],
+      },
+      execute: async ({ ref }) => actionAndSnapshot((page) => page.tap(ref)),
+    },
+    {
+      name: 'mobile_type',
+      description: 'Type text into a mobile element. Taps to focus first if not focused. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'number', description: 'Element ref from snapshot' },
+          text: { type: 'string', description: 'Text to type' },
+          clear: { type: 'boolean', description: 'Clear existing content first (default: false)' },
+        },
+        required: ['ref', 'text'],
+      },
+      execute: async ({ ref, text, clear }) => actionAndSnapshot((page) => page.type(ref, text, { clear })),
+    },
+    {
+      name: 'mobile_press',
+      description: 'Press a key on the mobile device. Keys: back, home, enter, delete, tab, escape, up, down, left, right, space, power, volup, voldown, recent. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'Key name (e.g. "back", "home", "enter")' },
+        },
+        required: ['key'],
+      },
+      execute: async ({ key }) => actionAndSnapshot((page) => page.press(key)),
+    },
+    {
+      name: 'mobile_scroll',
+      description: 'Scroll a mobile element in a direction. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'number', description: 'Element ref to scroll' },
+          direction: { type: 'string', enum: ['up', 'down', 'left', 'right'], description: 'Scroll direction' },
+        },
+        required: ['ref', 'direction'],
+      },
+      execute: async ({ ref, direction }) => actionAndSnapshot((page) => page.scroll(ref, direction)),
+    },
+    {
+      name: 'mobile_swipe',
+      description: 'Swipe between two screen coordinates on the mobile device. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          x1: { type: 'number', description: 'Start X' },
+          y1: { type: 'number', description: 'Start Y' },
+          x2: { type: 'number', description: 'End X' },
+          y2: { type: 'number', description: 'End Y' },
+          duration: { type: 'number', description: 'Duration in ms (default: 300)' },
+        },
+        required: ['x1', 'y1', 'x2', 'y2'],
+      },
+      execute: async ({ x1, y1, x2, y2, duration }) => actionAndSnapshot((page) => page.swipe(x1, y1, x2, y2, duration)),
+    },
+    {
+      name: 'mobile_long_press',
+      description: 'Long-press a mobile element by its ref. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'number', description: 'Element ref from snapshot' },
+        },
+        required: ['ref'],
+      },
+      execute: async ({ ref }) => actionAndSnapshot((page) => page.longPress(ref)),
+    },
+    {
+      name: 'mobile_launch',
+      description: 'Launch a mobile app by package name (Android) or bundle ID (iOS). Returns updated snapshot after 2s settle.',
+      parameters: {
+        type: 'object',
+        properties: {
+          pkg: { type: 'string', description: 'App identifier (e.g. "com.android.settings" or "com.apple.Preferences")' },
+        },
+        required: ['pkg'],
+      },
+      execute: async ({ pkg }) => {
+        const page = await getPage();
+        await page.launch(pkg);
+        await new Promise((r) => setTimeout(r, 2000));
+        return await page.snapshot();
+      },
+    },
+    {
+      name: 'mobile_back',
+      description: 'Navigate back on the mobile device. Returns updated snapshot.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => actionAndSnapshot((page) => page.back()),
+    },
+    {
+      name: 'mobile_home',
+      description: 'Press the home button on the mobile device. Returns updated snapshot.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => actionAndSnapshot((page) => page.home()),
+    },
+    {
+      name: 'mobile_screenshot',
+      description: 'Take a screenshot of the mobile screen. Returns base64-encoded PNG.',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const page = await getPage();
+        const buf = await page.screenshot();
+        return buf.toString('base64');
+      },
+    },
+    {
+      name: 'mobile_tap_xy',
+      description: 'Tap by pixel coordinates on the mobile screen. Use when elements lack refs. Returns updated snapshot.',
+      parameters: {
+        type: 'object',
+        properties: {
+          x: { type: 'number', description: 'X coordinate' },
+          y: { type: 'number', description: 'Y coordinate' },
+        },
+        required: ['x', 'y'],
+      },
+      execute: async ({ x, y }) => actionAndSnapshot((page) => page.tapXY(x, y)),
+    },
+  ];
+
+  // Android-only tools
+  if (platform !== 'ios') {
+    tools.push(
+      {
+        name: 'mobile_intent',
+        description: 'Launch an Android intent action for deep navigation. Skips multi-step UI navigation. Returns updated snapshot.',
+        parameters: {
+          type: 'object',
+          properties: {
+            action: { type: 'string', description: 'Intent action (e.g. "android.settings.BLUETOOTH_SETTINGS")' },
+            extras: { type: 'object', description: 'Intent extras as key-value pairs' },
+          },
+          required: ['action'],
+        },
+        execute: async ({ action, extras }) => actionAndSnapshot((page) => page.intent(action, extras || {})),
+      },
+      {
+        name: 'mobile_tap_grid',
+        description: 'Tap by grid cell (e.g. "C5") for vision-based fallback. Use with mobile_grid to get cell layout. Returns updated snapshot.',
+        parameters: {
+          type: 'object',
+          properties: {
+            cell: { type: 'string', description: 'Grid cell (e.g. "C5", "A1")' },
+          },
+          required: ['cell'],
+        },
+        execute: async ({ cell }) => actionAndSnapshot((page) => page.tapGrid(cell)),
+      },
+      {
+        name: 'mobile_grid',
+        description: 'Get grid layout info for the mobile screen. Use with mobile_screenshot for vision-based interaction when the accessibility tree is unreliable.',
+        parameters: { type: 'object', properties: {} },
+        execute: async () => {
+          const page = await getPage();
+          const grid = await page.grid();
+          return grid.text;
+        },
+      },
+    );
+  }
+
+  // iOS-only tools
+  if (platform === 'ios') {
+    tools.push({
+      name: 'mobile_unlock',
+      description: 'Unlock the iOS device with a passcode.',
+      parameters: {
+        type: 'object',
+        properties: {
+          passcode: { type: 'string', description: 'Device passcode' },
+        },
+        required: ['passcode'],
+      },
+      execute: async ({ passcode }) => actionAndSnapshot((page) => page.unlock(passcode)),
+    });
+  }
+
+  // Find tools (both platforms, no device call — reads refMap from last snapshot)
+  tools.push({
+    name: 'mobile_find_text',
+    description: 'Find an interactive element by visible text or accessibility label. Searches the refMap from the last snapshot — no device call. Returns the ref number or null if not found.',
+    parameters: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Text or label substring to search for' },
+      },
+      required: ['text'],
+    },
+    execute: async ({ text }) => {
+      const page = await getPage();
+      const ref = page.findByText(text);
+      return ref !== null && ref !== undefined ? ref : null;
+    },
+  });
+
+  // Wait tools (both platforms)
+  tools.push(
+    {
+      name: 'mobile_wait_text',
+      description: 'Wait until specific text appears on the mobile screen. Polls snapshot every 500ms. Returns snapshot when found or throws on timeout.',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'Text to wait for' },
+          timeout: { type: 'number', description: 'Timeout in ms (default: 10000)' },
+        },
+        required: ['text'],
+      },
+      execute: async ({ text, timeout }) => {
+        const page = await getPage();
+        return await page.waitForText(text, timeout || 10000);
+      },
+    },
+    {
+      name: 'mobile_wait_state',
+      description: 'Wait until an element reaches a specific state. States: enabled, disabled, checked, unchecked, focused, selected. Returns snapshot when matched.',
+      parameters: {
+        type: 'object',
+        properties: {
+          ref: { type: 'number', description: 'Element ref from snapshot' },
+          state: { type: 'string', enum: ['enabled', 'disabled', 'checked', 'unchecked', 'focused', 'selected'], description: 'Target state' },
+          timeout: { type: 'number', description: 'Timeout in ms (default: 10000)' },
+        },
+        required: ['ref', 'state'],
+      },
+      execute: async ({ ref, state, timeout }) => {
+        const page = await getPage();
+        return await page.waitForState(ref, state, timeout || 10000);
+      },
+    },
+  );
+
+  return {
+    tools,
+    async close() {
+      if (_page) {
+        _page.close();
+        _page = null;
+      }
+    },
+  };
+}
+
+module.exports = { createMobileTools };