rea-agents 6.2.0 → 6.4.0

package/dist/contracts/sessionToolContracts.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
+import { isAbsolute } from "node:path";
+import { localPathStringSchema } from "../domain/localPath.js";
 import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
 import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
 import { callPathInputSchema } from "../domain/callPathSchemas.js";
@@ -28,7 +29,7 @@ const session = (name, description, inputSchema) => ({
 /** Session-owned Evidence bundle export options. */
 export const exportEvidenceBundleInputSchema = z.strictObject({
     path: localPathStringSchema
-        .refine(isAbsoluteLocalPath, {
+        .refine(isAbsolute, {
         message: "path must be an absolute local filesystem path (for example /tmp/rea/evidence.json or C:\\rea\\evidence.json)",
     })
         .describe("Absolute local filesystem path for the exported evidence bundle; relative paths are rejected."),
@@ -41,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),
@@ -54,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

@@ -1,10 +1,15 @@
 import { z } from "zod";
-import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
+import { isAbsolute } from "node:path";
+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(),
@@ -17,7 +22,7 @@ export const addressContextInputSchema = z.strictObject({
 /** Session-owned Evidence bundle import options. */
 export const importEvidenceBundleInputSchema = z.strictObject({
     path: localPathStringSchema
-        .refine(isAbsoluteLocalPath, {
+        .refine(isAbsolute, {
         message: "path must be an absolute local filesystem path (for example /tmp/evidence.json or C:\\rea\\evidence.json)",
     })
         .describe("Absolute local filesystem path for the evidence bundle to import; relative paths are rejected."),

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,

package/dist/contracts/toolEffects.js

@@ -57,6 +57,7 @@ export const TOOL_EFFECTS = {
         writesFilesystem: true,
         launchesProcess: true,
     }),
+    inspect_pe_resources: evidence,
     inspect_analysis_view: evidence,
     inspect_firmware_regions: effects({
         mutatesSession: true,
@@ -74,6 +75,172 @@ export const TOOL_EFFECTS = {
         launchesProcess: true,
         writesFilesystem: true,
     }),
+    inspect_apktool_client: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+    }),
+    decode_android_resources: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+    }),
+    inspect_jeb_client: effects({
+        mutatesSession: true,
+        accessesNetwork: true,
+    }),
+    open_jeb_project: effects({
+        mutatesSession: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    list_jeb_units: effects({
+        mutatesSession: true,
+        accessesNetwork: true,
+    }),
+    decompile_jeb_item: effects({
+        mutatesSession: true,
+        accessesNetwork: true,
+    }),
+    inspect_adb_client: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+    }),
+    list_adb_devices: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    inspect_adb_device: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    list_adb_packages: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    pull_adb_package: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    read_adb_logcat: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    inspect_adb_package: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    pull_adb_file: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    push_adb_file: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    capture_adb_screen: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    list_adb_processes: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    list_adb_directory: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    list_adb_features: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    list_adb_services: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    inspect_adb_display: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    inspect_adb_window: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    read_adb_setting: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    collect_adb_bugreport: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        writesFilesystem: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    resolve_adb_packages: effects({
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+    }),
+    install_adb_package: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    uninstall_adb_package: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    start_adb_app: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    start_adb_activity: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
+    stop_adb_app: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        idempotent: false,
+    }),
     search_android_classes: effects({
         mutatesSession: true,
         launchesProcess: true,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { evidenceBundleSummarySchema } from "../domain/evidenceRecordSummary.js";
+import { BINARY_ARCHITECTURES } from "../domain/binaryTargetTypes.js";
 import { nativeFunctionAnnotationsSchema } from "../domain/native/nativeFunctionAnnotations.js";
 import { nativeLoadImageSchema } from "../domain/native/nativeLoadImage.js";
 import { nativeUiResultSchema } from "../domain/native/nativeUiObservation.js";
@@ -115,8 +117,8 @@ export const officialOutputSchemas = {
     procedure_references: evidenceResultOf(z.object({
         procedure: procedureIdentitySchema,
         direction: z.enum(["incoming", "outgoing"]),
-        reference_kinds_available: z.boolean().optional(),
-        unresolved_calls: z.array(unresolvedCallSchema).default([]),
+        reference_kinds_available: z.boolean(),
+        unresolved_calls: z.array(unresolvedCallSchema),
         references: z.array(referenceEdgeSchema),
     })),
     procedure_pseudo_code: evidenceResultOf(nullableText),
@@ -305,7 +307,7 @@ export const sessionOutputSchemas = {
         format: targetFormatSchema,
         kind: targetKindSchema,
         sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-        architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+        architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
     })),
     close_binary: lifecycleResultOf(z.union([
         z.null(),
@@ -340,7 +342,7 @@ export const sessionOutputSchemas = {
                 format: targetFormatSchema,
                 kind: targetKindSchema,
                 sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-                architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+                architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
             }),
         ]),
     ])),
@@ -350,7 +352,7 @@ export const sessionOutputSchemas = {
         records: z.number().int().min(0),
         unknowns: z.number().int().min(0),
     })),
-    get_evidence_bundle: lifecycleResultOf(evidenceBundleSchema),
+    get_evidence_bundle: lifecycleResultOf(z.union([evidenceBundleSchema, evidenceBundleSummarySchema])),
     get_navigation_context: lifecycleResultOf(z.object({
         document: z.string(),
         address: z.string(),

package/dist/contracts/toolOutputSchemaPrimitives.js

@@ -405,11 +405,8 @@ export const procedureInfoOutput = evidenceResultOf(z.object({
     length: z.number().min(0),
     signature: nullableText,
     locals: z.array(localVariableSchema),
-    classification: procedureClassificationSchema.nullable().default(null),
-    body: functionBodySchema.default({
-        available: false,
-        reason: "The provider did not report complete function body ranges.",
-    }),
+    classification: procedureClassificationSchema.nullable(),
+    body: functionBodySchema,
 }));
 export const symbolDiscoveryOutput = (property) => evidenceResultOf(z.object({
     count: z.number().int().min(0),

package/dist/contracts/toolSchemaMetadata.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { advertisedInputExamples } from "./advertisedInputExamples.js";
 import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
+import { digestCanonicalValue } from "../domain/canonicalDigest.js";
 const PROPERTY_DESCRIPTIONS = {
     addresses: "Ordered provider-normalized procedure addresses to analyze.",
     after: "The later or right-hand observation to compare.",
@@ -44,16 +46,87 @@ export const toolInputSchemaWithMetadata = (contract) => withAdvertisedJsonSchem
         ...options,
         libraryOptions: { reused: "ref", ...options.libraryOptions },
     });
+    const examples = advertisedInputExamples(contract);
     return {
         ...presentInputJsonSchema(shared, fallbackPropertyDescription),
-        examples: contract.examples.map(({ input }) => input),
+        ...(examples.length === 0 ? {} : { examples }),
     };
 });
-/** Share repeated output definitions without changing canonical validation. */
-export const toolOutputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.outputSchema, "output", (project) => (options) => project({
-    ...options,
-    libraryOptions: { reused: "ref", ...options.libraryOptions },
-}));
+/** Share output definitions and content-bound validator identities on the wire. */
+export const toolOutputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.outputSchema, "output", (project) => (options) => {
+    const shared = project({
+        ...options,
+        libraryOptions: { reused: "ref", ...options.libraryOptions },
+    });
+    // An explicit ID owns the reference base. Relative external references
+    // also depend on that base, so leave those projections unchanged.
+    if ("$id" in shared || hasRelativeSchemaReference(shared))
+        return shared;
+    return {
+        ...shared,
+        $id: `urn:rea:tool-output:sha256:${digestCanonicalValue({ target: options.target, schema: shared }, "Tool output schema")}`,
+    };
+});
+/**
+ * Apply a wire-presentation transform to one schema's advertised input
+ * projection. The wrapper preserves the schema's own parser and standard
+ * metadata, so both Zod registrations and plain standard schemas keep their
+ * canonical validation while only the advertised JSON changes.
+ */
+export const transformAdvertisedInputJsonSchema = (schema, transform) => {
+    const standard = Reflect.get(schema, "~standard");
+    if (!isSchemaRecord(standard))
+        return schema;
+    const jsonSchema = Reflect.get(standard, "jsonSchema");
+    if (!isSchemaRecord(jsonSchema))
+        return schema;
+    const project = Reflect.get(jsonSchema, "input");
+    if (typeof project !== "function")
+        return schema;
+    const byTarget = new Map();
+    const transformedInput = (options) => {
+        const target = Reflect.get(options, "target");
+        if (typeof target === "string") {
+            const cached = byTarget.get(target);
+            if (cached !== undefined)
+                return cached;
+        }
+        const projected = project(options);
+        const transformed = isSchemaRecord(projected)
+            ? transform(projected)
+            : projected;
+        if (typeof target === "string" && isSchemaRecord(transformed))
+            byTarget.set(target, transformed);
+        return transformed;
+    };
+    return {
+        ...schema,
+        "~standard": {
+            ...standard,
+            jsonSchema: { ...jsonSchema, input: transformedInput },
+        },
+    };
+};
+const hasRelativeSchemaReference = (schema) => {
+    const pending = [schema];
+    const visited = new WeakSet();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === null || typeof current !== "object" || visited.has(current))
+            continue;
+        visited.add(current);
+        for (const [key, value] of Object.entries(current)) {
+            if (["$id", "$ref", "$dynamicRef", "$recursiveRef"].includes(key) &&
+                typeof value === "string" &&
+                !value.startsWith("#") &&
+                !URL.canParse(value))
+                return true;
+            if (value !== null && typeof value === "object")
+                pending.push(value);
+        }
+    }
+    return false;
+};
 const withAdvertisedJsonSchema = (canonical, io, advertise = (project) => project) => {
     // Zod's input projection drops root metadata when a descendant transforms.
     // Preserve the parser and let the SDK own conversion of everything else.
@@ -89,6 +162,7 @@ const memoizeByTarget = (project) => {
         return projected;
     };
 };
+const isSchemaRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const fallbackPropertyDescription = (property) => {
     const explicit = Object.hasOwn(PROPERTY_DESCRIPTIONS, property)
         ? PROPERTY_DESCRIPTIONS[property]
@@ -118,5 +192,6 @@ const fallbackPropertyDescription = (property) => {
         return `Local filesystem ${words} selected for this operation.`;
     if (property.startsWith("is_") || property.startsWith("has_"))
         return `Whether ${words}.`;
-    return `Value for ${words}.`;
+    // A generic sentence would only restate the property name in every schema.
+    return undefined;
 };