@botlearn-course/daemon 0.0.7 → 0.0.9

package/dist/agent-service-sandbox.js

@@ -0,0 +1,1400 @@
+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_SCHEMA, AGENT_SERVICE_WS_SUBPROTOCOL, createSandboxFrame, parseSandboxFrame, UnsupportedSandboxProtocolError, } from "./agent-service-ws-protocol.js";
+import { log as defaultLog } from "./log.js";
+import { availableRunCapabilities } from "./runtime-capabilities.js";
+import { activationRuntimeEnv, runtimeChildEnv } from "./runtime-env.js";
+import { assertNoInjectedCredentials, redactSecretString } from "./redaction.js";
+import { RunDispatcher, } from "./run-dispatcher.js";
+import { ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, } 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;
+/** 出站 seq 基址：seq = connection_epoch * SEQ_EPOCH_BASE + n，跨重连单调（合同 §1.1）。 */
+const SEQ_EPOCH_BASE = 1_000_000_000;
+class SandboxClosedError 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 SandboxClosedError(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 sandboxStatePath(sandboxId) {
+    const root = path.join(ensureDaemonHome(), "agent-service-sandboxes", sandboxId);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(root, 0o700);
+    }
+    catch {
+        // Windows best effort.
+    }
+    return path.join(root, "state.json");
+}
+function emptySessionState() {
+    return {
+        courseRunId: null,
+        workspaceRef: null,
+        runtimeId: null,
+        nativeSessionId: null,
+        contextRevision: 0,
+        activationId: null,
+        completedCommands: [],
+        completedActivations: [],
+        pendingActivationCleanup: null,
+        acceptedCommands: {},
+        spool: [],
+    };
+}
+function normalizeSessionState(value) {
+    const base = emptySessionState();
+    if (!value || typeof value !== "object")
+        return base;
+    return {
+        courseRunId: typeof value.courseRunId === "string" ? value.courseRunId : null,
+        workspaceRef: typeof value.workspaceRef === "string" ? value.workspaceRef : null,
+        runtimeId: typeof value.runtimeId === "string" ? value.runtimeId : null,
+        nativeSessionId: typeof value.nativeSessionId === "string" ? value.nativeSessionId : null,
+        contextRevision: Number(value.contextRevision ?? 0),
+        activationId: typeof value.activationId === "string" ? value.activationId : null,
+        completedCommands: Array.isArray(value.completedCommands)
+            ? value.completedCommands.filter((item) => typeof item === "string")
+            : [],
+        completedActivations: Array.isArray(value.completedActivations)
+            ? value.completedActivations.filter((item) => typeof item === "string")
+            : [],
+        pendingActivationCleanup: (value.pendingActivationCleanup &&
+            typeof value.pendingActivationCleanup === "object" &&
+            typeof value.pendingActivationCleanup.activationId === "string" &&
+            typeof value.pendingActivationCleanup.agentRunId === "string" &&
+            Number.isInteger(value.pendingActivationCleanup.workerAttempt) &&
+            value.pendingActivationCleanup.workerAttempt > 0)
+            ? {
+                activationId: value.pendingActivationCleanup.activationId,
+                agentRunId: value.pendingActivationCleanup.agentRunId,
+                workerAttempt: value.pendingActivationCleanup.workerAttempt,
+            }
+            : null,
+        acceptedCommands: value.acceptedCommands &&
+            typeof value.acceptedCommands === "object" &&
+            !Array.isArray(value.acceptedCommands)
+            ? value.acceptedCommands
+            : {},
+        spool: Array.isArray(value.spool) ? value.spool : [],
+    };
+}
+function loadState(sandboxId, token) {
+    const file = sandboxStatePath(sandboxId);
+    if (existsSync(file)) {
+        try {
+            const value = JSON.parse(readFileSync(file, "utf8"));
+            const sessions = {};
+            if (value.sessions && typeof value.sessions === "object" && !Array.isArray(value.sessions)) {
+                for (const [sessionId, session] of Object.entries(value.sessions)) {
+                    sessions[sessionId] = normalizeSessionState(session);
+                }
+            }
+            return {
+                sandboxGeneration: Number(value.sandboxGeneration ?? 0),
+                // A controller launch always supplies a freshly minted sandbox-scoped bootstrap
+                // token. Preserve runtime/command continuity from disk, but never let an expired
+                // persisted reconnect token shadow the controller's recovery credential.
+                reconnectToken: token,
+                sessions,
+            };
+        }
+        catch {
+            // Corrupt state is reconstructed from the server desired state.
+        }
+    }
+    return {
+        sandboxGeneration: 0,
+        reconnectToken: token,
+        sessions: {},
+    };
+}
+function saveState(sandboxId, state) {
+    const file = sandboxStatePath(sandboxId);
+    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 user-scoped managed sandbox (ADR-015).
+ *
+ * 一个 sandbox 内可承载多个 runtime session（CourseRun Session）。server 通过显式命令帧
+ * （session.open/activate/close、turn.start/cancel、sandbox.drain/shutdown/sync）驱动；
+ * daemon 同时只允许一个 active session，且整个 sandbox 同时只有一个 active turn。
+ */
+export class AgentServiceSandboxClient {
+    options;
+    log;
+    random;
+    sleep;
+    state;
+    dispatcher;
+    /** agent_run_id → TURN scope（session/attempt/activation），事件与文件帧路由用。 */
+    turnScopes = new Map();
+    /** 每 run 内嵌 profile（turn payload 自带时优先）。 */
+    runProfiles = new Map();
+    /** activate 时装配的 per-session profile，turn.start 复用。 */
+    sessionProfiles = new Map();
+    /** activation-scoped 模型短凭据；只保存在内存中，绝不进入 state.json。 */
+    activationContexts = new Map();
+    pendingAcks = new Map();
+    pendingFilePrepares = new Map();
+    pendingFileCommits = new Map();
+    fileGrants = new Map();
+    inflightCommands = new Set();
+    socket = null;
+    sandboxGeneration = 0;
+    connectionEpoch = 0;
+    outboundSeq = 0;
+    inboundSeq = 0;
+    activeSessionId = null;
+    /** 全局串行下当前正在执行 turn 的 session（persistNativeSession 路由用）。 */
+    currentTurnSessionId = null;
+    heartbeatMs = 15_000;
+    staleMs = 45_000;
+    stopped = false;
+    permanentFailure = false;
+    lifecycleChain = Promise.resolve();
+    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.sandboxId, options.sandboxToken);
+        this.dispatcher = new RunDispatcher(this, options.runtimes, {
+            persistentSession: this,
+        });
+    }
+    prepareTurn(payload) {
+        const scope = this.turnScopes.get(payload.agent_run_id);
+        if (!scope)
+            throw new Error("managed turn has no runtime session scope");
+        const session = this.state.sessions[scope.sessionId];
+        if (!session)
+            throw new Error("managed turn runtime session is unknown");
+        const contextRevision = this.turnContextRevision(payload, session);
+        const activation = this.activationContexts.get(scope.sessionId);
+        if (!activation || activation.activationId !== scope.activationId) {
+            throw new Error("managed turn activation context is unavailable");
+        }
+        const prepared = ensureRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration, payload.agent_run_id);
+        // ensureRuntimeSessionWorkspace creates missing paths with the closed-by-default
+        // mode; re-expose only after the activation fence above has been checked.
+        exposeRuntimeSessionWorkspace(scope.sessionId, this.sandboxGeneration);
+        this.currentTurnSessionId = scope.sessionId;
+        const runtimeEnv = runtimeChildEnv(process.env);
+        delete runtimeEnv.DEEPSEEK_API_KEY;
+        delete runtimeEnv.DEEPSEEK_BASE_URL;
+        Object.assign(runtimeEnv, activation.runtimeEnv);
+        runtimeEnv.BOTLEARN_AGENT_SERVICE_ACTIVATION_ID = scope.activationId;
+        payload.context.instructions = [
+            ...activation.instructions,
+            ...(Array.isArray(payload.context.instructions)
+                ? payload.context.instructions.filter((item) => typeof item === "string")
+                : []),
+        ];
+        return {
+            workspaceDir: prepared.workspaceDir,
+            transcriptFile: prepared.transcriptFile,
+            nativeSessionId: session.nativeSessionId,
+            contextRevision,
+            runtimeEnv,
+        };
+    }
+    persistNativeSession(nativeSessionId) {
+        const sessionId = this.currentTurnSessionId;
+        if (!sessionId)
+            return;
+        const session = this.state.sessions[sessionId];
+        if (!session)
+            return;
+        session.nativeSessionId = nativeSessionId.trim() || null;
+        this.persist();
+    }
+    finishTurn(payload) {
+        const scope = this.turnScopes.get(payload.agent_run_id);
+        if (!scope)
+            return;
+        const activation = this.activationContexts.get(scope.sessionId);
+        const session = this.state.sessions[scope.sessionId];
+        if (session && activation?.activationId === scope.activationId) {
+            // Persist the cleanup obligation before attempting chmod. A terminal event has
+            // already been durably ACKed at this point, so reconnect/restart must finish this
+            // revoke even when the server desired state has already moved to idle.
+            session.pendingActivationCleanup = {
+                activationId: scope.activationId,
+                agentRunId: payload.agent_run_id,
+                workerAttempt: scope.workerAttempt,
+            };
+            this.persist();
+            try {
+                this.completePendingActivationCleanup(scope.sessionId);
+            }
+            catch (error) {
+                this.log.error("failed to revoke a terminal runtime session workspace", {
+                    sandboxId: this.options.sandboxId,
+                    runtimeSessionId: scope.sessionId,
+                    agentRunId: payload.agent_run_id,
+                    error: error instanceof Error ? redactSecretString(error.message) : String(error),
+                });
+                this.socket?.close(1011, "workspace_revoke_failed");
+                throw error;
+            }
+        }
+        this.turnScopes.delete(payload.agent_run_id);
+        if (this.currentTurnSessionId === scope.sessionId)
+            this.currentTurnSessionId = null;
+        for (const [key, grant] of this.fileGrants) {
+            if (this.sameTurnScope(scope, grant.scope))
+                this.fileGrants.delete(key);
+        }
+        this.persist();
+    }
+    completePendingActivationCleanup(sessionId) {
+        const session = this.state.sessions[sessionId];
+        const pending = session?.pendingActivationCleanup;
+        if (!session || !pending)
+            return;
+        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        const activation = this.activationContexts.get(sessionId);
+        if (activation?.activationId === pending.activationId) {
+            this.activationContexts.delete(sessionId);
+            this.sessionProfiles.delete(sessionId);
+        }
+        if (session.activationId === pending.activationId)
+            session.activationId = null;
+        if (!session.completedActivations.includes(pending.activationId)) {
+            // Session-close/generation-rotate are the retention bounds. Never evict an
+            // activation tombstone while the session is alive: activation IDs are opaque, so
+            // there is no safe monotonic ordering from which to infer that an old replay died.
+            session.completedActivations.push(pending.activationId);
+        }
+        const commandId = `run:${pending.agentRunId}:${pending.workerAttempt}`;
+        if (!session.completedCommands.includes(commandId)) {
+            session.completedCommands.push(commandId);
+            session.completedCommands = session.completedCommands.slice(-256);
+        }
+        delete session.acceptedCommands[commandId];
+        session.pendingActivationCleanup = null;
+        this.turnScopes.delete(pending.agentRunId);
+        if (this.activeSessionId === sessionId)
+            this.activeSessionId = null;
+        if (this.currentTurnSessionId === sessionId)
+            this.currentTurnSessionId = null;
+        for (const [key, grant] of this.fileGrants) {
+            if (grant.scope.sessionId === sessionId &&
+                grant.scope.workerAttempt === pending.workerAttempt &&
+                grant.scope.activationId === pending.activationId)
+                this.fileGrants.delete(key);
+        }
+        this.persist();
+    }
+    recoverPendingActivationCleanups() {
+        for (const sessionId of Object.keys(this.state.sessions)) {
+            this.completePendingActivationCleanup(sessionId);
+        }
+    }
+    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 SandboxClosedError ? 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", {
+                    sandboxId: this.options.sandboxId,
+                    delayMs: delay,
+                    error: error instanceof Error ? redactSecretString(error.message) : String(error),
+                });
+                await this.sleep(delay);
+            }
+        }
+        if (this.permanentFailure) {
+            throw new Error("Agent Service sandbox stopped after a permanent protocol failure");
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.dispatcher.cancelAll();
+        for (const [sessionId, session] of Object.entries(this.state.sessions)) {
+            session.activationId = null;
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        }
+        this.activationContexts.clear();
+        this.sessionProfiles.clear();
+        this.activeSessionId = null;
+        this.currentTurnSessionId = null;
+        this.persist();
+        this.socket?.close(1000, "daemon_stopping");
+    }
+    async postEvent(agentRunId, event) {
+        const scope = this.turnScopes.get(agentRunId);
+        if (!scope)
+            throw new Error("Agent Service sandbox event has no active turn scope");
+        const session = this.state.sessions[scope.sessionId];
+        if (!session)
+            throw new Error("Agent Service sandbox event session is unknown");
+        if (!this.sandboxGeneration || !this.connectionEpoch) {
+            throw new Error("Agent Service sandbox is not authenticated");
+        }
+        const frame = createSandboxFrame({
+            type: "turn.event",
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId: scope.sessionId,
+            agentRunId,
+            workerAttempt: scope.workerAttempt,
+            activationId: scope.activationId,
+            payload: event,
+        });
+        session.spool.push(frame);
+        try {
+            this.enforceSpoolLimit();
+        }
+        catch (error) {
+            session.spool.pop();
+            this.persist();
+            throw error;
+        }
+        this.persist();
+        const ack = new Promise((resolve, reject) => {
+            this.pendingAcks.set(frame.frame_id, { scope: { ...scope }, resolve, reject });
+        });
+        await this.sendFrame(frame);
+        await ack;
+    }
+    async postFile(agentRunId, file) {
+        const scope = this.turnScopes.get(agentRunId);
+        if (!scope)
+            throw new Error("Agent Service sandbox file has no active turn scope");
+        if (!file.sha256 || !Number.isInteger(file.size_bytes) || (file.size_bytes ?? -1) < 0) {
+            throw new Error("Agent Service sandbox file requires size_bytes and sha256");
+        }
+        const frame = createSandboxFrame({
+            type: "turn.file.prepare",
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId: scope.sessionId,
+            agentRunId,
+            workerAttempt: scope.workerAttempt,
+            activationId: scope.activationId,
+            payload: file,
+        });
+        const prepared = new Promise((resolve, reject) => {
+            this.pendingFilePrepares.set(frame.frame_id, {
+                scope: { ...scope },
+                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 scope = this.turnScopes.get(agentRunId);
+        if (!scope)
+            throw new Error("Agent Service sandbox file has no active turn scope");
+        const key = `${agentRunId}:${fileId}`;
+        const grant = this.fileGrants.get(key);
+        if (!grant)
+            throw new Error("Agent Service sandbox file has no upload grant");
+        if (!this.sameTurnScope(scope, grant.scope)) {
+            throw new Error("Agent Service sandbox file grant turn scope mismatch");
+        }
+        const data = await readFile(absPath);
+        assertNoInjectedCredentials(data, [
+            this.state.reconnectToken,
+            grant.uploadGrant,
+            ...Object.values(this.activationContexts.get(scope.sessionId)?.runtimeEnv ?? {}),
+        ]);
+        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",
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId: scope.sessionId,
+            agentRunId,
+            workerAttempt: scope.workerAttempt,
+            activationId: scope.activationId,
+            payload: { file_id: fileId, sha256: grant.record.sha256 },
+        });
+        const committed = new Promise((resolve, reject) => {
+            this.pendingFileCommits.set(frame.frame_id, {
+                scope: { ...scope },
+                resolve,
+                reject,
+            });
+        });
+        await this.sendFrame(frame);
+        try {
+            return await committed;
+        }
+        finally {
+            this.fileGrants.delete(key);
+        }
+    }
+    async getRunRuntimeProfile(agentRunId) {
+        const embedded = this.runProfiles.get(agentRunId);
+        if (embedded)
+            return embedded;
+        const scope = this.turnScopes.get(agentRunId);
+        const activated = scope ? this.sessionProfiles.get(scope.sessionId) : undefined;
+        if (!activated)
+            throw new Error("Agent Service sandbox runtime profile is unavailable");
+        return activated;
+    }
+    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
+        // sandbox.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 SandboxClosedError(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();
+                let frame;
+                try {
+                    frame = parseSandboxFrame(raw);
+                }
+                catch (error) {
+                    if (error instanceof UnsupportedSandboxProtocolError) {
+                        socket.close(4410, "protocol_incompatible");
+                        throw new SandboxClosedError(4410, "protocol_incompatible");
+                    }
+                    throw error;
+                }
+                if (frame.type === "sandbox.hello") {
+                    await this.handleHello(frame);
+                    if (heartbeat === null) {
+                        heartbeat = setInterval(() => {
+                            void this.sendHeartbeat().catch((error) => {
+                                this.log.warn("Agent Service sandbox heartbeat failed", {
+                                    sandboxId: this.options.sandboxId,
+                                    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 sandbox server frame timeout; reconnecting", {
+                                    sandboxId: this.options.sandboxId,
+                                    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.sandbox_id !== this.options.sandboxId) {
+            throw new SandboxClosedError(4403, "sandbox_mismatch");
+        }
+        if (this.sandboxGeneration && frame.sandbox_generation < this.sandboxGeneration) {
+            throw new SandboxClosedError(4409, "stale_generation");
+        }
+        if (frame.sandbox_generation !== this.state.sandboxGeneration) {
+            // Generation change wipes every session shard (contract §1.4).
+            this.dispatcher.cancelAll();
+            this.rejectPending(new Error("Agent Service sandbox generation changed"));
+            for (const sessionId of Object.keys(this.state.sessions)) {
+                revokeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
+                removeRuntimeSessionWorkspace(sessionId, this.state.sandboxGeneration);
+            }
+            this.state.sessions = {};
+            this.state.sandboxGeneration = frame.sandbox_generation;
+            this.sessionProfiles.clear();
+            this.activationContexts.clear();
+            this.runProfiles.clear();
+            this.turnScopes.clear();
+            this.activeSessionId = null;
+            this.currentTurnSessionId = null;
+        }
+        this.sandboxGeneration = frame.sandbox_generation;
+        this.connectionEpoch = frame.connection_epoch;
+        this.inboundSeq = frame.seq;
+        this.outboundSeq = frame.connection_epoch * SEQ_EPOCH_BASE;
+        this.recoverPendingActivationCleanups();
+        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_after_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("sandbox.ready", {
+            protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
+            daemon_version: this.options.daemonVersion,
+            resumed_sessions: Object.keys(this.state.sessions),
+            spool_frames: this.spoolFrameCount(),
+        });
+    }
+    assertServerFrame(frame) {
+        if (frame.sandbox_id !== this.options.sandboxId ||
+            frame.sandbox_generation !== this.sandboxGeneration ||
+            frame.connection_epoch !== this.connectionEpoch) {
+            throw new SandboxClosedError(4409, "connection_fenced");
+        }
+        if (frame.seq !== this.inboundSeq + 1)
+            throw new Error("server frame sequence gap");
+    }
+    async handleServerFrame(frame) {
+        switch (frame.type) {
+            case "sandbox.sync":
+                await this.applySync(frame);
+                return;
+            case "session.open":
+                this.scheduleLifecycle("session.open", () => this.handleSessionOpen(frame));
+                return;
+            case "session.activate":
+                this.scheduleLifecycle("session.activate", (fence) => this.handleSessionActivate(frame, fence));
+                return;
+            case "session.close":
+                this.scheduleLifecycle("session.close", (fence) => this.closeSession(frame.runtime_session_id, typeof frame.payload.reason === "string" ? frame.payload.reason : "closed", frame, fence));
+                return;
+            case "turn.start":
+                this.scheduleLifecycle("turn.start", () => this.handleTurnStart(frame));
+                return;
+            case "turn.cancel":
+                this.scheduleLifecycle("turn.cancel", () => this.handleTurnCancel(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, "ok");
+                return;
+            }
+            case "sandbox.shutdown":
+                this.stop();
+                return;
+            case "sandbox.drain":
+                await this.sendCommandAck(frame, "ok");
+                this.scheduleLifecycle("sandbox.drain", async (fence) => {
+                    if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
+                        await this.sendControlFrame("sandbox.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}`);
+        }
+    }
+    /** sandbox.sync 只做对账：重放 spool、关闭待关 session、应用 drain/shutdown。 */
+    async applySync(frame) {
+        await this.replaySpool();
+        const closeSessions = Array.isArray(frame.payload.close_sessions)
+            ? frame.payload.close_sessions.filter((item) => typeof item === "string" && item.length > 0)
+            : [];
+        for (const sessionId of closeSessions) {
+            this.scheduleLifecycle("sandbox.sync.close", (fence) => this.closeSession(sessionId, "sync_close", frame, fence));
+        }
+        const state = frame.payload.state;
+        if (state === "shutdown") {
+            this.stop();
+            return;
+        }
+        if (state === "drain") {
+            this.scheduleLifecycle("sandbox.sync.drain", async (fence) => {
+                if (await this.dispatcher.drain(10_000) && this.isCurrentLifecycleFence(fence)) {
+                    await this.sendControlFrame("sandbox.drained", {});
+                }
+            });
+        }
+        // idle/run/cancel：实际工作全部由显式命令帧下发（合同 §1.3）。
+    }
+    async handleSessionOpen(frame) {
+        const sessionId = frame.runtime_session_id;
+        const session = this.state.sessions[sessionId] ?? emptySessionState();
+        const courseRunId = frame.payload.course_run_id;
+        const requestedWorkspaceRef = frame.payload.workspace_ref;
+        if (typeof courseRunId !== "string" ||
+            courseRunId.length < 1 ||
+            (requestedWorkspaceRef !== null &&
+                requestedWorkspaceRef !== undefined &&
+                (typeof requestedWorkspaceRef !== "string" || requestedWorkspaceRef.length < 1))) {
+            throw new Error("invalid session.open payload");
+        }
+        if (session.courseRunId !== null && session.courseRunId !== courseRunId) {
+            throw new Error("runtime session course_run_id cannot be rebound");
+        }
+        if (session.workspaceRef !== null &&
+            typeof requestedWorkspaceRef === "string" &&
+            session.workspaceRef !== requestedWorkspaceRef) {
+            throw new Error("runtime session workspace_ref cannot be rebound");
+        }
+        session.courseRunId = courseRunId;
+        session.workspaceRef = session.workspaceRef ?? (typeof requestedWorkspaceRef === "string"
+            ? requestedWorkspaceRef
+            : `ws_${sessionId.replaceAll("-", "")}_g${this.sandboxGeneration}`);
+        ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
+        this.state.sessions[sessionId] = session;
+        this.persist();
+        await this.sendSessionFrame("session.opened", sessionId, {
+            workspace_ref: session.workspaceRef,
+            native_session_id: session.nativeSessionId,
+        });
+    }
+    async handleSessionActivate(frame, fence) {
+        const sessionId = frame.runtime_session_id;
+        const activationId = frame.activation_id;
+        const session = this.state.sessions[sessionId];
+        if (!session) {
+            await this.sendCommandAck(frame, "rejected", "session_not_open");
+            return;
+        }
+        const contextRevision = Number(frame.payload.context_revision);
+        const runtimeId = typeof frame.payload.runtime_id === "string"
+            ? frame.payload.runtime_id.trim()
+            : "";
+        if (!Number.isInteger(contextRevision) || contextRevision < 1 || !runtimeId) {
+            await this.sendCommandAck(frame, "rejected", "invalid_activation");
+            return;
+        }
+        if (contextRevision < session.contextRevision) {
+            await this.sendCommandAck(frame, "rejected", "context_revision_regression");
+            return;
+        }
+        let runtimeEnv;
+        try {
+            runtimeEnv = activationRuntimeEnv(frame.payload.runtime_env);
+        }
+        catch (error) {
+            await this.sendCommandAck(frame, "rejected", error instanceof Error ? error.message : "invalid_runtime_env");
+            return;
+        }
+        let instructions;
+        try {
+            instructions = this.activationInstructions(frame.payload.instructions);
+        }
+        catch (error) {
+            await this.sendCommandAck(frame, "rejected", error instanceof Error ? error.message : "invalid_instructions");
+            return;
+        }
+        const capabilities = Array.isArray(frame.payload.capabilities)
+            ? frame.payload.capabilities.filter((item) => typeof item === "string" && item.length > 0)
+            : [];
+        if (capabilities.length > 0) {
+            const workspace = ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
+            const available = new Set(availableRunCapabilities({
+                agent_run_id: "activation-probe",
+                course_run_id: session.courseRunId ?? "",
+                lesson_id: null,
+                task_id: null,
+                agent_instance_id: null,
+                runtime: { id: runtimeId },
+                input: {},
+                context: {},
+                limits: {},
+            }, workspace.workspaceDir));
+            const missing = capabilities.filter((item) => !available.has(item)).sort();
+            if (missing.length > 0) {
+                await this.sendCommandAck(frame, "rejected", `missing_capabilities:${missing.join(",")}`);
+                return;
+            }
+        }
+        const existingActivation = this.activationContexts.get(sessionId);
+        if (existingActivation?.activationId === activationId) {
+            if (this.activeSessionId !== sessionId ||
+                session.runtimeId !== runtimeId ||
+                session.contextRevision !== contextRevision) {
+                await this.sendCommandAck(frame, "rejected", "activation_redefinition");
+                return;
+            }
+            // Idempotent desired-state replay. Keep the original short credential snapshot so
+            // a running turn cannot switch tokens midway through output/file redaction.
+            await this.sendCommandAck(frame, "ok");
+            return;
+        }
+        if (session.completedActivations.includes(activationId)) {
+            // Desired-state commands are at-least-once. A replay that arrives after this
+            // activation's terminal event must remain a no-op: re-exposing the workspace here
+            // would leave an idle session readable and restore an expired credential snapshot.
+            await this.sendCommandAck(frame, "ok");
+            return;
+        }
+        // 同一时刻只允许一个 active session/activation。先撤销上一 workspace 的
+        // runtime 访问并等待进程退出，再暴露新 workspace，避免同 UID 跨 Session 读取。
+        const previousSessionId = this.activeSessionId;
+        const changesActivation = previousSessionId !== null && (previousSessionId !== sessionId || session.activationId !== activationId);
+        if (changesActivation) {
+            const stopped = await this.deactivateSession(previousSessionId);
+            if (fence && !this.isCurrentLifecycleFence(fence))
+                return;
+            if (!stopped) {
+                await this.sendCommandAck(frame, "rejected", "previous_activation_did_not_stop");
+                return;
+            }
+        }
+        const profile = frame.payload.profile;
+        if (profile && typeof profile === "object" && !Array.isArray(profile)) {
+            this.sessionProfiles.set(sessionId, profile);
+        }
+        else if (profile === null) {
+            this.sessionProfiles.delete(sessionId);
+        }
+        session.runtimeId = runtimeId;
+        session.contextRevision = contextRevision;
+        session.activationId = activationId;
+        exposeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        this.activationContexts.set(sessionId, { activationId, runtimeEnv, instructions });
+        this.activeSessionId = sessionId;
+        this.persist();
+        await this.sendCommandAck(frame, "ok");
+    }
+    async handleTurnStart(frame) {
+        const sessionId = frame.runtime_session_id;
+        const runId = frame.agent_run_id;
+        const attempt = frame.worker_attempt;
+        const activationId = frame.activation_id;
+        const session = this.state.sessions[sessionId];
+        const activation = this.activationContexts.get(sessionId);
+        if (!session ||
+            session.activationId === null ||
+            this.activeSessionId !== sessionId ||
+            !activation ||
+            activation.activationId !== activationId) {
+            await this.sendCommandAck(frame, "rejected", "session_not_activated");
+            return;
+        }
+        if (session.activationId !== activationId) {
+            await this.sendCommandAck(frame, "rejected", "activation_mismatch");
+            return;
+        }
+        const payload = frame.payload;
+        if (!this.validTurnPayload(payload)) {
+            await this.sendCommandAck(frame, "rejected", "invalid_turn_payload");
+            return;
+        }
+        if (payload.agent_run_id !== runId) {
+            await this.sendCommandAck(frame, "rejected", "agent_run_mismatch");
+            return;
+        }
+        if (session.courseRunId !== payload.course_run_id) {
+            await this.sendCommandAck(frame, "rejected", "course_run_mismatch");
+            return;
+        }
+        if (session.runtimeId !== payload.runtime.id) {
+            await this.sendCommandAck(frame, "rejected", "runtime_mismatch");
+            return;
+        }
+        try {
+            this.turnContextRevision(payload, session);
+        }
+        catch {
+            await this.sendCommandAck(frame, "rejected", "context_revision_mismatch");
+            return;
+        }
+        const activatedProfile = this.sessionProfiles.get(sessionId);
+        const expectedProfileHash = payload.context?.profileHash;
+        if (typeof expectedProfileHash === "string" &&
+            activatedProfile &&
+            activatedProfile.profileHash !== expectedProfileHash) {
+            await this.sendCommandAck(frame, "rejected", "profile_hash_mismatch");
+            return;
+        }
+        const scope = { sessionId, workerAttempt: attempt, activationId };
+        const existingScope = this.turnScopes.get(runId);
+        if (existingScope && !this.sameTurnScope(existingScope, scope)) {
+            await this.sendCommandAck(frame, "rejected", "turn_scope_mismatch");
+            return;
+        }
+        const commandId = `run:${runId}:${attempt}`;
+        if (session.completedCommands.includes(commandId) || this.inflightCommands.has(commandId)) {
+            await this.sendCommandAck(frame, "ok");
+            return;
+        }
+        this.turnScopes.set(runId, scope);
+        const accepted = session.acceptedCommands[commandId];
+        if (accepted && !this.inflightCommands.has(commandId)) {
+            await this.sendCommandAck(frame, "ok");
+            void this.reconcileInterruptedCommand(sessionId, commandId, accepted);
+            return;
+        }
+        if (!accepted) {
+            session.acceptedCommands[commandId] = {
+                agentRunId: runId,
+                workerAttempt: attempt,
+                contextRevision: session.contextRevision,
+                activationId,
+                acceptedAt: new Date().toISOString(),
+            };
+            this.persist();
+        }
+        const embeddedProfile = payload.context?.runtimeProfile;
+        if (embeddedProfile && typeof embeddedProfile === "object") {
+            this.runProfiles.set(runId, embeddedProfile);
+        }
+        this.inflightCommands.add(commandId);
+        await this.sendCommandAck(frame, "ok");
+        void this.dispatcher.dispatch(payload)
+            .then(() => {
+            if (!session.completedCommands.includes(commandId)) {
+                session.completedCommands.push(commandId);
+                session.completedCommands = session.completedCommands.slice(-256);
+            }
+            delete session.acceptedCommands[commandId];
+            this.persist();
+        })
+            .catch((error) => {
+            this.log.error("managed turn failed during terminal cleanup", {
+                sandboxId: this.options.sandboxId,
+                runtimeSessionId: sessionId,
+                agentRunId: runId,
+                error: error instanceof Error ? redactSecretString(error.message) : String(error),
+            });
+        })
+            .finally(() => {
+            this.inflightCommands.delete(commandId);
+            this.runProfiles.delete(runId);
+        });
+    }
+    async handleTurnCancel(frame) {
+        if (!this.matchesTurnScope(frame, this.turnScopes.get(frame.agent_run_id))) {
+            await this.sendCommandAck(frame, "rejected", "turn_scope_mismatch");
+            return;
+        }
+        this.dispatcher.cancel(frame.agent_run_id);
+        await this.sendCommandAck(frame, "ok");
+    }
+    /**
+     * 幂等关闭一个 runtime session：终止其 runtime 子进程、删除 workspace/native state、
+     * 清空本地状态分片，并回 session.closed。未知 session 直接回 closed。
+     */
+    async closeSession(sessionId, reason, sourceFrame, fence) {
+        const session = this.state.sessions[sessionId];
+        if (session) {
+            const runIds = this.runIdsForSession(sessionId);
+            session.activationId = null;
+            this.activationContexts.delete(sessionId);
+            this.sessionProfiles.delete(sessionId);
+            revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            for (const runId of runIds)
+                this.dispatcher.cancel(runId);
+            if (!await this.dispatcher.waitForRuns(runIds, 10_000)) {
+                throw new Error(`runtime session ${sessionId} did not stop before close`);
+            }
+            if (fence && !this.isCurrentLifecycleFence(fence))
+                return;
+            if (this.activeSessionId === sessionId)
+                this.activeSessionId = null;
+            if (this.currentTurnSessionId === sessionId)
+                this.currentTurnSessionId = null;
+            for (const runId of runIds)
+                this.turnScopes.delete(runId);
+            removeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+            delete this.state.sessions[sessionId];
+            this.persist();
+        }
+        await this.sendSessionFrame("session.closed", sessionId, { reason }, sourceFrame);
+    }
+    async reconcileInterruptedCommand(sessionId, commandId, accepted) {
+        try {
+            this.turnScopes.set(accepted.agentRunId, {
+                sessionId,
+                workerAttempt: accepted.workerAttempt,
+                activationId: accepted.activationId,
+            });
+            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,
+                },
+            });
+            const session = this.state.sessions[sessionId];
+            if (session) {
+                session.completedCommands.push(commandId);
+                session.completedCommands = session.completedCommands.slice(-256);
+                delete session.acceptedCommands[commandId];
+                this.persist();
+            }
+            this.finishTurn({ agent_run_id: accepted.agentRunId });
+        }
+        catch (error) {
+            this.log.error("failed to reconcile an interrupted accepted turn", {
+                sandboxId: this.options.sandboxId,
+                runtimeSessionId: sessionId,
+                agentRunId: accepted.agentRunId,
+                workerAttempt: accepted.workerAttempt,
+                error: error instanceof Error ? redactSecretString(error.message) : String(error),
+            });
+        }
+    }
+    turnContextRevision(payload, session) {
+        const raw = payload.context?.runtimeSession;
+        if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+            const contextRevision = Number(raw.contextRevision ?? 0);
+            if (Number.isInteger(contextRevision) && contextRevision >= 1) {
+                if (contextRevision !== session.contextRevision) {
+                    throw new Error(`runtime context revision mismatch: activated ${session.contextRevision}, ` +
+                        `received ${contextRevision}`);
+                }
+                return contextRevision;
+            }
+        }
+        return session.contextRevision;
+    }
+    activationInstructions(value) {
+        if (value === undefined || value === null)
+            return [];
+        if (!Array.isArray(value) || value.length > 64) {
+            throw new Error("invalid_activation_instructions");
+        }
+        const instructions = [];
+        let totalBytes = 0;
+        for (const item of value) {
+            if (typeof item !== "string" || item.length < 1) {
+                throw new Error("invalid_activation_instructions");
+            }
+            totalBytes += Buffer.byteLength(item, "utf8");
+            if (totalBytes > 100_000)
+                throw new Error("activation_instructions_too_large");
+            instructions.push(item);
+        }
+        return instructions;
+    }
+    validTurnPayload(payload) {
+        return Boolean(payload &&
+            typeof payload === "object" &&
+            typeof payload.agent_run_id === "string" &&
+            typeof payload.course_run_id === "string" &&
+            payload.runtime &&
+            typeof payload.runtime === "object" &&
+            typeof payload.runtime.id === "string" &&
+            payload.runtime.id.length > 0 &&
+            payload.input &&
+            typeof payload.input === "object" &&
+            !Array.isArray(payload.input) &&
+            payload.context &&
+            typeof payload.context === "object" &&
+            !Array.isArray(payload.context) &&
+            payload.limits &&
+            typeof payload.limits === "object" &&
+            !Array.isArray(payload.limits));
+    }
+    scheduleLifecycle(label, operation) {
+        const fence = this.currentLifecycleFence();
+        const socket = fence.socket;
+        this.lifecycleChain = this.lifecycleChain
+            .then(async () => {
+            if (!this.isCurrentLifecycleFence(fence))
+                return;
+            await operation(fence);
+        })
+            .catch((error) => {
+            this.log.error("Agent Service sandbox lifecycle command failed", {
+                sandboxId: this.options.sandboxId,
+                command: label,
+                error: error instanceof Error ? redactSecretString(error.message) : String(error),
+            });
+            if (this.socket === socket && socket?.readyState === WebSocketClient.OPEN) {
+                socket.close(1011, "lifecycle_command_failed");
+            }
+        });
+    }
+    currentLifecycleFence() {
+        return {
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            socket: this.socket,
+        };
+    }
+    isCurrentLifecycleFence(fence) {
+        return this.sandboxGeneration === fence.sandboxGeneration &&
+            this.connectionEpoch === fence.connectionEpoch &&
+            this.socket === fence.socket &&
+            fence.socket?.readyState === WebSocketClient.OPEN;
+    }
+    runIdsForSession(sessionId) {
+        return [...this.turnScopes]
+            .filter(([, scope]) => scope.sessionId === sessionId)
+            .map(([runId]) => runId);
+    }
+    async deactivateSession(sessionId) {
+        const session = this.state.sessions[sessionId];
+        if (!session)
+            return true;
+        const runIds = this.runIdsForSession(sessionId);
+        session.activationId = null;
+        this.activationContexts.delete(sessionId);
+        this.sessionProfiles.delete(sessionId);
+        revokeRuntimeSessionWorkspace(sessionId, this.sandboxGeneration);
+        if (this.activeSessionId === sessionId)
+            this.activeSessionId = null;
+        for (const runId of runIds)
+            this.dispatcher.cancel(runId);
+        this.persist();
+        return this.dispatcher.waitForRuns(runIds, 10_000);
+    }
+    sameTurnScope(left, right) {
+        return left.sessionId === right.sessionId &&
+            left.workerAttempt === right.workerAttempt &&
+            left.activationId === right.activationId;
+    }
+    matchesTurnScope(frame, expected) {
+        return expected !== undefined && this.sameTurnScope(expected, {
+            sessionId: frame.runtime_session_id,
+            workerAttempt: frame.worker_attempt,
+            activationId: frame.activation_id,
+        });
+    }
+    assertTurnScope(frame, expected, label) {
+        if (!this.matchesTurnScope(frame, expected)) {
+            throw new Error(`${label} turn scope mismatch`);
+        }
+    }
+    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.assertTurnScope(frame, pendingFile.scope, "file commit ACK");
+            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 pending = this.pendingAcks.get(frameId);
+        if (pending)
+            this.assertTurnScope(frame, pending.scope, "event ACK");
+        for (const session of Object.values(this.state.sessions)) {
+            const index = session.spool.findIndex((item) => item.frame_id === frameId);
+            if (index >= 0) {
+                const original = session.spool[index];
+                this.assertTurnScope(frame, {
+                    sessionId: original.runtime_session_id,
+                    workerAttempt: original.worker_attempt,
+                    activationId: original.activation_id,
+                }, "spooled event ACK");
+                session.spool.splice(index, 1);
+                break;
+            }
+        }
+        this.persist();
+        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.assertTurnScope(frame, pending.scope, "file upload grant");
+        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({
+            scope: pending.scope,
+            record: file,
+            uploadUrl,
+            uploadGrant,
+        });
+    }
+    async replaySpool() {
+        for (const session of Object.values(this.state.sessions)) {
+            for (const original of session.spool) {
+                const replay = {
+                    ...original,
+                    sandbox_generation: this.sandboxGeneration,
+                    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.sandboxGeneration)
+            return;
+        await this.sendControlFrame("sandbox.heartbeat", {
+            spool_frames: this.spoolFrameCount(),
+        });
+    }
+    async sendCommandAck(frame, status, error) {
+        if (frame.sandbox_generation !== this.sandboxGeneration ||
+            frame.connection_epoch !== this.connectionEpoch)
+            return;
+        await this.sendControlFrame("command.ack", {
+            command_frame_id: frame.frame_id,
+            status,
+            ...(error !== undefined ? { error } : {}),
+        });
+    }
+    async sendControlFrame(type, payload) {
+        await this.sendFrame(createSandboxFrame({
+            type,
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            payload,
+        }));
+    }
+    async sendSessionFrame(type, runtimeSessionId, payload, sourceFrame) {
+        if (sourceFrame &&
+            (sourceFrame.sandbox_generation !== this.sandboxGeneration ||
+                sourceFrame.connection_epoch !== this.connectionEpoch))
+            return;
+        await this.sendFrame(createSandboxFrame({
+            type,
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId,
+            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.outboundSeq += 1;
+        return this.outboundSeq;
+    }
+    spoolFrameCount() {
+        return Object.values(this.state.sessions)
+            .reduce((sum, session) => sum + session.spool.length, 0);
+    }
+    spoolBytes() {
+        return Object.values(this.state.sessions)
+            .reduce((sum, session) => sum + Buffer.byteLength(JSON.stringify(session.spool), "utf8"), 0);
+    }
+    enforceSpoolLimit() {
+        if (this.spoolFrameCount() > MAX_SPOOL_FRAMES || this.spoolBytes() > MAX_SPOOL_BYTES) {
+            this.dispatcher.cancelAll();
+            throw new Error("Agent Service sandbox 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.sandboxId, this.state);
+    }
+}