rea-agents 0.3.0 → 0.5.0

package/dist/reference/ReferenceSourceReaderValidate.js

@@ -0,0 +1,71 @@
+import { constants } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { err, ok } from "../domain/result.js";
+import { cancelled, failure } from "./ReferenceSourceReaderErrors.js";
+import { withinRoot } from "./ReferenceSourceReaderPaths.js";
+import {} from "./ReferenceSourceReaderTypes.js";
+export const bigLstat = (path) => lstat(path, { bigint: true });
+export const sameFile = (left, right) => left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs;
+export const isAborted = (signal) => signal?.aborted === true;
+const validLimits = (limits) => Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0);
+export const noFollowOpenSupported = () => Number.isSafeInteger(constants.O_NOFOLLOW) && constants.O_NOFOLLOW !== 0;
+export const validateDirectory = async (root, rootIdentity, path) => {
+    try {
+        const rootNow = await bigLstat(root);
+        if (!sameFile(rootIdentity, rootNow))
+            return { ok: false, code: "changed", message: "Reference root changed" };
+        const stats = await bigLstat(path);
+        if (stats.isSymbolicLink())
+            return {
+                ok: false,
+                code: "symlink",
+                message: "Symbolic links are not followed",
+            };
+        if (!stats.isDirectory())
+            return {
+                ok: false,
+                code: "changed",
+                message: "Directory identity changed",
+            };
+        const canonical = await realpath(path);
+        if (canonical !== path || !withinRoot(root, canonical))
+            return {
+                ok: false,
+                code: "changed",
+                message: "Directory escaped the reference root",
+            };
+        return { ok: true, stats };
+    }
+    catch {
+        return {
+            ok: false,
+            code: "io",
+            message: "Directory identity could not be verified",
+        };
+    }
+};
+export const prepareRoot = async (root, limits, signal) => {
+    if (!validLimits(limits))
+        return err(failure("invalid-limits", "Reader limits must be positive integers"));
+    if (isAborted(signal))
+        return err(cancelled());
+    try {
+        const metadata = await bigLstat(root);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory())
+            return err(failure("invalid-root", "Reference source root must be a directory"));
+        const canonicalRoot = await realpath(root);
+        if (isAborted(signal))
+            return err(cancelled());
+        const canonicalMetadata = await bigLstat(canonicalRoot);
+        if (!sameFile(metadata, canonicalMetadata))
+            return err(failure("invalid-root", "Reference source root changed during resolution"));
+        return ok({ canonicalRoot, rootIdentity: canonicalMetadata });
+    }
+    catch {
+        return err(failure("invalid-root", "Reference source root could not be resolved"));
+    }
+};

package/dist/server/createServer.js

@@ -3,13 +3,16 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { registerEnhancedTools } from "./registerEnhancedTools.js";
 import { registerOfficialTools } from "./registerOfficialTools.js";
 import { registerSessionTools } from "./registerSessionTools.js";
+import { registerNativeTools } from "./registerNativeTools.js";
+import { registerArtifactTools } from "./registerArtifactTools.js";
 import { silentLogger } from "../logger.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
  * fixed-target seam used by focused tests and embedders.
  */
-export const createServer = (analysis, session, logger = silentLogger, processPolicy) => {
+export const createServer = (analysis, session, options = {}) => {
+    const logger = options.logger ?? silentLogger;
     const server = new McpServer({ name: PRODUCT_IDENTITY.mcpServerKey, version: "0.1.0" }, {
         capabilities: { tools: {} },
         instructions: session === undefined
@@ -18,13 +21,36 @@ export const createServer = (analysis, session, logger = silentLogger, processPo
     });
     const toolLogger = logger.child({ layer: "server" });
     const activeTarget = session === undefined ? undefined : () => session.activeTarget();
-    const provider = session?.providerIdentity();
     const recordEvidence = session === undefined
         ? undefined
         : (evidence) => session.recordEvidence(evidence);
-    registerOfficialTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
-    registerEnhancedTools(server, analysis, toolLogger, activeTarget, provider, recordEvidence);
+    registerOfficialTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+        recordUnknown: session === undefined
+            ? undefined
+            : (input) => session.recordUnknown(input),
+    });
+    registerEnhancedTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+        recordUnknown: session === undefined
+            ? undefined
+            : (input) => session.recordUnknown(input),
+    });
+    registerNativeTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+    });
+    registerArtifactTools(server, analysis, {
+        logger: toolLogger,
+        activeTarget,
+        recordEvidence,
+    });
     if (session !== undefined)
-        registerSessionTools(server, session, toolLogger, processPolicy);
+        registerSessionTools(server, session, toolLogger, options);
     return server;
 };

package/dist/server/recordDerivedEvidence.js

@@ -0,0 +1,10 @@
+import { ok } from "../domain/result.js";
+/** Atomically record derived Evidence with an optional approved unknown. */
+export const recordDerivedEvidence = (session, evidence, unknown) => {
+    if (unknown !== undefined) {
+        const recorded = session.recordEvidenceWithUnknown(evidence, unknown);
+        return recorded.ok ? ok(evidence) : recorded;
+    }
+    const recorded = session.recordEvidence(evidence);
+    return recorded.ok ? ok(evidence) : recorded;
+};

package/dist/server/registerArtifactComparisonTool.js

@@ -0,0 +1,62 @@
+import { artifactComparisonInputSchema, compareArtifacts, } from "../domain/artifactComparison.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+import { resolveSessionEvidence } from "./sessionEvidence.js";
+import { ARTIFACT_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register Evidence-backed deterministic artifact comparison. */
+export const registerArtifactComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = artifactComparisonInputSchema.parse(input);
+        const left = resolveSessionEvidence(session, parsed.left);
+        if (!left.ok)
+            return toCallToolResult(left, contract);
+        const right = resolveSessionEvidence(session, parsed.right);
+        if (!right.ok)
+            return toCallToolResult(right, contract);
+        const comparison = compareArtifacts(left.value, right.value, parsed.offset, parsed.limit);
+        const leftEvidenceIds = evidenceIds(parsed.left);
+        const rightEvidenceIds = evidenceIds(parsed.right);
+        const evidence = createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
+            predicateType: "rea.artifact-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_evidence_ids: leftEvidenceIds,
+                right_evidence_ids: rightEvidenceIds,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [...leftEvidenceIds, ...rightEvidenceIds],
+        });
+        return toCallToolResult(recordDerivedEvidence(session, evidence, artifactUnknownInput(parsed, comparison.status)), contract);
+    });
+};
+const artifactUnknownInput = (input, status) => {
+    if (input.unknown_registry_approved !== true || status === "unchanged")
+        return undefined;
+    return {
+        approved: true,
+        question: `Artifact comparison is ${status}`,
+        severity: status === "unknown" || status === "truncated" ? "high" : "medium",
+        domain: "artifact-comparison",
+        supporting_evidence_ids: evidenceIds(input.left),
+        contradicting_evidence_ids: evidenceIds(input.right),
+        required_authority: "shipped-artifact",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            {
+                operation: "inventory_artifact",
+                rationale: "Capture both complete artifact graphs under equal limits.",
+            },
+        ],
+        relationships: [],
+    };
+};
+const evidenceIds = (input) => (Array.isArray(input) ? input : [input]).map(({ evidence_id: id }) => id);

package/dist/server/registerArtifactTools.js

@@ -0,0 +1,6 @@
+import { ARTIFACT_TOOL_CONTRACTS } from "../contracts/artifactToolContracts.js";
+import { registerEvidenceTools } from "./registerEvidenceTools.js";
+/** Register deterministic artifact inventory and safe extraction operations. */
+export const registerArtifactTools = (server, analysis, options) => {
+    registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, options);
+};

package/dist/server/registerBundleComparisonTool.js

@@ -0,0 +1,47 @@
+import { bundleComparisonInputSchema, compareBundles, } from "../domain/bundleComparison.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 { BUNDLE_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { isSessionEvidence } from "./sessionEvidence.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register canonical Evidence bundle comparison. */
+export const registerBundleComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = bundleComparisonInputSchema.parse(input);
+        const sourceIds = [
+            ...new Set([
+                ...parsed.left.records.map(({ evidence_id: id }) => id),
+                ...parsed.right.records.map(({ evidence_id: id }) => id),
+            ]),
+        ].sort();
+        if ([...parsed.left.records, ...parsed.right.records].some((evidence) => !isSessionEvidence(session, evidence)))
+            return toCallToolResult(err(new EvidenceIntegrityError("Bundle comparison input Evidence is not present in this session")), contract);
+        const ownedUnknownDigests = new Set(session
+            .exportEvidenceBundle()
+            .unknowns.map(({ revision_digest: digest }) => digest));
+        if ([...parsed.left.unknowns, ...parsed.right.unknowns].some(({ revision_digest: digest }) => !ownedUnknownDigests.has(digest)))
+            return toCallToolResult(err(new EvidenceIntegrityError("Bundle comparison input unknown history is not present in this session")), contract);
+        const comparison = compareBundles(parsed.left, parsed.right, parsed.record_pairs, parsed.offset, parsed.limit);
+        const evidence = createEvidence(undefined, BUNDLE_COMPARISON_PROVIDER, {
+            predicateType: "rea.bundle-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_bundle_sha256: comparison.left_bundle_sha256,
+                right_bundle_sha256: comparison.right_bundle_sha256,
+                record_pairs: parsed.record_pairs,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: sourceIds,
+        });
+        const recorded = session.recordEvidence(evidence);
+        return toCallToolResult(recorded.ok ? ok(evidence) : recorded, contract);
+    });
+};

package/dist/server/registerEnhancedTools.js

@@ -6,19 +6,21 @@ import { logToolExecution } from "./toolLogging.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
+import { UnknownRegistryError } from "../domain/errors.js";
+const WORKFLOW_PROVIDER = {
+    id: "rea-workflow",
+    name: "REA composed investigation workflow",
+    version: "1",
+};
 /** Register composed workflows against the same port as direct bridge tools. */
-export const registerEnhancedTools = (server, analysis, logger, activeTarget, provider = {
-    id: "unidentified",
-    name: "Unidentified provider",
-    version: null,
-}, recordEvidence) => {
+export const registerEnhancedTools = (server, analysis, options) => {
     const services = new EnhancedTools(analysis);
     for (const contract of ENHANCED_TOOL_CONTRACTS) {
         registerEnhancedTool(server, services, contract, {
-            logger,
-            activeTarget,
-            provider,
-            recordEvidence,
+            logger: options.logger,
+            activeTarget: options.activeTarget,
+            recordEvidence: options.recordEvidence,
+            recordUnknown: options.recordUnknown,
         });
     }
 };
@@ -38,16 +40,66 @@ const registerEnhancedTool = (server, services, contract, registration) => {
         const parameters = { ...parsedInput };
         const result = await logToolExecution(registration.logger, name, () => services.execute(name, input, context.mcpReq.signal));
         if (result.ok) {
-            const evidence = createEvidence(registration.activeTarget?.(), registration.provider, {
+            const evidence = createEvidence(registration.activeTarget?.(), WORKFLOW_PROVIDER, {
                 operation: name,
                 parameters,
                 result: result.value,
                 confidence: "derived",
-                redactedRawPayload: result.value,
+                limitations: [
+                    "Derived by an REA workflow from one or more provider observations.",
+                ],
+            });
+            const recorded = registration.recordEvidence?.(evidence);
+            if (recorded !== undefined && !recorded.ok)
+                return toCallToolResult(recorded, contract);
+            const unknowns = recordWorkflowUnknowns({
+                name,
+                input: parsedInput,
+                result: result.value,
+                evidenceId: evidence.evidence_id,
+                recordUnknown: registration.recordUnknown,
             });
-            registration.recordEvidence?.(evidence);
+            if (!unknowns.ok)
+                return toCallToolResult(unknowns, contract);
             return toCallToolResult({ ok: true, value: evidence }, contract);
         }
         return toCallToolResult(result, contract);
     });
 };
+const recordWorkflowUnknowns = ({ name, input, result, evidenceId, recordUnknown, }) => {
+    if (name !== "trace_feature" ||
+        input.unknown_registry_approved !== true ||
+        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({
+            approved: true,
+            question,
+            severity: "medium",
+            domain: "control-flow",
+            supporting_evidence_ids: [evidenceId],
+            contradicting_evidence_ids: [],
+            required_authority: "shipped-artifact",
+            required_confidence: "observed",
+            required_environment: null,
+            recommended_probes: [
+                {
+                    operation: "trace_feature",
+                    rationale: "Continue with a larger bounded budget.",
+                },
+            ],
+            relationships: [],
+        });
+        if (!recorded.ok &&
+            !(recorded.error instanceof UnknownRegistryError &&
+                recorded.error.reason === "already-exists"))
+            return recorded;
+    }
+    return { ok: true, value: null };
+};

package/dist/server/registerEvidenceTools.js

@@ -0,0 +1,36 @@
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register provider-backed contracts that return atomic Evidence v2 observations. */
+export const registerEvidenceTools = (server, analysis, contracts, options) => {
+    for (const contract of contracts) {
+        server.registerTool(contract.name, toolRegistrationOptions(contract), async (input, context) => {
+            const parameters = jsonObject(contract.inputSchema.parse(input));
+            const execution = await logToolExecution(options.logger, contract.name, () => analysis.execute(contract.name, parameters, {
+                signal: context.mcpReq.signal,
+            }));
+            if (!execution.ok)
+                return toCallToolResult(execution, contract);
+            const evidence = createEvidence(execution.value.subject ?? options.activeTarget?.(), execution.value.provider, {
+                operation: contract.name,
+                parameters,
+                result: execution.value.result,
+                rawResult: execution.value.rawResult,
+                limitations: execution.value.limitations,
+                locations: execution.value.locations,
+            });
+            const recorded = options.recordEvidence?.(evidence);
+            return recorded !== undefined && !recorded.ok
+                ? toCallToolResult(recorded, contract)
+                : toCallToolResult({ ok: true, value: evidence }, contract);
+        });
+    }
+};
+const jsonObject = (input) => {
+    const parsed = jsonValueSchema.parse(input);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new TypeError("Provider tool input was not an object");
+    return parsed;
+};

package/dist/server/registerFunctionComparisonTool.js

@@ -0,0 +1,68 @@
+import { compareFunctions, functionComparisonInputSchema, } from "../domain/functionComparison.js";
+import { createEvidence } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { FUNCTION_COMPARISON_PROVIDER } from "./sessionToolPolicies.js";
+import { toCallToolResult } from "./toolResult.js";
+import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
+import { resolveSessionEvidence } from "./sessionEvidence.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+/** Register explicit Evidence-backed function comparison. */
+export const registerFunctionComparisonTool = (server, session, contract) => {
+    server.registerTool(contract.name, toolRegistrationOptions(contract), (input) => {
+        const parsed = functionComparisonInputSchema.parse(input);
+        const left = resolveSessionEvidence(session, parsed.left);
+        if (!left.ok)
+            return toCallToolResult(left, contract);
+        const right = resolveSessionEvidence(session, parsed.right);
+        if (!right.ok)
+            return toCallToolResult(right, contract);
+        const leftIds = evidenceIds(left.value);
+        const rightIds = evidenceIds(right.value);
+        const comparison = compareFunctions(left.value, right.value, parsed.offset, parsed.limit);
+        const evidence = createEvidence(undefined, FUNCTION_COMPARISON_PROVIDER, {
+            predicateType: "rea.function-comparison/v1",
+            operation: contract.name,
+            parameters: {
+                left_evidence_ids: leftIds,
+                right_evidence_ids: rightIds,
+                offset: parsed.offset,
+                limit: parsed.limit,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [...leftIds, ...rightIds],
+        });
+        const recorded = recordDerivedEvidence(session, evidence, functionUnknownInput({
+            approved: parsed.unknown_registry_approved,
+            status: comparison.status,
+            leftIds,
+            rightIds,
+        }));
+        return toCallToolResult(recorded, contract);
+    });
+};
+const functionUnknownInput = ({ approved, status, leftIds, rightIds, }) => {
+    if (approved !== true || status === "unchanged")
+        return undefined;
+    return {
+        approved: true,
+        question: `Function comparison is ${status}`,
+        severity: status === "changed" ? "medium" : "high",
+        domain: "function-comparison",
+        supporting_evidence_ids: [...leftIds],
+        contradicting_evidence_ids: [...rightIds],
+        required_authority: "shipped-artifact",
+        required_confidence: "observed",
+        required_environment: null,
+        recommended_probes: [
+            {
+                operation: "analyze_function",
+                rationale: "Capture complete dossiers with equal providers and analysis limits.",
+            },
+        ],
+        relationships: [],
+    };
+};
+const evidenceIds = (input) => (Array.isArray(input) ? input : [input]).map(({ evidence_id: id }) => id);