rea-agents 2.1.0 → 2.3.0

package/dist/domain/replayMachine.js

@@ -0,0 +1,332 @@
+import { MultiDirectedGraph } from "graphology";
+import { singleSource } from "graphology-shortest-path";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+const replayIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u);
+const replayPathSchema = z
+    .array(z.union([z.string().max(256), z.number().int().nonnegative()]))
+    .max(32);
+const sensitiveHeaderNames = new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+    "set-cookie",
+]);
+const headerNameSchema = z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u);
+const headerValueSchema = z
+    .string()
+    .max(8_192)
+    .regex(/^[\t\x20-\x7e\x80-\xff]*$/u);
+const replayHeaderMatchersSchema = z
+    .record(headerNameSchema, headerValueSchema)
+    .superRefine((headers, context) => {
+    const names = Object.keys(headers).map((name) => name.toLowerCase());
+    if (new Set(names).size !== names.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay header matchers must be unique ignoring case",
+            input: headers,
+        });
+    if (names.some((name) => sensitiveHeaderNames.has(name)))
+        context.addIssue({
+            code: "custom",
+            message: "replay header matchers cannot persist authorization or cookie values; capture and guard through a secret alias instead",
+            input: headers,
+        });
+})
+    .transform((headers) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+    name.toLowerCase(),
+    value,
+])));
+const replayValueSourceSchema = z.discriminatedUnion("source", [
+    z.strictObject({
+        source: z.literal("request_header"),
+        name: z
+            .string()
+            .min(1)
+            .transform((name) => name.toLowerCase()),
+    }),
+    z.strictObject({ source: z.literal("request_json"), path: replayPathSchema }),
+    z.strictObject({
+        source: z.literal("websocket_json"),
+        path: replayPathSchema,
+    }),
+    z.strictObject({ source: z.literal("action_json"), path: replayPathSchema }),
+]);
+const replayTriggerSchema = z.discriminatedUnion("protocol", [
+    z.strictObject({
+        protocol: z.literal("http"),
+        method: z
+            .string()
+            .min(1)
+            .max(16)
+            .transform((method) => method.toUpperCase()),
+        path: z.string().startsWith("/"),
+        headers: replayHeaderMatchersSchema.default({}),
+        body: z.string().max(1_000_000).nullable().default(null),
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_connect"),
+        path: z.string().startsWith("/"),
+        headers: replayHeaderMatchersSchema.default({}),
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_message"),
+        path: z.string().startsWith("/"),
+        body: z.string().max(1_000_000).nullable().default(null),
+    }),
+]);
+const replayActionSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("http_response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.record(headerNameSchema, headerValueSchema).default({}),
+        body: z.string().max(1_000_000),
+    }),
+    z.strictObject({
+        type: z.literal("websocket_send"),
+        data: z.string().max(1_000_000),
+    }),
+    z.strictObject({ type: z.literal("disconnect") }),
+    z.strictObject({
+        type: z.literal("delay"),
+        duration_ms: z.number().int().nonnegative().max(30_000),
+    }),
+]);
+const replayTransitionSchema = z.strictObject({
+    id: replayIdentifierSchema,
+    from: replayIdentifierSchema,
+    to: replayIdentifierSchema,
+    priority: z.number().int().min(0).max(1_000).default(100),
+    trigger: replayTriggerSchema,
+    guards: z
+        .array(z.strictObject({
+        variable: replayIdentifierSchema,
+        value: replayValueSourceSchema,
+    }))
+        .max(32)
+        .default([]),
+    captures: z
+        .array(z.strictObject({
+        variable: replayIdentifierSchema,
+        value: replayValueSourceSchema,
+        sensitive: z.boolean().default(false),
+    }))
+        .max(32)
+        .default([]),
+    actions: z.array(replayActionSchema).min(1).max(32),
+    max_uses: z.number().int().min(1).max(10_000),
+});
+const transitionSignature = (transition) => {
+    const signature = canonicalize({
+        from: transition.from,
+        priority: transition.priority,
+        trigger: transition.trigger,
+    });
+    if (signature === undefined)
+        throw new TypeError("Replay transition signature is not canonical JSON");
+    return signature;
+};
+const replayMachineBaseSchema = z.strictObject({
+    initial_state: replayIdentifierSchema,
+    states: z
+        .array(z.strictObject({
+        name: replayIdentifierSchema,
+        terminal: z.boolean().default(false),
+        max_visits: z.number().int().min(1).max(100_000).default(100_000),
+    }))
+        .min(1)
+        .max(256),
+    transitions: z.array(replayTransitionSchema).min(1).max(2_000),
+    max_transitions: z.number().int().min(1).max(100_000),
+    limits: z
+        .strictObject({
+        connections: z.number().int().min(1).max(1_000).default(100),
+        messages: z.number().int().min(1).max(100_000).default(10_000),
+        bytes: z.number().int().min(1).max(10_000_000).default(1_000_000),
+        duration_ms: z.number().int().min(1).max(300_000).default(30_000),
+    })
+        .default({
+        connections: 100,
+        messages: 10_000,
+        bytes: 1_000_000,
+        duration_ms: 30_000,
+    }),
+});
+const validateReplayIdentities = (machine, context) => {
+    const names = machine.states.map(({ name }) => name);
+    const nameSet = new Set(names);
+    if (nameSet.size !== names.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine state names must be unique",
+            path: ["states"],
+            input: machine,
+        });
+    if (!nameSet.has(machine.initial_state))
+        context.addIssue({
+            code: "custom",
+            message: "replay machine initial state is not declared",
+            path: ["initial_state"],
+            input: machine,
+        });
+    const transitionIds = machine.transitions.map(({ id }) => id);
+    if (new Set(transitionIds).size !== transitionIds.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine transition IDs must be unique",
+            path: ["transitions"],
+            input: machine,
+        });
+    const signatures = machine.transitions.map(transitionSignature);
+    if (new Set(signatures).size !== signatures.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay machine transitions with the same state, trigger, and priority are ambiguous",
+            path: ["transitions"],
+            input: machine,
+        });
+    return nameSet;
+};
+const validateReplayVariables = (machine, context) => {
+    const capturedVariables = new Map();
+    for (const [transitionIndex, transition] of machine.transitions.entries()) {
+        for (const capture of transition.captures) {
+            if (capture.sensitive && capture.value.source === "action_json")
+                context.addIssue({
+                    code: "custom",
+                    message: "sensitive replay captures cannot read literal action JSON persisted in the replay plan",
+                    path: ["transitions", transitionIndex, "captures"],
+                    input: machine,
+                });
+            const sensitivity = capturedVariables.get(capture.variable);
+            if (sensitivity !== undefined && sensitivity !== capture.sensitive)
+                context.addIssue({
+                    code: "custom",
+                    message: "a replay variable cannot change secret classification between captures",
+                    path: ["transitions", transitionIndex, "captures"],
+                    input: machine,
+                });
+            capturedVariables.set(capture.variable, capture.sensitive);
+        }
+    }
+    const availableByState = new Map([
+        [machine.initial_state, new Set()],
+    ]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const transition of machine.transitions) {
+            const available = availableByState.get(transition.from);
+            if (available === undefined ||
+                transition.guards.some(({ variable }) => !available.has(variable)))
+                continue;
+            const nextAvailable = new Set(available);
+            for (const { variable } of transition.captures)
+                nextAvailable.add(variable);
+            const existing = availableByState.get(transition.to);
+            if (existing === undefined) {
+                availableByState.set(transition.to, nextAvailable);
+                changed = true;
+                continue;
+            }
+            for (const variable of nextAvailable)
+                if (!existing.has(variable)) {
+                    existing.add(variable);
+                    changed = true;
+                }
+        }
+    }
+    for (const [transitionIndex, transition] of machine.transitions.entries())
+        for (const [guardIndex, guard] of transition.guards.entries())
+            if (!availableByState.get(transition.from)?.has(guard.variable))
+                context.addIssue({
+                    code: "custom",
+                    message: "replay guard variable is not captured on an executable path before use",
+                    path: ["transitions", transitionIndex, "guards", guardIndex],
+                    input: machine,
+                });
+};
+const validateReplayActions = (machine, context) => {
+    for (const [index, transition] of machine.transitions.entries()) {
+        const httpResponses = transition.actions.filter(({ type }) => type === "http_response").length;
+        const websocketSends = transition.actions.some(({ type }) => type === "websocket_send");
+        const invalid = transition.trigger.protocol === "http"
+            ? httpResponses !== 1 || websocketSends
+            : httpResponses !== 0;
+        if (invalid)
+            context.addIssue({
+                code: "custom",
+                message: "replay actions must match the transition protocol and HTTP transitions require exactly one response",
+                path: ["transitions", index, "actions"],
+                input: machine,
+            });
+    }
+};
+const validateReplayGraph = (machine, names, context) => {
+    const graph = new MultiDirectedGraph();
+    for (const name of names)
+        graph.addNode(name);
+    for (const [index, transition] of machine.transitions.entries()) {
+        if (!names.has(transition.from) || !names.has(transition.to)) {
+            context.addIssue({
+                code: "custom",
+                message: "replay machine transition references an unknown state",
+                path: ["transitions", index],
+                input: machine,
+            });
+            continue;
+        }
+        graph.addDirectedEdgeWithKey(`${transition.id}:${String(index)}`, transition.from, transition.to);
+    }
+    if (!graph.hasNode(machine.initial_state))
+        return;
+    if (!machine.states.some(({ terminal }) => terminal))
+        context.addIssue({
+            code: "custom",
+            message: "replay machine must declare at least one terminal state",
+            path: ["states"],
+            input: machine,
+        });
+    const reachable = new Set(Object.keys(singleSource(graph, machine.initial_state)));
+    reachable.add(machine.initial_state);
+    for (const [index, state] of machine.states.entries()) {
+        if (!reachable.has(state.name))
+            context.addIssue({
+                code: "custom",
+                message: "replay machine state is unreachable from the initial state",
+                path: ["states", index],
+                input: machine,
+            });
+        if (state.terminal && graph.outDegree(state.name) > 0)
+            context.addIssue({
+                code: "custom",
+                message: "terminal replay machine state cannot have outgoing transitions",
+                path: ["states", index],
+                input: machine,
+            });
+        if (!state.terminal && graph.outDegree(state.name) === 0)
+            context.addIssue({
+                code: "custom",
+                message: "non-terminal replay machine state has no outgoing transition",
+                path: ["states", index],
+                input: machine,
+            });
+    }
+};
+/** Portable finite replay machine with no executable callbacks. */
+export const replayMachineSchema = z
+    .object(replayMachineBaseSchema.shape)
+    .strict()
+    .superRefine((machine, context) => {
+    const names = validateReplayIdentities(machine, context);
+    validateReplayVariables(machine, context);
+    validateReplayActions(machine, context);
+    validateReplayGraph(machine, names, context);
+});

package/dist/domain/replayMachineRun.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { replayMachineSchema } from "./replayMachine.js";
+import { replayMachineEventSchema, ReplayMachineRuntime, } from "./replayMachineRuntime.js";
+const refusalOutcomeSchema = z.enum([
+    "unmatched",
+    "invalid_state",
+    "guard_failed",
+    "transition_exhausted",
+    "invalid_capture",
+    "unexpected_reconnect",
+    "limit_exhausted",
+]);
+const MAX_DIRECT_REPLAY_EVENTS = 10_000;
+const MAX_DIRECT_REPLAY_ACTION_BYTES = 4 * 1_024 * 1_024;
+const MAX_DIRECT_REPLAY_ACTION_FIELDS = 1_024;
+const MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES = 1_024;
+const actionFieldCount = (machine) => machine.transitions.reduce((total, transition) => total +
+    transition.actions.reduce((fields, action) => fields +
+        (action.type === "http_response"
+            ? Object.keys(action.headers).length + 1
+            : action.type === "websocket_send"
+                ? 1
+                : 0), 0), 0);
+const maximumSensitiveCapturesPerEvent = (machine) => Math.max(0, ...machine.transitions.map(({ captures }) => captures.filter(({ sensitive }) => sensitive).length));
+/** Complete declarative input for one direct replay-machine run. */
+export const replayMachineRunInputSchema = z
+    .strictObject({
+    machine: replayMachineSchema,
+    events: z.array(replayMachineEventSchema).max(MAX_DIRECT_REPLAY_EVENTS),
+})
+    .superRefine(({ machine, events }, context) => {
+    const actionBytes = Buffer.byteLength(JSON.stringify(machine.transitions.map(({ id, actions }) => ({ id, actions }))));
+    if (actionBytes > MAX_DIRECT_REPLAY_ACTION_BYTES)
+        context.addIssue({
+            code: "custom",
+            path: ["machine", "transitions"],
+            message: "direct replay actions exceed the 4 MiB output boundary",
+            input: machine.transitions,
+        });
+    if (actionFieldCount(machine) > MAX_DIRECT_REPLAY_ACTION_FIELDS)
+        context.addIssue({
+            code: "custom",
+            path: ["machine", "transitions"],
+            message: "direct replay actions exceed the 1,024-field output boundary",
+            input: machine.transitions,
+        });
+    if (maximumSensitiveCapturesPerEvent(machine) * events.length >
+        MAX_DIRECT_REPLAY_SENSITIVE_CAPTURES)
+        context.addIssue({
+            code: "custom",
+            path: ["events"],
+            message: "direct replay events exceed the 1,024 sensitive-capture operation boundary",
+            input: events,
+        });
+});
+const replayMachineRunDecisionSchema = z.strictObject({
+    event_sequence: z.number().int().nonnegative(),
+    outcome: z.union([z.literal("matched"), refusalOutcomeSchema]),
+    transition_sequence: z.number().int().nonnegative().nullable(),
+});
+const replayRunActionSchema = z.discriminatedUnion("type", [
+    z.strictObject({
+        type: z.literal("http_response"),
+        status: z.number().int().min(100).max(599),
+        headers: z.record(z
+            .string()
+            .min(1)
+            .max(256)
+            .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), z.string().max(8_192)),
+        body: z.string().max(1_000_000),
+    }),
+    z.strictObject({
+        type: z.literal("websocket_send"),
+        data: z.string().max(1_000_000),
+    }),
+    z.strictObject({ type: z.literal("disconnect") }),
+    z.strictObject({
+        type: z.literal("delay"),
+        duration_ms: z.number().int().nonnegative().max(30_000),
+    }),
+]);
+const replayRunIdentifierSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u);
+const replayMachineRunJournalEntrySchema = z.strictObject({
+    sequence: z.number().int().nonnegative(),
+    at_ms: z.number().int().nonnegative(),
+    transition_id: replayRunIdentifierSchema,
+    state_before: replayRunIdentifierSchema,
+    state_after: replayRunIdentifierSchema,
+    captured_aliases: z
+        .array(z.strictObject({
+        name: replayRunIdentifierSchema,
+        sensitive: z.boolean(),
+    }))
+        .max(32),
+});
+/** Capture-value-free result of directly evaluating a finite replay machine. */
+export const replayMachineRunOutputSchema = z.strictObject({
+    schema_version: z.literal(1),
+    initial_state: replayRunIdentifierSchema,
+    final_state: replayRunIdentifierSchema,
+    terminal: z.boolean(),
+    decisions: z
+        .array(replayMachineRunDecisionSchema)
+        .max(MAX_DIRECT_REPLAY_EVENTS),
+    transition_journal: z
+        .array(replayMachineRunJournalEntrySchema)
+        .max(MAX_DIRECT_REPLAY_EVENTS),
+    transition_actions: z
+        .array(z.strictObject({
+        transition_id: replayRunIdentifierSchema,
+        actions: z.array(replayRunActionSchema).max(32),
+    }))
+        .max(2_000),
+    limits: z.strictObject({
+        configured: z.strictObject({
+            transitions: z.number().int().positive(),
+            connections: z.number().int().positive(),
+            messages: z.number().int().positive(),
+            bytes: z.number().int().positive(),
+            duration_ms: z.number().int().positive(),
+        }),
+        usage: z.strictObject({
+            offered_events: z.number().int().nonnegative(),
+            admitted_events: z.number().int().nonnegative(),
+            transitions: z.number().int().nonnegative(),
+            connections: z.number().int().nonnegative(),
+            messages: z.number().int().nonnegative(),
+            bytes: z.number().int().nonnegative(),
+            last_at_ms: z.number().int().nonnegative(),
+        }),
+    }),
+});
+const redactAction = (runtime, action) => {
+    switch (action.type) {
+        case "http_response":
+            return {
+                ...action,
+                headers: Object.fromEntries(Object.entries(action.headers).map(([name, value]) => [
+                    name,
+                    runtime.redactField(value),
+                ])),
+                body: runtime.redactField(action.body),
+            };
+        case "websocket_send":
+            return { ...action, data: runtime.redactField(action.data) };
+        case "delay":
+        case "disconnect":
+            return action;
+    }
+};
+/** Evaluate every supplied event in order without opening sockets or processes. */
+export const runReplayMachine = (input) => {
+    const runtime = new ReplayMachineRuntime(input.machine);
+    const decisions = [];
+    const transitionJournal = [];
+    const usedTransitionIds = new Set();
+    for (const [eventSequence, event] of input.events.entries()) {
+        const decision = runtime.dispatch(event);
+        decisions.push({
+            event_sequence: eventSequence,
+            outcome: decision.outcome,
+            transition_sequence: decision.transition?.sequence ?? null,
+        });
+        if (decision.outcome !== "matched")
+            continue;
+        usedTransitionIds.add(decision.transition.transition_id);
+        const definition = input.machine.transitions.find(({ id }) => id === decision.transition.transition_id);
+        if (definition === undefined)
+            throw new TypeError("Replay runtime selected an unknown transition");
+        transitionJournal.push({
+            sequence: decision.transition.sequence,
+            at_ms: decision.transition.at_ms,
+            transition_id: decision.transition.transition_id,
+            state_before: decision.transition.state_before,
+            state_after: decision.transition.state_after,
+            captured_aliases: definition.captures.map(({ variable, sensitive }) => ({
+                name: variable,
+                sensitive,
+            })),
+        });
+    }
+    const usage = runtime.usage;
+    const transitionActions = input.machine.transitions
+        .filter(({ id }) => usedTransitionIds.has(id))
+        .map(({ id, actions }) => ({
+        transition_id: id,
+        actions: actions.map((action) => redactAction(runtime, action)),
+    }));
+    return replayMachineRunOutputSchema.parse({
+        schema_version: 1,
+        initial_state: input.machine.initial_state,
+        final_state: runtime.state,
+        terminal: input.machine.states.find(({ name }) => name === runtime.state)
+            ?.terminal ?? false,
+        decisions,
+        transition_journal: transitionJournal,
+        transition_actions: transitionActions,
+        limits: {
+            configured: {
+                transitions: input.machine.max_transitions,
+                ...input.machine.limits,
+            },
+            usage: {
+                offered_events: input.events.length,
+                admitted_events: usage.events,
+                transitions: usage.transitions,
+                connections: usage.connections,
+                messages: usage.messages,
+                bytes: usage.bytes,
+                last_at_ms: usage.last_at_ms,
+            },
+        },
+    });
+};