@cursor/july 0.1.101 → 0.1.103

package/src/internal/discovery/hooks.ts

@@ -0,0 +1,63 @@
+/**
+ * `agent/hooks/*.ts`: observe-only event subscribers.
+ */
+
+import { basename, extname, relative } from "node:path";
+import type { DiscoveredHook, HookDefinition } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+
+export async function loadHooks(
+  ctx: DiscoveryContext,
+  hooksDir: string,
+  onDisable?: (name: string, path: string) => void
+): Promise<DiscoveredHook[]> {
+  if (!(await isDirectory(hooksDir))) {
+    return [];
+  }
+  const hooks: DiscoveredHook[] = [];
+  for (const filePath of await walkFiles(hooksDir)) {
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const rel = toPosix(relative(hooksDir, filePath));
+    const name = rel.slice(0, -extname(rel).length);
+    if (name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: `Hook name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "hook" : ["hook", "disabled"]
+    );
+    if (definition === undefined) {
+      continue;
+    }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      continue;
+    }
+    const hook = definition as HookDefinition;
+    if (
+      typeof hook.events !== "object" ||
+      hook.events === null ||
+      Object.keys(hook.events).length === 0
+    ) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, filePath),
+        message: "Hook declares no event handlers.",
+      });
+      continue;
+    }
+    hooks.push({ name, definition: hook });
+  }
+  return hooks;
+}

package/src/internal/discovery/info.ts

@@ -0,0 +1,186 @@
+/**
+ * The `info` / `GET /v1/info` projection of an {@link AgentProject}.
+ */
+
+import { resolveABMaxPlaygroundSessions } from "../../ab.js";
+import { resolveArtifactsMax } from "../../artifacts.js";
+import {
+  type AgentProject,
+  type AgentProjectInfo,
+  toPublicCloudInfo,
+} from "../../types.js";
+import { toolInputJsonSchema } from "../json-schema.js";
+import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "../mcp-endpoint.js";
+import { connectionTransportLabel } from "./connections.js";
+
+export function projectInfo(project: AgentProject): AgentProjectInfo {
+  const agent = project.agent;
+  const httpRoutes: AgentProjectInfo["channels"][number]["routes"] = [
+    { method: "POST", path: "/v1/session", url: "/v1/session" },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId",
+      url: "/v1/session/:sessionId",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/stop",
+      url: "/v1/session/:sessionId/stop",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/stream",
+      url: "/v1/session/:sessionId/stream",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/approvals",
+      url: "/v1/session/:sessionId/approvals",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/approvals/:callId",
+      url: "/v1/session/:sessionId/approvals/:callId",
+    },
+  ];
+  return {
+    name: project.name,
+    description: agent.description,
+    model: agent.model,
+    runtime: agent.runtime,
+    cloud:
+      agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
+    local: agent.local,
+    hosting: agent.hosting,
+    concurrency: agent.concurrency,
+    mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
+    instructions:
+      agent.instructions === undefined
+        ? undefined
+        : {
+            chars: agent.instructions.length,
+            preview:
+              agent.instructions.length > 280
+                ? `${agent.instructions.slice(0, 277)}...`
+                : agent.instructions,
+          },
+    tools: agent.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      execution: tool.execution,
+      needsApproval: tool.needsApproval,
+      effect: tool.effect,
+      inputSchema: tool.inputSchema,
+    })),
+    skills: agent.skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+    })),
+    extensions: agent.extensions ?? [],
+    connections: agent.connections.map((connection) => ({
+      name: connection.name,
+      transport: connectionTransportLabel(connection.transport),
+      advertiseTools: connection.advertiseTools,
+      effects: connection.effects,
+      tools: connection.tools,
+      disallowedTools: connection.disallowedTools,
+      cursorAccountServers:
+        "cursorAccount" in connection.transport
+          ? (connection.transport.servers ?? "*")
+          : undefined,
+    })),
+    subagents: agent.subagents.map((subagent) => ({
+      name: subagent.name,
+      description: subagent.description,
+      model: subagent.model,
+    })),
+    channels: [
+      { id: "http", routes: httpRoutes },
+      ...project.channels.map((channel) => {
+        const info: AgentProjectInfo["channels"][number] = {
+          id: channel.id,
+          routes: (channel.definition.routes ?? []).map((r) => {
+            const routeInfo: AgentProjectInfo["channels"][number]["routes"][number] =
+              {
+                method: r.method,
+                path: r.path,
+                url: `/v1/channels/${channel.id}${r.path}`,
+              };
+            if (r.description !== undefined) {
+              routeInfo.description = r.description;
+            }
+            if (r.bodySchema !== undefined) {
+              routeInfo.bodySchema = toolInputJsonSchema(r.bodySchema);
+            }
+            if (r.querySchema !== undefined) {
+              routeInfo.querySchema = toolInputJsonSchema(r.querySchema);
+            }
+            return routeInfo;
+          }),
+        };
+        const meta = channel.definition.meta;
+        if (meta?.kind !== undefined) {
+          info.kind = meta.kind;
+        }
+        if (meta?.githubWebhookEvents !== undefined) {
+          info.githubWebhookEvents = meta.githubWebhookEvents;
+        }
+        if (meta?.originWebhookEvents !== undefined) {
+          info.originWebhookEvents = meta.originWebhookEvents;
+        }
+        if (meta?.gitlabWebhookEvents !== undefined) {
+          info.gitlabWebhookEvents = meta.gitlabWebhookEvents;
+        }
+        if (meta?.bitbucketWebhookEvents !== undefined) {
+          info.bitbucketWebhookEvents = meta.bitbucketWebhookEvents;
+        }
+        if (meta?.deploymentEventTypes !== undefined) {
+          info.deploymentEventTypes = meta.deploymentEventTypes;
+        }
+        if (meta?.slackChannelPosts !== undefined) {
+          info.slackChannelPosts = meta.slackChannelPosts;
+        }
+        return info;
+      }),
+    ],
+    schedules: project.schedules.map((schedule) => ({
+      name: schedule.name,
+      cron: schedule.cron,
+      kind: schedule.kind,
+    })),
+    hooks: project.hooks.map((hook) => hook.name),
+    abs: project.abs.map((experiment) => experiment.name),
+    ...(project.abConfig === undefined && project.abs.length === 0
+      ? {}
+      : {
+          abConfig: {
+            maxPlaygroundSessions: resolveABMaxPlaygroundSessions(
+              project.abConfig?.maxPlaygroundSessions
+            ),
+            durableSamples: project.storage?.abs !== undefined,
+            durableSnapshots: project.storage?.abs?.putSnapshot !== undefined,
+          },
+        }),
+    storage:
+      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),
+          },
+    result: project.result === undefined ? undefined : true,
+    otel:
+      project.otel === undefined
+        ? undefined
+        : {
+            enabled: true as const,
+            serviceName: project.otel.serviceName,
+          },
+    diagnostics: project.diagnostics,
+  };
+}

package/src/internal/discovery/instructions.ts

@@ -0,0 +1,113 @@
+/**
+ * `agent/instructions.md` (or `.ts`, or a directory): the always-on system prompt.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  AgentConfigDefinition,
+  InstructionsDefinition,
+} from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import {
+  type DiscoveryContext,
+  displayPath,
+  errorMessage,
+  isBlank,
+} from "./context.js";
+import {
+  findModuleFile,
+  isDirectory,
+  isFile,
+  isModuleFile,
+  sortedEntries,
+} from "./fs.js";
+
+export async function loadInstructions(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  config: AgentConfigDefinition | undefined,
+  isRoot: boolean
+): Promise<string | undefined> {
+  const parts: string[] = [];
+
+  const markdownPath = join(agentDir, "instructions.md");
+  if (await isFile(markdownPath)) {
+    parts.push((await readFile(markdownPath, "utf8")).trim());
+  }
+
+  const modulePath = await findModuleFile(agentDir, "instructions");
+  if (modulePath !== undefined) {
+    const loaded = await loadInstructionsModule(ctx, modulePath);
+    if (loaded !== undefined) {
+      parts.push(loaded);
+    }
+  }
+
+  const instructionsDir = join(agentDir, "instructions");
+  if (await isDirectory(instructionsDir)) {
+    for (const entry of await sortedEntries(instructionsDir)) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      const entryPath = join(instructionsDir, entry.name);
+      if (entry.name.endsWith(".md")) {
+        parts.push((await readFile(entryPath, "utf8")).trim());
+      } else if (isModuleFile(entry.name)) {
+        const loaded = await loadInstructionsModule(ctx, entryPath);
+        if (loaded !== undefined) {
+          parts.push(loaded);
+        }
+      }
+    }
+  }
+
+  if (config?.instructions !== undefined && !isBlank(config.instructions)) {
+    parts.push(config.instructions.trim());
+  }
+
+  const combined = parts.filter((part) => part !== "").join("\n\n");
+  if (combined === "") {
+    if (isRoot) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, markdownPath),
+        message:
+          "instructions.md is required on the root agent (the always-on system prompt).",
+      });
+    }
+    return undefined;
+  }
+  return combined;
+}
+
+async function loadInstructionsModule(
+  ctx: DiscoveryContext,
+  modulePath: string
+): Promise<string | undefined> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await ctx.importModule(modulePath);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, modulePath),
+      message: `Failed to load module: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  const value = mod.default;
+  if (typeof value === "string") {
+    return value.trim();
+  }
+  if (getDefinitionKind(value) === "instructions") {
+    return (value as InstructionsDefinition).markdown.trim();
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, modulePath),
+    message:
+      "Instructions modules must default-export a string or defineInstructions({ markdown }).",
+  });
+  return undefined;
+}

package/src/internal/discovery/modules.ts

@@ -0,0 +1,113 @@
+/**
+ * Walk a slot's module files, import one, and check that its default export carries an expected definition brand.
+ */
+
+import { join } from "node:path";
+import type { DefinitionKind } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
+import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
+import { validateName } from "./names.js";
+
+type ImportableKind = Exclude<
+  DefinitionKind,
+  "instructions" | "eval" | "reminder"
+>;
+
+/** The module files of a slot directory whose filenames are valid names. */
+export async function moduleEntries(
+  ctx: DiscoveryContext,
+  dir: string,
+  kind: "tool" | "connection"
+): Promise<Array<{ name: string; path: string }>> {
+  if (!(await isDirectory(dir))) {
+    return [];
+  }
+  const entries: Array<{ name: string; path: string }> = [];
+  for (const entry of await sortedEntries(dir)) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, path),
+        message: `Nested ${kind} directories are not supported; ignoring.`,
+      });
+      continue;
+    }
+    if (!entry.isFile() || !isModuleFile(entry.name)) {
+      continue;
+    }
+    const name = moduleStem(entry.name);
+    if (validateName(ctx, kind, name, path)) {
+      entries.push({ name, path });
+    }
+  }
+  return entries;
+}
+
+/**
+ * The module's default export when it carries one of the expected brands;
+ * a diagnostic and `undefined` otherwise.
+ */
+export async function importDefault(
+  ctx: DiscoveryContext,
+  modulePath: string,
+  expected: ImportableKind | readonly ImportableKind[]
+): Promise<unknown> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await ctx.importModule(modulePath);
+  } catch (error) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, modulePath),
+      message: `Failed to load module: ${errorMessage(error)}`,
+    });
+    return undefined;
+  }
+  const kinds = typeof expected === "string" ? [expected] : expected;
+  const kind = getDefinitionKind(mod.default);
+  if (kind !== undefined && kinds.includes(kind as ImportableKind)) {
+    return mod.default;
+  }
+  const helpers = kinds.map(helperCall).join(" or ");
+  const expectedKinds = kinds.join(" or ");
+  const article = /^[aeiou]/.test(expectedKinds) ? "an" : "a";
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, modulePath),
+    message:
+      kind === undefined
+        ? `Module must default-export ${helpers}.`
+        : `Expected ${article} ${expectedKinds} definition but found "${kind}" (wrong authored slot?).`,
+  });
+  return undefined;
+}
+
+/** How a definition of `kind` is authored: `defineTool({ ... })`, `disableTool()`. */
+export function helperCall(kind: ImportableKind): string {
+  const name = DEFINE_HELPER_NAME[kind];
+  return kind === "disabled" || kind.startsWith("disabled-")
+    ? `${name}()`
+    : `${name}({ ... })`;
+}
+
+const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
+  agent: "defineAgent",
+  tool: "defineTool",
+  skill: "defineSkill",
+  extension: "defineExtension",
+  "disabled-tool": "disableTool",
+  "disabled-connection": "disableConnection",
+  disabled: "disable",
+  connection: "defineConnection",
+  channel: "defineChannel",
+  "http-channel": "httpChannel",
+  schedule: "defineSchedule",
+  hook: "defineHook",
+  ab: "defineAB",
+  storage: "defineStorage",
+  artifacts: "defineArtifacts",
+  otel: "defineOtel",
+  result: "defineResult",
+};

package/src/internal/discovery/names.ts

@@ -0,0 +1,45 @@
+/**
+ * The path-derived naming rule: filenames become the names the model sees.
+ */
+
+import { type DiscoveryContext, displayPath } from "./context.js";
+
+export const NAME_PATTERN: RegExp = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Filenames become the names the model sees. `__` is reserved: it joins an
+ * extension's namespace to its contribution (`ci__failed_jobs`), so no
+ * authored name may carry it.
+ */
+export function validateName(
+  ctx: DiscoveryContext,
+  kind: "skill" | "tool" | "extension" | "connection" | "subagent" | "channel",
+  name: string,
+  entryPath: string
+): boolean {
+  const label = {
+    skill: "Skill",
+    tool: "Tool",
+    extension: "Extension",
+    connection: "MCP connection",
+    subagent: "Subagent",
+    channel: "Channel",
+  }[kind];
+  if (!NAME_PATTERN.test(name)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `${label} name "${name}" must match ${NAME_PATTERN}.`,
+    });
+    return false;
+  }
+  if (name.includes("__")) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: `${label} name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+    });
+    return false;
+  }
+  return true;
+}