@cursor/july 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -147,6 +147,13 @@
       "import": "./dist/ab.js",
       "default": "./dist/ab.js"
     },
+    "./artifacts": {
+      "anysphere-source": "./src/artifacts.ts",
+      "bun": "./src/artifacts.ts",
+      "types": "./dist/artifacts.d.ts",
+      "import": "./dist/artifacts.js",
+      "default": "./dist/artifacts.js"
+    },
     "./storage": {
       "anysphere-source": "./src/storage.ts",
       "bun": "./src/storage.ts",

package/src/artifacts.ts

@@ -0,0 +1,78 @@
+/**
+ * `defineArtifacts` — authored at `agent/artifacts.ts`.
+ *
+ * Artifacts mark durable outputs the agent produced (reviewed PR URLs,
+ * reports, …) so they can be listed across sessions and rendered in the
+ * playground. Declare artifact *kinds* here; host code tags via
+ * `ctx.artifacts.tag(...)` (tools, hooks, and channel handlers all carry
+ * an {@link ArtifactsApi}), and `agentTool: true` exposes the model-facing
+ * `tag_artifact` built-in tool generated from the same kinds registry.
+ *
+ * ```ts
+ * import { z } from "zod";
+ * import { defineArtifacts } from "@anysphere/agent-serve/artifacts";
+ *
+ * export default defineArtifacts({
+ *   kinds: {
+ *     "reviewed-pr": {
+ *       description: "A pull request this agent reviewed.",
+ *       schema: z.object({ url: z.string(), verdict: z.string() }),
+ *     },
+ *     report: { description: "A generated report." },
+ *   },
+ *   agentTool: true,
+ * });
+ * ```
+ */
+
+// TODO(artifacts-files): file/blob payloads land on the Agent Stores mount
+// (any files, fuse-mounted everywhere, survives deploys) once it ships —
+// same migration as TODO(agent-stores). Serve via GET
+// /v1/artifacts/:id/content; cloud-runtime tags keep the VM-native
+// /opt/cursor/artifacts + cursor.com artifact URLs.
+
+import { brandDefinition } from "./internal/brand.js";
+import type { ArtifactsConfig, ArtifactsDefinition } from "./types.js";
+
+export type {
+  ArtifactKindConfig,
+  ArtifactListFilter,
+  ArtifactRecord,
+  ArtifactSource,
+  ArtifactsApi,
+  ArtifactsConfig,
+  ArtifactsDefinition,
+  ArtifactTagInput,
+} from "./types.js";
+
+/** Default {@link ArtifactsConfig.max} retention cap. */
+export const ARTIFACTS_DEFAULT_MAX = 1_000;
+
+export function defineArtifacts(config: ArtifactsConfig): ArtifactsDefinition {
+  for (const [kind, kindConfig] of Object.entries(config.kinds ?? {})) {
+    if (kind.trim() === "") {
+      throw new Error("defineArtifacts: kind names must be non-empty");
+    }
+    if (
+      typeof kindConfig.description !== "string" ||
+      kindConfig.description.trim() === ""
+    ) {
+      throw new Error(
+        `defineArtifacts: kinds.${kind}.description must be a non-empty string`
+      );
+    }
+  }
+  if (config.max !== undefined) {
+    if (!Number.isInteger(config.max) || config.max < 1) {
+      throw new Error("defineArtifacts: max must be a positive integer");
+    }
+  }
+  return brandDefinition("artifacts", config);
+}
+
+/** Effective retention cap for a config (default {@link ARTIFACTS_DEFAULT_MAX}). */
+export function resolveArtifactsMax(
+  config: ArtifactsConfig | undefined
+): number {
+  return config?.max ?? ARTIFACTS_DEFAULT_MAX;
+}

package/src/channels/github/github.test.ts

@@ -787,6 +787,12 @@ function handlerArgs(send: SendMessageFn): ChannelHandlerArgs {
         delete: async () => {},
       },
     },
+    artifacts: {
+      tag: async () => {
+        throw new Error("artifacts not configured in test");
+      },
+      list: async () => [],
+    },
     send,
     getSession: async () => null,
     receive: async () => fakeSession(),

package/src/evals/assertions.test.ts

@@ -210,6 +210,43 @@ describe("run-level assertions", () => {
     );
   });
 
+  it("taggedArtifact matches artifact.tagged events by kind and predicate", () => {
+    const { recorder, t } = setup([
+      ...weatherRun(),
+      event("artifact.tagged", {
+        id: "art_1",
+        kind: "reviewed-pr",
+        key: "pr-1",
+        title: "PR #1",
+        data: { url: "https://github.com/org/repo/pull/1" },
+        source: "model",
+      }),
+    ]);
+    t.taggedArtifact();
+    t.taggedArtifact("reviewed-pr");
+    t.taggedArtifact("report");
+    t.taggedArtifact("reviewed-pr", (record) => record.source === "model");
+    t.taggedArtifact("reviewed-pr", (record) => record.key === "other");
+    const results = recorder.results();
+    expect(results.map((r) => r.passed)).toEqual([
+      true,
+      true,
+      false,
+      true,
+      false,
+    ]);
+    expect(results[1]?.name).toBe("taggedArtifact(reviewed-pr)");
+    expect(results[2]?.detail).toBe("tagged kinds: [reviewed-pr]");
+  });
+
+  it("taggedArtifact fails when nothing was tagged", () => {
+    const { recorder, t } = setup();
+    t.taggedArtifact();
+    const [result] = recorder.results();
+    expect(result?.passed).toBe(false);
+    expect(result?.detail).toBe("tagged kinds: []");
+  });
+
   it("notCalledTool matches any lifecycle state", () => {
     const { recorder, t } = setup();
     t.notCalledTool("echo");

package/src/evals/assertions.ts

@@ -15,7 +15,7 @@
  * by `t.send(...)`, which narrows the events under inspection to that turn.
  */
 
-import type { SessionEvent } from "../types.js";
+import type { SessionEvent, SessionEventPayload } from "../types.js";
 import type { Expectation } from "./expect.js";
 import { evaluateExpectation, expectationSeverity } from "./expect.js";
 import type {
@@ -37,6 +37,12 @@ import { deriveRunFacts } from "./run-facts.js";
 /** Hard gates fail the eval; soft assertions are tracked scores. */
 export type EvalAssertionSeverity = "gate" | "soft";
 
+/** One `artifact.tagged` payload, as seen by `t.taggedArtifact(...)`. */
+export type EvalTaggedArtifactFact = Extract<
+  SessionEventPayload,
+  { type: "artifact.tagged" }
+>["data"];
+
 /**
  * Overall grade for one eval case.
  *
@@ -314,6 +320,14 @@ export interface EvalAssertions {
     name: string,
     matcher?: EvalSubagentMatcher
   ): EvalAssertionHandle;
+  /**
+   * Gate: at least one artifact was tagged (`ctx.artifacts.tag` or the
+   * `tag_artifact` built-in), optionally of `kind` and matching `predicate`.
+   */
+  taggedArtifact(
+    kind?: string,
+    predicate?: (record: EvalTaggedArtifactFact) => boolean
+  ): EvalAssertionHandle;
   /** Gate: at least one matching event of `type` occurred. */
   event(type: string, matcher?: EvalEventMatcher): EvalAssertionHandle;
   /** Gate: no matching event of `type` occurred. */
@@ -567,6 +581,28 @@ export function createAssertions(
       });
     },
 
+    taggedArtifact(
+      kind?: string,
+      predicate?: (record: EvalTaggedArtifactFact) => boolean
+    ) {
+      const tagged = events().flatMap((event) =>
+        event.type === "artifact.tagged" ? [event.data] : []
+      );
+      const matched = tagged.filter(
+        (record) =>
+          (kind === undefined || record.kind === kind) &&
+          (predicate === undefined || predicate(record) === true)
+      );
+      return record({
+        name: `taggedArtifact(${kind ?? ""})`,
+        passed: matched.length > 0,
+        detail:
+          matched.length > 0
+            ? undefined
+            : `tagged kinds: [${tagged.map((r) => r.kind).join(", ")}]`,
+      });
+    },
+
     event(type: string, matcher?: EvalEventMatcher) {
       const matched = matchingEvents(type, matcher);
       const passed = matchCount(matched.length, matcher?.count);

package/src/evals.ts

@@ -84,6 +84,7 @@ export type {
   EvalAssertionResult,
   EvalAssertionSeverity,
   EvalAssertions,
+  EvalTaggedArtifactFact,
   EvalVerdict,
 } from "./evals/assertions.js";
 export { computeVerdict, verdictFailsRun } from "./evals/assertions.js";

package/src/index.ts

@@ -32,6 +32,7 @@ import type {
 } from "./types.js";
 
 export { defineAB } from "./ab.js";
+export { defineArtifacts } from "./artifacts.js";
 // Authoring helpers (also available on their focused subpath exports).
 export {
   allowAll,

package/src/internal/artifacts-store.test.ts

@@ -0,0 +1,283 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineArtifacts } from "../artifacts.js";
+import { defineStorage, storageKeys } from "../storage.js";
+import type { JsonValue } from "../types.js";
+import { ArtifactsStore, artifactIdForKey } from "./artifacts-store.js";
+import { StorageCoordinator } from "./storage-coordinator.js";
+
+const AGENT = "artifacts-test";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function tempStateRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "agent-serve-artifacts-"));
+  cleanups.push(() => rm(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+/** Distinct-millisecond updatedAt stamps for eviction/order assertions. */
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 3));
+}
+
+describe("ArtifactsStore", () => {
+  it("upserts by key: same key ⇒ same id, replaced row, preserved createdAt", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+    });
+
+    const first = await store.tag({
+      kind: "report",
+      key: "weekly",
+      data: { rev: 1 },
+    });
+    await tick();
+    const second = await store.tag({
+      kind: "report",
+      key: "weekly",
+      data: { rev: 2 },
+      title: "Weekly report",
+    });
+
+    expect(second.id).toBe(first.id);
+    expect(second.id).toBe(artifactIdForKey("weekly"));
+    expect(second.createdAt).toBe(first.createdAt);
+    expect(second.updatedAt > first.updatedAt).toBe(true);
+
+    const rows = await store.list();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.data).toEqual({ rev: 2 });
+    expect(rows[0]?.title).toBe("Weekly report");
+  });
+
+  it("gives keyless tags fresh random ids", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+    });
+    const a = await store.tag({ data: 1 });
+    const b = await store.tag({ data: 2 });
+    expect(a.id).not.toBe(b.id);
+    expect(await store.list()).toHaveLength(2);
+  });
+
+  it("validates data against the declared kind schema", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      config: defineArtifacts({
+        kinds: {
+          "reviewed-pr": {
+            description: "A reviewed PR.",
+            schema: z.object({ url: z.string() }),
+          },
+          note: { description: "Schemaless note." },
+        },
+      }),
+    });
+
+    const ok = await store.tag({
+      kind: "reviewed-pr",
+      data: { url: "https://github.com/org/repo/pull/1" },
+    });
+    expect(ok.kind).toBe("reviewed-pr");
+
+    await expect(
+      store.tag({ kind: "reviewed-pr", data: { nope: true } })
+    ).rejects.toThrow(/does not match the "reviewed-pr" schema/);
+
+    // A kind without a schema accepts any payload.
+    await expect(
+      store.tag({ kind: "note", data: "free text" })
+    ).resolves.toMatchObject({ kind: "note" });
+  });
+
+  it("persists the schema's parsed output (defaults applied)", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      config: defineArtifacts({
+        kinds: {
+          report: {
+            description: "Report.",
+            schema: z.object({
+              name: z.string(),
+              status: z.string().default("draft"),
+            }),
+          },
+        },
+      }),
+    });
+    const record = await store.tag({ kind: "report", data: { name: "q3" } });
+    expect(record.data).toEqual({ name: "q3", status: "draft" });
+    expect((await store.list())[0]?.data).toEqual({
+      name: "q3",
+      status: "draft",
+    });
+  });
+
+  it("rejects unknown kinds when kinds are declared", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      config: defineArtifacts({
+        kinds: { note: { description: "Note." } },
+      }),
+    });
+    await expect(store.tag({ kind: "mystery", data: 1 })).rejects.toThrow(
+      /unknown kind "mystery" \(declared: note\)/
+    );
+  });
+
+  it('accepts freeform kinds (default "artifact") with zero config', async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+    });
+    const defaulted = await store.tag({ data: { anything: true } });
+    expect(defaulted.kind).toBe("artifact");
+    expect(defaulted.source).toBe("host");
+    const custom = await store.tag({ kind: "whatever", data: null });
+    expect(custom.kind).toBe("whatever");
+  });
+
+  it("evicts the oldest-updated row past the max cap", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      config: defineArtifacts({ max: 2 }),
+    });
+
+    await store.tag({ key: "a", data: "a" });
+    await tick();
+    await store.tag({ key: "b", data: "b" });
+    await tick();
+    // Refreshing "a" makes "b" the oldest-updated row.
+    await store.tag({ key: "a", data: "a2" });
+    await tick();
+    await store.tag({ key: "c", data: "c" });
+
+    const keys = (await store.list()).map((row) => row.key);
+    expect(keys.sort()).toEqual(["a", "c"]);
+  });
+
+  it("keeps exactly max rows under concurrent inserts", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      config: defineArtifacts({ max: 3 }),
+    });
+    await Promise.all(
+      Array.from({ length: 8 }, (_, i) => store.tag({ data: i }))
+    );
+    expect(await store.list()).toHaveLength(3);
+  });
+
+  it("skips corrupt row files instead of failing list", async () => {
+    const stateRoot = await tempStateRoot();
+    const store = new ArtifactsStore({ stateRoot });
+    await store.tag({ key: "good", data: 1 });
+    await writeFile(
+      join(stateRoot, "artifacts", "corrupt.json"),
+      "{not json",
+      "utf8"
+    );
+
+    const rows = await store.list();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.key).toBe("good");
+    // Inserts (and their eviction scan) keep working too.
+    await expect(store.tag({ key: "more", data: 2 })).resolves.toBeDefined();
+  });
+
+  it("filters list by kind and sessionId, newest-updated first", async () => {
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+    });
+    await store.tag({ kind: "report", data: 1, sessionId: "ses_1" });
+    await tick();
+    await store.tag({ kind: "report", data: 2, sessionId: "ses_2" });
+    await tick();
+    await store.tag({ kind: "note", data: 3, sessionId: "ses_1" });
+
+    expect(await store.list({ kind: "report" })).toHaveLength(2);
+    expect(await store.list({ sessionId: "ses_1" })).toHaveLength(2);
+    expect(
+      await store.list({ kind: "report", sessionId: "ses_1" })
+    ).toHaveLength(1);
+
+    const all = await store.list();
+    expect(all.map((row) => row.data)).toEqual([3, 2, 1]);
+  });
+
+  it("persists rows through defineStorage under storageKeys.artifact", async () => {
+    const backing = new Map<string, JsonValue>();
+    const coordinator = new StorageCoordinator({
+      definition: defineStorage({
+        put: (key, value) => {
+          backing.set(key, structuredClone(value));
+        },
+        get: (key) => backing.get(key),
+        delete: (key) => {
+          backing.delete(key);
+        },
+        list: (prefix) =>
+          [...backing.entries()]
+            .filter(([key]) => key.startsWith(prefix))
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([key, value]) => ({ key, value })),
+      }),
+      agentName: AGENT,
+      projectRoot: "/tmp",
+      logger: () => {},
+    });
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      storage: coordinator,
+    });
+
+    const record = await store.tag({ key: "pr-1", data: { url: "u" } });
+    expect(backing.get(storageKeys.artifact(AGENT, record.id))).toMatchObject({
+      id: record.id,
+      key: "pr-1",
+    });
+
+    await tick();
+    await store.tag({ key: "pr-1", data: { url: "u2" } });
+    expect([...backing.keys()]).toHaveLength(1);
+    expect((await store.list())[0]?.data).toEqual({ url: "u2" });
+  });
+
+  it("falls back to filesystem rows when the sink cannot delete", async () => {
+    const backing = new Map<string, JsonValue>();
+    // No `delete`: the sink could never evict past the cap, so artifact
+    // rows must not land there.
+    const coordinator = new StorageCoordinator({
+      definition: defineStorage({
+        put: (key, value) => {
+          backing.set(key, structuredClone(value));
+        },
+        get: (key) => backing.get(key),
+        list: (prefix) =>
+          [...backing.entries()]
+            .filter(([key]) => key.startsWith(prefix))
+            .map(([key, value]) => ({ key, value })),
+      }),
+      agentName: AGENT,
+      projectRoot: "/tmp",
+      logger: () => {},
+    });
+    expect(coordinator.supportsArtifacts).toBe(false);
+
+    const store = new ArtifactsStore({
+      stateRoot: await tempStateRoot(),
+      storage: coordinator,
+    });
+    await store.tag({ key: "local", data: 1 });
+    expect(backing.size).toBe(0);
+    expect(await store.list()).toHaveLength(1);
+  });
+});