rea-agents 5.0.0 → 6.1.0

package/dist/application/WebNetworkCaptureService.js

@@ -0,0 +1,134 @@
+import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js";
+import { excludeCaptureCoordinates } from "../domain/webNetworkCaptureCoordinates.js";
+import { redactExplicitText } from "../domain/explicitSensitiveValues.js";
+import { isAbsolute } from "node:path";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { createEvidence } from "../domain/evidence.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { jsonObjectSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
+const OPERATION = "inspect_web_network_capture";
+/** Shared CLI/MCP historical inspection preserves caller selection and producer record identity. */
+export class WebNetworkCaptureService {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    /** Return selected complete records inline, without inventing live browser attribution. */
+    async inspect(rawInput, options) {
+        if (options?.signal?.aborted)
+            return err(new AnalysisCancelledError(OPERATION));
+        const declarations = inspectWebNetworkCaptureInputSchema.shape.sensitive_values.safeParse(typeof rawInput === "object" &&
+            rawInput !== null &&
+            "sensitive_values" in rawInput
+            ? rawInput.sensitive_values
+            : undefined);
+        const failure = (error) => err(redactExplicitFailure(error, declarations.success ? declarations.data : []));
+        const parsed = inspectWebNetworkCaptureInputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return failure(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
+        const input = parsed.data;
+        if (!isAbsolute(input.capture_path))
+            return failure(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["capture_path"],
+                    reason: "invalid_format",
+                    message: "Expected an absolute filesystem path on this host.",
+                },
+            ]));
+        if (input.record_ordinals !== undefined &&
+            new Set(input.record_ordinals).size !== input.record_ordinals.length)
+            return failure(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["record_ordinals"],
+                    reason: "invalid_format",
+                    message: "Each requested producer ordinal must occur once.",
+                },
+            ]));
+        const loaded = await this.port.inspect(input, options);
+        if (!loaded.ok)
+            return failure(loaded.error);
+        if (options?.signal?.aborted)
+            return failure(new AnalysisCancelledError(OPERATION));
+        const report = webNetworkCaptureSchema.safeParse(loaded.value);
+        if (!report.success)
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter returned malformed historical evidence."));
+        const value = report.data;
+        const artifactSha256 = value.artifact.sha256;
+        if (artifactSha256 === null)
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter omitted its observed artifact digest before explicit projection."));
+        if (value.artifact.path !== input.capture_path ||
+            value.format !== input.format ||
+            value.total_records !== value.records.length ||
+            value.records.some((record, index) => record.ordinal !== index))
+            return failure(new AnalysisOutputError(OPERATION, "Capture adapter changed the selected artifact, format or original record sequence."));
+        const safeValue = excludeCaptureCoordinates(value, input.sensitive_values);
+        const redactText = (text) => redactExplicitText(text, input.sensitive_values);
+        const selected = input.record_ordinals ?? value.records.map(({ ordinal }) => ordinal);
+        const records = [];
+        for (const ordinal of selected) {
+            const record = safeValue.records[ordinal];
+            if (record === undefined)
+                return failure(new AnalysisInputError(OPERATION, undefined, [
+                    {
+                        path: ["record_ordinals"],
+                        reason: "invalid_format",
+                        message: `Producer ordinal ${ordinal} is outside the retained capture (${value.total_records} records).`,
+                    },
+                ]));
+            records.push({
+                ...record,
+                limitations: record.limitations.map(redactText),
+            });
+        }
+        const safePath = input.sensitive_values.some((literal) => input.capture_path.includes(literal))
+            ? ""
+            : input.capture_path;
+        const safeSha256 = input.sensitive_values.some((literal) => artifactSha256.includes(literal))
+            ? null
+            : artifactSha256;
+        const subjectUnavailableReason = redactText("The explicitly sensitive artifact digest is excluded; its cryptographic identity is unknown in this Evidence.");
+        const limitations = [
+            ...safeValue.limitations,
+            ...(safePath === ""
+                ? [
+                    "The explicitly sensitive artifact path is excluded; its size remains available.",
+                ]
+                : []),
+        ].map(redactText);
+        const parameters = jsonObjectSchema.parse({
+            capture_path: safePath,
+            ...(input.sensitive_values.some((literal) => input.format.includes(literal))
+                ? {}
+                : { format: input.format }),
+            record_ordinals: selected,
+            sensitive_value_count: input.sensitive_values.length,
+        });
+        return ok(createEvidence(safeSha256 === null
+            ? undefined
+            : {
+                path: safePath,
+                sha256: safeSha256,
+                format: "file",
+            }, value.decoder, {
+            operation: OPERATION,
+            parameters,
+            result: {
+                ...safeValue,
+                artifact: { ...value.artifact, path: safePath, sha256: safeSha256 },
+                records,
+                limitations: safeSha256 === null
+                    ? [...limitations, subjectUnavailableReason]
+                    : limitations,
+            },
+            confidence: "observed",
+            authority: "historical-reference",
+            limitations,
+            ...(safeSha256 === null ? { subjectUnavailableReason } : {}),
+            locations: safePath === "" ? [] : [{ kind: "artifact-path", path: safePath }],
+        }));
+    }
+}

package/dist/application/WebRuntimeService.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { err, ok } from "../domain/result.js";
 import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
 import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
@@ -69,5 +69,7 @@ const parseInput = (schema, rawInput, operation, options) => {
     const parsed = schema.safeParse(rawInput);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(operation, parsed.error.issues, rawInput, {
+            cause: parsed.error,
+        }));
 };

package/dist/application/WebScriptExportService.js

@@ -7,7 +7,7 @@ import { publishWebScripts } from "../browser/assets/PublishWebScripts.js";
 import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
@@ -21,7 +21,7 @@ export const exportWebScripts = async (rawInput, options = {}) => {
     const input = exportWebScriptsInputSchema.safeParse(rawInput);
     return input.success
         ? exportWebScriptsValidated(input.data, options)
-        : err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(input.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput));
 };
 /** Publish input already parsed by a named adapter contract. */
 export const exportWebScriptsValidated = async (input, options = {}) => {

package/dist/application/WebSourceLocationService.js

@@ -3,7 +3,7 @@ import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { selectedWebScriptArtifactsSchema, webArtifactFileSchema, } from "../domain/webScriptArtifacts.js";
@@ -41,7 +41,9 @@ export class WebSourceLocationService {
             return err(new AnalysisCancelledError(OPERATION));
         const parsed = webSourceLocationInputSchema.safeParse(rawInput);
         if (!parsed.success)
-            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+            return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         const admitted = admitContext(input);
         if (!admitted.ok)

package/dist/application/WindowsCapabilities.js

@@ -3,7 +3,7 @@ import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { windowsNativeCapabilities, } from "../process/WindowsAuthority.js";
-import { probeProcessCaptureCapability, } from "./ProcessCaptureCapability.js";
+import { probeProcessCaptureCapability, } from "../process/capture/ProcessCaptureCapability.js";
 /** Probe named prerequisites without converting missing controls into support. */
 export const probeWindowsCapabilities = async (dependencies = systemDependencies()) => {
     const [symlinkCreation, pty] = await Promise.all([

package/dist/application/WorkflowEvidence.js

@@ -0,0 +1,82 @@
+import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
+import { analysisProfileSchema, committedProviderSchema, } from "../domain/analysisProfile.js";
+import { createEvidence } from "../domain/evidence.js";
+import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
+/** Build the shared Evidence record for a successful composed binary workflow. */
+export const createWorkflowEvidence = (input) => createEvidence(input.target, REA_WORKFLOW_PROVIDER, {
+    operation: input.operation,
+    parameters: input.parameters,
+    result: input.result,
+    ...(input.upstreamProfile === undefined
+        ? {}
+        : {
+            analysisProfile: workflowAnalysisProfile(input.upstreamProfile, input.operation),
+        }),
+    confidence: "derived",
+    limitations: ["Derived by an REA composed workflow."],
+});
+/** Convert workflow Evidence into its exact replay binding, when it has a profile. */
+export const workflowSnapshotRecord = (evidence, operation) => {
+    if (!("analysis_profile" in evidence))
+        return undefined;
+    return {
+        operation,
+        parameters: evidence.parameters,
+        execution: {
+            result: evidence.normalized_result,
+            rawResult: evidence.raw_result,
+            provider: committedProviderSchema.parse(evidence.provider),
+            analysisProfile: analysisProfileSchema.parse(evidence.analysis_profile),
+            limitations: evidence.limitations,
+            locations: evidence.locations,
+            subject: evidence.subject === null
+                ? null
+                : {
+                    path: evidence.subject.local_path,
+                    sha256: evidence.subject.digest.sha256,
+                    format: evidence.subject.format,
+                    ...(evidence.subject.architecture === null
+                        ? {}
+                        : { architecture: evidence.subject.architecture }),
+                },
+        },
+    };
+};
+/** Retain residual workflow questions using the shared investigation policy. */
+export const recordWorkflowUnknowns = ({ name, result, evidenceId, recordUnknown, }) => {
+    if (!["trace_feature", "trace_call_path", "inspect_native_api"].includes(name) ||
+        recordUnknown === undefined ||
+        typeof result !== "object" ||
+        result === null ||
+        Array.isArray(result) ||
+        !Array.isArray(result.residual_unknowns))
+        return { ok: true, value: null };
+    for (const question of result.residual_unknowns) {
+        if (typeof question !== "string")
+            continue;
+        const recorded = recordUnknown({
+            question,
+            severity: "medium",
+            domain: name === "inspect_native_api" ? "native-api" : "control-flow",
+            supporting_evidence_ids: [evidenceId],
+            contradicting_evidence_ids: [],
+            required_authority: "shipped-artifact",
+            required_confidence: "observed",
+            required_environment: null,
+            recommended_probes: [
+                {
+                    operation: name,
+                    rationale: name === "inspect_native_api"
+                        ? "Confirm the unsupported boundary with a capable provider or ABI probe."
+                        : "Continue with a focused query or another available provider.",
+                },
+            ],
+            relationships: [],
+        });
+        if (!recorded.ok &&
+            !(recorded.error instanceof UnknownRegistryError &&
+                recorded.error.reason === "already-exists"))
+            return recorded;
+    }
+    return { ok: true, value: null };
+};

package/dist/application/binary/AnalysisProviderEvaluation.js

@@ -1,5 +1,5 @@
 import { analysisProfileSchema, } from "../../domain/analysisProfile.js";
-import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisUnsupportedTargetError, } from "../../domain/analysisErrorCore.js";
 import { jsonObjectSchema } from "../../domain/jsonValue.js";
 import { err, ok } from "../../domain/result.js";
 import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
@@ -22,10 +22,26 @@ export const evaluateAnalysisProviderCandidate = async (candidate, status, targe
         return err(new AnalysisCancelledError("open_binary"));
     if (!resolved.ok && resolved.error instanceof AnalysisCancelledError)
         return err(resolved.error);
-    if (!resolved.ok)
-        return ok(rejectedProfile(candidate, status, resolved.error.message, {
-            error_tag: resolved.error._tag,
-        }));
+    if (!resolved.ok) {
+        const error = resolved.error;
+        const rejection = error instanceof AnalysisUnsupportedTargetError
+            ? {
+                candidate,
+                status: {
+                    ...status,
+                    targetSupport: {
+                        status: "unsupported",
+                        code: "target_format_unsupported",
+                        reason: error.reason,
+                        diagnostics: { path: error.path, error_tag: error._tag },
+                    },
+                },
+            }
+            : rejectedProfile(candidate, status, error.message, {
+                error_tag: error._tag,
+            });
+        return ok({ ...rejection, profileError: error });
+    }
     try {
         if (resolved.value.profile === null)
             return ok(rejectedProfile(candidate, status, "Provider version or analysis profile could not be resolved"));

package/dist/application/binary/AnalysisProviderRegistry.js

@@ -114,6 +114,8 @@ export class AnalysisProviderRegistry {
         if (!evaluation.ok)
             return evaluation;
         const evaluated = evaluation.value;
+        if (evaluated.profileError !== undefined)
+            return err(evaluated.profileError);
         const statuses = replaceCandidate(baseline, evaluated.status);
         if (evaluated.profile === undefined ||
             evaluated.compatibility === undefined)

package/dist/application/binary/AnalysisSnapshotCache.js

@@ -1,8 +1,8 @@
-import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import { EvidenceIntegrityError, AnalysisSnapshotMismatchError, } from "../../domain/evidenceErrors.js";
 import { NoBinaryOpenError } from "../../domain/configurationErrors.js";
 import {} from "../../domain/analysisErrorBase.js";
 import { err, ok } from "../../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, createAnalysisSnapshotWorkflowEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../../domain/analysisSnapshot.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../../contracts/officialToolContracts.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
@@ -11,7 +11,6 @@ const STATEFUL_OPERATIONS = new Set([
     "current_document",
     "goto_address",
     "list_documents",
-    "set_current_document",
 ]);
 const CURSOR_DEFAULT_OPERATIONS = new Set([
     "address_name",
@@ -21,9 +20,9 @@ const CURSOR_DEFAULT_OPERATIONS = new Set([
     "prev_address",
     "xrefs",
 ]);
-const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
-    name !== "list_documents" &&
-    name !== "set_current_document"));
+const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" && name !== "list_documents"));
+/** Maximum duplicated result bindings retained across direct and workflow queries. */
+export const SNAPSHOT_CACHE_ENTRY_CEILING = 10_000;
 /** Whether an operation is immutable and independent of provider UI state. */
 export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATEFUL_OPERATIONS.has(operation) &&
     (!DOCUMENT_SCOPED_OPERATIONS.has(operation) ||
@@ -37,6 +36,7 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
 /** Bounded in-memory cache for one immutable binary identity. */
 export class AnalysisSnapshotCache {
     #entries = new Map();
+    #workflowEntries = new Map();
     #target;
     #binding;
     /** Whether staged entries belong to the supplied target and profile. */
@@ -51,7 +51,7 @@ export class AnalysisSnapshotCache {
     /** Replace cache state when the target or selected profile changes. */
     select(target, profile) {
         if (!this.matches(target, profile))
-            this.#entries.clear();
+            this.#clearEntries();
         this.#target = snapshotTarget(target);
         this.#binding = snapshotBinding(profile);
     }
@@ -61,15 +61,22 @@ export class AnalysisSnapshotCache {
             JSON.stringify(this.#target) !== JSON.stringify(snapshot.target)) ||
             (this.#binding !== undefined &&
                 !snapshotMatchesProfile(this.#binding, snapshot.binding.analysis_profile)))
-            this.#entries.clear();
+            this.#clearEntries();
         this.#target = structuredClone(snapshot.target);
         this.#binding = structuredClone(snapshot.binding);
         let imported = 0;
         for (const entry of snapshot.entries) {
+            if (!this.#entries.has(entry.query_id) && !this.#hasCapacity())
+                continue;
             if (!this.#entries.has(entry.query_id))
                 imported += 1;
             this.#entries.set(entry.query_id, structuredClone(entry));
         }
+        for (const entry of snapshot.workflow_entries ?? []) {
+            if (!this.#workflowEntries.has(entry.query_id) && !this.#hasCapacity())
+                continue;
+            this.#workflowEntries.set(entry.query_id, structuredClone(entry));
+        }
         return imported;
     }
     /** Build a complete snapshot for an active target. */
@@ -84,6 +91,9 @@ export class AnalysisSnapshotCache {
                 target: snapshotTargetIdentity,
                 binding,
                 entries: this.entries(),
+                ...(this.workflowEntries().length === 0
+                    ? {}
+                    : { workflow_entries: this.workflowEntries() }),
                 evidence_bundle: retainedEvidence,
             }));
         }
@@ -107,7 +117,7 @@ export class AnalysisSnapshotCache {
         if (active !== undefined &&
             (!snapshotMatchesTarget(validated.target, active.target) ||
                 !snapshotMatchesProfile(validated.binding, active.profile)))
-            return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the active binary"));
+            return err(new AnalysisSnapshotMismatchError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the active binary"));
         const importedEvidence = mergeEvidence(validated.evidence_bundle);
         return importedEvidence.ok ? ok(this.stage(validated)) : importedEvidence;
     }
@@ -117,6 +127,27 @@ export class AnalysisSnapshotCache {
             .sort((left, right) => left.query_id.localeCompare(right.query_id))
             .map((entry) => structuredClone(entry));
     }
+    /** Return canonical composed-workflow entries for persistence. */
+    workflowEntries() {
+        return [...this.#workflowEntries.values()]
+            .sort((left, right) => left.query_id.localeCompare(right.query_id))
+            .map((entry) => structuredClone(entry));
+    }
+    /** Record one exact derived workflow result unless the shared cache is full. */
+    recordWorkflow(input) {
+        this.select(input.target, input.profile);
+        const queryId = analysisQueryId(snapshotTarget(input.target), snapshotBinding(input.profile), input.operation, input.parameters);
+        if (!this.#workflowEntries.has(queryId) && !this.#hasCapacity())
+            return;
+        const entry = createAnalysisSnapshotWorkflowEntry({
+            target: snapshotTarget(input.target),
+            binding: snapshotBinding(input.profile),
+            operation: input.operation,
+            parameters: input.parameters,
+            execution: input.execution,
+        });
+        this.#workflowEntries.set(entry.query_id, entry);
+    }
     /** Replay an exact provider-specific query, marking its cached provenance. */
     lookup(target, profile, operation, parameters) {
         const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
@@ -153,9 +184,10 @@ export class AnalysisSnapshotCache {
     /** Record one successful immutable call unless the cache is full. */
     record(input) {
         const { target, profile, operation, parameters, execution } = input;
-        if (this.#entries.size >= 10_000)
-            return;
         this.select(target, profile);
+        const queryId = analysisQueryId(snapshotTarget(target), snapshotBinding(profile), operation, parameters);
+        if (!this.#entries.has(queryId) && !this.#hasCapacity())
+            return;
         const entry = createAnalysisSnapshotEntry({
             target: snapshotTarget(target),
             binding: snapshotBinding(profile),
@@ -167,8 +199,16 @@ export class AnalysisSnapshotCache {
     }
     /** Forget all target-bound entries. */
     clear() {
-        this.#entries.clear();
+        this.#clearEntries();
         this.#target = undefined;
         this.#binding = undefined;
     }
+    #clearEntries() {
+        this.#entries.clear();
+        this.#workflowEntries.clear();
+    }
+    #hasCapacity() {
+        return (this.#entries.size + this.#workflowEntries.size <
+            SNAPSHOT_CACHE_ENTRY_CEILING);
+    }
 }