rea-agents 2.0.0 → 2.2.0

package/dist/replay/LinuxJavaScriptReplaySandbox.js

@@ -0,0 +1,140 @@
+import { open } from "node:fs/promises";
+import { dirname } from "node:path";
+import { digestJson, } from "../application/JavaScriptReplayPlanning.js";
+import { buildLinuxX64ReplaySeccomp } from "./LinuxSeccompPolicy.js";
+import { resolveLinuxRuntimeClosure } from "./LinuxRuntimeClosure.js";
+export const assertRuntimeCommitment = (prepared, closure) => {
+    const observed = closure.map((item) => ({
+        source_path: item.sourcePath,
+        destination_path: item.destinationPath,
+        sha256: item.sha256,
+    }));
+    if (digestJson(observed) !==
+        digestJson(prepared.publicPlan.runtime.read_only_files))
+        throw new TypeError("Replay runtime closure changed after approval");
+};
+export const temporaryFilterHandle = async () => {
+    const { mkdtemp, writeFile, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const directory = await mkdtemp(join(tmpdir(), "rea-replay-filter-"));
+    const path = join(directory, "seccomp.bpf");
+    await writeFile(path, buildLinuxX64ReplaySeccomp(), { mode: 0o600 });
+    const handle = await open(path, "r");
+    return {
+        path,
+        handle,
+        close: async () => {
+            await handle.close();
+            await rm(directory, { recursive: true, force: true });
+        },
+    };
+};
+export const systemdArguments = (options) => {
+    const { unit, policy, prepared, workerPath, closure, filterPath } = options;
+    const limits = prepared.publicPlan.limits;
+    const descriptorPaths = [
+        filterPath,
+        ...closure.map(({ sourcePath }) => sourcePath),
+        workerPath,
+    ];
+    const workerFd = descriptorPaths.length + 2;
+    const wrapper = descriptorPaths
+        .map((_, index) => `exec ${String(index + 3)}<"$1"; shift`)
+        .concat('exec "$@"')
+        .join("\n");
+    return [
+        "--user",
+        "--pipe",
+        "--wait",
+        "--service-type=exec",
+        "--quiet",
+        `--unit=${unit}`,
+        `--property=MemoryMax=${String(limits.memory_bytes)}`,
+        "--property=MemorySwapMax=0",
+        `--property=TasksMax=${String(limits.tasks)}`,
+        `--property=CPUQuota=${String(limits.cpu_quota_percent)}%`,
+        "--property=KillMode=control-group",
+        "--property=SendSIGKILL=yes",
+        "--",
+        policy.shellPath,
+        "-c",
+        wrapper,
+        "rea-replay-wrapper",
+        ...descriptorPaths,
+        policy.bubblewrapPath,
+        "--unshare-all",
+        "--unshare-user",
+        "--disable-userns",
+        "--new-session",
+        "--die-with-parent",
+        "--cap-drop",
+        "ALL",
+        "--clearenv",
+        "--setenv",
+        "HOME",
+        "/work",
+        "--setenv",
+        "TMPDIR",
+        "/tmp",
+        "--setenv",
+        "TZ",
+        "UTC",
+        "--setenv",
+        "LANG",
+        "C",
+        "--setenv",
+        "LC_ALL",
+        "C",
+        "--tmpfs",
+        "/",
+        "--dir",
+        "/runtime",
+        "--dir",
+        "/work",
+        "--size",
+        String(limits.tmpfs_bytes),
+        "--tmpfs",
+        "/tmp",
+        ...bindArguments(closure),
+        "--ro-bind-fd",
+        String(workerFd),
+        "/runtime/worker.js",
+        "--proc",
+        "/proc",
+        "--dev",
+        "/dev",
+        "--remount-ro",
+        "/",
+        "--chdir",
+        "/work",
+        "--seccomp",
+        "3",
+        "--",
+        "/runtime/node",
+        `--max-old-space-size=${String(Math.max(8, Math.floor(limits.memory_bytes / 1024 / 1024 / 2)))}`,
+        "--experimental-vm-modules",
+        "--permission",
+        "--allow-fs-read=/runtime/worker.js",
+        "/runtime/worker.js",
+    ];
+};
+const bindArguments = (closure) => {
+    const arguments_ = [];
+    const directories = new Set();
+    for (const [index, item] of closure.entries()) {
+        const destination = item.destinationPath;
+        let parent = dirname(destination);
+        const chain = [];
+        while (parent !== "/" && !directories.has(parent)) {
+            chain.push(parent);
+            parent = dirname(parent);
+        }
+        for (const directory of chain.reverse()) {
+            directories.add(directory);
+            arguments_.push("--dir", directory);
+        }
+        arguments_.push("--ro-bind-fd", String(index + 4), destination);
+    }
+    return arguments_;
+};

package/dist/replay/ReplayOutcome.js

@@ -0,0 +1,95 @@
+import { digestJson, } from "../application/JavaScriptReplayPlanning.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+export const workerRequest = (prepared) => ({
+    schemaVersion: 1,
+    left: workerSide(prepared.publicPlan.left, prepared.leftSources),
+    ...(prepared.publicPlan.right === undefined ||
+        prepared.rightSources === undefined
+        ? {}
+        : { right: workerSide(prepared.publicPlan.right, prepared.rightSources) }),
+    cases: prepared.publicPlan.cases.map((item) => ({
+        caseId: item.case_id,
+        arguments: item.arguments,
+        inputSha256: item.sha256,
+    })),
+    determinism: {
+        clockIso: prepared.publicPlan.determinism.clock_iso,
+        randomSeed: prepared.publicPlan.determinism.random_seed,
+    },
+    limits: {
+        resultDepth: prepared.publicPlan.limits.result_depth,
+        resultNodes: prepared.publicPlan.limits.result_nodes,
+        exceptionBytes: Math.min(64 * 1024, prepared.publicPlan.limits.output_bytes),
+    },
+});
+const workerSide = (side, sources) => ({
+    modules: side.modules.map((module) => ({
+        alias: module.alias,
+        format: module.format,
+        dependencies: module.dependencies,
+        source: sources[module.alias] ?? "",
+    })),
+    entryAlias: side.entry_alias,
+    entryExport: side.entry_export,
+});
+export const commitOutcomes = (outcomes) => outcomes.map((outcome) => {
+    const semantic = outcome.value === undefined ? (outcome.exception ?? null) : outcome.value;
+    return {
+        case_id: outcome.case_id,
+        outcome: outcome.outcome,
+        ...(outcome.value === undefined
+            ? {}
+            : { value: jsonValueSchema.parse(outcome.value) }),
+        ...(outcome.exception === undefined
+            ? {}
+            : { exception: outcome.exception }),
+        input_sha256: outcome.input_sha256,
+        output_sha256: digestJson(semantic),
+        truncated: false,
+    };
+});
+export const compareOutcomes = (left, right) => left.map((item, index) => ({
+    case_id: item.case_id,
+    status: right[index] === undefined
+        ? "unknown"
+        : item.outcome === right[index].outcome &&
+            item.output_sha256 === right[index].output_sha256
+            ? "equal"
+            : "changed",
+    left_index: index,
+    right_index: index,
+}));
+export const terminationResult = (options) => {
+    const { prepared, stderr, termination, cleanup, limitation } = options;
+    const outcomes = prepared.publicPlan.cases.map((item) => ({
+        case_id: item.case_id,
+        outcome: termination,
+        input_sha256: item.sha256,
+        output_sha256: null,
+        truncated: termination === "protocol_error",
+    }));
+    const differential = prepared.publicPlan.right !== undefined;
+    return {
+        schema_version: 1,
+        plan_digest: prepared.publicPlan.plan_digest,
+        outcomes: [...outcomes, ...(differential ? outcomes : [])],
+        ...(differential
+            ? {
+                comparison: outcomes.map((item, index) => ({
+                    case_id: item.case_id,
+                    status: "unknown",
+                    left_index: index,
+                    right_index: index,
+                })),
+            }
+            : {}),
+        stderr,
+        termination,
+        cleanup,
+        limitations: [
+            limitation ??
+                `Replay terminated with ${termination}; the requested functional result remains unknown.`,
+        ],
+        reproducer: null,
+    };
+};

package/dist/replay/ReplayProcessLifecycle.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+export const boundedCollector = (maximum) => {
+    const chunks = [];
+    let bytes = 0;
+    let overflow = false;
+    return {
+        append: (chunk) => {
+            const retained = chunk.subarray(0, Math.max(0, maximum - bytes));
+            if (retained.byteLength > 0)
+                chunks.push(retained);
+            bytes += retained.byteLength;
+            if (retained.byteLength < chunk.byteLength)
+                overflow = true;
+        },
+        value: () => Buffer.concat(chunks).toString("utf8"),
+        exceeded: () => overflow,
+    };
+};
+const collect = async (executable, arguments_, maximum) => new Promise((resolve, reject) => {
+    const child = spawn(executable, [...arguments_], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = boundedCollector(maximum);
+    const stderr = boundedCollector(maximum);
+    const timeout = setTimeout(() => child.kill("SIGKILL"), 5_000);
+    timeout.unref();
+    child.stdout?.on("data", stdout.append);
+    child.stderr?.on("data", stderr.append);
+    child.once("error", (error) => {
+        clearTimeout(timeout);
+        reject(error);
+    });
+    child.once("close", (code) => {
+        clearTimeout(timeout);
+        resolve({ code, stdout: stdout.value(), stderr: stderr.value() });
+    });
+});
+export const killUnit = async (systemctl, unit) => {
+    try {
+        await collect(systemctl, ["--user", "kill", "--kill-whom=all", "--signal=SIGKILL", unit], 4096);
+    }
+    catch {
+        /* cleanup continues */
+    }
+};
+export const observeCleanup = async (systemctl, unit) => {
+    try {
+        const state = await collect(systemctl, ["--user", "show", "--property=ActiveState", "--value", unit], 4096);
+        const activeState = state.stdout.trim();
+        if (state.code !== 0 ||
+            activeState === "inactive" ||
+            activeState === "failed" ||
+            activeState.length === 0) {
+            await collect(systemctl, ["--user", "reset-failed", unit], 4096);
+            return { state: "complete", residual_resources: [] };
+        }
+        return { state: "incomplete", residual_resources: [unit] };
+    }
+    catch {
+        return { state: "incomplete", residual_resources: [unit] };
+    }
+};
+export const observeUnitResult = async (systemctl, unit) => {
+    try {
+        const result = await collect(systemctl, ["--user", "show", "--property=Result", "--value", unit], 4096);
+        return result.stdout.trim();
+    }
+    catch {
+        return "unknown";
+    }
+};

package/dist/server/ProcessCaptureElicitation.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { acceptedContent, inputRequired, inputResponse, } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { PermissionRequiredError } from "../domain/errors.js";
+import { isPermissionRequestWithinCeiling, } from "../domain/permissionPolicy.js";
+const RESPONSE_KEY = "process_capture_grant";
+const STATE_VERSION = 1;
+/** Shared continuation, replay, and round limits for process capture consent. */
+export const PROCESS_CAPTURE_ELICITATION_POLICY = {
+    protocolVersions: ["2026-07-28"],
+    stateTtlSeconds: 600,
+    roundTimeoutMs: 600_000,
+    maxConsumedNonces: 4_096,
+};
+const grantResponseSchema = z.strictObject({
+    lifetime: z.enum(["once", "session"]).meta({ default: "session" }),
+});
+const grantResponseJsonSchema = { ...z.toJSONSchema(grantResponseSchema) };
+// MCP elicitation accepts a reduced JSON Schema subset. These generator
+// annotations do not change the schema's fields or validation semantics; the
+// Standard Schema marker would make the SDK regenerate the removed keywords.
+Reflect.deleteProperty(grantResponseJsonSchema, "$schema");
+Reflect.deleteProperty(grantResponseJsonSchema, "additionalProperties");
+const stateSchema = z.strictObject({
+    version: z.literal(STATE_VERSION),
+    nonce: z.string().uuid(),
+    request: z.strictObject({
+        capability: z.literal("process_capture"),
+        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(),
+        operation_identity: z.string(),
+    }),
+});
+/** Authorize capture or return a signed MCP input-required continuation. */
+export const authorizeProcessCaptureWithElicitation = async (authority, request, context, elicitation) => {
+    const supported = elicitation.supported(context);
+    const initial = await authority.authorize(request, "read", {
+        elicitationSupported: supported,
+    });
+    if (initial.ok || !(initial.error instanceof PermissionRequiredError))
+        return initial;
+    const denied = initial.error;
+    if (!supported ||
+        denied.requested.capability !== "process_capture" ||
+        denied.ceiling === null ||
+        !isPermissionRequestWithinCeiling(denied.requested, denied.ceiling))
+        return initial;
+    const encodedState = context.mcpReq.requestState();
+    if (encodedState !== undefined) {
+        const state = stateSchema.safeParse(encodedState);
+        if (!state.success || !sameRequest(state.data.request, denied.requested))
+            return initial;
+        const response = inputResponse(context.mcpReq.inputResponses, RESPONSE_KEY);
+        if (response.kind === "elicit") {
+            if (!consumeNonce(elicitation.consumedNonces, state.data.nonce, elicitation.now()))
+                return initial;
+        }
+        if (response.kind === "elicit" && response.action === "accept") {
+            const content = acceptedContent(context.mcpReq.inputResponses, RESPONSE_KEY, grantResponseSchema);
+            if (content === undefined)
+                return initial;
+            return grantAndAuthorize(authority, state.data.request, content.lifetime);
+        }
+        if (response.kind === "elicit" &&
+            (response.action === "decline" || response.action === "cancel"))
+            return initial;
+    }
+    const state = await elicitation.stateCodec.mint({
+        version: STATE_VERSION,
+        nonce: randomUUID(),
+        request: {
+            capability: "process_capture",
+            roots: [...denied.requested.roots],
+            executables: [...denied.requested.executables],
+            environment_names: [...denied.requested.environment_names],
+            network: denied.requested.network,
+            mount: denied.requested.mount,
+            operation_identity: denied.requested.operation_identity,
+            ...(denied.requested.origins === undefined
+                ? {}
+                : { origins: [...denied.requested.origins] }),
+        },
+    });
+    return inputRequired({
+        inputRequests: {
+            [RESPONSE_KEY]: inputRequired.elicit({
+                message: permissionMessage(denied.requested),
+                requestedSchema: grantResponseJsonSchema,
+            }),
+        },
+        requestState: state,
+    });
+};
+const grantAndAuthorize = async (authority, request, lifetime) => {
+    const grant = {
+        ...request,
+        grant_id: `elicited:${randomUUID()}`,
+        lifetime,
+        operation_identity: lifetime === "once" ? request.operation_identity : null,
+        expires_at: null,
+    };
+    const granted = authority.grant(grant);
+    if (!granted.ok)
+        return authority.authorize(request, "read", {
+            elicitationSupported: true,
+        });
+    let authorized;
+    try {
+        authorized = await authority.authorize(request, "read", {
+            elicitationSupported: true,
+        });
+    }
+    catch (cause) {
+        authority.revoke(grant.grant_id);
+        throw cause;
+    }
+    if (!authorized.ok)
+        authority.revoke(grant.grant_id);
+    return authorized;
+};
+const sameRequest = (left, right) => left.capability === right.capability &&
+    left.network === right.network &&
+    left.mount === right.mount &&
+    left.operation_identity === right.operation_identity &&
+    sameOptionalStrings(left.origins, right.origins) &&
+    sameStrings(left.roots, right.roots) &&
+    sameStrings(left.executables, right.executables) &&
+    sameStrings(left.environment_names, right.environment_names);
+const sameStrings = (left, right) => left.length === right.length &&
+    left.every((value, index) => value === right[index]);
+const sameOptionalStrings = (left, right) => left === undefined
+    ? right === undefined
+    : right !== undefined && sameStrings(left, right);
+const consumeNonce = (consumed, nonce, now) => {
+    for (const [candidate, expiresAt] of consumed)
+        if (expiresAt <= now)
+            consumed.delete(candidate);
+    if (consumed.has(nonce) ||
+        consumed.size >= PROCESS_CAPTURE_ELICITATION_POLICY.maxConsumedNonces)
+        return false;
+    consumed.set(nonce, now + PROCESS_CAPTURE_ELICITATION_POLICY.stateTtlSeconds * 1_000);
+    return true;
+};
+const permissionMessage = (request) => [
+    "Allow REA to run this exact process-capture scope?",
+    `Executable: ${request.executables.join(", ") || "none"}`,
+    `Filesystem roots: ${request.roots.join(", ") || "none"}`,
+    `Environment names: ${request.environment_names.join(", ") || "none"}`,
+    `Origins: ${request.origins?.join(", ") || "none"}`,
+    `Network: ${request.network}`,
+    `Mount access: ${request.mount ? "yes" : "no"}`,
+    "Choose whether the grant applies once or for this MCP session.",
+].join("\n");