rea-agents 2.4.0 → 3.0.0

package/dist/application/CallPathTracing.js

@@ -0,0 +1,160 @@
+import { projectAnalysisError } from "../domain/errors.js";
+import { parseRelatedAddresses } from "../domain/hopperValues.js";
+import { ok } from "../domain/result.js";
+/** Trace one deterministic bounded direct caller/callee path. */
+export const traceCallPath = async (call, input, signal) => {
+    const state = createTraceState(input);
+    while (state.queueIndex < state.queue.length &&
+        state.traversalPath.length === 0) {
+        const address = state.queue[state.queueIndex++];
+        if (address === undefined)
+            break;
+        const current = state.visited.get(address);
+        if (current === undefined)
+            continue;
+        if (current.depth >= input.max_depth) {
+            state.frontier.add(address);
+            state.residual.add("Call-path traversal reached the depth limit.");
+            continue;
+        }
+        if (state.operations >= input.max_operations) {
+            recordPendingFrontier(state, input);
+            state.residual.add("Call-path traversal reached the operation budget.");
+            break;
+        }
+        state.operations += 1;
+        const found = await expandAddress(call, {
+            input,
+            state,
+            address,
+            current,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (found)
+            break;
+    }
+    return ok(projectTrace(input, state));
+};
+const createTraceState = (input) => ({
+    visited: new Map([[input.start, { depth: 0, path: [input.start] }]]),
+    queue: [input.start],
+    edges: new Map(),
+    failures: [],
+    frontier: new Set(),
+    residual: new Set(),
+    operations: 0,
+    queueIndex: 0,
+    traversalPath: input.goal === input.start ? [input.start] : [],
+});
+const expandAddress = async (call, expansion) => {
+    const { input, state, address, current, signal } = expansion;
+    const relation = input.direction === "forward" ? "callees" : "callers";
+    const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
+    const result = await call(tool, { procedure: address }, signal);
+    if (!result.ok) {
+        state.failures.push({
+            address,
+            error: projectAnalysisError(result.error),
+        });
+        state.residual.add(`Call relationships were unavailable for ${address}.`);
+        return false;
+    }
+    const related = parseRelatedAddresses(result.value, relation);
+    if (!related.ok) {
+        state.failures.push({
+            address,
+            error: projectAnalysisError(related.error),
+        });
+        state.residual.add(`Call relationships were unreadable for ${address}.`);
+        return false;
+    }
+    for (const relatedAddress of sortedUniqueAddresses(related.value)) {
+        recordEdge(input, state, {
+            address,
+            relatedAddress,
+            discoveryDepth: current.depth + 1,
+        });
+        const path = state.visited.get(relatedAddress)?.path ?? [
+            ...current.path,
+            relatedAddress,
+        ];
+        if (state.visited.has(relatedAddress)) {
+            if (relatedAddress === input.goal) {
+                state.traversalPath = path;
+                return true;
+            }
+            continue;
+        }
+        if (state.visited.size >= input.max_nodes) {
+            if (state.frontier.size < input.max_nodes)
+                state.frontier.add(relatedAddress);
+            state.residual.add("Call-path traversal reached the node limit.");
+            continue;
+        }
+        state.visited.set(relatedAddress, {
+            depth: current.depth + 1,
+            path,
+        });
+        if (relatedAddress === input.goal) {
+            state.traversalPath = path;
+            return true;
+        }
+        state.queue.push(relatedAddress);
+    }
+    return false;
+};
+const recordEdge = (input, state, edge) => {
+    const sourceAddress = input.direction === "forward" ? edge.address : edge.relatedAddress;
+    const targetAddress = input.direction === "forward" ? edge.relatedAddress : edge.address;
+    const edgeKey = `${sourceAddress}\u0000${targetAddress}`;
+    if (state.edges.has(edgeKey))
+        return;
+    if (state.edges.size >= input.max_nodes) {
+        state.residual.add("Call-path traversal reached the edge limit.");
+        return;
+    }
+    state.edges.set(edgeKey, {
+        source_address: sourceAddress,
+        target_address: targetAddress,
+        discovery_depth: edge.discoveryDepth,
+    });
+};
+const recordPendingFrontier = (state, input) => {
+    for (const pending of state.queue.slice(state.queueIndex - 1))
+        if (state.frontier.size < input.max_nodes)
+            state.frontier.add(pending);
+};
+const projectTrace = (input, state) => ({
+    start: input.start,
+    goal: input.goal ?? null,
+    direction: input.direction,
+    goal_status: input.goal === undefined
+        ? "not_requested"
+        : state.traversalPath.length > 0
+            ? "reached"
+            : "not_reached",
+    nodes: [...state.visited.entries()]
+        .map(([address, { depth }]) => ({ address, depth }))
+        .sort((left, right) => left.depth - right.depth || compareAddress(left.address, right.address)),
+    edges: [...state.edges.values()].sort((left, right) => left.discovery_depth - right.discovery_depth ||
+        compareAddress(left.source_address, right.source_address) ||
+        compareAddress(left.target_address, right.target_address)),
+    traversal_path: state.traversalPath,
+    failures: state.failures,
+    frontier: [...state.frontier].sort(compareAddress),
+    limits: {
+        max_depth: input.max_depth,
+        max_nodes: input.max_nodes,
+        max_operations: input.max_operations,
+        nodes_visited: state.visited.size,
+        operations_used: state.operations,
+    },
+    truncated: state.residual.size > 0,
+    residual_unknowns: [...state.residual],
+    limitations: [
+        "Direct provider call relationships may omit unresolved indirect calls.",
+        "A not_reached goal is only absent from this bounded traversal, not from the complete program.",
+    ],
+});
+const compareAddress = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const sortedUniqueAddresses = (addresses) => [...new Set(addresses)].sort(compareAddress);

package/dist/application/CapabilityInventory.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 const statusSchema = z.object({
     open: z.boolean(),
     kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),
@@ -11,6 +11,18 @@ const statusSchema = z.object({
         availability_code: z.string().nullable().optional(),
     })),
 });
+const NO_CLIENT_FEATURES = {
+    elicitation_form: false,
+    elicitation_url: false,
+    roots: false,
+    sampling: false,
+};
+const CLIENT_FEATURE_REQUIREMENTS = {
+    capture_process_scenario: {
+        required: [],
+        optional: ["elicitation_form"],
+    },
+};
 const ENHANCED_REQUIREMENTS = {
     swift_classes: ["list_procedures"],
     get_objc_classes: ["list_names"],
@@ -26,6 +38,7 @@ const ENHANCED_REQUIREMENTS = {
         "list_strings",
     ],
     analyze_function: ["analyze_function"],
+    inspect_native_api: ["analyze_function"],
     trace_feature: [
         "list_strings",
         "list_procedures",
@@ -33,8 +46,15 @@ const ENHANCED_REQUIREMENTS = {
         "resolve_containing_procedure",
     ],
 };
-/** Build stable per-operation availability without hiding familiar tools. */
-export const buildCapabilityInventory = (sessionStatus, policy) => {
+const SESSION_COMPOSITION_REQUIREMENTS = {
+    get_navigation_context: [
+        "current_document",
+        "current_address",
+        "resolve_containing_procedure",
+    ],
+};
+/** Build stable per-operation availability for discovery and tool visibility. */
+export const buildCapabilityInventory = (sessionStatus, policy, clientFeatures = NO_CLIENT_FEATURES) => {
     const status = statusSchema.parse(sessionStatus);
     const descriptors = new Map(status.capabilities.map((descriptor) => [
         descriptor.operation,
@@ -44,7 +64,7 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
             availability_code: descriptor.availability_code ?? null,
         },
     ]));
-    return TOOL_CONTRACTS.map((contract) => {
+    return GENERATED_MCP_TOOL_CATALOG.map((contract) => {
         const availability = availabilityFor({
             name: contract.name,
             kind: contract.kind,
@@ -53,12 +73,19 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
             descriptors,
             policy,
         });
+        const clientRequirements = clientRequirementsFor(contract.name, clientFeatures);
+        const clientBlocked = clientRequirements.missing_required.length > 0;
         return {
             name: contract.name,
             surface: contract.kind,
-            available: availability.reason === "available",
-            reason: availability.reason,
-            remediation: availability.remediation,
+            available: availability.reason === "available" && !clientBlocked,
+            reason: clientBlocked
+                ? "client_capability_missing"
+                : availability.reason,
+            remediation: clientBlocked
+                ? `Use an MCP client that supports: ${clientRequirements.missing_required.join(", ")}.`
+                : availability.remediation,
+            client_requirements: clientRequirements,
             effects: { ...contract.effects },
             annotations: {
                 read_only: contract.annotations.readOnlyHint ?? false,
@@ -69,7 +96,22 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
         };
     }).sort((left, right) => left.name.localeCompare(right.name));
 };
+const clientRequirementsFor = (name, clientFeatures) => {
+    const requirements = CLIENT_FEATURE_REQUIREMENTS[name] ?? {
+        required: [],
+        optional: [],
+    };
+    return {
+        required: [...requirements.required],
+        optional: [...requirements.optional],
+        missing_required: requirements.required.filter((feature) => !clientFeatures[feature]),
+        missing_optional: requirements.optional.filter((feature) => !clientFeatures[feature]),
+    };
+};
 const availabilityFor = (context) => {
+    const sessionComposition = SESSION_COMPOSITION_REQUIREMENTS[context.name];
+    if (sessionComposition !== undefined)
+        return composedAvailabilityFor(sessionComposition, context.descriptors);
     const javascriptApplication = javascriptApplicationAvailability(context);
     if (javascriptApplication !== null)
         return javascriptApplication;
@@ -94,6 +136,9 @@ const javascriptApplicationAvailability = ({ name, policy, }) => {
         : null;
 };
 const policyAvailability = ({ name, kind, policy, }) => {
+    const browser = browserPolicyAvailability(name, kind, policy);
+    if (browser !== null)
+        return browser;
     if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
         return {
             reason: "policy_disabled",
@@ -121,26 +166,43 @@ const policyAvailability = ({ name, kind, policy, }) => {
             reason: "policy_disabled",
             remediation: "Configure or grant an evidence_read root.",
         };
-    if (kind === "browser-provider")
-        return policy.browserObservationEnabled === true
+    if (kind === "electron-provider")
+        return policy.electronObservationEnabled === true
             ? { reason: "available", remediation: null }
             : {
                 reason: "policy_disabled",
-                remediation: "Enable browser observation and configure exact CDP endpoint and page origins.",
+                remediation: "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.",
             };
-    if (kind === "electron-provider")
-        return policy.electronObservationEnabled === true
+    if (kind === "runtime-provider")
+        return policy.v8InspectorObservationEnabled === true
             ? { reason: "available", remediation: null }
             : {
                 reason: "policy_disabled",
-                remediation: "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.",
+                remediation: "Enable V8 Inspector observation and configure exact loopback endpoints plus canonical file roots or exact origins.",
             };
     if (kind === "session")
         return { reason: "available", remediation: null };
     return null;
 };
+const browserPolicyAvailability = (name, kind, policy) => {
+    if (name === "capture_browser_scenario")
+        return policy.browserScenarioEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "policy_disabled",
+                remediation: "Enable browser scenarios and configure exact executable roots or loopback CDP endpoints, page origins, and environment secret names.",
+            };
+    if (kind !== "browser-provider")
+        return null;
+    return policy.browserObservationEnabled === true
+        ? { reason: "available", remediation: null }
+        : {
+            reason: "policy_disabled",
+            remediation: "Enable browser observation and configure exact CDP endpoint and page origins.",
+        };
+};
 const targetAvailability = ({ kind, targetKind, targetOpen, }) => {
-    if (!targetOpen)
+    if (!targetOpen && (kind === "official-proxy" || kind === "enhanced"))
         return {
             reason: "target_required",
             remediation: "Call open_binary with a supported local target.",
@@ -159,6 +221,11 @@ const providerAvailability = ({ descriptors, kind, name, }) => {
     if (kind === "enhanced")
         return composedAvailability(name, descriptors);
     const descriptor = descriptors.get(name);
+    if (descriptor === undefined &&
+        (kind === "artifact-provider" ||
+            kind === "managed-provider" ||
+            kind === "native-provider"))
+        return { reason: "available", remediation: null };
     if (descriptor === undefined)
         return {
             reason: "provider_missing",
@@ -184,6 +251,9 @@ const composedAvailability = (name, descriptors) => {
             reason: "provider_missing",
             remediation: "No provider composition is declared for this operation.",
         };
+    return composedAvailabilityFor(requirements, descriptors);
+};
+const composedAvailabilityFor = (requirements, descriptors) => {
     const missing = requirements.find((operation) => !descriptors.has(operation));
     if (missing !== undefined)
         return {

package/dist/application/ClientRegistrationStatus.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { supportedClients } from "./SupportedClients.js";
 const objectSchema = z.record(z.string(), z.unknown());
 const registrationSchema = z
@@ -41,7 +42,9 @@ export const readClientRegistrationStatuses = async (home, currentCommandPath =
 };
 const registrationAligned = (registration, client, currentCommandPath) => {
     const command = [registration.command, ...registration.args];
-    if (client === "codex" && registration.startup_timeout_sec !== 30)
+    if (client === "codex" &&
+        registration.startup_timeout_sec !==
+            MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)
         return false;
     if (command.length === 4 &&
         command[0] === "npx" &&

package/dist/application/CompositeProvider.js

@@ -1,5 +1,6 @@
 import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
 /** Synthetic compatibility identity for a deterministic provider set. */
 export const compositeProviderIdentity = (identities) => ({
     id: `composite:${identities
@@ -61,6 +62,10 @@ export class CompositeProvider {
             clients.set(provider, created);
             return created;
         };
+        const closeWithOutcome = async (options) => {
+            const outcomes = await Promise.all([...clients.entries()].map(([provider, client]) => closeAnalysisClient(client, provider.identity().id, options)));
+            return outcomes.find((outcome) => !outcome.ok) ?? ok(null);
+        };
         return {
             execute: (operation, parameters, options) => {
                 if (operation === "health")
@@ -80,8 +85,12 @@ export class CompositeProvider {
             runtimeLineageSnapshots: () => [...clients.values()]
                 .flatMap((client) => client.runtimeLineageSnapshots?.() ?? [])
                 .sort((left, right) => left.provider.id.localeCompare(right.provider.id)),
+            requestActivitySnapshots: () => [...clients.values()]
+                .flatMap((client) => client.requestActivitySnapshots?.() ?? [])
+                .sort((left, right) => left.provider.id.localeCompare(right.provider.id)),
+            closeWithOutcome,
             close: async () => {
-                await Promise.allSettled([...clients.values()].map(async (client) => client.close()));
+                await closeWithOutcome();
             },
         };
     }

package/dist/application/DirectAnalysis.js

@@ -12,6 +12,7 @@ import { err, ok } from "../domain/result.js";
 import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 import { authorizeFileReadWithDeferredWrite, } from "./DeferredFileAuthorization.js";
 import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
+import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 export { runCapabilityStatus, runProviderStatus, } from "./DirectAnalysisStatus.js";
 /**
  * Open one binary, execute one tool, and always release provider resources.
@@ -60,7 +61,7 @@ const authorizeAnalysis = async (authority, tool, arguments_) => {
                     cause: result.error,
                 }));
     }
-    if (tool === "inventory_artifact" &&
+    if (["inventory_artifact", "inspect_artifact"].includes(tool) &&
         arguments_.native_mount_approved === true) {
         const result = await authority.authorize({
             capability: "native_mount",
@@ -69,7 +70,7 @@ const authorizeAnalysis = async (authority, tool, arguments_) => {
             environment_names: [],
             network: "none",
             mount: true,
-            operation_identity: "inventory_artifact:native_mount",
+            operation_identity: `${tool}:native_mount`,
         }, "read");
         if (!result.ok)
             return err(result.error instanceof PermissionRequiredError
@@ -181,6 +182,7 @@ const executeAnalysisTool = async (input) => {
     const { session, tool, signal, evidenceProfile } = input;
     if (tool === "binary_overview" ||
         tool === "analyze_function" ||
+        tool === "inspect_native_api" ||
         tool === "trace_feature") {
         const result = await new EnhancedTools(session).execute(tool, input.arguments, signal);
         if (!result.ok)
@@ -212,6 +214,10 @@ const executeAnalysisTool = async (input) => {
         rawResult: result.value.rawResult,
         limitations: result.value.limitations,
         locations: result.value.locations,
+        evidenceLinks: tool === "inspect_artifact"
+            ? artifactInspectionResultSchema.parse(result.value.result)
+                .evidence_links
+            : [],
     });
     return { output: evidence, evidence };
 };
@@ -242,15 +248,18 @@ const prepareSnapshot = async (options) => {
         return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
     return ok({ snapshot: loaded.value });
 };
-const replayProviderFor = (session, tool) => tool === "binary_overview" || tool === "trace_feature"
+const replayProviderFor = (session, tool) => isWorkflowEvidenceTool(tool)
     ? REA_WORKFLOW_PROVIDER
     : session.providerIdentity(tool);
 const analysisProfileForEvidence = (session, tool) => {
-    if (tool !== "binary_overview" && tool !== "trace_feature")
+    if (!isWorkflowEvidenceTool(tool))
         return session.analysisProfile(tool);
     const upstream = session.analysisProfile();
     return upstream === undefined ? undefined : workflowAnalysisProfile(upstream);
 };
+const isWorkflowEvidenceTool = (tool) => tool === "binary_overview" ||
+    tool === "inspect_native_api" ||
+    tool === "trace_feature";
 const fileExists = async (path) => {
     try {
         await access(path);

package/dist/application/EnhancedLiteralTracing.js

@@ -0,0 +1,118 @@
+import { AnalysisOutputError } from "../domain/errors.js";
+import { parseAddressedPage } from "../domain/hopperValues.js";
+import { err, ok } from "../domain/result.js";
+const FEATURE_SEARCH_SOURCES = [
+    ["list_strings", "string"],
+    ["list_procedures", "procedure"],
+];
+const STRING_SEARCH_SOURCES = [
+    ["list_strings", "string"],
+];
+/** Trace a bounded feature or string literal through provider xrefs. */
+export const traceLiteralFeature = async (call, input, scope, signal) => {
+    const sources = scope === "feature" ? FEATURE_SEARCH_SOURCES : STRING_SEARCH_SOURCES;
+    const searched = await literalMatches(call, input, sources, signal);
+    if (!searched.ok)
+        return searched;
+    const residual = new Set();
+    const traced = await traceReferences(call, {
+        matches: searched.value.matches,
+        limit: input.limit,
+        operationBudget: input.max_operations - searched.value.operations,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (!traced.ok)
+        return traced;
+    for (const reason of traced.value.residual)
+        residual.add(reason);
+    const operations = searched.value.operations + traced.value.operations;
+    if (operations >= input.max_operations)
+        residual.add("Investigation reached the operation budget.");
+    if (searched.value.matches.length >= input.limit)
+        residual.add("Literal matches reached the configured limit.");
+    return ok({
+        query: input.query,
+        search_mode: "literal",
+        operations_used: operations,
+        operation_budget: input.max_operations,
+        matches: searched.value.matches,
+        references: traced.value.references,
+        truncated: residual.size > 0,
+        residual_unknowns: [...residual],
+    });
+};
+const literalMatches = async (call, input, sources, signal) => {
+    let operations = 0;
+    const matches = [];
+    const needle = input.case_sensitive ? input.query : input.query.toLowerCase();
+    for (const [tool, type] of sources) {
+        let offset = 0;
+        while (operations < input.max_operations && matches.length < input.limit) {
+            operations += 1;
+            const result = await call(tool, { offset, limit: 500 }, signal);
+            if (!result.ok)
+                return result;
+            const page = parseAddressedPage(result.value);
+            if (!page.ok)
+                return page;
+            for (const item of page.value.items) {
+                const haystack = input.case_sensitive
+                    ? item.name
+                    : item.name.toLowerCase();
+                if (haystack.includes(needle))
+                    matches.push({ type, address: item.address, value: item.name });
+                if (matches.length >= input.limit)
+                    break;
+            }
+            if (!page.value.hasMore || page.value.nextOffset === null)
+                break;
+            offset = page.value.nextOffset;
+        }
+    }
+    return ok({ matches, operations });
+};
+const traceReferences = async (call, request) => {
+    let operations = 0;
+    const references = [];
+    const residual = new Set();
+    for (const match of request.matches) {
+        if (operations >= request.operationBudget) {
+            residual.add("Reference traversal stopped at the operation budget.");
+            break;
+        }
+        operations += 1;
+        const xrefs = await call("xrefs", { address: match.address }, request.signal);
+        if (!xrefs.ok)
+            return xrefs;
+        if (!Array.isArray(xrefs.value))
+            return err(new AnalysisOutputError("xrefs", "provider returned a non-array result"));
+        for (const source of xrefs.value) {
+            if (typeof source !== "string")
+                return err(new AnalysisOutputError("xrefs", "provider returned a non-address value"));
+            if (operations >= request.operationBudget) {
+                residual.add("Containing-procedure resolution stopped at the operation budget.");
+                break;
+            }
+            operations += 1;
+            const resolved = await call("resolve_containing_procedure", { address: source }, request.signal);
+            if (!resolved.ok)
+                return resolved;
+            references.push({
+                target_address: match.address,
+                source_address: source,
+                containing_procedure: resolved.value,
+            });
+            if (references.length >= request.limit) {
+                residual.add("Reference results reached the configured limit.");
+                break;
+            }
+        }
+        if (references.length >= request.limit)
+            break;
+    }
+    return ok({
+        references,
+        operations,
+        residual: [...residual],
+    });
+};