rea-agents 6.4.0 → 6.7.0

package/dist/config/environment.js

@@ -4,18 +4,23 @@ 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 { ghidraDisabledAnalyzersSchema } from "./ghidraDisabledAnalyzers.js";
+import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS, DEFAULT_HOPPER_STARTUP_TIMEOUT_MS, DEFAULT_SWIFTC_COMPILE_TIMEOUT_MS, providerStartupTimeoutSchema, } from "./providerStartupTimeout.js";
 import { mcpInputSchemaProfileSchema } from "./mcpInputSchemaProfile.js";
+import { mcpOutputSchemaProfileSchema } from "./mcpOutputSchemaProfile.js";
 import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";
+import { parseLoaderArgs, parseStringArray } from "./parsers.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_MCP_OUTPUT_SCHEMA_PROFILE: mcpOutputSchemaProfileSchema.optional(),
     REA_IDA_MCP_CONFIG: z
         .string()
         .min(1)
         .refine(isAbsolute, "REA_IDA_MCP_CONFIG must be absolute")
         .optional(),
+    REA_JEB_MCP_TIMEOUT_MS: providerStartupTimeoutSchema.optional(),
     GHIDRA_INSTALL_DIR: z
         .string()
         .min(1)
@@ -31,9 +36,12 @@ const environmentSchema = z.object({
         .min(1)
         .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
         .optional(),
-    REA_GHIDRA_STARTUP_TIMEOUT_MS: ghidraStartupTimeoutSchema,
+    REA_GHIDRA_STARTUP_TIMEOUT_MS: providerStartupTimeoutSchema.default(DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS),
+    REA_HOPPER_STARTUP_TIMEOUT_MS: providerStartupTimeoutSchema.default(DEFAULT_HOPPER_STARTUP_TIMEOUT_MS),
+    REA_SWIFTC_COMPILE_TIMEOUT_MS: providerStartupTimeoutSchema.default(DEFAULT_SWIFTC_COMPILE_TIMEOUT_MS),
     REA_GHIDRA_LANGUAGE_ID: ghidraLanguageIdSchema.optional(),
     REA_GHIDRA_COMPILER_SPEC_ID: ghidraCompilerSpecIdSchema.optional(),
+    REA_GHIDRA_DISABLED_ANALYZERS: ghidraDisabledAnalyzersSchema.optional(),
     REA_GHIDRA_SEED_FILE: z
         .string()
         .min(1)
@@ -53,7 +61,41 @@ const environmentSchema = z.object({
         .default("info"),
     REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
 });
-export const parseEnvironment = (environment) => {
+/** Parse the JEB-only timeout at its isolated provider-composition boundary. */
+export const parseJebMcpTimeoutMs = (value) => {
+    if (value === undefined)
+        return ok(undefined);
+    const parsed = providerStartupTimeoutSchema.safeParse(value);
+    if (parsed.success)
+        return ok(parsed.data);
+    return err(new ConfigurationError("Invalid REA environment configuration", {
+        cause: parsed.error,
+        settings: [
+            {
+                setting: "REA_JEB_MCP_TIMEOUT_MS",
+                constraint: parsed.error.issues[0]?.message ?? "must be a valid timeout",
+            },
+        ],
+    }));
+};
+/** Parse individual settings before layered registration fragments are merged. */
+export const parseEnvironmentValues = (environment, unresolvedSettings = new Set()) => {
+    // Unknown client-specific entries are preserved by registration owners and
+    // still cross the child-process boundary. Check their byte admission before
+    // the known-setting schema strips them; never include rejected values.
+    // Cordis expression values stay unknown, but their literal names are known.
+    const keys = new Set([...Object.keys(environment), ...unresolvedSettings]);
+    const invalidEntries = [...keys]
+        .filter((key) => key.includes("\0") ||
+        (Object.hasOwn(environment, key) && environment[key]?.includes("\0")))
+        .map((setting) => ({
+        setting,
+        constraint: "Environment variable names and values must not contain NUL bytes",
+    }));
+    if (invalidEntries.length > 0)
+        return err(new ConfigurationError("Invalid REA environment configuration", {
+            settings: invalidEntries,
+        }));
     const parsed = environmentSchema.safeParse(environment);
     if (!parsed.success) {
         // Zod messages name the constraint, never the rejected value.
@@ -66,5 +108,38 @@ export const parseEnvironment = (environment) => {
             settings,
         }));
     }
-    return ok(parsed.data);
+    const { HOPPER_LOADER_ARGS_JSON: encodedLoaderArgs, REA_REFERENCE_SECRET_PATTERNS_JSON: encodedSecretPatterns, ...env } = parsed.data;
+    const loaderArgs = parseLoaderArgs(encodedLoaderArgs);
+    if (!loaderArgs.ok)
+        return loaderArgs;
+    const secretPatterns = parseStringArray(encodedSecretPatterns, "REA_REFERENCE_SECRET_PATTERNS_JSON");
+    if (!secretPatterns.ok)
+        return secretPatterns;
+    return ok({
+        ...env,
+        loaderArgs: loaderArgs.value,
+        referenceSecretPatterns: secretPatterns.value,
+    });
+};
+/** Validate complete runtime semantics without probing the host or persisting defaults. */
+export const parseEnvironment = (environment, 
+// Registration expressions are not evaluated; their absence is not proven.
+unresolvedSettings = new Set()) => {
+    const parsed = parseEnvironmentValues(environment, unresolvedSettings);
+    if (!parsed.ok)
+        return parsed;
+    const env = parsed.value;
+    // Ghidra's analyzeHeadless accepts -cspec only together with -processor.
+    if (env.REA_GHIDRA_COMPILER_SPEC_ID !== undefined &&
+        env.REA_GHIDRA_LANGUAGE_ID === undefined &&
+        !unresolvedSettings.has("REA_GHIDRA_LANGUAGE_ID"))
+        return err(new ConfigurationError("Invalid REA environment configuration", {
+            settings: [
+                {
+                    setting: "REA_GHIDRA_COMPILER_SPEC_ID",
+                    constraint: "requires REA_GHIDRA_LANGUAGE_ID",
+                },
+            ],
+        }));
+    return parsed;
 };

package/dist/config/ghidraDisabledAnalyzers.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const MAX_GHIDRA_DISABLED_ANALYZER_NAMES = 32;
+export const MAX_GHIDRA_DISABLED_ANALYZER_NAME_LENGTH = 120;
+// Ghidra's headless parser consumes `-`-prefixed arguments after a script path
+// as its own options, and REA joins the names with commas into one pre-script
+// argument, so a name can neither start with `-` nor contain a comma. The
+// remaining admitted characters keep the argument a single quotable token on
+// every supported launcher, including the Windows batch invocation.
+const ghidraAnalyzerNamePattern = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/u;
+/**
+ * Parse `REA_GHIDRA_DISABLED_ANALYZERS` into the Ghidra auto-analyzer names to
+ * disable before default auto-analysis, such as
+ * `Objective-C Message Analyzer`. Empty and blank entries are dropped; a list
+ * without names selects no override.
+ */
+export const ghidraDisabledAnalyzersSchema = z
+    .string()
+    .transform((value) => value
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0))
+    .refine((names) => names.length <= MAX_GHIDRA_DISABLED_ANALYZER_NAMES, `must list at most ${MAX_GHIDRA_DISABLED_ANALYZER_NAMES} analyzer names`)
+    .refine((names) => names.every((name) => name.length <= MAX_GHIDRA_DISABLED_ANALYZER_NAME_LENGTH), `must keep every analyzer name at most ${MAX_GHIDRA_DISABLED_ANALYZER_NAME_LENGTH} characters`)
+    .refine((names) => names.every((name) => ghidraAnalyzerNamePattern.test(name)), "must be Ghidra analyzer names starting with a letter or digit and containing only letters, digits, spaces, periods, underscores, and hyphens")
+    .transform((names) => (names.length === 0 ? undefined : names));

package/dist/config/homeDirectory.js

@@ -1,12 +1,15 @@
 import { userInfo } from "node:os";
+const firstNonempty = (...values) => values.find((value) => value !== undefined && value.length > 0);
 /** Resolve the caller's selected home before consulting the host account. */
 export const homeDirectoryFromEnvironment = (environment, platform) => {
+    const windowsDriveHome = environment.HOMEDRIVE !== undefined &&
+        environment.HOMEDRIVE.length > 0 &&
+        environment.HOMEPATH !== undefined &&
+        environment.HOMEPATH.length > 0
+        ? `${environment.HOMEDRIVE}${environment.HOMEPATH}`
+        : undefined;
     const selected = platform === "win32"
-        ? (environment.USERPROFILE ??
-            (environment.HOMEDRIVE !== undefined &&
-                environment.HOMEPATH !== undefined
-                ? `${environment.HOMEDRIVE}${environment.HOMEPATH}`
-                : environment.HOME))
-        : (environment.HOME ?? environment.USERPROFILE);
+        ? firstNonempty(environment.USERPROFILE, windowsDriveHome, environment.HOME)
+        : firstNonempty(environment.HOME, environment.USERPROFILE);
     return selected ?? userInfo().homedir;
 };

package/dist/config/mcpInputSchemaProfile.js

@@ -8,7 +8,11 @@ import { err, ok } from "../domain/result.js";
 // 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.';
+/** Select the exact compact presentation budget shared by registration and identity. */
+export const compactPresentationForMcpInputSchemaProfile = (profile) => profile === "compact"
+    ? { budgetBytes: COMPACT_INPUT_SCHEMA_BUDGET_BYTES }
+    : undefined;
+const profileConstraint = 'REA_MCP_INPUT_SCHEMA_PROFILE must be "full" (default) or "compact". The compact profile advertises bounded input schemas with fewer nested annotations for providers with schema compatibility constraints.';
 /** Parse the advertised input schema presentation selection. */
 export const parseMcpInputSchemaProfile = (value) => {
     if (value === undefined)

package/dist/config/mcpOutputSchemaProfile.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { err, ok } from "../domain/result.js";
+/** Select whether tools/list carries the large output contracts. */
+export const mcpOutputSchemaProfileSchema = z.enum(["full", "off"]);
+const profileConstraint = 'REA_MCP_OUTPUT_SCHEMA_PROFILE must be "full" (default) or "off". The off profile omits output schemas from tools/list while REA validates every successful result against its canonical tool contract and returns complete structured content.';
+/** Parse the output schema advertisement selection at server composition. */
+export const parseMcpOutputSchemaProfile = (value) => {
+    if (value === undefined)
+        return ok(undefined);
+    const parsed = mcpOutputSchemaProfileSchema.safeParse(value);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new ConfigurationError(profileConstraint, {
+            settings: [
+                {
+                    setting: "REA_MCP_OUTPUT_SCHEMA_PROFILE",
+                    constraint: profileConstraint,
+                },
+            ],
+        }));
+};

package/dist/config/parseConfig.js

@@ -1,52 +1,40 @@
-import { accessSync, constants } from "node:fs";
-import { join } from "node:path";
-import { ConfigurationError } from "../domain/configurationErrors.js";
-import { err, ok } from "../domain/result.js";
+import { accessSync, constants, statSync } from "node:fs";
+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);
-        return true;
+        return statSync(path).isFile();
     }
     catch {
         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) => {
-    const parsed = parseEnvironment(environment);
+    // JEB validates its own timeout during optional provider composition. It is
+    // not an AppConfig setting and must not prevent unrelated CLI/MCP startup.
+    // Registration validation still checks the complete environment directly.
+    const { REA_JEB_MCP_TIMEOUT_MS: _jebTimeout, ...appEnvironment } = environment;
+    const parsed = parseEnvironment(appEnvironment);
     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;
-    // 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
             ? {}
@@ -74,16 +62,22 @@ export const parseConfig = (environment) => {
         ...(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

@@ -113,7 +113,7 @@ export const ADB_TOOL_CONTRACTS = [
     {
         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.",
+        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),
@@ -157,7 +157,7 @@ export const ADB_TOOL_CONTRACTS = [
     {
         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.",
+        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),
@@ -203,7 +203,7 @@ export const ADB_TOOL_CONTRACTS = [
     {
         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.",
+        description: "Report the window manager's focus declarations with display context, original lines and explicit summary status. Reads `dumpsys window windows`, falling back to `displays` only when no focus field is declared. Singular fields are unknown for multiple contexts or repeated declarations; inspect focus_contexts for every observation. Read-only; no interaction occurs.",
         kind: "adb-provider",
         inputSchema: adbInputSchemas.inspect_adb_window,
         outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_window),
@@ -263,7 +263,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.",
+        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),
@@ -273,7 +273,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",
@@ -285,7 +285,7 @@ export const ADB_TOOL_CONTRACTS = [
     {
         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.",
+        description: "Request package removal for user 0 (`adb shell pm uninstall --user 0`) without data retention. 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),
@@ -299,7 +299,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.",
+        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),
@@ -313,7 +313,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.",
+        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),

package/dist/contracts/analysisDetail.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
-import { analysisViewResultSchema } from "../domain/analysisView/analysisView.js";
 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 the summary view of its retained record. */
-export const analysisDetailOutputSchemaOf = (analysis) => evidenceResultOf(z.union([analysis, analysisViewResultSchema]));
+/**
+ * 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_90073e9478eada1e2cc351b523e6ba9231c9b4bc9708773567b880094db9d4c7",
+        },
+        view: {
+            kind: "api-surface",
+            offset: 0,
+            limit: 50,
+        },
+    },
+    output: {
+        parent_evidence_id: "ev_90073e9478eada1e2cc351b523e6ba9231c9b4bc9708773567b880094db9d4c7",
+        parent_operation: "inspect_web_network_capture",
+        parent_digest: "90073e9478eada1e2cc351b523e6ba9231c9b4bc9708773567b880094db9d4c7",
+        view_digest: "c9494341920dc4cff6ecc6d8ed2c5e3abf15976642c253248e220d45f290ca7b",
+        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,
+        },
+    },
+};

package/dist/contracts/analysisViewToolContracts.js

@@ -1,19 +1,40 @@
+import { API_SURFACE_EXAMPLE } from "./analysisViewApiSurfaceExample.js";
 import { analysisViewResultSchema, inspectAnalysisViewInputSchema, } from "../domain/analysisView/analysisView.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
 const RETAINED_EXAMPLE_ID = `ev_${"a".repeat(64)}`;
-/** Selected views of already completed layout, JavaScript and native function Evidence. */
+/** Selected views of completed layout, JavaScript, native, inventory, WASM, Mach-O, Interface Builder and web network Evidence. */
 export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
     {
         name: "inspect_analysis_view",
         ...toolContractMetadata("inspect_analysis_view"),
         kind: "application",
-        description: "Inspect selected views of completed binary-layout, JavaScript application or native analyze_function Evidence without repeating analysis. Use an exact same-session retained evidence_id or portable inline Evidence. Select a summary, layout mitigations/linkage facet, one section/symbol/module, or a stable page. Module pages include assets, bundled and source modules; use node_id for ambiguous or unavailable paths. Native views select procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings/names, native API and high-pcode. Use nonnegative offset and a positive caller-selected limit (defaults 0 and 64); pseudocode uses UTF-16 code units, other native pages use rows. Returns artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the complete retained Evidence if needed.",
+        description: 'Inspect selected views of completed binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. For layout, JavaScript, inventory, WASM, Mach-O, Interface Builder, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, tool profile and execution/network states without reading WAT text. Select a layout mitigations/linkage facet, one section/symbol/module, or a stable page. Module pages include assets, bundled and source modules; use node_id for ambiguous or unavailable paths. Typed module references use view {kind: "javascript", collection: "modules", projection: "references", where: {path: "main.js", kind: "javascript-module"}, offset: 0, limit: 64}; where matches exact retained strings (null selects unavailable paths). Rows include canonical identity, retained source-range count and observation support states. Source coverage and selection remain explicit; exhausting matching rows does not prove runtime loading or complete analysis. For exact file/native facts and processing gaps, use view {kind: "javascript-facts", where: {paths: ["package.json"]}, property_keys: ["name", "operation", "analysis_status"]}. Rows page original observations with canonical identities and Evidence; missing properties remain omitted. Paths match recorded artifact-path/source-range locations; optional kinds filter nodes. To discover field names without values, opt into include_available_property_keys: true with property_keys: []. Canonical identity and Evidence are separate from properties; keep each node_id/observation_id pair together when composing results. Inventory uses view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json"], offset: 0, limit: 64}. Inventory views page nodes, occurrences, edges or integrity contradictions; occurrence logical_paths matches exact recorded strings (omitted means all available, [] means none). source_complete distinguishes complete inventories from partial source records; page exhaustion does not prove absence in a partial source. WASM views use kind wasm and facet sections/imports/exports/candidates/glue/wat/headers/details/tool_profile; text facets use UTF-16 code units and source forms remain exact. Mach-O views use kind macho and facet entrypoints/architectures/build_metadata/load_commands/dependencies/imports/exports/segments/provenance; source_exhaustive false means unreturned rows may exist. Interface Builder views use kind interface-builder and collection documents/nodes/edges/coverage; nodes and edges accept an exact document relative_path. EVM summary returns all inferred interface candidates, carrier/decoded identities and explicit unknowns without hex or duplicate stdout. EVM views use kind evm and facet functions/bytecode_hex/stdout/stderr; function pages preserve the original candidate rows, and text offsets/limits count UTF-16 code units (hex has two characters per decoded byte). Exhausting candidate pages does not establish global interface completeness. Managed artifact summaries preserve complete identity/classification, metadata status, module/MVID, frameworks, coverage and limitations without unrelated inventories. Managed pages use kind managed and collection references/resources/attributes, retaining source coverage and build-local token scope; page exhaustion does not establish complete metadata. Managed member summaries keep identity, selection with unmatched names, coverage and per-collection counts; managed-members pages use collection types/exported_types/fields/methods/member_refs/call_edges/field_accesses/user_strings and carry the source selection and coverage. Android package summaries retain all declarations, engine identity and counts without decoded manifest text. Android manifest pages use kind android, facet manifest, offset and limit in UTF-16 code units; source_status preserves partial decoded coverage even when the retained text page is exhausted. Dart AOT summary preserves target/ABI/library identity, snapshot headers and pool lower bounds. String pages use kind dart-aot, collection package_uris/dart_uris/class_like_tokens; source coverage remains partial when the producer says partial. Native function Evidence requires kind native: view: {kind: "native", facet: "procedure"}. Facets select procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings/names, native API and high-pcode. Use nonnegative offset and a positive caller-selected limit (defaults 0 and 64); pseudocode uses UTF-16 code units, other native pages use rows. Returns artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the complete retained Evidence if needed.',
         inputSchema: inspectAnalysisViewInputSchema,
         outputSchema: evidenceResultOf(analysisViewResultSchema),
         examples: [
             {
-                title: "Summarize retained JavaScript application Evidence",
+                title: "Read exact inventory paths from retained inspection Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "inventory",
+                        collection: "occurrences",
+                        logical_paths: ["package.json", "main.js"],
+                        offset: 0,
+                        limit: 32,
+                    },
+                },
+            },
+            {
+                title: "Group requests from retained HAR Evidence",
+                input: API_SURFACE_EXAMPLE.input,
+            },
+            {
+                title: "Summarize retained analysis Evidence, including WASM",
                 input: {
                     source: {
                         kind: "retained-evidence",
@@ -66,6 +87,47 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
                     },
                 },
             },
+            {
+                title: "Read selected metadata and native facts by exact retained paths",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "javascript-facts",
+                        where: { paths: ["package.json", "build/Release/addon.node"] },
+                        property_keys: [
+                            "name",
+                            "version",
+                            "bytes",
+                            "availability",
+                            "operation",
+                            "analysis_status",
+                        ],
+                        include_available_property_keys: true,
+                        offset: 0,
+                        limit: 32,
+                    },
+                },
+            },
+            {
+                title: "Read typed module reference facts from retained application Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "javascript",
+                        collection: "modules",
+                        projection: "references",
+                        where: { path: "main.js", kind: "javascript-module" },
+                        offset: 0,
+                        limit: 64,
+                    },
+                },
+            },
         ],
     },
 ];