rea-agents 1.3.0 → 1.4.0

package/dist/application/PermissionConfiguration.js

@@ -0,0 +1,26 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createPermissionAuthority, } from "./PermissionAuthority.js";
+import { readProjectPermissionStore } from "./ProjectPermissionStore.js";
+/** Load the same administrator and optional project policy for CLI and MCP. */
+export const loadConfiguredPermissionAuthority = async (config) => {
+    const authority = await createPermissionAuthority(config.permissionCeilings, config.administratorPermissionGrants);
+    if (!authority.ok)
+        return err(new ConfigurationError("Permission policy could not be loaded", {
+            cause: authority.error,
+        }));
+    if (config.permissionProjectRoot === undefined ||
+        config.permissionProjectStore === undefined)
+        return ok(authority.value);
+    const project = await readProjectPermissionStore(config.permissionProjectStore, config.permissionProjectRoot);
+    if (!project.ok)
+        return err(new ConfigurationError("Project permission policy could not be loaded", {
+            cause: project.error,
+        }));
+    const replaced = await authority.value.replaceProjectGrants(project.value?.grants ?? []);
+    return replaced.ok
+        ? ok(authority.value)
+        : err(new ConfigurationError("Project permission policy could not be applied", {
+            cause: replaced.error,
+        }));
+};

package/dist/application/ProcessCaptureError.js

@@ -4,14 +4,27 @@ export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
     userMessage;
     userCategory;
+    reason;
+    cleanupIncomplete;
+    cleanupResources;
     constructor(message, options) {
         super(message, options);
         this.userMessage = options?.userMessage;
         this.userCategory = options?.userCategory;
+        this.reason =
+            options?.reason ??
+                (options?.userCategory === "permission_required"
+                    ? "permission_required"
+                    : options?.userCategory === "cancelled"
+                        ? "cancelled"
+                        : "capture_failed");
+        this.cleanupIncomplete = this.reason === "cleanup_incomplete";
+        this.cleanupResources = options?.cleanupResources ?? [];
     }
 }
 /** Caller-visible cancellation without exposing capture implementation state. */
 export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
     userCategory: "cancelled",
+    reason: "cancelled",
     userMessage: "Process capture was cancelled. Start it again when ready.",
 });

package/dist/application/ProcessCaptureLifecycle.js

@@ -249,7 +249,9 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
             cause: executionFailure,
         });
     if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure);
+        throw new ProcessCaptureError(cleanupFailure, {
+            reason: "cleanup_incomplete",
+        });
     if (capture === undefined)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;

package/dist/application/ProcessCli.js

@@ -1,21 +1,13 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
-import { AnalysisError, projectAnalysisError } from "../domain/errors.js";
+import { AnalysisError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
+import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 const MAX_INPUT_BYTES = 64 * 1024 * 1024;
-/** Distinguish a safe process-command failure from successful Evidence. */
-export const isProcessCliErrorOutput = (value) => typeof value === "object" &&
-    value !== null &&
-    "error" in value &&
-    value.error === "Process command failed" &&
-    "category" in value &&
-    typeof value.category === "string" &&
-    "message" in value &&
-    typeof value.message === "string";
 /** Capture one JSON scenario through the same policy and evidence contract as MCP. */
 export const captureProcessScenarioFile = async (path) => {
     try {
@@ -30,6 +22,27 @@ export const captureProcessScenarioFile = async (path) => {
         const config = parseConfig(process.env);
         if (!config.ok)
             return cliAnalysisError(config.error);
+        const authority = await loadConfiguredPermissionAuthority(config.value);
+        if (!authority.ok)
+            return cliAnalysisError(authority.error);
+        const authorized = await authority.value.authorize({
+            capability: "process_capture",
+            roots: [scenario.working_directory, ...scenario.filesystem_roots],
+            executables: [scenario.executable],
+            environment_names: [
+                ...Object.keys(scenario.environment),
+                ...scenario.inherit_environment,
+            ],
+            network: scenario.network_access === "host" ? "external" : "none",
+            mount: false,
+            operation_identity: `capture_process_scenario:${scenario.executable}`,
+        }, "read");
+        if (!authorized.ok)
+            return cliAnalysisError(authorized.error instanceof PermissionRequiredError
+                ? authorized.error
+                : new AnalysisProtocolError(authorized.error.message, {
+                    cause: authorized.error,
+                }));
         const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
         if (!captured.ok)
             return cliAnalysisError(captured.error);

package/dist/application/ProcessHarness.js

@@ -98,7 +98,10 @@ const cleanupFailedStartup = async (options) => {
         sampledProcessGroupIds: [],
     });
     if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure, { cause: options.cause });
+        throw new ProcessCaptureError(cleanupFailure, {
+            cause: options.cause,
+            reason: "cleanup_incomplete",
+        });
     throw options.cause;
 };
 const createTerminalRenderer = (scenario, temporaryRoot, terminalPid) => new TerminalRenderer({

package/dist/application/ProgressReporter.js

@@ -0,0 +1,30 @@
+/** Create a monotonic, rate-bounded reporter around a surface-specific sink. */
+export const createProgressReporter = (sink, options = {}) => {
+    const minimumIntervalMs = options.minimumIntervalMs ?? 100;
+    const now = options.now ?? Date.now;
+    let lastCompleted = -1;
+    let lastSentAt = Number.NEGATIVE_INFINITY;
+    let sequence = 0;
+    return {
+        async report(update) {
+            if (!Number.isFinite(update.completed) || update.completed < 0)
+                throw new TypeError("Progress completed must be a nonnegative number");
+            if (update.total !== null && update.total < update.completed)
+                throw new TypeError("Progress total cannot be less than completed");
+            if (update.completed < lastCompleted)
+                throw new TypeError("Progress cannot move backwards");
+            lastCompleted = update.completed;
+            const observedAt = now();
+            if (update.terminal !== true &&
+                observedAt - lastSentAt < minimumIntervalMs)
+                return;
+            lastSentAt = observedAt;
+            sequence += 1;
+            await sink({ ...update, sequence });
+        },
+    };
+};
+/** Surface that deliberately ignores progress while preserving one workflow API. */
+export const silentProgressReporter = {
+    report: () => Promise.resolve(),
+};

package/dist/application/ProjectPermissionStore.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+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",
+        "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()),
+    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 parsed = storeSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+        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 }));
+    }
+};
+const isNotFound = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";

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/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/catalogIdentity.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
+import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
+/** Explicit CLI command inventory, kept separate from MCP tool counts. */
+export const CLI_COMMAND_NAMES = [
+    "analyze",
+    "inspect",
+    "decompile",
+    "setup",
+    "doctor",
+    "uninstall",
+    "upgrade",
+    "xrefs",
+    "trace",
+    "capabilities",
+    "providers",
+    "function",
+    "search",
+    "import-reference-source",
+    "inventory-artifact",
+    "extract-artifact",
+    "inspect-macho",
+    "inspect-signature",
+    "list-architectures",
+    "inspect-plist",
+    "demangle-swift",
+    "evidence-import",
+    "evidence-export",
+    "compare",
+    "investigate-versions",
+    "capture-process",
+    "compare-process-captures",
+    "policy",
+];
+const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
+    name: contract.name,
+    surface: contract.kind,
+    description: contract.description,
+    annotations: contract.annotations,
+    input_schema: z.toJSONSchema(contract.inputSchema, {
+        unrepresentable: "any",
+    }),
+    output_schema: z.toJSONSchema(contract.outputSchema, {
+        unrepresentable: "any",
+    }),
+})).sort((left, right) => left.name.localeCompare(right.name));
+const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
+    name: contract.name,
+    title: contract.title,
+    description: contract.description,
+    arguments: contract.arguments,
+    steps: contract.steps,
+})).sort((left, right) => left.name.localeCompare(right.name));
+const resourceCatalog = [
+    { name: "server-identity", uri: "rea://server/identity" },
+    { name: "active-residual-unknowns", uri: "rea://unknowns/active" },
+];
+const resourceTemplateCatalog = [
+    { name: "session-evidence", uri_template: "rea://evidence/{evidenceId}" },
+    {
+        name: "evidence-section",
+        uri_template: "rea://evidence/{evidenceId}/section/{section}",
+    },
+    { name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
+    {
+        name: "analysis-snapshot",
+        uri_template: "rea://snapshot/{snapshotDigest}",
+    },
+    {
+        name: "artifact-page",
+        uri_template: "rea://artifact/{manifestId}/{collection}",
+    },
+    {
+        name: "function-dossier",
+        uri_template: "rea://function/{targetSha256}/{address}",
+    },
+    {
+        name: "investigation-workspace-revision",
+        uri_template: "rea://workspace/{workspaceId}/revision/{revision}",
+    },
+];
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Catalog is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+/** Stable, schema-sensitive identity for every public REA surface. */
+export const CATALOG_IDENTITY = {
+    counts: {
+        cli_commands: CLI_COMMAND_NAMES.length,
+        mcp_tools: toolCatalog.length,
+        mcp_prompts: promptCatalog.length,
+        mcp_resources: resourceCatalog.length,
+        mcp_resource_templates: resourceTemplateCatalog.length,
+    },
+    digests: {
+        tools_sha256: digest(toolCatalog),
+        prompts_sha256: digest(promptCatalog),
+        resources_sha256: digest({ resourceCatalog, resourceTemplateCatalog }),
+        combined_sha256: digest({
+            cli: CLI_COMMAND_NAMES,
+            tools: toolCatalog,
+            prompts: promptCatalog,
+            resources: resourceCatalog,
+            resource_templates: resourceTemplateCatalog,
+        }),
+    },
+    tools: toolCatalog.map(({ name, surface, annotations }) => ({
+        name,
+        surface,
+        annotations: {
+            read_only: annotations.readOnlyHint ?? false,
+            destructive: annotations.destructiveHint ?? false,
+            idempotent: annotations.idempotentHint ?? false,
+            open_world: annotations.openWorldHint ?? true,
+        },
+    })),
+};