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)!: distinguish reinstall intent from observed replacement
morluto864314ac8579
diff --git a/docs/adb-device-analysis.md b/docs/adb-device-analysis.mdindex 44b5e1334..60fecc227 100644--- a/docs/adb-device-analysis.md+++ b/docs/adb-device-analysis.md@@ -97,12 +97,17 @@ existing analysis families directly, for example| `capture_adb_screen` | read | One `screencap -p` frame (exec-out, no device-side file) with dimensions || `collect_adb_bugreport` | read | Device-generated bugreport zip, digested || `push_adb_file` | **mutates device** | One local file to a device path (e.g. pushing tools into `/data/local/tmp`); checks for existing targets and refuses them without explicit overwrite (the check is not atomic); compares digests when device `sha256sum` is available |-| `install_adb_package` | **mutates device** | Local APK via `adb install [-r]`; preserves the device's Success/Failure verdict |+| `install_adb_package` | **mutates device** | Local APK via `adb install [-r]`; preserves its Success/Failure verdict, records `replace_requested`, and leaves actual replacement `null` because prior package state is not observed || `uninstall_adb_package` | **mutates device** | Removes a package and its data for user 0 || `start_adb_app` | **mutates device** | Resolves the package's launcher activity (`cmd package resolve-activity --brief`) and starts it (`am start -n`) || `start_adb_activity` | **mutates device** | Starts an intent (`am start -a` with optional URI, component, and up to 16 typed extras); preserves the activity manager's verdict || `stop_adb_app` | **mutates device** | Force-stops every process of a package, ending a dynamic-analysis run |+For `install_adb_package`, `replace_requested` records whether `-r` was sent.+The `replaced` result is `null`: the successful install response does not say+whether the package was installed fresh or replaced, and REA does not query the+device first. The install verdict and host APK digest remain available.+## Interpret the result- **Directory names retain whitespace and newlines.** Symlink targets do too,diff --git a/src/adb/AdbProvider.test.ts b/src/adb/AdbProvider.test.tsindex 77b06e3c9..8615e4cdf 100644--- a/src/adb/AdbProvider.test.ts+++ b/src/adb/AdbProvider.test.ts@@ -1222,15 +1222,21 @@ exit 1`,const apk = join(root, "app.apk");await writeFile(apk, "apk");const digest = createHash("sha256").update("apk").digest("hex");- const installed = await evidenceResult(providerOver(binary), {+ const execution = await providerOver(binary).execute({operation: "install_adb_package",input: { serial: "emulator-5554", apk_path: apk, replace: false },});- expect(installed).toMatchObject({+ expect(execution.ok).toBe(true);+ if (!execution.ok) throw execution.error;+ expect(execution.value.result).toMatchObject({bytes: 3,sha256: digest,- replaced: false,+ replace_requested: false,+ replaced: null,});+ expect(execution.value.limitations).toContain(+ "Whether an existing package was replaced is unknown; replace_requested records only the adb install mode",+ );const { binary: failing } = await writeAdbStub(() => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fidiff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsindex 881842642..395ec8125 100644--- a/src/adb/AdbProvider.ts+++ b/src/adb/AdbProvider.ts@@ -1884,12 +1884,14 @@ export class AdbProvider {apk_path: apkPath,bytes: digest.bytes,sha256: digest.sha256,- replaced: input.replace,+ replace_requested: input.replace,+ replaced: null,},provider,{limitations: ["Install changes device state; the installed APK's digest is the host file's digest",+ "Whether an existing package was replaced is unknown; replace_requested records only the adb install mode",],},),diff --git a/src/cli/adbCommands.ts b/src/cli/adbCommands.tsindex 677cf8f91..1a8180ee9 100644--- a/src/cli/adbCommands.ts+++ b/src/cli/adbCommands.ts@@ -284,7 +284,7 @@ export const registerAdbCommands = (});cli.command(CLI_COMMANDS.installAdbPackage, {description:- "Install one local APK; --replace re-installs keeping the app's data",+ "Install one local APK; --replace requests reinstall mode to keep existing app data",args: z.object({serial,"apk-path": z.string().min(1).describe("Local APK file to install"),@@ -293,7 +293,9 @@ export const registerAdbCommands = (replace: z.boolean().default(false)- .describe("Replace an existing install and keep its data"),+ .describe(+ "Request reinstall mode and keep existing app data if present",+ ),}),run: ({ args, options }) =>execute(CLI_COMMANDS.installAdbPackage, "install_adb_package", {diff --git a/src/contracts/adb/adbToolContracts.ts b/src/contracts/adb/adbToolContracts.tsindex dd5859617..df3d3e897 100644--- a/src/contracts/adb/adbToolContracts.ts+++ b/src/contracts/adb/adbToolContracts.ts@@ -288,7 +288,7 @@ export const ADB_TOOL_CONTRACTS = [name: "install_adb_package",...toolContractMetadata("install_adb_package"),description:- "Install one local APK on the device (`adb install [-r]`), recording the APK's host digest and byte size. A device-mutating tool: `replace` re-installs over an existing package while keeping its data; the device's own Success/Failure verdict is preserved with its reason.",+ "Install one local APK on the device (`adb install [-r]`), recording the APK's host digest and byte size. A device-mutating tool: `replace_requested` records whether `-r` was selected; `replaced` is null because install success does not establish prior package state. The device's own Success/Failure verdict is preserved with its reason.",kind: "adb-provider",inputSchema: adbInputSchemas.install_adb_package,outputSchema: evidenceResultOf(adbResultSchemas.install_adb_package),@@ -298,7 +298,7 @@ export const ADB_TOOL_CONTRACTS = [input: { serial: "emulator-5554", apk_path: "/tmp/app.apk" },},{- title: "Replace an existing install keeping data",+ title: "Request reinstall mode to keep existing app data",input: {serial: "emulator-5554",apk_path: "/tmp/app.apk",diff --git a/src/domain/adb/adbDeviceAnalysis.ts b/src/domain/adb/adbDeviceAnalysis.tsindex c524ebd02..ca6cf78e5 100644--- a/src/domain/adb/adbDeviceAnalysis.ts+++ b/src/domain/adb/adbDeviceAnalysis.ts@@ -234,7 +234,7 @@ export const adbInputSchemas = {.boolean().default(false).describe(- "Replace an existing installation and keep its data (adb install -r)",+ "Request replacement mode and keep existing app data if present (adb install -r); does not establish whether the app was already installed",),}),uninstall_adb_package: z.strictObject({@@ -685,7 +685,8 @@ export const adbResultSchemas = {apk_path: z.string().min(1),bytes: z.number().int().nonnegative(),sha256: z.string().regex(/^[a-f0-9]{64}$/u),- replaced: z.boolean(),+ replace_requested: z.boolean(),+ replaced: z.boolean().nullable(),}),uninstall_adb_package: z.strictObject({client,diff --git a/tests/boundary/cli/adbCli.test.ts b/tests/boundary/cli/adbCli.test.tsindex 71309e878..f0f1d3f91 100644--- a/tests/boundary/cli/adbCli.test.ts+++ b/tests/boundary/cli/adbCli.test.ts@@ -1,6 +1,8 @@-import { chmod, lstat, readFile } from "node:fs/promises";+import { chmod, lstat, readFile, unlink } from "node:fs/promises";import { expect, it, onTestFinished } from "vitest";+import { z } from "zod";+import { toolContract } from "../../../src/contracts/toolContracts.js";import {expectConfigurationRefusal,serveCli as serve,@@ -42,6 +44,107 @@ it("validates device serials before contacting any device", async () => {});});+it.skipIf(process.platform === "win32")(+ "preserves requested reinstall mode without claiming prior package state",+ async () => {+ const workspace = await createTestWorkspace("rea-adb-install-state-");+ onTestFinished(() => removeTestWorkspace(workspace.root));+ const apk = await workspace.write("app.apk", "apk");+ const adb = await workspace.write(+ "adb",+ `#!/bin/sh+root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)+printf '%s\\n' "$*" >> "$root/calls"+if [ "$1" = version ]; then+ printf 'Android Debug Bridge version 1.0.41\\nVersion 34.0.5-cli\\nInstalled as %s\\n' "$0"+ exit 0+fi+if [ "$1" = -s ] && [ "$3" = install ]; then+ if [ -f "$root/installed" ]; then+ if [ "$4" != -r ]; then+ printf 'Failure [INSTALL_FAILED_ALREADY_EXISTS]\\n'+ exit 0+ fi+ printf 'replacement\\n' >> "$root/events"+ else+ printf 'fresh-install\\n' >> "$root/events"+ fi+ : > "$root/installed"+ printf 'Performing Streamed Install\\nSuccess\\n'+ exit 0+fi+exit 1+`,+ );+ await chmod(adb, 0o755);++ const installEnvelope = z.object({+ ok: z.literal(true),+ data: toolContract("install_adb_package").outputSchema,+ });+ const install = async (replace: boolean) => {+ const result = await serve(+ [+ "install-adb-package",+ "emulator-5554",+ apk,+ ...(replace ? ["--replace"] : []),+ "--format",+ "json",+ "--full-output",+ ],+ { REA_ADB_PATH: adb },+ );+ expect(result.exitCode).toBe(0);+ return installEnvelope.parse(JSON.parse(result.stdout));+ };++ const freshReplace = await install(true);+ expect(freshReplace).toMatchObject({+ ok: true,+ data: {+ parameters: { replace: true },+ normalized_result: { replace_requested: true, replaced: null },+ confidence: "observed",+ },+ });+ expect(freshReplace.data.limitations.join("\n")).toContain(+ "Whether an existing package was replaced is unknown",+ );++ const existingReplace = await install(true);+ expect(existingReplace).toMatchObject({+ ok: true,+ data: {+ parameters: { replace: true },+ normalized_result: { replace_requested: true, replaced: null },+ },+ });++ await unlink(workspace.path("installed"));+ const freshDefault = await install(false);+ expect(freshDefault).toMatchObject({+ ok: true,+ data: {+ parameters: { replace: false },+ normalized_result: { replace_requested: false, replaced: null },+ },+ });+ expect(await readFile(workspace.path("events"), "utf8")).toBe(+ "fresh-install\nreplacement\nfresh-install\n",+ );+ const calls = await readFile(workspace.path("calls"), "utf8");+ expect(calls.split("\n").filter((line) => line !== "")).toEqual([+ "version",+ `-s emulator-5554 install -r ${apk}`,+ "version",+ `-s emulator-5554 install -r ${apk}`,+ "version",+ `-s emulator-5554 install ${apk}`,+ ]);+ },+);+it("requires the output directory option on pull", async () => {const result = await serve(["pull-adb-package",diff --git a/tests/boundary/mcp/adbMcp.test.ts b/tests/boundary/mcp/adbMcp.test.tsindex 07fe6e9c4..656855dd0 100644--- a/tests/boundary/mcp/adbMcp.test.ts+++ b/tests/boundary/mcp/adbMcp.test.ts@@ -233,7 +233,8 @@ const results: Readonly<Record<string, unknown>> = {apk_path: "/tmp/app.apk",bytes: 2048,sha256: "a".repeat(64),- replaced: false,+ replace_requested: false,+ replaced: null,},uninstall_adb_package: {client: clientIdentity,