@cursor/july 0.1.1

package/dist/internal/session-engine.js

@@ -0,0 +1,1377 @@
+/**
+ * The session engine owns durable sessions and turn execution. A session is
+ * one Cursor agent conversation plus a materialized workspace, an event log,
+ * and channel bookkeeping (continuation keys, per-session channel state).
+ * Turns are executed by the Cursor SDK runner and their streaming updates
+ * are mapped onto the channel event vocabulary and dispatched to channel
+ * event handlers and hooks.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
+import { slackThreadPermalink } from "../channels/slack/links.js";
+import { DIRECT_TOOL_CALL_CHANNEL_ID, isSymbolicConnectionTransport, } from "../types.js";
+import { ABCollector } from "./ab-collector.js";
+import { foldABStream } from "./ab-fold.js";
+import { buildABSnapshot } from "./ab-snapshot.js";
+import { ApprovalGate } from "./approval-gate.js";
+import { samePrincipal } from "./auth.js";
+import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
+import { EventLogStore } from "./event-log.js";
+import { TurnEventMapper } from "./event-mapper.js";
+import { createHostPlatforms } from "./host-platforms.js";
+import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, } from "./ids.js";
+import { validateToolInput } from "./json-schema.js";
+import { McpHost } from "./mcp-host.js";
+import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
+import { SessionStore } from "./session-store.js";
+import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
+import { buildAgentToolsCatalog, materializeWorkspace, writeWorkspaceFiles, } from "./workspace.js";
+export const HTTP_CHANNEL_ID = "http";
+export const SCHEDULE_CHANNEL_PREFIX = "schedule:";
+export class SessionBusyError extends Error {
+    constructor(sessionId) {
+        super(`Session ${sessionId} already has a running turn; wait for session.waiting before sending a follow-up`);
+        this.name = "SessionBusyError";
+    }
+}
+export class SessionAuthError extends Error {
+    constructor(sessionId) {
+        super(`Session ${sessionId} belongs to a different principal; pass the original caller auth on follow-up`);
+        this.name = "SessionAuthError";
+    }
+}
+export class UnknownChannelError extends Error {
+    constructor(channelId) {
+        super(`Unknown channel "${channelId}"`);
+        this.name = "UnknownChannelError";
+    }
+}
+export class UnknownToolError extends Error {
+    constructor(toolName, availableToolNames) {
+        super(`Unknown tool "${toolName}"`);
+        this.availableToolNames = availableToolNames;
+        this.name = "UnknownToolError";
+    }
+}
+export class ToolNotDirectlyCallableError extends Error {
+    constructor(toolName) {
+        super(`Tool "${toolName}" runs in the agent environment (execution: "agent") and cannot be called directly on the host`);
+        this.name = "ToolNotDirectlyCallableError";
+    }
+}
+export class ToolInputError extends Error {
+    constructor(args) {
+        super(`Invalid input for tool "${args.toolName}": ${args.detail}`);
+        this.name = "ToolInputError";
+    }
+}
+export class UnknownSessionError extends Error {
+    constructor(sessionId) {
+        super(`Unknown session ${sessionId}`);
+        this.name = "UnknownSessionError";
+    }
+}
+export class ApprovalNotFoundError extends Error {
+    constructor(sessionId, callId) {
+        super(`No pending approval for session ${sessionId} call ${callId}`);
+        this.name = "ApprovalNotFoundError";
+    }
+}
+export class ApprovalInterruptedError extends Error {
+    constructor(sessionId, callId) {
+        super(`Approval for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`);
+        this.name = "ApprovalInterruptedError";
+    }
+}
+export class SessionEngine {
+    constructor(options) {
+        var _a;
+        var _b;
+        this.channelsById = new Map();
+        /** Sessions with a turn being admitted (before the run promise exists). */
+        this.pendingTurns = new Set();
+        this.activeTurns = new Map();
+        /** Aborts the in-flight turn per session so a follow-up can preempt it. */
+        this.turnAborts = new Map();
+        /** Serializes turn admission per session (latest follow-up wins). */
+        this.admissionChains = new Map();
+        this.lastOutcomes = new Map();
+        this.updateChains = new Map();
+        this.dispatchChains = new Map();
+        this.backgroundWork = new Set();
+        this.approvals = new ApprovalGate();
+        /** Serve-time resolved connections (see {@link setResolvedConnections}). */
+        this.resolvedConnections = [];
+        this.project = options.project;
+        this.stateRoot = options.stateRoot;
+        this.runner = options.runner;
+        this.logger = (_b = options.logger) !== null && _b !== void 0 ? _b : (() => { });
+        this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
+        this.logs = new EventLogStore((sessionId) => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[agent-serve] failed to persist events for ${sessionId}: ${describeError(error)}`));
+        this.abCollector = new ABCollector(options.project.abs, this.logger, (sessionId) => __awaiter(this, void 0, void 0, function* () { return (yield this.logs.get(sessionId)).snapshot(0); }), Object.assign({ projectRoot: options.project.rootDir }, (((_a = options.project.abConfig) === null || _a === void 0 ? void 0 : _a.persistSamples) === undefined
+            ? {}
+            : { persistSamples: options.project.abConfig.persistSamples })));
+        // Peer and Cursor-account transports are symbolic until the serve host
+        // resolves them; the host-side MCP registry starts with the concrete
+        // connections and gains the rest via setResolvedConnections.
+        this.mcpHost = new McpHost(options.project.agent.connections.filter((connection) => !isSymbolicConnectionTransport(connection.transport)));
+        this.platforms = createHostPlatforms();
+        for (const channel of options.project.channels) {
+            this.channelsById.set(channel.id, channel.definition);
+        }
+    }
+    /**
+     * Attach serve-time resolved connections (peers, Cursor account bridge).
+     * They join the per-turn SDK `mcpServers` map (loopback URL for local
+     * turns, `cloudUrl` for cloud turns) and the host-side registry
+     * (`ctx.host.mcp`, always loopback).
+     */
+    setResolvedConnections(connections) {
+        this.resolvedConnections = connections;
+        for (const connection of connections) {
+            this.mcpHost.addConnection({
+                name: connection.name,
+                transport: Object.assign({ url: connection.localUrl }, (connection.headers === undefined
+                    ? {}
+                    : { headers: connection.headers })),
+            });
+        }
+    }
+    /** Shared host services (MCP / GitHub / Slack / reminders). */
+    get host() {
+        return {
+            mcp: this.mcpHost,
+            github: this.platforms.github,
+            slack: this.platforms.slack,
+            reminders: this.reminderApi,
+        };
+    }
+    /** Attach the serve-host reminder API (called from startServer). */
+    setReminders(api) {
+        this.reminderApi = api;
+    }
+    // ==========================================================================
+    // Sending messages
+    // ==========================================================================
+    /**
+     * Start or resume a session on a channel. When `continuationToken`
+     * addresses an existing session this is a follow-up turn; otherwise a new
+     * session is created (keyed by the provided token, or a fresh one).
+     */
+    send(channelId_1, message_1) {
+        return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
+            var _a, _b, _c;
+            const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : null;
+            const existing = options.continuationToken === undefined
+                ? undefined
+                : yield this.sessions.findByContinuation(channelId, options.continuationToken);
+            if (existing !== undefined) {
+                if (!samePrincipal(existing.auth, auth)) {
+                    throw new SessionAuthError(existing.sessionId);
+                }
+                // Refresh harness cwd when the caller supplies a newer worktree (e.g. PR
+                // synchronize). Leave the durable continuation key unchanged.
+                let record = existing;
+                if (options.workspaceDir !== undefined &&
+                    options.workspaceDir !== existing.workspaceOverride) {
+                    record = yield this.updateRecord(existing.sessionId, (current) => { var _a; return (Object.assign(Object.assign({}, current), { workspaceOverride: options.workspaceDir, pendingWorkspaceFiles: (_a = options.workspaceFiles) !== null && _a !== void 0 ? _a : current.pendingWorkspaceFiles })); });
+                }
+                else if (options.workspaceFiles !== undefined) {
+                    record = yield this.updateRecord(existing.sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: options.workspaceFiles })));
+                }
+                yield this.startTurn(record.sessionId, message);
+                return this.channelSession(record.sessionId, record, false);
+            }
+            const now = new Date().toISOString();
+            const channelState = this.initialChannelState(channelId, options.state);
+            const purpose = options.purpose === "eval" ? "eval" : "live";
+            let record = {
+                sessionId: newSessionId(),
+                channelId,
+                mode: (_b = options.mode) !== null && _b !== void 0 ? _b : "chat",
+                purpose,
+                continuationKey: (_c = options.continuationToken) !== null && _c !== void 0 ? _c : newContinuationKey(),
+                auth,
+                title: options.title,
+                channelState,
+                workspaceOverride: options.workspaceDir,
+                pendingWorkspaceFiles: options.workspaceFiles,
+                cloudOverride: options.cloud,
+                sdkAgentId: options.sdkAgentId,
+                turnCount: 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+            yield this.sessions.save(record);
+            yield this.appendEvent(record.sessionId, {
+                type: "session.started",
+                data: { channelId },
+            });
+            record = yield this.enrollABs(record);
+            yield this.startTurn(record.sessionId, message);
+            return this.channelSession(record.sessionId, record, true);
+        });
+    }
+    /**
+     * Sticky A/B enrollment at session creation — before the first turn, so
+     * variants are in the durable stream (and on {@link SessionRecord.abs})
+     * ahead of model/instructions work. Failures persist as `variant: null`
+     * (sticky skip). Eval harness sessions (`purpose: "eval"`) are never
+     * enrolled.
+     */
+    enrollABs(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.abCollector.enabled || record.purpose === "eval") {
+                return record;
+            }
+            const sessionInfo = this.sessionInfo(record);
+            const abs = {};
+            for (const experiment of this.project.abs) {
+                const def = experiment.definition;
+                const variantKeys = Object.keys(def.variants);
+                let variant = null;
+                try {
+                    variant = yield resolveABSplit(def.split, {
+                        agent: { name: this.project.name },
+                        channel: { id: record.channelId },
+                        session: sessionInfo,
+                        experiment: experiment.name,
+                        variants: variantKeys,
+                    });
+                    if (variant !== null && !(variant in def.variants)) {
+                        throw new Error(`split resolved to ${JSON.stringify(variant)}; expected one of ${variantKeys.join(", ")} or null to skip`);
+                    }
+                }
+                catch (error) {
+                    this.logger(`[agent-serve] ab "${experiment.name}" enrollment failed (sticky skip): ${describeError(error)}`);
+                    variant = null;
+                }
+                abs[experiment.name] = variant;
+                yield this.appendEvent(record.sessionId, {
+                    type: "ab.assigned",
+                    data: { experiment: experiment.name, variant },
+                });
+            }
+            return this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { abs })));
+        });
+    }
+    /**
+     * Ensure {@link SessionRecord.abs} is populated (hydrate from the durable
+     * `ab.assigned` stream when missing — e.g. older sessions after upgrade).
+     */
+    ensureAbs(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (record.abs !== undefined || record.purpose === "eval") {
+                return record;
+            }
+            if (!this.abCollector.enabled) {
+                return record;
+            }
+            const events = yield this.listEvents(record.sessionId, 0);
+            const folded = foldABStream(events);
+            if (folded.arms.size === 0) {
+                return record;
+            }
+            const abs = Object.fromEntries(folded.arms);
+            return this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { abs })));
+        });
+    }
+    /**
+     * Agent config for this session: base project agent plus any per-variant
+     * `instructions` overlays from enrolled A/B arms.
+     */
+    agentForSession(record) {
+        const base = this.project.agent;
+        const instructions = mergeABInstructions(base.instructions, record.abs, this.project.abs.map((experiment) => ({
+            name: experiment.name,
+            definition: experiment.definition,
+        })));
+        if (instructions === base.instructions) {
+            return base;
+        }
+        return Object.assign(Object.assign({}, base), { instructions });
+    }
+    /** Look up a session as a channel-scoped handle. */
+    getChannelSession(channelId, sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined || record.channelId !== channelId) {
+                return null;
+            }
+            return this.channelSession(sessionId, record, false);
+        });
+    }
+    /** Cross-channel hand-off (schedules and channel route handlers). */
+    receive(channel, input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const channelId = this.resolveChannelId(channel);
+            const definition = this.channelsById.get(channelId);
+            if ((definition === null || definition === void 0 ? void 0 : definition.receive) !== undefined) {
+                let lastCreated;
+                const send = (message_1, ...args_1) => __awaiter(this, [message_1, ...args_1], void 0, function* (message, options = {}) {
+                    const session = yield this.send(channelId, message, options);
+                    lastCreated = session;
+                    return session;
+                });
+                const returned = yield definition.receive(input, { send });
+                const session = returned !== null && returned !== void 0 ? returned : lastCreated;
+                if (session === undefined) {
+                    throw new Error(`Channel "${channelId}" receive hook did not start a session`);
+                }
+                return session;
+            }
+            return this.send(channelId, input.message, {
+                auth: input.auth,
+            });
+        });
+    }
+    /** Fire-and-forget task session (schedules' markdown form). */
+    runTask(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = yield this.send(args.channelId, args.prompt, Object.assign({ auth: args.auth, mode: "task" }, (args.title === undefined ? {} : { title: args.title })));
+            return { sessionId: session.id, done: this.waitForCompletion(session.id) };
+        });
+    }
+    // ==========================================================================
+    // Turn execution
+    // ==========================================================================
+    /**
+     * Admit a turn for `sessionId`. A follow-up that arrives while a turn is in
+     * flight preempts it: the running turn is cancelled and its SDK run marked
+     * terminal before the new turn starts. Admissions are serialized per session
+     * so a burst of follow-ups can't race two runs onto the same SDK agent — the
+     * last message wins. Resolves once the new turn has started (not finished).
+     */
+    startTurn(sessionId, message) {
+        var _a;
+        const prior = (_a = this.admissionChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const admitted = prior
+            .catch(() => { })
+            .then(() => this.admitTurn(sessionId, message));
+        this.admissionChains.set(sessionId, admitted.catch(() => { }));
+        return admitted;
+    }
+    admitTurn(sessionId, message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Interrupt any turn in flight and wait for it to settle so the SDK run is
+            // terminal before this turn's send (the follow-up also force-expires as a
+            // belt-and-suspenders — see buildTurnRequest).
+            yield this.interruptActiveTurn(sessionId);
+            this.pendingTurns.add(sessionId);
+            try {
+                let record = yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
+                // Arms must be on the record before tools/instructions see SessionInfo.
+                record = yield this.ensureAbs(record);
+                const turnId = `turn_${record.turnCount}`;
+                const isFirstTurn = record.turnCount === 1;
+                yield this.appendEvent(sessionId, {
+                    type: "message.received",
+                    turnId,
+                    data: { text: message },
+                });
+                yield this.appendEvent(sessionId, {
+                    type: "turn.started",
+                    turnId,
+                    data: {},
+                });
+                const abort = new AbortController();
+                this.turnAborts.set(sessionId, abort);
+                const turnPromise = this.executeTurn(record, turnId, message, isFirstTurn, abort.signal);
+                this.activeTurns.set(sessionId, turnPromise);
+                void turnPromise
+                    .then((outcome) => {
+                    this.lastOutcomes.set(sessionId, outcome);
+                })
+                    .catch(() => { })
+                    .finally(() => {
+                    // Guard against clobbering a newer turn that already replaced us.
+                    if (this.activeTurns.get(sessionId) === turnPromise) {
+                        this.activeTurns.delete(sessionId);
+                    }
+                    if (this.turnAborts.get(sessionId) === abort) {
+                        this.turnAborts.delete(sessionId);
+                    }
+                });
+            }
+            finally {
+                this.pendingTurns.delete(sessionId);
+            }
+        });
+    }
+    /**
+     * Cancel the turn in flight for `sessionId` (if any) and wait for it to
+     * settle, so its SDK run is terminal before the next turn's send. Safe to
+     * call when nothing is running.
+     */
+    interruptActiveTurn(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            (_a = this.turnAborts.get(sessionId)) === null || _a === void 0 ? void 0 : _a.abort();
+            const active = this.activeTurns.get(sessionId);
+            if (active !== undefined) {
+                yield active.catch(() => { });
+            }
+        });
+    }
+    /**
+     * Abort the in-flight turn without starting a follow-up. Returns whether
+     * a turn was active (or pending abort) when called.
+     */
+    interrupt(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const hadWork = this.turnAborts.has(sessionId) || this.activeTurns.has(sessionId);
+            yield this.interruptActiveTurn(sessionId);
+            return hadWork;
+        });
+    }
+    /**
+     * Local harness cwd for a session: per-send override, else
+     * `<agent.local.cwd>/<sessionId>`, else the durable session workspace.
+     */
+    harnessCwd(record) {
+        var _a;
+        if (record.workspaceOverride !== undefined) {
+            return record.workspaceOverride;
+        }
+        const agentCwd = (_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.cwd;
+        if (agentCwd !== undefined) {
+            return join(agentCwd, record.sessionId);
+        }
+        return this.sessions.workspaceDir(record.sessionId);
+    }
+    /**
+     * Directory that receives AGENTS.md / skills / agent tools. When the
+     * harness cwd is a one-off override (e.g. PR worktree), scaffold stays in
+     * the durable session workspace; otherwise scaffold lands in the harness.
+     */
+    scaffoldDir(record) {
+        if (record.workspaceOverride !== undefined) {
+            return this.sessions.workspaceDir(record.sessionId);
+        }
+        return this.harnessCwd(record);
+    }
+    executeTurn(record, turnId, message, isFirstTurn, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e;
+            const sessionId = record.sessionId;
+            const workspaceDir = this.scaffoldDir(record);
+            const harnessCwd = this.harnessCwd(record);
+            // Hold the open log so tool events append synchronously. Fire-and-forget
+            // `appendEvent` races parallel tool completions and delays the live stream
+            // until the next await tick — often after *all* parallel tools finish.
+            const log = yield this.logs.get(sessionId);
+            const emit = (payload) => {
+                try {
+                    const event = log.append(Object.assign(Object.assign({}, payload), { turnId }));
+                    this.queueDispatch(sessionId, event);
+                }
+                catch (error) {
+                    this.logger(`[agent-serve] failed to record event for ${sessionId}: ${describeError(error)}`);
+                }
+            };
+            const mapper = new TurnEventMapper(emit);
+            let outcome;
+            try {
+                // Scaffold agent files into the session workspace even when the harness
+                // cwd is overridden (e.g. a PR worktree). A/B variant instruction
+                // overlays are applied via agentForSession.
+                const agent = this.agentForSession(record);
+                yield materializeWorkspace({
+                    agent,
+                    workspaceDir,
+                    seed: isFirstTurn,
+                });
+                const pendingFiles = record.pendingWorkspaceFiles;
+                if (pendingFiles !== undefined && Object.keys(pendingFiles).length > 0) {
+                    yield writeWorkspaceFiles(harnessCwd, pendingFiles);
+                    yield this.updateRecord(sessionId, (current) => {
+                        const { pendingWorkspaceFiles: _cleared } = current, rest = __rest(current, ["pendingWorkspaceFiles"]);
+                        return rest;
+                    });
+                }
+                const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                    mapper.handleUpdate(update);
+                    // Yield so the HTTP NDJSON writer can flush tool start/result
+                    // events while sibling parallel tools are still executing.
+                    if (update.type === "tool-call-started" ||
+                        update.type === "tool-call-completed") {
+                        yield yieldEventLoop();
+                    }
+                }), signal);
+                outcome = yield this.runner.runTurn(request);
+            }
+            catch (error) {
+                this.approvals.cancelSession(sessionId, "deny");
+                outcome = { status: "error", errorMessage: describeError(error) };
+            }
+            finally {
+                this.approvals.cancelSession(sessionId, "deny");
+                yield this.clearPendingApprovals(sessionId);
+            }
+            mapper.finish();
+            if (mapper.title !== undefined) {
+                const title = mapper.title;
+                yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { title })));
+            }
+            const finalResult = (_a = outcome.result) !== null && _a !== void 0 ? _a : mapper.finalText;
+            const finalUsage = (_b = outcome.usage) !== null && _b !== void 0 ? _b : mapper.usage;
+            if (outcome.status === "finished") {
+                yield this.appendEvent(sessionId, {
+                    type: "turn.completed",
+                    turnId,
+                    data: Object.assign(Object.assign({}, (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage })),
+                });
+            }
+            else {
+                const interrupted = signal.aborted && outcome.status === "cancelled";
+                yield this.appendEvent(sessionId, {
+                    type: "turn.failed",
+                    turnId,
+                    data: {
+                        message: interrupted
+                            ? "turn interrupted"
+                            : ((_c = outcome.errorMessage) !== null && _c !== void 0 ? _c : (outcome.status === "cancelled"
+                                ? "turn cancelled"
+                                : "turn failed")),
+                    },
+                });
+            }
+            const current = yield this.sessions.get(sessionId);
+            const mode = (_d = current === null || current === void 0 ? void 0 : current.mode) !== null && _d !== void 0 ? _d : record.mode;
+            if (mode === "task") {
+                yield this.appendEvent(sessionId, outcome.status === "finished"
+                    ? { type: "session.completed", turnId, data: {} }
+                    : {
+                        type: "session.failed",
+                        turnId,
+                        data: { message: (_e = outcome.errorMessage) !== null && _e !== void 0 ? _e : "task failed" },
+                    });
+            }
+            else {
+                yield this.appendEvent(sessionId, {
+                    type: "session.waiting",
+                    turnId,
+                    data: {},
+                });
+            }
+            return Object.assign(Object.assign(Object.assign({}, outcome), (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage }));
+        });
+    }
+    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, emit, onUpdate, signal) {
+        var _a;
+        var _b;
+        // Per-session cloud attach (channel/tool handoff) forces cloud runtime
+        // even when the agent defaults to local for chat server tools.
+        const runtime = resolveSessionRuntime({
+            agentRuntime: agent.runtime,
+            cloudOverride: record.cloudOverride,
+        });
+        const mergedCloud = runtime === "cloud"
+            ? mergeCloudOptions({
+                base: agent.cloud,
+                override: record.cloudOverride,
+            })
+            : undefined;
+        let turnPrompt = prompt;
+        if (runtime === "cloud" && isFirstTurn) {
+            const preamble = [
+                (_b = (_a = agent.instructions) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "",
+                buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
+            ]
+                .filter((part) => part !== "")
+                .join("\n\n");
+            turnPrompt = preamble === "" ? prompt : `${preamble}\n\n${prompt}`;
+        }
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
+            ? {}
+            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime), subagents: agent.subagents.map((subagent) => { var _a; return (Object.assign({ name: subagent.name, description: (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name, prompt: subagentPrompt(subagent) }, (subagent.model === undefined ? {} : { model: subagent.model }))); }), onUpdate,
+            signal, 
+            // Local follow-ups expire any lingering active run so a preempted turn
+            // (or one orphaned by a crashed process) never blocks this send.
+            forceExpireActiveRun: runtime === "local" && !isFirstTurn, onSdkAgentId: (sdkAgentId) => __awaiter(this, void 0, void 0, function* () {
+                if (record.sdkAgentId === sdkAgentId) {
+                    return;
+                }
+                yield this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { sdkAgentId })));
+                record.sdkAgentId = sdkAgentId;
+                yield this.appendEvent(record.sessionId, {
+                    type: "agent.bound",
+                    turnId,
+                    data: Object.assign({ sdkAgentId }, (sdkAgentId.startsWith("bc-")
+                        ? { url: `https://cursor.com/agents/${sdkAgentId}` }
+                        : {})),
+                });
+            }) });
+    }
+    /**
+     * MCP servers for a turn: authored concrete connections plus resolved
+     * serve-time resolved connections (peers, Cursor account bridge).
+     * Resolved connections pick their URL by runtime — loopback for local
+     * turns, `cloudUrl` for cloud turns — and are omitted from cloud turns
+     * when no cloud URL exists unless a `servers` filter requires the bridge
+     * (see {@link assertCloudCanHonorAccountServersFilters}).
+     */
+    buildMcpServers(runtime) {
+        assertCloudCanHonorAccountServersFilters({
+            runtime,
+            resolvedConnections: this.resolvedConnections,
+        });
+        const servers = {};
+        for (const connection of this.project.agent.connections) {
+            if (isSymbolicConnectionTransport(connection.transport)) {
+                continue;
+            }
+            servers[connection.name] = connection.transport;
+        }
+        for (const resolved of this.resolvedConnections) {
+            const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
+            if (url === undefined) {
+                continue;
+            }
+            servers[resolved.name] = Object.assign({ url }, (resolved.headers === undefined
+                ? {}
+                : { headers: resolved.headers }));
+        }
+        return servers;
+    }
+    buildCustomTools(record, turnId, emit) {
+        const tools = {};
+        for (const tool of this.project.agent.tools) {
+            if (tool.execution !== "server") {
+                continue;
+            }
+            const execute = tool.definition.execute;
+            if (typeof execute !== "function") {
+                continue;
+            }
+            tools[tool.name] = {
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const validation = validateToolInput(tool.definition.inputSchema, args);
+                    if (!validation.ok) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Invalid input for tool "${tool.name}": ${validation.message}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const toolCallId = (_a = context.toolCallId) !== null && _a !== void 0 ? _a : newToolCallId(tool.name);
+                    const toolCtx = {
+                        toolCallId,
+                        session: this.sessionInfo(record),
+                        workspaceDir: this.harnessCwd(record),
+                        host: this.host,
+                        send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
+                                ? sendOptions.auth
+                                : record.auth })),
+                        getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
+                    };
+                    try {
+                        const needsGate = yield evaluateNeedsApproval(tool.definition.needsApproval, validation.value);
+                        if (needsGate) {
+                            const decision = yield this.parkForApproval({
+                                sessionId: record.sessionId,
+                                turnId,
+                                callId: toolCallId,
+                                toolName: tool.name,
+                                args: validation.value,
+                                emit,
+                            });
+                            if (decision === "deny") {
+                                return {
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: `Tool "${tool.name}" was denied by a human approver.`,
+                                        },
+                                    ],
+                                    isError: true,
+                                };
+                            }
+                        }
+                        const started = Date.now();
+                        this.logger(`[session] tool ${tool.name} start`);
+                        const result = yield execute(validation.value, toolCtx);
+                        this.logger(`[session] tool ${tool.name} done (${Date.now() - started}ms)`);
+                        return normalizeToolResult(result);
+                    }
+                    catch (error) {
+                        this.logger(`[session] tool ${tool.name} failed: ${describeError(error)}`);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Tool "${tool.name}" failed: ${describeError(error)}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }),
+            };
+        }
+        return tools;
+    }
+    /**
+     * Park a server-tool call until a human approves or denies. Emits
+     * `action.approval_requested` / `action.approval_resolved` on the
+     * held turn log so the playground and stream see the gate.
+     */
+    parkForApproval(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const requestedAt = new Date().toISOString();
+            const pendingRecord = {
+                callId: args.callId,
+                turnId: args.turnId,
+                toolName: args.toolName,
+                args: args.args,
+                requestedAt,
+            };
+            const resolutionPromise = this.approvals.wait(Object.assign({ sessionId: args.sessionId }, pendingRecord));
+            yield this.updateRecord(args.sessionId, (current) => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: [
+                    ...((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter((item) => item.callId !== args.callId),
+                    pendingRecord,
+                ] })); });
+            args.emit({
+                type: "action.approval_requested",
+                data: {
+                    callId: args.callId,
+                    toolName: args.toolName,
+                    args: args.args,
+                },
+            });
+            this.logger(`[session] tool ${args.toolName} awaiting approval (${args.callId})`);
+            const { decision, by } = yield resolutionPromise;
+            yield this.updateRecord(args.sessionId, (current) => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: ((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter((item) => item.callId !== args.callId) })); });
+            args.emit({
+                type: "action.approval_resolved",
+                data: Object.assign({ callId: args.callId, toolName: args.toolName, decision }, (by === undefined ? {} : { by })),
+            });
+            this.logger(`[session] tool ${args.toolName} approval ${decision} (${args.callId})`);
+            return decision;
+        });
+    }
+    clearPendingApprovals(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const current = yield this.sessions.get(sessionId);
+            if (current === undefined ||
+                current.pendingApprovals === undefined ||
+                current.pendingApprovals.length === 0) {
+                return;
+            }
+            yield this.updateRecord(sessionId, (record) => (Object.assign(Object.assign({}, record), { pendingApprovals: [] })));
+        });
+    }
+    /** Pending tool approvals for a session (live waiters ∪ persisted). */
+    listPendingApprovals(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return [];
+            }
+            const live = this.approvals.list(sessionId);
+            if (live.length > 0) {
+                return live;
+            }
+            return (_a = record.pendingApprovals) !== null && _a !== void 0 ? _a : [];
+        });
+    }
+    /**
+     * Approve or deny a parked server-tool call. Unblocks the in-flight
+     * SDK custom-tool callback for the same `callId`.
+     *
+     * Pass `asSessionOwner: true` only from an explicit host bridge (e.g. `--dev`
+     * playground resolving a Slack-owned parked tool). Ownership is checked
+     * against the stored session principal; `by` still records the clicker.
+     */
+    resolveApproval(sessionId, callId, decision, auth, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                throw new ApprovalNotFoundError(sessionId, callId);
+            }
+            const ownershipAuth = (options === null || options === void 0 ? void 0 : options.asSessionOwner) === true ? record.auth : auth;
+            if (!samePrincipal(record.auth, ownershipAuth)) {
+                throw new SessionAuthError(sessionId);
+            }
+            const pending = (_b = ((_a = record.pendingApprovals) !== null && _a !== void 0 ? _a : []).find((item) => item.callId === callId)) !== null && _b !== void 0 ? _b : this.approvals.list(sessionId).find((item) => item.callId === callId);
+            if (pending === undefined) {
+                throw new ApprovalNotFoundError(sessionId, callId);
+            }
+            const resolvedBy = approvalResolverLabel(auth);
+            if (!this.approvals.resolve(sessionId, callId, decision, resolvedBy)) {
+                yield this.removePendingApproval(sessionId, callId);
+                throw new ApprovalInterruptedError(sessionId, callId);
+            }
+            return pending;
+        });
+    }
+    removePendingApproval(sessionId, callId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, (current) => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: ((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter((item) => item.callId !== callId) })); });
+        });
+    }
+    // ==========================================================================
+    // Direct tool calls (deterministic invocation, no model turn)
+    // ==========================================================================
+    /**
+     * Call an authored server tool deterministically: validate `input`
+     * against the tool's schema (zod schemas validate and transform; plain
+     * JSON Schema inputs pass through unvalidated, matching the model path),
+     * run `execute` in-process, and return the normalized result exactly as
+     * the model would receive it.
+     *
+     * With `options.sessionId` the tool runs inside that session (its info
+     * and materialized workspace) and the call is recorded on the session's
+     * event stream as `actions.requested` / `action.result` under a
+     * per-call `turnId` (the call id), so it shows up in trajectories.
+     * Rejected with {@link SessionBusyError} while a model turn is running.
+     * Without a session, the tool runs against an **ephemeral** scratch
+     * workspace under `<stateRoot>/tool-calls/<callId>` (materialized with
+     * seed files, removed after the call returns).
+     *
+     * Throws {@link UnknownToolError}, {@link ToolNotDirectlyCallableError},
+     * {@link ToolInputError}, or {@link UnknownSessionError} before the tool
+     * body runs; a tool body that throws is reported as an `isError` outcome
+     * with the same `{ content, isError }` envelope the model would see, not
+     * an exception.
+     */
+    callTool(toolName_1) {
+        return __awaiter(this, arguments, void 0, function* (toolName, input = {}, options = {}) {
+            var _a;
+            const tool = this.project.agent.tools.find((t) => t.name === toolName);
+            if (tool === undefined) {
+                throw new UnknownToolError(toolName, this.project.agent.tools
+                    .filter((t) => t.execution === "server")
+                    .map((t) => t.name));
+            }
+            const execute = tool.definition.execute;
+            if (tool.execution !== "server" || typeof execute !== "function") {
+                throw new ToolNotDirectlyCallableError(toolName);
+            }
+            const validation = validateToolInput(tool.definition.inputSchema, input);
+            if (!validation.ok) {
+                throw new ToolInputError({ toolName, detail: validation.message });
+            }
+            const callId = newToolCallId(toolName);
+            const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : null;
+            let record;
+            let session;
+            let workspaceDir;
+            let scratchDir;
+            if (options.sessionId !== undefined) {
+                record = yield this.sessions.get(options.sessionId);
+                if (record === undefined) {
+                    throw new UnknownSessionError(options.sessionId);
+                }
+                // Direct calls respect the same serialization as follow-up sends: a
+                // running model turn owns the session workspace and event stream.
+                if (this.activeTurns.has(record.sessionId) ||
+                    this.pendingTurns.has(record.sessionId)) {
+                    throw new SessionBusyError(record.sessionId);
+                }
+                session = this.sessionInfo(record);
+                workspaceDir = this.harnessCwd(record);
+            }
+            else {
+                session = {
+                    id: callId,
+                    channelId: DIRECT_TOOL_CALL_CHANNEL_ID,
+                    mode: "task",
+                    auth,
+                };
+                scratchDir = join(this.stateRoot, "tool-calls", callId);
+                workspaceDir = scratchDir;
+            }
+            yield mkdir(workspaceDir, { recursive: true });
+            // Match what a model turn would see: session workspaces get the same
+            // scaffold as executeTurn (seeds only before the first turn); scratch
+            // workspaces are materialized fresh.
+            yield materializeWorkspace({
+                agent: this.project.agent,
+                workspaceDir: record === undefined ? workspaceDir : this.scaffoldDir(record),
+                seed: record === undefined || record.turnCount === 0,
+            });
+            // A per-call turnId keeps these events visible in trajectories (which
+            // drop turn-less action events) without attributing them to a model turn.
+            if (record !== undefined) {
+                yield this.appendEvent(record.sessionId, {
+                    type: "actions.requested",
+                    turnId: callId,
+                    data: { calls: [{ callId, toolName, args: validation.value }] },
+                });
+            }
+            const started = Date.now();
+            this.logger(`[session] tool ${toolName} start (direct ${callId})`);
+            let result;
+            let isError;
+            try {
+                result = normalizeToolResult(yield execute(validation.value, {
+                    toolCallId: callId,
+                    session,
+                    workspaceDir,
+                    host: this.host,
+                    send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
+                            ? sendOptions.auth
+                            : session.auth })),
+                    getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
+                }));
+                isError = isErrorEnvelope(result);
+            }
+            catch (error) {
+                this.logger(`[session] tool ${toolName} failed (direct ${callId}): ${describeError(error)}`);
+                // Same envelope the model path returns for a throwing tool body.
+                result = {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Tool "${toolName}" failed: ${describeError(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+                isError = true;
+            }
+            finally {
+                if (scratchDir !== undefined) {
+                    yield rm(scratchDir, { recursive: true, force: true }).catch(() => { });
+                }
+            }
+            const durationMs = Date.now() - started;
+            this.logger(`[session] tool ${toolName} done (direct ${callId}, ${durationMs}ms)`);
+            if (record !== undefined) {
+                yield this.appendEvent(record.sessionId, {
+                    type: "action.result",
+                    turnId: callId,
+                    data: { callId, toolName, output: result, isError },
+                });
+            }
+            const errorMessage = isError ? toolCallErrorMessage(result) : undefined;
+            return Object.assign(Object.assign({ toolName,
+                callId,
+                isError,
+                result,
+                durationMs }, (errorMessage === undefined ? {} : { errorMessage })), (record === undefined ? {} : { sessionId: record.sessionId }));
+        });
+    }
+    // ==========================================================================
+    // Events: append, dispatch to channel handlers + hooks
+    // ==========================================================================
+    appendEvent(sessionId, payload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const log = yield this.logs.get(sessionId);
+            const event = log.append(payload);
+            this.queueDispatch(sessionId, event);
+            return event;
+        });
+    }
+    queueDispatch(sessionId, event) {
+        var _a;
+        const chain = (_a = this.dispatchChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const next = chain
+            .then(() => this.dispatchEvent(sessionId, event))
+            .catch((error) => {
+            this.logger(`[agent-serve] event dispatch failed for ${sessionId}: ${describeError(error)}`);
+        });
+        this.dispatchChains.set(sessionId, next);
+    }
+    dispatchEvent(sessionId, event) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return;
+            }
+            const sessionCtx = { session: this.sessionInfo(record) };
+            const channelEvents = this.channelEventHandlersFor(record.channelId);
+            if (channelEvents !== undefined) {
+                // Handlers are declared against the narrowed event for their key; the
+                // dispatch key always matches, so widening here is sound.
+                const handlers = [
+                    channelEvents[event.type],
+                    channelEvents["*"],
+                ];
+                const channelCtx = {
+                    channelId: record.channelId,
+                    state: ((_a = record.channelState) !== null && _a !== void 0 ? _a : null),
+                    continuationToken: record.continuationKey,
+                    setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
+                };
+                for (const handler of handlers) {
+                    if (handler === undefined) {
+                        continue;
+                    }
+                    try {
+                        yield handler(event, channelCtx, sessionCtx);
+                    }
+                    catch (error) {
+                        this.logger(`[agent-serve] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`);
+                    }
+                }
+                // Handlers mutate channel state in place; persist after each batch.
+                yield this.updateRecord(sessionId, (current) => (Object.assign({}, current)));
+            }
+            for (const hook of this.project.hooks) {
+                const handlers = [
+                    hook.definition.events[event.type],
+                    hook.definition.events["*"],
+                ];
+                for (const handler of handlers) {
+                    if (handler === undefined) {
+                        continue;
+                    }
+                    try {
+                        yield handler(event, {
+                            agent: { name: this.project.name },
+                            channel: {
+                                id: record.channelId,
+                                continuationToken: record.continuationKey,
+                            },
+                            session: this.sessionInfo(record),
+                        });
+                    }
+                    catch (error) {
+                        this.logger(`[agent-serve] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
+                    }
+                }
+            }
+            if (this.abCollector.enabled) {
+                yield this.abCollector.onEvent(event, this.sessionInfo(record), this.project.name);
+            }
+        });
+    }
+    channelEventHandlersFor(channelId) {
+        var _a;
+        if (channelId === HTTP_CHANNEL_ID) {
+            return this.project.httpChannel.events;
+        }
+        return (_a = this.channelsById.get(channelId)) === null || _a === void 0 ? void 0 : _a.events;
+    }
+    // ==========================================================================
+    // Session handles
+    // ==========================================================================
+    waitForCompletion(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Drain admission first so pendingTurns → activeTurns is visible before we
+            // decide the session is idle (reminders use this for queueBehindTurn).
+            const chain = this.admissionChains.get(sessionId);
+            if (chain !== undefined) {
+                yield chain.catch(() => { });
+            }
+            const active = this.activeTurns.get(sessionId);
+            if (active !== undefined) {
+                return active;
+            }
+            return (_a = this.lastOutcomes.get(sessionId)) !== null && _a !== void 0 ? _a : { status: "finished" };
+        });
+    }
+    /**
+     * Sessions visible to `caller`, newest first (`GET /v1/sessions`).
+     * Callers only see sessions whose stored principal matches — except when
+     * `includeAll` is set (dev mode), where the listing becomes a full
+     * observability surface across every principal (channel-driven runs,
+     * schedule/task sessions, other callers). The route auth chain still
+     * gates who may call this at all.
+     */
+    listSessions(caller, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const includeAll = (_a = options === null || options === void 0 ? void 0 : options.includeAll) !== null && _a !== void 0 ? _a : false;
+            const records = yield this.sessions.list();
+            return records
+                .filter((record) => includeAll || samePrincipal(record.auth, caller))
+                .map((record) => {
+                const externalUrl = externalUrlForSession(record);
+                return Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId, channelId: record.channelId, mode: record.mode }, (record.title === undefined ? {} : { title: record.title })), { turnCount: record.turnCount, running: this.activeTurns.has(record.sessionId) ||
+                        this.pendingTurns.has(record.sessionId), createdAt: record.createdAt, updatedAt: record.updatedAt, continuationToken: record.continuationKey === null
+                        ? null
+                        : formatContinuationToken(record.channelId, record.continuationKey) }), (externalUrl === undefined ? {} : { externalUrl }));
+            })
+                .reverse();
+        });
+    }
+    /**
+     * Fold durable session streams into per-session A/B assignments and
+     * aggregate arm metrics (`GET /v1/abs`). Collector-independent: always
+     * reads `events.ndjson`.
+     */
+    abSnapshot(caller, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sessions = yield this.listSessions(caller, options);
+            const abConfig = this.project.abConfig;
+            const maxPlaygroundSessions = resolveABMaxPlaygroundSessions(abConfig === null || abConfig === void 0 ? void 0 : abConfig.maxPlaygroundSessions);
+            const foldedSessions = sessions.slice(0, maxPlaygroundSessions);
+            const snapshot = yield buildABSnapshot({
+                experiments: this.project.abs,
+                agentName: this.project.name,
+                sessions: foldedSessions,
+                loadRecord: (sessionId) => this.sessions.get(sessionId),
+                loadEvents: (sessionId) => this.listEvents(sessionId, 0),
+                sessionInfo: (record) => this.sessionInfo(record),
+                logger: this.logger,
+                config: {
+                    maxPlaygroundSessions,
+                    durableSamples: (abConfig === null || abConfig === void 0 ? void 0 : abConfig.persistSamples) !== undefined,
+                    durableSnapshots: (abConfig === null || abConfig === void 0 ? void 0 : abConfig.persistSnapshots) !== undefined,
+                },
+            });
+            // Side effect on the read path: playground polls GET /v1/abs ~every 4s.
+            // Authors who set persistSnapshots accept that write cadence.
+            const persistSnapshots = abConfig === null || abConfig === void 0 ? void 0 : abConfig.persistSnapshots;
+            if (persistSnapshots !== undefined) {
+                try {
+                    yield persistSnapshots.save(snapshot, {
+                        projectRoot: this.project.rootDir,
+                    });
+                }
+                catch (error) {
+                    this.logger(`[agent-serve] ab persistSnapshots.save threw: ${describeError(error)}`);
+                }
+            }
+            return snapshot;
+        });
+    }
+    eventStream(sessionId_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, startIndex = 0) {
+            const log = yield this.logs.get(sessionId);
+            return log.stream(startIndex);
+        });
+    }
+    /**
+     * Append an assistant message to a session transcript without a model turn
+     * and without a user `message.received` bubble. Used by host-driven channel
+     * tasks (e.g. webhook stages) to publish a final summary.
+     */
+    emitAssistantMessage(sessionId, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isTurnRunning(sessionId)) {
+                throw new SessionBusyError(sessionId);
+            }
+            const existing = yield this.sessions.get(sessionId);
+            if (existing === undefined) {
+                throw new Error(`Unknown session: ${sessionId}`);
+            }
+            const record = yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
+            const turnId = `turn_${record.turnCount}`;
+            yield this.appendEvent(sessionId, {
+                type: "turn.started",
+                turnId,
+                data: {},
+            });
+            yield this.appendEvent(sessionId, {
+                type: "message.completed",
+                turnId,
+                data: { text, finishReason: "stop" },
+            });
+            yield this.appendEvent(sessionId, {
+                type: "turn.completed",
+                turnId,
+                data: { result: text },
+            });
+            yield this.appendEvent(sessionId, {
+                type: "session.waiting",
+                data: {},
+            });
+            this.lastOutcomes.set(sessionId, {
+                status: "finished",
+                result: text,
+            });
+        });
+    }
+    /** Snapshot of recorded events (for download / offline trace). */
+    listEvents(sessionId_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, startIndex = 0) {
+            const log = yield this.logs.get(sessionId);
+            return log.snapshot(startIndex);
+        });
+    }
+    setContinuationToken(sessionId, token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { continuationKey: token })));
+        });
+    }
+    isTurnRunning(sessionId) {
+        // Include the admit window (pendingTurns) so busy policies do not treat a
+        // turn that has been accepted but not yet marked active as idle.
+        return this.activeTurns.has(sessionId) || this.pendingTurns.has(sessionId);
+    }
+    sessionInfo(record) {
+        return Object.assign(Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live", auth: record.auth, continuationKey: record.continuationKey }, (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
+            ? {}
+            : { sdkAgentId: record.sdkAgentId }));
+    }
+    channelSession(sessionId, record, isNew) {
+        return {
+            id: sessionId,
+            continuationToken: record.continuationKey,
+            isNew,
+            info: this.sessionInfo(record),
+            getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : 0); },
+            waitForCompletion: () => this.waitForCompletion(sessionId),
+            setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
+        };
+    }
+    resolveChannelId(channel) {
+        if (typeof channel === "string") {
+            if (channel !== HTTP_CHANNEL_ID &&
+                !this.channelsById.has(channel) &&
+                !channel.startsWith(SCHEDULE_CHANNEL_PREFIX)) {
+                throw new UnknownChannelError(channel);
+            }
+            return channel;
+        }
+        if (channel.__agentServe === "http-channel") {
+            return HTTP_CHANNEL_ID;
+        }
+        for (const [id, definition] of this.channelsById) {
+            if (definition === channel) {
+                return id;
+            }
+        }
+        throw new UnknownChannelError("<unregistered channel definition>");
+    }
+    initialChannelState(channelId, override) {
+        if (override !== undefined) {
+            return structuredClone(override);
+        }
+        const definition = this.channelsById.get(channelId);
+        if ((definition === null || definition === void 0 ? void 0 : definition.state) === undefined) {
+            return undefined;
+        }
+        return structuredClone(definition.state);
+    }
+    /** Serialized, immutable record updates (latest-wins per session). */
+    updateRecord(sessionId, updater) {
+        var _a;
+        const chain = (_a = this.updateChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const next = chain.then(() => __awaiter(this, void 0, void 0, function* () {
+            const current = yield this.sessions.get(sessionId);
+            if (current === undefined) {
+                throw new Error(`Session ${sessionId} not found`);
+            }
+            const updated = Object.assign(Object.assign({}, updater(current)), { updatedAt: new Date().toISOString() });
+            yield this.sessions.save(updated);
+            return updated;
+        }));
+        this.updateChains.set(sessionId, next.catch(() => { }));
+        return next;
+    }
+    // ==========================================================================
+    // Lifecycle
+    // ==========================================================================
+    trackBackground(promise) {
+        this.backgroundWork.add(promise);
+        void promise
+            .catch(() => { })
+            .finally(() => {
+            this.backgroundWork.delete(promise);
+        });
+    }
+    /** Drain running turns, dispatches, and pending writes, then dispose. */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            this.approvals.cancelAll("deny");
+            yield Promise.allSettled([...this.activeTurns.values()]);
+            yield Promise.allSettled([...this.backgroundWork]);
+            yield Promise.allSettled([...this.dispatchChains.values()]);
+            yield Promise.allSettled([...this.updateChains.values()]);
+            yield this.logs.flushAll();
+            yield this.mcpHost.close();
+            yield (_b = (_a = this.runner).dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
+        });
+    }
+}
+function subagentPrompt(subagent) {
+    var _a;
+    if (subagent.instructions !== undefined && subagent.instructions !== "") {
+        return subagent.instructions;
+    }
+    return (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Detects the `{ content, isError: true }` rich-result error envelope. */
+function isErrorEnvelope(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        !Array.isArray(result) &&
+        Array.isArray(result.content) &&
+        result.isError === true);
+}
+function evaluateNeedsApproval(needsApproval, input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (needsApproval === undefined || needsApproval === false) {
+            return false;
+        }
+        if (needsApproval === true) {
+            return true;
+        }
+        return Boolean(yield needsApproval(input));
+    });
+}
+function approvalResolverLabel(auth) {
+    var _a;
+    if (auth === null) {
+        return undefined;
+    }
+    const slackUser = (_a = auth.attributes) === null || _a === void 0 ? void 0 : _a.user_id;
+    if (auth.authenticator === "slack" &&
+        slackUser !== undefined &&
+        slackUser !== "") {
+        return slackUser;
+    }
+    return auth.principalId;
+}
+/** Deep link to the external conversation (Slack thread today). */
+function externalUrlForSession(record) {
+    var _a, _b, _c;
+    var _d, _e;
+    const auth = record.auth;
+    if (auth === null || auth.authenticator !== "slack") {
+        return undefined;
+    }
+    const channelId = (_d = (_a = auth.attributes) === null || _a === void 0 ? void 0 : _a.channel_id) !== null && _d !== void 0 ? _d : "";
+    const threadTs = (_e = (_b = auth.attributes) === null || _b === void 0 ? void 0 : _b.thread_ts) !== null && _e !== void 0 ? _e : "";
+    const teamId = (_c = auth.attributes) === null || _c === void 0 ? void 0 : _c.team_id;
+    const url = slackThreadPermalink(Object.assign({ channelId,
+        threadTs }, (teamId === undefined ? {} : { teamId })));
+    return url !== null && url !== void 0 ? url : undefined;
+}
+/** Let the HTTP NDJSON writer flush before the next SDK update. */
+function yieldEventLoop() {
+    return new Promise((resolve) => {
+        setImmediate(resolve);
+    });
+}