@cursor/july 0.1.1

package/src/internal/session-engine.ts

@@ -0,0 +1,1810 @@
+/**
+ * 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.
+ */
+
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { SDKCustomTool } from "@cursor/sdk";
+import {
+  type ABDefinition,
+  mergeABInstructions,
+  resolveABMaxPlaygroundSessions,
+  resolveABSplit,
+} from "../ab.js";
+import { slackThreadPermalink } from "../channels/slack/links.js";
+import {
+  type AgentProject,
+  type ApprovalDecision,
+  type AuthContext,
+  type CallToolOptions,
+  type ChannelDefinition,
+  type ChannelEventHandler,
+  type ChannelSession,
+  type ConnectionTransport,
+  DIRECT_TOOL_CALL_CHANNEL_ID,
+  type HookHandler,
+  type HostContext,
+  type HttpChannelDefinition,
+  isSymbolicConnectionTransport,
+  type JsonValue,
+  type PendingApproval,
+  type ReceiveInput,
+  type ResolvedAgent,
+  type RunnerTurnRequest,
+  type SendMessageFn,
+  type SendMessageOptions,
+  type SessionEvent,
+  type SessionEventPayload,
+  type SessionInfo,
+  type SessionRecord,
+  type SessionSummary,
+  type ToolCallOutcome,
+  type ToolContext,
+  type ToolNeedsApproval,
+  type TurnOutcome,
+} from "../types.js";
+import { ABCollector } from "./ab-collector.js";
+import { foldABStream } from "./ab-fold.js";
+import { type ABSnapshot, 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, type HostPlatforms } 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 type { AgentRunner } from "./sdk-runner.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: string) {
+    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: string) {
+    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: string) {
+    super(`Unknown channel "${channelId}"`);
+    this.name = "UnknownChannelError";
+  }
+}
+
+export class UnknownToolError extends Error {
+  constructor(
+    toolName: string,
+    readonly availableToolNames: string[]
+  ) {
+    super(`Unknown tool "${toolName}"`);
+    this.name = "UnknownToolError";
+  }
+}
+
+export class ToolNotDirectlyCallableError extends Error {
+  constructor(toolName: string) {
+    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: { toolName: string; detail: string }) {
+    super(`Invalid input for tool "${args.toolName}": ${args.detail}`);
+    this.name = "ToolInputError";
+  }
+}
+
+export class UnknownSessionError extends Error {
+  constructor(sessionId: string) {
+    super(`Unknown session ${sessionId}`);
+    this.name = "UnknownSessionError";
+  }
+}
+
+export class ApprovalNotFoundError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(`No pending approval for session ${sessionId} call ${callId}`);
+    this.name = "ApprovalNotFoundError";
+  }
+}
+
+export class ApprovalInterruptedError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(
+      `Approval for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`
+    );
+    this.name = "ApprovalInterruptedError";
+  }
+}
+
+export interface SessionEngineOptions {
+  project: AgentProject;
+  stateRoot: string;
+  runner: AgentRunner;
+  logger?: (line: string) => void;
+}
+
+/**
+ * A connection the serve host resolved once it was listening — a **peer**
+ * (`defineConnection({ agent })` mapped to the target agent's MCP endpoint)
+ * or the **Cursor account bridge** (`defineConnection({ cursorAccount })`
+ * mapped to the loopback bridge route). Local turns (and host-side MCP
+ * calls) use {@link localUrl}; cloud turns use {@link cloudUrl} when the
+ * serve host configured a public URL (peers and the account bridge).
+ */
+export interface EngineResolvedConnection {
+  /** MCP server name the model sees (the connection filename). */
+  name: string;
+  /** Loopback MCP URL, e.g. `http://127.0.0.1:3000/<slug>/v1/mcp`. */
+  localUrl: string;
+  /** Publicly reachable MCP URL for cloud turns, when configured. */
+  cloudUrl?: string;
+  /** Auth headers calls must present (host bearer / bridge secret). */
+  headers?: Record<string, string>;
+  /**
+   * When set, cloud turns must reach the account bridge via {@link cloudUrl}
+   * so the filter is enforced — omitting the bridge must not fail open to
+   * the account's broader native connector set.
+   */
+  accountServersFilter?: readonly string[];
+}
+
+export interface EngineSendOptions extends SendMessageOptions {
+  mode?: "chat" | "task";
+}
+
+export class SessionEngine {
+  readonly project: AgentProject;
+  readonly stateRoot: string;
+  readonly sessions: SessionStore;
+
+  private readonly runner: AgentRunner;
+  private readonly logger: (line: string) => void;
+  private readonly logs: EventLogStore;
+  private readonly channelsById = new Map<string, ChannelDefinition>();
+  /** Sessions with a turn being admitted (before the run promise exists). */
+  private readonly pendingTurns = new Set<string>();
+  private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
+  /** Aborts the in-flight turn per session so a follow-up can preempt it. */
+  private readonly turnAborts = new Map<string, AbortController>();
+  /** Serializes turn admission per session (latest follow-up wins). */
+  private readonly admissionChains = new Map<string, Promise<unknown>>();
+  private readonly lastOutcomes = new Map<string, TurnOutcome>();
+  private readonly updateChains = new Map<string, Promise<unknown>>();
+  private readonly dispatchChains = new Map<string, Promise<void>>();
+  private readonly backgroundWork = new Set<Promise<unknown>>();
+  private readonly mcpHost: McpHost;
+  private readonly platforms: HostPlatforms;
+  private readonly approvals = new ApprovalGate();
+  private readonly abCollector: ABCollector;
+  private reminderApi: HostContext["reminders"];
+  /** Serve-time resolved connections (see {@link setResolvedConnections}). */
+  private resolvedConnections: EngineResolvedConnection[] = [];
+
+  constructor(options: SessionEngineOptions) {
+    this.project = options.project;
+    this.stateRoot = options.stateRoot;
+    this.runner = options.runner;
+    this.logger = options.logger ?? (() => {});
+    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,
+      async (sessionId) => (await this.logs.get(sessionId)).snapshot(0),
+      {
+        projectRoot: options.project.rootDir,
+        ...(options.project.abConfig?.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: EngineResolvedConnection[]): void {
+    this.resolvedConnections = connections;
+    for (const connection of connections) {
+      this.mcpHost.addConnection({
+        name: connection.name,
+        transport: {
+          url: connection.localUrl,
+          ...(connection.headers === undefined
+            ? {}
+            : { headers: connection.headers }),
+        },
+      });
+    }
+  }
+
+  /** Shared host services (MCP / GitHub / Slack / reminders). */
+  get host(): HostContext {
+    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: HostContext["reminders"]): void {
+    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).
+   */
+  async send(
+    channelId: string,
+    message: string,
+    options: EngineSendOptions = {}
+  ): Promise<ChannelSession> {
+    const auth = options.auth ?? null;
+    const existing =
+      options.continuationToken === undefined
+        ? undefined
+        : await 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 = await this.updateRecord(existing.sessionId, (current) => ({
+          ...current,
+          workspaceOverride: options.workspaceDir,
+          pendingWorkspaceFiles:
+            options.workspaceFiles ?? current.pendingWorkspaceFiles,
+        }));
+      } else if (options.workspaceFiles !== undefined) {
+        record = await this.updateRecord(existing.sessionId, (current) => ({
+          ...current,
+          pendingWorkspaceFiles: options.workspaceFiles,
+        }));
+      }
+      await 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: SessionRecord = {
+      sessionId: newSessionId(),
+      channelId,
+      mode: options.mode ?? "chat",
+      purpose,
+      continuationKey: options.continuationToken ?? newContinuationKey(),
+      auth,
+      title: options.title,
+      channelState,
+      workspaceOverride: options.workspaceDir,
+      pendingWorkspaceFiles: options.workspaceFiles,
+      cloudOverride: options.cloud,
+      sdkAgentId: options.sdkAgentId,
+      turnCount: 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+    await this.sessions.save(record);
+    await this.appendEvent(record.sessionId, {
+      type: "session.started",
+      data: { channelId },
+    });
+    record = await this.enrollABs(record);
+    await 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.
+   */
+  private async enrollABs(record: SessionRecord): Promise<SessionRecord> {
+    if (!this.abCollector.enabled || record.purpose === "eval") {
+      return record;
+    }
+    const sessionInfo = this.sessionInfo(record);
+    const abs: Record<string, string | null> = {};
+    for (const experiment of this.project.abs) {
+      const def = experiment.definition as ABDefinition;
+      const variantKeys = Object.keys(def.variants);
+      let variant: string | null = null;
+      try {
+        variant = await 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;
+      await this.appendEvent(record.sessionId, {
+        type: "ab.assigned",
+        data: { experiment: experiment.name, variant },
+      });
+    }
+    return this.updateRecord(record.sessionId, (current) => ({
+      ...current,
+      abs,
+    }));
+  }
+
+  /**
+   * Ensure {@link SessionRecord.abs} is populated (hydrate from the durable
+   * `ab.assigned` stream when missing — e.g. older sessions after upgrade).
+   */
+  private async ensureAbs(record: SessionRecord): Promise<SessionRecord> {
+    if (record.abs !== undefined || record.purpose === "eval") {
+      return record;
+    }
+    if (!this.abCollector.enabled) {
+      return record;
+    }
+    const events = await 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) => ({
+      ...current,
+      abs,
+    }));
+  }
+
+  /**
+   * Agent config for this session: base project agent plus any per-variant
+   * `instructions` overlays from enrolled A/B arms.
+   */
+  private agentForSession(record: SessionRecord): ResolvedAgent {
+    const base = this.project.agent;
+    const instructions = mergeABInstructions(
+      base.instructions,
+      record.abs,
+      this.project.abs.map((experiment) => ({
+        name: experiment.name,
+        definition: experiment.definition as ABDefinition,
+      }))
+    );
+    if (instructions === base.instructions) {
+      return base;
+    }
+    return { ...base, instructions };
+  }
+
+  /** Look up a session as a channel-scoped handle. */
+  async getChannelSession(
+    channelId: string,
+    sessionId: string
+  ): Promise<ChannelSession | null> {
+    const record = await 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). */
+  async receive(
+    channel: ChannelDefinition | HttpChannelDefinition | string,
+    input: ReceiveInput
+  ): Promise<ChannelSession> {
+    const channelId = this.resolveChannelId(channel);
+    const definition = this.channelsById.get(channelId);
+
+    if (definition?.receive !== undefined) {
+      let lastCreated: ChannelSession | undefined;
+      const send: SendMessageFn = async (message, options = {}) => {
+        const session = await this.send(channelId, message, options);
+        lastCreated = session;
+        return session;
+      };
+      const returned = await definition.receive(input, { send });
+      const session = 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). */
+  async runTask(args: {
+    channelId: string;
+    prompt: string;
+    auth: AuthContext | null;
+    title?: string;
+  }): Promise<{ sessionId: string; done: Promise<TurnOutcome> }> {
+    const session = await this.send(args.channelId, args.prompt, {
+      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).
+   */
+  private startTurn(sessionId: string, message: string): Promise<void> {
+    const prior = this.admissionChains.get(sessionId) ?? Promise.resolve();
+    const admitted = prior
+      .catch(() => {})
+      .then(() => this.admitTurn(sessionId, message));
+    this.admissionChains.set(
+      sessionId,
+      admitted.catch(() => {})
+    );
+    return admitted;
+  }
+
+  private async admitTurn(sessionId: string, message: string): Promise<void> {
+    // 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).
+    await this.interruptActiveTurn(sessionId);
+    this.pendingTurns.add(sessionId);
+
+    try {
+      let record = await this.updateRecord(sessionId, (current) => ({
+        ...current,
+        turnCount: current.turnCount + 1,
+      }));
+      // Arms must be on the record before tools/instructions see SessionInfo.
+      record = await this.ensureAbs(record);
+      const turnId = `turn_${record.turnCount}`;
+      const isFirstTurn = record.turnCount === 1;
+
+      await this.appendEvent(sessionId, {
+        type: "message.received",
+        turnId,
+        data: { text: message },
+      });
+      await 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.
+   */
+  private async interruptActiveTurn(sessionId: string): Promise<void> {
+    this.turnAborts.get(sessionId)?.abort();
+    const active = this.activeTurns.get(sessionId);
+    if (active !== undefined) {
+      await active.catch(() => {});
+    }
+  }
+
+  /**
+   * Abort the in-flight turn without starting a follow-up. Returns whether
+   * a turn was active (or pending abort) when called.
+   */
+  async interrupt(sessionId: string): Promise<boolean> {
+    const hadWork =
+      this.turnAborts.has(sessionId) || this.activeTurns.has(sessionId);
+    await 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: SessionRecord): string {
+    if (record.workspaceOverride !== undefined) {
+      return record.workspaceOverride;
+    }
+    const agentCwd = this.project.agent.local?.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.
+   */
+  private scaffoldDir(record: SessionRecord): string {
+    if (record.workspaceOverride !== undefined) {
+      return this.sessions.workspaceDir(record.sessionId);
+    }
+    return this.harnessCwd(record);
+  }
+
+  private async executeTurn(
+    record: SessionRecord,
+    turnId: string,
+    message: string,
+    isFirstTurn: boolean,
+    signal: AbortSignal
+  ): Promise<TurnOutcome> {
+    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 = await this.logs.get(sessionId);
+    const emit = (payload: SessionEventPayload): void => {
+      try {
+        const event = log.append({ ...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: TurnOutcome;
+    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);
+      await materializeWorkspace({
+        agent,
+        workspaceDir,
+        seed: isFirstTurn,
+      });
+      const pendingFiles = record.pendingWorkspaceFiles;
+      if (pendingFiles !== undefined && Object.keys(pendingFiles).length > 0) {
+        await writeWorkspaceFiles(harnessCwd, pendingFiles);
+        await this.updateRecord(sessionId, (current) => {
+          const { pendingWorkspaceFiles: _cleared, ...rest } = current;
+          return rest;
+        });
+      }
+      const request = this.buildTurnRequest(
+        record,
+        agent,
+        turnId,
+        message,
+        isFirstTurn,
+        emit,
+        async (update) => {
+          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"
+          ) {
+            await yieldEventLoop();
+          }
+        },
+        signal
+      );
+      outcome = await this.runner.runTurn(request);
+    } catch (error) {
+      this.approvals.cancelSession(sessionId, "deny");
+      outcome = { status: "error", errorMessage: describeError(error) };
+    } finally {
+      this.approvals.cancelSession(sessionId, "deny");
+      await this.clearPendingApprovals(sessionId);
+    }
+
+    mapper.finish();
+
+    if (mapper.title !== undefined) {
+      const title = mapper.title;
+      await this.updateRecord(sessionId, (current) => ({ ...current, title }));
+    }
+
+    const finalResult = outcome.result ?? mapper.finalText;
+    const finalUsage = outcome.usage ?? mapper.usage;
+
+    if (outcome.status === "finished") {
+      await this.appendEvent(sessionId, {
+        type: "turn.completed",
+        turnId,
+        data: {
+          ...(finalResult === undefined ? {} : { result: finalResult }),
+          ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+        },
+      });
+    } else {
+      const interrupted = signal.aborted && outcome.status === "cancelled";
+      await this.appendEvent(sessionId, {
+        type: "turn.failed",
+        turnId,
+        data: {
+          message: interrupted
+            ? "turn interrupted"
+            : (outcome.errorMessage ??
+              (outcome.status === "cancelled"
+                ? "turn cancelled"
+                : "turn failed")),
+        },
+      });
+    }
+
+    const current = await this.sessions.get(sessionId);
+    const mode = current?.mode ?? record.mode;
+    if (mode === "task") {
+      await this.appendEvent(
+        sessionId,
+        outcome.status === "finished"
+          ? { type: "session.completed", turnId, data: {} }
+          : {
+              type: "session.failed",
+              turnId,
+              data: { message: outcome.errorMessage ?? "task failed" },
+            }
+      );
+    } else {
+      await this.appendEvent(sessionId, {
+        type: "session.waiting",
+        turnId,
+        data: {},
+      });
+    }
+
+    return {
+      ...outcome,
+      ...(finalResult === undefined ? {} : { result: finalResult }),
+      ...(finalUsage === undefined ? {} : { usage: finalUsage }),
+    };
+  }
+
+  private buildTurnRequest(
+    record: SessionRecord,
+    agent: ResolvedAgent,
+    turnId: string,
+    prompt: string,
+    isFirstTurn: boolean,
+    emit: (payload: SessionEventPayload) => void,
+    onUpdate: RunnerTurnRequest["onUpdate"],
+    signal: AbortSignal
+  ): RunnerTurnRequest {
+    // 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 = [
+        agent.instructions?.trim() ?? "",
+        buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
+      ]
+        .filter((part) => part !== "")
+        .join("\n\n");
+      turnPrompt = preamble === "" ? prompt : `${preamble}\n\n${prompt}`;
+    }
+    return {
+      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) => ({
+        name: subagent.name,
+        description: subagent.description ?? 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: async (sdkAgentId) => {
+        if (record.sdkAgentId === sdkAgentId) {
+          return;
+        }
+        await this.updateRecord(record.sessionId, (current) => ({
+          ...current,
+          sdkAgentId,
+        }));
+        record.sdkAgentId = sdkAgentId;
+        await this.appendEvent(record.sessionId, {
+          type: "agent.bound",
+          turnId,
+          data: {
+            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}).
+   */
+  private buildMcpServers(
+    runtime: "local" | "cloud"
+  ): Record<string, ConnectionTransport> {
+    assertCloudCanHonorAccountServersFilters({
+      runtime,
+      resolvedConnections: this.resolvedConnections,
+    });
+    const servers: Record<string, ConnectionTransport> = {};
+    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] = {
+        url,
+        ...(resolved.headers === undefined
+          ? {}
+          : { headers: resolved.headers }),
+      };
+    }
+    return servers;
+  }
+
+  private buildCustomTools(
+    record: SessionRecord,
+    turnId: string,
+    emit: (payload: SessionEventPayload) => void
+  ): Record<string, SDKCustomTool> {
+    const tools: Record<string, SDKCustomTool> = {};
+    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 as SDKCustomTool["inputSchema"],
+        execute: async (args, context) => {
+          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 = context.toolCallId ?? newToolCallId(tool.name);
+          const toolCtx: ToolContext = {
+            toolCallId,
+            session: this.sessionInfo(record),
+            workspaceDir: this.harnessCwd(record),
+            host: this.host,
+            send: (channelId, message, sendOptions = {}) =>
+              this.send(channelId, message, {
+                ...sendOptions,
+                auth:
+                  sendOptions.auth !== undefined
+                    ? sendOptions.auth
+                    : record.auth,
+              }),
+            getSession: (channelId, sessionId) =>
+              this.getChannelSession(channelId, sessionId),
+          };
+          try {
+            const needsGate = await evaluateNeedsApproval(
+              tool.definition.needsApproval,
+              validation.value
+            );
+            if (needsGate) {
+              const decision = await 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 = await execute(validation.value as never, 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.
+   */
+  private async parkForApproval(args: {
+    sessionId: string;
+    turnId: string;
+    callId: string;
+    toolName: string;
+    args: unknown;
+    emit: (payload: SessionEventPayload) => void;
+  }): Promise<ApprovalDecision> {
+    const requestedAt = new Date().toISOString();
+    const pendingRecord: PendingApproval = {
+      callId: args.callId,
+      turnId: args.turnId,
+      toolName: args.toolName,
+      args: args.args,
+      requestedAt,
+    };
+    const resolutionPromise = this.approvals.wait({
+      sessionId: args.sessionId,
+      ...pendingRecord,
+    });
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingApprovals: [
+        ...(current.pendingApprovals ?? []).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 } = await resolutionPromise;
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingApprovals: (current.pendingApprovals ?? []).filter(
+        (item) => item.callId !== args.callId
+      ),
+    }));
+    args.emit({
+      type: "action.approval_resolved",
+      data: {
+        callId: args.callId,
+        toolName: args.toolName,
+        decision,
+        ...(by === undefined ? {} : { by }),
+      },
+    });
+    this.logger(
+      `[session] tool ${args.toolName} approval ${decision} (${args.callId})`
+    );
+    return decision;
+  }
+
+  private async clearPendingApprovals(sessionId: string): Promise<void> {
+    const current = await this.sessions.get(sessionId);
+    if (
+      current === undefined ||
+      current.pendingApprovals === undefined ||
+      current.pendingApprovals.length === 0
+    ) {
+      return;
+    }
+    await this.updateRecord(sessionId, (record) => ({
+      ...record,
+      pendingApprovals: [],
+    }));
+  }
+
+  /** Pending tool approvals for a session (live waiters ∪ persisted). */
+  async listPendingApprovals(sessionId: string): Promise<PendingApproval[]> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      return [];
+    }
+    const live = this.approvals.list(sessionId);
+    if (live.length > 0) {
+      return live;
+    }
+    return record.pendingApprovals ?? [];
+  }
+
+  /**
+   * 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.
+   */
+  async resolveApproval(
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    auth: AuthContext | null,
+    options?: { asSessionOwner?: boolean }
+  ): Promise<PendingApproval> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      throw new ApprovalNotFoundError(sessionId, callId);
+    }
+    const ownershipAuth = options?.asSessionOwner === true ? record.auth : auth;
+    if (!samePrincipal(record.auth, ownershipAuth)) {
+      throw new SessionAuthError(sessionId);
+    }
+    const pending =
+      (record.pendingApprovals ?? []).find((item) => item.callId === callId) ??
+      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)) {
+      await this.removePendingApproval(sessionId, callId);
+      throw new ApprovalInterruptedError(sessionId, callId);
+    }
+    return pending;
+  }
+
+  private async removePendingApproval(
+    sessionId: string,
+    callId: string
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingApprovals: (current.pendingApprovals ?? []).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.
+   */
+  async callTool(
+    toolName: string,
+    input: unknown = {},
+    options: CallToolOptions = {}
+  ): Promise<ToolCallOutcome> {
+    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 = options.auth ?? null;
+    let record: SessionRecord | undefined;
+    let session: SessionInfo;
+    let workspaceDir: string;
+    let scratchDir: string | undefined;
+    if (options.sessionId !== undefined) {
+      record = await 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;
+    }
+    await 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.
+    await 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) {
+      await 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: unknown;
+    let isError: boolean;
+    try {
+      result = normalizeToolResult(
+        await execute(validation.value as never, {
+          toolCallId: callId,
+          session,
+          workspaceDir,
+          host: this.host,
+          send: (channelId, message, sendOptions = {}) =>
+            this.send(channelId, message, {
+              ...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) {
+        await 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) {
+      await this.appendEvent(record.sessionId, {
+        type: "action.result",
+        turnId: callId,
+        data: { callId, toolName, output: result, isError },
+      });
+    }
+
+    const errorMessage = isError ? toolCallErrorMessage(result) : undefined;
+    return {
+      toolName,
+      callId,
+      isError,
+      result,
+      durationMs,
+      ...(errorMessage === undefined ? {} : { errorMessage }),
+      ...(record === undefined ? {} : { sessionId: record.sessionId }),
+    };
+  }
+
+  // ==========================================================================
+  // Events: append, dispatch to channel handlers + hooks
+  // ==========================================================================
+
+  private async appendEvent(
+    sessionId: string,
+    payload: SessionEventPayload & { turnId?: string }
+  ): Promise<SessionEvent> {
+    const log = await this.logs.get(sessionId);
+    const event = log.append(payload);
+    this.queueDispatch(sessionId, event);
+    return event;
+  }
+
+  private queueDispatch(sessionId: string, event: SessionEvent): void {
+    const chain = this.dispatchChains.get(sessionId) ?? 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);
+  }
+
+  private async dispatchEvent(
+    sessionId: string,
+    event: SessionEvent
+  ): Promise<void> {
+    const record = await 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: Array<ChannelEventHandler | undefined> = [
+        channelEvents[event.type] as ChannelEventHandler | undefined,
+        channelEvents["*"],
+      ];
+      const channelCtx = {
+        channelId: record.channelId,
+        state: (record.channelState ?? null) as JsonValue,
+        continuationToken: record.continuationKey,
+        setContinuationToken: (token: string | null) =>
+          this.setContinuationToken(sessionId, token),
+      };
+      for (const handler of handlers) {
+        if (handler === undefined) {
+          continue;
+        }
+        try {
+          await 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.
+      await this.updateRecord(sessionId, (current) => ({ ...current }));
+    }
+
+    for (const hook of this.project.hooks) {
+      const handlers: Array<HookHandler | undefined> = [
+        hook.definition.events[event.type] as HookHandler | undefined,
+        hook.definition.events["*"],
+      ];
+      for (const handler of handlers) {
+        if (handler === undefined) {
+          continue;
+        }
+        try {
+          await 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) {
+      await this.abCollector.onEvent(
+        event,
+        this.sessionInfo(record),
+        this.project.name
+      );
+    }
+  }
+
+  private channelEventHandlersFor(
+    channelId: string
+  ): ChannelDefinition["events"] | undefined {
+    if (channelId === HTTP_CHANNEL_ID) {
+      return this.project.httpChannel.events;
+    }
+    return this.channelsById.get(channelId)?.events;
+  }
+
+  // ==========================================================================
+  // Session handles
+  // ==========================================================================
+
+  async waitForCompletion(sessionId: string): Promise<TurnOutcome> {
+    // 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) {
+      await chain.catch(() => {});
+    }
+    const active = this.activeTurns.get(sessionId);
+    if (active !== undefined) {
+      return active;
+    }
+    return this.lastOutcomes.get(sessionId) ?? { 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.
+   */
+  async listSessions(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<SessionSummary[]> {
+    const includeAll = options?.includeAll ?? false;
+    const records = await this.sessions.list();
+    return records
+      .filter((record) => includeAll || samePrincipal(record.auth, caller))
+      .map((record) => {
+        const externalUrl = externalUrlForSession(record);
+        return {
+          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`.
+   */
+  async abSnapshot(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<ABSnapshot> {
+    const sessions = await this.listSessions(caller, options);
+    const abConfig = this.project.abConfig;
+    const maxPlaygroundSessions = resolveABMaxPlaygroundSessions(
+      abConfig?.maxPlaygroundSessions
+    );
+    const foldedSessions = sessions.slice(0, maxPlaygroundSessions);
+    const snapshot = await 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?.persistSamples !== undefined,
+        durableSnapshots: 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?.persistSnapshots;
+    if (persistSnapshots !== undefined) {
+      try {
+        await persistSnapshots.save(snapshot, {
+          projectRoot: this.project.rootDir,
+        });
+      } catch (error) {
+        this.logger(
+          `[agent-serve] ab persistSnapshots.save threw: ${describeError(error)}`
+        );
+      }
+    }
+    return snapshot;
+  }
+
+  async eventStream(
+    sessionId: string,
+    startIndex = 0
+  ): Promise<ReadableStream<Uint8Array>> {
+    const log = await 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.
+   */
+  async emitAssistantMessage(sessionId: string, text: string): Promise<void> {
+    if (this.isTurnRunning(sessionId)) {
+      throw new SessionBusyError(sessionId);
+    }
+    const existing = await this.sessions.get(sessionId);
+    if (existing === undefined) {
+      throw new Error(`Unknown session: ${sessionId}`);
+    }
+    const record = await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      turnCount: current.turnCount + 1,
+    }));
+    const turnId = `turn_${record.turnCount}`;
+    await this.appendEvent(sessionId, {
+      type: "turn.started",
+      turnId,
+      data: {},
+    });
+    await this.appendEvent(sessionId, {
+      type: "message.completed",
+      turnId,
+      data: { text, finishReason: "stop" },
+    });
+    await this.appendEvent(sessionId, {
+      type: "turn.completed",
+      turnId,
+      data: { result: text },
+    });
+    await this.appendEvent(sessionId, {
+      type: "session.waiting",
+      data: {},
+    });
+    this.lastOutcomes.set(sessionId, {
+      status: "finished",
+      result: text,
+    });
+  }
+
+  /** Snapshot of recorded events (for download / offline trace). */
+  async listEvents(sessionId: string, startIndex = 0): Promise<SessionEvent[]> {
+    const log = await this.logs.get(sessionId);
+    return log.snapshot(startIndex);
+  }
+
+  async setContinuationToken(
+    sessionId: string,
+    token: string | null
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      continuationKey: token,
+    }));
+  }
+
+  isTurnRunning(sessionId: string): boolean {
+    // 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: SessionRecord): SessionInfo {
+    return {
+      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 }),
+    };
+  }
+
+  private channelSession(
+    sessionId: string,
+    record: SessionRecord,
+    isNew: boolean
+  ): ChannelSession {
+    return {
+      id: sessionId,
+      continuationToken: record.continuationKey,
+      isNew,
+      info: this.sessionInfo(record),
+      getEventStream: (options?: { startIndex?: number }) =>
+        this.eventStream(sessionId, options?.startIndex ?? 0),
+      waitForCompletion: () => this.waitForCompletion(sessionId),
+      setContinuationToken: (token: string | null) =>
+        this.setContinuationToken(sessionId, token),
+    };
+  }
+
+  private resolveChannelId(
+    channel: ChannelDefinition | HttpChannelDefinition | string
+  ): string {
+    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>");
+  }
+
+  private initialChannelState(
+    channelId: string,
+    override: JsonValue | undefined
+  ): JsonValue | undefined {
+    if (override !== undefined) {
+      return structuredClone(override);
+    }
+    const definition = this.channelsById.get(channelId);
+    if (definition?.state === undefined) {
+      return undefined;
+    }
+    return structuredClone(definition.state);
+  }
+
+  /** Serialized, immutable record updates (latest-wins per session). */
+  private updateRecord(
+    sessionId: string,
+    updater: (current: SessionRecord) => SessionRecord
+  ): Promise<SessionRecord> {
+    const chain = this.updateChains.get(sessionId) ?? Promise.resolve();
+    const next = chain.then(async () => {
+      const current = await this.sessions.get(sessionId);
+      if (current === undefined) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+      const updated = {
+        ...updater(current),
+        updatedAt: new Date().toISOString(),
+      };
+      await this.sessions.save(updated);
+      return updated;
+    });
+    this.updateChains.set(
+      sessionId,
+      next.catch(() => {})
+    );
+    return next;
+  }
+
+  // ==========================================================================
+  // Lifecycle
+  // ==========================================================================
+
+  trackBackground(promise: Promise<unknown>): void {
+    this.backgroundWork.add(promise);
+    void promise
+      .catch(() => {})
+      .finally(() => {
+        this.backgroundWork.delete(promise);
+      });
+  }
+
+  /** Drain running turns, dispatches, and pending writes, then dispose. */
+  async close(): Promise<void> {
+    this.approvals.cancelAll("deny");
+    await Promise.allSettled([...this.activeTurns.values()]);
+    await Promise.allSettled([...this.backgroundWork]);
+    await Promise.allSettled([...this.dispatchChains.values()]);
+    await Promise.allSettled([...this.updateChains.values()]);
+    await this.logs.flushAll();
+    await this.mcpHost.close();
+    await this.runner.dispose?.();
+  }
+}
+
+function subagentPrompt(subagent: ResolvedAgent): string {
+  if (subagent.instructions !== undefined && subagent.instructions !== "") {
+    return subagent.instructions;
+  }
+  return subagent.description ?? subagent.name;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Detects the `{ content, isError: true }` rich-result error envelope. */
+function isErrorEnvelope(result: unknown): boolean {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    !Array.isArray(result) &&
+    Array.isArray((result as { content?: unknown }).content) &&
+    (result as { isError?: unknown }).isError === true
+  );
+}
+
+async function evaluateNeedsApproval(
+  needsApproval: ToolNeedsApproval<never> | undefined,
+  input: unknown
+): Promise<boolean> {
+  if (needsApproval === undefined || needsApproval === false) {
+    return false;
+  }
+  if (needsApproval === true) {
+    return true;
+  }
+  return Boolean(await needsApproval(input as never));
+}
+
+function approvalResolverLabel(auth: AuthContext | null): string | undefined {
+  if (auth === null) {
+    return undefined;
+  }
+  const slackUser = auth.attributes?.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: SessionRecord): string | undefined {
+  const auth = record.auth;
+  if (auth === null || auth.authenticator !== "slack") {
+    return undefined;
+  }
+  const channelId = auth.attributes?.channel_id ?? "";
+  const threadTs = auth.attributes?.thread_ts ?? "";
+  const teamId = auth.attributes?.team_id;
+  const url = slackThreadPermalink({
+    channelId,
+    threadTs,
+    ...(teamId === undefined ? {} : { teamId }),
+  });
+  return url ?? undefined;
+}
+
+/** Let the HTTP NDJSON writer flush before the next SDK update. */
+function yieldEventLoop(): Promise<void> {
+  return new Promise((resolve) => {
+    setImmediate(resolve);
+  });
+}