rea-agents 2.4.0 → 3.0.0

package/dist/domain/browserScenarioDiffValues.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { browserScenarioCaptureSchema } from "./browserScenarioCapture.js";
+/** Scenario artifact families compared after step alignment. */
+export const browserScenarioArtifactKindSchema = z.enum([
+    "action_state",
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+]);
+const normalizableArtifactKindSchema = z.enum([
+    "action_state",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+    "events",
+]);
+const normalizationRuleSchema = z.strictObject({
+    rule_id: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        .describe("Stable rule identity; rules execute in rule_id order."),
+    artifacts: z
+        .array(normalizableArtifactKindSchema)
+        .min(1)
+        .max(7)
+        .describe("Artifact families whose durable string fields use this rule."),
+    match: z
+        .string()
+        .min(1)
+        .max(4_096)
+        .describe("Exact public literal to replace; regular expressions are not used."),
+    replacement: z
+        .string()
+        .max(4_096)
+        .describe("Recorded replacement text used in normalized comparison."),
+});
+const normalizationInputSchema = z
+    .strictObject({
+    rules: z.array(normalizationRuleSchema).max(128).default([]),
+})
+    .superRefine((normalization, context) => {
+    const ruleIds = new Set();
+    for (const [index, rule] of normalization.rules.entries()) {
+        if (ruleIds.has(rule.rule_id))
+            context.addIssue({
+                code: "custom",
+                path: ["rules", index, "rule_id"],
+                message: "Normalization rule IDs must be unique",
+            });
+        ruleIds.add(rule.rule_id);
+        if (new Set(rule.artifacts).size !== rule.artifacts.length)
+            context.addIssue({
+                code: "custom",
+                path: ["rules", index, "artifacts"],
+                message: "Normalization rule artifact kinds must be unique",
+            });
+    }
+});
+/** Input for step-aligned comparison of two browser scenario captures. */
+export const compareBrowserScenariosInputSchema = z.strictObject({
+    before_scenario: browserScenarioCaptureSchema.describe("Earlier complete capture_browser_scenario result."),
+    after_scenario: browserScenarioCaptureSchema.describe("Later complete capture_browser_scenario result."),
+    normalization: normalizationInputSchema
+        .default({ rules: [] })
+        .describe("Bounded exact-literal rules committed in the comparison result."),
+    max_changes: z
+        .number()
+        .int()
+        .min(1)
+        .max(20_000)
+        .default(2_000)
+        .describe("Maximum changed or unknown artifact records to retain."),
+});
+const evidenceStateSchema = z.enum([
+    "captured",
+    "not_requested",
+    "missing",
+    "truncated",
+]);
+const artifactDiffSchema = z.strictObject({
+    artifact: browserScenarioArtifactKindSchema,
+    status: z.enum(["changed", "unknown"]),
+    before_state: evidenceStateSchema,
+    after_state: evidenceStateSchema,
+    before_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    after_sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    reason: z.string().min(1).max(2_048).nullable(),
+});
+const alignmentFailureSchema = z.strictObject({
+    code: z.enum([
+        "duplicate_before_step_id",
+        "duplicate_after_step_id",
+        "missing_before_step",
+        "missing_after_step",
+        "action_mismatch",
+        "capture_context_mismatch",
+    ]),
+    step_id: z.string().min(1).max(64).nullable(),
+    reason: z.string().min(1).max(2_048),
+});
+const builtInNormalizationSchema = z.enum([
+    "ignore_step_elapsed_ms",
+    "ignore_event_sequence",
+    "ignore_event_step_index",
+    "compare_screenshot_content_digest",
+    "compare_normalized_text_content",
+]);
+/** Step alignment, recorded normalization, and bounded artifact differences. */
+export const browserScenarioDiffSchema = z.strictObject({
+    schema_version: z.literal(1),
+    comparison_kind: z.literal("browser_scenario"),
+    overall_status: z.enum(["changed", "unchanged", "unknown"]),
+    normalization: z.strictObject({
+        built_in_rules: z.array(builtInNormalizationSchema).length(5),
+        rules: z.array(normalizationRuleSchema).max(128),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+    alignment: z.strictObject({
+        status: z.enum(["aligned", "partial", "failed"]),
+        aligned_steps: z.number().int().min(0).max(129),
+        before_only: z.array(z.string().min(1).max(64)).max(129),
+        after_only: z.array(z.string().min(1).max(64)).max(129),
+        failures: z.array(alignmentFailureSchema).max(520),
+    }),
+    steps: z
+        .array(z.strictObject({
+        step_id: z.string().min(1).max(64),
+        before_step_index: z.number().int().min(0).max(128),
+        after_step_index: z.number().int().min(0).max(128),
+        before_action: z.string().min(1).max(64),
+        after_action: z.string().min(1).max(64),
+        status: z.enum(["changed", "unchanged", "unknown"]),
+        artifact_diffs: z.array(artifactDiffSchema).max(8),
+        omitted_artifact_diffs: z.number().int().min(0).max(8),
+    }))
+        .max(129),
+    artifact_diffs: z.strictObject({
+        total: z.number().int().min(0).max(1_032),
+        retained: z.number().int().min(0).max(1_032),
+        omitted: z.number().int().min(0).max(1_032),
+    }),
+    limitations: z.array(z.string().min(1).max(2_048)).max(64),
+});

package/dist/domain/browserScenarioNormalization.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+const BUILT_IN_RULES = [
+    "ignore_step_elapsed_ms",
+    "ignore_event_sequence",
+    "ignore_event_step_index",
+    "compare_screenshot_content_digest",
+    "compare_normalized_text_content",
+];
+/** Canonically order and commit a parsed browser scenario normalization policy. */
+export const commitBrowserScenarioNormalization = (input) => {
+    const rules = [...input.rules]
+        .map((rule) => ({
+        ...rule,
+        artifacts: [...rule.artifacts].sort(),
+    }))
+        .sort((left, right) => left.rule_id < right.rule_id ? -1 : left.rule_id > right.rule_id ? 1 : 0);
+    const commitment = { built_in_rules: [...BUILT_IN_RULES], rules };
+    return { ...commitment, sha256: digestCanonicalJson(commitment) };
+};
+/** Digest one artifact after applying committed exact-literal rules. */
+export const digestNormalizedScenarioValue = (value, artifact, rules) => digestCanonicalJson(normalize(value, artifact, rules));
+/** Compute a canonical SHA-256 commitment for JSON-compatible domain data. */
+export const digestCanonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Expected canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const normalize = (value, artifact, rules) => {
+    if (artifact === "screenshot")
+        return value;
+    if (typeof value === "string")
+        return rules
+            .filter(({ artifacts }) => artifacts.includes(artifact))
+            .reduce((normalized, rule) => normalized.split(rule.match).join(rule.replacement), value);
+    if (Array.isArray(value))
+        return value.map((item) => normalize(item, artifact, rules));
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        normalize(item, artifact, rules),
+    ]));
+};

package/dist/domain/browserScenarioValues.js

@@ -0,0 +1,372 @@
+import { z } from "zod";
+import { browserAllowedOriginsSchema, browserEndpointSchema, browserOriginSchema, } from "./browserObservation.js";
+export const BROWSER_SCENARIO_LIMITS = {
+    actions: 128,
+    secrets: 64,
+    storageEntries: 512,
+    replayRoutes: 256,
+    durationMs: 300_000,
+    actionTimeoutMs: 60_000,
+};
+export const scenarioIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/u);
+const absoluteExecutablePathSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .refine((value) => value.startsWith("/") ||
+    /^[A-Za-z]:[\\/]/u.test(value) ||
+    value.startsWith("\\\\"), "Expected an absolute browser executable path");
+const browserScenarioBaseUrlSchema = z
+    .string()
+    .min(1)
+    .max(65_536)
+    .transform((value, context) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "Invalid browser URL" });
+        return z.NEVER;
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.search !== "" ||
+        url.hash !== "") {
+        context.addIssue({
+            code: "custom",
+            message: "Browser URLs must be HTTP(S), omit credentials, and declare query values separately",
+        });
+        return z.NEVER;
+    }
+    return url.toString();
+});
+export const browserScenarioValueSchema = z.discriminatedUnion("source", [
+    z.strictObject({
+        source: z.literal("literal"),
+        value: z.string().max(65_536),
+        classification: z.literal("public"),
+    }),
+    z.strictObject({
+        source: z.literal("secret"),
+        secret_id: scenarioIdentifierSchema,
+    }),
+]);
+const queryEntrySchema = z.strictObject({
+    name: z.string().min(1).max(256),
+    value: browserScenarioValueSchema,
+});
+/** URL whose values remain explicit public literals or declared secret references. */
+export const browserScenarioUrlSchema = z.strictObject({
+    url: browserScenarioBaseUrlSchema,
+    query: z.array(queryEntrySchema).max(64).default([]),
+});
+export const browserScenarioBrowserSchema = z.discriminatedUnion("mode", [
+    z.strictObject({
+        mode: z.literal("launch"),
+        executable_path: absoluteExecutablePathSchema,
+        headless: z.literal(true),
+        user_data: z.literal("temporary-owned"),
+        cleanup: z.literal("close-and-delete-profile"),
+    }),
+    z.strictObject({
+        mode: z.literal("connect"),
+        cdp_endpoint: browserEndpointSchema,
+        target_id: z.string().trim().min(1).max(256),
+        ownership: z.literal("external"),
+        cleanup: z.literal("disconnect-only"),
+    }),
+]);
+export const browserScenarioEnvironmentSchema = z.strictObject({
+    viewport: z.strictObject({
+        width: z.number().int().min(320).max(7_680),
+        height: z.number().int().min(240).max(4_320),
+        device_scale_factor: z.number().min(0.5).max(4).default(1),
+    }),
+    locale: z
+        .string()
+        .min(2)
+        .max(64)
+        .regex(/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/u),
+    timezone: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)*$/u),
+    color_scheme: z.enum(["light", "dark", "no-preference"]),
+    reduced_motion: z.enum(["reduce", "no-preference"]),
+    service_workers: z.literal("block"),
+});
+const locatorSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("test_id"),
+        value: z.string().min(1).max(512),
+    }),
+    z.strictObject({
+        kind: z.literal("role"),
+        role: z.enum([
+            "button",
+            "checkbox",
+            "combobox",
+            "dialog",
+            "link",
+            "listbox",
+            "menuitem",
+            "option",
+            "radio",
+            "slider",
+            "spinbutton",
+            "switch",
+            "tab",
+            "textbox",
+        ]),
+        name: z.string().min(1).max(1_024),
+        exact: z.literal(true),
+    }),
+    z.strictObject({
+        kind: z.literal("css"),
+        selector: z.string().min(1).max(4_096),
+        approved: z.literal(true),
+    }),
+]);
+const stepBase = {
+    step_id: scenarioIdentifierSchema,
+    timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs)
+        .optional(),
+};
+export const browserScenarioActionSchema = z.discriminatedUnion("action", [
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("goto"),
+        destination: browserScenarioUrlSchema,
+        wait_until: z.enum(["commit", "domcontentloaded", "load"]),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("click"),
+        locator: locatorSchema,
+        button: z.enum(["left", "middle", "right"]).default("left"),
+        click_count: z.number().int().min(1).max(3).default(1),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("fill"),
+        locator: locatorSchema,
+        value: browserScenarioValueSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("press"),
+        locator: locatorSchema,
+        key: z.string().min(1).max(64),
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("select_option"),
+        locator: locatorSchema,
+        value: browserScenarioValueSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.enum(["check", "uncheck"]),
+        locator: locatorSchema,
+    }),
+    z.strictObject({
+        ...stepBase,
+        action: z.literal("wait_for"),
+        locator: locatorSchema,
+        state: z.enum(["attached", "detached", "visible", "hidden"]),
+    }),
+    z.strictObject({
+        step_id: scenarioIdentifierSchema,
+        action: z.literal("wait_for_timeout"),
+        duration_ms: z
+            .number()
+            .int()
+            .min(1)
+            .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    }),
+]);
+const storageEntrySchema = z.strictObject({
+    name: z.string().min(1).max(1_024),
+    value: browserScenarioValueSchema,
+});
+export const browserScenarioStorageSchema = z.strictObject({
+    cookies: z
+        .array(z.strictObject({
+        name: z.string().min(1).max(1_024),
+        value: browserScenarioValueSchema,
+        destination: browserScenarioUrlSchema,
+        http_only: z.boolean(),
+        secure: z.boolean(),
+        same_site: z.enum(["Strict", "Lax", "None"]),
+    }))
+        .max(128)
+        .default([]),
+    local_storage: z
+        .array(z.strictObject({
+        origin: browserOriginSchema,
+        entries: z.array(storageEntrySchema).max(128),
+    }))
+        .max(32)
+        .default([]),
+    session_storage: z
+        .array(z.strictObject({
+        origin: browserOriginSchema,
+        entries: z.array(storageEntrySchema).max(128),
+    }))
+        .max(32)
+        .default([]),
+});
+const headerNameSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u)
+    .transform((value) => value.toLowerCase());
+const replayHeaderSchema = z.strictObject({
+    name: headerNameSchema,
+    value: browserScenarioValueSchema,
+});
+const replayResponseSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.array(replayHeaderSchema).max(64).default([]),
+        body: browserScenarioValueSchema.optional(),
+    }),
+    z.strictObject({
+        kind: z.literal("redirect"),
+        status: z.union([
+            z.literal(301),
+            z.literal(302),
+            z.literal(303),
+            z.literal(307),
+            z.literal(308),
+        ]),
+        destination: browserScenarioUrlSchema,
+    }),
+]);
+const replayRouteSchema = z.strictObject({
+    route_id: scenarioIdentifierSchema,
+    method: z.enum(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]),
+    request: browserScenarioUrlSchema,
+    response: replayResponseSchema,
+});
+export const browserScenarioRequestReplaySchema = z.discriminatedUnion("mode", [
+    z.strictObject({ mode: z.literal("disabled") }),
+    z.strictObject({
+        mode: z.literal("exact"),
+        unmatched: z.enum(["abort", "passthrough-approved-origins"]),
+        routes: z
+            .array(replayRouteSchema)
+            .min(1)
+            .max(BROWSER_SCENARIO_LIMITS.replayRoutes),
+    }),
+]);
+export const browserScenarioSecretSchema = z.strictObject({
+    secret_id: scenarioIdentifierSchema,
+    environment_variable: z.string().regex(/^[A-Z_][A-Z0-9_]{0,127}$/u),
+    purpose: z.enum(["input", "storage", "request-replay"]),
+    redaction: z.literal("replace-with-secret-reference"),
+});
+const REQUIRED_REDACTED_HEADERS = [
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+];
+const normalizedNames = (maximum) => z
+    .array(z
+    .string()
+    .trim()
+    .min(1)
+    .max(256)
+    .transform((value) => value.toLowerCase()))
+    .max(maximum)
+    .transform((values) => [...new Set(values)].sort());
+export const browserScenarioRedactionSchema = z
+    .strictObject({
+    secret_values: z.literal("replace-with-secret-reference"),
+    query_parameter_names: normalizedNames(128).default([]),
+    header_names: normalizedNames(128).default([...REQUIRED_REDACTED_HEADERS]),
+})
+    .superRefine(({ header_names: names }, context) => {
+    for (const required of REQUIRED_REDACTED_HEADERS)
+        if (!names.includes(required))
+            context.addIssue({
+                code: "custom",
+                path: ["header_names"],
+                message: `Required credential header ${required} must be redacted`,
+            });
+});
+const snapshotKindSchema = z.enum([
+    "screenshot",
+    "dom",
+    "accessibility",
+    "url",
+    "history",
+    "storage",
+]);
+export const browserScenarioCaptureSchema = z.strictObject({
+    after_each_step: z.array(snapshotKindSchema).max(6),
+    at_end: z.array(snapshotKindSchema).max(6),
+    events: z.array(z.enum([
+        "console",
+        "page-errors",
+        "network",
+        "websockets",
+        "frames",
+        "workers",
+        "popups",
+        "downloads",
+    ])),
+});
+export const browserScenarioCaptureLimitsSchema = z.strictObject({
+    max_duration_ms: z
+        .number()
+        .int()
+        .min(100)
+        .max(BROWSER_SCENARIO_LIMITS.durationMs),
+    action_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    navigation_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actionTimeoutMs),
+    max_events: z.number().int().min(1).max(100_000),
+    max_frames: z.number().int().min(1).max(1_000),
+    max_workers: z.number().int().min(0).max(1_000),
+    max_popups: z.number().int().min(0).max(100),
+    max_websockets: z.number().int().min(0).max(10_000),
+    max_dom_nodes: z.number().int().min(1).max(100_000),
+    max_accessibility_nodes: z.number().int().min(1).max(100_000),
+    max_screenshots: z.number().int().min(0).max(256),
+    max_screenshot_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(8 * 1_024 * 1_024),
+    max_storage_entries: z
+        .number()
+        .int()
+        .min(0)
+        .max(BROWSER_SCENARIO_LIMITS.storageEntries),
+    max_total_metadata_bytes: z
+        .number()
+        .int()
+        .min(1_024)
+        .max(64 * 1_024 * 1_024),
+});
+export const browserScenarioAllowedOriginsSchema = browserAllowedOriginsSchema;