@cursor/july 0.1.101 → 0.1.103

package/docs/guides/cloud-runtime.md

@@ -1,120 +0,0 @@
----
-title: "Cloud runtime"
-description: "Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."
----
-
-# Cloud runtime
-
-By default, turns execute on the Cursor SDK's local harness, on the same
-machine as the server. Set `runtime: "cloud"` and turns execute on
-Cursor cloud agents instead. They're ephemeral VMs that carry a repo
-checkout, run `gh`, `git`, and tests for real, and scale past what one
-host's disk and CPU can do. The serve host keeps handling routing, host
-preparation, sessions, and bookkeeping.
-
-A canonical use is a PR driver whose triage runs on cloud VMs. The
-patterns in this guide come from running one against real PR traffic.
-
-## When to switch
-
-A guideline from running PR agents at scale: per-PR worktrees on the serve host
-don't scale to hundreds of engineers opening PRs. When the job needs a
-repo checkout at scale, use cloud. The signals:
-
-- The agent must run repo commands (tests, builds, `git`) against many
-  different refs concurrently.
-- Turns are long and heavy, and you don't want them competing with the
-  server for resources.
-- The work product is a PR or branch the VM can push, not a local file.
-
-Stay local when the agent is conversational, tool-driven against APIs,
-or works over host-prepared evidence. Local turns are cheaper, start
-faster, and support the full authored surface.
-
-## Configure it
-
-Cloud runtime is two fields on the agent config.
-
-```ts
-import { defineAgent } from "@cursor/july";
-
-export default defineAgent({
-  runtime: "cloud",
-  cloud: {
-    repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
-    // env / envVars / … forwarded to the Cursor SDK
-  },
-});
-```
-
-The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
-
-> [!IMPORTANT]
-> Cloud agents run against the Cursor backend under the signed-in
-> account, and every wake spends real cloud-agent budget. Decide
-> explicitly what may trigger one.
-
-## What changes on cloud
-
-Cloud turns run on a VM without your authored files, so the runtime
-mapping shifts:
-
-| Folder or file | Local runtime | Cloud runtime |
-| --- | --- | --- |
-| `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
-| Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
-| Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
-| `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
-| `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
-| `host-connections/*.ts` | `ctx.host.mcp` only | `ctx.host.mcp` only |
-| `sandbox/workspace/**` | seeded into the session workspace | ignored |
-| Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
-
-Authored skills are discovered natively after the first cloud turn,
-using the hosted store or the signed-in account.
-
-Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
-call rides one HTTP MCP request from the VM, and a parked call would
-hold that request open until it times out; there is no durable approval
-flow for cloud turns.
-
-Peer MCP connections need `--public-url` for cloud turns. Without one,
-peers are omitted and the server warns at startup.
-
-## Hybrid: local agent, cloud sessions
-
-A local-runtime agent can still open cloud-attached sessions per send.
-Channel handlers may pass a `cloud` block (repos pinned to a PR ref, say)
-in `send` options, and Slack handlers may return `cloud` from a mention
-hook. A PR driver works this way: chat stays local, and the `drive`
-flow attaches the PR to a cloud VM. The agent-level `cloud` config is the
-base that per-session options merge over.
-
-## Patterns that hold up
-
-These come from running a PR driver against real PR traffic:
-
-- One cloud session per unit of work, keyed with a stable continuation
-  token (`pr:owner/repo#N`) so every wake lands on the same conversation.
-- Keep the host deterministic: fetch briefs and metadata on the host,
-  send the VM a compact prompt, and let the VM re-read source of truth
-  with its own `gh` and `git` instead of trusting payload snapshots.
-- Limit exposure: add repository allowlists on webhook channels,
-  because every wake spends the account's budget.
-
-## Verify cloud agents
-
-`agent-sdk run` and `eval` work unchanged. The trajectory records the
-same event vocabulary plus `agent.bound` with the cloud URL, so you can
-open the cloud conversation for any session. Cloud turns take minutes.
-Pass generous `--timeout-ms` values, and keep curl timeouts long when
-driving channels directly.
-
-## What's next
-
-Continue with these pages:
-
-- [Agent config](../reference/agent-config.md): the `runtime` and
-  `cloud` fields
-- [GitHub guide](./github.md): the webhook patterns that pair with
-  cloud triage

package/src/continuation.ts

@@ -1,49 +0,0 @@
-/**
- * Public continuation-identity surface for `@cursor/july`.
- *
- * Omitted `continuation` on a channel constructor stays `/v1` (engine
- * minting). Deploy onto the v2 control plane with a root architecture
- * flag; omitted channels then inherit the kind `/v2` default:
- *
- * ```ts
- * export default defineAgent({
- *   architecture: "v2",
- * });
- * ```
- *
- * Per-channel selectors still override type (`"github.issue/v2"`,
- * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
- * `"origin.pr/v2"`, `"deployments.deployment/v2"`, `"none/v2"`.
- */
-
-export type {
-  ContinuationBuiltin,
-  ContinuationClaim,
-  ContinuationIdentity,
-  ContinuationProtocolVersion,
-  ContinuationSelector,
-  ConversationType,
-  MailboxContinuation,
-  ParsedContinuation,
-} from "./internal/continuation-identity.js";
-export {
-  BUILTINS,
-  bindMailboxContinuationSend,
-  builtinForType,
-  CONTINUATION_SELECTORS,
-  continuationSource,
-  defaultContinuationSelector,
-  extractContinuation,
-  formatConversationKey,
-  handshakeContinuation,
-  isContinuationSelector,
-  isV2DurableContinuationKey,
-  mintClaim,
-  newEvtKey,
-  normalizeIdentity,
-  parseContinuationSelector,
-  resolveContinuation,
-  resolveV2Key,
-  stampMailboxContinuation,
-  V2EngineError,
-} from "./internal/continuation-identity.js";

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

@@ -1,79 +0,0 @@
-/** 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/tools/follow_up.ts

@@ -1,29 +0,0 @@
-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/status.ts

@@ -1,39 +0,0 @@
-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/internal/convert-automation/index.ts

@@ -1,10 +0,0 @@
-export { convertWorkflow } from "./convert-workflow.js";
-export type {
-  ConvertAutomationMetadata,
-  ConvertedFile,
-  ConvertedMcpConnection,
-  ConvertMcpServer,
-  ConvertWorkflowInput,
-  ConvertWorkflowResult,
-  WorkflowJson,
-} from "./types.js";

package/src/internal/grokbot/runner.ts

@@ -1,370 +0,0 @@
-/**
- * The grokbot runtime's remote client — a thin client like `"cloud"`.
- * Turns execute on Cursor's hosted Grok Bot (Sand) harness (the Temporal
- * turn workflow and the account's own computer), reached through the
- * public `/v0/grokbot` session API.
- *
- * Sand delivery contract, preserved end to end: only content the agent
- * delivers through SendToUser becomes the user-visible reply. The hosted
- * transcript exposes those deliveries as `send-message` entries; the
- * agent's internal monologue never appears in the transcript, so it can
- * never leak into the session reply.
- */
-
-import { randomUUID } from "node:crypto";
-import type { RunnerTurnRequest, TurnOutcome } from "../../types.js";
-import {
-  cursorExternalApiUrl,
-  resolveApiKeySync,
-} from "../cursor/credentials.js";
-import type { AgentRunner } from "./../sdk-runner.js";
-
-export interface GrokBotRunnerOptions {
-  /** Cursor API key. Resolved as option → env → file → stored login. */
-  apiKey?: string;
-  /** Test seam. Defaults to global fetch. */
-  fetchImpl?: typeof fetch;
-  /**
-   * Test seam. Defaults to {@link cursorExternalApiUrl} (`api.cursor.com`).
-   * `/v0/grokbot` is an external-api microlith route — it 404s on api2.
-   */
-  backendUrl?: string;
-  /** Test seam. Poll interval while a turn runs. */
-  pollIntervalMs?: number;
-  /** Test seam. Hard turn deadline. */
-  turnTimeoutMs?: number;
-}
-
-/** One transcript entry as `/v0/grokbot/sessions/:id/entries` exposes it. */
-export interface GrokBotEntry {
-  seq: string;
-  updatedSeq: string;
-  kind: string;
-  role?: string;
-  text?: string;
-  createdAtMs: number;
-}
-
-interface GrokBotTurnStatus {
-  idle: boolean;
-  inFlight: boolean;
-  queued: number;
-}
-
-interface EntriesPage {
-  entries: GrokBotEntry[];
-  latestUpdatedSeq: string;
-  turn: GrokBotTurnStatus;
-}
-
-interface HostedAgent {
-  /** The `/v0/grokbot` session id (the hosted agent's durable id). */
-  remoteId: string;
-  /** Transcript cursor: newest `updatedSeq` this client has consumed. */
-  lastUpdatedSeq: bigint;
-}
-
-const DEFAULT_POLL_INTERVAL_MS = 750;
-const DEFAULT_TURN_TIMEOUT_MS = 20 * 60 * 1000;
-
-/**
- * Idle polls required after a send before the turn is considered settled
- * when the workflow never reported busy — covers the window between the
- * accepted dispatch and the workflow picking the signal up.
- */
-const MIN_IDLE_POLLS_WITHOUT_BUSY = 4;
-
-class GrokBotApiError extends Error {
-  constructor(
-    readonly status: number,
-    readonly path: string,
-    body: string
-  ) {
-    super(
-      `Grok Bot API ${path} failed (HTTP ${status}): ${body.slice(0, 300)}`
-    );
-    this.name = "GrokBotApiError";
-  }
-}
-
-/** Minimal `/v0/grokbot` client: bearer API key, JSON in/out. */
-class GrokBotApiClient {
-  private readonly fetchImpl: typeof fetch;
-  private readonly baseUrl: string;
-  private readonly apiKey: string;
-
-  constructor(options: GrokBotRunnerOptions) {
-    this.fetchImpl = options.fetchImpl ?? fetch;
-    this.baseUrl = (options.backendUrl ?? cursorExternalApiUrl()).replace(
-      /\/$/,
-      ""
-    );
-    const apiKey = resolveApiKeySync({
-      apiKey: options.apiKey,
-      backendUrl: options.backendUrl,
-    })?.apiKey;
-    if (apiKey === undefined || apiKey === "") {
-      throw new Error(
-        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY, CURSOR_API_KEY_FILE, or agent-sdk login) to reach the hosted Grok Bot harness.'
-      );
-    }
-    this.apiKey = apiKey;
-  }
-
-  private async request<T>(args: {
-    method: string;
-    path: string;
-    body?: unknown;
-  }): Promise<T> {
-    const headers: Record<string, string> = {
-      authorization: `Bearer ${this.apiKey}`,
-    };
-    if (args.body !== undefined) {
-      headers["content-type"] = "application/json";
-    }
-    const response = await this.fetchImpl(`${this.baseUrl}${args.path}`, {
-      method: args.method,
-      headers,
-      body: args.body === undefined ? undefined : JSON.stringify(args.body),
-    });
-    if (!response.ok) {
-      throw new GrokBotApiError(
-        response.status,
-        args.path,
-        await response.text().catch(() => "")
-      );
-    }
-    return (await response.json()) as T;
-  }
-
-  async createSession(args: {
-    name: string;
-    instructions: string | undefined;
-  }): Promise<{ id: string; latestUpdatedSeq: string }> {
-    return await this.request({
-      method: "POST",
-      path: "/v0/grokbot/sessions",
-      body: { name: args.name, instructions: args.instructions },
-    });
-  }
-
-  async sendMessage(args: {
-    sessionId: string;
-    text: string;
-  }): Promise<{ messageId: string; delivery: string }> {
-    return await this.request({
-      method: "POST",
-      path: `/v0/grokbot/sessions/${args.sessionId}/messages`,
-      body: { text: args.text, messageId: randomUUID() },
-    });
-  }
-
-  async listEntries(args: {
-    sessionId: string;
-    afterUpdatedSeq: bigint;
-  }): Promise<EntriesPage> {
-    return await this.request({
-      method: "GET",
-      path: `/v0/grokbot/sessions/${args.sessionId}/entries?afterUpdatedSeq=${args.afterUpdatedSeq}`,
-    });
-  }
-
-  async interrupt(args: { sessionId: string; reason: string }): Promise<void> {
-    await this.request({
-      method: "POST",
-      path: `/v0/grokbot/sessions/${args.sessionId}/interrupt`,
-      body: { reason: args.reason },
-    });
-  }
-}
-
-export class GrokBotRunner implements AgentRunner {
-  /**
-   * One hosted Grok Bot agent per SDK agent name — the backend
-   * get-or-creates by name, so every SDK session forwards into the same
-   * hosted agent and conversation, and the Grok Bot app shows one agent
-   * rather than one per session.
-   */
-  private readonly agents = new Map<string, HostedAgent>();
-  /**
-   * Per-hosted-agent turn chain. Sessions share one hosted conversation
-   * and one transcript cursor, so turns run one at a time per agent:
-   * deliveries attribute to the turn that sent them, and an abort only
-   * interrupts its own turn — mirroring the hosted workflow's own queue.
-   */
-  private readonly turns = new Map<string, Promise<unknown>>();
-  private client: GrokBotApiClient | undefined;
-
-  constructor(private readonly options: GrokBotRunnerOptions = {}) {}
-
-  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
-    if (request.runtime !== "grokbot") {
-      throw new Error(
-        `Session ${request.sessionId} is a ${request.runtime} turn, which the Grok Bot runner cannot execute.`
-      );
-    }
-    if (request.images !== undefined && request.images.length > 0) {
-      // Attachments ride the hosted box's upload path, which the /v0
-      // session API does not expose yet. Refuse rather than silently
-      // dropping what the user attached.
-      throw new Error(
-        "Image attachments are not supported on grokbot turns yet."
-      );
-    }
-    const name = hostedAgentName(request);
-    const previous = this.turns.get(name) ?? Promise.resolve();
-    const run = previous.then(() => this.executeTurn(request));
-    this.turns.set(
-      name,
-      run.catch(() => {})
-    );
-    return await run;
-  }
-
-  private async executeTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
-    const signal = request.signal;
-    if (signal?.aborted === true) {
-      return { status: "cancelled" };
-    }
-    const client = this.ensureClient();
-    const entry = await this.getAgent(client, request);
-
-    const send = await client.sendMessage({
-      sessionId: entry.remoteId,
-      text: request.prompt,
-    });
-    if (
-      send.delivery !== "accepted_temporal" &&
-      send.delivery !== "duplicate"
-    ) {
-      throw new Error(
-        `The hosted Grok Bot harness did not accept the turn (delivery: ${send.delivery}).`
-      );
-    }
-
-    const pollIntervalMs =
-      this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    const turnTimeoutMs = this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
-    const deadline = Date.now() + turnTimeoutMs;
-    const delivered: string[] = [];
-    let sawBusy = false;
-    let idlePolls = 0;
-
-    while (true) {
-      // On abort: interrupt the hosted run, drain entries once so a reply
-      // that already landed still streams out, then cancel.
-      const aborted = isAborted(signal);
-      if (aborted) {
-        await client
-          .interrupt({
-            sessionId: entry.remoteId,
-            reason: "The user sent a new message.",
-          })
-          .catch(() => {});
-      }
-      const page = await client.listEntries({
-        sessionId: entry.remoteId,
-        afterUpdatedSeq: entry.lastUpdatedSeq,
-      });
-      entry.lastUpdatedSeq = BigInt(page.latestUpdatedSeq);
-      for (const item of page.entries) {
-        if (item.kind !== "send-message" || item.text === undefined) {
-          continue;
-        }
-        const delta = delivered.length === 0 ? item.text : `\n\n${item.text}`;
-        delivered.push(item.text);
-        // The emit callback may be async; a rejection must never escape
-        // the poll loop.
-        void Promise.resolve(
-          request.onUpdate({ type: "text-delta", text: delta })
-        ).catch(() => {});
-      }
-      if (aborted) {
-        return { status: "cancelled" };
-      }
-      if (page.turn.inFlight || page.turn.queued > 0) {
-        sawBusy = true;
-      } else if (page.turn.idle) {
-        idlePolls += 1;
-        if (sawBusy || idlePolls >= MIN_IDLE_POLLS_WITHOUT_BUSY) {
-          return {
-            status: "finished",
-            result: delivered.length === 0 ? undefined : delivered.join("\n\n"),
-          };
-        }
-      }
-      if (Date.now() >= deadline) {
-        throw new Error(
-          `The grokbot turn for session ${request.sessionId} did not settle within ${Math.round(turnTimeoutMs / 60_000)} minutes.`
-        );
-      }
-      await this.sleep(pollIntervalMs, signal);
-    }
-  }
-
-  async dispose(): Promise<void> {
-    // Hosted agents live server-side (the account's Grok Bot agents);
-    // nothing in this process holds conversation state.
-    this.agents.clear();
-  }
-
-  private ensureClient(): GrokBotApiClient {
-    this.client ??= new GrokBotApiClient(this.options);
-    return this.client;
-  }
-
-  private async getAgent(
-    client: GrokBotApiClient,
-    request: RunnerTurnRequest
-  ): Promise<HostedAgent> {
-    const name = hostedAgentName(request);
-    const existing = this.agents.get(name);
-    if (existing !== undefined) {
-      return existing;
-    }
-    // Get-or-create: a reconnect (new process, same agent name) lands on
-    // the existing hosted agent. The returned tail seq starts the cursor
-    // after the hosted conversation's history so an old transcript never
-    // replays into this turn's reply.
-    const created = await client.createSession({
-      name,
-      instructions: request.instructions,
-    });
-    const entry: HostedAgent = {
-      remoteId: created.id,
-      lastUpdatedSeq: BigInt(created.latestUpdatedSeq),
-    };
-    this.agents.set(name, entry);
-    return entry;
-  }
-
-  private async sleep(
-    ms: number,
-    signal: AbortSignal | undefined
-  ): Promise<void> {
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(() => {
-        signal?.removeEventListener("abort", onAbort);
-        resolve();
-      }, ms);
-      const onAbort = (): void => {
-        clearTimeout(timer);
-        resolve();
-      };
-      signal?.addEventListener("abort", onAbort, { once: true });
-    });
-  }
-}
-
-function hostedAgentName(request: RunnerTurnRequest): string {
-  return request.agentName ?? "Agent SDK agent";
-}
-
-/**
- * `AbortSignal.aborted` is readonly to TypeScript, so an inline recheck
- * after an await narrows to the stale pre-await value; the function
- * boundary keeps the recheck honest.
- */
-function isAborted(signal: AbortSignal | undefined): boolean {
-  return signal?.aborted === true;
-}