rea-agents 6.0.0 → 6.1.0

package/dist/application/JsonFiles.js

@@ -1,34 +1,41 @@
-import { link, lstat, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { link, lstat, mkdtemp, open, readFile, realpath, rename, rm, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-import writeFileAtomic from "write-file-atomic";
 import { EvidenceFileError } from "../domain/evidenceErrors.js";
 import { err, ok } from "../domain/result.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
 export const readJsonFile = async (path) => {
+    const requestedPath = resolve(path);
     try {
-        const canonicalPath = await realpath(resolve(path));
+        const canonicalPath = await realpath(requestedPath);
         const stats = await lstat(canonicalPath);
         if (!stats.isFile())
-            return err(new EvidenceFileError("read", "not-file"));
+            return err(new EvidenceFileError("read", "not-file", { path: requestedPath }));
         const encoded = await readFile(canonicalPath);
         let decoded;
         try {
             decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(encoded));
         }
         catch (cause) {
-            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+            return err(new EvidenceFileError("read", "invalid-json", {
+                cause,
+                path: requestedPath,
+            }));
         }
         return ok(decoded);
     }
     catch (cause) {
-        return err(new EvidenceFileError("read", "io", { cause }));
+        return err(new EvidenceFileError("read", missingOrIo(cause), {
+            cause,
+            path: requestedPath,
+        }));
     }
 };
 /** Atomically write text to the caller-supplied path. */
-export const writeTextFile = async (encoded, path, overwrite) => {
-    const bytes = Buffer.byteLength(encoded, "utf8");
+export const writeTextFile = async (encoded, path, overwrite) => writeTextParts([encoded], path, overwrite);
+/** Publish complete streamed text atomically, keeping only one encoded part in memory. */
+export const writeTextParts = async (parts, path, overwrite) => {
+    const requestedPath = resolve(path);
     try {
-        const requestedPath = resolve(path);
         const canonicalParent = await realpath(dirname(requestedPath));
         const destination = resolve(canonicalParent, basename(requestedPath));
         const existing = await lstat(destination).catch((cause) => {
@@ -38,37 +45,52 @@ export const writeTextFile = async (encoded, path, overwrite) => {
         });
         if (existing !== undefined) {
             if (!overwrite)
-                return err(new EvidenceFileError("write", "exists"));
+                return err(new EvidenceFileError("write", "exists", { path: requestedPath }));
             if (!existing.isFile() || existing.isSymbolicLink())
-                return err(new EvidenceFileError("write", "not-file"));
+                return err(new EvidenceFileError("write", "not-file", { path: requestedPath }));
         }
-        if (overwrite)
-            await writeFileAtomic(destination, encoded, {
-                encoding: "utf8",
-                mode: 0o600,
-                fsync: true,
-            });
-        else
-            await publishNewFile(destination, encoded);
+        const bytes = await publishFile(destination, parts, overwrite);
         return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
         if (!overwrite && fileErrorCode(cause) === "EEXIST")
-            return err(new EvidenceFileError("write", "exists", { cause }));
-        return err(new EvidenceFileError("write", "io", { cause }));
+            return err(new EvidenceFileError("write", "exists", {
+                cause,
+                path: requestedPath,
+            }));
+        return err(new EvidenceFileError("write", missingOrIo(cause), {
+            cause,
+            path: requestedPath,
+        }));
     }
 };
-const publishNewFile = async (destination, encoded) => {
+/** A missing path or parent is a selection error, not a permission failure. */
+const missingOrIo = (cause) => {
+    const code = fileErrorCode(cause);
+    return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "io";
+};
+const publishFile = async (destination, parts, overwrite) => {
     const stagingDirectory = await mkdtemp(resolve(dirname(destination), ".rea-write-"));
     try {
         const staged = resolve(stagingDirectory, "content");
-        await writeFileAtomic(staged, encoded, {
-            encoding: "utf8",
-            mode: 0o600,
-            fsync: true,
-        });
+        const file = await open(staged, "wx", 0o600);
+        let bytes = 0;
+        try {
+            for (const part of parts) {
+                await file.writeFile(part, { encoding: "utf8" });
+                bytes += Buffer.byteLength(part, "utf8");
+            }
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (overwrite)
+            await rename(staged, destination);
         // A hard link publishes complete bytes atomically and cannot replace an existing name.
-        await link(staged, destination);
+        else
+            await link(staged, destination);
+        return bytes;
     }
     finally {
         await rm(stagingDirectory, { recursive: true, force: true });

package/dist/application/ProcedureAddressResolution.js

@@ -0,0 +1,11 @@
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Resolve a caller selector to an observed provider procedure identity. */
+export const resolveProcedureAddress = async (call, procedure, signal) => {
+    const result = await call("procedure_address", { procedure }, signal);
+    if (!result.ok)
+        return result;
+    return typeof result.value === "string" && result.value.length > 0
+        ? ok(result.value)
+        : err(new AnalysisOutputError("procedure_address", "provider returned no canonical procedure address"));
+};

package/dist/application/ReconstructionCoverageService.js

@@ -1,20 +1,23 @@
+import { z } from "zod";
 import { reconstructionCoverageEvaluationInputSchema } from "../domain/reconstructionCoverageInput.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { evaluateReconstructionClosure } from "../domain/reconstructionCoverage.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { requestInputError, workflowInputError } from "./workflowInputError.js";
+const OPERATION = "evaluate_reconstruction_coverage";
 /** Evaluate inline reconstruction coverage against a named boundary. */
 export const evaluateReconstructionCoverage = (rawInput, nowEpochMs = Date.now()) => {
     const parsed = reconstructionCoverageEvaluationInputSchema.safeParse(rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError("evaluate_reconstruction_coverage", {
-            cause: parsed.error,
-        }));
+        return err(requestInputError(OPERATION, parsed.error, rawInput));
     try {
         return ok(jsonValueSchema.parse(evaluateReconstructionClosure(parsed.data.coverage, parsed.data.boundary_id, nowEpochMs)));
     }
     catch (cause) {
-        return err(new AnalysisInputError("evaluate_reconstruction_coverage", { cause }));
+        return err(cause instanceof TypeError || cause instanceof z.ZodError
+            ? workflowInputError(OPERATION, cause)
+            : new AnalysisInputError(OPERATION, { cause }));
     }
 };

package/dist/application/ReconstructionObligationLedgerService.js

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
 import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedgerSchema, } from "../domain/reconstructionObligationLedgerSchemas.js";
 import { err, ok } from "../domain/result.js";
+import { requestInputError, workflowInputError } from "./workflowInputError.js";
 import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "./InvestigationProviders.js";
 import { deriveReconstructionObligationCandidates } from "./ReconstructionObligationCandidates.js";
 import { evaluateReconstructionObligationLedger } from "./ReconstructionObligationLedgerEvaluation.js";
@@ -14,7 +15,7 @@ export const resolveReconstructionObligationLedgerRequest = (input) => {
     const parsed = reconstructionObligationLedgerInputSchema.safeParse(input);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisInputError(OPERATION, { cause: parsed.error }));
+        : err(requestInputError(OPERATION, parsed.error, input));
 };
 /** Build the complete deterministic ledger and wrap it in portable Evidence. */
 export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
@@ -30,7 +31,7 @@ export const buildReconstructionObligationLedgerEvidenceValidated = (input) => {
     }
     catch (cause) {
         if (cause instanceof z.ZodError)
-            return err(new AnalysisInputError(OPERATION, { cause }));
+            return err(workflowInputError(OPERATION, cause));
         return err(new AnalysisProtocolError("Reconstruction obligation ledger generation failed", { cause }));
     }
 };

package/dist/application/Setup.js

@@ -1,3 +1,4 @@
+import { manualRegistrationRemediation, } from "./SupportedClients.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { discoverSetupState, planSetupActions } from "./SetupPlan.js";
 import { filterClientsNeedingConfigure, hostRemediation, initialProviderEnvironment, setupRegistrationCommand, systemSetupHost, } from "./SetupHost.js";
@@ -109,6 +110,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         clientsToConfigure: planned.clientsToConfigure,
     };
     readinessScope = resolvedReadinessScope(options.readinessScope, planSelection);
+    const manualRemediation = manualClientsRemediation(planned.selectedClients);
     if (options.dryRun === true)
         return {
             status: "planned",
@@ -117,6 +119,9 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             clients,
             doctor: summarizeDoctor(discovery.initialDoctor),
             clientStates,
+            ...(manualRemediation === undefined
+                ? {}
+                : { remediation: manualRemediation }),
         };
     let approved = options.approved || plannedActions.length === 0;
     let interactiveApproval = false;
@@ -183,7 +188,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         !(await installSkillAction(host, options, appliedActions)))
         return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
     const doctor = summarizeDoctor(await host.doctor(readinessScope));
-    const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
+    const remediation = combineRemediation(finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath), manualRemediation);
     return {
         status: remediation === undefined ? "ready" : "needs_human",
         plannedActions,
@@ -277,6 +282,13 @@ const setupFailure = async (remediation, [host, plannedActions, appliedActions,
     };
 };
 const emitProgress = (options, event) => options.onProgress?.(event);
+const manualClientsRemediation = (clients) => clients
+    .map((client) => manualRegistrationRemediation(client.name))
+    .find((remediation) => remediation !== undefined);
+const combineRemediation = (...parts) => {
+    const present = parts.filter((part) => part !== undefined && part !== "");
+    return present.length === 0 ? undefined : present.join(" ");
+};
 const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
     if (platform === "darwin" && installedHopper)
         return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";

package/dist/application/SetupClientConfiguration.js

@@ -1,21 +1,13 @@
-import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
+import { clientRegistrationEntry, clientConfigurationValuesEqual, clientServerPath, grokServerListedDisabled, legacyClientServerPath, parseClientConfiguration, serializeClientConfiguration, withClientServers, } from "./ClientConfigurationDocument.js";
 import { constants as fsConstants } from "node:fs";
 import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-const defaultCommand = () => [
-    "npx",
-    "-y",
-    PRODUCT_IDENTITY.registrationPackageSpecifier,
-    "mcp",
-];
-/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
-export const configureJsonClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "json");
-/** Back up, atomically update, and semantically read back one TOML MCP configuration. */
-export const configureTomlClient = (client, environment = {}, command = defaultCommand()) => configureClientDocument(client, environment, command, "toml");
+const defaultCommand = () => npxRegistrationCommand();
 /** Configure one supported client's native stdio MCP registration shape. */
 export const configureClientConfiguration = (client, environment = {}, command = defaultCommand()) => {
     if (client.format === undefined || client.format === "unsupported")
@@ -36,7 +28,7 @@ const configureClientDocument = async (client, environment, command, format) =>
     }
     let parsed;
     try {
-        parsed = parseClientConfiguration(original ?? (format === "toml" ? "" : "{}"), format);
+        parsed = parseClientConfiguration(original ?? (format === "toml" || format === "grok" ? "" : "{}"), format);
     }
     catch (cause) {
         // Malformed existing configuration fails the readback gate.
@@ -163,14 +155,17 @@ const restoreConfig = async (path, original) => {
         void cause;
     }
 };
-/** Whether REA's entry matches and no conflicting legacy entry remains. */
-const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) && !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey);
+/** Whether REA's entry matches, no legacy entry remains, and Grok is not suppressing it. */
+const registrationCurrent = (parsed, desired) => clientConfigurationValuesEqual(parsed.servers[PRODUCT_IDENTITY.mcpServerKey], desired) &&
+    !Object.hasOwn(parsed.legacyServers, PRODUCT_IDENTITY.mcpServerKey) &&
+    !(parsed.dialect === "grok" &&
+        grokServerListedDisabled(parsed.document, PRODUCT_IDENTITY.mcpServerKey));
 const clientConfigurationDesired = (client, providerEnvironment, command, format) => {
     const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
     const registration = clientRegistrationEntry(format ?? "json", command.length === 0 ? [PRODUCT_IDENTITY.cliBinary, "mcp"] : command, environment);
     return {
         ...registration,
-        ...(client.name === "codex"
+        ...(client.name === "codex" || client.name === "grok_build"
             ? {
                 startup_timeout_sec: MCP_STARTUP_POLICY.codexStartupTimeoutSeconds,
             }

package/dist/application/SetupHost.js

@@ -2,6 +2,7 @@ import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { SUPPORTED_NODE_VERSION_PROSE, supportsNodeVersion, } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution } from "./LinuxHopper.js";
@@ -13,7 +14,7 @@ import { setupInstallFailure } from "./SetupInstallFailure.js";
 import { providerRegistrationEnvironment } from "./SetupRegistrationEnvironment.js";
 /** Resolve the executable and arguments used in a managed MCP registration. */
 export const setupRegistrationCommand = (platform, useNpmRunner = process.env.npm_command === "exec") => useNpmRunner
-    ? PRODUCT_IDENTITY.mcpCommand.split(" ")
+    ? npxRegistrationCommand(platform)
     : platform === "win32"
         ? [
             process.execPath,
@@ -92,7 +93,9 @@ export const systemSetupHost = (doctorHost = systemDoctorHost()) => {
         configureClient: (client, providerEnvironment, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
             : configureClientConfiguration(client, providerEnvironment, command),
-        clientNeedsConfigure: (client, providerEnvironment, command) => clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
+        clientNeedsConfigure: (client, providerEnvironment, command) => client.format === "unsupported"
+            ? Promise.resolve(false)
+            : clientConfigurationAligned(client, providerEnvironment, command).then((aligned) => !aligned),
         inspectClientConfiguration: inspectClientConfiguration,
         skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
         installSkill: () => installCanonicalSkill(homedir()),

package/dist/application/SetupPlan.js

@@ -96,9 +96,11 @@ export const planSetupActions = async (input) => {
             blocker: `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`,
         };
     }
-    const clientPlans = inspections.flatMap(({ client, inspection }) => inspection.status === "create" ||
-        inspection.status === "update" ||
-        (input.discovery.installHopper && inspection.status === "already_current")
+    const clientPlans = inspections.flatMap(({ client, inspection }) => client.format !== "unsupported" &&
+        (inspection.status === "create" ||
+            inspection.status === "update" ||
+            (input.discovery.installHopper &&
+                inspection.status === "already_current"))
         ? [
             {
                 client,

package/dist/application/SupportedClients.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { lstatSync } from "node:fs";
 const vscodeUserDirectory = ({ home, platform, env, }) => {
     if (platform === "win32")
@@ -17,6 +17,23 @@ const claudeDesktopDirectory = ({ home, platform, env, }) => {
 const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? home;
 const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
 const codexDirectory = ({ home, env }) => env.CODEX_HOME ?? join(home, ".codex");
+const grokDirectory = ({ home, env }) => env.GROK_HOME ?? join(home, ".grok");
+/** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
+const grokBotDirectory = ({ home, env }) => {
+    const root = env.SAND_DATA_ROOT;
+    return root !== undefined && root !== "" && isAbsolute(root)
+        ? root
+        : join(home, ".grokbot");
+};
+/**
+ * Grok Bot stores connectors in the signed-in account and runs them on its
+ * hosted computer. The data directory is only a detection marker.
+ */
+export const GROK_BOT_MANUAL_REGISTRATION_REMEDIATION = "Grok Bot keeps connectors in the signed-in account and runs them on its hosted computer. Setup does not write that account store, and a data-directory mcp.json is not a registration. In the Grok Bot chat, add a custom MCP server named rea that runs on the Bot's computer with `npx -y rea-agents@<version> mcp`. Do not put credentials in the command or arguments. A stdio server on this machine is not attached.";
+/** Remediation for a client whose connector is not a local configuration file. */
+export const manualRegistrationRemediation = (clientName) => clientName === "grok_bot"
+    ? GROK_BOT_MANUAL_REGISTRATION_REMEDIATION
+    : undefined;
 const copilotDirectory = ({ home, env }) => env.COPILOT_HOME ?? join(home, ".copilot");
 const commandCodeDirectory = ({ home }) => join(home, ".commandcode");
 const opencodeDirectory = ({ home, env }) => join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode");
@@ -133,6 +150,20 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
         markerPath: vscodeUserDirectory,
         format: "vscode",
     },
+    {
+        name: "grok_build",
+        displayName: "Grok Build",
+        configPath: (context) => join(grokDirectory(context), "config.toml"),
+        markerPath: grokDirectory,
+        format: "grok",
+    },
+    {
+        name: "grok_bot",
+        displayName: "Grok Bot",
+        configPath: grokBotDirectory,
+        markerPath: grokBotDirectory,
+        format: "unsupported",
+    },
 ];
 const resolvePath = (path, context) => typeof path === "function" ? path(context) : join(context.home, ...path);
 /** Describe every client location that setup, doctor, or uninstall may inspect. */
@@ -141,7 +172,9 @@ export const supportedClients = (home, platform = process.platform, env = {
     CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
     CODEX_HOME: process.env.CODEX_HOME,
     COPILOT_HOME: process.env.COPILOT_HOME,
+    GROK_HOME: process.env.GROK_HOME,
     OPENCODE_CONFIG: process.env.OPENCODE_CONFIG,
+    SAND_DATA_ROOT: process.env.SAND_DATA_ROOT,
     XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
 }) => {
     const context = { home, platform, env };

package/dist/application/Uninstall.js

@@ -7,7 +7,7 @@ import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
-import { supportedClients } from "./SupportedClients.js";
+import { manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
 const systemFileSystem = {
     readText: (path) => readFile(path, "utf8"),
     copy: (source, destination) => copyFile(source, destination),
@@ -62,7 +62,8 @@ export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSys
 });
 const removeClient = async (client, fileSystem) => {
     if (client.format === "unsupported")
-        return item(client.name, "skipped", "This client has no documented local MCP configuration boundary.");
+        return item(client.name, "skipped", manualRegistrationRemediation(client.name) ??
+            "This client has no documented local MCP configuration boundary.");
     const resolved = await resolveUninstallConfigPath(client, fileSystem);
     if (typeof resolved !== "string")
         return resolved;
@@ -82,7 +83,7 @@ const removeClient = async (client, fileSystem) => {
     }
     catch (cause) {
         void cause;
-        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
+        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" || client.format === "grok" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
     }
     const name = PRODUCT_IDENTITY.mcpServerKey;
     // Beside a native OpenCode V2 table, OpenCode also loads a V1 `mcp.rea`.

package/dist/application/Update.js

@@ -25,6 +25,23 @@ export const updateInstallCommand = (installation, version) => [
     installation.prefix,
     `${PRODUCT_IDENTITY.packageName}@${version}`,
 ];
+const versionCheckRemediation = (release) => {
+    if (release.ok) {
+        return "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update.";
+    }
+    const failure = release.error;
+    const kind = failure.kind;
+    switch (kind) {
+        case "unavailable":
+            return `REA could not resolve the latest release: ${failure.detail}. Retry rea update when registry access is available.`;
+        case "invalid-metadata":
+            return `REA could not resolve the latest release: ${failure.detail}. Check the npm release metadata, then rerun rea update.`;
+        default: {
+            const exhaustive = kind;
+            throw new TypeError(`Unhandled release lookup failure: ${String(exhaustive)}`);
+        }
+    }
+};
 /** Identify, resolve, install, and verify REA without applying setup changes. */
 export const runUpdate = async (currentVersion, host, output = "human") => {
     const installation = await host.installation();
@@ -37,9 +54,7 @@ export const runUpdate = async (currentVersion, host, output = "human") => {
             currentVersion,
             latestVersion,
             reason: "version-check",
-            remediation: release.ok
-                ? "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update."
-                : `REA could not resolve the latest release: ${release.error}. Retry rea update when registry access is available.`,
+            remediation: versionCheckRemediation(release),
         };
     if (!gt(targetVersion, currentVersion))
         return {

package/dist/application/UpdateRuntime.js

@@ -3,9 +3,9 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import spawn from "cross-spawn";
-import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
 import { updateInstallCommand, } from "./Update.js";
 import { planIntegrationMaintenance } from "./UpdateMaintenance.js";
 /** Run an updater subprocess with complete diagnostics and isolated machine output. */
@@ -85,6 +85,50 @@ export const detectNpmInstallation = async (packageRoot, host) => {
         return undefined;
     return { prefix: dirname(library), packageRoot: canonicalPackageRoot };
 };
+const INVALID_NPM_RELEASE_METADATA = "Invalid npm release metadata: expected a version string or a single-element version array.";
+/** npm view arguments for dist-tags.latest, scoped to the owning prefix when known. */
+export const npmLatestVersionCommand = (installation) => [
+    "npm",
+    "view",
+    "--global",
+    ...(installation === undefined ? [] : ["--prefix", installation.prefix]),
+    PRODUCT_IDENTITY.packageName,
+    "dist-tags.latest",
+    "--json",
+    "--fetch-retries=0",
+    "--fetch-timeout=10000",
+];
+/**
+ * Read one latest version from `npm view --json`.
+ * npm 11 emits a JSON string. npm 12 emits that string as a one-element array.
+ */
+export const parseNpmLatestVersion = (metadata) => {
+    const decoded = safeParseJson(metadata);
+    if (!decoded.ok)
+        return err(decoded.error);
+    const version = readNpmLatestVersion(decoded.value);
+    return version === undefined
+        ? err(INVALID_NPM_RELEASE_METADATA)
+        : ok(version);
+};
+const readNpmLatestVersion = (value) => {
+    if (typeof value === "string")
+        return nonemptyVersion(value);
+    if (!Array.isArray(value) || value.length !== 1)
+        return undefined;
+    const only = value[0];
+    return typeof only === "string" ? nonemptyVersion(only) : undefined;
+};
+const nonemptyVersion = (value) => value.length === 0 ? undefined : value;
+/** Classify npm view output as a version or a lookup failure. */
+export const npmReleaseLookup = (response) => {
+    if (!response.ok)
+        return err({ kind: "unavailable", detail: response.error });
+    const parsed = parseNpmLatestVersion(response.value);
+    return parsed.ok
+        ? ok(parsed.value)
+        : err({ kind: "invalid-metadata", detail: parsed.error });
+};
 /** Create npm, registry, verification, and read-only maintenance effects. */
 export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = homedir()) => ({
     installation: () => detectNpmInstallation(packageRoot, {
@@ -92,30 +136,7 @@ export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", im
         globalRoot: () => requireCommandOutput(["npm", "root", "--global"]),
         globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"]),
     }),
-    latestVersion: async (installation) => {
-        const response = await runUpdateCommand([
-            "npm",
-            "view",
-            "--global",
-            ...(installation === undefined ? [] : ["--prefix", installation.prefix]),
-            PRODUCT_IDENTITY.packageName,
-            "dist-tags.latest",
-            "--json",
-            "--fetch-retries=0",
-            "--fetch-timeout=10000",
-        ]);
-        if (!response.ok)
-            return response;
-        try {
-            const parsed = z.string().min(1).safeParse(JSON.parse(response.value));
-            return parsed.success
-                ? ok(parsed.data)
-                : err(`Invalid npm release metadata: ${parsed.error.message}`);
-        }
-        catch (cause) {
-            return err(cause instanceof Error ? cause.message : String(cause));
-        }
-    },
+    latestVersion: async (installation) => npmReleaseLookup(await runUpdateCommand(npmLatestVersionCommand(installation))),
     installVersion: async (installation, version, output) => {
         const result = await runUpdateCommand(updateInstallCommand(installation, version), output);
         return result.ok ? ok(undefined) : result;

package/dist/application/WebModuleTraceService.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { err, ok } from "../domain/result.js";
 import { collectWebModuleImports, matchCapturedModules, } from "../domain/webModuleImports.js";
 import { webModuleTraceInputSchema, webModuleFileSchema, webModuleResolutionSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
@@ -48,7 +48,9 @@ export class WebModuleTraceService {
             return err(new AnalysisCancelledError(OPERATION));
         const parsed = webModuleTraceInputSchema.safeParse(rawInput);
         if (!parsed.success)
-            return err(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+            return err(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         for (const [path, value] of [
             ["manifest_path", input.manifest_path],

package/dist/application/WebNetworkCaptureService.js

@@ -4,7 +4,7 @@ import { redactExplicitText } from "../domain/explicitSensitiveValues.js";
 import { isAbsolute } from "node:path";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { inspectWebNetworkCaptureInputSchema, webNetworkCaptureSchema, } from "../domain/webNetworkCapture.js";
@@ -27,7 +27,9 @@ export class WebNetworkCaptureService {
         const failure = (error) => err(redactExplicitFailure(error, declarations.success ? declarations.data : []));
         const parsed = inspectWebNetworkCaptureInputSchema.safeParse(rawInput);
         if (!parsed.success)
-            return failure(new AnalysisInputError(OPERATION, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+            return failure(analysisInputErrorFromIssues(OPERATION, parsed.error.issues, rawInput, {
+                cause: parsed.error,
+            }));
         const input = parsed.data;
         if (!isAbsolute(input.capture_path))
             return failure(new AnalysisInputError(OPERATION, undefined, [

package/dist/application/WebRuntimeService.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonObjectSchema, jsonValueSchema } from "../domain/jsonValue.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { err, ok } from "../domain/result.js";
 import { observeWebExecutionInputSchema, webExecutionSchema, } from "../domain/webExecution.js";
 import { inspectWebEventListenersInputSchema, webEventListenersSchema, } from "../domain/webEventListeners.js";
@@ -69,5 +69,7 @@ const parseInput = (schema, rawInput, operation, options) => {
     const parsed = schema.safeParse(rawInput);
     return parsed.success
         ? ok(parsed.data)
-        : err(new AnalysisInputError(operation, { cause: parsed.error }, projectInputIssues(parsed.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(operation, parsed.error.issues, rawInput, {
+            cause: parsed.error,
+        }));
 };

package/dist/application/WebScriptExportService.js

@@ -7,7 +7,7 @@ import { publishWebScripts } from "../browser/assets/PublishWebScripts.js";
 import { selectScriptCapture } from "../browser/assets/ScriptCaptureAdapters.js";
 import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
@@ -21,7 +21,7 @@ export const exportWebScripts = async (rawInput, options = {}) => {
     const input = exportWebScriptsInputSchema.safeParse(rawInput);
     return input.success
         ? exportWebScriptsValidated(input.data, options)
-        : err(new AnalysisInputError(OPERATION, undefined, projectInputIssues(input.error.issues, rawInput)));
+        : err(analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput));
 };
 /** Publish input already parsed by a named adapter contract. */
 export const exportWebScriptsValidated = async (input, options = {}) => {