rea-agents 2.4.0 → 2.5.0

package/dist/application/BrowserScenarioCaptureService.js

@@ -0,0 +1,53 @@
+import { createBrowserScenarioEvidence } from "./BrowserScenarioEvidence.js";
+import { digestJson } from "./JavaScriptReplayPlanning.js";
+import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
+import { err } from "../domain/result.js";
+const OPERATION = "capture_browser_scenario";
+const PROVIDER_ID = "rea-playwright-browser-scenario";
+const networkScope = (origins) => origins.every((origin) => isLiteralLoopbackHostname(new URL(origin).hostname))
+    ? "loopback"
+    : "external";
+const authorizeScenario = async (authority, scenario) => {
+    if (authority === undefined)
+        return err(new AnalysisCapabilityUnavailableError(PROVIDER_ID, OPERATION, "browser scenario permission policy is not configured"));
+    const authorized = await authority.authorize({
+        capability: "browser_automate",
+        roots: [],
+        executables: scenario.browser.mode === "launch"
+            ? [scenario.browser.executable_path]
+            : [],
+        environment_names: scenario.secrets.map(({ environment_variable: name }) => name),
+        origins: [
+            ...(scenario.browser.mode === "connect"
+                ? [scenario.browser.cdp_endpoint]
+                : []),
+            ...scenario.allowed_origins,
+        ],
+        network: networkScope(scenario.allowed_origins),
+        mount: false,
+        operation_identity: `${OPERATION}:${digestJson(scenario)}`,
+    }, "write");
+    if (!authorized.ok)
+        return err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+    return { ok: true, value: true };
+};
+/** Authorize and execute one controlled browser scenario. */
+export const captureBrowserScenario = async (provider, authority, scenario, options = {}) => {
+    const authorized = await authorizeScenario(authority, scenario);
+    if (!authorized.ok)
+        return authorized;
+    if (provider === undefined)
+        return err(new AnalysisCapabilityUnavailableError(PROVIDER_ID, OPERATION, "browser scenario provider is not configured"));
+    const captured = await provider.captureScenario(scenario, options);
+    return captured.ok
+        ? {
+            ok: true,
+            value: createBrowserScenarioEvidence(scenario, captured.value, provider.identity()),
+        }
+        : captured;
+};

package/dist/application/BrowserScenarioEvidence.js

@@ -0,0 +1,40 @@
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { digestJson } from "./JavaScriptReplayPlanning.js";
+const browserScenarioParameters = (scenario) => ({
+    scenario_sha256: digestJson(scenario),
+    browser_mode: scenario.browser.mode,
+    start_url: sanitizeBrowserUrl(scenario.start_url.url),
+    allowed_origins: scenario.allowed_origins,
+    actions: scenario.actions.map(({ step_id, action }) => ({
+        step_id,
+        action,
+    })),
+    secret_declarations: scenario.secrets.map(({ secret_id, environment_variable, purpose, redaction }) => ({
+        secret_id,
+        environment_variable,
+        purpose,
+        redaction,
+    })),
+    capture: scenario.capture,
+    limits: scenario.limits,
+});
+/** Create Evidence v2 without retaining resolved scenario secret values. */
+export const createBrowserScenarioEvidence = (scenario, capture, provider) => createEvidence(undefined, provider, {
+    predicateType: "rea.browser-scenario-capture/v1",
+    operation: "capture_browser_scenario",
+    parameters: browserScenarioParameters(scenario),
+    result: jsonValueSchema.parse(capture),
+    confidence: "observed",
+    authority: "controlled-replay",
+    environment: {
+        id: `${capture.browser.product}@${capture.browser.version}`,
+        platform: process.platform,
+        architecture: process.arch,
+        isolation: capture.browser.process_ownership === "provider-owned"
+            ? "process"
+            : "none",
+    },
+    limitations: capture.limitations,
+});

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

@@ -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"],
@@ -33,8 +45,8 @@ const ENHANCED_REQUIREMENTS = {
         "resolve_containing_procedure",
     ],
 };
-/** Build stable per-operation availability without hiding familiar tools. */
-export const buildCapabilityInventory = (sessionStatus, policy) => {
+/** 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,
@@ -53,12 +65,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,6 +88,18 @@ 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 javascriptApplication = javascriptApplicationAvailability(context);
     if (javascriptApplication !== null)
@@ -94,6 +125,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 +155,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 +210,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",

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
@@ -212,6 +213,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 };
 };

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],
+    });
+};