@cursor/july 0.1.89 → 0.1.91

package/src/internal/cursor/backend-client.ts

@@ -296,6 +296,12 @@ async function parseRpcResponse(
 export interface CursorBackendClientOptions {
   backendUrl: string;
   apiKey: string;
+  /**
+   * Re-read the key on each authenticated call. Hosted freeze listens
+   * unsigned and the binder drops the key after restore; a constructor-frozen
+   * key would miss that bind.
+   */
+  getApiKey?: () => string;
   logger?: (line: string) => void;
   /** Test seam; defaults to global fetch. */
   fetchImpl?: typeof fetch;
@@ -303,21 +309,26 @@ export interface CursorBackendClientOptions {
 
 export class CursorBackendClient {
   private readonly backendUrl: string;
-  private readonly apiKey: string;
+  private readonly resolveApiKey: () => string;
   private readonly logger: (line: string) => void;
   private readonly fetchImpl: typeof fetch;
   private token: { value: string; expiresAtMs: number } | undefined;
   private tokenExchange: Promise<string> | undefined;
+  private lastExchangedApiKey: string | undefined;
 
   constructor(options: CursorBackendClientOptions) {
     this.backendUrl = options.backendUrl.endsWith("/")
       ? options.backendUrl.slice(0, -1)
       : options.backendUrl;
-    this.apiKey = options.apiKey;
+    this.resolveApiKey = options.getApiKey ?? (() => options.apiKey);
     this.logger = options.logger ?? (() => {});
     this.fetchImpl = options.fetchImpl ?? fetch;
   }
 
+  private currentApiKey(): string {
+    return this.resolveApiKey().trim();
+  }
+
   /** Who this API key acts as. */
   async getMe(): Promise<CursorIdentity> {
     return getMeResponseSchema.parse(await this.rpc("GetMe", {}));
@@ -443,7 +454,7 @@ export class CursorBackendClient {
           method: "POST",
           headers: {
             "content-type": "application/json",
-            authorization: `Bearer ${this.apiKey}`,
+            authorization: `Bearer ${this.currentApiKey()}`,
           },
           body: JSON.stringify({ repos: [...repos], permissions }),
           signal: AbortSignal.timeout(30_000),
@@ -525,6 +536,18 @@ export class CursorBackendClient {
    * when none is cached or it is near expiry.
    */
   private getAccessToken(): Promise<string> {
+    const apiKey = this.currentApiKey();
+    if (apiKey === "") {
+      return Promise.reject(
+        new CursorBackendError(
+          "The Cursor backend client has no API key yet. Bind CURSOR_API_KEY or CURSOR_API_KEY_FILE before authenticated calls."
+        )
+      );
+    }
+    if (this.lastExchangedApiKey !== apiKey) {
+      this.token = undefined;
+      this.tokenExchange = undefined;
+    }
     if (
       this.token !== undefined &&
       Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS
@@ -541,13 +564,14 @@ export class CursorBackendClient {
   }
 
   private async exchangeApiKey(): Promise<string> {
+    const apiKey = this.currentApiKey();
     let response: Response;
     try {
       response = await this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
         method: "POST",
         headers: {
           "content-type": "application/json",
-          authorization: `Bearer ${this.apiKey}`,
+          authorization: `Bearer ${apiKey}`,
         },
         body: "{}",
         signal: AbortSignal.timeout(30_000),
@@ -576,6 +600,7 @@ export class CursorBackendClient {
       value: body.data.accessToken,
       expiresAtMs: jwtExpiryMs(body.data.accessToken),
     };
+    this.lastExchangedApiKey = apiKey;
     this.logger("[agent-sdk] cursor account: minted a fresh access token");
     return body.data.accessToken;
   }

package/src/internal/cursor/credentials.ts

@@ -9,6 +9,10 @@
  *   dashboard-revocable user API key — only the key is stored.
  * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
  *   CI and hosted deployments stay env-driven.
+ * - `CURSOR_API_KEY_FILE` (or the hosted default path) is next: freeze bind
+ *   drops the key at task time without restarting July.
+ * - Stored `july login` is last. Same order for hosted and self-hosted:
+ *   option → env → file → login.
  *
  * There is deliberately no session-token storage, refresh-token rotation, or
  * cross-tool credential sharing here: short-lived access tokens are minted
@@ -16,6 +20,7 @@
  */
 
 import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -43,10 +48,11 @@ export function cursorBackendUrl(): string {
 
 /**
  * External API base URL for routes served only by the external-api
- * microlith (`/internal/agent-serve/*`, engine aliases). In production
- * these are mounted on api.cursor.com and 404 on api2.cursor.sh, so the
- * deploy surface needs its own default. `CURSOR_API_BASE_URL` still
- * overrides everything for local dev, where one server mounts all routes.
+ * microlith (`/internal/agent-serve/*`, `/v0/grokbot/*`, engine aliases).
+ * In production these are mounted on api.cursor.com and 404 on
+ * api2.cursor.sh, so the deploy surface needs its own default.
+ * `CURSOR_API_BASE_URL` still overrides everything for local dev, where
+ * one server mounts all routes.
  */
 export function cursorExternalApiUrl(): string {
   return trimTrailingSlash(
@@ -100,20 +106,13 @@ export function credentialsFilePath(): string {
   return join(configDirPath(), "credentials.json");
 }
 
-export async function readStoredCredentials(): Promise<
-  StoredCredentials | undefined
-> {
-  let raw: string;
-  try {
-    raw = await readFile(credentialsFilePath(), "utf8");
-  } catch {
-    return undefined;
-  }
+function parseStoredCredentialsJson(
+  raw: string
+): StoredCredentials | undefined {
   let parsed: unknown;
   try {
     parsed = JSON.parse(raw) as unknown;
   } catch {
-    // Corrupt file — treat as signed out; login rewrites it.
     return undefined;
   }
   const credentials = storedCredentialsSchema.safeParse(parsed);
@@ -126,6 +125,28 @@ export async function readStoredCredentials(): Promise<
   };
 }
 
+export function readStoredCredentialsSync(): StoredCredentials | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(credentialsFilePath(), "utf8");
+  } catch {
+    return undefined;
+  }
+  return parseStoredCredentialsJson(raw);
+}
+
+export async function readStoredCredentials(): Promise<
+  StoredCredentials | undefined
+> {
+  let raw: string;
+  try {
+    raw = await readFile(credentialsFilePath(), "utf8");
+  } catch {
+    return undefined;
+  }
+  return parseStoredCredentialsJson(raw);
+}
+
 export async function writeStoredCredentials(
   credentials: StoredCredentials
 ): Promise<void> {
@@ -148,10 +169,10 @@ export async function clearStoredCredentials(): Promise<boolean> {
 }
 
 // ============================================================================
-// Resolution (option > env > stored login)
+// Resolution (option > env > file > stored login)
 // ============================================================================
 
-export type ApiKeySource = "option" | "env" | "login";
+export type ApiKeySource = "option" | "env" | "file" | "login";
 
 export interface ResolvedApiKey {
   apiKey: string;
@@ -160,15 +181,43 @@ export interface ResolvedApiKey {
 }
 
 /**
- * Resolve the account API key for `backendUrl` (defaults to the active
- * backend): explicit option → `CURSOR_API_KEY` → stored login. A stored key
- * minted against a different backend is ignored rather than sent to the
- * wrong host.
+ * Hosted task-bind path. Not a secret: the snapshot may name this path.
+ * The binder writes the key here after restore; July re-reads on each use.
+ * Override with `CURSOR_API_KEY_FILE`. A missing file is unsigned — self-hosted
+ * then uses `CURSOR_API_KEY` or stored login.
  */
-export async function resolveApiKey(options?: {
+export const DEFAULT_CURSOR_API_KEY_FILE: string =
+  "/run/cursor/secrets/CURSOR_API_KEY";
+
+/**
+ * Read `CURSOR_API_KEY_FILE` (or {@link DEFAULT_CURSOR_API_KEY_FILE} when
+ * unset). Missing/empty files are unsigned, not an error — freeze bake
+ * listens before the binder drops the key; self-hosted falls through to
+ * env or login.
+ */
+export function readApiKeyFromFile(filePath?: string): string | undefined {
+  const configured = filePath ?? process.env.CURSOR_API_KEY_FILE;
+  const path =
+    configured !== undefined && configured.trim() !== ""
+      ? configured.trim()
+      : DEFAULT_CURSOR_API_KEY_FILE;
+  try {
+    const raw = readFileSync(path, "utf8").trim();
+    return raw === "" ? undefined : raw;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * First present source wins. We define the order; operators do not.
+ * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`
+ * (hosted default path if unset) → stored `july login`.
+ */
+export function resolveApiKeySync(options?: {
   apiKey?: string;
   backendUrl?: string;
-}): Promise<ResolvedApiKey | undefined> {
+}): ResolvedApiKey | undefined {
   const backendUrl = options?.backendUrl ?? cursorBackendUrl();
   if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
     return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
@@ -177,15 +226,29 @@ export async function resolveApiKey(options?: {
   if (envKey !== undefined && envKey.trim() !== "") {
     return { apiKey: envKey.trim(), source: "env", backendUrl };
   }
-  const stored = await readStoredCredentials();
+  const fileKey = readApiKeyFromFile();
+  if (fileKey !== undefined) {
+    return { apiKey: fileKey, source: "file", backendUrl };
+  }
+  const stored = readStoredCredentialsSync();
   if (stored !== undefined && stored.backendUrl === backendUrl) {
     return { apiKey: stored.apiKey, source: "login", backendUrl };
   }
   return undefined;
 }
 
+/**
+ * {@link resolveApiKeySync} as a Promise for call sites that already await.
+ */
+export async function resolveApiKey(options?: {
+  apiKey?: string;
+  backendUrl?: string;
+}): Promise<ResolvedApiKey | undefined> {
+  return resolveApiKeySync(options);
+}
+
 /** One-line hint for "no credentials" errors, shared across surfaces. */
-export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / pass serve({ apiKey })).`;
+export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / pass serve({ apiKey })).`;
 
 // ============================================================================
 // PKCE browser login (mirrors cursor-agent / Sand)

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,
@@ -2021,7 +2041,7 @@ async function loadABConfig(
         severity: "error",
         path: displayPath(ctx, path),
         message:
-          "ab.config.ts must default-export defineABConfig({ ... }) from @anysphere/agent-serve/ab.",
+          "ab.config.ts must default-export defineABConfig({ ... }) from @cursor/july/ab.",
       });
       return undefined;
     }

package/src/internal/distribution.ts

@@ -81,6 +81,37 @@ export function packageVersion(): string {
   return typeof parsed.version === "string" ? parsed.version : "0.0.0";
 }
 
+/** Facts `agent-sdk version` / `--version` print. */
+export interface CliVersionInfo {
+  /** Published npm name (`@cursor/july`). */
+  name: string;
+  /** `package.json` version of this install. */
+  version: string;
+  /** Bin the process was invoked as (`agent-sdk` / `agent-serve`). */
+  cli: string;
+}
+
+export function cliVersionInfo(): CliVersionInfo {
+  return {
+    name: PACKAGE_NAME,
+    version: packageVersion(),
+    cli: CLI_COMMAND_NAME,
+  };
+}
+
+/**
+ * Text or JSON for `version` / `--version` / `-V`.
+ * Text is the bare `package.json` version (npm-style). `--json` is the
+ * complete `{ name, version, cli }` payload.
+ */
+export function formatCliVersion(options?: { json?: boolean }): string {
+  const info = cliVersionInfo();
+  if (options?.json === true) {
+    return `${JSON.stringify(info, null, 2)}\n`;
+  }
+  return `${info.version}\n`;
+}
+
 /**
  * Authoring entry subpaths and their dist-relative output files — the
  * runtime mirror of the package `exports` map (the source of truth;

package/src/internal/eval-runner.ts

@@ -479,7 +479,7 @@ function resolveEvalMaxConcurrency(config: Partial<EvalConfigFile>): number {
   if (config.maxConcurrency === undefined) {
     throw new Error(
       `evals/evals.config.ts must define maxConcurrency (1–${EVAL_MAX_CONCURRENCY_LIMIT}; hard limit is due to model provider request limits). Example:\n` +
-        `  import { defineEvalConfig } from "@anysphere/agent-serve/evals";\n` +
+        `  import { defineEvalConfig } from "@cursor/july/evals";\n` +
         `  export default defineEvalConfig({ maxConcurrency: 20 });`
     );
   }

package/src/internal/grokbot/runner.ts

@@ -13,15 +13,21 @@
 
 import { randomUUID } from "node:crypto";
 import type { RunnerTurnRequest, TurnOutcome } from "../../types.js";
-import { cursorBackendUrl } from "../cursor/credentials.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "../cursor/credentials.js";
 import type { AgentRunner } from "./../sdk-runner.js";
 
 export interface GrokBotRunnerOptions {
-  /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
+  /** Cursor API key. Resolved as option → env → file → stored login. */
   apiKey?: string;
   /** Test seam. Defaults to global fetch. */
   fetchImpl?: typeof fetch;
-  /** Test seam. Defaults to {@link cursorBackendUrl}. */
+  /**
+   * Test seam. Defaults to {@link cursorExternalApiUrl} (`api.cursor.com`).
+   * `/v0/grokbot` is an external-api microlith route — it 404s on api2.
+   */
   backendUrl?: string;
   /** Test seam. Poll interval while a turn runs. */
   pollIntervalMs?: number;
@@ -89,14 +95,17 @@ class GrokBotApiClient {
 
   constructor(options: GrokBotRunnerOptions) {
     this.fetchImpl = options.fetchImpl ?? fetch;
-    this.baseUrl = (options.backendUrl ?? cursorBackendUrl()).replace(
+    this.baseUrl = (options.backendUrl ?? cursorExternalApiUrl()).replace(
       /\/$/,
       ""
     );
-    const apiKey = options.apiKey ?? process.env.CURSOR_API_KEY;
+    const apiKey = resolveApiKeySync({
+      apiKey: options.apiKey,
+      backendUrl: options.backendUrl,
+    })?.apiKey;
     if (apiKey === undefined || apiKey === "") {
       throw new Error(
-        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY or agent-sdk login) to reach the hosted Grok Bot harness.'
+        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY, CURSOR_API_KEY_FILE, or agent-sdk login) to reach the hosted Grok Bot harness.'
       );
     }
     this.apiKey = apiKey;

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

@@ -6,6 +6,7 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import { runfiles } from "@bazel/runfiles";
 import type { ModelSetting } from "../types.js";
 import {
   canonicalTemplateName,
@@ -75,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" },
@@ -103,7 +105,7 @@ export function resolveTemplate(name: string): TemplateResolution {
     };
   }
   const entry = TEMPLATES[resolved];
-  const dir = join(packageRootDir(), "templates", entry.dir);
+  const dir = resolvePackagePath("templates", entry.dir);
   return {
     ok: true,
     name: resolved,
@@ -115,6 +117,15 @@ export function resolveTemplate(name: string): TemplateResolution {
   };
 }
 
+function resolvePackagePath(...segments: string[]): string {
+  if (runfiles.workspace !== undefined) {
+    return runfiles.resolveWorkspaceRelative(
+      ["packages", "agent-serve", ...segments].join("/")
+    );
+  }
+  return join(packageRootDir(), ...segments);
+}
+
 export type InitTargetCheck = { ok: true } | { ok: false; message: string };
 
 /**
@@ -699,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