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,