@cursor/july 0.1.99 → 0.1.101

package/src/extensions/cursor-cloud-agents/lib/cloud.ts

@@ -0,0 +1,79 @@
+/** The Cursor SDK surface the tools share: auth, model, result views. */
+
+import type { ModelSelection, Run, RunStatus, SDKAgentInfo } from "@cursor/sdk";
+import { z } from "zod";
+import {
+  cursorWebsiteUrl,
+  resolveApiKeySync,
+  SIGN_IN_HINT,
+} from "../../../internal/cursor/credentials.js";
+import { toModelSelection } from "../../../internal/sdk-runner.js";
+import extension from "../extension.js";
+
+export const agentRef: z.ZodObject<{ agentId: z.ZodString }> = z.object({
+  agentId: z.string().describe("Agent id (`bc-...`) returned by a launch."),
+});
+
+export function apiKey(): string {
+  const key = resolveApiKeySync({ apiKey: extension.config.apiKey });
+  if (key === undefined) {
+    throw new Error(`Cloud agents need a Cursor API key. ${SIGN_IN_HINT}`);
+  }
+  return key.apiKey;
+}
+
+export function modelSelection(): ModelSelection | undefined {
+  const { model } = extension.config;
+  return model === undefined ? undefined : toModelSelection(model);
+}
+
+export function agentUrl(agentId: string): string {
+  return `${cursorWebsiteUrl()}/agents/${agentId}`;
+}
+
+// Type aliases, not interfaces: views flow into tool results.
+export type AgentView = {
+  agentId: string;
+  name: string;
+  archived: boolean | undefined;
+  url: string;
+};
+
+export type RunView = {
+  id: string;
+  status: RunStatus;
+  result: string | undefined;
+  error: string | undefined;
+  durationMs: number | undefined;
+  branches:
+    | Array<{
+        repoUrl: string;
+        branch: string | undefined;
+        prUrl: string | undefined;
+      }>
+    | undefined;
+};
+
+export function agentView(info: SDKAgentInfo): AgentView {
+  return {
+    agentId: info.agentId,
+    name: info.name,
+    archived: info.archived,
+    url: agentUrl(info.agentId),
+  };
+}
+
+export function runView(run: Run): RunView {
+  return {
+    id: run.id,
+    status: run.status,
+    result: run.result,
+    error: run.error?.message,
+    durationMs: run.durationMs,
+    branches: run.git?.branches.map((branch) => ({
+      repoUrl: branch.repoUrl,
+      branch: branch.branch,
+      prUrl: branch.prUrl,
+    })),
+  };
+}

package/src/extensions/cursor-cloud-agents/lib/fleet.ts

@@ -0,0 +1,109 @@
+/**
+ * Who launched which cloud agent. The tools authenticate with the serve
+ * host's one Cursor API key, so the host itself must keep every session's
+ * cloud agents bound to the principal that launched them: status and
+ * follow-ups only reach agents recorded here for the same principal, and
+ * the fleet listing is that principal's records, by default narrowed to the
+ * session that launched them.
+ */
+
+import { z } from "zod";
+import type { ToolContext } from "../../../types.js";
+
+const PREFIX = "cloud-agents";
+
+// Type alias, not an interface: fleet entries flow into tool results.
+export type FleetEntry = {
+  agentId: string;
+  name?: string;
+  launchedAt: string;
+  /** The session whose turn launched the agent; absent on records older than this field. */
+  sessionId?: string;
+};
+
+export type FleetScope = "session" | "all";
+
+const fleetSchema: z.ZodType<FleetEntry[]> = z.array(
+  z.object({
+    agentId: z.string(),
+    name: z.string().optional(),
+    launchedAt: z.string(),
+    sessionId: z.string().optional(),
+  })
+);
+const ownerSchema = z.object({ principal: z.string() });
+
+// `host.kv` has no compare-and-swap, and a model that launches two agents in
+// one turn calls this tool in parallel. Chain the index read-modify-write per
+// principal so neither launch overwrites the other's entry.
+const indexWrites = new Map<string, Promise<void>>();
+
+function withIndexLock(key: string, task: () => Promise<void>): Promise<void> {
+  const run = (indexWrites.get(key) ?? Promise.resolve()).then(task, task);
+  indexWrites.set(key, run);
+  return run.finally(() => {
+    if (indexWrites.get(key) === run) {
+      indexWrites.delete(key);
+    }
+  });
+}
+
+/** Unauthenticated sessions (local dev, direct calls) share one principal. */
+export function principalOf(ctx: ToolContext): string {
+  const auth = ctx.session.auth;
+  return auth === null
+    ? "anonymous"
+    : `${auth.principalType}:${auth.principalId}`;
+}
+
+export async function recordLaunch(
+  ctx: ToolContext,
+  agentId: string,
+  name: string | undefined
+): Promise<void> {
+  const principal = principalOf(ctx);
+  const entry: FleetEntry = {
+    agentId,
+    name,
+    launchedAt: new Date().toISOString(),
+    sessionId: ctx.session.id,
+  };
+  await ctx.host.kv.put(`${PREFIX}/agents/${agentId}`, { principal });
+  await withIndexLock(fleetKey(principal), async () => {
+    const fleet = await listFleet(ctx);
+    await ctx.host.kv.put(fleetKey(principal), [entry, ...fleet]);
+  });
+}
+
+/** Refuse agents launched by another principal, or not through the extension. */
+export async function assertOwned(
+  ctx: ToolContext,
+  agentId: string
+): Promise<void> {
+  const owner = ownerSchema.safeParse(
+    await ctx.host.kv.get(`${PREFIX}/agents/${agentId}`)
+  );
+  if (!owner.success || owner.data.principal !== principalOf(ctx)) {
+    throw new Error(
+      `Agent ${agentId} was not launched through this extension by this principal; only your own launches can be read or steered.`
+    );
+  }
+}
+
+/** The caller's launches, newest first: this session's, or every session's. */
+export async function listFleet(
+  ctx: ToolContext,
+  scope: FleetScope = "all"
+): Promise<FleetEntry[]> {
+  const fleet = fleetSchema.safeParse(
+    await ctx.host.kv.get(fleetKey(principalOf(ctx)))
+  );
+  const entries = fleet.success ? fleet.data : [];
+  return scope === "all"
+    ? entries
+    : entries.filter((entry) => entry.sessionId === ctx.session.id);
+}
+
+function fleetKey(principal: string): string {
+  return `${PREFIX}/principals/${encodeURIComponent(principal)}`;
+}

package/src/extensions/cursor-cloud-agents/lib/repos.ts

@@ -0,0 +1,81 @@
+/**
+ * Which repositories a launch may target. The model picks `repo` / `ref` /
+ * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
+ * Model-chosen targets always require that allowlist: an unbound mount
+ * (no `cloud.repos`) must not accept an arbitrary URL under the host API
+ * key, with or without `envVars`.
+ */
+
+import { parsePrUrl } from "../../../internal/scm/pr-url.js";
+import type { AgentCloudOptions } from "../../../types.js";
+
+export interface LaunchTarget {
+  repo?: string;
+  ref?: string;
+  prUrl?: string;
+}
+
+export function launchRepos(
+  target: LaunchTarget,
+  cloud: AgentCloudOptions
+): AgentCloudOptions["repos"] {
+  if (
+    target.repo === undefined &&
+    target.ref === undefined &&
+    target.prUrl === undefined
+  ) {
+    return cloud.repos;
+  }
+  const pr = target.prUrl === undefined ? undefined : parsePrUrl(target.prUrl);
+  if (target.prUrl !== undefined && pr?.provider !== "github") {
+    throw new Error(`prUrl must be a GitHub pull request URL: ${target.prUrl}`);
+  }
+  const prRepo =
+    pr === undefined ? undefined : `https://github.com/${pr.owner}/${pr.repo}`;
+  // A lone `ref` needs exactly one configured repository to apply to.
+  const configured = cloud.repos ?? [];
+  const url =
+    target.repo ??
+    prRepo ??
+    (configured.length === 1 ? configured[0]?.url : undefined);
+  if (url === undefined) {
+    throw new Error(
+      configured.length > 1
+        ? "`repo` is required: this extension configures several repositories."
+        : "`repo` is required: this extension has no configured default repository."
+    );
+  }
+  if (prRepo !== undefined && repoKey(prRepo) !== repoKey(url)) {
+    throw new Error(`prUrl ${target.prUrl} is not a pull request of ${url}.`);
+  }
+  const allowlisted = cloud.repos?.some(
+    (configured) => repoKey(configured.url) === repoKey(url)
+  );
+  if (allowlisted !== true) {
+    throw new Error(
+      cloud.repos === undefined
+        ? `Configure cloud.repos before launching against a model-chosen repository (${url}).`
+        : `${url} is not one of this extension's configured repositories.`
+    );
+  }
+  // Keep the matching allowlist entry's branch / PR defaults when the model
+  // only names the repository (handoff always passes `repo`). An explicit
+  // `ref` clears an inherited `prUrl` so branch and PR targets do not mix.
+  const match = configured.find(
+    (configuredRepo) => repoKey(configuredRepo.url) === repoKey(url)
+  );
+  return [
+    {
+      url,
+      startingRef: target.ref ?? match?.startingRef,
+      prUrl:
+        target.prUrl ?? (target.ref !== undefined ? undefined : match?.prUrl),
+    },
+  ];
+}
+
+function repoKey(url: string): string {
+  const parsed = new URL(url);
+  const path = parsed.pathname.replace(/\.git$/, "").replace(/\/+$/, "");
+  return `${parsed.hostname}${path}`.toLowerCase();
+}

package/src/extensions/cursor-cloud-agents/skills/handoff.md

@@ -0,0 +1,27 @@
+---
+description: "Delegate coding work to Cursor cloud agents: when to hand off, how to write the prompt, and how to follow up and check status."
+---
+
+# Cloud agent handoff
+
+Hand work to a Cursor cloud agent when it needs a repository checkout, a long run, or an isolated machine: implementing a change, running a test suite, opening a pull request. Answer questions and small reads yourself.
+
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__launch` and so on.
+
+## Launch
+
+Call `launch` with a self-contained prompt: the goal, the repository or pull request, constraints (branch, files to leave alone), and what done looks like (tests pass, PR opened). Pass `ref` or `prUrl` to pick a branch or pull request; `repo` must be one of the configured repositories.
+
+The result carries `agentId` (`bc-...`) and a `url`. Report both in full. Never truncate the id.
+
+## Follow up
+
+Call `follow_up` with the `agentId` to steer an agent you launched or ask for changes on its branch. A busy agent rejects the follow-up: check status and retry once its run has finished. Do not launch a second agent for follow-up work on the same branch.
+
+## Check status
+
+Call `status` with the `agentId`. The latest run carries `status` (`running`, `finished`, `error`, or `cancelled`), the final `result` text, an `error` message, and any pushed `branches` or pull requests; the agent itself reports `archived`. A run takes minutes: check when asked or when you need the result, not in a tight loop.
+
+## Fleet
+
+`list` returns the agents launched in this session, newest first; pass `scope: "all"` to include your launches from other sessions. Launch one agent per independent task and give each a descriptive `name`. Agents launched by others are out of reach.

package/src/extensions/cursor-cloud-agents/tools/follow_up.ts

@@ -0,0 +1,29 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { agentRef, apiKey } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+
+const follow_up: ToolDefinition = defineTool({
+  description:
+    "Send a follow-up prompt to a cloud agent you launched. The agent must be idle; a busy agent rejects the follow-up.",
+  effect: "write",
+  needsApproval: () => extension.config.needsApproval,
+  inputSchema: agentRef.extend({
+    prompt: z.string().min(1).describe("The follow-up instruction."),
+  }),
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agentId);
+    const agent = await Agent.resume(input.agentId, { apiKey: apiKey() });
+    try {
+      const run = await agent.send(input.prompt);
+      return { agentId: input.agentId, runId: run.id, status: run.status };
+    } finally {
+      agent.close();
+    }
+  },
+});
+
+export default follow_up;

package/src/extensions/cursor-cloud-agents/tools/launch.ts

@@ -0,0 +1,84 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { agentUrl, agentView, apiKey, modelSelection } from "../lib/cloud.js";
+import { recordLaunch } from "../lib/fleet.js";
+import { launchRepos } from "../lib/repos.js";
+
+const launch: ToolDefinition = defineTool({
+  description:
+    "Launch a Cursor cloud agent on a repository with a self-contained task. Returns the agent id and URL; check progress with the status tool.",
+  effect: "write",
+  needsApproval: () => extension.config.needsApproval,
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .min(1)
+      .describe(
+        "Self-contained task: goal, constraints, and what done looks like."
+      ),
+    repo: z
+      .string()
+      .url()
+      .optional()
+      .describe(
+        "GitHub repository URL, one of the configured repositories. Defaults to the configured repository."
+      ),
+    ref: z.string().optional().describe("Starting branch or commit."),
+    prUrl: z
+      .string()
+      .url()
+      .optional()
+      .describe("Work on this pull request's branch instead of a new one."),
+    name: z
+      .string()
+      .max(100)
+      .optional()
+      .describe("Display name; derived from the prompt when omitted."),
+  }),
+  async execute(input, ctx) {
+    const { cloud } = extension.config;
+    const key = apiKey();
+    const agent = await Agent.create({
+      apiKey: key,
+      model: modelSelection(),
+      name: input.name,
+      cloud: { ...cloud, repos: launchRepos(input, cloud) },
+    });
+    try {
+      const run = await agent.send(input.prompt);
+      await recordLaunch(ctx, agent.agentId, input.name);
+      return {
+        agentId: agent.agentId,
+        runId: run.id,
+        status: run.status,
+        url: agentUrl(agent.agentId),
+      };
+    } catch (error) {
+      // The API can fail after the agent exists (slow admission,
+      // post-create checks). The SDK seeded the id unless envVars made
+      // the server mint it, so read the agent back and keep the handle;
+      // envVars launches have no id to read back and surface the error.
+      const info =
+        cloud.envVars === undefined
+          ? await Agent.get(agent.agentId, { apiKey: key }).catch(
+              () => undefined
+            )
+          : undefined;
+      if (info === undefined) {
+        throw error;
+      }
+      await recordLaunch(ctx, info.agentId, input.name);
+      return {
+        ...agentView(info),
+        launchError: error instanceof Error ? error.message : String(error),
+      };
+    } finally {
+      agent.close();
+    }
+  },
+});
+
+export default launch;

package/src/extensions/cursor-cloud-agents/tools/list.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { agentUrl } from "../lib/cloud.js";
+import { listFleet } from "../lib/fleet.js";
+
+const list: ToolDefinition = defineTool({
+  description:
+    'List the cloud agents launched in this session, newest first. Pass scope "all" for every agent you launched, in any session.',
+  effect: "read",
+  inputSchema: z.object({
+    scope: z
+      .enum(["session", "all"])
+      .default("session")
+      .describe(
+        "session: agents this session launched; all: every agent launched by you, in any session."
+      ),
+    limit: z.number().int().min(1).max(100).default(20),
+  }),
+  async execute(input, ctx) {
+    const fleet = await listFleet(ctx, input.scope);
+    return {
+      sessionId: ctx.session.id,
+      agents: fleet
+        .slice(0, input.limit)
+        .map((entry) => ({ ...entry, url: agentUrl(entry.agentId) })),
+    };
+  },
+});
+
+export default list;

package/src/extensions/cursor-cloud-agents/tools/status.ts

@@ -0,0 +1,39 @@
+import { Agent } from "@cursor/sdk";
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { agentRef, agentView, apiKey, runView } from "../lib/cloud.js";
+import { assertOwned } from "../lib/fleet.js";
+
+const status: ToolDefinition = defineTool({
+  description:
+    "Read a cloud agent you launched and its latest run: state, final result text, error, and pushed branches or pull requests.",
+  effect: "read",
+  inputSchema: agentRef.extend({
+    runId: z
+      .string()
+      .optional()
+      .describe("A specific run; defaults to the latest."),
+  }),
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agentId);
+    const key = apiKey();
+    const cloud = { runtime: "cloud", apiKey: key } as const;
+    const info = await Agent.get(input.agentId, { apiKey: key });
+    // The run list carries no result text; fetch the run itself.
+    const runId =
+      input.runId ??
+      (await Agent.listRuns(input.agentId, { ...cloud, limit: 1 })).items[0]
+        ?.id;
+    const run =
+      runId === undefined
+        ? undefined
+        : await Agent.getRun(runId, { ...cloud, agentId: input.agentId });
+    return {
+      ...agentView(info),
+      run: run === undefined ? undefined : runView(run),
+    };
+  },
+});
+
+export default status;

package/src/extensions.ts

@@ -0,0 +1,98 @@
+/**
+ * Extensions — agent-shaped trees an agent mounts under a namespace.
+ *
+ * An extension is a directory laid out like `agent/`: `extension.ts`
+ * declares it, `tools/<name>.ts` and `skills/<name>.md|ts` are its
+ * contributions, `lib/` holds shared code.
+ *
+ * ```ts
+ * // extension.ts
+ * import { defineExtension } from "@cursor/july/extensions";
+ * import { z } from "zod";
+ *
+ * export default defineExtension({
+ *   root: import.meta.dirname,
+ *   description: "CRM lookups.",
+ *   config: z.object({ apiKey: z.string() }),
+ * });
+ *
+ * // tools/search.ts
+ * import extension from "../extension.js";
+ *
+ * export default defineTool({
+ *   description: "Search the CRM.",
+ *   execute: (input) => search(extension.config.apiKey, input),
+ * });
+ * ```
+ *
+ * A consumer mounts it from `agent/extensions/<ns>.ts`; the filename is the
+ * namespace, and every contribution is exposed as `<ns>__<name>`
+ * (`crm__search`). `__` is reserved for that: an authored `agent/tools/` or
+ * `agent/skills/` name may not contain it.
+ *
+ * ```ts
+ * // agent/extensions/crm.ts
+ * import crm from "@acme/crm";
+ *
+ * export default crm({ apiKey: process.env.CRM_API_KEY! });
+ * ```
+ *
+ * To adjust a contribution, mount as a directory instead and overlay the
+ * slot: `agent/extensions/crm/extension.ts` holds the mount, and
+ * `agent/extensions/crm/tools/search.ts` replaces `crm__search` — or removes
+ * it with `export default disableTool()`.
+ */
+
+import { brandDefinition } from "./internal/brand.js";
+import type {
+  DisabledToolDefinition,
+  Extension,
+  ExtensionMount,
+  ExtensionOptions,
+} from "./types.js";
+
+export type {
+  DisabledToolDefinition,
+  DiscoveredExtension,
+  Extension,
+  ExtensionDeclaration,
+  ExtensionMount,
+  ExtensionOptions,
+} from "./types.js";
+
+export function defineExtension<TConfig = undefined, TInput = TConfig>(
+  options: ExtensionOptions<TConfig, TInput>
+): Extension<TConfig, TInput> {
+  let mounted: { config: TConfig } | undefined;
+  const mount = (config?: TInput): ExtensionMount => {
+    const parsed =
+      options.config === undefined
+        ? (config as unknown as TConfig)
+        : options.config.parse(config);
+    mounted = { config: parsed };
+    return brandDefinition("extension", {
+      extension: handle,
+      config: parsed,
+    });
+  };
+  const handle = Object.defineProperties(mount, {
+    root: { value: options.root, enumerable: true },
+    description: { value: options.description, enumerable: true },
+    config: {
+      enumerable: true,
+      get(): TConfig {
+        if (mounted === undefined) {
+          throw new Error(
+            `Extension at ${options.root} read its config before an agent mounted it. Mount it from agent/extensions/<ns>.ts; the mount runs before the tree loads.`
+          );
+        }
+        return mounted.config;
+      },
+    },
+  }) as unknown as Extension<TConfig, TInput>;
+  return handle;
+}
+
+export function disableTool(): DisabledToolDefinition {
+  return brandDefinition("disabled-tool", {});
+}

package/src/files-backends/cursor-hosted.ts

@@ -51,6 +51,10 @@ import {
   type FileSinkEntry,
   type FileSinkPutResult,
 } from "../files.js";
+import {
+  resolveDeploymentStoreSourceIdSync,
+  resolveFrameworkStoreSourceIdSync,
+} from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
 /**
@@ -111,8 +115,7 @@ const MAX_LIST_WALK_PAGES = 1_000;
 export function isCursorHostedFilesAvailable(
   env: NodeJS.ProcessEnv = process.env
 ): boolean {
-  const sourceId = env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]?.trim();
-  return sourceId !== undefined && sourceId !== "";
+  return resolveDeploymentStoreSourceIdSync(env) !== undefined;
 }
 
 /**
@@ -125,8 +128,7 @@ export function isCursorHostedFilesAvailable(
 export function cursorFrameworkStoreSourceId(
   env: NodeJS.ProcessEnv = process.env
 ): string | undefined {
-  const sourceId = env[AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR]?.trim();
-  return sourceId === undefined || sourceId === "" ? undefined : sourceId;
+  return resolveFrameworkStoreSourceIdSync(env);
 }
 
 /**
@@ -164,6 +166,12 @@ export interface CursorHostedFilesOptions {
   resolveApiKey?: () => string | undefined;
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
+  /**
+   * Lazy store source id, re-resolved on every call and preferred over
+   * {@link storeSourceId} — freeze bind drops ids into `/run/cursor/secrets`
+   * after serve start without restarting July.
+   */
+  resolveStoreSourceId?: () => string | undefined;
   /** Test seam; defaults to global fetch. */
   fetch?: typeof fetch;
 }
@@ -650,7 +658,9 @@ function fetchImpl(options: CursorHostedFilesOptions): typeof fetch {
  */
 function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
   const id = (
-    options.storeSourceId ?? process.env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]
+    options.resolveStoreSourceId?.() ??
+    options.storeSourceId ??
+    resolveDeploymentStoreSourceIdSync(process.env)
   )?.trim();
   if (id === undefined || id === "") {
     throw new Error(

package/src/index.ts

@@ -78,6 +78,7 @@ export {
   stampMailboxContinuation,
   V2EngineError,
 } from "./continuation.js";
+export { defineExtension, disableTool } from "./extensions.js";
 export { defineHook } from "./hooks.js";
 export {
   InvalidAsOfError,
@@ -189,6 +190,7 @@ export {
   isToolEffect,
   MAX_RUNNING_TURNS_LIMIT,
   normalizeConnectionEffects,
+  normalizeConnectionTools,
   normalizeCursorAccountServers,
   supportsKvCas,
 } from "./types.js";