rea-agents 2.1.0 → 2.3.0

package/dist/cliApplicationCommands.js

@@ -1,5 +1,8 @@
 import { Cli, z } from "incur";
-import { compareApplicationVersionsEvidence, traceApplicationFeatureEvidence, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { traceJavaScriptSemanticsEvidenceValidated } from "./application/JavaScriptSemanticTraceService.js";
+import { resolveCompareApplicationVersionsRequest, resolveCompareJavaScriptExportShapesRequest, resolveTraceApplicationFeatureRequest, resolveTraceJavaScriptSemanticsRequest, } from "./application/ApplicationWorkflowEvidenceResolver.js";
+import { readEvidenceBundle } from "./application/EvidenceBundleFiles.js";
 import { runControlledReplay } from "./application/JavaScriptReplayService.js";
 import { executeNodeCharacterization, prepareNodeCharacterization, } from "./application/NodeRuntimeCharacterizationService.js";
 import { commitReconstructionCoverage, queryReconstructionCoverage, reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "./application/ReconstructionCoverageService.js";
@@ -19,14 +22,32 @@ export const registerApplicationCommands = (cli, logger) => {
         logger,
         name: CLI_COMMANDS.traceApplicationFeature,
         description: "Trace a typed seed through authenticated application Evidence JSON",
-        workflow: traceApplicationFeatureEvidence,
+        resolveInput: resolveTraceApplicationFeatureRequest,
+        workflow: traceApplicationFeatureEvidenceValidated,
+    });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.traceJavaScriptSemantics,
+        description: "Trace bounded static semantic relations through authenticated application Evidence",
+        resolveInput: resolveTraceJavaScriptSemanticsRequest,
+        workflow: traceJavaScriptSemanticsEvidenceValidated,
     });
     registerJsonCommand({
         cli,
         logger,
         name: CLI_COMMANDS.compareApplicationVersions,
         description: "Compare two authenticated JavaScript Application Graph versions",
-        workflow: compareApplicationVersionsEvidence,
+        resolveInput: resolveCompareApplicationVersionsRequest,
+        workflow: compareApplicationVersionsEvidenceValidated,
+    });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.compareJavaScriptExportShapes,
+        description: "Compare exact static JavaScript export return shapes without execution",
+        resolveInput: resolveCompareJavaScriptExportShapesRequest,
+        workflow: compareJavaScriptExportShapesEvidenceValidated,
     });
     cli.command(CLI_COMMANDS.runControlledReplay, {
         description: "Plan or execute an approved extracted-module replay in the Linux sandbox",
@@ -138,13 +159,10 @@ const registerCoverageCommands = (cli, logger) => {
     });
 };
 const configuredAuthority = async () => {
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        return { ok: false, error: projectAnalysisError(config.error) };
-    const authority = await loadConfiguredPermissionAuthority(config.value);
-    return authority.ok
-        ? { ok: true, config: config.value, authority: authority.value }
-        : { ok: false, error: projectAnalysisError(authority.error) };
+    const configured = await loadConfiguredAuthority();
+    return configured.ok
+        ? configured
+        : { ok: false, error: projectAnalysisError(configured.error) };
 };
 const replayDependencies = (config, authority) => ({
     policy: config.javascriptReplayPolicy,
@@ -152,25 +170,70 @@ const replayDependencies = (config, authority) => ({
     runner: new LinuxJavaScriptReplayRunner(),
     authority,
 });
-const registerJsonCommand = ({ cli, logger, name, description, workflow, }) => {
+const registerJsonCommand = ({ cli, logger, name, description, resolveInput, workflow, }) => {
     cli.command(name, {
         description,
         args: z.object({
             inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
         }),
-        run: ({ args }) => logCliCommand(logger, name, async () => {
+        options: z.object({
+            evidenceBundle: z
+                .string()
+                .optional()
+                .describe("Authorized Evidence bundle used to resolve Evidence IDs"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, name, async () => {
             const input = await parseCliJsonInput(args.inputJson, name);
             if (!input.ok)
                 return input.error;
-            const result = workflow(input.value);
+            const lookup = await loadEvidenceLookup(options.evidenceBundle, name);
+            if (!lookup.ok)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(lookup.error),
+                };
+            const resolved = resolveInput(input.value, lookup.value);
+            if (!resolved.ok)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(resolved.error),
+                };
+            const result = workflow(resolved.value);
             return result.ok
                 ? result.value
                 : {
                     error: "Application workflow failed",
-                    ...projectAnalysisError(result.error instanceof AnalysisInputError
-                        ? result.error
-                        : new AnalysisInputError(name)),
+                    ...projectAnalysisError(result.error),
                 };
         }),
     });
 };
+const loadEvidenceLookup = async (bundlePath, operation) => {
+    if (bundlePath === undefined)
+        return { ok: true, value: undefined };
+    const configured = await loadConfiguredAuthority();
+    if (!configured.ok)
+        return configured;
+    const authorized = await authorizeRootPermission(configured.authority, {
+        capability: "evidence_read",
+        roots: [bundlePath],
+        access: "read",
+        operation,
+    });
+    if (!authorized.ok)
+        return authorized;
+    const loaded = await readEvidenceBundle(bundlePath, configured.config.evidenceFilePolicy);
+    if (!loaded.ok)
+        return loaded;
+    const records = new Map(loaded.value.records.map((record) => [record.evidence_id, record]));
+    return { ok: true, value: (evidenceId) => records.get(evidenceId) };
+};
+const loadConfiguredAuthority = async () => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return config;
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    return authority.ok
+        ? { ok: true, config: config.value, authority: authority.value }
+        : authority;
+};

package/dist/cliCommandNames.js

@@ -49,7 +49,10 @@ export const CLI_COMMANDS = Object.freeze({
     analyzeJavaScriptApplication: "analyze-javascript-application",
     reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
     traceApplicationFeature: "trace-application-feature",
+    traceJavaScriptSemantics: "trace-javascript-semantics",
     compareApplicationVersions: "compare-application-versions",
+    compareJavaScriptExportShapes: "compare-javascript-export-shapes",
+    runReplayMachine: "run-replay-machine",
     runControlledReplay: "run-controlled-replay",
     prepareNodeCharacterization: "prepare-node-characterization",
     executeNodeCharacterization: "execute-node-characterization",

package/dist/cliElectronCommands.js

@@ -1,17 +1,16 @@
 import { Cli, z } from "incur";
 import { inspectElectronPage, listElectronTargets, } from "./application/ElectronObservationService.js";
-import { analyzeJavaScriptApplication } from "./application/JavaScriptApplicationService.js";
 import { reconcileJavaScriptRuntimeEvidence } from "./application/JavaScriptRuntimeReconciliationService.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
 import { inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "./domain/electronObservation.js";
-import { analyzeJavaScriptApplicationInputSchema } from "./domain/javascriptApplicationAnalysis.js";
 import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { parseCliJsonInput } from "./cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "./cliObservationOptions.js";
+import { runCliJavaScriptApplicationAnalysis } from "./cli/javascriptApplicationAnalysis.js";
 const scopeOptions = {
     allowedFileRoots: z
         .array(z.string().min(1))
@@ -134,37 +133,28 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
             path: z.string().describe("Absolute ASAR or extracted application path"),
         }),
         options: javascriptApplicationOptions,
-        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, async () => {
-            const context = await electronContext();
-            if (!context.ok)
-                return context.error;
-            const parsed = analyzeJavaScriptApplicationInputSchema.safeParse({
-                input_path: args.path,
-                approved: options.approved,
-                format: options.format,
-                source_map_read_approved: options.sourceMapReadApproved,
-                limits: {
-                    max_entries: options.maxEntries,
-                    max_total_artifact_bytes: options.maxTotalArtifactBytes,
-                    max_artifact_entry_bytes: options.maxArtifactEntryBytes,
-                    max_compression_ratio: options.maxCompressionRatio,
-                    max_depth: options.maxDepth,
-                    max_path_bytes: options.maxPathBytes,
-                    max_text_files: options.maxTextFiles,
-                    max_total_text_bytes: options.maxTotalTextBytes,
-                    max_text_file_bytes: options.maxTextFileBytes,
-                    max_ast_nodes: options.maxAstNodes,
-                    max_findings: options.maxFindings,
-                    max_modules: options.maxModules,
-                    max_source_map_sources: options.maxSourceMapSources,
-                    max_parse_milliseconds: options.maxParseMilliseconds,
-                },
-            });
-            if (!parsed.success)
-                return inputError("analyze_javascript_application");
-            const result = await analyzeJavaScriptApplication(context.authority, parsed.data);
-            return result.ok ? result.value : cliError(result.error);
-        }),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () => runCliJavaScriptApplicationAnalysis({
+            input_path: args.path,
+            approved: options.approved,
+            format: options.artifactFormat,
+            source_map_read_approved: options.sourceMapReadApproved,
+            limits: {
+                max_entries: options.maxEntries,
+                max_total_artifact_bytes: options.maxTotalArtifactBytes,
+                max_artifact_entry_bytes: options.maxArtifactEntryBytes,
+                max_compression_ratio: options.maxCompressionRatio,
+                max_depth: options.maxDepth,
+                max_path_bytes: options.maxPathBytes,
+                max_text_files: options.maxTextFiles,
+                max_total_text_bytes: options.maxTotalTextBytes,
+                max_text_file_bytes: options.maxTextFileBytes,
+                max_ast_nodes: options.maxAstNodes,
+                max_findings: options.maxFindings,
+                max_modules: options.maxModules,
+                max_source_map_sources: options.maxSourceMapSources,
+                max_parse_milliseconds: options.maxParseMilliseconds,
+            },
+        })),
     });
 };
 const electronContext = async () => {

package/dist/cliObservationOptions.js

@@ -108,7 +108,7 @@ export const javascriptApplicationOptions = z.object({
         .boolean()
         .default(false)
         .describe("Approve reading the application artifact"),
-    format: z
+    artifactFormat: z
         .enum(["auto", "asar", "directory"])
         .default("auto")
         .describe("Application artifact format"),

package/dist/cliOutput.js

@@ -1,4 +1,5 @@
 const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `rea --help`, correct the arguments, then try again.";
+const UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE = "Token windows cannot preserve structured output. Remove --token-limit/--token-offset and use --filter-output or command pagination.";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const validationError = (value) => {
     if (!isRecord(value))
@@ -9,6 +10,61 @@ const validationError = (value) => {
         return value.error.code === "VALIDATION_ERROR" ? value.error : undefined;
     return undefined;
 };
+/** Reject text-window controls that would corrupt a structured document. */
+export const validateCliOutputArguments = (arguments_) => {
+    let format = "toon";
+    let tokenWindow = false;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--")
+            break;
+        if (argument === "--json") {
+            format = "json";
+            continue;
+        }
+        if (argument === "--format") {
+            const value = arguments_[index + 1];
+            if (value !== undefined) {
+                format = value;
+                index += 1;
+            }
+            continue;
+        }
+        if (argument?.startsWith("--format=")) {
+            format = argument.slice("--format=".length);
+            continue;
+        }
+        if (argument === "--token-limit" || argument === "--token-offset") {
+            if (arguments_[index + 1] !== undefined) {
+                tokenWindow = true;
+                index += 1;
+            }
+            continue;
+        }
+        if (argument?.startsWith("--token-limit=") ||
+            argument?.startsWith("--token-offset="))
+            tokenWindow = true;
+    }
+    if (tokenWindow &&
+        (format === "json" || format === "jsonl" || format === "yaml"))
+        return {
+            ok: false,
+            format,
+            code: "UNSUPPORTED_OUTPUT_COMBINATION",
+            message: UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE,
+        };
+    return { ok: true };
+};
+/** Render one complete structured error before command execution. */
+export const renderCliOutputArgumentError = (error) => {
+    const value = {
+        ok: false,
+        error: { code: error.code, message: error.message },
+    };
+    if (error.format === "yaml")
+        return `ok: false\nerror:\n  code: ${error.code}\n  message: ${JSON.stringify(error.message)}\n`;
+    return `${JSON.stringify(value)}\n`;
+};
 /** Remove validator internals from Incur's caller-visible CLI output. */
 export const sanitizeCliOutput = (output) => {
     const trimmed = output.trimStart();

package/dist/cliProcessCommands.js

@@ -2,8 +2,13 @@ import { Cli, z } from "incur";
 import { captureProcessScenarioFile, compareProcessEvidenceFiles, } from "./application/ProcessCli.js";
 import { logCliCommand } from "./cliLogging.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput } from "./cliJsonInput.js";
+import { replayMachineRunInputSchema, runReplayMachine, } from "./domain/replayMachineRun.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { projectInputIssues } from "./domain/inputIssueProjection.js";
 /** Register Process Capture v4 one-shot commands through shared application services. */
 export const registerProcessCommands = (cli, logger) => {
+    registerReplayMachineCommand(cli, logger);
     cli.command(CLI_COMMANDS.captureProcess, {
         description: "Capture one approved Process Capture v4 JSON scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
@@ -14,7 +19,33 @@ export const registerProcessCommands = (cli, logger) => {
         args: z.object({
             left: z.string().describe("Left capture Evidence JSON path"),
             right: z.string().describe("Right capture Evidence JSON path"),
+            traceSpec: z
+                .string()
+                .optional()
+                .describe("Optional partial-order or finite-trace specification path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right, args.traceSpec)),
+    });
+};
+const registerReplayMachineCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.runReplayMachine, {
+        description: "Run ordered protocol events directly through a finite replay machine",
+        args: z.object({
+            inputJson: z.string().describe("Inline replay JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.runReplayMachine, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.runReplayMachine);
+            if (!input.ok)
+                return input.error;
+            const parsed = replayMachineRunInputSchema.safeParse(input.value);
+            return parsed.success
+                ? runReplayMachine(parsed.data)
+                : {
+                    error: "Process command failed",
+                    ...projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.runReplayMachine, {
+                        cause: parsed.error,
+                    }, projectInputIssues(parsed.error.issues, input.value))),
+                };
         }),
-        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right)),
     });
 };

package/dist/cliSetup.js

@@ -1,4 +1,5 @@
 import { cancel, confirm, intro, isCancel, multiselect, outro, } from "@clack/prompts";
+import { projectDoctorReport } from "./application/DoctorProjection.js";
 import { SUPPORTED_CLIENT_DEFINITIONS } from "./application/SupportedClients.js";
 const clientDisplayNames = new Map(SUPPORTED_CLIENT_DEFINITIONS.map(({ name, displayName }) => [
     name,
@@ -9,8 +10,8 @@ const promptStreams = {
     output: process.stderr,
     withGuide: true,
 };
-const agentAccessCapabilityId = "agent_access";
-/** Run the inline setup picker, exact preflight, and default-No consent. */
+const agentIntegrationCapabilityId = "agent_integration";
+/** Run the inline setup picker, exact preflight, and explicit consent. */
 export const confirmInteractiveSetup = async (actions, accessible) => {
     intro("REA setup", promptStreams);
     renderValueIntroduction();
@@ -31,7 +32,7 @@ export const confirmInteractiveSetup = async (actions, accessible) => {
         message: selectedActions.length === 1
             ? "Apply this change?"
             : `Apply these ${String(selectedActions.length)} changes?`,
-        initialValue: false,
+        initialValue: true,
         active: "Yes, apply",
         inactive: "No, cancel",
     });
@@ -77,10 +78,7 @@ export const conciseSetupResult = (result) => ({
     plannedActions: result.plannedActions,
     appliedActions: result.appliedActions,
     clients: result.clients,
-    doctor: {
-        healthy: result.doctor.healthy,
-        checks: result.doctor.checks.filter(({ ok }) => !ok),
-    },
+    doctor: projectDoctorReport(result.doctor, "summary"),
     ...(result.code === undefined ? {} : { code: result.code }),
     ...(result.remediation === undefined
         ? {}
@@ -90,41 +88,65 @@ const selectSetupActions = async (actions, accessible) => {
     const clientActions = actions.filter(({ kind }) => kind === "configure_client");
     const componentActions = actions.filter(({ kind }) => kind !== "configure_client");
     const capabilities = setupCapabilities(clientActions, componentActions);
+    const preselectedCapabilityIds = defaultCapabilityIds(capabilities);
     const selectedCapabilities = accessible
-        ? await selectCapabilitiesAccessibly(capabilities)
-        : await selectCapabilities(capabilities);
+        ? await selectCapabilitiesAccessibly(capabilities, preselectedCapabilityIds)
+        : await selectCapabilities(capabilities, preselectedCapabilityIds);
     if (selectedCapabilities === undefined)
         return undefined;
     const selectedCapabilityIds = new Set(selectedCapabilities);
+    const bundledSkillAction = componentActions.find(({ kind }) => kind === "install_skill");
     const selectedActionIds = componentActions
-        .filter(({ id }) => selectedCapabilityIds.has(id))
+        .filter(({ id }) => id !== bundledSkillAction?.id && selectedCapabilityIds.has(id))
         .map(({ id }) => id);
-    if (!selectedCapabilityIds.has(agentAccessCapabilityId))
+    if (!selectedCapabilityIds.has(agentIntegrationCapabilityId))
         return selectedActionIds;
+    const bundledSkillId = bundledSkillAction === undefined ? undefined : bundledSkillAction.id;
+    if (clientActions.length === 0)
+        return [
+            ...(bundledSkillId === undefined ? [] : [bundledSkillId]),
+            ...selectedActionIds,
+        ];
+    const preselectedClientIds = clientActions.map(({ id }) => id);
     const selectedClients = accessible
-        ? await selectClientsAccessibly(clientActions)
-        : await selectClients(clientActions);
-    return selectedClients === undefined
-        ? undefined
-        : [...selectedClients, ...selectedActionIds];
+        ? await selectClientsAccessibly(clientActions, preselectedClientIds)
+        : await selectClients(clientActions, preselectedClientIds);
+    if (selectedClients === undefined)
+        return undefined;
+    return [
+        ...selectedClients,
+        ...(bundledSkillId === undefined ? [] : [bundledSkillId]),
+        ...selectedActionIds,
+    ];
+};
+const defaultCapabilityIds = (capabilities) => {
+    const hasAgentIntegration = capabilities.some(({ id }) => id === agentIntegrationCapabilityId);
+    if (!hasAgentIntegration)
+        return [];
+    return [agentIntegrationCapabilityId];
 };
 const setupCapabilities = (clientActions, componentActions) => [
-    ...(clientActions.length === 0
+    ...(clientActions.length === 0 &&
+        !componentActions.some(({ kind }) => kind === "install_skill")
         ? []
         : [
             {
-                id: agentAccessCapabilityId,
-                label: "Coding-agent access (MCP)",
-                hint: `${String(clientActions.length)} detected ${clientActions.length === 1 ? "agent" : "agents"}`,
+                id: agentIntegrationCapabilityId,
+                label: "Agent integration (MCP + guided workflow)",
+                hint: clientActions.length === 0
+                    ? "MCP registrations are aligned; installs the matching bundled skill"
+                    : `${String(clientActions.length)} detected ${clientActions.length === 1 ? "agent" : "agents"}; installs the bundled skill when needed`,
             },
         ]),
-    ...componentActions.map((action) => ({
+    ...componentActions
+        .filter(({ kind }) => kind !== "install_skill")
+        .map((action) => ({
         id: action.id,
         label: `${action.label} (${actionModality(action)})`,
         hint: `${action.operation} · ${action.target}`,
     })),
 ];
-const selectCapabilities = async (capabilities) => {
+const selectCapabilities = async (capabilities, initialValues) => {
     const selection = await multiselect({
         ...promptStreams,
         message: "What should REA set up?",
@@ -133,19 +155,21 @@ const selectCapabilities = async (capabilities) => {
             label: capability.label,
             hint: capability.hint,
         })),
+        initialValues: [...initialValues],
         required: false,
         maxItems: Math.max(3, Math.min(capabilities.length, (process.stderr.rows ?? 24) - 8)),
         showInstructions: true,
     });
     return isCancel(selection) ? undefined : selection;
 };
-const selectCapabilitiesAccessibly = async (capabilities) => {
+const selectCapabilitiesAccessibly = async (capabilities, preselectedIds) => {
+    const preselected = new Set(preselectedIds);
     const selected = [];
     for (const capability of capabilities) {
         const included = await confirm({
             ...promptStreams,
             message: `Set up ${capability.label}? ${capability.hint}`,
-            initialValue: false,
+            initialValue: preselected.has(capability.id),
             vertical: true,
         });
         if (isCancel(included))
@@ -155,28 +179,30 @@ const selectCapabilitiesAccessibly = async (capabilities) => {
     }
     return selected;
 };
-const selectClients = async (actions) => {
+const selectClients = async (actions, initialValues) => {
     const selection = await multiselect({
         ...promptStreams,
         message: "Which agents should use REA?",
         options: actions.map((action) => ({
             value: action.id,
             label: `${action.label} (detected)`,
-            hint: `${action.operation} · ${action.target}`,
+            hint: `Configure the REA MCP server for ${action.label}`,
         })),
+        initialValues: [...initialValues],
         required: false,
         maxItems: Math.max(3, Math.min(actions.length, (process.stderr.rows ?? 24) - 8)),
         showInstructions: true,
     });
     return isCancel(selection) ? undefined : selection;
 };
-const selectClientsAccessibly = async (actions) => {
+const selectClientsAccessibly = async (actions, initialValues) => {
+    const preselected = new Set(initialValues);
     const selected = [];
     for (const action of actions) {
         const included = await confirm({
             ...promptStreams,
             message: `Configure ${action.label}? ${action.target}`,
-            initialValue: false,
+            initialValue: preselected.has(action.id),
             vertical: true,
         });
         if (isCancel(included))
@@ -223,7 +249,7 @@ const renderReadyCapabilities = (result, readyClients) => {
         writeLine("│  CLI: rea analyze /path/to/app");
     const firstClient = readyClients[0];
     if (firstClient !== undefined)
-        writeLine(`│  Try in ${firstClient}: "Use REA to explain how a feature works in /path/to/app."`);
+        writeLine(`│  Try in ${firstClient}: "Explain how a feature works in /path/to/app and show the evidence."`);
 };
 const readyAgentClients = (result, changedClients) => {
     const alignedClients = (result.doctor.identity?.registrations ?? [])

package/dist/contracts/applicationToolContracts.js

@@ -1,5 +1,8 @@
-import { applicationVersionComparisonResultSchema, compareApplicationVersionsInputSchema, } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
-import { applicationFeatureTraceResultSchema, traceApplicationFeatureInputSchema, } from "../domain/javascriptFeatureTraceSchemas.js";
+import { applicationVersionComparisonResultSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { applicationFeatureTraceResultSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import { javaScriptSemanticTraceResultSchema } from "../domain/javascriptSemanticTraceSchemas.js";
+import { javaScriptExportShapeComparisonResultSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
+import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "./applicationWorkflowInputContracts.js";
 import { controlledReplayInputSchema, controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
 import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
 import { reconstructionCoverageCommitInputSchema, reconstructionCoverageCommitOutputSchema, reconstructionCoverageQueryInputSchema, } from "../application/ReconstructionCoverageService.js";
@@ -7,9 +10,11 @@ import { reconstructionClosureResultSchema } from "../domain/reconstructionCover
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
+import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, } from "./javascriptApplicationWorkflowExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
+const semanticTraceOutputSchema = evidenceResultOf(javaScriptSemanticTraceResultSchema);
 const comparisonOutputSchema = evidenceResultOf(applicationVersionComparisonResultSchema);
+const exportShapeComparisonOutputSchema = evidenceResultOf(javaScriptExportShapeComparisonResultSchema);
 const HASH = "0".repeat(64);
 const NODE_PREPARATION_EXAMPLE = jsonObjectSchema.parse({
     preparation_approved: true,
@@ -77,9 +82,9 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "trace_application_feature",
         ...toolContractMetadata("trace_application_feature"),
-        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph with explicit direction, depth, node, edge, and path bounds. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
+        description: "Trace a typed literal seed through an authenticated JavaScript Application Graph supplied as full Evidence or an Evidence ID returned earlier in this session. Explicit direction, depth, node, edge, and path bounds apply. Original static, native, passive-runtime, inferred, and unknown authorities remain distinct; native addon handoffs never open a provider or execute the application.",
         kind: "application",
-        inputSchema: traceApplicationFeatureInputSchema,
+        inputSchema: traceApplicationFeatureRequestSchema,
         outputSchema: traceOutputSchema,
         examples: [
             {
@@ -88,12 +93,33 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "trace_javascript_semantics",
+        ...toolContractMetadata("trace_javascript_semantics"),
+        description: "Trace bounded static JavaScript data-flow, direct call/return, and closure relations from authenticated analyze_javascript_application v2 Evidence. Queries declare direction and exact node, relation, depth, function, module, and page limits. Dynamic or unsupported semantics remain explicit unknowns; static reachability never claims runtime execution.",
+        kind: "application",
+        inputSchema: traceJavaScriptSemanticsRequestSchema,
+        outputSchema: semanticTraceOutputSchema,
+        examples: [
+            {
+                title: "Trace backward provenance from one semantic node",
+                input: {
+                    application_evidence_id: `ev_${HASH}`,
+                    query: {
+                        seed: { kind: "semantic-node", node_id: `jsrg_node_${HASH}` },
+                        direction: "backward-provenance",
+                        source_map_authority: { authority: "none" },
+                    },
+                },
+            },
+        ],
+    },
     {
         name: "compare_application_versions",
         ...toolContractMetadata("compare_application_versions"),
-        description: "Compare two authenticated JavaScript Application Graph versions using unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
+        description: "Compare two authenticated JavaScript Application Graph versions supplied as full Evidence or Evidence IDs returned earlier in this session. Uses unique-only exact digest, module source digest, source-map identity, structural fingerprint, and non-module semantic-key tiers. Reports added, removed, changed, ambiguous, and unknown entities plus a bounded changed_from graph without fuzzy or module-ordinal pairing.",
         kind: "application",
-        inputSchema: compareApplicationVersionsInputSchema,
+        inputSchema: compareApplicationVersionsRequestSchema,
         outputSchema: comparisonOutputSchema,
         examples: [
             {
@@ -102,6 +128,20 @@ export const APPLICATION_TOOL_CONTRACTS = [
             },
         ],
     },
+    {
+        name: "compare_javascript_export_shapes",
+        ...toolContractMetadata("compare_javascript_export_shapes"),
+        description: "Compare bounded static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph, supplied as full Evidence or session Evidence IDs. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes and recommends controlled replay separately without executing JavaScript.",
+        kind: "application",
+        inputSchema: compareJavaScriptExportShapesRequestSchema,
+        outputSchema: exportShapeComparisonOutputSchema,
+        examples: [
+            {
+                title: "Compare one exact parser export without execution",
+                input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
+            },
+        ],
+    },
     {
         name: "run_controlled_replay",
         ...toolContractMetadata("run_controlled_replay"),
@@ -223,3 +263,10 @@ export const APPLICATION_TOOL_CONTRACTS = [
         ],
     },
 ];
+/** Resolve one named application contract without relying on array position. */
+export const applicationToolContract = (name) => {
+    const contract = APPLICATION_TOOL_CONTRACTS.find(({ name: candidate }) => candidate === name);
+    if (contract === undefined)
+        throw new Error(`Missing application tool contract: ${name}`);
+    return contract;
+};