dsh-adb 1.2.0 → 1.3.0

package/README.md

@@ -40,6 +40,7 @@ Topics: `dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_perf_baseline` | Perf regression: save a snapshot as a baseline (label/tags), compare current state and get a numeric diff (PSS, janky %, percentiles), list/delete baselines (stored locally under `baselineDir`) |
 | `adb_crash_report` | One-call crash scene: parsed logcat crash buffer + dropbox excerpt + process state + memory summary |
 | `adb_device_report` | One-click health report: device identity + top-RSS processes + crash buffer (real crashes w/ stacks vs. boot markers) + W/E/F logcat aggregated by tag + storage + health verdict; each section degrades independently; persisted under `reportDir` |
+| `adb_wait_for` | Wait until a device condition holds — device-online / boot-complete / process appeared / logcat keyword — polling up to a budget, instead of sleeping a fixed number of seconds; returns `matched:false` on timeout |
 
 Errors are structured `AdbError` with stable codes: `ADB_NOT_FOUND`, `ADB_UNAVAILABLE`, `DEVICE_NOT_FOUND`, `NO_DEVICES`, `CONNECT_FAILED`, `INSTALL_FAILED`, `ADB_EXIT_<code>`, etc.
 

package/README.zh-CN.md

@@ -40,6 +40,7 @@ Topics：`dsh-plugin` `dsh` `adb` `android` `automotive` `bench`
 | `adb_perf_baseline` | 性能回归：快照存基线（label/tags）、与当前状态数值对比（PSS/卡顿率/百分位）、list/delete（本地存储，`baselineDir`） |
 | `adb_crash_report` | 崩溃现场一键采集：crash buffer 解析 + dropbox 摘录 + 进程状态 + 内存摘要 |
 | `adb_device_report` | 一键体检：设备信息 + Top RSS 进程 + 崩溃缓冲（真实崩溃带堆栈/启动标记分类）+ W/E/F 日志按 tag 聚合 + 存储用量 + 健康结论；每节独立降级；落盘到 `reportDir` |
+| `adb_wait_for` | 等待原语：等设备上线 / 启动完成 / 进程出现 / logcat 出现关键字，轮询到预算上限，替代盲目 sleep；超时返回 `matched:false` |
 
 错误码：`ADB_NOT_FOUND`、`ADB_UNAVAILABLE`、`DEVICE_NOT_FOUND`、`NO_DEVICES`、`CONNECT_FAILED`、`INSTALL_FAILED`、`ADB_EXIT_<code>` 等，均为结构化 `AdbError`。
 

package/lib/index.js

@@ -8,6 +8,7 @@ import { registerInstallTool } from './tools/install.js';
 import { registerLogcatTool } from './tools/logcat.js';
 import { registerPerfTool } from './tools/perf.js';
 import { registerPerfBaselineTool } from './tools/perf-baseline.js';
+import { registerWaitTool } from './tools/wait.js';
 import { registerRpc } from './rpc.js';
 import { registerSkills } from './skill.js';
 export const name = 'dsh-adb';
@@ -31,10 +32,11 @@ export function apply(ctx, config) {
     registerPerfBaselineTool(ctx, cfg, config.baselineDir ?? DEFAULT_BASELINE_DIR);
     registerCrashReportTool(ctx, cfg);
     registerDeviceReportTool(ctx, cfg, reportDir);
+    registerWaitTool(ctx, cfg);
     registerSkills(ctx);
     // The RPC channel needs the client connection, which mounts after this
     // plugin starts in web compositions; register lazily so headless profiles
     // (no connection) stay unaffected.
     ctx.inject(['connection'], (readyCtx) => registerRpc(readyCtx, cfg, reportDir));
-    ctx.logger.info('[dsh-adb] loaded: 10 tools + web device panel rpc');
+    ctx.logger.info('[dsh-adb] loaded: 11 tools + web device panel rpc');
 }

package/lib/tools/wait.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type AdbConfig } from '../adb.js';
+import { type AdbDevice } from '../parsers/devices.js';
+import { type LogcatEntry } from '../parsers/logcat.js';
+import { type ProcessEntry } from '../parsers/sysinfo.js';
+/**
+ * adb_wait_for: wait until a device reaches a condition, instead of sleeping a
+ * fixed number of seconds. Conditions: device-online, boot-complete, process
+ * (a process appears), logcat-pattern (a keyword appears). Polls at
+ * `intervalMs` until `timeoutMs`, then returns `matched: false` (not an error)
+ * so the agent can react to the timeout instead of guessing.
+ */
+export type WaitCondition = 'device-online' | 'boot-complete' | 'process' | 'logcat-pattern';
+export interface WaitArgs {
+    serial?: string;
+    condition: WaitCondition;
+    /** Substring matched against process names (condition=process) or logcat tag/message (condition=logcat-pattern). */
+    pattern?: string;
+    /** Overall wait budget in milliseconds; defaults to 30000, capped at 300000. */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds; defaults to 1000. */
+    intervalMs?: number;
+}
+export interface WaitResult {
+    condition: WaitCondition;
+    matched: boolean;
+    waitedMs: number;
+    attempts: number;
+    reason?: string;
+}
+/** device-online: the serial is present in `adb devices -l` with state `device`. */
+export declare function checkDeviceOnline(devices: AdbDevice[], serial?: string): boolean;
+/** boot-complete: `getprop sys.boot_completed` output is exactly "1". */
+export declare function checkBootComplete(getpropOut: string): boolean;
+/** process: any process name contains the pattern. */
+export declare function checkProcessPresent(processes: ProcessEntry[], pattern: string): boolean;
+/** logcat-pattern: any entry's tag or message contains the keyword. */
+export declare function checkLogcatKeyword(entries: LogcatEntry[], keyword: string): boolean;
+/** Wait until the condition holds or the budget expires (returns matched:false on timeout). */
+export declare function waitForCondition(ctx: Context, cfg: AdbConfig, signal: AbortSignal, args: WaitArgs): Promise<WaitResult>;
+/** adb_wait_for: wait until a device condition holds (online / boot complete / process / logcat keyword). */
+export declare function registerWaitTool(ctx: Context, cfg: AdbConfig): void;

package/lib/tools/wait.js

@@ -0,0 +1,144 @@
+import { classifyFailure, jsonOutput, runAdb } from '../adb.js';
+import { parseDevices } from '../parsers/devices.js';
+import { parseLogcat } from '../parsers/logcat.js';
+import { parseProcessList } from '../parsers/sysinfo.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 300_000;
+const DEFAULT_INTERVAL_MS = 1_000;
+// ---- Pure condition checks (unit-tested) ----
+/** device-online: the serial is present in `adb devices -l` with state `device`. */
+export function checkDeviceOnline(devices, serial) {
+    return devices.some((device) => {
+        if (serial !== undefined && device.serial !== serial)
+            return false;
+        return device.state === 'device';
+    });
+}
+/** boot-complete: `getprop sys.boot_completed` output is exactly "1". */
+export function checkBootComplete(getpropOut) {
+    return getpropOut.trim() === '1';
+}
+/** process: any process name contains the pattern. */
+export function checkProcessPresent(processes, pattern) {
+    return processes.some((entry) => entry.name.includes(pattern));
+}
+/** logcat-pattern: any entry's tag or message contains the keyword. */
+export function checkLogcatKeyword(entries, keyword) {
+    return entries.some((entry) => entry.tag.includes(keyword) || entry.message.includes(keyword));
+}
+// ---- Poll loop ----
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('tool call aborted'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new Error('tool call aborted'));
+        }, { once: true });
+    });
+}
+/** Run one adb probe for the condition; returns true when satisfied. */
+async function probe(ctx, cfg, args, signal) {
+    const serial = args.serial;
+    switch (args.condition) {
+        case 'device-online': {
+            const result = await runAdb(ctx, cfg, ['devices', '-l'], { signal, maxBytes: 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkDeviceOnline(parseDevices(result.stdout), args.serial);
+        }
+        case 'boot-complete': {
+            const result = await runAdb(ctx, cfg, ['shell', 'getprop', 'sys.boot_completed'], { signal, serial });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkBootComplete(result.stdout);
+        }
+        case 'process': {
+            const result = await runAdb(ctx, cfg, ['shell', 'ps', '-A'], { signal, serial, maxBytes: 2 * 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkProcessPresent(parseProcessList(result.stdout), args.pattern);
+        }
+        case 'logcat-pattern': {
+            const result = await runAdb(ctx, cfg, ['logcat', '-v', 'threadtime', '-d'], { signal, serial, maxBytes: 8 * 1024 * 1024 });
+            if (result.exitCode !== 0)
+                throw classifyFailure(result);
+            return checkLogcatKeyword(parseLogcat(result.stdout), args.pattern);
+        }
+        default:
+            throw new Error(`unknown condition: ${String(args.condition)}`);
+    }
+}
+/** Validate args that fail fast — before the poll loop so they surface as errors, not timeouts. */
+function validateArgs(args) {
+    if (!['device-online', 'boot-complete', 'process', 'logcat-pattern'].includes(args.condition)) {
+        throw new Error(`unknown condition: ${String(args.condition)}`);
+    }
+    if ((args.condition === 'process' || args.condition === 'logcat-pattern') && (args.pattern === undefined || args.pattern === '')) {
+        throw new Error(`condition "${args.condition}" requires a non-empty "pattern"`);
+    }
+}
+/** Wait until the condition holds or the budget expires (returns matched:false on timeout). */
+export async function waitForCondition(ctx, cfg, signal, args) {
+    validateArgs(args);
+    const timeoutMs = Math.min(Math.floor(args.timeoutMs ?? DEFAULT_TIMEOUT_MS), MAX_TIMEOUT_MS);
+    const intervalMs = Math.max(Math.floor(args.intervalMs ?? DEFAULT_INTERVAL_MS), 250);
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    let attempts = 0;
+    let lastProbe;
+    while (true) {
+        attempts++;
+        try {
+            const satisfied = await probe(ctx, cfg, args, signal);
+            if (satisfied) {
+                return { condition: args.condition, matched: true, waitedMs: Date.now() - start, attempts };
+            }
+        }
+        catch (error) {
+            // A transient probe failure (device offline mid-wait) is not terminal:
+            // keep polling until the budget, but record the reason.
+            lastProbe = error instanceof Error ? error.message : String(error);
+        }
+        if (Date.now() >= deadline) {
+            return {
+                condition: args.condition,
+                matched: false,
+                waitedMs: timeoutMs,
+                attempts,
+                ...(lastProbe !== undefined ? { reason: lastProbe } : { reason: `condition not met within ${timeoutMs}ms` }),
+            };
+        }
+        await sleep(Math.min(intervalMs, deadline - Date.now()), signal);
+    }
+}
+/** adb_wait_for: wait until a device condition holds (online / boot complete / process / logcat keyword). */
+export function registerWaitTool(ctx, cfg) {
+    ctx.tools.register({
+        name: 'adb_wait_for',
+        description: 'Wait until a device reaches a condition, then return — instead of sleeping a fixed number of seconds. Conditions: device-online (device is in `adb devices` with state `device`), boot-complete (sys.boot_completed=1), process (a process whose name contains `pattern` appears in ps), logcat-pattern (a keyword appears in logcat tag/message). Polls every `intervalMs` up to `timeoutMs`; on timeout returns matched:false (not an error) so you can react. Use it to sequence multi-step device flows: install → wait for process → snapshot.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['condition'],
+            properties: {
+                condition: {
+                    type: 'string',
+                    enum: ['device-online', 'boot-complete', 'process', 'logcat-pattern'],
+                    description: 'Which condition to wait for.',
+                },
+                serial: { type: 'string', description: 'Target device serial; defaults to the plugin defaultSerial. For device-online, omit serial to wait for ANY device to come online.' },
+                pattern: { type: 'string', description: 'Required for process (process-name substring) and logcat-pattern (keyword).' },
+                timeoutMs: { type: 'integer', description: 'Overall wait budget in milliseconds; defaults to 30000, capped at 300000.' },
+                intervalMs: { type: 'integer', description: 'Poll interval in milliseconds; defaults to 1000, minimum 250.' },
+            },
+        },
+        output: jsonOutput(),
+        async execute(args, exec) {
+            return waitForCondition(ctx, cfg, exec.signal, args);
+        },
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-adb",
-  "version": "1.2.0",
-  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, web device panel (autocomplete, live logcat, profiler)",
+  "version": "1.3.0",
+  "description": "ADB device & bench operations for DeepSeek Harness: device discovery, structured logcat, apk install, file pull/push, performance snapshots, perf baselines, crash reports, one-click device health reports, condition waits, web device panel (autocomplete, live logcat, profiler)",
   "type": "module",
   "main": "lib/index.js",
   "exports": {