@cursor/july 0.1.99 → 0.1.101

package/src/channels/slack/stream.ts

@@ -4,11 +4,36 @@
 
 export type StreamTaskStatus = "pending" | "in_progress" | "complete" | "error";
 
+/**
+ * One update to a task card. Slack keeps one card per `id`: `title` and
+ * `status` replace the previous values, `details` and `output` are appended
+ * to what the card already shows.
+ */
 export interface StreamTaskChunk {
   type: "task_update";
   id: string;
   title: string;
   status: StreamTaskStatus;
+  details?: string;
+  output?: string;
+}
+
+export interface StreamMarkdownChunk {
+  type: "markdown_text";
+  text: string;
+}
+
+/**
+ * A `chat.*Stream` chunk. Slack fixes a stream's mode at `chat.startStream`:
+ * one opened with bare `markdown_text` rejects every later `chunks` append
+ * (`streaming_mode_mismatch`), and vice versa. The live-delivery strategy
+ * therefore always speaks chunks, wrapping text as `markdown_text` chunks so
+ * tool-step `task_update`s can share the same message.
+ */
+export type StreamChunk = StreamMarkdownChunk | StreamTaskChunk;
+
+export function markdownChunk(text: string): StreamMarkdownChunk {
+  return { type: "markdown_text", text };
 }
 
 /**
@@ -36,28 +61,10 @@ export function computeStreamAppend(
   return "";
 }
 
-/** Build task_update chunks for tool calls. */
-export function buildTaskChunksForCalls(
-  calls: Array<{ callId: string; toolName: string }>,
-  status: StreamTaskStatus
-): StreamTaskChunk[] {
-  return calls.map((call) => ({
-    type: "task_update" as const,
-    id: call.callId,
-    title: call.toolName,
-    status,
-  }));
-}
-
-export function buildTaskChunkForResult(args: {
-  callId: string;
-  toolName: string;
-  isError: boolean;
-}): StreamTaskChunk {
-  return {
-    type: "task_update",
-    id: args.callId,
-    title: args.toolName,
-    status: args.isError ? "error" : "complete",
-  };
+/** Clamp to `max` characters, ending in an ellipsis when cut. */
+export function truncateCardText(text: string, max: number): string {
+  if (text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, max - 1)}…`;
 }

package/src/channels/slack/tool-cards.ts

@@ -0,0 +1,221 @@
+/**
+ * Task cards for tool calls inside the streamed reply. One card per key:
+ * the call id for `per-call`, the tool name for `per-tool`. A card's title
+ * counts its calls and its status follows the whole group; with one call
+ * per key that reduces to the plain per-call card.
+ */
+
+import { redactSecretTokens } from "./redact.js";
+import type { ResolvedSlackToolCards } from "./reply-options.js";
+import { type StreamTaskChunk, truncateCardText } from "./stream.js";
+import type {
+  SlackChannelState,
+  SlackToolCall,
+  SlackToolResult,
+  ToolCardCount,
+} from "./types.js";
+
+/** The argument the playground puts in a built-in tool's header. */
+const TOOL_PRIMARY_ARGS: Readonly<Record<string, readonly string[]>> = {
+  grep: ["pattern"],
+  glob: ["glob_pattern", "globPattern"],
+  read: ["path", "file_path", "target_file"],
+  shell: ["command", "cmd"],
+  task: ["description", "prompt"],
+};
+/** For other tools: the telling key, if any. */
+const GENERIC_PRIMARY_ARGS = [
+  "pattern",
+  "query",
+  "command",
+  "cmd",
+  "path",
+  "file",
+  "file_path",
+  "target_file",
+  "url",
+  "prompt",
+  "description",
+  "name",
+  "message",
+];
+const PATH_ARGS = new Set([
+  "path",
+  "file",
+  "file_path",
+  "target_file",
+  "target_directory",
+  "targetDirectory",
+]);
+const LINE_MAX = 80;
+const JSON_MAX = 120;
+
+function oneLine(text: string, max: number): string {
+  return truncateCardText(
+    redactSecretTokens(text).replace(/\s+/g, " ").trim(),
+    max
+  );
+}
+
+/** Clamp the middle so both ends stay visible; tail-biased to keep filenames. */
+function clampPath(text: string, max: number): string {
+  const one = redactSecretTokens(text).replace(/\s+/g, " ").trim();
+  if (one.length <= max) {
+    return one;
+  }
+  const budget = max - 1;
+  const head = Math.max(1, Math.floor(budget * 0.35));
+  const tail = Math.max(1, budget - head);
+  return `${one.slice(0, head)}…${one.slice(one.length - tail)}`;
+}
+
+/**
+ * Default tool-card line for a call, matching the playground's tool header:
+ * the grep pattern, the glob pattern, the file path, the shell command. Other
+ * tools show a lone string argument bare, else compact JSON. No key labels,
+ * no knobs like `headLimit`.
+ */
+export function defaultToolCardDetails(
+  call: SlackToolCall
+): string | undefined {
+  const args = call.args;
+  if (args === undefined || args === null) {
+    return undefined;
+  }
+  if (typeof args === "string") {
+    const line = oneLine(args, LINE_MAX);
+    return line === "" ? undefined : line;
+  }
+  if (typeof args !== "object" || Array.isArray(args)) {
+    return oneLine(JSON.stringify(args), JSON_MAX);
+  }
+  const record = args as Record<string, unknown>;
+  for (const key of TOOL_PRIMARY_ARGS[call.toolName] ?? GENERIC_PRIMARY_ARGS) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      return PATH_ARGS.has(key)
+        ? clampPath(value, LINE_MAX)
+        : oneLine(value, LINE_MAX);
+    }
+  }
+  const entries = Object.entries(record);
+  if (entries.length === 0) {
+    return undefined;
+  }
+  const lone = entries.length === 1 ? entries[0]?.[1] : undefined;
+  if (typeof lone === "string" && lone.trim() !== "") {
+    return oneLine(lone, LINE_MAX);
+  }
+  return oneLine(JSON.stringify(record), JSON_MAX);
+}
+
+export interface ToolCards {
+  forCalls(
+    state: SlackChannelState,
+    calls: readonly SlackToolCall[]
+  ): StreamTaskChunk[];
+  forResult(state: SlackChannelState, result: SlackToolResult): StreamTaskChunk;
+}
+
+function tallyFor(state: SlackChannelState, key: string): ToolCardCount {
+  if (state.toolCardCounts === undefined) {
+    state.toolCardCounts = {};
+  }
+  const existing = state.toolCardCounts[key];
+  if (existing !== undefined) {
+    return existing;
+  }
+  const created: ToolCardCount = { started: 0, done: 0, errors: 0 };
+  state.toolCardCounts[key] = created;
+  return created;
+}
+
+/**
+ * Slack appends each update's text to the card verbatim, so a group's later
+ * batch of lines brings its own line break.
+ */
+function appendLines(
+  tally: ToolCardCount,
+  field: "details" | "output",
+  lines: readonly string[]
+): string | undefined {
+  if (lines.length === 0) {
+    return undefined;
+  }
+  const already = tally[field] ?? 0;
+  tally[field] = already + lines.length;
+  return `${already > 0 ? "\n" : ""}${lines.join("\n")}`;
+}
+
+function present(line: string | undefined): line is string {
+  return line !== undefined && line !== "";
+}
+
+export function createToolCards(
+  cards: ResolvedSlackToolCards,
+  toolLabel: (toolName: string) => string
+): ToolCards {
+  const keyOf = (call: { callId: string; toolName: string }): string =>
+    cards.group === "per-call" ? call.callId : `tool:${call.toolName}`;
+  const title = (toolName: string, started: number): string => {
+    const label = toolLabel(toolName);
+    return started > 1 ? `${label} ×${started}` : label;
+  };
+
+  return {
+    forCalls(state, calls) {
+      const groups = new Map<string, SlackToolCall[]>();
+      for (const call of calls) {
+        const key = keyOf(call);
+        groups.set(key, [...(groups.get(key) ?? []), call]);
+      }
+      return [...groups.entries()].map(([key, group]) => {
+        const tally = tallyFor(state, key);
+        tally.started += group.length;
+        const chunk: StreamTaskChunk = {
+          type: "task_update",
+          id: key,
+          title: title(group[0]!.toolName, tally.started),
+          status: "in_progress",
+        };
+        const details = appendLines(
+          tally,
+          "details",
+          group.map((call) => cards.details?.(call)).filter(present)
+        );
+        if (details !== undefined) {
+          chunk.details = details;
+        }
+        return chunk;
+      });
+    },
+
+    forResult(state, result) {
+      const tally = tallyFor(state, keyOf(result));
+      tally.done += 1;
+      if (result.isError) {
+        tally.errors += 1;
+      }
+      const chunk: StreamTaskChunk = {
+        type: "task_update",
+        id: keyOf(result),
+        title: title(result.toolName, tally.started),
+        status:
+          tally.done < tally.started
+            ? "in_progress"
+            : tally.errors > 0
+              ? "error"
+              : "complete",
+      };
+      const output = appendLines(
+        tally,
+        "output",
+        [cards.output?.(result)].filter(present)
+      );
+      if (output !== undefined) {
+        chunk.output = output;
+      }
+      return chunk;
+    },
+  };
+}

package/src/channels/slack/types.ts

@@ -79,6 +79,8 @@ export interface SlackChannelState {
    * for the rest of the turn.
    */
   streamingUnavailable?: boolean;
+  /** The open stream hit Slack's size cap; appends stop until it closes. */
+  streamFull?: boolean;
   /** Editable progress message ts when `chat.startStream` is unavailable. */
   progressTs: string | null;
   /**
@@ -86,8 +88,151 @@ export interface SlackChannelState {
    * replacing Approve/Deny buttons after a decision).
    */
   approvalMessageByCallId?: Record<string, string>;
+  /** `reply.reasoningCard` bookkeeping for the current turn. */
+  reasoningCard?: ReasoningCardState;
+  /** `reply.toolCards` per-tool tallies for the current turn, keyed by tool name. */
+  toolCardCounts?: Record<string, ToolCardCount>;
 }
 
+/**
+ * Slack appends a task card's `details` across updates, so the reasoning
+ * card is fed deltas: `blockSent` is how much of the current reasoning block
+ * is already on Slack, `pending` is buffered text awaiting a flush.
+ */
+export interface ReasoningCardState {
+  status: "in_progress" | "complete" | null;
+  blockSent: number | null;
+  pending: string;
+  lastFlushMs: number | null;
+  chars: number;
+}
+
+/**
+ * `details` / `output` count the lines already on the card, so a later
+ * batch can start on a new line (Slack appends updates verbatim).
+ */
+export interface ToolCardCount {
+  started: number;
+  done: number;
+  errors: number;
+  details?: number;
+  output?: number;
+}
+
+/** A tool call as the model requested it (`actions.requested`). */
+export interface SlackToolCall {
+  callId: string;
+  toolName: string;
+  args?: unknown;
+}
+
+/** A finished tool call (`action.result`). */
+export interface SlackToolResult {
+  callId: string;
+  toolName: string;
+  output?: unknown;
+  isError: boolean;
+}
+
+/**
+ * What the status chip under the thread shows while a turn runs. Slack caps
+ * each line at 50 characters. While a `chat.startStream` is open Slack shows
+ * its own generic "is working…" instead, so in `"stream"` mode these lines
+ * are only visible until the first chunk goes out.
+ */
+export interface SlackStatusOptions {
+  /** First line of each reasoning block, throttled. Defaults to `true`. */
+  reasoning?: boolean;
+  /**
+   * Tool calls as they start: `"Running grep, glob…"` (tool names through
+   * {@link SlackChannelOptions.toolLabels}), or your own line. Defaults to
+   * `true`.
+   */
+  tools?: boolean | ((calls: readonly SlackToolCall[]) => string);
+  /**
+   * Rotation Slack cycles through while nothing more specific is known
+   * (turn start, long silent stretches). Up to 5 entries. Defaults to
+   * Thinking… / Working on it… / Almost there….
+   */
+  idle?: readonly string[];
+}
+
+export type SlackToolCardGroup = "per-call" | "per-tool";
+
+/**
+ * Task cards for tool calls inside the streamed reply. Slack appends each
+ * update's `details` / `output` to the card, so the callbacks return the
+ * text to add, not the full card.
+ */
+export interface SlackToolCardOptions {
+  /**
+   * `"per-tool"` (default) keeps one card per tool name and counts calls in
+   * the title (`grep ×3`). `"per-call"` shows one card per call.
+   */
+  group?: SlackToolCardGroup;
+  /**
+   * `true` (default): cards expand to show one line per call, the way the
+   * reasoning card does. `false`: cards are their titles only.
+   */
+  collapsible?: boolean;
+  /**
+   * The line a collapsible card shows for a call. Defaults to what the
+   * playground shows in that tool's header: the grep pattern, the file
+   * path, the shell command.
+   */
+  details?: (call: SlackToolCall) => string | undefined;
+  /** Text appended to a collapsible card when a call finishes. */
+  output?: (result: SlackToolResult) => string | undefined;
+}
+
+/**
+ * One task card that receives the model's reasoning as it streams. Its
+ * status is `in_progress` while the model thinks and `complete` once the
+ * answer text starts.
+ */
+export interface SlackReasoningCardOptions {
+  /** Card title. Defaults to `"Thinking"`. */
+  title?: string;
+  /**
+   * Stop appending after this many characters. Defaults to 1500: Slack caps
+   * a streamed message (answer text plus cards) near 12k, so a long card
+   * shortens the answer that fits before the reply spills into a second
+   * message.
+   */
+  maxChars?: number;
+}
+
+/**
+ * How the reply reaches the thread while the turn runs.
+ *
+ * - `"post"` (default): live feedback is the status chip; the answer lands
+ *   as one message when the turn finishes.
+ * - `"stream"`: the answer text streams into one message as it is written.
+ *   Slack replaces the status chip with its generic "is working…" for the
+ *   duration, so live feedback inside the message comes from cards.
+ */
+export type SlackReplyOptions =
+  | {
+      mode: "post";
+      status?: SlackStatusOptions;
+    }
+  | {
+      mode: "stream";
+      status?: SlackStatusOptions;
+      /** Defaults to `false`. `true` is `{ group: "per-tool" }`. */
+      toolCards?: boolean | SlackToolCardOptions;
+      /** Defaults to `false`. */
+      reasoningCard?: boolean | SlackReasoningCardOptions;
+    };
+
+/**
+ * Human labels for tool names, shared by the status chip and the cards.
+ * A function may return `undefined` to keep the raw tool name.
+ */
+export type SlackToolLabels =
+  | Readonly<Record<string, string>>
+  | ((toolName: string) => string | undefined);
+
 export interface SlackAuthor {
   /** Slack user id. Empty string for bot posts with no `user` field. */
   userId: string;
@@ -502,13 +647,21 @@ export interface SlackChannelOptions {
    */
   deliverDefaults?: boolean;
   /**
-   * Stream assistant text while the turn runs via `chat.startStream` /
-   * `appendStream` / `stopStream` (defaults to `true`).
+   * How the reply reaches the thread: status chip + one message at the end
+   * (`"post"`, default), or a live-streamed message with optional tool and
+   * reasoning cards (`"stream"`). See {@link SlackReplyOptions}.
+   */
+  reply?: SlackReplyOptions;
+  /** Human labels for tool names in the status chip and cards. */
+  toolLabels?: SlackToolLabels;
+  /**
+   * @deprecated Use `reply: { mode: "stream" }` / `reply: { mode: "post" }`.
+   * Ignored when `reply` is set.
    */
   streaming?: boolean;
   /**
-   * Show task-style thinking steps for tool calls (stream chunks or status).
-   * Defaults to `true`.
+   * @deprecated Use `reply: { mode: "stream", toolCards: true }`. Ignored
+   * when `reply` is set.
    */
   thinkingSteps?: boolean;
   /**
@@ -556,8 +709,8 @@ export interface SlackChannelOptions {
   suggestedPrompts?: SlackSuggestedPrompt[];
   suggestedPromptsTitle?: string;
   /**
-   * Rotating `assistant.threads.setStatus` loading lines (Slack caps each
-   * entry at 50 chars). Defaults to Thinking… / Working on it… / Almost there….
+   * @deprecated Use `reply: { mode, status: { idle: [...] } }`. Ignored when
+   * `reply` is set.
    */
   loadingMessages?: string[];
   /**

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;