@cursor/july 0.1.9 → 0.1.10

package/src/internal/session-engine.ts

@@ -45,6 +45,7 @@ import {
   type SessionEvent,
   type SessionEventPayload,
   type SessionInfo,
+  type SessionListSource,
   type SessionRecord,
   type SessionSummary,
   type SlackNudgeHostApi,
@@ -1827,13 +1828,88 @@ export class SessionEngine {
    * 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.
+   *
+   * When the project uses `cursorHostedStorage`, prefers durable Bugbot rows
+   * (merged with any newer local records not flushed yet). Falls back to the
+   * local `--state-root` store when the sink is unavailable.
    */
   async listSessions(
     caller: AuthContext | null,
     options?: { includeAll?: boolean }
   ): Promise<SessionSummary[]> {
+    return (await this.listSessionsWithSource(caller, options)).sessions;
+  }
+
+  /**
+   * Same as {@link listSessions}, plus which store answered
+   * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+   * `--state-root`).
+   */
+  async listSessionsWithSource(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<{ sessions: SessionSummary[]; source: SessionListSource }> {
     const includeAll = options?.includeAll ?? false;
+    if (this.storage?.isCursorHosted === true) {
+      try {
+        const records = await this.mergeStoredAndLocalSessions();
+        return {
+          sessions: this.summarizeSessionRecords(records, caller, includeAll),
+          source: "cursor-hosted",
+        };
+      } catch (error) {
+        this.logger(
+          `[agentkit] cursor-hosted session list failed; falling back to local: ${describeError(error)}`
+        );
+      }
+    }
     const records = await this.sessions.list();
+    // Local store is createdAt-asc; reverse so newest created leads.
+    return {
+      sessions: this.summarizeSessionRecords(
+        [...records].reverse(),
+        caller,
+        includeAll
+      ),
+      source: "local",
+    };
+  }
+
+  /**
+   * Durable sink rows plus local records (local wins on the same id when
+   * newer — covers debounce windows that have not flushed yet). Newest
+   * `updatedAt` first.
+   */
+  private async mergeStoredAndLocalSessions(): Promise<SessionRecord[]> {
+    const storage = this.storage;
+    if (storage === undefined) {
+      throw new Error("storage is not configured");
+    }
+    const stored = await storage.listSessionsFromSink();
+    const local = await this.sessions.list();
+    const byId = new Map<string, SessionRecord>();
+    for (const record of stored) {
+      byId.set(record.sessionId, record);
+    }
+    for (const record of local) {
+      const existing = byId.get(record.sessionId);
+      if (
+        existing === undefined ||
+        record.updatedAt.localeCompare(existing.updatedAt) >= 0
+      ) {
+        byId.set(record.sessionId, record);
+      }
+    }
+    return [...byId.values()].sort((a, b) =>
+      b.updatedAt.localeCompare(a.updatedAt)
+    );
+  }
+
+  private summarizeSessionRecords(
+    records: readonly SessionRecord[],
+    caller: AuthContext | null,
+    includeAll: boolean
+  ): SessionSummary[] {
     return records
       .filter((record) => includeAll || samePrincipal(record.auth, caller))
       .map((record) => {
@@ -1858,8 +1934,7 @@ export class SessionEngine {
                 ),
           ...(externalUrl === undefined ? {} : { externalUrl }),
         };
-      })
-      .reverse();
+      });
   }
 
   /**

package/src/internal/sessions-client.ts

@@ -4,15 +4,33 @@
  * Customer-facing errors never include hosting URLs or infra jargon.
  */
 
-import type { SessionEvent, SessionSummary } from "../types.js";
+import type {
+  SessionEvent,
+  SessionListSource,
+  SessionSummary,
+} from "../types.js";
 import { sanitizeCustomerError } from "./logs-client.js";
 import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
 
+export interface ListedSessions {
+  sessions: SessionSummary[];
+  /** Present when the server reports which store answered. */
+  source?: SessionListSource;
+}
+
 export async function listSessions(args: {
   baseUrl: string;
   auth?: RequestAuth;
   fetchImpl?: typeof fetch;
 }): Promise<SessionSummary[]> {
+  return (await listSessionsWithSource(args)).sessions;
+}
+
+export async function listSessionsWithSource(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<ListedSessions> {
   const baseUrl = args.baseUrl.replace(/\/$/, "");
   const fetchImpl = args.fetchImpl ?? fetch;
   let resp: Response;
@@ -30,18 +48,21 @@ export async function listSessions(args: {
   if (!resp.ok) {
     throw new Error(`Could not list sessions (HTTP ${resp.status}).`);
   }
-  const body = (await resp.json()) as { sessions?: unknown };
-  if (!Array.isArray(body.sessions)) {
-    return [];
-  }
-  const out: SessionSummary[] = [];
-  for (const row of body.sessions) {
-    const parsed = parseSessionSummary(row);
-    if (parsed !== undefined) {
-      out.push(parsed);
+  const body = (await resp.json()) as { sessions?: unknown; source?: unknown };
+  const sessions: SessionSummary[] = [];
+  if (Array.isArray(body.sessions)) {
+    for (const row of body.sessions) {
+      const parsed = parseSessionSummary(row);
+      if (parsed !== undefined) {
+        sessions.push(parsed);
+      }
     }
   }
-  return out;
+  const source =
+    body.source === "cursor-hosted" || body.source === "local"
+      ? body.source
+      : undefined;
+  return source === undefined ? { sessions } : { sessions, source };
 }
 
 export async function fetchSessionEvents(args: {
@@ -186,10 +207,24 @@ export async function resolvePreviousSessionId(args: {
   return pickPreviousSession(sessions)?.sessionId;
 }
 
+/** Human label for {@link SessionListSource} in CLI output. */
+export function formatSessionListSource(source: SessionListSource): string {
+  return source === "cursor-hosted"
+    ? "Listing from cursor-hosted storage (durable DB)."
+    : "Listing from local session store.";
+}
+
 /** Format a sessions table (id, channel, mode, turns, running, updated). */
-export function formatSessionsTable(sessions: SessionSummary[]): string {
+export function formatSessionsTable(
+  sessions: SessionSummary[],
+  options?: { source?: SessionListSource }
+): string {
+  const sourceLine =
+    options?.source === undefined
+      ? ""
+      : `${formatSessionListSource(options.source)}\n`;
   if (sessions.length === 0) {
-    return "No sessions.\n";
+    return `${sourceLine}No sessions.\n`;
   }
   const header = ["SESSION", "CHANNEL", "MODE", "TURNS", "RUNNING", "UPDATED"];
   const rows = sessions.map((s) => [
@@ -200,7 +235,7 @@ export function formatSessionsTable(sessions: SessionSummary[]): string {
     s.running ? "yes" : "no",
     s.updatedAt,
   ]);
-  return `${renderTable(header, rows)}\n`;
+  return `${sourceLine}${renderTable(header, rows)}\n`;
 }
 
 function renderTable(header: string[], rows: string[][]): string {

package/src/internal/storage-coordinator.ts

@@ -24,6 +24,7 @@ import {
   type StorageDefinition,
   storageKeys,
 } from "../storage.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
@@ -261,6 +262,14 @@ export class StorageCoordinator {
     return this.definition.list !== undefined;
   }
 
+  /**
+   * True when the authored sink is `cursorHostedStorage` (Bugbot via the
+   * control-plane proxy). `GET /v1/sessions` prefers this durable list.
+   */
+  get isCursorHosted(): boolean {
+    return isCursorHostedStorage(this.definition);
+  }
+
   /**
    * Saved session records for this agent (startup restore). Errors are
    * logged and read as "nothing saved" — a broken store must never block
@@ -275,6 +284,33 @@ export class StorageCoordinator {
       .filter((record) => record != null);
   }
 
+  /**
+   * Session records from the sink for the sessions API. Unlike
+   * {@link listSessions}, missing `list` or a thrown sink error **propagates**
+   * so the caller can fall back to the local session store.
+   */
+  async listSessionsFromSink(): Promise<SessionRecord[]> {
+    const list = this.definition.list;
+    if (list === undefined) {
+      throw new Error("storage sink has no list");
+    }
+    const entries = await list(
+      storageKeys.sessionPrefix(this.agentName),
+      this.context("restore")
+    );
+    if (!Array.isArray(entries)) {
+      throw new Error("storage list returned a non-array");
+    }
+    return entries
+      .map((entry) => entry.value as unknown as SessionRecord)
+      .filter(
+        (record) =>
+          record != null &&
+          typeof record.sessionId === "string" &&
+          record.sessionId !== ""
+      );
+  }
+
   /**
    * Saved event stream for one session: chunk values concatenated in key
    * order (chunks are keyed by their first event's index, zero-padded, so

package/src/storage-backends/cursor-hosted.ts

@@ -80,9 +80,29 @@ export interface CursorHostedStorageOptions {
   fetch?: typeof fetch;
 }
 
+/**
+ * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
+ * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
+ * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
+ * (TS9010).
+ */
+export const CURSOR_HOSTED_STORAGE: unique symbol = Symbol.for(
+  "@cursor/july.storage.cursor-hosted"
+);
+
+/** True when `value` is (or was built from) {@link cursorHostedStorage}. */
+export function isCursorHostedStorage(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[CURSOR_HOSTED_STORAGE] === true
+  );
+}
+
 type CursorHostedStorageMethods = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 > & {
+  readonly [CURSOR_HOSTED_STORAGE]: true;
   evals: StorageEvalsTable;
   abs: StorageABTable;
 };
@@ -155,6 +175,7 @@ export function cursorHostedStorage(
   options: CursorHostedStorageOptions = {}
 ): CursorHostedStorageMethods {
   return {
+    [CURSOR_HOSTED_STORAGE]: true,
     async put(key, value): Promise<void> {
       await storageRpc(options, "/internal/agent-serve/storage/kv/put", {
         key,

package/src/types.ts

@@ -886,6 +886,13 @@ export interface SessionSummary {
   externalUrl?: string;
 }
 
+/**
+ * Where `GET /v1/sessions` loaded rows from.
+ * - `cursor-hosted` — durable Bugbot `agent_serve_kv` via `cursorHostedStorage`
+ * - `local` — the serve process `--state-root` session store
+ */
+export type SessionListSource = "cursor-hosted" | "local";
+
 /**
  * A session handle scoped to the channel that owns it. This is what channel
  * route handlers get back from `send()` / `getSession()`.
@@ -1897,6 +1904,15 @@ export interface ServeOptions {
    * SSO/Okta proxy in front of the host).
    */
   allowAnonymousCursorGithub?: boolean;
+  /**
+   * Allow {@link allowAnonymous} together with
+   * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`
+   * refuses to start because every admitted anonymous caller could drive the
+   * signed-in account's MCP connectors. Set it only when the network boundary
+   * already authenticates callers (e.g. an SSO/Okta proxy, or the hosted
+   * agent-serve alias token).
+   */
+  allowAnonymousCursorAccountMcp?: boolean;
   /**
    * Public base URL where this server is reachable from outside the host
    * (e.g. `https://agents.example.com`). Used to resolve peer

package/dist/channels/slack/post-update-delivery.js

@@ -1,318 +0,0 @@
-/**
- * Live-reply delivery strategies for the Slack default handlers.
- *
- * A single strategy owns how an in-progress reply is opened, updated,
- * finalized, and cleaned up so the handlers in `defaults.ts` don't fork on the
- * delivery mode at every event:
- *
- * - `stream`: Slack chat.startStream / appendStream / stopStream.
- * - `post-update`: a chat.postMessage skeleton edited with chat.update. This is
- *   the only path that preserves Cursor-account identity pinning (which only
- *   covers postMessage).
- *
- * `buildDefaultEvents` selects one via {@link selectLiveDeliveryStrategy} up
- * front and calls into it. All calls keep the same soft-fail / log behavior as
- * the inlined logic they replaced.
- */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { appendChatStream, deleteMessage, postMessage, setThreadStatus, startChatStream, stopChatStream, updateMessage, } from "./api.js";
-import { SLACK_POST_UPDATE_MIN_INTERVAL_MS } from "./constants.js";
-import { computeStreamAppend } from "./stream.js";
-function createPostUpdateStrategy(deps) {
-    const { botToken, getLog } = deps;
-    return {
-        inlineToolSteps: false,
-        start(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, threadTs, sessionId }) {
-                const log = getLog();
-                try {
-                    const posted = yield postMessage({
-                        botToken,
-                        channel: channelId,
-                        text: "…",
-                        threadTs,
-                    });
-                    if (posted.ts !== "") {
-                        channel.state.streamTs = posted.ts;
-                        channel.state.streamChannelId = channelId;
-                        channel.state.lastPostedText = "";
-                        log.info("postMessage skeleton ok", {
-                            channel: channelId,
-                            message_ts: posted.ts,
-                            session: sessionId,
-                        });
-                    }
-                }
-                catch (error) {
-                    log.warn("postMessage skeleton failed", {
-                        error: error instanceof Error ? error.message : String(error),
-                        channel: channelId,
-                        session: sessionId,
-                    });
-                    // Transient proxy/network failures must not permanently disable
-                    // live delivery — only the stream path sets streamingUnavailable
-                    // when Slack reports the feature unsupported.
-                }
-            });
-        },
-        append(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, text, sessionId }) {
-                var _b;
-                const now = Date.now();
-                const isFirstUpdate = channel.state.lastPostedText === null ||
-                    channel.state.lastPostedText === "";
-                const lastAt = (_b = channel.state.lastPostUpdateAtMs) !== null && _b !== void 0 ? _b : 0;
-                const due = isFirstUpdate || now - lastAt >= SLACK_POST_UPDATE_MIN_INTERVAL_MS;
-                if (!due) {
-                    // Skip intermediate update; message.completed flushes full text.
-                    return;
-                }
-                const result = yield updateMessage({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    text,
-                });
-                if (!result.ok) {
-                    getLog().warn("chat.update failed", {
-                        error: result.error,
-                        channel: channelId,
-                        message_ts: streamTs,
-                        session: sessionId,
-                    });
-                    return;
-                }
-                channel.state.lastPostUpdateAtMs = now;
-                channel.state.lastPostedText = text;
-            });
-        },
-        finalize(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, text, sessionId }) {
-                const log = getLog();
-                const result = yield updateMessage({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    text,
-                });
-                channel.state.streamTs = null;
-                if (result.ok) {
-                    channel.state.lastPostedText = text;
-                    log.info("reply delivered via chat.update", {
-                        channel: channelId,
-                        message_ts: streamTs,
-                        session: sessionId,
-                        chars: text.length,
-                    });
-                    return { delivered: true };
-                }
-                log.warn("chat.update finalize failed; falling back to postMessage", {
-                    error: result.error,
-                    channel: channelId,
-                    message_ts: streamTs,
-                    session: sessionId,
-                });
-                // Only suppress the fallback when the skeleton already holds the exact
-                // final text. Partial updates must not permanently truncate.
-                if (channel.state.lastPostedText === text) {
-                    return { delivered: true };
-                }
-                // The skeleton still shows the placeholder or a stale partial and we're
-                // about to post the full reply as a fresh message. Best-effort delete the
-                // orphan so the thread doesn't show a duplicate.
-                yield deleteMessage({ botToken, channel: channelId, ts: streamTs });
-                return { delivered: false };
-            });
-        },
-        finalizeEmpty(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channelId, streamTs }) {
-                yield updateMessage({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    text: " ",
-                });
-            });
-        },
-        cleanupOrphan(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel }) {
-                var _b;
-                // A skeleton that was never finalized (e.g. an empty turn that produced
-                // no message.completed) would otherwise linger as a "…" placeholder
-                // forever. Best-effort delete it and clear typing.
-                const orphanTs = channel.state.streamTs;
-                if (orphanTs === null || orphanTs === "") {
-                    return;
-                }
-                const orphanChannelId = (_b = channel.state.streamChannelId) !== null && _b !== void 0 ? _b : channel.state.channelId;
-                if (orphanChannelId !== null && orphanChannelId !== "") {
-                    yield deleteMessage({
-                        botToken,
-                        channel: orphanChannelId,
-                        ts: orphanTs,
-                    });
-                }
-                channel.state.streamTs = null;
-                if (channel.state.channelId !== null && channel.state.threadTs !== null) {
-                    yield setThreadStatus({
-                        botToken,
-                        channelId: channel.state.channelId,
-                        threadTs: channel.state.threadTs,
-                        status: "",
-                    });
-                }
-            });
-        },
-        fail(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, errorText }) {
-                const updated = yield updateMessage({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    text: errorText,
-                });
-                channel.state.streamTs = null;
-                return { delivered: updated.ok };
-            });
-        },
-    };
-}
-function createStreamStrategy(deps) {
-    const { botToken, getLog } = deps;
-    return {
-        inlineToolSteps: true,
-        start(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, threadTs, sessionId }) {
-                const log = getLog();
-                const started = yield startChatStream({
-                    botToken,
-                    channel: channelId,
-                    thread_ts: threadTs,
-                    markdown_text: "",
-                });
-                if (!started.ok) {
-                    log.warn("chat.startStream unavailable", {
-                        error: started.error,
-                        channel: channelId,
-                        thread_ts: threadTs,
-                        session: sessionId,
-                    });
-                    if (started.unsupported === true) {
-                        channel.state.streamingUnavailable = true;
-                    }
-                    return;
-                }
-                channel.state.streamTs = started.ts;
-                channel.state.streamChannelId = started.channel;
-                channel.state.lastPostedText = "";
-                log.info("chat.startStream ok", {
-                    channel: started.channel,
-                    stream_ts: started.ts,
-                    session: sessionId,
-                });
-            });
-        },
-        append(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, text, sessionId }) {
-                const appendText = computeStreamAppend(channel.state.lastPostedText, text);
-                if (appendText === "") {
-                    return;
-                }
-                const result = yield appendChatStream({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    markdown_text: appendText,
-                });
-                if (!result.ok) {
-                    getLog().warn("appendStream failed", {
-                        error: result.error,
-                        channel: channelId,
-                        stream_ts: streamTs,
-                        session: sessionId,
-                    });
-                    if (result.unsupported === true) {
-                        channel.state.streamingUnavailable = true;
-                    }
-                    return;
-                }
-                channel.state.lastPostedText = text;
-            });
-        },
-        finalize(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, text, sessionId }) {
-                const log = getLog();
-                // Only send the unsent suffix — full text was already appended.
-                const appendText = computeStreamAppend(channel.state.lastPostedText, text);
-                const stopped = yield stopChatStream({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    markdown_text: appendText === "" ? undefined : appendText,
-                });
-                if (stopped.ok) {
-                    channel.state.streamTs = null;
-                    channel.state.lastPostedText = text;
-                    log.info("reply delivered via stream", {
-                        channel: channelId,
-                        stream_ts: streamTs,
-                        session: sessionId,
-                        chars: text.length,
-                    });
-                    return { delivered: true };
-                }
-                log.warn("chat.stopStream failed; falling back to postMessage", {
-                    error: stopped.error,
-                    channel: channelId,
-                    stream_ts: streamTs,
-                    session: sessionId,
-                });
-                if (stopped.unsupported === true) {
-                    channel.state.streamingUnavailable = true;
-                }
-                channel.state.streamTs = null;
-                // If we already streamed content, do not post the full reply again.
-                const alreadyStreamed = typeof channel.state.lastPostedText === "string" &&
-                    channel.state.lastPostedText.length > 0;
-                return { delivered: alreadyStreamed };
-            });
-        },
-        finalizeEmpty(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channelId, streamTs }) {
-                yield stopChatStream({ botToken, channel: channelId, ts: streamTs });
-            });
-        },
-        cleanupOrphan() {
-            return __awaiter(this, void 0, void 0, function* () {
-                // The stream path closes its message in message.completed / turn.failed;
-                // there is nothing to clean up after turn.completed.
-            });
-        },
-        fail(_a) {
-            return __awaiter(this, arguments, void 0, function* ({ channel, channelId, streamTs, errorText }) {
-                const stopped = yield stopChatStream({
-                    botToken,
-                    channel: channelId,
-                    ts: streamTs,
-                    markdown_text: errorText,
-                });
-                channel.state.streamTs = null;
-                return { delivered: stopped.ok };
-            });
-        },
-    };
-}
-/** Pick the live-reply delivery strategy for a `buildDefaultEvents` instance. */
-export function selectLiveDeliveryStrategy(deps, usePostUpdate) {
-    return usePostUpdate
-        ? createPostUpdateStrategy(deps)
-        : createStreamStrategy(deps);
-}