@cursor/july 0.1.23 → 0.1.25

package/src/internal/cli-slack.ts

@@ -491,6 +491,16 @@ interface ConnectWaitTarget {
   notConnectedAt?: string;
 }
 
+/**
+ * Slack's team-scoped admin page listing pending app-install requests.
+ * Provisioned apps have no OAuth flow (no redirect URLs, install-from-Slack
+ * disabled), so the oauth_authorize_url Slack returns from
+ * apps.manifest.create dead-ends; approval happens here instead.
+ */
+function slackAppRequestsUrl(slackTeamId: string): string {
+  return `https://app.slack.com/apps-manage/${encodeURIComponent(slackTeamId)}/integrations/requests`;
+}
+
 /** "Name (T0123ABCD)", or the bare id when the backend has no name. */
 function formatWorkspace(workspace: SlackConnectedWorkspace): string {
   const name = workspace.slackTeamName ?? "";
@@ -719,6 +729,7 @@ export async function cmdSlackCreate(
   const iconStatus = await applySlackCreateIcon(ctx, iconSource, result);
 
   if (result.status === "pending_admin_approval") {
+    const approveUrl = slackAppRequestsUrl(workspace.slackTeamId);
     if (ctx.json) {
       ctx.out(
         `${JSON.stringify(
@@ -729,7 +740,7 @@ export async function cmdSlackCreate(
             slackTeamId: workspace.slackTeamId,
             envKeys: target.envKeys,
             wrote,
-            oauthAuthorizeUrl: result.oauthAuthorizeUrl ?? null,
+            approveUrl,
             iconStatus,
           },
           null,
@@ -739,9 +750,7 @@ export async function cmdSlackCreate(
     } else {
       ctx.err(
         `The Slack app was created (app ${result.appId}), but installing it needs a Slack workspace-admin approval.\n` +
-          (result.oauthAuthorizeUrl === undefined
-            ? ""
-            : `\n  Approve it (or send this to a workspace admin):\n\n    ${result.oauthAuthorizeUrl}\n\n`) +
+          `\n  A workspace admin can approve it here:\n\n    ${approveUrl}\n\n` +
           `Once an admin approves the app, re-run \`${CLI} slack create\` to finish the install and mint the tokens.\n`
       );
     }

package/src/internal/discovery.artifact-tool.test.ts

@@ -0,0 +1,136 @@
+import { mkdir, 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 { defineArtifacts } from "../artifacts.js";
+import { defineAgent } from "../index.js";
+import { defineTool } from "../tools.js";
+import type { AgentConfig, ArtifactsConfig } from "../types.js";
+import { loadAgentProject, projectInfo } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+const TAGGABLE: ArtifactsConfig = {
+  kinds: {
+    "reviewed-pr": { description: "A reviewed PR." },
+    report: { description: "A report." },
+  },
+  agentTool: true,
+};
+
+async function scaffold(options: {
+  agent?: AgentConfig;
+  artifacts?: ArtifactsConfig;
+  authoredTools?: string[];
+}) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-artifact-tool-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "Be brief.\n");
+  if (options.artifacts !== undefined) {
+    await writeFile(join(agentDir, "artifacts.ts"), "export default {};\n");
+  }
+  for (const name of options.authoredTools ?? []) {
+    await mkdir(join(agentDir, "tools"), { recursive: true });
+    await writeFile(
+      join(agentDir, "tools", `${name}.ts`),
+      "export default {};\n"
+    );
+  }
+  return loadAgentProject(rootDir, {
+    importModule: async (path) => {
+      if (path.endsWith("artifacts.ts")) {
+        return { default: defineArtifacts(options.artifacts ?? {}) };
+      }
+      if (path.includes(join("agent", "tools"))) {
+        return {
+          default: defineTool({
+            description: "Authored tool.",
+            execute: () => "authored",
+          }),
+        };
+      }
+      return { default: defineAgent(options.agent ?? {}) };
+    },
+  });
+}
+
+describe("loadAgentProject tag_artifact built-in", () => {
+  it("materializes tag_artifact when agentTool is true", async () => {
+    const project = await scaffold({ artifacts: TAGGABLE });
+    const tool = project.agent.tools.find((t) => t.name === "tag_artifact");
+    expect(tool).toMatchObject({
+      name: "tag_artifact",
+      execution: "server",
+      needsApproval: false,
+    });
+    expect(tool?.description).toContain("- reviewed-pr: A reviewed PR.");
+    expect(project.diagnostics).toEqual([]);
+
+    // Info/manifest surface it exactly like authored tools.
+    const info = projectInfo(project);
+    const infoTool = info.tools.find((t) => t.name === "tag_artifact");
+    expect(infoTool?.execution).toBe("server");
+    expect(infoTool?.inputSchema).toBeDefined();
+    expect(info.artifacts?.agentTool).toBe(true);
+  });
+
+  it("stays absent without agentTool", async () => {
+    const withoutFlag = await scaffold({
+      artifacts: { kinds: { report: { description: "A report." } } },
+    });
+    expect(withoutFlag.agent.tools.some((t) => t.name === "tag_artifact")).toBe(
+      false
+    );
+
+    const unauthored = await scaffold({});
+    expect(unauthored.agent.tools.some((t) => t.name === "tag_artifact")).toBe(
+      false
+    );
+  });
+
+  it("skips the tool on cloud runtime, with a warning", async () => {
+    const project = await scaffold({
+      agent: {
+        runtime: "cloud",
+        cloud: { repos: [{ url: "https://github.com/org/repo" }] },
+      },
+      artifacts: TAGGABLE,
+    });
+    expect(project.agent.tools.some((t) => t.name === "tag_artifact")).toBe(
+      false
+    );
+    expect(
+      project.diagnostics.some(
+        (d) =>
+          d.severity === "warning" &&
+          d.message.includes("tag_artifact") &&
+          d.message.includes("not available on cloud agents")
+      )
+    ).toBe(true);
+  });
+
+  it("lets an authored tag_artifact shadow the built-in, with a warning", async () => {
+    const project = await scaffold({
+      artifacts: TAGGABLE,
+      authoredTools: ["tag_artifact"],
+    });
+    const tools = project.agent.tools.filter((t) => t.name === "tag_artifact");
+    expect(tools).toHaveLength(1);
+    expect(tools[0]?.description).toBe("Authored tool.");
+    expect(project.diagnostics).toEqual([
+      expect.objectContaining({
+        severity: "warning",
+        message: expect.stringContaining("shadows the built-in tool"),
+      }),
+    ]);
+  });
+});

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

@@ -0,0 +1,119 @@
+import { mkdir, 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 { defineArtifacts } from "../artifacts.js";
+import { defineAgent } from "../index.js";
+import type { ArtifactsConfig } from "../types.js";
+import { loadAgentProject, projectInfo } from "./discovery.js";
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function scaffold(options: {
+  artifacts?: ArtifactsConfig;
+  subagentArtifacts?: boolean;
+}) {
+  const rootDir = await mkdtemp(join(tmpdir(), "agent-serve-artifacts-disc-"));
+  cleanups.push(() => rm(rootDir, { recursive: true, force: true }));
+  const agentDir = join(rootDir, "agent");
+  await mkdir(agentDir, { recursive: true });
+  await writeFile(join(agentDir, "agent.ts"), "export default {};\n");
+  await writeFile(join(agentDir, "instructions.md"), "Be brief.\n");
+  if (options.artifacts !== undefined) {
+    await writeFile(join(agentDir, "artifacts.ts"), "export default {};\n");
+  }
+  if (options.subagentArtifacts === true) {
+    const subagentDir = join(agentDir, "subagents", "helper");
+    await mkdir(subagentDir, { recursive: true });
+    await writeFile(join(subagentDir, "agent.ts"), "export default {};\n");
+    await writeFile(join(subagentDir, "instructions.md"), "Help.\n");
+    await writeFile(join(subagentDir, "artifacts.ts"), "export default {};\n");
+  }
+  return loadAgentProject(rootDir, {
+    importModule: async (path) => {
+      if (path.endsWith("artifacts.ts")) {
+        return { default: defineArtifacts(options.artifacts ?? {}) };
+      }
+      if (path.includes("subagents")) {
+        return { default: defineAgent({ description: "Helper." }) };
+      }
+      return { default: defineAgent({}) };
+    },
+  });
+}
+
+describe("loadAgentProject artifacts", () => {
+  it("discovers agent/artifacts.ts and surfaces it on the manifest and info", async () => {
+    const project = await scaffold({
+      artifacts: {
+        kinds: {
+          "reviewed-pr": { description: "A reviewed PR." },
+          report: { description: "A report." },
+        },
+        max: 50,
+      },
+    });
+    expect(project.artifacts).toBeDefined();
+    expect(project.diagnostics).toEqual([]);
+    expect(projectInfo(project).artifacts).toEqual({
+      kinds: ["reviewed-pr", "report"],
+      agentTool: false,
+      max: 50,
+    });
+  });
+
+  it("defaults max to 1000 on info and stays absent when unauthored", async () => {
+    const withDefaults = await scaffold({ artifacts: { kinds: {} } });
+    expect(projectInfo(withDefaults).artifacts).toEqual({
+      kinds: [],
+      agentTool: false,
+      max: 1000,
+    });
+
+    const without = await scaffold({});
+    expect(without.artifacts).toBeUndefined();
+    expect(projectInfo(without).artifacts).toBeUndefined();
+  });
+
+  it("errors when agentTool is set without declared kinds", async () => {
+    const project = await scaffold({ artifacts: { agentTool: true } });
+    expect(project.diagnostics).toEqual([
+      expect.objectContaining({
+        severity: "error",
+        message: expect.stringContaining(
+          "the tag_artifact tool needs at least one declared kind"
+        ),
+      }),
+    ]);
+  });
+
+  it("accepts agentTool with at least one kind (schema optional)", async () => {
+    const project = await scaffold({
+      artifacts: {
+        kinds: { note: { description: "A note." } },
+        agentTool: true,
+      },
+    });
+    expect(project.diagnostics).toEqual([]);
+    expect(projectInfo(project).artifacts?.agentTool).toBe(true);
+  });
+
+  it("warns and ignores artifacts on subagents", async () => {
+    const project = await scaffold({ subagentArtifacts: true });
+    expect(project.diagnostics).toEqual([
+      expect.objectContaining({
+        severity: "warning",
+        message: expect.stringContaining(
+          "artifacts are not supported on subagents"
+        ),
+      }),
+    ]);
+    expect(project.artifacts).toBeUndefined();
+  });
+});

package/src/internal/discovery.ts

@@ -18,6 +18,7 @@ import {
 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
+import { resolveArtifactsMax } from "../artifacts.js";
 import { httpChannel } from "../channels.js";
 import type { StorageDefinition } from "../storage.js";
 import {
@@ -27,6 +28,7 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
+  type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
   type ConnectionDefinition,
@@ -58,7 +60,11 @@ import {
 import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { normalizePositiveInt } from "./bounded-int.js";
 import { getDefinitionKind } from "./brand.js";
-import { builtinTools } from "./builtin-tools/index.js";
+import {
+  artifactBuiltinTool,
+  builtinTools,
+  TAG_ARTIFACT_TOOL_NAME,
+} from "./builtin-tools/index.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import {
@@ -280,6 +286,8 @@ export async function loadAgentProject(
   const abs = await loadABs(ctx, agentDir);
   const abConfig = await loadABConfig(ctx, agentDir);
   const storage = await loadStorage(ctx, agentDir);
+  const artifacts = await loadArtifacts(ctx, agentDir);
+  await appendArtifactTool(ctx, agentDir, agent, artifacts);
 
   if (agentDir !== rootDir) {
     await warnUnknownSlots(ctx, agentDir);
@@ -297,6 +305,7 @@ export async function loadAgentProject(
     abs,
     abConfig,
     storage,
+    artifacts,
     diagnostics,
   };
 }
@@ -351,6 +360,14 @@ async function loadAgent(
         message: "builtinTools is not supported on subagents; ignoring.",
       });
     }
+    const artifactsPath = await findModuleFile(agentDir, "artifacts");
+    if (artifactsPath !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, artifactsPath),
+        message: "artifacts are not supported on subagents; ignoring.",
+      });
+    }
     return {
       name,
       ...(config?.description === undefined
@@ -1579,6 +1596,81 @@ async function loadStorage(
   return definition as StorageDefinition | undefined;
 }
 
+// ============================================================================
+// Artifacts (agent/artifacts.ts)
+// ============================================================================
+
+async function loadArtifacts(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<ArtifactsDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "artifacts");
+  if (path === undefined) {
+    return undefined;
+  }
+  const imported = await importDefault(ctx, path, "artifacts");
+  if (imported === undefined) {
+    return undefined;
+  }
+  const definition = imported as ArtifactsDefinition;
+  if (
+    definition.agentTool === true &&
+    Object.keys(definition.kinds ?? {}).length === 0
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        "artifacts.agentTool requires kinds: the tag_artifact tool needs at least one declared kind; its descriptions are the tool prompt.",
+    });
+  }
+  return definition;
+}
+
+/**
+ * Materialize the `tag_artifact` built-in when `defineArtifacts` set
+ * `agentTool: true`. Appended after `loadAgent` because the tool is
+ * generated from the artifacts kinds registry, not `AgentConfig.builtinTools`.
+ */
+async function appendArtifactTool(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  agent: ResolvedAgent,
+  artifacts: ArtifactsDefinition | undefined
+): Promise<void> {
+  const tool = artifactBuiltinTool(artifacts);
+  if (tool === undefined) {
+    return;
+  }
+  const artifactsPath = displayPath(
+    ctx,
+    (await findModuleFile(agentDir, "artifacts")) ??
+      join(agentDir, "artifacts.ts")
+  );
+  // TODO(artifacts-cloud): on cloud runtimes, ship tag_artifact as an
+  // execution: "agent" script and have the host fold its action.result
+  // stream events into artifact records — agent-tool calls already surface
+  // durably in the session stream.
+  if (agent.runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: artifactsPath,
+      message:
+        "tag_artifact is an in-process server tool (like builtinTools) and is not available on cloud agents; it is skipped.",
+    });
+    return;
+  }
+  if (agent.tools.some((t) => t.name === TAG_ARTIFACT_TOOL_NAME)) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: artifactsPath,
+      message: `Authored tool "${TAG_ARTIFACT_TOOL_NAME}" shadows the built-in tool of the same name; the authored tool wins.`,
+    });
+    return;
+  }
+  agent.tools.push(tool);
+}
+
 function resolveABName(definition: unknown, fallback: string): string {
   if (
     typeof definition === "object" &&
@@ -1759,6 +1851,14 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       project.storage === undefined
         ? undefined
         : { name: project.storage.name },
+    artifacts:
+      project.artifacts === undefined
+        ? undefined
+        : {
+            kinds: Object.keys(project.artifacts.kinds ?? {}),
+            agentTool: project.artifacts.agentTool === true,
+            max: resolveArtifactsMax(project.artifacts),
+          },
     diagnostics: project.diagnostics,
   };
 }
@@ -1779,6 +1879,7 @@ async function importDefault(
     | "hook"
     | "ab"
     | "storage"
+    | "artifacts"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {

package/src/internal/distribution.ts

@@ -107,6 +107,7 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["evals/reporters", "evals/reporters.js"],
   ["evals/loaders", "evals/loaders.js"],
   ["ab", "ab.js"],
+  ["artifacts", "artifacts.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
   ["storage/postgres-kv", "storage-backends/postgres-kv.js"],

package/src/internal/handleAgentServeTrigger.test.ts

@@ -115,6 +115,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("recv"),