rea-agents 1.3.0 → 1.5.0

package/dist/application/ProjectPermissionStore.js

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, stat, unlink, } from "node:fs/promises";
+import { dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+const grantSchema = z.object({
+    grant_id: z.string().min(1),
+    capability: z.enum([
+        "process_capture",
+        "browser_observe",
+        "evidence_read",
+        "evidence_write",
+        "investigation_input",
+        "investigation_workspace_read",
+        "investigation_workspace_write",
+        "snapshot_read",
+        "snapshot_write",
+        "artifact_extract",
+        "native_mount",
+        "reference_read",
+    ]),
+    roots: z.array(z.string()),
+    executables: z.array(z.string()),
+    environment_names: z.array(z.string()),
+    origins: z.array(z.string()).optional(),
+    network: z.enum(["none", "loopback", "external"]),
+    mount: z.boolean(),
+    lifetime: z.literal("project"),
+    operation_identity: z.string().nullable(),
+    expires_at: z.iso.datetime().nullable(),
+});
+const storeSchema = z.object({
+    schema_version: z.literal(1),
+    project_id: z.string().regex(/^project_[a-f0-9]{64}$/u),
+    project_root: z.string(),
+    grants: z.array(grantSchema).max(1_000),
+});
+/** Owner-only project policy persistence failure. */
+export class ProjectPermissionStoreError extends Error {
+    reason;
+    _tag = "ProjectPermissionStoreError";
+    constructor(reason, options) {
+        super(`Project permission store failed: ${reason}`, options);
+        this.reason = reason;
+    }
+}
+/** Derive relocation-explicit project identity from its canonical root. */
+const identifyPermissionProject = async (projectRoot) => {
+    try {
+        const root = await realpath(projectRoot);
+        return ok({
+            id: `project_${createHash("sha256").update(root).digest("hex")}`,
+            root,
+        });
+    }
+    catch (cause) {
+        return err(new ProjectPermissionStoreError("project_not_found", { cause }));
+    }
+};
+/** Read and validate an owner-only store bound to the requested project. */
+export const readProjectPermissionStore = async (path, projectRoot) => {
+    const project = await identifyPermissionProject(projectRoot);
+    if (!project.ok)
+        return project;
+    try {
+        const metadata = await stat(path);
+        if ((metadata.mode & 0o077) !== 0)
+            return err(new ProjectPermissionStoreError("not_owner_only"));
+        const encoded = await readFile(path, "utf8");
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded);
+        }
+        catch (cause) {
+            return err(new ProjectPermissionStoreError("invalid", { cause }));
+        }
+        const parsed = storeSchema.safeParse(decoded);
+        if (!parsed.success ||
+            parsed.data.project_id !== project.value.id ||
+            parsed.data.project_root !== project.value.root)
+            return err(new ProjectPermissionStoreError("invalid"));
+        return ok(parsed.data);
+    }
+    catch (cause) {
+        if (isNotFound(cause))
+            return ok(null);
+        return err(new ProjectPermissionStoreError("io", { cause }));
+    }
+};
+/** Atomically replace explicit project grants with owner-only permissions. */
+export const writeProjectPermissionStore = async (path, projectRoot, grants) => {
+    const project = await identifyPermissionProject(projectRoot);
+    if (!project.ok)
+        return project;
+    const candidate = storeSchema.safeParse({
+        schema_version: 1,
+        project_id: project.value.id,
+        project_root: project.value.root,
+        grants,
+    });
+    if (!candidate.success)
+        return err(new ProjectPermissionStoreError("invalid", { cause: candidate.error }));
+    try {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await writeFileAtomic(path, `${JSON.stringify(candidate.data, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        const metadata = await stat(path);
+        if ((metadata.mode & 0o077) !== 0) {
+            return err(new ProjectPermissionStoreError("not_owner_only"));
+        }
+        return ok(candidate.data);
+    }
+    catch (cause) {
+        return err(new ProjectPermissionStoreError("io", { cause }));
+    }
+};
+/** Revoke one grant while serializing the complete read-modify-write cycle. */
+export const revokeProjectPermissionGrant = async (path, projectRoot, grantId) => {
+    let lock;
+    try {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const acquired = await acquirePermissionStoreLock(path);
+        if (!acquired.ok)
+            return acquired;
+        lock = acquired.value;
+        const current = await readProjectPermissionStore(path, projectRoot);
+        if (!current.ok)
+            return current;
+        const grants = current.value?.grants ?? [];
+        const retained = grants.filter(({ grant_id }) => grant_id !== grantId);
+        if (retained.length === grants.length)
+            return ok(false);
+        const written = await writeProjectPermissionStore(path, projectRoot, retained);
+        return written.ok ? ok(true) : written;
+    }
+    catch (cause) {
+        return err(new ProjectPermissionStoreError("io", { cause }));
+    }
+    finally {
+        if (lock !== undefined)
+            await releasePermissionStoreLock(lock);
+    }
+};
+const acquirePermissionStoreLock = async (destination) => {
+    const path = `${destination}.lock`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            return ok(await createPermissionStoreLock(path));
+        }
+        catch (cause) {
+            if (!isAlreadyExists(cause))
+                return err(new ProjectPermissionStoreError("io", { cause }));
+            if (await removeStalePermissionStoreLock(path))
+                continue;
+            if (attempt === 99)
+                return err(new ProjectPermissionStoreError("locked", { cause }));
+            await delay(10);
+        }
+    }
+    return err(new ProjectPermissionStoreError("locked"));
+};
+const createPermissionStoreLock = async (path) => {
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(`${String(process.pid)}\n`, "utf8");
+        await handle.sync();
+        return { path, handle };
+    }
+    catch (cause) {
+        await handle.close().catch(() => undefined);
+        await unlink(path).catch(() => undefined);
+        throw cause;
+    }
+};
+const removeStalePermissionStoreLock = async (path) => {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 32)
+            return false;
+        const encoded = (await readFile(path, "utf8")).trim();
+        if (!/^[1-9][0-9]{0,9}$/u.test(encoded))
+            return false;
+        if (processIsAlive(Number(encoded)))
+            return false;
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const processIsAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return errorCode(cause) !== "ESRCH";
+    }
+};
+const releasePermissionStoreLock = async (lock) => {
+    await lock.handle.close().catch(() => undefined);
+    await unlink(lock.path).catch(() => undefined);
+};
+const isNotFound = (cause) => errorCode(cause) === "ENOENT";
+const isAlreadyExists = (cause) => errorCode(cause) === "EEXIST";
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? cause.code
+    : undefined;

package/dist/application/ReferenceSourceImportPolicy.js

@@ -4,6 +4,7 @@ import ignore from "ignore";
 import { err, ok } from "../domain/result.js";
 import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, DEFAULT_REFERENCE_SOURCE_LIMITS, } from "./ReferenceSourceImportTypes.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 const failure = (code, message) => ({
     tag: "reference-source-import",
     code,
@@ -29,8 +30,8 @@ const authorizeRoot = async (requestedRoot, approvedRoots) => {
         if (!(await stat(requestedRoot)).isDirectory())
             return err(failure("invalid-root", "Reference source root is not a directory"));
         const canonicalRoot = await realpath(resolve(requestedRoot));
-        for (const approvedRoot of approvedRoots) {
-            const canonicalApproved = await realpath(resolve(approvedRoot));
+        const canonicalApprovedRoots = await canonicalizeConfiguredRoots(approvedRoots.map((approvedRoot) => resolve(approvedRoot)));
+        for (const canonicalApproved of canonicalApprovedRoots) {
             if (withinRoot(canonicalApproved, canonicalRoot))
                 return ok(canonicalRoot);
         }

package/dist/application/Setup.js

@@ -1,6 +1,6 @@
 import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
@@ -10,6 +10,7 @@ import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
 import { configureDetectedClients } from "./SetupClients.js";
+import { supportedClients } from "./SupportedClients.js";
 import { installCanonicalSkill } from "./SetupSkill.js";
 import { setupPlan } from "./SetupPlan.js";
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
@@ -160,46 +161,6 @@ export const detectClients = async (home) => {
             detected.push(candidate);
     return detected;
 };
-/** Describe every client location that setup or uninstall may own. */
-export const supportedClients = (home) => [
-    {
-        name: "claude_code",
-        configPath: join(home, ".claude.json"),
-        markerPath: join(home, ".claude"),
-    },
-    {
-        name: "claude_desktop",
-        configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
-        markerPath: join(home, "Library/Application Support/Claude"),
-    },
-    {
-        name: "codex",
-        configPath: join(home, ".codex/config.toml"),
-        markerPath: join(home, ".codex"),
-        format: "toml",
-    },
-    {
-        name: "cursor",
-        configPath: join(home, ".cursor/mcp.json"),
-        markerPath: join(home, ".cursor"),
-    },
-    {
-        name: "gemini_cli",
-        configPath: join(home, ".gemini/settings.json"),
-        markerPath: join(home, ".gemini"),
-    },
-    {
-        name: "windsurf",
-        configPath: join(home, ".codeium/windsurf/mcp_config.json"),
-        markerPath: join(home, ".codeium/windsurf"),
-    },
-    {
-        name: "devin",
-        configPath: join(home, ".devin"),
-        markerPath: join(home, ".devin"),
-        format: "unsupported",
-    },
-];
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
 export const configureJsonClient = async (client, hopperPath, command = [
     "npx",

package/dist/application/SupportedClients.js

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+/** Describe every client location that setup, doctor, or uninstall may inspect. */
+export const supportedClients = (home) => [
+    {
+        name: "claude_code",
+        configPath: join(home, ".claude.json"),
+        markerPath: join(home, ".claude"),
+    },
+    {
+        name: "claude_desktop",
+        configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
+        markerPath: join(home, "Library/Application Support/Claude"),
+    },
+    {
+        name: "codex",
+        configPath: join(home, ".codex/config.toml"),
+        markerPath: join(home, ".codex"),
+        format: "toml",
+    },
+    {
+        name: "cursor",
+        configPath: join(home, ".cursor/mcp.json"),
+        markerPath: join(home, ".cursor"),
+    },
+    {
+        name: "gemini_cli",
+        configPath: join(home, ".gemini/settings.json"),
+        markerPath: join(home, ".gemini"),
+    },
+    {
+        name: "windsurf",
+        configPath: join(home, ".codeium/windsurf/mcp_config.json"),
+        markerPath: join(home, ".codeium/windsurf"),
+    },
+    {
+        name: "devin",
+        configPath: join(home, ".devin"),
+        markerPath: join(home, ".devin"),
+        format: "unsupported",
+    },
+];

package/dist/application/TerminalRenderer.js

@@ -49,7 +49,7 @@ export class TerminalRenderer {
     /** Await all queued parsing and return immutable rendered observations. */
     async frames() {
         await this.#pending;
-        return this.#frames;
+        return structuredClone(this.#frames);
     }
     /** Whether a rendered observation exceeded its independent capture budget. */
     truncated() {

package/dist/application/Uninstall.js

@@ -5,7 +5,7 @@ import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
-import { supportedClients } from "./Setup.js";
+import { supportedClients } from "./SupportedClients.js";
 const systemFileSystem = {
     readText: (path) => readFile(path, "utf8"),
     copy: (source, destination) => copyFile(source, destination),

package/dist/application/Upgrade.js

@@ -42,6 +42,8 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
         versionCheck: latestVersion === undefined ? "unavailable" : "available",
         installMethod: "npm",
         command: UPGRADE_COMMAND,
+        clientRestartRequired: true,
+        remediation: "Rerun rea setup to refresh registrations and the skill, then restart clients that may retain an older MCP server.",
     };
 };
 /** Create the npm registry and subprocess effects for a production upgrade. */

package/dist/application/runtime.js

@@ -11,7 +11,7 @@ import { silentLogger } from "../logger.js";
  */
 export const createBinarySession = (config, logger = silentLogger) => {
     return new BinarySession(new CompositeProvider([
-        new ArtifactProvider(config.artifactNativeMountEnabled),
+        new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled),
         new NativeMacOSProvider(),
         new HopperProvider(config, logger),
     ]), { snapshotsEnabled: config.hopperLoaderArgs.length === 0 });

package/dist/artifacts/ArtifactProvider.js

@@ -10,8 +10,10 @@ const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     nativeMountEnabled;
-    constructor(nativeMountEnabled = false) {
+    integrityContinueEnabled;
+    constructor(nativeMountEnabled = false, integrityContinueEnabled = false) {
         this.nativeMountEnabled = nativeMountEnabled;
+        this.integrityContinueEnabled = integrityContinueEnabled;
     }
     #capabilities = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) => Object.freeze({
         provider: IDENTITY,
@@ -48,15 +50,17 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target, this.nativeMountEnabled);
+        return new ArtifactClient(target, this.nativeMountEnabled, this.integrityContinueEnabled);
     }
 }
 class ArtifactClient {
     target;
     nativeMountEnabled;
-    constructor(target, nativeMountEnabled) {
+    integrityContinueEnabled;
+    constructor(target, nativeMountEnabled, integrityContinueEnabled) {
         this.target = target;
         this.nativeMountEnabled = nativeMountEnabled;
+        this.integrityContinueEnabled = integrityContinueEnabled;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -99,6 +103,12 @@ class ArtifactClient {
                     nativeMountApproved: parsed.native_mount_approved === true,
                     nativeMountEnabled: this.nativeMountEnabled,
                 },
+                integrity: {
+                    mode: parsed.integrity_policy,
+                    approved: parsed.integrity_continue_approved === true,
+                    enabled: this.integrityContinueEnabled,
+                    maxMismatches: parsed.max_integrity_mismatches,
+                },
             });
             return ok(createAnalysisExecution(result, IDENTITY, {
                 rawResult: null,

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -59,7 +59,7 @@ export class MachOSliceArtifactReader {
         return Promise.resolve(createReadStream(this.path, { start: offset, end: offset + size - 1 }));
     }
     provenance() {
-        return this.#command === undefined ? [] : [this.#command];
+        return this.#command === undefined ? [] : [structuredClone(this.#command)];
     }
     close() {
         return Promise.resolve();

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -67,7 +67,7 @@ export class NativeDmgArtifactReader {
         return this.#directory.open(entry, signal);
     }
     provenance() {
-        return this.#provenance;
+        return structuredClone(this.#provenance);
     }
     async close() {
         let detachFailure;

package/dist/artifacts/SafeOutputTree.js

@@ -59,7 +59,7 @@ export class SafeOutputTree {
         return this.#outputRoot;
     }
     get cleanup() {
-        return this.#cleanup;
+        return structuredClone(this.#cleanup);
     }
     /** Stream one selected regular file with exact byte and digest verification. */
     async write(relativePath, source, expectedSha256, signal) {
@@ -123,7 +123,7 @@ export class SafeOutputTree {
     /** Remove only this operation's unsealed tree and verify absence. */
     async rollback() {
         if (this.#published)
-            return this.#cleanup;
+            return structuredClone(this.#cleanup);
         await rm(this.#stagingRoot, { recursive: true, force: true });
         const absent = await isAbsent(this.#stagingRoot);
         this.#cleanup = {
@@ -133,7 +133,7 @@ export class SafeOutputTree {
         };
         if (!absent)
             throw new ArtifactReaderFailure("integrity", "Extraction output cleanup could not be verified");
-        return this.#cleanup;
+        return structuredClone(this.#cleanup);
     }
     async #prepareParent(relativePath) {
         const parts = relativePath.split("/");

package/dist/browser/CdpBrowserProvider.js

@@ -0,0 +1,158 @@
+import { browserTargetListSchema, sanitizeBrowserUrl, webPageInspectionSchema, } from "../domain/browserObservation.js";
+import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { CdpConnection } from "./CdpConnection.js";
+import { discoverCdpEndpoint, } from "./CdpEndpoint.js";
+import { capturePage } from "./CdpPageCapture.js";
+const IDENTITY = {
+    id: "rea-cdp-browser",
+    name: "REA Chrome DevTools Protocol observation provider",
+    version: "1",
+};
+/** Passive, origin-scoped browser observation through a user-owned CDP endpoint. */
+export class CdpBrowserProvider {
+    identity() {
+        return IDENTITY;
+    }
+    async listTargets(input, options = {}) {
+        try {
+            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "list_browser_targets", options.signal);
+            const allowedOrigins = new Set(input.allowed_origins);
+            const selected = selectTargets(discovery, allowedOrigins);
+            const items = selected.allowed.slice(input.offset, input.offset + input.limit);
+            const nextOffset = input.offset + items.length;
+            return ok(browserTargetListSchema.parse({
+                schema_version: 1,
+                browser: discovery.version,
+                targets: {
+                    items,
+                    offset: input.offset,
+                    limit: input.limit,
+                    total: selected.allowed.length,
+                    next_offset: nextOffset < selected.allowed.length ? nextOffset : null,
+                    has_more: nextOffset < selected.allowed.length,
+                },
+                excluded: selected.excluded,
+                limitations: [
+                    "Only page targets whose current URL matches an approved exact origin are listed.",
+                ],
+            }));
+        }
+        catch (cause) {
+            return err(providerError(cause, "list_browser_targets"));
+        }
+    }
+    async inspectPage(input, options = {}) {
+        let connection;
+        let sessionId;
+        try {
+            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, "inspect_web_page", options.signal);
+            const target = authorizeTarget(discovery, input);
+            connection = await CdpConnection.connect(discovery.browserWebSocketUrl, options.signal);
+            const attached = await connection.send("Target.attachToTarget", { targetId: target.id, flatten: true }, undefined, options.signal);
+            sessionId = attachedSessionId(attached);
+            const result = await capturePage({
+                connection,
+                sessionId,
+                discovery,
+                target,
+                input,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(options.progress === undefined
+                    ? {}
+                    : { progress: options.progress }),
+            });
+            return ok(webPageInspectionSchema.parse(result));
+        }
+        catch (cause) {
+            return err(providerError(cause, "inspect_web_page"));
+        }
+        finally {
+            if (connection !== undefined) {
+                if (sessionId !== undefined)
+                    await bestEffortCleanup(connection, sessionId);
+                await connection.close();
+            }
+        }
+    }
+}
+const selectTargets = (discovery, allowedOrigins) => {
+    const allowed = [];
+    let disallowedOrigin = 0;
+    let unsupportedUrl = 0;
+    let nonPage = 0;
+    for (const target of discovery.targets) {
+        if (target.type !== "page") {
+            nonPage += 1;
+            continue;
+        }
+        const url = sanitizeBrowserUrl(target.url);
+        if (url.origin === null) {
+            unsupportedUrl += 1;
+            continue;
+        }
+        if (!allowedOrigins.has(url.origin)) {
+            disallowedOrigin += 1;
+            continue;
+        }
+        allowed.push({
+            target_id: target.id,
+            type: target.type,
+            title: target.title.slice(0, 16_384),
+            url: url.url,
+            origin: url.origin,
+            attached: target.attached,
+        });
+    }
+    allowed.sort((left, right) => left.target_id.localeCompare(right.target_id));
+    return {
+        allowed,
+        excluded: {
+            disallowed_origin: disallowedOrigin,
+            unsupported_url: unsupportedUrl,
+            non_page: nonPage,
+        },
+    };
+};
+const authorizeTarget = (discovery, input) => {
+    const target = discovery.targets.find((candidate) => candidate.id === input.target_id);
+    if (target === undefined)
+        throw new BrowserObservationError("inspect_web_page", "target_not_found");
+    const origin = sanitizeBrowserUrl(target.url).origin;
+    if (target.type !== "page" ||
+        origin === null ||
+        !input.allowed_origins.includes(origin))
+        throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+    return target;
+};
+const attachedSessionId = (value) => {
+    if (typeof value !== "object" || value === null || !("sessionId" in value))
+        throw new BrowserObservationError("inspect_web_page", "protocol_error");
+    if (typeof value.sessionId !== "string" || value.sessionId.length > 256)
+        throw new BrowserObservationError("inspect_web_page", "protocol_error");
+    return value.sessionId;
+};
+const bestEffortCleanup = async (connection, sessionId) => {
+    for (const method of [
+        "Network.disable",
+        "Debugger.disable",
+        "Runtime.disable",
+        "Page.disable",
+    ]) {
+        try {
+            await connection.send(method, {}, sessionId);
+        }
+        catch {
+            // Cleanup continues so detach is still attempted.
+        }
+    }
+    try {
+        await connection.send("Target.detachFromTarget", { sessionId });
+    }
+    catch {
+        // Closing REA's socket is the final non-destructive cleanup boundary.
+    }
+};
+const providerError = (cause, operation) => cause instanceof AnalysisError
+    ? cause
+    : new ProviderAdapterError(IDENTITY.id, operation, { cause });