From 7a0140b4aa43276368058ab98826b77e040ea14f Mon Sep 17 00:00:00 2001 From: akushonkamen <74654766+akushonkamen@users.noreply.github.com> Date: Mon, 12 Oct 2026 01:07:22 +0800 Subject: [PATCH] fix(android): bound inline search Evidence with retained inventory provenance (#1890) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Focused and zero-match search_android_classes responses embedded every examined class name: JadxSession records each raw list_classes page into observed calls, those calls ride into Evidence raw_result on the registration path, and the complete inline Evidence is serialized into every tool response (issue #1850: 382,435 bytes for one match). When the server session retains Evidence, record the complete raw-call record first, then deliver a summary Evidence that keeps the pagination audit (totals, offsets, page sizes, elided item counts), the unchanged normalized matches and truthful coverage metadata, and links the retained complete inventory by Evidence ID. Sessions without retention keep the complete inline delivery, so complete CLI JSON output is unchanged and no provenance is discarded. 🤖 Generated with AI assistance (disclosure voluntary per repo policy) --- .../android/AndroidSearchEvidenceSummary.ts | 120 ++++++++++++++++ src/server/registerAndroidTools.ts | 25 +++- .../androidSearchEvidenceBudget.test.ts | 131 ++++++++++++++++++ tests/fixtures/android/jadx-mcp.mjs | 12 +- tests/fixtures/android/jadx.ts | 11 +- 5 files changed, 295 insertions(+), 4 deletions(-) create mode 100644 src/application/android/AndroidSearchEvidenceSummary.ts create mode 100644 tests/boundary/process/androidSearchEvidenceBudget.test.ts diff --git a/src/application/android/AndroidSearchEvidenceSummary.ts b/src/application/android/AndroidSearchEvidenceSummary.ts new file mode 100644 index 000000000..42c0fb80f --- /dev/null +++ b/src/application/android/AndroidSearchEvidenceSummary.ts @@ -0,0 +1,120 @@ +import type { EvidenceWriter } from "../investigation/InvestigationRecordPort.js"; +import { createEvidence, type Evidence } from "../../domain/evidence.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { JsonValue } from "../../domain/jsonValue.js"; +import { ok, type Result } from "../../domain/result.js"; + +/** + * Complete class-inventory pages dominate raw-call provenance for focused + * searches: one traversal embeds every examined class name regardless of the + * match count. The summary keeps the pagination audit inline (totals, page + * offsets and sizes, elided item counts) and links the retained record that + * still carries the complete inventory. + */ +const elideInventoryText = (text: string): string | undefined => { + let page: JsonValue; + try { + page = JSON.parse(text) as JsonValue; + } catch { + return undefined; + } + if ( + typeof page !== "object" || + page === null || + Array.isArray(page) || + !Array.isArray(page.items) + ) + return undefined; + const { items, ...audited } = page; + return JSON.stringify({ ...audited, items_omitted: items.length }); +}; + +/** Replace inventoried page bodies with their pagination audit. */ +const summarizeInventoryCall = (call: JsonValue): JsonValue => { + if ( + typeof call !== "object" || + call === null || + Array.isArray(call) || + call.operation !== "list_classes" + ) + return call; + const response = call.response; + if ( + typeof response !== "object" || + response === null || + Array.isArray(response) || + !Array.isArray(response.content) + ) + return call; + let elided = false; + const content = response.content.map((entry: JsonValue) => { + if ( + typeof entry !== "object" || + entry === null || + Array.isArray(entry) || + typeof entry.text !== "string" + ) + return entry; + const summarized = elideInventoryText(entry.text); + if (summarized === undefined) return entry; + elided = true; + return { ...entry, text: summarized }; + }); + return elided + ? { ...call, inventory_elided: true, response: { ...response, content } } + : call; +}; + +/** + * Retain the complete search Evidence — full raw provider calls included — + * in the session record, then deliver a bounded summary Evidence inline. + * Callers without a retaining session keep the complete inline delivery, so + * complete CLI JSON output is unchanged. Coverage metadata stays truthful in + * both copies: the examined inventory is never rewritten to matched-only. + */ +export const summarizeRetainedAndroidSearch = ( + evidence: Evidence, + recordEvidence: EvidenceWriter["recordEvidence"] | undefined, +): Result => { + if (recordEvidence === undefined) return ok(evidence); + const recorded = recordEvidence(evidence); + if (!recorded.ok) return recorded; + const subject = evidence.subject; + const raw = evidence.raw_result; + const summarized: JsonValue = + raw === null || + typeof raw !== "object" || + Array.isArray(raw) || + !Array.isArray(raw.calls) + ? raw + : { + ...raw, + complete_evidence_id: evidence.evidence_id, + calls: raw.calls.map(summarizeInventoryCall), + }; + return ok( + createEvidence( + subject === null + ? undefined + : { + path: subject.local_path, + sha256: subject.digest.sha256, + format: subject.format, + ...(subject.architecture === null + ? {} + : { architecture: subject.architecture }), + }, + evidence.provider, + { + operation: evidence.operation, + parameters: evidence.parameters, + result: evidence.normalized_result, + rawResult: summarized, + confidence: evidence.confidence, + limitations: evidence.limitations, + locations: evidence.locations, + evidenceLinks: [evidence.evidence_id], + }, + ), + ); +}; diff --git a/src/server/registerAndroidTools.ts b/src/server/registerAndroidTools.ts index 887e263dd..722bd6695 100644 --- a/src/server/registerAndroidTools.ts +++ b/src/server/registerAndroidTools.ts @@ -1,9 +1,13 @@ import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js"; +import { summarizeRetainedAndroidSearch } from "../application/android/AndroidSearchEvidenceSummary.js"; import { toolContract } from "../contracts/toolContracts.js"; import type { Logger } from "pino"; -import { createContractToolHandler } from "./contractToolHandler.js"; +import { + createContractToolHandler, + type ContractToolService, +} from "./contractToolHandler.js"; import { toolRegistrationOptions } from "./toolRegistrationOptions.js"; import type { WithAdmittedAnalysis } from "./analysisAdmission.js"; @@ -22,6 +26,23 @@ export const registerAndroidTools = ( recordEvidence, withAdmittedAnalysis, ); + // Focused class searches keep complete raw inventory in the retained + // record and deliver a bounded summary inline; the generic handler then + // records and delivers the summary as the search contract's Evidence. + const searchService: ContractToolService<"search_android_classes"> = { + execute: async (operation, input, options) => { + const executed = await service.execute(operation, input, options); + if (!executed.ok) return executed; + return summarizeRetainedAndroidSearch(executed.value, recordEvidence); + }, + }; + const searchHandler = createContractToolHandler( + server, + searchService, + logger, + recordEvidence, + withAdmittedAnalysis, + ); const packageContract = toolContract("inspect_android_package"); server.registerTool( packageContract.name, @@ -32,7 +53,7 @@ export const registerAndroidTools = ( server.registerTool( searchContract.name, toolRegistrationOptions(searchContract), - handler(searchContract), + searchHandler(searchContract), ); const classContract = toolContract("inspect_android_class"); server.registerTool( diff --git a/tests/boundary/process/androidSearchEvidenceBudget.test.ts b/tests/boundary/process/androidSearchEvidenceBudget.test.ts new file mode 100644 index 000000000..143c72189 --- /dev/null +++ b/tests/boundary/process/androidSearchEvidenceBudget.test.ts @@ -0,0 +1,131 @@ +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { expect, it as test, onTestFinished } from "vitest"; +import { androidResultSchemas } from "../../../src/domain/android/androidAnalysis.js"; +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { createServer } from "../../../src/server/createServer.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; +import { + createJadxProtocolFixture, + verifyJadxFixtureCleanup, +} from "../../fixtures/android/jadx.js"; + +const INVENTORY_CLASS_COUNT = 7096; + +/** Count inventoried names across raw call records: MCP pages ride in text content. */ +const rawInventoryNames = (raw: unknown): number => { + const calls = + ( + raw as { + calls?: { + operation: string; + response: { content?: { text?: string }[] }; + }[]; + } + ).calls ?? []; + return calls + .flatMap((call) => call.response.content ?? []) + .map((entry) => + entry.text === undefined ? {} : (JSON.parse(entry.text) as unknown), + ) + .filter((page) => Array.isArray((page as { items?: unknown[] }).items)) + .flatMap((page) => (page as { items: unknown[] }).items).length; +}; + +test("delivers bounded search_android_classes Evidence while retaining the complete inventory", async () => { + const { provider, apk, launches } = await createJadxProtocolFixture( + "normal", + undefined, + { classCount: INVENTORY_CLASS_COUNT - 1 }, + ); + const session = createTestBinarySession(() => { + throw new Error("APK analysis must not acquire a deep binary provider"); + }); + const server = createServer( + { kind: "session", session }, + { androidAnalysis: provider }, + ); + const client = new Client({ + name: "android-search-inventory-budget", + version: "1", + }); + onTestFinished(async () => { + await client.close(); + await server.close(); + await session.close(); + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + + const search = async (query: string) => + parseEvidence( + ( + await client.callTool({ + name: "search_android_classes", + arguments: { path: apk, query }, + }) + ).structuredContent, + ); + + const single = await search("Target"); + expect( + androidResultSchemas.search_android_classes.parse(single.normalized_result), + ).toMatchObject({ + query: "Target", + total_classes: INVENTORY_CLASS_COUNT, + matches: ["fixture.Target"], + coverage: "complete", + }); + // The inline raw record keeps the pagination audit, not the class names. + const singleRaw = JSON.stringify(single.raw_result); + expect(singleRaw).not.toContain("fixture.Class"); + expect(singleRaw).toContain("items_omitted"); + expect(Buffer.byteLength(JSON.stringify(single))).toBeLessThan(32 * 1024); + // The complete inventory stays locally retrievable through the retained record. + const completeId = single.evidence_links[0]; + expect(completeId).toBeDefined(); + expect(completeId).toBe( + (single.raw_result as { complete_evidence_id: string }) + .complete_evidence_id, + ); + const complete = session.evidenceById(completeId as string); + expect(complete).toBeDefined(); + expect(complete?.operation).toBe("search_android_classes"); + expect(rawInventoryNames(complete?.raw_result)).toBe(INVENTORY_CLASS_COUNT); + expect(JSON.stringify(complete?.raw_result)).toContain("fixture.Class7094"); + + const empty = await search("fixture.Missing"); + expect( + androidResultSchemas.search_android_classes.parse(empty.normalized_result), + ).toMatchObject({ + query: "fixture.Missing", + total_classes: INVENTORY_CLASS_COUNT, + matches: [], + coverage: "complete", + }); + expect(JSON.stringify(empty.raw_result)).not.toContain("fixture.Class"); + + await client.close(); + await server.close(); + await verifyJadxFixtureCleanup(launches); +}); + +test("keeps the complete search inventory inline without a retaining session", async () => { + const { service, apk, launches, provider } = await createJadxProtocolFixture( + "normal", + undefined, + { classCount: INVENTORY_CLASS_COUNT - 1 }, + ); + const result = await service.execute("search_android_classes", { + path: apk, + query: "Target", + }); + if (!result.ok) throw result.error; + // Complete CLI JSON output keeps the full raw provider inventory. + expect(rawInventoryNames(result.value.raw_result)).toBe( + INVENTORY_CLASS_COUNT, + ); + await provider.close(); + await verifyJadxFixtureCleanup(launches); +}); diff --git a/tests/fixtures/android/jadx-mcp.mjs b/tests/fixtures/android/jadx-mcp.mjs index e95029d53..4c008a7f4 100644 --- a/tests/fixtures/android/jadx-mcp.mjs +++ b/tests/fixtures/android/jadx-mcp.mjs @@ -10,10 +10,20 @@ const server = new McpServer({ version: mode === "empty-server-identity" ? "" : mode === "version" ? "99.0.0" : "1", }); +const requestedCount = Number.parseInt( + process.env.REA_FAKE_JADX_CLASS_COUNT ?? "", + 10, +); +const generatedCount = + Number.isInteger(requestedCount) && requestedCount >= 0 + ? requestedCount + : mode === "large-inventory" + ? 9000 + : 400; const classes = [ "fixture.Target", ...Array.from( - { length: mode === "large-inventory" ? 9000 : 400 }, + { length: generatedCount }, (_, index) => `fixture.Class${index}`, ), ]; diff --git a/tests/fixtures/android/jadx.ts b/tests/fixtures/android/jadx.ts index 49e17c2d5..373f3a624 100644 --- a/tests/fixtures/android/jadx.ts +++ b/tests/fixtures/android/jadx.ts @@ -27,6 +27,7 @@ const fixture = fileURLToPath(new URL("./jadx-mcp.mjs", import.meta.url)); export const createJadxProtocolFixture = async ( mode = "normal", cleanupFailure?: () => boolean, + inventory?: { readonly classCount?: number }, ) => { const root = await createTestTempDirectory("rea-android-boundary-"); const apk = join(root, "fixture.apk"); @@ -64,7 +65,15 @@ export const createJadxProtocolFixture = async ( command: process.execPath, arguments: [fixture], expectedCommand: process.execPath, - env: { ...options.env, REA_FAKE_JADX_MODE: mode }, + env: { + ...options.env, + REA_FAKE_JADX_MODE: mode, + ...(inventory?.classCount === undefined + ? {} + : { + REA_FAKE_JADX_CLASS_COUNT: String(inventory.classCount), + }), + }, }); launches.push({ runId: options.runId,