rea-agents 1.0.0 → 1.2.0

package/dist/application/ProcessOwnership.js

@@ -43,7 +43,13 @@ const systemHost = {
         process.kill(-processGroupId, signal);
     },
 };
-/** Verify run-token ownership before signaling a POSIX process group. */
+/**
+ * Verify run-token ownership before signaling a POSIX process group.
+ *
+ * Process IDs and group IDs can be reused. REA therefore re-reads every live
+ * member's environment immediately before signaling and fails closed if any
+ * member cannot be inspected or lacks the per-capture run token.
+ */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
     let members;
     try {
@@ -97,6 +103,38 @@ export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { cleaned: true, signaled: true };
 };
+/** Observe one group without signaling it, failing closed on identity doubt. */
+export const observeOwnedProcessGroup = async (ownership, host = systemHost) => {
+    let members;
+    try {
+        members = await host.listMembers(ownership.processGroupId);
+    }
+    catch {
+        return {
+            state: "unverifiable",
+            reason: "process group could not be inspected",
+        };
+    }
+    if (members.length === 0)
+        return { state: "empty" };
+    for (const member of members) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return {
+                    state: "unverifiable",
+                    reason: "process ownership did not match",
+                };
+        }
+        catch {
+            return {
+                state: "unverifiable",
+                reason: "process ownership could not be revalidated",
+            };
+        }
+    }
+    return { state: "alive" };
+};
 const commandMatches = (actual, expected) => {
     const normalizedActual = actual.trim();
     const normalizedExpected = expected.trim();

package/dist/application/ProcessSampling.js

@@ -24,17 +24,25 @@ const parseProcStat = (identifier, stat) => {
         .split(/\s+/);
     const pid = Number(identifier);
     const parentPid = Number(fields[1]);
+    const processGroupId = Number(fields[2]);
+    const sessionId = Number(fields[3]);
     const startTime = fields[19];
     if (!Number.isSafeInteger(pid) ||
         pid <= 0 ||
         !Number.isSafeInteger(parentPid) ||
         parentPid < 0 ||
+        !Number.isSafeInteger(processGroupId) ||
+        processGroupId <= 0 ||
+        !Number.isSafeInteger(sessionId) ||
+        sessionId <= 0 ||
         startTime === undefined ||
         !/^\d+$/.test(startTime))
         return undefined;
     return {
         pid,
         parent_pid: parentPid,
+        process_group_id: processGroupId,
+        session_id: sessionId,
         command: "",
         startTime,
     };
@@ -104,13 +112,15 @@ const inspectProcess = async (pid, expectedParent, signal, identities) => {
     return {
         pid: before.pid,
         parent_pid: before.parent_pid,
+        process_group_id: before.process_group_id,
+        session_id: before.session_id,
         startTime: before.startTime,
         command,
         children: children ?? [],
     };
 };
 const sampleLinux = async (context) => {
-    const { rootPid, limit, signal, sampledPids, identities } = context;
+    const { rootPid, limit, signal, identities } = context;
     if (limit <= 0)
         return [];
     const rootStat = await readProcessStat(rootPid, signal);
@@ -131,11 +141,9 @@ const sampleLinux = async (context) => {
         for (const node of batchResults) {
             if (node === undefined)
                 continue;
-            if (!sampledPids.has(node.pid)) {
-                if (rows.length >= limit)
-                    break;
-                rows.push(node);
-            }
+            if (rows.length >= limit)
+                break;
+            rows.push(node);
             if (rows.length >= limit)
                 break;
             for (const child of node.children) {
@@ -152,15 +160,17 @@ const sampleLinux = async (context) => {
     return rows;
 };
 const readPsRows = async (signal) => {
-    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="], { signal });
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,pgid=,sess=,command="], { signal });
     return stdout
         .split("\n")
-        .map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/u.exec(line))
+        .map((line) => /\s*(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)/u.exec(line))
         .filter((match) => match !== null)
         .map((match) => ({
         pid: Number(match[1]),
         parent_pid: Number(match[2]),
-        command: match[3] ?? "",
+        process_group_id: Number(match[3]),
+        session_id: Number(match[4]),
+        command: match[5] ?? "",
         startTime: undefined,
     }))
         .filter((row) => Number.isSafeInteger(row.pid) &&
@@ -170,7 +180,7 @@ const readPsRows = async (signal) => {
         .sort((left, right) => left.pid - right.pid);
 };
 const samplePs = async (context) => {
-    const { rootPid, limit, signal, sampledPids } = context;
+    const { rootPid, limit, signal } = context;
     if (limit <= 0)
         return [];
     const rows = await readPsRows(signal);
@@ -194,9 +204,8 @@ const samplePs = async (context) => {
             continue;
         visited.add(pid);
         const row = rowByPid.get(pid);
-        if (row !== undefined && !sampledPids.has(row.pid)) {
+        if (row !== undefined)
             result.push(row);
-        }
         if (result.length >= limit)
             break;
         for (const child of childrenByParent.get(pid) ?? []) {
@@ -212,11 +221,9 @@ const sampleProcesses = async (context) => {
     const rows = process.platform === "linux"
         ? await sampleLinux(context)
         : await samplePs(context);
-    const { elapsedMs, sampledPids, identities } = context;
+    const { elapsedMs, identities } = context;
     const samples = [];
     for (const row of rows) {
-        if (sampledPids.has(row.pid))
-            continue;
         if (row.startTime !== undefined) {
             const existing = identities.get(row.pid);
             if (existing !== undefined && existing !== row.startTime)
@@ -228,6 +235,8 @@ const sampleProcesses = async (context) => {
             pid: row.pid,
             parent_pid: row.parent_pid,
             command: row.command,
+            process_group_id: row.process_group_id,
+            session_id: row.session_id,
         });
     }
     return samples;
@@ -235,31 +244,38 @@ const sampleProcesses = async (context) => {
 /** Start bounded process-tree sampling and expose an awaited stop. */
 export const startProcessSampler = (rootPid, started, limit, samples) => {
     const identities = new Map();
-    const sampledPids = new Set(samples.map(({ pid }) => pid));
+    const lastObservations = new Map();
     let pending;
     let stopped = false;
     let abortCurrent;
     let partial = false;
     const sample = () => {
-        if (stopped || pending !== undefined || sampledPids.size >= limit)
+        if (stopped || pending !== undefined)
             return;
         const controller = new AbortController();
         abortCurrent = () => controller.abort();
         pending = sampleProcesses({
             rootPid,
             elapsedMs: Date.now() - started,
-            limit: limit - sampledPids.size,
-            sampledPids,
+            limit: limit + 1,
             identities,
             signal: controller.signal,
         })
             .then((values) => {
             for (const value of values) {
-                if (sampledPids.size >= limit)
-                    break;
-                if (sampledPids.has(value.pid))
+                const observation = JSON.stringify({
+                    parent_pid: value.parent_pid,
+                    command: value.command,
+                    process_group_id: value.process_group_id,
+                    session_id: value.session_id,
+                });
+                if (lastObservations.get(value.pid) === observation)
+                    continue;
+                if (samples.length >= limit) {
+                    partial = true;
                     continue;
-                sampledPids.add(value.pid);
+                }
+                lastObservations.set(value.pid, observation);
                 samples.push(value);
             }
         })

package/dist/application/Setup.js

@@ -1,30 +1,71 @@
 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 { execFile } from "node:child_process";
-import { promisify } from "node:util";
 import { z } from "zod";
 import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
-import { probeHomebrew } from "./homebrew.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
-const execFileAsync = promisify(execFile);
+import { installMacHopper } from "./MacHopper.js";
+import { installCanonicalSkill } from "./SetupSkill.js";
+export { installCanonicalSkill } from "./SetupSkill.js";
 const registrationCommand = () => process.env.npm_command === "exec"
     ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
+const setupPlan = (platform, hopperPath, clients) => [
+    ...(hopperPath === undefined
+        ? [
+            {
+                kind: "install_hopper",
+                target: platform === "darwin"
+                    ? "~/Applications/Hopper Disassembler.app"
+                    : "system package manager",
+                detail: "Download the official Hopper package, verify it, install it, and open Hopper for activation.",
+                external: true,
+            },
+        ]
+        : []),
+    ...clients
+        .filter(({ format }) => format !== "unsupported")
+        .map((client) => ({
+        kind: "configure_client",
+        target: client.configPath,
+        detail: `Add the REA MCP registration for ${client.name}; preserve unrelated configuration.`,
+        external: false,
+    })),
+    {
+        kind: "install_skill",
+        target: "~/.agents/skills/rea-analysis/SKILL.md",
+        detail: "Install or update the bundled REA analysis skill.",
+        external: false,
+    },
+];
+const configureDetectedClients = async (options) => {
+    for (const client of options.detectedClients) {
+        const result = await options.host.configureClient(client, options.hopperPath, registrationCommand());
+        options.clients[client.name] = result;
+        if (result.status === "failed")
+            return `${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`;
+        if (result.status === "configured")
+            options.appliedActions.push(`configured_${client.name}`);
+    }
+    return undefined;
+};
 /**
  * Install prerequisites and configure detected clients idempotently.
- * With `yes` false, mutations requiring consent are reported as `needs_human`;
- * with `yes` true, external installers still fail closed if they require UI.
+ * Discovery always precedes mutation. Interactive confirmation or explicit
+ * unattended options authorize only the actions represented in the result.
  */
-export const runSetup = async (yes, host = systemSetupHost()) => {
-    const actions = [];
+export const runSetup = async (options, host = systemSetupHost(), confirm) => {
+    const appliedActions = [];
+    let plannedActions = [];
     const clients = {};
     const fail = async (remediation) => ({
         status: "needs_human",
-        actions,
+        plannedActions,
+        appliedActions,
         clients,
         doctor: await host.doctor(),
         remediation,
@@ -32,43 +73,59 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
     const unsupported = await hostRemediation(host);
     if (unsupported !== undefined)
         return fail(unsupported);
-    if (host.platform === "darwin" && !(await host.hasHomebrew())) {
-        if (!yes)
-            return fail("Re-run with --yes to install Homebrew.");
-        if (!(await host.installHomebrew()))
-            return fail("Homebrew installation was interrupted; resolve the installer prompt and re-run setup.");
-        actions.push("installed_homebrew");
-    }
     let hopperPath = await host.hopperPath();
-    if (hopperPath === undefined) {
-        if (!yes)
-            return fail("Re-run with --yes to install Hopper.");
-        if (!(await host.installHopper()))
-            return fail("Hopper installation was interrupted; resolve the system prompt and re-run setup.");
-        actions.push("installed_hopper");
-        hopperPath = await host.hopperPath();
-        if (hopperPath === undefined)
-            return fail("Hopper installation completed but its launcher was not found.");
+    const detectedClients = await host.detectedClients();
+    plannedActions = setupPlan(host.platform, hopperPath, detectedClients);
+    let approved = options.approved;
+    let interactiveApproval = false;
+    if (!approved && confirm !== undefined && !options.structured) {
+        interactiveApproval = await confirm(plannedActions);
+        approved = interactiveApproval;
     }
-    for (const client of await host.detectedClients()) {
-        const result = await host.configureClient(client, hopperPath, registrationCommand());
-        clients[client.name] = result;
-        if (result.status === "failed")
-            return fail(`${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`);
-        if (result.status === "configured")
-            actions.push(`configured_${client.name}`);
+    if (!approved)
+        return {
+            status: confirm === undefined ? "needs_confirmation" : "planned",
+            plannedActions,
+            appliedActions,
+            clients,
+            doctor: await host.doctor(),
+            remediation: "Review the setup plan, then rerun interactively or with --yes.",
+        };
+    if (hopperPath === undefined &&
+        (interactiveApproval || options.installHopper)) {
+        hopperPath = await host.installHopper();
+        if (hopperPath === undefined)
+            return {
+                status: "needs_human",
+                plannedActions,
+                appliedActions,
+                clients,
+                doctor: await host.doctor(),
+                remediation: "Hopper installation failed; install Hopper manually or rerun setup after resolving the reported system error.",
+            };
+        appliedActions.push("installed_hopper");
     }
+    const clientFailure = await configureDetectedClients({
+        host,
+        detectedClients,
+        hopperPath,
+        clients,
+        appliedActions,
+    });
+    if (clientFailure !== undefined)
+        return fail(clientFailure);
     const skill = await host.installSkill();
     if (skill === "failed")
         return fail("Agent skill installation or readback failed.");
     if (skill === "installed")
-        actions.push("installed_skill");
+        appliedActions.push("installed_skill");
     const doctor = await host.doctor();
-    const activationRequired = actions.includes("installed_hopper");
+    const activationRequired = appliedActions.includes("installed_hopper");
     const ready = doctor.healthy && !activationRequired;
     return {
         status: ready ? "ready" : "needs_human",
-        actions,
+        plannedActions,
+        appliedActions,
         clients,
         doctor,
         ...(ready
@@ -76,15 +133,17 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
             : {
                 remediation: activationRequired
                     ? "Open Hopper, complete its one-time activation, then rerun rea doctor --json."
-                    : "Run rea doctor and apply each reported remediation.",
+                    : hopperPath === undefined
+                        ? "Hopper is optional for non-Hopper providers. Rerun with --yes --install-hopper for deep native analysis."
+                        : "Run rea doctor and apply each reported remediation.",
             }),
     };
 };
 const hostRemediation = async (host) => {
     if (host.platform !== "darwin" && host.platform !== "linux")
         return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
-    if (major(host.nodeVersion) < 24)
-        return "Install Node.js 24.18 or newer.";
+    if (!supportsNodeVersion(host.nodeVersion))
+        return "Install Node.js 22.19+ or 24.11+ and rerun setup.";
     if (host.platform === "darwin") {
         const version = await host.macosVersion();
         return version === undefined || major(version) < 12
@@ -95,7 +154,7 @@ const hostRemediation = async (host) => {
         ? undefined
         : "REA supports Hopper on Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.";
 };
-/** Production setup effects for macOS, Homebrew, JSON MCP clients, and the canonical skill directory. */
+/** Production setup effects for Hopper, agent configuration, and the canonical skill directory. */
 const systemSetupHost = () => {
     const doctorHost = systemDoctorHost();
     return {
@@ -103,15 +162,13 @@ const systemSetupHost = () => {
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
         linuxDistribution: readLinuxDistribution,
-        hasHomebrew: () => brewSucceeds(["--version"]),
-        installHomebrew: () => commandSucceeds("/bin/bash", [
-            "-c",
-            "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)",
-        ], { ...process.env, NONINTERACTIVE: "1" }),
         hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
-        installHopper: () => process.platform === "linux"
-            ? installLinuxHopper().then(({ status }) => status === "installed")
-            : brewSucceeds(["install", "--cask", "hopper-disassembler"]),
+        installHopper: async () => {
+            const result = process.platform === "linux"
+                ? await installLinuxHopper()
+                : await installMacHopper();
+            return result.status === "installed" ? result.launcherPath : undefined;
+        },
         detectedClients: () => detectClients(homedir()),
         configureClient: (client, hopperPath, command) => client.format === "unsupported"
             ? Promise.resolve({ status: "skipped" })
@@ -311,59 +368,6 @@ export const configureTomlClient = async (client, hopperPath, command = [
         ...(backupPath === undefined ? {} : { backupPath }),
     };
 };
-/** Transactionally install or upgrade the versioned canonical REA skill. */
-export const installCanonicalSkill = async (home) => {
-    const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
-    const backup = `${destination}.rea.backup`;
-    let original;
-    try {
-        const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
-        original = await readFile(destination, "utf8").catch(() => undefined);
-        if (original === content)
-            return "unchanged";
-        await mkdir(dirname(destination), { recursive: true });
-        if (original !== undefined)
-            await writeFileAtomic(backup, original, {
-                encoding: "utf8",
-                mode: 0o600,
-            });
-        await writeFileAtomic(destination, content, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-        if ((await readFile(destination, "utf8")) !== content)
-            throw new Error("skill readback mismatch");
-        return "installed";
-    }
-    catch {
-        try {
-            if (original === undefined)
-                await rm(destination, { force: true });
-            else
-                await writeFileAtomic(destination, original, {
-                    encoding: "utf8",
-                    mode: 0o600,
-                });
-        }
-        catch {
-            // The backup remains beside the skill for explicit operator recovery.
-        }
-        return "failed";
-    }
-};
-const commandSucceeds = async (command, args, env) => {
-    try {
-        await execFileAsync(command, args, env === undefined ? {} : { env });
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const brewSucceeds = async (args) => {
-    const result = await probeHomebrew(async (command) => (await commandSucceeds(command, args)) ? true : undefined);
-    return result === true;
-};
 const major = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
 const exists = async (path) => {
     try {

package/dist/application/SetupSkill.js

@@ -0,0 +1,44 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { PRODUCT_IDENTITY } from "../identity.js";
+/** Transactionally install or upgrade the versioned canonical REA skill. */
+export const installCanonicalSkill = async (home) => {
+    const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
+    const backup = `${destination}.rea.backup`;
+    let original;
+    try {
+        const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
+        original = await readFile(destination, "utf8").catch(() => undefined);
+        if (original === content)
+            return "unchanged";
+        await mkdir(dirname(destination), { recursive: true });
+        if (original !== undefined)
+            await writeFileAtomic(backup, original, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+        await writeFileAtomic(destination, content, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        if ((await readFile(destination, "utf8")) !== content)
+            throw new Error("skill readback mismatch");
+        return "installed";
+    }
+    catch {
+        try {
+            if (original === undefined)
+                await rm(destination, { force: true });
+            else
+                await writeFileAtomic(destination, original, {
+                    encoding: "utf8",
+                    mode: 0o600,
+                });
+        }
+        catch {
+            // The backup remains beside the skill for explicit operator recovery.
+        }
+        return "failed";
+    }
+};

package/dist/application/TerminalRenderer.js

@@ -0,0 +1,92 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+// SAFETY: both pinned xterm packages publish CommonJS at runtime and matching declarations.
+const HeadlessPackage = require("@xterm/headless");
+// SAFETY: the addon package is pinned with the compatible headless xterm release.
+const SerializePackage = require("@xterm/addon-serialize");
+/** Owns one headless terminal and serializes writes into deterministic frames. */
+/**
+ * Reconstructs bounded terminal states while raw PTY chunks remain authoritative.
+ *
+ * Rendered frames answer what an operator saw after control-sequence handling;
+ * raw frames preserve byte/chunk differences that can render identically.
+ * Comparisons retain both because neither representation subsumes the other.
+ */
+export class TerminalRenderer {
+    options;
+    #terminal;
+    #serializeAddon = new SerializePackage.SerializeAddon();
+    #frames = [];
+    #pending = Promise.resolve();
+    #capturedBytes = 0;
+    #truncated = false;
+    constructor(options) {
+        this.options = options;
+        this.#terminal = new HeadlessPackage.Terminal({
+            allowProposedApi: true,
+            cols: options.columns,
+            rows: options.rows,
+            scrollback: options.scrollback,
+        });
+        this.#terminal.loadAddon(this.#serializeAddon);
+    }
+    /** Queue one PTY chunk and capture state only after xterm has parsed it. */
+    write(data, atMs) {
+        this.#pending = this.#pending.then(() => new Promise((resolveWrite) => {
+            this.#terminal.write(data, () => {
+                this.#capture(atMs);
+                resolveWrite();
+            });
+        }));
+    }
+    /** Queue a terminal resize after every preceding write. */
+    resize(columns, rows, atMs) {
+        this.#pending = this.#pending.then(() => {
+            this.#terminal.resize(columns, rows);
+            this.#capture(atMs);
+        });
+    }
+    /** Await all queued parsing and return immutable rendered observations. */
+    async frames() {
+        await this.#pending;
+        return this.#frames;
+    }
+    /** Whether a rendered observation exceeded its independent capture budget. */
+    truncated() {
+        return this.#truncated;
+    }
+    /** Release addon and terminal resources after all writes settle. */
+    async dispose() {
+        await this.#pending;
+        this.#serializeAddon.dispose();
+        this.#terminal.dispose();
+    }
+    #capture(atMs) {
+        const buffer = this.#terminal.buffer.active;
+        const lines = [];
+        for (let row = 0; row < this.#terminal.rows; row += 1) {
+            const line = buffer.getLine(buffer.viewportY + row);
+            lines.push(this.options.normalize((line?.translateToString(false, 0, this.#terminal.cols) ?? "").padEnd(this.#terminal.cols, " ")));
+        }
+        const serializedState = this.options.normalize(this.#serializeAddon.serialize());
+        const bytes = Buffer.byteLength(serializedState) +
+            lines.reduce((total, line) => total + Buffer.byteLength(line), 0);
+        if (this.#frames.length >= this.options.maxFrames ||
+            this.#capturedBytes + bytes > this.options.maxBytes) {
+            this.#truncated = true;
+            return;
+        }
+        this.#capturedBytes += bytes;
+        this.#frames.push({
+            sequence: this.#frames.length,
+            at_ms: atMs,
+            columns: this.#terminal.cols,
+            rows: this.#terminal.rows,
+            cursor_x: buffer.cursorX,
+            cursor_y: buffer.cursorY,
+            active_buffer: buffer.type,
+            lines,
+            serialized_state: serializedState,
+        });
+    }
+}

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(),
+        new ArtifactProvider(config.artifactNativeMountEnabled),
         new NativeMacOSProvider(),
         new HopperProvider(config, logger),
     ]));