rea-agents 6.3.0 → 6.5.0

package/dist/captures/parseFieldDiscovery.js

@@ -0,0 +1,66 @@
+export class FieldDiscoveryBudgetError extends Error {
+}
+export const FIELD_RECORD_BUDGET = 8 * 1024 * 1024;
+/** TShark -G fields: P/name/abbreviation or F/name/abbreviation/type/parent/base/mask/blurb. */
+export const parseFieldDiscovery = (text, input) => {
+    const copy = (value) => Buffer.from(value, "utf16le").toString("utf16le");
+    const query = input.query.toLowerCase();
+    const records = [];
+    let examined = 0, matching = 0, sourceLine = 0, budget = 0;
+    // Walk the bounded text once; allocate record objects only for the requested page.
+    for (let start = 0; start < text.length;) {
+        const end = text.indexOf("\n", start);
+        let line = text.slice(start, end < 0 ? text.length : end);
+        start = end < 0 ? text.length : end + 1;
+        sourceLine++;
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        const columns = line.split("\t", 9);
+        const [tag, name, abbreviation] = columns;
+        if (!((tag === "P" && columns.length === 3) ||
+            (tag === "F" && columns.length === 8)) ||
+            name === undefined ||
+            abbreviation === undefined ||
+            abbreviation === "")
+            throw new Error(`Malformed TShark field glossary record at line ${sourceLine}`);
+        if ((input.kind === "protocols") !== (tag === "P"))
+            continue;
+        examined++;
+        if (input.protocol !== null &&
+            (tag === "P" ? abbreviation : columns[4]) !== input.protocol)
+            continue;
+        if (![name, abbreviation, ...(tag === "F" ? [columns[7] ?? ""] : [])].some((value) => value.toLowerCase().includes(query)))
+            continue;
+        matching++;
+        if (matching <= input.offset ||
+            records.length >= (input.limit ?? Number.MAX_SAFE_INTEGER))
+            continue;
+        // Six bytes per source byte covers worst-case JSON escaping, plus record bookkeeping.
+        budget += Buffer.byteLength(line, "utf8") * 6 + 512;
+        if (budget > FIELD_RECORD_BUDGET)
+            throw new FieldDiscoveryBudgetError("Selected glossary records exceed the 8 MiB representation budget; narrow the query or page size");
+        // Detach retained fields from the much larger producer string.
+        records.push({
+            source_line: sourceLine,
+            kind: tag === "P" ? "protocol" : "field",
+            name: copy(name),
+            abbreviation: copy(abbreviation),
+            field_type: tag === "F" ? copy(columns[3] ?? "") : null,
+            parent_protocol: tag === "F" ? copy(columns[4] ?? "") : null,
+            display_base: tag === "F" ? copy(columns[5] ?? "") : null,
+            bitmask: tag === "F" ? copy(columns[6] ?? "") : null,
+            description: tag === "F" ? copy(columns[7] ?? "") : null,
+        });
+    }
+    if (sourceLine === 0)
+        throw new Error("TShark returned an empty field glossary");
+    return {
+        records,
+        output_window: {
+            examined,
+            matching,
+            returned: records.length,
+            has_more: Math.max(0, matching - input.offset) > records.length,
+        },
+    };
+};

package/dist/captures/parsePacketOutput.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { packetFieldsSchema } from "../domain/captures/packetCapture.js";
+// _index/_score are TShark export metadata, not captured packet fields.
+const producerSchema = z.array(z.object({ _source: z.object({ layers: packetFieldsSchema }) }));
+export const parsePacketOutput = (text, fields) => {
+    const decoded = JSON.parse(text);
+    const packets = producerSchema
+        .parse(decoded)
+        .map((packet) => packet._source.layers);
+    const selected = new Set(["frame.number", ...fields]);
+    let previous = 0n;
+    for (const packet of packets) {
+        const frame = BigInt(packet["frame.number"][0]);
+        if (frame <= previous ||
+            Object.keys(packet).some((name) => !selected.has(name)))
+            throw new AnalysisOutputError("inspect_packet_capture", "TShark returned unordered frames or unselected fields.");
+        previous = frame;
+    }
+    return packets;
+};

package/dist/catalogIdentity.js

@@ -4,20 +4,26 @@ import { z } from "zod";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
-const sortedToolContracts = [...TOOL_CONTRACTS].sort((left, right) => left.name.localeCompare(right.name));
-const createToolCatalog = () => sortedToolContracts.map((contract) => ({
+import { compareUnicodeCodePoints } from "./domain/unicodeCodePointOrder.js";
+import { advertisedInputJsonSchema } from "./contracts/toolSchemaMetadata.js";
+import { presentAdvertisedInputSchema, } from "./contracts/compactInputSchema.js";
+const sortByName = (contracts) => [...contracts].sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+const sortedToolContracts = sortByName(TOOL_CONTRACTS);
+/**
+ * Digested per-tool projection. Every contract field that changes what a
+ * client receives belongs here, including `returns_target_content`: a server
+ * that predates the untrusted-content framing must not digest equal to one
+ * that emits `_meta.provenance`, or a stale process would report aligned.
+ */
+const createToolCatalog = (contracts, compactPresentation) => contracts.map((contract) => ({
     name: contract.name,
     title: contract.title,
     surface: contract.kind,
     description: contract.description,
     effects: { ...contract.effects },
+    returns_target_content: contract.returnsTargetContent,
     annotations: contract.annotations,
-    input_schema: {
-        type: "object",
-        ...z.toJSONSchema(contract.inputSchema, {
-            unrepresentable: "any",
-        }),
-    },
+    input_schema: presentAdvertisedInputSchema(advertisedInputJsonSchema(contract), compactPresentation),
     output_schema: {
         type: "object",
         ...z.toJSONSchema(contract.outputSchema, {
@@ -25,51 +31,56 @@ const createToolCatalog = () => sortedToolContracts.map((contract) => ({
         }),
     },
 }));
-const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
+const createPromptCatalog = (contracts) => contracts
+    .map((contract) => ({
     name: contract.name,
     title: contract.title,
     description: contract.description,
+    objective: contract.objective,
     arguments: contract.arguments,
     steps: contract.steps,
-})).sort((left, right) => left.name.localeCompare(right.name));
+}))
+    .sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+const promptCatalog = createPromptCatalog(PROMPT_CONTRACTS);
 const digest = (value) => {
     const encoded = canonicalize(value);
     if (encoded === undefined)
         throw new TypeError("Catalog is not canonical JSON");
     return createHash("sha256").update(encoded).digest("hex");
 };
-const createCatalogDigests = () => {
-    const tools = createToolCatalog();
+/**
+ * Catalog digests over the given tool contracts. Exported so tests can prove
+ * which contract fields the identity covers; production uses
+ * {@link CATALOG_IDENTITY}.
+ */
+export const createCatalogDigests = (contracts = TOOL_CONTRACTS, promptContracts = PROMPT_CONTRACTS, compactPresentation = undefined) => {
+    const tools = createToolCatalog(sortByName(contracts), compactPresentation);
+    const prompts = createPromptCatalog(promptContracts);
     return {
         tools_sha256: digest(tools),
-        prompts_sha256: digest(promptCatalog),
+        prompts_sha256: digest(prompts),
         combined_sha256: digest({
             cli: CLI_COMMAND_NAMES,
             tools,
-            prompts: promptCatalog,
+            prompts,
         }),
     };
 };
-let catalogDigests;
-/** Stable, schema-sensitive identity; schema digests are computed on first use. */
-export const CATALOG_IDENTITY = {
-    counts: {
-        cli_commands: CLI_COMMAND_NAMES.length,
-        mcp_tools: sortedToolContracts.length,
-        mcp_prompts: promptCatalog.length,
-    },
-    get digests() {
-        return (catalogDigests ??= createCatalogDigests());
-    },
-    tools: sortedToolContracts.map(({ name, kind, effects, annotations }) => ({
-        name,
-        surface: kind,
-        effects: { ...effects },
-        annotations: {
-            read_only: annotations.readOnlyHint ?? false,
-            destructive: annotations.destructiveHint ?? false,
-            idempotent: annotations.idempotentHint ?? false,
-            open_world: annotations.openWorldHint ?? true,
+export const createCatalogIdentity = (compactPresentation = undefined) => {
+    const selectedPresentation = compactPresentation === undefined
+        ? undefined
+        : { budgetBytes: compactPresentation.budgetBytes };
+    let catalogDigests;
+    return {
+        counts: {
+            cli_commands: CLI_COMMAND_NAMES.length,
+            mcp_tools: sortedToolContracts.length,
+            mcp_prompts: promptCatalog.length,
+        },
+        get digests() {
+            return (catalogDigests ??= createCatalogDigests(TOOL_CONTRACTS, PROMPT_CONTRACTS, selectedPresentation));
         },
-    })),
+    };
 };
+/** Stable, schema-sensitive identity; schema digests are computed on first use. */
+export const CATALOG_IDENTITY = createCatalogIdentity();

package/dist/cli/adbCommands.js

@@ -0,0 +1,337 @@
+import { z } from "incur";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";
+import { createAdbDeviceAnalysisProvider } from "../composition/adb.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Expose the same explicit ADB requests through one-shot CLI commands. */
+export const registerAdbCommands = (cli, logger, environment, provider = createAdbDeviceAnalysisProvider(environment)) => {
+    const service = new AdbDeviceAnalysisService(provider);
+    const execute = (name, operation, input) => withCommandCancellation((signal) => logCliCommand(logger, name, async () => {
+        const result = await service.execute(operation, input, { signal });
+        try {
+            await provider.close();
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return projectAnalysisError(cause);
+            throw cause;
+        }
+        return result.ok ? result.value : projectAnalysisError(result.error);
+    }));
+    const serial = z
+        .string()
+        .min(1)
+        .describe("Device serial exactly as `adb devices` reports it");
+    cli.command(CLI_COMMANDS.inspectAdbClient, {
+        description: "Inspect the caller-selected adb client without contacting devices",
+        args: z.object({}),
+        run: () => execute(CLI_COMMANDS.inspectAdbClient, "inspect_adb_client", {}),
+    });
+    cli.command(CLI_COMMANDS.listAdbDevices, {
+        description: "List attached devices with serial, state, transport, and inferred kind",
+        args: z.object({}),
+        run: () => execute(CLI_COMMANDS.listAdbDevices, "list_adb_devices", {}),
+    });
+    cli.command(CLI_COMMANDS.inspectAdbDevice, {
+        description: "Inspect one device's build identity through a fixed getprop whitelist",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.inspectAdbDevice, "inspect_adb_device", args),
+    });
+    cli.command(CLI_COMMANDS.listAdbPackages, {
+        description: "List installed packages on one device with base APK device paths",
+        args: z.object({ serial }),
+        options: z.object({
+            scope: z
+                .enum(["all", "third_party", "system"])
+                .default("all")
+                .describe("Restrict to third-party or system packages"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.listAdbPackages, "list_adb_packages", {
+            serial: args.serial,
+            scope: options.scope,
+        }),
+    });
+    cli.command(CLI_COMMANDS.pullAdbPackage, {
+        description: "Pull one installed package's complete APK set with SHA-256 digests",
+        args: z.object({
+            serial,
+            package: z.string().min(1).describe("Installed package name"),
+        }),
+        options: z.object({
+            "output-directory": z
+                .string()
+                .min(1)
+                .describe("Local directory for the pulled APK set; a package-named subdirectory is created inside"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.pullAdbPackage, "pull_adb_package", {
+            serial: args.serial,
+            package: args.package,
+            output_directory: options["output-directory"],
+        }),
+    });
+    cli.command(CLI_COMMANDS.readAdbLogcat, {
+        description: "Read a bounded dump of the device log for one buffer",
+        args: z.object({ serial }),
+        options: z.object({
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(10_000)
+                .default(500)
+                .describe("Number of most recent lines to read"),
+            buffer: z
+                .enum(["main", "system", "radio", "events", "crash"])
+                .default("main")
+                .describe("Log buffer to read"),
+            pid: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Restrict to one process id"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.readAdbLogcat, "read_adb_logcat", {
+            serial: args.serial,
+            count: options.count,
+            buffer: options.buffer,
+            ...(options.pid === undefined ? {} : { pid: options.pid }),
+        }),
+    });
+    cli.command(CLI_COMMANDS.inspectAdbPackage, {
+        description: "Inspect one installed package's version, installer, and flags through dumpsys",
+        args: z.object({ serial, package: z.string().min(1).describe("Package") }),
+        run: ({ args }) => execute(CLI_COMMANDS.inspectAdbPackage, "inspect_adb_package", {
+            serial: args.serial,
+            package: args.package,
+        }),
+    });
+    cli.command(CLI_COMMANDS.pullAdbFile, {
+        description: "Pull one device file to a local copy with a SHA-256 digest",
+        args: z.object({
+            serial,
+            "device-path": z.string().min(1).describe("Absolute device path to pull"),
+        }),
+        options: z.object({
+            "output-directory": z
+                .string()
+                .min(1)
+                .describe("Local directory for the pulled file"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.pullAdbFile, "pull_adb_file", {
+            serial: args.serial,
+            device_path: args["device-path"],
+            output_directory: options["output-directory"],
+        }),
+    });
+    cli.command(CLI_COMMANDS.pushAdbFile, {
+        description: "Push one local file to the device; refuses existing targets without --overwrite",
+        args: z.object({
+            serial,
+            "local-path": z.string().min(1).describe("Existing local file"),
+            "device-path": z.string().min(1).describe("Absolute device destination"),
+        }),
+        options: z.object({
+            overwrite: z
+                .boolean()
+                .default(false)
+                .describe("Allow replacing an existing device file"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.pushAdbFile, "push_adb_file", {
+            serial: args.serial,
+            local_path: args["local-path"],
+            device_path: args["device-path"],
+            overwrite: options.overwrite,
+        }),
+    });
+    cli.command(CLI_COMMANDS.captureAdbScreen, {
+        description: "Capture one screen frame as a digested PNG",
+        args: z.object({ serial }),
+        options: z.object({
+            "output-directory": z
+                .string()
+                .min(1)
+                .describe("Local directory for screen.png"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.captureAdbScreen, "capture_adb_screen", {
+            serial: args.serial,
+            output_directory: options["output-directory"],
+        }),
+    });
+    cli.command(CLI_COMMANDS.listAdbProcesses, {
+        description: "List running processes exactly as ps -A reports them",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.listAdbProcesses, "list_adb_processes", args),
+    });
+    cli.command(CLI_COMMANDS.listAdbDirectory, {
+        description: "List one device directory with kinds, permissions, and sizes",
+        args: z.object({
+            serial,
+            "device-path": z
+                .string()
+                .min(1)
+                .describe("Absolute device directory path to list"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.listAdbDirectory, "list_adb_directory", {
+            serial: args.serial,
+            device_path: args["device-path"],
+        }),
+    });
+    cli.command(CLI_COMMANDS.listAdbFeatures, {
+        description: "List the device's declared hardware and software features",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.listAdbFeatures, "list_adb_features", args),
+    });
+    cli.command(CLI_COMMANDS.listAdbServices, {
+        description: "List the device's binder services and interfaces",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.listAdbServices, "list_adb_services", args),
+    });
+    cli.command(CLI_COMMANDS.inspectAdbDisplay, {
+        description: "Report the display's declared size and density",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.inspectAdbDisplay, "inspect_adb_display", args),
+    });
+    cli.command(CLI_COMMANDS.inspectAdbWindow, {
+        description: "Report the window manager's current focus declarations",
+        args: z.object({ serial }),
+        run: ({ args }) => execute(CLI_COMMANDS.inspectAdbWindow, "inspect_adb_window", args),
+    });
+    cli.command(CLI_COMMANDS.readAdbSetting, {
+        description: "Read one settings value from system, secure, or global",
+        args: z.object({
+            serial,
+            namespace: z
+                .enum(["system", "secure", "global"])
+                .describe("Settings namespace to read"),
+            key: z.string().min(1).describe("Setting key to read"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.readAdbSetting, "read_adb_setting", {
+            serial: args.serial,
+            namespace: args.namespace,
+            key: args.key,
+        }),
+    });
+    cli.command(CLI_COMMANDS.collectAdbBugreport, {
+        description: "Collect and digest one device-generated bugreport archive",
+        args: z.object({ serial }),
+        options: z.object({
+            "output-directory": z
+                .string()
+                .min(1)
+                .describe("Local directory for the bugreport zip"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.collectAdbBugreport, "collect_adb_bugreport", {
+            serial: args.serial,
+            output_directory: options["output-directory"],
+        }),
+    });
+    cli.command(CLI_COMMANDS.resolveAdbPackages, {
+        description: "Find installed packages by case-insensitive name substring",
+        args: z.object({
+            serial,
+            query: z.string().min(2).describe("Package-name substring to find"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.resolveAdbPackages, "resolve_adb_packages", {
+            serial: args.serial,
+            query: args.query,
+        }),
+    });
+    cli.command(CLI_COMMANDS.installAdbPackage, {
+        description: "Install one local APK; --replace requests reinstall mode to keep existing app data",
+        args: z.object({
+            serial,
+            "apk-path": z.string().min(1).describe("Local APK file to install"),
+        }),
+        options: z.object({
+            replace: z
+                .boolean()
+                .default(false)
+                .describe("Request reinstall mode and keep existing app data if present"),
+        }),
+        run: ({ args, options }) => execute(CLI_COMMANDS.installAdbPackage, "install_adb_package", {
+            serial: args.serial,
+            apk_path: args["apk-path"],
+            replace: options.replace,
+        }),
+    });
+    cli.command(CLI_COMMANDS.uninstallAdbPackage, {
+        description: "Uninstall one package and its data from the device",
+        args: z.object({
+            serial,
+            package: z.string().min(1).describe("Installed package to uninstall"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.uninstallAdbPackage, "uninstall_adb_package", {
+            serial: args.serial,
+            package: args.package,
+        }),
+    });
+    cli.command(CLI_COMMANDS.startAdbApp, {
+        description: "Start one installed app by resolving and launching its launcher activity",
+        args: z.object({
+            serial,
+            package: z.string().min(1).describe("Installed package to start"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.startAdbApp, "start_adb_app", {
+            serial: args.serial,
+            package: args.package,
+        }),
+    });
+    cli.command(CLI_COMMANDS.startAdbActivity, {
+        description: "Start an intent with am start (action, URI, component, extras)",
+        args: z.object({
+            serial,
+            action: z.string().min(1).describe("Intent action to start"),
+        }),
+        options: z.object({
+            "data-uri": z.string().min(1).optional().describe("Intent data URI (-d)"),
+            component: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Explicit component in package/activity form (-n)"),
+            extra: z
+                .array(z.string().min(1))
+                .default([])
+                .describe("Typed extra as type:key:value (string, boolean, int, long, float), repeatable"),
+        }),
+        run: ({ args, options }) => {
+            const extras = options.extra.map((entry) => {
+                const first = entry.indexOf(":");
+                const second = entry.indexOf(":", first + 1);
+                if (first === -1 || second === -1)
+                    throw new Error(`--extra expects type:key:value, received: ${entry}`);
+                return {
+                    type: entry.slice(0, first),
+                    key: entry.slice(first + 1, second),
+                    value: entry.slice(second + 1),
+                };
+            });
+            return execute(CLI_COMMANDS.startAdbActivity, "start_adb_activity", {
+                serial: args.serial,
+                action: args.action,
+                ...(options["data-uri"] === undefined
+                    ? {}
+                    : { data_uri: options["data-uri"] }),
+                ...(options.component === undefined
+                    ? {}
+                    : { component: options.component }),
+                extras,
+            });
+        },
+    });
+    cli.command(CLI_COMMANDS.stopAdbApp, {
+        description: "Force-stop every process of one package",
+        args: z.object({
+            serial,
+            package: z.string().min(1).describe("Package to force-stop"),
+        }),
+        run: ({ args }) => execute(CLI_COMMANDS.stopAdbApp, "stop_adb_app", {
+            serial: args.serial,
+            package: args.package,
+        }),
+    });
+};

package/dist/cli/analysisViewCommands.js

@@ -1,5 +1,8 @@
 import { z } from "incur";
 import { inspectAnalysisViewValidated } from "../application/analysisView/AnalysisViewService.js";
+import { readEvidenceBundle } from "../application/EvidenceBundleFiles.js";
+import { inspectEvidenceBundle } from "../application/investigation/InspectEvidenceBundle.js";
+import { getEvidenceBundleInputSchema, importEvidenceBundleInputSchema, } from "../contracts/sessionToolSchemas.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";
@@ -9,8 +12,43 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
 /** Project selected views of completed analysis Evidence through the CLI. */
 export const registerAnalysisViewCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectEvidenceBundle, {
+        description: "Inspect complete or selected discovery metadata from a local Evidence bundle",
+        args: z.object({
+            inputJson: z
+                .string()
+                .describe("JSON or JSON file with absolute path, detail and optional record filters"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.inspectEvidenceBundle, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.inspectEvidenceBundle);
+            if (!input.ok)
+                return input.error;
+            const schema = getEvidenceBundleInputSchema.safeExtend({
+                path: importEvidenceBundleInputSchema.shape.path,
+            });
+            const parsed = schema.safeParse(input.value);
+            if (!parsed.success)
+                return {
+                    error: "Evidence bundle inspection failed",
+                    ...projectAnalysisError(analysisInputErrorFromIssues(CLI_COMMANDS.inspectEvidenceBundle, parsed.error.issues, input.value)),
+                };
+            const loaded = await readEvidenceBundle(parsed.data.path);
+            if (!loaded.ok)
+                return {
+                    error: "Evidence bundle inspection failed",
+                    ...projectAnalysisError(loaded.error),
+                };
+            const result = inspectEvidenceBundle(loaded.value, parsed.data);
+            return result.ok
+                ? result.value
+                : {
+                    error: "Evidence bundle inspection failed",
+                    ...projectAnalysisError(result.error),
+                };
+        }),
+    });
     cli.command(CLI_COMMANDS.inspectAnalysisView, {
-        description: "Project a selected view of completed layout or JavaScript application Evidence JSON",
+        description: "Project a selected view of completed binary-layout, JavaScript application, native function, artifact-inventory, WASM, Mach-O, Interface Builder, EVM, managed, Android package, Dart AOT, web network capture or pcap Evidence JSON",
         args: z.object({
             inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
         }),

package/dist/cli/androidCommands.js

@@ -72,13 +72,19 @@ export const registerAndroidCommands = (cli, logger, environment) => {
         }),
     });
     cli.command(CLI_COMMANDS.traceAndroidReferences, {
-        description: "Trace incoming APK class or unique-method references",
+        description: "Trace incoming APK using nodes for a class or selected method",
         args: z.object({ path, className }),
         options: z.object({
             methodName: z
                 .string()
                 .optional()
-                .describe("Unique declared method name; omit for class references"),
+                .describe("Declared method name; omit for class references"),
+            overloadIndex: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Index among same-name methods from inspect-android-class"),
         }),
         run: ({ args, options }) => execute(CLI_COMMANDS.traceAndroidReferences, "trace_android_references", {
             path: args.path,
@@ -86,6 +92,9 @@ export const registerAndroidCommands = (cli, logger, environment) => {
             ...(options.methodName === undefined
                 ? {}
                 : { method_name: options.methodName }),
+            ...(options.overloadIndex === undefined
+                ? {}
+                : { overload_index: options.overloadIndex }),
         }),
     });
 };