@cursor/july 0.1.39 → 0.1.41

package/src/internal/session-engine.ts

@@ -23,6 +23,12 @@ import {
 } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
+import {
+  SessionLedger,
+  type SessionLedgerKv,
+  supportsSessionLedgerKv,
+} from "../ledger/session-ledger.js";
+import { fileKv } from "../storage-backends/file-kv.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -40,6 +46,7 @@ import {
   DIRECT_TOOL_CALL_CHANNEL_ID,
   type HookHandler,
   type HostContext,
+  type HostKvApi,
   type HttpChannelDefinition,
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
@@ -78,6 +85,11 @@ import {
   mapSdkTokenUsage,
 } from "./cloud-turn-cost.js";
 import { isDevMode } from "./dev-mode.js";
+import {
+  ledgerKeyPrefix,
+  namespacedKv,
+  storageCasKv,
+} from "./durable-session-store.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
@@ -95,6 +107,7 @@ import {
   newToolCallId,
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
+import { LedgerServing, newLedgerPodId } from "./ledger-serving.js";
 import { McpHost } from "./mcp-host.js";
 import {
   buildSessionContextBlock,
@@ -215,6 +228,21 @@ export interface SessionEngineOptions {
    * stub; production uses billed usage events when an agent id is known.
    */
   estimateTurnCost?: EstimateTurnCostFn;
+  /**
+   * Explicit durable-session store for `serving: "ledger"` agents — a KV
+   * dedicated to the ledger (session identity, leases, commit heads),
+   * separate from agent state. Must implement the ledger's CAS methods
+   * (`getWithVersion` / `putIfAbsent` / `putIfVersion`); construction
+   * fails fast otherwise. Supply the **raw** store: the engine owns key
+   * scoping and namespaces every ledger key under
+   * `agentkit/v1/<agent>/durable-session/` itself — a self-hoster never
+   * writes prefixes. Default when omitted: the authored storage backend
+   * (`agent/storage.ts`) when it implements the `cas` group, else — with
+   * no authored storage — a file store under `<stateRoot>/ledger-kv`
+   * (single-process correctness only). An authored storage backend
+   * *without* `cas` fails fast. Ignored for resident-mode agents.
+   */
+  durableSessionStore?: HostKvApi;
 }
 
 /**
@@ -250,6 +278,13 @@ interface ActiveToolContext {
 
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
+  /**
+   * Internal (ledger serving): this send *is* a lease-holding turn
+   * delivery, so it must run the resident path. Without the flag, every
+   * send on a `serving: "ledger"` agent routes through the ledger
+   * (claim → turn → commit) and the pump would recurse into itself.
+   */
+  ledgerDelivery?: boolean;
 }
 
 interface CoalescedQueuedTurn {
@@ -341,6 +376,12 @@ export class SessionEngine {
   private readonly cloudCostBackfillDone = new Set<string>();
   /** Deduped in-flight cloud cost backfills, keyed by session id. */
   private readonly cloudCostBackfill = new Map<string, Promise<void>>();
+  /**
+   * Ledger-mode delivery seam; set only when the agent declares
+   * `serving: "ledger"`. When present, {@link send} routes every
+   * non-delivery call through the ledger's claim → turn → commit.
+   */
+  private readonly ledgerServing: LedgerServing | undefined;
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
@@ -425,6 +466,82 @@ export class SessionEngine {
     for (const channel of options.project.channels) {
       this.channelsById.set(channel.id, channel.definition);
     }
+    this.ledgerServing = this.buildLedgerServing(options);
+  }
+
+  /**
+   * Ledger-mode wiring (`serving: "ledger"`): resolve a CAS-capable
+   * durable-session store and build the delivery seam. Resident agents
+   * (the default) return undefined and never touch ledger keys.
+   */
+  private buildLedgerServing(
+    options: SessionEngineOptions
+  ): LedgerServing | undefined {
+    if (options.project.agent.serving !== "ledger") {
+      return undefined;
+    }
+    const ledgerKv = this.resolveDurableSessionStore(options);
+    return new LedgerServing({
+      ledger: new SessionLedger({ kv: ledgerKv, podId: newLedgerPodId() }),
+      deliverTurn: (request) =>
+        this.send(request.channelId, request.message, {
+          ...request.options,
+          continuationToken: request.continuationToken,
+          ledgerDelivery: true,
+        }),
+      logger: this.logger,
+    });
+  }
+
+  /**
+   * Pick the KV the ledger coordinates on, in precedence order:
+   *
+   * 1. `options.durableSessionStore` — an explicit store separate from
+   *    agent state (advanced deployments, tests).
+   * 2. The authored storage backend (`agent/storage.ts`) when it
+   *    implements the `cas` group — one backend serves both the storage
+   *    API and the durable session API.
+   * 3. No authored storage: a file store under `<stateRoot>/ledger-kv`
+   *    (same place resident state lives; single-process only).
+   *
+   * An authored backend without `cas` fails fast: silently falling back
+   * to local files would fork coordination away from the deployment's
+   * durable store. The check demands exactly the methods the
+   * coordination-only ledger uses — `listKeys` is not one of them.
+   *
+   * Whatever store wins, the returned handle is scoped here — once —
+   * under `agentkit/v1/<agent>/durable-session/`. The ledger speaks bare
+   * `session/…` / `ledger/…` keys; namespacing is this boundary's job,
+   * exactly like `host.kv`'s agent scoping.
+   */
+  private resolveDurableSessionStore(
+    options: SessionEngineOptions
+  ): SessionLedgerKv {
+    const namespace = ledgerKeyPrefix(options.project.name);
+    const explicit = options.durableSessionStore;
+    if (explicit !== undefined) {
+      if (!supportsSessionLedgerKv(explicit)) {
+        throw new Error(
+          `Agent "${options.project.name}" declares serving: "ledger", but the configured durableSessionStore is not CAS-capable (getWithVersion / putIfAbsent / putIfVersion). Provide a store implementing those methods (see @cursor/july/kv).`
+        );
+      }
+      return namespacedKv(explicit, namespace);
+    }
+    const casArgs = {
+      agentName: options.project.name,
+      projectRoot: options.project.rootDir,
+    };
+    const authored = options.project.storage;
+    if (authored !== undefined) {
+      if (authored.cas === undefined) {
+        throw new Error(
+          `Agent "${options.project.name}" declares serving: "ledger", which needs conditional writes, but the storage backend in agent/storage.ts does not implement the cas group. Add cas: {...} to defineStorage (fileKv and cursorHostedStorage already include it), or pass an explicit durableSessionStore.`
+        );
+      }
+      return namespacedKv(storageCasKv(authored, casArgs), namespace);
+    }
+    const fallback = fileKv({ dir: join(options.stateRoot, "ledger-kv") });
+    return namespacedKv(storageCasKv(fallback, casArgs), namespace);
   }
 
   /**
@@ -592,6 +709,12 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
+    // Ledger-mode agents acquire the session lease before any turn runs;
+    // only the seam's own lease-holding deliveries fall through to the
+    // resident path.
+    if (this.ledgerServing !== undefined && options.ledgerDelivery !== true) {
+      return this.ledgerServing.deliver(channelId, message, options);
+    }
     const auth = options.auth ?? null;
     let existing =
       options.continuationToken === undefined
@@ -616,20 +739,27 @@ export class SessionEngine {
       // Refresh harness cwd when the caller supplies a newer worktree (e.g. PR
       // synchronize). Leave the durable continuation key unchanged.
       let record = existing;
-      if (
+      const refreshWorkspace =
         options.workspaceDir !== undefined &&
-        options.workspaceDir !== existing.workspaceOverride
+        options.workspaceDir !== existing.workspaceOverride;
+      if (
+        refreshWorkspace ||
+        options.workspaceFiles !== undefined ||
+        options.images !== undefined
       ) {
         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,
+          workspaceOverride: refreshWorkspace
+            ? options.workspaceDir
+            : current.workspaceOverride,
+          pendingWorkspaceFiles: mergePendingWorkspaceFiles(
+            current.pendingWorkspaceFiles,
+            options.workspaceFiles
+          ),
+          pendingImages: mergePendingImages(
+            current.pendingImages,
+            options.images
+          ),
         }));
       }
       // Refresh the cloud attach the same way: a follow-up send carries the
@@ -668,6 +798,7 @@ export class SessionEngine {
       channelState,
       workspaceOverride: options.workspaceDir,
       pendingWorkspaceFiles: options.workspaceFiles,
+      pendingImages: options.images,
       cloudOverride: options.cloud,
       sdkAgentId: options.sdkAgentId,
       turnCount: 0,
@@ -1299,15 +1430,29 @@ export class SessionEngine {
           stateRoot: this.stateRoot,
         });
         const pendingFiles = record.pendingWorkspaceFiles;
+        const pendingImages = record.pendingImages;
         if (
           pendingFiles !== undefined &&
           Object.keys(pendingFiles).length > 0
         ) {
           await writeWorkspaceFiles(harnessCwd, pendingFiles);
-          await this.updateRecord(sessionId, (current) => {
-            const { pendingWorkspaceFiles: _cleared, ...rest } = current;
-            return rest;
-          });
+        }
+        if (
+          (pendingFiles !== undefined &&
+            Object.keys(pendingFiles).length > 0) ||
+          (pendingImages !== undefined && pendingImages.length > 0)
+        ) {
+          await this.updateRecord(sessionId, (current) => ({
+            ...current,
+            pendingWorkspaceFiles:
+              current.pendingWorkspaceFiles === pendingFiles
+                ? undefined
+                : current.pendingWorkspaceFiles,
+            pendingImages:
+              current.pendingImages === pendingImages
+                ? undefined
+                : current.pendingImages,
+          }));
         }
         // The harness only loads the scaffolded AGENTS.md when the session
         // workspace is its own project root. When the harness cwd is borrowed
@@ -1340,7 +1485,8 @@ export class SessionEngine {
               await yieldEventLoop();
             }
           },
-          signal
+          signal,
+          pendingImages
         );
         this.activeToolContexts.set(sessionId, { record, turnId, emit });
         try {
@@ -1443,7 +1589,8 @@ export class SessionEngine {
     instructionsInvisibleToHarness: boolean,
     emit: (payload: SessionEventPayload) => void,
     onUpdate: RunnerTurnRequest["onUpdate"],
-    signal: AbortSignal
+    signal: AbortSignal,
+    images?: Array<{ data: string; mimeType: string }>
   ): RunnerTurnRequest {
     // Per-session cloud attach (channel/tool handoff) forces cloud runtime
     // even when the agent defaults to local for chat server tools.
@@ -1508,6 +1655,7 @@ export class SessionEngine {
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,
+      ...(images !== undefined && images.length > 0 ? { images } : {}),
       ...(agent.model === undefined ? {} : { model: agent.model }),
       runtime,
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
@@ -3193,6 +3341,8 @@ export class SessionEngine {
   /** Drain running turns, dispatches, and pending writes, then dispose. */
   async close(): Promise<void> {
     this.approvals.cancelAll("deny");
+    // Ledger deliveries spawn turns, so settle them before activeTurns.
+    await this.ledgerServing?.close();
     await Promise.allSettled([...this.activeTurns.values()]);
     await Promise.allSettled([...this.backgroundWork]);
     await Promise.allSettled([...this.dispatchChains.values()]);
@@ -3208,6 +3358,32 @@ export class SessionEngine {
 const RESTORE_FETCH_CONCURRENCY = 8;
 
 /** NDJSON payload for a restored event stream; undefined when empty. */
+function mergePendingImages(
+  current: Array<{ data: string; mimeType: string }> | undefined,
+  incoming: Array<{ data: string; mimeType: string }> | undefined
+): Array<{ data: string; mimeType: string }> | undefined {
+  if (incoming === undefined) {
+    return current;
+  }
+  if (current === undefined || current.length === 0) {
+    return incoming;
+  }
+  return [...current, ...incoming];
+}
+
+function mergePendingWorkspaceFiles(
+  current: SessionRecord["pendingWorkspaceFiles"],
+  incoming: SessionRecord["pendingWorkspaceFiles"]
+): SessionRecord["pendingWorkspaceFiles"] {
+  if (incoming === undefined) {
+    return current;
+  }
+  if (current === undefined) {
+    return incoming;
+  }
+  return { ...current, ...incoming };
+}
+
 function eventsNdjson(events: SessionEvent[]): string | undefined {
   if (events.length === 0) {
     return undefined;

package/src/internal/slack-provision-client.ts

@@ -386,7 +386,7 @@ function mapErrorResponse(
       );
     case 403:
       return new SlackProvisionApiError(
-        `${serverError ?? "Not authorized"} — Slack provisioning needs team-admin permission and the cloud-agent entitlement on that team.`,
+        `${serverError ?? "Not authorized"} — Slack provisioning needs team membership and the cloud-agent entitlement on that team.`,
         { status: 403 }
       );
     case 404: {

package/src/internal/workspace.ts

@@ -421,16 +421,27 @@ export function buildSkillMd(skill: DiscoveredSkill): string {
 
 /**
  * Write relative path → contents under `workspaceDir`, refusing paths that
- * escape the directory.
+ * escape the directory. Values may be utf8 strings or base64 blob envelopes.
  */
 export async function writeWorkspaceFiles(
   workspaceDir: string,
-  files: Record<string, string>
+  files: Record<
+    string,
+    string | { encoding: "base64"; data: string; mimeType?: string }
+  >
 ): Promise<void> {
   for (const [relativePath, contents] of Object.entries(files)) {
     const target = resolveWorkspaceWritePath(workspaceDir, relativePath);
     await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, contents, "utf8");
+    if (typeof contents === "string") {
+      await writeFile(target, contents, "utf8");
+    } else if (contents.encoding === "base64") {
+      await writeFile(target, Buffer.from(contents.data, "base64"));
+    } else {
+      throw new Error(
+        `Unsupported workspace file encoding for ${relativePath}`
+      );
+    }
   }
 }
 

package/src/kv/memory-kv.ts

@@ -0,0 +1,99 @@
+/**
+ * In-memory {@link HostKvCasApi} — the test/dev implementation of the
+ * interface module (`@cursor/july/kv`), exported at
+ * `@cursor/july/kv/memory`.
+ *
+ * The memory KV *is* the dev shim: tests and local runs exercise the
+ * same CAS coordination paths that hosted serving uses, not a mock of an
+ * RPC. Values are deep-copied on both write and
+ * read so callers can never observe (or cause) shared-reference mutation.
+ */
+
+import type { StorageCasTable } from "../storage.js";
+import type {
+  HostKvCasApi,
+  JsonValue,
+  KvCasResult,
+  KvVersionedEntry,
+} from "../types.js";
+
+/** Create an empty in-memory CAS-capable KV. */
+export function createMemoryKv(): HostKvCasApi {
+  const entries = new Map<string, { value: JsonValue; version: string }>();
+  let versionCounter = 0;
+
+  const nextVersion = (): string => {
+    versionCounter += 1;
+    return `v${versionCounter}`;
+  };
+
+  const snapshot = (key: string): KvVersionedEntry | undefined => {
+    const entry = entries.get(key);
+    if (entry === undefined) {
+      return undefined;
+    }
+    return { value: structuredClone(entry.value), version: entry.version };
+  };
+
+  return {
+    async get(key): Promise<JsonValue | undefined> {
+      return snapshot(key)?.value;
+    },
+
+    async put(key, value): Promise<void> {
+      entries.set(key, {
+        value: structuredClone(value),
+        version: nextVersion(),
+      });
+    },
+
+    async delete(key): Promise<void> {
+      entries.delete(key);
+    },
+
+    async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
+      return snapshot(key);
+    },
+
+    async putIfAbsent(key, value): Promise<KvCasResult> {
+      if (entries.has(key)) {
+        return { ok: false, current: snapshot(key) };
+      }
+      const version = nextVersion();
+      entries.set(key, { value: structuredClone(value), version });
+      return { ok: true, version };
+    },
+
+    async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
+      const entry = entries.get(key);
+      if (entry === undefined || entry.version !== expectedVersion) {
+        return { ok: false, current: snapshot(key) };
+      }
+      const version = nextVersion();
+      entries.set(key, { value: structuredClone(value), version });
+      return { ok: true, version };
+    },
+
+    async listKeys(prefix): Promise<string[]> {
+      return [...entries.keys()].filter((key) => key.startsWith(prefix)).sort();
+    },
+  };
+}
+
+/**
+ * In-memory `cas` group for `defineStorage` — a complete conditional-write
+ * group for sinks whose plain methods are inert or live elsewhere (test
+ * fixtures, an off-hosting no-op sink). Non-durable and process-local by
+ * construction; a real deployment backend should implement CAS against
+ * its own store instead.
+ */
+export function memoryCasTable(): StorageCasTable {
+  const kv = createMemoryKv();
+  return {
+    getWithVersion: (key) => kv.getWithVersion(key),
+    putIfAbsent: (key, value) => kv.putIfAbsent(key, value),
+    putIfVersion: (key, value, expectedVersion) =>
+      kv.putIfVersion(key, value, expectedVersion),
+    listKeys: (prefix) => kv.listKeys(prefix),
+  };
+}

package/src/kv.ts

@@ -0,0 +1,27 @@
+/**
+ * The CAS-capable KV **interface** — `@cursor/july/kv`.
+ *
+ * This module is implementation-free on purpose: it is the contract a
+ * bring-your-own KV implements so coordination protocols (conditional
+ * writes are the substrate for the upcoming session ledger) can run on
+ * it. {@link HostKvCasApi} is the conditional-write superset of the plain
+ * {@link HostKvApi}; {@link supportsKvCas} is the runtime probe for
+ * stores of unknown provenance — a `defineStorage` backend declares CAS
+ * through its `cas` group instead, so it never needs probing.
+ *
+ * Implementations live elsewhere:
+ *
+ * - `@cursor/july/kv/memory` — `createMemoryKv`, the test/dev shim.
+ * - The storage backends implement the same operations as the `cas`
+ *   group on `defineStorage` (see `StorageCasTable` in
+ *   `@cursor/july/storage`): `fileKv` (single-process) and
+ *   `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
+ */
+
+export type {
+  HostKvApi,
+  HostKvCasApi,
+  KvCasResult,
+  KvVersionedEntry,
+} from "./types.js";
+export { supportsKvCas } from "./types.js";