rea-agents 6.4.0 → 6.7.0

package/dist/cli/browserCommands.js

@@ -5,9 +5,11 @@ 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";
+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
 /** Register CLI equivalents of the passive browser MCP tools. */
 export const registerBrowserCommands = (cli, logger) => {
     registerTargetList(cli, logger);
@@ -19,33 +21,41 @@ 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 result.ok ? result.value : browserCliError(result.error);
-        }),
+                return browserCliError(analysisInputErrorFromIssues("list_browser_targets", parsed.error.issues, input));
+            return await finishAnalysisCommand(() => listBrowserTargets(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, context.provider.identity().id, "list_browser_targets", signal);
+        })),
     });
 };
 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 +67,25 @@ 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 result.ok ? result.value : browserCliError(result.error);
-        }),
+                return browserCliError(analysisInputErrorFromIssues("inspect_web_page", parsed.error.issues, input));
+            return await finishAnalysisCommand(() => inspectWebPage(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, context.provider.identity().id, "inspect_web_page", signal);
+        })),
     });
 };
 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 +96,56 @@ 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 result.ok ? result.value : browserCliError(result.error);
-        }),
+                return browserCliError(analysisInputErrorFromIssues("analyze_web_bundle", parsed.error.issues, input));
+            return await finishAnalysisCommand(() => analyzeWebBundle(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, context.provider.identity().id, "analyze_web_bundle", signal);
+        })),
     });
 };
 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 result.ok ? result.value : browserCliError(result.error);
-        }),
+                return browserCliError(analysisInputErrorFromIssues("observe_web_session", parsed.error.issues, input));
+            return await finishAnalysisCommand(() => observeWebSession(context.provider, parsed.data, { signal }), {
+                close: async () => {
+                    await context.provider.close?.();
+                },
+            }, context.provider.identity().id, "observe_web_session", signal);
+        })),
     });
 };

package/dist/cli/captureCommands.js

@@ -0,0 +1,72 @@
+import { inspectPacketFieldsInputSchema } from "../domain/captures/packetFields.js";
+import { z } from "incur";
+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";
+import { absoluteCallerPath } from "../filesystem/callerPath.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", signal))),
+    });
+    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: absoluteCallerPath(args.path),
+            }, { signal }), service, "tshark-capture", "inspect_packet_capture", signal);
+        })),
+    });
+};

package/dist/cli/cliResultOutput.js

@@ -0,0 +1,274 @@
+import { constants } from "node:buffer";
+import { Cli, Filter, Formatter } from "incur";
+import { estimateTokenCount, sliceByTokens } from "tokenx";
+import { parseCliOutputArguments, validateCliOutputArguments, } from "../cliOutput.js";
+import { cliOperationFailureIdentity, 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;
+    let completed;
+    const recoverFormattingFailure = async (cause) => {
+        // A rejected command never reaches write(). Destination failures retain
+        // handled ownership. Only a completed, unwritten result can be replaced.
+        if (completed === undefined ||
+            handled ||
+            !(cause instanceof RangeError) ||
+            cause.message !== "Invalid string length")
+            return false;
+        const { originalFailure } = completed;
+        error = projectAnalysisError(new AnalysisResourceConstraintError(completed.metadata.command, "memory", `The ${format} result could not fit in a runtime string. The original result was not written.`, {
+            format,
+            formatted_characters: null,
+            max_string_characters: constants.MAX_STRING_LENGTH,
+            ...(originalFailure === undefined
+                ? {}
+                : { original_failure: originalFailure }),
+        }, {
+            cause,
+            retryable: false,
+            remediationAction: "Use --format json to stream the complete result, or narrow it with --filter-output. Token limits are applied after formatting and cannot avoid this constraint.",
+        }));
+        const document = options.fullOutput
+            ? {
+                ok: false,
+                error,
+                meta: {
+                    command: completed.metadata.command,
+                    duration: completed.metadata.duration,
+                },
+            }
+            : error;
+        // Recovery must remain actionable even when a token window/count was
+        // requested. Do not apply those controls to this small typed failure.
+        const text = Formatter.format(document, format);
+        handled = true;
+        try {
+            await writeOutputText(destination, `${text}\n`);
+        }
+        catch (writeFailure) {
+            failed = true;
+            throw writeFailure;
+        }
+        return true;
+    };
+    const write = async (value, metadata) => {
+        completed = undefined;
+        if (metadata.format !== format)
+            return false;
+        try {
+            return await writeResult(value, metadata);
+        }
+        catch (cause) {
+            if (await recoverFormattingFailure(cause))
+                return true;
+            throw cause;
+        }
+    };
+    return {
+        get handled() {
+            return handled;
+        },
+        get failed() {
+            return failed;
+        },
+        get error() {
+            return error;
+        },
+        write,
+        recoverFormattingFailure,
+    };
+    async function writeResult(value, metadata) {
+        const failure = options.fullOutput
+            ? cliOperationFailurePayload(value)
+            : undefined;
+        completed = {
+            metadata,
+            originalFailure: cliOperationFailureIdentity(value),
+        };
+        const filterPaths = options.filterOutput
+            ? Filter.parse(options.filterOutput)
+            : undefined;
+        const filtered = filterPaths === undefined ? value : Filter.apply(value, filterPaths);
+        if (filterPaths !== undefined &&
+            filterPaths.length > 0 &&
+            (format === "json" || format === "jsonl") &&
+            Array.isArray(filtered))
+            normalizeFilteredJsonArrays(filtered);
+        // 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) {
+                const count = estimateTokenCount(Formatter.format(tokenValue, format));
+                handled = true;
+                try {
+                    await writeOutputText(destination, `${count}\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.
+        const failureText = failure !== undefined && format !== "json" && format !== "jsonl"
+            ? Formatter.format(document, format)
+            : undefined;
+        handled = true;
+        try {
+            if (failureText !== undefined) {
+                // Incur's error sentinel only carries code/message/retryable. Render
+                // the full caller-visible failure at this output boundary.
+                await writeOutputText(destination, `${failureText}\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 }) },
+    };
+};
+/** Filter.apply owns these mapped arrays; an empty path list returns the source. */
+const normalizeFilteredJsonArrays = (selection) => {
+    const pending = [selection];
+    while (pending.length > 0) {
+        const array = pending.pop();
+        for (let index = 0; index < array.length; index += 1) {
+            const value = array[index];
+            if (value === undefined ||
+                typeof value === "function" ||
+                typeof value === "symbol")
+                array[index] = null;
+            else if (Array.isArray(value))
+                pending.push(value);
+        }
+    }
+};