@cursor/july 0.1.32 → 0.1.34

package/src/memory.ts

@@ -16,14 +16,21 @@
  * path — typically a server tool under `agent/tools/`, which can resolve
  * state via `ctx.stateRoot`.
  *
- * TODO(agent-store): once agent-serve can mount the agent's AgentStore
- * (durable S3-backed filesystem shared across serve hosts and cloud VMs),
- * ship an AgentStore-backed backend and make it the default. The journal
- * format is designed to survive that move unchanged.
+ * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
+ * the journal lives on the deployment's Agent Store (survives deploys,
+ * visible on cloud VMs under the store mount) and is mirrored to
+ * `<stateRoot>/memory/journal.jsonl` so the workspace symlink read path
+ * keeps working for local-runtime turns.
  */
 
-import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { agentStoreKeys, FileConflictError, type FileSink } from "./files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "./files-backends/cursor-hosted.js";
 import { defineHook } from "./hooks.js";
 import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
 
@@ -48,11 +55,11 @@ export type TurnMemoryRecord = {
   usage?: TurnUsage;
 };
 
-/** Where turn records go. Receives the agent's state root per append. */
+/** Where turn records go. Receives the agent's state root and name per append. */
 export interface MemoryBackend {
   appendTurn(
     record: TurnMemoryRecord,
-    ctx: { stateRoot: string }
+    ctx: { stateRoot: string; agentName: string }
   ): Promise<void>;
 }
 
@@ -65,7 +72,7 @@ export interface FileMemoryBackendOptions {
 }
 
 /**
- * Default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
+ * Local default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
  * — the directory the framework symlinks into session workspaces. Rotated
  * segments stay alongside as `journal-<epoch-ms>.jsonl`.
  */
@@ -105,6 +112,112 @@ export function fileMemoryBackend(
   };
 }
 
+export interface AgentStoreMemoryBackendOptions {
+  /** Sink override (tests). Defaults to the deployment's Agent Store. */
+  sink?: FileSink;
+  /** Rotation threshold, same meaning as {@link FileMemoryBackendOptions}. */
+  maxJournalBytes?: number;
+}
+
+/**
+ * Journal on the deployment's Agent Store — durable across deploys, visible
+ * on cloud VMs under the store mount. Appends are read-modify-write with
+ * etag preconditions (retried on a lost race), then mirrored to
+ * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
+ */
+export function agentStoreMemoryBackend(
+  options: AgentStoreMemoryBackendOptions = {}
+): MemoryBackend {
+  const sink = options.sink ?? cursorHostedFiles();
+  const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
+  // Appends are chained per journal key (same shape as fileMemoryBackend);
+  // a failed append must not poison the chain for later turns.
+  const appendChains = new Map<string, Promise<void>>();
+
+  const append = async (
+    record: TurnMemoryRecord,
+    ctx: { stateRoot: string; agentName: string }
+  ): Promise<void> => {
+    const key = agentStoreKeys.memoryJournal(ctx.agentName);
+    const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const current = await sink.get(key);
+      const currentBody =
+        current === undefined
+          ? new Uint8Array(0)
+          : current instanceof Uint8Array
+            ? current
+            : current.body;
+      const etag =
+        current === undefined || current instanceof Uint8Array
+          ? undefined
+          : current.etag;
+      let next: Uint8Array;
+      let rotatedStamp: string | undefined;
+      if (currentBody.byteLength >= maxJournalBytes) {
+        rotatedStamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+        await sink.put(
+          agentStoreKeys.memoryJournalRotated(ctx.agentName, rotatedStamp),
+          currentBody,
+          { ifMatch: null }
+        );
+        next = line;
+      } else {
+        next = Buffer.concat([currentBody, line]);
+      }
+      try {
+        await sink.put(key, next, {
+          ifMatch: current === undefined ? null : etag,
+        });
+      } catch (error) {
+        if (error instanceof FileConflictError && attempt < 2) {
+          continue;
+        }
+        throw error;
+      }
+      await mirrorJournalLocally(ctx.stateRoot, next);
+      if (rotatedStamp !== undefined) {
+        // Rotated segments sit beside the live journal locally too, so the
+        // workspace symlink read path keeps pre-rotation history.
+        await writeFile(
+          join(ctx.stateRoot, MEMORY_DIR_NAME, `journal-${rotatedStamp}.jsonl`),
+          currentBody
+        );
+      }
+      return;
+    }
+  };
+
+  return {
+    async appendTurn(record, ctx) {
+      const key = agentStoreKeys.memoryJournal(ctx.agentName);
+      const prior = appendChains.get(key) ?? Promise.resolve();
+      const next = prior.catch(() => {}).then(() => append(record, ctx));
+      appendChains.set(key, next);
+      await next;
+    },
+  };
+}
+
+/** Atomic full rewrite of the local mirror; also hydrates a fresh pod after a deploy. */
+async function mirrorJournalLocally(
+  stateRoot: string,
+  contents: Uint8Array
+): Promise<void> {
+  const dir = join(stateRoot, MEMORY_DIR_NAME);
+  await mkdir(dir, { recursive: true });
+  const tmp = join(dir, `.tmp-${randomUUID()}`);
+  await writeFile(tmp, contents);
+  await rename(tmp, join(dir, "journal.jsonl"));
+}
+
+/** Hosted deployments journal to the Agent Store; local dev to plain files. */
+function defaultMemoryBackend(): MemoryBackend {
+  return isCursorHostedFilesAvailable()
+    ? agentStoreMemoryBackend()
+    : fileMemoryBackend();
+}
+
 export interface MemoryHookOptions {
   /** Where records go. Defaults to {@link fileMemoryBackend}. */
   backend?: MemoryBackend;
@@ -126,7 +239,7 @@ function truncate(text: string, max: number): string {
  * ```
  */
 export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
-  const backend = options.backend ?? fileMemoryBackend();
+  const backend = options.backend ?? defaultMemoryBackend();
   const maxTextLength = options.maxTextLength ?? 2000;
   // Inbound message per turn (truncated at receipt so large pastes are not
   // retained), keyed `<sessionId>/<turnId>` — `message.received` and the
@@ -167,7 +280,10 @@ export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
     if (usage !== undefined) {
       entry.usage = usage;
     }
-    await backend.appendTurn(entry, { stateRoot: ctx.stateRoot });
+    await backend.appendTurn(entry, {
+      stateRoot: ctx.stateRoot,
+      agentName: ctx.agent.name,
+    });
   };
 
   const sweepSession = (ctx: HookContext): void => {

package/src/storage.ts

@@ -276,7 +276,6 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
- * | `agentkit/v1/{agent}/artifacts/{id}` | `ArtifactRecord` via `ctx.artifacts` |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -307,11 +306,6 @@ export const storageKeys = {
   kv: (agent: string, key: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
   kvPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
-  /** Tagged artifact rows (see `ctx.artifacts` / `ArtifactsApi`). */
-  artifact: (agent: string, id: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/${keySegment(id)}`,
-  artifactPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/`,
 } as const;
 
 /**

package/src/types.ts

@@ -1838,6 +1838,8 @@ export interface ArtifactRecord {
   key?: string;
   title?: string;
   data: JsonValue;
+  /** Present when the artifact carries a file/blob payload (served at `GET /v1/artifacts/:id/content`). */
+  content?: { size: number; contentType?: string };
   sessionId?: string;
   turnId?: string;
   source: ArtifactSource;
@@ -1853,6 +1855,13 @@ export interface ArtifactTagInput {
   title?: string;
   /** Upsert key: tagging the same key again replaces the row. */
   key?: string;
+  /**
+   * File/blob payload, served via `GET /v1/artifacts/:id/content`.
+   * Re-tagging a keyed artifact without `contents` keeps the existing payload.
+   */
+  contents?: string | Uint8Array;
+  /** MIME type reported when serving {@link contents}. */
+  contentType?: string;
   /**
    * Session to attribute (and stream an `artifact.tagged` event to). On
    * session-bound facades ({@link ToolContext.artifacts},
@@ -2460,6 +2469,12 @@ export interface ServeOptions {
    * Local turns always use the loopback URL.
    */
   publicUrl?: string;
+  /**
+   * Authenticated HTTP MCP URL that proxies this hosted deployment's
+   * `/v1/mcp/tools` endpoint. Cloud turns use it to call authored server tools
+   * on the AgentSDK host. The resolved Cursor API key authenticates requests.
+   */
+  cloudToolsUrl?: string;
   /**
    * Pull GitHub webhook metadata from `/v0/scm-events` (Cursor account auth).
    * The stream is read as the host's Cursor user, so this requires a signed-in

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"}