@cursor/july 0.1.1 → 0.1.2

package/src/storage.ts

@@ -0,0 +1,325 @@
+/**
+ * Durable storage plug-in for agent-serve.
+ *
+ * Author `agent/storage.ts` with {@link defineStorage} to mirror the
+ * framework's durable state into storage you own (a database, S3, a data
+ * pipeline, …). Without it, state lives under `--state-root` on local disk
+ * only (and eval/A/B history follows the narrower `persistRuns` /
+ * `persistSamples` / `persistSnapshots` hooks).
+ *
+ * The sink is a plain key-value store — four functions, no schema:
+ *
+ * ```ts
+ * import { defineStorage } from "@anysphere/agent-serve/storage";
+ *
+ * export default defineStorage({
+ *   put: (key, value) => db.upsert(key, value),
+ *   get: (key) => db.get(key),
+ *   delete: (key) => db.delete(key),
+ *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
+ * });
+ * ```
+ *
+ * The **framework mints every key** from a stable, versioned scheme (see
+ * {@link storageKeys}) and decides **when** to call the sink: session
+ * records and event chunks flush when a turn's handlers have settled,
+ * reads happen at serve start (bulk restore), on continuation-token misses
+ * (lazy restore), and at playground hydration. Authors do not schedule
+ * reads or writes — the only timing knobs are {@link StoragePolicy}'s
+ * `debounceMs` (event write batching) and `restore` (startup hydration).
+ *
+ * Because keys are opaque strings to the sink, new kinds of durable state
+ * (channel cursors, thread affinity, …) are new key prefixes — existing
+ * sinks store them with no code changes.
+ *
+ * Delivery semantics: writes are **serialized** (one sink call in flight
+ * per agent, in order), **bounded** (a sink that falls behind sheds writes
+ * rather than growing memory), and **at-most-once** — a throwing `put` is
+ * logged and dropped, never retried, and never fails a turn. The local
+ * event log under `--state-root` remains the live source of truth; this
+ * interface is the durable mirror.
+ */
+
+import { createHash } from "node:crypto";
+import { brandDefinition } from "./internal/brand.js";
+import type { JsonValue } from "./types.js";
+
+// ============================================================================
+// Sink interface
+// ============================================================================
+
+/** One `{ key, value }` pair returned by {@link StorageConfig.list}. */
+export interface StorageEntry {
+  key: string;
+  value: JsonValue;
+}
+
+/** Context passed to every sink call. */
+export interface StorageContext {
+  /** Agent name (also baked into every key; see {@link storageKeys}). */
+  agentName: string;
+  /** Absolute agent project root (directory that contains `agent/`). */
+  projectRoot: string;
+  /**
+   * Why the framework is calling:
+   * - `"policy"` — a flush trigger fired (turn end, debounce, change)
+   * - `"shutdown"` — the serve process is draining; last chance to write
+   * - `"restore"` — serve start or a lazy restore; reads rebuilding state
+   */
+  reason: "policy" | "shutdown" | "restore";
+}
+
+export interface StoragePolicy {
+  /**
+   * Batch event-chunk writes on a quiet-period timer instead of flushing
+   * once per turn. The debounce **spans turn boundaries** — a rapid
+   * multi-turn exchange becomes one write when the session goes quiet —
+   * so it is the right choice for chatty sessions where per-turn writes
+   * are too many. Unset (default): one event chunk per turn.
+   */
+  debounceMs?: number;
+  /**
+   * Guardrails for the **startup bulk restore**. Whatever `list` returns
+   * is filtered to these caps before anything is written to local disk, so
+   * a large store cannot blow up `--state-root` or stall serve start.
+   * Newest sessions (by `updatedAt`) win within each cap.
+   *
+   * `"off"` disables the startup restore entirely — sessions then restore
+   * one at a time as follow-ups actually arrive (lazy-only; recommended
+   * for high-traffic deployments).
+   */
+  restore?: StorageRestorePolicy | "off";
+}
+
+/** Caps applied to the startup bulk restore. See {@link StoragePolicy.restore}. */
+export interface StorageRestorePolicy {
+  /** Max sessions materialized (default {@link STORAGE_DEFAULT_RESTORE_MAX_SESSIONS}). */
+  maxSessions?: number;
+  /**
+   * Skip sessions whose `updatedAt` is older than this (default
+   * {@link STORAGE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
+   * reachable lazily on their next follow-up.
+   */
+  maxAgeMs?: number;
+  /**
+   * Stop restoring once this many bytes of records + events have been
+   * written (default {@link STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
+   * Checked before each session is written, so one oversized stream
+   * cannot blow past the budget.
+   */
+  maxTotalBytes?: number;
+}
+
+export interface StorageConfig {
+  /** Optional label surfaced on `GET /v1/info` diagnostics. */
+  name?: string;
+  /** Timing knobs; see {@link StoragePolicy}. */
+  policy?: StoragePolicy;
+  /**
+   * Store one value under a key (upsert, last-write-wins). Called on the
+   * framework's schedule — never concurrently, always in order. Keep it
+   * fast or buffer internally: the delivery queue is bounded, so a sink
+   * that falls behind sustained traffic sheds writes (logged) instead of
+   * growing memory; it never stalls the agent loop.
+   */
+  put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
+  /** Remove a key. Optional — without it, deletions are skipped. */
+  delete?(key: string, ctx: StorageContext): void | Promise<void>;
+  /**
+   * Point lookup. Optional — required for **lazy restore** (resolving a
+   * continuation token on a replacement host) and the A/B backfill.
+   * Return `undefined`/`null` only for a **definitive** miss: on the lazy
+   * restore path a throw propagates and fails the follow-up (retryable) —
+   * a store outage must not read as "unknown token", which would fork the
+   * conversation onto a new session.
+   */
+  get?(
+    key: string,
+    ctx: StorageContext
+  ): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
+  /**
+   * All entries under a key prefix, in ascending key order. Optional —
+   * required for the **startup bulk restore** (sessions + event streams)
+   * and playground eval history.
+   */
+  list?(
+    prefix: string,
+    ctx: StorageContext
+  ): StorageEntry[] | Promise<StorageEntry[]>;
+}
+
+export type StorageDefinition = StorageConfig & {
+  readonly __agentServe: "storage";
+};
+
+/**
+ * Author the project storage sink (`agent/storage.ts`, default
+ * export). See the module doc for semantics and an example.
+ */
+export function defineStorage(config: StorageConfig): StorageDefinition {
+  if (typeof config.put !== "function") {
+    throw new Error("defineStorage: config.put must be a function");
+  }
+  for (const hook of ["get", "list", "delete"] as const) {
+    const value = config[hook];
+    if (value !== undefined && typeof value !== "function") {
+      throw new Error(
+        `defineStorage: config.${hook} must be a function when set`
+      );
+    }
+  }
+  // Validate eagerly so a bad policy fails at discovery, not first flush.
+  resolveStoragePolicy(config.policy);
+  return brandDefinition("storage", config);
+}
+
+// ============================================================================
+// Key scheme
+// ============================================================================
+
+/**
+ * Framework-owned key root. All {@link storageKeys} values live under this
+ * prefix so a shared store can route or namespace agentkit data.
+ */
+export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+
+/**
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
+ * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
+ * route on prefixes (e.g. event chunks to object storage, everything else
+ * to a database). Channel ids and continuation tokens are the only segments
+ * that may contain caller-controlled characters; they are URI-encoded, and
+ * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
+ * by a `sha256:…` digest — so every minted key has a bounded length that any
+ * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
+ * no matter what a caller stuffs into a token. The substitution is
+ * deterministic: writes and continuation lookups build the same key.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `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}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
+ * | `agentkit/v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
+ * | `agentkit/v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
+ */
+export const storageKeys = {
+  session: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
+  sessionPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/`,
+  sessionEvents: (
+    agent: string,
+    sessionId: string,
+    firstIndex: number
+  ): string =>
+    `${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}/`,
+  continuation: (
+    agent: string,
+    channelId: string,
+    continuationKey: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+  reminder: (agent: string, reminderId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
+  reminderPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
+  evalRun: (agent: string, runId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-run/${runId}`,
+  evalRunPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-run/`,
+  abSample: (agent: string, sessionId: string, at: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-sample/${sessionId}/${at}`,
+  abSnapshot: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
+} as const;
+
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export const MAX_KEY_SEGMENT_BYTES = 256;
+
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ */
+function keySegment(raw: string): string {
+  const encoded = encodeURIComponent(raw);
+  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
+    return encoded;
+  }
+  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
+
+// ============================================================================
+// Policy resolution
+// ============================================================================
+
+export const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1_000;
+export const STORAGE_DEFAULT_RESTORE_MAX_AGE_MS: number = 30 * 24 * 60 * 60_000;
+export const STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1_073_741_824; // 1 GiB
+
+/** {@link StoragePolicy} with defaults applied. */
+export interface ResolvedStoragePolicy {
+  /** Event-chunk flush trigger: per turn, or debounced across turns. */
+  events: "turnEnd" | { debounceMs: number };
+  restore:
+    | "off"
+    | { maxSessions: number; maxAgeMs: number; maxTotalBytes: number };
+}
+
+/** Apply {@link StoragePolicy} defaults (exposed for tooling/tests). */
+export function resolveStoragePolicy(
+  policy: StoragePolicy | undefined
+): ResolvedStoragePolicy {
+  return {
+    events:
+      policy?.debounceMs === undefined
+        ? "turnEnd"
+        : { debounceMs: clampInt(policy.debounceMs, 2_000, 0, 60_000) },
+    restore:
+      policy?.restore === "off"
+        ? "off"
+        : {
+            maxSessions: clampInt(
+              policy?.restore?.maxSessions,
+              STORAGE_DEFAULT_RESTORE_MAX_SESSIONS,
+              0,
+              1_000_000
+            ),
+            maxAgeMs: clampInt(
+              policy?.restore?.maxAgeMs,
+              STORAGE_DEFAULT_RESTORE_MAX_AGE_MS,
+              0,
+              10 * 365 * 24 * 60 * 60_000
+            ),
+            maxTotalBytes: clampInt(
+              policy?.restore?.maxTotalBytes,
+              STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES,
+              0,
+              1_099_511_627_776 // 1 TiB
+            ),
+          },
+  };
+}
+
+function clampInt(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number
+): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}

package/src/types.ts

@@ -11,6 +11,7 @@
 import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type { StorageDefinition } from "./storage.js";
 
 // ============================================================================
 // JSON
@@ -43,7 +44,8 @@ export type DefinitionKind =
   | "reminder"
   | "hook"
   | "eval"
-  | "ab";
+  | "ab"
+  | "storage";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -186,6 +188,34 @@ export interface AgentConfig {
    * {@link cloud}.
    */
   local?: AgentLocalOptions;
+  /**
+   * Managed-hosting declarations (`agentkit deploy` onto Cursor's
+   * agent-serve hosting). The manifest is the source of truth: deploy reads
+   * it and sends it with the deployment request. Ignored by local serving.
+   */
+  hosting?: AgentHostingOptions;
+}
+
+/**
+ * Managed-hosting block on {@link AgentConfig.hosting}.
+ */
+export interface AgentHostingOptions {
+  /**
+   * Domains the deployed engine pod may reach (egress allowlist), e.g.
+   * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
+   * Lowercase hostnames with at least two labels and an alphabetic TLD;
+   * max 20. `agentkit deploy` sends these as `egressAllowedDomains`
+   * (unioned with any `--allow-domain` flags). Only valid on repo-backed
+   * deployments.
+   */
+  egressDomains?: string[];
+  /**
+   * Secret names this agent expects at runtime (declarative documentation;
+   * values are never authored in files). `agentkit deploy` warns when a
+   * declared name is not set on the deployment — set values with
+   * `agentkit secrets set <slug> NAME`.
+   */
+  secretNames?: string[];
 }
 
 /**
@@ -1532,6 +1562,8 @@ export interface ResolvedAgent {
    * (`cwd` is absolute — relative paths resolved against the project root).
    */
   local?: AgentLocalOptions;
+  /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
+  hosting?: AgentHostingOptions;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
@@ -1556,6 +1588,8 @@ export interface AgentProject {
   abs: DiscoveredAB[];
   /** Optional `agent/ab.config.ts` (`defineABConfig`). */
   abConfig?: ABConfigFile;
+  /** Optional `agent/storage.ts` (`defineStorage`). */
+  storage?: StorageDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -1579,6 +1613,8 @@ export interface AgentProjectInfo {
   cloud?: AgentCloudPublicInfo;
   /** Local harness options when authored (`cwd` absolute). */
   local?: { cwd?: string };
+  /** Managed-hosting declarations when authored (egress allowlist, expected secrets). */
+  hosting?: { egressDomains?: string[]; secretNames?: string[] };
   /**
    * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
    * and MCP clients delegate to this agent through these tools.
@@ -1613,12 +1649,14 @@ export interface AgentProjectInfo {
   hooks: string[];
   /** Live A/B experiment names (`defineAB` under `agent/ab`). */
   abs: string[];
-  /** Playground fold / persistence meta from `agent/ab.config.ts`. */
+  /** Playground fold / durable-sink meta from `agent/ab.config.ts`. */
   abConfig?: {
     maxPlaygroundSessions?: number;
     durableSamples: boolean;
     durableSnapshots: boolean;
   };
+  /** Project storage sink from `agent/storage.ts`, when authored. */
+  storage?: { name?: string };
   diagnostics: Diagnostic[];
 }