rea-agents 6.4.0 → 6.5.0

package/dist/server/registerWasmTools.js

@@ -0,0 +1,46 @@
+import { compareWasmInterfaces } from "../application/wasm/WasmInterfaceComparisonService.js";
+import { COMPARE_WASM_INTERFACES_CONTRACT } from "../contracts/wasm/wasmComparisonContracts.js";
+import { resolvePairedEvidenceRequest } from "../application/EvidenceInputResolver.js";
+import { recordSessionEvidenceSources } from "./sessionEvidence.js";
+import { summarizeRetainedAnalysis } from "../application/analysisView/AnalysisViewService.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { err } from "../domain/result.js";
+import { wasmArtifactModule } from "../composition/wasm.js";
+import { createEvidenceToolHandler } from "./contractToolHandler.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Bind the named WASM contract to shared validation and session Evidence recording. */
+export const registerWasmTools = (server, service, logger, recordEvidence, withAdmittedAnalysis, evidenceById) => {
+    const comparison = COMPARE_WASM_INTERFACES_CONTRACT;
+    const compareHandler = createEvidenceToolHandler(server, async (rawInput, options) => {
+        const input = comparison.inputSchema.safeParse(rawInput);
+        if (!input.success)
+            return err(analysisInputErrorFromIssues(comparison.name, input.error.issues, rawInput));
+        const sources = resolvePairedEvidenceRequest(input.data, evidenceById);
+        if (!sources.ok)
+            return sources;
+        const result = await compareWasmInterfaces(sources.value, options);
+        if (!result.ok)
+            return result;
+        const recorded = recordSessionEvidenceSources(recordEvidence, [
+            sources.value.left,
+            sources.value.right,
+        ]);
+        return recorded.ok ? result : recorded;
+    }, logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(comparison.name, toolRegistrationOptions(comparison), compareHandler(comparison));
+    const contract = wasmArtifactModule.contract;
+    const handler = createEvidenceToolHandler(server, async (rawInput, options) => {
+        const parsed = contract.inputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return err(analysisInputErrorFromIssues(contract.name, parsed.error.issues, rawInput, { cause: parsed.error }));
+        const { detail, ...input } = parsed.data;
+        const inspected = await service.inspect(input, options);
+        return detail === "summary" && inspected.ok
+            ? summarizeRetainedAnalysis(inspected.value, {
+                recordEvidence,
+                evidenceById,
+            })
+            : inspected;
+    }, logger, recordEvidence, withAdmittedAnalysis);
+    server.registerTool(contract.name, toolRegistrationOptions(contract), handler(contract));
+};

package/dist/server/registerWebNetworkCaptureTool.js

@@ -1,20 +1,34 @@
+import { requireAnalysisViewRetention, summarizeRetainedAnalysis, } from "../application/analysisView/AnalysisViewService.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js";
+import { captureSensitiveValues } from "../domain/webNetworkCapture.js";
+import { err } from "../domain/result.js";
 import { toolContract } from "../contracts/toolContracts.js";
 import { createEvidenceToolHandler } from "./contractToolHandler.js";
-import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { toolRegistrationOptions, applicationValidatedInputSchema, } from "./toolRegistrationOptions.js";
 /** Bind historical inspection to its named contract and caller-owned Evidence writer. */
-export const registerWebNetworkCaptureTool = (server, service, logger, recordEvidence, withAdmittedAnalysis) => {
+export const registerWebNetworkCaptureTool = (server, service, logger, recordEvidence, withAdmittedAnalysis, evidenceById) => {
     const contract = toolContract("inspect_web_network_capture");
     const registration = toolRegistrationOptions(contract);
     // Keep the exact advertised contract; the shared service validates raw input
     // before effects so caller-declared sensitivity also covers invalid arguments.
     // SDK pre-validation otherwise emits unprojected issue paths as plain text.
-    const inputSchema = {
-        "~standard": {
-            ...registration.inputSchema["~standard"],
-            vendor: "rea-application",
-            validate: (value) => ({ value }),
-        },
-    };
-    const handler = createEvidenceToolHandler(server, (input, options) => service.inspect(input, options), logger, recordEvidence, withAdmittedAnalysis);
+    const inputSchema = applicationValidatedInputSchema(registration.inputSchema);
+    const handler = createEvidenceToolHandler(server, async (rawInput, options) => {
+        const parsed = contract.inputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return err(redactExplicitFailure(analysisInputErrorFromIssues(contract.name, parsed.error.issues, rawInput, { cause: parsed.error }), captureSensitiveValues(rawInput)));
+        const { detail, ...input } = parsed.data;
+        const retention = { recordEvidence, evidenceById };
+        if (detail === "summary") {
+            const ready = requireAnalysisViewRetention(contract.name, retention);
+            if (!ready.ok)
+                return ready;
+        }
+        const inspected = await service.inspect(input, options);
+        return detail === "summary" && inspected.ok
+            ? summarizeRetainedAnalysis(inspected.value, retention)
+            : inspected;
+    }, logger, recordEvidence, withAdmittedAnalysis);
     server.registerTool(contract.name, { ...registration, inputSchema }, handler(contract));
 };

package/dist/server/retainedSummaryDelivery.js

@@ -0,0 +1,28 @@
+import { requireAnalysisViewRetention, summarizeRetainedAnalysis, } from "../application/analysisView/AnalysisViewService.js";
+import { ok } from "../domain/result.js";
+/**
+ * Summary delivery for the named operations: refuse it before analysis when
+ * this server retains no Evidence, then return the retained summary view.
+ */
+export const retainedSummaryDelivery = (operations, options) => {
+    const retention = {
+        recordEvidence: options.recordEvidence,
+        evidenceById: options.evidenceById,
+    };
+    const selected = (operation, parameters) => operations.has(operation) && parameters.detail === "summary";
+    return {
+        preflight: (operation, parameters) => selected(operation, parameters)
+            ? requireAnalysisViewRetention(operation, retention)
+            : ok(null),
+        projectEvidence: (operation, parameters, evidence) => selected(operation, parameters)
+            ? summarizeRetainedAnalysis(evidence, retention)
+            : ok(evidence),
+    };
+};
+/** Delivery detail selects a response shape; it never reaches tools or Evidence identity. */
+export const withoutDeliveryDetail = (operations) => (operation, parameters) => {
+    if (!operations.has(operation))
+        return parameters;
+    const { detail: _detail, ...selected } = parameters;
+    return selected;
+};

package/dist/server/sessionAvailabilityPolicy.js

@@ -3,6 +3,9 @@ import { platform } from "node:process";
 export const sessionAvailabilityPolicy = (configured, defaults) => {
     const policy = configured ??
         (() => ({
+            packetCaptureEnabled: defaults.optionalFeatures?.packetCaptureEnabled ?? false,
+            signalRecordingEnabled: defaults.optionalFeatures?.signalRecordingEnabled ?? false,
+            wasmArtifactEnabled: defaults.optionalFeatures?.wasmArtifactEnabled ?? false,
             evmInterfaceEnabled: defaults.optionalFeatures?.evmInterfaceEnabled ?? false,
             processCaptureEnabled: platform !== "win32",
             recordedCrashEnabled: defaults.optionalFeatures?.recordedCrashEnabled ?? false,

package/dist/server/toolRegistrationOptions.js

@@ -1,4 +1,12 @@
 import { toolInputSchemaWithMetadata, toolOutputSchemaWithMetadata, } from "../contracts/toolSchemaMetadata.js";
+/** Preserve advertised contracts while the application owns structured input failures. */
+export const applicationValidatedInputSchema = (schema) => ({
+    "~standard": {
+        ...schema["~standard"],
+        vendor: "rea-application",
+        validate: (value) => ({ value }),
+    },
+});
 /** Project the canonical Zod contracts directly into SDK registration. */
 export const toolRegistrationOptions = (contract) => ({
     title: contract.title,

package/dist/server/toolResult.js

@@ -1,10 +1,29 @@
+import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../domain/analysisView/analysisViewErrors.js";
 import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";
+import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
 import { projectAnalysisError, } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
 import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
-import { encodeToolResult, MCP_RESULT_STRING_LIMIT, } from "./toolResultEncoding.js";
+import { encodeToolResult, MCP_RESULT_STRING_LIMIT, TARGET_CONTENT_RESULT_META, } from "./toolResultEncoding.js";
 /** Create one delivery policy from the already selected, parsed response budget. */
 export const createToolResultDelivery = (maximumResponseBytes) => new ToolResultDelivery(maximumResponseBytes ?? STDIO_DEFAULT_MAX_BUFFER_SIZE);
+/** Offer a named, schema-validated source page only for retained native analysis. */
+const nativeEvidenceContinuation = (evidence) => {
+    if (evidence.operation !== "analyze_function")
+        return {};
+    const input = inspectAnalysisViewInputSchema.safeParse({
+        source: { kind: "retained-evidence", evidence_id: evidence.evidence_id },
+        view: { kind: "native", facet: "pseudocode", offset: 0 },
+    });
+    if (!input.success)
+        return {};
+    return {
+        continuation: {
+            name: INSPECT_ANALYSIS_VIEW_OPERATION,
+            arguments: jsonValueSchema.parse(input.data),
+        },
+    };
+};
 /** Immutable encoding and recovery policy shared by one MCP server. */
 export class ToolResultDelivery {
     resultBudgetBytes;
@@ -16,12 +35,12 @@ export class ToolResultDelivery {
     toCallToolResult(result, contract) {
         return result.ok
             ? this.successResult(contract.kind === "session" ? { result: result.value } : result.value, contract)
-            : this.toErrorToolResult(result.error);
+            : this.toErrorToolResult(result.error, contract.returnsTargetContent);
     }
     /** Deliver Evidence using the producer's explicit recording acknowledgment. */
     toEvidenceToolResult(evidence, contract, recorded) {
         return recorded !== undefined && !recorded.ok
-            ? this.toErrorToolResult(recorded.error)
+            ? this.toErrorToolResult(recorded.error, contract.returnsTargetContent)
             : this.successResult(evidence, contract, {
                 evidence_id: evidence.evidence_id,
                 ...(recorded === undefined
@@ -31,17 +50,23 @@ export class ToolResultDelivery {
                             kind: "retained-evidence",
                             evidence_id: evidence.evidence_id,
                         },
+                        ...nativeEvidenceContinuation(evidence),
                     }),
             });
     }
-    /** Project an error without allocating oversized repeated MCP text. */
-    toErrorToolResult(error) {
-        return this.projectedErrorResult(projectAnalysisError(error));
+    /**
+     * Project an error without allocating oversized repeated MCP text.
+     * `targetContent` is the failing tool's `returnsTargetContent`: a failure
+     * can carry target-derived text (a message, captured output, or a partial
+     * observation), so it is marked exactly like that tool's successful results.
+     */
+    toErrorToolResult(error, targetContent) {
+        return this.projectedErrorResult(projectAnalysisError(error), targetContent);
     }
     /** Deliver the original failure with the producer-acknowledged partial Evidence reference. */
-    toRecordedPartialErrorToolResult(error, evidenceId, recorded) {
+    toRecordedPartialErrorToolResult(error, evidenceId, recorded, targetContent) {
         if (!recorded.ok)
-            return this.toErrorToolResult(error);
+            return this.toErrorToolResult(error, targetContent);
         const projected = projectAnalysisError(error);
         return this.projectedErrorResult({
             ...projected,
@@ -52,34 +77,40 @@ export class ToolResultDelivery {
                     evidence_id: evidenceId,
                 },
             },
-        });
+        }, targetContent);
     }
-    projectedErrorResult(projected) {
+    projectedErrorResult(projected, targetContent) {
         const structuredContent = { error: projected };
         // Errors reach the wire as text only; the structured copy is a private
         // carrier the transport removes after its own budget check.
-        const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "text");
+        const encoded = encodeToolResult(structuredContent, this.resultBudgetBytes, "error-text", targetContent);
         // The transport retains an oversized projected error before replacing it
         // with a recoverable delivery constraint, using this same budget.
         return {
             content: encoded.ok ? [{ type: "text", text: encoded.text }] : [],
             structuredContent,
             isError: true,
+            ...(targetContent ? { _meta: TARGET_CONTENT_RESULT_META } : {}),
         };
     }
     successResult(value, contract, recovery = {}) {
-        const encoded = encodeToolResult(value, this.resultBudgetBytes);
+        const encoded = encodeToolResult(value, this.resultBudgetBytes, "structured-and-text", contract.returnsTargetContent);
         if (encoded.ok)
             return {
                 content: [{ type: "text", text: encoded.text }],
                 structuredContent: value,
+                ...(contract.returnsTargetContent
+                    ? { _meta: TARGET_CONTENT_RESULT_META }
+                    : {}),
             };
         const retainedEvidence = recovery.evidence_reference !== undefined;
-        const recoveryAdvice = retainedEvidence
-            ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
-            : encoded.constraint === "string-length"
-                ? "Use complete CLI JSON output to consume the analysis."
-                : "Use a larger MCP response budget with a matching client receive buffer, or use complete CLI JSON output to consume the analysis.";
+        const recoveryAdvice = recovery.continuation !== undefined
+            ? "Call inspect_analysis_view with the supplied continuation arguments to read retained pseudocode. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence."
+            : retainedEvidence
+                ? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
+                : encoded.constraint === "string-length"
+                    ? "Use complete CLI JSON output to consume the analysis."
+                    : "Use a larger MCP response budget with a matching client receive buffer, or use complete CLI JSON output to consume the analysis.";
         return this.toErrorToolResult(new AnalysisResourceConstraintError(contract.name, "transport", encoded.constraint === "string-length"
             ? `The operation completed, but its complete MCP response exceeds Node's single-string representation limit. ${recoveryAdvice}`
             : `The operation completed, but its complete MCP response exceeds the stdio response budget. The analysis result was not truncated. ${recoveryAdvice}`, {
@@ -91,6 +122,8 @@ export class ToolResultDelivery {
             response_code_units_at_least: encoded.codeUnitsAtLeast,
             constraint: encoded.constraint,
             ...recovery,
-        }));
+        }, recovery.continuation === undefined
+            ? undefined
+            : { remediationAction: recoveryAdvice }), contract.returnsTargetContent);
     }
 }

package/dist/server/toolResultEncoding.js

@@ -5,12 +5,45 @@ const RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({
     content: [{ type: "text", text: "" }],
     structuredContent: null,
 })) - 4;
-const TEXT_RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ content: [{ type: "text", text: "" }] }));
+const ERROR_RESULT_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ content: [{ type: "text", text: "" }], isError: true }));
+/**
+ * Result metadata marking content that originates from the analysis target.
+ * Hosts and hooks can read it to treat the result as untrusted data.
+ */
+export const TARGET_CONTENT_RESULT_META = Object.freeze({
+    provenance: Object.freeze({
+        untrusted_content: true,
+        source: "analysis_target",
+    }),
+});
+/** Whether a delivered tool result already carries the untrusted target-content marker. */
+export const carriesTargetContentMarker = (result) => {
+    const meta = result._meta;
+    if (typeof meta !== "object" || meta === null)
+        return false;
+    const provenance = Reflect.get(meta, "provenance");
+    return (typeof provenance === "object" &&
+        provenance !== null &&
+        Reflect.get(provenance, "untrusted_content") === true);
+};
+// `,"_meta":{...}` added to the delivered result object.
+const TARGET_CONTENT_META_BYTES = Buffer.byteLength(JSON.stringify({ _meta: TARGET_CONTENT_RESULT_META })) - 1;
+/** Measure an already-formed MCP result object without allocating its JSON text. */
+export const measureMcpResultWithinBudget = (value, budgetBytes) => {
+    let bytes = 0;
+    for (const part of bufferedJsonParts(jsonParts(value))) {
+        bytes += Buffer.byteLength(part);
+        if (bytes > budgetBytes)
+            return { ok: false, bytesAtLeast: bytes, constraint: "receive-buffer" };
+    }
+    return { ok: true, bytes };
+};
 /** Account for the delivered JSON representations before allocating the complete text. */
-export const encodeToolResult = (value, budgetBytes, representations = "structured-and-text") => {
+export const encodeToolResult = (value, budgetBytes, representations = "structured-and-text", targetContent = false) => {
     const structured = representations === "structured-and-text";
     const parts = [];
-    let bytes = structured ? RESULT_ENVELOPE_BYTES : TEXT_RESULT_ENVELOPE_BYTES;
+    let bytes = (structured ? RESULT_ENVELOPE_BYTES : ERROR_RESULT_ENVELOPE_BYTES) +
+        (targetContent ? TARGET_CONTENT_META_BYTES : 0);
     let codeUnits = bytes;
     for (const part of bufferedJsonParts(jsonParts(value))) {
         const escapedPart = JSON.stringify(part);

package/dist/serverIdentity.js

@@ -1,6 +1,6 @@
 import { dirname, basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CATALOG_IDENTITY } from "./catalogIdentity.js";
+import { CATALOG_IDENTITY, } from "./catalogIdentity.js";
 import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
 const packageRoot = () => {
     const moduleDirectory = dirname(fileURLToPath(import.meta.url));
@@ -11,19 +11,22 @@ const packageRoot = () => {
 };
 /** Build one runtime identity without claiming alignment from absent observations. */
 export const createServerIdentity = (input) => {
-    const serverPath = resolve(process.argv[1] ?? "unknown");
+    const catalog = input.catalog ?? CATALOG_IDENTITY;
+    const serverPath = input.commandPath || undefined;
     const reasons = [];
     if (input.expected?.package_version !== undefined &&
         input.expected.package_version !== PRODUCT_IDENTITY.packageVersion)
         reasons.push("package_version_mismatch");
     if (input.expected?.catalog_digest !== undefined &&
-        input.expected.catalog_digest !== CATALOG_IDENTITY.digests.combined_sha256)
+        input.expected.catalog_digest !== catalog.digests.combined_sha256)
         reasons.push("catalog_digest_mismatch");
     if (input.expected?.server_path !== undefined &&
+        serverPath !== undefined &&
         resolve(input.expected.server_path) !== serverPath)
         reasons.push("registration_path_mismatch");
     const observedExpectation = input.expected !== undefined &&
         Object.values(input.expected).some((value) => value !== undefined);
+    const pathComparable = input.expected?.server_path === undefined || serverPath !== undefined;
     return {
         package: {
             name: PRODUCT_IDENTITY.packageName,
@@ -35,7 +38,7 @@ export const createServerIdentity = (input) => {
             name: PRODUCT_IDENTITY.mcpServerKey,
             version: PRODUCT_IDENTITY.packageVersion,
             started_at: input.startedAt,
-            command_path: serverPath,
+            command_path: serverPath ?? null,
         },
         sdk: SDK_IDENTITY,
         negotiated_protocol_version: input.protocolVersion ?? null,
@@ -46,7 +49,10 @@ export const createServerIdentity = (input) => {
             name: PRODUCT_IDENTITY.skillName,
             expected_version: PRODUCT_IDENTITY.skillVersion,
         },
-        catalog: CATALOG_IDENTITY,
+        catalog: {
+            counts: catalog.counts,
+            digests: catalog.digests,
+        },
         protocol_features: {
             progress: true,
             cancellation: true,
@@ -55,15 +61,18 @@ export const createServerIdentity = (input) => {
         alignment: {
             state: reasons.length > 0
                 ? "mcp_server_restart_required"
-                : observedExpectation
+                : observedExpectation && pathComparable
                     ? "aligned"
                     : "unknown",
             reasons,
             remediation: reasons.length > 0
                 ? "Restart the registered MCP server/client, then compare identity again."
-                : observedExpectation
+                : observedExpectation && pathComparable
                     ? null
-                    : "Supply expected package, catalog, or registration identity to compare the live server.",
+                    : input.expected?.server_path !== undefined &&
+                        serverPath === undefined
+                        ? "The server entrypoint path is unavailable, so registration identity cannot be compared."
+                        : "Supply expected package, catalog, or registration identity to compare the live server.",
         },
     };
 };