@cursor/july 0.1.90 → 0.1.91

package/src/internal/cli-deploy.ts

@@ -28,6 +28,7 @@ import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   type AgentkitDeployAccepted,
   type AgentkitDeployStatus,
+  type AgentkitStopAccepted,
   AgentServeDeployClient,
   type DeleteAccepted,
   type DeployAccepted,
@@ -1187,11 +1188,25 @@ export async function cmdStop(
   if (typeof ctx === "number") {
     return ctx;
   }
-  let accepted: StopAccepted;
+  // Stop takes only a slug, so there is no manifest to dispatch on (unlike
+  // deploy). The v2 agentkit 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 agentkit mount) falls back to the v1 stop.
+  let architecture: "v1" | "v2" = "v2";
+  let accepted: StopAccepted | AgentkitStopAccepted;
   try {
-    accepted = await ctx.client.stopDeployment({ teamId: ctx.teamId, slug });
+    accepted = await ctx.client.stopAgentkit({ teamId: ctx.teamId, slug });
   } catch (error) {
-    return renderApiError(error, ctx.err);
+    if (!(error instanceof DeployApiError) || error.status !== 404) {
+      return renderApiError(error, ctx.err);
+    }
+    try {
+      accepted = await ctx.client.stopDeployment({ teamId: ctx.teamId, slug });
+      architecture = "v1";
+    } catch (v1Error) {
+      return renderApiError(v1Error, ctx.err);
+    }
   }
   if (ctx.noWait) {
     if (ctx.json) {
@@ -1201,11 +1216,16 @@ export async function cmdStop(
     }
     return 0;
   }
-  let detail: DeploymentDetail;
+  let detail: DeploymentDetail | AgentkitDeployStatus;
   try {
-    detail = await pollUntil(ctx, slug, new Set(["stopped"]), () =>
-      ctx.client.getDeployment({ teamId: ctx.teamId, slug })
-    );
+    detail =
+      architecture === "v2"
+        ? await pollUntil(ctx, slug, new Set(["stopped"]), () =>
+            ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug })
+          )
+        : await pollUntil(ctx, slug, new Set(["stopped"]), () =>
+            ctx.client.getDeployment({ teamId: ctx.teamId, slug })
+          );
   } catch (error) {
     return renderApiError(error, ctx.err);
   }

package/src/internal/cursor-agent-template.ts

@@ -6,6 +6,7 @@ const TEMPLATE_NAMES = [
   "agentic-owners",
   "demo",
   "pr-autofixer",
+  "security-help",
   "security-reviewer",
   "triage-linear",
   "triage-jira",

package/src/internal/deploy-client.ts

@@ -255,6 +255,17 @@ export interface AgentkitDeployStatus {
 export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> =
   new Set(["running", "failed", "stopped"]);
 
+/**
+ * `POST /internal/agentkit/deployments/:slug/stop` 202 body. Like v1
+ * {@link StopAccepted} but keyed by catalog ids instead of the numeric
+ * deployment row id.
+ */
+export interface AgentkitStopAccepted {
+  applicationId: string;
+  releaseId: string;
+  status: string;
+}
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -332,6 +343,14 @@ const agentkitDeployStatusSchema = z
   })
   .passthrough();
 
+const agentkitStopAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    status: z.string(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -602,6 +621,22 @@ export class AgentServeDeployClient {
     return agentkitDeployStatusSchema.parse(raw);
   }
 
+  /**
+   * Stop a v2 deployment (`POST /internal/agentkit/deployments/:slug/stop`).
+   * 202 means accepted; poll {@link getAgentkitDeploy} until `stopped`.
+   */
+  async stopAgentkit(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitStopAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentkit/deployments/${encodeURIComponent(args.slug)}/stop?teamId=${args.teamId}`,
+      context: { verb: "stop", slug: args.slug },
+    });
+    return agentkitStopAcceptedSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",
@@ -888,8 +923,12 @@ function mapErrorResponse(
       );
     }
     case 409:
+      // The server's 409 body distinguishes real conflicts (CAS races,
+      // "still deploying", architecture-v2 slugs on the v1 surface); keep
+      // its message when present.
       return new DeployApiError(
-        `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,
+        serverError ??
+          `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,
         409
       );
     case 429: {

package/src/internal/deploy-manifest.ts

@@ -40,7 +40,10 @@ import {
   handshakeChannelContinuation,
 } from "./continuation-channel.js";
 import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
-import { projectInfo } from "./discovery.js";
+import {
+  projectInfo,
+  runtimeArchitectureCompatibilityError,
+} from "./discovery.js";
 import { packageVersion } from "./distribution.js";
 
 export const DEPLOY_MANIFEST_VERSION: 1 = 1;
@@ -125,6 +128,12 @@ export function buildAgentDeployManifest(
   project: AgentProject,
   options?: { nowMs?: number; cliVersion?: string }
 ): AgentDeployManifestV1 {
+  const runtimeArchitectureError = runtimeArchitectureCompatibilityError(
+    project.agent
+  );
+  if (runtimeArchitectureError !== undefined) {
+    throw new Error(runtimeArchitectureError);
+  }
   applyAgentContinuationDefaults(project);
   const channels = project.channels.map((channel) => {
     const handshake = handshakeChannelContinuation(channel);

package/src/internal/discovery.ts

@@ -524,6 +524,17 @@ async function loadAgent(
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
   const architecture = resolveArchitecture(ctx, agentDir, config?.architecture);
+  const runtimeArchitectureError = runtimeArchitectureCompatibilityError({
+    runtime,
+    architecture,
+  });
+  if (runtimeArchitectureError !== undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message: runtimeArchitectureError,
+    });
+  }
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -570,6 +581,15 @@ async function loadAgent(
   };
 }
 
+export function runtimeArchitectureCompatibilityError(agent: {
+  runtime: AgentRuntime;
+  architecture?: AgentArchitecture;
+}): string | undefined {
+  return agent.architecture === "v2" && agent.runtime === "grokbot"
+    ? 'architecture: "v2" cannot use runtime: "grokbot": the grokbot runtime executes through the signed-in account\'s hosted /v0/grokbot box, not a deployment-scoped v2 runtime.'
+    : undefined;
+}
+
 function resolveArchitecture(
   ctx: DiscoveryContext,
   agentDir: string,

package/src/internal/http-channel.ts

@@ -7,8 +7,8 @@
  * Continuation semantics: `POST /v1/session` returns a `continuationToken`;
  * each accepted follow-up rotates it and returns the replacement, and a
  * stale token is rejected with 409. Follow-ups address any chat session by
- * id (including custom channels such as `drive`) when the token matches
- * that session's channel + key; task sessions stay fire-and-forget.
+ * id (including custom channels such as `drive`) when the token matches its
+ * active HTTP follow-up key; task sessions stay fire-and-forget.
  */
 
 import type {
@@ -20,11 +20,7 @@ import type {
   SessionRecord,
 } from "../types.js";
 import { samePrincipal } from "./auth.js";
-import {
-  formatContinuationToken,
-  newContinuationKey,
-  parseContinuationToken,
-} from "./ids.js";
+import { formatContinuationToken, parseContinuationToken } from "./ids.js";
 import { isLoopbackAddress } from "./net.js";
 import type { ServerRoute } from "./router.js";
 import {
@@ -32,7 +28,6 @@ import {
   ApprovalNotFoundError,
   HTTP_CHANNEL_ID,
   SessionAuthError,
-  SessionBusyError,
   type SessionEngine,
 } from "./session-engine.js";
 import {
@@ -143,10 +138,8 @@ export function buildHttpChannelRoutes(args: {
           `Unknown session ${sessionId}.`
         );
       }
-      // Playground (and other HTTP clients) may follow up on any chat
-      // session — including custom channels like `drive` — using that
-      // session's own continuation token. Task/schedule sessions stay
-      // fire-and-forget.
+      // HTTP can follow any chat session. Its credential is separate from the
+      // owning channel's continuation key.
       if (record.mode === "task") {
         return errorResponse(
           409,
@@ -178,12 +171,7 @@ export function buildHttpChannelRoutes(args: {
         );
       }
       const presented = parseContinuationToken(body.continuationToken);
-      if (
-        presented === null ||
-        presented.channelId !== record.channelId ||
-        record.continuationKey === null ||
-        presented.key !== record.continuationKey
-      ) {
+      if (presented === null) {
         return errorResponse(
           409,
           "stale_continuation_token",
@@ -192,34 +180,19 @@ export function buildHttpChannelRoutes(args: {
       }
 
       const message = await transformMessage(body.message, ctx.auth);
-      try {
-        // Continue as the session owner after the HTTP ownership gate so
-        // `--dev` relaxed reads can follow up on channel-owned sessions
-        // (drive/slack/…) without failing SessionAuthError.
-        await engine.send(record.channelId, message, {
-          auth: record.auth,
-          continuationToken: record.continuationKey,
-        });
-      } catch (error) {
-        if (error instanceof SessionBusyError) {
-          return errorResponse(
-            409,
-            "session_busy",
-            "A turn is already running; wait for session.waiting before sending a follow-up."
-          );
-        }
-        throw error;
+      const rotated = await engine.followUpHttp(sessionId, presented, message);
+      if (rotated === undefined) {
+        return errorResponse(
+          409,
+          "stale_continuation_token",
+          "The continuation token does not address this session's active continuation."
+        );
       }
-
-      // Rotate only after the message is accepted so a rejected send leaves
-      // the caller's token valid for retry.
-      const rotated = newContinuationKey();
-      await engine.setContinuationToken(sessionId, rotated);
       return jsonResponse(
         {
           ok: true,
           sessionId,
-          continuationToken: formatContinuationToken(record.channelId, rotated),
+          continuationToken: formatContinuationToken(HTTP_CHANNEL_ID, rotated),
         },
         { headers: { [SESSION_ID_HEADER]: sessionId } }
       );

package/src/internal/init-project.ts

@@ -76,6 +76,7 @@ const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
+  "security-help": { dir: "security-help" },
   "security-reviewer": { dir: "security-reviewer" },
   "triage-linear": { dir: "triage", overlay: "linear" },
   "triage-jira": { dir: "triage", overlay: "jira" },
@@ -709,6 +710,7 @@ Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
+  npx ${PACKAGE_NAME} init ./security-help --template security-help   # answer security questions in Slack
   npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues
   npx ${PACKAGE_NAME} init ./my-triage --template triage-jira     # comment on Jira issues
   npx ${PACKAGE_NAME} init ./my-owners --template agentic-owners  # review PRs via owners policies

package/src/internal/session-engine.ts

@@ -925,6 +925,51 @@ export class SessionEngine {
     return this.channelSession(record.sessionId, record, true, false, since);
   }
 
+  /**
+   * Atomically validate and rotate an HTTP follow-up credential, then admit
+   * the message to its exact session without changing the owning channel key.
+   */
+  async followUpHttp(
+    sessionId: string,
+    token: { channelId: string; key: string },
+    message: string
+  ): Promise<string | undefined> {
+    const next = newContinuationKey();
+    const stale = new Error("stale HTTP continuation");
+    let previous: string | undefined;
+    try {
+      await this.updateRecord(sessionId, (record) => {
+        const expectedChannel =
+          record.httpContinuationKey === undefined
+            ? record.channelId
+            : HTTP_CHANNEL_ID;
+        const expectedKey =
+          record.httpContinuationKey ?? record.continuationKey;
+        if (token.channelId !== expectedChannel || token.key !== expectedKey) {
+          throw stale;
+        }
+        previous = record.httpContinuationKey;
+        return { ...record, httpContinuationKey: next };
+      });
+    } catch (error) {
+      if (error === stale) {
+        return undefined;
+      }
+      throw error;
+    }
+    try {
+      await this.startTurn(sessionId, message);
+      return next;
+    } catch (error) {
+      await this.updateRecord(sessionId, (record) =>
+        record.httpContinuationKey === next
+          ? { ...record, httpContinuationKey: previous }
+          : record
+      );
+      throw error;
+    }
+  }
+
   /** Whether a continuation token already maps to a session on this channel. */
   async hasContinuationSession(
     channelId: string,
@@ -3315,12 +3360,17 @@ export class SessionEngine {
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
           continuationToken:
-            record.continuationKey === null
-              ? null
-              : formatContinuationToken(
-                  record.channelId,
-                  record.continuationKey
-                ),
+            record.httpContinuationKey !== undefined
+              ? formatContinuationToken(
+                  HTTP_CHANNEL_ID,
+                  record.httpContinuationKey
+                )
+              : record.continuationKey === null
+                ? null
+                : formatContinuationToken(
+                    record.channelId,
+                    record.continuationKey
+                  ),
           externalUrl: links.slack ?? links.github,
           prUrl: links.github,
         };
@@ -3606,8 +3656,8 @@ export class SessionEngine {
       ...current,
       continuationKey: token,
     }));
-    // Keep armed reminders addressed at the conversation across rotation
-    // (the built-in HTTP channel rotates after every follow-up).
+    // Keep armed reminders addressed at the conversation across channel
+    // continuation rotation.
     if (
       previous?.continuationKey != null &&
       token !== null &&

package/src/types.ts

@@ -1201,10 +1201,8 @@ export type ConnectionConfig = (
    *
    * Derive the identity from durable session facts — `session.auth`,
    * `session.id`, or your channel's own session state. Do **not** key it
-   * off `session.continuationKey`: the HTTP channel rotates the
-   * continuation key after every accepted follow-up, so a tenant mapping
-   * keyed on it silently breaks mid-conversation. (Channels that mint
-   * stable, parseable tokens by design are the exception.)
+   * off `session.continuationKey`: it is a channel routing key, and channels
+   * may re-key it independently of the authenticated principal.
    *
    * Works attached or advertised. Advertised connections
    * ({@link advertiseTools}) open per-operation clients with the
@@ -1593,6 +1591,11 @@ export interface SessionRecord {
   abs?: Record<string, string | null>;
   /** Channel-local continuation key; null when the session is not addressable. */
   continuationKey: string | null;
+  /**
+   * Rotating HTTP follow-up credential for a channel-owned session.
+   * Omitted until HTTP accepts the first follow-up.
+   */
+  httpContinuationKey?: string;
   auth: AuthContext | null;
   title?: string;
   channelState?: JsonValue;
@@ -1668,7 +1671,7 @@ export interface SessionSummary {
   queued?: boolean;
   createdAt: string;
   updatedAt: string;
-  /** `<channelId>:<key>` wire token, or null when not addressable. */
+  /** Active wire token for HTTP follow-ups, or null when not addressable. */
   continuationToken: string | null;
   /**
    * Conversation permalink (Slack thread, else GitHub PR).

package/templates/security-help/README.md

@@ -0,0 +1,37 @@
+# Security help
+
+Answers security questions in Slack from your FAQ files and takes a first
+look when someone pastes a GitHub pull request.
+
+```bash
+npx @cursor/july init ./security-help --template security-help
+```
+
+`init` asks which repos it may read. Skip the prompt with
+`--var repos=owner/repo`.
+
+## Run
+
+```bash
+agent-sdk login
+agent-sdk slack create --name "Security Help" --channel-posts
+agent-sdk dev
+```
+
+Slack is a dedicated bot (`@Security Help`). Mentions, DMs, and channel
+watch go through that app. GitHub reads use your Cursor GitHub connection
+for the repos in `agent/lib/repos.ts`. Paste a PR URL in Slack, or replay
+one in the playground.
+
+## Edit
+
+- `agent/lib/repos.ts`: repos it may read
+- `agent/channels/slack.ts`: channel ids to watch (`watch`)
+- `agent/knowledge/faq/`: answers for your company
+- `agent/skills/`: how to look at a PR, a leak, or an access ask
+- `agent/instructions.md`: routing
+
+`--channel-posts` is required to watch channels. Mentions and DMs work
+without it.
+
+`agent-sdk eval` runs three smoke turns and writes nothing to Slack or GitHub.

package/templates/security-help/agent/agent.ts

@@ -0,0 +1,18 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  name: "Security Help",
+  description:
+    "Answers security questions in Slack and takes a first look at a GitHub pull request.",
+  model: {
+    id: "grok-4.6",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  },
+  tools: ["read", "grep"],
+  local: {
+    sandbox: true,
+  },
+});

package/templates/security-help/agent/channels/github.ts

@@ -0,0 +1,13 @@
+import { githubChannel } from "@cursor/july/channels/github";
+import { REPOS } from "../lib/repos.js";
+
+export default githubChannel({
+  webhookEvents: [],
+  deliverReplies: false,
+  cursorAccount: {
+    repos: REPOS,
+    permissions: "read",
+  },
+  onPullRequest: () => null,
+  onComment: () => null,
+});

package/templates/security-help/agent/channels/slack.ts

@@ -0,0 +1,89 @@
+import {
+  defaultSlackAuth,
+  extractGithubPrRef,
+  type SlackMessageHandler,
+  slackChannel,
+} from "@cursor/july/channels/slack";
+import { loadPrFiles } from "../lib/pr-first-pass.js";
+import { REPOS, watches } from "../lib/repos.js";
+
+const watch: string[] = [];
+
+const clear = {
+  "pr/meta.md": "",
+  "pr/diff.patch": "",
+  "pr/head.sha": "",
+};
+
+const handleSlack: SlackMessageHandler = async (ctx, message) => {
+  const auth = defaultSlackAuth(message, ctx);
+  if (auth === null) {
+    return null;
+  }
+
+  const pr = extractGithubPrRef(message.markdown);
+  if (pr === undefined) {
+    return { auth };
+  }
+
+  const title = `Security Help ${pr.label}`;
+  const fullName = `${pr.owner}/${pr.repo}`;
+  if (!watches(fullName)) {
+    return {
+      auth,
+      title,
+      workspaceFiles: clear,
+      context: [
+        `Security help can only fetch ${REPOS.join(", ")} (got ${fullName}).`,
+      ],
+    };
+  }
+
+  const loaded = await loadPrFiles({
+    github: ctx.host.github,
+    ref: pr,
+  });
+  return {
+    auth,
+    title,
+    workspaceFiles: loaded ?? clear,
+    context:
+      loaded === undefined
+        ? ["Could not fetch the pull request. Connect GitHub or check the URL."]
+        : undefined,
+  };
+};
+
+export default slackChannel({
+  envPrefix: "SECURITY_HELP",
+  policy: {
+    blockExternals: true,
+  },
+  engagement: {
+    channelPosts:
+      watch.length === 0
+        ? undefined
+        : {
+            allow: watch,
+            posts: "top-level" as const,
+          },
+  },
+  onAppMention: handleSlack,
+  onDirectMessage: handleSlack,
+  onChannelPost: watch.length === 0 ? undefined : handleSlack,
+  suggestedPrompts: [
+    {
+      title: "Look at a PR",
+      message: "First look at https://github.com/owner/repo/pull/1",
+    },
+    {
+      title: "How urgent",
+      message: "How urgent is this?",
+    },
+    {
+      title: "Ask for context",
+      message: "What else do we need before answering?",
+    },
+  ],
+  suggestedPromptsTitle: "Ask security",
+});

package/templates/security-help/agent/instructions.md

@@ -0,0 +1,20 @@
+# Security help
+
+Answer security questions in Slack from the FAQ and skills.
+If you do not know, say so and ask a human.
+
+Open the skill or FAQ for the ask. Those files are under `agent/skills/` and `agent/knowledge/faq/`.
+
+| If the ask is about | Open |
+| --- | --- |
+| A GitHub pull request | `agent/skills/security-pr-first-pass.md` |
+| An access request | `agent/skills/access-request.md` |
+| A leak, alert, or incident | `agent/skills/security-playbooks.md` |
+| Who can approve, privacy, or policy | `agent/knowledge/faq/approvals.md` |
+| Phishing text, email, or a call | `agent/knowledge/faq/phishing.md` |
+| Which team or channel owns a request | `agent/knowledge/faq/channels.md` |
+| Another security question | `agent/skills/security-first-pass.md` |
+
+A pull request earlier in the thread is not this one.
+
+If you say an incident is over or a system is safe, show why. Looking at a pull request is not that.

package/templates/security-help/agent/knowledge/faq/approvals.md

@@ -0,0 +1,5 @@
+# Approvals
+
+Who can say yes depends on the request. If this file does not name an owner, ask a human for that topic.
+
+Privacy questions (training, retention, where prompts sit) go to a privacy or security person.

package/templates/security-help/agent/knowledge/faq/channels.md

@@ -0,0 +1,6 @@
+# Channels
+
+`#security` is for security questions and phishing reports.
+
+Name the channel that owns SaaS access, identity groups, laptops, and billing.
+Until you do, say you do not know which team owns that request.

package/templates/security-help/agent/knowledge/faq/phishing.md

@@ -0,0 +1,10 @@
+# Phishing
+
+`#security` is where phishing and unexpected texts, emails, or calls go.
+If the thread is already about that, keep it there.
+
+Leave the original message alone. Do not reply, click, or send a 2FA code on it.
+Confirm unknown texts or calls over Slack or in person before acting.
+
+If an account looks compromised, they should lock it now and wait for a human.
+If security already gave a verdict in-thread, follow that.