@avasapp/agent-bridge 0.6.0 → 0.6.1

package/README.md

@@ -4,7 +4,7 @@ Let coding agents drive any running Expo or React Native app directly. Seed data
 
 ![The same checks with agent-device alone (22.4 s) and with agent-bridge (1.4 s): hide a tab, turn on dark mode, fill in a form, seed data, fake a live message and undo it all](example/media/demo.gif)
 
-The same 19 checks on [the example app](example), at real speed: 22.4 s with agent-device alone, 1.4 s with agent-bridge. Most calls take a few milliseconds ([benchmarks](docs/benchmarks.md)).
+The same 19 checks on [the example app](example), at real speed: 22.4 s with agent-device alone, 1.4 s with agent-bridge. With [Argent](https://github.com/software-mansion/argent) instead of agent-device it is [17.1 s against 1.4 s](example/media/demo-argent.gif) while screen recording (Argent alone takes 11.6 s without the recorder). Most calls take a few milliseconds ([benchmarks](docs/benchmarks.md)).
 
 Works on Expo (dev-tools socket) and on bare React Native (CDP over Metro). Nothing ships to users: every entry point compiles to an empty stub in release builds, and `agent-bridge assert-absent` checks a bundle in CI ([security](docs/security.md)).
 

package/dist/cli.js

@@ -1685,7 +1685,7 @@ import { dirname as dirname6, relative as relative6, resolve as resolve2, sep as
 import { createInterface as createInterface4 } from "readline/promises";
 
 // package.json
-var version = "0.6.0";
+var version = "0.6.1";
 
 // src/init/detect.ts
 import { dirname as dirname4, join as join6, relative as relative3 } from "path";
@@ -2903,9 +2903,39 @@ async function runInit(args, io) {
 
 // src/mcp/server.ts
 import { createInterface as createInterface5 } from "readline";
+
+// src/runtime/tools/descriptions.ts
+var INTERNAL_TOOLS = ["bridge.adopt"];
+var UNLISTED_WITHOUT_APP = [...INTERNAL_TOOLS, "bridge.ping"];
+var TARGET_HELP = "target is a string (testID, label, placeholder or text) or an object that must match every key it sets: {testID, label, placeholder, text, at:[x,y], index}. Unknown keys are errors. {at:[x,y]} hits the smallest element covering that point, for icon-only buttons with no label. Several matches: add an index, either in the target or as a trailing {index:n} argument.";
+var TOOL_DESCRIPTIONS = {
+  "app.reload": `Reload the app's JS (Expo's reloadAppAsync, else DevSettings.reload). Pending restores (store, query, mocks, pins, storage) are lost, and the reply names them: restore first. Returns before it reloads; a session waits for the new bridge and reports what was lost.`,
+  "app.restore": `Undo what the app's own tools changed: runs the undos they registered with onRestore, newest first, once. Returns how many ran.`,
+  "bridge.adopt": `Internal: a session hands back its journal after a reload.`,
+  "bridge.logs": `Errors and warnings the app logged, newest last. Options: {level: "error"|"warn"|"all", limit, clear}.`,
+  "bridge.pending": `What bridge.restore would undo right now, per area (store, query, net, app, ...): the value is true, or detail such as a store's snapshot against its current value. Empty when nothing is pending. Changes nothing.`,
+  "bridge.ping": `Round-trip check. Returns the app clock.`,
+  "bridge.restore": `Undo what the agent changed: runs every *.restore tool in name order, scenario.restore last, and returns each result or error.`,
+  "bridge.tools": `Every tool this app exposes.`,
+  "scenario.apply": `Apply a scenario: [name, options?]. Options must fit its schema (scenario.list). Returns what it returns. Applying an active one undoes it first. bridge.restore undoes it.`,
+  "scenario.list": `Setups the app defines, e.g. a signed-in user: name, description, options (a JSON Schema), active.`,
+  "scenario.restore": `Undo every active scenario, newest first. bridge.restore runs this after every other restorer.`,
+  "screen.capture": `Screenshot the app as a PNG. Returns {path} of a file on the device. \`{base64:true}\` returns {base64} instead when small enough (else {path}). Only works if the app already has react-native-view-shot; otherwise errors and you use agent-device, simctl or adb.`,
+  "screen.fill": `Type into an input, then wait for the render. ${TARGET_HELP} {submit:true} also submits. "" clears it. {type:true} types one character at a time, waiting for a render after each (for debounced or per-character inputs; "\\n" is the Enter key). An input with no value prop gets its native text set; if that cannot be done the reply has a warning.`,
+  "screen.findText": `Find text on screen (substring, or exact with {exact:true}) and whether each match is on screen. Searches the same joined text screen.snapshot shows (nested Text concatenated) and accessibility labels; {labels:false} searches text only. Each match says which field matched; a miss lists near misses. Ignores screens the user can't reach (unfocused tabs and stack screens, under a modal); \`hidden\` counts matches there.`,
+  "screen.press": `Press a button, then wait for the render. ${TARGET_HELP} Text with no handler of its own presses the nearest ancestor that has one, and the reply says via:"ancestor". Disabled elements are refused; {force:true} presses anyway, to see what the app does on tap. {scroll:true} scrolls an off-screen target into view first. With no onPress it sends the "activate" accessibility action, as a screen reader's double tap does (swipe-to-confirm buttons, sliders), and the reply says via:"accessibilityAction:activate". {action:"increment"} (or any name in the element's snapshot \`actions\`) sends that action instead. A Switch (native switch host or role switch, with onValueChange) is toggled with onValueChange(!value), not the row around it; reply via:"onValueChange". {long:true} long presses: onPressIn, onLongPress, onPressOut (never onPress); an error when there is no onLongPress, on the element or an ancestor. {scroll:true} also pages the largest vertical FlatList/SectionList/FlashList for a row it has not rendered yet (and scrolls back if it finds none; onEndReached may fire). A tap inside a react-native-gesture-handler GestureDetector cannot be pressed from here (its callbacks run on the UI thread): the error says so.`,
+  "screen.refresh": `Pull to refresh: call the onRefresh of the RefreshControl of the scrollable holding a target (or the largest one with a RefreshControl on screen), then wait for the render. It does not wait for the data: follow with screen.waitFor.`,
+  "screen.scroll": `Scroll the nearest ScrollView/FlatList/FlashList, then wait for the render. Takes a target (or {to: target}) to bring into the middle of its scrollable, {toEnd:true}, {toStart:true}, or {by: points} (negative scrolls back); the last argument may be {within: target, index} to name the scrollable (a target inside it, or its testID). Without a target it scrolls the largest scrollable on screen. Only rendered elements can be targeted: rows a FlatList has not rendered yet need {toEnd:true} or {by} first. Returns the offset and, for a target, whether it is now on screen. ${TARGET_HELP}`,
+  "screen.setValue": `Set a Switch, Slider, Picker or SegmentedControl: calls its onValueChange (and a Slider's onSlidingComplete) with the value, waits for the render and reads the value back. A Switch takes true or false, a Slider a number within minimumValue and maximumValue (0 and 1 by default) and on its step (onSlidingStart, onValueChange, onSlidingComplete), a Picker one of its Picker.Item values, a SegmentedControl one of its values (a wrong type or value is an error that lists the options). The reply has \`value\` as the app now shows it, and a warning when that is not what was set (a controlled value the app refused). Disabled controls are refused; {force:true} sets anyway. {scroll:true} scrolls or pages the target into view first (pages the largest vertical list; onEndReached may fire). ${TARGET_HELP}`,
+  "screen.snapshot": `Buttons, inputs, text, and testID or labelled views on screen, with rects and checked/selected/expanded state (a Switch's value is checked). \`actions\` lists the accessibility actions an element handles; one with "activate" and no onPress (a swipe-to-confirm) is a button screen.press can press. Only the focused screen: unfocused tabs and stack screens, content under an open modal, display:none and accessibility-hidden subtrees are left out, and \`hidden\` counts the elements skipped. {all:true} lists everything, marking off-screen (onScreen:false) and hidden (hidden:true) ones. A WebView registered with the react-native-webview adapter shows as one \`webview\` element with its name: use webview.* inside it. Options: {format:"json"|"text"} (the runtime default is JSON with rects; the CLI and the MCP server return the text form unless you pass {format:"json"}). Text is one line per element: kind (or role: switch, checkbox, tab), #testID, text, label, value, state, then \`readonly\`, \`actions=\u2026\`, \`offscreen\`, \`hidden\`. Lines that repeat get \`index=N\` (the {index} of the target that names them); a line with no testID, text, label or placeholder gets \`@x,y\`, the point for {at:[x,y]}. JSON has rects, onScreen:false and hidden:true. {kinds:["button","input"]} keeps only those kinds (kinds are button, input, text, view, webview; a switch or tab is a button); {within: target} keeps only elements under that target in the tree (a target as for screen.press; with several matches pass {testID, index} inside it).`,
+  "screen.waitFor": `Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. {scroll:true} also accepts a match rendered off screen and scrolls it into view, (it does not page lists for rows they have not rendered: wait for the list, then press/fill/setValue with {scroll:true}; not with gone). Default timeout 5000 ms; a timeout lists near misses.`
+};
+
+// src/mcp/server.ts
 var SUPPORTED = ["2025-06-18", "2024-11-05"];
 var STATUS_TOOL = "agent_bridge_status";
 var MAX_NAME = 64;
+var BUILTIN_LIST = Object.entries(TOOL_DESCRIPTIONS).filter(([name]) => !UNLISTED_WITHOUT_APP.includes(name)).map(([name, description]) => ({ name, description }));
 function mcpNames(tools, reserved = []) {
   const out = /* @__PURE__ */ new Map();
   const taken = new Set(reserved);
@@ -3001,25 +3031,34 @@ function startMcpServer(options) {
     options.log?.(`agent-bridge mcp: not connected: ${now}`);
   };
   const announce = () => {
-    if (!initialized || listed === null || signature === listed || signature === announced)
+    if (!initialized || listed === null) return;
+    if (signature === listed) {
+      announced = "";
       return;
+    }
+    if (signature === announced) return;
     announced = signature;
     send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
   };
+  const setTools = (list2, sig) => {
+    signature = sig;
+    names2 = mcpNames(list2, [STATUS_TOOL]);
+    tools = [...names2].map(([mcp, name]) => ({
+      name,
+      mcp,
+      description: list2.find((t) => t.name === name)?.description
+    }));
+    announce();
+  };
+  setTools(BUILTIN_LIST, "builtin");
+  const BUILTIN_MCP = mcpNames(BUILTIN_LIST, [STATUS_TOOL]);
   const adopt = (next) => {
     const list2 = next.tools();
     const sig = JSON.stringify([next.device.deviceId, list2]);
     bridge = next;
     lastError = void 0;
     if (sig !== signature) {
-      signature = sig;
-      names2 = mcpNames(list2, [STATUS_TOOL]);
-      tools = [...names2].map(([mcp, name]) => ({
-        name,
-        mcp,
-        description: list2.find((t) => t.name === name)?.description
-      }));
-      announce();
+      setTools(list2, sig);
     }
   };
   const ensure = () => {
@@ -3121,7 +3160,15 @@ Start the app and call again; the server reconnects on the next call. The ${STAT
         );
       }
       const tool = typeof params.name === "string" ? names2.get(params.name) : void 0;
-      if (!tool) return null;
+      if (!tool) {
+        const builtin = typeof params.name === "string" ? BUILTIN_MCP.get(params.name) : void 0;
+        if (!builtin) return null;
+        return failure(
+          text(
+            `The connected app has no ${builtin} tool (for scenario tools: it defines no scenarios). Call tools/list again for its tools.`
+          )
+        );
+      }
       const input = params.arguments ?? {};
       let args = input.args ?? [];
       if (typeof args === "string") {
@@ -3170,7 +3217,7 @@ The call may or may not have run; check before repeating one that changes state.
             protocolVersion: SUPPORTED.includes(asked) ? asked : SUPPORTED[0],
             capabilities: { tools: { listChanged: true } },
             serverInfo: { name: "agent-bridge", version: options.version ?? "0.0.0" },
-            instructions: `Tools of the connected React Native app. Each takes \`args\`, an array of the tool's arguments. Results over 32 KB come back as a summary unless \`full\` is true. If the list is empty or calls fail, call ${STATUS_TOOL}.`
+            instructions: `Tools of the connected React Native app. Each takes \`args\`, an array of the tool's arguments. Results over 32 KB come back as a summary unless \`full\` is true. Until an app connects the list shows only the built-in tools (screen, app, bridge, and scenario, which only exists when the app defines scenarios); calls fail until then, and the app's own tools (query, store, net, ...) appear once it connects. If calls fail, call ${STATUS_TOOL}.`
           }
         };
       }

package/dist/runtime/index.cjs

@@ -70,6 +70,33 @@ async function runUndos() {
   return { ran: batch.length, errors };
 }
 
+// src/runtime/tools/descriptions.ts
+var INTERNAL_TOOLS = ["bridge.adopt"];
+var UNLISTED_WITHOUT_APP = [...INTERNAL_TOOLS, "bridge.ping"];
+var TARGET_HELP = "target is a string (testID, label, placeholder or text) or an object that must match every key it sets: {testID, label, placeholder, text, at:[x,y], index}. Unknown keys are errors. {at:[x,y]} hits the smallest element covering that point, for icon-only buttons with no label. Several matches: add an index, either in the target or as a trailing {index:n} argument.";
+var TOOL_DESCRIPTIONS = {
+  "app.reload": `Reload the app's JS (Expo's reloadAppAsync, else DevSettings.reload). Pending restores (store, query, mocks, pins, storage) are lost, and the reply names them: restore first. Returns before it reloads; a session waits for the new bridge and reports what was lost.`,
+  "app.restore": `Undo what the app's own tools changed: runs the undos they registered with onRestore, newest first, once. Returns how many ran.`,
+  "bridge.adopt": `Internal: a session hands back its journal after a reload.`,
+  "bridge.logs": `Errors and warnings the app logged, newest last. Options: {level: "error"|"warn"|"all", limit, clear}.`,
+  "bridge.pending": `What bridge.restore would undo right now, per area (store, query, net, app, ...): the value is true, or detail such as a store's snapshot against its current value. Empty when nothing is pending. Changes nothing.`,
+  "bridge.ping": `Round-trip check. Returns the app clock.`,
+  "bridge.restore": `Undo what the agent changed: runs every *.restore tool in name order, scenario.restore last, and returns each result or error.`,
+  "bridge.tools": `Every tool this app exposes.`,
+  "scenario.apply": `Apply a scenario: [name, options?]. Options must fit its schema (scenario.list). Returns what it returns. Applying an active one undoes it first. bridge.restore undoes it.`,
+  "scenario.list": `Setups the app defines, e.g. a signed-in user: name, description, options (a JSON Schema), active.`,
+  "scenario.restore": `Undo every active scenario, newest first. bridge.restore runs this after every other restorer.`,
+  "screen.capture": `Screenshot the app as a PNG. Returns {path} of a file on the device. \`{base64:true}\` returns {base64} instead when small enough (else {path}). Only works if the app already has react-native-view-shot; otherwise errors and you use agent-device, simctl or adb.`,
+  "screen.fill": `Type into an input, then wait for the render. ${TARGET_HELP} {submit:true} also submits. "" clears it. {type:true} types one character at a time, waiting for a render after each (for debounced or per-character inputs; "\\n" is the Enter key). An input with no value prop gets its native text set; if that cannot be done the reply has a warning.`,
+  "screen.findText": `Find text on screen (substring, or exact with {exact:true}) and whether each match is on screen. Searches the same joined text screen.snapshot shows (nested Text concatenated) and accessibility labels; {labels:false} searches text only. Each match says which field matched; a miss lists near misses. Ignores screens the user can't reach (unfocused tabs and stack screens, under a modal); \`hidden\` counts matches there.`,
+  "screen.press": `Press a button, then wait for the render. ${TARGET_HELP} Text with no handler of its own presses the nearest ancestor that has one, and the reply says via:"ancestor". Disabled elements are refused; {force:true} presses anyway, to see what the app does on tap. {scroll:true} scrolls an off-screen target into view first. With no onPress it sends the "activate" accessibility action, as a screen reader's double tap does (swipe-to-confirm buttons, sliders), and the reply says via:"accessibilityAction:activate". {action:"increment"} (or any name in the element's snapshot \`actions\`) sends that action instead. A Switch (native switch host or role switch, with onValueChange) is toggled with onValueChange(!value), not the row around it; reply via:"onValueChange". {long:true} long presses: onPressIn, onLongPress, onPressOut (never onPress); an error when there is no onLongPress, on the element or an ancestor. {scroll:true} also pages the largest vertical FlatList/SectionList/FlashList for a row it has not rendered yet (and scrolls back if it finds none; onEndReached may fire). A tap inside a react-native-gesture-handler GestureDetector cannot be pressed from here (its callbacks run on the UI thread): the error says so.`,
+  "screen.refresh": `Pull to refresh: call the onRefresh of the RefreshControl of the scrollable holding a target (or the largest one with a RefreshControl on screen), then wait for the render. It does not wait for the data: follow with screen.waitFor.`,
+  "screen.scroll": `Scroll the nearest ScrollView/FlatList/FlashList, then wait for the render. Takes a target (or {to: target}) to bring into the middle of its scrollable, {toEnd:true}, {toStart:true}, or {by: points} (negative scrolls back); the last argument may be {within: target, index} to name the scrollable (a target inside it, or its testID). Without a target it scrolls the largest scrollable on screen. Only rendered elements can be targeted: rows a FlatList has not rendered yet need {toEnd:true} or {by} first. Returns the offset and, for a target, whether it is now on screen. ${TARGET_HELP}`,
+  "screen.setValue": `Set a Switch, Slider, Picker or SegmentedControl: calls its onValueChange (and a Slider's onSlidingComplete) with the value, waits for the render and reads the value back. A Switch takes true or false, a Slider a number within minimumValue and maximumValue (0 and 1 by default) and on its step (onSlidingStart, onValueChange, onSlidingComplete), a Picker one of its Picker.Item values, a SegmentedControl one of its values (a wrong type or value is an error that lists the options). The reply has \`value\` as the app now shows it, and a warning when that is not what was set (a controlled value the app refused). Disabled controls are refused; {force:true} sets anyway. {scroll:true} scrolls or pages the target into view first (pages the largest vertical list; onEndReached may fire). ${TARGET_HELP}`,
+  "screen.snapshot": `Buttons, inputs, text, and testID or labelled views on screen, with rects and checked/selected/expanded state (a Switch's value is checked). \`actions\` lists the accessibility actions an element handles; one with "activate" and no onPress (a swipe-to-confirm) is a button screen.press can press. Only the focused screen: unfocused tabs and stack screens, content under an open modal, display:none and accessibility-hidden subtrees are left out, and \`hidden\` counts the elements skipped. {all:true} lists everything, marking off-screen (onScreen:false) and hidden (hidden:true) ones. A WebView registered with the react-native-webview adapter shows as one \`webview\` element with its name: use webview.* inside it. Options: {format:"json"|"text"} (the runtime default is JSON with rects; the CLI and the MCP server return the text form unless you pass {format:"json"}). Text is one line per element: kind (or role: switch, checkbox, tab), #testID, text, label, value, state, then \`readonly\`, \`actions=\u2026\`, \`offscreen\`, \`hidden\`. Lines that repeat get \`index=N\` (the {index} of the target that names them); a line with no testID, text, label or placeholder gets \`@x,y\`, the point for {at:[x,y]}. JSON has rects, onScreen:false and hidden:true. {kinds:["button","input"]} keeps only those kinds (kinds are button, input, text, view, webview; a switch or tab is a button); {within: target} keeps only elements under that target in the tree (a target as for screen.press; with several matches pass {testID, index} inside it).`,
+  "screen.waitFor": `Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. {scroll:true} also accepts a match rendered off screen and scrolls it into view, (it does not page lists for rows they have not rendered: wait for the list, then press/fill/setValue with {scroll:true}; not with gone). Default timeout 5000 ms; a timeout lists near misses.`
+};
+
 // src/runtime/tools/restore.ts
 var SUFFIX = ".restore";
 var SELF = "bridge.restore";
@@ -108,17 +135,16 @@ function journalRev(tools) {
 function restorers(tools) {
   return Object.entries(tools).filter(([name, d]) => name.endsWith(SUFFIX) && name !== SELF && typeof d !== "function").map(([name, d]) => [name.slice(0, -SUFFIX.length), d]).filter((e) => typeof e[1] !== "function");
 }
-var INTERNAL_TOOLS = ["bridge.adopt"];
 function restoreTools(getTools) {
   return {
     "bridge.pending": {
       maxArgs: 0,
-      description: "What bridge.restore would undo right now, per area (store, query, net, app, ...): the value is true, or detail such as a store's snapshot against its current value. Empty when nothing is pending. Changes nothing.",
+      description: TOOL_DESCRIPTIONS["bridge.pending"],
       run: () => pendingByArea(getTools(), true)
     },
     "bridge.adopt": {
       maxArgs: 1,
-      description: "Internal: a session hands back its journal after a reload.",
+      description: TOOL_DESCRIPTIONS["bridge.adopt"],
       run: async (data) => {
         const tools = getTools();
         const out = {};
@@ -137,7 +163,7 @@ function restoreTools(getTools) {
       }
     },
     [SELF]: {
-      description: "Undo what the agent changed: runs every *.restore tool in name order, scenario.restore last, and returns each result or error.",
+      description: TOOL_DESCRIPTIONS["bridge.restore"],
       run: async () => {
         const tools = getTools();
         const results = {};
@@ -176,7 +202,7 @@ function selectReload(host, devSettingsReload) {
 function appTools(reload, getTools) {
   return {
     "app.reload": {
-      description: "Reload the app's JS (Expo's reloadAppAsync, else DevSettings.reload). Pending restores (store, query, mocks, pins, storage) are lost, and the reply names them: restore first. Returns before it reloads; a session waits for the new bridge and reports what was lost.",
+      description: TOOL_DESCRIPTIONS["app.reload"],
       run: () => {
         setTimeout(reload, 50);
         const lost = getTools ? Object.keys(pendingByArea(getTools())) : [];
@@ -190,7 +216,7 @@ function appTools(reload, getTools) {
         const labels = pendingUndos();
         return labels.length ? labels : false;
       },
-      description: "Undo what the app's own tools changed: runs the undos they registered with onRestore, newest first, once. Returns how many ran.",
+      description: TOOL_DESCRIPTIONS["app.restore"],
       run: async () => {
         const { ran, errors } = await runUndos();
         if (errors.length)
@@ -205,11 +231,11 @@ function appTools(reload, getTools) {
 function bridgeTools(listTools) {
   return {
     "bridge.ping": {
-      description: "Round-trip check. Returns the app clock.",
+      description: TOOL_DESCRIPTIONS["bridge.ping"],
       run: () => ({ pong: true, at: Date.now() })
     },
     "bridge.tools": {
-      description: "Every tool this app exposes.",
+      description: TOOL_DESCRIPTIONS["bridge.tools"],
       run: listTools
     }
   };
@@ -229,7 +255,7 @@ function loadViewShot() {
 function captureTools(load) {
   return {
     "screen.capture": {
-      description: "Screenshot the app as a PNG. Returns {path} of a file on the device. `{base64:true}` returns {base64} instead when small enough (else {path}). Only works if the app already has react-native-view-shot; otherwise errors and you use agent-device, simctl or adb.",
+      description: TOOL_DESCRIPTIONS["screen.capture"],
       maxArgs: 1,
       run: async (options) => {
         const viewShot = load();
@@ -255,7 +281,7 @@ function captureTools(load) {
 function logTools(logs) {
   return {
     "bridge.logs": {
-      description: 'Errors and warnings the app logged, newest last. Options: {level: "error"|"warn"|"all", limit, clear}.',
+      description: TOOL_DESCRIPTIONS["bridge.logs"],
       run: (options = {}) => {
         const entries = logs.read(options);
         if (options.clear) logs.clear();
@@ -361,7 +387,7 @@ function scenarioTools(getScenarios, getTools) {
   };
   return {
     "scenario.list": {
-      description: "Setups the app defines, e.g. a signed-in user: name, description, options (a JSON Schema), active.",
+      description: TOOL_DESCRIPTIONS["scenario.list"],
       run: () => Object.entries(getScenarios()).map(([name, s]) => ({
         name,
         description: s.description,
@@ -370,7 +396,7 @@ function scenarioTools(getScenarios, getTools) {
       })).sort((a, b) => a.name.localeCompare(b.name))
     },
     "scenario.apply": {
-      description: "Apply a scenario: [name, options?]. Options must fit its schema (scenario.list). Returns what it returns. Applying an active one undoes it first. bridge.restore undoes it.",
+      description: TOOL_DESCRIPTIONS["scenario.apply"],
       run: async (name, options) => {
         const scenario = find(name);
         if (scenario.options) {
@@ -407,7 +433,7 @@ scenario.list shows its options schema.`
     },
     "scenario.restore": {
       pending: () => active.size > 0,
-      description: "Undo every active scenario, newest first. bridge.restore runs this after every other restorer.",
+      description: TOOL_DESCRIPTIONS["scenario.restore"],
       run: async () => {
         const names = [...active.keys()].reverse();
         const errors = [];
@@ -2196,7 +2222,6 @@ function createScreen(env) {
 
 // src/runtime/tools/screen.ts
 var devToolsHook = () => globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
-var TARGET_HELP = "target is a string (testID, label, placeholder or text) or an object that must match every key it sets: {testID, label, placeholder, text, at:[x,y], index}. Unknown keys are errors. {at:[x,y]} hits the smallest element covering that point, for icon-only buttons with no label. Several matches: add an index, either in the target or as a trailing {index:n} argument.";
 function screenTools() {
   const screen = createScreen({
     roots: () => fiberRoots(devToolsHook()),
@@ -2204,35 +2229,35 @@ function screenTools() {
   });
   return {
     "screen.findText": {
-      description: "Find text on screen (substring, or exact with {exact:true}) and whether each match is on screen. Searches the same joined text screen.snapshot shows (nested Text concatenated) and accessibility labels; {labels:false} searches text only. Each match says which field matched; a miss lists near misses. Ignores screens the user can't reach (unfocused tabs and stack screens, under a modal); `hidden` counts matches there.",
+      description: TOOL_DESCRIPTIONS["screen.findText"],
       run: (text, options) => screen.findText(text, options)
     },
     "screen.snapshot": {
-      description: 'Buttons, inputs, text, and testID or labelled views on screen, with rects and checked/selected/expanded state (a Switch\'s value is checked). `actions` lists the accessibility actions an element handles; one with "activate" and no onPress (a swipe-to-confirm) is a button screen.press can press. Only the focused screen: unfocused tabs and stack screens, content under an open modal, display:none and accessibility-hidden subtrees are left out, and `hidden` counts the elements skipped. {all:true} lists everything, marking off-screen (onScreen:false) and hidden (hidden:true) ones. A WebView registered with the react-native-webview adapter shows as one `webview` element with its name: use webview.* inside it. Options: {format:"json"|"text"} (the runtime default is JSON with rects; the CLI and the MCP server return the text form unless you pass {format:"json"}). Text is one line per element: kind (or role: switch, checkbox, tab), #testID, text, label, value, state, then `readonly`, `actions=\u2026`, `offscreen`, `hidden`. Lines that repeat get `index=N` (the {index} of the target that names them); a line with no testID, text, label or placeholder gets `@x,y`, the point for {at:[x,y]}. JSON has rects, onScreen:false and hidden:true. {kinds:["button","input"]} keeps only those kinds (kinds are button, input, text, view, webview; a switch or tab is a button); {within: target} keeps only elements under that target in the tree (a target as for screen.press; with several matches pass {testID, index} inside it).',
+      description: TOOL_DESCRIPTIONS["screen.snapshot"],
       run: (options) => options?.format === "text" ? screen.snapshotText(options) : screen.snapshot(options)
     },
     "screen.fill": {
-      description: `Type into an input, then wait for the render. ${TARGET_HELP} {submit:true} also submits. "" clears it. {type:true} types one character at a time, waiting for a render after each (for debounced or per-character inputs; "\\n" is the Enter key). An input with no value prop gets its native text set; if that cannot be done the reply has a warning.`,
+      description: TOOL_DESCRIPTIONS["screen.fill"],
       run: (target, text, options) => screen.fill(target, text, options)
     },
     "screen.press": {
-      description: `Press a button, then wait for the render. ${TARGET_HELP} Text with no handler of its own presses the nearest ancestor that has one, and the reply says via:"ancestor". Disabled elements are refused; {force:true} presses anyway, to see what the app does on tap. {scroll:true} scrolls an off-screen target into view first. With no onPress it sends the "activate" accessibility action, as a screen reader's double tap does (swipe-to-confirm buttons, sliders), and the reply says via:"accessibilityAction:activate". {action:"increment"} (or any name in the element's snapshot \`actions\`) sends that action instead. A Switch (native switch host or role switch, with onValueChange) is toggled with onValueChange(!value), not the row around it; reply via:"onValueChange". {long:true} long presses: onPressIn, onLongPress, onPressOut (never onPress); an error when there is no onLongPress, on the element or an ancestor. {scroll:true} also pages the largest vertical FlatList/SectionList/FlashList for a row it has not rendered yet (and scrolls back if it finds none; onEndReached may fire). A tap inside a react-native-gesture-handler GestureDetector cannot be pressed from here (its callbacks run on the UI thread): the error says so.`,
+      description: TOOL_DESCRIPTIONS["screen.press"],
       run: (target, options) => screen.press(target, options)
     },
     "screen.setValue": {
-      description: `Set a Switch, Slider, Picker or SegmentedControl: calls its onValueChange (and a Slider's onSlidingComplete) with the value, waits for the render and reads the value back. A Switch takes true or false, a Slider a number within minimumValue and maximumValue (0 and 1 by default) and on its step (onSlidingStart, onValueChange, onSlidingComplete), a Picker one of its Picker.Item values, a SegmentedControl one of its values (a wrong type or value is an error that lists the options). The reply has \`value\` as the app now shows it, and a warning when that is not what was set (a controlled value the app refused). Disabled controls are refused; {force:true} sets anyway. {scroll:true} scrolls or pages the target into view first (pages the largest vertical list; onEndReached may fire). ${TARGET_HELP}`,
+      description: TOOL_DESCRIPTIONS["screen.setValue"],
       run: (target, value, options) => screen.setValue(target, value, options)
     },
     "screen.scroll": {
-      description: `Scroll the nearest ScrollView/FlatList/FlashList, then wait for the render. Takes a target (or {to: target}) to bring into the middle of its scrollable, {toEnd:true}, {toStart:true}, or {by: points} (negative scrolls back); the last argument may be {within: target, index} to name the scrollable (a target inside it, or its testID). Without a target it scrolls the largest scrollable on screen. Only rendered elements can be targeted: rows a FlatList has not rendered yet need {toEnd:true} or {by} first. Returns the offset and, for a target, whether it is now on screen. ${TARGET_HELP}`,
+      description: TOOL_DESCRIPTIONS["screen.scroll"],
       run: (arg, options) => screen.scroll(arg, options)
     },
     "screen.refresh": {
-      description: "Pull to refresh: call the onRefresh of the RefreshControl of the scrollable holding a target (or the largest one with a RefreshControl on screen), then wait for the render. It does not wait for the data: follow with screen.waitFor.",
+      description: TOOL_DESCRIPTIONS["screen.refresh"],
       run: (target, options) => screen.refresh(target, options)
     },
     "screen.waitFor": {
-      description: "Wait until a target is on screen, or gone with {gone:true}. Matches testID, label, placeholder, then the same joined text screen.snapshot shows. {scroll:true} also accepts a match rendered off screen and scrolls it into view, (it does not page lists for rows they have not rendered: wait for the list, then press/fill/setValue with {scroll:true}; not with gone). Default timeout 5000 ms; a timeout lists near misses.",
+      description: TOOL_DESCRIPTIONS["screen.waitFor"],
       run: (target, options) => screen.waitFor(target, options)
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avasapp/agent-bridge",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Let coding agents drive a running React Native app directly: seed state, flip flags, navigate and check the screen in about a millisecond per call, with no taps.",
   "type": "module",
   "license": "MIT",

package/skills/agent-bridge/SKILL.md

@@ -36,7 +36,7 @@ roughly 200 ms more startup per call (machine-dependent).
 If the app's tools are already in your tool list as an MCP server
 (`agent-bridge mcp`; names like `screen_snapshot` for `screen.snapshot`), call
 those: each takes `args`, an array of the tool's arguments, and `full: true` for
-a result over 32 KB. If the list is empty or a call fails, call `agent_bridge_status`. A failed call keeps the session's own error (`may or may not have run`): check state before repeating a call that changes it. The rest of this skill applies the same way.
+a result over 32 KB. With no app connected the MCP list shows only the built-in tools and calls fail until the app connects; if a call fails, call `agent_bridge_status`. A failed call keeps the session's own error (`may or may not have run`): check state before repeating a call that changes it. The rest of this skill applies the same way.
 
 ## Start a session