@cursor/july 0.1.39 → 0.1.41

package/dist/internal/session-engine.js

@@ -15,17 +15,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
@@ -33,6 +22,8 @@ import { slackThreadPermalink } from "../channels/slack/links.js";
 import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
+import { SessionLedger, supportsSessionLedgerKv, } from "../ledger/session-ledger.js";
+import { fileKv } from "../storage-backends/file-kv.js";
 import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
@@ -43,6 +34,7 @@ import { samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { applyCloudUsageToEvents, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, 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";
@@ -51,6 +43,7 @@ import { createHostKvApi } from "./host-kv.js";
 import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, 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, SCHEDULE_CHANNEL_PREFIX, } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
@@ -211,6 +204,67 @@ 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.
+     */
+    buildLedgerServing(options) {
+        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, Object.assign(Object.assign({}, 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.
+     */
+    resolveDurableSessionStore(options) {
+        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);
     }
     /**
      * Attach serve-time resolved connections (peers, Cursor account bridge).
@@ -349,6 +403,12 @@ export class SessionEngine {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
             var _a;
             var _b, _c, _d, _e, _f;
+            // 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 = (_b = options.auth) !== null && _b !== void 0 ? _b : null;
             let existing = options.continuationToken === undefined
                 ? undefined
@@ -365,12 +425,14 @@ 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 (options.workspaceDir !== undefined &&
-                    options.workspaceDir !== existing.workspaceOverride) {
-                    record = yield this.updateRecord(existing.sessionId, (current) => { var _a; return (Object.assign(Object.assign({}, current), { workspaceOverride: options.workspaceDir, pendingWorkspaceFiles: (_a = options.workspaceFiles) !== null && _a !== void 0 ? _a : current.pendingWorkspaceFiles })); });
-                }
-                else if (options.workspaceFiles !== undefined) {
-                    record = yield this.updateRecord(existing.sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: options.workspaceFiles })));
+                const refreshWorkspace = options.workspaceDir !== undefined &&
+                    options.workspaceDir !== existing.workspaceOverride;
+                if (refreshWorkspace ||
+                    options.workspaceFiles !== undefined ||
+                    options.images !== undefined) {
+                    record = yield this.updateRecord(existing.sessionId, (current) => (Object.assign(Object.assign({}, current), { 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
                 // caller's CURRENT cloud options (e.g. a PR attach re-derived per wake),
@@ -399,6 +461,7 @@ export class SessionEngine {
                 channelState,
                 workspaceOverride: options.workspaceDir,
                 pendingWorkspaceFiles: options.workspaceFiles,
+                pendingImages: options.images,
                 cloudOverride: options.cloud,
                 sdkAgentId: options.sdkAgentId,
                 turnCount: 0,
@@ -918,13 +981,19 @@ export class SessionEngine {
                         stateRoot: this.stateRoot,
                     });
                     const pendingFiles = record.pendingWorkspaceFiles;
+                    const pendingImages = record.pendingImages;
                     if (pendingFiles !== undefined &&
                         Object.keys(pendingFiles).length > 0) {
                         yield writeWorkspaceFiles(harnessCwd, pendingFiles);
-                        yield this.updateRecord(sessionId, (current) => {
-                            const { pendingWorkspaceFiles: _cleared } = current, rest = __rest(current, ["pendingWorkspaceFiles"]);
-                            return rest;
-                        });
+                    }
+                    if ((pendingFiles !== undefined &&
+                        Object.keys(pendingFiles).length > 0) ||
+                        (pendingImages !== undefined && pendingImages.length > 0)) {
+                        yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, 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
@@ -945,7 +1014,7 @@ export class SessionEngine {
                             update.type === "tool-call-delta") {
                             yield yieldEventLoop();
                         }
-                    }), signal);
+                    }), signal, pendingImages);
                     this.activeToolContexts.set(sessionId, { record, turnId, emit });
                     try {
                         outcome = yield this.runner.runTurn(request);
@@ -1024,7 +1093,7 @@ export class SessionEngine {
             return Object.assign(Object.assign(Object.assign({}, outcome), (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage }));
         });
     }
-    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal) {
+    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal, images) {
         var _a, _b, _c;
         // Per-session cloud attach (channel/tool handoff) forces cloud runtime
         // even when the agent defaults to local for chat server tools.
@@ -1078,9 +1147,9 @@ export class SessionEngine {
                 turnPrompt = `${preamble}\n\n${turnPrompt}`;
             }
         }
-        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
             ? {}
-            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true, runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId), subagents: buildRunnerSubagents(agent), onUpdate,
+            : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true, 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 })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId), subagents: buildRunnerSubagents(agent), onUpdate,
             signal, 
             // Local follow-ups expire any lingering active run so a preempted turn
             // (or one orphaned by a crashed process) never blocks this send.
@@ -2412,22 +2481,42 @@ export class SessionEngine {
     /** Drain running turns, dispatches, and pending writes, then dispose. */
     close() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             this.approvals.cancelAll("deny");
+            // Ledger deliveries spawn turns, so settle them before activeTurns.
+            yield (_a = this.ledgerServing) === null || _a === void 0 ? void 0 : _a.close();
             yield Promise.allSettled([...this.activeTurns.values()]);
             yield Promise.allSettled([...this.backgroundWork]);
             yield Promise.allSettled([...this.dispatchChains.values()]);
             yield Promise.allSettled([...this.updateChains.values()]);
             yield this.logs.flushAll();
-            yield (_a = this.storage) === null || _a === void 0 ? void 0 : _a.close();
+            yield (_b = this.storage) === null || _b === void 0 ? void 0 : _b.close();
             yield this.mcpHost.close();
-            yield (_c = (_b = this.runner).dispose) === null || _c === void 0 ? void 0 : _c.call(_b);
+            yield (_d = (_c = this.runner).dispose) === null || _d === void 0 ? void 0 : _d.call(_c);
         });
     }
 }
 /** Parallel event-stream loads during the startup bulk restore. */
 const RESTORE_FETCH_CONCURRENCY = 8;
 /** NDJSON payload for a restored event stream; undefined when empty. */
+function mergePendingImages(current, incoming) {
+    if (incoming === undefined) {
+        return current;
+    }
+    if (current === undefined || current.length === 0) {
+        return incoming;
+    }
+    return [...current, ...incoming];
+}
+function mergePendingWorkspaceFiles(current, incoming) {
+    if (incoming === undefined) {
+        return current;
+    }
+    if (current === undefined) {
+        return incoming;
+    }
+    return Object.assign(Object.assign({}, current), incoming);
+}
 function eventsNdjson(events) {
     if (events.length === 0) {
         return undefined;

package/dist/internal/slack-provision-client.js

@@ -250,7 +250,7 @@ function mapErrorResponse(response, bodyText, context) {
         case 401:
             return new SlackProvisionApiError("The Cursor API key was rejected. Run `agent-sdk login` again or update CURSOR_API_KEY.", { status: 401 });
         case 403:
-            return new SlackProvisionApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — Slack provisioning needs team-admin permission and the cloud-agent entitlement on that team.`, { status: 403 });
+            return new SlackProvisionApiError(`${serverError !== null && serverError !== void 0 ? serverError : "Not authorized"} — Slack provisioning needs team membership and the cloud-agent entitlement on that team.`, { status: 403 });
         case 404: {
             // Fastify's route-not-found envelope means we hit the wrong host
             // (api2 vs api.cursor.com), not a closed gate.

package/dist/internal/workspace.d.ts

@@ -108,7 +108,11 @@ export declare function materializeWorkspace(options: MaterializeWorkspaceOption
 export declare 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 declare function writeWorkspaceFiles(workspaceDir: string, files: Record<string, string>): Promise<void>;
+export declare function writeWorkspaceFiles(workspaceDir: string, files: Record<string, string | {
+    encoding: "base64";
+    data: string;
+    mimeType?: string;
+}>): Promise<void>;
 //# sourceMappingURL=workspace.d.ts.map

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/internal/workspace.js

@@ -352,14 +352,22 @@ export function buildSkillMd(skill) {
 }
 /**
  * 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 function writeWorkspaceFiles(workspaceDir, files) {
     return __awaiter(this, void 0, void 0, function* () {
         for (const [relativePath, contents] of Object.entries(files)) {
             const target = resolveWorkspaceWritePath(workspaceDir, relativePath);
             yield mkdir(dirname(target), { recursive: true });
-            yield writeFile(target, contents, "utf8");
+            if (typeof contents === "string") {
+                yield writeFile(target, contents, "utf8");
+            }
+            else if (contents.encoding === "base64") {
+                yield writeFile(target, Buffer.from(contents.data, "base64"));
+            }
+            else {
+                throw new Error(`Unsupported workspace file encoding for ${relativePath}`);
+            }
         }
     });
 }

package/dist/kv/memory-kv.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 } from "../types.js";
+/** Create an empty in-memory CAS-capable KV. */
+export declare function createMemoryKv(): HostKvCasApi;
+/**
+ * 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 declare function memoryCasTable(): StorageCasTable;
+//# sourceMappingURL=memory-kv.d.ts.map

package/dist/kv/memory-kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kv.d.ts","sourceRoot":"","sources":["../../src/kv/memory-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,aAAa,CAAC;AAErB,gDAAgD;AAChD,wBAAgB,cAAc,IAAI,YAAY,CA4D7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAShD"}

package/dist/kv/memory-kv.js

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+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());
+    });
+};
+/** Create an empty in-memory CAS-capable KV. */
+export function createMemoryKv() {
+    const entries = new Map();
+    let versionCounter = 0;
+    const nextVersion = () => {
+        versionCounter += 1;
+        return `v${versionCounter}`;
+    };
+    const snapshot = (key) => {
+        const entry = entries.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        return { value: structuredClone(entry.value), version: entry.version };
+    };
+    return {
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                return (_a = snapshot(key)) === null || _a === void 0 ? void 0 : _a.value;
+            });
+        },
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                entries.set(key, {
+                    value: structuredClone(value),
+                    version: nextVersion(),
+                });
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                entries.delete(key);
+            });
+        },
+        getWithVersion(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return snapshot(key);
+            });
+        },
+        putIfAbsent(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (entries.has(key)) {
+                    return { ok: false, current: snapshot(key) };
+                }
+                const version = nextVersion();
+                entries.set(key, { value: structuredClone(value), version });
+                return { ok: true, version };
+            });
+        },
+        putIfVersion(key, value, expectedVersion) {
+            return __awaiter(this, void 0, void 0, function* () {
+                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 };
+            });
+        },
+        listKeys(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                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() {
+    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/dist/kv.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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";
+//# sourceMappingURL=kv.d.ts.map

package/dist/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,YAAY,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/kv.js

@@ -0,0 +1,20 @@
+/**
+ * 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 { supportsKvCas } from "./types.js";