@ppppaaaaa/adb-control 0.0.0-stage → 2.0.0

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: adb-control
+      name: '@local/adb-control'
+      config: {}

package/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#1f2430"/>
+  <rect x="18" y="10" width="28" height="44" rx="6" fill="#2c3546" stroke="#3ddc84" stroke-width="2.5"/>
+  <rect x="24" y="16" width="16" height="24" rx="2" fill="#3ddc84" opacity="0.25"/>
+  <circle cx="32" cy="46" r="2.6" fill="#3ddc84"/>
+  <path d="M14 26a10 10 0 0 1 0 12" fill="none" stroke="#3ddc84" stroke-width="2.5" stroke-linecap="round" opacity="0.9"/>
+  <path d="M9 29a15 15 0 0 1 0 6" fill="none" stroke="#3ddc84" stroke-width="2.5" stroke-linecap="round" opacity="0.6"/>
+  <path d="M50 26a10 10 0 0 0 0 12" fill="none" stroke="#3ddc84" stroke-width="2.5" stroke-linecap="round" opacity="0.9"/>
+  <path d="M55 29a15 15 0 0 0 0 6" fill="none" stroke="#3ddc84" stroke-width="2.5" stroke-linecap="round" opacity="0.6"/>
+</svg>

package/index.js

@@ -0,0 +1,1079 @@
+// @local/adb-control — control Android phones over wired or wireless ADB.
+//
+// Design principle: the UI hierarchy is the PRIMARY interface. The agent
+// reads a compact, indexed element tree (adb_ui_map) and acts on elements by
+// their index (adb_tap / adb_set_text / adb_scroll / adb_wait_for). Screenshots
+// are SECONDARY: a confirmation/fallback channel (adb_screenshot) for game
+// surfaces, lock screens, WebViews that hide their tree, and for verifying an
+// action landed — never the first thing to reach for.
+//
+// Tools:
+//   adb_ui_map     PRIMARY READ. Indexed element tree + screen + focused input.
+//   adb_tap        tap/long-press by element ref (text/desc/id) or raw x,y fallback.
+//   adb_set_text   focus a field by ref and type into it, replacing existing text.
+//   adb_scroll     scroll by direction/fraction, optionally inside a ref's bounds.
+//   adb_wait_for   poll the tree until an element appears/leaves (replaces sleeping).
+//   adb_devices    list connected devices (USB serials and wireless ip:port)
+//   adb_connect    wireless connect / pair / disconnect / switch a USB device to tcpip
+//   adb_input      low-level tap/swipe/text/key on raw coordinates (no tree lookup)
+//   adb_shell      run an arbitrary shell command on the device
+//   adb_screenshot SECONDARY. PNG on the host, for fallback/verification only.
+//   adb_ui_dump    raw uiautomator XML when adb_ui_map is not enough
+//   adb_files      push / pull files between host and device
+//   adb_install    install an APK from a host path
+//   adb_configure  persist default adb path, default device, screenshot dir
+//
+// Settings persist in ~/.dsh/adb-control.json; the default adb binary is
+// settings.adbPath || $DSH_ADB || "adb" on PATH.
+
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PLUGIN = 'adb-control';
+const SETTINGS_PATH = path.join(os.homedir(), '.dsh', 'adb-control.json');
+const MAX_TEXT_OUTPUT = 60000;
+const MAX_XML_OUTPUT = 120000;
+const MAX_MAP_CHARS = 24000;
+
+//#region settings
+
+function loadSettings() {
+	try {
+		const raw = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
+		return raw && typeof raw === 'object' ? raw : {};
+	} catch {
+		return {};
+	}
+}
+
+function saveSettings(patch) {
+	const next = { ...loadSettings(), ...patch };
+	for (const key of Object.keys(next)) if (next[key] === undefined) delete next[key];
+	mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+	writeFileSync(SETTINGS_PATH, JSON.stringify(next, null, 2) + '\n', 'utf8');
+	return next;
+}
+
+function resolveAdb() {
+	return loadSettings().adbPath || process.env.DSH_ADB || 'adb';
+}
+
+function screenshotDir() {
+	return loadSettings().screenshotDir || path.join(os.homedir(), 'dsh-adb-screenshots');
+}
+
+//#endregion
+
+//#region adb plumbing
+
+function runAdb(args, { timeoutMs = 30000, signal, maxBuffer = 8 * 1024 * 1024, encoding = 'utf8' } = {}) {
+	return new Promise((resolve, reject) => {
+		execFile(resolveAdb(), args, { timeout: timeoutMs, signal, maxBuffer, encoding, windowsHide: true }, (error, stdout, stderr) => {
+			if (error) {
+				if (signal?.aborted) return reject(new Error('cancelled by the caller'));
+				if (error.code === 'ENOENT') return reject(new Error('adb executable not found ("' + resolveAdb() + '"). Install adb (e.g. sudo apt install adb) or set the path with the adb_configure tool.'));
+				const detail = [stderr, error.message].filter(Boolean).join('\n').trim();
+				return reject(new Error(detail || 'adb exited with an error'));
+			}
+			resolve({ stdout, stderr });
+		});
+	});
+}
+
+/** Parse `adb devices -l` into structured rows; the serial contains ":" for wireless targets. */
+function parseDevices(text) {
+	return text.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line && !line.startsWith('List of devices') && !line.startsWith('*'))
+		.map((line) => {
+			const fields = Object.fromEntries(line.split(/\s+/).slice(2).map((f) => {
+				const i = f.indexOf(':');
+				return i > 0 ? [f.slice(0, i), f.slice(i + 1)] : [f, true];
+			}));
+			const [serial, state] = line.split(/\s+/);
+			return {
+				serial,
+				state,
+				connection: serial.includes(':') ? 'wireless' : 'usb',
+				...(fields.model ? { model: fields.model } : {}),
+				...(fields.device ? { device: fields.device } : {}),
+				...(fields.product ? { product: fields.product } : {}),
+				...(fields.transport_id ? { transportId: fields.transport_id } : {})
+			};
+		});
+}
+
+/**
+ * Resolve the `-s` prefix for a call. Explicit argument wins, then the saved
+ * default device, then a single connected device; ambiguity fails loud with
+ * the candidate list so the caller can pick one.
+ */
+async function deviceArgs(device) {
+	const target = device || loadSettings().defaultDevice;
+	if (target) return ['-s', target];
+	const online = parseDevices((await runAdb(['devices', '-l'])).stdout).filter((d) => d.state === 'device');
+	if (online.length === 1) return ['-s', online[0].serial];
+	if (online.length === 0) throw new Error('no Android device is currently online. Connect one over USB (with USB debugging enabled) or use adb_connect for wireless.');
+	throw new Error('multiple devices online (' + online.map((d) => d.serial).join(', ') + '). Pass "device" with one serial, or set a default with adb_configure.');
+}
+
+/** KEYCODE names accepted by adb_input; bare numbers pass through as raw codes. */
+const KEYCODES = {
+	home: 3, back: 4, menu: 82, power: 26, wake: 224, sleep: 223,
+	volume_up: 24, volume_down: 25, mute: 164, recents: 187, app_switch: 187,
+	enter: 66, del: 67, tab: 61, space: 62, search: 84, notification: 83,
+	dpad_up: 19, dpad_down: 20, dpad_left: 21, dpad_right: 22, dpad_center: 23,
+	media_play: 126, media_pause: 127, media_next: 87, media_prev: 88,
+	volume_mute: 164, brightness_up: 221, brightness_down: 220, camera: 27
+};
+
+function requireNumber(value, name) {
+	const n = Number(value);
+	if (!Number.isFinite(n)) throw new Error('this action requires a numeric "' + name + '"');
+	return n;
+}
+
+function clip(text, limit) {
+	return text.length > limit ? text.slice(0, limit) + '\n… [truncated ' + (text.length - limit) + ' characters]' : text;
+}
+
+function escapeRe(s) {
+	return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+//#endregion
+
+//#region ui tree model
+//
+// The tree is the primary interface, so this region carries the real weight:
+// fetch the dump, decode XML entities, flatten it into an indexed list of
+// meaningful (actionable or labelled) nodes, render it as a compact outline,
+// and resolve stable refs before an action runs.
+
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', '#39': "'", '#34': '"' };
+
+function decodeEntities(text) {
+	return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+		if (XML_ENTITIES[body] !== undefined) return XML_ENTITIES[body];
+		if (body[0] === '#') {
+			const code = body[1] === 'x' || body[1] === 'X' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+			if (Number.isFinite(code)) {
+				try { return String.fromCodePoint(code); } catch { return whole; }
+			}
+		}
+		return whole;
+	});
+}
+
+/** Extract the raw uiautomator XML for the current screen. */
+async function dumpUiXml(base, signal) {
+	await runAdb([...base, 'shell', 'uiautomator', 'dump', '/sdcard/window_dump.xml'], { signal, timeoutMs: 30000 });
+	const xml = (await runAdb([...base, 'shell', 'cat', '/sdcard/window_dump.xml'], { signal, timeoutMs: 20000 })).stdout;
+	if (!xml.trim()) throw new Error('uiautomator produced an empty dump (the screen may not expose a view hierarchy, e.g. a game or the lock screen). Fall back to adb_screenshot.');
+	return xml;
+}
+
+function parseBounds(raw) {
+	const m = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(raw || '');
+	if (!m) return undefined;
+	const [x1, y1, x2, y2] = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+	return { x1, y1, x2, y2, cx: Math.round((x1 + x2) / 2), cy: Math.round((y1 + y2) / 2), w: x2 - x1, h: y2 - y1 };
+}
+
+function readAttr(tag, name) {
+	const m = new RegExp('\\b' + name + '="([^"]*)"').exec(tag);
+	return m ? decodeEntities(m[1]) : '';
+}
+
+/** Actionable classes: containers worth naming even when their own text is empty. */
+const SCROLLABLE_CLASSES = /ScrollView|RecyclerView|ListView|GridView|ViewPager|HorizontalScrollView|NestedScrollView|WebView/i;
+const INPUT_CLASSES = /EditText|AutoCompleteTextView|SearchView/i;
+const LABEL_CLASSES = /TextView|Button|CheckBox|RadioButton|Switch|ToggleButton|ImageView|ImageButton|Tab|Chip|MenuItem/i;
+
+/**
+ * Flatten uiautomator XML into an indexed list of useful nodes.
+ *
+ * Everything visible gets a path number, but only nodes that can be acted on
+ * or that carry a label get their own line: an unlabelled, unclickable
+ * FrameLayout is noise for an agent picking a target. `ref` indexes follow
+ * document order, so ref 3 stays ref 3 as long as the screen does not change.
+ */
+function buildTree(xml) {
+	const nodes = [];
+	const stack = [];
+	const tagRe = /<(\/?)([A-Za-z][\w.:-]*)((?:"[^"]*"|[^>"])*?)(\/?)>/g;
+	let m;
+	while ((m = tagRe.exec(xml)) !== null) {
+		const [, closing, tagName, attrText, selfClosing] = m;
+		if (closing) { stack.pop(); continue; }
+		const tag = tagName;
+		const cls = readAttr(attrText, 'class');
+		const attrs = {
+			text: readAttr(attrText, 'text'),
+			desc: readAttr(attrText, 'content-desc'),
+			id: readAttr(attrText, 'resource-id'),
+			cls,
+			pkg: readAttr(attrText, 'package'),
+			clickable: readAttr(attrText, 'clickable') === 'true',
+			longClickable: readAttr(attrText, 'long-clickable') === 'true',
+			scrollable: readAttr(attrText, 'scrollable') === 'true',
+			checkable: readAttr(attrText, 'checkable') === 'true',
+			checked: readAttr(attrText, 'checked') === 'true',
+			selected: readAttr(attrText, 'selected') === 'true',
+			enabled: readAttr(attrText, 'enabled') !== 'false',
+			focused: readAttr(attrText, 'focused') === 'true',
+			editable: INPUT_CLASSES.test(cls) || INPUT_CLASSES.test(tag),
+			password: readAttr(attrText, 'password') === 'true',
+			bounds: parseBounds(readAttr(attrText, 'bounds'))
+		};
+		const node = {
+			ref: nodes.length,
+			depth: stack.length,
+			parent: stack.length ? stack[stack.length - 1] : -1,
+			shortClass: (attrs.cls.split('.').pop() || tag),
+			...attrs,
+			children: 0
+		};
+		if (node.parent >= 0) nodes[node.parent].children += 1;
+		nodes.push(node);
+		if (!selfClosing) stack.push(node.ref);
+	}
+	return nodes;
+}
+
+function isMeaningful(node) {
+	if (!node.bounds || node.bounds.w <= 0 || node.bounds.h <= 0) return false;
+	if (node.text || node.desc || node.id) return true;
+	if (node.clickable || node.longClickable || node.scrollable || node.editable || node.checkable) return true;
+	if (node.focused || node.selected || node.checked) return true;
+	return LABEL_CLASSES.test(node.shortClass);
+}
+
+/** Indent a node by its depth relative to the nearest meaningful ancestor. */
+function depthByMeaning(nodes) {
+	const depth = new Array(nodes.length).fill(0);
+	for (const node of nodes) {
+		let parent = node.parent;
+		while (parent >= 0 && !isMeaningful(nodes[parent])) parent = nodes[parent].parent;
+		depth[node.ref] = parent >= 0 ? depth[parent] + 1 : 0;
+	}
+	return depth;
+}
+
+function describeNode(node) {
+	const bits = [];
+	bits.push(node.shortClass);
+	if (node.id) bits.push('#' + node.id.replace(/^.*\//, ''));
+	if (node.text) bits.push(JSON.stringify(node.text));
+	if (node.desc && node.desc !== node.text) bits.push('desc=' + JSON.stringify(node.desc));
+	const flags = [];
+	if (node.clickable) flags.push(node.longClickable ? 'tap/hold' : 'tap');
+	else if (node.longClickable) flags.push('hold');
+	if (node.editable) flags.push('input');
+	if (node.scrollable) flags.push('scroll');
+	if (node.checkable) flags.push(node.checked ? 'checked' : 'unchecked');
+	if (node.selected) flags.push('selected');
+	if (node.focused) flags.push('focused');
+	if (!node.enabled) flags.push('disabled');
+	if (node.password) flags.push('password');
+	if (flags.length) bits.push('[' + flags.join(',') + ']');
+	return bits.join(' ');
+}
+
+/** Render the meaningful nodes as an indented outline with refs. */
+function renderTree(nodes) {
+	const depths = depthByMeaning(nodes);
+	const lines = [];
+	for (const node of nodes) {
+		if (!isMeaningful(node)) continue;
+		const b = node.bounds;
+		lines.push('[' + node.ref + '] ' + '  '.repeat(Math.min(depths[node.ref], 12)) + describeNode(node) +
+			' @(' + b.cx + ',' + b.cy + ') ' + b.w + 'x' + b.h);
+	}
+	return lines.join('\n');
+}
+
+/** Serialize the meaningful nodes for the structured tool result. */
+function serializeTree(nodes) {
+	const depths = depthByMeaning(nodes);
+	const out = [];
+	for (const node of nodes) {
+		if (!isMeaningful(node)) continue;
+		const b = node.bounds;
+		out.push({
+			ref: node.ref,
+			depth: depths[node.ref],
+			class: node.shortClass,
+			...(node.id ? { id: node.id } : {}),
+			...(node.text ? { text: node.text } : {}),
+			...(node.desc ? { desc: node.desc } : {}),
+			bounds: [b.x1, b.y1, b.x2, b.y2],
+			center: [b.cx, b.cy],
+			...(node.clickable ? { clickable: true } : {}),
+			...(node.longClickable ? { longClickable: true } : {}),
+			...(node.editable ? { editable: true } : {}),
+			...(node.scrollable ? { scrollable: true } : {}),
+			...(node.checkable ? { checkable: true, checked: node.checked } : {}),
+			...(node.selected ? { selected: true } : {}),
+			...(node.focused ? { focused: true } : {}),
+			...(node.enabled ? {} : { enabled: false }),
+			...(node.password ? { password: true } : {})
+		});
+	}
+	return out;
+}
+
+/**
+ * The tree plus enough device context that an agent can pick a target and
+ * sanity-check orientation without a screenshot.
+ */
+async function uiMap(args, exec) {
+	const base = await deviceArgs(args.device);
+	const xml = await dumpUiXml(base, exec.signal);
+
+	let wmSize = '';
+	let rotation = '';
+	if (args.include_system_info !== false) {
+		try {
+			wmSize = (await runAdb([...base, 'shell', 'wm', 'size'], { signal: exec.signal, timeoutMs: 10000 })).stdout.trim();
+		} catch { /* informational only */ }
+		try {
+			rotation = (await runAdb([...base, 'shell', 'dumpsys', 'input', '|', 'grep', 'SurfaceOrientation'], { timeoutMs: 10000, signal: exec.signal })).stdout.trim();
+		} catch { /* informational only */ }
+	}
+
+	const nodes = buildTree(xml);
+	const meaningful = nodes.filter(isMeaningful);
+	const sizeMatch = /(\d+)x(\d+)/.exec(wmSize);
+	const screen = sizeMatch ? { width: Number(sizeMatch[1]), height: Number(sizeMatch[2]) } : undefined;
+
+	// The focused editable node is what adb_set_text will target when no ref is given.
+	const focusedEditable = meaningful.find((n) => n.editable && n.focused) || meaningful.find((n) => n.focused && n.editable);
+
+	const packages = [...new Set(nodes.map((n) => n.pkg).filter(Boolean))];
+	let outline = renderTree(nodes);
+	if (!outline.trim()) {
+		outline = '(no labelled or actionable nodes found — this screen hides its view hierarchy, e.g. a game or a secure surface. Fall back to adb_screenshot.)';
+	}
+	outline = clip(outline, MAX_MAP_CHARS);
+
+	const header = [
+		'screen ' + (screen ? screen.width + 'x' + screen.height : 'unknown') +
+			(packages.length ? '  package ' + packages[0] : '') +
+			(rotation ? '  ' + rotation.replace(/\s+/g, ' ') : ''),
+		meaningful.length + ' elements with refs (act on them with adb_tap / adb_set_text / adb_scroll / adb_wait_for)',
+		focusedEditable ? 'focused input: [' + focusedEditable.ref + '] ' + describeNode(focusedEditable) : 'no focused input'
+	].join('\n');
+
+	return {
+		device: base[1] ?? 'auto',
+		...(screen ? { screen } : {}),
+		...(packages.length ? { packages } : {}),
+		elementCount: meaningful.length,
+		...(focusedEditable ? { focusedInput: { ref: focusedEditable.ref, ...(focusedEditable.text ? { text: focusedEditable.text } : {}) } } : {}),
+		elements: serializeTree(nodes),
+		text: header + '\n\n' + outline
+	};
+}
+
+/**
+ * Match nodes against a selector. Every selector string in this plugin can be
+ * a bare ref number ("12"), or `text:`, `desc:`, `id:`, `class:` with either
+ * exact or `~` fuzzy matching.
+ */
+function parseSelector(selector) {
+	const raw = String(selector).trim();
+	if (/^\d+$/.test(raw)) return { kind: 'ref', value: Number(raw) };
+	const m = /^(text|desc|id|class|contains|regex)\s*(:|~=|=)\s*([\S\s]*)$/.exec(raw);
+	if (m) {
+		const kind = m[1] === 'contains' ? 'text' : m[1];
+		const fuzzy = m[2] === '~=';
+		return { kind, value: m[3], fuzzy, raw };
+	}
+	if (raw.startsWith('~')) return { kind: 'text', value: raw.slice(1), fuzzy: true, raw };
+	return { kind: 'text', value: raw, fuzzy: true, raw };
+}
+
+function selectorMatches(node, sel) {
+	if (sel.fuzzy) {
+		const needle = sel.value.toLowerCase();
+		if (sel.kind === 'text') return (node.text + ' ' + node.desc).toLowerCase().includes(needle);
+		if (sel.kind === 'desc') return node.desc.toLowerCase().includes(needle);
+		if (sel.kind === 'id') return node.id.toLowerCase().includes(needle);
+		if (sel.kind === 'class') return node.shortClass.toLowerCase().includes(needle);
+	}
+	try {
+		if (sel.kind === 'regex') return new RegExp(sel.value, 'i').test(node.text + ' ' + node.desc + ' ' + node.id);
+	} catch {
+		throw new Error('invalid regex selector: ' + sel.value);
+	}
+	if (sel.kind === 'text') return node.text === sel.value || node.desc === sel.value;
+	if (sel.kind === 'desc') return node.desc === sel.value;
+	if (sel.kind === 'id') return node.id === sel.value || node.id.replace(/^.*\//, '') === sel.value;
+	if (sel.kind === 'class') return node.shortClass.toLowerCase() === sel.value.toLowerCase();
+	return false;
+}
+
+/**
+ * Resolve a selector against a live dump.
+ *
+ * Ambiguity is an error, not a coin flip: acting on the wrong element is worse
+ * than asking again, so the message lists the candidates with their refs.
+ */
+async function resolveTarget(base, selector, { need = 'any', signal } = {}) {
+	const nodes = buildTree(await dumpUiXml(base, signal));
+	const meaningful = nodes.filter(isMeaningful);
+	const sel = parseSelector(selector);
+
+	let candidates;
+	if (sel.kind === 'ref') {
+		const node = nodes[sel.value];
+		if (!node) throw new Error('ref ' + sel.value + ' is out of range for this screen (' + meaningful.length + ' elements). Call adb_ui_map to refresh refs.');
+		candidates = [node];
+	} else {
+		candidates = meaningful.filter((n) => selectorMatches(n, sel));
+	}
+
+	if (!candidates.length) {
+		throw new Error('no element matched "' + selector + '" on the current screen. Call adb_ui_map to see the available refs.');
+	}
+
+	// A clickable node is usually the real target, even when a child label matched first.
+	const preferred = need === 'clickable'
+		? candidates.filter((n) => n.clickable || n.longClickable)
+		: need === 'editable'
+			? candidates.filter((n) => n.editable || n.clickable)
+			: need === 'scrollable'
+				? candidates.filter((n) => n.scrollable)
+				: candidates;
+	const pool = preferred.length ? preferred : candidates;
+
+	if (pool.length > 1) {
+		const detail = pool.slice(0, 8).map((n) => '  [' + n.ref + '] ' + describeNode(n)).join('\n');
+		throw new Error(pool.length + ' elements matched "' + selector + '". Pick one by ref:\n' + detail +
+			(pool.length > 8 ? '\n  … and ' + (pool.length - 8) + ' more' : ''));
+	}
+
+	const node = pool[0];
+	if (!node.bounds) throw new Error('the matched element has no bounds and cannot be clicked');
+	if (need === 'editable' && !node.editable && !node.clickable) {
+		throw new Error('element [' + node.ref + '] is neither an input field nor clickable: ' + describeNode(node));
+	}
+	return { nodes, node, sel };
+}
+
+function firstScrollable(nodes, node) {
+	if (node?.scrollable) return node;
+	if (node) {
+		for (let p = node.parent; p >= 0; p = nodes[p].parent) if (nodes[p].scrollable) return nodes[p];
+	}
+	return nodes.filter((n) => n.scrollable && n.bounds && n.bounds.h > 0).sort((a, b) => (b.bounds.w * b.bounds.h) - (a.bounds.w * a.bounds.h))[0];
+}
+
+/** Read the current text of an editable node, for replace-style set_text. */
+async function readFieldText(base, ref, signal) {
+	try {
+		const xml = await dumpUiXml(base, signal);
+		const node = buildTree(xml)[ref];
+		return node?.text || '';
+	} catch {
+		return '';
+	}
+}
+
+//#endregion
+
+//#region tool factory
+
+/** Build a ToolDefinition-shaped plain object (no external schema dependency). */
+function defineTool({ name, description, parameters, execute, concurrencySafe = false, presentCall }) {
+	return {
+		name,
+		description,
+		parameters,
+		output: {
+			schema: { type: 'object', description: 'JSON result; the rendered text carries the same content.' },
+			render(args, value) {
+				return [{ type: 'text', text: typeof value?.text === 'string' && value.text ? value.text : JSON.stringify(value, null, 2) }];
+			}
+		},
+		isConcurrencySafe: () => concurrencySafe,
+		...(presentCall ? { presentCall } : {}),
+		async execute(args, exec) {
+			const value = await execute(args ?? {}, exec);
+			return { ...value, text: value.text ?? JSON.stringify(value) };
+		}
+	};
+}
+
+const deviceParam = { type: 'string', description: 'Target device serial or wireless address (ip:port). Omit to use the saved default device, or the only connected device.' };
+const selectorParam = {
+	type: 'string',
+	description: 'Element selector: a ref number from adb_ui_map ("12"), or text:/desc:/id:/class: with the exact ("text:Sign in") or fuzzy ("text~=sign") form. Bare strings match text or content-desc, fuzzy by default.'
+};
+
+//#endregion
+
+//#region primary tools — UI tree first
+
+const adbUiMap = defineTool({
+	name: 'adb_ui_map',
+	description: 'PRIMARY way to see the phone. Dumps the current UI hierarchy as a compact indexed tree: one line per labelled or interactive element with its ref, class, resource-id, text, content-desc, flags (tap/input/scroll/checked/disabled) and center coordinates, plus screen size and the focused input field. Start every interaction here, then act by ref with adb_tap, adb_set_text, adb_scroll or adb_wait_for. Call it again after each action because refs are only valid for the screen they were read on. Use adb_screenshot only when a screen exposes no usable tree (games, video, secure surfaces).',
+	parameters: {
+		type: 'object',
+		properties: {
+			device: deviceParam,
+			include_system_info: { type: 'boolean', description: 'Also read screen size and orientation (default true; small extra adb round trip).' }
+		}
+	},
+	concurrencySafe: true,
+	presentCall() {
+		return { card: 'terminal', title: 'adb ui map' };
+	},
+	execute: uiMap
+});
+
+const adbTap = defineTool({
+	name: 'adb_tap',
+	description: 'THE way to press things. Resolves an element selector against the live UI tree and taps its center, so the agent never has to guess pixel coordinates. Give "selector" (a ref from adb_ui_map such as "12", or "text:Sign in" / "desc:Search" / "id:com.app:id/ok"), or fall back to raw "x","y" only when the tree has nothing usable. Ambiguous selectors fail with the candidate refs instead of tapping something wrong. Set action "long_press" to hold.',
+	parameters: {
+		type: 'object',
+		properties: {
+			action: { type: 'string', enum: ['tap', 'long_press'], description: 'Tap (default) or long press.' },
+			selector: selectorParam,
+			x: { type: 'integer', description: 'Raw X fallback, only when no selector matches (device pixels, origin top-left).' },
+			y: { type: 'integer', description: 'Raw Y fallback.' },
+			duration_ms: { type: 'integer', description: 'Hold duration for long_press (default 800).' },
+			device: deviceParam
+		}
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb ' + (args.action === 'long_press' ? 'long press' : 'tap') + ' ' + (args.selector ?? args.x + ',' + args.y) };
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const long = args.action === 'long_press';
+		let x;
+		let y;
+		let target;
+
+		if (args.selector !== undefined && args.selector !== null && String(args.selector).length) {
+			const { node } = await resolveTarget(base, args.selector, { need: 'clickable', signal: exec.signal });
+			({ cx: x, cy: y } = node.bounds);
+			target = { ref: node.ref, class: node.shortClass, ...(node.text ? { text: node.text } : {}), ...(node.desc ? { desc: node.desc } : {}), center: [x, y] };
+		} else if (args.x !== undefined && args.y !== undefined) {
+			x = Math.round(requireNumber(args.x, 'x'));
+			y = Math.round(requireNumber(args.y, 'y'));
+			target = { center: [x, y], source: 'raw coordinates' };
+		} else {
+			throw new Error('adb_tap needs "selector" (preferred) or both "x" and "y". Call adb_ui_map to get refs.');
+		}
+
+		if (long) {
+			const ms = Number.isFinite(Number(args.duration_ms)) ? Math.max(1, Math.round(Number(args.duration_ms))) : 800;
+			await runAdb([...base, 'shell', 'input', 'swipe', String(x), String(y), String(x), String(y), String(ms)], { signal: exec.signal, timeoutMs: 30000 });
+			return { action: 'long_press', device: base[1] ?? 'auto', ...target, durationMs: ms, text: 'long pressed ' + JSON.stringify(target) + ' for ' + ms + 'ms' };
+		}
+		await runAdb([...base, 'shell', 'input', 'tap', String(x), String(y)], { signal: exec.signal, timeoutMs: 30000 });
+		return { action: 'tap', device: base[1] ?? 'auto', ...target, text: 'tapped ' + JSON.stringify(target) + '. Read the tree again with adb_ui_map to confirm the screen changed.' };
+	}
+});
+
+const adbSetText = defineTool({
+	name: 'adb_set_text',
+	description: 'Type text into an input field located through the UI tree. Give "selector" for the field (ref or text:/id:/desc:); if omitted, the focused input from adb_ui_map is used, or you may pass raw "x","y" to tap a field first. Existing text is cleared by default (select-all + delete), so this sets rather than appends. Punctuation-heavy text is routed through base64 so special characters survive.',
+	parameters: {
+		type: 'object',
+		properties: {
+			text: { type: 'string', description: 'Text to enter.', required: true },
+			selector: selectorParam,
+			x: { type: 'integer', description: 'Raw fallback: tap this X to focus the field before typing.' },
+			y: { type: 'integer', description: 'Raw fallback: tap this Y to focus the field before typing.' },
+			clear: { type: 'boolean', description: 'Clear the field first (default true). Set false to append at the cursor.' },
+			submit: { type: 'boolean', description: 'Press Enter after typing (default false).' },
+			device: deviceParam
+		},
+		required: ['text']
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb text', description: String(args.text).slice(0, 80) };
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const clear = args.clear !== false;
+		let focused = null;
+
+		if (args.selector !== undefined && args.selector !== null && String(args.selector).length) {
+			const { node } = await resolveTarget(base, args.selector, { need: 'editable', signal: exec.signal });
+			focused = { ref: node.ref, class: node.shortClass, center: [node.bounds.cx, node.bounds.cy] };
+			await runAdb([...base, 'shell', 'input', 'tap', String(node.bounds.cx), String(node.bounds.cy)], { signal: exec.signal, timeoutMs: 30000 });
+		} else if (args.x !== undefined && args.y !== undefined) {
+			const x = Math.round(requireNumber(args.x, 'x'));
+			const y = Math.round(requireNumber(args.y, 'y'));
+			focused = { center: [x, y], source: 'raw coordinates' };
+			await runAdb([...base, 'shell', 'input', 'tap', String(x), String(y)], { signal: exec.signal, timeoutMs: 30000 });
+		}
+
+		await new Promise((r) => setTimeout(r, 250));
+
+		const typed = String(args.text);
+		if (!typed) throw new Error('adb_set_text requires non-empty "text"');
+
+		// ASCII without shell metacharacters goes straight through, as most
+		// `input text` implementations only accept [A-Za-z0-9._%+- ] reliably.
+		if (/^[A-Za-z0-9._%+@\- ,!?]+$/.test(typed)) {
+			if (clear && focused?.ref !== undefined) {
+				const existing = await readFieldText(base, focused.ref, exec.signal);
+				if (existing) {
+					// No clean "clear" in `input`; select-all then delete is the portable route.
+					await runAdb([...base, 'shell', 'input', 'keyevent', 'KEYCODE_MOVE_END'], { signal: exec.signal, timeoutMs: 20000 });
+					for (let i = 0; i < Math.min(existing.length + 4, 200); i += 1) {
+						await runAdb([...base, 'shell', 'input', 'keyevent', 'KEYCODE_DEL'], { signal: exec.signal, timeoutMs: 20000 });
+					}
+				}
+			}
+			await runAdb([...base, 'shell', 'input', 'text', typed.replace(/ /g, '%s')], { signal: exec.signal, timeoutMs: 30000 });
+		} else {
+			// Non-ASCII or punctuation-heavy: inject via base64 so quoting and
+			// the shell's own escaping cannot corrupt the payload.
+			const b64 = Buffer.from(typed, 'utf8').toString('base64');
+			if (clear) await runAdb([...base, 'shell', 'input', 'keyevent', 'KEYCODE_MOVE_END'], { signal: exec.signal, timeoutMs: 20000 });
+			const cmd = clear
+				? 'echo ' + b64 + ' | base64 -d > /data/local/tmp/dsh_text.txt && input text "$(cat /data/local/tmp/dsh_text.txt)"; rm -f /data/local/tmp/dsh_text.txt'
+				: 'echo ' + b64 + ' | base64 -d >> /data/local/tmp/dsh_text.txt && input text "$(cat /data/local/tmp/dsh_text.txt)"; rm -f /data/local/tmp/dsh_text.txt';
+			await runAdb([...base, 'shell', cmd], { signal: exec.signal, timeoutMs: 30000 });
+		}
+
+		if (args.submit) await runAdb([...base, 'shell', 'input', 'keyevent', 'KEYCODE_ENTER'], { signal: exec.signal, timeoutMs: 20000 });
+
+		return {
+			device: base[1] ?? 'auto',
+			...(focused ? { field: focused } : {}),
+			cleared: clear,
+			characters: typed.length,
+			text: 'typed ' + typed.length + ' character(s) into ' + (focused ? JSON.stringify(focused) : 'the focused field') + (clear ? ' (field cleared first)' : '') + (args.submit ? ' and pressed Enter' : '') + '.'
+		};
+	}
+});
+
+const adbScroll = defineTool({
+	name: 'adb_scroll',
+	description: 'Scroll the screen or a scrollable element. Prefers the UI tree: give "selector" for the list to scroll (ref or id:/class~=RecyclerView), otherwise the largest scrollable node is used, otherwise a scroll runs at screen center. direction up/down move the content by one screen (down = look further down a list); "fraction" tunes the distance. After scrolling, call adb_ui_map again — refs change as new rows appear.',
+	parameters: {
+		type: 'object',
+		properties: {
+			direction: { type: 'string', enum: ['up', 'down', 'left', 'right'], description: 'Content movement direction.', required: true },
+			selector: selectorParam,
+			fraction: { type: 'number', description: 'Portion of the scrollable area to travel, 0-1 (default 0.8).' },
+			duration_ms: { type: 'integer', description: 'Gesture duration in ms (default 300).' },
+			device: deviceParam
+		},
+		required: ['direction']
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb scroll ' + args.direction };
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const fraction = Number.isFinite(Number(args.fraction)) ? Math.min(1, Math.max(0.05, Number(args.fraction))) : 0.8;
+		const duration = Number.isFinite(Number(args.duration_ms)) ? Math.max(50, Math.round(Number(args.duration_ms))) : 300;
+
+		const nodes = buildTree(await dumpUiXml(base, exec.signal));
+		let region;
+		let matched;
+		if (args.selector !== undefined && args.selector !== null && String(args.selector).length) {
+			const resolved = await resolveTarget(base, args.selector, { need: 'scrollable', signal: exec.signal });
+			matched = resolved.node;
+			region = resolved.node.bounds;
+		}
+		if (!region) {
+			const scrollable = firstScrollable(nodes);
+			if (scrollable?.bounds) {
+				region = scrollable.bounds;
+				matched = scrollable;
+			}
+		}
+		if (!region) {
+			const size = await screenSize(base, exec.signal);
+			if (!size) throw new Error('could not determine screen size to scroll; pass "selector" for a specific element.');
+			region = { x1: Math.round(size.width * 0.1), y1: Math.round(size.height * 0.15), x2: Math.round(size.width * 0.9), y2: Math.round(size.height * 0.85), cx: Math.round(size.width / 2), cy: Math.round(size.height / 2), w: Math.round(size.width * 0.8), h: Math.round(size.height * 0.7) };
+		}
+
+		const dx = Math.round((region.w / 2) * fraction);
+		const dy = Math.round((region.h / 2) * fraction);
+		const from = { x: region.cx, y: region.cy };
+		let to;
+		if (args.direction === 'down') to = { x: from.x, y: from.y - dy };
+		else if (args.direction === 'up') to = { x: from.x, y: from.y + dy };
+		else if (args.direction === 'right') to = { x: from.x - dx, y: from.y };
+		else to = { x: from.x + dx, y: from.y };
+
+		await runAdb([...base, 'shell', 'input', 'swipe', String(from.x), String(from.y), String(to.x), String(to.y), String(duration)], { signal: exec.signal, timeoutMs: 30000 });
+
+		return {
+			device: base[1] ?? 'auto',
+			direction: args.direction,
+			...(matched ? { scrolledElement: { ref: matched.ref, class: matched.shortClass, ...(matched.id ? { id: matched.id } : {}) } } : { scrolledElement: null }),
+			from: [from.x, from.y],
+			to: [to.x, to.y],
+			text: 'scrolled ' + args.direction + ' ' + Math.round(fraction * 100) + '% within ' + (matched ? 'element [' + matched.ref + '] ' + matched.shortClass : 'the screen') + '. Call adb_ui_map again to see the new rows.'
+		};
+	}
+});
+
+const adbWaitFor = defineTool({
+	name: 'adb_wait_for',
+	description: 'Wait until the UI tree reaches the expected state, polling the hierarchy instead of sleeping blindly. state "appear" (default) waits for a matching element, "disappear" waits for it to be gone, "change" waits until the tree differs from the current screen. Use it after a tap or app launch, then read the tree with adb_ui_map. Returns the matched element when it appears.',
+	parameters: {
+		type: 'object',
+		properties: {
+			selector: selectorParam,
+			state: { type: 'string', enum: ['appear', 'disappear', 'change'], description: 'Condition to wait for (default appear).' },
+			timeout_ms: { type: 'integer', description: 'Give up after this long (default 10000, max 120000).' },
+			interval_ms: { type: 'integer', description: 'Poll interval (default 700).' },
+			device: deviceParam
+		},
+		required: ['selector']
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb wait for ' + args.selector };
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const state = args.state || 'appear';
+		const timeoutMs = Math.min(120000, Number(args.timeout_ms) > 0 ? Number(args.timeout_ms) : 10000);
+		const intervalMs = Math.min(5000, Number(args.interval_ms) > 0 ? Number(args.interval_ms) : 700);
+		const sel = parseSelector(args.selector);
+		const deadline = Date.now() + timeoutMs;
+
+		const snapshotOf = (nodes) => nodes.filter(isMeaningful).map((n) => n.shortClass + '|' + n.text + '|' + n.desc + '|' + n.id).join('\n');
+		const firstNodes = buildTree(await dumpUiXml(base, exec.signal));
+		const baseline = snapshotOf(firstNodes);
+		const find = (nodes) => nodes.filter(isMeaningful).filter((n) => selectorMatches(n, sel));
+
+		if (state === 'appear') {
+			const already = find(firstNodes);
+			if (already.length) return { state, matched: true, elapsedMs: 0, element: describeNode(already[0]), text: 'already present: [' + already[0].ref + '] ' + describeNode(already[0]) };
+		} else if (state === 'disappear') {
+			if (!find(firstNodes).length) return { state, matched: true, elapsedMs: 0, text: 'already gone: nothing matches "' + args.selector + '"' };
+		}
+
+		let polls = 0;
+		while (Date.now() < deadline) {
+			await new Promise((r) => setTimeout(r, intervalMs));
+			if (exec.signal?.aborted) throw new Error('cancelled by the caller');
+			polls += 1;
+			let nodes;
+			try {
+				nodes = buildTree(await dumpUiXml(base, exec.signal));
+			} catch {
+				continue; // transient dump failure (animating/secure window) — keep polling
+			}
+			const elapsed = timeoutMs - Math.max(0, deadline - Date.now());
+
+			if (state === 'appear') {
+				const hits = find(nodes);
+				if (hits.length) {
+					return {
+						state, matched: true, elapsedMs: elapsed, polls,
+						element: serializeTree(nodes).find((n) => n.ref === hits[0].ref),
+						text: 'appeared after ' + elapsed + 'ms: [' + hits[0].ref + '] ' + describeNode(hits[0])
+					};
+				}
+			} else if (state === 'disappear') {
+				if (!find(nodes).length) return { state, matched: true, elapsedMs: elapsed, polls, text: 'disappeared after ' + elapsed + 'ms' };
+			} else if (snapshotOf(nodes) !== baseline) {
+				return { state: 'change', matched: true, elapsedMs: elapsed, polls, text: 'the UI tree changed after ' + elapsed + 'ms. Call adb_ui_map for the new refs.' };
+			}
+		}
+
+		return {
+			state, matched: false, polls, elapsedMs: timeoutMs,
+			text: 'timed out after ' + timeoutMs + 'ms waiting for "' + args.selector + '" to ' + state + '. Call adb_ui_map to inspect the actual screen (or adb_screenshot if the tree is unavailable).'
+		};
+	}
+});
+
+//#endregion
+
+//#region secondary tools — screenshot and raw access
+
+const adbScreenshot = defineTool({
+	name: 'adb_screenshot',
+	description: 'SECONDARY, fallback use only. Captures the screen to a PNG on this computer and returns its absolute path (view it with read_image). Prefer adb_ui_map: the tree gives exact elements and refs, while a screenshot costs an image read and still leaves you guessing coordinates. Reach for this when the hierarchy is empty or useless — games, video, canvas/WebView surfaces, the lock screen, custom-drawn UI — or to visually confirm a result that the tree cannot express.',
+	parameters: {
+		type: 'object',
+		properties: {
+			device: deviceParam,
+			out_path: { type: 'string', description: 'Absolute PNG path to write (default ~/dsh-adb-screenshots/adb-<timestamp>.png).' }
+		}
+	},
+	concurrencySafe: true,
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const png = (await runAdb([...base, 'exec-out', 'screencap', '-p'], { signal: exec.signal, timeoutMs: 30000, encoding: 'buffer', maxBuffer: 32 * 1024 * 1024 })).stdout;
+		if (!png?.length) throw new Error('screencap returned no image data');
+		const file = args.out_path || path.join(screenshotDir(), 'adb-' + Date.now() + '.png');
+		await mkdir(path.dirname(file), { recursive: true });
+		await writeFile(file, png);
+		let width;
+		let height;
+		if (png.length > 24 && png[0] === 0x89 && png[1] === 0x50) {
+			width = png.readUInt32BE(16);
+			height = png.readUInt32BE(20);
+		}
+		return { path: file, bytes: png.length, ...(width ? { width, height } : {}), text: 'saved ' + file + ' (' + png.length + ' bytes' + (width ? ', ' + width + 'x' + height : '') + '). Use read_image on this path to view it. This is the fallback channel — adb_ui_map is cheaper and gives clickable refs.' };
+	}
+});
+
+/** Physical screen size, cached per call chain; used when no scrollable node exists. */
+async function screenSize(base, signal) {
+	try {
+		const out = (await runAdb([...base, 'shell', 'wm', 'size'], { signal, timeoutMs: 10000 })).stdout;
+		const m = /(\d+)x(\d+)/.exec(out);
+		if (m) return { width: Number(m[1]), height: Number(m[2]) };
+	} catch { /* fall through */ }
+	return undefined;
+}
+
+const adbUiDump = defineTool({
+	name: 'adb_ui_dump',
+	description: 'Raw uiautomator XML of the current screen, unprocessed. Only needed when adb_ui_map is not enough — for example to inspect layout containers, view-id naming patterns, or attributes the compact tree omits. Prefer adb_ui_map for normal interaction.',
+	parameters: {
+		type: 'object',
+		properties: {
+			device: deviceParam,
+			include_hidden: { type: 'boolean', description: 'Also keep nodes with empty bounds (default false, which drops the invisible ones to save space).' }
+		}
+	},
+	concurrencySafe: true,
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const xml = (await dumpUiXml(base, exec.signal)).trim();
+		const out = args.include_hidden ? xml : xml.replace(/<node[^>]*bounds="\[\d+,\d+\]\[\d+,\d+\]"[^>]*\/>/g, (tag) => {
+			const bounds = parseBounds(readAttr(tag, 'bounds'));
+			return bounds && bounds.w > 0 && bounds.h > 0 ? tag : '';
+		});
+		return { device: base[1] ?? 'auto', bytes: out.length, text: clip(out, MAX_XML_OUTPUT) };
+	}
+});
+
+const adbInput = defineTool({
+	name: 'adb_input',
+	description: 'LOW-LEVEL raw input on coordinates, without consulting the UI tree: tap, long_press, swipe, text, key. Prefer adb_tap / adb_set_text / adb_scroll when the hierarchy is available, since they resolve real elements instead of guessed pixels. Use this for gestures the tree cannot express (pinch-like multi-step drags, precise swipes, coordinate work derived from a screenshot), and for key presses (home, back, recents, power, volume_up, enter, del, dpad_*, media_*) or raw KEYCODE numbers.',
+	parameters: {
+		type: 'object',
+		properties: {
+			action: { type: 'string', enum: ['tap', 'long_press', 'swipe', 'text', 'key'], description: 'Input operation.', required: true },
+			device: deviceParam,
+			x: { type: 'integer', description: 'X coordinate for tap/long_press/swipe (device pixels, origin top-left).' },
+			y: { type: 'integer', description: 'Y coordinate for tap/long_press/swipe.' },
+			x2: { type: 'integer', description: 'End X for swipe.' },
+			y2: { type: 'integer', description: 'End Y for swipe.' },
+			duration_ms: { type: 'integer', description: 'Duration in ms for long_press (default 800) or swipe (default 300).' },
+			text: { type: 'string', description: 'Text to type for action "text".' },
+			key: { type: 'string', description: 'Key name (see description) or raw KEYCODE for action "key".' }
+		},
+		required: ['action']
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const duration = Number.isFinite(Number(args.duration_ms)) ? Math.max(1, Math.round(Number(args.duration_ms))) : undefined;
+		let argv;
+		if (args.action === 'tap') {
+			argv = [...base, 'shell', 'input', 'tap', String(requireNumber(args.x, 'x')), String(requireNumber(args.y, 'y'))];
+		} else if (args.action === 'long_press') {
+			const ms = duration ?? 800;
+			const x = String(requireNumber(args.x, 'x'));
+			const y = String(requireNumber(args.y, 'y'));
+			argv = [...base, 'shell', 'input', 'swipe', x, y, x, y, String(ms)];
+		} else if (args.action === 'swipe') {
+			argv = [...base, 'shell', 'input', 'swipe', String(requireNumber(args.x, 'x')), String(requireNumber(args.y, 'y')), String(requireNumber(args.x2, 'x2')), String(requireNumber(args.y2, 'y2')), String(duration ?? 300)];
+		} else if (args.action === 'text') {
+			if (!args.text) throw new Error('action "text" requires "text"');
+			argv = [...base, 'shell', 'input', 'text', args.text.replace(/ /g, '%s')];
+		} else {
+			if (!args.key) throw new Error('action "key" requires "key"');
+			const code = /^\d+$/.test(args.key) ? args.key : KEYCODES[String(args.key).toLowerCase()];
+			if (!code) throw new Error('unknown key "' + args.key + '". Known names: ' + Object.keys(KEYCODES).join(', ') + ' (or pass a raw KEYCODE number).');
+			argv = [...base, 'shell', 'input', 'keyevent', String(code)];
+		}
+		await runAdb(argv, { signal: exec.signal, timeoutMs: 30000 });
+		return { action: args.action, device: base[1] ?? 'auto', text: args.action + ' sent' };
+	}
+});
+
+//#endregion
+
+//#region device, shell, files
+
+const adbDevices = defineTool({
+	name: 'adb_devices',
+	description: 'List Android devices visible to adb, including USB (wired) and wireless (ip:port) targets with their state and model. Call this first to learn usable device identifiers.',
+	parameters: {},
+	concurrencySafe: true,
+	async execute(_args, exec) {
+		const devices = parseDevices((await runAdb(['devices', '-l'], { signal: exec.signal })).stdout);
+		const saved = loadSettings().defaultDevice;
+		const text = devices.length
+			? devices.map((d) => d.serial + '  ' + d.state + '  ' + d.connection + (d.model ? '  ' + d.model : '')).join('\n')
+			: 'No devices found. Enable USB debugging, plug the phone in (accept the prompt on the phone), or use adb_connect for wireless.';
+		return {
+			devices: devices.map(({ serial, state, connection, model }) => ({ serial, state, connection, ...(model ? { model } : {}) })),
+			...(saved ? { defaultDevice: saved } : {}),
+			text
+		};
+	}
+});
+
+const adbConnect = defineTool({
+	name: 'adb_connect',
+	description: 'Manage wireless ADB. action "pair": pair with an Android 11+ device using the IP:port and 6-digit code shown under Developer options > Wireless debugging > Pair device with pairing code. action "connect": connect to a wireless target (ip:port). action "tcpip": make a USB-connected device listen on tcpip 5555 so you can then unplug and adb_connect to its IP. action "disconnect": drop a wireless target.',
+	parameters: {
+		type: 'object',
+		properties: {
+			action: { type: 'string', enum: ['pair', 'connect', 'tcpip', 'disconnect'], description: 'Wireless operation to perform.', required: true },
+			target: { type: 'string', description: 'IP:port for pair/connect/disconnect; USB serial for tcpip.', required: true },
+			port: { type: 'integer', description: 'For tcpip: the TCP port to enable on the device (default 5555).' },
+			pairing_code: { type: 'string', description: '6-digit pairing code, required for action "pair".' }
+		},
+		required: ['action', 'target']
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb ' + args.action + ' ' + args.target };
+	},
+	async execute(args, exec) {
+		const port = args.port && Number.isInteger(Number(args.port)) ? Number(args.port) : 5555;
+		let argv;
+		if (args.action === 'pair') {
+			if (!args.pairing_code) throw new Error('wireless pairing needs the 6-digit "pairing_code" shown on the phone (Developer options > Wireless debugging > Pair device with pairing code).');
+			argv = ['pair', args.target, String(args.pairing_code)];
+		} else if (args.action === 'connect') {
+			argv = ['connect', args.target];
+		} else if (args.action === 'disconnect') {
+			argv = ['disconnect', args.target];
+		} else {
+			argv = ['-s', args.target, 'tcpip', String(port)];
+		}
+		const { stdout, stderr } = await runAdb(argv, { signal: exec.signal, timeoutMs: 20000 });
+		const output = (stdout + stderr).trim() || 'done';
+		return { action: args.action, target: args.target, ok: !/failed|cannot|unable/i.test(output), text: output };
+	}
+});
+
+const adbShell = defineTool({
+	name: 'adb_shell',
+	description: 'Run a shell command on the Android device (for example: dumpsys battery, pm list packages, logcat -d -t 200, getprop, am start -a android.intent.action.VIEW -d https://example.com, wm size). stdout and stderr are returned.',
+	parameters: {
+		type: 'object',
+		properties: {
+			command: { type: 'string', description: 'Shell command line to run on the device.', required: true },
+			device: deviceParam,
+			timeout_ms: { type: 'integer', description: 'Timeout in ms (default 30000, max 600000).' }
+		},
+		required: ['command']
+	},
+	presentCall(args) {
+		return { card: 'terminal', title: 'adb shell', description: args.command };
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const timeoutMs = Math.min(600000, Number(args.timeout_ms) > 0 ? Number(args.timeout_ms) : 30000);
+		const { stdout, stderr } = await runAdb([...base, 'shell', args.command], { signal: exec.signal, timeoutMs });
+		const output = clip((stdout + (stdout && stderr ? '\n' : '') + stderr).trim(), MAX_TEXT_OUTPUT);
+		return { device: base[1] ?? 'auto', ok: true, text: output || '(no output)' };
+	}
+});
+
+const adbFiles = defineTool({
+	name: 'adb_files',
+	description: 'Transfer files between this computer and the Android device. action "push" copies local_path to remote_path on the device; action "pull" copies remote_path from the device to local_path.',
+	parameters: {
+		type: 'object',
+		properties: {
+			action: { type: 'string', enum: ['push', 'pull'], description: 'Transfer direction.', required: true },
+			local_path: { type: 'string', description: 'Absolute path on this computer.', required: true },
+			remote_path: { type: 'string', description: 'Path on the device (e.g. /sdcard/Download/file.mp4).', required: true },
+			device: deviceParam
+		},
+		required: ['action', 'local_path', 'remote_path']
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const argv = args.action === 'push' ? [...base, 'push', args.local_path, args.remote_path] : [...base, 'pull', args.remote_path, args.local_path];
+		const { stdout, stderr } = await runAdb(argv, { signal: exec.signal, timeoutMs: 300000 });
+		return { action: args.action, text: (stdout + stderr).trim() || 'done' };
+	}
+});
+
+const adbInstall = defineTool({
+	name: 'adb_install',
+	description: 'Install an APK file from this computer onto the Android device. keep_data keeps existing app data on reinstall (default true). downgrade allows installing an older version over a newer one.',
+	parameters: {
+		type: 'object',
+		properties: {
+			apk_path: { type: 'string', description: 'Absolute path to the .apk on this computer.', required: true },
+			device: deviceParam,
+			keep_data: { type: 'boolean', description: 'Reinstall while keeping app data (-r, default true).' },
+			downgrade: { type: 'boolean', description: 'Allow version downgrade (-d).' }
+		},
+		required: ['apk_path']
+	},
+	async execute(args, exec) {
+		const base = await deviceArgs(args.device);
+		const flags = [];
+		if (args.keep_data !== false) flags.push('-r');
+		if (args.downgrade) flags.push('-d');
+		const { stdout, stderr } = await runAdb([...base, 'install', ...flags, args.apk_path], { signal: exec.signal, timeoutMs: 300000 });
+		const output = (stdout + stderr).trim();
+		return { ok: /success/i.test(output), text: output || 'done' };
+	}
+});
+
+const adbConfigure = defineTool({
+	name: 'adb_configure',
+	description: "Show or change this plugin's persistent settings: adb_path (adb binary when not on PATH), default_device (serial or ip:port used when a tool call omits \"device\"), screenshot_dir. Omitted fields keep their values.",
+	parameters: {
+		type: 'object',
+		properties: {
+			adb_path: { type: 'string', description: 'Absolute path or command name of the adb binary.' },
+			default_device: { type: 'string', description: 'Default device serial / ip:port for subsequent calls.' },
+			screenshot_dir: { type: 'string', description: 'Directory for adb_screenshot output.' },
+			clear_default_device: { type: 'boolean', description: 'Remove the saved default device.' }
+		}
+	},
+	async execute(args) {
+		const patch = {};
+		if (args.adb_path) patch.adbPath = args.adb_path;
+		if (args.clear_default_device) patch.defaultDevice = undefined;
+		else if (args.default_device) patch.defaultDevice = args.default_device;
+		if (args.screenshot_dir) patch.screenshotDir = args.screenshot_dir;
+		const settings = Object.keys(patch).length ? saveSettings(patch) : loadSettings();
+		const shown = { adbPath: settings.adbPath || null, defaultDevice: settings.defaultDevice || null, screenshotDir: screenshotDir() };
+		return { settingsPath: SETTINGS_PATH, ...shown, text: 'settings at ' + SETTINGS_PATH + ': ' + JSON.stringify(shown) };
+	}
+});
+
+//#endregion
+
+/**
+ * Register every ADB tool. The UI-tree tools are registered first so the
+ * hierarchy-first flow is the obvious one; screenshot and raw input stay
+ * available as secondary channels.
+ * @param ctx - the plugin context.
+ */
+export function apply(ctx) {
+	for (const tool of [
+		adbUiMap, adbTap, adbSetText, adbScroll, adbWaitFor,
+		adbDevices, adbConnect, adbInput, adbShell, adbScreenshot, adbUiDump,
+		adbFiles, adbInstall, adbConfigure
+	]) {
+		ctx.effect(() => ctx.tools.register(tool));
+	}
+}
+
+export const inject = ['tools'];
+export const name = PLUGIN;

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ADB Phone Control",
+    "description": "Control Android phones with UI tree as primary, screenshot as fallback. adb_ui_map reads an indexed element tree (ref, class, id, text, desc, flags, center coords); adb_tap/adb_set_text/adb_scroll/adb_wait_for act by ref. Screenshots are only for game surfaces, WebViews, lock screens, and verification. Also: adb_devices, adb_connect, adb_input, adb_shell, adb_ui_dump, adb_files, adb_install, adb_configure."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ADB 手机控制",
+    "description": "以界面树为主、截图为辅控制安卓手机。adb_ui_map 读取索引化元素树（ref、类、id、文本、描述、标志、中心坐标），adb_tap/adb_set_text/adb_scroll/adb_wait_for 用 ref 精准操作。截图仅作游戏、WebView、锁屏等无树场面的兜底/验证。另有 adb_devices/adb_connect/adb_input/adb_shell/adb_ui_dump/adb_files/adb_install/adb_configure。"
+  }
+}

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@ppppaaaaa/adb-control",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Control Android phones over wired or wireless ADB from the agent. UI tree first, screenshot secondary.",
+  "version": "2.0.0",
+  
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": ["index.js", "cordis.patch.yml", "locale/*.json", "icon.svg"],
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.