rea-agents 2.3.0 → 2.5.0

package/dist/application/BinarySessionStatus.js

@@ -1,5 +1,5 @@
 /** Project internal provider routing state into the caller-visible session status. */
-export const binarySessionStatus = ({ target, route, router, runtimeAvailability, runId, runtimeLineageSnapshots, }) => {
+export const binarySessionStatus = ({ target, route, router, runtimeAvailability, runId, runtimeLineageSnapshots, requestActivitySnapshots, }) => {
     const configuredProvider = router.configuredIdentity();
     const provider = providerSummary(configuredProvider);
     const providers = router.providerIdentities(route).map(providerSummary);
@@ -41,6 +41,7 @@ export const binarySessionStatus = ({ target, route, router, runtimeAvailability
                 run_id: runId,
                 process_lineage: processLineageStatus(runtimeLineageSnapshots),
             },
+        analysis_activity: requestActivityStatus(requestActivitySnapshots),
     };
     return target === undefined
         ? { open: false, ...common }
@@ -54,6 +55,35 @@ export const binarySessionStatus = ({ target, route, router, runtimeAvailability
             architecture: target.architecture ?? null,
         };
 };
+const requestActivityStatus = (snapshots) => {
+    const providers = snapshots
+        .slice()
+        .sort((left, right) => left.provider.id.localeCompare(right.provider.id))
+        .map(({ provider, active, queuedRequests }) => ({
+        provider: providerSummary(provider),
+        active: active === null
+            ? null
+            : {
+                request_id: active.requestId,
+                operation: active.operation,
+                elapsed_ms: active.elapsedMs,
+                timeout_ms: active.timeoutMs,
+                caller_state: active.callerState,
+            },
+        queued_requests: queuedRequests,
+    }));
+    const active = snapshots.flatMap((snapshot) => snapshot.active === null ? [] : [snapshot.active]);
+    return {
+        status: snapshots.length === 0
+            ? "not_observed"
+            : active.some(({ callerState }) => callerState === "timed_out")
+                ? "timed_out_busy"
+                : active.length > 0
+                    ? "busy"
+                    : "idle",
+        providers,
+    };
+};
 const providerSummary = ({ id, name, version, }) => ({ id, name, version });
 const processLineageStatus = (snapshots) => snapshots.length === 0
     ? { status: "not_observed" }
@@ -91,6 +121,7 @@ const capabilityStatus = (descriptor) => ({
     operation: descriptor.operation,
     available: descriptor.available,
     reason: descriptor.reason,
+    availability_code: descriptor.availabilityCode ?? null,
     input_contract_version: descriptor.inputContractVersion,
     output_contract_version: descriptor.outputContractVersion,
     pagination: descriptor.pagination,

package/dist/application/BrowserEvidence.js

@@ -1,5 +1,6 @@
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { commitBrowserScenarioNormalization } from "../domain/browserScenarioNormalization.js";
 /** Create Evidence v2 for a policy-scoped external browser observation. */
 export const createBrowserEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
     predicateType: browserPredicate(operation),
@@ -20,6 +21,18 @@ export const createBrowserEvidence = (operation, input, result, provider) => cre
 });
 const browserParameters = (input) => {
     if (!("cdp_endpoint" in input)) {
+        if ("before_scenario" in input &&
+            input.before_scenario !== undefined &&
+            input.after_scenario !== undefined)
+            return {
+                comparison_kind: "browser_scenario",
+                before_browser: input.before_scenario.browser,
+                after_browser: input.after_scenario.browser,
+                before_start_origin: input.before_scenario.scenario.start_origin,
+                after_start_origin: input.after_scenario.scenario.start_origin,
+                max_changes: input.max_changes,
+                normalization_sha256: commitBrowserScenarioNormalization(input.normalization).sha256,
+            };
         if ("max_changes" in input)
             return {
                 before_target_id: input.before.inspection.target.target_id,
@@ -74,6 +87,7 @@ const browserParameters = (input) => {
         include_websocket_shapes: input.include_websocket_shapes,
         include_script_sources: input.include_script_sources,
         include_storage_keys: input.include_storage_keys,
+        include_storage_fingerprints: input.include_storage_fingerprints,
         limits: input.limits,
         ...(input.include_script_sources && "source_capture_approved" in input
             ? {

package/dist/application/BrowserScenarioCapturePort.js

@@ -0,0 +1 @@
+export {};

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

@@ -8,8 +8,21 @@ const statusSchema = z.object({
         operation: z.string(),
         available: z.boolean(),
         reason: z.string().nullable(),
+        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"],
@@ -32,10 +45,17 @@ 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, descriptor]));
+    const descriptors = new Map(status.capabilities.map((descriptor) => [
+        descriptor.operation,
+        {
+            available: descriptor.available,
+            reason: descriptor.reason,
+            availability_code: descriptor.availability_code ?? null,
+        },
+    ]));
     return TOOL_CONTRACTS.map((contract) => {
         const availability = availabilityFor({
             name: contract.name,
@@ -45,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,
@@ -61,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)
@@ -86,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",
@@ -113,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.",
@@ -151,13 +210,18 @@ 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",
             remediation: "Install or configure a provider that declares this operation.",
         };
     if (!descriptor.available &&
-        descriptor.reason?.toLowerCase().includes("require macos") === true)
+        descriptor.availability_code === "unsupported_host")
         return {
             reason: "unsupported_host",
             remediation: descriptor.reason,
@@ -187,7 +251,7 @@ const composedAvailability = (name, descriptors) => {
         .find((descriptor) => descriptor?.available === false);
     if (unavailable !== undefined)
         return {
-            reason: unavailable.reason?.toLowerCase().includes("require macos") === true
+            reason: unavailable.availability_code === "unsupported_host"
                 ? "unsupported_host"
                 : "provider_unavailable",
             remediation: unavailable.reason ?? "Choose another target or configured provider.",

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 };
 };