@cursor/july 0.1.7 → 0.1.8

package/src/internal/storage-coordinator.ts

@@ -392,6 +392,47 @@ export class StorageCoordinator {
     );
   }
 
+  // ==========================================================================
+  // Author KV ({@link HostContext.kv})
+  // ==========================================================================
+
+  /**
+   * Whether the sink can serve awaited author reads/writes (`get` is
+   * required — `put` is always present on {@link StorageConfig}).
+   */
+  get supportsAuthorKv(): boolean {
+    return this.definition.get !== undefined;
+  }
+
+  /**
+   * Awaited author KV read. Unlike framework session mirrors, this awaits
+   * the sink and propagates errors — handlers need read-after-write.
+   */
+  async kvGet(authorKey: string): Promise<JsonValue | undefined> {
+    const get = this.definition.get;
+    if (get === undefined) {
+      throw new Error("storage get is not configured");
+    }
+    const key = storageKeys.kv(this.agentName, authorKey);
+    // Preserve stored JSON `null` (distinct from a missing key).
+    return await get(key, this.context("restore"));
+  }
+
+  /**
+   * Awaited author KV write. Goes straight to the sink (not the
+   * at-most-once delivery queue) so callers observe durable success/failure.
+   */
+  async kvPut(authorKey: string, value: JsonValue): Promise<void> {
+    const key = storageKeys.kv(this.agentName, authorKey);
+    await this.definition.put(key, value, this.context("policy"));
+  }
+
+  /** Awaited author KV delete. No-op when the sink omits `delete`. */
+  async kvDelete(authorKey: string): Promise<void> {
+    const key = storageKeys.kv(this.agentName, authorKey);
+    await this.definition.delete?.(key, this.context("policy"));
+  }
+
   // ==========================================================================
   // Evals (dedicated `evals` table)
   // ==========================================================================

package/src/storage-backends/file-kv.ts

@@ -0,0 +1,221 @@
+/**
+ * File-backed `defineStorage` helper: a file-per-key KV store plus
+ * file-backed `evals` / `abs` tables.
+ *
+ * Implements the whole `defineStorage` surface with zero external
+ * dependencies: the four KV methods against a flat directory of JSON files
+ * (one file per key, filename = URI-encoded key), eval runs as
+ * `eval-runs/<agent>/<runId>.json`, and A/B metrics as
+ * `ab/<agent>/samples.ndjson` (append-only) plus `ab/<agent>/snapshot.json`
+ * (latest aggregate). KV keys carry the agent name inside the framework
+ * key scheme, but the evals/abs tables have no such scheme — the agent
+ * subdirectory keeps agents sharing one storage `dir` from mixing or
+ * overwriting each other's history. Swap this for a real backend
+ * (Postgres, S3, …) in production; the contracts are identical.
+ *
+ * Layout notes:
+ * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
+ *   so `list(prefix)` is a readdir + decode + filter, returned in key
+ *   order as the contract requires.
+ * - `put` writes via tmp + rename: the framework serializes writes, but a
+ *   restore-path `get`/`list` can run concurrently and must never see a
+ *   torn file.
+ * - `get` distinguishes a definitive miss (ENOENT → `undefined`) from a
+ *   real failure (anything else throws) — on the lazy-restore path a
+ *   throw correctly fails the follow-up instead of forking the session.
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  appendFile,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageContext,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+export interface FileKvOptions {
+  /**
+   * Directory holding the storage files, relative to the agent project root
+   * (default `".agent-serve/kv"`). Absolute paths are used as-is.
+   */
+  dir?: string;
+}
+
+type FileKvMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function fileKv(options?: FileKvOptions): FileKvMethods {
+  const resolveDir = (ctx: StorageContext): string =>
+    join(ctx.projectRoot, options?.dir ?? ".agent-serve/kv");
+  // The evals/abs tables are scoped per agent (KV keys already carry the
+  // agent name via the framework key scheme).
+  const evalRunsDir = (ctx: StorageContext): string =>
+    join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
+  const abDir = (ctx: StorageContext): string =>
+    join(resolveDir(ctx), "ab", encodeURIComponent(ctx.agentName));
+  const filePath = (ctx: StorageContext, key: string): string =>
+    join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
+  const readKey = async (
+    ctx: StorageContext,
+    key: string
+  ): Promise<JsonValue | undefined> => {
+    try {
+      return JSON.parse(
+        await readFile(filePath(ctx, key), "utf8")
+      ) as JsonValue;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined; // definitive miss — key was never written
+      }
+      throw error; // real failure: let lazy restore fail the follow-up
+    }
+  };
+
+  return {
+    async put(key, value, ctx): Promise<void> {
+      await writeJsonAtomic({
+        dir: resolveDir(ctx),
+        fileName: `${encodeURIComponent(key)}.json`,
+        value,
+      });
+    },
+
+    get(key, ctx): Promise<JsonValue | undefined> {
+      return readKey(ctx, key);
+    },
+
+    async delete(key, ctx): Promise<void> {
+      await rm(filePath(ctx, key), { force: true });
+    },
+
+    async list(prefix, ctx): Promise<StorageEntry[]> {
+      let names: string[];
+      try {
+        names = await readdir(resolveDir(ctx));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return []; // nothing stored yet
+        }
+        throw error;
+      }
+      const keys = names
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
+        .filter((key) => key.startsWith(prefix))
+        .sort();
+      const entries: StorageEntry[] = [];
+      for (const key of keys) {
+        const value = await readKey(ctx, key);
+        if (value !== undefined) {
+          entries.push({ key, value });
+        }
+      }
+      return entries;
+    },
+
+    // Playground eval batches: one JSON file per run under eval-runs/<agent>/.
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await writeJsonAtomic({
+          dir: evalRunsDir(ctx),
+          fileName: `${encodeURIComponent(run.runId)}.json`,
+          value: run,
+        });
+      },
+      async delete(runId, ctx): Promise<void> {
+        await rm(join(evalRunsDir(ctx), `${encodeURIComponent(runId)}.json`), {
+          force: true,
+        });
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const dir = evalRunsDir(ctx);
+        let names: string[];
+        try {
+          names = await readdir(dir);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return [];
+          }
+          throw error;
+        }
+        const runs: EvalRunSnapshot[] = [];
+        for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+          // One unreadable/corrupt file must not wipe the whole history:
+          // hydrate treats a throwing list() as "nothing saved".
+          try {
+            runs.push(
+              JSON.parse(
+                await readFile(join(dir, name), "utf8")
+              ) as EvalRunSnapshot
+            );
+          } catch {}
+        }
+        return runs;
+      },
+    },
+
+    // A/B metrics: append-only sample log + latest aggregate snapshot,
+    // both under ab/<agent>/.
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        const dir = abDir(ctx);
+        await mkdir(dir, { recursive: true });
+        await appendFile(
+          join(dir, "samples.ndjson"),
+          `${JSON.stringify(sample)}\n`,
+          "utf8"
+        );
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await writeJsonAtomic({
+          dir: abDir(ctx),
+          fileName: "snapshot.json",
+          value: snapshot,
+        });
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        try {
+          return JSON.parse(
+            await readFile(join(abDir(ctx), "snapshot.json"), "utf8")
+          ) as ABSnapshot;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return undefined;
+          }
+          throw error;
+        }
+      },
+    },
+  };
+}
+
+/** tmp + rename write so concurrent readers never see a torn file. */
+async function writeJsonAtomic(args: {
+  dir: string;
+  fileName: string;
+  value: unknown;
+}): Promise<void> {
+  await mkdir(args.dir, { recursive: true });
+  const tmp = join(args.dir, `.tmp-${randomUUID()}`);
+  await writeFile(tmp, JSON.stringify(args.value), "utf8");
+  await rename(tmp, join(args.dir, args.fileName));
+}

package/src/storage-backends/postgres-kv.ts

@@ -0,0 +1,248 @@
+/**
+ * Postgres `defineStorage` helper on the agent-serve tables
+ * (backend/packages/prisma-bugbot):
+ *
+ *   agent_serve_kv(deployment_id, key, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, key)
+ *   agent_serve_eval_runs(deployment_id, agent, run_id, run JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, run_id)
+ *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, kind, ref)
+ *
+ * `postgresStorage` implements the whole `defineStorage` surface as plain
+ * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
+ * table (sessions, event chunks, continuations, reminders), the `evals`
+ * table against `agent_serve_eval_runs` (one row per playground eval
+ * batch), and the `abs` table against `agent_serve_ab` (`kind = 'sample'`
+ * rows per metric sample plus one `kind = 'snapshot'` row holding the
+ * latest aggregate).
+ *
+ * - KV `put` upserts on the primary key (LWW matches the framework contract).
+ * - KV `list` is a prefix range scan on the PK btree (`key >= p AND key < p||…`
+ *   spelled as LIKE with escaped wildcards, ordered by key).
+ * - `get` returning no row is a definitive miss (`undefined`); a connection
+ *   error throws, so lazy restore fails the follow-up instead of forking
+ *   the session.
+ *
+ * Connection comes from `BUGBOTDB_URL` — the repo-wide convention for the
+ * bugbot Postgres database, whose Prisma package owns these tables' schema
+ * and migrations; locally it falls back to the dev bugbot DB. Non-local
+ * URLs enable TLS (`ssl.rejectUnauthorized`) because PlanetScale requires
+ * SSL even when the vault URL omits `sslmode`.
+ * `deploymentId` scopes rows per deployment (`AGENT_SERVE_DEPLOYMENT_ID`);
+ * the local default keeps dev runs of different checkouts from colliding
+ * only by agent name.
+ *
+ * Callers must pass `Pool` from their own `import { Pool } from "pg"`.
+ * This module must not import `pg` itself: Node resolves modules from
+ * *this* file's directory tree, so a `pg` dep declared only on the
+ * consuming agent package would never be found after a hosted install.
+ */
+
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/** Minimal `pg.Pool` surface used here (avoids importing `pg` from this path). */
+export interface PostgresQueryable {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    values?: readonly unknown[]
+  ): Promise<{ rows: T[] }>;
+}
+
+/** `pg.Pool` constructor supplied by the consuming example package. */
+export type PostgresPoolConstructor = new (config?: {
+  connectionString?: string;
+  max?: number;
+  ssl?: boolean | { rejectUnauthorized?: boolean };
+}) => PostgresQueryable;
+
+export interface PostgresStorageOptions {
+  /**
+   * Pass `Pool` from `import { Pool } from "pg"` in the example that declares
+   * the `pg` dependency (hosted installs put it in that package's
+   * `node_modules` only).
+   */
+  Pool: PostgresPoolConstructor;
+  /** Postgres connection string (default: env, then local bugbot dev DB). */
+  databaseUrl?: string;
+  /** Value for the tables' deployment_id column (default: env or "local-dev"). */
+  deploymentId?: string;
+}
+
+type PostgresStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+/** True for local bugbot/dev URLs that do not speak TLS. */
+export function isLocalPostgresUrl(connectionString: string): boolean {
+  try {
+    const host = new URL(connectionString).hostname.toLowerCase();
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "::1" ||
+      host === "[::1]"
+    );
+  } catch {
+    return /@(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(connectionString);
+  }
+}
+
+/** Postgres-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function postgresStorage(
+  options: PostgresStorageOptions
+): PostgresStorageMethods {
+  const connectionString =
+    options.databaseUrl ??
+    process.env.BUGBOTDB_URL ??
+    "postgresql://prisma:prisma@localhost:5432/bugbot";
+  // Prod Bugbot is PlanetScale Postgres: TLS is required and the vault
+  // `BUGBOTDB_URL` often omits `sslmode`. Without an explicit `ssl` option,
+  // `pg` opens plaintext and PlanetScale rejects with "SSL connection is
+  // required" — sessions stay in-memory. Skip TLS only for local hosts.
+  const pool = new options.Pool({
+    connectionString,
+    // Small fixed pool per agent, mirroring the backend's connection_limit
+    // clamp on BUGBOTDB_URL consumers (backend/server/src/prisma.ts).
+    max: 3,
+    ...(isLocalPostgresUrl(connectionString)
+      ? {}
+      : { ssl: { rejectUnauthorized: true } }),
+  });
+  const deploymentId =
+    options.deploymentId ??
+    process.env.AGENT_SERVE_DEPLOYMENT_ID ??
+    "local-dev";
+
+  return {
+    async put(key, value): Promise<void> {
+      await pool.query(
+        `INSERT INTO agent_serve_kv (deployment_id, key, value, updated_at)
+         VALUES ($1, $2, $3::jsonb, now())
+         ON CONFLICT ON CONSTRAINT pk_agent_serve_kv
+         DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+        [deploymentId, key, JSON.stringify(value)]
+      );
+    },
+
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await pool.query<{ value: JsonValue }>(
+        `SELECT value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key = $2`,
+        [deploymentId, key]
+      );
+      return result.rows[0]?.value; // no row ⇒ definitive miss
+    },
+
+    async delete(key): Promise<void> {
+      await pool.query(
+        `DELETE FROM agent_serve_kv WHERE deployment_id = $1 AND key = $2`,
+        [deploymentId, key]
+      );
+    },
+
+    async list(prefix): Promise<StorageEntry[]> {
+      // Escape LIKE wildcards in the prefix so keys containing % or _
+      // (URI-encoded segments cannot, but be safe) match literally.
+      const escaped = prefix.replace(/([\\%_])/g, "\\$1");
+      const result = await pool.query<{ key: string; value: JsonValue }>(
+        `SELECT key, value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key LIKE $2 ESCAPE '\\'
+         ORDER BY key ASC`,
+        [deploymentId, `${escaped}%`]
+      );
+      return result.rows;
+    },
+
+    // Playground eval batches → agent_serve_eval_runs (one row per run).
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await pool.query(
+          `INSERT INTO agent_serve_eval_runs (deployment_id, agent, run_id, run, updated_at)
+           VALUES ($1, $2, $3, $4::jsonb, now())
+           ON CONFLICT ON CONSTRAINT pk_agent_serve_eval_runs
+           DO UPDATE SET run = EXCLUDED.run, updated_at = now()`,
+          [deploymentId, ctx.agentName, run.runId, JSON.stringify(run)]
+        );
+      },
+      async delete(runId, ctx): Promise<void> {
+        await pool.query(
+          `DELETE FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2 AND run_id = $3`,
+          [deploymentId, ctx.agentName, runId]
+        );
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const result = await pool.query<{ run: EvalRunSnapshot }>(
+          `SELECT run FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2`,
+          [deploymentId, ctx.agentName]
+        );
+        return result.rows.map((row) => row.run);
+      },
+    },
+
+    // A/B metrics → agent_serve_ab: sample rows plus one snapshot row.
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        await upsertAbRow(pool, {
+          deploymentId,
+          agent: ctx.agentName,
+          kind: "sample",
+          // One boundary event emits a sample per enrolled experiment with
+          // the same sessionId/at — the experiment must be in the row key
+          // or those samples overwrite each other.
+          ref: `${sample.experiment}/${sample.sessionId}/${sample.at}`,
+          value: sample,
+        });
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await upsertAbRow(pool, {
+          deploymentId,
+          agent: ctx.agentName,
+          kind: "snapshot",
+          ref: "",
+          value: snapshot,
+        });
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        const result = await pool.query<{ value: JsonValue }>(
+          `SELECT value FROM agent_serve_ab
+           WHERE deployment_id = $1 AND agent = $2 AND kind = 'snapshot' AND ref = ''`,
+          [deploymentId, ctx.agentName]
+        );
+        return result.rows[0]?.value as unknown as ABSnapshot | undefined;
+      },
+    },
+  };
+}
+
+async function upsertAbRow(
+  pool: PostgresQueryable,
+  row: {
+    deploymentId: string;
+    agent: string;
+    kind: "sample" | "snapshot";
+    ref: string;
+    value: unknown;
+  }
+): Promise<void> {
+  await pool.query(
+    `INSERT INTO agent_serve_ab (deployment_id, agent, kind, ref, value, updated_at)
+     VALUES ($1, $2, $3, $4, $5::jsonb, now())
+     ON CONFLICT ON CONSTRAINT pk_agent_serve_ab
+     DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
+    [row.deploymentId, row.agent, row.kind, row.ref, JSON.stringify(row.value)]
+  );
+}

package/src/storage.ts

@@ -33,7 +33,9 @@
  *
  * Because keys are opaque strings to the sink, new kinds of durable state
  * (channel cursors, thread affinity, …) are new key prefixes — existing
- * sinks store them with no code changes.
+ * sinks store them with no code changes. Authors can also store their own
+ * JSON under `agentkit/v1/{agent}/kv/…` via {@link HostContext.kv}; the
+ * framework still mints the full key from the author-supplied segment.
  *
  * Delivery semantics: writes are **serialized** (one sink call in flight
  * per agent, in order), **bounded** (a sink that falls behind sheds writes
@@ -274,6 +276,7 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -301,6 +304,13 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
   reminderPrefix: (agent: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
+  /**
+   * Author-facing opaque JSON (see {@link HostContext.kv}). `key` is
+   * URI-encoded / digested like other caller-controlled segments.
+   */
+  kv: (agent: string, key: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
+  kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
 } as const;
 
 /**

package/src/types.ts

@@ -316,6 +316,28 @@ export interface HostMcpCallResult {
   structuredContent?: JsonObject;
 }
 
+/**
+ * Durable Slack follow-up nudge + ask-claim API attached to {@link HostContext}.
+ * Used for mid-turn inject, boundary resume skip, and delayed-parent dedupe.
+ */
+export interface SlackNudgeHostApi {
+  append(input: {
+    continuationKey: string;
+    sourceTs: string;
+    text: string;
+    author?: string;
+  }): Promise<boolean>;
+  /** Drain pending nudges and return a `<slack_followup>` block, if any. */
+  drainFormatted(continuationKey: string): Promise<string | undefined>;
+  clear(continuationKey: string): Promise<void>;
+  hasUndelivered(continuationKey: string): Promise<boolean>;
+  isDelivered(continuationKey: string, sourceTs: string): Promise<boolean>;
+  /** Claim `channelId:message.ts` exactly once (false = already seen). */
+  tryClaimAsk(channelId: string, messageTs: string): Promise<boolean>;
+  /** Release a claim after a failed send so Slack redelivery can retry. */
+  releaseAsk(channelId: string, messageTs: string): Promise<void>;
+}
+
 /**
  * Shared host services available on every tool / channel / schedule surface.
  * Channel packs attach this as `ctx.host` so handlers can tap GitHub, Slack,
@@ -339,6 +361,29 @@ export interface HostContext {
    * the serve host has attached a {@link ReminderRunner}.
    */
   reminders?: ReminderHostApi;
+  /**
+   * Slack ask-dedupe / optional nudge helpers. Always present on a live
+   * {@link SessionEngine} host. Mid-turn nudge inject is not used; busy
+   * Slack follow-ups coalesce and drain at turn boundaries.
+   */
+  slackNudges?: SlackNudgeHostApi;
+  /**
+   * Author-facing durable JSON KV (`agentkit/v1/{agent}/kv/…`). Backed by
+   * `agent/storage.ts` (`defineStorage`) when authored; otherwise files
+   * under `--state-root/kv`. Prefer this over ad-hoc files under the
+   * project tree so state survives host replacement.
+   */
+  kv: HostKvApi;
+}
+
+/** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
+export interface HostKvApi {
+  /** Read one value. Miss → `undefined`. */
+  get(key: string): Promise<JsonValue | undefined>;
+  /** Write or replace one value. */
+  put(key: string, value: JsonValue): Promise<void>;
+  /** Remove one key. No-op when missing. */
+  delete(key: string): Promise<void>;
 }
 
 /** Runtime context handed to a tool's `execute`. */
@@ -851,6 +896,11 @@ export interface ChannelSession {
   readonly continuationToken: string | null;
   /** True when this `send()` created the session. */
   readonly isNew: boolean;
+  /**
+   * True when `admission: "coalesce"` enqueued this message behind an
+   * in-flight turn instead of starting immediately (Slack busy path).
+   */
+  readonly coalesced?: boolean;
   readonly info: SessionInfo;
   /** Replay recorded events from `startIndex`, then follow live (NDJSON). */
   getEventStream(options?: {
@@ -919,6 +969,17 @@ export interface SendMessageOptions {
    * store is gone.
    */
   sdkAgentId?: string;
+  /**
+   * Turn admission when a session is already busy.
+   * - `"preempt"` (default) — interrupt the in-flight turn (HTTP / MCP).
+   * - `"coalesce"` — enqueue and return without interrupting (Slack).
+   */
+  admission?: "preempt" | "coalesce";
+  /**
+   * Optional source message timestamp for coalesce queue items. When a
+   * mid-turn nudge already delivered this `sourceTs`, boundary resume skips it.
+   */
+  coalesceSourceTs?: string;
 }
 
 export type SendMessageFn = (
@@ -1183,6 +1244,28 @@ export interface ChannelStartArgs {
   /** Shared host services (MCP / GitHub / Slack). Same as {@link ChannelHandlerArgs.host}. */
   host: HostContext;
   waitUntil(promise: Promise<unknown>): void;
+  /**
+   * Whether a live session already exists for a continuation token on this
+   * channel (includes lazy restore from storage).
+   */
+  hasContinuationSession(continuationToken: string): Promise<boolean>;
+  /**
+   * Whether a model turn is in flight (or being admitted) for the session
+   * addressed by this continuation token.
+   */
+  isContinuationBusy(continuationToken: string): Promise<boolean>;
+  /**
+   * Slack warm-delta watermark: last agent reply ts recorded on the session's
+   * channel state (`lastBotMessageTs`), when present.
+   */
+  getContinuationLastBotMessageTs(
+    continuationToken: string
+  ): Promise<string | undefined>;
+  /**
+   * Interrupt the in-flight turn for a continuation token and clear any
+   * coalesced follow-ups queued behind it. Returns whether work was active.
+   */
+  interruptContinuation(continuationToken: string): Promise<boolean>;
   /**
    * Approve or deny a parked {@link ToolConfig.needsApproval} tool call
    * for a session on this channel. Channel packs (e.g. Slack Block Kit