rea-agents 1.1.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

@@ -9,9 +9,50 @@ import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 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.
  * Discovery always precedes mutation. Interactive confirmation or explicit
@@ -34,34 +75,7 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
     const detectedClients = await host.detectedClients();
-    plannedActions = [
-        ...(hopperPath === undefined
-            ? [
-                {
-                    kind: "install_hopper",
-                    target: host.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,
-                },
-            ]
-            : []),
-        ...detectedClients
-            .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,
-        },
-    ];
+    plannedActions = setupPlan(host.platform, hopperPath, detectedClients);
     let approved = options.approved;
     let interactiveApproval = false;
     if (!approved && confirm !== undefined && !options.structured) {
@@ -91,14 +105,15 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
             };
         appliedActions.push("installed_hopper");
     }
-    for (const client of 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")
-            appliedActions.push(`configured_${client.name}`);
-    }
+    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.");
@@ -353,46 +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 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),
     ]));

package/dist/artifacts/ArtifactProvider.js

@@ -12,6 +12,10 @@ const IDENTITY = Object.freeze({
 });
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
+    nativeMountEnabled;
+    constructor(nativeMountEnabled = false) {
+        this.nativeMountEnabled = nativeMountEnabled;
+    }
     #capabilities = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) => Object.freeze({
         provider: IDENTITY,
         operation: contract.name,
@@ -36,8 +40,8 @@ export class ArtifactProvider {
             timeoutMs: 120_000,
         }),
         limitations: Object.freeze([
-            "DMG and PKG child inventory requires a future native read-only adapter.",
-            "Nested containers are recorded but not recursively expanded implicitly.",
+            "DMG child inventory is macOS-only and requires per-call approval plus operator policy; PKG remains root-hash-only.",
+            "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
         ]),
     })));
     identity() {
@@ -47,13 +51,15 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target);
+        return new ArtifactClient(target, this.nativeMountEnabled);
     }
 }
 class ArtifactClient {
     target;
-    constructor(target) {
+    nativeMountEnabled;
+    constructor(target, nativeMountEnabled) {
         this.target = target;
+        this.nativeMountEnabled = nativeMountEnabled;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -90,7 +96,13 @@ class ArtifactClient {
                 occurrenceLimit: parsed.occurrence_limit,
                 edgeOffset: parsed.edge_offset,
                 edgeLimit: parsed.edge_limit,
-            }, options?.signal);
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                nativeMount: {
+                    nativeMountApproved: parsed.native_mount_approved === true,
+                    nativeMountEnabled: this.nativeMountEnabled,
+                },
+            });
             return ok(createAnalysisExecution(result, IDENTITY, {
                 rawResult: null,
                 limitations: result.limitations,
@@ -120,7 +132,7 @@ const limitsFrom = (input) => ({
 const isArtifactOperation = (operation) => ARTIFACT_TOOL_CONTRACTS.some(({ name }) => name === operation);
 const translateFailure = (operation, cause) => {
     if (cause instanceof ArtifactReaderFailure)
-        return new ArtifactOperationError(operation, cause.reason);
+        return new ArtifactOperationError(operation, cause.reason, cause.details);
     return new ArtifactOperationError(operation, "io");
 };
 const subjectFor = (path, manifest) => ({

package/dist/artifacts/ArtifactReader.js

@@ -1,9 +1,11 @@
 /** Typed adapter failure translated at provider boundary. */
 export class ArtifactReaderFailure extends Error {
     reason;
-    constructor(reason, message, options) {
+    details;
+    constructor(reason, message, options, details) {
         super(message, options);
         this.reason = reason;
+        this.details = details;
         this.name = "ArtifactReaderFailure";
     }
 }

package/dist/artifacts/AsarArtifactReader.js

@@ -1,7 +1,13 @@
 import { Readable } from "node:stream";
 import { extractFile, listPackage, statFile } from "@electron/asar";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
-/** Official Electron ASAR adapter. Individual files remain caller-bounded. */
+/**
+ * Official Electron ASAR adapter. Individual files remain caller-bounded.
+ *
+ * An entry marked `unpacked` is metadata, not an integrity exemption: Electron
+ * stores its bytes beside the archive in `<archive>.unpacked`, and callers must
+ * hash those companion bytes against the archive's declared integrity value.
+ */
 export class AsarArtifactReader {
     path;
     format = "asar";
@@ -34,6 +40,7 @@ export class AsarArtifactReader {
                     /^[a-f0-9]{64}$/u.test(metadata.integrity.hash)
                     ? metadata.integrity.hash
                     : null,
+                unpacked: "unpacked" in metadata && metadata.unpacked === true,
                 limitations: kind === "symlink"
                     ? ["ASAR symlink target was not followed or disclosed."]
                     : [

package/dist/artifacts/DirectoryArtifactReader.js

@@ -55,6 +55,7 @@ export class DirectoryArtifactReader {
                     encrypted: false,
                     byteOffset: null,
                     declaredSha256: null,
+                    unpacked: false,
                     limitations: kind === "symlink"
                         ? ["Symlink target was not followed or disclosed."]
                         : [],

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -40,6 +40,7 @@ export class MachOSliceArtifactReader {
                 encrypted: false,
                 byteOffset: architecture.file_offset,
                 declaredSha256: null,
+                unpacked: false,
                 limitations: [],
                 adapterKey: `${String(architecture.file_offset)}:${String(architecture.size)}`,
             };