rea-agents 2.5.0 → 3.1.0

package/dist/contracts/managedWorkflowToolContracts.js

@@ -7,6 +7,7 @@ import { projectManagedApplicationGraphInputSchema } from "../domain/managedAppl
 import { managedWorkflowOutputSchemas } from "./toolOutputSchemas.js";
 import { MANAGED_MEMBER_COMPARISON_EXAMPLE, MANAGED_NATIVE_VERIFICATION_EXAMPLE, MANAGED_APPLICATION_GRAPH_EXAMPLE, MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE, MANAGED_RUNTIME_CORRELATION_EXAMPLE, } from "./managedWorkflowExamples.js";
 import { toolContractMetadata } from "./toolEffects.js";
+import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 const managedEvidenceIdSchema = evidenceIdSchema.describe("Session-owned inspect_managed_members Evidence ID");
 const managedArtifactEvidenceIdSchema = evidenceIdSchema.describe("Session-owned inspect_managed_artifact Evidence ID");
@@ -66,46 +67,48 @@ export const managedNativeVerificationReferenceInputSchema = z
         ids.add(evidenceId);
     }
 });
-/** MCP references for projecting managed Evidence into an application graph. */
-export const managedApplicationGraphReferenceInputSchema = z
-    .strictObject({
-    managed_artifact_evidence_id: managedArtifactEvidenceIdSchema.optional(),
-    managed_members_evidence_id: managedEvidenceIdSchema.optional(),
-    managed_native_boundaries_evidence_id: managedBoundaryEvidenceIdSchema.optional(),
+const managedApplicationGraphReferenceFacts = {
     limits: projectManagedApplicationGraphInputSchema.shape.limits,
-})
+};
+/** MCP references requiring at least one managed Evidence source. */
+export const managedApplicationGraphReferenceInputSchema = z
+    .union([
+    z.strictObject({
+        ...managedApplicationGraphReferenceFacts,
+        managed_artifact_evidence_id: managedArtifactEvidenceIdSchema,
+        managed_members_evidence_id: managedEvidenceIdSchema.optional(),
+        managed_native_boundaries_evidence_id: managedBoundaryEvidenceIdSchema.optional(),
+    }),
+    z.strictObject({
+        ...managedApplicationGraphReferenceFacts,
+        managed_artifact_evidence_id: managedArtifactEvidenceIdSchema.optional(),
+        managed_members_evidence_id: managedEvidenceIdSchema,
+        managed_native_boundaries_evidence_id: managedBoundaryEvidenceIdSchema.optional(),
+    }),
+    z.strictObject({
+        ...managedApplicationGraphReferenceFacts,
+        managed_artifact_evidence_id: managedArtifactEvidenceIdSchema.optional(),
+        managed_members_evidence_id: managedEvidenceIdSchema.optional(),
+        managed_native_boundaries_evidence_id: managedBoundaryEvidenceIdSchema,
+    }),
+])
     .superRefine((input, context) => {
     const ids = [
         input.managed_artifact_evidence_id,
         input.managed_members_evidence_id,
         input.managed_native_boundaries_evidence_id,
     ].filter((id) => id !== undefined);
-    if (ids.length === 0)
-        context.addIssue({
-            code: "custom",
-            message: "At least one managed Evidence ID is required",
-        });
     if (new Set(ids).size !== ids.length)
         context.addIssue({
             code: "custom",
             message: "Managed application graph Evidence IDs must be unique",
         });
 });
-const comparisonOutputSchema = managedWorkflowOutputSchemas.compare_managed_members;
-if (comparisonOutputSchema === undefined)
-    throw new Error("Missing managed workflow output schema for compare_managed_members");
-const runtimeOutputSchema = managedWorkflowOutputSchemas.plan_managed_runtime_correlation;
-if (runtimeOutputSchema === undefined)
-    throw new Error("Missing managed workflow output schema for plan_managed_runtime_correlation");
-const reconstructionOutputSchema = managedWorkflowOutputSchemas.import_managed_reconstruction;
-if (reconstructionOutputSchema === undefined)
-    throw new Error("Missing managed workflow output schema for import_managed_reconstruction");
-const nativeVerificationOutputSchema = managedWorkflowOutputSchemas.verify_managed_native_boundaries;
-if (nativeVerificationOutputSchema === undefined)
-    throw new Error("Missing managed workflow output schema for verify_managed_native_boundaries");
-const managedApplicationGraphOutputSchema = managedWorkflowOutputSchemas.project_managed_application_graph;
-if (managedApplicationGraphOutputSchema === undefined)
-    throw new Error("Missing managed workflow output schema for project_managed_application_graph");
+const comparisonOutputSchema = requireOutputSchema(managedWorkflowOutputSchemas, "compare_managed_members");
+const runtimeOutputSchema = requireOutputSchema(managedWorkflowOutputSchemas, "plan_managed_runtime_correlation");
+const reconstructionOutputSchema = requireOutputSchema(managedWorkflowOutputSchemas, "import_managed_reconstruction");
+const nativeVerificationOutputSchema = requireOutputSchema(managedWorkflowOutputSchemas, "verify_managed_native_boundaries");
+const managedApplicationGraphOutputSchema = requireOutputSchema(managedWorkflowOutputSchemas, "project_managed_application_graph");
 /** Provider-neutral managed-code workflow contracts. */
 export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
     {

package/dist/contracts/nativeToolContracts.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { nativeOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
+import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
 const examples = {
     inspect_macho: {},
     inspect_signature: {},
@@ -10,9 +11,7 @@ const examples = {
     demangle_swift: { symbols: ["$s4Test3fooyyF"] },
 };
 const native = (name, description, inputSchema) => {
-    const outputSchema = nativeOutputSchemas[name];
-    if (outputSchema === undefined)
-        throw new Error(`Missing native output schema for ${name}`);
+    const outputSchema = requireOutputSchema(nativeOutputSchemas, name);
     return {
         name,
         ...toolContractMetadata(name),

package/dist/contracts/promptContracts.js

@@ -1,4 +1,3 @@
-import { TOOL_CONTRACTS } from "./toolContracts.js";
 const optional = (description, completion) => ({
     description,
     required: false,
@@ -81,8 +80,8 @@ export const PROMPT_CONTRACTS = [
                 instruction: "Build function dossiers and corroborate references and call relationships. Keep indirect or truncated paths unknown.",
             },
             {
-                tools: ["export_evidence_bundle", "record_unknown"],
-                instruction: "Cite retained Evidence IDs. Record residual unknowns only after separate explicit approval for registry mutation.",
+                tools: ["snapshot_evidence_bundle", "record_unknown"],
+                instruction: "Snapshot the canonical bundle, copy its opaque URI unchanged, and read that resource before citing retained Evidence IDs. Record residual unknowns only after separate explicit approval for registry mutation.",
             },
         ],
     },
@@ -100,8 +99,8 @@ export const PROMPT_CONTRACTS = [
         },
         steps: [
             {
-                tools: ["inventory_artifact"],
-                instruction: "Inventory each target independently before extraction. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
+                tools: ["open_binary", "inventory_artifact"],
+                instruction: "For each supplied target path, open that target before inventory because inventory_artifact uses the active target and accepts no path. Follow nodes, occurrences, and edges to completion and retain every Evidence page for each manifest.",
             },
             {
                 tools: [
@@ -112,8 +111,8 @@ export const PROMPT_CONTRACTS = [
                 instruction: "For JavaScript/Electron versions, reconstruct each approved artifact independently, optionally reconcile separately retained passive runtime Evidence, then compare authenticated graphs with unique-only identity tiers. Keep ambiguous and incomplete matches unknown.",
             },
             {
-                tools: ["export_evidence_bundle", "compare_artifacts"],
-                instruction: "Resolve any supplied manifest IDs to retained inventory Evidence, validate graph commitments, then compare the complete left and right Evidence page sets.",
+                tools: ["snapshot_evidence_bundle", "compare_artifacts"],
+                instruction: "Snapshot and read the canonical bundle through its exact resource URI, resolve any supplied manifest IDs to retained inventory Evidence, validate graph commitments, then compare the complete left and right Evidence page sets.",
             },
             {
                 tools: ["open_binary", "analyze_function", "compare_functions"],
@@ -141,8 +140,8 @@ export const PROMPT_CONTRACTS = [
         },
         steps: [
             {
-                tools: ["export_evidence_bundle"],
-                instruction: "Load the current canonical bundle and verify that every selected comparison Evidence ID is present and compatible with the intended claim.",
+                tools: ["snapshot_evidence_bundle"],
+                instruction: "Snapshot the current canonical bundle, copy its opaque URI unchanged, read the resource, and verify that every selected comparison Evidence ID is present and compatible with the intended claim.",
             },
             {
                 tools: [
@@ -194,11 +193,11 @@ export const PROMPT_CONTRACTS = [
             },
             {
                 tools: [
-                    "export_evidence_bundle",
+                    "snapshot_evidence_bundle",
                     "capture_process_scenario",
                     "correlate_static_and_runtime",
                 ],
-                instruction: "Reuse a retained capture when supplied. Otherwise capture only after operator policy and per-call approval, then correlate through explicit hypotheses rather than timing or name coincidence.",
+                instruction: "Snapshot and read retained Evidence through the exact resource URI. Reuse a retained capture when supplied. Otherwise capture only after operator policy and per-call approval, then correlate through explicit hypotheses rather than timing or name coincidence.",
             },
             {
                 tools: ["record_unknown"],
@@ -222,8 +221,8 @@ export const PROMPT_CONTRACTS = [
                 instruction: "List current heads first and select only active, session-owned unknown IDs. Preserve their exact revision and requirements.",
             },
             {
-                tools: ["export_evidence_bundle", "verify_unknown_resolution"],
-                instruction: "Inspect cited supporting, contradicting, and mutation Evidence, then validate any resolved head against bundle integrity and authority requirements.",
+                tools: ["snapshot_evidence_bundle", "verify_unknown_resolution"],
+                instruction: "Snapshot and read the canonical bundle through its exact resource URI, inspect cited supporting, contradicting, and mutation Evidence, then validate any resolved head against bundle integrity and authority requirements.",
             },
             {
                 tools: ["update_unknown"],
@@ -252,8 +251,8 @@ export const PROMPT_CONTRACTS = [
                 instruction: "Inspect capture capability, declared effects, and limits before proposing execution. An unavailable capability is not permission to widen policy.",
             },
             {
-                tools: ["export_evidence_bundle"],
-                instruction: "Review any prior capture for unanswered dimensions, truncation, scenario commitments, and descendant settlement before designing a repeat.",
+                tools: ["snapshot_evidence_bundle"],
+                instruction: "Snapshot and read the canonical bundle through its exact resource URI, then review any prior capture for unanswered dimensions, truncation, scenario commitments, and descendant settlement before designing a repeat.",
             },
             {
                 tools: ["capture_process_scenario"],

package/dist/contracts/sessionToolSchemas.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
+import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
+import { callPathInputSchema } from "../domain/callPath.js";
+import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
+import { functionComparisonInputSchema } from "../domain/functionComparison.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { processScenarioSchema } from "../domain/processCapture.js";
+import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
+import { recordUnknownInputSchema } from "../domain/residualUnknown.js";
+import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
+import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
+import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
+import { updateUnknownInputSchema } from "../domain/residualUnknown.js";
+import { openBinaryInputSchema, closeBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { binarySessionInputSchema } from "./sessionStatusContract.js";
+/** Retain the current canonical Evidence bundle as a session resource. */
+export const snapshotEvidenceBundleInputSchema = z.strictObject({});
+/** Release one session-retained immutable Evidence bundle. */
+export const releaseEvidenceBundleInputSchema = z.strictObject({
+    bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+});
+/** Optional document selection for volatile navigation context. */
+export const navigationContextInputSchema = z.strictObject({
+    document: z.string().min(1).optional(),
+});
+/** Explicit reproducible address context query. */
+export const addressContextInputSchema = z.strictObject({
+    address: z.string().min(1),
+    document: z.string().min(1).optional(),
+});
+/** Session-owned Evidence bundle import options. */
+export const importEvidenceBundleInputSchema = z.strictObject({
+    path: z.string().min(1),
+});
+/** Evidence references for deterministic process comparison. */
+export const processComparisonInputSchema = z.strictObject({
+    left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
+    trace_spec: processTraceSpecificationSchema.optional(),
+    max_capture_age_ms: z.number().int().nonnegative().optional(),
+    unknown_registry_approved: z
+        .literal(true)
+        .optional()
+        .describe("Explicit approval to record capture disagreement durably"),
+});
+/** Residual-unknown list filters. */
+export const listUnknownsInputSchema = z.strictObject({
+    status: z
+        .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
+        .optional(),
+    severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+    domain: z.string().trim().min(1).max(100).optional(),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+});
+/** Exact residual-unknown identity to revalidate. */
+export const verifyUnknownResolutionInputSchema = z.strictObject({
+    unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u),
+});
+export { artifactComparisonInputSchema, binarySessionInputSchema, bundleComparisonInputSchema, callPathInputSchema, changedBehaviorInputSchema, closeBinaryInputSchema, functionComparisonInputSchema, jsonValueSchema, openBinaryInputSchema, processScenarioSchema, reconstructionVerificationInputSchema, recordUnknownInputSchema, replayMachineRunInputSchema, staticRuntimeCorrelationInputSchema, updateUnknownInputSchema, };

package/dist/contracts/toolContractExamples.js

@@ -31,11 +31,15 @@ export const TOOL_EXAMPLE_OVERRIDES = {
     get_call_graph: { address: "0x1000" },
     find_xrefs_to_name: { name: "malloc" },
     analyze_function: { procedure: "main" },
+    inspect_native_api: { procedure: "main" },
     trace_feature: { query: "license" },
     find_code_for_string: { query: "authorization failed" },
     trace_call_path: { start: "0x1000", goal: "0x1100" },
     open_binary: { path: "/tmp/fixture" },
+    export_evidence_bundle: { path: "/tmp/evidence.json" },
+    inspect_address_context: { address: "0x1000" },
     import_evidence_bundle: { path: "evidence.json" },
+    release_evidence_bundle: { bundle_digest: "a".repeat(64) },
     capture_process_scenario: {
         approved: true,
         executable: "/usr/bin/true",

package/dist/contracts/toolContractHelpers.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
+export const document = z.string().optional().describe("The document name");
+export const address = z
+    .string()
+    .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
+export const optionalAddress = address.optional();
+export const procedure = z.string().describe("The procedure name or address");
+export const pagination = {
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+};
+const exampleInputSchema = z.record(z.string(), jsonValueSchema);
+export const examplesFor = (name, inputSchema) => {
+    const parsed = inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {});
+    return [
+        {
+            title: `Example ${name.replaceAll("_", " ")} request`,
+            input: exampleInputSchema.parse(parsed),
+        },
+    ];
+};

package/dist/contracts/toolContracts.js

@@ -1,19 +1,6 @@
 import { z } from "zod";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { processScenarioSchema } from "../domain/processCapture.js";
-import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
-import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
-import { functionComparisonInputSchema } from "../domain/functionComparison.js";
-import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
-import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
-import { callPathInputSchema } from "../domain/callPath.js";
-import { staticRuntimeCorrelationInputSchema } from "../domain/staticRuntimeCorrelation.js";
-import { reconstructionVerificationInputSchema } from "../domain/reconstructionVerification.js";
-import { replayMachineRunInputSchema } from "../domain/replayMachineRun.js";
-import { processTraceSpecificationSchema } from "../domain/processTraceComparison.js";
 import { enhancedInputSchemas } from "./enhancedInputs.js";
 import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sessionOutputSchemas, } from "./toolOutputSchemas.js";
-import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
 import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
 import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
 import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";
@@ -22,33 +9,14 @@ import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.
 import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
 import { JAVASCRIPT_RUNTIME_OBSERVATION_TOOL_CONTRACTS } from "./javascriptRuntimeObservationToolContracts.js";
 import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
-import { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { addressContextInputSchema, artifactComparisonInputSchema, binarySessionInputSchema, bundleComparisonInputSchema, callPathInputSchema, changedBehaviorInputSchema, closeBinaryInputSchema, functionComparisonInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, openBinaryInputSchema, processComparisonInputSchema, processScenarioSchema, reconstructionVerificationInputSchema, recordUnknownInputSchema, releaseEvidenceBundleInputSchema, replayMachineRunInputSchema, snapshotEvidenceBundleInputSchema, staticRuntimeCorrelationInputSchema, updateUnknownInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
+import { address, document, examplesFor, optionalAddress, pagination, procedure, } from "./toolContractHelpers.js";
 import { toolContractMetadata } from "./toolEffects.js";
-import { binarySessionInputSchema } from "./sessionStatusContract.js";
 import { functionInstructionInputSchema } from "./functionInstructionContract.js";
 import { HOPPER_MEMORY_TOOL_DEFINITIONS } from "./hopperMemoryContracts.js";
 import { analysisSearchInput } from "./analysisSearchContract.js";
-export { binarySessionInputSchema } from "./sessionStatusContract.js";
-const document = z.string().optional().describe("The document name");
-const address = z
-    .string()
-    .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
-const optionalAddress = address.optional();
-const procedure = z.string().describe("The procedure name or address");
-const pagination = {
-    offset: z.number().int().min(0).default(0),
-    limit: z.number().int().min(1).max(500).default(100),
-};
-const exampleInputSchema = z.record(z.string(), jsonValueSchema);
-const examplesFor = (name, inputSchema) => {
-    const parsed = inputSchema.parse(TOOL_EXAMPLE_OVERRIDES[name] ?? {});
-    return [
-        {
-            title: `Example ${name.replaceAll("_", " ")} request`,
-            input: exampleInputSchema.parse(parsed),
-        },
-    ];
-};
+import { FUNCTION_WORKFLOW_TOOL_CONTRACTS } from "./functionWorkflowToolContracts.js";
+export { addressContextInputSchema, binarySessionInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, processComparisonInputSchema, releaseEvidenceBundleInputSchema, snapshotEvidenceBundleInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
 const official = (name, description, inputSchema) => {
     const trackedInputSchema = inputSchema.extend({
         unknown_registry_approved: z
@@ -139,49 +107,22 @@ export const ENHANCED_TOOL_CONTRACTS = [
     enhanced("analyze_swift_types", "Categorize exhaustively paged procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Scans at most 5,000 names and returns at most 50 entries per category.", enhancedInputSchemas.analyze_swift_types),
     enhanced("find_xrefs_to_name", "Resolve an exact name through the bound provider's exhaustively paged name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this compact xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
     enhanced("binary_overview", "Use immediately after opening a target to summarize document, exhaustive procedure/string counts, and a bounded segment sample. detail controls segment fields and limit controls only the returned segment sample.", enhancedInputSchemas.binary_overview),
-    enhanced("analyze_function", "Preferred bounded analysis for one procedure symbol or address. Returns identity, provider-specific pseudocode, optional assembly, comments, calls, typed-or-explicitly-unavailable references, referenced strings/names, and local CFG blocks with exact truncation metadata.", enhancedInputSchemas.analyze_function),
+    ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
     enhanced("trace_feature", "Trace a bounded literal feature query through matching strings and procedures, xrefs, and truthful containing-procedure resolution. Returns the operation budget, truncation, and residual unknowns; unknown_registry_approved: true records them durably without inferring reference kinds.", enhancedInputSchemas.trace_feature),
     enhanced("find_code_for_string", "Resolve one literal string query to bounded analyzed string entries, xrefs, and truthful containing-procedure candidates. Returns an Evidence ID, exact operation budget, truncation, and residual unknowns; it never infers reference kinds or runtime reachability.", enhancedInputSchemas.find_code_for_string),
     enhanced("trace_call_path", "Trace a deterministic bounded caller or callee path from one exact procedure address, optionally stopping at a goal. Returns visited nodes, direct-call edges, one shortest traversal path, failures, frontier, consumed limits, an Evidence ID, and explicit residual unknowns without claiming unresolved indirect calls are absent.", enhancedInputSchemas.trace_call_path),
 ];
 /** Session-owned Evidence bundle export options. */
 export const exportEvidenceBundleInputSchema = z.strictObject({
-    path: z.string().min(1).optional(),
-    overwrite: z.boolean().default(false),
-});
-/** Session-owned Evidence bundle import options. */
-export const importEvidenceBundleInputSchema = z.strictObject({
     path: z.string().min(1),
-});
-/** Evidence references for deterministic process comparison. */
-export const processComparisonInputSchema = z.strictObject({
-    left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-    right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-    trace_spec: processTraceSpecificationSchema.optional(),
-    max_capture_age_ms: z.number().int().nonnegative().optional(),
-    unknown_registry_approved: z
-        .literal(true)
-        .optional()
-        .describe("Explicit approval to record capture disagreement durably"),
-});
-/** Residual-unknown list filters. */
-export const listUnknownsInputSchema = z.strictObject({
-    status: z
-        .enum(["open", "investigating", "blocked", "contradicted", "resolved"])
-        .optional(),
-    severity: z.enum(["low", "medium", "high", "critical"]).optional(),
-    domain: z.string().trim().min(1).max(100).optional(),
-});
-/** Exact residual-unknown identity to revalidate. */
-export const verifyUnknownResolutionInputSchema = z.strictObject({
-    unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u),
+    overwrite: z.boolean().default(false),
 });
 /** Target lifecycle tools available only on the long-lived MCP adapter. */
 export const SESSION_TOOL_CONTRACTS = [
     session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. An optional snapshot v2 is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly.", openBinaryInputSchema),
     session("close_binary", "Optionally write a provider-neutral analysis snapshot atomically, then close the active target and every provider resource started for it. Snapshot files require an operator-approved root and explicit overwrite; a failed save leaves the session open so cached analysis is not lost.", closeBinaryInputSchema),
     session("binary_session", "Report compact target, provider, and alignment state without starting analysis. The default summary is the routing check agents should use; detail=capabilities returns one family-filtered availability page, while detail=full is reserved for complete provider diagnostics.", binarySessionInputSchema),
-    session("export_evidence_bundle", "Return the session's deterministic Evidence v2 bundle, or atomically write it beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
+    session("export_evidence_bundle", "Atomically write the session's deterministic Evidence v2 bundle beneath an operator-approved root. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering. For an in-session read, use snapshot_evidence_bundle and read its exact resource URI instead.", exportEvidenceBundleInputSchema),
     session("import_evidence_bundle", "Read a bounded local JSON bundle beneath an operator-approved root, validate every Evidence v2 ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
     session("capture_process_scenario", "Run one bounded process under a PTY using operator-approved executable and working roots. Produces Process Capture v4; legacy v3 captures cannot be upgraded and must be recaptured with this tool. Requires approved: true; unknown_registry_approved: true separately records capture residuals. Captures raw and xterm-rendered terminal frames, scripted interactions, lifecycle filesystem checkpoints, process ownership, declarative command shims, and loopback replay. Disabled unless operator policy enables it; not a security sandbox.", processScenarioSchema),
     session("compare_process_captures", "Compare two compatible Process Capture v4 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),
@@ -192,11 +133,15 @@ export const SESSION_TOOL_CONTRACTS = [
     session("build_call_path", "Build bounded shortest-first direct-callee paths from explicit analyze_function Evidence groups using exact canonical addresses. Missing dossiers, incomplete callee pages, provider mixing, and depth frontiers remain unknown; every node and edge cites source Evidence.", callPathInputSchema),
     session("correlate_static_and_runtime", "Evaluate explicit caller-declared hypotheses between exact static comparison findings and runtime comparison dimensions. Similar names or paths are never auto-matched, consistent cochange never proves causality, and unknown or truncated inputs remain unresolved.", staticRuntimeCorrelationInputSchema),
     session("verify_reconstruction", "Verify a finite typed behavioral and structural specification against a canonical Evidence bundle. Pass means every declared claim has complete comparable authority—not global source equivalence; changed claims fail and missing, limited, or unresolved evidence stays unknown.", reconstructionVerificationInputSchema),
-    session("list_unknowns", "List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.", listUnknownsInputSchema),
+    session("list_unknowns", "List current residual-unknown heads in deterministic ID order, with optional exact status, severity, and domain filters. Pages default to 100 items; while has_more is true, pass next_offset as offset and continue until false. This is read-only; unresolved, contradicted, and non-truth dispositions remain distinct.", listUnknownsInputSchema),
     session("record_unknown", "Create one deterministic residual unknown and immutable mutation evidence. Requires approved: true, 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 approved: true and 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("run_replay_machine", "Evaluate ordered HTTP and WebSocket events directly against one validated finite replay machine without opening sockets or launching a target. Returns every decision, a capture-value-free transition journal, one redacted action table entry per used transition, captured aliases, final state, and exact configured and consumed limits.", replayMachineRunInputSchema),
+    session("snapshot_evidence_bundle", "Retain the current canonical Evidence v2 bundle as an immutable session resource. Returns a compact digest summary and exact opaque URI; copy that URI unchanged and call MCP resources/read (Codex: read_mcp_resource) for the full bundle. Repeating an unchanged snapshot is idempotent.", snapshotEvidenceBundleInputSchema),
+    session("release_evidence_bundle", "Release one immutable session-retained Evidence v2 bundle by exact digest. This is the recovery operation when bounded bundle retention is exhausted; releasing an unknown digest is idempotent and reports released: false.", releaseEvidenceBundleInputSchema),
+    session("get_navigation_context", "Compose the selected document, current address, and containing/current procedure into one provider-neutral result. The result reflects sequential provider observations, not an atomic cursor snapshot; a cursor outside any procedure returns procedure: null. Scalar navigation getters remain available for evaluation and compatibility.", 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; xrefs, assembly, and pseudocode remain separate bounded follow-ups.", addressContextInputSchema),
 ];
 /** Complete ordered public inventory used by registration and verification. */
 export const TOOL_CONTRACTS = [

package/dist/contracts/toolEffects.js

@@ -67,6 +67,7 @@ export const TOOL_EFFECTS = {
     find_xrefs_to_name: evidence,
     binary_overview: evidence,
     analyze_function: evidence,
+    inspect_native_api: effects({ mutatesSession: true, idempotent: false }),
     trace_feature: effects({ mutatesSession: true, idempotent: false }),
     find_code_for_string: effects({ mutatesSession: true, idempotent: false }),
     trace_call_path: effects({ mutatesSession: true, idempotent: false }),
@@ -106,6 +107,16 @@ export const TOOL_EFFECTS = {
     }),
     list_electron_targets: browserEvidence,
     inspect_electron_page: browserEvidence,
+    capture_electron_scenario: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        accessesNetwork: true,
+        changesUiState: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
     list_javascript_runtime_targets: browserEvidence,
     observe_javascript_runtime: browserEvidence,
     analyze_javascript_application: evidence,
@@ -149,11 +160,19 @@ export const TOOL_EFFECTS = {
         writesFilesystem: true,
         mayDiscardData: true,
     }),
+    snapshot_evidence_bundle: effects({ mutatesSession: true }),
+    release_evidence_bundle: effects({
+        mutatesSession: true,
+        mayDiscardData: true,
+    }),
+    get_navigation_context: effects({ mutatesSession: true }),
+    inspect_address_context: effects({ mutatesSession: true }),
     import_evidence_bundle: effects({ mutatesSession: true }),
     capture_process_scenario: effects({
         mutatesSession: true,
         writesFilesystem: true,
         launchesProcess: true,
+        accessesNetwork: true,
         idempotent: false,
     }),
     compare_process_captures: sessionEvidence,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/processCapture.js";
-import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
 import { residualUnknownSchema } from "../domain/residualUnknown.js";
 import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
+import { nativeApiInspectionResultSchema } from "../domain/nativeApiBoundary.js";
 import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/nativeInspection.js";
 import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
@@ -21,7 +22,23 @@ import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCor
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
 import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, analysisActivity, addressedEntry, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { addressList, addressedEntry, analysisActivity, bounded, containingProcedureResolution, clientFeatureAvailabilitySchema, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+const contextFacetSchema = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("available"), value: jsonValueSchema }),
+    z.object({
+        state: z.literal("unavailable"),
+        reason: z.string(),
+        remediation: z.string(),
+    }),
+]);
+const bookmarkFacetSchema = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("available"), value: z.array(addressedEntry) }),
+    z.object({
+        state: z.literal("unavailable"),
+        reason: z.string(),
+        remediation: z.string(),
+    }),
+]);
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -188,6 +205,7 @@ export const enhancedOutputSchemas = {
         string_count: z.number().int().min(0),
     })),
     analyze_function: functionDossierOutput,
+    inspect_native_api: resultOf(nativeApiInspectionResultSchema),
     trace_feature: literalTraceOutput,
     find_code_for_string: literalTraceOutput,
     trace_call_path: callPathTraceOutput,
@@ -293,16 +311,43 @@ export const sessionOutputSchemas = {
             }),
         ]),
     ])),
-    export_evidence_bundle: lifecycleResultOf(z.union([
-        evidenceBundleSchema,
-        z.object({
-            path: z.string(),
-            bytes: z.number().int().min(0),
-            records: z.number().int().min(0),
-        }),
-    ])),
+    export_evidence_bundle: lifecycleResultOf(z.object({
+        path: z.string(),
+        bytes: z.number().int().min(0),
+        records: z.number().int().min(0),
+        unknowns: z.number().int().min(0),
+    })),
+    snapshot_evidence_bundle: lifecycleResultOf(z.object({
+        bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+        bundle_version: z.literal(2),
+        bytes: z.number().int().min(0),
+        records: z.number().int().min(0),
+        unknowns: z.number().int().min(0),
+        scope: z.literal("session"),
+        survives_session: z.literal(false),
+        bundle_uri: z.string().regex(/^rea:\/\/evidence-bundle\/[a-f0-9]{64}$/u),
+    })),
+    release_evidence_bundle: lifecycleResultOf(z.object({
+        bundle_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+        released: z.boolean(),
+    })),
+    get_navigation_context: lifecycleResultOf(z.object({
+        document: z.string(),
+        address: z.string(),
+        procedure: z.union([z.string(), z.null()]),
+    })),
+    inspect_address_context: lifecycleResultOf(z.object({
+        address: z.string(),
+        document: z.string().nullable(),
+        name: contextFacetSchema,
+        procedure: contextFacetSchema,
+        comment: contextFacetSchema,
+        inline_comment: contextFacetSchema,
+        bookmarks: bookmarkFacetSchema,
+    })),
     import_evidence_bundle: lifecycleResultOf(z.object({
         imported: z.number().int().min(0),
+        unknowns_added: z.number().int().min(0),
         total: z.number().int().min(0),
     })),
     capture_process_scenario: resultOf(processCaptureSchema),
@@ -314,7 +359,17 @@ export const sessionOutputSchemas = {
     build_call_path: resultOf(callPathResultSchema),
     correlate_static_and_runtime: resultOf(staticRuntimeCorrelationResultSchema),
     verify_reconstruction: resultOf(reconstructionVerificationResultSchema),
-    list_unknowns: lifecycleResultOf(z.array(residualUnknownSchema)),
+    list_unknowns: lifecycleResultOf(z.object({
+        items: z.array(z.object({
+            unknown: residualUnknownSchema,
+            uri: z.string().regex(/^rea:\/\/unknown\/unk_[a-f0-9]{64}$/u),
+        })),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(500),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+        has_more: z.boolean(),
+    })),
     record_unknown: lifecycleResultOf(residualUnknownSchema),
     update_unknown: lifecycleResultOf(residualUnknownSchema),
     verify_unknown_resolution: lifecycleResultOf(z.object({