@cursor/july 0.1.24 → 0.1.26

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

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { defineStorage, type StorageContext } from "../storage.js";
+import {
+  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+  AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+  CURSOR_HOSTED_STORAGE,
+  CURSOR_HOSTED_STORAGE_ENV_VARS,
+  cursorHostedStorage,
+  isCursorHostedStorage,
+} from "./cursor-hosted.js";
+
+const storageCtx: StorageContext = {
+  agentName: "test-agent",
+  projectRoot: "/tmp/test-agent",
+  reason: "policy",
+};
+
+describe("cursorHostedStorage", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("exports the platform-managed env names", () => {
+    expect(AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR).toBe(
+      "BUGBOTDB_URL"
+    );
+    expect(AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR).toBe("AGENT_SERVE_DEPLOYMENT_ID");
+    expect(CURSOR_HOSTED_STORAGE_ENV_VARS).toEqual([
+      "BUGBOTDB_URL",
+      "AGENT_SERVE_DEPLOYMENT_ID",
+    ]);
+  });
+
+  it("requires CURSOR_API_KEY", async () => {
+    vi.stubEnv("CURSOR_API_KEY", "");
+    const methods = cursorHostedStorage({
+      baseUrl: "https://api.cursor.com",
+    });
+    await expect(methods.put("k", 1, storageCtx)).rejects.toThrow(
+      /CURSOR_API_KEY/
+    );
+  });
+
+  it("calls the control-plane storage proxy with the pod credential", async () => {
+    const fetchMock = vi.fn(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        expect(String(input)).toBe(
+          "https://api.cursor.com/internal/agent-serve/storage/kv/put"
+        );
+        expect(init?.method).toBe("POST");
+        expect(init?.headers).toMatchObject({
+          Authorization: "Bearer key_pod",
+          "Content-Type": "application/json",
+        });
+        expect(JSON.parse(String(init?.body))).toEqual({
+          key: "session/1",
+          value: { ok: true },
+        });
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      }
+    );
+
+    const methods = cursorHostedStorage({
+      baseUrl: "https://api.cursor.com",
+      apiKey: "key_pod",
+      fetch: fetchMock as typeof fetch,
+    });
+
+    await methods.put("session/1", { ok: true }, storageCtx);
+    expect(fetchMock).toHaveBeenCalledOnce();
+  });
+
+  it("maps get misses to undefined", async () => {
+    const methods = cursorHostedStorage({
+      baseUrl: "https://api.cursor.com",
+      apiKey: "key_pod",
+      fetch: (async () =>
+        new Response(JSON.stringify({ found: false, value: null }), {
+          status: 200,
+        })) as typeof fetch,
+    });
+    await expect(methods.get("missing", storageCtx)).resolves.toBeUndefined();
+  });
+
+  it("exposes evals and abs surfaces", () => {
+    const methods = cursorHostedStorage({
+      baseUrl: "https://api.cursor.com",
+      apiKey: "key_pod",
+      fetch: (async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+        })) as typeof fetch,
+    });
+    expect(typeof methods.evals.put).toBe("function");
+    expect(typeof methods.abs.putSample).toBe("function");
+    expect(typeof methods.abs.getSnapshot).toBe("function");
+  });
+
+  it("marks the sink so defineStorage preserves cursor-hosted detection", () => {
+    const methods = cursorHostedStorage({
+      baseUrl: "https://api.cursor.com",
+      apiKey: "key_pod",
+      fetch: (async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+        })) as typeof fetch,
+    });
+    expect(methods[CURSOR_HOSTED_STORAGE]).toBe(true);
+    expect(isCursorHostedStorage(methods)).toBe(true);
+    expect(
+      isCursorHostedStorage(
+        defineStorage({
+          name: "cursor-hosted",
+          ...methods,
+        })
+      )
+    ).toBe(true);
+    expect(isCursorHostedStorage(defineStorage({ put: () => {} }))).toBe(false);
+  });
+});

package/src/storage.ts

@@ -277,6 +277,7 @@ export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
  * | `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}).
@@ -311,6 +312,11 @@ 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

@@ -45,7 +45,8 @@ export type DefinitionKind =
   | "hook"
   | "eval"
   | "ab"
-  | "storage";
+  | "storage"
+  | "artifacts";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -516,6 +517,11 @@ export interface ToolContext {
     channelId: string,
     sessionId: string
   ): Promise<ChannelSession | null>;
+  /**
+   * Durable artifacts, bound to this tool call's session: `tag` auto-fills
+   * `sessionId` (and `turnId` when known).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**
@@ -922,6 +928,18 @@ export type SessionEventPayload =
       data: { callId: string; name?: string; description?: string };
     }
   | { type: "subagent.completed"; data: { callId: string; name?: string } }
+  | {
+      /** An artifact was tagged for this session (see {@link ArtifactsApi.tag}). */
+      type: "artifact.tagged";
+      data: {
+        id: string;
+        kind: string;
+        key?: string;
+        title?: string;
+        data: JsonValue;
+        source: ArtifactSource;
+      };
+    }
   | {
       type: "turn.completed";
       data: { result?: string; usage?: TurnUsage };
@@ -1292,6 +1310,11 @@ export interface ChannelHandlerArgs {
     request: Request,
     sessionId: string
   ): { playgroundUrl: string; traceUrl: string };
+  /**
+   * Durable artifacts (unbound — channel handlers have no ambient session;
+   * pass `sessionId` in `tag` input to attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type ChannelRouteHandler = (
@@ -1482,6 +1505,12 @@ export interface ChannelStartArgs {
    * should prefer this over `console.*` so CLI/eval hosts can redirect.
    */
   logger: (line: string) => void;
+  /**
+   * Durable artifacts (unbound, same facade as
+   * {@link ChannelHandlerArgs.artifacts}) — for host pipelines the channel
+   * drives outside any route handler.
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**
@@ -1528,7 +1557,7 @@ export interface ChannelConfig<TState = JsonValue> {
    */
   receive?: (
     input: ReceiveInput,
-    args: { send: SendMessageFn }
+    args: { send: SendMessageFn; artifacts: ArtifactsApi }
     // biome-ignore lint/suspicious/noConfusingVoidType: hooks may return a session, nothing, or an async nothing
   ) => Promise<ChannelSession | undefined | void> | ChannelSession | void;
   /** Stream-event handlers for sessions owned by this channel. */
@@ -1575,6 +1604,11 @@ export interface HookContext {
    * memory journal) write here.
    */
   stateRoot: string;
+  /**
+   * Durable artifacts, bound to this hook's session: `tag` auto-fills
+   * `sessionId` (and `turnId` when known).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type HookHandler<TEvent extends SessionEvent = SessionEvent> = (
@@ -1595,6 +1629,107 @@ export interface HookConfig {
 
 export type HookDefinition = HookConfig & BrandedDefinition<"hook">;
 
+// ============================================================================
+// Artifacts (agent/artifacts.ts)
+// ============================================================================
+
+/** One declared artifact kind (see {@link ArtifactsConfig.kinds}). */
+export interface ArtifactKindConfig {
+  /**
+   * What this kind holds. Also the model-facing prompt for the
+   * `tag_artifact` built-in tool when {@link ArtifactsConfig.agentTool}
+   * is enabled.
+   */
+  description: string;
+  /**
+   * Optional Zod schema; `tag` validates the payload against it and
+   * persists the parsed output (defaults and coercions applied), so
+   * the schema's output must stay JSON-serializable.
+   */
+  schema?: z.ZodType;
+}
+
+/** Input to `defineArtifacts` (authored at `agent/artifacts.ts`). */
+export interface ArtifactsConfig {
+  /**
+   * Declared artifact kinds. With kinds declared, `tag` only accepts
+   * these; with none, any kind string is accepted freeform.
+   */
+  kinds?: Record<string, ArtifactKindConfig>;
+  /**
+   * Expose the model-facing `tag_artifact` built-in tool generated from
+   * {@link kinds}. Requires at least one declared kind.
+   */
+  agentTool?: boolean;
+  /**
+   * Retention cap (default 1000). On insert past the cap, the
+   * oldest-updated artifact is evicted.
+   */
+  max?: number;
+}
+
+export type ArtifactsDefinition = ArtifactsConfig &
+  BrandedDefinition<"artifacts">;
+
+/** Who tagged an artifact: host code, or the model via `tag_artifact`. */
+export type ArtifactSource = "host" | "model";
+
+/** One durable tagged artifact. */
+export interface ArtifactRecord {
+  /** Stable id: derived from {@link key} when present, else random. */
+  id: string;
+  kind: string;
+  /** Author-chosen upsert key (same key ⇒ same id ⇒ replaces the row). */
+  key?: string;
+  title?: string;
+  data: JsonValue;
+  sessionId?: string;
+  turnId?: string;
+  source: ArtifactSource;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Input to {@link ArtifactsApi.tag}. */
+export interface ArtifactTagInput {
+  /** Defaults to `"artifact"` when no kinds are declared. */
+  kind?: string;
+  data: JsonValue;
+  title?: string;
+  /** Upsert key: tagging the same key again replaces the row. */
+  key?: string;
+  /**
+   * Session to attribute (and stream an `artifact.tagged` event to). On
+   * session-bound facades ({@link ToolContext.artifacts},
+   * {@link HookContext.artifacts}) this is auto-filled and a different
+   * value is rejected; unbound facades
+   * ({@link ChannelHandlerArgs.artifacts}) accept it explicitly.
+   */
+  sessionId?: string;
+  turnId?: string;
+  /** Defaults to `"host"`. */
+  source?: ArtifactSource;
+}
+
+/** Filter for {@link ArtifactsApi.list}. */
+export interface ArtifactListFilter {
+  kind?: string;
+  sessionId?: string;
+}
+
+/**
+ * The artifacts API, attached as `ctx.artifacts` on tools
+ * ({@link ToolContext}), hooks ({@link HookContext}), and channel handlers
+ * ({@link ChannelHandlerArgs}). Tool and hook facades are session-bound:
+ * `tag` auto-fills the session; the channel facade is unbound.
+ */
+export interface ArtifactsApi {
+  /** Tag (upsert) one artifact. See {@link ArtifactTagInput}. */
+  tag(input: ArtifactTagInput): Promise<ArtifactRecord>;
+  /** Tagged artifacts, newest-updated first. */
+  list(filter?: ArtifactListFilter): Promise<ArtifactRecord[]>;
+}
+
 // ============================================================================
 // Schedules (agent/schedules/*)
 // ============================================================================
@@ -1613,6 +1748,11 @@ export interface ScheduleHandlerArgs {
   appAuth: AuthContext;
   /** Shared host services (MCP / GitHub / Slack). Same as tool `ctx.host`. */
   host: HostContext;
+  /**
+   * Durable artifacts (unbound — schedule handlers have no ambient session;
+   * pass `sessionId` explicitly to attribute).
+   */
+  artifacts: ArtifactsApi;
 }
 
 export interface ScheduleConfig {
@@ -1666,6 +1806,12 @@ export interface ReminderFireContext extends ReminderUntilContext {
   /** Wake the reminder's already-bound session (target is implicit). */
   followup(args: { message: string }): Promise<ChannelSession>;
   cancel(reason?: string): Promise<void>;
+  /**
+   * Durable artifacts (unbound — the reminder is bound to a continuation
+   * token, not a resolved session; pass `sessionId` in `tag` input to
+   * attribute one).
+   */
+  artifacts: ArtifactsApi;
 }
 
 /**
@@ -1919,6 +2065,8 @@ export interface AgentProject {
   abConfig?: ABConfigFile;
   /** Optional `agent/storage.ts` (`defineStorage`). */
   storage?: StorageDefinition;
+  /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
+  artifacts?: ArtifactsDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -1988,6 +2136,8 @@ export interface AgentProjectInfo {
   };
   /** Project storage sink from `agent/storage.ts`, when authored. */
   storage?: { name?: string };
+  /** Declared artifact kinds from `agent/artifacts.ts`, when authored. */
+  artifacts?: { kinds: string[]; agentTool: boolean; max: number };
   diagnostics: Diagnostic[];
 }