@cursor/july 0.1.16 → 0.1.18

package/src/internal/session-engine.ts

@@ -39,6 +39,7 @@ import {
   type PendingApproval,
   type ReceiveInput,
   type ResolvedAgent,
+  type RunnerSubagent,
   type RunnerTurnRequest,
   type SendMessageFn,
   type SendMessageOptions,
@@ -957,13 +958,18 @@ export class SessionEngine {
   }
 
   /**
-   * Local harness cwd for a session: per-send override, else
-   * `<agent.local.cwd>/<sessionId>`, else the durable session workspace.
+   * Local harness cwd for a session: per-send override, else the shared
+   * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
+   * the durable session workspace.
    */
   harnessCwd(record: SessionRecord): string {
     if (record.workspaceOverride !== undefined) {
       return record.workspaceOverride;
     }
+    const shared = this.project.agent.local?.workspaceDir;
+    if (shared !== undefined) {
+      return shared;
+    }
     const agentCwd = this.project.agent.local?.cwd;
     if (agentCwd !== undefined) {
       return join(agentCwd, record.sessionId);
@@ -972,12 +978,64 @@ export class SessionEngine {
   }
 
   /**
-   * Directory that receives AGENTS.md / skills / agent tools. When the
-   * harness cwd is a one-off override (e.g. PR worktree), scaffold stays in
-   * the durable session workspace; otherwise scaffold lands in the harness.
+   * True when the harness cwd is a directory the session does not own — a
+   * per-send override (e.g. a PR worktree) or a workspace shared by every
+   * session. Agent scaffold has to stay out of those, so it lands in the
+   * durable session workspace and the instructions travel inline instead.
+   */
+  private hasBorrowedWorkspace(record: SessionRecord): boolean {
+    return (
+      record.workspaceOverride !== undefined ||
+      this.project.agent.local?.workspaceDir !== undefined
+    );
+  }
+
+  /**
+   * Resolve the shared harness workspace during startup, so the first session
+   * is not the one that waits for it. Only possible with
+   * `local.workspaceDir`: every other layout gives a session its own cwd,
+   * which is unknowable until that session exists.
+   *
+   * Best effort — warming is an optimization, and a turn rebuilds on its own.
    */
+  async prewarmSharedWorkspace(): Promise<void> {
+    const agent = this.project.agent;
+    const workspaceDir = agent.local?.workspaceDir;
+    if (
+      workspaceDir === undefined ||
+      agent.runtime !== "local" ||
+      this.runner.prewarm === undefined
+    ) {
+      return;
+    }
+    const startedAt = Date.now();
+    try {
+      const outcome = await this.runner.prewarm({
+        workspaceDir,
+        runnerStateDir: join(this.stateRoot, "runner"),
+        sandbox: agent.local?.sandbox === true,
+        mcpServers: this.buildMcpServers("local"),
+        subagents: buildRunnerSubagents(agent),
+        ...(agent.model === undefined ? {} : { model: agent.model }),
+      });
+      // Report what happened rather than that the call returned: a runner
+      // that cannot warm resolves cleanly, and logging success there would
+      // tell an operator the workspace is hot when nothing touched it.
+      this.logger(
+        outcome.warmed
+          ? `[agentkit] warmed ${workspaceDir} in ${Date.now() - startedAt}ms`
+          : `[agentkit] did not warm ${workspaceDir}: ${outcome.reason}`
+      );
+    } catch (error) {
+      this.logger(
+        `[agentkit] could not warm ${workspaceDir}: ${describeError(error)}`
+      );
+    }
+  }
+
+  /** Directory that receives AGENTS.md / skills / agent tools. */
   private scaffoldDir(record: SessionRecord): string {
-    if (record.workspaceOverride !== undefined) {
+    if (this.hasBorrowedWorkspace(record)) {
       return this.sessions.workspaceDir(record.sessionId);
     }
     return this.harnessCwd(record);
@@ -1053,13 +1111,13 @@ export class SessionEngine {
           });
         }
         // The harness only loads the scaffolded AGENTS.md when the session
-        // workspace is its own project root. With a per-session cwd override
-        // (PR worktree) the scaffold lands elsewhere, and a workspace nested
-        // inside a git repo re-roots harness rules at that repo — in both
-        // cases deliver instructions inline on the first turn instead.
+        // workspace is its own project root. When the harness cwd is borrowed
+        // (PR worktree, shared checkout) the scaffold lands elsewhere, and a
+        // workspace nested inside a git repo re-roots harness rules at that
+        // repo — in both cases deliver instructions inline on the first turn.
         const instructionsInvisibleToHarness =
           isFirstTurn &&
-          (record.workspaceOverride !== undefined ||
+          (this.hasBorrowedWorkspace(record) ||
             (await isNestedInGitRepo(harnessCwd)));
         const request = this.buildTurnRequest(
           record,
@@ -1201,10 +1259,10 @@ export class SessionEngine {
         turnPrompt = `${preamble}\n\n${turnPrompt}`;
       } else if (instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
-        // per-session harness cwd override, agent tool scripts live only in
-        // the durable scaffold dir — embed bodies like cloud. Otherwise the
-        // catalog can reference on-disk paths under the harness cwd.
-        const includeScripts = record.workspaceOverride !== undefined;
+        // borrowed harness cwd, agent tool scripts live only in the durable
+        // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+        // reference on-disk paths under the harness cwd.
+        const includeScripts = this.hasBorrowedWorkspace(record);
         const preamble = buildAgentsMdContent(agent, { includeScripts });
         turnPrompt = `${preamble}\n\n${turnPrompt}`;
       }
@@ -1215,6 +1273,7 @@ export class SessionEngine {
         ? {}
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
+      sandbox: this.project.agent.local?.sandbox === true,
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,
@@ -1224,12 +1283,7 @@ export class SessionEngine {
       customTools:
         runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {},
       mcpServers: this.buildMcpServers(runtime),
-      subagents: agent.subagents.map((subagent) => ({
-        name: subagent.name,
-        description: subagent.description ?? subagent.name,
-        prompt: subagentPrompt(subagent),
-        ...(subagent.model === undefined ? {} : { model: subagent.model }),
-      })),
+      subagents: buildRunnerSubagents(agent),
       onUpdate,
       signal,
       // Local follow-ups expire any lingering active run so a preempted turn
@@ -2094,10 +2148,24 @@ export class SessionEngine {
     sessionId: string,
     token: string | null
   ): Promise<void> {
+    const previous = await this.sessions.get(sessionId);
     await this.updateRecord(sessionId, (current) => ({
       ...current,
       continuationKey: token,
     }));
+    // Keep armed reminders addressed at the conversation across rotation
+    // (the built-in HTTP channel rotates after every follow-up).
+    if (
+      previous?.continuationKey != null &&
+      token !== null &&
+      token !== previous.continuationKey
+    ) {
+      await this.reminderApi?.rekeyContinuation(
+        previous.channelId,
+        previous.continuationKey,
+        token
+      );
+    }
   }
 
   isTurnRunning(sessionId: string): boolean {
@@ -2509,6 +2577,20 @@ function subagentPrompt(subagent: ResolvedAgent): string {
   return subagent.description ?? subagent.name;
 }
 
+/**
+ * Subagents as the runner takes them. Shared by turns and by workspace
+ * warming, which has to describe the same agent a turn would to reach the
+ * executor that turn will run on.
+ */
+function buildRunnerSubagents(agent: ResolvedAgent): RunnerSubagent[] {
+  return agent.subagents.map((subagent) => ({
+    name: subagent.name,
+    description: subagent.description ?? subagent.name,
+    prompt: subagentPrompt(subagent),
+    ...(subagent.model === undefined ? {} : { model: subagent.model }),
+  }));
+}
+
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/internal/slack-provision-client.ts

@@ -0,0 +1,442 @@
+/**
+ * Thin client for the Agent Serve Slack provisioning API
+ * (`/internal/agent-serve/slack` on the Cursor backend — "Add to Slack").
+ * Pure request/response + error mapping — no console I/O, no polling
+ * loops; rendering lives in `cli-slack.ts`.
+ *
+ * Auth is the user API key sent directly as the bearer (the routes are
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
+ * The endpoints are gated on the `agent_serve_slack_provisioning` Statsig
+ * gate and 404 when it is off — the error mapping says so instead of
+ * "not found". Expected provisioning failures carry a stable JSON `code`
+ * (`not_connected`, `insufficient_scopes`, `manager_reauth_required`,
+ * `app_conflict`, `app_cap_reached`, `ratelimited`, `invalid_app_id`, …)
+ * which flows through on {@link SlackProvisionApiError.code} so the CLI
+ * can branch.
+ */
+
+import { z } from "zod";
+
+export type SlackAppEnv = "dev" | "prod";
+
+/** One manager-connected Slack workspace from `GET /status`. */
+export interface SlackConnectedWorkspace {
+  slackTeamId: string;
+  /** Workspace name; absent on older backends, null on pre-existing rows. */
+  slackTeamName?: string | null;
+  slackUserId: string;
+  connectedAt: string;
+}
+
+/** One provisioned managed Slack app from `GET /status` (no token material). */
+export interface SlackManagedAppInfo {
+  slackAppId: string;
+  slackTeamId: string;
+  slug: string;
+  env: string;
+  installStatus: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SlackProvisionStatus {
+  workspaces: SlackConnectedWorkspace[];
+  apps: SlackManagedAppInfo[];
+}
+
+export type SlackAppIconContentType = "image/png" | "image/jpeg" | "image/gif";
+
+/** Icon source for `setAppIcon`: an https image URL or a base64 file. */
+export type SlackAppIconInput =
+  | { url: string }
+  | { base64: string; contentType: SlackAppIconContentType };
+
+/**
+ * Outcome of `POST /apps`. Credentials are returned exactly once and never
+ * persisted server-side — the caller owns storing them. `appToken` can be
+ * absent when Slack's install response omitted the app-level token.
+ * `oauthAuthorizeUrl` is only minted on a fresh app create, so an update
+ * that lands in admin approval omits it.
+ */
+export type SlackAppProvisionResult =
+  | {
+      status: "installed";
+      appId: string;
+      botToken: string;
+      appToken?: string;
+      /** Present when the provision requested an icon (best-effort outcome). */
+      iconStatus?: "set" | "failed";
+    }
+  | {
+      status: "pending_admin_approval";
+      appId: string;
+      oauthAuthorizeUrl?: string;
+      iconStatus?: "set" | "failed";
+    };
+
+export class SlackProvisionApiError extends Error {
+  readonly status: number;
+  /** Stable backend error code (`not_connected`, `ratelimited`, …). */
+  readonly code?: string;
+  /** Seconds to wait before retrying (from 429 responses). */
+  readonly retryAfterSeconds?: number;
+  /** Drifted manifest paths (from `manifest_drift` 409 bodies). */
+  readonly changedPaths?: string[];
+
+  constructor(
+    message: string,
+    options: {
+      status: number;
+      code?: string;
+      retryAfterSeconds?: number;
+      changedPaths?: string[];
+    }
+  ) {
+    super(message);
+    this.name = "SlackProvisionApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+    this.changedPaths = options.changedPaths;
+  }
+}
+
+// ============================================================================
+// Response shapes (backend agentServeSlackEndpoints route bodies).
+// Interfaces are hand-written (the package compiles with
+// --isolatedDeclarations, so exported types cannot be z.infer of an
+// unannotated schema); the zod schemas below stay module-internal.
+// ============================================================================
+
+// All response schemas are `.passthrough()` so unknown fields from a newer
+// backend flow through untouched instead of breaking the parse.
+const statusResponseSchema = z
+  .object({
+    workspaces: z.array(
+      z
+        .object({
+          slackTeamId: z.string(),
+          slackTeamName: z.string().nullish(),
+          slackUserId: z.string(),
+          connectedAt: z.string(),
+        })
+        .passthrough()
+    ),
+    apps: z.array(
+      z
+        .object({
+          slackAppId: z.string(),
+          slackTeamId: z.string(),
+          slug: z.string(),
+          env: z.string(),
+          installStatus: z.string(),
+          createdAt: z.string(),
+          updatedAt: z.string(),
+        })
+        .passthrough()
+    ),
+  })
+  .passthrough();
+
+const connectResponseSchema = z
+  .object({
+    url: z.string().min(1),
+  })
+  .passthrough();
+
+const provisionResponseSchema = z.discriminatedUnion("status", [
+  z
+    .object({
+      status: z.literal("installed"),
+      appId: z.string(),
+      botToken: z.string(),
+      appToken: z.string().optional(),
+      iconStatus: z.enum(["set", "failed"]).optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      status: z.literal("pending_admin_approval"),
+      appId: z.string(),
+      oauthAuthorizeUrl: z.string().optional(),
+      iconStatus: z.enum(["set", "failed"]).optional(),
+    })
+    .passthrough(),
+]);
+
+const deleteResponseSchema = z
+  .object({
+    deleted: z.boolean(),
+  })
+  .passthrough();
+
+const setIconResponseSchema = z
+  .object({
+    ok: z.boolean(),
+  })
+  .passthrough();
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export interface AgentServeSlackClientOptions {
+  backendUrl: string;
+  apiKey: string;
+  /** Test seam; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export class AgentServeSlackClient {
+  private readonly backendUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: AgentServeSlackClientOptions) {
+    this.backendUrl = options.backendUrl.endsWith("/")
+      ? options.backendUrl.slice(0, -1)
+      : options.backendUrl;
+    this.apiKey = options.apiKey;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /** Manager-connected workspaces + the managed-app inventory. */
+  async status(teamId: number): Promise<SlackProvisionStatus> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agent-serve/slack/status?teamId=${teamId}`,
+      context: { verb: "read Slack provisioning status" },
+    });
+    return statusResponseSchema.parse(raw);
+  }
+
+  /**
+   * Mint the browser consent URL for the Slack manager grant. After the
+   * user approves it, the workspace shows up in {@link status}.
+   */
+  async connect(teamId: number): Promise<string> {
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agent-serve/slack/connect",
+      body: { teamId },
+      context: { verb: "start the Slack workspace connect" },
+    });
+    return connectResponseSchema.parse(raw).url;
+  }
+
+  /**
+   * Provision (create or update) and install one managed Slack app for
+   * (slackTeamId, slug, env). Expected failures throw
+   * {@link SlackProvisionApiError} with a stable `code`.
+   */
+  async provisionApp(args: {
+    teamId: number;
+    slackTeamId: string;
+    slug: string;
+    env: SlackAppEnv;
+    /** Full Slack app manifest JSON string. */
+    manifest: string;
+    /** Icon URL, applied best-effort by the backend after the install. */
+    icon?: { url: string };
+    /** Overwrite manifest edits made in Slack (skips the drift check). */
+    force?: boolean;
+  }): Promise<SlackAppProvisionResult> {
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agent-serve/slack/apps",
+      body: {
+        teamId: args.teamId,
+        slackTeamId: args.slackTeamId,
+        slug: args.slug,
+        env: args.env,
+        manifest: args.manifest,
+        icon: args.icon,
+        force: args.force,
+      },
+      context: { verb: "provision the Slack app" },
+    });
+    return provisionResponseSchema.parse(raw);
+  }
+
+  /** Delete the Slack app and its inventory row. */
+  async deleteApp(args: { teamId: number; slackAppId: string }): Promise<void> {
+    const raw = await this.request({
+      method: "DELETE",
+      path: `/internal/agent-serve/slack/apps/${encodeURIComponent(args.slackAppId)}?teamId=${args.teamId}`,
+      context: { verb: "delete the Slack app" },
+    });
+    deleteResponseSchema.parse(raw);
+  }
+
+  /** Set the app's icon: an https image URL or a base64 png/jpeg/gif ≤512KB. */
+  async setAppIcon(args: {
+    teamId: number;
+    slackAppId: string;
+    icon: SlackAppIconInput;
+  }): Promise<void> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agent-serve/slack/apps/${encodeURIComponent(args.slackAppId)}/icon`,
+      body: { teamId: args.teamId, icon: args.icon },
+      context: { verb: "set the Slack app icon" },
+    });
+    setIconResponseSchema.parse(raw);
+  }
+
+  private async request(args: {
+    method: "GET" | "POST" | "DELETE";
+    path: string;
+    body?: unknown;
+    context: { verb: string };
+  }): Promise<unknown> {
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      authorization: `Bearer ${this.apiKey}`,
+    };
+    if (args.body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.backendUrl}${args.path}`, {
+        method: args.method,
+        headers,
+        body: args.body === undefined ? undefined : JSON.stringify(args.body),
+        signal: AbortSignal.timeout(60_000),
+      });
+    } catch (error) {
+      throw new SlackProvisionApiError(
+        `Could not reach the Cursor backend at ${this.backendUrl}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { status: 0 }
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw mapErrorResponse(response, text, args.context);
+    }
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new SlackProvisionApiError(
+        `The Cursor backend returned a non-JSON response to ${args.context.verb}.`,
+        { status: response.status }
+      );
+    }
+  }
+}
+
+// ============================================================================
+// Error mapping (HTTP → actionable human messages, stable codes kept)
+// ============================================================================
+
+function parseErrorBody(bodyText: string): {
+  error?: string;
+  code?: string;
+  retryAfterSeconds?: number;
+  changedPaths?: string[];
+} {
+  let parsed: {
+    error?: unknown;
+    code?: unknown;
+    retryAfterSeconds?: unknown;
+    changedPaths?: unknown;
+  };
+  try {
+    parsed = JSON.parse(bodyText) as typeof parsed;
+  } catch {
+    return {};
+  }
+  return {
+    error:
+      typeof parsed.error === "string" && parsed.error !== ""
+        ? parsed.error
+        : undefined,
+    code:
+      typeof parsed.code === "string" && parsed.code !== ""
+        ? parsed.code
+        : undefined,
+    retryAfterSeconds:
+      typeof parsed.retryAfterSeconds === "number"
+        ? parsed.retryAfterSeconds
+        : undefined,
+    changedPaths:
+      Array.isArray(parsed.changedPaths) &&
+      parsed.changedPaths.every(
+        (path): path is string => typeof path === "string"
+      )
+        ? parsed.changedPaths
+        : undefined,
+  };
+}
+
+function mapErrorResponse(
+  response: Response,
+  bodyText: string,
+  context: { verb: string }
+): SlackProvisionApiError {
+  const body = parseErrorBody(bodyText);
+  const serverError = body.error;
+  switch (response.status) {
+    case 401:
+      return new SlackProvisionApiError(
+        "The Cursor API key was rejected. Run `agentkit login` again or update CURSOR_API_KEY.",
+        { status: 401 }
+      );
+    case 403:
+      return new SlackProvisionApiError(
+        `${serverError ?? "Not authorized"} — Slack provisioning needs team-admin permission and the cloud-agent entitlement on that team.`,
+        { status: 403 }
+      );
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new SlackProvisionApiError(
+          `Agent Serve Slack API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          { status: 404 }
+        );
+      }
+      // The gate-off body is exactly {error: "Not found"}; anything else
+      // (e.g. "App not found" on delete) is a real not-found to surface.
+      if (serverError !== undefined && serverError !== "Not found") {
+        return new SlackProvisionApiError(serverError, {
+          status: 404,
+          code: body.code,
+        });
+      }
+      return new SlackProvisionApiError(
+        `Not found — Cursor's "Add to Slack" provisioning (the agent_serve_slack_provisioning feature gate) is not enabled for this account yet.`,
+        { status: 404 }
+      );
+    }
+    case 429: {
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfterSeconds =
+        retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
+          ? Number(retryAfterHeader)
+          : body.retryAfterSeconds;
+      return new SlackProvisionApiError(
+        `${serverError ?? "Rate limited"}${
+          retryAfterSeconds === undefined
+            ? ""
+            : ` — retry in ${retryAfterSeconds}s`
+        }`,
+        { status: 429, code: body.code ?? "ratelimited", retryAfterSeconds }
+      );
+    }
+    default:
+      return new SlackProvisionApiError(
+        serverError ??
+          `The ${context.verb} request failed (${response.status}): ${
+            bodyText.slice(0, 300) || "(empty body)"
+          }`,
+        {
+          status: response.status,
+          code: body.code,
+          changedPaths: body.changedPaths,
+        }
+      );
+  }
+}