@cursor/july 0.1.101 → 0.1.102

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

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+import {
+  lastAssistantText,
+  transcriptLines,
+  transcriptPath,
+} from "../lib/transcript.js";
+
+const dump: ToolDefinition = defineTool({
+  description:
+    "Write a cloud agent's full conversation to a JSONL file in your workspace so you can read what it did: one JSON message per line (prompts, assistant text, thinking, tool calls). Read the last line for the final report.",
+  effect: "read",
+  inputSchema: agentRef,
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agent_id);
+    const backend = cloudAgentsBackend();
+    const [messages, info] = await Promise.all([
+      backend.conversation(input.agent_id),
+      backend.info(input.agent_id),
+    ]);
+    if (messages.length === 0) {
+      return {
+        agentId: input.agent_id,
+        lineCount: 0,
+        status: info.status,
+        note: "The agent has not produced any transcript yet.",
+      };
+    }
+    // Absolute: the harness's shell does not run in the workspace directory.
+    const path = join(ctx.workspaceDir, transcriptPath(input.agent_id));
+    const jsonl = `${transcriptLines(messages).join("\n")}\n`;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, jsonl, "utf8");
+    return {
+      agentId: input.agent_id,
+      path,
+      sizeBytes: Buffer.byteLength(jsonl),
+      lineCount: messages.length,
+      status: info.status,
+      finalMessage: lastAssistantText(messages),
+      note: `One JSON message per line. Grep it, or read the final report with \`tail -n 1 ${path}\`.`,
+    };
+  },
+});
+
+export default dump;

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

@@ -0,0 +1,18 @@
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+
+const get: ToolDefinition = defineTool({
+  description:
+    "Look up a cloud agent you launched by id: its status, branch, pull request, changed-file counts, summary, and any error. Use dump to read everything it did.",
+  effect: "read",
+  inputSchema: agentRef,
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agent_id);
+    return cloudAgentsBackend().info(input.agent_id);
+  },
+});
+
+export default get;

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

@@ -1,15 +1,14 @@
-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 { cloudAgentsBackend } from "../lib/backend.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.",
+    "Launch a Cursor cloud agent on a repository with a self-contained task. Returns the agent id and URL; check on it with get, read what it did with dump.",
   effect: "write",
   needsApproval: () => extension.config.needsApproval,
   inputSchema: z.object({
@@ -26,8 +25,13 @@ const launch: ToolDefinition = defineTool({
       .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
+    starting_ref: z
+      .string()
+      .optional()
+      .describe(
+        "Branch or commit to start from; defaults to the configured or default branch."
+      ),
+    pr_url: z
       .string()
       .url()
       .optional()
@@ -39,45 +43,21 @@ const launch: ToolDefinition = defineTool({
       .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(),
+    const { cloud, model } = extension.config;
+    const launched = await cloudAgentsBackend().launch({
+      prompt: input.prompt,
       name: input.name,
-      cloud: { ...cloud, repos: launchRepos(input, cloud) },
+      model,
+      cloud: {
+        ...cloud,
+        repos: launchRepos(
+          { repo: input.repo, ref: input.starting_ref, prUrl: input.pr_url },
+          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();
-    }
+    await recordLaunch(ctx, launched.agentId, input.name);
+    return launched;
   },
 });
 

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
-import { agentUrl } from "../lib/cloud.js";
+import { agentUrl } from "../lib/backend.js";
 import { listFleet } from "../lib/fleet.js";
 
 const list: ToolDefinition = defineTool({

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

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { defineTool } from "../../../tools.js";
+import type { ToolDefinition } from "../../../types.js";
+import extension from "../extension.js";
+import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertOwned } from "../lib/fleet.js";
+import { agentRef } from "../lib/inputs.js";
+
+const reply: ToolDefinition = defineTool({
+  description:
+    "Send a follow-up prompt to a cloud agent you launched. It queues behind the current run; pass interrupt to stop that run's current step and deliver it now.",
+  effect: "write",
+  needsApproval: () => extension.config.needsApproval,
+  inputSchema: agentRef.extend({
+    prompt: z.string().min(1).describe("The follow-up instruction."),
+    interrupt: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Deliver now, cancelling the in-flight step, instead of waiting for the current run to finish."
+      ),
+  }),
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agent_id);
+    const { runId } = await cloudAgentsBackend().followUp(
+      input.agent_id,
+      input.prompt,
+      input.interrupt
+    );
+    return { agentId: input.agent_id, runId, queued: !input.interrupt };
+  },
+});
+
+export default reply;

package/src/extensions.ts

@@ -12,39 +12,63 @@
  *
  * export default defineExtension({
  *   root: import.meta.dirname,
- *   description: "CRM lookups.",
- *   config: z.object({ apiKey: z.string() }),
+ *   description: "Investigate failing CI builds.",
+ *   config: z.object({ org: z.string(), token: z.string() }),
  * });
  *
- * // tools/search.ts
+ * // tools/failed_jobs.ts
  * import extension from "../extension.js";
  *
  * export default defineTool({
- *   description: "Search the CRM.",
- *   execute: (input) => search(extension.config.apiKey, input),
+ *   description: "List the failed jobs of a build.",
+ *   execute: (input) => failedJobs(extension.config, 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.
+ * (`ci__failed_jobs`). `__` 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";
+ * // agent/extensions/ci.ts
+ * import ci from "@acme/ci-triage";
  *
- * export default crm({ apiKey: process.env.CRM_API_KEY! });
+ * export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
  * ```
  *
  * 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
+ * slot: `agent/extensions/ci/extension.ts` holds the mount, and
+ * `agent/extensions/ci/tools/job_log.ts` replaces `ci__job_log` — or removes
  * it with `export default disableTool()`.
+ *
+ * A Cursor plugin (the marketplace format: `.cursor-plugin/plugin.json`,
+ * `skills/`, `commands/`, `agents/`, `mcp.json`) mounts the same way with
+ * `cursorPlugin`. Its skills and commands become `<ns>__<name>` skills, its
+ * agents `<ns>__<name>` subagents, and its MCP servers `<ns>__<server>`
+ * connections. Rules and hooks are not mounted yet.
+ *
+ * ```ts
+ * // agent/extensions/notion.ts
+ * import { cursorPlugin } from "@cursor/july/extensions";
+ *
+ * export default cursorPlugin({
+ *   path: "plugins/notion-workspace",
+ *   variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
+ * });
+ * ```
+ *
+ * A directory mount overlays its MCP servers too:
+ * `agent/extensions/notion/mcp-connections/notion.ts` replaces
+ * `notion__notion` with your own `defineConnection` (headers, `oauth`,
+ * `advertiseTools`), and `export default disableConnection()` drops a server
+ * the agent should not carry.
  */
 
 import { brandDefinition } from "./internal/brand.js";
 import type {
+  CursorPluginOptions,
+  DisabledConnectionDefinition,
   DisabledToolDefinition,
   Extension,
   ExtensionMount,
@@ -52,6 +76,9 @@ import type {
 } from "./types.js";
 
 export type {
+  CursorPluginDeclaration,
+  CursorPluginOptions,
+  DisabledConnectionDefinition,
   DisabledToolDefinition,
   DiscoveredExtension,
   Extension,
@@ -96,3 +123,19 @@ export function defineExtension<TConfig = undefined, TInput = TConfig>(
 export function disableTool(): DisabledToolDefinition {
   return brandDefinition("disabled-tool", {});
 }
+
+export function disableConnection(): DisabledConnectionDefinition {
+  return brandDefinition("disabled-connection", {});
+}
+
+export function cursorPlugin(options: CursorPluginOptions): ExtensionMount {
+  return brandDefinition("extension", {
+    extension: {
+      root: options.path,
+      description: undefined,
+      layout: "cursor-plugin",
+      variables: options.variables ?? {},
+    },
+    config: undefined,
+  });
+}

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

@@ -51,10 +51,7 @@ import {
   type FileSinkEntry,
   type FileSinkPutResult,
 } from "../files.js";
-import {
-  resolveDeploymentStoreSourceIdSync,
-  resolveFrameworkStoreSourceIdSync,
-} from "../internal/cursor/hosted-store-secrets.js";
+import { resolveDeploymentStoreSourceIdSync } from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
 /**
@@ -118,19 +115,6 @@ export function isCursorHostedFilesAvailable(
   return resolveDeploymentStoreSourceIdSync(env) !== undefined;
 }
 
-/**
- * The framework-level store's source id, or `undefined` when the deployment
- * has none (v1, self-hosted, or a v2 deploy predating framework-store
- * provisioning). Same detection posture as
- * {@link isCursorHostedFilesAvailable}: keyed on the id alone — a missing
- * credential must fail loudly at use, not silently deselect the store.
- */
-export function cursorFrameworkStoreSourceId(
-  env: NodeJS.ProcessEnv = process.env
-): string | undefined {
-  return resolveFrameworkStoreSourceIdSync(env);
-}
-
 /**
  * Local `serve`/`run` with a personal `CURSOR_API_KEY` can address
  * `/v0/agent-serve-files/user`. Hosted deployments have a store source id

package/src/files.ts

@@ -23,7 +23,7 @@
  * know the write did not land.
  */
 
-import { STORAGE_KEY_ROOT } from "./storage.js";
+import { AGENTSDK_STORAGE_KEY_ROOT, STORAGE_KEY_ROOT } from "./storage.js";
 
 // ============================================================================
 // Sink interface
@@ -163,39 +163,48 @@ export const AGENT_SERVE_USER_STORE_KEY_PREFIX = "agent-serve";
  * `--agent-store-skills-dir` walk finds them the same way it finds user-store
  * skills. Memory and artifacts stay under {@link STORAGE_KEY_ROOT}.
  */
-export const agentStoreKeys = {
-  artifactRow: (agent: string, id: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/rows/${encodeURIComponent(id)}.json`,
-  artifactRowPrefix: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/rows/`,
-  artifactContent: (agent: string, id: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/artifacts/content/${encodeURIComponent(id)}`,
-  skillFile: (
-    skillName: string,
-    relPath: string,
-    skillsPrefix: string = "skills/"
-  ): string => `${skillsPrefix}${skillName}/${relPath}`,
-  skillsPrefix: (): string => "skills/",
-  /** Personal-key cloud agents: namespaced so they cannot collide with the user's own `skills/`. */
-  userSkillsPrefix: (agent: string): string =>
-    `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/skills/`,
-  memoryDir: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/memory`,
-  memoryJournal: (agent: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/memory/journal.jsonl`,
-  memoryJournalRotated: (agent: string, stamp: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/memory/journal-${stamp}.jsonl`,
-  // SDK conversation mirror (the runner's SQLite store, exported through the
-  // store APIs): one manifest per SDK agent id plus its content-addressed
-  // checkpoint blobs. See internal/conversation-mirror.ts.
-  conversationManifest: (agent: string, sdkAgentId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/manifest.json`,
-  conversationBlob: (
-    agent: string,
-    sdkAgentId: string,
-    blobId: string
-  ): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/blobs/${encodeURIComponent(blobId)}`,
-} as const;
+function createAgentStoreKeys(root: string) {
+  return {
+    artifactRow: (agent: string, id: string): string =>
+      `${root}/${agent}/artifacts/rows/${encodeURIComponent(id)}.json`,
+    artifactRowPrefix: (agent: string): string =>
+      `${root}/${agent}/artifacts/rows/`,
+    artifactContent: (agent: string, id: string): string =>
+      `${root}/${agent}/artifacts/content/${encodeURIComponent(id)}`,
+    skillFile: (
+      skillName: string,
+      relPath: string,
+      skillsPrefix: string = "skills/"
+    ): string => `${skillsPrefix}${skillName}/${relPath}`,
+    skillsPrefix: (): string => "skills/",
+    /** Personal-key cloud agents: namespaced so they cannot collide with the user's own `skills/`. */
+    userSkillsPrefix: (agent: string): string =>
+      `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/skills/`,
+    memoryDir: (agent: string): string => `${root}/${agent}/memory`,
+    memoryJournal: (agent: string): string =>
+      `${root}/${agent}/memory/journal.jsonl`,
+    memoryJournalRotated: (agent: string, stamp: string): string =>
+      `${root}/${agent}/memory/journal-${stamp}.jsonl`,
+    // SDK conversation mirror (the runner's SQLite store, exported through the
+    // store APIs): one manifest per SDK agent id plus its content-addressed
+    // checkpoint blobs. See internal/conversation-mirror.ts.
+    conversationManifest: (agent: string, sdkAgentId: string): string =>
+      `${root}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/manifest.json`,
+    conversationBlob: (
+      agent: string,
+      sdkAgentId: string,
+      blobId: string
+    ): string =>
+      `${root}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/blobs/${encodeURIComponent(blobId)}`,
+  } as const;
+}
+
+export type AgentStoreKeys = ReturnType<typeof createAgentStoreKeys>;
+export const agentStoreKeys: AgentStoreKeys =
+  createAgentStoreKeys(STORAGE_KEY_ROOT);
+export const agentSdkAgentStoreKeys: AgentStoreKeys = createAgentStoreKeys(
+  AGENTSDK_STORAGE_KEY_ROOT
+);
 
 /**
  * Deployment store FUSE mount on cloud-runtime VMs. Mirrors

package/src/index.ts

@@ -78,7 +78,12 @@ export {
   stampMailboxContinuation,
   V2EngineError,
 } from "./continuation.js";
-export { defineExtension, disableTool } from "./extensions.js";
+export {
+  cursorPlugin,
+  defineExtension,
+  disableConnection,
+  disableTool,
+} from "./extensions.js";
 export { defineHook } from "./hooks.js";
 export {
   InvalidAsOfError,
@@ -167,15 +172,19 @@ export type {
   StorageDefinition,
   StorageEntry,
   StorageEvalsTable,
+  StorageKeys,
   StoragePolicy,
   StorageRestorePolicy,
 } from "./storage.js";
 export {
+  AGENTSDK_STORAGE_KEY_ROOT,
+  agentSdkStorageKeys,
   defineStorage,
   isDurableSessionRecordKey,
   parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  storageKeysForArchitecture,
   summarizeDurableSessionRecord,
 } from "./storage.js";
 export { defineTool } from "./tools.js";

package/src/internal/conversation-mirror.ts

@@ -37,16 +37,13 @@
  */
 
 import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
-import { agentStoreKeys, type FileSink } from "../files.js";
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
+import { agentSdkAgentStoreKeys, type FileSink } from "../files.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import type { AgentProject } from "../types.js";
 import { mapBounded } from "./bounded.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import { describeError } from "./describe-error.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 /**
  * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
@@ -70,7 +67,7 @@ export interface ConversationMirror {
   persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
 }
 
-/** Wire shape at {@link agentStoreKeys.conversationManifest}. */
+/** Wire shape at {@link agentSdkAgentStoreKeys.conversationManifest}. */
 interface ConversationManifestV1 {
   v: 1;
   /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
@@ -181,7 +178,11 @@ export function createConversationMirror(
             continue;
           }
           await sink.put(
-            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+            agentSdkAgentStoreKeys.conversationBlob(
+              agentName,
+              sdkAgentId,
+              blobId
+            ),
             bytes
           );
           // Content-addressed: once in the sink, never re-uploaded.
@@ -197,7 +198,7 @@ export function createConversationMirror(
         };
         // Manifest last: it only ever references blobs already uploaded.
         await sink.put(
-          agentStoreKeys.conversationManifest(agentName, sdkAgentId),
+          agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId),
           new TextEncoder().encode(JSON.stringify(manifest))
         );
       });
@@ -242,7 +243,11 @@ export function createConversationMirror(
           async (blobId) => ({
             blobId,
             body: await sink.get(
-              agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)
+              agentSdkAgentStoreKeys.conversationBlob(
+                agentName,
+                sdkAgentId,
+                blobId
+              )
             ),
           })
         );
@@ -317,7 +322,7 @@ async function readManifest(
   sdkAgentId: string
 ): Promise<ManifestRead> {
   const body = await sink.get(
-    agentStoreKeys.conversationManifest(agentName, sdkAgentId)
+    agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId)
   );
   if (body === undefined) {
     return { outcome: "miss" };
@@ -379,17 +384,17 @@ export function selectConversationMirror(input: {
   logger?: (line: string) => void;
   env?: Record<string, string | undefined>;
 }): ConversationMirror | undefined {
-  if (input.project.agent.architecture !== "v2") {
-    return undefined;
-  }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.project.agent.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     return undefined;
   }
-  const envSnapshot = env as NodeJS.ProcessEnv;
   return createConversationMirror({
     sink: cursorHostedFiles({
-      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveStoreSourceId: () =>
+        hosting.resolveStoreIds().frameworkStoreSourceId,
       // Full chain (env → key file → stored login): frozen engines listen
       // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
       // is constructed.