rea-agents 3.2.1 → 4.0.0

package/dist/application/BinaryTargetResolver.js

@@ -7,6 +7,7 @@ import { promisify } from "node:util";
 import { isPathWithinRoot } from "../domain/localPath.js";
 import { BinaryTargetError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
+import { mzWindowsHeaderOffset } from "../domain/dosMz.js";
 import { hasZipSignature, zipPackageFormatForPath, } from "../domain/zipPackageFormat.js";
 import { parseExecutableHeader, parsePeRecord, } from "../domain/binaryTarget.js";
 const execFileAsync = promisify(execFile);
@@ -64,7 +65,30 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         }
     }
     catch (cause) {
-        return err(new BinaryTargetError(candidate, "path is not readable", { cause }));
+        if (!(cause instanceof Error))
+            throw cause;
+        const code = filesystemErrorCode(cause);
+        if (code === undefined)
+            throw cause;
+        return err(new BinaryTargetError(candidate, targetFailureReason(code, cause.message), { cause }));
+    }
+};
+const filesystemErrorCode = (cause) => {
+    const code = Reflect.get(cause, "code");
+    return typeof code === "string" ? code : undefined;
+};
+const targetFailureReason = (code, detail) => {
+    switch (code) {
+        case "ENOENT":
+        case "ENOTDIR":
+            return `target does not exist or a path component is not a directory: ${detail}`;
+        case "EACCES":
+        case "EPERM":
+            return `permission denied while reading target: ${detail}`;
+        case "EISDIR":
+            return `target is a directory, not a readable file: ${detail}`;
+        default:
+            return `target could not be read (${code}): ${detail}`;
     }
 };
 const detectArtifactFormat = async (path, handle) => {
@@ -181,9 +205,28 @@ const readExecutableMetadata = async (handle, hostArchitecture) => {
     const prefix = Buffer.alloc(4096);
     const prefixRead = await handle.read(prefix, 0, prefix.length, 0);
     const bytes = prefix.subarray(0, prefixRead.bytesRead);
-    if (bytes.length >= 64 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
-        const offset = bytes.readUInt32LE(0x3c);
-        return readPeMetadata(handle, offset);
+    if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) {
+        const offset = mzWindowsHeaderOffset(bytes);
+        if (offset !== null) {
+            if (offset < 64)
+                return err("invalid Windows new-header offset in MZ image");
+            return readPeMetadata(handle, offset);
+        }
+        // MZ relocation records may extend past the initial probe; their format
+        // bounds are at most 65535 records inside a 65535-paragraph header.
+        const tableEnd = bytes.length >= 28
+            ? bytes.readUInt16LE(24) + bytes.readUInt16LE(6) * 4
+            : 0;
+        const headerBytes = bytes.length >= 28 ? bytes.readUInt16LE(8) * 16 : 0;
+        const fileSize = (await handle.stat()).size;
+        if (tableEnd > bytes.length &&
+            tableEnd <= headerBytes &&
+            tableEnd <= fileSize) {
+            const table = Buffer.alloc(tableEnd);
+            const observed = await handle.read(table, 0, table.length, 0);
+            return parseExecutableHeader(table.subarray(0, observed.bytesRead), hostArchitecture, fileSize);
+        }
+        return parseExecutableHeader(bytes, hostArchitecture, fileSize);
     }
     if (bytes.length >= 8) {
         const magic = bytes.readUInt32BE(0);
@@ -205,6 +248,9 @@ const readPeMetadata = async (handle, offset) => {
     const fileHeaderRead = await handle.read(fileHeader, 0, fileHeader.length, offset);
     if (fileHeaderRead.bytesRead !== fileHeader.length)
         return err("invalid or truncated PE header");
+    const signature = fileHeader.toString("ascii", 0, 2);
+    if (["NE", "LE", "LX"].includes(signature))
+        return err(`unsupported ${signature} executable in MZ image`);
     const optionalHeaderSize = fileHeader.readUInt16LE(20);
     if (optionalHeaderSize > 4096)
         return err("invalid PE optional header size");

package/dist/application/BrowserEvidence.js

@@ -1,25 +1,31 @@
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
 import { commitBrowserScenarioNormalization } from "../domain/browserScenarioNormalization.js";
-/** Create Evidence for a policy-scoped external browser observation. */
+/** Create Evidence for one request-scoped external browser observation. */
 export const createBrowserEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
     predicateType: browserPredicate(operation),
     operation,
-    parameters: browserParameters(input),
+    parameters: browserParameters(input, result),
     result: jsonValueSchema.parse(result),
     confidence: "observed",
     authority: "external-service",
     environment: "browser" in result
         ? {
             id: `${result.browser.product}@${result.browser.revision}`,
-            platform: process.platform,
-            architecture: process.arch,
+            platform: "unknown",
+            architecture: "unknown",
             isolation: "none",
         }
         : null,
-    limitations: result.limitations,
+    limitations: [
+        ...result.limitations,
+        ...("browser" in result
+            ? ["Browser host platform and architecture were not observed."]
+            : []),
+    ],
 });
-const browserParameters = (input) => {
+const browserParameters = (input, result) => {
     if (!("cdp_endpoint" in input)) {
         if ("before_scenario" in input &&
             input.before_scenario !== undefined &&
@@ -50,9 +56,14 @@ const browserParameters = (input) => {
             };
         throw new Error("Browser comparison input did not match a comparison type");
     }
+    const observedOrigin = browserResultTargetOrigin(result);
     const scope = {
         cdp_endpoint: input.cdp_endpoint,
-        allowed_origins: input.allowed_origins,
+        allowed_origins: input.allowed_origins.length > 0
+            ? input.allowed_origins
+            : "target_id" in input && observedOrigin !== undefined
+                ? [observedOrigin]
+                : [],
     };
     if (!("target_id" in input))
         return scope;
@@ -80,6 +91,24 @@ const browserParameters = (input) => {
             : {}),
     };
 };
+const browserResultTargetOrigin = (result) => {
+    if ("inspection" in result &&
+        typeof result.inspection === "object" &&
+        result.inspection !== null &&
+        "target" in result.inspection &&
+        typeof result.inspection.target === "object" &&
+        result.inspection.target !== null &&
+        "origin" in result.inspection.target &&
+        typeof result.inspection.target.origin === "string")
+        return result.inspection.target.origin;
+    if (!("target" in result))
+        return undefined;
+    if ("origin" in result.target)
+        return result.target.origin;
+    if ("initial_url" in result.target)
+        return sanitizeBrowserUrl(result.target.initial_url).origin ?? undefined;
+    return undefined;
+};
 const isScreenshotComparison = (input) => "channel_threshold" in input;
 const browserPredicate = (operation) => {
     switch (operation) {

package/dist/application/BrowserObservationService.js

@@ -1,11 +1,9 @@
-import { projectPermissionFailure } from "./PermissionFailure.js";
-import { isLiteralLoopbackHostname, } from "../domain/browserObservation.js";
 import { AnalysisCapabilityUnavailableError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { createBrowserEvidence } from "./BrowserEvidence.js";
-/** Authorize and execute one policy-scoped target discovery observation. */
-export const listBrowserTargets = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "list_browser_targets");
+/** List browser targets within the endpoint and origin scope in the request. */
+export const listBrowserTargets = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "list_browser_targets");
     if (!ready.ok)
         return ready;
     const result = await ready.value.listTargets(input, options);
@@ -13,9 +11,9 @@ export const listBrowserTargets = async (browser, authority, input, options = {}
         ? ok(createBrowserEvidence("list_browser_targets", input, result.value, ready.value.identity()))
         : result;
 };
-/** Authorize and execute one policy-scoped passive page inspection. */
-export const inspectWebPage = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "inspect_web_page");
+/** Inspect one page within the endpoint and origin scope in the request. */
+export const inspectWebPage = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "inspect_web_page");
     if (!ready.ok)
         return ready;
     const result = await ready.value.inspectPage(input, options);
@@ -23,9 +21,9 @@ export const inspectWebPage = async (browser, authority, input, options = {}) =>
         ? ok(createBrowserEvidence("inspect_web_page", input, result.value, ready.value.identity()))
         : result;
 };
-/** Capture approved sources and derive bounded static web-bundle evidence. */
-export const analyzeWebBundle = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "analyze_web_bundle");
+/** Capture requested sources and derive static web-bundle evidence. */
+export const analyzeWebBundle = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "analyze_web_bundle");
     if (!ready.ok)
         return ready;
     const analyzed = await ready.value.analyzeBundle(input, options);
@@ -34,8 +32,8 @@ export const analyzeWebBundle = async (browser, authority, input, options = {})
     return ok(createBrowserEvidence("analyze_web_bundle", input, analyzed.value, ready.value.identity()));
 };
 /** Observe navigation caused by external user actions during one armed window. */
-export const observeWebSession = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "observe_web_session");
+export const observeWebSession = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "observe_web_session");
     if (!ready.ok)
         return ready;
     const observed = await ready.value.observeSession(input, options);
@@ -44,8 +42,8 @@ export const observeWebSession = async (browser, authority, input, options = {})
         : observed;
 };
 /** Discover WebMCP declarations without exposing an invocation surface. */
-export const discoverWebMcpTools = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "discover_webmcp_tools");
+export const discoverWebMcpTools = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "discover_webmcp_tools");
     if (!ready.ok)
         return ready;
     const discovered = await ready.value.discoverWebMcpTools(input, options);
@@ -63,9 +61,9 @@ export const compareWebCaptureEvidence = async (browser, input) => {
         ? ok(createBrowserEvidence("compare_web_captures", input, compared.value, ready.value.identity()))
         : compared;
 };
-/** Capture one explicitly approved visible-viewport screenshot. */
-export const captureWebScreenshot = async (browser, authority, input, options = {}) => {
-    const ready = await prepare(browser, authority, input, "capture_web_screenshot");
+/** Capture one visible-viewport screenshot for the requested target. */
+export const captureWebScreenshot = async (browser, input, options = {}) => {
+    const ready = requireBrowser(browser, "capture_web_screenshot");
     if (!ready.ok)
         return ready;
     const captured = await ready.value.captureScreenshot(input, options);
@@ -83,31 +81,6 @@ export const compareWebScreenshotEvidence = async (browser, input) => {
         ? ok(createBrowserEvidence("compare_web_screenshots", input, compared.value, ready.value.identity()))
         : compared;
 };
-const prepare = async (browser, authority, input, operation) => {
-    if (authority === undefined)
-        return err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation permission policy is not configured"));
-    const authorized = await authority.authorize({
-        capability: "browser_observe",
-        roots: [],
-        executables: [],
-        environment_names: [],
-        origins: [input.cdp_endpoint, ...input.allowed_origins],
-        network: browserNetworkScope(input.allowed_origins),
-        mount: false,
-        operation_identity: `${operation}:${input.target_id ?? input.cdp_endpoint}`,
-    }, "read");
-    if (!authorized.ok)
-        return err(projectPermissionFailure(authorized.error));
-    return browser === undefined
-        ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation provider is not configured"))
-        : ok(browser);
-};
 const requireBrowser = (browser, operation) => browser === undefined
-    ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser comparison provider is not configured"))
+    ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation provider is not configured"))
     : ok(browser);
-const browserNetworkScope = (allowedOrigins) => allowedOrigins.every((origin) => {
-    const hostname = new URL(origin).hostname;
-    return isLiteralLoopbackHostname(hostname);
-})
-    ? "loopback"
-    : "external";

package/dist/application/BrowserScenarioCaptureService.js

@@ -1,43 +1,10 @@
-import { projectPermissionFailure } from "./PermissionFailure.js";
 import { createBrowserScenarioEvidence } from "./BrowserScenarioEvidence.js";
-import { digestJson } from "./JavaScriptReplayPlanning.js";
 import { AnalysisCapabilityUnavailableError, } from "../domain/errors.js";
-import { isLiteralLoopbackHostname } from "../domain/browserObservation.js";
 import { err } from "../domain/result.js";
 const OPERATION = "capture_browser_scenario";
 const PROVIDER_ID = "rea-playwright-browser-scenario";
-const networkScope = (origins) => origins.every((origin) => isLiteralLoopbackHostname(new URL(origin).hostname))
-    ? "loopback"
-    : "external";
-const authorizeScenario = async (authority, scenario) => {
-    if (authority === undefined)
-        return err(new AnalysisCapabilityUnavailableError(PROVIDER_ID, OPERATION, "browser scenario permission policy is not configured"));
-    const authorized = await authority.authorize({
-        capability: "browser_automate",
-        roots: [],
-        executables: scenario.browser.mode === "launch"
-            ? [scenario.browser.executable_path]
-            : [],
-        environment_names: scenario.secrets.map(({ environment_variable: name }) => name),
-        origins: [
-            ...(scenario.browser.mode === "connect"
-                ? [scenario.browser.cdp_endpoint]
-                : []),
-            ...scenario.allowed_origins,
-        ],
-        network: networkScope(scenario.allowed_origins),
-        mount: false,
-        operation_identity: `${OPERATION}:${digestJson(scenario)}`,
-    }, "write");
-    if (!authorized.ok)
-        return err(projectPermissionFailure(authorized.error));
-    return { ok: true, value: true };
-};
-/** Authorize and execute one controlled browser scenario. */
-export const captureBrowserScenario = async (provider, authority, scenario, options = {}) => {
-    const authorized = await authorizeScenario(authority, scenario);
-    if (!authorized.ok)
-        return authorized;
+/** Execute one controlled browser scenario using its explicit request scope. */
+export const captureBrowserScenario = async (provider, scenario, options = {}) => {
     if (provider === undefined)
         return err(new AnalysisCapabilityUnavailableError(PROVIDER_ID, OPERATION, "browser scenario provider is not configured"));
     const captured = await provider.captureScenario(scenario, options);

package/dist/application/BrowserScenarioEvidence.js

@@ -1,22 +1,23 @@
 import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-import { digestJson } from "./JavaScriptReplayPlanning.js";
+import { digestCanonicalJson } from "../domain/browserScenarioNormalization.js";
 const browserScenarioParameters = (scenario) => ({
-    scenario_sha256: digestJson(scenario),
+    scenario_sha256: digestCanonicalJson(scenario),
     browser_mode: scenario.browser.mode,
+    ...(scenario.browser.mode === "launch"
+        ? { browser_headless: scenario.browser.headless }
+        : {}),
     start_url: sanitizeBrowserUrl(scenario.start_url.url),
-    allowed_origins: scenario.allowed_origins,
+    environment: scenario.environment,
     actions: scenario.actions.map(({ step_id, action }) => ({
         step_id,
         action,
     })),
     action_timeouts_ms: scenario.actions.map((item) => "timeout_ms" in item ? (item.timeout_ms ?? null) : null),
-    secret_declarations: scenario.secrets.map(({ secret_id, environment_variable, purpose, redaction }) => ({
+    secret_declarations: scenario.secrets.map(({ secret_id, environment_variable }) => ({
         secret_id,
         environment_variable,
-        purpose,
-        redaction,
     })),
     capture: scenario.capture,
 });
@@ -30,11 +31,14 @@ export const createBrowserScenarioEvidence = (scenario, capture, provider) => cr
     authority: "controlled-replay",
     environment: {
         id: `${capture.browser.product}@${capture.browser.version}`,
-        platform: process.platform,
-        architecture: process.arch,
+        platform: "unknown",
+        architecture: "unknown",
         isolation: capture.browser.process_ownership === "provider-owned"
             ? "process"
             : "none",
     },
-    limitations: capture.limitations,
+    limitations: [
+        ...capture.limitations,
+        "Browser host platform and architecture were not observed.",
+    ],
 });

package/dist/application/CapabilityClientRequirements.js

@@ -5,18 +5,9 @@ export const NO_CLIENT_FEATURES = {
     roots: false,
     sampling: false,
 };
-const CLIENT_FEATURE_REQUIREMENTS = {
-    capture_process_scenario: {
-        required: [],
-        optional: ["elicitation_form"],
-    },
-};
 /** Project a tool's client requirements against the negotiated feature set. */
-export const clientRequirementsFor = (name, clientFeatures) => {
-    const requirements = CLIENT_FEATURE_REQUIREMENTS[name] ?? {
-        required: [],
-        optional: [],
-    };
+export const clientRequirementsFor = (_name, clientFeatures) => {
+    const requirements = { required: [], optional: [] };
     return {
         required: [...requirements.required],
         optional: [...requirements.optional],

package/dist/application/CapabilityInventory.js

@@ -9,6 +9,7 @@ const statusSchema = z.object({
     capabilities: z.array(providerCapability),
 });
 const ENHANCED_REQUIREMENTS = {
+    trace_native_values: ["analyze_function", "resolve_native_call_targets"],
     trace_native_ui_action: [
         "decode_interface_builder",
         "list_names",
@@ -111,9 +112,9 @@ const availabilityFor = (context) => {
     const javascriptApplication = javascriptApplicationAvailability(context);
     if (javascriptApplication !== null)
         return javascriptApplication;
-    const policyDecision = policyAvailability(context);
-    if (policyDecision !== null)
-        return policyDecision;
+    const workflowAvailability = workflowAvailabilityFor(context);
+    if (workflowAvailability !== null)
+        return workflowAvailability;
     const targetDecision = targetAvailability(context);
     if (targetDecision !== null)
         return targetDecision;
@@ -126,78 +127,63 @@ const javascriptApplicationAvailability = ({ name, }) => {
         ? { reason: "available", remediation: null }
         : null;
 };
-const policyAvailability = ({ name, kind, policy, }) => {
-    const browser = browserPolicyAvailability(name, kind, policy);
+const workflowAvailabilityFor = ({ name, kind, policy, }) => {
+    const browser = browserProviderAvailability(name, kind, policy);
     if (browser !== null)
         return browser;
     if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
         return {
-            reason: "policy_disabled",
-            remediation: "Enable or grant process_capture within the administrator ceiling.",
-        };
-    if (name === "run_controlled_replay" && !policy.javascriptReplayEnabled)
-        return {
-            reason: "policy_disabled",
-            remediation: "Enable javascript_replay with exact source roots and sandbox executables.",
-        };
-    if (name === "run_controlled_replay")
-        return { reason: "available", remediation: null };
-    if (name === "plan_managed_runtime_correlation" &&
-        !policy.managedRuntimeEnabled)
-        return {
-            reason: "policy_disabled",
-            remediation: "Enable managed_runtime with exact artifact roots and a runtime executable.",
+            reason: "unsupported_host",
+            remediation: "Run process capture on a supported Linux or macOS host.",
         };
-    if (name === "plan_managed_runtime_correlation")
-        return { reason: "available", remediation: null };
     if (kind === "application")
         return { reason: "available", remediation: null };
-    const electron = electronPolicyAvailability(name, kind, policy);
+    const electron = electronProviderAvailability(name, kind, policy);
     if (electron !== null)
         return electron;
     if (kind === "runtime-provider")
         return policy.v8InspectorObservationEnabled === true
             ? { reason: "available", remediation: null }
             : {
-                reason: "policy_disabled",
-                remediation: "Enable V8 Inspector observation; pass the user's literal-loopback Inspector endpoint to the tool.",
+                reason: "provider_missing",
+                remediation: "Start REA with its JavaScript runtime provider available.",
             };
     if (kind === "session")
         return { reason: "available", remediation: null };
     return null;
 };
-const electronPolicyAvailability = (name, kind, policy) => {
+const electronProviderAvailability = (name, kind, policy) => {
     if (kind !== "electron-provider")
         return null;
     if (name === "capture_electron_scenario")
         return policy.electronAutomationEnabled === true
             ? { reason: "available", remediation: null }
             : {
-                reason: "policy_disabled",
-                remediation: "Enable active Electron automation and configure exact executable and application roots.",
+                reason: "provider_missing",
+                remediation: "Start REA with the Electron scenario provider available.",
             };
     return policy.electronObservationEnabled === true
         ? { reason: "available", remediation: null }
         : {
-            reason: "policy_disabled",
-            remediation: "Enable Electron observation; pass the user's literal-loopback CDP endpoint to the tool.",
+            reason: "provider_missing",
+            remediation: "Start REA with its Electron observation provider available.",
         };
 };
-const browserPolicyAvailability = (name, kind, policy) => {
+const browserProviderAvailability = (name, kind, policy) => {
     if (name === "capture_browser_scenario")
         return policy.browserScenarioEnabled === true
             ? { reason: "available", remediation: null }
             : {
-                reason: "policy_disabled",
-                remediation: "Enable browser scenarios and configure exact executable roots or loopback CDP endpoints, page origins, and environment secret names.",
+                reason: "provider_missing",
+                remediation: "Start REA with its browser scenario provider available.",
             };
     if (kind !== "browser-provider")
         return null;
     return policy.browserObservationEnabled === true
         ? { reason: "available", remediation: null }
         : {
-            reason: "policy_disabled",
-            remediation: "Enable browser observation and configure exact CDP endpoint and page origins.",
+            reason: "provider_missing",
+            remediation: "Start REA with its browser observation provider available.",
         };
 };
 const targetAvailability = ({ kind, targetKind, targetOpen, }) => {

package/dist/application/ClientConfigurationDocument.js

@@ -1,5 +1,6 @@
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify, parse as parseJsonc, printParseErrorCode, } from "jsonc-parser";
 import { z } from "zod";
 const objectSchema = z.record(z.string(), z.unknown());
 /** Compare parsed configuration values without depending on parser prototypes. */
@@ -13,15 +14,91 @@ const normalizeConfigurationValue = (value) => {
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([key, nested]) => [key, normalizeConfigurationValue(nested)]));
 };
-/** Parse the client format and reject malformed root or server-table values. */
+/** Return the top-level object used for MCP server registrations by a client. */
+export const clientConfigurationServersKey = (format) => {
+    switch (format) {
+        case "toml":
+            return "mcp_servers";
+        case "opencode":
+            return "mcp";
+        case "vscode":
+            return "servers";
+        default:
+            return "mcpServers";
+    }
+};
+const parseDocument = (text, format) => {
+    if (format === "toml")
+        return objectSchema.parse(parseToml(text));
+    const errors = [];
+    const document = parseJsonc(text, errors, { allowTrailingComma: true });
+    const firstError = errors[0];
+    if (firstError !== undefined)
+        throw new SyntaxError(`Invalid JSON/JSONC at offset ${firstError.offset}: ${printParseErrorCode(firstError.error)}`);
+    return objectSchema.parse(document);
+};
+/** Parse a client document and reject malformed roots or MCP server tables. */
 export const parseClientConfiguration = (text, format) => {
-    const document = objectSchema.parse(format === "toml" ? parseToml(text) : JSON.parse(text));
-    const serversKey = format === "toml" ? "mcp_servers" : "mcpServers";
+    if (format === undefined || format === "unsupported")
+        throw new TypeError("client does not have a supported MCP config format");
+    const document = parseDocument(text, format);
+    const serversKey = clientConfigurationServersKey(format);
     const value = document[serversKey];
     const servers = value === undefined ? {} : objectSchema.parse(value);
     return { document, servers, serversKey };
 };
-/** Serialize a validated client document using the selected format. */
-export const serializeClientConfiguration = (document, format) => format === "toml"
-    ? stringifyToml(document)
-    : `${JSON.stringify(document, null, 2)}\n`;
+/** Serialize a validated client document, retaining JSONC comments. */
+export const serializeClientConfiguration = (document, format, originalText, editedServerName) => {
+    if (format === undefined || format === "unsupported")
+        throw new TypeError("client does not have a supported MCP config format");
+    if (format === "toml")
+        return stringifyToml(document);
+    if (originalText !== undefined && editedServerName !== undefined) {
+        const serversKey = clientConfigurationServersKey(format);
+        const servers = objectSchema.parse(document[serversKey] ?? {});
+        const editedValue = Object.hasOwn(servers, editedServerName)
+            ? servers[editedServerName]
+            : undefined;
+        const edits = modify(originalText, [serversKey, editedServerName], editedValue, {
+            formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
+        });
+        return applyEdits(originalText, edits);
+    }
+    return `${JSON.stringify(document, null, 2)}\n`;
+};
+/** Build the stdio entry shape expected by one client's configuration dialect. */
+export const clientRegistrationEntry = (format, command, environment) => {
+    const [executable = "rea", ...args] = command;
+    switch (format) {
+        case "opencode":
+            return {
+                type: "local",
+                command: [...command],
+                enabled: true,
+                ...(Object.keys(environment).length === 0
+                    ? {}
+                    : { environment: { ...environment } }),
+            };
+        case "vscode":
+            return {
+                type: "stdio",
+                command: executable,
+                args,
+                ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+            };
+        case "copilot_cli":
+            return {
+                type: "stdio",
+                command: executable,
+                args,
+                tools: ["*"],
+                ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+            };
+        default:
+            return {
+                command: executable,
+                args,
+                ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+            };
+    }
+};

package/dist/application/ClientRegistrationIdentity.js

@@ -0,0 +1,32 @@
+import { basename, isAbsolute, resolve } from "node:path";
+import { valid } from "semver";
+import { PRODUCT_IDENTITY } from "../identity.js";
+/** Check that one parsed command points to REA's MCP entry point. */
+export const isOwnedClientRegistrationCommand = (command, currentCommandPath = resolve(process.argv[1] ?? "unknown")) => {
+    if (command.length === 3 &&
+        command[2] === "mcp" &&
+        resolve(command[0] ?? "") === resolve(process.execPath) &&
+        resolve(command[1] ?? "") === currentCommandPath)
+        return true;
+    if (command.length === 2 && command[1] === "mcp") {
+        const executable = command[0] ?? "";
+        if (executable === PRODUCT_IDENTITY.cliBinary ||
+            (isAbsolute(executable) &&
+                basename(executable) === PRODUCT_IDENTITY.cliBinary) ||
+            resolve(executable) === currentCommandPath)
+            return true;
+    }
+    if (command.length !== 4 ||
+        command[0] !== "npx" ||
+        command[1] !== "-y" ||
+        command[3] !== "mcp")
+        return false;
+    const packageReference = command[2] ?? "";
+    if (packageReference === PRODUCT_IDENTITY.packageName ||
+        packageReference === PRODUCT_IDENTITY.packageSpecifier ||
+        packageReference === PRODUCT_IDENTITY.registrationPackageSpecifier)
+        return true;
+    const versionPrefix = `${PRODUCT_IDENTITY.packageName}@`;
+    return (packageReference.startsWith(versionPrefix) &&
+        valid(packageReference.slice(versionPrefix.length)) !== null);
+};