rea-agents 2.1.0 → 2.3.0

package/dist/application/LoopbackReplay.js

@@ -1,113 +1,144 @@
 import { createServer, } from "node:http";
 import { WebSocketServer } from "ws";
-class ReplayRecorder {
-    scenario;
-    events = [];
-    started = Date.now();
-    truncated = false;
-    constructor(scenario) {
-        this.scenario = scenario;
+import {} from "../domain/replayMachineRuntime.js";
+import { closeReplayServer, listenOnLoopback, recordMachineEvent, readReplayRequestBody, ReplayRecorder, requestHeaders, waitForReplayDelay, } from "./LoopbackReplayRecorder.js";
+const recordHttpResponse = (recorder, request, data, outcome) => recorder.record({
+    at_ms: recorder.atMs(),
+    protocol: "http",
+    direction: "response",
+    method: request.method,
+    path: request.path,
+    data,
+    outcome,
+});
+const handleMachineHttp = async (recorder, request) => {
+    const machine = recorder.machine;
+    if (machine === undefined)
+        return;
+    const decision = recorder.dispatchMachine({
+        protocol: "http",
+        connection: "not_applicable",
+        at_ms: request.rawAtMs,
+        recorded_at_ms: request.recordedAtMs,
+        method: request.method,
+        path: request.path,
+        headers: requestHeaders(request.request),
+        body: request.body,
+    });
+    recordMachineEvent(recorder, {
+        at_ms: request.recordedAtMs,
+        protocol: "http",
+        direction: "request",
+        method: request.method,
+        path: request.path,
+        data: request.body,
+    }, decision);
+    if (decision.outcome !== "matched") {
+        request.response.statusCode = decision.outcome === "unmatched" ? 404 : 409;
+        request.response.end();
+        return;
     }
-    atMs() {
-        return (Math.floor((Date.now() - this.started) /
-            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
+    for (const action of decision.actions) {
+        if (action.type === "delay")
+            await waitForReplayDelay(action.duration_ms);
+        else if (action.type === "disconnect") {
+            request.response.destroy();
+            recordHttpResponse(recorder, request, "", "disconnected");
+            return;
+        }
+        else if (action.type === "http_response") {
+            request.response.statusCode = action.status;
+            for (const [name, value] of Object.entries(action.headers))
+                request.response.setHeader(name, value);
+            request.response.end(action.body);
+            recordHttpResponse(recorder, request, machine.redact(action.body), "matched");
+        }
     }
-    record(event) {
-        if (this.events.length < this.scenario.limits.protocol_events)
-            this.events.push({ sequence: this.events.length, ...event });
-        else
-            this.truncated = true;
+};
+const handleStaticHttp = async (recorder, request, calls) => {
+    const index = recorder.scenario.replay.http.findIndex((route) => route.method !== request.method || route.path !== request.path
+        ? false
+        : (route.request_body === undefined ||
+            route.request_body === request.body) &&
+            Object.entries(route.request_headers).every(([name, value]) => request.request.headers[name.toLowerCase()] === value));
+    const route = recorder.scenario.replay.http[index];
+    const used = index < 0 ? 0 : (calls.get(index) ?? 0);
+    const outcome = route === undefined
+        ? "unmatched"
+        : used >= route.max_calls
+            ? "script_exhausted"
+            : "matched";
+    recorder.record({
+        at_ms: recorder.atMs(),
+        protocol: "http",
+        direction: "request",
+        method: request.method,
+        path: request.path,
+        data: request.body.length === 0 ? "" : "<redacted-request-body>",
+        outcome,
+    });
+    if (route === undefined || outcome === "script_exhausted") {
+        request.response.statusCode = route === undefined ? 404 : 409;
+        request.response.end();
+        return;
     }
-}
-const readRequestBody = async (request, limit) => {
-    const chunks = [];
-    let bytes = 0;
-    for await (const chunk of request) {
-        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        bytes += value.byteLength;
-        if (bytes > limit)
-            return undefined;
-        chunks.push(value);
+    calls.set(index, used + 1);
+    if (route.delay_ms > 0)
+        await waitForReplayDelay(route.delay_ms);
+    if (route.disconnect) {
+        request.response.destroy();
+        recordHttpResponse(recorder, request, "", "disconnected");
+        return;
     }
-    return Buffer.concat(chunks).toString("utf8");
+    request.response.statusCode = route.status;
+    for (const [name, value] of Object.entries(route.response_headers))
+        request.response.setHeader(name, value);
+    request.response.end(route.body);
+    recordHttpResponse(recorder, request, route.body, "matched");
 };
-const createHttpHandler = (recorder) => {
-    const calls = new Map();
-    return async (request, response) => {
-        const method = request.method ?? "GET";
-        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
-        const body = await readRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
-        if (body === undefined) {
-            recorder.truncated = true;
-            response.statusCode = 413;
-            response.end();
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "http",
-                direction: "request",
-                method,
-                path,
-                data: "<body-over-limit>",
-                outcome: "unmatched",
-            });
-            return;
-        }
-        const index = recorder.scenario.replay.http.findIndex((route) => {
-            if (route.method !== method || route.path !== path)
-                return false;
-            if (route.request_body !== undefined && route.request_body !== body)
-                return false;
-            return Object.entries(route.request_headers).every(([name, value]) => request.headers[name.toLowerCase()] === value);
-        });
-        const route = recorder.scenario.replay.http[index];
-        const used = index < 0 ? 0 : (calls.get(index) ?? 0);
-        const outcome = route === undefined
-            ? "unmatched"
-            : used >= route.max_calls
-                ? "script_exhausted"
-                : "matched";
+const handleHttpRequest = async (recorder, request, response, calls) => {
+    const body = await readReplayRequestBody(request, recorder.scenario.limits.protocol_body_bytes);
+    const method = request.method ?? "GET";
+    const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+    if (body === undefined) {
+        recorder.truncated = true;
+        response.statusCode = 413;
+        response.end();
         recorder.record({
             at_ms: recorder.atMs(),
             protocol: "http",
             direction: "request",
             method,
             path,
-            data: body.length === 0 ? "" : "<redacted-request-body>",
-            outcome,
+            data: "<body-over-limit>",
+            outcome: "unmatched",
         });
-        if (route === undefined || outcome === "script_exhausted") {
-            response.statusCode = route === undefined ? 404 : 409;
-            response.end();
-            return;
-        }
-        calls.set(index, used + 1);
-        if (route.delay_ms > 0)
-            await new Promise((resolveDelay) => setTimeout(resolveDelay, route.delay_ms));
-        if (route.disconnect) {
-            response.destroy();
-            recorder.record({
-                at_ms: recorder.atMs(),
-                protocol: "http",
-                direction: "response",
-                method,
-                path,
-                data: "",
-                outcome: "disconnected",
-            });
-            return;
-        }
-        response.statusCode = route.status;
-        for (const [name, value] of Object.entries(route.response_headers))
-            response.setHeader(name, value);
-        response.end(route.body);
-        recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "http",
-            direction: "response",
-            method,
-            path,
-            data: route.body,
-            outcome: "matched",
+        return;
+    }
+    const replayRequest = {
+        request,
+        response,
+        method,
+        path,
+        body,
+        rawAtMs: recorder.rawAtMs(),
+        recordedAtMs: recorder.atMs(),
+    };
+    await (recorder.machine === undefined
+        ? handleStaticHttp(recorder, replayRequest, calls)
+        : recorder.enqueueMachine(() => handleMachineHttp(recorder, replayRequest)));
+};
+const createHttpHandler = (recorder) => {
+    const calls = new Map();
+    return (request, response) => {
+        void handleHttpRequest(recorder, request, response, calls).catch(() => {
+            recorder.truncated = true;
+            if (response.headersSent)
+                response.destroy();
+            else {
+                response.statusCode = 500;
+                response.end();
+            }
         });
     };
 };
@@ -161,6 +192,119 @@ const sendWebSocketScript = async (client, connection, recorder) => {
         });
     }
 };
+const runWebSocketActions = async (client, recorder, decision, path) => {
+    for (const action of decision.actions) {
+        if (action.type === "delay") {
+            await waitForReplayDelay(action.duration_ms);
+            continue;
+        }
+        if (action.type === "disconnect") {
+            client.close();
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "websocket",
+                direction: "sent",
+                method: null,
+                path,
+                data: "",
+                outcome: "disconnected",
+            });
+            return;
+        }
+        if (action.type === "websocket_send" && client.readyState === 1) {
+            client.send(action.data);
+            recorder.record({
+                at_ms: recorder.atMs(),
+                protocol: "websocket",
+                direction: "sent",
+                method: null,
+                path,
+                data: recorder.machine?.redact(action.data) ?? action.data,
+                outcome: "matched",
+            });
+        }
+    }
+};
+const handleStaticWebSocket = (client, recorder, connection, path) => {
+    client.on("message", (value) => recorder.record({
+        at_ms: recorder.atMs(),
+        protocol: "websocket",
+        direction: "received",
+        method: null,
+        path,
+        data: value.toString(),
+        outcome: "matched",
+    }));
+    void sendWebSocketScript(client, connection, recorder);
+};
+const handleMachineWebSocket = (options) => {
+    const { client, request, recorder, connection, path } = options;
+    const machine = recorder.machine;
+    if (machine === undefined)
+        return;
+    void recorder
+        .enqueueMachine(async () => {
+        const connectedAt = recorder.atMs();
+        const connectionDecision = recorder.dispatchMachine({
+            protocol: "websocket_connect",
+            connection: connection === 1 ? "initial" : "reconnect",
+            at_ms: recorder.rawAtMs(),
+            recorded_at_ms: connectedAt,
+            method: null,
+            path,
+            headers: requestHeaders(request),
+            body: "",
+        });
+        recordMachineEvent(recorder, {
+            at_ms: connectedAt,
+            protocol: "websocket",
+            direction: "received",
+            method: null,
+            path,
+            data: "",
+        }, connectionDecision);
+        if (connectionDecision.outcome === "matched")
+            await runWebSocketActions(client, recorder, connectionDecision, path);
+        else
+            client.close();
+    })
+        .catch(() => {
+        recorder.truncated = true;
+        client.terminate();
+    });
+    client.on("message", (value) => {
+        const body = value.toString();
+        const rawAtMs = recorder.rawAtMs();
+        const recordedAtMs = recorder.atMs();
+        void recorder
+            .enqueueMachine(async () => {
+            const decision = recorder.dispatchMachine({
+                protocol: "websocket_message",
+                connection: connection === 1 ? "initial" : "reconnect",
+                at_ms: rawAtMs,
+                recorded_at_ms: recordedAtMs,
+                method: null,
+                path,
+                headers: {},
+                body,
+            });
+            recordMachineEvent(recorder, {
+                at_ms: recordedAtMs,
+                protocol: "websocket",
+                direction: "received",
+                method: null,
+                path,
+                data: body,
+            }, decision);
+            if (decision.outcome === "matched")
+                await runWebSocketActions(client, recorder, decision, path);
+        })
+            .catch(() => {
+            recorder.truncated = true;
+            client.terminate();
+        });
+    });
+};
 const createWebSocketReplay = (server, recorder) => {
     let connections = 0;
     const websocket = new WebSocketServer({
@@ -169,13 +313,14 @@ const createWebSocketReplay = (server, recorder) => {
         clientTracking: true,
     });
     server.on("upgrade", (request, socket, head) => {
-        if (new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
+        if (recorder.machine === undefined &&
+            new URL(request.url ?? "/", "http://127.0.0.1").pathname !== "/ws") {
             socket.destroy();
             return;
         }
         websocket.handleUpgrade(request, socket, head, (client) => websocket.emit("connection", client, request));
     });
-    websocket.on("connection", (client) => {
+    websocket.on("connection", (client, request) => {
         connections += 1;
         if (connections > recorder.scenario.limits.connections) {
             recorder.truncated = true;
@@ -183,60 +328,59 @@ const createWebSocketReplay = (server, recorder) => {
             return;
         }
         client.on("error", () => undefined);
-        client.on("message", (value) => recorder.record({
-            at_ms: recorder.atMs(),
-            protocol: "websocket",
-            direction: "received",
-            method: null,
-            path: "/ws",
-            data: value.toString(),
-            outcome: "matched",
-        }));
-        void sendWebSocketScript(client, connections, recorder);
+        const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+        if (recorder.machine === undefined)
+            handleStaticWebSocket(client, recorder, connections, path);
+        else
+            handleMachineWebSocket({
+                client,
+                request,
+                recorder,
+                connection: connections,
+                path,
+            });
     });
     return websocket;
 };
-const listen = async (server) => {
-    await new Promise((resolveListen, rejectListen) => {
-        server.once("error", rejectListen);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", rejectListen);
-            resolveListen();
-        });
-    });
-    const address = server.address();
-    if (address === null || typeof address === "string")
-        throw new Error("loopback replay did not acquire a TCP port");
-    return address.port;
-};
-const closeServer = (server) => new Promise((resolveClose, rejectClose) => {
-    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
-});
 /** Start bounded HTTP and WebSocket replay endpoints on IPv4 loopback only. */
-export const startLoopbackReplay = async (scenario) => {
-    const recorder = new ReplayRecorder(scenario);
+export const startLoopbackReplay = async (scenario, recordEvent = () => undefined) => {
+    const recorder = new ReplayRecorder(scenario, recordEvent);
     const server = createServer(createHttpHandler(recorder));
     const websocket = createWebSocketReplay(server, recorder);
+    let closePromise;
     let port;
     try {
-        port = await listen(server);
+        port = await listenOnLoopback(server);
     }
     catch (cause) {
-        await closeServer(server).catch(() => undefined);
+        await closeReplayServer(server).catch(() => undefined);
         throw cause;
     }
     return {
         httpUrl: `http://127.0.0.1:${String(port)}`,
         websocketUrl: `ws://127.0.0.1:${String(port)}/ws`,
-        events: recorder.events,
+        get events() {
+            return recorder.events.map((event) => ({ ...event }));
+        },
+        get transitions() {
+            return recorder.transitions.map((transition) => ({
+                ...transition,
+                sensitive_aliases: [...transition.sensitive_aliases],
+            }));
+        },
         get truncated() {
             return recorder.truncated;
         },
         async close() {
-            for (const client of websocket.clients)
-                client.terminate();
-            await new Promise((resolveClose) => websocket.close(() => resolveClose()));
-            await closeServer(server);
+            closePromise ??= (async () => {
+                recorder.stopMachineAdmission();
+                for (const client of websocket.clients)
+                    client.terminate();
+                await new Promise((resolveClose) => websocket.close(() => resolveClose()));
+                await closeReplayServer(server);
+                await recorder.drainMachine();
+            })();
+            await closePromise;
         },
     };
 };

package/dist/application/LoopbackReplayRecorder.js

@@ -0,0 +1,101 @@
+import { ReplayMachineRuntime, } from "../domain/replayMachineRuntime.js";
+/** Bounded protocol and replay-machine observations for one process run. */
+export class ReplayRecorder {
+    scenario;
+    recordEvent;
+    events = [];
+    started = Date.now();
+    machine;
+    #machineQueue = Promise.resolve();
+    #machineAdmissionOpen = true;
+    truncated = false;
+    constructor(scenario, recordEvent = () => undefined) {
+        this.scenario = scenario;
+        this.recordEvent = recordEvent;
+        this.machine =
+            scenario.replay.machine === null
+                ? undefined
+                : new ReplayMachineRuntime(scenario.replay.machine);
+    }
+    get transitions() {
+        return this.machine?.timeline ?? [];
+    }
+    atMs() {
+        return (Math.floor((Date.now() - this.started) /
+            this.scenario.normalization.time_bucket_ms) * this.scenario.normalization.time_bucket_ms);
+    }
+    rawAtMs() {
+        return Date.now() - this.started;
+    }
+    enqueueMachine(operation) {
+        if (!this.#machineAdmissionOpen)
+            return Promise.reject(new Error("replay machine is closing"));
+        const result = this.#machineQueue.then(operation);
+        this.#machineQueue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    stopMachineAdmission() {
+        this.#machineAdmissionOpen = false;
+    }
+    async drainMachine() {
+        await this.#machineQueue;
+    }
+    dispatchMachine(event) {
+        if (this.machine === undefined)
+            throw new Error("replay machine is not configured");
+        return this.machine.dispatch(event);
+    }
+    recordTransition(decision) {
+        if (decision.transition !== null)
+            this.recordEvent("replay_transitions", decision.transition.sequence);
+    }
+    record(event) {
+        if (this.events.length >= this.scenario.limits.protocol_events) {
+            this.truncated = true;
+            return;
+        }
+        const sequence = this.events.length;
+        this.events.push({ sequence, ...event });
+        this.recordEvent("protocol_events", sequence);
+    }
+}
+export const requestHeaders = (request) => Object.fromEntries(Object.entries(request.headers).flatMap(([name, value]) => value === undefined
+    ? []
+    : [[name, Array.isArray(value) ? value.join(", ") : value]]));
+export const readReplayRequestBody = async (request, limit) => {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += value.byteLength;
+        if (bytes > limit)
+            return undefined;
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+};
+export const recordMachineEvent = (recorder, event, decision) => {
+    recorder.record({
+        ...event,
+        data: recorder.machine?.redact(event.data) ?? event.data,
+        outcome: decision.outcome,
+    });
+    recorder.recordTransition(decision);
+};
+export const waitForReplayDelay = (durationMs) => new Promise((resolveDelay) => setTimeout(resolveDelay, durationMs));
+export const listenOnLoopback = async (server) => {
+    await new Promise((resolveListen, rejectListen) => {
+        server.once("error", rejectListen);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", rejectListen);
+            resolveListen();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string")
+        throw new Error("loopback replay did not acquire a TCP port");
+    return address.port;
+};
+export const closeReplayServer = (server) => new Promise((resolveClose, rejectClose) => {
+    server.close((error) => error === undefined ? resolveClose() : rejectClose(error));
+});

package/dist/application/PermissionAuthority.js

@@ -74,13 +74,15 @@ const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
 export class PermissionAuthority {
     policy;
     configuredAuthority;
-    constructor(policy, configuredAuthority) {
+    outsideCeilingRestartRequired;
+    constructor(policy, configuredAuthority, outsideCeilingRestartRequired = false) {
         this.policy = policy;
         this.configuredAuthority = configuredAuthority;
+        this.outsideCeilingRestartRequired = outsideCeilingRestartRequired;
     }
     /** Create a connection-owned overlay for once and session grants. */
     createConnectionAuthority() {
-        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this);
+        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this, true);
     }
     /** Canonicalize and authorize one exact operation before its side effect. */
     async authorize(request, access, options = {}) {
@@ -165,7 +167,9 @@ export class PermissionAuthority {
         const denied = evaluatePermission(effective, request);
         if (denied.allowed)
             return ok({ decision: denied, owner: this });
-        return err(new PermissionRequiredError(request, denied.missing, ceilingFor(effective, request.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+        const outsideAdministratorCeiling = denied.reason === "outside_administrator_ceiling";
+        return err(new PermissionRequiredError(request, denied.missing, ceilingFor(effective, request.capability), !outsideAdministratorCeiling && (options.elicitationSupported ?? false), options.restartRequired ??
+            (outsideAdministratorCeiling && this.outsideCeilingRestartRequired)));
     }
     /** Atomically replace optional persisted project grants. */
     async replaceProjectGrants(grants) {