@botlearn-course/daemon 0.0.2 → 0.0.4

package/dist/agent-service-session.js

@@ -0,0 +1,796 @@
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureDaemonHome } from "./auth-store.js";
+import { AGENT_SERVICE_WS_SUBPROTOCOL, createSandboxFrame, parseSandboxFrame, } from "./agent-service-ws-protocol.js";
+import { log as defaultLog } from "./log.js";
+import { assertNoInjectedCredentials, redactSecretString } from "./redaction.js";
+import { RunDispatcher, } from "./run-dispatcher.js";
+import { ensureRuntimeSessionWorkspace } from "./workspace.js";
+import { WebSocketClient, } from "./websocket-client.js";
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
+const MAX_SPOOL_FRAMES = 1024;
+const MAX_SPOOL_BYTES = 8 * 1024 * 1024;
+class SessionClosedError extends Error {
+    code;
+    reason;
+    constructor(code, reason) {
+        super(`sandbox WebSocket closed (${code}): ${reason}`);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+class SocketInbox {
+    queued = [];
+    waiting = [];
+    constructor(socket) {
+        socket.on("message", (data, isBinary) => {
+            this.push(isBinary ? new Error("binary WebSocket frames are not supported") : data.toString());
+        });
+        socket.on("error", (error) => this.push(error));
+        socket.on("close", (code, reason) => {
+            this.push(new SessionClosedError(code, reason.toString() || "closed"));
+        });
+    }
+    next() {
+        const value = this.queued.shift();
+        if (value !== undefined) {
+            return value instanceof Error ? Promise.reject(value) : Promise.resolve(value);
+        }
+        return new Promise((resolve, reject) => this.waiting.push({ resolve, reject }));
+    }
+    push(value) {
+        const waiter = this.waiting.shift();
+        if (!waiter) {
+            this.queued.push(value);
+            return;
+        }
+        if (value instanceof Error)
+            waiter.reject(value);
+        else
+            waiter.resolve(value);
+    }
+}
+function waitForOpen(socket) {
+    return new Promise((resolve, reject) => {
+        const onOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onUnexpected = (_request, response) => {
+            cleanup();
+            reject(new Error(`sandbox WebSocket upgrade failed: ${response.statusCode ?? "unknown"}`));
+        };
+        const cleanup = () => {
+            socket.off("open", onOpen);
+            socket.off("error", onError);
+            socket.off("unexpected-response", onUnexpected);
+        };
+        socket.on("open", onOpen);
+        socket.on("error", onError);
+        socket.on("unexpected-response", onUnexpected);
+    });
+}
+function sessionStatePath(sessionId) {
+    const root = path.join(ensureDaemonHome(), "agent-service-sessions", sessionId);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(root, 0o700);
+    }
+    catch {
+        // Windows best effort.
+    }
+    return path.join(root, "state.json");
+}
+function loadState(sessionId, token) {
+    const file = sessionStatePath(sessionId);
+    if (existsSync(file)) {
+        try {
+            const value = JSON.parse(readFileSync(file, "utf8"));
+            return {
+                sessionGeneration: Number(value.sessionGeneration ?? 0),
+                nextOutboundSeq: Number(value.nextOutboundSeq ?? 0),
+                reconnectToken: typeof value.reconnectToken === "string" ? value.reconnectToken : token,
+                completedCommands: Array.isArray(value.completedCommands)
+                    ? value.completedCommands.filter((item) => typeof item === "string")
+                    : [],
+                acceptedCommands: value.acceptedCommands &&
+                    typeof value.acceptedCommands === "object" &&
+                    !Array.isArray(value.acceptedCommands)
+                    ? value.acceptedCommands
+                    : {},
+                runtime: {
+                    runtimeId: typeof value.runtime?.runtimeId === "string" ? value.runtime.runtimeId : null,
+                    nativeSessionId: typeof value.runtime?.nativeSessionId === "string"
+                        ? value.runtime.nativeSessionId
+                        : null,
+                    contextRevision: Number(value.runtime?.contextRevision ?? 0),
+                },
+                spool: Array.isArray(value.spool) ? value.spool : [],
+            };
+        }
+        catch {
+            // Corrupt state is reconstructed from the server desired state.
+        }
+    }
+    return {
+        sessionGeneration: 0,
+        nextOutboundSeq: 0,
+        reconnectToken: token,
+        completedCommands: [],
+        acceptedCommands: {},
+        runtime: {
+            runtimeId: null,
+            nativeSessionId: null,
+            contextRevision: 0,
+        },
+        spool: [],
+    };
+}
+function saveState(sessionId, state) {
+    const file = sessionStatePath(sessionId);
+    const tmp = `${file}.tmp-${process.pid}`;
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeFileSync(fd, JSON.stringify(state), { encoding: "utf8" });
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, file);
+    try {
+        const directoryFd = openSync(path.dirname(file), "r");
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+    }
+    catch {
+        // Directory fsync is unavailable on Windows; the file itself is still flushed.
+    }
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows best effort.
+    }
+}
+/** Long-running daemon client for one persistent managed sandbox session. */
+export class AgentServiceSessionClient {
+    options;
+    log;
+    random;
+    sleep;
+    state;
+    dispatcher;
+    attempts = new Map();
+    runtimeProfiles = new Map();
+    pendingAcks = new Map();
+    pendingFilePrepares = new Map();
+    pendingFileCommits = new Map();
+    fileGrants = new Map();
+    inflightCommands = new Set();
+    socket = null;
+    sessionGeneration = 0;
+    connectionEpoch = 0;
+    inboundSeq = 0;
+    heartbeatMs = 15_000;
+    staleMs = 45_000;
+    stopped = false;
+    permanentFailure = false;
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? defaultLog;
+        this.random = options.random ?? Math.random;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.state = loadState(options.sessionId, options.sessionToken);
+        this.dispatcher = new RunDispatcher(this, options.runtimes, {
+            persistentSession: this,
+        });
+    }
+    prepareTurn(payload) {
+        const activation = this.runtimeActivation(payload);
+        if (activation.contextRevision !== this.state.runtime.contextRevision) {
+            throw new Error(`runtime context revision mismatch: accepted ${this.state.runtime.contextRevision}, ` +
+                `received ${activation.contextRevision}`);
+        }
+        const prepared = ensureRuntimeSessionWorkspace(this.options.sessionId, this.sessionGeneration, payload.agent_run_id);
+        return {
+            workspaceDir: prepared.workspaceDir,
+            transcriptFile: prepared.transcriptFile,
+            nativeSessionId: this.state.runtime.nativeSessionId,
+            contextRevision: activation.contextRevision,
+            ...(this.options.runtimeEnv
+                ? { runtimeEnv: { ...process.env, ...this.options.runtimeEnv } }
+                : {}),
+        };
+    }
+    persistNativeSession(sessionId) {
+        this.state.runtime.nativeSessionId = sessionId.trim() || null;
+        this.persist();
+    }
+    async run() {
+        let failures = 0;
+        let authFailures = 0;
+        while (!this.stopped && !this.permanentFailure) {
+            try {
+                await this.connectOnce();
+                failures = 0;
+            }
+            catch (error) {
+                const close = error instanceof SessionClosedError ? error : null;
+                if (close?.code === 4403 || close?.code === 4410) {
+                    this.permanentFailure = true;
+                    break;
+                }
+                if (close?.code === 4401) {
+                    authFailures += 1;
+                    if (authFailures >= 3) {
+                        this.permanentFailure = true;
+                        break;
+                    }
+                }
+                else {
+                    authFailures = 0;
+                }
+                if (this.stopped)
+                    break;
+                const base = RECONNECT_DELAYS_MS[Math.min(failures, RECONNECT_DELAYS_MS.length - 1)];
+                failures += 1;
+                const delay = Math.round(base * (1 + this.random() * 0.25));
+                this.log.warn("Agent Service sandbox WebSocket disconnected; reconnecting", {
+                    runtimeSessionId: this.options.sessionId,
+                    delayMs: delay,
+                    error: error instanceof Error ? redactSecretString(error.message) : String(error),
+                });
+                await this.sleep(delay);
+            }
+        }
+        if (this.permanentFailure) {
+            throw new Error("Agent Service sandbox session stopped after a permanent protocol failure");
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.dispatcher.cancelAll();
+        this.socket?.close(1000, "daemon_stopping");
+    }
+    async postEvent(agentRunId, event) {
+        const attempt = this.attempts.get(agentRunId);
+        if (!attempt)
+            throw new Error("Agent Service session event has no active turn attempt");
+        if (!this.sessionGeneration || !this.connectionEpoch) {
+            throw new Error("Agent Service session is not authenticated");
+        }
+        const frame = createSandboxFrame({
+            type: "turn.event",
+            sessionId: this.options.sessionId,
+            sessionGeneration: this.sessionGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            agentRunId,
+            workerAttempt: attempt,
+            payload: event,
+        });
+        this.state.spool.push(frame);
+        try {
+            this.enforceSpoolLimit();
+        }
+        catch (error) {
+            this.state.spool.pop();
+            this.persist();
+            throw error;
+        }
+        this.persist();
+        const ack = new Promise((resolve, reject) => {
+            this.pendingAcks.set(frame.frame_id, { resolve, reject });
+        });
+        await this.sendFrame(frame);
+        await ack;
+    }
+    async postFile(agentRunId, file) {
+        const attempt = this.attempts.get(agentRunId);
+        if (!attempt)
+            throw new Error("Agent Service session file has no active turn attempt");
+        if (!file.sha256 || !Number.isInteger(file.size_bytes) || (file.size_bytes ?? -1) < 0) {
+            throw new Error("Agent Service session file requires size_bytes and sha256");
+        }
+        const frame = createSandboxFrame({
+            type: "turn.file.prepare",
+            sessionId: this.options.sessionId,
+            sessionGeneration: this.sessionGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            agentRunId,
+            workerAttempt: attempt,
+            payload: file,
+        });
+        const prepared = new Promise((resolve, reject) => {
+            this.pendingFilePrepares.set(frame.frame_id, { resolve, reject });
+        });
+        await this.sendFrame(frame);
+        const grant = await prepared;
+        this.fileGrants.set(`${agentRunId}:${grant.record.id}`, grant);
+        return grant.record;
+    }
+    async uploadFileContent(agentRunId, fileId, absPath, mimeType) {
+        const attempt = this.attempts.get(agentRunId);
+        if (!attempt)
+            throw new Error("Agent Service session file has no active turn attempt");
+        const key = `${agentRunId}:${fileId}`;
+        const grant = this.fileGrants.get(key);
+        if (!grant)
+            throw new Error("Agent Service session file has no upload grant");
+        const data = await readFile(absPath);
+        assertNoInjectedCredentials(data, [this.state.reconnectToken, grant.uploadGrant]);
+        const response = await fetch(grant.uploadUrl, {
+            method: "PUT",
+            headers: {
+                authorization: `Bearer ${grant.uploadGrant}`,
+                "content-type": mimeType ?? grant.record.mime_type ?? "application/octet-stream",
+            },
+            body: data,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new Error(`Agent Service file upload failed (${response.status}): ${redactSecretString(text.slice(0, 500))}`);
+        }
+        const frame = createSandboxFrame({
+            type: "turn.file.committed",
+            sessionId: this.options.sessionId,
+            sessionGeneration: this.sessionGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            agentRunId,
+            workerAttempt: attempt,
+            payload: { file_id: fileId, sha256: grant.record.sha256 },
+        });
+        const committed = new Promise((resolve, reject) => {
+            this.pendingFileCommits.set(frame.frame_id, { resolve, reject });
+        });
+        await this.sendFrame(frame);
+        try {
+            return await committed;
+        }
+        finally {
+            this.fileGrants.delete(key);
+        }
+    }
+    async getRunRuntimeProfile(agentRunId) {
+        const profile = this.runtimeProfiles.get(agentRunId);
+        if (!profile)
+            throw new Error("Agent Service session runtime profile is unavailable");
+        return profile;
+    }
+    async connectOnce() {
+        const socket = new WebSocketClient(this.options.wsUrl, AGENT_SERVICE_WS_SUBPROTOCOL, {
+            headers: { Authorization: `Bearer ${this.state.reconnectToken}` },
+            maxPayload: 262_144,
+        });
+        // Attach message/close listeners before awaiting open; the server may send
+        // session.hello immediately after the upgrade completes.
+        const inbox = new SocketInbox(socket);
+        await waitForOpen(socket);
+        if (socket.protocol !== AGENT_SERVICE_WS_SUBPROTOCOL) {
+            socket.close(4410, "protocol_incompatible");
+            throw new SessionClosedError(4410, "protocol_incompatible");
+        }
+        this.socket = socket;
+        let heartbeat = null;
+        let staleCheck = null;
+        let lastServerFrameAt = Date.now();
+        try {
+            while (!this.stopped) {
+                const raw = await inbox.next();
+                lastServerFrameAt = Date.now();
+                const frame = parseSandboxFrame(raw);
+                if (frame.type === "session.hello") {
+                    await this.handleHello(frame);
+                    if (heartbeat === null) {
+                        heartbeat = setInterval(() => {
+                            void this.sendHeartbeat().catch((error) => {
+                                this.log.warn("Agent Service session heartbeat failed", {
+                                    runtimeSessionId: this.options.sessionId,
+                                    error: error instanceof Error ? redactSecretString(error.message) : String(error),
+                                });
+                            });
+                        }, this.heartbeatMs);
+                        if (typeof heartbeat.unref === "function")
+                            heartbeat.unref();
+                        staleCheck = setInterval(() => {
+                            if (Date.now() - lastServerFrameAt >= this.staleMs &&
+                                socket.readyState === WebSocketClient.OPEN) {
+                                this.log.warn("Agent Service session server frame timeout; reconnecting", {
+                                    runtimeSessionId: this.options.sessionId,
+                                    staleMs: this.staleMs,
+                                });
+                                socket.close(4000, "server_stale");
+                            }
+                        }, Math.max(1_000, Math.min(this.heartbeatMs, Math.floor(this.staleMs / 3))));
+                        if (typeof staleCheck.unref === "function")
+                            staleCheck.unref();
+                    }
+                    continue;
+                }
+                this.assertServerFrame(frame);
+                this.inboundSeq = frame.seq;
+                await this.handleServerFrame(frame);
+            }
+        }
+        finally {
+            if (heartbeat !== null)
+                clearInterval(heartbeat);
+            if (staleCheck !== null)
+                clearInterval(staleCheck);
+            this.rejectPendingFiles(new Error("Agent Service file transport disconnected"));
+            if (this.socket === socket)
+                this.socket = null;
+            if (socket.readyState === WebSocketClient.OPEN)
+                socket.close(1000, "reconnecting");
+        }
+    }
+    async handleHello(frame) {
+        if (frame.session_id !== this.options.sessionId) {
+            throw new SessionClosedError(4403, "session_mismatch");
+        }
+        if (this.sessionGeneration && frame.session_generation < this.sessionGeneration) {
+            throw new SessionClosedError(4409, "stale_generation");
+        }
+        if (frame.session_generation !== this.state.sessionGeneration) {
+            this.rejectPending(new Error("Agent Service session generation changed"));
+            this.state.spool = [];
+            this.state.completedCommands = [];
+            this.state.acceptedCommands = {};
+            this.state.runtime = {
+                runtimeId: null,
+                nativeSessionId: null,
+                contextRevision: 0,
+            };
+            this.state.nextOutboundSeq = 0;
+            this.state.sessionGeneration = frame.session_generation;
+        }
+        this.sessionGeneration = frame.session_generation;
+        this.connectionEpoch = frame.connection_epoch;
+        this.inboundSeq = frame.seq;
+        const heartbeatSeconds = Number(frame.payload.heartbeat_seconds ?? 15);
+        this.heartbeatMs = Math.max(1_000, Math.min(60_000, heartbeatSeconds * 1000));
+        const staleSeconds = Number(frame.payload.stale_seconds ?? 45);
+        // The server owns this deadline. Keep only a defensive protocol floor/ceiling rather
+        // than stretching it relative to the heartbeat and silently ignoring its contract.
+        this.staleMs = Math.min(300_000, Math.max(1_000, staleSeconds * 1000));
+        this.persist();
+        await this.sendControlFrame("session.ready", {
+            daemon_version: this.options.daemonVersion,
+            protocol_versions: ["botlearn-agent-sandbox-ws/0.1"],
+            local_event_cursor: this.state.spool.at(-1)?.seq ?? 0,
+            spool_frames: this.state.spool.length,
+            spool_bytes: this.spoolBytes(),
+            active_run_id: this.dispatcher.activeCount > 0 ? "active" : null,
+        });
+    }
+    assertServerFrame(frame) {
+        if (frame.session_id !== this.options.sessionId ||
+            frame.session_generation !== this.sessionGeneration ||
+            frame.connection_epoch !== this.connectionEpoch) {
+            throw new SessionClosedError(4409, "connection_fenced");
+        }
+        if (frame.seq !== this.inboundSeq + 1)
+            throw new Error("server frame sequence gap");
+    }
+    async handleServerFrame(frame) {
+        switch (frame.type) {
+            case "session.sync":
+                await this.replaySpool();
+                await this.applyDesiredState(frame);
+                return;
+            case "event.ack":
+                this.ackEventOrFile(frame);
+                return;
+            case "turn.file.upload_grant":
+                this.acceptFileGrant(frame);
+                return;
+            case "ping":
+                await this.sendControlFrame("pong", { ping_frame_id: frame.frame_id });
+                return;
+            case "auth.rotate": {
+                const token = frame.payload.reconnect_token;
+                if (typeof token !== "string" || !token)
+                    throw new Error("invalid reconnect token");
+                this.state.reconnectToken = token;
+                this.persist();
+                await this.sendCommandAck(frame);
+                return;
+            }
+            case "session.shutdown":
+                this.stop();
+                return;
+            case "turn.cancel":
+                if (frame.agent_run_id)
+                    this.dispatcher.cancel(frame.agent_run_id);
+                await this.sendCommandAck(frame);
+                return;
+            case "session.drain":
+                await this.sendCommandAck(frame);
+                if (await this.dispatcher.drain(10_000)) {
+                    await this.sendControlFrame("session.drained", {});
+                }
+                return;
+            case "protocol.error":
+                throw new Error(`server protocol error: ${String(frame.payload.code ?? "unknown")}`);
+            default:
+                throw new Error(`unexpected server frame: ${frame.type}`);
+        }
+    }
+    async applyDesiredState(frame) {
+        const state = frame.payload.state;
+        const runId = typeof frame.payload.active_agent_run_id === "string"
+            ? frame.payload.active_agent_run_id
+            : null;
+        const attempt = Number(frame.payload.worker_attempt ?? 0);
+        if (state === "idle")
+            return;
+        if (state === "shutdown") {
+            this.stop();
+            return;
+        }
+        if (state === "drain") {
+            if (await this.dispatcher.drain(10_000)) {
+                await this.sendControlFrame("session.drained", {});
+            }
+            return;
+        }
+        if (!runId || !Number.isInteger(attempt) || attempt < 1) {
+            throw new Error("desired turn is missing fencing fields");
+        }
+        if (state === "cancel") {
+            this.dispatcher.cancel(runId);
+            await this.sendCommandAck(frame);
+            return;
+        }
+        if (state !== "run" || !frame.payload.run || typeof frame.payload.run !== "object") {
+            throw new Error("invalid desired session state");
+        }
+        const commandId = `run:${runId}:${attempt}`;
+        this.attempts.set(runId, attempt);
+        if (this.state.completedCommands.includes(commandId) ||
+            this.inflightCommands.has(commandId)) {
+            await this.sendCommandAck(frame, commandId);
+            return;
+        }
+        const payload = frame.payload.run;
+        const activation = this.runtimeActivation(payload);
+        const accepted = this.state.acceptedCommands[commandId];
+        if (accepted && !this.inflightCommands.has(commandId)) {
+            await this.sendCommandAck(frame, commandId);
+            void this.reconcileInterruptedCommand(commandId, accepted);
+            return;
+        }
+        if (!accepted) {
+            if (this.state.runtime.runtimeId !== null &&
+                this.state.runtime.runtimeId !== activation.runtimeId) {
+                throw new Error("runtime changed inside one persistent session generation");
+            }
+            if (activation.contextRevision !== this.state.runtime.contextRevision + 1) {
+                throw new Error(`runtime context revision gap: expected ${this.state.runtime.contextRevision + 1}, ` +
+                    `received ${activation.contextRevision}`);
+            }
+            this.state.runtime.runtimeId = activation.runtimeId;
+            this.state.runtime.contextRevision = activation.contextRevision;
+            this.state.acceptedCommands[commandId] = {
+                agentRunId: runId,
+                workerAttempt: attempt,
+                contextRevision: activation.contextRevision,
+                acceptedAt: new Date().toISOString(),
+            };
+            this.persist();
+        }
+        const embeddedProfile = payload.context.runtimeProfile;
+        if (embeddedProfile && typeof embeddedProfile === "object") {
+            this.runtimeProfiles.set(runId, embeddedProfile);
+        }
+        this.inflightCommands.add(commandId);
+        await this.sendCommandAck(frame, commandId);
+        void this.dispatcher.dispatch(payload)
+            .then(() => {
+            this.state.completedCommands.push(commandId);
+            this.state.completedCommands = this.state.completedCommands.slice(-256);
+            delete this.state.acceptedCommands[commandId];
+            this.persist();
+        })
+            .finally(() => {
+            this.inflightCommands.delete(commandId);
+            this.runtimeProfiles.delete(runId);
+        });
+    }
+    async reconcileInterruptedCommand(commandId, accepted) {
+        try {
+            this.attempts.set(accepted.agentRunId, accepted.workerAttempt);
+            await this.postEvent(accepted.agentRunId, {
+                type: "run.failed",
+                event_id: `recovery-${commandId.replaceAll(":", "-")}`,
+                seq: 1,
+                error: "daemon restarted after accepting the turn; execution outcome is unknown",
+                payload: {
+                    error_type: "execution_outcome_unknown",
+                    retryable: true,
+                    session_disposition: "close_generation",
+                    context_revision: accepted.contextRevision,
+                },
+            });
+            this.state.completedCommands.push(commandId);
+            this.state.completedCommands = this.state.completedCommands.slice(-256);
+            delete this.state.acceptedCommands[commandId];
+            this.persist();
+        }
+        catch (error) {
+            this.log.error("failed to reconcile an interrupted accepted turn", {
+                runtimeSessionId: this.options.sessionId,
+                agentRunId: accepted.agentRunId,
+                workerAttempt: accepted.workerAttempt,
+                error: error instanceof Error ? redactSecretString(error.message) : String(error),
+            });
+        }
+    }
+    runtimeActivation(payload) {
+        const raw = payload.context.runtimeSession;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new Error("managed turn is missing runtime session context");
+        }
+        const value = raw;
+        const runtimeSessionId = value.runtimeSessionId;
+        const generation = Number(value.sessionGeneration ?? 0);
+        const contextRevision = Number(value.contextRevision ?? 0);
+        const runtimeId = typeof payload.runtime.id === "string" ? payload.runtime.id.trim() : "";
+        if (value.schemaVersion !== "agent-runtime-session-context/0.1" ||
+            runtimeSessionId !== this.options.sessionId ||
+            generation !== this.sessionGeneration ||
+            !Number.isInteger(contextRevision) ||
+            contextRevision < 1 ||
+            !runtimeId) {
+            throw new Error("managed turn runtime session context is invalid");
+        }
+        return { runtimeId, contextRevision };
+    }
+    ackEventOrFile(frame) {
+        const frameId = frame.payload.frame_id;
+        if (typeof frameId !== "string")
+            throw new Error("event.ack has no frame_id");
+        const pendingFile = this.pendingFileCommits.get(frameId);
+        if (pendingFile) {
+            this.pendingFileCommits.delete(frameId);
+            const file = frame.payload.file;
+            if (!file || typeof file !== "object" || Array.isArray(file)) {
+                pendingFile.reject(new Error("file commit ACK has no file record"));
+            }
+            else {
+                pendingFile.resolve(file);
+            }
+            return;
+        }
+        const index = this.state.spool.findIndex((item) => item.frame_id === frameId);
+        if (index >= 0)
+            this.state.spool.splice(index, 1);
+        this.persist();
+        const pending = this.pendingAcks.get(frameId);
+        if (pending) {
+            this.pendingAcks.delete(frameId);
+            pending.resolve();
+        }
+    }
+    acceptFileGrant(frame) {
+        const requestFrameId = frame.payload.request_frame_id;
+        if (typeof requestFrameId !== "string")
+            throw new Error("file grant has no request_frame_id");
+        const pending = this.pendingFilePrepares.get(requestFrameId);
+        if (!pending)
+            return;
+        this.pendingFilePrepares.delete(requestFrameId);
+        const file = frame.payload.file;
+        const uploadUrl = frame.payload.upload_url;
+        const uploadGrant = frame.payload.upload_grant;
+        if (!file ||
+            typeof file !== "object" ||
+            Array.isArray(file) ||
+            typeof uploadUrl !== "string" ||
+            !uploadUrl ||
+            typeof uploadGrant !== "string" ||
+            !uploadGrant) {
+            pending.reject(new Error("invalid Agent Service file upload grant"));
+            return;
+        }
+        pending.resolve({
+            record: file,
+            uploadUrl,
+            uploadGrant,
+        });
+    }
+    async replaySpool() {
+        for (const original of this.state.spool) {
+            const replay = {
+                ...original,
+                session_generation: this.sessionGeneration,
+                connection_epoch: this.connectionEpoch,
+                seq: this.nextOutboundSeq(),
+                sent_at: new Date().toISOString(),
+            };
+            Object.assign(original, replay);
+            this.persist();
+            await this.sendFrame(original);
+        }
+    }
+    async sendHeartbeat() {
+        if (!this.socket ||
+            this.socket.readyState !== WebSocketClient.OPEN ||
+            !this.sessionGeneration)
+            return;
+        await this.sendControlFrame("session.heartbeat", {
+            active_turns: this.dispatcher.activeCount,
+            spool_frames: this.state.spool.length,
+            spool_bytes: this.spoolBytes(),
+        });
+    }
+    async sendCommandAck(frame, commandId) {
+        await this.sendControlFrame("command.ack", {
+            command_id: commandId ?? frame.frame_id,
+            command_seq: frame.seq,
+            accepted: true,
+        });
+    }
+    async sendControlFrame(type, payload) {
+        await this.sendFrame(createSandboxFrame({
+            type,
+            sessionId: this.options.sessionId,
+            sessionGeneration: this.sessionGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            payload,
+        }));
+    }
+    async sendFrame(frame) {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocketClient.OPEN)
+            return;
+        await new Promise((resolve, reject) => {
+            socket.send(JSON.stringify(frame), (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    nextOutboundSeq() {
+        this.state.nextOutboundSeq += 1;
+        this.persist();
+        return this.state.nextOutboundSeq;
+    }
+    spoolBytes() {
+        return Buffer.byteLength(JSON.stringify(this.state.spool), "utf8");
+    }
+    enforceSpoolLimit() {
+        if (this.state.spool.length > MAX_SPOOL_FRAMES || this.spoolBytes() > MAX_SPOOL_BYTES) {
+            this.dispatcher.cancelAll();
+            throw new Error("Agent Service session event spool exceeded its bounded limit");
+        }
+    }
+    rejectPending(error) {
+        for (const pending of this.pendingAcks.values())
+            pending.reject(error);
+        this.pendingAcks.clear();
+        this.rejectPendingFiles(error);
+    }
+    rejectPendingFiles(error) {
+        for (const pending of this.pendingFilePrepares.values())
+            pending.reject(error);
+        this.pendingFilePrepares.clear();
+        for (const pending of this.pendingFileCommits.values())
+            pending.reject(error);
+        this.pendingFileCommits.clear();
+        this.fileGrants.clear();
+    }
+    persist() {
+        saveState(this.options.sessionId, this.state);
+    }
+}