@cursor/july 0.1.23 → 0.1.25

package/src/internal/session-engine.ts

@@ -24,6 +24,10 @@ import {
 import {
   type AgentProject,
   type ApprovalDecision,
+  type ArtifactListFilter,
+  type ArtifactRecord,
+  type ArtifactsApi,
+  type ArtifactTagInput,
   type AuthContext,
   type CallToolOptions,
   type ChannelDefinition,
@@ -60,6 +64,7 @@ import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
 import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
 import { ApprovalGate } from "./approval-gate.js";
+import { ArtifactsStore } from "./artifacts-store.js";
 import { samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { isDevMode } from "./dev-mode.js";
@@ -278,6 +283,8 @@ export class SessionEngine {
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
+  /** Engine-owned artifacts service behind every `ctx.artifacts` facade. */
+  private readonly artifactsStore: ArtifactsStore;
   /** Serve-time resolved connections (see {@link setResolvedConnections}). */
   private resolvedConnections: EngineResolvedConnection[] = [];
 
@@ -315,6 +322,11 @@ export class SessionEngine {
       stateRoot: options.stateRoot,
       ...(this.storage === undefined ? {} : { storage: this.storage }),
     });
+    this.artifactsStore = new ArtifactsStore({
+      stateRoot: options.stateRoot,
+      storage: this.storage,
+      config: options.project.artifacts,
+    });
     this.abCollector = new ABCollector(
       options.project.abs,
       this.logger,
@@ -370,6 +382,78 @@ export class SessionEngine {
     };
   }
 
+  /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
+  get artifacts(): ArtifactsApi {
+    return this.artifactsApi();
+  }
+
+  /**
+   * Build one `ctx.artifacts` facade over the engine-owned artifacts
+   * service. With a `binding` (tools, hooks) `tag` auto-fills the bound
+   * session (and turn when known) and rejects a conflicting explicit
+   * `sessionId`; without one (channel handlers) callers may pass
+   * `sessionId` / `turnId` explicitly.
+   */
+  artifactsApi(binding?: { sessionId: string; turnId?: string }): ArtifactsApi {
+    return {
+      tag: async (input) => {
+        if (binding === undefined) {
+          return this.tagArtifact(input);
+        }
+        if (
+          input.sessionId !== undefined &&
+          input.sessionId !== binding.sessionId
+        ) {
+          throw new Error(
+            `artifacts.tag: this context is bound to session ${binding.sessionId}; cannot tag for ${input.sessionId}`
+          );
+        }
+        return this.tagArtifact({
+          ...input,
+          sessionId: binding.sessionId,
+          turnId: input.turnId ?? binding.turnId,
+        });
+      },
+      list: (filter) => this.artifactsStore.list(filter),
+    };
+  }
+
+  /**
+   * Single tag funnel: upsert the row, then — for session-bound tags —
+   * append `artifact.tagged` through {@link appendEvent} so persistence
+   * flush and hook fan-out are inherited. Session-less tags skip the event.
+   * An unknown `sessionId` rejects before the row is written (appending to
+   * a session that was never materialized here would mint an orphan local
+   * event log, breaking the local-over-sink restore invariant).
+   */
+  private async tagArtifact(input: ArtifactTagInput): Promise<ArtifactRecord> {
+    if (
+      input.sessionId !== undefined &&
+      (await this.getOrRestoreSession(input.sessionId)) === undefined
+    ) {
+      throw new UnknownSessionError(input.sessionId);
+    }
+    const record = await this.artifactsStore.tag(input);
+    if (record.sessionId !== undefined) {
+      await this.appendEvent(record.sessionId, {
+        type: "artifact.tagged",
+        turnId: record.turnId,
+        data: {
+          id: record.id,
+          kind: record.kind,
+          key: record.key,
+          title: record.title,
+          data: record.data,
+          source: record.source,
+        },
+      });
+    }
+    this.logger(
+      `[session] artifact tagged kind=${record.kind} id=${record.id} source=${record.source} session=${record.sessionId ?? "-"} key=${record.key ?? "-"}`
+    );
+    return record;
+  }
+
   private slackNudgeHostApi(): SlackNudgeHostApi {
     return {
       append: (input) => this.nudgeStore.append(input),
@@ -1408,6 +1492,10 @@ export class SessionEngine {
             workspaceDir: this.harnessCwd(record),
             stateRoot: this.stateRoot,
             host: this.host,
+            artifacts: this.artifactsApi({
+              sessionId: record.sessionId,
+              turnId,
+            }),
             send: (channelId, message, sendOptions = {}) =>
               this.send(channelId, message, {
                 ...sendOptions,
@@ -1730,6 +1818,14 @@ export class SessionEngine {
           workspaceDir,
           stateRoot: this.stateRoot,
           host: this.host,
+          // Scratch calls have no real session; their facade stays unbound.
+          artifacts:
+            record === undefined
+              ? this.artifactsApi()
+              : this.artifactsApi({
+                  sessionId: record.sessionId,
+                  turnId: callId,
+                }),
           send: (channelId, message, sendOptions = {}) =>
             this.send(channelId, message, {
               ...sendOptions,
@@ -1882,6 +1978,10 @@ export class SessionEngine {
             },
             session: this.sessionInfo(record),
             stateRoot: this.stateRoot,
+            artifacts: this.artifactsApi({
+              sessionId: record.sessionId,
+              turnId: event.turnId,
+            }),
           });
         } catch (error) {
           this.logger(
@@ -1951,6 +2051,31 @@ export class SessionEngine {
     return (await this.listSessionsWithSource(caller, options)).sessions;
   }
 
+  /**
+   * Artifacts for `GET /v1/artifacts`, newest-updated first. Without
+   * `includeAll`, the sessions-list ownership rule applies: only artifacts
+   * tagged on a session whose principal matches the caller. Session-less
+   * artifacts are agent-scoped and visible only with `includeAll`.
+   */
+  async listArtifacts(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean; filter?: ArtifactListFilter }
+  ): Promise<ArtifactRecord[]> {
+    const records = await this.artifactsStore.list(options?.filter);
+    if (options?.includeAll === true) {
+      return records;
+    }
+    const sessions = await this.sessions.list();
+    const owned = new Set(
+      sessions
+        .filter((record) => samePrincipal(record.auth, caller))
+        .map((record) => record.sessionId)
+    );
+    return records.filter(
+      (record) => record.sessionId !== undefined && owned.has(record.sessionId)
+    );
+  }
+
   /**
    * Same as {@link listSessions}, plus which store answered
    * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =

package/src/internal/storage-coordinator.ts

@@ -495,6 +495,68 @@ export class StorageCoordinator {
     await this.definition.delete?.(key, this.context("policy"));
   }
 
+  // ==========================================================================
+  // Artifacts (`ctx.artifacts`)
+  // ==========================================================================
+
+  /**
+   * Whether the sink can serve awaited artifact rows: `get` (upsert
+   * read-back), `list` (listing + eviction), and `delete` (`max` cap
+   * eviction) are all required — without `delete` the retention cap
+   * could never evict, so rows fall back to the filesystem store.
+   */
+  get supportsArtifacts(): boolean {
+    return (
+      this.definition.get !== undefined &&
+      this.definition.list !== undefined &&
+      this.definition.delete !== undefined
+    );
+  }
+
+  /** Awaited artifact-row read. Errors propagate (read-after-write). */
+  async artifactGet(id: string): Promise<JsonValue | undefined> {
+    const get = this.definition.get;
+    if (get === undefined) {
+      throw new Error("storage get is not configured");
+    }
+    const value = await get(
+      storageKeys.artifact(this.agentName, id),
+      this.context("restore")
+    );
+    return value ?? undefined;
+  }
+
+  /** Awaited artifact-row write (straight to the sink, like author KV). */
+  async artifactPut(id: string, value: JsonValue): Promise<void> {
+    await this.definition.put(
+      storageKeys.artifact(this.agentName, id),
+      value,
+      this.context("policy")
+    );
+  }
+
+  /** Awaited artifact-row delete. Errors propagate (cap eviction). */
+  async artifactDelete(id: string): Promise<void> {
+    const del = this.definition.delete;
+    if (del === undefined) {
+      throw new Error("storage delete is not configured");
+    }
+    await del(storageKeys.artifact(this.agentName, id), this.context("policy"));
+  }
+
+  /** All artifact-row values for this agent. Errors propagate. */
+  async artifactList(): Promise<JsonValue[]> {
+    const list = this.definition.list;
+    if (list === undefined) {
+      throw new Error("storage list is not configured");
+    }
+    const entries = await list(
+      storageKeys.artifactPrefix(this.agentName),
+      this.context("restore")
+    );
+    return Array.isArray(entries) ? entries.map((entry) => entry.value) : [];
+  }
+
   // ==========================================================================
   // Evals (dedicated `evals` table)
   // ==========================================================================

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 = (
@@ -1575,6 +1598,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 +1623,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/*)
 // ============================================================================
@@ -1919,6 +2048,8 @@ export interface AgentProject {
   abConfig?: ABConfigFile;
   /** Optional `agent/storage.ts` (`defineStorage`). */
   storage?: StorageDefinition;
+  /** Optional `agent/artifacts.ts` (`defineArtifacts`). */
+  artifacts?: ArtifactsDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -1988,6 +2119,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[];
 }