@cursor/july 0.1.97 → 0.1.100

package/src/channels/slack/types.ts

@@ -61,8 +61,14 @@ export interface SlackChannelState {
   streamTs: string | null;
   /** Channel id used when the stream was started. */
   streamChannelId?: string | null;
-  /** Last cumulative text sent via appendStream (for incremental append). */
+  /** Last assistant text delivered to the thread (stream or postMessage). */
   lastPostedText?: string | null;
+  /**
+   * Text of the current assistant block already written into the open stream.
+   * The harness restarts its cumulative text at every tool boundary, so the
+   * append delta cannot be measured against {@link lastPostedText}.
+   */
+  streamBlockText?: string | null;
   /**
    * Slack message ts of the agent's last delivered reply in this thread.
    * Warm turns use this as the `<slack_thread_delta>` watermark.
@@ -73,13 +79,160 @@ 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;
   /**
    * Message ts of approval cards keyed by tool call id (for
    * 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;
@@ -494,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;
   /**
@@ -548,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";
 
 /**
@@ -76,8 +80,9 @@ export const AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR =
  * user-level store above. The user store carries author-facing bytes
  * (`ctx.host.files`, skills, memory, artifacts) and is browsable and
  * mountable; the framework store carries engine-owned session state —
- * session records, event transcripts, continuation index, and the SDK
- * conversation mirror — and is never exposed to authors or models.
+ * session records, event transcripts, hosted-execution run logs,
+ * continuation index, and the SDK conversation mirror — and is never
+ * exposed to authors or models.
  * Provisioned by the v2 deploy pipeline alongside the user store; v1
  * deployments have only the user store.
  */
@@ -110,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;
 }
 
 /**
@@ -124,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);
 }
 
 /**
@@ -163,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;
 }
@@ -649,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/index.ts

@@ -79,6 +79,10 @@ export {
   V2EngineError,
 } from "./continuation.js";
 export { defineHook } from "./hooks.js";
+export {
+  InvalidAsOfError,
+  VacuousTimeArgsError,
+} from "./internal/as-of.js";
 export type { LoadAgentProjectOptions } from "./internal/discovery.js";
 export {
   formatDiagnostics,

package/src/internal/as-of.ts

@@ -0,0 +1,107 @@
+const TIMEZONE_SUFFIX = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+
+export class InvalidAsOfError extends Error {
+  constructor(value: string) {
+    super(
+      `asOf must be an ISO-8601 instant with a timezone (e.g. ` +
+        `2026-08-31T12:00:00Z); received ${JSON.stringify(value)}.`
+    );
+    this.name = "InvalidAsOfError";
+  }
+}
+
+function parseInstant(value: string): Date | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "" || !TIMEZONE_SUFFIX.test(trimmed)) {
+    return undefined;
+  }
+  const instant = new Date(trimmed);
+  return Number.isNaN(instant.getTime()) ? undefined : instant;
+}
+
+export function normalizeAsOf(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const instant = parseInstant(value);
+  if (instant === undefined) {
+    throw new InvalidAsOfError(value);
+  }
+  return instant.toISOString();
+}
+
+export function sessionClock(asOf: string | undefined): () => Date {
+  if (asOf === undefined) {
+    return () => new Date();
+  }
+  const frozen = new Date(asOf).getTime();
+  return () => new Date(frozen);
+}
+
+export class VacuousTimeArgsError extends Error {
+  constructor(toolName: string, missing: readonly string[]) {
+    super(
+      `Tool "${toolName}" declares timeArgs ` +
+        `${JSON.stringify(missing)} that its input schema does not define, ` +
+        `so bounding would silently check nothing. Make the declaration ` +
+        `match the schema's property names.`
+    );
+    this.name = "VacuousTimeArgsError";
+  }
+}
+
+export function assertTimeArgs(
+  tools: readonly {
+    name: string;
+    definition: { timeArgs?: readonly string[] };
+    inputSchema?: { properties?: Record<string, unknown> };
+  }[],
+  asOf: string | undefined
+): void {
+  if (asOf === undefined) {
+    return;
+  }
+  for (const tool of tools) {
+    const declared = tool.definition.timeArgs;
+    if (declared === undefined || declared.length === 0) {
+      continue;
+    }
+    const properties = tool.inputSchema?.properties ?? {};
+    const missing = declared.filter((name) => !(name in properties));
+    if (missing.length > 0) {
+      throw new VacuousTimeArgsError(tool.name, missing);
+    }
+  }
+}
+
+export function timeArgViolation(
+  input: unknown,
+  timeArgs: readonly string[],
+  asOf: string
+): string | undefined {
+  const record =
+    typeof input === "object" && input !== null
+      ? (input as Record<string, unknown>)
+      : {};
+  const frozen = new Date(asOf).getTime();
+  for (const name of timeArgs) {
+    const value = record[name];
+    const instant = typeof value === "string" ? parseInstant(value) : undefined;
+    if (instant === undefined) {
+      return (
+        `Time argument "${name}" must be an absolute ISO-8601 instant with ` +
+        `a timezone (e.g. ${asOf}); received ${JSON.stringify(value)}. This ` +
+        `session reads the world as of ${asOf} — supply absolute bounds at ` +
+        `or before that instant and retry.`
+      );
+    }
+    if (instant.getTime() > frozen) {
+      return (
+        `Time argument "${name}" (${JSON.stringify(value)}) is later than ` +
+        `the instant this session reads the world as of (${asOf}). Supply ` +
+        `bounds at or before that instant and retry.`
+      );
+    }
+  }
+  return undefined;
+}

package/src/internal/cli-deploy.ts

@@ -66,6 +66,8 @@ import { stderrPalette } from "./terminal-style.js";
 
 const DEFAULT_POLL_INTERVAL_MS = 3_000;
 const DEFAULT_DEPLOY_TIMEOUT_MS = 10 * 60 * 1000;
+/** `--multi-tenant` HTTP deploy is Anysphere-only (team id 1). */
+const MULTI_TENANT_HTTP_DEPLOY_TEAM_ID = 1;
 
 /** One agent directory selected for deploy (single or multi-agent parent). */
 export type DeployTarget = ChildAgentDir;
@@ -114,7 +116,8 @@ export interface DeployCliOptions {
   allowDomains?: string[];
   /**
    * deploy `--multi-tenant`: add a release to an existing Cursor-managed
-   * (multi-tenant) product. Cannot create a new multi-tenant application.
+   * (multi-tenant) product. Hidden Anysphere-only flag. Cannot create a
+   * new multi-tenant application.
    */
   multiTenant?: boolean;
   /** Test seams. */
@@ -297,6 +300,14 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     return ctx;
   }
 
+  if (
+    options.multiTenant === true &&
+    ctx.teamId !== MULTI_TENANT_HTTP_DEPLOY_TEAM_ID
+  ) {
+    ctx.err("--multi-tenant is not available for this team.\n");
+    return 1;
+  }
+
   const targets = await resolveDeployTargets(options, ctx);
   if (typeof targets === "number") {
     return targets;
@@ -947,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.
  */
@@ -990,7 +1001,10 @@ async function deployOneAgentsdk(
       ...(args.multiTenant ? { multiTenant: true } : {}),
     });
   } catch (error) {
-    return renderApiError(error, ctx.err);
+    return renderApiError(error, ctx.err, {
+      multiTenant: args.multiTenant,
+      teamId: ctx.teamId,
+    });
   }
 
   if (ctx.noWait) {
@@ -1301,6 +1315,21 @@ export async function cmdDeploymentStatus(
   if (typeof ctx === "number") {
     return ctx;
   }
+  // Same dispatch as `stop`: v1 409s architecture-v2 slugs, so the v2
+  // GET goes first. A v2 404 (missing slug, or an older backend) falls
+  // through to the v1 agent-serve detail.
+  try {
+    const detail = await ctx.client.getAgentkitDeploy({
+      teamId: ctx.teamId,
+      slug,
+    });
+    renderAgentkitDeploymentStatus(ctx, detail);
+    return 0;
+  } catch (error) {
+    if (!(error instanceof DeployApiError) || error.status !== 404) {
+      return renderApiError(error, ctx.err);
+    }
+  }
   let detail: DeploymentDetail;
   try {
     detail = await ctx.client.getDeployment({ teamId: ctx.teamId, slug });
@@ -1393,6 +1422,40 @@ export async function cmdDeploymentStatus(
   return 0;
 }
 
+function renderAgentkitDeploymentStatus(
+  ctx: DeployCliContext,
+  detail: AgentkitDeployStatus
+): void {
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+    return;
+  }
+  const lines = [
+    `${detail.slug} (team ${detail.teamId})`,
+    `  status:       ${detail.status}`,
+    `  architecture: v2`,
+    `  application:  ${detail.applicationId}`,
+    `  release:      ${detail.releaseId}`,
+    `  progress:     ${detail.progress}`,
+  ];
+  if (detail.statusMessage !== null && detail.statusMessage.trim() !== "") {
+    lines.push(`  step:         ${detail.statusMessage}`);
+  }
+  if (detail.repositories !== undefined) {
+    lines.push(
+      `  watching:     ${
+        detail.repositories.length === 0
+          ? "(nothing)"
+          : detail.repositories.join(", ")
+      }`
+    );
+  }
+  if (detail.lastError !== null && detail.lastError !== undefined) {
+    lines.push(`  last error:   ${sanitizeCustomerError(detail.lastError)}`);
+  }
+  ctx.out(`${lines.join("\n")}\n`);
+}
+
 // ============================================================================
 // stop <slug>
 // ============================================================================
@@ -1415,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 {
@@ -1901,10 +1964,35 @@ async function pollUntil<
   };
 
   for (;;) {
-    const detail = await fetchDetail().catch((error: unknown) => {
+    let detail: T;
+    try {
+      detail = await fetchDetail();
+    } catch (error: unknown) {
+      // Capacity / rate-limit on GET is not a bake failure. The v2 accept
+      // already started freeze; keep polling until the wait budget expires.
+      if (
+        isTransientDeployStatusError(error) &&
+        Date.now() - startedAt < ctx.timeoutMs
+      ) {
+        if (!ctx.json) {
+          const elapsed = Math.round((Date.now() - startedAt) / 1000);
+          const label = "Waiting for status (server busy)";
+          if (tty) {
+            ctx.err(`\r\x1b[2K${slug}: ${label} (${elapsed}s)`);
+            sawProgress = true;
+          } else if (label !== lastLabel) {
+            ctx.err(`${slug}: ${label}\n`);
+          }
+          lastLabel = label;
+        }
+        const waitMs = transientDeployStatusWaitMs(error, ctx.pollIntervalMs);
+        const remaining = ctx.timeoutMs - (Date.now() - startedAt);
+        await sleep(Math.max(0, Math.min(waitMs, remaining)));
+        continue;
+      }
       finishProgressLine();
       throw error;
-    });
+    }
     report(detail);
     if (terminal.has(detail.status)) {
       finishProgressLine();
@@ -1922,6 +2010,28 @@ async function pollUntil<
   }
 }
 
+/** Load-shed / rate-limit on status GET — the deploy itself may still be baking. */
+function isTransientDeployStatusError(error: unknown): error is DeployApiError {
+  return (
+    error instanceof DeployApiError &&
+    (error.status === 503 || error.status === 429)
+  );
+}
+
+function transientDeployStatusWaitMs(
+  error: DeployApiError,
+  pollIntervalMs: number
+): number {
+  if (
+    error.status === 429 &&
+    error.retryAfterSeconds !== undefined &&
+    error.retryAfterSeconds > 0
+  ) {
+    return Math.max(pollIntervalMs, error.retryAfterSeconds * 1000);
+  }
+  return pollIntervalMs;
+}
+
 /**
  * Wait until GET 404s (the delete reconciler purged the record). Treats
  * other errors as failures. Throws DeployApiError on timeout.
@@ -2000,16 +2110,26 @@ function deployFailureDetail(lastError: string | null | undefined): string {
   return `: ${sanitizeCustomerError(lastError.trim())}`;
 }
 
-function renderApiError(error: unknown, err: (text: string) => void): number {
+function renderApiError(
+  error: unknown,
+  err: (text: string) => void,
+  context?: { multiTenant?: boolean; teamId?: number }
+): number {
   if (error instanceof DeployApiError) {
     err(`${error.message}\n`);
     if (
       error.status === 409 &&
       error.message.includes("application multiTenant does not match")
     ) {
-      err(
-        "This slug is a Cursor-managed (multi-tenant) product. Redeploy it with --multi-tenant.\n"
-      );
+      if (context?.multiTenant === true) {
+        err(
+          "This slug is a single-tenant application. Redeploy it without --multi-tenant.\n"
+        );
+      } else if (context?.teamId === MULTI_TENANT_HTTP_DEPLOY_TEAM_ID) {
+        err(
+          "This slug is a Cursor-managed (multi-tenant) product. Redeploy it with --multi-tenant.\n"
+        );
+      }
     }
     return 1;
   }

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.