rea-agents 0.3.0 → 0.5.0

package/dist/server/registerInvestigationTools.js

@@ -0,0 +1,224 @@
+import { buildCallPath, callPathInputSchema } from "../domain/callPath.js";
+import { correlateStaticAndRuntime, staticRuntimeCorrelationInputSchema, } from "../domain/staticRuntimeCorrelation.js";
+import { reconstructionVerificationInputSchema, verifyReconstruction, } from "../domain/reconstructionVerification.js";
+import { changedBehaviorInputSchema, findChangedBehavior, } from "../domain/changedBehavior.js";
+import { createEvidence } from "../domain/evidence.js";
+import { EvidenceIntegrityError } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, RECONSTRUCTION_PROVIDER, STATIC_RUNTIME_PROVIDER, } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+/** Register Evidence-composed differential investigation workflows. */
+export const registerInvestigationTools = (server, session, contracts) => {
+    registerChangedBehavior(server, session, contracts[0]);
+    registerCallPath(server, session, contracts[1]);
+    registerStaticRuntime(server, session, contracts[2]);
+    registerReconstruction(server, session, contracts[3]);
+};
+const registerChangedBehavior = (server, session, contract) => {
+    server.registerTool(contract.name, contractOptions(contract), (input) => {
+        const parsed = changedBehaviorInputSchema.parse(input);
+        const closure = evidenceClosure(session, comparisonClosure(parsed.comparisons));
+        if (!closure.ok)
+            return toCallToolResult(closure, contract);
+        const links = closure.value;
+        const result = findChangedBehavior(parsed.comparisons, parsed.offset, parsed.limit);
+        const evidence = createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
+            predicateType: "rea.changed-behavior/v1",
+            operation: contract.name,
+            parameters: {
+                comparison_evidence_ids: parsed.comparisons.map(({ evidence_id: id }) => id),
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(result),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: result.limitations,
+            evidenceLinks: links,
+        });
+        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.behavior_status === "unknown" ||
+            result.behavior_status === "truncated", {
+            question: `Changed behavior result ${evidence.evidence_id} remains ${result.behavior_status}`,
+            domain: "changed-behavior",
+            requiredAuthority: "controlled-replay",
+            requiredConfidence: "observed",
+            probes: [
+                {
+                    operation: "capture_process_scenario",
+                    rationale: "Capture both versions under the same bounded scenario and environment.",
+                },
+            ],
+        });
+        return toCallToolResult(recorded, contract);
+    });
+};
+const registerCallPath = (server, session, contract) => {
+    server.registerTool(contract.name, contractOptions(contract), (input) => {
+        const parsed = callPathInputSchema.parse(input);
+        const closure = evidenceClosure(session, functionEvidenceIds(parsed.functions));
+        if (!closure.ok)
+            return toCallToolResult(closure, contract);
+        const links = closure.value;
+        const result = buildCallPath(parsed);
+        const evidence = createEvidence(undefined, CALL_PATH_PROVIDER, {
+            predicateType: "rea.call-path/v1",
+            operation: contract.name,
+            parameters: {
+                start: parsed.start.address,
+                goal: parsed.goal.address,
+                max_depth: parsed.max_depth,
+                max_paths: parsed.max_paths,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(result),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: result.limitations,
+            evidenceLinks: links,
+        });
+        const recorded = recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
+            question: `Call path ${parsed.start.address} → ${parsed.goal.address} is ${result.status}`,
+            domain: "call-path",
+            requiredAuthority: "shipped-artifact",
+            requiredConfidence: "derived",
+            probes: [
+                {
+                    operation: "analyze_function",
+                    rationale: "Collect complete callee dossiers for the reported frontier addresses.",
+                },
+            ],
+        });
+        return toCallToolResult(recorded, contract);
+    });
+};
+const registerStaticRuntime = (server, session, contract) => {
+    server.registerTool(contract.name, contractOptions(contract), (input) => {
+        const parsed = staticRuntimeCorrelationInputSchema.parse(input);
+        const closure = evidenceClosure(session, comparisonClosure([
+            ...parsed.static_comparisons,
+            ...parsed.runtime_comparisons,
+        ]));
+        if (!closure.ok)
+            return toCallToolResult(closure, contract);
+        const links = closure.value;
+        const result = correlateStaticAndRuntime(parsed);
+        const evidence = createEvidence(undefined, STATIC_RUNTIME_PROVIDER, {
+            predicateType: "rea.static-runtime-correlation/v1",
+            operation: contract.name,
+            parameters: {
+                mapping_count: parsed.mappings.length,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(result),
+            confidence: "inferred",
+            authority: "analyst-inference",
+            limitations: result.limitations,
+            evidenceLinks: links,
+        });
+        return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown" || result.status === "truncated", {
+            question: `Static/runtime correlation result ${evidence.evidence_id} is ${result.status}`,
+            domain: "static-runtime-correlation",
+            requiredAuthority: null,
+            requiredConfidence: "derived",
+            probes: [
+                {
+                    operation: "capture_process_scenario",
+                    rationale: "Repeat runtime observations and complete the mapped static comparison Evidence.",
+                },
+            ],
+        }), contract);
+    });
+};
+const registerReconstruction = (server, session, contract) => {
+    server.registerTool(contract.name, contractOptions(contract), (input) => {
+        const parsed = reconstructionVerificationInputSchema.parse(input);
+        const owned = session.exportEvidenceBundle();
+        const ownedUnknowns = new Set(owned.unknowns.map(({ revision_digest: digest }) => digest));
+        const ownedEvidenceIds = new Set(owned.records.map(({ evidence_id: id }) => id));
+        if (parsed.evidence_bundle.records.some(({ evidence_id: id }) => !ownedEvidenceIds.has(id)) ||
+            parsed.evidence_bundle.unknowns.some(({ revision_digest: digest }) => !ownedUnknowns.has(digest)))
+            return toCallToolResult(err(new EvidenceIntegrityError("Reconstruction input unknown history is not present in this session")), contract);
+        const result = verifyReconstruction(parsed.specification, owned, parsed.offset, parsed.limit);
+        const closure = evidenceClosure(session, result.evidence_links);
+        if (!closure.ok)
+            return toCallToolResult(closure, contract);
+        const links = closure.value;
+        const evidence = createEvidence(undefined, RECONSTRUCTION_PROVIDER, {
+            predicateType: "rea.reconstruction-verification/v1",
+            operation: contract.name,
+            parameters: {
+                specification_sha256: result.specification_sha256,
+                claim_ids: parsed.specification.claims.map(({ claim_id: id }) => id),
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(result),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: result.limitations,
+            evidenceLinks: links,
+        });
+        return toCallToolResult(recordWorkflowEvidence(session, evidence, parsed.unknown_registry_approved, result.status === "unknown", {
+            question: `Reconstruction ${result.specification_sha256} has unknown claims`,
+            domain: "reconstruction-verification",
+            requiredAuthority: null,
+            requiredConfidence: "derived",
+            probes: result.recommended_probes.map(({ operation, rationale }) => ({
+                operation,
+                rationale,
+            })),
+        }), contract);
+    });
+};
+const contractOptions = (contract) => ({
+    description: contract.description,
+    inputSchema: contract.inputSchema,
+    outputSchema: contract.outputSchema,
+    annotations: contract.annotations,
+});
+const comparisonClosure = (comparisons) => uniqueIds(comparisons.flatMap((evidence) => [
+    evidence.evidence_id,
+    ...evidence.evidence_links,
+]));
+const functionEvidenceIds = (groups) => uniqueIds(groups.flatMap((group) => (Array.isArray(group) ? group : [group]).map(({ evidence_id: id }) => id)));
+const uniqueIds = (ids) => [...new Set(ids)].sort((left, right) => left.localeCompare(right));
+const evidenceClosure = (session, seedIds) => {
+    const records = new Map(session
+        .exportEvidenceBundle()
+        .records.map((evidence) => [evidence.evidence_id, evidence]));
+    const visited = new Set();
+    const pending = [...seedIds];
+    while (pending.length > 0) {
+        const evidenceId = pending.pop();
+        if (evidenceId === undefined || visited.has(evidenceId))
+            continue;
+        const evidence = records.get(evidenceId);
+        if (evidence === undefined)
+            return err(new EvidenceIntegrityError("Investigation input has a dangling Evidence link"));
+        visited.add(evidenceId);
+        pending.push(...evidence.evidence_links);
+    }
+    return ok(uniqueIds([...visited]));
+};
+const recordWorkflowEvidence = (...[session, evidence, approved, unresolved, input]) => {
+    if (approved !== true || !unresolved) {
+        return recordDerivedEvidence(session, evidence, undefined);
+    }
+    return recordDerivedEvidence(session, evidence, {
+        approved: true,
+        question: input.question,
+        severity: "high",
+        domain: input.domain,
+        supporting_evidence_ids: [evidence.evidence_id],
+        contradicting_evidence_ids: [],
+        required_authority: input.requiredAuthority,
+        required_confidence: input.requiredConfidence,
+        required_environment: null,
+        recommended_probes: [...input.probes],
+        relationships: [],
+    });
+};

package/dist/server/registerNativeTools.js

@@ -0,0 +1,6 @@
+import { NATIVE_TOOL_CONTRACTS } from "../contracts/nativeToolContracts.js";
+import { registerEvidenceTools } from "./registerEvidenceTools.js";
+/** Register provider-neutral static inspection operations. */
+export const registerNativeTools = (server, analysis, options) => {
+    registerEvidenceTools(server, analysis, NATIVE_TOOL_CONTRACTS, options);
+};

package/dist/server/registerOfficialTools.js

@@ -1,20 +1,17 @@
-import { OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
 import { createEvidence } from "../domain/evidence.js";
+import { AnalysisCapabilityUnavailableError, UnknownRegistryError, } from "../domain/errors.js";
 /** Register direct bridge proxies, preserving MCP cancellation and typed errors. */
-export const registerOfficialTools = (server, analysis, logger, activeTarget, provider = {
-    id: "unidentified",
-    name: "Unidentified provider",
-    version: null,
-}, recordEvidence) => {
+export const registerOfficialTools = (server, analysis, options) => {
     for (const contract of OFFICIAL_TOOL_CONTRACTS) {
         registerOfficialTool(server, analysis, contract, {
-            logger,
-            activeTarget,
-            provider,
-            recordEvidence,
+            logger: options.logger,
+            activeTarget: options.activeTarget,
+            recordEvidence: options.recordEvidence,
+            recordUnknown: options.recordUnknown,
         });
     }
 };
@@ -30,15 +27,45 @@ const registerOfficialTool = (server, analysis, contract, registration) => {
             signal: context.mcpReq.signal,
         }));
         if (result.ok) {
-            const evidence = createEvidence(registration.activeTarget?.(), registration.provider, {
+            const evidence = createEvidence(result.value.subject ?? registration.activeTarget?.(), result.value.provider, {
                 operation: contract.name,
                 parameters: arguments_,
-                result: result.value,
-                redactedRawPayload: result.value,
+                result: result.value.result,
+                rawResult: result.value.rawResult,
+                limitations: result.value.limitations,
+                locations: result.value.locations,
             });
-            registration.recordEvidence?.(evidence);
+            const recorded = registration.recordEvidence?.(evidence);
+            if (recorded !== undefined && !recorded.ok)
+                return toCallToolResult(recorded, contract);
             return toCallToolResult({ ok: true, value: evidence }, contract);
         }
+        if (result.error instanceof AnalysisCapabilityUnavailableError &&
+            approvedUnknownTracking(input) &&
+            registration.recordUnknown !== undefined) {
+            const unknown = registration.recordUnknown({
+                approved: true,
+                question: `${contract.name} is unavailable: ${result.error.reason}`,
+                severity: "medium",
+                domain: "provider-capability",
+                supporting_evidence_ids: [],
+                contradicting_evidence_ids: [],
+                required_authority: "shipped-artifact",
+                required_confidence: "observed",
+                required_environment: null,
+                recommended_probes: [
+                    {
+                        operation: contract.name,
+                        rationale: "Use a provider that declares this capability available.",
+                    },
+                ],
+                relationships: [],
+            });
+            if (!unknown.ok &&
+                !(unknown.error instanceof UnknownRegistryError &&
+                    unknown.error.reason === "already-exists"))
+                return toCallToolResult(unknown, contract);
+        }
         return toCallToolResult(result, contract);
     });
 };
@@ -53,7 +80,13 @@ const projectOfficialArguments = (contract, input) => {
     }
     const projected = {};
     for (const key of Object.keys(contract.inputSchema.shape)) {
+        if (key === "unknown_registry_approved")
+            continue;
         projected[key] = parsed.data[key] ?? null;
     }
     return projected;
 };
+const approvedUnknownTracking = (input) => typeof input === "object" &&
+    input !== null &&
+    "unknown_registry_approved" in input &&
+    input.unknown_registry_approved === true;

package/dist/server/registerProcessComparisonTool.js

@@ -0,0 +1,106 @@
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { createEvidence } from "../domain/evidence.js";
+import { EvidenceIntegrityError } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { compareProcessCaptures, processCaptureSchema, } from "../domain/processCapture.js";
+import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+import { err } from "../domain/result.js";
+import { PROCESS_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register deterministic process-capture comparison and contradiction tracking. */
+export const registerProcessComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = z
+            .object({
+            left_evidence_id: z.string(),
+            left: processCaptureSchema,
+            right_evidence_id: z.string(),
+            right: processCaptureSchema,
+            unknown_registry_approved: z.literal(true).optional(),
+        })
+            .parse(input);
+        const validated = validateCaptureSources(session, parsed);
+        if (!validated.ok)
+            return toCallToolResult(validated, contract);
+        const comparison = compareProcessCaptures(parsed.left, parsed.right);
+        const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
+            predicateType: "rea.process-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_evidence_id: parsed.left_evidence_id,
+                right_evidence_id: parsed.right_evidence_id,
+                left_normalization: parsed.left.normalization,
+                right_normalization: parsed.right.normalization,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
+        });
+        return toCallToolResult(recordDerivedEvidence(session, evidence, comparisonUnknownInput(parsed, comparison)), contract);
+    });
+};
+const validateCaptureSources = (session, parsed) => {
+    for (const [evidenceId, capture] of [
+        [parsed.left_evidence_id, parsed.left],
+        [parsed.right_evidence_id, parsed.right],
+    ]) {
+        const evidence = session.evidenceById(evidenceId);
+        const result = processCaptureSchema.safeParse(evidence?.normalized_result);
+        if (evidence === undefined ||
+            evidence.operation !== "capture_process_scenario" ||
+            evidence.predicate_type !== "rea.process-capture/v2" ||
+            evidence.provider.id !== PROCESS_PROVIDER.id ||
+            evidence.provider.name !== PROCESS_PROVIDER.name ||
+            evidence.provider.version !== PROCESS_PROVIDER.version ||
+            evidence.confidence !== "observed" ||
+            evidence.authority !== "controlled-replay" ||
+            !result.success ||
+            canonicalJson(result.data) !== canonicalJson(capture))
+            return err(new EvidenceIntegrityError("Process comparison payload does not match its source Evidence"));
+    }
+    return { ok: true, value: null };
+};
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Process capture could not be canonicalized");
+    return encoded;
+};
+const comparisonUnknownInput = (parsed, comparison) => {
+    if (parsed.unknown_registry_approved !== true ||
+        comparison.status === "unchanged")
+        return undefined;
+    const differingScopes = [
+        ["terminal", comparison.terminal],
+        ["exit", comparison.exit],
+        ["filesystem", comparison.filesystem],
+        ["protocol", comparison.protocol],
+        ["process", comparison.process],
+    ]
+        .filter(([, status]) => status !== "unchanged")
+        .map(([scope]) => scope)
+        .join(", ");
+    return {
+        approved: true,
+        question: `Process captures disagree across: ${differingScopes}`,
+        severity: "high",
+        domain: "process-comparison",
+        supporting_evidence_ids: [parsed.left_evidence_id],
+        contradicting_evidence_ids: [parsed.right_evidence_id],
+        required_authority: "controlled-replay",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            {
+                operation: "capture_process_scenario",
+                rationale: "Repeat both scenarios under the same controlled environment.",
+            },
+        ],
+        relationships: [],
+    };
+};