rea-agents 2.4.0 → 2.5.0

package/dist/domain/browserObservation.js

@@ -201,9 +201,16 @@ export const inspectWebPageInputSchema = z
     websocket_shape_approved: z.boolean().default(false),
     include_script_sources: z.boolean().default(false),
     include_storage_keys: z.boolean().default(false),
+    include_storage_fingerprints: z.boolean().default(false),
     limits: browserInspectionLimitsSchema.default(DEFAULT_BROWSER_INSPECTION_LIMITS),
 })
     .superRefine((input, context) => {
+    if (input.include_storage_fingerprints && !input.include_storage_keys)
+        context.addIssue({
+            code: "custom",
+            path: ["include_storage_fingerprints"],
+            message: "Storage fingerprints require storage key capture",
+        });
     if (input.limits.max_script_source_bytes >
         input.limits.max_total_script_source_bytes)
         context.addIssue({
@@ -261,7 +268,7 @@ export const inspectWebPageInputSchema = z
             message: "Per-field accessibility text limit cannot exceed the total text limit",
         });
 });
-const sanitizedBrowserUrlSchema = z.object({
+export const sanitizedBrowserUrlSchema = z.object({
     url: z.string().max(MAX_SANITIZED_BROWSER_URL_CHARS),
     origin: z.string().max(2_048).nullable(),
     query_parameter_names: z

package/dist/domain/browserObservationErrors.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/browserObservationSchemas.js

@@ -57,6 +57,12 @@ const browserAxNodeSchema = z.object({
     name: z.string().nullable(),
     description: z.string().nullable(),
     ignored: z.boolean(),
+    states: z
+        .array(z.object({
+        name: z.string(),
+        value: z.union([z.boolean(), z.number(), z.string()]),
+    }))
+        .default([]),
 });
 const browserScriptSourceSchema = z.discriminatedUnion("included", [
     z.object({ included: z.literal(false), reason: z.string() }),
@@ -280,6 +286,26 @@ export const webPageInspectionSchema = z.object({
         session_storage_keys: z.array(z.string()),
         indexed_db_names: z.array(z.string()),
         cache_names: z.array(z.string()),
+        content_fingerprints: z
+            .array(z.object({
+            scope: z.enum([
+                "cookie",
+                "local_storage",
+                "session_storage",
+                "indexed_db_schema",
+                "indexed_db_record",
+                "cache_entry",
+            ]),
+            identity_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+            value_sha256: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/u)
+                .nullable(),
+            complete: z.boolean(),
+        }))
+            .default([]),
+        fingerprint_algorithm: z.literal("sha256").default("sha256"),
+        fingerprints_complete: z.boolean().default(false),
         values_redacted: z.literal(true),
     }),
     limitations: z.array(z.string()),

package/dist/domain/browserScenario.js

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { BROWSER_SCENARIO_LIMITS, browserScenarioActionSchema, browserScenarioAllowedOriginsSchema, browserScenarioBrowserSchema, browserScenarioCaptureLimitsSchema, browserScenarioCaptureSchema, browserScenarioEnvironmentSchema, browserScenarioRedactionSchema, browserScenarioRequestReplaySchema, browserScenarioSecretSchema, browserScenarioStorageSchema, browserScenarioUrlSchema, } from "./browserScenarioValues.js";
+export { BROWSER_SCENARIO_LIMITS, browserScenarioActionSchema, browserScenarioUrlSchema, browserScenarioValueSchema, } from "./browserScenarioValues.js";
+const scenarioShapeSchema = z.strictObject({
+    schema_version: z.literal(1),
+    browser: browserScenarioBrowserSchema,
+    start_url: browserScenarioUrlSchema,
+    allowed_origins: browserScenarioAllowedOriginsSchema,
+    environment: browserScenarioEnvironmentSchema,
+    actions: z
+        .array(browserScenarioActionSchema)
+        .min(1)
+        .max(BROWSER_SCENARIO_LIMITS.actions),
+    storage: browserScenarioStorageSchema,
+    request_replay: browserScenarioRequestReplaySchema,
+    secrets: z
+        .array(browserScenarioSecretSchema)
+        .max(BROWSER_SCENARIO_LIMITS.secrets)
+        .default([]),
+    redaction: browserScenarioRedactionSchema,
+    capture: browserScenarioCaptureSchema,
+    limits: browserScenarioCaptureLimitsSchema,
+    approved: z.literal(true),
+});
+const addIssue = (context, path, message) => context.addIssue({ code: "custom", path, message });
+const assertUnique = (values, path, label, context) => {
+    if (new Set(values).size !== values.length)
+        addIssue(context, path, `${label} must be unique`);
+};
+const originFor = (destination) => new URL(destination.url).origin;
+const assertAllowedDestination = (destination, allowedOrigins, path, context) => {
+    if (!allowedOrigins.has(originFor(destination)))
+        addIssue(context, path, `URL origin ${originFor(destination)} is not declared in allowed_origins`);
+};
+const secretReferencesInValue = (value) => (value?.source === "secret" ? [value.secret_id] : []);
+const destinationSecretReferences = (destination) => destination.query.flatMap(({ value }) => secretReferencesInValue(value));
+const actionSecretReferences = (action) => {
+    if (action.action === "fill" || action.action === "select_option")
+        return secretReferencesInValue(action.value);
+    if (action.action === "goto")
+        return destinationSecretReferences(action.destination);
+    return [];
+};
+const validateStorage = (scenario, allowedOrigins, context) => {
+    const references = [];
+    scenario.storage.cookies.forEach((cookie, index) => {
+        assertAllowedDestination(cookie.destination, allowedOrigins, ["storage", "cookies", index, "destination"], context);
+        references.push(...secretReferencesInValue(cookie.value));
+        references.push(...destinationSecretReferences(cookie.destination));
+    });
+    for (const collection of ["local_storage", "session_storage"])
+        scenario.storage[collection].forEach((storage, index) => {
+            if (!allowedOrigins.has(storage.origin))
+                addIssue(context, ["storage", collection, index, "origin"], `Storage origin ${storage.origin} is not declared in allowed_origins`);
+            for (const entry of storage.entries)
+                references.push(...secretReferencesInValue(entry.value));
+        });
+    return references;
+};
+const SENSITIVE_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+]);
+const FORBIDDEN_REPLAY_HEADERS = new Set([
+    "content-length",
+    "location",
+    "transfer-encoding",
+]);
+const validateRequestReplay = (scenario, allowedOrigins, context) => {
+    if (scenario.request_replay.mode === "disabled")
+        return [];
+    assertUnique(scenario.request_replay.routes.map(({ route_id: id }) => id), ["request_replay", "routes"], "Replay route IDs", context);
+    assertUnique(scenario.request_replay.routes.map(({ method, request }) => `${method} ${request.url}?${request.query
+        .map(({ name, value }) => value.source === "secret"
+        ? `${name}=\${secret:${value.secret_id}}`
+        : `${name}=${value.value}`)
+        .join("&")}`), ["request_replay", "routes"], "Replay request matchers", context);
+    const references = [];
+    scenario.request_replay.routes.forEach((route, routeIndex) => {
+        assertAllowedDestination(route.request, allowedOrigins, ["request_replay", "routes", routeIndex, "request"], context);
+        references.push(...destinationSecretReferences(route.request));
+        if (route.response.kind === "redirect") {
+            assertAllowedDestination(route.response.destination, allowedOrigins, ["request_replay", "routes", routeIndex, "response", "destination"], context);
+            references.push(...destinationSecretReferences(route.response.destination));
+            return;
+        }
+        assertUnique(route.response.headers.map(({ name }) => name.toLowerCase()), ["request_replay", "routes", routeIndex, "response", "headers"], "Replay response header names", context);
+        route.response.headers.forEach((header, headerIndex) => {
+            if (FORBIDDEN_REPLAY_HEADERS.has(header.name))
+                addIssue(context, [
+                    "request_replay",
+                    "routes",
+                    routeIndex,
+                    "response",
+                    "headers",
+                    headerIndex,
+                ], `Replay header ${header.name} must be modeled by the provider`);
+            if (SENSITIVE_HEADERS.has(header.name) &&
+                header.value.source === "literal")
+                addIssue(context, [
+                    "request_replay",
+                    "routes",
+                    routeIndex,
+                    "response",
+                    "headers",
+                    headerIndex,
+                    "value",
+                ], `Credential header ${header.name} requires a declared secret`);
+            references.push(...secretReferencesInValue(header.value));
+        });
+        references.push(...secretReferencesInValue(route.response.body));
+    });
+    return references;
+};
+const validateSecretReferences = (scenario, references, context) => {
+    const declared = new Set(scenario.secrets.map(({ secret_id: id }) => id));
+    for (const reference of references)
+        if (!declared.has(reference))
+            addIssue(context, ["secrets"], `Secret reference ${reference} is not declared`);
+    const used = new Set(references);
+    scenario.secrets.forEach(({ secret_id: id }, index) => {
+        if (!used.has(id))
+            addIssue(context, ["secrets", index, "secret_id"], `Secret declaration ${id} is unused`);
+    });
+};
+const validateRedactionCoverage = (scenario, context) => {
+    const redactedQueries = new Set(scenario.redaction.query_parameter_names);
+    const destinations = [scenario.start_url];
+    for (const action of scenario.actions)
+        if (action.action === "goto")
+            destinations.push(action.destination);
+    for (const cookie of scenario.storage.cookies)
+        destinations.push(cookie.destination);
+    if (scenario.request_replay.mode === "exact")
+        for (const route of scenario.request_replay.routes) {
+            destinations.push(route.request);
+            if (route.response.kind === "redirect")
+                destinations.push(route.response.destination);
+        }
+    for (const destination of destinations)
+        for (const query of destination.query)
+            if (query.value.source === "secret" &&
+                !redactedQueries.has(query.name.toLowerCase()))
+                addIssue(context, ["redaction", "query_parameter_names"], `Secret query parameter ${query.name} must be declared for redaction`);
+};
+const validateBrowserScenario = (scenario, context) => {
+    const allowedOrigins = new Set(scenario.allowed_origins);
+    assertAllowedDestination(scenario.start_url, allowedOrigins, ["start_url"], context);
+    assertUnique(scenario.actions.map(({ step_id: id }) => id), ["actions"], "Action step IDs", context);
+    assertUnique(scenario.secrets.map(({ secret_id: id }) => id), ["secrets"], "Secret IDs", context);
+    assertUnique(scenario.secrets.map(({ environment_variable: name }) => name), ["secrets"], "Secret environment variables", context);
+    const references = scenario.actions.flatMap(actionSecretReferences);
+    for (const [index, action] of scenario.actions.entries())
+        if (action.action === "goto")
+            assertAllowedDestination(action.destination, allowedOrigins, ["actions", index, "destination"], context);
+    references.push(...destinationSecretReferences(scenario.start_url));
+    references.push(...validateStorage(scenario, allowedOrigins, context));
+    references.push(...validateRequestReplay(scenario, allowedOrigins, context));
+    validateSecretReferences(scenario, references, context);
+    validateRedactionCoverage(scenario, context);
+};
+/** Strict provider-neutral contract for one bounded browser capture scenario. */
+export const browserScenarioSchema = scenarioShapeSchema.superRefine(validateBrowserScenario);

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,
+});