@cursor/july 0.1.24 → 0.1.26

package/src/internal/server.artifacts.test.ts

@@ -0,0 +1,334 @@
+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 { defineChannel, httpChannel } from "../channels.js";
+import { defineTool } from "../tools.js";
+import type {
+  AgentProject,
+  ArtifactRecord,
+  AuthContext,
+  DiscoveredChannel,
+  DiscoveredTool,
+  ServeOptions,
+} from "../types.js";
+import { toolInputJsonSchema } from "./json-schema.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { type AgentMount, startServer } from "./server.js";
+import { SessionEngine } from "./session-engine.js";
+
+const seedTool = defineTool({
+  description: "Tags one artifact (test seed).",
+  inputSchema: z.object({
+    kind: z.string(),
+    key: z.string().optional(),
+    note: z.string().optional(),
+  }),
+  execute: async ({ kind, key, note }, ctx) => {
+    const record = await ctx.artifacts.tag({
+      kind,
+      key,
+      data: { note: note ?? null },
+    });
+    return { id: record.id };
+  },
+});
+
+function testProject(
+  rootDir: string,
+  options?: { channels?: DiscoveredChannel[] }
+): AgentProject {
+  const discovered: DiscoveredTool = {
+    name: "seed",
+    description: seedTool.description,
+    inputSchema: toolInputJsonSchema(seedTool.inputSchema),
+    execution: "server",
+    needsApproval: false,
+    definition: seedTool,
+  };
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "artifacts-route-test",
+    agent: {
+      name: "artifacts-route-test",
+      runtime: "local",
+      instructions: "Test agent.",
+      tools: [discovered],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: options?.channels ?? [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    artifacts: defineArtifacts({
+      kinds: {
+        "reviewed-pr": { description: "A reviewed PR." },
+        report: { description: "A report." },
+      },
+    }),
+    diagnostics: [],
+  };
+}
+
+const noTurnRunner: AgentRunner = {
+  runTurn: () => {
+    throw new Error("runTurn must not be called");
+  },
+};
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function startTestServer(
+  options?: Partial<ServeOptions>,
+  projectOptions?: { channels?: DiscoveredChannel[] }
+) {
+  const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-artroute-"));
+  cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+  const mounts: AgentMount[] = [
+    { slug: "", project: testProject(stateRoot, projectOptions) },
+  ];
+  const handle = await startServer(mounts, {
+    port: 0,
+    stateRoot,
+    playground: false,
+    schedules: false,
+    logger: () => {},
+    runner: noTurnRunner,
+    ...options,
+  });
+  cleanups.push(() => handle.close());
+  return handle;
+}
+
+async function listArtifacts(
+  url: string,
+  query = "",
+  headers: Record<string, string> = {}
+): Promise<{ status: number; artifacts: ArtifactRecord[] }> {
+  const response = await fetch(`${url}/v1/artifacts${query}`, { headers });
+  if (response.status !== 200) {
+    return { status: response.status, artifacts: [] };
+  }
+  const body = (await response.json()) as { artifacts: ArtifactRecord[] };
+  return { status: response.status, artifacts: body.artifacts };
+}
+
+/** Force distinct `updatedAt` millis so newest-first ordering is stable. */
+function tick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 5));
+}
+
+describe("GET /v1/artifacts", () => {
+  it("lists newest-updated first with kind filtering (dev includeAll)", async () => {
+    const handle = await startTestServer({ dev: true });
+    await handle.callTool("seed", { kind: "reviewed-pr", key: "pr-1" });
+    await tick();
+    await handle.callTool("seed", { kind: "report", key: "r-1" });
+    await tick();
+    await handle.callTool("seed", { kind: "reviewed-pr", key: "pr-2" });
+
+    const all = await listArtifacts(handle.url);
+    expect(all.status).toBe(200);
+    expect(all.artifacts.map((a) => a.key)).toEqual(["pr-2", "r-1", "pr-1"]);
+
+    const reports = await listArtifacts(handle.url, "?kind=report");
+    expect(reports.artifacts.map((a) => a.key)).toEqual(["r-1"]);
+
+    const none = await listArtifacts(handle.url, "?kind=missing");
+    expect(none.artifacts).toEqual([]);
+  });
+
+  it("filters by sessionId", async () => {
+    // Scratch (session-less) seeds never match a sessionId filter.
+    const handle = await startTestServer({ dev: true });
+    await handle.callTool("seed", { kind: "report", key: "loose" });
+    const filtered = await listArtifacts(handle.url, "?sessionId=ses_other");
+    expect(filtered.status).toBe(200);
+    expect(filtered.artifacts).toEqual([]);
+    expect((await listArtifacts(handle.url)).artifacts).toHaveLength(1);
+  });
+
+  it("bounds the limit and rejects non-positive limits", async () => {
+    const handle = await startTestServer({ dev: true });
+    for (const key of ["a", "b", "c"]) {
+      await handle.callTool("seed", { kind: "report", key });
+      await tick();
+    }
+    const limited = await listArtifacts(handle.url, "?limit=2");
+    expect(limited.artifacts).toHaveLength(2);
+    expect(limited.artifacts.map((a) => a.key)).toEqual(["c", "b"]);
+
+    // Above the ceiling clamps rather than erroring.
+    const clamped = await listArtifacts(handle.url, "?limit=99999");
+    expect(clamped.status).toBe(200);
+    expect(clamped.artifacts).toHaveLength(3);
+
+    expect((await listArtifacts(handle.url, "?limit=0")).status).toBe(400);
+    expect((await listArtifacts(handle.url, "?limit=nope")).status).toBe(400);
+  });
+
+  it("hides session-less artifacts from non-includeAll callers", async () => {
+    // No --dev: loopback callers get the strict per-principal view, and
+    // session-less (agent-scoped) artifacts have no owning principal.
+    const handle = await startTestServer();
+    await handle.callTool("seed", { kind: "report", key: "agent-scoped" });
+    const listed = await listArtifacts(handle.url);
+    expect(listed.status).toBe(200);
+    expect(listed.artifacts).toEqual([]);
+  });
+
+  it("channel onStart gets the unbound artifacts facade", async () => {
+    const channel: DiscoveredChannel = {
+      id: "starter",
+      definition: defineChannel({
+        async onStart({ artifacts }) {
+          await artifacts.tag({
+            kind: "report",
+            key: "from-onstart",
+            data: 1,
+          });
+        },
+      }),
+    };
+    const handle = await startTestServer(
+      { dev: true },
+      { channels: [channel] }
+    );
+    const listed = await listArtifacts(handle.url);
+    expect(listed.artifacts.map((a) => a.key)).toEqual(["from-onstart"]);
+    expect(listed.artifacts[0]?.sessionId).toBeUndefined();
+  });
+
+  it("requires the bearer token when one is configured", async () => {
+    const handle = await startTestServer({ authToken: "sekrit" });
+    const denied = await fetch(`${handle.url}/v1/artifacts`);
+    expect(denied.status).toBe(401);
+    const allowed = await fetch(`${handle.url}/v1/artifacts`, {
+      headers: { authorization: "Bearer sekrit" },
+    });
+    expect(allowed.status).toBe(200);
+  });
+
+  it("never widens to includeAll when a bearer token is configured", async () => {
+    // Bearer auth vetoes relaxSessionReadAuth even under --dev on loopback,
+    // matching GET /v1/sessions.
+    const handle = await startTestServer({ dev: true, authToken: "sekrit" });
+    await handle.callTool("seed", { kind: "report", key: "agent-scoped" });
+    const listed = await listArtifacts(handle.url, "", {
+      authorization: "Bearer sekrit",
+    });
+    expect(listed.status).toBe(200);
+    expect(listed.artifacts).toEqual([]);
+  });
+});
+
+describe("SessionEngine.listArtifacts ownership", () => {
+  const alice: AuthContext = {
+    authenticator: "test",
+    principalId: "alice",
+    principalType: "user",
+  };
+  const bob: AuthContext = {
+    authenticator: "test",
+    principalId: "bob",
+    principalType: "user",
+  };
+
+  async function makeEngine(): Promise<SessionEngine> {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-artown-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+    const engine = new SessionEngine({
+      project: testProject(stateRoot),
+      stateRoot,
+      runner: noTurnRunner,
+    });
+    cleanups.push(() => engine.close());
+    return engine;
+  }
+
+  async function seedSession(
+    engine: SessionEngine,
+    sessionId: string,
+    auth: AuthContext | null
+  ): Promise<void> {
+    await engine.sessions.save({
+      sessionId,
+      channelId: "http",
+      mode: "chat",
+      continuationKey: null,
+      auth,
+      turnCount: 0,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    });
+  }
+
+  it("scopes non-includeAll listings to the caller's sessions", async () => {
+    const engine = await makeEngine();
+    await seedSession(engine, "ses_alice", alice);
+    await seedSession(engine, "ses_bob", bob);
+    await engine.artifacts.tag({
+      kind: "report",
+      key: "alice-report",
+      data: 1,
+      sessionId: "ses_alice",
+    });
+    await engine.artifacts.tag({
+      kind: "report",
+      key: "bob-report",
+      data: 1,
+      sessionId: "ses_bob",
+    });
+    await engine.artifacts.tag({ kind: "report", key: "loose", data: 1 });
+
+    const forAlice = await engine.listArtifacts(alice);
+    expect(forAlice.map((a) => a.key)).toEqual(["alice-report"]);
+
+    const forBob = await engine.listArtifacts(bob);
+    expect(forBob.map((a) => a.key)).toEqual(["bob-report"]);
+
+    const anonymous = await engine.listArtifacts(null);
+    expect(anonymous).toEqual([]);
+
+    const everything = await engine.listArtifacts(null, { includeAll: true });
+    expect(everything.map((a) => a.key).sort()).toEqual([
+      "alice-report",
+      "bob-report",
+      "loose",
+    ]);
+  });
+
+  it("applies the filter before ownership scoping", async () => {
+    const engine = await makeEngine();
+    await seedSession(engine, "ses_alice", alice);
+    await engine.artifacts.tag({
+      kind: "reviewed-pr",
+      key: "pr",
+      data: 1,
+      sessionId: "ses_alice",
+    });
+    await engine.artifacts.tag({
+      kind: "report",
+      key: "rep",
+      data: 1,
+      sessionId: "ses_alice",
+    });
+    const filtered = await engine.listArtifacts(alice, {
+      filter: { kind: "reviewed-pr" },
+    });
+    expect(filtered.map((a) => a.key)).toEqual(["pr"]);
+  });
+});

package/src/internal/server.ts

@@ -139,6 +139,10 @@ import { sessionUrlsForRequest } from "./session-urls.js";
 
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
 
+/** `GET /v1/artifacts` limit defaults / ceiling. */
+const ARTIFACTS_LIST_DEFAULT_LIMIT = 200;
+const ARTIFACTS_LIST_MAX_LIMIT = 1000;
+
 /** One agent to serve: its slug (empty for single-agent mode) and project. */
 export interface AgentMount {
   slug: string;
@@ -490,6 +494,7 @@ export async function startServer(
           interruptContinuation: (continuationToken) =>
             engine.interruptContinuation(channel.id, continuationToken),
           logger,
+          artifacts: engine.artifacts,
         };
         try {
           await definition.onStart(startArgs);
@@ -999,6 +1004,44 @@ function mountAgentRoutes(
     },
   });
 
+  // Durable artifacts (ctx.artifacts / tag_artifact), newest-updated first.
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/artifacts`,
+    auth: httpAuth,
+    handler: async (request, ctx) => {
+      const url = new URL(request.url);
+      const limitRaw = url.searchParams.get("limit");
+      let limit = ARTIFACTS_LIST_DEFAULT_LIMIT;
+      if (limitRaw !== null && limitRaw !== "") {
+        const parsed = Number.parseInt(limitRaw, 10);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+          return errorResponse(
+            400,
+            "invalid_request",
+            "`limit` must be a positive integer."
+          );
+        }
+        limit = Math.min(parsed, ARTIFACTS_LIST_MAX_LIMIT);
+      }
+      const kind = url.searchParams.get("kind") ?? undefined;
+      const sessionId = url.searchParams.get("sessionId") ?? undefined;
+      // Same includeAll gate as /v1/sessions: never with bearer or custom
+      // channel auth (strict per-principal isolation); otherwise session
+      // ownership applies (see SessionEngine.listArtifacts).
+      const includeAll =
+        relaxSessionReadAuth &&
+        (relaxSessionReadAuthBeyondLoopback ||
+          (typeof ctx.requestIp === "string" &&
+            isLoopbackAddress(ctx.requestIp)));
+      const artifacts = await engine.listArtifacts(ctx.auth, {
+        includeAll,
+        filter: { kind, sessionId },
+      });
+      return jsonResponse({ artifacts: artifacts.slice(0, limit) });
+    },
+  });
+
   // The agent's MCP surface: peers and external MCP clients delegate to
   // this agent (ask / check / call_tool) over streamable HTTP. Stateless —
   // POST only; GET/DELETE get a spec-compliant 405 from the endpoint.
@@ -1736,6 +1779,7 @@ async function startCursorSlackRelay(input: {
         envelope,
         send: args.send,
         host: args.host,
+        artifacts: args.artifacts,
         hasContinuationSession: (continuationToken) =>
           target.runtime.engine.hasContinuationSession(
             target.channelId,
@@ -1803,6 +1847,7 @@ function buildChannelHandlerArgs(input: {
     requestIp: input.requestIp ?? null,
     auth,
     host: runtime.engine.host,
+    artifacts: runtime.engine.artifacts,
     send: (message, sendOptions = {}) =>
       runtime.engine.send(channelId, message, {
         ...sendOptions,

package/src/internal/session-engine.artifacts.test.ts

@@ -0,0 +1,293 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { defineArtifacts } from "../artifacts.js";
+import { defineChannel, httpChannel } from "../channels.js";
+import { defineHook } from "../hooks.js";
+import { defineSchedule } from "../schedules.js";
+import { defineTool } from "../tools.js";
+import type {
+  AgentProject,
+  ArtifactsDefinition,
+  DiscoveredChannel,
+  DiscoveredHook,
+  DiscoveredSchedule,
+  DiscoveredTool,
+  JsonObject,
+  ToolContext,
+} from "../types.js";
+import { ScheduleRunner } from "./schedule-runner.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionEngine } from "./session-engine.js";
+
+const AGENT = "artifacts-engine-test";
+
+function tagTool(): DiscoveredTool {
+  const definition = defineTool({
+    description: "Tags the reviewed PR as an artifact.",
+    async execute(_input: JsonObject, ctx: ToolContext) {
+      const record = await ctx.artifacts.tag({
+        kind: "artifact",
+        key: "pr-1",
+        title: "Reviewed PR",
+        data: { url: "https://github.com/org/repo/pull/1" },
+      });
+      return { id: record.id };
+    },
+  });
+  return {
+    name: "tag_result",
+    description: definition.description,
+    execution: "server",
+    needsApproval: false,
+    inputSchema: { type: "object", additionalProperties: false },
+    definition,
+  };
+}
+
+function testProject(options?: {
+  artifacts?: ArtifactsDefinition;
+  tools?: DiscoveredTool[];
+  hooks?: DiscoveredHook[];
+  schedules?: DiscoveredSchedule[];
+  channels?: DiscoveredChannel[];
+}): AgentProject {
+  return {
+    rootDir: "/tmp/artifacts-fixture",
+    agentDir: "/tmp/artifacts-fixture/agent",
+    name: AGENT,
+    agent: {
+      name: AGENT,
+      runtime: "local",
+      instructions: "Test agent.",
+      tools: options?.tools ?? [],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: options?.channels ?? [],
+    schedules: options?.schedules ?? [],
+    hooks: options?.hooks ?? [],
+    abs: [],
+    artifacts: options?.artifacts,
+    diagnostics: [],
+  };
+}
+
+function echoRunner(): AgentRunner {
+  return {
+    runTurn: async (request) => ({
+      status: "finished",
+      result: `echo: ${request.prompt}`,
+    }),
+  };
+}
+
+/** Runner that invokes the session-bound `tag_result` custom tool. */
+function toolCallingRunner(): AgentRunner {
+  return {
+    runTurn: async (request) => {
+      const tool = request.customTools.tag_result;
+      if (tool === undefined) {
+        throw new Error("tag_result not registered");
+      }
+      await tool.execute({}, { toolCallId: "call_tag_1" });
+      return { status: "finished", result: "done" };
+    },
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function makeEngine(
+  project: AgentProject,
+  runner: AgentRunner
+): Promise<SessionEngine> {
+  const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-artifacts-eng-"));
+  cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+  const engine = new SessionEngine({ project, stateRoot, runner });
+  cleanups.push(() => engine.close());
+  return engine;
+}
+
+describe("session engine artifacts wiring", () => {
+  it("tool ctx.artifacts auto-fills the session and appends artifact.tagged", async () => {
+    const engine = await makeEngine(
+      testProject({ tools: [tagTool()] }),
+      toolCallingRunner()
+    );
+    const session = await engine.send("http", "review the PR", { auth: null });
+    await session.waitForCompletion();
+
+    const rows = await engine.artifacts.list({ sessionId: session.id });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      kind: "artifact",
+      key: "pr-1",
+      sessionId: session.id,
+      turnId: "turn_1",
+      source: "host",
+    });
+
+    const events = await engine.listEvents(session.id);
+    const tagged = events.filter((event) => event.type === "artifact.tagged");
+    expect(tagged).toHaveLength(1);
+    expect(tagged[0]).toMatchObject({
+      sessionId: session.id,
+      turnId: "turn_1",
+      data: {
+        id: rows[0]?.id,
+        kind: "artifact",
+        key: "pr-1",
+        title: "Reviewed PR",
+        source: "host",
+      },
+    });
+  });
+
+  it("bound facades reject a conflicting explicit sessionId", async () => {
+    const engine = await makeEngine(testProject(), echoRunner());
+    const session = await engine.send("http", "hello", { auth: null });
+    await session.waitForCompletion();
+
+    const bound = engine.artifactsApi({ sessionId: session.id });
+    await expect(
+      bound.tag({ data: 1, sessionId: "ses_other" })
+    ).rejects.toThrow(/bound to session/);
+    // The matching sessionId (a no-op override) is fine.
+    await expect(
+      bound.tag({ data: 1, sessionId: session.id })
+    ).resolves.toMatchObject({ sessionId: session.id });
+  });
+
+  it("session-less tags via the unbound channel facade write the row only", async () => {
+    const engine = await makeEngine(testProject(), echoRunner());
+    const session = await engine.send("http", "hello", { auth: null });
+    await session.waitForCompletion();
+    const eventCount = (await engine.listEvents(session.id)).length;
+
+    // ChannelHandlerArgs.artifacts is this same unbound facade.
+    const record = await engine.artifacts.tag({ data: { note: "no session" } });
+    expect(record.sessionId).toBeUndefined();
+    expect(await engine.artifacts.list()).toHaveLength(1);
+    expect(await engine.listEvents(session.id)).toHaveLength(eventCount);
+  });
+
+  it("unbound tags with an explicit sessionId stream to that session", async () => {
+    const engine = await makeEngine(testProject(), echoRunner());
+    const session = await engine.send("http", "hello", { auth: null });
+    await session.waitForCompletion();
+
+    const record = await engine.artifacts.tag({
+      data: "attributed",
+      sessionId: session.id,
+    });
+    expect(record.sessionId).toBe(session.id);
+    const events = await engine.listEvents(session.id);
+    expect(events.some((event) => event.type === "artifact.tagged")).toBe(true);
+  });
+
+  it("tags for an unknown sessionId reject before writing the row", async () => {
+    const engine = await makeEngine(testProject(), echoRunner());
+    await expect(
+      engine.artifacts.tag({ data: 1, sessionId: "ses_nope" })
+    ).rejects.toThrow(/Unknown session/);
+    expect(await engine.artifacts.list()).toHaveLength(0);
+  });
+
+  it("schedule handlers get the unbound artifacts facade", async () => {
+    const cron = "* * * * *";
+    const schedule: DiscoveredSchedule = {
+      name: "tagger",
+      cron,
+      kind: "run",
+      definition: defineSchedule({
+        cron,
+        async run({ artifacts }) {
+          await artifacts.tag({ key: "from-schedule", data: "s" });
+        },
+      }),
+    };
+    const project = testProject({ schedules: [schedule] });
+    const engine = await makeEngine(project, echoRunner());
+    const runner = new ScheduleRunner(engine, project);
+    await runner.dispatch("tagger");
+
+    const rows = await engine.artifacts.list();
+    expect(rows.map((row) => row.key)).toEqual(["from-schedule"]);
+    expect(rows[0]?.sessionId).toBeUndefined();
+  });
+
+  it("channel receive hooks get the unbound artifacts facade", async () => {
+    const channel: DiscoveredChannel = {
+      id: "handoff",
+      definition: defineChannel({
+        async receive(input, { send, artifacts }) {
+          await artifacts.tag({ key: "from-receive", data: "r" });
+          return send(input.message, { auth: input.auth });
+        },
+      }),
+    };
+    const engine = await makeEngine(
+      testProject({ channels: [channel] }),
+      echoRunner()
+    );
+    await engine.receive("handoff", { message: "hand-off", auth: null });
+
+    const rows = await engine.artifacts.list();
+    expect(rows.map((row) => row.key)).toEqual(["from-receive"]);
+    expect(rows[0]?.sessionId).toBeUndefined();
+  });
+
+  it("hook ctx.artifacts is bound to the hook's session", async () => {
+    const hook: DiscoveredHook = {
+      name: "tagger",
+      definition: defineHook({
+        events: {
+          async "turn.completed"(_event, ctx) {
+            await ctx.artifacts.tag({ key: "from-hook", data: "h" });
+          },
+        },
+      }),
+    };
+    const engine = await makeEngine(
+      testProject({ hooks: [hook] }),
+      echoRunner()
+    );
+    const session = await engine.send("http", "hello", { auth: null });
+    await session.waitForCompletion();
+
+    await vi.waitFor(async () => {
+      const rows = await engine.artifacts.list({ sessionId: session.id });
+      expect(rows.map((row) => row.key)).toEqual(["from-hook"]);
+    });
+    const events = await engine.listEvents(session.id);
+    expect(events.some((event) => event.type === "artifact.tagged")).toBe(true);
+  });
+
+  it("enforces declared kinds end to end", async () => {
+    const engine = await makeEngine(
+      testProject({
+        artifacts: defineArtifacts({
+          kinds: { note: { description: "Note." } },
+        }),
+      }),
+      echoRunner()
+    );
+    await expect(
+      engine.artifacts.tag({ kind: "bogus", data: 1 })
+    ).rejects.toThrow(/unknown kind/);
+    await expect(
+      engine.artifacts.tag({ kind: "note", data: 1 })
+    ).resolves.toMatchObject({ kind: "note" });
+  });
+});