rea-agents 2.0.0 → 2.1.0

package/dist/cliInvestigationCommands.js

@@ -11,31 +11,74 @@ const investigationOptionsSchema = z.object({
         .boolean()
         .default(false)
         .describe("Approve persistent workspace writes"),
-    workspaceName: z.string().trim().min(1).max(200).default("default"),
-    expectedRevision: z.number().int().min(1).optional(),
+    workspaceName: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .default("default")
+        .describe("Logical name recorded in the investigation workspace"),
+    expectedRevision: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Required current workspace revision for an atomic update"),
     replayRunId: z
         .string()
         .regex(/^run_[a-f0-9]{64}$/u)
         .optional()
         .describe("Replay one verified complete workspace run without rescanning"),
-    maxEntries: z.number().int().min(1).max(50_000).default(10_000),
+    maxEntries: z
+        .number()
+        .int()
+        .min(1)
+        .max(50_000)
+        .default(10_000)
+        .describe("Maximum artifact entries to inspect per version"),
     maxTotalBytes: z
         .number()
         .int()
         .min(1)
         .max(Number.MAX_SAFE_INTEGER)
-        .default(1_073_741_824),
+        .default(1_073_741_824)
+        .describe("Maximum total uncompressed artifact content to inspect"),
     maxEntryBytes: z
         .number()
         .int()
         .min(1)
         .max(Number.MAX_SAFE_INTEGER)
-        .default(268_435_456),
-    pageSize: z.number().int().min(1).max(500).default(500),
-    changeLimit: z.number().int().min(1).max(500).default(500),
-    integrityPolicy: z.enum(["fail", "record-and-continue"]).default("fail"),
-    integrityContinueApproved: z.boolean().default(false),
-    maxIntegrityMismatches: z.number().int().min(1).max(100).default(10),
+        .default(268_435_456)
+        .describe("Maximum uncompressed content to inspect for one entry"),
+    pageSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(500)
+        .describe("Maximum graph items loaded per investigation page"),
+    changeLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .default(500)
+        .describe("Maximum version changes to record"),
+    integrityPolicy: z
+        .enum(["fail", "record-and-continue"])
+        .default("fail")
+        .describe("Behavior when declared artifact integrity does not match"),
+    integrityContinueApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve continuing after recorded integrity mismatches"),
+    maxIntegrityMismatches: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(10)
+        .describe("Maximum integrity mismatches to record before stopping"),
 });
 /** Register the persistent cross-version CLI workflow. */
 export const registerInvestigationCommands = (cli, logger) => {

package/dist/cliObservationOptions.js

@@ -0,0 +1,137 @@
+import { z } from "incur";
+const boundedCount = (subject, maximum, fallback, minimum = 1) => z
+    .number()
+    .int()
+    .min(minimum)
+    .max(maximum)
+    .default(fallback)
+    .describe(`Maximum ${subject}`);
+const boundedBytes = (subject, maximum, fallback) => boundedCount(`${subject} in bytes`, maximum, fallback);
+const positiveCount = (subject, fallback) => z.number().int().min(1).default(fallback).describe(`Maximum ${subject}`);
+const browserScopeOptions = {
+    allowedOrigins: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
+    approved: z.boolean().default(false).describe("Approve passive observation"),
+};
+export const browserPageInspectionOptions = z.object({
+    ...browserScopeOptions,
+    observationMs: boundedCount("observation duration in milliseconds", 10_000, 500, 0),
+    includeAccessibilityText: z
+        .boolean()
+        .default(false)
+        .describe("Include bounded accessibility text"),
+    includeConsoleText: z
+        .boolean()
+        .default(false)
+        .describe("Include bounded console message text"),
+    consoleTextApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve capturing console message text"),
+    includeJsonBodyShapes: z
+        .boolean()
+        .default(false)
+        .describe("Include structural shapes of JSON response bodies"),
+    jsonBodySchemaApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve inspecting JSON response bodies for structural shapes"),
+    includeWebsocketShapes: z
+        .boolean()
+        .default(false)
+        .describe("Include structural shapes of WebSocket payloads"),
+    websocketShapeApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve inspecting WebSocket payloads for structural shapes"),
+    includeScriptSources: z
+        .boolean()
+        .default(false)
+        .describe("Include bounded JavaScript source text"),
+    includeStorageKeys: z
+        .boolean()
+        .default(false)
+        .describe("Include storage key names without values"),
+    maxFrames: boundedCount("page frames", 1_000, 200),
+    maxDomNodes: boundedCount("DOM nodes", 10_000, 2_000),
+    maxAxNodes: boundedCount("accessibility nodes", 10_000, 2_000),
+    maxAxTextFieldBytes: boundedBytes("one accessibility text field", 16 * 1_024, 1_024),
+    maxTotalAxTextBytes: boundedBytes("total accessibility text", 1_024 * 1_024, 64 * 1_024),
+    maxScripts: boundedCount("scripts", 1_000, 200),
+    maxResources: boundedCount("resources", 10_000, 2_000),
+    maxWorkers: boundedCount("workers", 5_000, 500),
+    maxStorageKeys: boundedCount("storage keys", 10_000, 1_000),
+    maxScriptSourceBytes: boundedBytes("one script source", 4 * 1_024 * 1_024, 1_024 * 1_024),
+    maxTotalScriptSourceBytes: boundedBytes("total script source", 16 * 1_024 * 1_024, 4 * 1_024 * 1_024),
+    maxNetworkEvents: boundedCount("network events", 10_000, 1_000),
+    maxConsoleEvents: boundedCount("console events", 2_000, 200),
+    maxConsoleTextFieldBytes: boundedBytes("one console text field", 16 * 1_024, 1_024),
+    maxTotalConsoleTextBytes: boundedBytes("total console text", 1_024 * 1_024, 64 * 1_024),
+    maxJsonBodyBytes: boundedBytes("one JSON response body", 4 * 1_024 * 1_024, 1_024 * 1_024),
+    maxTotalJsonBodyBytes: boundedBytes("total JSON response bodies", 16 * 1_024 * 1_024, 4 * 1_024 * 1_024),
+    maxJsonShapeNodes: boundedCount("JSON shape nodes", 100_000, 5_000),
+    maxJsonShapeDepth: boundedCount("JSON shape depth", 100, 20),
+    maxWebsocketEvents: boundedCount("WebSocket events", 5_000, 500),
+    maxWebsocketShapeBytes: boundedBytes("one WebSocket shape", 1_024 * 1_024, 64 * 1_024),
+    maxTotalWebsocketShapeBytes: boundedBytes("total WebSocket shapes", 16 * 1_024 * 1_024, 1_024 * 1_024),
+});
+const electronScopeOptions = {
+    allowedFileRoots: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Filesystem roots; defaults to REA_ELECTRON_FILE_ROOTS_JSON"),
+    approved: z.boolean().default(false).describe("Approve passive observation"),
+};
+export const electronPageInspectionOptions = z.object({
+    ...electronScopeOptions,
+    observationMs: boundedCount("observation duration in milliseconds", 10_000, 100, 0),
+    includeScriptSources: z
+        .boolean()
+        .default(false)
+        .describe("Include bounded JavaScript source text"),
+    sourceCaptureApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve capturing bounded script source text"),
+    maxFrames: boundedCount("page frames", 1_000, 200),
+    maxDomNodes: boundedCount("DOM nodes", 10_000, 2_000),
+    maxScripts: boundedCount("scripts", 2_000, 500),
+    maxResources: boundedCount("resources", 10_000, 2_000),
+    maxWorkers: boundedCount("workers", 5_000, 500),
+    maxScriptSourceBytes: boundedBytes("one captured script source", 4 * 1_024 * 1_024, 1_024 * 1_024),
+    maxTotalScriptSourceBytes: boundedBytes("total captured script source", 16 * 1_024 * 1_024, 4 * 1_024 * 1_024),
+});
+export const javascriptApplicationOptions = z.object({
+    approved: z
+        .boolean()
+        .default(false)
+        .describe("Approve reading the application artifact"),
+    format: z
+        .enum(["auto", "asar", "directory"])
+        .default("auto")
+        .describe("Application artifact format"),
+    sourceMapReadApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve reading local source maps referenced by the application"),
+    maxEntries: positiveCount("artifact entries to inspect", 8_000),
+    maxTotalArtifactBytes: positiveCount("total uncompressed artifact content to inspect", 512 * 1_024 * 1_024),
+    maxArtifactEntryBytes: positiveCount("uncompressed content for one artifact entry", 128 * 1_024 * 1_024),
+    maxCompressionRatio: z
+        .number()
+        .min(1)
+        .default(1_000)
+        .describe("Maximum accepted compressed-to-uncompressed expansion ratio"),
+    maxDepth: positiveCount("artifact directory depth", 64),
+    maxPathBytes: positiveCount("encoded artifact path length", 4_096),
+    maxTextFiles: positiveCount("text files to parse", 5_000),
+    maxTotalTextBytes: positiveCount("total text content to parse", 128 * 1_024 * 1_024),
+    maxTextFileBytes: positiveCount("size of one parsed text file", 8 * 1_024 * 1_024),
+    maxAstNodes: positiveCount("JavaScript AST nodes to parse", 2_000_000),
+    maxFindings: positiveCount("static-analysis findings to return", 8_000),
+    maxModules: positiveCount("application modules to project", 20_000),
+    maxSourceMapSources: positiveCount("original sources from source maps", 5_000),
+    maxParseMilliseconds: positiveCount("JavaScript parsing time in milliseconds", 30_000),
+});

package/dist/cliPolicyCommands.js

@@ -36,17 +36,40 @@ export const registerPolicyCommands = (cli, logger) => {
     cli.command(CLI_COMMANDS.policy, {
         description: "Inspect, explain, or revoke unified local permission grants",
         args: z.object({
-            action: z.enum(["status", "list", "explain", "revoke"]),
-            value: z.string().optional(),
+            action: z
+                .enum(["status", "list", "explain", "revoke"])
+                .describe("Permission-policy operation to perform"),
+            value: z
+                .string()
+                .optional()
+                .describe("Capability to explain or grant ID to revoke"),
         }),
         options: z.object({
-            root: z.string().optional(),
-            executable: z.string().optional(),
-            environmentNames: z.array(z.string()).default([]),
-            origins: z.array(z.string()).default([]),
-            network: z.enum(["none", "loopback", "external"]).default("none"),
-            mount: z.boolean().default(false),
-            write: z.boolean().default(false),
+            root: z.string().optional().describe("Filesystem root to authorize"),
+            executable: z
+                .string()
+                .optional()
+                .describe("Executable path to authorize"),
+            environmentNames: z
+                .array(z.string())
+                .default([])
+                .describe("Environment variable names the operation may read"),
+            origins: z
+                .array(z.string())
+                .default([])
+                .describe("Exact browser origins the operation may access"),
+            network: z
+                .enum(["none", "loopback", "external"])
+                .default("none")
+                .describe("Maximum network scope to authorize"),
+            mount: z
+                .boolean()
+                .default(false)
+                .describe("Authorize mounting an artifact filesystem"),
+            write: z
+                .boolean()
+                .default(false)
+                .describe("Explain the write form of the requested capability"),
             yes: z
                 .boolean()
                 .default(false)
@@ -58,56 +81,67 @@ export const registerPolicyCommands = (cli, logger) => {
             if (!config.ok)
                 return failure(config.error);
             if (args.action === "status")
-                return {
-                    reload: "SIGHUP",
-                    restart_required: false,
-                    administrator_ceilings: config.value.permissionCeilings,
-                    project_store: config.value.permissionProjectStore ?? null,
-                };
+                return policyStatus(config.value);
             if (args.action === "list")
-                return readProjectGrants(config.value).then((result) => result.ok ? { grants: result.grants } : result.error);
-            if (args.action === "revoke") {
-                if (args.value === undefined)
-                    return { error: "Grant ID is required for policy revoke" };
-                const { permissionProjectRoot, permissionProjectStore } = config.value;
-                if (permissionProjectRoot === undefined ||
-                    permissionProjectStore === undefined)
-                    return { error: "Project policy is not configured" };
-                const approval = await approvePolicyRevocation({
+                return policyList(config.value);
+            if (args.action === "revoke")
+                return policyRevoke({
+                    config: config.value,
+                    grantId: args.value,
                     approved: options.yes,
                     interactive: !agent && !formatExplicit && process.stdin.isTTY === true,
-                    grantId: args.value,
                     confirm: confirmPolicyRevocation,
                 });
-                if (!approval.approved)
-                    return approval.reason === "required"
-                        ? {
-                            error: "Policy revoke requires confirmation. Rerun interactively or with --yes.",
-                            grant_id: args.value,
-                        }
-                        : {
-                            error: "Policy revocation was cancelled",
-                            grant_id: args.value,
-                        };
-                const revoked = await revokeProjectPermissionGrant(permissionProjectStore, permissionProjectRoot, args.value);
-                return revoked.ok && revoked.value
-                    ? {
-                        revoked: args.value,
-                        reload: "Send SIGHUP to the REA MCP process",
-                    }
-                    : revoked.ok
-                        ? { error: "Grant was not found", grant_id: args.value }
-                        : { error: revoked.error.message };
-            }
             const capability = capabilitySchema.safeParse(args.value);
             if (!capability.success)
                 return {
                     error: "A registered capability is required for policy explain",
                 };
-            return explain(config.value, capability.data, options);
+            return policyExplain(config.value, capability.data, options);
         }),
     });
 };
+const policyStatus = (config) => ({
+    reload: "SIGHUP",
+    restart_required: false,
+    administrator_ceilings: config.permissionCeilings,
+    project_store: config.permissionProjectStore ?? null,
+});
+const policyList = (config) => readProjectGrants(config).then((result) => result.ok ? { grants: result.grants } : result.error);
+const policyRevoke = async (context) => {
+    if (context.grantId === undefined)
+        return { error: "Grant ID is required for policy revoke" };
+    const { permissionProjectRoot, permissionProjectStore } = context.config;
+    if (permissionProjectRoot === undefined ||
+        permissionProjectStore === undefined)
+        return { error: "Project policy is not configured" };
+    const approval = await approvePolicyRevocation({
+        approved: context.approved,
+        interactive: context.interactive,
+        grantId: context.grantId,
+        confirm: context.confirm,
+    });
+    if (!approval.approved)
+        return approval.reason === "required"
+            ? {
+                error: "Policy revoke requires confirmation. Rerun interactively or with --yes.",
+                grant_id: context.grantId,
+            }
+            : {
+                error: "Policy revocation was cancelled",
+                grant_id: context.grantId,
+            };
+    const revoked = await revokeProjectPermissionGrant(permissionProjectStore, permissionProjectRoot, context.grantId);
+    return revoked.ok && revoked.value
+        ? {
+            revoked: context.grantId,
+            reload: "Send SIGHUP to the REA MCP process",
+        }
+        : revoked.ok
+            ? { error: "Grant was not found", grant_id: context.grantId }
+            : { error: revoked.error.message };
+};
+const policyExplain = async (config, capability, options) => explain(config, capability, options);
 const confirmPolicyRevocation = async (grantId) => {
     const prompt = createInterface({
         input: process.stdin,

package/dist/cliSetup.js

@@ -0,0 +1,289 @@
+import { cancel, confirm, intro, isCancel, multiselect, outro, } from "@clack/prompts";
+import { SUPPORTED_CLIENT_DEFINITIONS } from "./application/SupportedClients.js";
+const clientDisplayNames = new Map(SUPPORTED_CLIENT_DEFINITIONS.map(({ name, displayName }) => [
+    name,
+    displayName,
+]));
+const promptStreams = {
+    input: process.stdin,
+    output: process.stderr,
+    withGuide: true,
+};
+const agentAccessCapabilityId = "agent_access";
+/** Run the inline setup picker, exact preflight, and default-No consent. */
+export const confirmInteractiveSetup = async (actions, accessible) => {
+    intro("REA setup", promptStreams);
+    renderValueIntroduction();
+    renderDetectedSummary(actions);
+    renderKeyboardHelp(accessible);
+    const selectedActionIds = await selectSetupActions(actions, accessible);
+    if (selectedActionIds === undefined)
+        return cancelledDecision();
+    if (selectedActionIds.length === 0) {
+        cancel("Nothing selected. No changes were made.", promptStreams);
+        return { approved: false, selectedActionIds };
+    }
+    const selected = new Set(selectedActionIds);
+    const selectedActions = actions.filter(({ id }) => selected.has(id));
+    renderPreflight(selectedActions);
+    const approved = await confirm({
+        ...promptStreams,
+        message: selectedActions.length === 1
+            ? "Apply this change?"
+            : `Apply these ${String(selectedActions.length)} changes?`,
+        initialValue: false,
+        active: "Yes, apply",
+        inactive: "No, cancel",
+    });
+    if (isCancel(approved) || !approved) {
+        cancel("Setup cancelled. No changes were made.", promptStreams);
+        return { approved: false, selectedActionIds };
+    }
+    return { approved: true, selectedActionIds };
+};
+/** Render stable, append-only progress for real setup operations. */
+export const renderSetupProgress = (event) => {
+    const symbol = event.state === "started"
+        ? "◇"
+        : event.state === "completed"
+            ? "◆"
+            : event.state === "warning"
+                ? "!"
+                : "✗";
+    const suffix = event.detail === undefined ? "" : ` · ${event.detail}`;
+    writeLine(`${symbol}  ${event.label}${suffix}`);
+};
+/** Finish an interactive setup journey without exposing the full doctor catalog. */
+export const renderInteractiveSetupResult = (result) => {
+    if (result.status === "ready") {
+        const changedClients = Object.entries(result.clients)
+            .filter(([, client]) => client.status === "configured")
+            .map(([client]) => clientDisplayNames.get(client) ?? client);
+        const readyClients = readyAgentClients(result, changedClients);
+        renderReadyCapabilities(result, readyClients);
+        outro(changedClients.length === 0
+            ? "REA is ready for local app analysis."
+            : `Restart ${changedClients.join(", ")} to load REA.`, promptStreams);
+        return;
+    }
+    if (result.status === "planned")
+        return;
+    writeLine(`!  ${result.remediation ?? "Setup needs attention."}`);
+    outro("Run `rea doctor` for the remaining checks.", promptStreams);
+};
+/** Keep default non-TTY output actionable without emitting the full catalog. */
+export const conciseSetupResult = (result) => ({
+    status: result.status,
+    plannedActions: result.plannedActions,
+    appliedActions: result.appliedActions,
+    clients: result.clients,
+    doctor: {
+        healthy: result.doctor.healthy,
+        checks: result.doctor.checks.filter(({ ok }) => !ok),
+    },
+    ...(result.code === undefined ? {} : { code: result.code }),
+    ...(result.remediation === undefined
+        ? {}
+        : { remediation: result.remediation }),
+});
+const selectSetupActions = async (actions, accessible) => {
+    const clientActions = actions.filter(({ kind }) => kind === "configure_client");
+    const componentActions = actions.filter(({ kind }) => kind !== "configure_client");
+    const capabilities = setupCapabilities(clientActions, componentActions);
+    const selectedCapabilities = accessible
+        ? await selectCapabilitiesAccessibly(capabilities)
+        : await selectCapabilities(capabilities);
+    if (selectedCapabilities === undefined)
+        return undefined;
+    const selectedCapabilityIds = new Set(selectedCapabilities);
+    const selectedActionIds = componentActions
+        .filter(({ id }) => selectedCapabilityIds.has(id))
+        .map(({ id }) => id);
+    if (!selectedCapabilityIds.has(agentAccessCapabilityId))
+        return selectedActionIds;
+    const selectedClients = accessible
+        ? await selectClientsAccessibly(clientActions)
+        : await selectClients(clientActions);
+    return selectedClients === undefined
+        ? undefined
+        : [...selectedClients, ...selectedActionIds];
+};
+const setupCapabilities = (clientActions, componentActions) => [
+    ...(clientActions.length === 0
+        ? []
+        : [
+            {
+                id: agentAccessCapabilityId,
+                label: "Coding-agent access (MCP)",
+                hint: `${String(clientActions.length)} detected ${clientActions.length === 1 ? "agent" : "agents"}`,
+            },
+        ]),
+    ...componentActions.map((action) => ({
+        id: action.id,
+        label: `${action.label} (${actionModality(action)})`,
+        hint: `${action.operation} · ${action.target}`,
+    })),
+];
+const selectCapabilities = async (capabilities) => {
+    const selection = await multiselect({
+        ...promptStreams,
+        message: "What should REA set up?",
+        options: capabilities.map((capability) => ({
+            value: capability.id,
+            label: capability.label,
+            hint: capability.hint,
+        })),
+        required: false,
+        maxItems: Math.max(3, Math.min(capabilities.length, (process.stderr.rows ?? 24) - 8)),
+        showInstructions: true,
+    });
+    return isCancel(selection) ? undefined : selection;
+};
+const selectCapabilitiesAccessibly = async (capabilities) => {
+    const selected = [];
+    for (const capability of capabilities) {
+        const included = await confirm({
+            ...promptStreams,
+            message: `Set up ${capability.label}? ${capability.hint}`,
+            initialValue: false,
+            vertical: true,
+        });
+        if (isCancel(included))
+            return undefined;
+        if (included)
+            selected.push(capability.id);
+    }
+    return selected;
+};
+const selectClients = async (actions) => {
+    const selection = await multiselect({
+        ...promptStreams,
+        message: "Which agents should use REA?",
+        options: actions.map((action) => ({
+            value: action.id,
+            label: `${action.label} (detected)`,
+            hint: `${action.operation} · ${action.target}`,
+        })),
+        required: false,
+        maxItems: Math.max(3, Math.min(actions.length, (process.stderr.rows ?? 24) - 8)),
+        showInstructions: true,
+    });
+    return isCancel(selection) ? undefined : selection;
+};
+const selectClientsAccessibly = async (actions) => {
+    const selected = [];
+    for (const action of actions) {
+        const included = await confirm({
+            ...promptStreams,
+            message: `Configure ${action.label}? ${action.target}`,
+            initialValue: false,
+            vertical: true,
+        });
+        if (isCancel(included))
+            return undefined;
+        if (included)
+            selected.push(action.id);
+    }
+    return selected;
+};
+const renderValueIntroduction = () => {
+    writeLine("│  Understand local apps and binaries from your coding agent.");
+    writeLine("│");
+    writeLine("│  • Trace how a feature works with local evidence.");
+    writeLine("│  • Use the same analysis capabilities from REA's CLI and supported agents.");
+    writeLine("│  • Keep analyzed targets on this machine instead of uploading them to a hosted service.");
+};
+const renderDetectedSummary = (actions) => {
+    const clients = actions.filter(({ kind }) => kind === "configure_client");
+    writeLine("│");
+    if (clients.length === 0) {
+        writeLine("◆  No agent integrations need configuration");
+    }
+    else {
+        writeLine(`◆  Found ${String(clients.length)} supported ${clients.length === 1 ? "agent" : "agents"}`);
+        writeLine(`│  ${humanList(clients.map(({ label }) => label))}`);
+    }
+};
+const renderKeyboardHelp = (accessible) => {
+    writeLine("│");
+    writeLine(accessible
+        ? "│  Keys: Enter answer · Ctrl-C cancel"
+        : "│  Keys: ↑/↓ navigate · Space toggle · Enter confirm · Ctrl-C cancel");
+};
+const renderReadyCapabilities = (result, readyClients) => {
+    writeLine("◆  What you can do now");
+    const providers = readyProviders(result);
+    if (providers.length > 0)
+        writeLine(`│  Deep analysis: ${humanList(providers)}`);
+    if (readyClients.length > 0)
+        writeLine(`│  Agent access: ${humanList(readyClients)}`);
+    if (result.doctor.identity?.skill.state === "aligned")
+        writeLine("│  Guided reverse-engineering workflows: installed");
+    if (providers.length > 0)
+        writeLine("│  CLI: rea analyze /path/to/app");
+    const firstClient = readyClients[0];
+    if (firstClient !== undefined)
+        writeLine(`│  Try in ${firstClient}: "Use REA to explain how a feature works in /path/to/app."`);
+};
+const readyAgentClients = (result, changedClients) => {
+    const alignedClients = (result.doctor.identity?.registrations ?? [])
+        .filter(({ state }) => state === "aligned")
+        .map(({ client }) => clientDisplayNames.get(client) ?? client);
+    return [...new Set([...alignedClients, ...changedClients])];
+};
+const readyProviders = (result) => {
+    const providers = [
+        ...(result.doctor.hopperPath === undefined ? [] : ["Hopper"]),
+        ...(result.doctor.providerInspections ?? [])
+            .filter(({ available }) => available)
+            .map(({ id }) => displayProviderId(id)),
+    ];
+    return [...new Set(providers)];
+};
+const displayProviderId = (id) => id.length === 0 ? id : `${id[0]?.toUpperCase() ?? ""}${id.slice(1)}`;
+const actionModality = (action) => {
+    if (action.kind === "configure_client")
+        return "MCP";
+    if (action.kind === "install_hopper")
+        return "provider";
+    return "skill";
+};
+const humanList = (values) => {
+    if (values.length < 2)
+        return values[0] ?? "";
+    if (values.length === 2)
+        return `${values[0]} and ${values[1]}`;
+    return `${values.slice(0, -1).join(", ")}, and ${values.at(-1)}`;
+};
+const renderPreflight = (actions) => {
+    writeLine("│");
+    writeLine("◆  Ready to review");
+    for (const action of actions) {
+        writeLine("│");
+        writeLine(`│  ${action.operation.toUpperCase()}  ${action.label}`);
+        writeLine(`│          ${action.target}`);
+        if (action.backupPath !== undefined)
+            writeLine(`│          backup: ${action.backupPath}`);
+        for (const origin of action.networkOrigins ?? [])
+            writeLine(`│          network: ${origin}`);
+        if (action.integrity !== undefined)
+            writeLine(`│          integrity: ${action.integrity}`);
+        for (const command of action.commands ?? [])
+            writeLine(`│          command: ${command}`);
+        writeLine(`│          ${action.detail}`);
+        if (action.external)
+            writeLine("│          external software");
+    }
+    writeLine("│");
+    writeLine("│  REA will preserve unrelated configuration and will not install or upgrade Node.js, npm, Homebrew, Java, or Ghidra.");
+};
+const cancelledDecision = () => {
+    cancel("Setup cancelled. No changes were made.", promptStreams);
+    return {
+        approved: false,
+        selectedActionIds: [],
+    };
+};
+const writeLine = (line) => {
+    process.stderr.write(`${line}\n`);
+};