Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(adb)!: distinguish reinstall intent from observed replacement

morluto864314ac8579
diff --git a/docs/adb-device-analysis.md b/docs/adb-device-analysis.md
index 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.ts
index 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; fi
diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,