rea-agents 3.2.0 → 4.0.0

package/dist/application/ProcessCheckpoints.js

@@ -1,178 +0,0 @@
-import { snapshotRoots } from "./FilesystemSnapshot.js";
-import { scheduleProcessDelay } from "./ProcessTimer.js";
-/** Classify path-stable filesystem effects between two bounded states. */
-export const classifyFilesystemEffects = (before, after) => {
-    const beforeByPath = new Map(before.map((file) => [file.path, file]));
-    const afterByPath = new Map(after.map((file) => [file.path, file]));
-    return [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])]
-        .sort()
-        .map((path) => {
-        const beforeFile = beforeByPath.get(path) ?? null;
-        const afterFile = afterByPath.get(path) ?? null;
-        if (beforeFile === null) {
-            if (afterFile === null)
-                throw new TypeError(`Filesystem effect ${path} has no file state`);
-            return {
-                path,
-                status: "created",
-                before: null,
-                after: afterFile,
-            };
-        }
-        if (afterFile === null)
-            return {
-                path,
-                status: "deleted",
-                before: beforeFile,
-                after: null,
-            };
-        return {
-            path,
-            status: JSON.stringify(beforeFile) === JSON.stringify(afterFile)
-                ? "unchanged"
-                : "modified",
-            before: beforeFile,
-            after: afterFile,
-        };
-    });
-};
-/** Coordinates named lifecycle filesystem observations without overlapping scans. */
-export class ProcessCheckpoints {
-    scenario;
-    started;
-    #captures = [];
-    #captured = new Set();
-    #terminalCounts = new Map();
-    #terminalTails = new Map();
-    #timers = new Set();
-    #signal;
-    #recordEvent;
-    #pending = Promise.resolve();
-    constructor(scenario, started, before, options = { signal: undefined }) {
-        this.scenario = scenario;
-        this.started = started;
-        this.#signal = options.signal;
-        this.#recordEvent = options.recordEvent ?? (() => undefined);
-        this.#captures.push({
-            name: "before",
-            at_ms: 0,
-            files: before.files,
-            effects: [],
-            truncated: before.truncated,
-        });
-        this.#recordEvent("filesystem_checkpoints", 0);
-        this.#captured.add("before");
-        for (const checkpoint of scenario.checkpoints) {
-            if (checkpoint.trigger.type !== "time")
-                continue;
-            const timer = scheduleProcessDelay(checkpoint.trigger.at_ms, () => this.capture(checkpoint.name));
-            this.#timers.add(timer);
-        }
-    }
-    /** Observe normalized terminal text and fire matching literal checkpoints once. */
-    observeTerminal(data) {
-        for (const checkpoint of this.scenario.checkpoints) {
-            const trigger = checkpoint.trigger;
-            if (trigger.type !== "terminal_literal" ||
-                this.#captured.has(checkpoint.name))
-                continue;
-            const combined = `${this.#terminalTails.get(checkpoint.name) ?? ""}${data}`;
-            const count = (this.#terminalCounts.get(checkpoint.name) ?? 0) +
-                countOccurrences(combined, trigger.value);
-            this.#terminalCounts.set(checkpoint.name, count);
-            this.#terminalTails.set(checkpoint.name, trigger.value.length === 1
-                ? ""
-                : combined.slice(-(trigger.value.length - 1)));
-            if (count >= trigger.occurrence)
-                this.capture(checkpoint.name);
-        }
-    }
-    /** Capture every checkpoint assigned to the specified lifecycle trigger. */
-    trigger(type) {
-        for (const checkpoint of this.scenario.checkpoints)
-            if (checkpoint.trigger.type === type)
-                this.capture(checkpoint.name);
-    }
-    /** Queue one idempotent named snapshot. */
-    capture(name) {
-        this.#scheduleCapture(name, this.#signal);
-    }
-    /** Read one committed checkpoint for synchronous journal projection. */
-    at(index) {
-        const checkpoint = this.#captures[index];
-        return checkpoint === undefined ? undefined : structuredClone(checkpoint);
-    }
-    #scheduleCapture(name, signal) {
-        if (this.#captured.has(name))
-            return;
-        this.#captured.add(name);
-        // Serialize scans even when time, terminal, and lifecycle triggers fire
-        // together. Each effect set is intentionally relative to the immediately
-        // preceding checkpoint, which preserves transient create/delete behavior.
-        this.#pending = this.#pending.then(async () => {
-            const snapshot = await snapshotRoots(this.scenario, signal);
-            const previous = this.#captures.at(-1)?.files ?? [];
-            const index = this.#captures.length;
-            this.#captures.push({
-                name,
-                at_ms: Math.max(0, Date.now() - this.started),
-                files: snapshot.files,
-                effects: classifyFilesystemEffects(previous, snapshot.files),
-                truncated: snapshot.truncated,
-            });
-            this.#recordEvent("filesystem_checkpoints", index);
-        });
-    }
-    /** Queue one named snapshot and return its exact captured record. */
-    async captureAndRead(name, signal) {
-        const captureSignal = signal === undefined
-            ? this.#signal
-            : this.#signal === undefined
-                ? signal
-                : AbortSignal.any([this.#signal, signal]);
-        this.#scheduleCapture(name, captureSignal);
-        const scheduled = this.#pending;
-        await scheduled;
-        const index = this.#captures.findIndex(({ name: capturedName }) => capturedName === name);
-        const checkpoint = this.#captures[index];
-        if (index < 0 || checkpoint === undefined)
-            throw new Error(`filesystem checkpoint was not captured: ${name}`);
-        return { index, checkpoint: structuredClone(checkpoint) };
-    }
-    /** Finish pending snapshots and return them in observation order. */
-    async finish(after) {
-        for (const timer of this.#timers)
-            timer.cancel();
-        await this.#pending;
-        const previous = this.#captures.at(-1)?.files ?? [];
-        const index = this.#captures.length;
-        this.#captures.push({
-            name: "after_settlement",
-            at_ms: Math.max(0, Date.now() - this.started),
-            files: after.files,
-            effects: classifyFilesystemEffects(previous, after.files),
-            truncated: after.truncated,
-        });
-        this.#recordEvent("filesystem_checkpoints", index);
-        return structuredClone(this.#captures);
-    }
-    /** Cancel scheduled captures and await any snapshot already in progress. */
-    async dispose() {
-        for (const timer of this.#timers)
-            timer.cancel();
-        this.#timers.clear();
-        await this.#pending;
-    }
-}
-const countOccurrences = (text, value) => {
-    let count = 0;
-    let offset = 0;
-    while (offset <= text.length - value.length) {
-        const found = text.indexOf(value, offset);
-        if (found < 0)
-            break;
-        count += 1;
-        offset = found + value.length;
-    }
-    return count;
-};

package/dist/application/ProcessReactiveCoordinator.js

@@ -1,223 +0,0 @@
-import { commitProcessReactiveProposal, createProcessReactiveSnapshot, reduceProcessReactiveScenario, } from "../domain/processReactiveRuntime.js";
-import { scheduleProcessDelay } from "./ProcessTimer.js";
-const systemTimerHost = {
-    schedule: (callback, delayMs) => scheduleProcessDelay(delayMs, callback),
-};
-/**
- * Serializes live observations, deadlines, and effect commits for one run.
- * Producer callbacks enqueue work without awaiting it, preventing reentrancy.
- */
-export class ProcessReactiveCoordinator {
-    #scenario;
-    #executor;
-    #timerHost;
-    #now;
-    #scenarioDeadlineAt;
-    #onDecision;
-    #snapshot;
-    #pendingInputs = [];
-    #tail = Promise.resolve();
-    #running = false;
-    #failure;
-    #stateTimer;
-    #scenarioTimer;
-    #stateDeadlineAt = 0;
-    #effectAbort;
-    #accepting = true;
-    #closed = false;
-    constructor(options) {
-        this.#scenario = options.scenario;
-        this.#executor = options.executor;
-        this.#timerHost = options.timerHost ?? systemTimerHost;
-        this.#now = options.now ?? Date.now;
-        this.#scenarioDeadlineAt = this.#now() + options.scenario.deadline_ms;
-        this.#onDecision = options.onDecision;
-        this.#snapshot = createProcessReactiveSnapshot(options.scenario);
-        this.#scheduleScenarioDeadline();
-        this.#scheduleStateDeadline();
-    }
-    /** Current immutable reducer snapshot after all completed turns. */
-    get snapshot() {
-        return this.#snapshot;
-    }
-    /** Enqueue producer work without creating a floating promise. */
-    enqueue(input) {
-        if (!this.#accepting)
-            return;
-        if (this.#interruptsEffects(input))
-            this.#effectAbort?.abort();
-        this.#enqueueOwned(input);
-    }
-    /** Submit one input and wait until every turn queued before it completes. */
-    async submit(input) {
-        this.enqueue(input);
-        await this.drain();
-        return this.#snapshot;
-    }
-    /** Wait for currently queued reducer/effect work and surface host failures. */
-    async drain() {
-        for (;;) {
-            const observedTail = this.#tail;
-            await observedTail;
-            if (observedTail === this.#tail)
-                break;
-        }
-        if (this.#failure !== undefined)
-            throw this.#failure;
-    }
-    /** Stop owned deadlines after queued work settles. */
-    async close() {
-        this.#accepting = false;
-        this.#clearTimers();
-        await this.drain();
-        this.#closed = true;
-    }
-    #enqueueOwned(input) {
-        if (this.#closed || this.#failure !== undefined)
-            return;
-        this.#pendingInputs.push(input);
-        this.#startWorker();
-    }
-    #startWorker() {
-        if (this.#running || this.#pendingInputs.length === 0)
-            return;
-        this.#running = true;
-        this.#tail = this.#runQueue()
-            .catch((cause) => this.#fail(cause))
-            .finally(() => {
-            this.#running = false;
-            if (this.#pendingInputs.length > 0)
-                this.#startWorker();
-        });
-    }
-    async #runQueue() {
-        for (;;) {
-            const input = this.#nextInput();
-            if (input === undefined)
-                return;
-            await this.#advance(input);
-        }
-    }
-    #nextInput() {
-        const terminalIndex = this.#pendingInputs.findIndex(({ kind }) => kind === "cancelled" || kind === "cleanup_failed");
-        if (terminalIndex >= 0)
-            return this.#pendingInputs.splice(terminalIndex, 1)[0];
-        let observationIndex = -1;
-        let captureOrder = Number.POSITIVE_INFINITY;
-        for (const [index, input] of this.#pendingInputs.entries())
-            if (input.kind === "observation" &&
-                input.observation.capture_order < captureOrder) {
-                observationIndex = index;
-                captureOrder = input.observation.capture_order;
-            }
-        return observationIndex >= 0
-            ? this.#pendingInputs.splice(observationIndex, 1)[0]
-            : this.#pendingInputs.shift();
-    }
-    #fail(cause) {
-        this.#failure ??= cause;
-        this.#accepting = false;
-        this.#closed = true;
-        this.#effectAbort?.abort();
-        this.#pendingInputs.length = 0;
-        this.#clearTimers();
-    }
-    async #advance(input) {
-        const before = this.#snapshot;
-        let decision = reduceProcessReactiveScenario(this.#scenario, before, input);
-        let effectResults = [];
-        if (decision.kind === "proposal") {
-            const effectAbort = new AbortController();
-            this.#effectAbort = effectAbort;
-            try {
-                effectResults = await this.#executor.execute(decision.effects, effectAbort.signal);
-            }
-            catch (cause) {
-                if (effectAbort.signal.aborted)
-                    return;
-                throw cause;
-            }
-            finally {
-                if (this.#effectAbort === effectAbort)
-                    this.#effectAbort = undefined;
-            }
-            if (effectAbort.signal.aborted)
-                return;
-            const expired = this.#expiredDeadlineInput();
-            if (expired !== undefined) {
-                this.#enqueueOwned(expired);
-                return;
-            }
-            decision = commitProcessReactiveProposal(this.#scenario, decision, effectResults);
-        }
-        this.#snapshot = decision.snapshot;
-        this.#onDecision?.(decision, input);
-        if (this.#snapshot.status === "finished")
-            this.#clearTimers();
-        else if (this.#accepting &&
-            (before.active_state !== this.#snapshot.active_state ||
-                before.state_entry_capture_order !==
-                    this.#snapshot.state_entry_capture_order))
-            this.#scheduleStateDeadline();
-        for (const result of effectResults)
-            if (result.status === "succeeded" &&
-                !this.#hasObservation(result.observation.event_id))
-                this.#enqueueOwned({
-                    kind: "observation",
-                    observation: result.observation,
-                });
-    }
-    #hasObservation(eventId) {
-        return (this.#snapshot.observations.some((observation) => observation.event_id === eventId) ||
-            this.#pendingInputs.some((input) => input.kind === "observation" &&
-                input.observation.event_id === eventId));
-    }
-    #interruptsEffects(input) {
-        if (input.kind === "cancelled" ||
-            input.kind === "cleanup_failed" ||
-            input.kind === "scenario_deadline" ||
-            input.kind === "target_lost")
-            return true;
-        return (input.kind === "state_deadline" &&
-            input.state_id === this.#snapshot.active_state &&
-            input.state_entry_capture_order ===
-                this.#snapshot.state_entry_capture_order);
-    }
-    #expiredDeadlineInput() {
-        const now = this.#now();
-        if (now >= this.#scenarioDeadlineAt)
-            return { kind: "scenario_deadline" };
-        if (now < this.#stateDeadlineAt)
-            return undefined;
-        return {
-            kind: "state_deadline",
-            state_id: this.#snapshot.active_state,
-            state_entry_capture_order: this.#snapshot.state_entry_capture_order,
-        };
-    }
-    #scheduleScenarioDeadline() {
-        if (!this.#accepting)
-            return;
-        this.#scenarioTimer = this.#timerHost.schedule(() => this.enqueue({ kind: "scenario_deadline" }), this.#scenario.deadline_ms);
-    }
-    #scheduleStateDeadline() {
-        if (!this.#accepting)
-            return;
-        this.#stateTimer?.cancel();
-        const state = this.#scenario.states.find(({ id }) => id === this.#snapshot.active_state);
-        if (state === undefined)
-            return;
-        this.#stateDeadlineAt = this.#now() + state.deadline_ms;
-        const identity = {
-            state_id: state.id,
-            state_entry_capture_order: this.#snapshot.state_entry_capture_order,
-        };
-        this.#stateTimer = this.#timerHost.schedule(() => this.enqueue({ kind: "state_deadline", ...identity }), state.deadline_ms);
-    }
-    #clearTimers() {
-        this.#stateTimer?.cancel();
-        this.#scenarioTimer?.cancel();
-        this.#stateTimer = undefined;
-        this.#scenarioTimer = undefined;
-    }
-}

package/dist/application/ProcessReactiveEffects.js

@@ -1,153 +0,0 @@
-import { createProcessObservation } from "../domain/processObservation.js";
-import { normalizeProcessElapsedTime } from "./ProcessNormalization.js";
-const elapsed = (host) => Math.max(0, host.now() - host.startedAtMs);
-const interactionData = (action) => {
-    if (action.type === "send_input")
-        return action.sensitive
-            ? `<redacted-input:${String(Buffer.byteLength(action.data))}-bytes>`
-            : action.data;
-    if (action.type === "resize")
-        return `${String(action.columns)}x${String(action.rows)}`;
-    if (action.type === "close_stdin")
-        return "";
-    return action.signal;
-};
-const interactionType = (action) => {
-    if (action.type === "send_input")
-        return "input";
-    if (action.type === "resize")
-        return "resize";
-    if (action.type === "close_stdin")
-        return "stdin_close";
-    return "signal";
-};
-const performTerminalAction = (host, terminal, action, atMs) => {
-    if (action.type === "send_input")
-        terminal.write(action.data);
-    else if (action.type === "resize") {
-        terminal.resize(action.columns, action.rows);
-        // Rendered frames share the normalized clock used by captured terminal
-        // frames and by the scheduled-event resize path. Passing the raw elapsed
-        // time here stamped this frame on a different clock, so the next bucketed
-        // frame could appear to move backwards and fail capture validation with
-        // "rendered_frames: timestamps must be ordered".
-        host.renderer.resize(action.columns, action.rows, normalizeProcessElapsedTime(atMs, host.timeBucketMs));
-    }
-    else if (action.type === "close_stdin")
-        terminal.closeInput();
-    else
-        terminal.kill(action.signal);
-};
-const recordInteraction = (host, action, atMs, outcome) => {
-    const index = host.interactions.length;
-    const event = {
-        sequence: index,
-        scheduled_at_ms: atMs,
-        dispatched_at_ms: atMs,
-        type: interactionType(action),
-        data: interactionData(action),
-        outcome,
-    };
-    host.interactions.push(event);
-    const location = host.journal.record("interaction_events", index);
-    if (outcome !== "dispatched")
-        return { status: "rejected" };
-    return {
-        status: "succeeded",
-        observation: createProcessObservation({
-            source: "interaction",
-            source_sequence: index,
-            captured_at_ms: atMs,
-            subject_id: null,
-            location,
-            payload: event,
-        }),
-    };
-};
-const executeTerminalAction = (host, action) => {
-    if (action.type === "send_signal" && action.target.kind !== "root")
-        return { status: "rejected" };
-    const terminal = host.terminal();
-    if (terminal === undefined)
-        return { status: "target_lost" };
-    const atMs = elapsed(host);
-    let outcome = "dispatched";
-    try {
-        performTerminalAction(host, terminal, action, atMs);
-    }
-    catch {
-        outcome = "failed";
-    }
-    return recordInteraction(host, action, atMs, outcome);
-};
-const executeCheckpoint = async (host, action, signal) => {
-    try {
-        const { index, checkpoint } = await host.checkpoints.captureAndRead(action.name, signal);
-        const location = host.journal.entries.findLast((entry) => entry.collection === "filesystem_checkpoints" && entry.index === index);
-        if (location === undefined)
-            return { status: "rejected" };
-        return {
-            status: "succeeded",
-            observation: createProcessObservation({
-                source: "filesystem",
-                source_sequence: index,
-                captured_at_ms: checkpoint.at_ms,
-                subject_id: `checkpoint:${checkpoint.name}`,
-                location,
-                payload: checkpoint,
-            }),
-        };
-    }
-    catch {
-        return { status: "rejected" };
-    }
-};
-/** Execute proposed effects in order and stop after the first failure. */
-export const executeProcessReactiveEffects = async (host, actions, signal) => {
-    const results = [];
-    for (const action of actions) {
-        if (signal.aborted)
-            return results;
-        const result = action.type === "checkpoint"
-            ? await executeCheckpoint(host, action, signal)
-            : executeTerminalAction(host, action);
-        results.push(result);
-        if (result.status !== "succeeded")
-            break;
-    }
-    return results;
-};
-const triggerSources = (trigger) => {
-    if (trigger.kind === "terminal_text")
-        return [];
-    if (trigger.kind === "event")
-        return [
-            "terminal_raw",
-            "interaction",
-            "process",
-            "filesystem",
-            "http",
-            "websocket",
-            "shim",
-        ].includes(trigger.source)
-            ? []
-            : [trigger.source];
-    return trigger.kind === "repeat"
-        ? triggerSources(trigger.trigger)
-        : trigger.triggers.flatMap(triggerSources);
-};
-/** Return unsupported sources, selectors, and checkpoint collisions pre-launch. */
-export const unsupportedProcessReactiveFeatures = (scenario, reservedCheckpointNames = new Set([
-    "before",
-    "after_settlement",
-])) => [
-    ...scenario.states.flatMap((state) => state.on.flatMap((transition) => triggerSources(transition.when).map((source) => `${transition.id}:source:${source}`))),
-    ...scenario.states.flatMap((state) => state.on.flatMap((transition) => transition.actions.flatMap((action) => {
-        if (action.type === "send_signal" && action.target.kind !== "root")
-            return [`${transition.id}:target:${action.target.kind}`];
-        if (action.type === "checkpoint" &&
-            reservedCheckpointNames.has(action.name))
-            return [`${transition.id}:checkpoint:${action.name}`];
-        return [];
-    }))),
-];

package/dist/application/ProcessReactiveHarness.js

@@ -1,106 +0,0 @@
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
-import { ProcessReactiveCoordinator } from "./ProcessReactiveCoordinator.js";
-import { executeProcessReactiveEffects, unsupportedProcessReactiveFeatures, } from "./ProcessReactiveEffects.js";
-import { subscribeProcessReactiveObservations } from "./ProcessReactiveObservations.js";
-import { normalizeProcessSamples, normalizeProcessShimEvent, redactProtocolEvents, } from "./ProcessNormalization.js";
-const reactiveTerminalFor = (terminal) => {
-    if (terminal === undefined)
-        return undefined;
-    return {
-        write: (data) => terminal.write(data),
-        resize: (columns, rows) => terminal.resize(columns, rows),
-        closeInput: () => {
-            const end = Reflect.get(terminal, "end");
-            if (typeof end !== "function")
-                throw new ProcessCaptureError("PTY backend does not expose an stdin-close operation");
-            Reflect.apply(end, terminal, []);
-        },
-        kill: (signal) => terminal.kill(signal),
-    };
-};
-const controlKind = (input) => input.kind === "observation" ? undefined : input.kind;
-/** Reject reactive declarations the current process adapter cannot execute. */
-export const assertSupportedReactiveScenario = (scenario) => {
-    if (scenario.reactive === null)
-        return;
-    const unsupported = unsupportedProcessReactiveFeatures(scenario.reactive);
-    if (unsupported.length === 0)
-        return;
-    throw new ProcessCaptureError(`reactive scenario requests unsupported features: ${unsupported.join(", ")}`);
-};
-/**
- * Attach the serialized reactive runtime once the target PID is available.
- *
- * Subscription replays journal entries admitted during launcher startup before
- * observing new records, so PID-dependent normalization cannot drop them.
- */
-export const startProcessReactiveHarness = (options) => {
-    if (options.scenario.reactive === null)
-        return undefined;
-    const controls = [];
-    const coordinator = new ProcessReactiveCoordinator({
-        scenario: options.scenario.reactive,
-        executor: {
-            execute: (actions, signal) => executeProcessReactiveEffects({
-                terminal: () => reactiveTerminalFor(options.terminal()),
-                renderer: options.renderer,
-                checkpoints: options.checkpoints,
-                interactions: options.capture.interactions,
-                journal: options.capture.journal,
-                startedAtMs: options.started,
-                now: Date.now,
-                timeBucketMs: options.scenario.normalization.time_bucket_ms,
-            }, actions, signal),
-        },
-        onDecision: (decision, input) => {
-            const kind = controlKind(input);
-            if (kind === undefined || decision.kind !== "finished")
-                return;
-            controls.push({
-                sequence: controls.length,
-                kind,
-                after_capture_order: decision.snapshot.observations.at(-1)?.capture_order ?? -1,
-            });
-        },
-    });
-    return {
-        coordinator,
-        controls,
-        unsubscribe: subscribeProcessReactiveObservations({
-            journal: options.capture.journal,
-            frames: options.capture.frames,
-            interactions: options.capture.interactions,
-            checkpointAt: (index) => options.checkpoints.at(index),
-            processSampleAt: (index) => {
-                const rootPid = options.terminal()?.pid;
-                return rootPid === undefined
-                    ? undefined
-                    : normalizeProcessSamples(options.capture.processSamples, options.scenario, rootPid)[index];
-            },
-            protocolEventAt: (index) => redactProtocolEvents(options.capture.protocolEvents().slice(index, index + 1), options.scenario)[0],
-            shimEventAt: (index) => {
-                const event = options.shimReplay.events[index];
-                const rootPid = options.terminal()?.pid;
-                return event === undefined || rootPid === undefined
-                    ? undefined
-                    : normalizeProcessShimEvent(event, options.scenario, options.capture.temporaryRoot, rootPid);
-            },
-            sink: coordinator,
-        }),
-    };
-};
-/** Project internal reducer state into the stable Process Capture shape. */
-export const projectProcessReactiveRun = (harness) => {
-    if (harness === undefined)
-        return null;
-    const snapshot = harness.coordinator.snapshot;
-    const completion = snapshot.status === "running"
-        ? { status: snapshot.status, outcome: null }
-        : { status: snapshot.status, outcome: snapshot.outcome };
-    return {
-        ...completion,
-        active_state: snapshot.active_state,
-        transitions: snapshot.transitions,
-        controls: harness.controls,
-    };
-};