rea-agents 1.7.0 → 2.0.0

package/dist/contracts/managedWorkflowToolContracts.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { compareManagedMembersInputSchema } from "../domain/managedMemberComparison.js";
+import { managedNativeVerificationInputSchema } from "../domain/managedNativeVerification.js";
+import { managedReconstructionImportInputSchema } from "../domain/managedReconstruction.js";
+import { managedRuntimeCorrelationInputSchema } from "../domain/managedRuntimeCorrelation.js";
+import { projectManagedApplicationGraphInputSchema } from "../domain/managedApplicationGraph.js";
+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";
+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");
+const managedBoundaryEvidenceIdSchema = evidenceIdSchema.describe("Session-owned inspect_managed_native_boundaries Evidence ID");
+const nativeObservationEvidenceIdSchema = evidenceIdSchema.describe("Session-owned inspect_macho or analyze_function Evidence ID");
+/** MCP references for comparing two session-owned managed observations. */
+export const compareManagedMembersReferenceInputSchema = z
+    .strictObject({
+    left_evidence_id: managedEvidenceIdSchema,
+    right_evidence_id: managedEvidenceIdSchema,
+    limits: compareManagedMembersInputSchema.shape.limits,
+    unknown_registry_approved: compareManagedMembersInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    if (input.left_evidence_id === input.right_evidence_id)
+        context.addIssue({
+            code: "custom",
+            path: ["right_evidence_id"],
+            message: "Managed member Evidence must be distinct",
+        });
+});
+/** MCP reference for planning from one session-owned managed observation. */
+export const managedRuntimeCorrelationReferenceInputSchema = managedRuntimeCorrelationInputSchema
+    .omit({ static_members: true })
+    .extend({ static_members_evidence_id: managedEvidenceIdSchema });
+/** MCP reference for importing reconstruction against session Evidence. */
+export const managedReconstructionReferenceInputSchema = managedReconstructionImportInputSchema
+    .omit({ static_members: true })
+    .extend({ static_members_evidence_id: managedEvidenceIdSchema });
+/** MCP references for managed/native verification from session Evidence. */
+export const managedNativeVerificationReferenceInputSchema = z
+    .strictObject({
+    managed_boundaries_evidence_id: managedBoundaryEvidenceIdSchema,
+    native_observation_evidence_ids: z
+        .array(nativeObservationEvidenceIdSchema)
+        .min(1)
+        .max(50)
+        .describe("Unique session-owned native observation Evidence IDs"),
+    limits: managedNativeVerificationInputSchema.shape.limits,
+    unknown_registry_approved: managedNativeVerificationInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    const ids = new Set();
+    for (const [index, evidenceId,] of input.native_observation_evidence_ids.entries()) {
+        if (evidenceId === input.managed_boundaries_evidence_id)
+            context.addIssue({
+                code: "custom",
+                path: ["native_observation_evidence_ids", index],
+                message: "Native observation Evidence must be distinct from managed boundary Evidence",
+            });
+        if (ids.has(evidenceId))
+            context.addIssue({
+                code: "custom",
+                path: ["native_observation_evidence_ids", index],
+                message: "Native observation Evidence IDs must be unique",
+            });
+        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(),
+    limits: projectManagedApplicationGraphInputSchema.shape.limits,
+})
+    .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");
+/** Provider-neutral managed-code workflow contracts. */
+export const MANAGED_WORKFLOW_TOOL_CONTRACTS = [
+    {
+        name: "compare_managed_members",
+        ...toolContractMetadata("compare_managed_members"),
+        description: "Compare two authenticated inspect_managed_members Evidence records using unique-only CIL/signature and structural method-shape tiers. Names are reported as observations but are not used as a matching basis; metadata tokens are remapped as build-local coordinates bound to each artifact SHA-256 and MVID.",
+        kind: "application",
+        inputSchema: compareManagedMembersReferenceInputSchema,
+        outputSchema: comparisonOutputSchema,
+        examples: [
+            {
+                title: "Compare two managed member observations",
+                input: {
+                    left_evidence_id: MANAGED_MEMBER_COMPARISON_EXAMPLE.left.evidence_id,
+                    right_evidence_id: MANAGED_MEMBER_COMPARISON_EXAMPLE.right.evidence_id,
+                    limits: MANAGED_MEMBER_COMPARISON_EXAMPLE.limits,
+                },
+            },
+        ],
+    },
+    {
+        name: "verify_managed_native_boundaries",
+        ...toolContractMetadata("verify_managed_native_boundaries"),
+        description: "Verify managed P/Invoke/native-boundary declarations against authenticated native export or function Evidence without executing managed code or translating managed metadata tokens into native addresses. The workflow preserves declaration-only, verified, inferred, contradicted, and unresolved states.",
+        kind: "application",
+        inputSchema: managedNativeVerificationReferenceInputSchema,
+        outputSchema: nativeVerificationOutputSchema,
+        examples: [
+            {
+                title: "Verify a managed P/Invoke declaration against native Evidence",
+                input: {
+                    managed_boundaries_evidence_id: MANAGED_NATIVE_VERIFICATION_EXAMPLE.managed_boundaries.evidence_id,
+                    native_observation_evidence_ids: MANAGED_NATIVE_VERIFICATION_EXAMPLE.native_observations.map(({ evidence_id: evidenceId }) => evidenceId),
+                    limits: MANAGED_NATIVE_VERIFICATION_EXAMPLE.limits,
+                },
+            },
+        ],
+    },
+    {
+        name: "import_managed_reconstruction",
+        ...toolContractMetadata("import_managed_reconstruction"),
+        description: "Import decompiler-produced managed reconstruction against authenticated inspect_managed_members Evidence. The workflow locks each method to artifact SHA-256, MVID, metadata token, signature hash, and normalized IL hash, records the decompiler identity and options, and marks C# or pseudocode as analyst inference rather than canonical byte observation.",
+        kind: "application",
+        inputSchema: managedReconstructionReferenceInputSchema,
+        outputSchema: reconstructionOutputSchema,
+        examples: [
+            {
+                title: "Import a decompiler reconstruction for one managed method",
+                input: {
+                    static_members_evidence_id: MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE.static_members.evidence_id,
+                    decompiler: MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE.decompiler,
+                    methods: MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE.methods,
+                    notes: MANAGED_RECONSTRUCTION_IMPORT_EXAMPLE.notes,
+                },
+            },
+        ],
+    },
+    {
+        name: "plan_managed_runtime_correlation",
+        ...toolContractMetadata("plan_managed_runtime_correlation"),
+        description: "Prepare a separately authorized managed runtime-correlation admission plan from authenticated inspect_managed_members Evidence. The operation is default-disabled, requires the managed_runtime permission ceiling and grant, locks the exact artifact SHA-256, MVID, method signature, and normalized IL shape, distinguishes attach/load/debugger/reflection/instrumentation effects, and records that no target code was executed.",
+        kind: "application",
+        inputSchema: managedRuntimeCorrelationReferenceInputSchema,
+        outputSchema: runtimeOutputSchema,
+        examples: [
+            {
+                title: "Plan an exact-build managed runtime correlation",
+                input: {
+                    static_members_evidence_id: MANAGED_RUNTIME_CORRELATION_EXAMPLE.static_members.evidence_id,
+                    method: MANAGED_RUNTIME_CORRELATION_EXAMPLE.method,
+                    requested_effect: MANAGED_RUNTIME_CORRELATION_EXAMPLE.requested_effect,
+                    host: MANAGED_RUNTIME_CORRELATION_EXAMPLE.host,
+                    bounds: MANAGED_RUNTIME_CORRELATION_EXAMPLE.bounds,
+                },
+            },
+        ],
+    },
+    {
+        name: "project_managed_application_graph",
+        ...toolContractMetadata("project_managed_application_graph"),
+        description: "Project authenticated managed artifact, member, and native-boundary Evidence into the provider-neutral application graph without executing managed code, loading assemblies, or translating managed metadata tokens to native addresses. The graph preserves managed static observations as managed-specific nodes linked to source Evidence.",
+        kind: "application",
+        inputSchema: managedApplicationGraphReferenceInputSchema,
+        outputSchema: managedApplicationGraphOutputSchema,
+        examples: [
+            {
+                title: "Project static managed observations into an application graph",
+                input: {
+                    managed_members_evidence_id: MANAGED_APPLICATION_GRAPH_EXAMPLE.managed_members.evidence_id,
+                    limits: MANAGED_APPLICATION_GRAPH_EXAMPLE.limits,
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/nativeToolContracts.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { nativeOutputSchemas } from "./toolOutputSchemas.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { toolContractMetadata } from "./toolEffects.js";
 const examples = {
     inspect_macho: {},
     inspect_signature: {},
@@ -14,16 +15,11 @@ const native = (name, description, inputSchema) => {
         throw new Error(`Missing native output schema for ${name}`);
     return {
         name,
+        ...toolContractMetadata(name),
         description,
         kind: "native-provider",
         inputSchema,
         outputSchema,
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
         examples: [
             {
                 title: `Example ${name.replaceAll("_", " ")} request`,

package/dist/contracts/promptContracts.js

@@ -51,8 +51,12 @@ export const PROMPT_CONTRACTS = [
         },
         steps: [
             {
-                tools: ["binary_session", "open_binary"],
-                instruction: "Inspect provider availability and effects first. Open target_path only when no matching target is active.",
+                tools: [
+                    "binary_session",
+                    "open_binary",
+                    "analyze_javascript_application",
+                ],
+                instruction: "Inspect provider availability and effects first. For an approved JavaScript/Electron artifact, reconstruct its application graph without execution; otherwise open target_path only when no matching target is active.",
             },
             {
                 tools: ["list_documents", "set_current_document", "binary_overview"],
@@ -62,6 +66,10 @@ export const PROMPT_CONTRACTS = [
                 tools: ["search_strings", "search_procedures", "procedure_address"],
                 instruction: "Search in literal mode first, follow every continuation needed for the stated scope, and resolve selected procedures to canonical addresses.",
             },
+            {
+                tools: ["trace_application_feature"],
+                instruction: "When authenticated application-graph Evidence exists, trace a typed literal route, API, channel, module, string, or native export through a bounded cross-layer subgraph before native localization.",
+            },
             {
                 tools: [
                     "analyze_function",
@@ -95,6 +103,14 @@ export const PROMPT_CONTRACTS = [
                 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: [
+                    "analyze_javascript_application",
+                    "reconcile_javascript_runtime",
+                    "compare_application_versions",
+                ],
+                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.",

package/dist/contracts/toolContractExamples.js

@@ -1,4 +1,3 @@
-import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "./processCaptureExample.js";
 import { UNKNOWN_CONTRACT_EXAMPLES } from "./unknownContractExamples.js";
 import { ARTIFACT_COMPARISON_EXAMPLE } from "./artifactComparisonExample.js";
 import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
@@ -38,32 +37,18 @@ export const TOOL_EXAMPLE_OVERRIDES = {
     },
     compare_process_captures: {
         left_evidence_id: `ev_${"0".repeat(64)}`,
-        left: EMPTY_PROCESS_CAPTURE_EXAMPLE,
         right_evidence_id: `ev_${"1".repeat(64)}`,
-        right: EMPTY_PROCESS_CAPTURE_EXAMPLE,
     },
-    compare_artifacts: ARTIFACT_COMPARISON_EXAMPLE,
-    compare_functions: FUNCTION_COMPARISON_EXAMPLE,
+    compare_artifacts: {
+        left_evidence_ids: [ARTIFACT_COMPARISON_EXAMPLE.left.evidence_id],
+        right_evidence_ids: [ARTIFACT_COMPARISON_EXAMPLE.right.evidence_id],
+    },
+    compare_functions: {
+        left_evidence_ids: [FUNCTION_COMPARISON_EXAMPLE.left.evidence_id],
+        right_evidence_ids: [FUNCTION_COMPARISON_EXAMPLE.right.evidence_id],
+    },
     compare_bundles: {
-        left: {
-            bundle_version: 2,
-            artifacts: [],
-            providers: [],
-            environments: [],
-            scenarios: [],
-            captures: [],
-            unknowns: [],
-            records: [],
-        },
-        right: {
-            bundle_version: 2,
-            artifacts: [],
-            providers: [],
-            environments: [],
-            scenarios: [],
-            captures: [],
-            unknowns: [],
-            records: [],
-        },
+        left_bundle_path: "/approved/left-evidence.json",
+        right_bundle_path: "/approved/right-evidence.json",
     },
 };

package/dist/contracts/toolContracts.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { processCaptureSchema, processScenarioSchema, } from "../domain/processCapture.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";
@@ -14,9 +14,13 @@ import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sess
 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";
+import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";
 import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
 import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
+import { APPLICATION_TOOL_CONTRACTS } from "./applicationToolContracts.js";
 import { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
+import { toolContractMetadata } from "./toolEffects.js";
 const document = z.string().optional().describe("The document name");
 const address = z
     .string()
@@ -54,23 +58,6 @@ const examplesFor = (name, inputSchema) => {
         },
     ];
 };
-const annotations = (name, kind) => ({
-    readOnlyHint: (kind === "enhanced" && name !== "trace_feature") ||
-        name === "binary_session" ||
-        name === "list_unknowns" ||
-        name === "verify_unknown_resolution",
-    destructiveHint: name === "export_evidence_bundle" ||
-        name === "close_binary" ||
-        name === "unset_bookmark" ||
-        name === "set_address_name" ||
-        name === "set_addresses_names" ||
-        name === "set_comment" ||
-        name === "set_inline_comment",
-    idempotentHint: name !== "close_binary" &&
-        name !== "record_unknown" &&
-        name !== "update_unknown",
-    openWorldHint: name === "capture_process_scenario",
-});
 const official = (name, description, inputSchema) => {
     const trackedInputSchema = inputSchema.extend({
         unknown_registry_approved: z
@@ -80,30 +67,30 @@ const official = (name, description, inputSchema) => {
     });
     return {
         name,
+        ...toolContractMetadata(name),
         description,
         kind: "official-proxy",
         inputSchema: trackedInputSchema,
         outputSchema: requireOutputSchema(officialOutputSchemas, name),
-        annotations: annotations(name, "official-proxy"),
         examples: examplesFor(name, trackedInputSchema),
     };
 };
 const enhanced = (name, description, inputSchema) => ({
     name,
+    ...toolContractMetadata(name),
     description,
     kind: "enhanced",
     inputSchema,
     outputSchema: requireOutputSchema(enhancedOutputSchemas, name),
-    annotations: annotations(name, "enhanced"),
     examples: examplesFor(name, inputSchema),
 });
 const session = (name, description, inputSchema) => ({
     name,
+    ...toolContractMetadata(name),
     description,
     kind: "session",
     inputSchema,
     outputSchema: requireOutputSchema(sessionOutputSchemas, name),
-    annotations: annotations(name, "session"),
     examples: examplesFor(name, inputSchema),
 });
 /** Bridge operations exposed without additional application composition. */
@@ -171,28 +158,46 @@ export const binarySessionInputSchema = z.object({
         .optional(),
     expected_server_path: z.string().min(1).optional(),
 });
+/** 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),
+    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),
+});
 /** 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 deterministic deep-provider candidates, host availability, target support, the immutable active binding/profile, capability descriptors, and whether a target is open. Candidate discovery never starts an analysis process; use rejection codes and local diagnostics before choosing provider_id.", 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.", z.object({
-        path: z.string().min(1).optional(),
-        overwrite: z.boolean().default(false),
-    })),
-    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.", z.object({ path: z.string().min(1) })),
+    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("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, exit, settlement, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Process Capture v3 is unsupported and must be recaptured with capture_process_scenario. Missing or truncated observations are never treated as equivalent.", z.object({
-        left_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-        left: processCaptureSchema,
-        right_evidence_id: z.string().regex(/^ev_[a-f0-9]{64}$/u),
-        right: processCaptureSchema,
-        max_capture_age_ms: z.number().int().nonnegative().optional(),
-        unknown_registry_approved: z
-            .literal(true)
-            .optional()
-            .describe("Explicit approval to record capture disagreement durably"),
-    })),
+    session("compare_process_captures", "Compare two compatible Process Capture v4 observations across terminal, interaction, exit, settlement, process, filesystem, command-shim, HTTP, and WebSocket evidence, returning the first bounded divergence. Process Capture v3 is unsupported and must be recaptured with capture_process_scenario. Missing or truncated observations are never treated as equivalent.", processComparisonInputSchema),
     session("compare_artifacts", "Compare two bounded sets of inventory_artifact Evidence pages by logical occurrence path, content identity, metadata, and graph relations. Pages must share and satisfy their graph commitment; every delta cites both sets, and gaps yield truncated or unknown, never equivalence.", artifactComparisonInputSchema),
     session("compare_functions", "Compare two explicit bounded sets of analyze_function Evidence pages 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),
     session("compare_bundles", "Compare two canonical Evidence v2 bundles by exact record membership, explicit one-to-one observation pairs, and complete residual-unknown revision histories. Missing bundle members describe omission only, never behavioral equivalence; output is digest-anchored and deterministically paginated.", bundleComparisonInputSchema),
@@ -200,16 +205,10 @@ 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.", z.object({
-        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(),
-    })),
+    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("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.", z.object({ unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u) })),
+    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),
 ];
 /** Complete ordered public inventory used by registration and verification. */
 export const TOOL_CONTRACTS = [
@@ -217,7 +216,10 @@ export const TOOL_CONTRACTS = [
     ...ENHANCED_TOOL_CONTRACTS,
     ...NATIVE_TOOL_CONTRACTS,
     ...ARTIFACT_TOOL_CONTRACTS,
+    ...MANAGED_TOOL_CONTRACTS,
+    ...MANAGED_WORKFLOW_TOOL_CONTRACTS,
     ...BROWSER_TOOL_CONTRACTS,
     ...ELECTRON_TOOL_CONTRACTS,
+    ...APPLICATION_TOOL_CONTRACTS,
     ...SESSION_TOOL_CONTRACTS,
 ];

package/dist/contracts/toolEffects.js

@@ -0,0 +1,160 @@
+const effects = (overrides = {}) => ({
+    mutatesTarget: false,
+    mutatesSession: false,
+    writesFilesystem: false,
+    launchesProcess: false,
+    accessesNetwork: false,
+    changesUiState: false,
+    mayDiscardData: false,
+    idempotent: true,
+    ...overrides,
+});
+const evidence = effects({ mutatesSession: true });
+const nativeEvidence = effects({ mutatesSession: true, launchesProcess: true });
+const browserEvidence = effects({
+    mutatesSession: true,
+    accessesNetwork: true,
+});
+const sessionEvidence = effects({ mutatesSession: true });
+/** Explicit effect audit for every public tool. */
+export const TOOL_EFFECTS = {
+    address_name: evidence,
+    comment: evidence,
+    current_address: evidence,
+    current_procedure: evidence,
+    current_document: evidence,
+    goto_address: effects({ mutatesSession: true, changesUiState: true }),
+    inline_comment: evidence,
+    list_bookmarks: evidence,
+    list_documents: evidence,
+    list_names: evidence,
+    list_procedures: evidence,
+    list_segments: evidence,
+    list_strings: evidence,
+    next_address: evidence,
+    prev_address: evidence,
+    procedure_address: evidence,
+    procedure_assembly: evidence,
+    procedure_callees: evidence,
+    procedure_callers: evidence,
+    procedure_info: evidence,
+    procedure_references: evidence,
+    procedure_pseudo_code: evidence,
+    resolve_containing_procedure: evidence,
+    search_procedures: evidence,
+    search_strings: evidence,
+    set_address_name: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_addresses_names: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_bookmark: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_comment: effects({ mutatesTarget: true, mutatesSession: true }),
+    set_current_document: effects({ mutatesSession: true, changesUiState: true }),
+    set_inline_comment: effects({ mutatesTarget: true, mutatesSession: true }),
+    unset_bookmark: effects({
+        mutatesTarget: true,
+        mutatesSession: true,
+        mayDiscardData: true,
+    }),
+    xrefs: evidence,
+    swift_classes: evidence,
+    get_objc_classes: evidence,
+    get_objc_protocols: evidence,
+    batch_decompile: evidence,
+    get_call_graph: evidence,
+    analyze_swift_types: evidence,
+    find_xrefs_to_name: evidence,
+    binary_overview: evidence,
+    analyze_function: evidence,
+    trace_feature: effects({ mutatesSession: true, idempotent: false }),
+    inspect_macho: nativeEvidence,
+    inspect_signature: nativeEvidence,
+    inspect_plist: nativeEvidence,
+    list_architectures: nativeEvidence,
+    demangle_swift: nativeEvidence,
+    inventory_artifact: evidence,
+    extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }),
+    inspect_managed_artifact: evidence,
+    inspect_managed_members: evidence,
+    inspect_managed_native_boundaries: evidence,
+    compare_managed_members: sessionEvidence,
+    verify_managed_native_boundaries: sessionEvidence,
+    import_managed_reconstruction: sessionEvidence,
+    plan_managed_runtime_correlation: sessionEvidence,
+    project_managed_application_graph: sessionEvidence,
+    list_browser_targets: browserEvidence,
+    inspect_web_page: browserEvidence,
+    analyze_web_bundle: browserEvidence,
+    observe_web_session: browserEvidence,
+    discover_webmcp_tools: browserEvidence,
+    compare_web_captures: browserEvidence,
+    capture_web_screenshot: browserEvidence,
+    compare_web_screenshots: browserEvidence,
+    list_electron_targets: browserEvidence,
+    inspect_electron_page: browserEvidence,
+    analyze_javascript_application: evidence,
+    reconcile_javascript_runtime: evidence,
+    trace_application_feature: evidence,
+    compare_application_versions: evidence,
+    run_controlled_replay: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+    }),
+    open_binary: effects({ mutatesSession: true, launchesProcess: true }),
+    close_binary: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        mayDiscardData: true,
+        idempotent: false,
+    }),
+    binary_session: effects(),
+    export_evidence_bundle: effects({
+        writesFilesystem: true,
+        mayDiscardData: true,
+    }),
+    import_evidence_bundle: effects({ mutatesSession: true }),
+    capture_process_scenario: effects({
+        mutatesSession: true,
+        writesFilesystem: true,
+        launchesProcess: true,
+        idempotent: false,
+    }),
+    compare_process_captures: sessionEvidence,
+    compare_artifacts: sessionEvidence,
+    compare_functions: sessionEvidence,
+    compare_bundles: effects({ mutatesSession: true }),
+    find_changed_behavior: sessionEvidence,
+    build_call_path: sessionEvidence,
+    correlate_static_and_runtime: sessionEvidence,
+    verify_reconstruction: sessionEvidence,
+    list_unknowns: effects(),
+    record_unknown: effects({ mutatesSession: true, idempotent: false }),
+    update_unknown: effects({ mutatesSession: true, idempotent: false }),
+    verify_unknown_resolution: effects(),
+};
+/** Derive MCP annotations without tool-name or tool-family heuristics. */
+export const annotationsFromEffects = (value) => ({
+    readOnlyHint: !(value.mutatesTarget ||
+        value.mutatesSession ||
+        value.writesFilesystem ||
+        value.launchesProcess ||
+        value.accessesNetwork ||
+        value.changesUiState ||
+        value.mayDiscardData),
+    destructiveHint: value.mayDiscardData,
+    idempotentHint: value.idempotent,
+    openWorldHint: value.launchesProcess || value.accessesNetwork,
+});
+/** Resolve the audited metadata for one public tool. */
+export const toolContractMetadata = (name) => {
+    const audited = TOOL_EFFECTS[name];
+    if (audited === undefined)
+        throw new Error(`Missing effect audit for ${name}`);
+    return {
+        title: name
+            .split("_")
+            .map((word) => word[0]?.toUpperCase() + word.slice(1))
+            .join(" "),
+        effects: audited,
+        annotations: annotationsFromEffects(audited),
+    };
+};