@cursor/july 0.1.99 → 0.1.100

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/files-backends/cursor-hosted.ts

@@ -51,6 +51,10 @@ import {
   type FileSinkEntry,
   type FileSinkPutResult,
 } from "../files.js";
+import {
+  resolveDeploymentStoreSourceIdSync,
+  resolveFrameworkStoreSourceIdSync,
+} from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
 /**
@@ -111,8 +115,7 @@ const MAX_LIST_WALK_PAGES = 1_000;
 export function isCursorHostedFilesAvailable(
   env: NodeJS.ProcessEnv = process.env
 ): boolean {
-  const sourceId = env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]?.trim();
-  return sourceId !== undefined && sourceId !== "";
+  return resolveDeploymentStoreSourceIdSync(env) !== undefined;
 }
 
 /**
@@ -125,8 +128,7 @@ export function isCursorHostedFilesAvailable(
 export function cursorFrameworkStoreSourceId(
   env: NodeJS.ProcessEnv = process.env
 ): string | undefined {
-  const sourceId = env[AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR]?.trim();
-  return sourceId === undefined || sourceId === "" ? undefined : sourceId;
+  return resolveFrameworkStoreSourceIdSync(env);
 }
 
 /**
@@ -164,6 +166,12 @@ export interface CursorHostedFilesOptions {
   resolveApiKey?: () => string | undefined;
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
+  /**
+   * Lazy store source id, re-resolved on every call and preferred over
+   * {@link storeSourceId} — freeze bind drops ids into `/run/cursor/secrets`
+   * after serve start without restarting July.
+   */
+  resolveStoreSourceId?: () => string | undefined;
   /** Test seam; defaults to global fetch. */
   fetch?: typeof fetch;
 }
@@ -650,7 +658,9 @@ function fetchImpl(options: CursorHostedFilesOptions): typeof fetch {
  */
 function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
   const id = (
-    options.storeSourceId ?? process.env[AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR]
+    options.resolveStoreSourceId?.() ??
+    options.storeSourceId ??
+    resolveDeploymentStoreSourceIdSync(process.env)
   )?.trim();
   if (id === undefined || id === "") {
     throw new Error(

package/src/internal/cli-deploy.ts

@@ -958,7 +958,7 @@ async function deployAgentsdkApplication(
 }
 
 /**
- * `architecture: "v2"` deploy: POST `/internal/agentkit/deployments` and
+ * `architecture: "v2"` deploy: POST `/internal/agentsdk/deployments` and
  * poll the matching GET. The v2 accept path starts freeze bake; it does
  * not mint an engine alias or alias token.
  */
@@ -1478,7 +1478,7 @@ export async function cmdStop(
   // deploy). The v2 agentsdk control plane goes first: v1 endpoints refuse
   // `architecture: "v2"` slugs with a 409 rather than a 404, so v1-first
   // could not fall through. A v2 404 (including an older backend without
-  // the `/internal/agentkit` mount) falls back to the v1 stop.
+  // the `/internal/agentsdk` mount) falls back to the v1 stop.
   let architecture: "v1" | "v2" = "v2";
   let accepted: StopAccepted | AgentkitStopAccepted;
   try {

package/src/internal/conversation-mirror.ts

@@ -383,18 +383,13 @@ export function selectConversationMirror(input: {
     return undefined;
   }
   const env = input.env ?? process.env;
-  const frameworkStoreId = cursorFrameworkStoreSourceId(
-    env as NodeJS.ProcessEnv
-  );
-  if (
-    env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined ||
-    frameworkStoreId === undefined
-  ) {
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
     return undefined;
   }
+  const envSnapshot = env as NodeJS.ProcessEnv;
   return createConversationMirror({
     sink: cursorHostedFiles({
-      storeSourceId: frameworkStoreId,
+      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
       // Full chain (env → key file → stored login): frozen engines listen
       // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
       // is constructed.

package/src/internal/cursor/hosted-store-secrets.ts

@@ -0,0 +1,72 @@
+/**
+ * Task-time bind paths for hosted deployment file-store source ids.
+ *
+ * Freeze v2 snapshots start `agent-serve serve` at bake time without a service
+ * account, so neither store id is in process env. Execute-from-freeze binds
+ * the deployment credential and store ids into `/run/cursor/secrets/` without
+ * restarting July — the same pattern as {@link DEFAULT_CURSOR_API_KEY_FILE}.
+ */
+
+import { readFileSync } from "node:fs";
+
+export const DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE =
+  "/run/cursor/secrets/AGENT_SERVE_STORE_SOURCE_ID";
+
+export const DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE =
+  "/run/cursor/secrets/AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+
+const STORE_SOURCE_ID_ENV = "AGENT_SERVE_STORE_SOURCE_ID";
+const FRAMEWORK_STORE_SOURCE_ID_ENV = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+const STORE_SOURCE_ID_FILE_ENV = "AGENT_SERVE_STORE_SOURCE_ID_FILE";
+const FRAMEWORK_STORE_SOURCE_ID_FILE_ENV =
+  "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE";
+
+function readTrimmedFile(path: string): string | undefined {
+  try {
+    const raw = readFileSync(path, "utf8").trim();
+    return raw === "" ? undefined : raw;
+  } catch {
+    return undefined;
+  }
+}
+
+function readBoundSecretFile(
+  fileEnvVar: string,
+  defaultPath: string,
+  env: NodeJS.ProcessEnv
+): string | undefined {
+  const configured = env[fileEnvVar]?.trim();
+  const path =
+    configured !== undefined && configured !== "" ? configured : defaultPath;
+  return readTrimmedFile(path);
+}
+
+/** Deployment user-land store: env, then task-bind file. */
+export function resolveDeploymentStoreSourceIdSync(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const fromEnv = env[STORE_SOURCE_ID_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") {
+    return fromEnv;
+  }
+  return readBoundSecretFile(
+    STORE_SOURCE_ID_FILE_ENV,
+    DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE,
+    env
+  );
+}
+
+/** Engine framework store: env, then task-bind file. */
+export function resolveFrameworkStoreSourceIdSync(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const fromEnv = env[FRAMEWORK_STORE_SOURCE_ID_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") {
+    return fromEnv;
+  }
+  return readBoundSecretFile(
+    FRAMEWORK_STORE_SOURCE_ID_FILE_ENV,
+    DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE,
+    env
+  );
+}