rea-agents 3.2.0 → 4.0.0

package/dist/application/NodeRuntimeCharacterizationService.js

@@ -1,191 +0,0 @@
-import { createHash } from "node:crypto";
-import { z } from "zod";
-import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
-import { AnalysisInputError, AnalysisProtocolError, ReplayPlanStaleError, } from "../domain/errors.js";
-import { createEvidence } from "../domain/evidence.js";
-import { controlledReplayOutputSchema, } from "../domain/javascriptReplay.js";
-import { createRuntimeCharacterizationPlan, } from "../domain/runtimeCharacterization.js";
-import { err, ok } from "../domain/result.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
-import { InstrumentedJavaScriptReplayHost } from "./InstrumentedJavaScriptReplayHost.js";
-import { runControlledReplayValidated, } from "./JavaScriptReplayService.js";
-const PREPARE_OPERATION = "prepare_node_characterization";
-const EXECUTE_OPERATION = "execute_node_characterization";
-const PROVIDER = {
-    id: "rea-node-characterization",
-    name: "REA Node runtime characterization",
-    version: "1",
-};
-/** Prepare exact Node/JavaScript characterization without executing target code. */
-export const prepareNodeCharacterization = async (dependencies, rawInput, options = {}) => {
-    const parsed = nodeCharacterizationPreparationInputSchema.safeParse(rawInput);
-    if (!parsed.success)
-        return err(new AnalysisInputError(PREPARE_OPERATION, { cause: parsed.error }));
-    const prepared = await prepareValidated(dependencies, parsed.data, options);
-    return prepared.ok
-        ? ok(jsonValueSchema.parse(nodeCharacterizationPreparationOutputSchema.parse(prepared.value)))
-        : prepared;
-};
-/** Execute only a freshly recomputed and separately approved characterization plan. */
-export const executeNodeCharacterization = async (dependencies, rawInput, options = {}) => {
-    const parsed = nodeCharacterizationExecutionInputSchema.safeParse(rawInput);
-    if (!parsed.success)
-        return err(new AnalysisInputError(EXECUTE_OPERATION, { cause: parsed.error }));
-    const prepared = await prepareValidated(dependencies, parsed.data.preparation, options);
-    if (!prepared.ok)
-        return prepared;
-    if (prepared.value.plan.plan_sha256 !== parsed.data.approved_plan_sha256)
-        return err(new ReplayPlanStaleError(parsed.data.approved_plan_sha256, prepared.value.plan.plan_sha256));
-    const plannedReplay = controlledReplayOutputSchema.parse(prepared.value.replay);
-    if (plannedReplay.phase !== "plan")
-        return err(new AnalysisProtocolError("Node characterization preparation did not produce a replay plan"));
-    const host = new InstrumentedJavaScriptReplayHost(dependencies.host, parsed.data.preparation.instrumentation);
-    const executed = await runControlledReplayValidated({ ...dependencies, host }, {
-        ...parsed.data.preparation.replay,
-        mode: "execute",
-        plan_digest: plannedReplay.plan.plan_digest,
-    }, options);
-    if (!executed.ok)
-        return executed;
-    const replayOutput = controlledReplayOutputSchema.parse(executed.value);
-    if (replayOutput.phase !== "execute")
-        return err(new AnalysisProtocolError("Node characterization execution omitted replay Evidence"));
-    if (host.instrumentation === null)
-        return err(new AnalysisProtocolError("Node characterization execution omitted instrumentation evidence"));
-    return ok(jsonValueSchema.parse(nodeCharacterizationExecutionOutputSchema.parse({
-        phase: "execution",
-        plan: prepared.value.plan,
-        transformation: host.instrumentation.manifest,
-        transformation_evidence: prepared.value.transformation_evidence,
-        evidence: createCharacterizationEvidence(prepared.value, replayOutput),
-        replay: replayOutput,
-    })));
-};
-const prepareValidated = async (dependencies, input, options) => {
-    const host = new InstrumentedJavaScriptReplayHost(dependencies.host, input.instrumentation);
-    const replay = await runControlledReplayValidated({ ...dependencies, host }, input.replay, options);
-    if (!replay.ok)
-        return replay;
-    const output = controlledReplayOutputSchema.parse(replay.value);
-    if (output.phase !== "plan" || host.instrumentation === null)
-        return err(new AnalysisProtocolError("Node characterization preparation omitted committed plan evidence"));
-    const module = output.plan.left.modules.find(({ alias }) => alias === input.selected_alias);
-    if (module === undefined)
-        return err(new AnalysisProtocolError("Node characterization replay plan omitted selected module"));
-    const plan = createCharacterizationPlan(input, host.instrumentation, output.plan);
-    return ok({
-        phase: "preparation",
-        plan,
-        transformation: host.instrumentation.manifest,
-        transformation_evidence: createTransformationEvidence(input, host.instrumentation),
-        replay: output,
-    });
-};
-const createTransformationEvidence = (input, instrumentation) => createEvidence({
-    path: input.instrumentation.artifact_path,
-    sha256: input.instrumentation.artifact_sha256,
-    format: "javascript-bundle",
-}, PROVIDER, {
-    predicateType: "rea.javascript-export-transformation",
-    operation: PREPARE_OPERATION,
-    parameters: {
-        selected_alias: input.selected_alias,
-        selected_sha256: input.instrumentation.selection.selected_sha256,
-    },
-    result: jsonValueSchema.parse(instrumentation.manifest),
-    confidence: "derived",
-    authority: "shipped-artifact",
-    locations: [
-        {
-            kind: "file-offset-range",
-            start: input.instrumentation.selection.byte_start,
-            end: input.instrumentation.selection.byte_end,
-        },
-    ],
-    limitations: [
-        "The transformation is deterministic derived evidence; execution authority is established only by a separately approved characterization run.",
-    ],
-});
-const createCharacterizationEvidence = (prepared, replay) => {
-    return createEvidence({
-        path: prepared.plan.artifact.path,
-        sha256: prepared.plan.artifact.sha256,
-        format: "javascript-bundle",
-    }, PROVIDER, {
-        predicateType: "rea.runtime-characterization",
-        operation: EXECUTE_OPERATION,
-        parameters: {
-            plan_sha256: prepared.plan.plan_sha256,
-            replay_evidence_id: replay.evidence.evidence_id,
-        },
-        result: jsonValueSchema.parse({
-            plan: prepared.plan,
-            transformation_evidence_id: prepared.transformation_evidence.evidence_id,
-            replay_evidence_id: replay.evidence.evidence_id,
-            execution: replay.evidence.normalized_result,
-        }),
-        confidence: "observed",
-        authority: "controlled-replay",
-        environment: replay.evidence.environment,
-        limitations: [
-            "This Evidence proves only the finite approved characterization plan and transformed controlled-replay authority, not unmodified shipped-runtime equivalence.",
-            ...replay.evidence.limitations,
-        ],
-        evidenceLinks: [
-            prepared.transformation_evidence.evidence_id,
-            replay.evidence.evidence_id,
-        ],
-    });
-};
-const createCharacterizationPlan = (input, instrumentation, replayPlan) => createRuntimeCharacterizationPlan({
-    preparation_sha256: digestPreparation(instrumentation.manifest.instrumented_sha256, replayPlan.plan_digest),
-    artifact: {
-        path: input.instrumentation.artifact_path,
-        sha256: input.instrumentation.artifact_sha256,
-        byte_length: instrumentation.manifest.original_byte_length,
-    },
-    runtime: {
-        family: "ecmascript",
-        provider_id: "node-javascript",
-        executable_path: replayPlan.runtime.executable.path,
-        executable_sha256: replayPlan.runtime.executable.sha256,
-        version: replayPlan.runtime.executable.version,
-        profile_sha256: replayPlan.policy_sha256,
-    },
-    callable: {
-        callable_id: `callable/${input.instrumentation.selection.selected_sha256}`,
-        module_id: stableModuleId(input.selected_alias),
-        export_name: input.instrumentation.selection.export_name,
-        semantic_evidence_id: null,
-        selector_sha256: input.instrumentation.selection.selected_sha256,
-    },
-    working_directory: "/work",
-    isolated_home: "/work",
-    expected_effect: input.expected_effect,
-    allowed_boundaries: [],
-    limits: {
-        max_calls: replayPlan.cases.length,
-        max_processes: 0,
-        max_files: 0,
-        max_bytes: replayPlan.limits.output_bytes,
-        max_handles: replayPlan.limits.tasks,
-        timeout_ms: replayPlan.limits.wall_time_ms,
-        idle_timeout_ms: replayPlan.limits.wall_time_ms,
-    },
-    determinism: {
-        clock: "fixed",
-        randomness: "seeded",
-        identifiers: "deterministic",
-        seed: replayPlan.determinism.random_seed,
-    },
-    authority: {
-        preparation_approved: true,
-        execution_approved: false,
-        network: "none",
-        provider_owned_process_only: true,
-    },
-});
-const digestPreparation = (instrumentedSha256, replayPlanDigest) => createHash("sha256")
-    .update(`rea.node-characterization-preparation\0${instrumentedSha256}\0${replayPlanDigest}`)
-    .digest("hex");
-const stableModuleId = (alias) => `module/${createHash("sha256").update(alias).digest("hex")}`;

package/dist/application/PermissionAuthority.js

@@ -1,268 +0,0 @@
-import { realpath } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
-import { consumePermission, clearSessionPermissions, createPermissionPolicy, evaluatePermission, grantPermission, reloadPermissionCeilings, revokePermission, } from "../domain/permissionPolicy.js";
-import { PermissionRequiredError, } from "../domain/errors.js";
-import { err, ok } from "../domain/result.js";
-/** Failure to establish a filesystem object's canonical authorization identity. */
-export class PermissionPathError extends Error {
-    path;
-    reason;
-    _tag = "PermissionPathError";
-    constructor(path, reason, options) {
-        super(`Cannot canonicalize permission path: ${path}`, options);
-        this.path = path;
-        this.reason = reason;
-    }
-}
-/** Canonicalize administrator ceilings before they become authorization state. */
-export const canonicalizePermissionCeilings = async (ceilings) => {
-    const normalized = [];
-    for (const ceiling of ceilings) {
-        const canonical = await canonicalizeScope(ceiling, "read");
-        if (!canonical.ok)
-            return canonical;
-        normalized.push(canonical.value);
-    }
-    return ok(normalized);
-};
-/** Canonicalize one exact operation request before subset evaluation. */
-export const canonicalizePermissionRequest = async (request, access) => {
-    const canonical = await canonicalizeScope(request, access);
-    return canonical.ok
-        ? ok({ ...canonical.value, operation_identity: request.operation_identity })
-        : canonical;
-};
-const canonicalizeScope = async (scope, access) => {
-    const roots = await canonicalizePaths(scope.roots, access);
-    if (!roots.ok)
-        return roots;
-    const executables = await canonicalizePaths(scope.executables, "read");
-    if (!executables.ok)
-        return executables;
-    return ok({ ...scope, roots: roots.value, executables: executables.value });
-};
-const canonicalizePaths = async (paths, access) => {
-    const canonical = [];
-    for (const path of paths) {
-        const result = await canonicalizePath(path, access);
-        if (!result.ok)
-            return result;
-        canonical.push(result.value);
-    }
-    return ok(canonical);
-};
-const canonicalizePath = async (path, access) => {
-    const requested = resolve(path);
-    try {
-        return ok(await realpath(requested));
-    }
-    catch (cause) {
-        if (access !== "write" || !isNotFound(cause))
-            return err(new PermissionPathError(path, errorReason(cause), { cause }));
-    }
-    try {
-        const parent = await realpath(dirname(requested));
-        return ok(join(parent, basename(requested)));
-    }
-    catch (cause) {
-        return err(new PermissionPathError(path, errorReason(cause), { cause }));
-    }
-};
-const isNotFound = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
-const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
-/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
-export class PermissionAuthority {
-    policy;
-    configuredAuthority;
-    outsideCeilingRemediation;
-    constructor(policy, configuredAuthority, outsideCeilingRemediation = "configure") {
-        this.policy = policy;
-        this.configuredAuthority = configuredAuthority;
-        this.outsideCeilingRemediation = outsideCeilingRemediation;
-    }
-    /** Create a connection-owned overlay for once and session grants. */
-    createConnectionAuthority() {
-        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this, "restart");
-    }
-    /** Canonicalize and authorize one exact operation before its side effect. */
-    async authorize(request, access, options = {}) {
-        const evaluated = await this.evaluateRequest(request, access, options);
-        if (!evaluated.ok)
-            return evaluated;
-        const { decision, owner, request: canonicalRequest } = evaluated.value;
-        owner.policy = consumePermission(owner.policy, decision);
-        return ok({ ...decision, request: canonicalRequest });
-    }
-    /** Dry-run the exact shared evaluation without consuming a once grant. */
-    async explain(request, access, options = {}) {
-        const evaluated = await this.evaluateRequest(request, access, options);
-        return evaluated.ok
-            ? ok({
-                ...evaluated.value.decision,
-                request: evaluated.value.request,
-            })
-            : evaluated;
-    }
-    async evaluateRequest(request, access, options) {
-        const canonical = await canonicalizePermissionRequest(request, access);
-        if (!canonical.ok)
-            return canonical;
-        const evaluated = this.evaluateCanonical(canonical.value, options);
-        return evaluated.ok
-            ? ok({ ...evaluated.value, request: canonical.value })
-            : evaluated;
-    }
-    /** Add authority beneath the administrator ceiling. */
-    grant(grant) {
-        const policy = this.configuredAuthority === undefined
-            ? this.policy
-            : {
-                ...this.policy,
-                ceilings: this.configuredAuthority.effectivePolicy().ceilings,
-            };
-        const result = grantPermission(policy, grant);
-        if (result.ok)
-            this.policy = result.value;
-        return result;
-    }
-    /** Revoke authority immediately for subsequent operations. */
-    revoke(grantId) {
-        this.policy = revokePermission(this.policy, grantId);
-    }
-    /** Drop once/session authority when its owning connection ends. */
-    clearSessionGrants() {
-        this.policy = clearSessionPermissions(this.policy);
-    }
-    effectivePolicy() {
-        if (this.configuredAuthority === undefined)
-            return this.policy;
-        const configured = this.configuredAuthority.effectivePolicy();
-        return {
-            ceilings: configured.ceilings,
-            grants: [...configured.grants, ...this.policy.grants],
-            revoked_grant_ids: new Set([
-                ...configured.revoked_grant_ids,
-                ...this.policy.revoked_grant_ids,
-            ]),
-            consumed_grant_ids: new Set([
-                ...configured.consumed_grant_ids,
-                ...this.policy.consumed_grant_ids,
-            ]),
-        };
-    }
-    evaluateCanonical(request, options) {
-        const configured = this.configuredAuthority;
-        if (configured !== undefined) {
-            const configuredDecision = evaluatePermission(configured.effectivePolicy(), request);
-            if (configuredDecision.allowed)
-                return ok({ decision: configuredDecision, owner: configured });
-        }
-        const localPolicy = configured === undefined
-            ? this.policy
-            : { ...this.policy, ceilings: configured.effectivePolicy().ceilings };
-        const localDecision = evaluatePermission(localPolicy, request);
-        if (localDecision.allowed)
-            return ok({ decision: localDecision, owner: this });
-        const effective = this.effectivePolicy();
-        const denied = evaluatePermission(effective, request);
-        if (denied.allowed)
-            return ok({ decision: denied, owner: this });
-        const outsideAdministratorCeiling = denied.reason === "outside_administrator_ceiling";
-        const requestedRemediation = options.remediation ?? "configure";
-        const remediation = outsideAdministratorCeiling && requestedRemediation !== "restart"
-            ? this.outsideCeilingRemediation
-            : requestedRemediation;
-        return err(new PermissionRequiredError({
-            requested: request,
-            missing: denied.missing,
-            ceiling: ceilingFor(effective, request.capability),
-            remediation,
-        }));
-    }
-    /** Atomically replace optional persisted project grants. */
-    async replaceProjectGrants(grants) {
-        return this.replaceGrants(grants, "project");
-    }
-    /** Replace grants derived from the currently loaded administrator ceiling. */
-    async replaceAdministratorGrants(grants) {
-        return this.replaceGrants(grants, "administrator");
-    }
-    async replaceGrants(grants, lifetime) {
-        const canonical = await canonicalizeGrants(grants);
-        if (!canonical.ok)
-            return canonical;
-        const replaced = addGrantsToPolicy({
-            ...this.policy,
-            grants: this.policy.grants.filter((grant) => grant.lifetime !== lifetime),
-        }, canonical.value);
-        if (!replaced.ok)
-            return replaced;
-        this.policy = replaced.value;
-        return ok(null);
-    }
-    /** Atomically replace reloadable ceilings and persisted grants. */
-    async replaceConfiguredPolicy(configuration) {
-        const ceilings = await canonicalizePermissionCeilings(configuration.ceilings);
-        if (!ceilings.ok)
-            return ceilings;
-        const grants = await canonicalizeGrants([
-            ...configuration.administratorGrants,
-            ...configuration.projectGrants,
-        ]);
-        if (!grants.ok)
-            return grants;
-        const candidate = {
-            ...reloadPermissionCeilings(this.policy, ceilings.value),
-            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator" && lifetime !== "project"),
-        };
-        const replaced = addGrantsToPolicy(candidate, grants.value);
-        if (!replaced.ok)
-            return replaced;
-        this.policy = replaced.value;
-        return ok(null);
-    }
-    /** Replace ceilings without restarting the MCP process. */
-    async reload(ceilings) {
-        const canonical = await canonicalizePermissionCeilings(ceilings);
-        if (!canonical.ok)
-            return canonical;
-        this.policy = reloadPermissionCeilings(this.policy, canonical.value);
-        return ok(null);
-    }
-}
-/** Create one canonical policy and optional grants at the composition root. */
-export const createPermissionAuthority = async (ceilings, grants = []) => {
-    const canonical = await canonicalizePermissionCeilings(ceilings);
-    if (!canonical.ok)
-        return canonical;
-    const canonicalGrants = await canonicalizeGrants(grants);
-    if (!canonicalGrants.ok)
-        return canonicalGrants;
-    const policy = addGrantsToPolicy(createPermissionPolicy(canonical.value), canonicalGrants.value);
-    return policy.ok ? ok(new PermissionAuthority(policy.value)) : policy;
-};
-const canonicalizeGrants = async (grants) => {
-    const canonical = [];
-    for (const grant of grants) {
-        const canonicalGrant = await canonicalizeGrant(grant);
-        if (!canonicalGrant.ok)
-            return canonicalGrant;
-        canonical.push(canonicalGrant.value);
-    }
-    return ok(canonical);
-};
-const addGrantsToPolicy = (initial, grants) => {
-    let policy = initial;
-    for (const grant of grants) {
-        const added = grantPermission(policy, grant);
-        if (!added.ok)
-            return err(new PermissionPathError(grant.grant_id, "io", { cause: added.error }));
-        policy = added.value;
-    }
-    return ok(policy);
-};
-const canonicalizeGrant = async (grant) => {
-    const scope = await canonicalizeScope(grant, "read");
-    return scope.ok ? ok({ ...grant, ...scope.value }) : scope;
-};
-const ceilingFor = (policy, capability) => policy.ceilings.find((ceiling) => ceiling.capability === capability) ?? null;

package/dist/application/PermissionConfiguration.js

@@ -1,26 +0,0 @@
-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/PermissionFailure.js

@@ -1,5 +0,0 @@
-import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
-/** Preserve permission denials and project failed path resolution for callers. */
-export const projectPermissionFailure = (error) => error instanceof PermissionRequiredError
-    ? error
-    : new AnalysisProtocolError(error.message, { cause: error });

package/dist/application/ProcessCaptureAuthority.js

@@ -1,24 +0,0 @@
-import { realpath } from "node:fs/promises";
-import { isPathWithinRoot } from "../domain/localPath.js";
-import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
-import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
-export const assertRealPathAuthority = async (scenario, policy) => {
-    const executable = await realpath(scenario.executable);
-    const executableRoots = await canonicalizeConfiguredRoots(policy.executableRoots);
-    if (!executableRoots.some((root) => isPathWithinRoot(root, executable)))
-        throw new ProcessCaptureError("resolved executable is outside approved roots");
-    const workingDirectory = await realpath(scenario.working_directory);
-    const workingRoots = await canonicalizeConfiguredRoots(policy.workingRoots);
-    if (!workingRoots.some((root) => isPathWithinRoot(root, workingDirectory)))
-        throw new ProcessCaptureError("resolved working directory is outside approved roots");
-    for (const root of scenario.filesystem_roots) {
-        const resolvedRoot = await realpath(root);
-        if (!workingRoots.some((approved) => isPathWithinRoot(approved, resolvedRoot)))
-            throw new ProcessCaptureError("resolved filesystem root is outside approved roots");
-    }
-};
-/** Reject cancellation before a process capture operation begins. */
-export const assertNotCancelled = (signal) => {
-    if (signal?.aborted === true)
-        throw processCaptureCancelled();
-};

package/dist/application/ProcessCapturePermission.js

@@ -1,13 +0,0 @@
-/** Build the exact permission request shared by process-capture adapters. */
-export const processCapturePermissionRequest = (scenario) => ({
-    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}`,
-});