@cursor/july 0.1.24 → 0.1.26

package/src/internal/artifacts-store.ts

@@ -0,0 +1,290 @@
+/**
+ * Durable artifact rows behind `ctx.artifacts` ({@link ArtifactsApi}).
+ *
+ * Mirror of host-kv: when `defineStorage` is authored with `get` + `list`,
+ * rows live in that sink under `storageKeys.artifact`; otherwise one
+ * JSON file per row under `--state-root/artifacts`.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { resolveArtifactsMax } from "../artifacts.js";
+import type {
+  ArtifactListFilter,
+  ArtifactRecord,
+  ArtifactsConfig,
+  ArtifactTagInput,
+  JsonValue,
+} from "../types.js";
+import type { StorageCoordinator } from "./storage-coordinator.js";
+
+// TODO(agent-stores): the KV backing store is migrating to Agent Stores.
+// Swap only this adapter to the Agent Stores API when that lands; the
+// engine, tool, HTTP, and playground layers must not change.
+interface ArtifactRowStore {
+  get(id: string): Promise<ArtifactRecord | undefined>;
+  put(record: ArtifactRecord): Promise<void>;
+  delete(id: string): Promise<void>;
+  list(): Promise<ArtifactRecord[]>;
+}
+
+export interface CreateArtifactsStoreOptions {
+  stateRoot: string;
+  storage?: StorageCoordinator;
+  /** `agent/artifacts.ts` config, when authored. */
+  config?: ArtifactsConfig;
+}
+
+/** Kind used by freeform tags when no kinds are declared. */
+export const ARTIFACT_DEFAULT_KIND = "artifact";
+
+/**
+ * Upsert + list semantics over one {@link ArtifactRowStore}: kind/schema
+ * validation, deterministic ids for keyed tags, and `max` eviction. The
+ * engine wraps this into the per-context {@link ArtifactsApi} facades and
+ * owns the `artifact.tagged` event append.
+ */
+export class ArtifactsStore {
+  private readonly rows: ArtifactRowStore;
+  private readonly config: ArtifactsConfig | undefined;
+  private readonly max: number;
+  /** Serializes tags so read-modify-write upserts and eviction don't race. */
+  private tagChain: Promise<unknown> = Promise.resolve();
+
+  constructor(options: CreateArtifactsStoreOptions) {
+    this.rows =
+      options.storage?.supportsArtifacts === true
+        ? createCoordinatorRowStore(options.storage)
+        : createFilesystemRowStore(options.stateRoot);
+    this.config = options.config;
+    this.max = resolveArtifactsMax(options.config);
+  }
+
+  tag(input: ArtifactTagInput): Promise<ArtifactRecord> {
+    const result = this.tagChain.then(() => this.tagSerialized(input));
+    this.tagChain = result.catch(() => {});
+    return result;
+  }
+
+  private async tagSerialized(
+    input: ArtifactTagInput
+  ): Promise<ArtifactRecord> {
+    const { kind, data } = this.resolveKindAndData(input);
+    const id =
+      input.key === undefined
+        ? `art_${randomUUID()}`
+        : artifactIdForKey(input.key);
+    const existing = await this.rows.get(id);
+    const now = new Date().toISOString();
+    const record: ArtifactRecord = {
+      id,
+      kind,
+      key: input.key,
+      title: input.title,
+      data,
+      sessionId: input.sessionId,
+      turnId: input.turnId,
+      source: input.source ?? "host",
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    };
+    await this.rows.put(record);
+    if (existing === undefined) {
+      await this.evictPastCap();
+    }
+    return record;
+  }
+
+  async list(filter?: ArtifactListFilter): Promise<ArtifactRecord[]> {
+    const records = await this.rows.list();
+    return records
+      .filter(
+        (record) =>
+          (filter?.kind === undefined || record.kind === filter.kind) &&
+          (filter?.sessionId === undefined ||
+            record.sessionId === filter.sessionId)
+      )
+      .sort(byNewestUpdated);
+  }
+
+  /**
+   * Resolve the effective kind (freeform when no kinds are declared) and
+   * the payload to persist. Like tool input schemas
+   * (`validateToolInput`), zod schemas validate *and* transform: the
+   * parsed output — defaults and coercions applied — is what gets stored.
+   */
+  private resolveKindAndData(input: ArtifactTagInput): {
+    kind: string;
+    data: JsonValue;
+  } {
+    const kind = input.kind ?? ARTIFACT_DEFAULT_KIND;
+    if (kind.trim() === "") {
+      throw new Error("artifacts.tag: kind must be a non-empty string");
+    }
+    const kinds = this.config?.kinds;
+    if (kinds === undefined || Object.keys(kinds).length === 0) {
+      return { kind, data: input.data };
+    }
+    const kindConfig = kinds[kind];
+    if (kindConfig === undefined) {
+      throw new Error(
+        `artifacts.tag: unknown kind ${JSON.stringify(kind)} (declared: ${Object.keys(kinds).join(", ")})`
+      );
+    }
+    if (kindConfig.schema !== undefined) {
+      const parsed = kindConfig.schema.safeParse(input.data);
+      if (!parsed.success) {
+        throw new Error(
+          `artifacts.tag: data does not match the ${JSON.stringify(kind)} schema: ${parsed.error.message}`
+        );
+      }
+      return { kind, data: parsed.data as JsonValue };
+    }
+    return { kind, data: input.data };
+  }
+
+  private async evictPastCap(): Promise<void> {
+    const records = await this.rows.list();
+    if (records.length <= this.max) {
+      return;
+    }
+    const oldestFirst = records.sort((a, b) => byNewestUpdated(b, a));
+    for (const record of oldestFirst.slice(0, records.length - this.max)) {
+      await this.rows.delete(record.id);
+    }
+  }
+}
+
+/** Deterministic id for a keyed tag (same key ⇒ same id ⇒ upsert). */
+export function artifactIdForKey(key: string): string {
+  if (key.trim() === "") {
+    throw new Error("artifacts.tag: key must be a non-empty string");
+  }
+  return `art_${createHash("sha256").update(key, "utf8").digest("hex").slice(0, 32)}`;
+}
+
+function byNewestUpdated(a: ArtifactRecord, b: ArtifactRecord): number {
+  if (a.updatedAt !== b.updatedAt) {
+    return a.updatedAt < b.updatedAt ? 1 : -1;
+  }
+  // Tie-break so eviction and listing stay deterministic.
+  if (a.createdAt !== b.createdAt) {
+    return a.createdAt < b.createdAt ? 1 : -1;
+  }
+  return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+}
+
+function isArtifactRecord(
+  value: JsonValue | undefined
+): value is ArtifactRecord & JsonValue {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    typeof value.id !== "string" ||
+    typeof value.kind !== "string" ||
+    (value.source !== "host" && value.source !== "model") ||
+    typeof value.createdAt !== "string" ||
+    typeof value.updatedAt !== "string" ||
+    !("data" in value)
+  ) {
+    return false;
+  }
+  for (const field of ["key", "title", "sessionId", "turnId"] as const) {
+    if (value[field] !== undefined && typeof value[field] !== "string") {
+      return false;
+    }
+  }
+  return true;
+}
+
+function createCoordinatorRowStore(
+  storage: StorageCoordinator
+): ArtifactRowStore {
+  return {
+    async get(id): Promise<ArtifactRecord | undefined> {
+      const value = await storage.artifactGet(id);
+      return isArtifactRecord(value) ? value : undefined;
+    },
+    async put(record): Promise<void> {
+      await storage.artifactPut(record.id, record as unknown as JsonValue);
+    },
+    async delete(id): Promise<void> {
+      await storage.artifactDelete(id);
+    },
+    async list(): Promise<ArtifactRecord[]> {
+      const values = await storage.artifactList();
+      return values.filter(isArtifactRecord);
+    },
+  };
+}
+
+function createFilesystemRowStore(stateRoot: string): ArtifactRowStore {
+  const dir = join(stateRoot, "artifacts");
+  const filePath = (id: string): string =>
+    join(dir, `${encodeURIComponent(id)}.json`);
+
+  // Missing and corrupt rows both read as absent — a truncated/garbled
+  // file must not poison list() (and with it every insert's eviction).
+  const readRecord = async (
+    path: string
+  ): Promise<ArtifactRecord | undefined> => {
+    try {
+      const value = JSON.parse(await readFile(path, "utf8")) as JsonValue;
+      return isArtifactRecord(value) ? value : undefined;
+    } catch (error) {
+      if (
+        (error as NodeJS.ErrnoException).code === "ENOENT" ||
+        error instanceof SyntaxError
+      ) {
+        return undefined;
+      }
+      throw error;
+    }
+  };
+
+  return {
+    get(id): Promise<ArtifactRecord | undefined> {
+      return readRecord(filePath(id));
+    },
+    async put(record): Promise<void> {
+      await mkdir(dir, { recursive: true });
+      const tmp = join(dir, `.tmp-${randomUUID()}`);
+      await writeFile(tmp, JSON.stringify(record), "utf8");
+      await rename(tmp, filePath(record.id));
+    },
+    async delete(id): Promise<void> {
+      await rm(filePath(id), { force: true });
+    },
+    async list(): Promise<ArtifactRecord[]> {
+      let names: string[];
+      try {
+        names = await readdir(dir);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return [];
+        }
+        throw error;
+      }
+      const records: ArtifactRecord[] = [];
+      for (const name of names.sort()) {
+        if (name.startsWith(".") || !name.endsWith(".json")) {
+          continue;
+        }
+        const record = await readRecord(join(dir, name));
+        if (record !== undefined) {
+          records.push(record);
+        }
+      }
+      return records;
+    },
+  };
+}

package/src/internal/authored-loaders.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { AUTHORING_ENTRY_FILES } from "./distribution.js";
+
+describe("AUTHORING_ENTRY_FILES", () => {
+  it("mirrors the package exports map (the runtime alias hooks derive their targets from it)", () => {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+    ) as {
+      exports: Record<string, string | { import?: string }>;
+    };
+    const fromExports = Object.entries(pkg.exports)
+      .filter(
+        ([exportPath, conditions]) =>
+          typeof conditions !== "string" && exportPath !== "./package.json"
+      )
+      .map(([exportPath, conditions]) => {
+        const subpath =
+          exportPath === "." ? "" : exportPath.replace(/^\.\//, "");
+        const importTarget = (conditions as { import?: string }).import;
+        expect(
+          importTarget,
+          `exports["${exportPath}"] must have an import condition`
+        ).toBeDefined();
+        return [subpath, importTarget?.replace(/^\.\/dist\//, "")];
+      });
+    expect(AUTHORING_ENTRY_FILES.map((entry) => [...entry])).toEqual(
+      fromExports
+    );
+  });
+});

package/src/internal/builtin-tools/artifacts.test.ts

@@ -0,0 +1,247 @@
+import { mkdtemp, rm } 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 { httpChannel } from "../../channels.js";
+import type { AgentProject, JsonSchemaObject } from "../../types.js";
+import { toolInputJsonSchema } from "../json-schema.js";
+import { SessionEngine, ToolInputError } from "../session-engine.js";
+import { tagArtifactTool } from "./artifacts.js";
+import { artifactBuiltinTool, TAG_ARTIFACT_TOOL_NAME } from "./index.js";
+
+const KINDS = 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,
+});
+
+describe("tagArtifactTool schema", () => {
+  it("builds a discriminated union over the declared kinds", () => {
+    const definition = tagArtifactTool(KINDS);
+    const jsonSchema = toolInputJsonSchema(definition.inputSchema);
+    const variants = (jsonSchema.anyOf ?? jsonSchema.oneOf) as Array<{
+      properties: Record<string, JsonSchemaObject>;
+      required?: string[];
+    }>;
+    expect(variants).toHaveLength(2);
+    expect(variants.map((v) => v.properties.kind?.const)).toEqual([
+      "reviewed-pr",
+      "report",
+    ]);
+    // The kind's zod schema shapes `data`; kinds without one pass through.
+    expect(variants[0]?.properties.data?.properties).toMatchObject({
+      url: { type: "string" },
+      verdict: { type: "string" },
+    });
+    expect(variants[1]?.properties.data?.additionalProperties).toBe(true);
+    for (const variant of variants) {
+      expect(variant.required).toEqual(
+        expect.arrayContaining(["kind", "data"])
+      );
+      expect(variant.required).not.toContain("title");
+      expect(variant.required).not.toContain("key");
+    }
+  });
+
+  it("keeps the author's data schema description", () => {
+    const definition = tagArtifactTool({
+      kinds: {
+        note: {
+          description: "A note.",
+          schema: z.object({ text: z.string() }).describe("Author-described."),
+        },
+      },
+      agentTool: true,
+    });
+    const jsonSchema = toolInputJsonSchema(definition.inputSchema);
+    const variants = (jsonSchema.anyOf ?? jsonSchema.oneOf) as Array<{
+      properties: Record<string, JsonSchemaObject>;
+    }>;
+    expect(variants[0]?.properties.data?.description).toBe("Author-described.");
+  });
+
+  it("rejects payloads that miss the kind schema", () => {
+    const definition = tagArtifactTool(KINDS);
+    const schema = definition.inputSchema as z.ZodTypeAny;
+    expect(
+      schema.safeParse({ kind: "reviewed-pr", data: { url: 1 } }).success
+    ).toBe(false);
+    expect(
+      schema.safeParse({
+        kind: "reviewed-pr",
+        data: { url: "https://x", verdict: "approved" },
+      }).success
+    ).toBe(true);
+    expect(schema.safeParse({ kind: "unknown", data: {} }).success).toBe(false);
+  });
+
+  it("rejects blank keys at the schema boundary and trims valid ones", () => {
+    const definition = tagArtifactTool(KINDS);
+    const schema = definition.inputSchema as z.ZodTypeAny;
+    expect(
+      schema.safeParse({ kind: "report", data: {}, key: "" }).success
+    ).toBe(false);
+    expect(
+      schema.safeParse({ kind: "report", data: {}, key: "   " }).success
+    ).toBe(false);
+    const parsed = schema.safeParse({
+      kind: "report",
+      data: {},
+      key: " pr-1 ",
+    });
+    expect(parsed.success).toBe(true);
+    expect((parsed as { data: { key: string } }).data.key).toBe("pr-1");
+  });
+
+  it("prompts with the kind descriptions and key upsert semantics", () => {
+    const definition = tagArtifactTool(KINDS);
+    expect(definition.description).toContain(
+      "- reviewed-pr: A pull request this agent reviewed."
+    );
+    expect(definition.description).toContain("- report: A generated report.");
+    expect(definition.description).toContain("upsert");
+    expect(definition.description).toContain("stable key");
+  });
+
+  it("requires at least one declared kind", () => {
+    expect(() => tagArtifactTool({ kinds: {} })).toThrow(/at least one/);
+  });
+});
+
+describe("tagArtifactTool execute", () => {
+  const cleanups: Array<() => Promise<void>> = [];
+
+  afterEach(async () => {
+    while (cleanups.length > 0) {
+      await cleanups.pop()?.();
+    }
+  });
+
+  async function makeEngine(
+    logger?: (line: string) => void
+  ): Promise<SessionEngine> {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-tagtool-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+    const tool = artifactBuiltinTool(KINDS);
+    if (tool === undefined) {
+      throw new Error("expected tag_artifact to be enabled");
+    }
+    const project: AgentProject = {
+      rootDir: stateRoot,
+      agentDir: join(stateRoot, "agent"),
+      name: "tag-artifact-test",
+      agent: {
+        name: "tag-artifact-test",
+        runtime: "local",
+        instructions: "Test agent.",
+        tools: [tool],
+        skills: [],
+        connections: [],
+        subagents: [],
+        seedFiles: [],
+      },
+      httpChannel: httpChannel(),
+      channels: [],
+      schedules: [],
+      hooks: [],
+      abs: [],
+      artifacts: KINDS,
+      diagnostics: [],
+    };
+    const engine = new SessionEngine({
+      project,
+      stateRoot,
+      logger,
+      runner: {
+        runTurn: () => {
+          throw new Error("no model turns in this test");
+        },
+      },
+    });
+    cleanups.push(() => engine.close());
+    return engine;
+  }
+
+  it("tags through ctx.artifacts with source model and confirms", async () => {
+    const engine = await makeEngine();
+    const outcome = await engine.callTool(TAG_ARTIFACT_TOOL_NAME, {
+      kind: "reviewed-pr",
+      data: { url: "https://github.com/org/repo/pull/1", verdict: "lgtm" },
+      title: "PR #1",
+      key: "pr-1",
+    });
+    expect(outcome.isError).toBe(false);
+    const rows = await engine.artifacts.list();
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      kind: "reviewed-pr",
+      key: "pr-1",
+      title: "PR #1",
+      data: { url: "https://github.com/org/repo/pull/1", verdict: "lgtm" },
+      source: "model",
+    });
+    expect(outcome.result).toEqual({
+      tagged: true,
+      id: rows[0]?.id,
+      kind: "reviewed-pr",
+      key: "pr-1",
+    });
+  });
+
+  it("logs the tag without the data payload", async () => {
+    const lines: string[] = [];
+    const engine = await makeEngine((line) => lines.push(line));
+    await engine.callTool(TAG_ARTIFACT_TOOL_NAME, {
+      kind: "report",
+      data: { secret: "do-not-log" },
+      key: "r-1",
+    });
+    const [record] = await engine.artifacts.list();
+    const logged = lines.find((line) =>
+      line.includes("[session] artifact tagged")
+    );
+    expect(logged).toBe(
+      `[session] artifact tagged kind=report id=${record?.id} source=model session=- key=r-1`
+    );
+    expect(lines.join("\n")).not.toContain("do-not-log");
+  });
+
+  it("rejects undeclared kinds and schema-invalid payloads at the boundary", async () => {
+    const engine = await makeEngine();
+    await expect(
+      engine.callTool(TAG_ARTIFACT_TOOL_NAME, { kind: "unknown", data: {} })
+    ).rejects.toThrow(ToolInputError);
+    await expect(
+      engine.callTool(TAG_ARTIFACT_TOOL_NAME, {
+        kind: "reviewed-pr",
+        data: { url: 1 },
+      })
+    ).rejects.toThrow(ToolInputError);
+  });
+});
+
+describe("artifactBuiltinTool", () => {
+  it("is enabled only by agentTool: true with kinds", () => {
+    expect(artifactBuiltinTool(undefined)).toBeUndefined();
+    expect(
+      artifactBuiltinTool({
+        kinds: { report: { description: "A report." } },
+      })
+    ).toBeUndefined();
+    expect(artifactBuiltinTool({ agentTool: true, kinds: {} })).toBeUndefined();
+
+    const tool = artifactBuiltinTool(KINDS);
+    expect(tool).toMatchObject({
+      name: TAG_ARTIFACT_TOOL_NAME,
+      execution: "server",
+      needsApproval: false,
+    });
+  });
+});

package/src/internal/builtin-tools/artifacts.ts

@@ -0,0 +1,74 @@
+/**
+ * The `tag_artifact` built-in tool, enabled by
+ * `defineArtifacts({ agentTool: true })` rather than
+ * `AgentConfig.builtinTools`: its input schema and description are
+ * generated from the declared kinds registry.
+ */
+
+import { z } from "zod";
+import { defineTool } from "../../tools.js";
+import type { ArtifactsConfig, ToolDefinition } from "../../types.js";
+
+export const TAG_ARTIFACT_TOOL_NAME = "tag_artifact";
+
+function kindVariant(name: string, schema: z.ZodType | undefined) {
+  return z.object({
+    kind: z.literal(name),
+    data:
+      schema ??
+      z
+        .object({})
+        .passthrough()
+        .describe("Freeform JSON object payload for this kind."),
+    title: z
+      .string()
+      .optional()
+      .describe("Short human-readable label shown in artifact lists."),
+    key: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe(
+        "Stable upsert key: tagging the same key again updates the existing record instead of creating a new one."
+      ),
+  });
+}
+
+export function tagArtifactTool(config: ArtifactsConfig): ToolDefinition {
+  const kinds = Object.entries(config.kinds ?? {});
+  const [first, ...rest] = kinds.map(([name, kind]) =>
+    kindVariant(name, kind.schema)
+  );
+  if (first === undefined) {
+    // Discovery already errors on agentTool without kinds.
+    throw new Error(
+      "tag_artifact requires at least one declared artifact kind"
+    );
+  }
+  const description = [
+    "Tag a durable artifact: a record of a notable output you produced, kept across sessions and listed for the people supervising this agent. Tag one whenever you finish something worth surfacing durably.",
+    "Kinds:",
+    ...kinds.map(([name, kind]) => `- ${name}: ${kind.description}`),
+    "Same `key` upserts: tagging it again updates that record — use a stable key when re-tagging the same underlying thing (e.g. the same PR URL).",
+  ].join("\n");
+  return defineTool({
+    description,
+    inputSchema: z.discriminatedUnion("kind", [first, ...rest]),
+    async execute(input, ctx) {
+      const record = await ctx.artifacts.tag({
+        kind: input.kind,
+        data: input.data,
+        title: input.title,
+        key: input.key,
+        source: "model",
+      });
+      return {
+        tagged: true,
+        id: record.id,
+        kind: record.kind,
+        key: record.key,
+      };
+    },
+  });
+}

package/src/internal/builtin-tools/index.ts

@@ -6,13 +6,17 @@
  */
 
 import type {
+  ArtifactsConfig,
   BuiltinToolsConfig,
   DiscoveredTool,
   ToolDefinition,
 } from "../../types.js";
 import { toolInputJsonSchema } from "../json-schema.js";
+import { TAG_ARTIFACT_TOOL_NAME, tagArtifactTool } from "./artifacts.js";
 import { reminderTools } from "./reminders.js";
 
+export { TAG_ARTIFACT_TOOL_NAME } from "./artifacts.js";
+
 /** Resolve the enabled built-in tools, in stable catalog order. */
 export function builtinTools(
   config: BuiltinToolsConfig | undefined
@@ -24,6 +28,23 @@ export function builtinTools(
   return tools;
 }
 
+/**
+ * The `tag_artifact` built-in, enabled by `defineArtifacts({ agentTool:
+ * true })` (not `AgentConfig.builtinTools` — the tool is generated from
+ * the kinds registry). Undefined without kinds: discovery already errors.
+ */
+export function artifactBuiltinTool(
+  config: ArtifactsConfig | undefined
+): DiscoveredTool | undefined {
+  if (
+    config?.agentTool !== true ||
+    Object.keys(config.kinds ?? {}).length === 0
+  ) {
+    return undefined;
+  }
+  return toDiscovered({ [TAG_ARTIFACT_TOOL_NAME]: tagArtifactTool(config) })[0];
+}
+
 function toDiscovered(
   byName: Record<string, ToolDefinition>
 ): DiscoveredTool[] {