rea-agents 4.0.0 → 4.1.0

package/dist/cliEvidenceCommands.js

@@ -2,7 +2,8 @@ import { Cli, z } from "incur";
 import { compareEvidenceBundlesCommand, exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
 import { logCliCommand } from "./cliLogging.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
-import { projectAnalysisError } from "./domain/errors.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+import {} from "./domain/analysisErrorBase.js";
 /** Register caller-path Evidence commands. */
 export const registerEvidenceCommands = (cli, logger) => {
     cli.command(CLI_COMMANDS.evidenceImport, {

package/dist/cliJavaScriptRuntimeCommands.js

@@ -4,7 +4,8 @@ import { V8InspectorProvider } from "./browser/V8InspectorProvider.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { logCliCommand } from "./cliLogging.js";
 import { javascriptRuntimeKindSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "./domain/javascriptRuntimeObservation.js";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
 const observeOptionsSchema = z.object({
     runtimeKind: javascriptRuntimeKindSchema
         .optional()

package/dist/cliJsonInput.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+import { safeParseJson } from "./domain/safeJson.js";
 /** Parse inline JSON or one local JSON file for a CLI workflow. */
 export const parseCliJsonInput = async (value, operation) => {
     const inline = parseJson(value);
@@ -8,24 +10,37 @@ export const parseCliJsonInput = async (value, operation) => {
     if (["{", "["].includes(value.trimStart()[0] ?? ""))
         return { ok: false, error: inputError(operation) };
     try {
+        // Read raw bytes so invalid UTF-8 is rejected by parseJson instead of
+        // being silently replaced by lossy "utf8" decoding.
         const parsed = parseJson(await readFile(value));
         return parsed === undefined
             ? jsonFileError(value, operation, "invalid-json")
             : { ok: true, value: parsed };
     }
-    catch {
-        return jsonFileError(value, operation, "read-failed");
+    catch (cause) {
+        return jsonFileError(value, operation, "read-failed", cause);
     }
 };
 const parseJson = (value) => {
-    try {
-        return JSON.parse(typeof value === "string"
-            ? value
-            : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(value));
+    let text;
+    if (typeof value === "string") {
+        text = value;
     }
-    catch {
-        return undefined;
+    else {
+        try {
+            text = new TextDecoder("utf-8", {
+                fatal: true,
+                ignoreBOM: true,
+            }).decode(value);
+        }
+        catch (cause) {
+            // Decoding failure means the bytes are not valid UTF-8 JSON input.
+            void cause;
+            return undefined;
+        }
     }
+    const parsed = safeParseJson(text);
+    return parsed.ok ? parsed.value : undefined;
 };
 const inputError = (operation) => ({
     error: "Application workflow failed",
@@ -33,11 +48,11 @@ const inputError = (operation) => ({
         { path: [], reason: "invalid_format", expected: "JSON" },
     ])),
 });
-const jsonFileError = (path, operation, reason) => ({
+const jsonFileError = (path, operation, reason, cause) => ({
     ok: false,
     error: {
         error: "Application workflow failed",
-        ...projectAnalysisError(new AnalysisInputError(operation, undefined, reason === "invalid-json"
+        ...projectAnalysisError(new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, reason === "invalid-json"
             ? [{ path: [], reason: "invalid_format", expected: "JSON" }]
             : [])),
         ...(path === undefined ? {} : { input_path: path }),

package/dist/cliLogging.js

@@ -1,5 +1,6 @@
 import { analysisCliErrorEnvelopeSchema, analysisErrorProjectionSchema, } from "./contracts/errorSchemas.js";
-import { AnalysisError, projectAnalysisError, } from "./domain/errors.js";
+import { AnalysisError } from "./domain/analysisErrorBase.js";
+import { projectAnalysisError, } from "./domain/analysisErrorProjection.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Identify caller-visible CLI outcomes that mean the requested operation failed. */
 export const isCliOperationFailure = (value) => {

package/dist/cliOutput.js

@@ -1,3 +1,4 @@
+import { safeParseJson } from "./domain/safeJson.js";
 const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `rea --help`, correct the arguments, then try again.";
 const UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE = "Token windows cannot preserve structured output. Remove --token-limit/--token-offset and use --filter-output or command pagination.";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -67,23 +68,21 @@ export const renderCliOutputArgumentError = (error) => {
 export const sanitizeCliOutput = (output) => {
     const trimmed = output.trimStart();
     if (trimmed.startsWith("{")) {
-        try {
-            const parsed = JSON.parse(trimmed);
-            if (!isRecord(parsed))
-                return output;
-            const error = validationError(parsed);
-            if (error !== undefined) {
-                const safeError = {
-                    code: "VALIDATION_ERROR",
-                    message: SAFE_VALIDATION_MESSAGE,
-                };
-                if (error === parsed)
-                    return `${JSON.stringify(safeError)}\n`;
-                return `${JSON.stringify({ ...parsed, error: safeError })}\n`;
-            }
-        }
-        catch {
+        const decoded = safeParseJson(trimmed);
+        if (!decoded.ok)
+            return output;
+        const parsed = decoded.value;
+        if (!isRecord(parsed))
             return output;
+        const error = validationError(parsed);
+        if (error !== undefined) {
+            const safeError = {
+                code: "VALIDATION_ERROR",
+                message: SAFE_VALIDATION_MESSAGE,
+            };
+            if (error === parsed)
+                return `${JSON.stringify(safeError)}\n`;
+            return `${JSON.stringify({ ...parsed, error: safeError })}\n`;
         }
         return output;
     }

package/dist/config/environment.js

@@ -1,10 +1,15 @@
 import { z } from "zod";
 import { isAbsolute } from "node:path";
-import { ConfigurationError } from "../domain/errors.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
 const environmentSchema = z.object({
     REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
+    REA_IDA_MCP_CONFIG: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_IDA_MCP_CONFIG must be absolute")
+        .optional(),
     GHIDRA_INSTALL_DIR: z
         .string()
         .min(1)
@@ -15,6 +20,11 @@ const environmentSchema = z.object({
         .min(1)
         .refine(isAbsolute, "JAVA_HOME must be absolute")
         .optional(),
+    REA_GHIDRA_NATIVEAOT_JAR: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
+        .optional(),
     REA_ILSPY_CMD_PATH: z
         .string()
         .min(1)

package/dist/config/parseConfig.js

@@ -1,4 +1,4 @@
-import { ConfigurationError } from "../domain/errors.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
 import { ok } from "../domain/result.js";
 import { parseEnvironment } from "./environment.js";
 import { parseStringArray, parseLoaderArgs } from "./parsers.js";
@@ -19,8 +19,14 @@ export const parseConfig = (environment) => {
         return secretPatterns;
     return ok({
         analysisProvider: env.REA_ANALYSIS_PROVIDER,
+        ...(env.REA_IDA_MCP_CONFIG === undefined
+            ? {}
+            : { idaMcpConfigPath: env.REA_IDA_MCP_CONFIG }),
         ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
         ghidraJavaHome: env.JAVA_HOME,
+        ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
+            ? {}
+            : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),
         ilspyCmdPath: env.REA_ILSPY_CMD_PATH,
         hopperLauncherPath: env.HOPPER_LAUNCHER_PATH ?? defaultHopperLauncherPath(),
         hopperTargetPath: env.HOPPER_TARGET_PATH,

package/dist/config/parsers.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ConfigurationError } from "../domain/errors.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
 export const parseStringArray = (encoded, name) => {
     try {

package/dist/contracts/androidToolContracts.js

@@ -0,0 +1,77 @@
+import { androidInputSchemas, androidResultSchemas, } from "../domain/androidAnalysis.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+/** Static APK operations backed by a separately supplied headless engine. */
+export const ANDROID_TOOL_CONTRACTS = [
+    {
+        name: "inspect_android_package",
+        ...toolContractMetadata("inspect_android_package"),
+        description: "Inspect a local APK's package, SDK and permission declarations, decoded manifest and class/resource counts. Does not execute the APK or verify signatures. Requires a caller-supplied JADX MCP JAR and Java; uses one worker in an isolated temporary workspace.",
+        kind: "android-provider",
+        inputSchema: androidInputSchemas.inspect_android_package,
+        outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_package),
+        examples: [
+            { title: "Inspect an APK", input: { path: "/tmp/Example.apk" } },
+        ],
+    },
+    {
+        name: "search_android_classes",
+        ...toolContractMetadata("search_android_classes"),
+        description: "Search complete decompiler class names in an explicit local APK by case-sensitive substring. Empty query inventories all classes. Retains artifact and engine identity; no APK execution.",
+        kind: "android-provider",
+        inputSchema: androidInputSchemas.search_android_classes,
+        outputSchema: evidenceResultOf(androidResultSchemas.search_android_classes),
+        examples: [
+            {
+                title: "Find activity classes",
+                input: { path: "/tmp/Example.apk", query: "Activity" },
+            },
+        ],
+    },
+    {
+        name: "inspect_android_class",
+        ...toolContractMetadata("inspect_android_class"),
+        description: "Inspect one exact Android class's methods, fields and inner classes. Returns display signatures and explicit unknown DEX descriptors without materializing the whole application source.",
+        kind: "android-provider",
+        inputSchema: androidInputSchemas.inspect_android_class,
+        outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_class),
+        examples: [
+            {
+                title: "Inspect a class",
+                input: { path: "/tmp/Example.apk", class_name: "example.MainActivity" },
+            },
+        ],
+    },
+    {
+        name: "inspect_android_method",
+        ...toolContractMetadata("inspect_android_method"),
+        description: "Decompile one Android method with smali fallback. Requires explicit overload_index when multiple methods share a name. Reports representation, fallback markers and source truncation; never treats display signatures as exact DEX identities.",
+        kind: "android-provider",
+        inputSchema: androidInputSchemas.inspect_android_method,
+        outputSchema: evidenceResultOf(androidResultSchemas.inspect_android_method),
+        examples: [
+            {
+                title: "Decompile a method",
+                input: {
+                    path: "/tmp/Example.apk",
+                    class_name: "example.MainActivity",
+                    method_name: "onCreate",
+                },
+            },
+        ],
+    },
+    {
+        name: "trace_android_references",
+        ...toolContractMetadata("trace_android_references"),
+        description: "Trace incoming static references to an exact Android class or unique method. Overloaded method reference queries are explicitly unsupported by the current engine. Source lines and DEX offsets remain unknown; no runtime calls are inferred.",
+        kind: "android-provider",
+        inputSchema: androidInputSchemas.trace_android_references,
+        outputSchema: evidenceResultOf(androidResultSchemas.trace_android_references),
+        examples: [
+            {
+                title: "Find references to a class",
+                input: { path: "/tmp/Example.apk", class_name: "example.MainActivity" },
+            },
+        ],
+    },
+];

package/dist/contracts/applicationToolContracts.js

@@ -17,12 +17,16 @@ const sourceToBundleOutputSchema = evidenceResultOf(sourceToBundleComparisonResu
 const exportShapeComparisonOutputSchema = evidenceResultOf(javaScriptExportShapeComparisonResultSchema);
 const reconstructionObligationLedgerOutputSchema = evidenceResultOf(reconstructionObligationLedgerSchema);
 const HASH = "0".repeat(64);
+const retained = (evidence_id) => ({
+    kind: "retained-evidence",
+    evidence_id,
+});
 /** Provider-neutral graph workflow contracts shared by MCP and CLI adapters. */
 export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "trace_application_feature",
         ...toolContractMetadata("trace_application_feature"),
-        description: "Trace a typed literal seed through every reachable part of an authenticated JavaScript Application Graph supplied as inline Evidence. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+        description: "Trace a typed literal seed through every reachable part of an authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
         kind: "application",
         inputSchema: traceApplicationFeatureRequestSchema,
         outputSchema: traceOutputSchema,
@@ -31,12 +35,19 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Trace one module seed through a retained application graph",
                 input: JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_FEATURE_TRACE_EXAMPLE,
+                    application: retained(JAVASCRIPT_FEATURE_TRACE_EXAMPLE.application.evidence_id),
+                },
+            },
         ],
     },
     {
         name: "trace_javascript_semantics",
         ...toolContractMetadata("trace_javascript_semantics"),
-        description: "Trace static JavaScript data-flow, direct call/return, and closure relations from inline application Evidence. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
+        description: "Trace static JavaScript data-flow, direct call/return, and closure relations from inline application Evidence or an exact same-session retained reference. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
         kind: "application",
         inputSchema: traceJavaScriptSemanticsRequestSchema,
         outputSchema: semanticTraceOutputSchema,
@@ -56,7 +67,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "compare_application_versions",
         ...toolContractMetadata("compare_application_versions"),
-        description: "Compare two authenticated JavaScript Application Graph versions supplied as inline Evidence. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus the complete matching changed_from graph without fuzzy or module-ordinal pairing.",
+        description: "Compare two authenticated JavaScript Application Graph versions supplied as inline Evidence or exact same-session retained references. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus the complete matching changed_from graph without fuzzy or module-ordinal pairing.",
         kind: "application",
         inputSchema: compareApplicationVersionsRequestSchema,
         outputSchema: comparisonOutputSchema,
@@ -65,12 +76,20 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Compare authenticated static and reconciled application graphs",
                 input: JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE,
+                    left: retained(JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.left.evidence_id),
+                    right: retained(JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE.right.evidence_id),
+                },
+            },
         ],
     },
     {
         name: "compare_source_to_bundle",
         ...toolContractMetadata("compare_source_to_bundle"),
-        description: "Compare a cryptographically committed HistoricalSourceGraph with inline authenticated JavaScript Application Graph Evidence. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.",
+        description: "Compare a cryptographically committed HistoricalSourceGraph with authenticated JavaScript Application Graph Evidence supplied inline or by exact same-session retained reference. Uses explicit exact-digest, source-map path, current-path, suffix, and basename signals with stable weights. Classifies unchanged, modified, removed, split, merged, duplicated, and unknown; incomplete coverage and ambiguous weak signals never become absence or forced matches.",
         kind: "application",
         inputSchema: compareSourceToBundleRequestSchema,
         outputSchema: sourceToBundleOutputSchema,
@@ -84,7 +103,7 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "compare_javascript_export_shapes",
         ...toolContractMetadata("compare_javascript_export_shapes"),
-        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
+        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
         kind: "application",
         inputSchema: compareJavaScriptExportShapesRequestSchema,
         outputSchema: exportShapeComparisonOutputSchema,
@@ -93,6 +112,14 @@ export const APPLICATION_TOOL_CONTRACTS = [
                 title: "Compare one exact parser export without execution",
                 input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
             },
+            {
+                title: "Use exact Evidence already retained in this session",
+                input: {
+                    ...JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
+                    left: retained(JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.left.evidence_id),
+                    right: retained(JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE.right.evidence_id),
+                },
+            },
         ],
     },
     {

package/dist/contracts/applicationWorkflowInputContracts.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { evidenceSchema } from "../domain/evidence.js";
+import { evidenceInputSchema } from "./evidenceInputContracts.js";
 import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
 import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
 import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
@@ -10,33 +10,33 @@ const traceApplicationFeatureFacts = {
     seed: traceApplicationFeatureInputSchema.shape.seed,
     direction: traceApplicationFeatureInputSchema.shape.direction,
 };
-/** MCP/CLI trace request carrying all Evidence inline. */
+/** Application trace request accepting inline or same-session application Evidence. */
 export const traceApplicationFeatureRequestSchema = z.strictObject({
     ...traceApplicationFeatureFacts,
-    application: evidenceSchema,
+    application: evidenceInputSchema,
 });
-/** MCP/CLI semantic trace request carrying Evidence inline. */
+/** Semantic trace request accepting inline or same-session application Evidence. */
 export const traceJavaScriptSemanticsRequestSchema = z.strictObject({
-    application: evidenceSchema,
+    application: evidenceInputSchema,
     query: javaScriptSemanticQueryInputSchema,
 });
 const compareApplicationVersionsFacts = {
     left_native_observations: compareApplicationVersionsInputSchema.shape.left_native_observations,
     right_native_observations: compareApplicationVersionsInputSchema.shape.right_native_observations,
 };
-/** MCP/CLI comparison request carrying all Evidence inline. */
+/** Application comparison request accepting inline or same-session application Evidence. */
 export const compareApplicationVersionsRequestSchema = z.strictObject({
     ...compareApplicationVersionsFacts,
-    left: evidenceSchema,
-    right: evidenceSchema,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
 });
 const compareSourceToBundleFacts = {
     reference: compareSourceToBundleInputSchema.shape.reference,
 };
-/** Historical-source comparison carrying application Evidence inline. */
+/** Historical-source comparison accepting inline or same-session application Evidence. */
 export const compareSourceToBundleRequestSchema = z.strictObject({
     ...compareSourceToBundleFacts,
-    application: evidenceSchema,
+    application: evidenceInputSchema,
 });
 const compareJavaScriptExportShapesFacts = {
     left_module_path: compareJavaScriptExportShapesInputSchema.shape.left_module_path,
@@ -44,9 +44,9 @@ const compareJavaScriptExportShapesFacts = {
     right_module_path: compareJavaScriptExportShapesInputSchema.shape.right_module_path,
     right_export_name: compareJavaScriptExportShapesInputSchema.shape.right_export_name,
 };
-/** MCP/CLI export-shape request carrying application Evidence inline. */
+/** Export-shape request accepting inline or same-session application Evidence. */
 export const compareJavaScriptExportShapesRequestSchema = z.strictObject({
     ...compareJavaScriptExportShapesFacts,
-    left: evidenceSchema,
-    right: evidenceSchema,
+    left: evidenceInputSchema,
+    right: evidenceInputSchema,
 });

package/dist/contracts/artifactComparisonExample.js

@@ -1,11 +1,10 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
+import { canonicalDigest } from "../domain/comparisonSemantics.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 const inventory = (digit) => {
     const sha = digit.repeat(64);
-    const artifactId = `art_${digestCanonical({ sha256: sha })}`;
-    const occurrenceId = `occ_${digestCanonical({ root: artifactId })}`;
+    const artifactId = `art_${canonicalDigest({ sha256: sha }, "Artifact example")}`;
+    const occurrenceId = `occ_${canonicalDigest({ root: artifactId }, "Artifact example")}`;
     const nodes = [
         {
             artifact_id: artifactId,
@@ -36,18 +35,18 @@ const inventory = (digit) => {
             limitations: [],
         },
     ];
-    const graphSha256 = digestCanonical({
+    const graphSha256 = canonicalDigest({
         nodes,
         occurrences,
         edges: [],
         integrity_contradictions: [],
-    });
+    }, "Artifact example");
     return jsonValueSchema.parse({
         manifest: {
-            manifest_id: `agm_${digestCanonical({
+            manifest_id: `agm_${canonicalDigest({
                 root_artifact_id: artifactId,
                 graph_sha256: graphSha256,
-            })}`,
+            }, "Artifact example")}`,
             root_artifact_id: artifactId,
             root_sha256: sha,
             root_format: "file",
@@ -63,12 +62,6 @@ const inventory = (digit) => {
         limitations: [],
     });
 };
-const digestCanonical = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Artifact example is not canonical JSON");
-    return createHash("sha256").update(encoded).digest("hex");
-};
 const provider = {
     id: "rea-artifact",
     name: "REA artifact graph",

package/dist/contracts/enhancedToolContracts.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { enhancedInputSchemas } from "./enhancedInputs.js";
+import { enhancedOutputSchemas, requireOutputSchema, } from "./toolOutputSchemas.js";
+import { examplesFor } from "./toolContractHelpers.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
+const enhanced = (name, description, inputSchema) => ({
+    name,
+    ...toolContractMetadata(name),
+    description,
+    kind: "enhanced",
+    inputSchema,
+    outputSchema: requireOutputSchema(enhancedOutputSchemas, name),
+    examples: examplesFor(name, inputSchema),
+});
+/** Workflow tools composed from one or more provider operations. */
+export const ENHANCED_TOOL_CONTRACTS = [
+    enhanced("inspect_native_dispatch_metadata", "Inspect the bound provider's name inventory for Objective-C class/method symbols and Swift mangled symbols, returning at most max_records decoded names. Includes target SHA-256 when available, provider identity/version, analysis-profile digest, facet coverage, and per-record Evidence. This is symbol-level evidence, not runtime metadata: ivar layouts, protocol conformances, witness/class tables, and relative pointers are explicitly marked unsupported unless a provider supplies those decoders. The provider controls how its name inventory is acquired.", enhancedInputSchemas.inspect_native_dispatch_metadata),
+    enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels, optionally filtering by literal substring.", enhancedInputSchemas.get_objc_classes),
+    enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels.", enhancedInputSchemas.get_objc_protocols),
+    enhanced("batch_decompile", "Decompile each explicit procedure symbol or address concurrently. Returns ordered per-item success or error results and aggregate counts.", enhancedInputSchemas.batch_decompile),
+    enhanced("get_call_graph", "Traverse the bound provider's caller or callee relationships from one symbol or address until the reachable graph is exhausted. Every node has an ok/error status and failures use safe typed projections; unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
+    enhanced("analyze_swift_types", 'Categorize analyzed procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Returns deduplicated names grouped with counts. Optionally select one category and/or apply a case-sensitive literal name filter; for example, use {category: "classes", pattern: "Account"} to find matching class symbols.', enhancedInputSchemas.analyze_swift_types),
+    enhanced("find_xrefs_to_name", "Resolve an exact name against the bound provider's name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
+    enhanced("binary_overview", "Return native-binary metadata, every segment with its length, and exhaustive procedure/string counts. Use search_procedures, list_procedures, or analyze_function directly when you already know which procedure to inspect.", enhancedInputSchemas.binary_overview),
+    ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
+    enhanced("trace_feature", "Trace a literal feature query through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
+    enhanced("trace_call_path", "Trace direct callers or callees from one exact procedure address until the graph is exhausted or the optional goal is reached. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
+    enhanced("trace_native_ui_action", "Trace one unique compiled UI action, object ID, native symbol or exact function address through authored connections, encoded or symbolized Objective-C handlers, and bounded static call references. Typed direct and resolved indirect calls, ambiguous candidates, inferred untyped provider callees, and targetless sites remain distinct. Runtime reachability is unknown; use trace_native_values for recovered value dependencies.", enhancedInputSchemas.trace_native_ui_action),
+    enhanced("trace_native_values", "Trace a bounded static dependency graph from one explicit native procedure. Includes high-p-code def-use, constants, operators, memory and branch operations, resolved call edges, and derived argument/parameter and return/output bindings. Missing bindings, alias semantics, persistent state and RNG roles remain unknown. Budgets bound depth, decompilations, graph size and payloads; nodes are paginated.", enhancedInputSchemas.trace_native_values),
+];

package/dist/contracts/errorSchemas.js

@@ -56,14 +56,16 @@ export const analysisErrorProjectionSchema = z.discriminatedUnion("code", [
     generic("target_unavailable"),
     generic("execution_failure"),
 ]);
-/** Legacy CLI envelope: a human label plus the canonical projected error fields. */
+/** CLI label and input diagnostics surrounding the strict canonical error projection. */
 export const analysisCliErrorEnvelopeSchema = z
     .object({
     error: z.string().min(1),
+    input_path: z.string().optional(),
+    input_reason: z.enum(["invalid-json", "read-failed"]).optional(),
 })
     .passthrough()
     .superRefine((value, context) => {
-    const { error: _label, ...projection } = value;
+    const { error: _label, input_path: _inputPath, input_reason: _inputReason, ...projection } = value;
     const parsed = analysisErrorProjectionSchema.safeParse(projection);
     if (!parsed.success) {
         context.addIssue({

package/dist/contracts/evidenceInputContracts.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { evidenceSchema } from "../domain/evidence.js";
+import { prefixedDigestSchema } from "../domain/digests.js";
+/** Exact reference to Evidence already retained by the current session. */
+export const retainedEvidenceReferenceSchema = z.strictObject({
+    kind: z.literal("retained-evidence"),
+    evidence_id: prefixedDigestSchema("ev"),
+});
+/** Portable inline Evidence or an exact, session-scoped reference. */
+export const evidenceInputSchema = z.union([
+    evidenceSchema,
+    retainedEvidenceReferenceSchema,
+]);

package/dist/contracts/firmwareToolContracts.js

@@ -0,0 +1,38 @@
+import { firmwareInputSchemas, firmwareResultSchemas, } from "../domain/firmwareAnalysis.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { toolContractMetadata } from "./toolEffects.js";
+/** Explicit local firmware observations and extraction, backed by caller-supplied tools. */
+export const FIRMWARE_TOOL_CONTRACTS = [
+    {
+        name: "inspect_firmware_regions",
+        ...toolContractMetadata("inspect_firmware_regions"),
+        kind: "firmware-provider",
+        description: "Inspect signature candidates in a local firmware file with Binwalk 3.1.0. Returns offsets, reported lengths, descriptions and raw confidence values. Length validation and runtime addresses remain unknown. No extraction or target execution. Linux, caller-supplied tool and util-linux prlimit required; 128 MiB input limit, one worker and 120-second deadline.",
+        inputSchema: firmwareInputSchemas.inspect_firmware_regions,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.inspect_firmware_regions),
+        examples: [
+            {
+                title: "Inspect firmware regions",
+                input: { path: "/tmp/firmware.bin" },
+            },
+        ],
+    },
+    {
+        name: "extract_firmware",
+        ...toolContractMetadata("extract_firmware"),
+        kind: "firmware-provider",
+        description: "Extract caller-selected firmware bytes with Unblob 26.6.4 into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks and extraction diagnostics inline. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
+        inputSchema: firmwareInputSchemas.extract_firmware,
+        outputSchema: evidenceResultOf(firmwareResultSchemas.extract_firmware),
+        examples: [
+            {
+                title: "Extract selected firmware",
+                input: {
+                    path: "/tmp/firmware.bin",
+                    output_directory: "/tmp/firmware-output",
+                    range: { offset: 64, length: 4096 },
+                },
+            },
+        ],
+    },
+];