@cursor/july 0.1.100 → 0.1.102

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/index.ts

@@ -21,6 +21,7 @@ export * from "./auth.js";
 export * from "./blocks.js";
 export * from "./bot-mentions.js";
 export * from "./channel-watch.js";
+export * from "./code-fences.js";
 export * from "./constants.js";
 export * from "./credentials.js";
 export * from "./defaults.js";

package/src/channels/slack/live-delivery.ts

@@ -22,6 +22,7 @@ import {
   startChatStream,
   stopChatStream,
 } from "./api.js";
+import { highlightCodeFences } from "./code-fences.js";
 import { SLACK_MARKDOWN_TEXT_MAX_LEN } from "./constants.js";
 import type { SlackLog } from "./log.js";
 import {
@@ -117,7 +118,7 @@ export function createStreamDeliveryStrategy(
     const openingText = markdown_text ?? "";
     const opening: StreamChunk[] = [];
     if (openingText !== "") {
-      opening.push(markdownChunk(openingText));
+      opening.push(markdownChunk(highlightCodeFences(openingText)));
     }
     opening.push(...(chunks ?? []));
     if (opening.length === 0) {
@@ -181,16 +182,24 @@ export function createStreamDeliveryStrategy(
     return opened ? activeStreamTs(args.channel) : null;
   };
 
+  /**
+   * What to append for the new cumulative text, as Slack should see it: the
+   * block text on both sides goes through the same fence rewrite, so the
+   * delta lines up with what the stream already holds.
+   */
+  const streamDelta = (channel: SlackChannel, text: string): string =>
+    computeStreamAppend(
+      highlightCodeFences(channel.state.streamBlockText ?? ""),
+      highlightCodeFences(text)
+    );
+
   const stopWithSuffix = async (args: {
     channel: SlackChannel;
     channelId: string;
     ts: string;
     text: string;
   }): Promise<{ ok: boolean; error?: string }> => {
-    const appendText = computeStreamAppend(
-      args.channel.state.streamBlockText,
-      args.text
-    );
+    const appendText = streamDelta(args.channel, args.text);
     const stopped = await stopChatStream({
       botToken,
       channel: args.channelId,
@@ -299,10 +308,7 @@ export function createStreamDeliveryStrategy(
       if (ts === null) {
         return;
       }
-      const appendText = computeStreamAppend(
-        channel.state.streamBlockText,
-        text
-      );
+      const appendText = streamDelta(channel, text);
       if (appendText === "") {
         return;
       }
@@ -374,10 +380,7 @@ export function createStreamDeliveryStrategy(
         return { delivered: false };
       }
       // Measured before the stop attempt mutates stream state.
-      const remainder = computeStreamAppend(
-        channel.state.streamBlockText,
-        text
-      );
+      const remainder = streamDelta(channel, text);
       const stopped =
         channel.state.streamFull === true
           ? { ok: false, error: "msg_too_long" }

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/connections.ts

@@ -8,7 +8,9 @@
  * are available to the agent (SDK `mcpServers`), host (`ctx.host.mcp`),
  * and channel/schedule handlers. Pass `advertiseTools: true` for named
  * tools on local turns. Pass `effects: "read"` with `advertiseTools` to
- * advertise only tools the server classifies as reads. Files under
+ * advertise only tools the server classifies as reads. Pass `tools` as
+ * a name list to keep a subset, same shape as `defineAgent({ tools })`.
+ * Pass `disallowedTools` to drop names. Files under
  * `host-connections/` stay off the model.
  *
  * ```ts
@@ -42,6 +44,20 @@
  *   advertiseTools: true,
  *   effects: "read",
  * });
+ *
+ * // named subset: advertise and call only these tools
+ * export default defineConnection({
+ *   url: "https://mcp.example.com/inventory",
+ *   advertiseTools: true,
+ *   tools: ["search_skus", "get_stock"],
+ * });
+ *
+ * // drop a few tools from a large server
+ * export default defineConnection({
+ *   url: "https://mcp.example.com/inventory",
+ *   advertiseTools: true,
+ *   disallowedTools: ["place_order", "delete_sku"],
+ * });
  * ```
  *
  * A **Cursor account MCP connection** exposes the MCP connectors the operator
@@ -129,6 +145,7 @@ export {
   isInlineStdioConnection,
   isToolEffect,
   normalizeConnectionEffects,
+  normalizeConnectionTools,
   normalizeCursorAccountServers,
 } from "./types.js";
 

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

@@ -0,0 +1,120 @@
+/**
+ * Cursor cloud agents as an extension. Mount it and the agent can hand
+ * coding work to Cursor cloud agents and steer a fleet of them:
+ *
+ * ```ts
+ * // agent/extensions/cloud.ts
+ * import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
+ *
+ * export default cursorCloudAgents({
+ *   cloud: { repos: [{ url: "https://github.com/acme/api" }], autoCreatePR: true },
+ * });
+ * ```
+ *
+ * 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";
+import { defineExtension } from "../../extensions.js";
+import type {
+  AgentCloudOptions,
+  Extension,
+  ModelSetting,
+} from "../../types.js";
+
+/** Mount options; every field is optional. */
+export interface CursorCloudAgentsOptions {
+  /**
+   * Launch defaults: target `repos`, `env`, `autoCreatePR`, ... in the same
+   * vocabulary as `defineAgent({ cloud })`. Configured `repos` are also the
+   * allowlist for a launch's own `repo` / `prUrl`; model-chosen targets are
+   * refused when no allowlist is configured. With none configured,
+   * `needsApproval` defaults to true so prompt-only launches park first.
+   */
+  cloud?: AgentCloudOptions;
+  /** Model for launched agents. The account default when omitted. */
+  model?: ModelSetting;
+  /**
+   * Park launches and follow-ups for a human approval. Defaults to `true`
+   * when no `cloud.repos` are configured (prompt-only launches still use
+   * the host key); `false` once repositories are configured. Pass an
+   * explicit boolean to override. Model-chosen `repo` / `prUrl` still
+   * require the allowlist regardless of this flag.
+   */
+  needsApproval?: boolean;
+  /** Cursor API key. Defaults to the serve host's own key. */
+  apiKey?: string;
+}
+
+/** {@link CursorCloudAgentsOptions} with defaults applied. */
+export interface CursorCloudAgentsConfig {
+  cloud: AgentCloudOptions;
+  model?: ModelSetting;
+  needsApproval: boolean;
+  apiKey?: string;
+}
+
+const repo = z.object({
+  url: z.string().url(),
+  startingRef: z.string().optional(),
+  prUrl: z.string().url().optional(),
+});
+
+const cloud: z.ZodType<AgentCloudOptions> = z.object({
+  env: z
+    .discriminatedUnion("type", [
+      z.object({ type: z.literal("cloud"), name: z.string().optional() }),
+      z.object({ type: z.literal("pool"), name: z.string().optional() }),
+      z.object({ type: z.literal("machine"), name: z.string().optional() }),
+    ])
+    .optional(),
+  repos: z.array(repo).optional(),
+  workOnCurrentBranch: z.boolean().optional(),
+  autoCreatePR: z.boolean().optional(),
+  skipReviewerRequest: z.boolean().optional(),
+  envVars: z.record(z.string()).optional(),
+});
+
+const model: z.ZodType<ModelSetting> = z.union([
+  z.string().min(1),
+  z.object({
+    id: z.string().min(1),
+    params: z.array(z.object({ id: z.string(), value: z.string() })).optional(),
+  }),
+]);
+
+const config: z.ZodType<
+  CursorCloudAgentsConfig,
+  z.ZodTypeDef,
+  CursorCloudAgentsOptions | undefined
+> = z
+  .object({
+    cloud: cloud.default({}),
+    model: model.optional(),
+    needsApproval: z.boolean().optional(),
+    apiKey: z.string().optional(),
+  })
+  .default({})
+  .transform((options) => ({
+    ...options,
+    needsApproval: options.needsApproval ?? options.cloud.repos === undefined,
+  }));
+
+const cursorCloudAgents: Extension<
+  CursorCloudAgentsConfig,
+  CursorCloudAgentsOptions | undefined
+> = defineExtension({
+  root: import.meta.dirname,
+  description: "Launch, steer, and monitor Cursor cloud agents.",
+  config,
+});
+
+export default cursorCloudAgents;

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;
+  }
+}