@cursor/july 0.1.97 → 0.1.100

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

@@ -0,0 +1,219 @@
+/**
+ * Cursor-managed durable KV for hosted **architecture v2** agents.
+ *
+ * Talks to the AgentSDK v2 KV proxy
+ * (`POST /internal/agentsdk/kv/*`) using the engine's pod
+ * `CURSOR_API_KEY`. The server resolves the v2 deployment from that service
+ * account (factorydb `agentsdk_deployment`) and persists rows in factorydb
+ * `agentsdk_kv` — v1's Bugbot-backed `/internal/agent-serve/storage/*`
+ * routes cannot resolve a v2 pod credential at all.
+ *
+ * The v2 wire protocol is four routes, not v1's eight:
+ *
+ * - `POST /internal/agentsdk/kv/get`
+ *   `{ key }` → `{ found, value, version }` — reads always carry the CAS
+ *   version token ({@link KvV2GetResponse}).
+ * - `POST /internal/agentsdk/kv/put`
+ *   `{ key, value, ifAbsent? | ifVersion? }` → `{ ok, version, current }`
+ *   ({@link KvV2PutResponse}) — one write primitive: last-write-wins when
+ *   unconditional (still bumps the token), atomic create-if-absent with
+ *   `ifAbsent: true`, atomic compare-and-swap with `ifVersion`.
+ * - `POST /internal/agentsdk/kv/delete` `{ key }` → `{ ok }`.
+ * - `POST /internal/agentsdk/kv/list`
+ *   `{ prefix, limit?, cursor?, keysOnly? }` → `{ entries, nextCursor }`
+ *   ({@link KvV2ListResponse}) — ascending key order with keyset
+ *   pagination. `list` / `listKeys` below drain every page, so the v1
+ *   truncated-scan failure mode does not exist here.
+ *
+ * Eval runs and A/B samples still ride the v1 storage proxy's dedicated
+ * tables (`evals` / `abs` below); moving them to factorydb is a separate
+ * follow-up from the KV cutover.
+ *
+ * This backend is platform-selected for architecture v2
+ * (framework-storage-selection.ts) — authors never import it; `agent/storage.ts`
+ * is rejected on v2.
+ */
+
+import type {
+  StorageABTable,
+  StorageCasTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
+import {
+  CURSOR_HOSTED_STORAGE,
+  type CursorHostedStorageOptions,
+  cursorHostedStorage,
+  storageRpc,
+} from "./cursor-hosted.js";
+
+const KV_V2_PREFIX = "/internal/agentsdk/kv";
+
+/** Wire shape of the v2 `get` route. `null` ⇒ JSON `undefined`. */
+export interface KvV2GetResponse {
+  found: boolean;
+  value: JsonValue | null;
+  version: string | null;
+}
+
+/** Wire shape of the v2 `put` route (all three write modes). */
+export interface KvV2PutResponse {
+  ok: boolean;
+  /** New version token on an accepted write, else `null`. */
+  version: string | null;
+  /** Entry observed when a conditional write lost; `null` when absent. */
+  current: { value: JsonValue | null; version: string } | null;
+}
+
+/** Wire shape of the v2 `list` route. */
+export interface KvV2ListResponse {
+  entries: Array<{
+    key: string;
+    /** Omitted when the request asked for keys only. */
+    value?: JsonValue | null;
+    version: string;
+  }>;
+  /** Last key of this page when more rows remain, else `null`. */
+  nextCursor: string | null;
+}
+
+type CursorHostedStorageV2Methods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  readonly [CURSOR_HOSTED_STORAGE]: true;
+  cas: StorageCasTable;
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+function toCasResult(response: KvV2PutResponse): KvCasResult {
+  if (response.ok) {
+    if (response.version === null) {
+      throw new Error(
+        "cursorHostedStorageV2: conditional write succeeded without a version token"
+      );
+    }
+    return { ok: true, version: response.version };
+  }
+  const current: KvVersionedEntry | undefined =
+    response.current === null
+      ? undefined
+      : {
+          value: response.current.value ?? null,
+          version: response.current.version,
+        };
+  return { ok: false, current };
+}
+
+/**
+ * Drain every page of a v2 `list` scan. The server pages by keyset (each
+ * `nextCursor` is the strictly-greatest key returned so far), so a cursor
+ * that fails to advance means a broken server — fail loudly rather than
+ * loop forever.
+ */
+async function listAllPages(
+  options: CursorHostedStorageOptions,
+  body: { prefix: string; keysOnly?: boolean }
+): Promise<KvV2ListResponse["entries"]> {
+  const entries: KvV2ListResponse["entries"] = [];
+  let cursor: string | undefined;
+  for (;;) {
+    const page = await storageRpc<KvV2ListResponse>(
+      options,
+      `${KV_V2_PREFIX}/list`,
+      cursor === undefined ? body : { ...body, cursor }
+    );
+    entries.push(...page.entries);
+    if (page.nextCursor === null) {
+      return entries;
+    }
+    if (cursor !== undefined && page.nextCursor <= cursor) {
+      throw new Error(
+        `cursorHostedStorageV2: list("${body.prefix}") cursor did not advance`
+      );
+    }
+    cursor = page.nextCursor;
+  }
+}
+
+/**
+ * Architecture-v2 `defineStorage` methods (AgentSDK v2 KV proxy → factorydb
+ * `agentsdk_kv`). Platform-selected; spread into `defineStorage({...})` by
+ * framework-storage-selection.ts. No `listNewest`: v2 session records live
+ * on the framework file store, so the only consumer of write-time ordering
+ * never reaches this backend and the engine's `list` fallback covers the
+ * rest.
+ */
+export function cursorHostedStorageV2(
+  options: CursorHostedStorageOptions = {}
+): CursorHostedStorageV2Methods {
+  // Eval runs and A/B samples stay on the v1 proxy's dedicated tables.
+  const v1 = cursorHostedStorage(options);
+  return {
+    [CURSOR_HOSTED_STORAGE]: true,
+    async put(key, value): Promise<void> {
+      await storageRpc(options, `${KV_V2_PREFIX}/put`, { key, value });
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await storageRpc<KvV2GetResponse>(
+        options,
+        `${KV_V2_PREFIX}/get`,
+        { key }
+      );
+      if (!result.found) {
+        return undefined;
+      }
+      return result.value ?? undefined;
+    },
+    async delete(key): Promise<void> {
+      await storageRpc(options, `${KV_V2_PREFIX}/delete`, { key });
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const entries = await listAllPages(options, { prefix });
+      return entries.map((entry) => ({
+        key: entry.key,
+        value: entry.value ?? null,
+      }));
+    },
+    cas: {
+      async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
+        const result = await storageRpc<KvV2GetResponse>(
+          options,
+          `${KV_V2_PREFIX}/get`,
+          { key }
+        );
+        if (!result.found || result.version === null) {
+          return undefined;
+        }
+        return { value: result.value ?? null, version: result.version };
+      },
+      async putIfAbsent(key, value): Promise<KvCasResult> {
+        const result = await storageRpc<KvV2PutResponse>(
+          options,
+          `${KV_V2_PREFIX}/put`,
+          { key, value, ifAbsent: true }
+        );
+        return toCasResult(result);
+      },
+      async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
+        const result = await storageRpc<KvV2PutResponse>(
+          options,
+          `${KV_V2_PREFIX}/put`,
+          { key, value, ifVersion: expectedVersion }
+        );
+        return toCasResult(result);
+      },
+      async listKeys(prefix): Promise<string[]> {
+        const entries = await listAllPages(options, {
+          prefix,
+          keysOnly: true,
+        });
+        return entries.map((entry) => entry.key);
+      },
+    },
+    evals: v1.evals,
+    abs: v1.abs,
+  };
+}

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

@@ -207,7 +207,12 @@ function resolveBaseUrl(options: CursorHostedStorageOptions): string {
   return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
 
-async function storageRpc<T>(
+/**
+ * One authenticated POST to the control-plane proxy. Shared with the
+ * architecture-v2 backend (`cursor-hosted-v2.ts`), which speaks a different
+ * route family over the same transport and credential chain.
+ */
+export async function storageRpc<T>(
   options: CursorHostedStorageOptions,
   path: string,
   body: Record<string, unknown>

package/src/storage-protocol.ts

@@ -38,6 +38,7 @@ const DURABLE_SESSION_RECORD_KEY_RE =
  * | --- | --- |
  * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `agentkit/v1/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
  *
@@ -59,6 +60,15 @@ export const storageKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
   sessionEventsPrefix: (agent: string, sessionId: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
+  /**
+   * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+   * the factory `ses_…` so a throw that never minted a July session still
+   * lands under a stable key. Per-execution rows live inside the document.
+   */
+  sessionRun: (agent: string, sessionPublicId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
+  sessionRunsPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-runs/`,
   continuation: (
     agent: string,
     channelId: string,

package/src/tools.ts

@@ -99,6 +99,15 @@ type ServerToolConfig<TSchema> = {
    * write, so a dry-run session answers it instead of running it.
    */
   effect?: ToolEffectDeclaration<ToolInput<TSchema>>;
+  /**
+   * Input properties carrying time bounds. In an `asOf` session each named
+   * argument must be an absolute ISO-8601 instant with a timezone, no later
+   * than the frozen instant; a call that omits one, or supplies a relative
+   * or later value, is refused so the model retries with absolute bounds.
+   * Names must exist in {@link inputSchema} or the frozen session refuses to
+   * start. Ignored without `asOf`.
+   */
+  timeArgs?: readonly string[];
   /** What a `"write"` tool returns in a dry-run session. */
   dryRunResult?:
     | ToolExecuteResult
@@ -126,10 +135,11 @@ type AgentToolConfig<TSchema> = {
   needsApproval?: never;
   /**
    * Agent tools run inside the harness, not through the host's tool path, so
-   * a dry run cannot answer them. Classify the work as a server tool if it
-   * needs to be dry-runnable.
+   * a dry run cannot answer them and an `asOf` session cannot bound them.
+   * Classify the work as a server tool if it needs either.
    */
   effect?: never;
+  timeArgs?: never;
   dryRunResult?: never;
 };
 

package/src/types.ts

@@ -880,6 +880,8 @@ export interface ToolContext {
    * `subagent.completed`). Omitted for scratch `callTool` with no session.
    */
   emit?: (payload: SessionEventPayload) => void;
+  /** The session's frozen `asOf`, or the wall clock. Use instead of `Date.now()`. */
+  now(): Date;
 }
 
 /**
@@ -992,6 +994,17 @@ export interface ToolConfig<TInput> {
    * write, so a dry run stubs it — see {@link ToolEffect}.
    */
   effect?: ToolEffectDeclaration<TInput>;
+  /**
+   * Input properties that carry time bounds. In a session created with
+   * {@link SendMessageOptions.asOf}, every named argument must be an
+   * absolute ISO-8601 instant with a timezone, no later than the session's
+   * frozen instant — a call that omits one, or supplies a relative or later
+   * value, is refused so the model retries with absolute bounds. Names must
+   * exist in {@link inputSchema}; a session with `asOf` refuses to start
+   * otherwise, because a misspelled name would silently check nothing.
+   * Ignored in sessions without `asOf`.
+   */
+  timeArgs?: readonly string[];
   /**
    * What a write tool returns in a dry-run session instead of executing.
    *
@@ -1025,6 +1038,7 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
   readonly effect?: ToolEffectDeclaration<never>;
+  readonly timeArgs?: readonly string[];
   readonly dryRunResult?:
     | ToolExecuteResult
     | ((input: never) => ToolExecuteResult);
@@ -1624,6 +1638,8 @@ export interface SessionInfo {
   purpose?: SessionPurpose;
   /** True when write-classified tool calls are answered by the host. */
   dryRun?: boolean;
+  /** Frozen instant this session reads at; absent means the wall clock. */
+  asOf?: string;
   auth: AuthContext | null;
   title?: string;
   /**
@@ -1658,6 +1674,8 @@ export interface SessionRecord {
   purpose?: SessionPurpose;
   /** Frozen at create from {@link SendMessageOptions.dryRun}. */
   dryRun?: boolean;
+  /** Frozen at create from {@link SendMessageOptions.asOf}. */
+  asOf?: string;
   /**
    * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
    * the agent loop / tools can read arms without re-folding the log. Source
@@ -1853,6 +1871,13 @@ export interface SendMessageOptions {
    * model chose stay on the session log as the record of the intended action.
    */
   dryRun?: boolean;
+  /**
+   * ISO-8601 instant with a timezone, frozen at create: the prompt states
+   * it, {@link ToolContext.now} returns it, and tools that declare
+   * {@link ToolConfig.timeArgs} refuse calls not bounded at or before it. A
+   * tool that declares nothing still reads the present.
+   */
+  asOf?: string;
   /**
    * Absolute directory used as the local harness `cwd` for this session.
    * On create, sets the session workspace. On resume (continuation hit),
@@ -2289,6 +2314,11 @@ export interface ChannelMeta {
    * by `info` so watched channels are auditable.
    */
   slackChannelPosts?: readonly string[];
+  /**
+   * Author-facing notices about deprecated options the pack still honored.
+   * Discovery surfaces each one as a `validate` warning on the channel file.
+   */
+  deprecations?: readonly string[];
 }
 
 export interface ChannelConfig<TState = JsonValue> {