@cursor/july 0.1.24 → 0.1.26

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),
@@ -632,7 +716,10 @@ export class SessionEngine {
         lastCreated = session;
         return session;
       };
-      const returned = await definition.receive(input, { send });
+      const returned = await definition.receive(input, {
+        send,
+        artifacts: this.artifactsApi(),
+      });
       const session = returned ?? lastCreated;
       if (session === undefined) {
         throw new Error(
@@ -1408,6 +1495,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 +1821,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 +1981,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 +2054,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/session-urls.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import {
+  eventsUrlForSession,
+  playgroundUrlForSession,
+  sessionUrlsForRequest,
+} from "./session-urls.js";
+
+describe("sessionUrls", () => {
+  it("builds playground and trace URLs for a single-agent mount", () => {
+    const request = new Request("http://127.0.0.1:3000/v1/channels/review");
+    expect(sessionUrlsForRequest(request, "", "ses_abc")).toEqual({
+      playgroundUrl: "http://127.0.0.1:3000/playground?sessionId=ses_abc",
+      traceUrl: "http://127.0.0.1:3000/v1/session/ses_abc/events",
+    });
+  });
+
+  it("prefixes the multi-agent slug mount", () => {
+    const request = new Request(
+      "http://127.0.0.1:3000/bugbot/v1/channels/review"
+    );
+    expect(playgroundUrlForSession(request, "/bugbot", "ses_1")).toBe(
+      "http://127.0.0.1:3000/bugbot/playground?sessionId=ses_1"
+    );
+    expect(eventsUrlForSession(request.url, "bugbot", "ses with spaces")).toBe(
+      "http://127.0.0.1:3000/bugbot/v1/session/ses%20with%20spaces/events"
+    );
+  });
+});