rea-agents 6.3.0 → 6.4.0

package/dist/contracts/compactInputSchema.js

@@ -0,0 +1,256 @@
+import { schemaArrays, schemaChildren, schemaMaps, } from "./inputSchemaPresentation.js";
+// Kimi expands schema-local references before sending tools to Moonshot.
+// Compact advertisements must fit after expansion, independently of client
+// reference handling. Canonical server-side validation remains unchanged.
+/** Annotation keys that carry guidance but no validation semantics. */
+const annotationKeys = new Set(["description", "examples", "default", "title"]);
+/** Keys whose values are literal data, never nested schemas to rewrite. */
+const dataKeys = new Set(["const", "enum", "examples", "default"]);
+const definitionKeys = new Set(["$defs", "definitions"]);
+// An empty schema accepts every JSON value. Kimi otherwise infers string.
+const jsonValueTypes = [
+    "null",
+    "boolean",
+    "object",
+    "array",
+    "number",
+    "string",
+];
+const isSchemaObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const serializedBytes = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+/** Rewrite every schema-valued position; literal data stays opaque. */
+const rebuildSchemaPositions = (node, rebuild) => {
+    if (Array.isArray(node))
+        return node.map((child) => rebuild(child));
+    if (!isSchemaObject(node))
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (dataKeys.has(key)) {
+            out[key] = value;
+            continue;
+        }
+        if (schemaMaps.has(key) && isSchemaObject(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [name, rebuild(child)]));
+            continue;
+        }
+        if (schemaArrays.has(key) && Array.isArray(value)) {
+            out[key] = value.map((child) => rebuild(child));
+            continue;
+        }
+        if (schemaChildren.has(key)) {
+            out[key] = Array.isArray(value)
+                ? value.map((child) => rebuild(child))
+                : rebuild(value);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+};
+/**
+ * Drop annotation prose from every subschema while preserving all validation
+ * keywords. The root keeps its own description because the root-union
+ * projection encodes accepted input groups there; the root's echoed literal
+ * examples leave with the rest of the annotation prose.
+ */
+const stripAnnotations = (schema) => {
+    const rebuilt = rebuildSchemaPositions(schema, stripChildAnnotations);
+    const out = {};
+    for (const [key, value] of Object.entries(rebuilt)) {
+        if (annotationKeys.has(key) && key !== "description")
+            continue;
+        out[key] = value;
+    }
+    return out;
+};
+const stripChildAnnotations = (child) => {
+    const rebuilt = rebuildSchemaPositions(child, stripChildAnnotations);
+    if (!isSchemaObject(rebuilt))
+        return rebuilt;
+    const kept = {};
+    for (const [key, value] of Object.entries(rebuilt))
+        if (!annotationKeys.has(key))
+            kept[key] = value;
+    return kept;
+};
+const resolveLocalReference = (root, reference) => {
+    if (reference === "#")
+        return root;
+    if (!reference.startsWith("#/"))
+        return undefined;
+    let value = root;
+    for (const token of reference.slice(2).split("/")) {
+        const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (!isSchemaObject(value) || !Object.hasOwn(value, key))
+            return undefined;
+        value = value[key];
+    }
+    return value;
+};
+/** Stop serialization at the budget before allocating an expanded schema. */
+const inlineWithinBudget = (root, budgetBytes) => {
+    let resolved = true;
+    function* serialize(value, position, active) {
+        if (Array.isArray(value)) {
+            yield "[";
+            for (const [index, child] of value.entries()) {
+                if (index > 0)
+                    yield ",";
+                yield* serialize(child, position, active);
+            }
+            yield "]";
+        }
+        else if (isSchemaObject(value)) {
+            if (position === "schema" && Object.keys(value).length === 0) {
+                yield JSON.stringify({ type: jsonValueTypes });
+                return;
+            }
+            if (position === "schema" && typeof value.$ref === "string") {
+                const target = resolveLocalReference(root, value.$ref);
+                if (target === undefined || active.has(value.$ref)) {
+                    resolved = false;
+                    return;
+                }
+                const { $ref, ...siblings } = value;
+                // Reference siblings are independent constraints in draft 2020-12.
+                // Merging their keys into the target would overwrite validation rules.
+                yield* serialize(Object.keys(siblings).length === 0
+                    ? target
+                    : { allOf: [target, siblings] }, "schema", new Set([...active, $ref]));
+                return;
+            }
+            yield "{";
+            let first = true;
+            for (const [key, child] of Object.entries(value)) {
+                if (position === "schema" && definitionKeys.has(key))
+                    continue;
+                if (!first)
+                    yield ",";
+                first = false;
+                yield JSON.stringify(key) + ":";
+                const childPosition = position === "map"
+                    ? "schema"
+                    : position === "schema" && schemaMaps.has(key)
+                        ? "map"
+                        : position === "schema" &&
+                            (schemaArrays.has(key) || schemaChildren.has(key))
+                            ? "schema"
+                            : "data";
+                yield* serialize(child, childPosition, active);
+            }
+            yield "}";
+        }
+        else {
+            yield JSON.stringify(value);
+        }
+    }
+    const chunks = [];
+    let bytes = 0;
+    for (const chunk of serialize(root, "schema", new Set())) {
+        bytes += Buffer.byteLength(chunk, "utf8");
+        if (bytes > budgetBytes || !resolved)
+            return undefined;
+        chunks.push(chunk);
+    }
+    return resolved
+        ? JSON.parse(chunks.join(""))
+        : undefined;
+};
+/** Preserve every possible type, including referenced and nullable unions. */
+const detectedTypes = (schema, root, active = new Set()) => {
+    if (!isSchemaObject(schema))
+        return undefined;
+    if (typeof schema.$ref === "string") {
+        if (active.has(schema.$ref))
+            return undefined;
+        return detectedTypes(resolveLocalReference(root, schema.$ref), root, new Set([...active, schema.$ref]));
+    }
+    if (typeof schema.type === "string")
+        return [schema.type];
+    if (Array.isArray(schema.type) &&
+        schema.type.every((type) => typeof type === "string"))
+        return schema.type;
+    const alternatives = Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : Array.isArray(schema.oneOf)
+            ? schema.oneOf
+            : [];
+    if (alternatives.length === 0)
+        return undefined;
+    const types = alternatives.map((branch) => detectedTypes(branch, root, active));
+    if (types.some((type) => type === undefined))
+        return undefined;
+    return [...new Set(types.flatMap((type) => type ?? []))];
+};
+const REDUCED_ANNOTATION = "Advertised in reduced form by the compact input schema profile; the server still validates complete canonical inputs.";
+/**
+ * Present only the root property shape with per-property guidance. Used for
+ * schemas whose validation structure alone exceeds the compact budget; the
+ * canonical schema still rejects malformed calls server-side.
+ */
+const reduceToShallowProperties = (schema) => {
+    const properties = isSchemaObject(schema.properties) ? schema.properties : {};
+    const description = [
+        typeof schema.description === "string" ? schema.description : undefined,
+        REDUCED_ANNOTATION,
+    ]
+        .filter((text) => text !== undefined)
+        .join(" ");
+    const $schema = typeof schema.$schema === "string" ? { $schema: schema.$schema } : {};
+    const shallow = Object.fromEntries(Object.entries(properties).map(([name, value]) => {
+        const types = detectedTypes(value, schema);
+        const type = types?.length === 1 ? types[0] : types;
+        const description = isSchemaObject(value) && typeof value.description === "string"
+            ? { description: value.description }
+            : {};
+        return [
+            name,
+            { ...(type === undefined ? {} : { type }), ...description },
+        ];
+    }));
+    return {
+        ...$schema,
+        type: "object",
+        description,
+        properties: shallow,
+        ...(Array.isArray(schema.required)
+            ? { required: [...schema.required] }
+            : {}),
+        ...(typeof schema.minProperties === "number"
+            ? { minProperties: schema.minProperties }
+            : {}),
+        ...(isSchemaObject(schema.dependentRequired)
+            ? { dependentRequired: { ...schema.dependentRequired } }
+            : {}),
+        ...(schema.additionalProperties === false
+            ? { additionalProperties: false }
+            : {}),
+    };
+};
+/**
+ * Render an advertised input schema within a per-schema byte budget for
+ * providers that validate the literal serialized schema size. Validation
+ * keywords and the canonical contract are preserved; only
+ * annotation prose and, for structurally oversized schemas, nested
+ * validation detail leave the advertised form.
+ */
+export const compactAdvertisedInputSchema = (schema, budgetBytes) => {
+    const inline = inlineWithinBudget(stripAnnotations(schema), budgetBytes);
+    if (inline !== undefined)
+        return { schema: inline, presentation: "inline" };
+    const reduced = reduceToShallowProperties(schema);
+    if (serializedBytes(reduced) <= budgetBytes)
+        return { schema: reduced, presentation: "reduced" };
+    // A future contract with an extreme root-property count still advertises
+    // an honest, budget-fitting shape instead of an oversized one.
+    return {
+        schema: reduceToShallowProperties({
+            type: "object",
+            description: (typeof schema.description === "string"
+                ? `${schema.description} `
+                : "") + REDUCED_ANNOTATION,
+        }),
+        presentation: "reduced",
+    };
+};

package/dist/contracts/functionWorkflowToolContracts.js

@@ -24,6 +24,6 @@ const functionWorkflow = (name, description) => {
 };
 /** Function dossier and native API reconstruction workflow contracts. */
 export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [
-    functionWorkflow("analyze_function", "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations."),
+    functionWorkflow("analyze_function", "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive analyzed body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations with available callee identities."),
     functionWorkflow("inspect_native_api", "Analyze a native API boundary in one function identified by symbol or provider-returned address. Returns confidence, evidence, jump-table dispatch/data/case mappings, separately evidenced default targets, unsupported branches, and residual unknowns. Null case values mean unresolved cases, never a known default."),
 ];

package/dist/contracts/inputSchemaPresentation.js

@@ -1,5 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
-const schemaMaps = new Set([
+export const schemaMaps = new Set([
     "$defs",
     "definitions",
     "properties",
@@ -7,8 +7,8 @@ const schemaMaps = new Set([
     "dependentSchemas",
     "dependencies",
 ]);
-const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
-const schemaChildren = new Set([
+export const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+export const schemaChildren = new Set([
     "items",
     "additionalItems",
     "contains",
@@ -56,15 +56,15 @@ const describeSchema = (schema, root, describeProperty) => {
                 key,
                 Object.fromEntries(Object.entries(value).map(([name, child]) => {
                     const described = describeSchema(child, root, describeProperty);
+                    if (key !== "properties" || !isObject(described))
+                        return [name, described];
+                    const description = referencedDescription(root, described) ??
+                        describeProperty(name);
                     return [
                         name,
-                        key === "properties" && isObject(described)
-                            ? {
-                                ...described,
-                                description: referencedDescription(root, described) ??
-                                    describeProperty(name),
-                            }
-                            : described,
+                        description === undefined
+                            ? described
+                            : { ...described, description },
                     ];
                 })),
             ];

package/dist/contracts/javascript/electronToolContracts.js

@@ -2,12 +2,17 @@ import { toolContractMetadata } from "../toolEffects.js";
 import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
 import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../../domain/javascript/electronObservation.js";
 import { electronActiveObservationInputSchema, electronActiveObservationResultSchema, } from "../../domain/javascript/electronActiveObservation.js";
+import { analysisDetailOutputSchemaOf, analysisDetailSchema, } from "../analysisDetail.js";
 import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../../domain/javascript/javascriptApplicationAnalysis.js";
 import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../../domain/javascript/javascriptRuntimeReconciliationSchemas.js";
 import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
 const listOutputSchema = evidenceResultOf(electronTargetListSchema);
 const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
-const applicationOutputSchema = evidenceResultOf(javascriptApplicationAnalysisResultSchema);
+/** Caller-selected delivery of a completed JavaScript application analysis. */
+export const analyzeJavaScriptApplicationRequestSchema = analyzeJavaScriptApplicationInputSchema.extend({
+    detail: analysisDetailSchema,
+});
+const applicationOutputSchema = analysisDetailOutputSchemaOf(javascriptApplicationAnalysisResultSchema);
 const reconciliationOutputSchema = evidenceResultOf(javascriptRuntimeReconciliationResultSchema);
 const endpoint = "http://127.0.0.1:9223";
 const activeExample = {
@@ -54,9 +59,9 @@ export const ELECTRON_TOOL_CONTRACTS = [
     {
         name: "analyze_javascript_application",
         ...toolContractMetadata("analyze_javascript_application"),
-        description: "Reconstruct one local ASAR or extracted JavaScript application as an inline application graph without executing it. Returns recovered graph nodes, edges, semantic relations, integrity contradictions, limitations, and coverage. Integrity mismatches fail by default; record-and-continue retains observed bytes as untrusted and marks graph coverage partial.",
+        description: "Reconstruct one local ASAR or extracted JavaScript application as an inline application graph without executing it. Returns recovered graph nodes, edges, semantic relations, integrity contradictions, limitations, and coverage. Select detail summary to retain the complete analysis Evidence in this session and receive only its summary view, then inspect selected modules or pages with inspect_analysis_view. Integrity mismatches fail by default; record-and-continue retains observed bytes as untrusted and marks graph coverage partial.",
         kind: "electron-provider",
-        inputSchema: analyzeJavaScriptApplicationInputSchema,
+        inputSchema: analyzeJavaScriptApplicationRequestSchema,
         outputSchema: applicationOutputSchema,
         examples: [
             {
@@ -67,6 +72,13 @@ export const ELECTRON_TOOL_CONTRACTS = [
                     integrity_policy: "fail",
                 },
             },
+            {
+                title: "Retain the complete analysis and return its summary view",
+                input: {
+                    input_path: "/Applications/Example.app/Contents/Resources/app.asar",
+                    detail: "summary",
+                },
+            },
         ],
     },
     {

package/dist/contracts/javascript/javascriptRecoveryToolContracts.js

@@ -7,7 +7,7 @@ export const JAVASCRIPT_RECOVERY_TOOL_CONTRACTS = [
         name: "recover_javascript_sources",
         ...toolContractMetadata("recover_javascript_sources"),
         kind: "application",
-        description: "Recover readable modules from one local UTF-8 JavaScript script/bundle into an absent directory, using caller-supplied Wakaru 1.13.0 on Linux x64. Returns original/derived digests, extraction byte ranges, emitted source maps, warnings and analysis_input inline. Structural splitting may fall back to one module; original names and runtime equivalence remain unknown. No application code execution. Requires util-linux prlimit; one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB input, 128 MiB output, 10000 entries and 8 MiB per diagnostic/report stream.",
+        description: "Recover readable modules from one local UTF-8 JavaScript script/bundle into an absent directory, using caller-supplied Wakaru ^1.13.0 (verified with 1.14.0) on Linux x64. Returns original/derived digests, extraction byte ranges, emitted source maps, warnings and analysis_input inline. Structural splitting may fall back to one module; original names and runtime equivalence remain unknown. No application code execution. Requires util-linux prlimit; one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB input, 128 MiB output, 10000 entries and 8 MiB per diagnostic/report stream.",
         inputSchema: javascriptRecoveryInputSchema,
         outputSchema: evidenceResultOf(javascriptRecoveryResultSchema),
         examples: [

package/dist/contracts/jeb/jebToolContracts.js

@@ -0,0 +1,64 @@
+import { jebInputSchemas, jebResultSchemas, } from "../../domain/jeb/jebAnalysis.js";
+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "../toolEffects.js";
+/** JEB-backed inspection served by a caller-supplied running engine client. */
+export const JEB_TOOL_CONTRACTS = [
+    {
+        name: "inspect_jeb_client",
+        ...toolContractMetadata("inspect_jeb_client"),
+        description: "Inspect the running JEB client serving MCP: engine version, GUI or headless mode, and startup time. Does not open a target. Requires a caller-started JEB client reachable at REA_JEB_MCP_URL (default http://127.0.0.1:8425/mcp); REA never installs or launches JEB.",
+        kind: "jeb-provider",
+        inputSchema: jebInputSchemas.inspect_jeb_client,
+        outputSchema: evidenceResultOf(jebResultSchemas.inspect_jeb_client),
+        examples: [{ title: "Check the engine", input: {} }],
+    },
+    {
+        name: "open_jeb_project",
+        ...toolContractMetadata("open_jeb_project"),
+        description: "Open or create a JEB project from an artifact file or existing .jdb2 database on the engine host. Returns the project's input-file digests and top-level units. The engine analyzes the target itself; REA does not read the file or execute it. Fails when a project is already open.",
+        kind: "jeb-provider",
+        inputSchema: jebInputSchemas.open_jeb_project,
+        outputSchema: evidenceResultOf(jebResultSchemas.open_jeb_project),
+        examples: [
+            {
+                title: "Open a target for analysis",
+                input: { path: "/tmp/Example.apk" },
+            },
+        ],
+    },
+    {
+        name: "list_jeb_units",
+        ...toolContractMetadata("list_jeb_units"),
+        description: "List project units by stable unit path and type, with optional wildcard filter, parent restriction, and pagination. The engine caps pages at 100 units; a full page reports partial coverage because more units may exist. Read-only.",
+        kind: "jeb-provider",
+        inputSchema: jebInputSchemas.list_jeb_units,
+        outputSchema: evidenceResultOf(jebResultSchemas.list_jeb_units),
+        examples: [
+            {
+                title: "List units",
+                input: {},
+            },
+            {
+                title: "Find DEX units",
+                input: { filter: "*.dex" },
+            },
+        ],
+    },
+    {
+        name: "decompile_jeb_item",
+        ...toolContractMetadata("decompile_jeb_item"),
+        description: "Decompile one type or method to engine pseudo-code using its decompiler (Dalvik, Java, or native). item_address comes from the engine's code item listing; unit_path defaults to the engine's first code unit and stays unknown when omitted. Read-only with respect to the target file.",
+        kind: "jeb-provider",
+        inputSchema: jebInputSchemas.decompile_jeb_item,
+        outputSchema: evidenceResultOf(jebResultSchemas.decompile_jeb_item),
+        examples: [
+            {
+                title: "Decompile a method",
+                input: {
+                    item_address: "Lcom/example/Main;->onCreate()V",
+                    item_kind: "method",
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/native/binaryDiagnosticsToolContracts.js

@@ -1,21 +1,43 @@
 import { inspectRecordedCrashInputSchema, recordedCrashSchema, } from "../../domain/native/recordedCrash.js";
 import { inspectBinaryLayoutInputSchema, binaryLayoutSchema, } from "../../domain/native/binaryLayout.js";
+import { analysisDetailOutputSchemaOf, analysisDetailSchema, } from "../analysisDetail.js";
 import { toolContractMetadata } from "../toolEffects.js";
 import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
+import { inspectPeResourcesInputSchema, peResourcesSchema, } from "../../domain/native/peResources.js";
+/** Caller-selected delivery of completed binary layout Evidence. */
+export const inspectBinaryLayoutRequestSchema = inspectBinaryLayoutInputSchema.extend({ detail: analysisDetailSchema });
 /** Offline binary diagnostics are independent of macOS process/UI providers. */
 export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [
+    {
+        name: "inspect_pe_resources",
+        ...toolContractMetadata("inspect_pe_resources"),
+        kind: "native-provider",
+        description: "Inspect one explicit local PE32/PE32+ image's complete bounded type/name/language resource tree without executing it or opening a disassembler. Returns numeric IDs versus original UTF-16 names, directory/data-entry file locations, payload RVA/file ranges, complete SHA-256 hashes and static RT_GROUP_ICON image-resource candidates. Language fallback, image decoding and actual shell/window loading remain unobserved. Reads a stable regular file; malformed or ambiguous mappings, non-identical overlapping ranges and exhausted budgets return no partial success. Portable on supported Node hosts; no Windows SDK or engine installation required.",
+        inputSchema: inspectPeResourcesInputSchema,
+        outputSchema: evidenceResultOf(peResourcesSchema),
+        examples: [
+            {
+                title: "Inspect PE resource identities and icon relationships",
+                input: { path: "/artifacts/application.exe" },
+            },
+        ],
+    },
     {
         name: "inspect_binary_layout",
         ...toolContractMetadata("inspect_binary_layout"),
         kind: "native-provider",
-        description: "Inspect an explicit local binary without launching it as a host process. Returns file-backed section/segment ranges, linked addresses, original symbol/REL/RELA table identities, complete encoded RELR tables and upstream-derived offsets with unknown per-word locations/addends, raw name bytes, dependency/interpreter names and static mitigation inferences inline with artifact SHA-256 Evidence. Initial profile: ELF64 x86-64 little-endian EXEC/DYN/REL on Linux x64 via caller-supplied Python with unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2. Runtime addresses/library paths, overall relocation inventory completeness and complete derived GOT/PLT coverage remain unknown. Zero executable entry values mean absence; relocatable entries are not applicable. Upstream can emulate PLT instructions with Unicorn for derived static maps. Uses bounded complete output and owned temporary files/processes; malformed, unsupported or oversized objects return no partial success.",
-        inputSchema: inspectBinaryLayoutInputSchema,
-        outputSchema: evidenceResultOf(binaryLayoutSchema),
+        description: "Inspect an explicit local binary without launching it as a host process. Returns file-backed section/segment ranges, linked addresses, original symbol/REL/RELA table identities, complete encoded RELR tables and upstream-derived offsets with unknown per-word locations/addends, raw name bytes, dependency/interpreter names and static mitigation inferences inline with artifact SHA-256 Evidence. Initial profile: ELF64 x86-64 little-endian EXEC/DYN/REL on Linux x64 via caller-supplied Python with unchanged pwntools 4.15.0, pyelftools 0.33 and Unicorn 2.1.2. Runtime addresses/library paths, overall relocation inventory completeness and complete derived GOT/PLT coverage remain unknown. Zero executable entry values mean absence; relocatable entries are not applicable. Upstream can emulate PLT instructions with Unicorn for derived static maps. Uses bounded complete output and owned temporary files/processes; malformed, unsupported or oversized objects return no partial success. Select detail summary to retain the complete layout Evidence in this session and receive only its summary view, then inspect sections, symbols, mitigations or linkage with inspect_analysis_view.",
+        inputSchema: inspectBinaryLayoutRequestSchema,
+        outputSchema: analysisDetailOutputSchemaOf(binaryLayoutSchema),
         examples: [
             {
                 title: "Inspect ELF linked and file layout",
                 input: { path: "/artifacts/application.elf" },
             },
+            {
+                title: "Retain the complete layout and return its summary view",
+                input: { path: "/artifacts/application.elf", detail: "summary" },
+            },
         ],
     },
     {

package/dist/contracts/officialToolContracts.js

@@ -44,21 +44,21 @@ export const OFFICIAL_TOOL_CONTRACTS = [
     official("next_address", "Return the next analyzed object address after an explicit address or current cursor. This is a navigation primitive, not instruction-flow or CFG analysis.", z.object({ document, address: optionalAddress })),
     official("prev_address", "Return the previous analyzed object start before an explicit address or current cursor. This is a navigation primitive and may fail at document boundaries; data objects and instructions remain distinct from control flow.", z.object({ document, address: optionalAddress })),
     official("procedure_address", "Resolve an unambiguous procedure symbol name or provider-normalized address to its canonical entry address. External address spaces remain explicit.", z.object({ procedure, document })),
-    official("procedure_assembly", "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string.", z.object({ procedure, document })),
+    official("procedure_assembly", "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string. Ghidra terminal-call assumptions that may cut the analyzed body are reported in Evidence limitations.", z.object({ procedure, document })),
     official("procedure_callees", "Return the provider's resolved direct callees for one procedure identified by symbol or address. Unresolved indirect calls may be absent; use analyze_function and typed references to preserve available edge uncertainty.", z.object({ procedure, document })),
     official("procedure_callers", "Return the provider's resolved direct callers for one procedure identified by symbol or address. Results reflect completed static analysis and may omit unresolved indirect references.", z.object({ procedure, document })),
-    official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
-    official("read_function_instructions", "Return every raw instruction for one analyzed procedure. Instruction text is provider-specific.", functionInstructionInputSchema),
+    official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Extents reflect the provider's analyzed body; Ghidra terminal-call assumptions that may cut it are reported in Evidence limitations. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
+    official("read_function_instructions", "Return every raw instruction for one analyzed procedure. Instruction text and body extent are provider-specific. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations.", functionInstructionInputSchema),
     ...HOPPER_MEMORY_TOOL_DEFINITIONS.map(({ name, description, inputSchema }) => official(name, description, inputSchema)),
     official("procedure_references", "Return every raw incoming or outgoing reference edge for one procedure. Endpoint procedures are resolved only from provider containment. Ghidra preserves detailed reference flags. Hopper preserves native CallReference classifications and exact endpoints while leaving unavailable detailed flags explicit.", z.object({
         procedure,
         direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
         document,
     })),
-    official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
+    official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters. Ghidra no-return assumptions may cut the analyzed body; Evidence limitations report observed terminal calls and available callee identities.", z.object({ procedure, document })),
     official("resolve_containing_procedure", "Resolve an arbitrary address, including an interior instruction or exact external entry, to its provider-analyzed containing procedure. A negative result distinguishes outside segments from not in a procedure and is never guessed from nearby symbols.", z.object({ address, document })),
     official("search_procedures", "Search every analyzed procedure name using literal matching by default or regex when requested. Results are deterministic and complete. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
-    official("search_strings", "Search every analyzed string object using literal matching by default or regex when requested. Results are deterministic and complete over the native inventory. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
+    official("search_strings", "Search every provider-defined string object using literal matching by default or regex when requested. Results are deterministic and complete over those defined objects, not every text sequence in artifact bytes. Ghidra may omit packed or undefined literals, including Rust strings; an empty result does not prove text is absent. If an address is known, read_bytes and xrefs inspect its bytes and references. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
     official("set_address_name", "Assign an analyst name to one mapped hexadecimal address and report whether the native edit succeeded and exact readback matched. Hopper rejects symbol names exceeding 1024 UTF-16 code units before mutation, and rejects names owned by another address; use set_addresses_names to explicitly move or swap labels among selected addresses. This mutates analysis metadata.", z.object({ address, name: z.string(), document })),
     official("set_addresses_names", "Assign analyst names to multiple mapped addresses in one call and return per-address edit/readback success booleans. Hopper validates mapped destinations, native string representations, its 1024 UTF-16 code-unit symbol-name limit, and unique destinations/names before applying edits. Existing labels may move or swap only among explicitly selected addresses; unselected label owners remain unchanged. This mutates analysis metadata; verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
     official("set_bookmark", "Create or replace a bookmark at a mapped hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.", z.object({ address, name: z.string().optional(), document })),

package/dist/contracts/sessionToolContracts.js

@@ -42,7 +42,7 @@ export const SESSION_TOOL_CONTRACTS = [
     session("binary_session", "Report the complete current target, provider, capability availability, client-feature, analysis, and server-identity status without starting analysis.", binarySessionInputSchema),
     session("export_evidence_bundle", "Atomically write the session's deterministic Evidence bundle to the requested local path. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
     session("import_evidence_bundle", "Read the JSON bundle at the supplied local path, validate every Evidence ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
-    session("capture_process_scenario", "Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. The target runs with the current user's permissions; this is not a security sandbox.", processScenarioSchema),
+    session("capture_process_scenario", "Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. The renderer admits at most 1,000,000 combined terminal cells, computed as columns × (rows + scrollback); every resize uses the selected scrollback and must fit the same budget. Supply a smaller terminal shape when that product is too large; dimensions are never clamped. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. A positive finalization_ms makes a timeout or idle deadline send SIGTERM to the captured root through its start identity, keep observing, and send SIGKILL once after the interval; exit.finalization records each attempt with its delivery result and the observed exit, and cancellation still ends the run at once. The target runs with the current user's permissions; this is not a security sandbox.", processScenarioSchema),
     session("compare_process_captures", "Compare two compatible process capture observations across terminal, interaction, lifecycle, process, filesystem, command-shim, HTTP, and WebSocket evidence. Optional trace_spec validates exact events against an explicit partial order or finite trace language; concurrency is never inferred from timestamps or broad sorting. Missing, journal-free, or truncated observations are never treated as equivalent.", processComparisonInputSchema),
     session("compare_artifacts", "Compare complete artifact inventories by logical occurrence path, content identity, metadata, and graph relations. Pass the inventory Evidence nested in each inspect_artifact result as left and right. Every delta cites both inputs, and gaps yield truncated or unknown, never equivalence. Returns every change inline.", artifactComparisonInputSchema),
     session("compare_functions", "Compare two explicit sets of analyze_function Evidence across identity, exact provider text, calls, references, strings, and address-normalized CFG topology. Missing or provider-incompatible facets remain truncated or unknown; every conclusion cites both Evidence sets.", functionComparisonInputSchema),
@@ -55,7 +55,7 @@ export const SESSION_TOOL_CONTRACTS = [
     session("record_unknown", "Create one deterministic residual unknown and immutable mutation evidence. Validates all evidence and relationship references, and rejects duplicate stable identity.", recordUnknownInputSchema),
     session("update_unknown", "Append one immutable full-state revision and mutation evidence. Requires exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.", updateUnknownInputSchema),
     session("verify_unknown_resolution", "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", verifyUnknownResolutionInputSchema),
-    session("get_evidence_bundle", "Return every Evidence record and residual unknown currently retained by this session as one inline bundle for direct inspection or follow-up workflows.", getEvidenceBundleInputSchema),
+    session("get_evidence_bundle", "Return every retained Evidence record and residual unknown as a complete canonical bundle by default. detail=summary discovers retained records without copying or transferring their payloads; optionally filter by exact Evidence ID, operation, target SHA-256, analysis-profile digest or canonical native procedure address. Metadata distinguishes complete record retention from native value-flow truncation or unavailable/unknown coverage. Use a discovered evidence_id with inspect_analysis_view without restarting a provider. Filters apply only to summary delivery.", getEvidenceBundleInputSchema),
     session("get_navigation_context", "Return the selected document, current address, and containing/current procedure in one provider-neutral result. The result reflects sequential provider observations, not an atomic cursor snapshot; a cursor outside any procedure returns procedure: null.", navigationContextInputSchema),
     session("inspect_address_context", "Inspect one explicit reproducible address for its analyzed name, containing procedure, regular and inline comments, and matching bookmarks. Each unsupported facet returns a typed unavailable outcome; use xrefs, assembly, or pseudocode for those deeper views.", addressContextInputSchema),
 ];

package/dist/contracts/sessionToolSchemas.js

@@ -4,8 +4,12 @@ import { localPathStringSchema } from "../domain/localPath.js";
 import { processTraceSpecificationSchema } from "../domain/process/processTraceSpecification.js";
 import { evidenceSchema } from "../domain/evidence.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
-/** Return the current canonical Evidence bundle inline. */
-export const getEvidenceBundleInputSchema = z.strictObject({});
+import { evidenceRecordFiltersSchema } from "../domain/evidenceRecordSummary.js";
+/** Complete retained Evidence, or selected discovery metadata without payloads. */
+export const getEvidenceBundleInputSchema = z.strictObject({
+    detail: z.enum(["complete", "summary"]).default("complete"),
+    filters: evidenceRecordFiltersSchema.optional(),
+});
 /** Optional document selection for volatile navigation context. */
 export const navigationContextInputSchema = z.strictObject({
     document: z.string().min(1).optional(),

package/dist/contracts/toolContractExamples.js

@@ -45,11 +45,17 @@ export const TOOL_EXAMPLE_OVERRIDES = {
     trace_native_ui_action: { action: "buildTapped:" },
     open_binary: { path: "/tmp/fixture" },
     export_evidence_bundle: { path: "/tmp/evidence.json" },
+    get_evidence_bundle: {
+        detail: "summary",
+        filters: { operation: "analyze_function", procedure_address: "0x1000" },
+    },
     inspect_address_context: { address: "0x1000" },
     import_evidence_bundle: { path: "/tmp/evidence.json" },
     capture_process_scenario: {
         executable: "/usr/bin/true",
         working_directory: "/tmp",
+        timeout_ms: 30_000,
+        finalization_ms: 1_500,
     },
     compare_process_captures: {
         left: PROCESS_CAPTURE_REFERENCE,

package/dist/contracts/toolContractTypes.js

@@ -6,6 +6,9 @@ export const TOOL_KINDS = [
     "artifact-provider",
     "managed-provider",
     "android-provider",
+    "apktool-provider",
+    "jeb-provider",
+    "adb-provider",
     "firmware-provider",
     "browser-provider",
     "electron-provider",

package/dist/contracts/toolContracts.js

@@ -6,6 +6,9 @@ import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
 import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";
 import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";
 import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";
+import { APKTOOL_TOOL_CONTRACTS } from "./apktool/apktoolToolContracts.js";
+import { JEB_TOOL_CONTRACTS } from "./jeb/jebToolContracts.js";
+import { ADB_TOOL_CONTRACTS } from "./adb/adbToolContracts.js";
 import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managed/managedWorkflowToolContracts.js";
 import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";
 import { ELECTRON_TOOL_CONTRACTS } from "./javascript/electronToolContracts.js";
@@ -29,6 +32,9 @@ export const TOOL_CONTRACTS = [
     ...EVM_TOOL_CONTRACTS,
     ...MANAGED_TOOL_CONTRACTS,
     ...ANDROID_TOOL_CONTRACTS,
+    ...APKTOOL_TOOL_CONTRACTS,
+    ...JEB_TOOL_CONTRACTS,
+    ...ADB_TOOL_CONTRACTS,
     ...FIRMWARE_TOOL_CONTRACTS,
     ...MANAGED_WORKFLOW_TOOL_CONTRACTS,
     ...BROWSER_PROVIDER_TOOL_CONTRACTS,