rea-agents 3.2.1 → 4.0.0

package/dist/domain/processReactiveRuntime.js

@@ -1,116 +0,0 @@
-import { matchProcessReactiveTrigger } from "./processReactiveMatching.js";
-import {} from "./processReactiveScenario.js";
-export { commitProcessReactiveProposal } from "./processReactiveTransition.js";
-const counterValue = (counters, id) => counters.find((counter) => counter.id === id)?.count ?? 0;
-const observeInput = (snapshot, observation) => {
-    const duplicate = snapshot.observations.find(({ event_id }) => event_id === observation.event_id);
-    if (duplicate !== undefined)
-        return { kind: "invalid" };
-    const prior = snapshot.observations.at(-1);
-    if (prior !== undefined && observation.capture_order <= prior.capture_order)
-        return { kind: "invalid" };
-    return {
-        kind: "new",
-        snapshot: {
-            ...snapshot,
-            observations: [...snapshot.observations, observation],
-        },
-    };
-};
-/** Create the initial immutable reducer state for one validated scenario. */
-export const createProcessReactiveSnapshot = (scenario) => ({
-    status: "running",
-    outcome: null,
-    active_state: scenario.initial_state,
-    state_entry_capture_order: 0,
-    observations: [],
-    consumed_event_ids: [],
-    transition_uses: [],
-    state_visits: [{ id: scenario.initial_state, count: 1 }],
-    checkpoints: [],
-    transitions: [],
-});
-const finishedDecision = (snapshot, outcome, evaluations = []) => ({
-    kind: "finished",
-    outcome,
-    evaluations,
-    snapshot: { ...snapshot, status: "finished", outcome },
-});
-const reduceControlInput = (snapshot, input) => {
-    if (input.kind === "cleanup_failed")
-        return finishedDecision(snapshot, "cleanup_failed");
-    if (snapshot.status === "finished")
-        return { kind: "already_finished", snapshot, evaluations: [] };
-    if (input.kind === "observation")
-        return null;
-    if (input.kind === "state_deadline")
-        return input.state_id === snapshot.active_state &&
-            input.state_entry_capture_order === snapshot.state_entry_capture_order
-            ? finishedDecision(snapshot, "predicate_timeout")
-            : { kind: "waiting", snapshot, evaluations: [] };
-    if (input.kind === "scenario_deadline")
-        return finishedDecision(snapshot, "scenario_deadline");
-    if (input.kind === "target_lost")
-        return finishedDecision(snapshot, "target_lost");
-    return finishedDecision(snapshot, "cancelled");
-};
-/** Advance one validated scenario using only an observation or explicit deadline. */
-export const reduceProcessReactiveScenario = (scenario, snapshot, input) => {
-    const controlDecision = reduceControlInput(snapshot, input);
-    if (controlDecision !== null)
-        return controlDecision;
-    if (input.kind !== "observation")
-        return finishedDecision(snapshot, "capture_incomplete");
-    const admitted = observeInput(snapshot, input.observation);
-    if (admitted.kind === "invalid")
-        return finishedDecision(snapshot, "capture_incomplete");
-    const observed = admitted.snapshot;
-    const state = scenario.states.find(({ id }) => id === observed.active_state);
-    if (state === undefined)
-        return finishedDecision(observed, "target_lost");
-    const matches = state.on.map((transition) => ({
-        transition,
-        match: matchProcessReactiveTrigger(transition.when, observed),
-        uses: counterValue(observed.transition_uses, transition.id),
-    }));
-    const evaluations = matches.map(({ transition, match, uses }) => ({
-        transition_id: transition.id,
-        status: uses >= transition.max_uses
-            ? "exhausted"
-            : match.matched
-                ? "matched"
-                : "unmatched",
-        matched_event_ids: match.eventIds,
-    }));
-    const eligible = matches.filter(({ transition, match, uses }) => match.matched && uses < transition.max_uses);
-    if (eligible.length === 0)
-        return { kind: "waiting", snapshot: observed, evaluations };
-    const minimumPriority = eligible.reduce((minimum, { transition }) => Math.min(minimum, transition.priority), Number.POSITIVE_INFINITY);
-    const winners = eligible.filter(({ transition }) => transition.priority === minimumPriority);
-    if (winners.length !== 1)
-        return finishedDecision(observed, "ambiguous_match", evaluations);
-    const winner = winners[0];
-    if (winner === undefined)
-        return finishedDecision(observed, "capture_incomplete", evaluations);
-    const targetDeclaration = winner.transition.target;
-    if (targetDeclaration.kind === "goto") {
-        const target = scenario.states.find(({ id }) => id === targetDeclaration.state);
-        if (target === undefined ||
-            counterValue(observed.state_visits, target.id) >= target.max_visits)
-            return finishedDecision(observed, "capture_incomplete", evaluations);
-    }
-    return {
-        kind: "proposal",
-        snapshot: observed,
-        evaluations,
-        effects: winner.transition.actions,
-        proposal: {
-            transition_id: winner.transition.id,
-            transition_identity: canonicalize(winner.transition) ?? "",
-            observation_event_id: input.observation.event_id,
-            trigger_event_ids: winner.match.eventIds,
-            consume_event_ids: winner.match.consumeIds,
-        },
-    };
-};
-import canonicalize from "canonicalize";

package/dist/domain/processReactiveScenario.js

@@ -1,296 +0,0 @@
-import { z } from "zod";
-import { jsonValueSchema } from "./jsonValue.js";
-import { processObservationSourceSchema } from "./processObservation.js";
-import { definitelyAvailableCheckpoints } from "./processReactiveCheckpointDataflow.js";
-import { preflightProcessReactiveScenario } from "./processReactiveScenarioPreflight.js";
-/** Structural depth guard for recursive Zod parsing. */
-export const PROCESS_REACTIVE_LIMITS = {
-    // Recursive Zod schemas need a practical stack guard, not a small tree quota.
-    triggerDepth: 256,
-    jsonDepth: 256,
-};
-const identifierSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);
-const checkpointNameSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/u);
-const positiveRuntime = z.number().int().safe().positive();
-const frontierSchema = z.discriminatedUnion("kind", [
-    z.strictObject({ kind: z.literal("scenario_start") }),
-    z.strictObject({ kind: z.literal("state_entry") }),
-    z.strictObject({ kind: z.literal("checkpoint"), name: checkpointNameSchema }),
-    z.strictObject({ kind: z.literal("event_id"), event_id: identifierSchema }),
-]);
-const ignoredFieldSchema = z.enum([
-    "sequence",
-    "at_ms",
-    "scheduled_at_ms",
-    "dispatched_at_ms",
-    "elapsed_ms",
-]);
-const processReactiveTriggerSchema = z.lazy(() => z.discriminatedUnion("kind", [
-    z.strictObject({
-        kind: z.literal("event"),
-        source: processObservationSourceSchema,
-        exact: jsonValueSchema,
-        ignore_fields: z
-            .array(ignoredFieldSchema)
-            .refine((values) => new Set(values).size === values.length, {
-            message: "ignored event fields must be unique",
-        }),
-        since: frontierSchema,
-        consume: z.boolean(),
-        cardinality: z
-            .strictObject({
-            min: z.number().int().safe().positive(),
-            max: z.number().int().safe().positive(),
-        })
-            .refine(({ min, max }) => min <= max, {
-            message: "cardinality min must not exceed max",
-        }),
-    }),
-    z.strictObject({
-        kind: z.literal("terminal_text"),
-        view: z.literal("decoded"),
-        encoding: z.literal("utf8"),
-        literal: z.string().min(1),
-        case_sensitive: z.literal(true),
-        control_sequences: z.literal("include"),
-        occurrence: z.number().int().safe().positive(),
-        since: frontierSchema,
-        consume: z.boolean(),
-    }),
-    z.strictObject({
-        kind: z.literal("all"),
-        triggers: z.array(processReactiveTriggerSchema).min(2),
-    }),
-    z.strictObject({
-        kind: z.literal("any"),
-        triggers: z.array(processReactiveTriggerSchema).min(2),
-    }),
-    z.strictObject({
-        kind: z.literal("sequence"),
-        triggers: z.array(processReactiveTriggerSchema).min(1),
-    }),
-    z
-        .strictObject({
-        kind: z.literal("repeat"),
-        trigger: processReactiveTriggerSchema,
-        min: z.number().int().safe().positive(),
-        max: z.number().int().safe().positive(),
-    })
-        .refine(({ min, max }) => min <= max, {
-        message: "repeat min must not exceed max",
-    }),
-]));
-const signalTargetSchema = z.discriminatedUnion("kind", [
-    z.strictObject({ kind: z.literal("root") }),
-    z.strictObject({ kind: z.literal("process_group") }),
-    z.strictObject({
-        kind: z.literal("subject_id"),
-        subject_id: identifierSchema,
-    }),
-]);
-const processReactiveActionSchema = z.discriminatedUnion("type", [
-    z.strictObject({
-        type: z.literal("send_input"),
-        data: z.string(),
-        sensitive: z.boolean(),
-    }),
-    z.strictObject({
-        type: z.literal("resize"),
-        columns: z.number().int().positive(),
-        rows: z.number().int().positive(),
-    }),
-    z.strictObject({ type: z.literal("close_stdin") }),
-    z.strictObject({
-        type: z.literal("send_signal"),
-        target: signalTargetSchema,
-        signal: z.enum(["SIGINT", "SIGTERM", "SIGKILL"]),
-    }),
-    z.strictObject({ type: z.literal("checkpoint"), name: checkpointNameSchema }),
-]);
-const transitionTargetSchema = z.discriminatedUnion("kind", [
-    z.strictObject({ kind: z.literal("goto"), state: identifierSchema }),
-    z.strictObject({ kind: z.literal("finish"), outcome: z.literal("passed") }),
-]);
-const transitionSchema = z.strictObject({
-    id: identifierSchema,
-    priority: z.number().int().safe().min(0),
-    max_uses: z.number().int().safe().positive(),
-    when: processReactiveTriggerSchema,
-    actions: z.array(processReactiveActionSchema),
-    target: transitionTargetSchema,
-});
-const stateSchema = z.strictObject({
-    id: identifierSchema,
-    max_visits: z.number().int().safe().positive(),
-    deadline_ms: positiveRuntime,
-    on: z.array(transitionSchema).min(1),
-});
-const scenarioShapeSchema = z.strictObject({
-    initial_state: identifierSchema,
-    deadline_ms: positiveRuntime,
-    states: z.array(stateSchema).min(1),
-});
-const measureTrigger = (trigger) => {
-    if (trigger.kind === "event" || trigger.kind === "terminal_text")
-        return { depth: 1 };
-    const children = trigger.kind === "repeat" ? [trigger.trigger] : trigger.triggers;
-    const measured = children.map(measureTrigger);
-    return {
-        depth: 1 + measured.reduce((maximum, { depth }) => Math.max(maximum, depth), 0),
-    };
-};
-const collectCheckpointFrontiers = (trigger) => {
-    if (trigger.kind === "event" || trigger.kind === "terminal_text")
-        return trigger.since.kind === "checkpoint" ? [trigger.since.name] : [];
-    const children = trigger.kind === "repeat" ? [trigger.trigger] : trigger.triggers;
-    return children.flatMap(collectCheckpointFrontiers);
-};
-const validateTriggerSemantics = (trigger, path, context) => {
-    if (trigger.kind === "event") {
-        const exact = trigger.exact;
-        if (trigger.ignore_fields.length > 0 &&
-            (typeof exact !== "object" || exact === null || Array.isArray(exact)))
-            context.addIssue({
-                code: "custom",
-                message: "ignored fields require an exact object payload",
-                path: [...path, "ignore_fields"],
-            });
-        if (typeof exact === "object" &&
-            exact !== null &&
-            !Array.isArray(exact) &&
-            trigger.ignore_fields.some((field) => field in exact))
-            context.addIssue({
-                code: "custom",
-                message: "exact payload must omit every ignored field",
-                path: [...path, "exact"],
-            });
-        return;
-    }
-    if (trigger.kind === "terminal_text")
-        return;
-    if (trigger.kind === "repeat") {
-        validateTriggerSemantics(trigger.trigger, [...path, "trigger"], context);
-        return;
-    }
-    for (const [index, child] of trigger.triggers.entries())
-        validateTriggerSemantics(child, [...path, "triggers", index], context);
-};
-const validateTransition = (input) => {
-    const { transition, validation, path, context } = input;
-    const measured = measureTrigger(transition.when);
-    validateTriggerSemantics(transition.when, [...path, "when"], context);
-    if (measured.depth > PROCESS_REACTIVE_LIMITS.triggerDepth)
-        context.addIssue({
-            code: "custom",
-            message: "trigger nesting exceeds the configured limit",
-            path: [...path, "when"],
-        });
-    if (validation.transitionIds.has(transition.id))
-        context.addIssue({
-            code: "custom",
-            message: "transition ids must be unique",
-            path: [...path, "id"],
-        });
-    validation.transitionIds.add(transition.id);
-    for (const action of transition.actions) {
-        if (action.type !== "checkpoint")
-            continue;
-        if (validation.checkpoints.has(action.name))
-            context.addIssue({
-                code: "custom",
-                message: "checkpoint action names must be unique",
-                path: [...path, "actions"],
-            });
-        validation.checkpoints.add(action.name);
-    }
-    for (const name of collectCheckpointFrontiers(transition.when))
-        validation.checkpointReferences.push({
-            name,
-            stateId: input.stateId,
-            path: [...path, "when"],
-        });
-    if (transition.target.kind !== "goto")
-        return;
-    if (!validation.knownStates.has(transition.target.state)) {
-        context.addIssue({
-            code: "custom",
-            message: "transition target state is not declared",
-            path: [...path, "target", "state"],
-        });
-        return;
-    }
-    validation.adjacency.get(input.stateId)?.add(transition.target.state);
-};
-const validateTotalsAndReferences = (scenario, validation, context) => {
-    const available = definitelyAvailableCheckpoints(scenario);
-    for (const reference of validation.checkpointReferences)
-        if (!available.get(reference.stateId)?.has(reference.name))
-            context.addIssue({
-                code: "custom",
-                message: "checkpoint frontier is not definitely available before this transition",
-                path: reference.path,
-            });
-};
-const validateReachability = (scenario, stateIds, validation, context) => {
-    const reachable = new Set();
-    const pending = validation.knownStates.has(scenario.initial_state)
-        ? [scenario.initial_state]
-        : [];
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined || reachable.has(current))
-            continue;
-        reachable.add(current);
-        pending.push(...(validation.adjacency.get(current) ?? []));
-    }
-    for (const [index, id] of stateIds.entries())
-        if (!reachable.has(id))
-            context.addIssue({
-                code: "custom",
-                message: "state is unreachable from the initial state",
-                path: ["states", index],
-            });
-};
-const validateScenarioGraph = (scenario, context) => {
-    const stateIds = scenario.states.map(({ id }) => id);
-    const knownStates = new Set(stateIds);
-    if (knownStates.size !== stateIds.length)
-        context.addIssue({
-            code: "custom",
-            message: "state ids must be unique",
-            path: ["states"],
-        });
-    if (!knownStates.has(scenario.initial_state))
-        context.addIssue({
-            code: "custom",
-            message: "initial state is not declared",
-            path: ["initial_state"],
-        });
-    const validation = {
-        knownStates,
-        transitionIds: new Set(),
-        checkpoints: new Set(),
-        checkpointReferences: [],
-        adjacency: new Map(stateIds.map((id) => [id, new Set()])),
-    };
-    for (const [stateIndex, state] of scenario.states.entries()) {
-        if (state.deadline_ms > scenario.deadline_ms)
-            context.addIssue({
-                code: "custom",
-                message: "state deadline must not exceed scenario deadline",
-                path: ["states", stateIndex, "deadline_ms"],
-            });
-        for (const [transitionIndex, transition] of state.on.entries())
-            validateTransition({
-                stateId: state.id,
-                transition,
-                path: ["states", stateIndex, "on", transitionIndex],
-                validation,
-                context,
-            });
-    }
-    validateTotalsAndReferences(scenario, validation, context);
-    validateReachability(scenario, stateIds, validation, context);
-};
-/** Strict boundary schema for a bounded declarative reactive scenario. */
-export const processReactiveScenarioSchema = z.preprocess((input, context) => preflightProcessReactiveScenario(input, context, PROCESS_REACTIVE_LIMITS), scenarioShapeSchema.superRefine((scenario, context) => validateScenarioGraph(scenario, context)));

package/dist/domain/processReactiveScenarioPreflight.js

@@ -1,95 +0,0 @@
-import { z } from "zod";
-const isUnknownRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const reject = (context, message) => {
-    context.addIssue({ code: "custom", message });
-    return false;
-};
-const inspectJsonValue = (value, context, limits) => {
-    const pending = [{ value, depth: 1 }];
-    const seen = new WeakSet();
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        if (current.depth > limits.jsonDepth)
-            return reject(context, "event exact JSON exceeds the configured depth limit");
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        if (seen.has(current.value))
-            return reject(context, "event exact JSON must not contain cycles");
-        seen.add(current.value);
-        if (Array.isArray(current.value)) {
-            for (const child of current.value)
-                pending.push({ value: child, depth: current.depth + 1 });
-            continue;
-        }
-        if (!isUnknownRecord(current.value))
-            continue;
-        for (const key in current.value) {
-            if (!Object.hasOwn(current.value, key))
-                continue;
-            pending.push({
-                value: current.value[key],
-                depth: current.depth + 1,
-            });
-        }
-    }
-    return true;
-};
-const collectTriggerRoots = (states) => {
-    const pending = [];
-    for (const stateValue of states) {
-        if (!isUnknownRecord(stateValue) || !Array.isArray(stateValue["on"]))
-            continue;
-        for (const transitionValue of stateValue["on"])
-            if (isUnknownRecord(transitionValue))
-                pending.push({ value: transitionValue["when"], depth: 1 });
-    }
-    return pending;
-};
-const enqueueTriggerChildren = (trigger, depth, traversal) => {
-    if (trigger["kind"] === "repeat") {
-        traversal.pending.push({ value: trigger["trigger"], depth: depth + 1 });
-        return true;
-    }
-    if (trigger["kind"] !== "all" &&
-        trigger["kind"] !== "any" &&
-        trigger["kind"] !== "sequence")
-        return true;
-    const children = trigger["triggers"];
-    if (!Array.isArray(children))
-        return true;
-    for (const child of children)
-        traversal.pending.push({ value: child, depth: depth + 1 });
-    return true;
-};
-const inspectTriggerTree = (pending, context, limits) => {
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        if (current.depth > limits.triggerDepth)
-            return reject(context, "trigger nesting exceeds the configured limit");
-        if (isUnknownRecord(current.value) &&
-            current.value["kind"] === "event" &&
-            !inspectJsonValue(current.value["exact"], context, limits))
-            return false;
-        if (isUnknownRecord(current.value) &&
-            !enqueueTriggerChildren(current.value, current.depth, {
-                pending,
-                context,
-                limits,
-            }))
-            return false;
-    }
-    return true;
-};
-/** Reject oversized unknown trees before the recursive Zod schema visits them. */
-export const preflightProcessReactiveScenario = (input, context, limits) => {
-    if (!isUnknownRecord(input) || !Array.isArray(input["states"]))
-        return input;
-    const pending = collectTriggerRoots(input["states"]);
-    if (!inspectTriggerTree(pending, context, limits))
-        return z.NEVER;
-    return input;
-};