@cursor/july 0.1.101 → 0.1.102

package/src/channels/slack/api.ts

@@ -288,18 +288,20 @@ export async function setThreadTitle(args: {
 export async function setSuggestedPrompts(args: {
   botToken: SlackBotToken | undefined;
   channelId: string;
-  threadTs: string;
+  threadTs?: string;
   prompts: SlackSuggestedPrompt[];
   title?: string;
 }): Promise<SoftSlackResult> {
   const body: Record<string, unknown> = {
     channel_id: args.channelId,
-    thread_ts: args.threadTs,
     prompts: args.prompts.map((p) => ({
       title: p.title,
       message: p.message,
     })),
   };
+  if (args.threadTs !== undefined && args.threadTs !== "") {
+    body.thread_ts = args.threadTs;
+  }
   if (args.title !== undefined && args.title !== "") {
     body.title = args.title;
   }

package/src/channels/slack/assistant.ts

@@ -48,7 +48,7 @@ export async function maybeSetThreadTitle(args: {
 export async function maybeSetSuggestedPrompts(args: {
   botToken: SlackBotToken | undefined;
   channelId: string;
-  threadTs: string;
+  threadTs?: string;
   prompts: SlackSuggestedPrompt[];
   title?: string;
   log?: SlackLog;

package/src/channels/slack/dispatch.ts

@@ -38,6 +38,7 @@ import { isExternalSlackSender } from "./external-policy.js";
 import {
   describeSlackEventShape,
   formatSlackContextBlock,
+  parseAppHomeOpened,
   parseAppMentionEvent,
   parseAssistantThreadStarted,
   parseChannelMessageEvent,
@@ -181,8 +182,9 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    */
   blockExternals?: boolean;
   /**
-   * Suggested prompts written on `assistant_thread_started` so the
-   * assistant pane is not blank before the first user message.
+   * Suggested prompts pinned when a user opens the agent Messages tab
+   * (`app_home_opened`). Older apps still seed them on
+   * `assistant_thread_started`.
    */
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
@@ -766,6 +768,29 @@ export function dispatchInboundFromEventBody(
     return true;
   }
 
+  const home = parseAppHomeOpened(body);
+  if (home !== null) {
+    const prompts = deps.suggestedPrompts ?? [];
+    log.info("app home opened", {
+      channel: home.channelId,
+      tab: home.tab,
+      user: home.userId,
+      event_id: eventId,
+    });
+    if (home.tab === "messages" && prompts.length > 0) {
+      deps.waitUntil(
+        maybeSetSuggestedPrompts({
+          botToken: deps.credentials?.botToken,
+          channelId: home.channelId,
+          prompts,
+          title: deps.suggestedPromptsTitle,
+          log,
+        })
+      );
+    }
+    return true;
+  }
+
   const assistantThread = parseAssistantThreadStarted(body);
   if (assistantThread !== null) {
     const prompts = deps.suggestedPrompts ?? [];

package/src/channels/slack/inbound.ts

@@ -138,6 +138,43 @@ export function parseAppMentionEvent(
   return delegation === undefined ? message : { ...message, delegation };
 }
 
+export interface SlackAppHomeOpened {
+  channelId: string;
+  tab: string;
+  userId?: string;
+  teamId?: string;
+}
+
+/** Slack fires this when a user opens the app Home or Messages tab. */
+export function parseAppHomeOpened(body: unknown): SlackAppHomeOpened | null {
+  const root = asRecord(body);
+  if (root === null || root.type !== "event_callback") {
+    return null;
+  }
+  const event = asRecord(root.event);
+  if (event === null || event.type !== "app_home_opened") {
+    return null;
+  }
+  const channelId = asString(event.channel);
+  const tab = asString(event.tab);
+  if (
+    channelId === undefined ||
+    channelId === "" ||
+    tab === undefined ||
+    tab === ""
+  ) {
+    return null;
+  }
+  const userId = asString(event.user);
+  const teamId = asString(root.team_id) ?? asString(event.team_id);
+  return {
+    channelId,
+    tab,
+    userId: userId === undefined || userId === "" ? undefined : userId,
+    teamId: teamId === undefined || teamId === "" ? undefined : teamId,
+  };
+}
+
 export interface SlackAssistantThreadStarted {
   channelId: string;
   threadTs: string;

package/src/channels/slack/manifest.ts

@@ -84,7 +84,8 @@ const BOT_SCOPES = [
 const BOT_EVENTS = [
   "app_mention",
   "message.im",
-  "assistant_thread_started",
+  // agent_view DMs: Slack no longer fires assistant_thread_started.
+  "app_home_opened",
 ] as const;
 
 /** Slack's display_information.description bound. */

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

@@ -11,13 +11,15 @@
  * });
  * ```
  *
- * Contributes `cloud__launch`, `cloud__follow_up`, `cloud__status`,
- * `cloud__list` and the `cloud__handoff` skill (the namespace is the mount
- * filename). Calls go through the Cursor SDK with the serve host's Cursor
- * API key (`CURSOR_API_KEY`, key file, or `login`); each launched agent
- * stays bound to the principal that launched it, and launches go to the
- * configured repositories. The tools run on the serve host, so they need
- * the local runtime.
+ * Contributes `cloud__launch`, `cloud__get`, `cloud__dump`, `cloud__reply`,
+ * `cloud__cancel`, `cloud__list` and the `cloud__handoff` skill (the
+ * namespace is the mount filename), the action vocabulary Sand's CloudAgent
+ * tool uses, over the same backend calls: launches through the v1 Cloud
+ * Agents API, everything else through the BackgroundComposerService RPCs,
+ * all under the serve host's Cursor API key (`CURSOR_API_KEY`, key file, or
+ * `login`). Each launched agent stays bound to the principal that launched
+ * it, and launches go to the configured repositories. The tools run on the
+ * serve host, so they need the local runtime.
  */
 
 import { z } from "zod";

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

@@ -0,0 +1,395 @@
+/**
+ * The Cursor backend as the tools use it: launches go through the public
+ * v1 Cloud Agents API (the only surface that takes per-launch `envVars`),
+ * everything about an existing agent goes through the same
+ * `aiserver.v1.BackgroundComposerService` RPCs Sand's CloudAgent tool
+ * calls, so follow-ups queue, runs pause, and the full conversation is
+ * readable. Both authenticate with the host's Cursor API key; the RPCs
+ * exchange it for a session token the way the dashboard client does.
+ */
+
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { CursorBackendClient } from "../../../internal/cursor/backend-client.js";
+import {
+  cursorBackendUrl,
+  cursorExternalApiUrl,
+  cursorWebsiteUrl,
+  resolveApiKeySync,
+  SIGN_IN_HINT,
+} from "../../../internal/cursor/credentials.js";
+import { toModelSelection } from "../../../internal/sdk-runner.js";
+import type { AgentCloudOptions, ModelSetting } from "../../../types.js";
+import extension from "../extension.js";
+
+const SERVICE = "BackgroundComposerService";
+/** Launches and follow-ups from this extension carry the SDK source, like the v1 API. */
+const SOURCE = "BACKGROUND_COMPOSER_SOURCE_SDK";
+const RPC_TIMEOUT_MS = 60_000;
+// The create call returns once the initial run exists, which can wait on a VM.
+const LAUNCH_TIMEOUT_MS = 300_000;
+
+export class CloudAgentsApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number
+  ) {
+    super(message);
+    this.name = "CloudAgentsApiError";
+  }
+}
+
+export type CloudAgentStatus =
+  | "creating"
+  | "running"
+  | "finished"
+  | "error"
+  | "expired"
+  | "unknown";
+
+// Type aliases, not interfaces: these flow into tool results.
+export type CloudAgentInfo = {
+  agentId: string;
+  name: string;
+  status: CloudAgentStatus;
+  archived: boolean;
+  url: string;
+  branch?: string;
+  prUrl?: string;
+  summary?: string;
+  error?: string;
+  changes?: { filesChanged: number; linesAdded: number; linesRemoved: number };
+};
+
+export type CloudAgentToolCall = {
+  name: string;
+  args: unknown;
+  content?: string;
+  error?: string;
+};
+
+export type CloudAgentMessage = {
+  role: "user" | "assistant";
+  text?: string;
+  thinking?: string;
+  toolCalls?: CloudAgentToolCall[];
+};
+
+export type CloudAgentLaunch = {
+  agentId: string;
+  runId: string;
+  status: string;
+  url: string;
+};
+
+export type LaunchRequest = {
+  prompt: string;
+  name?: string;
+  cloud: AgentCloudOptions;
+  model?: ModelSetting;
+};
+
+// ---------------------------------------------------------------------------
+// Proto-JSON response schemas (camelCase; default-valued fields are omitted)
+// ---------------------------------------------------------------------------
+
+const composerSchema = z.object({
+  bcId: z.string(),
+  name: z.string().optional(),
+  status: z.string().optional(),
+  isArchived: z.boolean().optional(),
+  branchName: z.string().optional(),
+  prUrl: z.string().optional(),
+  linesAdded: z.number().optional(),
+  linesRemoved: z.number().optional(),
+  filesChanged: z.number().optional(),
+});
+
+const errorDetailsSchema = z.object({
+  details: z
+    .object({ title: z.string().optional(), detail: z.string().optional() })
+    .optional(),
+});
+
+const infoResponseSchema = z.object({
+  composer: z.object({
+    composer: composerSchema,
+    summary: z.string().optional(),
+    startError: errorDetailsSchema.optional(),
+    permanentError: errorDetailsSchema.optional(),
+  }),
+});
+
+const toolResultSchema = z.object({
+  toolName: z.string().optional(),
+  args: z.string().optional(),
+  rawArgs: z.string().optional(),
+  content: z.string().optional(),
+  error: z
+    .object({ clientVisibleErrorMessage: z.string().optional() })
+    .optional(),
+});
+
+const conversationResponseSchema = z.object({
+  conversation: z
+    .array(
+      z.object({
+        type: z.string().optional(),
+        text: z.string().optional(),
+        thinking: z.object({ text: z.string().optional() }).optional(),
+        toolResults: z.array(toolResultSchema).optional(),
+      })
+    )
+    .optional(),
+});
+
+const followupResponseSchema = z.object({ runId: z.string().optional() });
+
+const launchResponseSchema = z.object({
+  agent: z.object({ id: z.string(), url: z.string().optional() }),
+  run: z.object({ id: z.string(), status: z.string() }),
+});
+
+// ---------------------------------------------------------------------------
+
+export class CloudAgentsBackend {
+  private readonly rpcClient: CursorBackendClient;
+
+  constructor(
+    private readonly apiKey: () => string,
+    private readonly fetchImpl: typeof fetch = fetch
+  ) {
+    // The key is read per call: the host can sign in after the mount.
+    this.rpcClient = new CursorBackendClient({
+      backendUrl: cursorBackendUrl(),
+      apiKey: "",
+      getApiKey: apiKey,
+      fetchImpl,
+    });
+  }
+
+  /** `POST /v1/agents`: create the agent and start its first run in one call. */
+  async launch(request: LaunchRequest): Promise<CloudAgentLaunch> {
+    const { cloud } = request;
+    const body = {
+      prompt: { text: request.prompt },
+      name: request.name,
+      model:
+        request.model === undefined
+          ? undefined
+          : toModelSelection(request.model),
+      env: cloud.env,
+      envVars: cloud.envVars,
+      repos: cloud.repos,
+      workOnCurrentBranch: cloud.workOnCurrentBranch,
+      autoCreatePR: cloud.autoCreatePR,
+      skipReviewerRequest: cloud.skipReviewerRequest,
+    };
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${cursorExternalApiUrl()}/v1/agents`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey()}`,
+          "x-ghost-mode": "true",
+          "x-cursor-client-type": "agent-serve",
+          "x-request-id": randomUUID(),
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(LAUNCH_TIMEOUT_MS),
+      });
+    } catch (error) {
+      throw new CloudAgentsApiError(
+        `Cloud agent launch failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CloudAgentsApiError(
+        `Cloud agent launch failed (${response.status}): ${apiErrorMessage(text)}`,
+        response.status
+      );
+    }
+    const parsed = launchResponseSchema.parse(JSON.parse(text));
+    return {
+      agentId: parsed.agent.id,
+      runId: parsed.run.id,
+      status: parsed.run.status.toLowerCase(),
+      url: parsed.agent.url ?? agentUrl(parsed.agent.id),
+    };
+  }
+
+  async info(agentId: string): Promise<CloudAgentInfo> {
+    const { composer } = infoResponseSchema.parse(
+      await this.rpcClient.serviceRpc(
+        SERVICE,
+        "GetBackgroundComposerInfo",
+        { bcId: agentId },
+        RPC_TIMEOUT_MS
+      )
+    );
+    const { composer: summary } = composer;
+    const failure = composer.permanentError ?? composer.startError;
+    return {
+      agentId: summary.bcId,
+      name: summary.name ?? "",
+      status: statusOf(summary.status),
+      archived: summary.isArchived === true,
+      url: agentUrl(summary.bcId),
+      branch: emptyToUndefined(summary.branchName),
+      prUrl: emptyToUndefined(summary.prUrl),
+      summary: emptyToUndefined(composer.summary),
+      error: failureMessage(failure),
+      changes:
+        summary.filesChanged === undefined
+          ? undefined
+          : {
+              filesChanged: summary.filesChanged,
+              linesAdded: summary.linesAdded ?? 0,
+              linesRemoved: summary.linesRemoved ?? 0,
+            },
+    };
+  }
+
+  async conversation(agentId: string): Promise<CloudAgentMessage[]> {
+    const { conversation } = conversationResponseSchema.parse(
+      await this.rpcClient.serviceRpc(
+        SERVICE,
+        "GetBackgroundComposerConversation",
+        { bcId: agentId },
+        RPC_TIMEOUT_MS
+      )
+    );
+    return (conversation ?? []).map((message) => {
+      const toolCalls = (message.toolResults ?? []).map((result) => ({
+        name: result.toolName ?? "",
+        args: parseArgs(result.args ?? result.rawArgs),
+        content: result.content,
+        error: result.error?.clientVisibleErrorMessage,
+      }));
+      return {
+        role: message.type === "MESSAGE_TYPE_HUMAN" ? "user" : "assistant",
+        text: emptyToUndefined(message.text),
+        thinking: emptyToUndefined(message.thinking?.text),
+        toolCalls: toolCalls.length === 0 ? undefined : toolCalls,
+      };
+    });
+  }
+
+  /**
+   * Queue a follow-up behind the current run, or with `interrupt` cancel the
+   * in-flight step and run it now; the backend's `synchronous` switch.
+   */
+  async followUp(
+    agentId: string,
+    prompt: string,
+    interrupt: boolean
+  ): Promise<{ runId: string | undefined }> {
+    const { runId } = followupResponseSchema.parse(
+      await this.rpcClient.serviceRpc(
+        SERVICE,
+        "AddAsyncFollowupBackgroundComposer",
+        {
+          bcId: agentId,
+          synchronous: interrupt,
+          followupSource: SOURCE,
+          followupMessage: {
+            text: prompt,
+            type: "MESSAGE_TYPE_HUMAN",
+            bubbleId: randomUUID(),
+          },
+        },
+        RPC_TIMEOUT_MS
+      )
+    );
+    return { runId };
+  }
+
+  async pause(agentId: string): Promise<void> {
+    await this.rpcClient.serviceRpc(
+      SERVICE,
+      "PauseBackgroundComposer",
+      { bcId: agentId, source: SOURCE },
+      RPC_TIMEOUT_MS
+    );
+  }
+}
+
+let backend: CloudAgentsBackend | undefined;
+
+/** The process-wide backend for this mount, built on first use. */
+export function cloudAgentsBackend(): CloudAgentsBackend {
+  backend ??= new CloudAgentsBackend(apiKey);
+  return backend;
+}
+
+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 agentUrl(agentId: string): string {
+  return `${cursorWebsiteUrl()}/agents/${agentId}`;
+}
+
+function statusOf(status: string | undefined): CloudAgentStatus {
+  switch (status) {
+    case "BACKGROUND_COMPOSER_STATUS_CREATING":
+      return "creating";
+    case "BACKGROUND_COMPOSER_STATUS_RUNNING":
+      return "running";
+    case "BACKGROUND_COMPOSER_STATUS_FINISHED":
+      return "finished";
+    case "BACKGROUND_COMPOSER_STATUS_ERROR":
+      return "error";
+    case "BACKGROUND_COMPOSER_STATUS_EXPIRED":
+      return "expired";
+    default:
+      return "unknown";
+  }
+}
+
+function failureMessage(
+  failure: z.infer<typeof errorDetailsSchema> | undefined
+): string | undefined {
+  const parts = [failure?.details?.title, failure?.details?.detail].filter(
+    (part): part is string => part !== undefined && part !== ""
+  );
+  return parts.length === 0 ? undefined : parts.join(": ");
+}
+
+function parseArgs(args: string | undefined): unknown {
+  if (args === undefined || args === "") {
+    return undefined;
+  }
+  try {
+    return JSON.parse(args) as unknown;
+  } catch {
+    return args;
+  }
+}
+
+function emptyToUndefined(value: string | undefined): string | undefined {
+  return value === undefined || value === "" ? undefined : value;
+}
+
+function apiErrorMessage(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as {
+      error?: { code?: string; message?: string };
+      code?: string;
+      message?: string;
+    };
+    const code = parsed.error?.code ?? parsed.code;
+    const message = parsed.error?.message ?? parsed.message;
+    return (
+      [code, message].filter((part) => part !== undefined).join(": ") || text
+    );
+  } catch {
+    return text;
+  }
+}

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

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const agentRef: z.ZodObject<{ agent_id: z.ZodString }> = z.object({
+  agent_id: z.string().describe("Agent id (`bc-...`) returned by launch."),
+});

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

@@ -0,0 +1,23 @@
+/** A cloud agent's conversation as JSONL lines, one message per line. */
+
+import type { CloudAgentMessage } from "./backend.js";
+
+/** Workspace-relative path of a dumped transcript; the directory Sand uses too. */
+export function transcriptPath(agentId: string): string {
+  return `cloud-agent-transcripts/${agentId}.jsonl`;
+}
+
+export function transcriptLines(messages: CloudAgentMessage[]): string[] {
+  return messages.map((message) => JSON.stringify(message));
+}
+
+/** The text of the last assistant message, the agent's report. */
+export function lastAssistantText(
+  messages: CloudAgentMessage[]
+): string | undefined {
+  return messages
+    .toReversed()
+    .find(
+      (message) => message.role === "assistant" && message.text !== undefined
+    )?.text;
+}

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

@@ -1,26 +1,40 @@
 ---
-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."
+description: "Delegate coding work to Cursor cloud agents: when to hand off, how to write the prompt, and how to look an agent up by id, read what it did, reply, and cancel."
 ---
 
 # 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.
+The tools below are this extension's; they appear under its mount namespace, as `<namespace>__launch` and so on. Every agent is addressed by its `agent_id` (`bc-...`).
 
 ## 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.
+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 `starting_ref` or `pr_url` 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
+## Look an agent up by id
 
-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.
+Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, or `expired`), its `branch` and pull request `prUrl` once pushed, the `changes` it made so far (files and lines), a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
 
-## Check status
+## Read what it did
 
-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.
+To read the report or understand what was done, call `dump` with the `agent_id`. It writes the agent's whole conversation, every run, to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus the `finalMessage`. Each line is one JSON message with `role` (`user` or `assistant`) and, for assistant lines, `text`, `thinking`, and `toolCalls` (tool `name`, `args`, `content`, `error`). Read it with your file and shell tools, using the returned path:
+
+- `tail -n 1 <path>` gives the final report.
+- `grep '"toolCalls"' <path>` shows the commands and edits it made.
+- `grep '"role":"user"' <path>` shows every prompt it received, including replies.
+
+Use `dump` before summarizing an agent's work for a person, and to understand a failure before replying with a fix.
+
+## Reply
+
+Call `reply` with the `agent_id` and a prompt to steer an agent or ask for changes on its branch. The follow-up queues behind the current run and starts when it finishes; pass `interrupt: true` to stop the current step and deliver it now. Do not launch a second agent for follow-up work on the same branch.
+
+## Cancel
+
+Call `cancel` with the `agent_id` to stop the active run. The agent keeps its branch and conversation, so a `reply` can continue from where it stopped.
 
 ## Fleet
 

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

@@ -0,0 +1,19 @@
+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 cancel: ToolDefinition = defineTool({
+  description:
+    "Stop a cloud agent's active run. The agent keeps its branch and conversation; reply to it to continue.",
+  effect: "write",
+  inputSchema: agentRef,
+  async execute(input, ctx) {
+    await assertOwned(ctx, input.agent_id);
+    await cloudAgentsBackend().pause(input.agent_id);
+    return { agentId: input.agent_id, cancelled: true };
+  },
+});
+
+export default cancel;