rea-agents 6.2.0 → 6.4.0

package/dist/composition/auxiliaryAnalysisProviders.js

@@ -1,13 +1,14 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
-import { ARTIFACT_PROVIDER_IDENTITY, artifactCapabilities, } from "../artifacts/ArtifactProviderMetadata.js";
-import { MANAGED_STATIC_PROVIDER_IDENTITY, managedStaticCapabilities, } from "../dotnet/ManagedStaticProviderMetadata.js";
+import { artifactCapabilities } from "../artifacts/ArtifactProviderMetadata.js";
+import { ARTIFACT_GRAPH_PROVIDER, MANAGED_STATIC_PROVIDER, } from "../application/InvestigationProviders.js";
+import { managedStaticCapabilities } from "../dotnet/ManagedStaticProviderMetadata.js";
 import { NATIVE_MACOS_PROVIDER_IDENTITY, nativeMacOSCapabilities, } from "../native/NativeMacOSProviderMetadata.js";
 /** Wire the three existing auxiliary AnalysisProvider implementations lazily. */
 export const auxiliaryAnalysisProviderDeclarations = (selectedEnvironment, platform = process.platform) => {
     const environment = snapshotEnvironment(selectedEnvironment, platform);
     return [
         {
-            identity: ARTIFACT_PROVIDER_IDENTITY,
+            identity: ARTIFACT_GRAPH_PROVIDER,
             capabilities: artifactCapabilities(platform),
             load: async () => {
                 const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
@@ -23,7 +24,7 @@ export const auxiliaryAnalysisProviderDeclarations = (selectedEnvironment, platf
             },
         },
         {
-            identity: MANAGED_STATIC_PROVIDER_IDENTITY,
+            identity: MANAGED_STATIC_PROVIDER,
             capabilities: managedStaticCapabilities(),
             load: async () => {
                 const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");

package/dist/composition/binaryDiagnostics.js

@@ -2,6 +2,10 @@ import { RecordedCrashService } from "../application/binaryDiagnostics/RecordedC
 import { PwntoolsRecordedCrashProvider } from "../native/pwntools/PwntoolsRecordedCrashProvider.js";
 import { BinaryLayoutService } from "../application/binaryDiagnostics/BinaryLayoutService.js";
 import { PwntoolsLayoutProvider } from "../native/pwntools/PwntoolsLayoutProvider.js";
+import { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js";
+import { PeResourcesProvider } from "../native/pe/PeResourcesProvider.js";
+/** Portable PE inspection with no engine, installation or target acquisition. */
+export const createPeResourcesService = () => new PeResourcesService(new PeResourcesProvider());
 /** Compose the offline adapter without import-time I/O or dependency acquisition. */
 export const createBinaryLayoutService = (environment = process.env) => new BinaryLayoutService(new PwntoolsLayoutProvider(environment));
 /** Compose recorded-core inspection without acquiring a debugger or toolchain. */

package/dist/composition/browserScenario.js

@@ -1,4 +1,4 @@
 import { PlaywrightBrowserScenarioProvider } from "../browser/PlaywrightBrowserScenarioProvider.js";
-import { PlaywrightScenarioSessionFactory } from "../browser/PlaywrightScenarioSession.js";
+import { PlaywrightScenarioSession } from "../browser/PlaywrightScenarioSession.js";
 /** Construct a fresh provider without opening a target or acquiring an engine. */
-export const createBrowserScenarioProvider = (environment) => new PlaywrightBrowserScenarioProvider(new PlaywrightScenarioSessionFactory(environment));
+export const createBrowserScenarioProvider = (environment) => new PlaywrightBrowserScenarioProvider((scenario, options) => PlaywrightScenarioSession.open(scenario, environment, options));

package/dist/composition/directAnalysis.js

@@ -1,24 +1,31 @@
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { parseConfig } from "../config/parseConfig.js";
 import { runDirectAnalysis as executeDirectAnalysis, runProviderAnalysis as executeProviderAnalysis, runManagedProviderExecution as executeManagedProvider, } from "../application/DirectAnalysis.js";
-import { runCapabilityStatus as executeCapabilityStatus, runProviderStatus as executeProviderStatus, } from "../application/DirectAnalysisStatus.js";
-import { createBinarySession, createManagedBinarySession } from "./binary.js";
+import { runSessionStatus as executeSessionStatus } from "../application/DirectAnalysisStatus.js";
 /** Bind one-shot analysis and status commands to one caller-selected environment. */
 export const createDirectAnalysis = (selectedEnvironment) => {
     const environment = snapshotEnvironment(selectedEnvironment);
     const dependencies = {
         readConfiguration: () => parseConfig(environment),
-        createBinarySession: (config, logger) => createBinarySession(config, logger, environment),
-        createManagedBinarySession,
+        createBinarySession: async (config, logger) => {
+            const { createBinarySession } = await import("./binary.js");
+            return createBinarySession(config, logger, environment);
+        },
+        createManagedBinarySession: async () => {
+            const { createManagedBinarySession } = await import("./binary.js");
+            return createManagedBinarySession();
+        },
     };
     return {
         runDirectAnalysis: executeDirectAnalysis.bind(undefined, dependencies),
         runProviderAnalysis: executeProviderAnalysis.bind(undefined, dependencies),
-        runProviderStatus: executeProviderStatus.bind(undefined, dependencies),
-        runCapabilityStatus: executeCapabilityStatus.bind(undefined, dependencies),
+        runSessionStatus: executeSessionStatus.bind(undefined, dependencies),
     };
 };
 /** Execute managed metadata without configuration or native provider candidates. */
 export const runManagedProviderExecution = executeManagedProvider.bind(undefined, {
-    createManagedBinarySession,
+    createManagedBinarySession: async () => {
+        const { createManagedBinarySession } = await import("./binary.js");
+        return createManagedBinarySession();
+    },
 });

package/dist/composition/javascriptAnalysisWorkerProcess.js

@@ -0,0 +1,48 @@
+import { parseJavaScriptSource } from "../domain/javascript/javascriptSourceParser.js";
+import { analyzeParsedJavaScriptStaticSourceSteps } from "../domain/javascript/javascriptStaticAnalysis.js";
+import { analyzeParsedJavaScriptSemanticsSteps, classifyParsedJavaScriptOpenReceiversSteps, } from "../domain/javascript/javascriptSemanticAnalysis.js";
+import { failedJavaScriptStaticAnalysis } from "../domain/javascript/javascriptStaticAnalysisHelpers.js";
+import { projectJavaScriptModuleSemantics } from "../domain/javascript/javascriptModuleSemanticIr.js";
+import { measureJavaScriptModuleTransfer } from "../javascript/analysis/JavaScriptAnalysisTransfer.js";
+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
+import { projectJavaScriptSemanticFileSteps } from "../application/javascript/JavaScriptSemanticGraphBuilder.js";
+import { completeJavaScriptAnalysisSteps } from "../application/javascript/JavaScriptAnalysisControl.js";
+import { serveJavaScriptAnalysisWorker, } from "../javascript/analysis/JavaScriptAnalysisWorkerServer.js";
+const analyze = async (file, nodeBudget, callbacks) => {
+    if (!file.text.included)
+        throw new TypeError("JavaScript worker requires decoded source text");
+    await callbacks.phase("parse");
+    let parsed = parseJavaScriptSource(file.text.value, file.path);
+    if (parsed === null) {
+        await callbacks.checkpoint(failedJavaScriptStaticAnalysis());
+        return null;
+    }
+    await callbacks.phase("static");
+    const receivers = await completeJavaScriptAnalysisSteps(classifyParsedJavaScriptOpenReceiversSteps(parsed));
+    const facts = await completeJavaScriptAnalysisSteps(analyzeParsedJavaScriptStaticSourceSteps(file.text.value, parsed, receivers));
+    const resultBudgetBytes = await callbacks.checkpoint(facts);
+    if (facts.parse_status === "failed")
+        return null;
+    if (resultBudgetBytes === 0)
+        throw new AnalysisResourceConstraintError("analyze_javascript_application", "memory", `The parent reserved its remaining result capacity for static observations; semantic analysis of ${file.path} was not started`, { semantic_result_budget_bytes: 0 });
+    await callbacks.phase("semantic");
+    const ir = await completeJavaScriptAnalysisSteps(analyzeParsedJavaScriptSemanticsSteps(parsed));
+    parsed = null;
+    const module = projectJavaScriptModuleSemantics(ir);
+    const measured = measureJavaScriptModuleTransfer(module);
+    if (measured.retentionBytes > resultBudgetBytes)
+        throw new AnalysisResourceConstraintError("analyze_javascript_application", "memory", `Completed module facts for ${file.path} exceed the parent's offered result budget; static facts were retained`, {
+            semantic_result_budget_bytes: resultBudgetBytes,
+            module_transfer_bytes: measured.bytes,
+        });
+    await callbacks.phase("projection");
+    const projection = await completeJavaScriptAnalysisSteps(projectJavaScriptSemanticFileSteps(file, ir, nodeBudget));
+    return { module, projection };
+};
+try {
+    await serveJavaScriptAnalysisWorker(analyze);
+}
+catch (cause) {
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`);
+    process.exitCode = 1;
+}

package/dist/composition/jeb.js

@@ -0,0 +1,6 @@
+import { JebProvider } from "../jeb/JebProvider.js";
+/** Construct one JEB provider bound to the caller-selected MCP endpoint. */
+export const createJebAnalysisProvider = (environment = process.env, connectionFactory) => new JebProvider({
+    environment,
+    ...(connectionFactory === undefined ? {} : { connectionFactory }),
+});

package/dist/config/environment.js

@@ -3,11 +3,14 @@ import { isAbsolute } from "node:path";
 import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
+import { ghidraCompilerSpecIdSchema, ghidraLanguageIdSchema, } from "./ghidraLanguageOverride.js";
 import { ghidraStartupTimeoutSchema } from "./ghidraStartupTimeout.js";
+import { mcpInputSchemaProfileSchema } from "./mcpInputSchemaProfile.js";
 import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";
 const environmentSchema = z.object({
     REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
     REA_MCP_MAX_RESPONSE_BYTES: mcpResponseBudgetSchema.optional(),
+    REA_MCP_INPUT_SCHEMA_PROFILE: mcpInputSchemaProfileSchema.optional(),
     REA_IDA_MCP_CONFIG: z
         .string()
         .min(1)
@@ -29,6 +32,13 @@ const environmentSchema = z.object({
         .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
         .optional(),
     REA_GHIDRA_STARTUP_TIMEOUT_MS: ghidraStartupTimeoutSchema,
+    REA_GHIDRA_LANGUAGE_ID: ghidraLanguageIdSchema.optional(),
+    REA_GHIDRA_COMPILER_SPEC_ID: ghidraCompilerSpecIdSchema.optional(),
+    REA_GHIDRA_SEED_FILE: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_GHIDRA_SEED_FILE must be absolute")
+        .optional(),
     REA_ILSPY_CMD_PATH: z
         .string()
         .min(1)

package/dist/config/ghidraLanguageOverride.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+// Ghidra language IDs are four colon-separated fields; variants may contain
+// spaces ("x86:LE:16:Real Mode") but never leading or trailing whitespace.
+export const ghidraLanguageIdSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_.+-]+:(?:LE|BE):[1-9]\d*:[A-Za-z0-9_.+-](?:[A-Za-z0-9_.+ -]*[A-Za-z0-9_.+-])?$/u, "must be a Ghidra language ID such as x86:LE:32:default");
+export const ghidraCompilerSpecIdSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_.+-]+$/u, "must be a Ghidra compiler-spec ID such as default or borlandcpp");

package/dist/config/mcpInputSchemaProfile.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { err, ok } from "../domain/result.js";
+// Moonshot's function-calling API rejects requests while any single tool
+// parameters schema exceeds its literal serialized size cap. Community
+// measurements bound the cap between ~13.7 KB (accepted) and ~15 KB
+// (rejected); 13 KiB leaves margin under the lower bound. See
+// https://github.com/morluto/rea/issues/1484 for the measured evidence.
+export const COMPACT_INPUT_SCHEMA_BUDGET_BYTES = 13 * 1024;
+export const mcpInputSchemaProfileSchema = z.enum(["full", "compact"]);
+const profileConstraint = 'REA_MCP_INPUT_SCHEMA_PROFILE must be "full" (default) or "compact". The compact profile advertises input schemas without nested annotation prose for providers that cap each tool schema\'s serialized size.';
+/** Parse the advertised input schema presentation selection. */
+export const parseMcpInputSchemaProfile = (value) => {
+    if (value === undefined)
+        return ok(undefined);
+    const parsed = mcpInputSchemaProfileSchema.safeParse(value);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new ConfigurationError(profileConstraint, {
+            settings: [
+                {
+                    setting: "REA_MCP_INPUT_SCHEMA_PROFILE",
+                    constraint: profileConstraint,
+                },
+            ],
+        }));
+};

package/dist/config/parseConfig.js

@@ -1,7 +1,7 @@
 import { accessSync, constants } from "node:fs";
 import { join } from "node:path";
 import { ConfigurationError } from "../domain/configurationErrors.js";
-import { ok } from "../domain/result.js";
+import { err, ok } from "../domain/result.js";
 import { parseEnvironment } from "./environment.js";
 import { homeDirectoryFromEnvironment } from "./homeDirectory.js";
 import { parseStringArray, parseLoaderArgs } from "./parsers.js";
@@ -36,10 +36,24 @@ export const parseConfig = (environment) => {
     const secretPatterns = parseStringArray(env.REA_REFERENCE_SECRET_PATTERNS_JSON, "REA_REFERENCE_SECRET_PATTERNS_JSON");
     if (!secretPatterns.ok)
         return secretPatterns;
+    // Ghidra's analyzeHeadless accepts -cspec only together with -processor.
+    if (env.REA_GHIDRA_COMPILER_SPEC_ID !== undefined &&
+        env.REA_GHIDRA_LANGUAGE_ID === undefined)
+        return err(new ConfigurationError("Invalid REA environment configuration", {
+            settings: [
+                {
+                    setting: "REA_GHIDRA_COMPILER_SPEC_ID",
+                    constraint: "requires REA_GHIDRA_LANGUAGE_ID",
+                },
+            ],
+        }));
     return ok({
         ...(env.REA_MCP_MAX_RESPONSE_BYTES === undefined
             ? {}
             : { mcpMaxResponseBytes: env.REA_MCP_MAX_RESPONSE_BYTES }),
+        ...(env.REA_MCP_INPUT_SCHEMA_PROFILE === undefined
+            ? {}
+            : { mcpInputSchemaProfile: env.REA_MCP_INPUT_SCHEMA_PROFILE }),
         analysisProvider: env.REA_ANALYSIS_PROVIDER,
         ...(env.REA_IDA_MCP_CONFIG === undefined
             ? {}
@@ -47,6 +61,19 @@ export const parseConfig = (environment) => {
         ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
         ghidraJavaHome: env.JAVA_HOME,
         ghidraStartupTimeoutMs: env.REA_GHIDRA_STARTUP_TIMEOUT_MS,
+        ...(env.REA_GHIDRA_LANGUAGE_ID === undefined
+            ? {}
+            : {
+                ghidraLanguageOverride: {
+                    languageId: env.REA_GHIDRA_LANGUAGE_ID,
+                    ...(env.REA_GHIDRA_COMPILER_SPEC_ID === undefined
+                        ? {}
+                        : { compilerSpecId: env.REA_GHIDRA_COMPILER_SPEC_ID }),
+                },
+            }),
+        ...(env.REA_GHIDRA_SEED_FILE === undefined
+            ? {}
+            : { ghidraSeedFile: env.REA_GHIDRA_SEED_FILE }),
         ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
             ? {}
             : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),

package/dist/contracts/adb/adbToolContracts.js

@@ -0,0 +1,353 @@
+import { adbInputSchemas, adbResultSchemas, } from "../../domain/adb/adbDeviceAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** ADB device inspection and acquisition over a caller-supplied binary. */
+export const ADB_TOOL_CONTRACTS = [
+    {
+        name: "inspect_adb_client",
+        ...toolContractMetadata("inspect_adb_client"),
+        description: "Inspect the caller-selected adb client: resolved binary, version, and install path. Never contacts devices and never starts the adb server. REA never installs platform tools; select a binary with REA_ADB_PATH (absolute) or adb on PATH.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.inspect_adb_client,
+        outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_client),
+        examples: [{ title: "Check the adb client", input: {} }],
+    },
+    {
+        name: "list_adb_devices",
+        ...toolContractMetadata("list_adb_devices"),
+        description: "List attached devices exactly as `adb devices -l` reports them: serial, state, transport, model metadata, and an inferred emulator/physical kind with its evidence basis. Emulators and USB or network devices appear alike; REA neither starts nor manages them. May start the local adb server on first use.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_devices,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_devices),
+        examples: [{ title: "List attached devices", input: {} }],
+    },
+    {
+        name: "inspect_adb_device",
+        ...toolContractMetadata("inspect_adb_device"),
+        description: "Inspect one device's build identity through a fixed `getprop` whitelist: Android and SDK versions, security patch, fingerprint, product identity, CPU ABIs, and debuggable flag, plus the observed emulator indicator ro.kernel.qemu. Read-only with respect to the device.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.inspect_adb_device,
+        outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_device),
+        examples: [
+            { title: "Inspect one device", input: { serial: "emulator-5554" } },
+        ],
+    },
+    {
+        name: "list_adb_packages",
+        ...toolContractMetadata("list_adb_packages"),
+        description: "List installed packages on one device with each base APK's device path, optionally scoped to third-party or system packages. Paths are device filesystem paths, not host-local. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_packages,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_packages),
+        examples: [
+            {
+                title: "List third-party packages",
+                input: { serial: "emulator-5554", scope: "third_party" },
+            },
+        ],
+    },
+    {
+        name: "pull_adb_package",
+        ...toolContractMetadata("pull_adb_package"),
+        description: "Pull one installed package's complete APK set (base plus every split, as `pm path` reports) from the device into a caller-selected output directory, creating a package-named subdirectory that must not already exist. Every pulled file is digested with SHA-256; partial pulls keep successful artifacts and per-file failure reasons. The device keeps the originals.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.pull_adb_package,
+        outputSchema: evidenceResultOf(adbResultSchemas.pull_adb_package),
+        examples: [
+            {
+                title: "Pull a package APK set",
+                input: {
+                    serial: "emulator-5554",
+                    package: "com.example.app",
+                    output_directory: "/tmp/rea-pulls",
+                },
+            },
+        ],
+    },
+    {
+        name: "read_adb_logcat",
+        ...toolContractMetadata("read_adb_logcat"),
+        description: "Read a bounded dump of the device log (`logcat -d -t`) for one buffer, optionally restricted to a process id. No streaming, no clearing; the newest lines are kept when the count cap trims. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.read_adb_logcat,
+        outputSchema: evidenceResultOf(adbResultSchemas.read_adb_logcat),
+        examples: [
+            {
+                title: "Read the last 200 main-buffer lines",
+                input: { serial: "emulator-5554", count: 200, buffer: "main" },
+            },
+        ],
+    },
+    {
+        name: "inspect_adb_package",
+        ...toolContractMetadata("inspect_adb_package"),
+        description: "Inspect one installed package through `dumpsys package`: version name/code, install and update times, installer, user id, flags, and the requested-permission count. A fixed projection of version-dependent output; unknown sections are ignored rather than guessed. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.inspect_adb_package,
+        outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_package),
+        examples: [
+            {
+                title: "Inspect an installed package",
+                input: { serial: "emulator-5554", package: "com.example.app" },
+            },
+        ],
+    },
+    {
+        name: "pull_adb_file",
+        ...toolContractMetadata("pull_adb_file"),
+        description: "Pull one absolute device path (a database, shared-preferences XML, or any readable file) into a caller-selected output directory, digesting it with SHA-256. The local copy must not already exist. Read-only with respect to the device.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.pull_adb_file,
+        outputSchema: evidenceResultOf(adbResultSchemas.pull_adb_file),
+        examples: [
+            {
+                title: "Pull an app database",
+                input: {
+                    serial: "emulator-5554",
+                    device_path: "/data/data/com.example.app/databases/app.db",
+                    output_directory: "/tmp/rea-pulls",
+                },
+            },
+        ],
+    },
+    {
+        name: "push_adb_file",
+        ...toolContractMetadata("push_adb_file"),
+        description: "Push one local file to an absolute device path. The only device-mutating ADB tool: existing device files are refused unless overwrite is explicitly requested, and the transfer is verified by comparing the local digest with the device's own sha256sum when the device provides one.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.push_adb_file,
+        outputSchema: evidenceResultOf(adbResultSchemas.push_adb_file),
+        examples: [
+            {
+                title: "Push a script to tmp",
+                input: {
+                    serial: "emulator-5554",
+                    local_path: "/tmp/frida-server",
+                    device_path: "/data/local/tmp/frida-server",
+                },
+            },
+        ],
+    },
+    {
+        name: "capture_adb_screen",
+        ...toolContractMetadata("capture_adb_screen"),
+        description: "Capture one frame of the device screen as a PNG (`screencap -p` through exec-out, no device-side file) into a caller-selected output directory, digesting it and reporting its dimensions. No recording or interaction.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.capture_adb_screen,
+        outputSchema: evidenceResultOf(adbResultSchemas.capture_adb_screen),
+        examples: [
+            {
+                title: "Capture the current screen",
+                input: {
+                    serial: "emulator-5554",
+                    output_directory: "/tmp/rea-captures",
+                },
+            },
+        ],
+    },
+    {
+        name: "list_adb_processes",
+        ...toolContractMetadata("list_adb_processes"),
+        description: "List running processes exactly as `ps -A` reports them: user, pid, ppid, rss, state, and name. Useful for pairing with instrumentation lanes. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_processes,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_processes),
+        examples: [{ title: "List processes", input: { serial: "emulator-5554" } }],
+    },
+    {
+        name: "list_adb_directory",
+        ...toolContractMetadata("list_adb_directory"),
+        description: "List one absolute device directory (`ls -la`): names, kinds, permissions, owner, group, sizes, dates, and symlink targets. Recognizes the standard errors for absent paths and denied reads. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_directory,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_directory),
+        examples: [
+            {
+                title: "List an app's data directory",
+                input: {
+                    serial: "emulator-5554",
+                    device_path: "/data/data/com.example.app",
+                },
+            },
+        ],
+    },
+    {
+        name: "list_adb_features",
+        ...toolContractMetadata("list_adb_features"),
+        description: "List the device's declared hardware and software features (`pm list features`) for device fingerprinting. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_features,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_features),
+        examples: [{ title: "List features", input: { serial: "emulator-5554" } }],
+    },
+    {
+        name: "list_adb_services",
+        ...toolContractMetadata("list_adb_services"),
+        description: "List the device's binder services with their interfaces (`service list`). Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.list_adb_services,
+        outputSchema: evidenceResultOf(adbResultSchemas.list_adb_services),
+        examples: [{ title: "List services", input: { serial: "emulator-5554" } }],
+    },
+    {
+        name: "inspect_adb_display",
+        ...toolContractMetadata("inspect_adb_display"),
+        description: "Report the display's physical and any overridden size (`wm size`) and density (`wm density`) as the device declares them. Read-only; setting values is not exposed.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.inspect_adb_display,
+        outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_display),
+        examples: [
+            { title: "Inspect the display", input: { serial: "emulator-5554" } },
+        ],
+    },
+    {
+        name: "inspect_adb_window",
+        ...toolContractMetadata("inspect_adb_window"),
+        description: "Report the window manager's current focus declarations (`dumpsys window windows`: mCurrentFocus and mFocusedApp) — what is on screen at read time without any interaction. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.inspect_adb_window,
+        outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_window),
+        examples: [
+            { title: "Inspect window focus", input: { serial: "emulator-5554" } },
+        ],
+    },
+    {
+        name: "read_adb_setting",
+        ...toolContractMetadata("read_adb_setting"),
+        description: "Read one settings value (`settings get`) from the system, secure, or global namespace. Absent keys report the device's own null observation. Read-only; writing settings is not exposed.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.read_adb_setting,
+        outputSchema: evidenceResultOf(adbResultSchemas.read_adb_setting),
+        examples: [
+            {
+                title: "Read the ADB-enabled setting",
+                input: {
+                    serial: "emulator-5554",
+                    namespace: "secure",
+                    key: "adb_enabled",
+                },
+            },
+        ],
+    },
+    {
+        name: "collect_adb_bugreport",
+        ...toolContractMetadata("collect_adb_bugreport"),
+        description: "Collect one device-generated bugreport archive (`adb bugreport`) into a caller-selected output directory, digesting the zip. The archive contains the device's own dumpstate, dumpsys, and logcat report; collection can take minutes. Read-only with respect to configuration.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.collect_adb_bugreport,
+        outputSchema: evidenceResultOf(adbResultSchemas.collect_adb_bugreport),
+        examples: [
+            {
+                title: "Collect a bugreport",
+                input: {
+                    serial: "emulator-5554",
+                    output_directory: "/tmp/rea-bugreports",
+                },
+            },
+        ],
+    },
+    {
+        name: "resolve_adb_packages",
+        ...toolContractMetadata("resolve_adb_packages"),
+        description: "Find installed packages by case-insensitive substring of the package name (e.g. `whatsapp` → `com.whatsapp`), returning each match's base APK device path. The first step of an easy get: resolve, then pull_adb_package the exact name. Read-only.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.resolve_adb_packages,
+        outputSchema: evidenceResultOf(adbResultSchemas.resolve_adb_packages),
+        examples: [
+            {
+                title: "Find a package by partial name",
+                input: { serial: "emulator-5554", query: "whatsapp" },
+            },
+        ],
+    },
+    {
+        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.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.install_adb_package,
+        outputSchema: evidenceResultOf(adbResultSchemas.install_adb_package),
+        examples: [
+            {
+                title: "Install an APK",
+                input: { serial: "emulator-5554", apk_path: "/tmp/app.apk" },
+            },
+            {
+                title: "Replace an existing install keeping data",
+                input: {
+                    serial: "emulator-5554",
+                    apk_path: "/tmp/app.apk",
+                    replace: true,
+                },
+            },
+        ],
+    },
+    {
+        name: "uninstall_adb_package",
+        ...toolContractMetadata("uninstall_adb_package"),
+        description: "Uninstall one package from the device (`adb uninstall`), removing its data for user 0. A device-mutating tool; absent packages report the device's own refusal reason.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.uninstall_adb_package,
+        outputSchema: evidenceResultOf(adbResultSchemas.uninstall_adb_package),
+        examples: [
+            {
+                title: "Uninstall a package",
+                input: { serial: "emulator-5554", package: "com.example.app" },
+            },
+        ],
+    },
+    {
+        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.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.start_adb_app,
+        outputSchema: evidenceResultOf(adbResultSchemas.start_adb_app),
+        examples: [
+            {
+                title: "Start an app",
+                input: { serial: "emulator-5554", package: "com.example.app" },
+            },
+        ],
+    },
+    {
+        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.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.start_adb_activity,
+        outputSchema: evidenceResultOf(adbResultSchemas.start_adb_activity),
+        examples: [
+            {
+                title: "Open a deep link",
+                input: {
+                    serial: "emulator-5554",
+                    action: "android.intent.action.VIEW",
+                    data_uri: "https://example.com/path",
+                },
+            },
+            {
+                title: "Start with typed extras",
+                input: {
+                    serial: "emulator-5554",
+                    action: "com.example.APP_ACTION",
+                    extras: [{ key: "level", type: "int", value: "3" }],
+                },
+            },
+        ],
+    },
+    {
+        name: "stop_adb_app",
+        ...toolContractMetadata("stop_adb_app"),
+        description: "Force-stop every process of one package (`am force-stop`), ending a dynamic-analysis run. A device-mutating tool; it succeeds whether or not the package had running processes.",
+        kind: "adb-provider",
+        inputSchema: adbInputSchemas.stop_adb_app,
+        outputSchema: evidenceResultOf(adbResultSchemas.stop_adb_app),
+        examples: [
+            {
+                title: "Stop an app",
+                input: { serial: "emulator-5554", package: "com.example.app" },
+            },
+        ],
+    },
+];