@cursor/july 0.1.6 → 0.1.8

package/src/internal/session-engine.ts

@@ -17,6 +17,10 @@ import {
   resolveABSplit,
 } from "../ab.js";
 import { slackThreadPermalink } from "../channels/slack/links.js";
+import {
+  SlackAskDedupeStore,
+  SlackNudgeStore,
+} from "../channels/slack/nudge-store.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -43,6 +47,7 @@ import {
   type SessionInfo,
   type SessionRecord,
   type SessionSummary,
+  type SlackNudgeHostApi,
   type ToolCallOutcome,
   type ToolContext,
   type ToolNeedsApproval,
@@ -57,6 +62,7 @@ import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import { createHostKvApi } from "./host-kv.js";
 import { createHostPlatforms, type HostPlatforms } from "./host-platforms.js";
 import {
   formatContinuationToken,
@@ -196,10 +202,29 @@ export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
 }
 
+interface CoalescedQueuedTurn {
+  message: string;
+  sourceTs?: string;
+}
+
+interface AdmitTurnOptions {
+  admission?: "preempt" | "coalesce";
+  sourceTs?: string;
+  /**
+   * When true, skip `clearCoalesced` on the preempt admit path. Used by
+   * coalesce drain so asks that arrived during drain are not wiped.
+   */
+  retainCoalesced?: boolean;
+}
+
 export class SessionEngine {
   readonly project: AgentProject;
   readonly stateRoot: string;
   readonly sessions: SessionStore;
+  /** Durable Slack mid-turn nudges under `<stateRoot>/slack-nudges`. */
+  readonly nudgeStore: SlackNudgeStore;
+  /** Durable `channelId:ts` ask claims under `<stateRoot>/slack-asks`. */
+  readonly askDedupe: SlackAskDedupeStore;
   /**
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
@@ -226,6 +251,16 @@ export class SessionEngine {
   private readonly turnAborts = new Map<string, AbortController>();
   /** Serializes turn admission per session (latest follow-up wins). */
   private readonly admissionChains = new Map<string, Promise<unknown>>();
+  /**
+   * Per-session coalesce queue for `admission: "coalesce"` (Slack). Drained
+   * into one follow-up turn when the active turn finishes without interrupt.
+   */
+  private readonly coalesceQueues = new Map<string, CoalescedQueuedTurn[]>();
+  /**
+   * Sessions whose turn lifecycle is draining coalesced follow-ups. Counts as
+   * busy so inbound coalesce admits enqueue instead of racing `clearCoalesced`.
+   */
+  private readonly coalesceDrains = new Map<string, Promise<void>>();
   private readonly lastOutcomes = new Map<string, TurnOutcome>();
   private readonly updateChains = new Map<string, Promise<unknown>>();
   private readonly dispatchChains = new Map<string, Promise<void>>();
@@ -235,6 +270,7 @@ export class SessionEngine {
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
   private reminderApi: HostContext["reminders"];
+  private readonly kvApi: HostContext["kv"];
   /** Serve-time resolved connections (see {@link setResolvedConnections}). */
   private resolvedConnections: EngineResolvedConnection[] = [];
 
@@ -244,6 +280,12 @@ export class SessionEngine {
     this.runner = options.runner;
     this.logger = options.logger ?? (() => {});
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
+    this.nudgeStore = new SlackNudgeStore(
+      join(options.stateRoot, "slack-nudges")
+    );
+    this.askDedupe = new SlackAskDedupeStore(
+      join(options.stateRoot, "slack-asks")
+    );
     this.logs = new EventLogStore(
       (sessionId) => this.sessions.eventFilePath(sessionId),
       (sessionId, error) =>
@@ -260,6 +302,11 @@ export class SessionEngine {
             projectRoot: options.project.rootDir,
             logger: this.logger,
           });
+    this.kvApi = createHostKvApi({
+      agentName: options.project.name,
+      stateRoot: options.stateRoot,
+      ...(this.storage === undefined ? {} : { storage: this.storage }),
+    });
     this.abCollector = new ABCollector(
       options.project.abs,
       this.logger,
@@ -302,13 +349,32 @@ export class SessionEngine {
     }
   }
 
-  /** Shared host services (MCP / GitHub / Slack / reminders). */
+  /** Shared host services (MCP / GitHub / Slack / reminders / kv / Slack nudges). */
   get host(): HostContext {
     return {
       mcp: this.mcpHost,
       github: this.platforms.github,
       slack: this.platforms.slack,
       reminders: this.reminderApi,
+      kv: this.kvApi,
+      slackNudges: this.slackNudgeHostApi(),
+    };
+  }
+
+  private slackNudgeHostApi(): SlackNudgeHostApi {
+    return {
+      append: (input) => this.nudgeStore.append(input),
+      drainFormatted: (continuationKey) =>
+        this.nudgeStore.drainFormatted(continuationKey),
+      clear: (continuationKey) => this.nudgeStore.clear(continuationKey),
+      hasUndelivered: (continuationKey) =>
+        this.nudgeStore.hasUndelivered(continuationKey),
+      isDelivered: (continuationKey, sourceTs) =>
+        this.nudgeStore.isDelivered(continuationKey, sourceTs),
+      tryClaimAsk: (channelId, messageTs) =>
+        this.askDedupe.tryClaim(channelId, messageTs),
+      releaseAsk: (channelId, messageTs) =>
+        this.askDedupe.release(channelId, messageTs),
     };
   }
 
@@ -371,8 +437,13 @@ export class SessionEngine {
           pendingWorkspaceFiles: options.workspaceFiles,
         }));
       }
-      await this.startTurn(record.sessionId, message);
-      return this.channelSession(record.sessionId, record, false);
+      const coalesced = await this.startTurn(record.sessionId, message, {
+        admission: options.admission ?? "preempt",
+        ...(options.coalesceSourceTs === undefined
+          ? {}
+          : { sourceTs: options.coalesceSourceTs }),
+      });
+      return this.channelSession(record.sessionId, record, false, coalesced);
     }
 
     const now = new Date().toISOString();
@@ -402,8 +473,31 @@ export class SessionEngine {
       data: { channelId },
     });
     record = await this.enrollABs(record);
-    await this.startTurn(record.sessionId, message);
-    return this.channelSession(record.sessionId, record, true);
+    await this.startTurn(record.sessionId, message, {
+      admission: options.admission ?? "preempt",
+      ...(options.coalesceSourceTs === undefined
+        ? {}
+        : { sourceTs: options.coalesceSourceTs }),
+    });
+    return this.channelSession(record.sessionId, record, true, false);
+  }
+
+  /** Whether a continuation token already maps to a session on this channel. */
+  async hasContinuationSession(
+    channelId: string,
+    continuationToken: string
+  ): Promise<boolean> {
+    let existing = await this.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing === undefined) {
+      existing = await this.restoreSessionByContinuation(
+        channelId,
+        continuationToken
+      );
+    }
+    return existing !== undefined;
   }
 
   /**
@@ -559,17 +653,25 @@ export class SessionEngine {
   // ==========================================================================
 
   /**
-   * 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).
+   * Admit a turn for `sessionId`.
+   *
+   * Default (`preempt`): a follow-up cancels the running turn and starts
+   * immediately (HTTP / MCP). With `admission: "coalesce"` (Slack), a busy
+   * session enqueues the message and returns without interrupting; the queue
+   * drains into one follow-up when the active turn finishes.
+   *
+   * Resolves to `true` when the message was coalesced (enqueued), `false`
+   * when a turn was started.
    */
-  private startTurn(sessionId: string, message: string): Promise<void> {
+  private startTurn(
+    sessionId: string,
+    message: string,
+    options: AdmitTurnOptions = {}
+  ): Promise<boolean> {
     const prior = this.admissionChains.get(sessionId) ?? Promise.resolve();
     const admitted = prior
       .catch(() => {})
-      .then(() => this.admitTurn(sessionId, message));
+      .then(() => this.admitTurn(sessionId, message, options));
     this.admissionChains.set(
       sessionId,
       admitted.catch(() => {})
@@ -577,11 +679,88 @@ export class SessionEngine {
     return admitted;
   }
 
-  private async admitTurn(sessionId: string, message: string): Promise<void> {
+  private enqueueCoalesced(sessionId: string, item: CoalescedQueuedTurn): void {
+    const queue = this.coalesceQueues.get(sessionId) ?? [];
+    if (
+      item.sourceTs !== undefined &&
+      queue.some((entry) => entry.sourceTs === item.sourceTs)
+    ) {
+      return;
+    }
+    queue.push(item);
+    this.coalesceQueues.set(sessionId, queue);
+  }
+
+  private clearCoalesced(sessionId: string): void {
+    this.coalesceQueues.delete(sessionId);
+  }
+
+  private formatCoalescedFollowups(
+    items: readonly CoalescedQueuedTurn[]
+  ): string {
+    if (items.length === 1) {
+      return items[0]!.message;
+    }
+    const parts = [
+      "<slack_followups>",
+      `ANSWER-EACH: ${items.length} asks arrived while you were busy. Address each in order; keep replies compact.`,
+      "",
+    ];
+    for (let i = 0; i < items.length; i++) {
+      parts.push(`### Ask ${i + 1}`);
+      parts.push(items[i]!.message);
+      parts.push("");
+    }
+    parts.push("</slack_followups>");
+    return parts.join("\n").trimEnd();
+  }
+
+  private async drainCoalescedFollowups(sessionId: string): Promise<void> {
+    const queued = this.coalesceQueues.get(sessionId) ?? [];
+    if (queued.length === 0) {
+      return;
+    }
+    this.coalesceQueues.delete(sessionId);
+    const message = this.formatCoalescedFollowups(queued);
+    this.logger(
+      `[session] coalesce drain starting follow-up (${queued.length}) ${sessionId}`
+    );
+    await this.startTurn(sessionId, message, {
+      admission: "preempt",
+      retainCoalesced: true,
+    });
+  }
+
+  private async admitTurn(
+    sessionId: string,
+    message: string,
+    options: AdmitTurnOptions = {}
+  ): Promise<boolean> {
+    const admission = options.admission ?? "preempt";
+    if (admission === "coalesce" && this.isTurnRunning(sessionId)) {
+      this.enqueueCoalesced(sessionId, {
+        message,
+        ...(options.sourceTs === undefined
+          ? {}
+          : { sourceTs: options.sourceTs }),
+      });
+      this.logger(`[session] coalesce enqueue ${sessionId}`);
+      return true;
+    }
+
     // 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);
+    // belt-and-suspenders — see buildTurnRequest). Drain-resume skips interrupt:
+    // the parent lifecycle already cleared activeTurns, and awaiting the in-
+    // flight coalesce drain here would deadlock on itself.
+    if (options.retainCoalesced !== true) {
+      await this.interruptActiveTurn(sessionId);
+    }
+    // Preempt owns the conversation — drop stale coalesced asks. Coalesce
+    // admits and drain-resume keep the queue (retainCoalesced / coalesce path).
+    if (admission === "preempt" && options.retainCoalesced !== true) {
+      this.clearCoalesced(sessionId);
+    }
     this.pendingTurns.add(sessionId);
 
     try {
@@ -607,31 +786,58 @@ export class SessionEngine {
 
       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);
+      // Lifecycle promise includes post-turn coalesce drain so waiters and
+      // interrupt settle after follow-ups are admitted (not only executeTurn).
+      // Assigned before the async body runs so self-identity checks typecheck.
+      let lifecycle!: Promise<TurnOutcome>;
+      lifecycle = (async (): Promise<TurnOutcome> => {
+        let outcome: TurnOutcome;
+        try {
+          outcome = await this.executeTurn(
+            record,
+            turnId,
+            message,
+            isFirstTurn,
+            abort.signal
+          );
+        } catch (error) {
+          outcome = {
+            status: "error",
+            errorMessage: describeError(error),
+          };
+        }
+        this.lastOutcomes.set(sessionId, outcome);
+        const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
+        if (wasCurrent) {
+          this.activeTurns.delete(sessionId);
+        }
+        if (this.turnAborts.get(sessionId) === abort) {
+          this.turnAborts.delete(sessionId);
+        }
+        if (wasCurrent && !abort.signal.aborted) {
+          const drain = this.drainCoalescedFollowups(sessionId).catch(
+            (error) => {
+              this.logger(
+                `[session] coalesce drain failed for ${sessionId}: ${describeError(error)}`
+              );
+            }
+          );
+          this.coalesceDrains.set(sessionId, drain);
+          try {
+            await drain;
+          } finally {
+            if (this.coalesceDrains.get(sessionId) === drain) {
+              this.coalesceDrains.delete(sessionId);
+            }
           }
-        });
+        }
+        return outcome;
+      })();
+      this.activeTurns.set(sessionId, lifecycle);
     } finally {
       this.pendingTurns.delete(sessionId);
     }
+    return false;
   }
 
   /**
@@ -645,19 +851,102 @@ export class SessionEngine {
     if (active !== undefined) {
       await active.catch(() => {});
     }
+    const drain = this.coalesceDrains.get(sessionId);
+    if (drain !== undefined) {
+      await drain.catch(() => {});
+    }
   }
 
   /**
    * Abort the in-flight turn without starting a follow-up. Returns whether
-   * a turn was active (or pending abort) when called.
+   * a turn was active (or pending abort) when called. Also clears any
+   * coalesced follow-ups queued behind the session.
    */
   async interrupt(sessionId: string): Promise<boolean> {
     const hadWork =
-      this.turnAborts.has(sessionId) || this.activeTurns.has(sessionId);
+      this.turnAborts.has(sessionId) ||
+      this.activeTurns.has(sessionId) ||
+      this.coalesceDrains.has(sessionId) ||
+      (this.coalesceQueues.get(sessionId)?.length ?? 0) > 0;
+    this.clearCoalesced(sessionId);
+    const record = await this.sessions.get(sessionId);
+    const continuationKey = record?.continuationKey;
+    if (continuationKey !== undefined && continuationKey !== null) {
+      await this.nudgeStore.clear(continuationKey);
+    }
     await this.interruptActiveTurn(sessionId);
     return hadWork;
   }
 
+  async isContinuationBusy(
+    channelId: string,
+    continuationToken: string
+  ): Promise<boolean> {
+    let existing = await this.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing === undefined) {
+      existing = await this.restoreSessionByContinuation(
+        channelId,
+        continuationToken
+      );
+    }
+    if (existing === undefined) {
+      return false;
+    }
+    return this.isTurnRunning(existing.sessionId);
+  }
+
+  /**
+   * Last agent-posted Slack message ts for warm `<slack_thread_delta>`, from
+   * the session's channel state when present.
+   */
+  async getContinuationLastBotMessageTs(
+    channelId: string,
+    continuationToken: string
+  ): Promise<string | undefined> {
+    let existing = await this.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing === undefined) {
+      existing = await this.restoreSessionByContinuation(
+        channelId,
+        continuationToken
+      );
+    }
+    if (existing === undefined) {
+      return undefined;
+    }
+    const state = existing.channelState;
+    if (state === null || state === undefined || typeof state !== "object") {
+      return undefined;
+    }
+    const ts = (state as { lastBotMessageTs?: unknown }).lastBotMessageTs;
+    return typeof ts === "string" && ts.trim() !== "" ? ts.trim() : undefined;
+  }
+
+  async interruptContinuation(
+    channelId: string,
+    continuationToken: string
+  ): Promise<boolean> {
+    let existing = await this.sessions.findByContinuation(
+      channelId,
+      continuationToken
+    );
+    if (existing === undefined) {
+      existing = await this.restoreSessionByContinuation(
+        channelId,
+        continuationToken
+      );
+    }
+    if (existing === undefined) {
+      return false;
+    }
+    return this.interrupt(existing.sessionId);
+  }
+
   /**
    * Local harness cwd for a session: per-send override, else
    * `<agent.local.cwd>/<sessionId>`, else the durable session workspace.
@@ -1498,15 +1787,20 @@ export class SessionEngine {
   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;
+    // The active lifecycle promise also awaits coalesce drain + the drained
+    // follow-up's admission, so Slack coalesced waiters see the resume turn.
+    for (;;) {
+      const chain = this.admissionChains.get(sessionId);
+      if (chain !== undefined) {
+        await chain.catch(() => {});
+      }
+      const active = this.activeTurns.get(sessionId);
+      if (active !== undefined) {
+        await active;
+        continue;
+      }
+      return this.lastOutcomes.get(sessionId) ?? { status: "finished" };
     }
-    return this.lastOutcomes.get(sessionId) ?? { status: "finished" };
   }
 
   /**
@@ -1674,9 +1968,14 @@ export class SessionEngine {
   }
 
   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);
+    // Include the admit window (pendingTurns) and coalesce drain so busy
+    // policies do not treat a turn that has finished executeTurn but not yet
+    // resumed queued follow-ups as idle (avoids clearCoalesced races).
+    return (
+      this.activeTurns.has(sessionId) ||
+      this.pendingTurns.has(sessionId) ||
+      this.coalesceDrains.has(sessionId)
+    );
   }
 
   sessionInfo(record: SessionRecord): SessionInfo {
@@ -1698,12 +1997,14 @@ export class SessionEngine {
   private channelSession(
     sessionId: string,
     record: SessionRecord,
-    isNew: boolean
+    isNew: boolean,
+    coalesced = false
   ): ChannelSession {
     return {
       id: sessionId,
       continuationToken: record.continuationKey,
       isNew,
+      ...(coalesced ? { coalesced: true } : {}),
       info: this.sessionInfo(record),
       getEventStream: (options?: { startIndex?: number }) =>
         this.eventStream(sessionId, options?.startIndex ?? 0),

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)
   // ==========================================================================