rea-agents 3.0.0 → 3.2.0

package/dist/domain/investigationWorkspace.js

@@ -1,346 +0,0 @@
-import { createHash } from "node:crypto";
-import canonicalize from "canonicalize";
-import { z } from "zod";
-import { evidenceBundleSchema, parseEvidenceBundle, } from "./evidenceBundle.js";
-const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
-const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
-const artifactFormatSchema = evidenceBundleSchema.shape.artifacts.element.shape.format;
-/** Bounded controls for one automatic, provider-neutral artifact comparison. */
-const investigationRunOptionsSchema = z.object({
-    max_entries: z.number().int().min(1).max(50_000).default(10_000),
-    max_total_bytes: z
-        .number()
-        .int()
-        .min(1)
-        .max(Number.MAX_SAFE_INTEGER)
-        .default(1_073_741_824),
-    max_entry_bytes: z
-        .number()
-        .int()
-        .min(1)
-        .max(Number.MAX_SAFE_INTEGER)
-        .default(268_435_456),
-    max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
-    max_depth: z.number().int().min(0).max(100).default(20),
-    max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
-    page_size: z.number().int().min(1).max(500).default(500),
-    change_limit: z.number().int().min(1).max(500).default(500),
-});
-const DEFAULT_INVESTIGATION_RUN_OPTIONS = {
-    max_entries: 10_000,
-    max_total_bytes: 1_073_741_824,
-    max_entry_bytes: 268_435_456,
-    max_compression_ratio: 1_000,
-    max_depth: 20,
-    max_path_bytes: 4_096,
-    page_size: 500,
-    change_limit: 500,
-};
-/** Explicit write approval and two local versions for an automatic run. */
-export const crossVersionInvestigationInputSchema = z
-    .object({
-    approved: z.literal(true),
-    workspace_path: z.string().min(1).max(4_096),
-    workspace_name: z.string().trim().min(1).max(200).default("default"),
-    expected_workspace_revision: z.number().int().min(1).optional(),
-    replay_run_id: z
-        .string()
-        .regex(/^run_[a-f0-9]{64}$/u)
-        .optional(),
-    left_path: z.string().min(1).max(4_096),
-    right_path: z.string().min(1).max(4_096),
-    integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
-    integrity_continue_approved: z.boolean().default(false),
-    max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
-    options: investigationRunOptionsSchema.default(DEFAULT_INVESTIGATION_RUN_OPTIONS),
-})
-    .superRefine((input, context) => {
-    if (input.integrity_policy === "record-and-continue" &&
-        input.integrity_continue_approved !== true)
-        context.addIssue({
-            code: "custom",
-            path: ["integrity_continue_approved"],
-            message: "record-and-continue requires explicit approval",
-        });
-});
-const targetSchema = z.object({
-    root_sha256: digestSchema,
-    graph_sha256: digestSchema,
-    manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
-    format: artifactFormatSchema,
-});
-const stageSchema = z.enum([
-    "inventory_left",
-    "inventory_right",
-    "compare_artifacts",
-    "find_changed_behavior",
-]);
-const investigationRunBaseSchema = z.object({
-    schema_version: z.literal(1),
-    run_id: z.string().regex(/^run_[a-f0-9]{64}$/u),
-    request_sha256: digestSchema,
-    left: targetSchema,
-    right: targetSchema,
-    options: investigationRunOptionsSchema,
-    integrity_policy: z.enum(["fail", "record-and-continue"]),
-    integrity_continue_approved: z.boolean(),
-    max_integrity_mismatches: z.number().int().min(1).max(100),
-    status: z.enum(["running", "complete"]),
-    completed_stages: z.array(stageSchema).max(4),
-    left_inventory_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
-    right_inventory_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
-    comparison_evidence_id: evidenceIdSchema.nullable(),
-    result_evidence_id: evidenceIdSchema.nullable(),
-    limitations: z.array(z.string().max(4_096)).max(100),
-});
-export const investigationRunSchema = z
-    .union([
-    investigationRunBaseSchema.extend({
-        legacy_request_identity: z.literal(true),
-    }),
-    investigationRunBaseSchema,
-])
-    .superRefine((run, context) => {
-    if (!("legacy_request_identity" in run))
-        return;
-    const legacyIdentity = createLegacyInvestigationRunIdentity(run);
-    if (run.integrity_policy !== "fail" ||
-        run.integrity_continue_approved ||
-        run.max_integrity_mismatches !== 10 ||
-        run.run_id !== legacyIdentity.runId ||
-        run.request_sha256 !== legacyIdentity.requestSha256)
-        context.addIssue({
-            code: "custom",
-            path: ["legacy_request_identity"],
-            message: "Legacy request identity is valid only for migrated strict runs",
-        });
-});
-export const investigationRunSummarySchema = z.object({
-    schema_version: z.literal(1),
-    workspace_id: z.string().regex(/^ws_[a-f0-9]{64}$/u),
-    run_id: z.string().regex(/^run_[a-f0-9]{64}$/u),
-    left_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
-    right_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
-    inventory_evidence_count: z.number().int().min(2).max(200),
-    comparison_evidence_id: evidenceIdSchema,
-    limitations: z.array(z.string().max(4_096)).max(100),
-});
-/** Durable schema for one revisioned cross-version investigation workspace. */
-export const investigationWorkspaceSchema = z.object({
-    workspace_version: z.literal(1),
-    workspace_id: z.string().regex(/^ws_[a-f0-9]{64}$/u),
-    name: z.string().trim().min(1).max(200),
-    revision: z.number().int().min(1),
-    previous_revision_digest: z
-        .string()
-        .regex(/^wrev_[a-f0-9]{64}$/u)
-        .nullable(),
-    revision_digest: z.string().regex(/^wrev_[a-f0-9]{64}$/u),
-    bundle: evidenceBundleSchema,
-    runs: z.array(investigationRunSchema).max(1_000),
-});
-const legacyInvestigationRunSchema = investigationRunBaseSchema
-    .omit({
-    integrity_policy: true,
-    integrity_continue_approved: true,
-    max_integrity_mismatches: true,
-})
-    .strict();
-const legacyInvestigationWorkspaceSchema = investigationWorkspaceSchema
-    .extend({
-    runs: z.array(legacyInvestigationRunSchema).max(1_000),
-})
-    .strict();
-/** Derive a stable run identity from content commitments and bounded controls. */
-export const createInvestigationRunIdentity = (input) => {
-    const requestSha256 = digestCanonical({
-        schema: "rea.cross-version-investigation-request/v1",
-        left: input.left,
-        right: input.right,
-        options: input.options,
-        integrity: {
-            policy: input.integrity_policy,
-            approved: input.integrity_continue_approved,
-            max_mismatches: input.max_integrity_mismatches,
-        },
-    });
-    return { runId: `run_${requestSha256}`, requestSha256 };
-};
-/** Build the first canonical workspace revision. */
-export const createInvestigationWorkspace = (name, bundle, runs) => buildWorkspace({
-    workspaceId: `ws_${digestCanonical({ schema: "rea.workspace/v1", name })}`,
-    name,
-    revision: 1,
-    previousRevisionDigest: null,
-    bundle,
-    runs,
-});
-/** Create the next immutable workspace revision. */
-export const reviseInvestigationWorkspace = (current, bundle, runs) => buildWorkspace({
-    workspaceId: current.workspace_id,
-    name: current.name,
-    revision: current.revision + 1,
-    previousRevisionDigest: current.revision_digest,
-    bundle,
-    runs,
-});
-/** Parse a workspace and verify identities, revision digest, and references. */
-export const parseInvestigationWorkspace = (input) => {
-    if (isLegacyWorkspace(input))
-        return migrateLegacyWorkspace(input);
-    const parsed = investigationWorkspaceSchema.parse(input);
-    const bundle = parseEvidenceBundle(parsed.bundle);
-    const canonical = buildWorkspace({
-        workspaceId: parsed.workspace_id,
-        name: parsed.name,
-        revision: parsed.revision,
-        previousRevisionDigest: parsed.previous_revision_digest,
-        bundle,
-        runs: parsed.runs,
-    });
-    if (parsed.workspace_id !== workspaceIdFor(parsed.name))
-        throw new TypeError("Investigation workspace ID does not match its name");
-    if (parsed.revision_digest !== canonical.revision_digest)
-        throw new TypeError("Investigation workspace revision digest is invalid");
-    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
-        throw new TypeError("Investigation workspace is not canonical");
-    validateRunReferences(canonical);
-    return canonical;
-};
-/** Encode a validated workspace as byte-stable canonical JSON. */
-export const serializeInvestigationWorkspace = (workspace) => canonicalJson(parseInvestigationWorkspace(workspace));
-const buildWorkspace = (input) => {
-    const runs = [...input.runs]
-        .map((run) => investigationRunSchema.parse(run))
-        .sort((left, right) => left.run_id.localeCompare(right.run_id));
-    assertUnique(runs.map(({ run_id: id }) => id), "investigation run ID");
-    const semantic = {
-        workspace_version: 1,
-        workspace_id: input.workspaceId,
-        name: input.name,
-        revision: input.revision,
-        previous_revision_digest: input.previousRevisionDigest,
-        bundle: parseEvidenceBundle(input.bundle),
-        runs,
-    };
-    return investigationWorkspaceSchema.parse({
-        ...semantic,
-        revision_digest: `wrev_${digestCanonical(semantic)}`,
-    });
-};
-const validateRunReferences = (workspace) => {
-    const evidenceIds = new Set(workspace.bundle.records.map(({ evidence_id: id }) => id));
-    for (const run of workspace.runs) {
-        const expectedIdentity = createInvestigationRunIdentity(run);
-        const legacyIdentity = createLegacyInvestigationRunIdentity(run);
-        if ((run.run_id !== expectedIdentity.runId ||
-            run.request_sha256 !== expectedIdentity.requestSha256) &&
-            (!("legacy_request_identity" in run) ||
-                run.integrity_policy !== "fail" ||
-                run.integrity_continue_approved ||
-                run.max_integrity_mismatches !== 10 ||
-                run.run_id !== legacyIdentity.runId ||
-                run.request_sha256 !== legacyIdentity.requestSha256))
-            throw new TypeError("Investigation run identity is invalid");
-        validateRunStages(run);
-        const references = [
-            ...run.left_inventory_evidence_ids,
-            ...run.right_inventory_evidence_ids,
-            ...(run.comparison_evidence_id === null
-                ? []
-                : [run.comparison_evidence_id]),
-            ...(run.result_evidence_id === null ? [] : [run.result_evidence_id]),
-        ];
-        if (references.some((evidenceId) => !evidenceIds.has(evidenceId)))
-            throw new TypeError("Investigation run references missing Evidence");
-    }
-};
-/** Derive the pre-integrity-policy run identity for strict workspace migration. */
-export const createLegacyInvestigationRunIdentity = (input) => {
-    const requestSha256 = digestCanonical({
-        schema: "rea.cross-version-investigation-request/v1",
-        left: input.left,
-        right: input.right,
-        options: input.options,
-    });
-    return { runId: `run_${requestSha256}`, requestSha256 };
-};
-const isLegacyWorkspace = (input) => {
-    if (typeof input !== "object" || input === null || !("runs" in input))
-        return false;
-    const runs = input.runs;
-    return (Array.isArray(runs) &&
-        runs.some((run) => typeof run === "object" && run !== null && !("integrity_policy" in run)));
-};
-const migrateLegacyWorkspace = (input) => {
-    const parsed = legacyInvestigationWorkspaceSchema.parse(input);
-    const bundle = parseEvidenceBundle(parsed.bundle);
-    const runs = [...parsed.runs].sort((left, right) => left.run_id.localeCompare(right.run_id));
-    const semantic = {
-        workspace_version: 1,
-        workspace_id: parsed.workspace_id,
-        name: parsed.name,
-        revision: parsed.revision,
-        previous_revision_digest: parsed.previous_revision_digest,
-        bundle,
-        runs,
-    };
-    if (parsed.workspace_id !== workspaceIdFor(parsed.name))
-        throw new TypeError("Investigation workspace ID does not match its name");
-    if (parsed.revision_digest !== `wrev_${digestCanonical(semantic)}`)
-        throw new TypeError("Investigation workspace revision digest is invalid");
-    const canonical = legacyInvestigationWorkspaceSchema.parse({
-        ...semantic,
-        revision_digest: parsed.revision_digest,
-    });
-    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
-        throw new TypeError("Investigation workspace is not canonical");
-    for (const run of runs) {
-        const identity = createLegacyInvestigationRunIdentity(run);
-        if (run.run_id !== identity.runId ||
-            run.request_sha256 !== identity.requestSha256)
-            throw new TypeError("Investigation run identity is invalid");
-    }
-    const migrated = buildWorkspace({
-        workspaceId: parsed.workspace_id,
-        name: parsed.name,
-        revision: parsed.revision,
-        previousRevisionDigest: parsed.previous_revision_digest,
-        bundle,
-        runs: runs.map((run) => ({
-            ...run,
-            legacy_request_identity: true,
-            integrity_policy: "fail",
-            integrity_continue_approved: false,
-            max_integrity_mismatches: 10,
-        })),
-    });
-    validateRunReferences(migrated);
-    return migrated;
-};
-const validateRunStages = (run) => {
-    const expected = [
-        "inventory_left",
-        "inventory_right",
-        ...(run.comparison_evidence_id === null ? [] : ["compare_artifacts"]),
-        ...(run.result_evidence_id === null ? [] : ["find_changed_behavior"]),
-    ];
-    if (JSON.stringify(run.completed_stages) !== JSON.stringify(expected))
-        throw new TypeError("Investigation run stages are inconsistent");
-    if (run.status === "complete" && run.result_evidence_id === null)
-        throw new TypeError("Completed investigation run has no result Evidence");
-    if (run.status === "running" && run.result_evidence_id !== null)
-        throw new TypeError("Running investigation run has final result Evidence");
-};
-const workspaceIdFor = (name) => `ws_${digestCanonical({ schema: "rea.workspace/v1", name })}`;
-const digestCanonical = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
-const canonicalJson = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Investigation workspace could not canonicalize data");
-    return encoded;
-};
-const assertUnique = (values, description) => {
-    if (new Set(values).size !== values.length)
-        throw new TypeError(`Duplicate ${description}`);
-};

package/dist/domain/jsonLimits.js

@@ -1,26 +0,0 @@
-/** Return whether every node, key, and string fits within the supplied limits. */
-export const isJsonWithinLimits = (root, limits) => {
-    const pending = [
-        { value: root, depth: 0 },
-    ];
-    let nodes = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        nodes += 1;
-        if (nodes > limits.maxNodes || current.depth > limits.maxDepth)
-            return false;
-        if (typeof current.value === "string" &&
-            current.value.length > limits.maxStringLength)
-            return false;
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        for (const [key, value] of Object.entries(current.value)) {
-            if (key.length > limits.maxStringLength)
-                return false;
-            pending.push({ value, depth: current.depth + 1 });
-        }
-    }
-    return true;
-};

package/dist/domain/knownPageCoverage.js

@@ -1,21 +0,0 @@
-/**
- * Assess source-page and downstream-projection completeness without treating an
- * unreturned row as absent. `includedCount` is the number retained downstream.
- */
-export const assessKnownPageCoverage = (page, includedCount = page.items.length) => {
-    const observedCount = Math.min(page.total, page.returned, page.items.length);
-    const retainedCount = Math.min(observedCount, Math.max(0, Math.floor(includedCount)));
-    const sourceOmittedCount = Math.max(0, page.total - observedCount);
-    const sourceComplete = page.complete &&
-        page.offset === 0 &&
-        page.returned === page.total &&
-        sourceOmittedCount === 0;
-    const omittedCount = Math.max(0, page.total - retainedCount);
-    return {
-        complete: sourceComplete && omittedCount === 0,
-        sourceComplete,
-        includedCount: retainedCount,
-        omittedCount,
-        sourceOmittedCount,
-    };
-};

package/dist/domain/processPairedExperiment.js

@@ -1,128 +0,0 @@
-import { z } from "zod";
-import { PROCESS_COMPARISON_DIMENSIONS, compareProcessCaptures, processDimensionObservations, } from "./processComparison.js";
-import { digestProcessCommitment, processScenarioSchema, } from "./processScenario.js";
-const sideIdentifierSchema = z
-    .string()
-    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,127}$/u);
-const environmentNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
-const processDimensionSchema = z.enum(PROCESS_COMPARISON_DIMENSIONS);
-const sideBindingSchema = z
-    .object({
-    id: sideIdentifierSchema,
-    executable: z.string().startsWith("/"),
-    arguments: z.array(z.string()).max(256).optional(),
-    environment: z.record(environmentNameSchema, z.string()).default({}),
-})
-    .strict();
-/** Boundary contract for one bounded authority/candidate process experiment. */
-export const processPairedExperimentSchema = z
-    .object({
-    approved: z.literal(true),
-    shared_scenario: processScenarioSchema,
-    authority: sideBindingSchema,
-    candidate: sideBindingSchema,
-    repeat_count: z.number().int().min(2).max(10).default(3),
-    freshness_policy: z
-        .object({
-        max_capture_age_ms: z.number().int().positive().max(86_400_000),
-    })
-        .strict(),
-    required_dimensions: z
-        .array(processDimensionSchema)
-        .min(1)
-        .max(PROCESS_COMPARISON_DIMENSIONS.length)
-        .default([...PROCESS_COMPARISON_DIMENSIONS]),
-})
-    .strict()
-    .superRefine((experiment, context) => {
-    if (experiment.authority.id === experiment.candidate.id)
-        context.addIssue({
-            code: "custom",
-            message: "authority and candidate identities must differ",
-            path: ["candidate", "id"],
-        });
-    if (new Set(experiment.required_dimensions).size !==
-        experiment.required_dimensions.length)
-        context.addIssue({
-            code: "custom",
-            message: "required process dimensions must be unique",
-            path: ["required_dimensions"],
-        });
-});
-/** Apply a side binding without changing the shared observation contract. */
-export const bindProcessScenario = (shared, side) => processScenarioSchema.parse({
-    ...shared,
-    executable: side.executable,
-    arguments: side.arguments ?? shared.arguments,
-    environment: { ...shared.environment, ...side.environment },
-});
-const classifyInstability = (dimensions) => {
-    if (dimensions.has("exit"))
-        return "flaky_exit";
-    if (dimensions.has("filesystem") || dimensions.has("process"))
-        return "environmental_drift";
-    return "nondeterministic_output";
-};
-const timingKeys = new Set([
-    "at_ms",
-    "scheduled_at_ms",
-    "dispatched_at_ms",
-    "elapsed_ms",
-]);
-const withoutTiming = (value) => typeof value !== "object" || value === null || Array.isArray(value)
-    ? value
-    : Object.fromEntries(Object.entries(value).filter(([key]) => !timingKeys.has(key)));
-const observationsWithoutTiming = (capture, dimension) => dimension === "exit"
-    ? [
-        {
-            ...capture.exit,
-            settlement: {
-                state: capture.settlement.state,
-                cleanup_outcome: capture.settlement.cleanup_outcome,
-            },
-        },
-    ]
-    : processDimensionObservations(capture, dimension).map(withoutTiming);
-const hasOnlyTimingVariance = (captures, dimensions) => dimensions.every((dimension) => {
-    const first = captures[0];
-    if (first === undefined)
-        return false;
-    const baseline = JSON.stringify(observationsWithoutTiming(first, dimension));
-    return captures
-        .slice(1)
-        .every((capture) => JSON.stringify(observationsWithoutTiming(capture, dimension)) ===
-        baseline);
-});
-/** Compare same-side repeats before permitting a cross-side claim. */
-export const analyzeProcessRepeatability = (captures, requiredDimensions) => {
-    if (captures.length < 2)
-        return {
-            classification: "insufficient_samples",
-            stable: false,
-            digest: digestProcessCommitment({ captures: [], requiredDimensions }),
-            comparisons: [],
-            unstable_dimensions: [],
-        };
-    const baseline = captures[0];
-    if (baseline === undefined)
-        throw new TypeError("Repeatability analysis lost its baseline capture");
-    const comparisons = captures
-        .slice(1)
-        .map((capture) => compareProcessCaptures(baseline, capture));
-    const unstable = new Set(requiredDimensions.filter((dimension) => comparisons.some((comparison) => comparison[dimension] !== "unchanged")));
-    const unstableDimensions = PROCESS_COMPARISON_DIMENSIONS.filter((dimension) => unstable.has(dimension));
-    return {
-        classification: unstable.size === 0
-            ? "stable"
-            : hasOnlyTimingVariance(captures, unstableDimensions)
-                ? "timing_variance"
-                : classifyInstability(unstable),
-        stable: unstable.size === 0,
-        digest: digestProcessCommitment({
-            requiredDimensions,
-            comparisons,
-        }),
-        comparisons,
-        unstable_dimensions: unstableDimensions,
-    };
-};

package/dist/server/DynamicToolAvailability.js

@@ -1,70 +0,0 @@
-import { buildCapabilityInventory, } from "../application/CapabilityInventory.js";
-/**
- * Track public SDK tool handles and keep their visible state synchronized with
- * the same availability projection returned by `binary_session`.
- */
-export const installDynamicToolAvailability = (server, session, policy) => {
-    const tools = new Map();
-    const originalRegisterTool = server.registerTool.bind(server);
-    const originalSendToolListChanged = server.sendToolListChanged.bind(server);
-    let synchronizing = false;
-    const controller = {
-        synchronize: () => {
-            if (synchronizing)
-                return false;
-            synchronizing = true;
-            try {
-                const availability = new Map(buildCapabilityInventory(session.status(), policy(), clientFeatures(server)).map((item) => [item.name, item.available]));
-                let changed = false;
-                for (const [name, tool] of tools) {
-                    const enabled = availability.get(name) === true;
-                    if (tool.enabled === enabled)
-                        continue;
-                    changed = true;
-                    if (enabled)
-                        tool.enable();
-                    else
-                        tool.disable();
-                }
-                return changed;
-            }
-            finally {
-                synchronizing = false;
-            }
-        },
-    };
-    const wrappedRegisterTool = (...args) => {
-        const name = args[0];
-        if (typeof name !== "string")
-            throw new TypeError("MCP tool registration requires a string name");
-        const registered = Reflect.apply(originalRegisterTool, server, args);
-        if (!isRegisteredTool(registered))
-            throw new TypeError(`MCP SDK did not return a tool handle for ${name}`);
-        tools.set(name, registered);
-        return registered;
-    };
-    if (!Reflect.set(server, "registerTool", wrappedRegisterTool))
-        throw new TypeError("Unable to install dynamic MCP tool registration");
-    if (!Reflect.set(server, "sendToolListChanged", () => {
-        if (controller.synchronize())
-            originalSendToolListChanged();
-    }))
-        throw new TypeError("Unable to install dynamic MCP tool notifications");
-    return controller;
-};
-const clientFeatures = (server) => {
-    const capabilities = server.server.getClientCapabilities();
-    return {
-        elicitation_form: capabilities?.elicitation?.form !== undefined,
-        elicitation_url: capabilities?.elicitation?.url !== undefined,
-        roots: capabilities?.roots !== undefined,
-        sampling: capabilities?.sampling !== undefined,
-    };
-};
-const isRegisteredTool = (value) => {
-    if (typeof value !== "object" || value === null)
-        return false;
-    return (typeof Reflect.get(value, "enabled") === "boolean" &&
-        typeof Reflect.get(value, "enable") === "function" &&
-        typeof Reflect.get(value, "disable") === "function");
-};