rea-agents 6.0.0 → 6.2.0

package/dist/application/XrefsAddressResolution.js

@@ -0,0 +1,45 @@
+import { addressedValue } from "../contracts/toolOutputSchemaPrimitives.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
+/** Resolve a CLI symbol selector without changing existing address spellings. */
+export const resolveXrefsAddress = async (analysis, selector, signal) => {
+    if (selector.length === 0 ||
+        /^[0-9a-f]+$/iu.test(selector) ||
+        /^0x/iu.test(selector) ||
+        /:0x/iu.test(selector))
+        return ok(selector);
+    const inventory = await analysis.execute("list_names", {}, { signal });
+    if (!inventory.ok) {
+        if (inventory.error instanceof AnalysisCapabilityUnavailableError &&
+            inventory.error.operation === "list_names" &&
+            !inventory.error.cleanupIncomplete)
+            return resolveProcedureAddress(async (operation, parameters, signal) => {
+                const result = await analysis.execute(operation, parameters, signal === undefined ? {} : { signal });
+                return result.ok ? ok(result.value.result) : result;
+            }, selector, signal);
+        return inventory;
+    }
+    if (!Array.isArray(inventory.value.result))
+        return err(new AnalysisOutputError("list_names", "Expected a symbol inventory array"));
+    const addresses = new Set();
+    for (const [index, item] of inventory.value.result.entries()) {
+        const parsed = addressedValue.safeParse(item);
+        if (!parsed.success || parsed.data.address.length === 0)
+            return err(new AnalysisOutputError("list_names", `Invalid symbol inventory entry at index ${index}`));
+        if (parsed.data.value === selector)
+            addresses.add(parsed.data.address);
+    }
+    const [address] = addresses;
+    if (addresses.size === 1 && address !== undefined)
+        return ok(address);
+    return err(new AnalysisInputError("xrefs", undefined, [
+        {
+            path: ["address"],
+            reason: "invalid_value",
+            message: addresses.size === 0
+                ? `Unknown analyzed symbol name ${JSON.stringify(selector)}. Use an exact analyzed name or a hexadecimal address.`
+                : `Analyzed symbol name ${JSON.stringify(selector)} is ambiguous at ${[...addresses].join(", ")}. Select an exact address.`,
+        },
+    ]));
+};

package/dist/application/analysisView/AnalysisViewService.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { ANALYSIS_VIEW_PROVIDER } from "../InvestigationProviders.js";
+import { resolveEvidenceInput } from "../EvidenceInputResolver.js";
+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
+import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
+import { createEvidence, parseEvidence, } from "../../domain/evidence.js";
+import { INSPECT_ANALYSIS_VIEW_OPERATION, inspectAnalysisViewInputSchema, projectAnalysisView, } from "../../domain/analysisView/analysisView.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { err, ok } from "../../domain/result.js";
+/** Authenticate a selected-view request and project already completed Evidence. */
+export const inspectAnalysisView = (rawInput, lookup) => {
+    const parsed = inspectAnalysisViewInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, parsed.error.issues, rawInput, { cause: parsed.error }));
+    return inspectAnalysisViewValidated(parsed.data, lookup);
+};
+/** Project a view from input already parsed by a trusted adapter. */
+export const inspectAnalysisViewValidated = (input, lookup) => {
+    const resolved = resolveAnalysisViewSource(input.source, lookup);
+    if (!resolved.ok)
+        return resolved;
+    const parent = resolved.value;
+    const projected = projectAnalysisView({
+        evidenceId: parent.evidence_id,
+        operation: parent.operation,
+        normalizedResult: parent.normalized_result,
+        limitations: parent.limitations,
+    }, input.view);
+    if (!projected.ok)
+        return projected;
+    if (parent.subject !== null &&
+        parent.subject.digest.sha256 !== projected.value.artifact.sha256)
+        return err(new EvidenceIntegrityError(`Parent subject SHA-256 ${parent.subject.digest.sha256} differs from analysis artifact SHA-256 ${projected.value.artifact.sha256}.`));
+    return ok(createAnalysisViewEvidence(input, parent, projected.value));
+};
+const resolveAnalysisViewSource = (source, lookup) => {
+    if (source.kind === "retained-evidence")
+        return resolveEvidenceInput(source, lookup);
+    try {
+        return ok(parseEvidence(source.evidence));
+    }
+    catch (cause) {
+        if (cause instanceof z.ZodError)
+            return err(analysisInputErrorFromIssues(INSPECT_ANALYSIS_VIEW_OPERATION, cause.issues, source.evidence, { cause }));
+        if (cause instanceof TypeError)
+            return err(new EvidenceIntegrityError(cause.message, cause.message.length > 0 ? { userMessage: cause.message } : undefined));
+        throw cause;
+    }
+};
+const createAnalysisViewEvidence = (input, parent, result) => {
+    const target = parent.subject === null
+        ? undefined
+        : {
+            path: parent.subject.local_path,
+            sha256: parent.subject.digest.sha256,
+            format: parent.subject.format,
+            ...(parent.subject.architecture === null
+                ? {}
+                : { architecture: parent.subject.architecture }),
+        };
+    return createEvidence(target, ANALYSIS_VIEW_PROVIDER, {
+        predicateType: "rea.analysis-view",
+        operation: INSPECT_ANALYSIS_VIEW_OPERATION,
+        parameters: {
+            parent_evidence_id: parent.evidence_id,
+            view: jsonValueSchema.parse(input.view),
+        },
+        result: jsonValueSchema.parse(result),
+        rawResult: null,
+        confidence: "derived",
+        authority: parent.authority,
+        limitations: result.limitations,
+        locations: [{ kind: "artifact-path", path: result.artifact.path }],
+        evidenceLinks: [parent.evidence_id],
+    });
+};

package/dist/application/binary/AnalysisClientCleanup.js

@@ -1,14 +1,39 @@
 import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
-import { err, ok } from "../../domain/result.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
+import { err } from "../../domain/result.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
 /** Close one provider client and normalize unexpected adapter rejection. */
 export const closeAnalysisClient = async (client, providerId, options = {}) => {
     try {
-        if (client.closeWithOutcome !== undefined)
-            return await client.closeWithOutcome(options);
-        await client.close();
-        return ok(null);
+        return await client.close(options);
     }
     catch (cause) {
+        // A typed cleanup failure already names its leftover resources.
+        if (cause instanceof AnalysisError && cause.cleanupIncomplete)
+            return err(cause);
         return err(new ProviderCleanupError(providerId, ["provider-client"], { reason: "provider client close rejected unexpectedly" }, { cause }));
     }
 };
+/** Preserve the original lifecycle failure alongside incomplete cleanup. */
+export const analysisErrorWithCleanupFailure = (primary, cleanup, operation = "close_binary") => {
+    const projected = projectAnalysisError(cleanup);
+    return new ProviderAdapterError(cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea", operation, {
+        cause: primary,
+        userMessage: projectAnalysisError(primary).message,
+        ...(primary.capturedOutput === undefined
+            ? {}
+            : { capturedOutput: primary.capturedOutput }),
+        ...(primary.partialObservation === undefined
+            ? {}
+            : { partialObservation: primary.partialObservation }),
+        cleanup: {
+            reason: projected.message,
+            resources: cleanup.cleanupResources,
+        },
+        diagnostics: {
+            primary_error: projectAnalysisError(primary),
+            cleanup_error: projected,
+        },
+    });
+};

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,22 +22,37 @@ 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"));
         const profile = analysisProfileSchema.parse(resolved.value.profile);
-        const compatibility = jsonObjectSchema.parse(resolved.value.compatibility);
         const identity = candidate.identity();
         if (profile.provider.id !== identity.id ||
             profile.provider.name !== identity.name ||
             (identity.version !== null &&
                 profile.provider.version !== identity.version))
             return ok(rejectedProfile(candidate, status, "Resolved analysis profile has mismatched provider identity"));
-        return ok({ candidate, status, profile, compatibility });
+        return ok({ candidate, status, profile });
     }
     catch (cause) {
         void cause;

package/dist/application/binary/AnalysisProviderRegistry.js

@@ -114,14 +114,14 @@ 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)
+        if (evaluated.profile === undefined)
             return err(selectionError("provider_unavailable", providerId, statuses));
         return ok(selectedResult(providerId, source, {
             ...evaluated,
             profile: evaluated.profile,
-            compatibility: evaluated.compatibility,
         }, statuses));
     }
     async #selectAutomatically(context) {
@@ -147,8 +147,7 @@ export class AnalysisProviderRegistry {
             return result.value;
         });
         const statuses = evaluations.map(({ status }) => status);
-        const usable = evaluations.filter((evaluation) => evaluation.profile !== undefined &&
-            evaluation.compatibility !== undefined);
+        const usable = evaluations.filter((evaluation) => evaluation.profile !== undefined);
         if (usable.length === 0)
             return ok({
                 requestedProviderId: "auto",
@@ -193,7 +192,6 @@ const selectedResult = (requestedProviderId, source, evaluated, statuses) => {
             identity: structuredClone(evaluated.profile.provider),
             selectionSource: source,
             profile: structuredClone(evaluated.profile),
-            compatibility: structuredClone(evaluated.compatibility),
         },
         candidates: replaceCandidate(statuses, selectedStatus),
     };

package/dist/application/binary/AnalysisSnapshotCache.js

@@ -1,4 +1,4 @@
-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";
@@ -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,7 @@ 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. */
@@ -34,7 +31,8 @@ export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATE
         typeof parameters.address === "string") &&
     descriptor?.effects.mutatesArtifact === false &&
     descriptor.cachePolicy !== "live" &&
-    descriptor.effects.mayWriteFilesystem === false &&
+    (descriptor.cachePolicy === "snapshot" ||
+        descriptor.effects.mayWriteFilesystem === false) &&
     descriptor.effects.changesPermissions === false;
 /** Bounded in-memory cache for one immutable binary identity. */
 export class AnalysisSnapshotCache {
@@ -75,7 +73,7 @@ export class AnalysisSnapshotCache {
                 imported += 1;
             this.#entries.set(entry.query_id, structuredClone(entry));
         }
-        for (const entry of snapshot.workflow_entries ?? []) {
+        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));
@@ -89,15 +87,16 @@ export class AnalysisSnapshotCache {
         try {
             const snapshotTargetIdentity = snapshotTarget(target);
             const binding = snapshotBinding(profile);
-            const retainedEvidence = structuredClone(evidenceBundle);
+            const entries = [...this.#entries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+            const workflows = [...this.#workflowEntries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+            // Parsing owns the returned JSON and metadata; pre-cloning the same
+            // payloads here only adds another full materialization.
             return ok(parseAnalysisSnapshot({
                 target: snapshotTargetIdentity,
                 binding,
-                entries: this.entries(),
-                ...(this.workflowEntries().length === 0
-                    ? {}
-                    : { workflow_entries: this.workflowEntries() }),
-                evidence_bundle: retainedEvidence,
+                entries,
+                workflow_entries: workflows,
+                evidence_bundle: evidenceBundle,
             }));
         }
         catch (cause) {
@@ -120,7 +119,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;
     }