rea-agents 2.1.0 → 2.3.0

package/dist/contracts/applicationWorkflowInputContracts.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { evidenceSchema } from "../domain/evidence.js";
+import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticQueryInputSchema } from "../domain/javascriptSemanticQuerySchemas.js";
+const evidenceIdSchema = z
+    .string()
+    .regex(/^ev_[a-f0-9]{64}$/u)
+    .describe("Evidence ID returned earlier in this session");
+const requireExactlyOne = (context, fields) => {
+    const [leftName, left, rightName, right] = fields;
+    if ((left === undefined) !== (right === undefined))
+        return;
+    context.addIssue({
+        code: "custom",
+        path: [left === undefined ? leftName : rightName],
+        message: `Supply exactly one of ${leftName} or ${rightName}`,
+    });
+};
+/** MCP/CLI trace request accepting full Evidence or a ledger reference. */
+export const traceApplicationFeatureRequestSchema = z
+    .strictObject({
+    application: evidenceSchema.optional(),
+    application_evidence_id: evidenceIdSchema.optional(),
+    native_observations: traceApplicationFeatureInputSchema.shape.native_observations,
+    native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    seed: traceApplicationFeatureInputSchema.shape.seed,
+    direction: traceApplicationFeatureInputSchema.shape.direction,
+    limits: traceApplicationFeatureInputSchema.shape.limits,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "application",
+        input.application,
+        "application_evidence_id",
+        input.application_evidence_id,
+    ]);
+});
+/** MCP/CLI semantic trace request accepting full Evidence or a ledger reference. */
+export const traceJavaScriptSemanticsRequestSchema = z
+    .strictObject({
+    application: evidenceSchema.optional(),
+    application_evidence_id: evidenceIdSchema.optional(),
+    query: javaScriptSemanticQueryInputSchema,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "application",
+        input.application,
+        "application_evidence_id",
+        input.application_evidence_id,
+    ]);
+});
+/** MCP/CLI comparison request accepting full Evidence or ledger references. */
+export const compareApplicationVersionsRequestSchema = z
+    .strictObject({
+    left: evidenceSchema.optional(),
+    left_evidence_id: evidenceIdSchema.optional(),
+    right: evidenceSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_native_observations: compareApplicationVersionsInputSchema.shape.left_native_observations,
+    left_native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    right_native_observations: compareApplicationVersionsInputSchema.shape.right_native_observations,
+    right_native_observation_evidence_ids: z
+        .array(evidenceIdSchema)
+        .max(64)
+        .default([]),
+    limits: compareApplicationVersionsInputSchema.shape.limits,
+    unknown_registry_approved: compareApplicationVersionsInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "left",
+        input.left,
+        "left_evidence_id",
+        input.left_evidence_id,
+    ]);
+    requireExactlyOne(context, [
+        "right",
+        input.right,
+        "right_evidence_id",
+        input.right_evidence_id,
+    ]);
+});
+/** MCP/CLI export-shape request accepting full Evidence or ledger references. */
+export const compareJavaScriptExportShapesRequestSchema = z
+    .strictObject({
+    left: evidenceSchema.optional(),
+    left_evidence_id: evidenceIdSchema.optional(),
+    right: evidenceSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_module_path: compareJavaScriptExportShapesInputSchema.shape.left_module_path,
+    left_export_name: compareJavaScriptExportShapesInputSchema.shape.left_export_name,
+    right_module_path: compareJavaScriptExportShapesInputSchema.shape.right_module_path,
+    right_export_name: compareJavaScriptExportShapesInputSchema.shape.right_export_name,
+    limits: compareJavaScriptExportShapesInputSchema.shape.limits,
+    unknown_registry_approved: compareJavaScriptExportShapesInputSchema.shape.unknown_registry_approved,
+})
+    .superRefine((input, context) => {
+    requireExactlyOne(context, [
+        "left",
+        input.left,
+        "left_evidence_id",
+        input.left_evidence_id,
+    ]);
+    requireExactlyOne(context, [
+        "right",
+        input.right,
+        "right_evidence_id",
+        input.right_evidence_id,
+    ]);
+});

package/dist/contracts/electronToolContracts.js

@@ -1,12 +1,80 @@
+import { z } from "zod";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
 import { electronPageInspectionSchema, electronTargetListSchema, inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "../domain/electronObservation.js";
-import { analyzeJavaScriptApplicationInputSchema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
+import { analyzeJavaScriptApplicationInputSchema, javaScriptApplicationAnalysisResultV1Schema, javascriptApplicationAnalysisResultSchema, } from "../domain/javascriptApplicationAnalysis.js";
+import { JAVASCRIPT_APPLICATION_NODE_KINDS } from "../domain/javascriptApplicationGraphSchemas.js";
+import { applicationCoverageSchema } from "../domain/javascriptApplicationEvidenceSchemas.js";
 import { javascriptRuntimeReconciliationResultSchema, reconcileJavaScriptRuntimeInputSchema, } from "../domain/javascriptRuntimeReconciliationSchemas.js";
 import { JAVASCRIPT_RUNTIME_RECONCILIATION_EXAMPLE } from "./javascriptRuntimeReconciliationExample.js";
 const listOutputSchema = evidenceResultOf(electronTargetListSchema);
 const inspectionOutputSchema = evidenceResultOf(electronPageInspectionSchema);
-const applicationOutputSchema = evidenceResultOf(javascriptApplicationAnalysisResultSchema);
+/** MCP-only response selection; analysis identity does not depend on projection. */
+export const analyzeJavaScriptApplicationToolInputSchema = analyzeJavaScriptApplicationInputSchema.extend({
+    detail: z
+        .enum(["summary", "full"])
+        .default("summary")
+        .describe("summary returns bounded findings and paged graph resource URIs; full returns the complete graph only when explicitly required"),
+});
+/** Bounded default projection for agent-facing JavaScript application analysis. */
+const applicationGraphSummarySchema = z.strictObject({
+    graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+    node_count: z.number().int().min(0),
+    edge_count: z.number().int().min(0),
+    roots: z.strictObject({
+        items: z.array(z.string().regex(/^jag_node_[a-f0-9]{64}$/u)),
+        total: z.number().int().min(0),
+        truncated: z.boolean(),
+    }),
+    node_kinds: z.array(z.strictObject({
+        kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+        count: z.number().int().min(1),
+    })),
+    top_findings: z.array(z.strictObject({
+        node_id: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
+        kind: z.enum(JAVASCRIPT_APPLICATION_NODE_KINDS),
+        label: z.string().nullable(),
+        authority: z.string(),
+        state: z.string(),
+        confidence: z.string(),
+        location: z.json(),
+    })),
+    coverage: applicationCoverageSchema,
+    limitations: z.array(z.string()),
+    pages: z.strictObject({
+        nodes: z.string().startsWith("rea://evidence/"),
+        edges: z.string().startsWith("rea://evidence/"),
+        page_limit: z.number().int().min(1).max(500),
+    }),
+});
+const semanticGraphSummarySchema = z.strictObject({
+    graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
+    nodes: z.number().int().min(0),
+    relations: z.number().int().min(0),
+    unknown_frontiers: z.number().int().min(0),
+    fingerprints: z.number().int().min(0),
+    coverage: z.enum(["complete", "partial", "unknown", "unavailable"]),
+    query_tool: z.literal("trace_javascript_semantics"),
+});
+const summaryFields = {
+    unknowns: z.array(z.string().min(1).max(4_096)).max(1_000),
+    graph: applicationGraphSummarySchema,
+};
+/** Bounded default projection for agent-facing JavaScript application analysis. */
+export const javascriptApplicationAnalysisSummarySchema = z.discriminatedUnion("schema_version", [
+    javaScriptApplicationAnalysisResultV1Schema
+        .omit({ graph: true })
+        .extend(summaryFields),
+    javaScriptApplicationAnalysisResultV1Schema.omit({ graph: true }).extend({
+        schema_version: z.literal(2),
+        ...summaryFields,
+        semantic_graph: semanticGraphSummarySchema,
+    }),
+]);
+const applicationOutputSchema = evidenceResultOf(z.union([
+    javascriptApplicationAnalysisSummarySchema,
+    javascriptApplicationAnalysisResultSchema,
+]));
 const reconciliationOutputSchema = evidenceResultOf(javascriptRuntimeReconciliationResultSchema);
 const endpoint = "http://127.0.0.1:9223";
 const root = "/Applications/Example.app/Contents/Resources";
@@ -66,9 +134,9 @@ export const ELECTRON_TOOL_CONTRACTS = [
     {
         name: "analyze_javascript_application",
         ...toolContractMetadata("analyze_javascript_application"),
-        description: "Statically reconstruct one approved local ASAR or extracted JavaScript application as Evidence v2 and JavaScript Application Graph v1. Maps BrowserWindow preferences, preload and contextBridge APIs, literal and dynamic IPC, handler locations, sender-validation observations, utility processes, and requested native addon bindings without executing JavaScript; source-map contents require separate approval.",
+        description: "Statically reconstruct one approved local ASAR or extracted JavaScript application without executing it. The default summary returns architecture/security counts, top evidence-backed findings, unknowns, and paged graph resource URIs; request detail=full only when the complete graph must be returned immediately. Identical inputs are deterministic, so do not repeat the call or reread full Evidence without a specific missing detail.",
         kind: "electron-provider",
-        inputSchema: analyzeJavaScriptApplicationInputSchema,
+        inputSchema: analyzeJavaScriptApplicationToolInputSchema,
         outputSchema: applicationOutputSchema,
         examples: [
             {
@@ -78,6 +146,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
                     format: "auto",
                     approved: true,
                     source_map_read_approved: false,
+                    detail: "summary",
                 },
             },
         ],

package/dist/contracts/javascriptApplicationWorkflowExamples.js

@@ -28,19 +28,42 @@ const reconciliationEvidence = createEvidence(undefined, {
     limitations: reconciliation.limitations,
     evidenceLinks: reconciliation.evidence_links,
 });
-/** Valid public trace request without proprietary artifacts. */
+const EXAMPLE_EVIDENCE_ID = `ev_${"0".repeat(64)}`;
+const SECOND_EXAMPLE_EVIDENCE_ID = `ev_${"1".repeat(64)}`;
+const TRACE_SEED = {
+    kind: "module",
+    value: "renderer.js",
+    match: "exact",
+    case_sensitive: false,
+};
+/** Natural trace request using the Evidence ID returned by its producer. */
 export const JAVASCRIPT_FEATURE_TRACE_EXAMPLE = {
-    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
-    seed: {
-        kind: "module",
-        value: "renderer.js",
-        match: "exact",
-        case_sensitive: false,
-    },
+    application_evidence_id: EXAMPLE_EVIDENCE_ID,
+    seed: TRACE_SEED,
     direction: "both",
 };
-/** Valid static/runtime graph pair demonstrating comparison authority. */
+/** Natural version comparison using two producer-returned Evidence IDs. */
 export const JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE = {
+    left_evidence_id: EXAMPLE_EVIDENCE_ID,
+    right_evidence_id: SECOND_EXAMPLE_EVIDENCE_ID,
+};
+/** Exact static return-shape comparison using producer-returned Evidence IDs. */
+export const JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE = {
+    left_evidence_id: EXAMPLE_EVIDENCE_ID,
+    right_evidence_id: SECOND_EXAMPLE_EVIDENCE_ID,
+    left_module_path: "parser.mjs",
+    left_export_name: "default",
+    right_module_path: "parser.mjs",
+    right_export_name: "default",
+};
+/** Full-Evidence compatibility fixture used by pure domain and adapter tests. */
+export const JAVASCRIPT_FEATURE_TRACE_FULL_EVIDENCE_EXAMPLE = {
+    application: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
+    seed: TRACE_SEED,
+    direction: "both",
+};
+/** Full-Evidence compatibility comparison fixture. */
+export const JAVASCRIPT_VERSION_COMPARISON_FULL_EVIDENCE_EXAMPLE = {
     left: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE,
     right: reconciliationEvidence,
 };

package/dist/contracts/managedToolContracts.js

@@ -3,6 +3,11 @@ import { managedOutputSchemas } from "./toolOutputSchemas.js";
 import { toolContractMetadata } from "./toolEffects.js";
 /** Exact caller boundary for execution-free PE/CLI triage and identity. */
 export const managedArtifactInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Managed PE/CLI path to open before inspection; omit only when a managed target is already active"),
     reference_offset: z.number().int().min(0).default(0),
     reference_limit: z.number().int().min(1).max(500).default(100),
     resource_offset: z.number().int().min(0).default(0),
@@ -111,14 +116,14 @@ export const MANAGED_TOOL_CONTRACTS = [
     {
         name: "inspect_managed_artifact",
         ...toolContractMetadata("inspect_managed_artifact"),
-        description: "Classify the active PE/CLI artifact and inventory exact assembly/module identity, target framework evidence, references, resources, and custom attributes without loading or executing target code. Returns bounded pages and explicit partial or malformed coverage.",
+        description: "Open and classify an explicit managed PE/CLI path, or inspect the active managed target, then inventory exact assembly/module identity, target framework evidence, references, resources, and custom attributes without loading or executing target code. Returns bounded pages and explicit partial or malformed coverage.",
         kind: "managed-provider",
         inputSchema: managedArtifactInputSchema,
         outputSchema,
         examples: [
             {
                 title: "Example inspect managed artifact request",
-                input: {},
+                input: { path: "/tmp/Example.dll" },
             },
         ],
     },

package/dist/contracts/processCaptureExample.js

@@ -55,6 +55,7 @@ export const EMPTY_PROCESS_CAPTURE_EXAMPLE = {
     ],
     shim_events: [],
     protocol_events: [],
+    replay_transitions: [],
     files_before: [],
     files_after: [],
     filesystem_effects: [],

package/dist/contracts/replayMachineExample.js

@@ -0,0 +1,37 @@
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+/** Minimal login callback accepted by the direct replay-machine contract. */
+export const REPLAY_MACHINE_RUN_EXAMPLE = jsonObjectSchema.parse({
+    machine: {
+        initial_state: "waiting",
+        states: [{ name: "waiting" }, { name: "complete", terminal: true }],
+        transitions: [
+            {
+                id: "accept_callback",
+                from: "waiting",
+                to: "complete",
+                trigger: { protocol: "http", method: "POST", path: "/callback" },
+                captures: [
+                    {
+                        variable: "token",
+                        value: { source: "request_json", path: ["token"] },
+                        sensitive: true,
+                    },
+                ],
+                actions: [{ type: "http_response", status: 204, body: "" }],
+                max_uses: 1,
+            },
+        ],
+        max_transitions: 1,
+    },
+    events: [
+        {
+            protocol: "http",
+            connection: "not_applicable",
+            at_ms: 0,
+            method: "POST",
+            path: "/callback",
+            headers: {},
+            body: '{"token":"opaque"}',
+        },
+    ],
+});

package/dist/contracts/sessionStatusContract.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { TOOL_KINDS } from "./toolContractTypes.js";
+/** Caller observations and projection controls for binary_session. */
+export const binarySessionInputSchema = z.object({
+    detail: z
+        .enum(["summary", "capabilities", "full"])
+        .default("summary")
+        .describe("summary returns routing state; capabilities returns one filtered tool-availability page; full returns complete diagnostics only when required"),
+    capability_family: z
+        .enum(TOOL_KINDS)
+        .optional()
+        .describe("Optional tool family for detail=capabilities"),
+    cursor: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe("Zero-based capability cursor for detail=capabilities"),
+    limit: z.number().int().min(1).max(100).default(25),
+    expected_package_version: z.string().min(1).optional(),
+    expected_catalog_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional(),
+    expected_server_path: z.string().min(1).optional(),
+});

package/dist/contracts/toolContractExamples.js

@@ -2,6 +2,7 @@ import { UNKNOWN_CONTRACT_EXAMPLES } from "./unknownContractExamples.js";
 import { ARTIFACT_COMPARISON_EXAMPLE } from "./artifactComparisonExample.js";
 import { FUNCTION_COMPARISON_EXAMPLE } from "./functionComparisonExample.js";
 import { INVESTIGATION_EXAMPLES } from "./investigationExamples.js";
+import { REPLAY_MACHINE_RUN_EXAMPLE } from "./replayMachineExample.js";
 /** Canonical examples for contracts whose required inputs have no defaults. */
 export const TOOL_EXAMPLE_OVERRIDES = {
     ...UNKNOWN_CONTRACT_EXAMPLES,
@@ -35,6 +36,7 @@ export const TOOL_EXAMPLE_OVERRIDES = {
         executable: "/usr/bin/true",
         working_directory: "/tmp",
     },
+    run_replay_machine: REPLAY_MACHINE_RUN_EXAMPLE,
     compare_process_captures: {
         left_evidence_id: `ev_${"0".repeat(64)}`,
         right_evidence_id: `ev_${"1".repeat(64)}`,

package/dist/contracts/toolContractTypes.js

@@ -1 +1,12 @@
-export {};
+/** Canonical adapter families responsible for public MCP tools. */
+export const TOOL_KINDS = [
+    "official-proxy",
+    "enhanced",
+    "native-provider",
+    "artifact-provider",
+    "managed-provider",
+    "browser-provider",
+    "electron-provider",
+    "application",
+    "session",
+];

package/dist/contracts/toolContracts.js

@@ -9,6 +9,8 @@ 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";
@@ -21,6 +23,8 @@ 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";
+import { binarySessionInputSchema } from "./sessionStatusContract.js";
+export { binarySessionInputSchema } from "./sessionStatusContract.js";
 const document = z.string().optional().describe("The document name");
 const address = z
     .string()
@@ -149,15 +153,6 @@ export const ENHANCED_TOOL_CONTRACTS = [
     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),
     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),
 ];
-/** Caller observations used to compare a live server with expected identity. */
-export const binarySessionInputSchema = z.object({
-    expected_package_version: z.string().min(1).optional(),
-    expected_catalog_digest: z
-        .string()
-        .regex(/^[a-f0-9]{64}$/u)
-        .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(),
@@ -171,6 +166,7 @@ export const importEvidenceBundleInputSchema = z.strictObject({
 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)
@@ -193,11 +189,11 @@ export const verifyUnknownResolutionInputSchema = z.strictObject({
 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("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("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.", processComparisonInputSchema),
+    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),
     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),
@@ -209,6 +205,7 @@ export const SESSION_TOOL_CONTRACTS = [
     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),
 ];
 /** Complete ordered public inventory used by registration and verification. */
 export const TOOL_CONTRACTS = [

package/dist/contracts/toolEffects.js

@@ -93,7 +93,10 @@ export const TOOL_EFFECTS = {
     analyze_javascript_application: evidence,
     reconcile_javascript_runtime: evidence,
     trace_application_feature: evidence,
+    trace_javascript_semantics: evidence,
     compare_application_versions: evidence,
+    compare_javascript_export_shapes: evidence,
+    run_replay_machine: effects(),
     run_controlled_replay: effects({
         mutatesSession: true,
         writesFilesystem: true,

package/dist/contracts/toolOutputSchemaGroups.js

@@ -18,8 +18,9 @@ import { changedBehaviorResultSchema } from "../domain/changedBehavior.js";
 import { callPathResultSchema } from "../domain/callPath.js";
 import { staticRuntimeCorrelationResultSchema } from "../domain/staticRuntimeCorrelation.js";
 import { reconstructionVerificationResultSchema } from "../domain/reconstructionVerification.js";
+import { replayMachineRunOutputSchema } from "../domain/replayMachineRun.js";
 import { analysisErrorProjectionSchema } from "./errorSchemas.js";
-import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
+import { addressList, addressedEntry, bounded, containingProcedureResolution, functionDossierOutput, graphNode, lifecycleResultOf, nullableText, pageOutput, procedureIdentity, procedureInfoOutput, evidenceResultOf as resultOf, searchPageOutput, segmentOutput, sessionProvider, providerIdentity, toolAvailability, symbolDiscoveryOutput, targetFormatSchema, targetKindSchema, } from "./toolOutputSchemaPrimitives.js";
 /** Exact structured-content schemas shared by direct analysis providers. */
 export const officialOutputSchemas = {
     address_name: resultOf(nullableText),
@@ -190,15 +191,57 @@ export const sessionOutputSchemas = {
         }),
     ])),
     binary_session: lifecycleResultOf(z.union([
-        sessionProvider.extend({ open: z.literal(false) }),
-        sessionProvider.extend({
-            open: z.literal(true),
-            path: z.string(),
-            format: targetFormatSchema,
-            kind: targetKindSchema,
-            sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-            architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+        z.object({
+            view: z.literal("summary"),
+            open: z.boolean(),
+            provider: providerIdentity,
+            active_provider: providerIdentity.nullable(),
+            target: z
+                .object({
+                path: z.string(),
+                format: targetFormatSchema,
+                kind: targetKindSchema,
+                sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+                architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+            })
+                .nullable(),
+            alignment: z.object({
+                state: z.enum(["aligned", "mcp_server_restart_required", "unknown"]),
+                reasons: z.array(z.string()),
+                remediation: z.string().nullable(),
+            }),
+            recommended_actions: z.array(z.string()),
+        }),
+        z.object({
+            view: z.literal("capabilities"),
+            open: z.boolean(),
+            provider: providerIdentity,
+            active_provider: providerIdentity.nullable(),
+            capability_family: z.string().nullable(),
+            capabilities: z.object({
+                items: z.array(toolAvailability),
+                cursor: z.number().int().min(0),
+                limit: z.number().int().min(1),
+                total: z.number().int().min(0),
+                next_cursor: z.number().int().min(0).nullable(),
+                has_more: z.boolean(),
+            }),
         }),
+        z.union([
+            sessionProvider.extend({
+                view: z.literal("full"),
+                open: z.literal(false),
+            }),
+            sessionProvider.extend({
+                view: z.literal("full"),
+                open: z.literal(true),
+                path: z.string(),
+                format: targetFormatSchema,
+                kind: targetKindSchema,
+                sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+                architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
+            }),
+        ]),
     ])),
     export_evidence_bundle: lifecycleResultOf(z.union([
         evidenceBundleSchema,
@@ -229,4 +272,5 @@ export const sessionOutputSchemas = {
         truthVerified: z.boolean(),
         unknown: residualUnknownSchema,
     })),
+    run_replay_machine: lifecycleResultOf(replayMachineRunOutputSchema),
 };