Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(native): inspect oversized retained function dossiers via bounded views
jhuang-twa9ee2360fd11
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex 5eedd9c14..7bf2fb76c 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -237,7 +237,12 @@ Ordinary responses keep their existing complete result contract.## Retained application Evidence inputs`inspect_analysis_view` projects a caller-selected view of already completed-`inspect_binary_layout` or `analyze_javascript_application` Evidence. Source is+`inspect_binary_layout`, `analyze_javascript_application`, or `analyze_function`+Evidence. Native views select procedure, pseudocode, assembly, callers/callees,+references, and high-pcode facets without starting a provider. Native offset+and limit default to 0 and 64; pseudocode uses UTF-16 code units and never+splits surrogate pairs, while other pages count rows. Unavailable facts and+provider limitations remain explicit. Source isan exact same-session retained reference or portable inline Evidence. Views area summary, a layout mitigations or linkage facet, one section/symbol/module, ora stable page with a caller-selected positive `limit`. Module pages includediff --git a/skill-src/reverse-engineer-anything/references/native-and-artifacts.md b/skill-src/reverse-engineer-anything/references/native-and-artifacts.mdindex f47017171..65b68c6b2 100644--- a/skill-src/reverse-engineer-anything/references/native-and-artifacts.md+++ b/skill-src/reverse-engineer-anything/references/native-and-artifacts.md@@ -34,6 +34,14 @@ cross-references. Addresses and recovered pseudocode are analysis observations,not original source. Provider unavailability and unsupported metadata remainunknown rather than false.+For a completed `analyze_function` dossier, use `inspect_analysis_view` with+`view: {kind: "native", facet: "value_flow_operations", offset: 0, limit: 32}`+and the exact retained Evidence ID to read selected facts without reanalysis.+Native facets also include procedure, pseudocode, assembly, callers/callees,+references, and value-flow summaries. Pseudocode offsets and limits count UTF-16+code units; use the returned `next_offset` for continuation. Provider limitations+and unavailable facts remain explicit; the complete parent Evidence is retained.+To see which functions or Objective-C methods a Mach-O actually calls in onerun, use `observe_native_calls` with explicit breakpoints and a bounded`duration_ms`/`max_events`. It launches a new process under LLDB, so the targetdiff --git a/src/application/analysisView/AnalysisViewService.test.ts b/src/application/analysisView/AnalysisViewService.test.tsindex 29289efae..b361e162f 100644--- a/src/application/analysisView/AnalysisViewService.test.ts+++ b/src/application/analysisView/AnalysisViewService.test.ts@@ -2,6 +2,8 @@ import { expect, it } from "vitest";import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";import { createEvidence, parseEvidence } from "../../domain/evidence.js";+import { functionDossierSchema } from "../../domain/hopperValues.js";+import { ghidraFunctionDossier } from "../../domain/ghidraValues.fixture.js";import {analysisViewJavaScriptAnalysisWithSource,analysisViewJavaScriptEvidence,@@ -9,6 +11,96 @@ import {} from "../../../tests/fixtures/analysisView.js";import { inspectAnalysisView } from "./AnalysisViewService.js";+it.each(["/fixtures/unknown.exe", ""])(+ "preserves recorded empty native identity fields: path=%j",+ (path) => {+ const original = functionDossierSchema.parse(ghidraFunctionDossier());+ const parent = createEvidence(+ { path, format: "pe", sha256: "c".repeat(64) },+ { id: "ghidra", name: "Ghidra", version: "12.1.4" },+ {+ operation: "analyze_function",+ parameters: {},+ result: {+ ...original,+ procedure: {+ ...original.procedure,+ address: "",+ body: { available: false, reason: "Not recorded" },+ },+ },+ },+ );+ const result = inspectAnalysisView({+ source: { kind: "inline", evidence: parent },+ view: {+ kind: "native",+ facet: "procedure",+ offset: 0,+ limit: 64,+ },+ });+ if (!result.ok) throw result.error;+ expect(result.value.normalized_result).toMatchObject({+ procedure_address: "",+ artifact: { path },+ item: { address: "" },+ });+ expect(result.value.locations).toEqual(+ path.length > 0 ? [{ kind: "artifact-path", path }] : [],+ );+ },+);++it("projects a small native view from an authenticated >10 MiB retained dossier", () => {+ const original = functionDossierSchema.parse(ghidraFunctionDossier());+ const parent = createEvidence(+ { path: "/fixtures/large.exe", format: "pe", sha256: "c".repeat(64) },+ { id: "ghidra", name: "Ghidra", version: "12.1.4" },+ {+ operation: "analyze_function",+ parameters: { address: "0x401000" },+ result: { ...original, pseudocode: "X".repeat(11 * 1024 * 1024) },+ limitations: ["Synthetic fixture"],+ },+ );+ const input = {+ source: {+ kind: "retained-evidence" as const,+ evidence_id: parent.evidence_id,+ },+ view: {+ kind: "native" as const,+ facet: "pseudocode" as const,+ offset: 0,+ limit: 128,+ },+ };+ const view = inspectAnalysisView(input, (id) =>+ id === parent.evidence_id ? parent : undefined,+ );+ if (!view.ok) throw view.error;+ expect(view.value.evidence_links).toEqual([parent.evidence_id]);+ expect(view.value.normalized_result).toMatchObject({+ kind: "native",+ parent_operation: "analyze_function",+ parent_evidence_id: parent.evidence_id,+ procedure_address: "0x401000",+ artifact: { path: "/fixtures/large.exe", sha256: "c".repeat(64) },+ coverage: { total: 11 * 1024 * 1024, examined: 128, next_offset: 128 },+ });+ expect(view.value.locations).toEqual([+ { kind: "artifact-path", path: "/fixtures/large.exe" },+ { kind: "address", address: "0x401000" },+ ]);+ expect(JSON.stringify(view.value).length).toBeLessThan(12000);+ expect(JSON.stringify(parent).length).toBeGreaterThan(10 * 1024 * 1024);+ expect(inspectAnalysisView(input, () => undefined)).toMatchObject({+ ok: false,+ error: { _tag: "EvidenceIntegrityError" },+ });+});+it("projects inline layout Evidence and retains a derived view record", () => {const parent = analysisViewLayoutEvidence();const result = inspectAnalysisView({diff --git a/src/application/analysisView/AnalysisViewService.ts b/src/application/analysisView/AnalysisViewService.tsindex 0d10d5fa8..7af6fb24a 100644--- a/src/application/analysisView/AnalysisViewService.ts+++ b/src/application/analysisView/AnalysisViewService.ts@@ -53,6 +53,13 @@ export const inspectAnalysisViewValidated = (operation: parent.operation,normalizedResult: parent.normalized_result,limitations: parent.limitations,+ artifact:+ parent.subject === null+ ? null+ : {+ path: parent.subject.local_path,+ sha256: parent.subject.digest.sha256,+ },},input.view,);@@ -126,7 +133,16 @@ const createAnalysisViewEvidence = (confidence: "derived",authority: parent.authority,limitations: result.limitations,- locations: [{ kind: "artifact-path", path: result.artifact.path }],+ locations: [+ ...(result.artifact.path.length > 0+ ? [{ kind: "artifact-path" as const, path: result.artifact.path }]+ : []),+ ...(result.kind === "native" &&+ result.procedure_address !== null &&+ result.procedure_address.length > 0+ ? [{ kind: "address" as const, address: result.procedure_address }]+ : []),+ ],evidenceLinks: [parent.evidence_id],});};diff --git a/src/cli/analysisViewCommands.ts b/src/cli/analysisViewCommands.tsindex a0deb0229..a193d2740 100644--- a/src/cli/analysisViewCommands.ts+++ b/src/cli/analysisViewCommands.ts@@ -18,7 +18,7 @@ export const registerAnalysisViewCommands = (): void => {cli.command(CLI_COMMANDS.inspectAnalysisView, {description:- "Project a selected view of completed layout or JavaScript application Evidence JSON",+ "Project a selected view of completed layout, JavaScript application or native function Evidence JSON",args: z.object({inputJson: z.string().describe("Inline workflow JSON or JSON file path"),}),diff --git a/src/contracts/analysisViewToolContracts.ts b/src/contracts/analysisViewToolContracts.tsindex b8f455767..be65b229f 100644--- a/src/contracts/analysisViewToolContracts.ts+++ b/src/contracts/analysisViewToolContracts.ts@@ -8,14 +8,14 @@ import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";const RETAINED_EXAMPLE_ID = `ev_${"a".repeat(64)}`;-/** Selected views of already completed layout and JavaScript analysis Evidence. */+/** Selected views of already completed layout, JavaScript and native function Evidence. */export const ANALYSIS_VIEW_TOOL_CONTRACTS = [{name: "inspect_analysis_view",...toolContractMetadata("inspect_analysis_view"),kind: "application",description:- "Inspect a selected view of completed binary-layout or JavaScript application 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 with a positive limit. Module pages contain JavaScript assets, bundled modules and source modules; use node_id when paths are ambiguous or unavailable. Returns selected facts inline with 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 retained Evidence when needed.",+ "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, callers/callees, references 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: [@@ -43,6 +43,21 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [},},},+ {+ title: "Page native high-pcode operations from retained Evidence",+ input: {+ source: {+ kind: "retained-evidence",+ evidence_id: RETAINED_EXAMPLE_ID,+ },+ view: {+ kind: "native",+ facet: "value_flow_operations",+ offset: 0,+ limit: 32,+ },+ },+ },{title: "Page module identities from retained application Evidence",input: {diff --git a/src/domain/analysisView/analysisView.test.ts b/src/domain/analysisView/analysisView.test.tsindex e3aabcf14..1fd6fb7f1 100644--- a/src/domain/analysisView/analysisView.test.ts+++ b/src/domain/analysisView/analysisView.test.ts@@ -1,6 +1,8 @@import { expect, it } from "vitest";import { resolveJavaScriptSourceMapReference } from "../javascript/javascriptSourceMapPaths.js";+import { functionDossierSchema } from "../hopperValues.js";+import { ghidraFunctionDossier } from "../ghidraValues.fixture.js";import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";import {analysisViewBindJavaScriptGraphs,@@ -48,21 +50,190 @@ const javascriptParent = (limitations: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.limitations,});-it("accepts caller-selected page sizes and rejects malformed bounds", () => {- const input = {- source: { kind: "retained-evidence", evidence_id: `ev_${"a".repeat(64)}` },- view: { kind: "page", collection: "sections", offset: 0, limit: 500 },- };- expect(inspectAnalysisViewInputSchema.safeParse(input).success).toBe(true);- for (const limit of [0, -1, 0.5, Infinity, Number.MAX_SAFE_INTEGER + 1])- expect(- inspectAnalysisViewInputSchema.safeParse({- ...input,- view: { ...input.view, limit },- }).success,- ).toBe(false);+const nativeParent = (+ result: unknown = ghidraFunctionDossier(),+): AnalysisViewParent => ({+ evidenceId: "ev_" + "b".repeat(64),+ operation: "analyze_function",+ normalizedResult: result,+ limitations: ["Retained provider limitation"],+ artifact: { path: "/fixtures/example.exe", sha256: "a".repeat(64) },+});++it("projects native procedure and bounded assembly and high-pcode with exact parent identity", () => {+ const parent = nativeParent();+ const procedure = projectAnalysisView(parent, {+ kind: "native",+ facet: "procedure",+ offset: 0,+ limit: 64,+ });+ if (!procedure.ok) throw procedure.error;+ expect(procedure.value).toMatchObject({+ kind: "native",+ parent_operation: "analyze_function",+ artifact: parent.artifact,+ item: { address: "0x401000" },+ });+ expect(procedure.value.view_digest).not.toBe(parent.evidenceId.slice(3));+ const assembly = projectAnalysisView(parent, {+ kind: "native",+ facet: "assembly",+ offset: 0,+ limit: 1,+ });+ if (!assembly.ok) throw assembly.error;+ expect(assembly.value).toMatchObject({+ coverage: { examined: 1, total: 2, next_offset: 1 },+ item: ["0x401000: CALL 0x401020"],+ });+ const flow = projectAnalysisView(parent, {+ kind: "native",+ facet: "value_flow_operations",+ offset: 0,+ limit: 1,+ });+ if (!flow.ok) throw flow.error;+ expect(flow.value).toMatchObject({ item: [{ opcode: "COPY" }] });+});++it("rejects invalid native parents, unsupported source operations and singleton offsets", () => {+ const view = {+ kind: "native",+ facet: "assembly",+ offset: 0,+ limit: 4,+ } as const;+ expect(projectAnalysisView(nativeParent({}), view)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ expect(+ projectAnalysisView({ ...nativeParent(), artifact: null }, view),+ ).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ expect(projectAnalysisView(layoutParent(), view)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ expect(projectAnalysisView(javascriptParent(), view)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+ expect(+ projectAnalysisView(nativeParent(), {+ kind: "native",+ facet: "procedure",+ offset: 1,+ limit: 2,+ }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisInputError" } });+});++it("preserves native API limitations and unavailable residual unknowns", () => {+ const original = functionDossierSchema.parse(ghidraFunctionDossier());+ const view = {+ kind: "native",+ facet: "procedure",+ offset: 0,+ limit: 64,+ } as const;+ const unavailable = projectAnalysisView(+ nativeParent({+ ...original,+ native_api: {+ available: false,+ reason: "No decompiler",+ residual_unknowns: ["Calling convention unresolved"],+ },+ }),+ view,+ );+ if (!unavailable.ok) throw unavailable.error;+ expect(unavailable.value.unknowns).toContain("Calling convention unresolved");+ const available = projectAnalysisView(nativeParent(), view);+ if (!available.ok) throw available.error;+ if (!original.native_api?.available) throw new Error("expected API fixture");+ expect(available.value.limitations).toEqual(+ expect.arrayContaining(original.native_api.limitations),+ );+});++it("reports the malformed native dossier field", () => {+ const result = projectAnalysisView(+ nativeParent({+ ...functionDossierSchema.parse(ghidraFunctionDossier()),+ pseudocode: 12,+ }),+ {+ kind: "native",+ facet: "pseudocode",+ offset: 0,+ limit: 64,+ },+ );+ expect(result).toMatchObject({+ ok: false,+ error: {+ issues: expect.arrayContaining([+ expect.objectContaining({+ path: ["source", "normalized_result", "pseudocode"],+ }),+ ]),+ },+ });});+it("native pseudocode pages do not split surrogate pairs", () => {+ const original = functionDossierSchema.parse(ghidraFunctionDossier());+ const parent = nativeParent({ ...original, pseudocode: "ab😀cd" });+ expect(+ projectAnalysisView(parent, {+ kind: "native",+ facet: "pseudocode",+ offset: 3,+ limit: 2,+ }),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisInputError" } });+ const safe = projectAnalysisView(parent, {+ kind: "native",+ facet: "pseudocode",+ offset: 2,+ limit: 3,+ });+ if (!safe.ok) throw safe.error;+ expect(safe.value).toMatchObject({+ item: { text: "😀c", unit: "utf16-code-units" },+ coverage: { examined: 3, next_offset: 5 },+ });+});++it.each([+ { kind: "page", collection: "sections", offset: 0, limit: 500 },+ { kind: "native", facet: "assembly", offset: 0, limit: 500 },+])(+ "accepts caller-selected page sizes and rejects malformed bounds: $kind",+ (view) => {+ const input = {+ source: {+ kind: "retained-evidence",+ evidence_id: `ev_${"a".repeat(64)}`,+ },+ view,+ };+ expect(inspectAnalysisViewInputSchema.safeParse(input).success).toBe(true);+ for (const limit of [0, -1, 0.5, Infinity, Number.MAX_SAFE_INTEGER + 1])+ expect(+ inspectAnalysisViewInputSchema.safeParse({+ ...input,+ view: { ...input.view, limit },+ }).success,+ ).toBe(false);+ },+);+it("projects layout summary, facet, item, and stable pages", () => {const parent = layoutParent();const layout = analysisViewLayoutFixture();diff --git a/src/domain/analysisView/analysisView.ts b/src/domain/analysisView/analysisView.tsindex efb9f5d44..db2d2dbac 100644--- a/src/domain/analysisView/analysisView.ts+++ b/src/domain/analysisView/analysisView.ts@@ -12,6 +12,7 @@ import { jsonObjectSchema, jsonValueSchema } from "../jsonValue.js";import { err, ok, type Result } from "../result.js";import type { AnalysisError } from "../analysisErrorBase.js";import { binaryLayoutSchema } from "../native/binaryLayout.js";+import { functionDossierSchema } from "../hopperValues.js";import {parseOwnedJavaScriptApplicationAnalysisSteps,type JavaScriptApplicationAnalysisResult,@@ -19,6 +20,7 @@ import {import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";import { projectBinaryLayoutView } from "./binaryLayoutView.js";import { projectJavaScriptApplicationView } from "./javascriptApplicationView.js";+import { projectNativeFunctionView } from "./nativeFunctionView.js";/** Public name of the selected-view workflow. */export const INSPECT_ANALYSIS_VIEW_OPERATION = "inspect_analysis_view" as const;@@ -73,12 +75,35 @@ const pageViewSchema = z.strictObject({limit: z.number().int().positive(),});+/** Bounded native function facets of already authenticated analyze_function Evidence. */+const nativeViewSchema = z.strictObject({+ kind: z.literal("native"),+ facet: z.enum([+ "procedure",+ "pseudocode",+ "assembly",+ "callers",+ "callees",+ "incoming_references",+ "outgoing_references",+ "value_flow_summary",+ "value_flow_operations",+ "value_flow_def_use",+ "value_flow_effects",+ "value_flow_parameters",+ "value_flow_parameter_uses",+ ]),+ offset: z.number().int().nonnegative().default(0),+ limit: z.number().int().positive().default(64),+});+/** Caller-selected projection of already completed analysis Evidence. */export const analysisViewRequestSchema = z.discriminatedUnion("kind", [summaryViewSchema,facetViewSchema,itemViewSchema,pageViewSchema,+ nativeViewSchema,]);/** Inline Evidence or an exact same-session retained reference. */@@ -108,7 +133,9 @@ const coverageSchema = z.strictObject({});const artifactSchema = z.strictObject({- path: z.string().min(1),+ path: z+ .string()+ .describe("Exact recorded artifact path, including an empty string."),sha256: digestSchema,});@@ -150,6 +177,7 @@ const viewResultBase = {parent_operation: z.enum(["inspect_binary_layout","analyze_javascript_application",+ "analyze_function",]),parent_digest: digestSchema,view_digest: digestSchema,@@ -185,6 +213,13 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [items: z.array(jsonValueSchema),...viewResultBase,}),+ z.strictObject({+ kind: z.literal("native"),+ view: nativeViewSchema,+ procedure_address: z.string().nullable(),+ item: jsonValueSchema,+ ...viewResultBase,+ }),]);export type AnalysisViewRequest = z.output<typeof analysisViewRequestSchema>;@@ -200,6 +235,7 @@ export interface AnalysisViewParent {readonly operation: string;readonly normalizedResult: unknown;readonly limitations: readonly string[];+ readonly artifact?: { readonly path: string; readonly sha256: string } | null;}/** Construct a typed input failure for one selected-view constraint. */@@ -216,7 +252,11 @@ export type UnsignedAnalysisView =>| Omit<Extract<AnalysisViewResult, { readonly kind: "facet" }>, "view_digest">| Omit<Extract<AnalysisViewResult, { readonly kind: "item" }>, "view_digest">- | Omit<Extract<AnalysisViewResult, { readonly kind: "page" }>, "view_digest">;+ | Omit<Extract<AnalysisViewResult, { readonly kind: "page" }>, "view_digest">+ | Omit<+ Extract<AnalysisViewResult, { readonly kind: "native" }>,+ "view_digest"+ >;/** Attach the content digest that must change when projected bytes change. */export const sealAnalysisView = (@@ -261,7 +301,7 @@ const unsupportedParent = (new AnalysisUnsupportedTargetError(INSPECT_ANALYSIS_VIEW_OPERATION,parentArtifactPath(parent),- `Parent Evidence operation ${JSON.stringify(parent.operation)} is not inspect_binary_layout or analyze_javascript_application.`,+ `Parent Evidence operation ${JSON.stringify(parent.operation)} is not inspect_binary_layout, analyze_javascript_application or analyze_function.`,);const parentArtifactPath = (parent: AnalysisViewParent): string => {@@ -327,5 +367,22 @@ export const projectAnalysisView = ();return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;}+ if (parent.operation === "analyze_function") {+ const native = functionDossierSchema.safeParse(parent.normalizedResult);+ if (!native.success)+ return err(+ analysisInputErrorFromIssues(+ INSPECT_ANALYSIS_VIEW_OPERATION,+ native.error.issues.map((issue) => ({+ ...issue,+ path: ["source", "normalized_result", ...issue.path],+ })),+ { source: { normalized_result: parent.normalizedResult } },+ { cause: native.error },+ ),+ );+ const projected = projectNativeFunctionView(parent, native.data, view);+ return projected.ok ? ok(sealAnalysisView(projected.value)) : projected;+ }return err(unsupportedParent(parent));};diff --git a/src/domain/analysisView/binaryLayoutView.ts b/src/domain/analysisView/binaryLayoutView.tsindex 5a52904a8..13a9b766f 100644--- a/src/domain/analysisView/binaryLayoutView.ts+++ b/src/domain/analysisView/binaryLayoutView.ts@@ -152,6 +152,10 @@ export const projectBinaryLayoutView = (view: AnalysisViewRequest,): Result<UnsignedAnalysisView, AnalysisError> => {const shared = parentFields(parent, layout);+ if (view.kind === "native")+ return err(+ layoutIncompatible("Native views require analyze_function Evidence."),+ );if (view.kind === "summary")return ok({kind: "summary",diff --git a/src/domain/analysisView/javascriptApplicationView.ts b/src/domain/analysisView/javascriptApplicationView.tsindex 5216c72b4..d6e994fc9 100644--- a/src/domain/analysisView/javascriptApplicationView.ts+++ b/src/domain/analysisView/javascriptApplicationView.ts@@ -243,6 +243,10 @@ export const projectJavaScriptApplicationView = (): Result<UnsignedAnalysisView, AnalysisError> => {const shared = parentFields(parent, analysis);const modules = moduleEntries(analysis.graph.nodes);+ if (view.kind === "native")+ return err(+ jsIncompatible("Native views require analyze_function Evidence."),+ );if (view.kind === "summary")return ok({kind: "summary",diff --git a/src/domain/analysisView/nativeFunctionView.ts b/src/domain/analysisView/nativeFunctionView.tsnew file mode 100644index 000000000..d17f69b03--- /dev/null+++ b/src/domain/analysisView/nativeFunctionView.ts@@ -0,0 +1,202 @@+import type { AnalysisError } from "../analysisErrorBase.js";+import { uniqueSorted } from "../canonicalOrdering.js";+import type { FunctionDossier } from "../hopperValues.js";+import { jsonValueSchema } from "../jsonValue.js";+import { err, ok, type Result } from "../result.js";+import {+ analysisViewInputError,+ type AnalysisViewCoverage,+ type AnalysisViewParent,+ type AnalysisViewRequest,+ type UnsignedAnalysisView,+} from "./analysisView.js";+import {+ completeWithinViewCoverage,+ pageViewCoverage,+} from "./analysisViewCoverage.js";++type Artifact = { readonly path: string; readonly sha256: string };++const viewError = (message: string): AnalysisError =>+ analysisViewInputError([+ { path: ["view"], reason: "invalid_value", message },+ ]);++const parentFields = (+ parent: AnalysisViewParent,+ dossier: FunctionDossier,+ artifact: Artifact,+) => {+ const flow = dossier.native_value_flow;+ const api = dossier.native_api;+ const unknowns: string[] = [];+ if (flow === null) unknowns.push("native_value_flow was not recorded");+ else if (!flow.available)+ unknowns.push("native_value_flow unavailable: " + flow.reason);+ else if (flow.truncated)+ unknowns.push(+ "native_value_flow is truncated; omitted observations remain unknown",+ );+ if (api === null) unknowns.push("native_api was not recorded");+ else if (!api.available)+ unknowns.push(+ "native_api unavailable: " + api.reason,+ ...api.residual_unknowns,+ );+ return {+ parent_evidence_id: parent.evidenceId,+ parent_operation: "analyze_function" as const,+ parent_digest: parent.evidenceId.slice(3),+ procedure_address: dossier.procedure.address,+ artifact,+ limitations: uniqueSorted([+ ...parent.limitations,+ ...dossier.limitations,+ ...(flow?.limitations ?? []),+ ...(api?.available ? api.limitations : []),+ ]),+ unknowns: uniqueSorted(unknowns),+ };+};++const pseudocodePage = (+ body: string,+ offset: number,+ limit: number,+): Result<+ {+ readonly item: { readonly text: string; readonly unit: "utf16-code-units" };+ readonly coverage: AnalysisViewCoverage;+ },+ AnalysisError+> => {+ const start = Math.min(offset, body.length);+ const high = (n: number) => n >= 0xd800 && n <= 0xdbff;+ const low = (n: number) => n >= 0xdc00 && n <= 0xdfff;+ if (+ start > 0 &&+ start < body.length &&+ high(body.charCodeAt(start - 1)) &&+ low(body.charCodeAt(start))+ )+ return err(viewError("Pseudocode offset splits a UTF-16 surrogate pair."));+ let end = Math.min(start + limit, body.length);+ if (+ end > start &&+ end < body.length &&+ high(body.charCodeAt(end - 1)) &&+ low(body.charCodeAt(end))+ )+ end--;+ if (end === start && start < body.length)+ return err(+ viewError(+ "Increase pseudocode limit to include the next complete Unicode character.",+ ),+ );+ return ok({+ item: { text: body.slice(start, end), unit: "utf16-code-units" },+ coverage: pageViewCoverage(start, end - start, body.length),+ });+};++const nativeRows = (+ dossier: FunctionDossier,+ facet: Exclude<+ Extract<AnalysisViewRequest, { readonly kind: "native" }>["facet"],+ "procedure" | "pseudocode" | "value_flow_summary"+ >,+) => {+ const sourceFlow = dossier.native_value_flow;+ const flow = sourceFlow?.available ? sourceFlow : undefined;+ return {+ assembly: dossier.assembly,+ callers: dossier.callers,+ callees: dossier.callees,+ incoming_references: dossier.incoming_references,+ outgoing_references: dossier.outgoing_references,+ value_flow_operations: flow?.operations,+ value_flow_def_use: flow?.def_use,+ value_flow_effects: flow?.effects,+ value_flow_parameters: flow?.parameters,+ value_flow_parameter_uses: flow?.parameter_uses,+ }[facet];+};++/** Project bounded native function facets from complete retained Evidence without reanalysis. */+export const projectNativeFunctionView = (+ parent: AnalysisViewParent,+ dossier: FunctionDossier,+ view: AnalysisViewRequest,+): Result<UnsignedAnalysisView, AnalysisError> => {+ if (view.kind !== "native")+ return err(viewError("analyze_function Evidence requires a native view."));+ const artifact = parent.artifact;+ if (!artifact)+ return err(+ analysisViewInputError([+ {+ path: ["source", "subject"],+ reason: "invalid_value",+ message:+ "Native function Evidence requires an artifact-bound subject.",+ },+ ]),+ );+ const common = parentFields(parent, dossier, artifact);+ const singleton = (item: unknown): UnsignedAnalysisView => ({+ kind: "native",+ view,+ item: jsonValueSchema.parse(item),+ coverage: completeWithinViewCoverage(1, 1),+ ...common,+ });+ const flow = dossier.native_value_flow;+ if (view.facet === "procedure" || view.facet === "value_flow_summary") {+ if (view.offset !== 0)+ return err(viewError("Singleton native facets require offset 0."));+ if (view.facet === "procedure") return ok(singleton(dossier.procedure));+ const status =+ flow === null+ ? { available: false, reason: "not recorded" }+ : !flow.available+ ? { available: false, reason: flow.reason }+ : {+ available: true,+ provenance: flow.provenance,+ truncated: flow.truncated,+ omitted_operations_lower_bound:+ flow.omitted_operations_lower_bound,+ known_omitted_inputs: flow.known_omitted_inputs,+ known_omitted_edges: flow.known_omitted_edges,+ operations: flow.operations.length,+ def_use: flow.def_use.length,+ effects: flow.effects.length,+ parameters: flow.parameters.length,+ parameter_uses: flow.parameter_uses.length,+ };+ return ok(singleton(status));+ }+ if (view.facet === "pseudocode") {+ const page = pseudocodePage(dossier.pseudocode, view.offset, view.limit);+ return page.ok+ ? ok({ kind: "native", view, ...page.value, ...common })+ : page;+ }+ const rows = nativeRows(dossier, view.facet);+ if (rows === undefined)+ return ok(+ singleton({+ available: false,+ reason: flow?.available === false ? flow.reason : "not recorded",+ }),+ );+ const items = rows.slice(view.offset, view.offset + view.limit);+ return ok({+ kind: "native",+ view,+ item: jsonValueSchema.parse(items),+ coverage: pageViewCoverage(view.offset, items.length, rows.length),+ ...common,+ });+};diff --git a/tests/boundary/cli/analysisViewCli.test.ts b/tests/boundary/cli/analysisViewCli.test.tsindex 86e0d9b27..2abaf700a 100644--- a/tests/boundary/cli/analysisViewCli.test.ts+++ b/tests/boundary/cli/analysisViewCli.test.ts@@ -7,6 +7,8 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { cliTest } from "../../support/cli/cliFixture.js";import { analysisViewLayoutEvidence } from "../../fixtures/analysisView.js";+import { createEvidence } from "../../../src/domain/evidence.js";+import { ghidraFunctionDossier } from "../../../src/domain/ghidraValues.fixture.js";cliTest("projects one section from a JSON file of inline layout Evidence",async ({ cli }) => {@@ -43,6 +45,48 @@ cliTest(},);+cliTest(+ "projects native function pseudocode without requiring Ghidra",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-native-view-cli-");+ const parent = createEvidence(+ { path: "/fixtures/native.exe", format: "pe", sha256: "a".repeat(64) },+ { id: "ghidra", name: "Ghidra", version: "12.1.4" },+ {+ operation: "analyze_function",+ parameters: { address: "0x401000" },+ result: ghidraFunctionDossier(),+ },+ );+ const input = join(root, "native-view.json");+ await writeFile(+ input,+ JSON.stringify({+ source: { kind: "inline", evidence: parent },+ view: { kind: "native", facet: "pseudocode", offset: 0, limit: 12 },+ }),+ );+ const result = await cli.run({+ arguments: ["inspect-analysis-view", input, "--json"],+ environment: { HOME: root, XDG_CONFIG_HOME: root, XDG_CACHE_HOME: root },+ });+ expect(result.exitCode).toBe(0);+ expect(result.json).toMatchObject({+ operation: "inspect_analysis_view",+ normalized_result: {+ kind: "native",+ parent_evidence_id: parent.evidence_id,+ procedure_address: "0x401000",+ item: { text: "int fixture_", unit: "utf16-code-units" },+ },+ locations: [+ { kind: "artifact-path", path: "/fixtures/native.exe" },+ { kind: "address", address: "0x401000" },+ ],+ });+ },+);+cliTest("rejects malformed JSON before projection", async ({ cli }) => {const root = await createTestTempDirectory("rea-analysis-view-cli-bad-");const result = await cli.run({diff --git a/tests/boundary/mcp/analysisViewMcp.test.ts b/tests/boundary/mcp/analysisViewMcp.test.tsindex 3edeffba7..3c15312aa 100644--- a/tests/boundary/mcp/analysisViewMcp.test.ts+++ b/tests/boundary/mcp/analysisViewMcp.test.ts@@ -6,7 +6,9 @@ import { z } from "zod";import { BinaryLayoutService } from "../../../src/application/binaryDiagnostics/BinaryLayoutService.js";import { toolContract } from "../../../src/contracts/toolContracts.js";-import { parseEvidence } from "../../../src/domain/evidence.js";+import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";+import { functionDossierSchema } from "../../../src/domain/hopperValues.js";+import { ghidraFunctionDossier } from "../../../src/domain/ghidraValues.fixture.js";import { ok } from "../../../src/domain/result.js";import {createJavaScriptApplicationGraph,@@ -109,6 +111,68 @@ it("advertises exact schemas and projects one layout section from retained Evide);});+it("delivers a bounded native dossier view over MCP without a Ghidra provider or lost connection", async () => {+ const { client, session } = await connect();+ const original = functionDossierSchema.parse(ghidraFunctionDossier());+ const parent = createEvidence(+ {+ path: "/fixtures/oversized-native.exe",+ format: "pe",+ sha256: "b".repeat(64),+ },+ { id: "ghidra", name: "Ghidra", version: "12.1.4" },+ {+ operation: "analyze_function",+ parameters: { address: "0x401000" },+ result: { ...original, pseudocode: "X".repeat(11 * 1024 * 1024) },+ },+ );+ expect(session.recordEvidence(parent).ok).toBe(true);+ const advertised = (await client.listTools()).tools.find(+ (tool) => tool.name === "inspect_analysis_view",+ );+ if (advertised?.outputSchema === undefined)+ throw new Error("missing view schemas");+ const ajv = new Ajv2020({ strict: false, validateFormats: false });+ const inputSchema: Record<string, unknown> = advertised.inputSchema;+ const outputSchema: Record<string, unknown> = advertised.outputSchema;+ const arguments_ = {+ source: { kind: "retained-evidence", evidence_id: parent.evidence_id },+ view: { kind: "native", facet: "pseudocode", offset: 0, limit: 500 },+ };+ expect(ajv.validateSchema(inputSchema)).toBe(true);+ expect(ajv.validateSchema(outputSchema)).toBe(true);+ expect(+ ajv.validate(inputSchema, arguments_),+ JSON.stringify(ajv.errors),+ ).toBe(true);+ const response = await client.callTool({+ name: "inspect_analysis_view",+ arguments: arguments_,+ });+ expect(response.isError).not.toBe(true);+ expect(+ ajv.validate(outputSchema, response.structuredContent),+ JSON.stringify(ajv.errors),+ ).toBe(true);+ const parsed = toolContract("inspect_analysis_view").outputSchema.parse(+ response.structuredContent,+ );+ expect(parsed.normalized_result).toMatchObject({+ kind: "native",+ parent_evidence_id: parent.evidence_id,+ procedure_address: "0x401000",+ coverage: { examined: 500, next_offset: 500, total: 11 * 1024 * 1024 },+ });+ expect(parsed.evidence_links).toEqual([parent.evidence_id]);+ expect(parsed.locations).toEqual([+ { kind: "artifact-path", path: "/fixtures/oversized-native.exe" },+ { kind: "address", address: "0x401000" },+ ]);+ expect(JSON.stringify(response.structuredContent).length).toBeLessThan(12000);+ await client.ping();+});+it("retains an oversized selected observation and keeps subsequent views usable", async () => {const { client, session } = await connect();const analysis = analysisViewJavaScriptAnalysisWithSource();@@ -185,6 +249,71 @@ it("retains an oversized selected observation and keeps subsequent views usable"expect(summary.isError).not.toBe(true);});+it("retains an oversized native assembly row and permits a subsequent smaller view", async () => {+ const { client, session } = await connect();+ const row = "\0".repeat(1_000_000);+ const parent = createEvidence(+ { path: "/fixtures/large-row.exe", format: "pe", sha256: "c".repeat(64) },+ { id: "ghidra", name: "Ghidra", version: "12.1.4" },+ {+ operation: "analyze_function",+ parameters: {},+ result: {+ ...functionDossierSchema.parse(ghidraFunctionDossier()),+ assembly: [row],+ },+ },+ );+ expect(session.recordEvidence(parent).ok).toBe(true);+ const source = { kind: "retained-evidence", evidence_id: parent.evidence_id };+ const response = await client.callTool({+ name: "inspect_analysis_view",+ arguments: {+ source,+ view: { kind: "native", facet: "assembly", offset: 0, limit: 1 },+ },+ });+ expect(response.isError).toBe(true);+ const error = z+ .object({+ error: z.object({+ details: z.object({+ reported_limits: z.object({+ evidence_reference: z.object({+ kind: z.literal("retained-evidence"),+ evidence_id: z.string(),+ }),+ }),+ }),+ }),+ })+ .parse(parseMcpToolError(response));+ const retained = session.evidenceById(+ error.error.details.reported_limits.evidence_reference.evidence_id,+ );+ expect(retained?.normalized_result).toMatchObject({+ item: [row],+ parent_evidence_id: parent.evidence_id,+ });+ const next = await client.callTool({+ name: "inspect_analysis_view",+ arguments: {+ source,+ view: { kind: "native", facet: "pseudocode", offset: 0, limit: 12 },+ },+ });+ expect(next.isError).not.toBe(true);+ expect(+ toolContract("inspect_analysis_view").outputSchema.parse(+ next.structuredContent,+ ).normalized_result,+ ).toMatchObject({+ item: { text: "int fixture_" },+ parent_evidence_id: parent.evidence_id,+ });+ await client.ping();+});+it("returns a JavaScript summary without graph payloads from a retained reference", async () => {const { client, session } = await connect();const parent = analysisViewJavaScriptEvidence();