rea-agents 6.3.0 → 6.5.0

package/dist/config/parseConfig.js

@@ -1,12 +1,9 @@
 import { accessSync, constants } from "node:fs";
-import { join } from "node:path";
-import { ConfigurationError } from "../domain/configurationErrors.js";
 import { ok } from "../domain/result.js";
 import { parseEnvironment } from "./environment.js";
 import { homeDirectoryFromEnvironment } from "./homeDirectory.js";
-import { parseStringArray, parseLoaderArgs } from "./parsers.js";
-const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
-const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
+import { linuxHopperLauncherCandidates, REA_MANAGED_LINUX_HOPPER_LAUNCHER, } from "../application/LinuxHopper.js";
+import { MAC_HOPPER_SYSTEM_LAUNCHER, macHopperLauncherCandidates, } from "../application/MacHopperPaths.js";
 const executableAvailable = (path) => {
     try {
         accessSync(path, constants.X_OK);
@@ -16,13 +13,17 @@ const executableAvailable = (path) => {
         return false;
     }
 };
-const defaultHopperLauncherPath = (platform, homeDirectory, executable = executableAvailable) => {
+export const defaultHopperLauncherPath = (platform, homeDirectory, executable = executableAvailable) => {
+    if (platform === "darwin") {
+        for (const candidate of macHopperLauncherCandidates(homeDirectory))
+            if (executable(candidate))
+                return candidate;
+        return MAC_HOPPER_SYSTEM_LAUNCHER;
+    }
     if (platform !== "linux")
-        return DEFAULT_HOPPER_LAUNCHER_PATH;
-    if (executable(SYSTEM_LINUX_HOPPER))
-        return SYSTEM_LINUX_HOPPER;
-    const userLocal = join(homeDirectory, ".local/share/rea/hopper/bin/Hopper");
-    return executable(userLocal) ? userLocal : SYSTEM_LINUX_HOPPER;
+        return MAC_HOPPER_SYSTEM_LAUNCHER;
+    return (linuxHopperLauncherCandidates(homeDirectory).find(executable) ??
+        REA_MANAGED_LINUX_HOPPER_LAUNCHER);
 };
 /** Parse provider configuration and runtime prerequisites at the composition root. */
 export const parseConfig = (environment) => {
@@ -30,16 +31,13 @@ export const parseConfig = (environment) => {
     if (!parsed.ok)
         return parsed;
     const env = parsed.value;
-    const loaderArgs = parseLoaderArgs(env.HOPPER_LOADER_ARGS_JSON);
-    if (!loaderArgs.ok)
-        return loaderArgs;
-    const secretPatterns = parseStringArray(env.REA_REFERENCE_SECRET_PATTERNS_JSON, "REA_REFERENCE_SECRET_PATTERNS_JSON");
-    if (!secretPatterns.ok)
-        return secretPatterns;
     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,16 +45,35 @@ 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_DISABLED_ANALYZERS === undefined
+            ? {}
+            : { ghidraDisabledAnalyzers: env.REA_GHIDRA_DISABLED_ANALYZERS }),
         ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
             ? {}
             : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),
         ilspyCmdPath: env.REA_ILSPY_CMD_PATH,
         hopperLauncherPath: env.HOPPER_LAUNCHER_PATH ??
             defaultHopperLauncherPath(process.platform, homeDirectoryFromEnvironment(environment, process.platform)),
+        hopperStartupTimeoutMs: env.REA_HOPPER_STARTUP_TIMEOUT_MS,
         hopperTargetPath: env.HOPPER_TARGET_PATH,
         hopperTargetKind: env.HOPPER_TARGET_KIND,
-        hopperLoaderArgs: loaderArgs.value,
+        hopperLoaderArgs: env.loaderArgs,
         logLevel: env.REA_LOG_LEVEL,
-        referenceSourcePolicy: { secretPatterns: secretPatterns.value },
+        referenceSourcePolicy: {
+            secretPatterns: env.referenceSecretPatterns,
+        },
     });
 };

package/dist/config/parsers.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ConfigurationError } from "../domain/configurationErrors.js";
+import { nulFreeStringSchema } from "../domain/localPath.js";
 import { err, ok } from "../domain/result.js";
 import { safeParseJson } from "../domain/safeJson.js";
 /** Decode explicitly selected reference-source exclusion patterns. */
@@ -10,16 +11,16 @@ export const parseStringArray = (encoded, name) => {
 export const parseLoaderArgs = (encoded) => {
     if (encoded === undefined)
         return ok([]);
-    return parseConfiguredStringArray(encoded, "HOPPER_LOADER_ARGS_JSON", z.string());
+    return parseConfiguredStringArray(encoded, "HOPPER_LOADER_ARGS_JSON", nulFreeStringSchema, "must encode an array of strings without NUL bytes");
 };
-const parseConfiguredStringArray = (encoded, setting, itemSchema) => {
+const parseConfiguredStringArray = (encoded, setting, itemSchema, requirement = "must encode an array of strings") => {
     const decoded = safeParseJson(encoded);
     if (!decoded.ok)
         return err(configuredArrayError(setting, "must be valid JSON", decoded.cause));
     const parsed = z.array(itemSchema).safeParse(decoded.value);
     return parsed.success
         ? ok(parsed.data)
-        : err(configuredArrayError(setting, "must encode an array of strings", parsed.error));
+        : err(configuredArrayError(setting, requirement, parsed.error));
 };
 const configuredArrayError = (setting, requirement, cause) => {
     const constraint = `${setting} ${requirement}`;

package/dist/config/{ghidraStartupTimeout.js → providerStartupTimeout.js}

@@ -1,12 +1,16 @@
 import { z } from "zod";
 /** Default absolute deadline for Ghidra import, analysis, bridge, and readiness. */
 export const DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS = 330_000;
+/** Default absolute deadline for Hopper launch, analysis, bridge, and readiness. */
+export const DEFAULT_HOPPER_STARTUP_TIMEOUT_MS = 120_000;
+/** Default deadline for Darwin ownership-helper `swiftc` compilation. */
+/** Fresh Swift SDK cache took ~88s on the supported Intel macOS VM. */
+export const DEFAULT_SWIFTC_COMPILE_TIMEOUT_MS = 120_000;
 // Node schedules delays above this signed 32-bit boundary as a 1 ms timer.
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Parse the optional setting without reading the ambient process environment. */
-export const ghidraStartupTimeoutSchema = z
+export const providerStartupTimeoutSchema = z
     .string()
     .regex(/^[1-9]\d*$/u, "must be a positive decimal integer")
     .transform(Number)
-    .pipe(z.number().int().min(1).max(MAX_TIMER_DELAY_MS))
-    .default(DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS);
+    .pipe(z.number().int().min(1).max(MAX_TIMER_DELAY_MS));

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. A device-mutating tool: checks for an existing device file before transfer and refuses it unless overwrite is explicitly requested; this check is not an atomic create and another process can create the path before adb writes. When the device provides sha256sum, the transfer is verified by comparing it with the local digest.",
+        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 the immediate children of one absolute device directory, including hidden entries: names, kinds, permissions, owner, group, sizes, dates, and symlink targets. Names and targets preserve embedded newlines. 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 (mCurrentFocus and mFocusedApp from `dumpsys window windows`, or from `dumpsys window displays` when the windows section declares neither, as on Android 16) — 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_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),
+        examples: [
+            {
+                title: "Install an APK",
+                input: { serial: "emulator-5554", apk_path: "/tmp/app.apk" },
+            },
+            {
+                title: "Request reinstall mode to keep existing app 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'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),
+        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 -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),
+        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" },
+            },
+        ],
+    },
+];

package/dist/contracts/advertisedInputExamples.js

@@ -0,0 +1,48 @@
+import { evidenceSchema } from "../domain/evidence.js";
+/** The Evidence identifier of a complete Evidence record, or undefined. */
+const evidenceRecordId = (value) => typeof value.evidence_id === "string" &&
+    Object.hasOwn(value, "normalized_result") &&
+    evidenceSchema.safeParse(value).success
+    ? value.evidence_id
+    : undefined;
+/** Replace each embedded complete Evidence record with its exact retained reference. */
+const referenceEmbeddedEvidence = (value) => {
+    if (Array.isArray(value)) {
+        const items = value.map(referenceEmbeddedEvidence);
+        return {
+            value: items.map((item) => item.value),
+            embedsEvidence: items.some((item) => item.embedsEvidence),
+        };
+    }
+    if (value === null || typeof value !== "object")
+        return { value, embedsEvidence: false };
+    const evidenceId = evidenceRecordId(value);
+    if (evidenceId !== undefined)
+        return {
+            value: { kind: "retained-evidence", evidence_id: evidenceId },
+            embedsEvidence: true,
+        };
+    const entries = Object.entries(value).map(([key, child]) => [key, referenceEmbeddedEvidence(child)]);
+    return {
+        value: Object.fromEntries(entries.map(([key, child]) => [key, child.value])),
+        embedsEvidence: entries.some(([, child]) => child.embedsEvidence),
+    };
+};
+/**
+ * Examples advertised in a tool's input schema. Embedded complete Evidence is
+ * shown as its exact same-session retained reference when the canonical input
+ * schema accepts that form; an example that can only carry inline Evidence
+ * stays in the canonical contract and its executable tests but leaves the
+ * advertisement. Every advertised example is a distinct valid canonical input.
+ */
+export const advertisedInputExamples = (contract) => {
+    const advertised = new Map();
+    for (const { input } of contract.examples) {
+        const projection = referenceEmbeddedEvidence(input);
+        if (projection.embedsEvidence &&
+            !contract.inputSchema.safeParse(projection.value).success)
+            continue;
+        advertised.set(JSON.stringify(projection.value), projection.value);
+    }
+    return [...advertised.values()];
+};

package/dist/contracts/analysisDetail.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+/** Caller-selected delivery of completed analysis Evidence that supports retained views. */
+export const analysisDetailSchema = z
+    .enum(["complete", "summary"])
+    .default("complete")
+    .describe("complete returns the complete analysis Evidence inline. summary retains that complete Evidence in this session and returns its inspect_analysis_view summary; inspect pages, items or facets through normalized_result.parent_evidence_id.");
+/**
+ * Complete analysis Evidence, or that operation's summary view of its retained
+ * record. Callers pass the summary variant the handler actually returns so the
+ * advertised output does not accept other view kinds.
+ */
+export const analysisDetailOutputSchemaOf = (analysis, summary) => evidenceResultOf(z.union([analysis, summary]));

package/dist/contracts/analysisViewApiSurfaceExample.js

@@ -0,0 +1,68 @@
+/** Generated from the two-request apiSurfaceHar fixture through the HAR decoder and view service. */
+export const API_SURFACE_EXAMPLE = {
+    input: {
+        source: {
+            kind: "retained-evidence",
+            evidence_id: "ev_9e218c18bc6159ec9c8492a9130c286496fb1b6d9f03ec2f4ea3321ce2b15097",
+        },
+        view: {
+            kind: "api-surface",
+            offset: 0,
+            limit: 50,
+        },
+    },
+    output: {
+        parent_evidence_id: "ev_9e218c18bc6159ec9c8492a9130c286496fb1b6d9f03ec2f4ea3321ce2b15097",
+        parent_operation: "inspect_web_network_capture",
+        parent_digest: "9e218c18bc6159ec9c8492a9130c286496fb1b6d9f03ec2f4ea3321ce2b15097",
+        view_digest: "47c1859b7a86dd10770061767300bdb6ec177a9254e8dc7863d5ea8603343da6",
+        artifact: {
+            path: "/fixtures/api-surface.har",
+            sha256: "bf58e2c06e55bfe7e0628157c4ad027ce0aeb81a10e8edef8a7f95b8e5f14225",
+        },
+        coverage: {
+            status: "page",
+            examined: 1,
+            total: 1,
+            next_offset: null,
+            exhausted: true,
+        },
+        limitations: [
+            "Grouping does not establish handler identity, URL-space schemas or causality.",
+            "HAR text is producer-decoded Unicode. Original body bytes remain unknown unless content explicitly uses valid base64; declared sizes are preserved independently of retained bytes. mitmproxy 12.2.3 SaveHar may report null optional postData.text; that null is retained and omitted only from the upstream validation copy.",
+        ],
+        unknowns: [],
+        records: {
+            examined: 2,
+            total: 2,
+            excluded: 0,
+        },
+        templated_groups: 1,
+        groups: [
+            {
+                method: "GET",
+                origin: "https://api.example.test",
+                path_template: "/users/{numeric}",
+                templated_segments: [
+                    {
+                        segment_index: 1,
+                        rule: "numeric",
+                        basis: "inferred",
+                        observed_values: ["8812", "9031"],
+                    },
+                ],
+                record_ordinals: [0, 1],
+                statuses: [200, 404],
+                content_types: ["application/json", "text/plain"],
+                flags: ["mixed-statuses", "mixed-content-types"],
+            },
+        ],
+        excluded_records: [],
+        kind: "api-surface",
+        view: {
+            kind: "api-surface",
+            offset: 0,
+            limit: 50,
+        },
+    },
+};