Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(adb): evaluate the full activity start report
morlutoc89972c8777d
diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsindex 7113d49bf..b9af6d14f 100644--- a/src/adb/AdbProvider.ts+++ b/src/adb/AdbProvider.ts@@ -23,9 +23,11 @@ import {type AnalysisExecution,} from "../application/AnalysisProvider.js";import type {+ AdbActivityStartPartialObservation,AdbAcquiredFilePartialObservation,AdbRequest,} from "../domain/adb/adbDeviceAnalysis.js";+import { adbResultSchemas } from "../domain/adb/adbDeviceAnalysis.js";import {AnalysisArtifactChangedError,AnalysisCancelledError,@@ -1985,28 +1987,55 @@ export class AdbProvider {signal,);if (!started.ok) return started;- const verdict = parseAmStartOutput(started.value.stdout);- if (verdict.status === "refused")+ const verdict = parseAmStartOutput(+ started.value.stdout,+ started.value.stderr,+ );+ const result = {+ ...resultFields,+ started_activity: verdict.startedActivity,+ reported_activity: verdict.activity,+ reported_status: verdict.reportedStatus,+ };+ if (verdict.status === "refused") {+ const partialObservation: AdbActivityStartPartialObservation =+ operation === "start_adb_app"+ ? {+ provider_id: "adb",+ operation,+ result: adbResultSchemas.start_adb_app.parse(result),+ }+ : {+ provider_id: "adb",+ operation,+ result: adbResultSchemas.start_adb_activity.parse(result),+ };return err(new AnalysisUnsupportedTargetError(operation,serial,verdict.reason ?? "am start refused the intent",+ {+ capturedOutput: {+ stdout: started.value.stdout,+ stderr: started.value.stderr,+ truncated: false,+ },+ partialObservation,+ },),);+ }return ok(- createAnalysisExecution(- {- ...resultFields,- started_activity: verdict.startedActivity,- },- provider,- {- limitations: [- "Starting an activity changes device state; am start -W waits for launch completion but no lifecycle observation is captured",- ],+ createAnalysisExecution(result, provider, {+ rawResult: {+ stdout: started.value.stdout,+ stderr: started.value.stderr,},- ) as AnalysisExecution,+ limitations: [+ "Starting an activity changes device state; am start -W waits for launch completion but no lifecycle observation is captured",+ ],+ }) as AnalysisExecution,);}diff --git a/src/adb/AdbShellOutput.test.ts b/src/adb/AdbShellOutput.test.tsnew file mode 100644index 000000000..1b9ad1f0b--- /dev/null+++ b/src/adb/AdbShellOutput.test.ts@@ -0,0 +1,75 @@+import { describe, expect, it } from "vitest";++import { parseAmStartOutput } from "./AdbShellOutput.js";++const starting =+ "Starting: Intent { act=android.intent.action.MAIN cmp=com.example/.Main }";++describe("parseAmStartOutput", () => {+ it("recognizes a CRLF wait-timeout report", () => {+ expect(+ parseAmStartOutput(+ `${starting}\r\nStatus: timeout\r\nActivity: com.example/.Main\r\nComplete\r\n`,+ ),+ ).toMatchObject({+ status: "refused",+ activity: "com.example/.Main",+ reportedStatus: "timeout",+ reason: "am start reported status: timeout",+ });+ });++ it("treats every non-ok status as refusal, including a later status after ok", () => {+ expect(+ parseAmStartOutput(`${starting}\nStatus: ok\nStatus: timeout\n`),+ ).toMatchObject({+ status: "refused",+ reportedStatus: "timeout",+ reason: "am start reported status: timeout",+ });+ expect(+ parseAmStartOutput(`${starting}\nStatus: future-value\n`),+ ).toMatchObject({+ status: "refused",+ reportedStatus: "future-value",+ });+ });++ it("gives hard errors in either stream priority over status and attempt", () => {+ expect(+ parseAmStartOutput(+ `${starting}\nStatus: timeout\nActivity: com.example/.Main\n`,+ "Exception: Activity class does not exist\n",+ ),+ ).toEqual({+ status: "refused",+ startedActivity: "act=android.intent.action.MAIN cmp=com.example/.Main",+ activity: "com.example/.Main",+ reportedStatus: "timeout",+ reason: "Activity class does not exist",+ });+ expect(+ parseAmStartOutput(+ `${starting}\nStatus: ok\nError: Activity class does not exist\n`,+ ),+ ).toMatchObject({+ status: "refused",+ reason: "Activity class does not exist",+ });+ });++ it("keeps Starting-only output compatible and refuses no-attempt output", () => {+ expect(parseAmStartOutput(starting)).toMatchObject({+ status: "started",+ reportedStatus: null,+ activity: null,+ });+ expect(+ parseAmStartOutput("Status: ok\nWarning: Activity not started\n"),+ ).toMatchObject({+ status: "refused",+ startedActivity: null,+ reportedStatus: "ok",+ });+ });+});diff --git a/src/adb/AdbShellOutput.ts b/src/adb/AdbShellOutput.tsindex 97720366f..f3323e7b2 100644--- a/src/adb/AdbShellOutput.ts+++ b/src/adb/AdbShellOutput.ts@@ -320,32 +320,80 @@ export const parseResolveActivityOutput = (stdout: string): string | null => {return lines.length === 0 ? null : lines[lines.length - 1]!;};+/** Parsed facts and verdict from the full `am start -W` report. */+export interface AmStartOutput {+ readonly status: "started" | "refused";+ readonly startedActivity: string | null;+ readonly activity: string | null;+ readonly reportedStatus: string | null;+ readonly reason: string | null;+}+/**- * Parse `am start` output. Success prints `Starting: Intent { ... }`;- * refusals print lines starting with `Error:` or `Warning:` and activity- * classes that do not exist name the component.+ * Parse the complete `am start -W` report. `Starting:` records an attempt;+ * hard errors and any non-ok Activity Manager status determine the verdict.*/export const parseAmStartOutput = (stdout: string,-): {- readonly status: "started" | "refused";- readonly startedActivity: string | null;- readonly reason: string | null;-} => {- const text = stdout.trim();- const starting = /^Starting:\s+Intent\s*\{(.*)\}\s*$/mu.exec(text);- if (starting !== null)+ stderr = "",+): AmStartOutput => {+ const normalizedStdout = stdout.replaceAll("\r\n", "\n");+ const starting = /^Starting:[ \t]+Intent[ \t]*\{(.*)\}[ \t]*$/mu.exec(+ normalizedStdout,+ );+ const startedActivity = starting?.[1]?.trim() ?? null;+ const activityMatch = /^Activity:[ \t]*(.*)$/mu.exec(normalizedStdout);+ const activity = activityMatch?.[1]?.trim() || null;+ const statuses = [...normalizedStdout.matchAll(/^Status:[ \t]*(.*)$/gmu)].map(+ (match) => match[1]!.trim(),+ );+ const nonOkStatus = statuses.find((status) => status.toLowerCase() !== "ok");+ const reportedStatus = nonOkStatus ?? statuses[0] ?? null;+ const error = [normalizedStdout, stderr.replaceAll("\r\n", "\n")]+ .flatMap((stream) => stream.split("\n"))+ .map((line) => line.trim())+ .map((line) => ({+ line,+ match: /^(?:Error|Exception)(?::|\b)(.*)$/iu.exec(line),+ }))+ .find(({ match }) => match !== null);+ const errorReason = error?.match?.[1]?.trim() || error?.line || null;+ const statusReason =+ nonOkStatus === ""+ ? "am start reported an empty status"+ : nonOkStatus === undefined+ ? null+ : `am start reported status: ${nonOkStatus}`;+ const reason =+ errorReason ??+ statusReason ??+ (/^Warning:/mu.test(normalizedStdout.trim())+ ? normalizedStdout.trim().slice(0, 512)+ : null);+ if (errorReason !== null || nonOkStatus !== undefined)+ return {+ status: "refused",+ startedActivity,+ activity,+ reportedStatus,+ reason: reason ?? "am start did not report a successful launch",+ };+ if (startedActivity !== null)return {status: "started",- startedActivity: starting[1]!.trim(),+ startedActivity,+ activity,+ reportedStatus,reason: null,};- const error = /^(?:Error|Warning|Exception)(?::|\b)(.*)$/mu.exec(text);+ const text = `${normalizedStdout}\n${stderr.replaceAll("\r\n", "\n")}`.trim();return {status: "refused",- startedActivity: null,+ startedActivity,+ activity,+ reportedStatus,reason:- error?.[1]?.trim() ??+ reason ??(text === "" ? "am start returned no activity" : text.slice(0, 512)),};};diff --git a/src/contracts/adb/adbToolContracts.ts b/src/contracts/adb/adbToolContracts.tsindex 0ebd39790..b121c8846 100644--- a/src/contracts/adb/adbToolContracts.ts+++ b/src/contracts/adb/adbToolContracts.ts@@ -326,7 +326,7 @@ export const ADB_TOOL_CONTRACTS = [name: "start_adb_app",...toolContractMetadata("start_adb_app"),description:- "Start one installed app by launching its declared launcher activity: the component is resolved through `cmd package resolve-activity --brief`, then started with `am start -n`. A device-mutating tool for dynamic-analysis workflows; pair with `read_adb_logcat` (pid filter) and `list_adb_processes` to observe the started app, and `stop_adb_app` to end the run.",+ "Start one installed app's resolved launcher activity with `am start -W -n`. A device-mutating tool for dynamic analysis. The full wait report determines success; failures retain launch-attempt facts and raw output. Pair with `read_adb_logcat` (pid filter) and `list_adb_processes` to observe the app, and `stop_adb_app` to end the run.",kind: "adb-provider",inputSchema: adbInputSchemas.start_adb_app,outputSchema: evidenceResultOf(adbResultSchemas.start_adb_app),@@ -341,7 +341,7 @@ export const ADB_TOOL_CONTRACTS = [name: "start_adb_activity",...toolContractMetadata("start_adb_activity"),description:- "Start an intent with `am start`: one action, optional data URI, optional explicit component, and up to 16 typed extras (string, boolean, int, long, float). A device-mutating tool; the activity manager's Starting/Error verdict is preserved verbatim.",+ "Start an intent with `am start -W`: one action, optional data URI, optional explicit component, and up to 16 typed extras (string, boolean, int, long, float). A device-mutating tool; the full wait report determines success, with failed-attempt facts and raw output retained.",kind: "adb-provider",inputSchema: adbInputSchemas.start_adb_activity,outputSchema: evidenceResultOf(adbResultSchemas.start_adb_activity),diff --git a/src/domain/adb/adbDeviceAnalysis.ts b/src/domain/adb/adbDeviceAnalysis.tsindex 11198df5e..17cdc223e 100644--- a/src/domain/adb/adbDeviceAnalysis.ts+++ b/src/domain/adb/adbDeviceAnalysis.ts@@ -679,6 +679,8 @@ export const adbResultSchemas = {package_name: packageNameSchema,component: z.string().min(1),started_activity: z.string().nullable(),+ reported_activity: z.string().nullable().optional(),+ reported_status: z.string().nullable().optional(),}),start_adb_activity: z.strictObject({client,@@ -694,6 +696,8 @@ export const adbResultSchemas = {}),),started_activity: z.string().nullable(),+ reported_activity: z.string().nullable().optional(),+ reported_status: z.string().nullable().optional(),}),stop_adb_app: z.strictObject({client,@@ -702,6 +706,19 @@ export const adbResultSchemas = {}),} as const;+/** Launch-attempt facts retained when Activity Manager does not report success. */+export type AdbActivityStartPartialObservation =+ | {+ readonly provider_id: "adb";+ readonly operation: "start_adb_app";+ readonly result: z.infer<typeof adbResultSchemas.start_adb_app>;+ }+ | {+ readonly provider_id: "adb";+ readonly operation: "start_adb_activity";+ readonly result: z.infer<typeof adbResultSchemas.start_adb_activity>;+ };+/** Acquired package facts retained when cancellation leaves caller-owned output. */export type AdbPackagePullPartialObservation = {readonly provider_id: "adb";diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.tsindex 43f39f627..60c3c0472 100644--- a/src/domain/analysisErrorBase.ts+++ b/src/domain/analysisErrorBase.ts@@ -114,6 +114,7 @@ import type { Evidence } from "./evidence.js";import type { AndroidPartialObservation } from "./android/androidPartialObservation.js";import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js";import type {+ AdbActivityStartPartialObservation,AdbAcquiredFilePartialObservation,AdbPackagePullPartialObservation,} from "./adb/adbDeviceAnalysis.js";@@ -143,5 +144,6 @@ export type AnalysisPartialObservation =| AndroidPartialObservation| FirmwarePartialObservation| NativeUiObservationResult+ | AdbActivityStartPartialObservation| AdbAcquiredFilePartialObservation| AdbPackagePullPartialObservation;diff --git a/tests/boundary/mcp/adbStartMcp.test.ts b/tests/boundary/mcp/adbStartMcp.test.tsnew file mode 100644index 000000000..702a6360d--- /dev/null+++ b/tests/boundary/mcp/adbStartMcp.test.ts@@ -0,0 +1,189 @@+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { chmod, readFile, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect, it, onTestFinished } from "vitest";++import { AdbProvider } from "../../../src/adb/AdbProvider.js";+import { analysisErrorProjectionSchema } from "../../../src/contracts/errorSchemas.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++const responseText = (response: { readonly content: readonly unknown[] }) =>+ response.content+ .flatMap((part) =>+ typeof part === "object" &&+ part !== null &&+ "text" in part &&+ typeof part.text === "string"+ ? [part.text]+ : [],+ )+ .join("");++const createFakeAdb = async () => {+ const directory = await createTestTempDirectory("rea-adb-start-mcp-");+ const binary = join(directory, "adb");+ const stdoutFile = join(directory, "stdout");+ const stderrFile = join(directory, "stderr");+ const callsFile = join(directory, "calls");+ const fakeAdbSource = `#!/usr/bin/env node+const fs = require("node:fs");+const [stdoutPath, stderrPath, callsPath] = ${JSON.stringify([stdoutFile, stderrFile, callsFile])};+const args = process.argv.slice(2);+fs.appendFileSync(callsPath, args.join(" ") + "\\n");+if (args[0] === "version") {+ process.stdout.write("Android Debug Bridge version 1.0.41\\nVersion 34.0.5-stub\\n");+} else if (args.includes("resolve-activity")) {+ process.stdout.write("com.example/.Main\\n");+} else {+ process.stdout.write(fs.readFileSync(stdoutPath, "utf8"));+ process.stderr.write(fs.readFileSync(stderrPath, "utf8"));+}+`;+ await writeFile(binary, fakeAdbSource);+ await chmod(binary, 0o755);+ return {+ binary,+ calls: async () => (await readFile(callsFile, "utf8")).trim().split("\n"),+ setReport: async (stdout: string, stderr: string) => {+ await writeFile(stdoutFile, stdout);+ await writeFile(stderrFile, stderr);+ },+ };+};++it+ .skipIf(process.platform === "win32")+ .each(["start_adb_app", "start_adb_activity"] as const)(+ "%s preserves successful reports and failed launch attempts through MCP (ADB process output simulated)",+ async (operation) => {+ const fakeAdb = await createFakeAdb();+ const { binary } = fakeAdb;+ const starting =+ "Starting: Intent { act=android.intent.action.MAIN cmp=com.example/.Main }\n";+ let stdout = `${starting}Warning: Activity not started, intent has been delivered to currently running top-most instance.\nStatus: ok\nActivity: com.example/.Main\nWaitTime: 315\nComplete\n`;+ let stderr = "";+ await fakeAdb.setReport(stdout, stderr);++ const server = createServer(+ {+ kind: "session",+ session: createTestBinarySession(() => {+ throw new Error("ADB start must not open a deep-analysis provider");+ }),+ },+ {+ adbDeviceAnalysis: new AdbProvider({+ environment: { REA_ADB_PATH: binary },+ }),+ },+ );+ onTestFinished(() => server.close());+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ const client = new Client({ name: "adb-start-boundary", version: "0.0.0" });+ onTestFinished(() => client.close());+ await client.connect(clientTransport);++ const input =+ operation === "start_adb_app"+ ? { serial: "emulator-5554", package: "com.example" }+ : {+ serial: "emulator-5554",+ action: "android.intent.action.MAIN",+ data_uri: "https://example.invalid/launch",+ component: "com.example/.Main",+ extras: [{ key: "mode", type: "string" as const, value: "test" }],+ };+ const success = await client.callTool({+ name: operation,+ arguments: input,+ });+ expect(success.isError).not.toBe(true);+ const evidence = toolContract(operation).outputSchema.parse(+ parseEvidence(JSON.parse(responseText(success))),+ );+ expect(evidence.confidence).toBe("observed");+ expect(evidence.normalized_result).toMatchObject({+ started_activity: "act=android.intent.action.MAIN cmp=com.example/.Main",+ reported_activity: "com.example/.Main",+ reported_status: "ok",+ });+ expect(evidence.raw_result).toEqual({ stdout, stderr });++ stdout = `${starting}Status: timeout\nActivity: com.example/.Main\nWaitTime: 10004\nComplete\n`;+ await fakeAdb.setReport(stdout, stderr);+ const timeout = await client.callTool({+ name: operation,+ arguments: input,+ });+ expect(timeout.isError).toBe(true);+ const timeoutError = analysisErrorProjectionSchema.parse(+ JSON.parse(responseText(timeout)).error,+ );+ expect(timeoutError).toMatchObject({+ code: "unsupported_target",+ details: {+ path: "emulator-5554",+ reason: "am start reported status: timeout",+ captured_output: { stdout, stderr, truncated: false },+ partial_observation: {+ provider_id: "adb",+ operation,+ result: {+ started_activity:+ "act=android.intent.action.MAIN cmp=com.example/.Main",+ reported_activity: "com.example/.Main",+ reported_status: "timeout",+ },+ },+ },+ });+ expect(timeoutError).not.toHaveProperty("timeout_ms");++ stdout = `${starting}Status: ok\nActivity: com.example/.Main\nComplete\n`;+ stderr = "Exception: Activity class does not exist\n";+ await fakeAdb.setReport(stdout, stderr);+ const hardError = await client.callTool({+ name: operation,+ arguments: input,+ });+ expect(hardError.isError).toBe(true);+ const hardErrorProjection = analysisErrorProjectionSchema.parse(+ JSON.parse(responseText(hardError)).error,+ );+ expect(hardErrorProjection.message).toContain(+ "Activity class does not exist",+ );+ expect(hardErrorProjection.details).toMatchObject({+ captured_output: { stdout, stderr, truncated: false },+ partial_observation: {+ operation,+ result: { reported_status: "ok" },+ },+ });++ const calls = await fakeAdb.calls();+ expect(+ calls.filter((arguments_) => arguments_.includes("start -W")),+ ).toEqual(+ Array.from({ length: 3 }, () =>+ [+ "-s emulator-5554 shell am start -W",+ ...(operation === "start_adb_app"+ ? ["-n com.example/.Main"]+ : [+ "-a android.intent.action.MAIN",+ "-d https://example.invalid/launch",+ "-n com.example/.Main",+ "--es mode test",+ ]),+ ].join(" "),+ ),+ );+ },+);