@cursor/july 0.1.100 → 0.1.101

package/src/channels/origin/types.ts

@@ -4,11 +4,14 @@ import type {
   ArtifactsApi,
   AuthContext,
   AuthPolicy,
+  ChannelEventHandlers,
   ChannelStartArgs,
   HostContext,
+  SendMessageFn,
 } from "../../types.js";
 import type { OriginTokenProvider } from "./api.js";
 import type { OriginHandle } from "./binding.js";
+import type { OriginChannelState } from "./state.js";
 
 export interface OriginActor {
   id: string;
@@ -70,6 +73,12 @@ export interface OriginEventContext {
    */
   payload: Record<string, unknown>;
   sender?: OriginActor;
+  /**
+   * Channel `send`. Set on every delivery path (HTTP webhook, hosted
+   * admission, SCM events) so a hook can start a turn itself instead of
+   * returning `{ auth, message }` or a deferred `{ task }`.
+   */
+  send?: SendMessageFn;
   host: HostContext;
   artifacts: ArtifactsApi;
   /**
@@ -242,6 +251,21 @@ export interface OriginChannelOptions {
    * pull request URL, or a resolver for custom cloud options.
    */
   cloud?: boolean | AgentCloudOptions | OriginCloudOptionsResolver;
+  /**
+   * When false, skip posting completed assistant messages (and failure
+   * notices) back to the Origin pull request. Defaults to true — the GitHub
+   * channel's reply-delivery posture. Outbound credentials resolve like
+   * `ctx.origin`: {@link app} / `ORIGIN_APP_*` env when configured,
+   * otherwise the Cursor-account session exchange (hosted v2 deployments
+   * post as the deployment service-account principal).
+   */
+  deliverReplies?: boolean;
+  /**
+   * Channel stream-event handlers, merged over the built-in reply-delivery
+   * defaults (`buildDefaultOriginEvents`) — same override contract as the
+   * GitHub channel's `events`.
+   */
+  events?: ChannelEventHandlers<OriginChannelState>;
   /** Called once when the server mounts this channel. */
   onStart?: (args: ChannelStartArgs) => void | Promise<void>;
   /** Called when the server shuts down. */

package/src/channels/slack/api.ts

@@ -5,6 +5,7 @@
 import { ErrorCode, type WebAPIPlatformError, WebClient } from "@slack/web-api";
 import { slackifyMarkdown } from "slackify-markdown";
 import type { ArtifactsApi, HostContext } from "../../types.js";
+import { highlightCodeFences } from "./code-fences.js";
 import {
   SLACK_DEFAULT_LOADING_MESSAGES,
   SLACK_LOADING_MESSAGE_MAX_LEN,
@@ -495,7 +496,7 @@ export async function postMessage(args: {
       operation: "chat.postMessage",
       body: {
         ...base,
-        markdown_text: args.text,
+        markdown_text: highlightCodeFences(args.text),
       },
     });
     // Older workspaces / scopes may not accept markdown_text — retry with text.

package/src/channels/slack/code-fences.ts

@@ -0,0 +1,183 @@
+/**
+ * Slack highlights a fenced code block only when its info string is a
+ * language it knows (`ts`, `python`, …). Models on this harness cite code
+ * with Cursor's `startLine:endLine:path` form, or a bare path, which Slack
+ * shows verbatim as the block's header with no highlighting. The header is
+ * the only slot Slack offers, so a block gets colors by moving the reference
+ * to a comment on its first line. Files whose language has no comment
+ * syntax, or that Slack cannot color anyway, keep the reference as header.
+ */
+
+const FENCE = /^(\s*)(`{3,}|~{3,})(.*)$/;
+/** A line that may still grow into a fence. */
+const FENCE_START = /^\s*(`{1,2}|~{1,2})$/;
+const CITATION = /^(\d+):(\d+):(\S+)$/;
+
+const LANGUAGE_BY_EXTENSION: Readonly<Record<string, string>> = {
+  ts: "ts",
+  mts: "ts",
+  cts: "ts",
+  tsx: "tsx",
+  js: "js",
+  mjs: "js",
+  cjs: "js",
+  jsx: "jsx",
+  py: "python",
+  go: "go",
+  rs: "rust",
+  java: "java",
+  kt: "kotlin",
+  swift: "swift",
+  rb: "ruby",
+  php: "php",
+  c: "c",
+  h: "c",
+  cc: "cpp",
+  cpp: "cpp",
+  hpp: "cpp",
+  cs: "csharp",
+  json: "json",
+  jsonc: "jsonc",
+  yaml: "yaml",
+  yml: "yaml",
+  toml: "toml",
+  xml: "xml",
+  html: "html",
+  css: "css",
+  scss: "scss",
+  md: "markdown",
+  mdx: "mdx",
+  sh: "bash",
+  bash: "bash",
+  zsh: "bash",
+  sql: "sql",
+  proto: "protobuf",
+  tf: "hcl",
+  graphql: "graphql",
+  dockerfile: "dockerfile",
+  ini: "ini",
+};
+
+/** `[open, close]` comment delimiters; languages without one (JSON) are absent. */
+const COMMENT_BY_LANGUAGE: Readonly<Record<string, readonly [string, string]>> =
+  {
+    ts: ["//", ""],
+    tsx: ["//", ""],
+    js: ["//", ""],
+    jsx: ["//", ""],
+    go: ["//", ""],
+    rust: ["//", ""],
+    java: ["//", ""],
+    kotlin: ["//", ""],
+    swift: ["//", ""],
+    php: ["//", ""],
+    c: ["//", ""],
+    cpp: ["//", ""],
+    csharp: ["//", ""],
+    jsonc: ["//", ""],
+    protobuf: ["//", ""],
+    python: ["#", ""],
+    ruby: ["#", ""],
+    yaml: ["#", ""],
+    toml: ["#", ""],
+    bash: ["#", ""],
+    dockerfile: ["#", ""],
+    ini: ["#", ""],
+    hcl: ["#", ""],
+    graphql: ["#", ""],
+    sql: ["--", ""],
+    css: ["/*", "*/"],
+    scss: ["/*", "*/"],
+    html: ["<!--", "-->"],
+    xml: ["<!--", "-->"],
+    markdown: ["<!--", "-->"],
+    mdx: ["<!--", "-->"],
+  };
+
+function languageForPath(path: string): string | undefined {
+  const base = path.slice(path.lastIndexOf("/") + 1).toLowerCase();
+  const ext = base.includes(".") ? base.slice(base.lastIndexOf(".") + 1) : base;
+  return LANGUAGE_BY_EXTENSION[ext];
+}
+
+function looksLikePath(info: string): boolean {
+  return info.includes("/") || languageForPath(info) !== undefined;
+}
+
+/**
+ * Replacement lines for an opening fence whose info string is a citation or
+ * a path: the fence tagged with the language, then the reference as a
+ * comment. Falls back to the reference as the header when the block cannot
+ * carry a comment. `null` when the info string is neither.
+ */
+function rewriteOpening(
+  indent: string,
+  marks: string,
+  info: string
+): string[] | null {
+  const token = info.trim().split(/\s+/)[0] ?? "";
+  const cited = CITATION.exec(token);
+  const path = cited?.[3] ?? (looksLikePath(token) ? token : undefined);
+  if (path === undefined) {
+    return null;
+  }
+  const reference = cited === null ? path : `${path}:${cited[1]}-${cited[2]}`;
+  const language = languageForPath(path);
+  const comment =
+    language === undefined ? undefined : COMMENT_BY_LANGUAGE[language];
+  if (comment === undefined) {
+    return [`${indent}${marks}${reference}`];
+  }
+  const [open, close] = comment;
+  const commented =
+    close === "" ? `${open} ${reference}` : `${open} ${reference} ${close}`;
+  return [`${indent}${marks}${language}`, `${indent}${commented}`];
+}
+
+/**
+ * Rewrite fence info strings so Slack highlights the block. Safe to run on
+ * a growing stream: the output for a prefix is a prefix of the output for
+ * the full text, because an opening fence whose line has not ended yet is
+ * held back rather than emitted half-formed.
+ */
+export function highlightCodeFences(markdown: string): string {
+  const complete = markdown.endsWith("\n");
+  const lines = markdown.split("\n");
+  if (complete) {
+    lines.pop();
+  }
+  const out: string[] = [];
+  let open: { marks: string } | null = null;
+  const heldBack = (): string =>
+    `${out.join("\n")}${out.length > 0 ? "\n" : ""}`;
+  for (const [index, line] of lines.entries()) {
+    const last = index === lines.length - 1 && !complete;
+    const fence = FENCE.exec(line);
+    if (fence === null) {
+      if (last && open === null && FENCE_START.test(line)) {
+        return heldBack();
+      }
+      out.push(line);
+      continue;
+    }
+    const [, indent = "", marks = "", info = ""] = fence;
+    if (open !== null) {
+      if (
+        marks[0] === open.marks[0] &&
+        marks.length >= open.marks.length &&
+        info.trim() === ""
+      ) {
+        open = null;
+      }
+      out.push(line);
+      continue;
+    }
+    if (last) {
+      // Opening fence still being written: wait for the whole line.
+      return heldBack();
+    }
+    open = { marks };
+    out.push(...(rewriteOpening(indent, marks, info) ?? [line]));
+  }
+  return complete ? `${out.join("\n")}\n` : out.join("\n");
+}

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/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,118 @@
+/**
+ * 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__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.
+ */
+
+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/cloud.ts

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

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

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