rea-agents 2.4.0 → 3.0.0

package/dist/domain/browserScenarioCapture.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { browserScenarioCompletenessSchema, browserScenarioEventSchema, browserScenarioStepSchema, } from "./browserScenarioCaptureValues.js";
+export { browserScenarioCompletenessSchema, browserScenarioEventSchema, browserScenarioStepSchema, browserStepArtifactsSchema, captureStateSchema, } from "./browserScenarioCaptureValues.js";
+/** Step-indexed, explicitly bounded browser scenario observation. */
+export const browserScenarioCaptureSchema = z
+    .strictObject({
+    schema_version: z.literal(1),
+    browser: z.strictObject({
+        mode: z.enum(["launch", "connect"]),
+        process_ownership: z.enum(["provider-owned", "external"]),
+        cleanup: z.enum(["terminated-owned-process", "disconnected-external"]),
+        product: z.string().min(1).max(1_024),
+        version: z.string().min(1).max(256),
+    }),
+    scenario: z.strictObject({
+        start_origin: z.string().min(1).max(2_048),
+        allowed_origins: z.array(z.string().min(1).max(2_048)).min(1).max(32),
+        action_count: z.number().int().min(1).max(128),
+        secret_references: z.array(z.string().min(1).max(64)).max(64),
+    }),
+    duration_ms: z.number().int().min(0),
+    steps: z.array(browserScenarioStepSchema).min(1).max(129),
+    events: z.strictObject({
+        retained: z.number().int().min(0),
+        dropped: z.number().int().min(0),
+        items: z.array(browserScenarioEventSchema).max(100_000),
+    }),
+    completeness: browserScenarioCompletenessSchema,
+    limitations: z.array(z.string().min(1).max(2_048)).max(64),
+})
+    .superRefine((capture, context) => {
+    if (capture.events.retained !== capture.events.items.length)
+        context.addIssue({
+            code: "custom",
+            path: ["events", "retained"],
+            message: "Retained event count must equal items length",
+        });
+    if (capture.steps.length !== capture.scenario.action_count + 1)
+        context.addIssue({
+            code: "custom",
+            path: ["steps"],
+            message: "Capture must include initial state and one entry per action",
+        });
+    const expectedIndices = capture.steps.map((_, index) => index);
+    if (capture.steps.some(({ step_index: index }, offset) => index !== expectedIndices[offset]))
+        context.addIssue({
+            code: "custom",
+            path: ["steps"],
+            message: "Step indices must be contiguous from zero",
+        });
+    if (capture.events.items.some(({ step_index: index }) => index >= capture.steps.length))
+        context.addIssue({
+            code: "custom",
+            path: ["events", "items"],
+            message: "Event references an unknown step index",
+        });
+});

package/dist/domain/browserScenarioCaptureValues.js

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { sanitizedBrowserUrlSchema } from "./browserObservation.js";
+import { webScreenshotArtifactSchema } from "./webScreenshot.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().max(1_048_576);
+const textArtifactSchema = z
+    .strictObject({
+    sha256: digestSchema,
+    bytes: z
+        .number()
+        .int()
+        .min(0)
+        .max(16 * 1_024 * 1_024),
+    text: boundedTextSchema,
+})
+    .superRefine((artifact, context) => {
+    const bytes = Buffer.from(artifact.text);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (bytes.byteLength !== artifact.bytes || sha256 !== artifact.sha256)
+        context.addIssue({
+            code: "custom",
+            message: "Text artifact digest or size mismatch",
+        });
+});
+export const captureStateSchema = (value) => z.discriminatedUnion("state", [
+    z.strictObject({ state: z.literal("captured"), value }),
+    z.strictObject({
+        state: z.literal("not_requested"),
+    }),
+    z.strictObject({
+        state: z.literal("missing"),
+        reason: z.string().min(1).max(1_024),
+    }),
+    z.strictObject({
+        state: z.literal("truncated"),
+        observed: z.number().int().min(0),
+        retained: z.number().int().min(0),
+        reason: z.string().min(1).max(1_024),
+    }),
+]);
+const historySchema = z.strictObject({
+    length: z.number().int().min(0),
+    current_url: sanitizedBrowserUrlSchema,
+    navigation_entries: z
+        .array(z.strictObject({
+        type: z.enum([
+            "navigate",
+            "reload",
+            "back_forward",
+            "prerender",
+            "unknown",
+        ]),
+        name: sanitizedBrowserUrlSchema,
+    }))
+        .max(256),
+});
+const storageValueSchema = z.strictObject({
+    name: z.string().max(1_024),
+    value_state: z.enum(["hashed", "redacted-secret"]),
+    value_sha256: digestSchema.nullable(),
+});
+const storageSnapshotSchema = z.strictObject({
+    cookies: z
+        .array(z.strictObject({
+        name: z.string().max(1_024),
+        domain: z.string().max(2_048),
+        path: z.string().max(4_096),
+        secure: z.boolean(),
+        http_only: z.boolean(),
+        same_site: z.enum(["Strict", "Lax", "None"]),
+        value_state: z.enum(["hashed", "redacted-secret"]),
+        value_sha256: digestSchema.nullable(),
+    }))
+        .max(512),
+    local_storage: z.array(storageValueSchema).max(512),
+    session_storage: z.array(storageValueSchema).max(512),
+});
+export const browserStepArtifactsSchema = z.strictObject({
+    screenshot: captureStateSchema(webScreenshotArtifactSchema),
+    dom: captureStateSchema(textArtifactSchema),
+    accessibility: captureStateSchema(textArtifactSchema),
+    url: captureStateSchema(sanitizedBrowserUrlSchema),
+    history: captureStateSchema(historySchema),
+    storage: captureStateSchema(storageSnapshotSchema),
+});
+const eventBase = {
+    sequence: z.number().int().min(1),
+    step_index: z.number().int().min(0),
+};
+const eventUrl = sanitizedBrowserUrlSchema.nullable();
+export const browserScenarioEventSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("console"),
+        level: z.string().min(1).max(64),
+        text: z.string().max(65_536),
+        url: eventUrl,
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("page-error"),
+        message: z.string().max(65_536),
+        stack: z.string().max(262_144).nullable(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum(["request", "response", "request-failed"]),
+        method: z.string().min(1).max(32),
+        url: sanitizedBrowserUrlSchema,
+        resource_type: z.string().min(1).max(64),
+        status: z.number().int().min(100).max(599).nullable(),
+        header_names: z.array(z.string().max(256)).max(256),
+        failure: z.string().max(1_024).nullable(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum(["websocket-opened", "websocket-closed"]),
+        url: sanitizedBrowserUrlSchema,
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum(["websocket-frame-sent", "websocket-frame-received"]),
+        url: sanitizedBrowserUrlSchema,
+        payload_type: z.enum(["text", "binary"]),
+        payload_bytes: z.number().int().min(0),
+        payload_text: z.string().max(65_536).nullable(),
+        truncated: z.boolean(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.enum([
+            "frame-attached",
+            "frame-detached",
+            "frame-navigated",
+            "worker-created",
+            "worker-closed",
+            "popup-opened",
+            "popup-closed",
+        ]),
+        url: eventUrl,
+        name: z.string().max(1_024).nullable(),
+    }),
+    z.strictObject({
+        ...eventBase,
+        kind: z.literal("download-cancelled"),
+        suggested_filename: z.string().max(1_024),
+        url: sanitizedBrowserUrlSchema,
+    }),
+]);
+const completenessSectionSchema = z.enum([
+    "action",
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+    "frames",
+    "workers",
+    "popups",
+    "websockets",
+]);
+export const browserScenarioCompletenessSchema = z
+    .strictObject({
+    status: z.enum(["complete", "incomplete", "truncated"]),
+    equality_eligible: z.boolean(),
+    missing_sections: z.array(completenessSectionSchema),
+    truncated_sections: z.array(completenessSectionSchema),
+})
+    .superRefine((value, context) => {
+    const expectedStatus = value.truncated_sections.length > 0
+        ? "truncated"
+        : value.missing_sections.length > 0
+            ? "incomplete"
+            : "complete";
+    if (value.status !== expectedStatus)
+        context.addIssue({
+            code: "custom",
+            path: ["status"],
+            message: "Completeness status does not match section accounting",
+        });
+    if (value.equality_eligible !== (expectedStatus === "complete"))
+        context.addIssue({
+            code: "custom",
+            path: ["equality_eligible"],
+            message: "Missing or truncated evidence is never equality-eligible",
+        });
+});
+export const browserScenarioStepSchema = z.strictObject({
+    step_index: z.number().int().min(0),
+    step_id: z.string().min(1).max(64),
+    action: z.string().min(1).max(64),
+    status: z.enum(["completed", "failed", "cancelled"]),
+    elapsed_ms: z.number().int().min(0),
+    before_url: sanitizedBrowserUrlSchema,
+    after_url: sanitizedBrowserUrlSchema,
+    error: z.string().max(4_096).nullable(),
+    event_sequence_start: z.number().int().min(1),
+    event_sequence_end: z.number().int().min(0),
+    artifacts: browserStepArtifactsSchema,
+    completeness: browserScenarioCompletenessSchema,
+});

package/dist/domain/browserScenarioDiff.js

@@ -0,0 +1,324 @@
+import {} from "./browserScenarioCapture.js";
+import { browserScenarioDiffSchema, } from "./browserScenarioDiffValues.js";
+import { commitBrowserScenarioNormalization, digestCanonicalJson, digestNormalizedScenarioValue, } from "./browserScenarioNormalization.js";
+export { browserScenarioDiffSchema, compareBrowserScenariosInputSchema, } from "./browserScenarioDiffValues.js";
+/** Compare scenario steps by stable step ID and apply only committed literal rules. */
+export const compareBrowserScenarios = (input) => {
+    const normalization = commitBrowserScenarioNormalization(input.normalization);
+    const alignment = alignScenarioSteps(input.before_scenario, input.after_scenario);
+    const compared = compareAlignedSteps({
+        beforeCapture: input.before_scenario,
+        afterCapture: input.after_scenario,
+        alignment,
+        rules: normalization.rules,
+        maxChanges: input.max_changes,
+    });
+    const failures = [...alignment.failures, ...compared.failures];
+    const alignmentStatus = failures.length === 0
+        ? "aligned"
+        : compared.steps.length === 0
+            ? "failed"
+            : "partial";
+    const stepStatuses = compared.steps.map(({ status }) => status);
+    const equalityEligible = input.before_scenario.completeness.equality_eligible &&
+        input.after_scenario.completeness.equality_eligible &&
+        alignmentStatus === "aligned";
+    const overallStatus = stepStatuses.includes("changed")
+        ? "changed"
+        : stepStatuses.includes("unknown") || !equalityEligible
+            ? "unknown"
+            : "unchanged";
+    return browserScenarioDiffSchema.parse({
+        schema_version: 1,
+        comparison_kind: "browser_scenario",
+        overall_status: overallStatus,
+        normalization,
+        alignment: {
+            status: alignmentStatus,
+            aligned_steps: compared.steps.length,
+            before_only: alignment.beforeOnly,
+            after_only: alignment.afterOnly,
+            failures,
+        },
+        steps: compared.steps,
+        artifact_diffs: {
+            total: compared.totalArtifactDiffs,
+            retained: compared.totalArtifactDiffs -
+                Math.max(0, compared.totalArtifactDiffs - input.max_changes),
+            omitted: Math.max(0, compared.totalArtifactDiffs - input.max_changes),
+        },
+        limitations: [
+            "Steps align only by exact, unique step_id; missing, duplicate, or action-mismatched steps are reported and prevent an unchanged claim.",
+            "Only declared literal normalization rules are applied, in canonical rule_id order, to already-redacted durable capture fields.",
+            "Elapsed time and event sequence/index values are excluded as volatile; screenshot bytes are compared by content digest.",
+            "A changed status proves an observed normalized difference. Missing or truncated evidence, incompatible capture context, or alignment failure prevents an unchanged claim.",
+            ...(compared.totalArtifactDiffs > input.max_changes
+                ? [
+                    `${String(compared.totalArtifactDiffs - input.max_changes)} artifact difference record(s) were omitted by max_changes.`,
+                ]
+                : []),
+        ],
+    });
+};
+const alignScenarioSteps = (beforeCapture, afterCapture) => {
+    const beforeDuplicates = duplicateStepIds(beforeCapture.steps);
+    const afterDuplicates = duplicateStepIds(afterCapture.steps);
+    const before = uniqueSteps(beforeCapture.steps, beforeDuplicates);
+    const after = uniqueSteps(afterCapture.steps, afterDuplicates);
+    const beforeOnly = [...before.keys()]
+        .filter((stepId) => !after.has(stepId))
+        .sort();
+    const afterOnly = [...after.keys()]
+        .filter((stepId) => !before.has(stepId))
+        .sort();
+    const failures = [
+        ...duplicateFailures("before", beforeDuplicates),
+        ...duplicateFailures("after", afterDuplicates),
+        ...missingFailures("before", afterOnly),
+        ...missingFailures("after", beforeOnly),
+    ];
+    if (!captureContextsMatch(beforeCapture, afterCapture))
+        failures.push({
+            code: "capture_context_mismatch",
+            step_id: null,
+            reason: "Browser product/version or scenario origin scope differs between captures.",
+        });
+    return {
+        before,
+        after,
+        beforeOnly,
+        afterOnly,
+        failures,
+        orderedStepIds: beforeCapture.steps
+            .map(({ step_id }) => step_id)
+            .filter((stepId, index, values) => values.indexOf(stepId) === index &&
+            before.has(stepId) &&
+            after.has(stepId)),
+    };
+};
+const compareAlignedSteps = (input) => {
+    const remaining = { value: input.maxChanges };
+    let totalArtifactDiffs = 0;
+    const steps = [];
+    const failures = [];
+    for (const stepId of input.alignment.orderedStepIds) {
+        const beforeStep = input.alignment.before.get(stepId);
+        const afterStep = input.alignment.after.get(stepId);
+        if (beforeStep === undefined || afterStep === undefined)
+            continue;
+        if (beforeStep.action !== afterStep.action)
+            failures.push({
+                code: "action_mismatch",
+                step_id: stepId,
+                reason: `Aligned step action changed from ${beforeStep.action} to ${afterStep.action}.`,
+            });
+        const artifacts = compareStepArtifacts({
+            beforeCapture: input.beforeCapture,
+            beforeStep,
+            afterCapture: input.afterCapture,
+            afterStep,
+            rules: input.rules,
+        });
+        const reportable = artifacts.flatMap(({ diff }) => diff === null ? [] : [diff]);
+        totalArtifactDiffs += reportable.length;
+        const retained = reportable.slice(0, remaining.value);
+        remaining.value -= retained.length;
+        const statuses = artifacts.map(({ status }) => status);
+        steps.push({
+            step_id: stepId,
+            before_step_index: beforeStep.step_index,
+            after_step_index: afterStep.step_index,
+            before_action: beforeStep.action,
+            after_action: afterStep.action,
+            status: statuses.includes("changed")
+                ? "changed"
+                : statuses.includes("unknown")
+                    ? "unknown"
+                    : "unchanged",
+            artifact_diffs: retained,
+            omitted_artifact_diffs: reportable.length - retained.length,
+        });
+    }
+    return { steps, failures, totalArtifactDiffs };
+};
+const duplicateStepIds = (steps) => {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const { step_id: stepId } of steps) {
+        if (seen.has(stepId))
+            duplicates.add(stepId);
+        seen.add(stepId);
+    }
+    return duplicates;
+};
+const uniqueSteps = (steps, duplicates) => new Map(steps.flatMap((step) => duplicates.has(step.step_id) ? [] : [[step.step_id, step]]));
+const duplicateFailures = (side, duplicates) => [...duplicates].sort().map((stepId) => ({
+    code: side === "before"
+        ? "duplicate_before_step_id"
+        : "duplicate_after_step_id",
+    step_id: stepId,
+    reason: `${side} capture contains duplicate step_id ${stepId}.`,
+}));
+const missingFailures = (side, stepIds) => stepIds.map((stepId) => ({
+    code: side === "before" ? "missing_before_step" : "missing_after_step",
+    step_id: stepId,
+    reason: `Step ${stepId} is missing from the ${side} capture.`,
+}));
+const captureContextsMatch = (before, after) => before.browser.product === after.browser.product &&
+    before.browser.version === after.browser.version &&
+    before.scenario.start_origin === after.scenario.start_origin &&
+    digestCanonicalJson([...before.scenario.allowed_origins].sort()) ===
+        digestCanonicalJson([...after.scenario.allowed_origins].sort());
+const compareStepArtifacts = (input) => {
+    const common = {
+        beforeStep: input.beforeStep,
+        afterStep: input.afterStep,
+        rules: input.rules,
+    };
+    return [
+        compareCapturedValues({
+            ...common,
+            artifact: "action_state",
+            before: captured(actionState(input.beforeStep)),
+            after: captured(actionState(input.afterStep)),
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "screenshot",
+            before: input.beforeStep.artifacts.screenshot,
+            after: input.afterStep.artifacts.screenshot,
+            project: screenshotProjection,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "dom",
+            before: input.beforeStep.artifacts.dom,
+            after: input.afterStep.artifacts.dom,
+            project: ({ text }) => text,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "accessibility",
+            before: input.beforeStep.artifacts.accessibility,
+            after: input.afterStep.artifacts.accessibility,
+            project: ({ text }) => text,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "url",
+            before: input.beforeStep.artifacts.url,
+            after: input.afterStep.artifacts.url,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "history",
+            before: input.beforeStep.artifacts.history,
+            after: input.afterStep.artifacts.history,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "storage",
+            before: input.beforeStep.artifacts.storage,
+            after: input.afterStep.artifacts.storage,
+        }),
+        compareCapturedValues({
+            ...common,
+            artifact: "events",
+            before: captured(eventsFor(input.beforeCapture, input.beforeStep.step_index)),
+            after: captured(eventsFor(input.afterCapture, input.afterStep.step_index)),
+            beforeState: eventEvidenceState(input.beforeCapture, input.beforeStep),
+            afterState: eventEvidenceState(input.afterCapture, input.afterStep),
+        }),
+    ];
+};
+const compareCapturedValues = (input) => {
+    const { artifact, before, after, beforeStep, afterStep, rules, project = (value) => value, } = input;
+    const beforeState = input.beforeState ?? artifactEvidenceState(artifact, before, beforeStep);
+    const afterState = input.afterState ?? artifactEvidenceState(artifact, after, afterStep);
+    if (beforeState === "not_requested" && afterState === "not_requested")
+        return { artifact, status: "not_compared", diff: null };
+    const beforeSha256 = beforeState === "captured" && before.state === "captured"
+        ? digestNormalizedScenarioValue(project(before.value), artifact, rules)
+        : null;
+    const afterSha256 = afterState === "captured" && after.state === "captured"
+        ? digestNormalizedScenarioValue(project(after.value), artifact, rules)
+        : null;
+    if (beforeState !== "captured" ||
+        afterState !== "captured" ||
+        before.state !== "captured" ||
+        after.state !== "captured")
+        return {
+            artifact,
+            status: "unknown",
+            diff: {
+                artifact,
+                status: "unknown",
+                before_state: beforeState,
+                after_state: afterState,
+                before_sha256: beforeSha256,
+                after_sha256: afterSha256,
+                reason: `Artifact coverage is not comparable (${beforeState} before, ${afterState} after).`,
+            },
+        };
+    if (beforeSha256 === null || afterSha256 === null)
+        throw new TypeError("Captured artifact digest refinement failed");
+    if (beforeSha256 === afterSha256)
+        return { artifact, status: "unchanged", diff: null };
+    return {
+        artifact,
+        status: "changed",
+        diff: {
+            artifact,
+            status: "changed",
+            before_state: beforeState,
+            after_state: afterState,
+            before_sha256: beforeSha256,
+            after_sha256: afterSha256,
+            reason: null,
+        },
+    };
+};
+const artifactEvidenceState = (artifact, state, step) => {
+    if (state.state !== "captured")
+        return state.state;
+    const section = artifact === "action_state" ? "action" : artifact;
+    if (step.completeness.truncated_sections.includes(section))
+        return "truncated";
+    if (step.completeness.missing_sections.includes(section))
+        return "missing";
+    return "captured";
+};
+const eventEvidenceState = (capture, step) => {
+    const sections = [
+        "events",
+        "frames",
+        "workers",
+        "popups",
+        "websockets",
+    ];
+    if (capture.events.dropped > 0 ||
+        sections.some((section) => capture.completeness.truncated_sections.includes(section) ||
+            step.completeness.truncated_sections.includes(section)))
+        return "truncated";
+    if (sections.some((section) => capture.completeness.missing_sections.includes(section) ||
+        step.completeness.missing_sections.includes(section)))
+        return "missing";
+    return "captured";
+};
+const actionState = (step) => ({
+    action: step.action,
+    status: step.status,
+    before_url: step.before_url,
+    after_url: step.after_url,
+    error: step.error,
+});
+const eventsFor = (capture, stepIndex) => capture.events.items.flatMap(({ sequence: _sequence, step_index: eventStepIndex, ...event }) => eventStepIndex === stepIndex ? [event] : []);
+const captured = (value) => ({
+    state: "captured",
+    value,
+});
+const screenshotProjection = (screenshot) => ({
+    sha256: screenshot.sha256,
+    bytes: screenshot.bytes,
+    media_type: screenshot.media_type,
+});