rea-agents 6.4.0 → 6.5.0

package/dist/cli/browserAdvancedCommands.js

@@ -5,12 +5,15 @@ import { captureWebScreenshot, compareWebCaptureEvidence, compareWebScreenshotEv
 import { CdpBrowserProvider } from "../browser/CdpBrowserProvider.js";
 import { logCliCommand } from "../cliLogging.js";
 import { AnalysisInputError, } from "../domain/analysisErrorCore.js";
-import { browserCaptureComparisonInputSchema } from "../domain/browserCaptureComparison.js";
+import { compareBrowserScenariosInputSchema } from "../domain/browserScenarioDiffValues.js";
+import { browserScenarioCaptureSchema } from "../domain/browserScenarioCapture.js";
+import { compareWebCapturesInputSchema } from "../domain/webCaptureDiffSchemas.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
 import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "../domain/webScreenshot.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register WebMCP, capture-diff, and screenshot CLI equivalents. */
 export const registerAdvancedBrowserCommands = (cli, logger) => {
     registerWebMcp(cli, logger);
@@ -22,7 +25,9 @@ const registerWebMcp = (cli, logger) => {
     cli.command(CLI_COMMANDS.discoverWebMcpTools, {
         description: "Passively discover page-declared WebMCP tools",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
@@ -34,19 +39,20 @@ const registerWebMcp = (cli, logger) => {
                 .default(100)
                 .describe("Observation duration in milliseconds"),
         }),
-        run: ({ args, options }) => logCliCommand(logger, "discover-webmcp-tools", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "discover-webmcp-tools", async () => {
             const context = browserContext();
-            const parsed = discoverWebMcpToolsInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
                 observation_ms: options.observationMs,
-            });
+            };
+            const parsed = discoverWebMcpToolsInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("discover_webmcp_tools");
-            const result = await discoverWebMcpTools(context.provider, parsed.data);
+                return inputError("discover_webmcp_tools", projectInputIssues(parsed.error.issues, input));
+            const result = await discoverWebMcpTools(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerCaptureDiff = (cli, logger) => {
@@ -75,16 +81,20 @@ const registerCaptureDiff = (cli, logger) => {
             if (!inputs.ok)
                 return inputs.error;
             const { before, after, normalization } = inputs.value;
-            const scenarioComparison = browserCaptureComparisonInputSchema.safeParse({
-                before_scenario: before,
-                after_scenario: after,
-                normalization,
-            });
-            const parsed = scenarioComparison.success
-                ? scenarioComparison
-                : browserCaptureComparisonInputSchema.safeParse({ before, after });
+            // Passive snapshots own the inspection wrapper. Otherwise recognize
+            // scenario-owned fields even when the scenario manifest is missing.
+            const scenarioInput = [before, after].some((capture) => typeof capture === "object" &&
+                capture !== null &&
+                !("inspection" in capture) &&
+                Object.keys(browserScenarioCaptureSchema.shape).some((field) => field in capture));
+            const input = scenarioInput
+                ? { before_scenario: before, after_scenario: after, normalization }
+                : { before, after };
+            const parsed = scenarioInput
+                ? compareBrowserScenariosInputSchema.safeParse(input)
+                : compareWebCapturesInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("compare_web_captures");
+                return inputError("compare_web_captures", projectInputIssues(parsed.error.issues, input));
             const result = await compareWebCaptureEvidence(new CdpBrowserProvider(), parsed.data);
             return result.ok ? result.value : browserCliError(result.error);
         }),
@@ -94,24 +104,27 @@ const registerScreenshot = (cli, logger) => {
     cli.command(CLI_COMMANDS.captureWebScreenshot, {
         description: "Capture one visible page viewport within the supplied origin scope",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
             ...browserScopeOptions,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "capture-web-screenshot", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "capture-web-screenshot", async () => {
             const context = browserContext();
-            const parsed = captureWebScreenshotInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
-            });
+            };
+            const parsed = captureWebScreenshotInputSchema.safeParse(input);
             if (!parsed.success)
-                return inputError("capture_web_screenshot");
-            const result = await captureWebScreenshot(context.provider, parsed.data);
+                return inputError("capture_web_screenshot", projectInputIssues(parsed.error.issues, input));
+            const result = await captureWebScreenshot(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerScreenshotDiff = (cli, logger) => {

package/dist/cli/browserCommands.js

@@ -5,9 +5,10 @@ import { logCliCommand } from "../cliLogging.js";
 import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "../domain/browserObservation.js";
 import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema } from "../domain/browserSession.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { browserPageInspectionOptions, browserScopeOptions, observationDuration, } from "../cliObservationOptions.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register CLI equivalents of the passive browser MCP tools. */
 export const registerBrowserCommands = (cli, logger) => {
     registerTargetList(cli, logger);
@@ -19,33 +20,38 @@ const registerTargetList = (cli, logger) => {
     cli.command(CLI_COMMANDS.listBrowserTargets, {
         description: "List page targets from a selected loopback CDP browser, optionally filtered by origin",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
         }),
         options: z.object({ ...browserScopeOptions }),
-        run: ({ args, options }) => logCliCommand(logger, "list-browser-targets", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "list-browser-targets", async () => {
             const context = browserContext();
-            const parsed = listBrowserTargetsInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
-            });
+            };
+            const parsed = listBrowserTargetsInputSchema.safeParse(input);
             if (!parsed.success)
-                return browserCliError(new AnalysisInputError("list_browser_targets"));
-            const result = await listBrowserTargets(context.provider, parsed.data);
+                return browserCliError(analysisInputErrorFromIssues("list_browser_targets", parsed.error.issues, input));
+            const result = await listBrowserTargets(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerPageInspection = (cli, logger) => {
     cli.command(CLI_COMMANDS.inspectWebPage, {
         description: "Passively inspect one page through CDP, defaulting to its current origin",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: browserPageInspectionOptions,
-        run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "inspect-web-page", async () => {
             const context = browserContext();
-            const parsed = inspectWebPageInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
@@ -57,19 +63,24 @@ const registerPageInspection = (cli, logger) => {
                 include_script_sources: options.includeScriptSources,
                 include_storage_keys: options.includeStorageKeys,
                 include_storage_fingerprints: options.includeStorageFingerprints,
-            });
+            };
+            const parsed = inspectWebPageInputSchema.safeParse(input);
             if (!parsed.success)
-                return browserCliError(new AnalysisInputError("inspect_web_page"));
-            const result = await inspectWebPage(context.provider, parsed.data);
+                return browserCliError(analysisInputErrorFromIssues("inspect_web_page", parsed.error.issues, input));
+            const result = await inspectWebPage(context.provider, parsed.data, {
+                signal,
+            });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerBundleAnalysis = (cli, logger) => {
     cli.command(CLI_COMMANDS.analyzeWebBundle, {
         description: "Capture and statically analyze a page bundle, defaulting to the selected target origin",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
@@ -80,46 +91,52 @@ const registerBundleAnalysis = (cli, logger) => {
                 .default(false)
                 .describe("Fetch source maps referenced by captured scripts"),
         }),
-        run: ({ args, options }) => logCliCommand(logger, "analyze-web-bundle", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "analyze-web-bundle", async () => {
             const context = browserContext();
-            const parsed = analyzeWebBundleInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
                 observation_ms: options.observationMs,
                 include_script_sources: true,
                 fetch_source_maps: options.fetchSourceMaps,
-            });
+            };
+            const parsed = analyzeWebBundleInputSchema.safeParse(input);
             if (!parsed.success)
-                return browserCliError(new AnalysisInputError("analyze_web_bundle"));
-            const result = await analyzeWebBundle(context.provider, parsed.data);
+                return browserCliError(analysisInputErrorFromIssues("analyze_web_bundle", parsed.error.issues, input));
+            const result = await analyzeWebBundle(context.provider, parsed.data, {
+                signal,
+            });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };
 const registerObservationSession = (cli, logger) => {
     cli.command(CLI_COMMANDS.observeWebSession, {
         description: "Observe user-driven page navigation during a chosen window",
         args: z.object({
-            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            endpoint: z
+                .string()
+                .describe("Loopback CDP HTTP endpoint or browser WebSocket URL"),
             targetId: z.string().describe("Target ID from list-browser-targets"),
         }),
         options: z.object({
             ...browserScopeOptions,
             observationMs: observationDuration(10_000, 1),
         }),
-        run: ({ args, options }) => logCliCommand(logger, "observe-web-session", async () => {
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, "observe-web-session", async () => {
             const context = browserContext();
-            const parsed = observeWebSessionInputSchema.safeParse({
+            const input = {
                 cdp_endpoint: args.endpoint,
                 allowed_origins: options.allowedOrigins,
                 target_id: args.targetId,
                 observation_ms: options.observationMs,
-            });
+            };
+            const parsed = observeWebSessionInputSchema.safeParse(input);
             if (!parsed.success)
-                return browserCliError(new AnalysisInputError("observe_web_session"));
-            const result = await observeWebSession(context.provider, parsed.data);
+                return browserCliError(analysisInputErrorFromIssues("observe_web_session", parsed.error.issues, input));
+            const result = await observeWebSession(context.provider, parsed.data, { signal });
             return result.ok ? result.value : browserCliError(result.error);
-        }),
+        })),
     });
 };

package/dist/cli/captureCommands.js

@@ -0,0 +1,72 @@
+import { inspectPacketFieldsInputSchema } from "../domain/captures/packetFields.js";
+import { z } from "incur";
+import { resolve } from "node:path";
+import { createPacketCaptureService } from "../composition/captures.js";
+import { packetCaptureOptionsSchema, packetCaptureSelectorBudgetIssue, withinPacketCaptureSelectorBudget, } from "../domain/captures/packetCapture.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
+export const registerCaptureCommands = (cli, logger, environment, service = createPacketCaptureService(environment)) => {
+    cli.command(CLI_COMMANDS.inspectPacketFields, {
+        description: "Search installed TShark protocol and field definitions",
+        options: z
+            .object({
+            ...inspectPacketFieldsInputSchema.shape,
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(Number.MAX_SAFE_INTEGER)
+                .optional()
+                .describe("Maximum matching records to return; defaults to 50"),
+            all: z
+                .boolean()
+                .default(false)
+                .describe("Return all remaining matches within resource limits"),
+        })
+            .superRefine((options, context) => {
+            if (options.all && options.limit !== undefined)
+                context.addIssue({
+                    code: "custom",
+                    path: ["all"],
+                    message: "all and limit are mutually exclusive",
+                });
+        }),
+        run: ({ options: { all, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectPacketFields, async () => finishAnalysisCommand(() => service.inspectFields({ ...options, ...(all ? { limit: null } : {}) }, { signal }), service, "tshark-capture", "inspect_packet_fields"))),
+    });
+    cli.command(CLI_COMMANDS.inspectPacketCapture, {
+        description: "Inspect an existing packet capture with caller-supplied TShark",
+        args: z.object({ path: z.string().describe("Local packet capture") }),
+        options: z
+            .object({
+            ...packetCaptureOptionsSchema.shape,
+            match_limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Returned matching frames per page; default 50"),
+            all_matches: z
+                .boolean()
+                .default(false)
+                .describe("Return all remaining matching frames instead of a bounded page"),
+        })
+            .superRefine((options, context) => {
+            if (options.all_matches && options.match_limit !== undefined)
+                context.addIssue({
+                    code: "custom",
+                    path: ["all_matches"],
+                    message: "all_matches and match_limit are mutually exclusive",
+                });
+        })
+            .refine(withinPacketCaptureSelectorBudget, packetCaptureSelectorBudgetIssue),
+        run: ({ args, options: { all_matches, ...options } }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectPacketCapture, async () => {
+            return finishAnalysisCommand(() => service.inspect({
+                ...options,
+                ...(all_matches ? { match_limit: null } : {}),
+                path: resolve(args.path),
+            }, { signal }), service, "tshark-capture", "inspect_packet_capture");
+        })),
+    });
+};

package/dist/cli/cliResultOutput.js

@@ -0,0 +1,188 @@
+import { constants } from "node:buffer";
+import { Cli, Filter, Formatter } from "incur";
+import { estimateTokenCount, sliceByTokens } from "tokenx";
+import { parseCliOutputArguments, validateCliOutputArguments, } from "../cliOutput.js";
+import { cliOperationFailurePayload } from "../cliLogging.js";
+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError, } from "../domain/analysisErrorProjection.js";
+import { jsonOutputParts, writeJsonOutput, writeOutputText, } from "./jsonOutput.js";
+const registeredCommands = Cli.toCommands;
+/** Install formatting once, after registration, for every ordinary CLI result. */
+export const streamCliCommandResults = (cli, output) => {
+    const commands = registeredCommands.get(cli);
+    if (commands !== undefined)
+        wrapCommands(commands, [], output);
+};
+const wrapCommands = (commands, parents, output) => {
+    for (const [name, entry] of commands) {
+        const path = [...parents, name];
+        if ("_group" in entry) {
+            wrapCommands(entry.commands, path, output);
+            if (entry.root !== undefined)
+                wrapCommand(entry.root, path.join(" "), output);
+        }
+        else if (!("_alias" in entry) && !("_fetch" in entry))
+            wrapCommand(entry, path.join(" "), output);
+    }
+};
+const wrapCommand = (command, name, output) => {
+    const run = command.run;
+    command.run = (context) => {
+        const started = performance.now();
+        const result = run(context);
+        // Generator results and Incur's sentinel responses retain their own protocol.
+        if (typeof result === "object" &&
+            result !== null &&
+            Symbol.asyncIterator in result)
+            return result;
+        return Promise.resolve(result).then(async (value) => {
+            if (typeof value === "object" &&
+                value !== null &&
+                Symbol.for("incur.sentinel") in value)
+                return value;
+            if (!(await output.write(value, {
+                command: name,
+                format: context.format,
+                duration: `${Math.round(performance.now() - started)}ms`,
+            })))
+                return value;
+            if (output.error !== undefined)
+                return context.error({
+                    code: output.error.code,
+                    message: output.error.message,
+                });
+            return undefined;
+        });
+    };
+};
+/** Preserve Incur output controls and stream JSON while framing failures. */
+export const createCliResultOutput = (arguments_, destination) => {
+    const options = parseCliOutputArguments(arguments_);
+    if (options.parseError || !validateCliOutputArguments(arguments_).ok)
+        return undefined;
+    const format = options.format;
+    let handled = false;
+    let failed = false;
+    let error;
+    return {
+        get handled() {
+            return handled;
+        },
+        get failed() {
+            return failed;
+        },
+        get error() {
+            return error;
+        },
+        async write(value, metadata) {
+            if (metadata.format !== format)
+                return false;
+            const failure = options.fullOutput
+                ? cliOperationFailurePayload(value)
+                : undefined;
+            const filtered = options.filterOutput
+                ? Filter.apply(value, Filter.parse(options.filterOutput))
+                : value;
+            // Leave successful YAML and bare YAML rendering to Incur. The custom
+            // boundary is needed only for a full failure envelope, whose error
+            // sentinel otherwise drops category, remediation, and details.
+            if (format !== "json" && format !== "jsonl" && failure === undefined)
+                return false;
+            if (options.tokenCount) {
+                // Incur/tokenx materialize JSON. Measure its UTF-16 expansion before
+                // allowing that allocation, independently of UTF-8 bytes. Other formats
+                // retain Incur's materializing behavior.
+                const tokenValue = failure ?? filtered;
+                let characters = 0;
+                if (tokenValue !== undefined &&
+                    tokenValue !== null &&
+                    typeof tokenValue !== "function" &&
+                    typeof tokenValue !== "symbol") {
+                    if (format === "json" || format === "jsonl") {
+                        for (const part of jsonOutputParts(tokenValue, format, format === "json"))
+                            characters += part.length;
+                        characters = Math.max(0, characters - 1);
+                    }
+                }
+                if (characters <= constants.MAX_STRING_LENGTH) {
+                    if (failure === undefined)
+                        return false;
+                    handled = true;
+                    try {
+                        await writeOutputText(destination, `${estimateTokenCount(Formatter.format(failure, format))}\n`);
+                        return true;
+                    }
+                    catch (cause) {
+                        failed = true;
+                        throw cause;
+                    }
+                }
+                error = projectAnalysisError(new AnalysisResourceConstraintError(metadata.command, "memory", "Token counting requires a formatted string larger than the runtime permits.", {
+                    formatted_characters: characters,
+                    max_string_characters: constants.MAX_STRING_LENGTH,
+                }, {
+                    remediationAction: "Remove --token-count to stream the complete JSON result, or narrow it with --filter-output.",
+                }));
+            }
+            const meta = {
+                command: metadata.command,
+                duration: metadata.duration,
+            };
+            const errorDocument = options.fullOutput && failure !== undefined
+                ? fullFailureEnvelope(failure, meta, format, options.tokenLimit, options.tokenOffset)
+                : undefined;
+            const document = options.fullOutput
+                ? failure !== undefined
+                    ? errorDocument
+                    : filtered === undefined
+                        ? { ok: true, meta }
+                        : { ok: true, data: filtered, meta }
+                : // A selected null is a value; only a selection with no JSON value
+                    // falls back to the empty document.
+                    filtered === undefined ||
+                        typeof filtered === "function" ||
+                        typeof filtered === "symbol"
+                        ? {}
+                        : filtered;
+            // Once writing starts, a failed destination must not receive a second
+            // document from Incur's error formatter.
+            handled = true;
+            try {
+                if (failure !== undefined && format !== "json" && format !== "jsonl") {
+                    // Incur's error sentinel only carries code/message/retryable. Render
+                    // the full caller-visible failure at this output boundary.
+                    await writeOutputText(destination, `${Formatter.format(document, format)}\n`);
+                }
+                else {
+                    await writeJsonOutput(error === undefined
+                        ? document
+                        : options.fullOutput
+                            ? { ok: false, error, meta }
+                            : error, destination, format);
+                }
+            }
+            catch (cause) {
+                failed = true;
+                throw cause;
+            }
+            return true;
+        },
+    };
+};
+const fullFailureEnvelope = (failure, meta, format, tokenLimit, tokenOffset) => {
+    if (tokenLimit === undefined && tokenOffset === undefined)
+        return { ok: false, error: failure, meta };
+    const formatted = Formatter.format(failure, format);
+    const total = estimateTokenCount(formatted);
+    const offset = tokenOffset ?? 0;
+    const end = tokenLimit === undefined ? total : offset + tokenLimit;
+    if (offset === 0 && end >= total)
+        return { ok: false, error: failure, meta };
+    const actualEnd = Math.min(end, total);
+    const nextOffset = actualEnd < total ? actualEnd : undefined;
+    return {
+        ok: false,
+        error: `${sliceByTokens(formatted, offset, end)}\n[truncated: showing tokens ${offset}–${actualEnd} of ${total}]`,
+        meta: { ...meta, ...(nextOffset === undefined ? {} : { nextOffset }) },
+    };
+};