@cursor/july 0.1.40 → 0.1.42

package/src/types.ts

@@ -204,8 +204,31 @@ export interface AgentConfig {
    * {@link BuiltinToolsConfig}.
    */
   builtinTools?: BuiltinToolsConfig;
+  /**
+   * How the serve host coordinates event delivery and turn execution. See
+   * {@link AgentServingMode}. Defaults to `"resident"`; opt in to
+   * `"ledger"` per agent — rollback is flipping the value back.
+   */
+  serving?: AgentServingMode;
 }
 
+/**
+ * Serving coordination mode on {@link AgentConfig.serving}.
+ *
+ * - `"resident"` (default): the in-process session engine owns delivery —
+ *   today's behavior, unchanged.
+ * - `"ledger"`: every delivery coordinates through the KV session ledger
+ *   before its turn runs: session identity, a one-writer-per-session
+ *   lease with generation fencing, and a fenced commit sequence.
+ *   Requires a store with conditional writes (the `cas` group on
+ *   `defineStorage`, or an explicit CAS-capable override); startup fails
+ *   fast otherwise. This stage is coordination only — there is no
+ *   durable inbox yet, so an event arriving while the lease is held
+ *   waits in-process and a crash loses it exactly as resident serving
+ *   does. The durable mailbox lands in a follow-up.
+ */
+export type AgentServingMode = "resident" | "ledger";
+
 /**
  * Built-in tools on {@link AgentConfig.builtinTools}. Each enabled
  * capability materializes as ordinary server tools at discovery time, so
@@ -432,9 +455,9 @@ export interface SlackNudgeHostApi {
 }
 
 /**
- * Shared host services available on every tool / channel / schedule surface.
- * Channel packs attach this as `ctx.host` so handlers can tap GitHub, Slack,
- * or MCP without the pack depending on another platform.
+ * Shared host services available on every tool / hook / channel / schedule
+ * surface. Channel packs attach this as `ctx.host` so handlers can tap
+ * GitHub, Slack, or MCP without the pack depending on another platform.
  */
 export interface HostContext {
   /**
@@ -493,6 +516,71 @@ export interface HostKvApi {
   delete(key: string): Promise<void>;
 }
 
+/** A value plus its opaque version token, as returned by CAS-capable reads. */
+export interface KvVersionedEntry {
+  value: JsonValue;
+  /**
+   * Opaque per-key token that changes on every successful write. Callers
+   * must not parse it — backends mint whatever is cheap for them (a
+   * counter, a UUID, an `updated_at`/`xmin` pair, …).
+   */
+  version: string;
+}
+
+/**
+ * Outcome of a conditional write. On conflict the backend returns the
+ * entry it observed (`undefined` when the key is absent), so a CAS retry
+ * loop gets its re-read for free instead of paying a second round trip.
+ */
+export type KvCasResult =
+  | { ok: true; version: string }
+  | { ok: false; current: KvVersionedEntry | undefined };
+
+/**
+ * Conditional-write superset of {@link HostKvApi} for coordination
+ * protocols (the upcoming session ledger). Version-token CAS was chosen
+ * over compare-value: every candidate backend can mint a cheap opaque
+ * token (counter, UUID, row version), while compare-value would force
+ * deep JSON equality with key-order pitfalls on each of them. The
+ * agent-facing `host.kv` stays plain {@link HostKvApi}; storage backends
+ * supply CAS via the optional `cas` group on `defineStorage`, and
+ * coordination features fail fast when the backend lacks it.
+ */
+export interface HostKvCasApi extends HostKvApi {
+  /** Read one value with its version token. Miss → `undefined`. */
+  getWithVersion(key: string): Promise<KvVersionedEntry | undefined>;
+  /** Create the key only when absent. Conflict returns the existing entry. */
+  putIfAbsent(key: string, value: JsonValue): Promise<KvCasResult>;
+  /**
+   * Replace the value only when the key still carries `expectedVersion`.
+   * Conflict (version moved, or key deleted) returns the current entry.
+   */
+  putIfVersion(
+    key: string,
+    value: JsonValue,
+    expectedVersion: string
+  ): Promise<KvCasResult>;
+  /** All keys under a prefix, in ascending key order. */
+  listKeys(prefix: string): Promise<string[]>;
+}
+
+/**
+ * Runtime probe: does this KV implement the CAS superset? Only for
+ * stores of unknown provenance — e.g. a caller-supplied {@link HostKvApi}
+ * object whose static type does not carry the CAS methods. A
+ * `defineStorage` backend declares CAS through its `cas` group instead
+ * and never needs probing.
+ */
+export function supportsKvCas(kv: HostKvApi): kv is HostKvCasApi {
+  const candidate = kv as Partial<HostKvCasApi>;
+  return (
+    typeof candidate.getWithVersion === "function" &&
+    typeof candidate.putIfAbsent === "function" &&
+    typeof candidate.putIfVersion === "function" &&
+    typeof candidate.listKeys === "function"
+  );
+}
+
 /**
  * Which set of files a call addresses.
  *
@@ -1218,7 +1306,15 @@ export interface SessionRecord {
    * One-shot files to write into the harness cwd before the next turn
    * (see {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
    */
-  pendingWorkspaceFiles?: Record<string, string>;
+  pendingWorkspaceFiles?: Record<
+    string,
+    string | { encoding: "base64"; data: string; mimeType?: string }
+  >;
+  /**
+   * One-shot vision images for the next turn (see
+   * {@link SendMessageOptions.images}). Cleared after apply.
+   */
+  pendingImages?: Array<{ data: string; mimeType: string }>;
   /**
    * Per-session cloud options captured at session creation, merged over the
    * agent's static `cloud` config on every turn of this session. Lets a
@@ -1346,9 +1442,18 @@ export interface SendMessageOptions {
    * the first turn; on resume, replaces any pending files. Prefer this
    * over {@link workspaceDir} when you only need to inject a few
    * host-prepared files (skills/AGENTS.md still land in the normal
-   * session workspace).
+   * session workspace). Values may be utf8 strings or
+   * `{ encoding: "base64", data }` blobs (Slack attachments, binary docs).
+   */
+  workspaceFiles?: Record<
+    string,
+    string | { encoding: "base64"; data: string; mimeType?: string }
+  >;
+  /**
+   * Base64 images for this turn's Cursor SDK `send({ images })` (vision).
+   * Cleared after the turn starts. Slack inbound fills this from uploads.
    */
-  workspaceFiles?: Record<string, string>;
+  images?: Array<{ data: string; mimeType: string }>;
   /**
    * Per-session cloud options, merged over the agent's static `cloud`
    * config (new sessions only). When set, this session runs as cloud even
@@ -1786,6 +1891,12 @@ export interface HookContext {
    * memory journal) write here.
    */
   stateRoot: string;
+  /**
+   * Shared host services (MCP / GitHub / Slack / kv / files). Same as
+   * tool `ctx.host`. `files` is bound to this hook's session, so a
+   * relative path cannot read another session's files.
+   */
+  host: HostContext;
   /**
    * Durable artifacts, bound to this hook's session: `tag` auto-fills
    * `sessionId` (and `turnId` when known).
@@ -2230,6 +2341,11 @@ export interface ResolvedAgent {
   hosting?: AgentHostingOptions;
   /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
   concurrency?: AgentConcurrencyOptions;
+  /**
+   * Validated serving mode from {@link AgentConfig.serving}. Undefined
+   * means `"resident"` (the default path).
+   */
+  serving?: AgentServingMode;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
@@ -2301,7 +2417,18 @@ export interface AgentProjectInfo {
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
-  connections: Array<{ name: string; transport: string; hostOnly?: boolean }>;
+  connections: Array<{
+    name: string;
+    transport: string;
+    hostOnly?: boolean;
+    /**
+     * Present only for `cursorAccount` connections: the connector-name
+     * allowlist, or `"*"` for every connected server. Structured twin of the
+     * `cursor-account[:a,b]` transport label so consumers (e.g. the
+     * dashboard's connector scoping) never parse the display string.
+     */
+    cursorAccountServers?: string[] | "*";
+  }>;
   subagents: Array<{
     name: string;
     description?: string;
@@ -2367,6 +2494,11 @@ export interface RunnerTurnRequest {
   runnerStateDir: string;
   prompt: string;
   isFirstTurn: boolean;
+  /**
+   * Base64 images for this turn (Cursor SDK `SDKUserMessage.images`).
+   * Set from {@link SendMessageOptions.images} / Slack attachments.
+   */
+  images?: Array<{ data: string; mimeType: string }>;
   model?: ModelSetting;
   runtime: AgentRuntime;
   /** Cloud options when {@link runtime} is `"cloud"`. */

package/dist/channels/slack/post-update-delivery.d.ts

@@ -1,85 +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.
- */
-import type { ChannelEventContext } from "../../types.js";
-import type { SlackLog } from "./log.js";
-import type { SlackBotToken, SlackChannelState } from "./types.js";
-type SlackChannel = ChannelEventContext<SlackChannelState>;
-export interface LiveDeliveryDeps {
-    botToken: SlackBotToken | undefined;
-    getLog: () => SlackLog;
-}
-/**
- * How the default handlers deliver an in-progress reply. Methods write live
- * delivery state (`streamTs`, `streamChannelId`, `lastPostedText`,
- * `lastPostUpdateAtMs`, `streamingUnavailable`) on `channel.state` directly.
- */
-export interface LiveDeliveryStrategy {
-    /** True when tool-call thinking steps can be appended to the live message. */
-    readonly inlineToolSteps: boolean;
-    /** Open the live message (skeleton post / stream start). */
-    start(args: {
-        channel: SlackChannel;
-        channelId: string;
-        threadTs: string;
-        sessionId: string;
-    }): Promise<void>;
-    /** Push the latest cumulative text to the live message (throttled). */
-    append(args: {
-        channel: SlackChannel;
-        channelId: string;
-        streamTs: string;
-        text: string;
-        sessionId: string;
-    }): Promise<void>;
-    /**
-     * Flush the final reply text. `delivered` is false only when the caller must
-     * post the full reply as a fresh message (finalize failed on partial text).
-     */
-    finalize(args: {
-        channel: SlackChannel;
-        channelId: string;
-        streamTs: string;
-        text: string;
-        sessionId: string;
-    }): Promise<{
-        delivered: boolean;
-    }>;
-    /** Close the live message when the turn produced no final text. */
-    finalizeEmpty(args: {
-        channel: SlackChannel;
-        channelId: string;
-        streamTs: string;
-    }): Promise<void>;
-    /** Best-effort remove a live message left open after the turn ended. */
-    cleanupOrphan(args: {
-        channel: SlackChannel;
-    }): Promise<void>;
-    /** Deliver the error text into the live message; `delivered` gates a fallback post. */
-    fail(args: {
-        channel: SlackChannel;
-        channelId: string;
-        streamTs: string;
-        errorText: string;
-        sessionId: string;
-    }): Promise<{
-        delivered: boolean;
-    }>;
-}
-/** Pick the live-reply delivery strategy for a `buildDefaultEvents` instance. */
-export declare function selectLiveDeliveryStrategy(deps: LiveDeliveryDeps, usePostUpdate: boolean): LiveDeliveryStrategy;
-export {};
-//# sourceMappingURL=post-update-delivery.d.ts.map

package/dist/channels/slack/post-update-delivery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"post-update-delivery.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/post-update-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAW1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE,KAAK,YAAY,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,MAAM,QAAQ,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,4DAA4D;IAC5D,KAAK,CAAC,IAAI,EAAE;QACV,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,IAAI,EAAE;QACX,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE;QACb,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpC,mEAAmE;IACnE,aAAa,CAAC,IAAI,EAAE;QAClB,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,wEAAwE;IACxE,aAAa,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,uFAAuF;IACvF,IAAI,CAAC,IAAI,EAAE;QACT,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrC;AA6RD,iFAAiF;AACjF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,aAAa,EAAE,OAAO,GACrB,oBAAoB,CAItB"}