@cursor/july 0.1.103 → 0.1.105

package/src/internal/filesystem/walk.ts

@@ -0,0 +1,369 @@
+/**
+ * Recursive listing, existence probes, and native LS trees. Matches the
+ * change-monitor VFS contract on origin/main: `list` is files-only and
+ * recursive; `stat` tells file / directory / missing apart; composers
+ * merge already-sorted streams with a k-way heap.
+ */
+
+import { posix } from "node:path";
+import { minimatch } from "minimatch";
+import type { DirEntry, FileInfo, FileSystem } from "../../filesystem.js";
+import { normalizeFsPath } from "../../filesystem.js";
+import { mergeSorted } from "./merge.js";
+
+/**
+ * Native LS `directoryTreeRoot` (LocalLsExecutor ingest tree).
+ * Synthesis builds this from `list` + `stat` via `buildLsTree`.
+ * Not a FileSystem method result and not part of the public
+ * Agent SDK surface.
+ */
+export interface LsDirectoryTreeNode {
+  absPath: string;
+  childrenDirs: LsDirectoryTreeNode[];
+  childrenFiles: Array<{ name: string }>;
+  childrenWereProcessed: boolean;
+  fullSubtreeExtensionCounts: Record<string, number>;
+  numFiles: number;
+}
+
+/** Filename-character ingest budget; matches LocalLsExecutor. */
+export const LS_INGEST_CHARACTER_BUDGET = 2_500;
+
+/**
+ * Yield the files under `prefix`, sorted. A file whose path equals
+ * `prefix` is not under itself.
+ */
+export async function* listFilesFromPaths(
+  files: Iterable<DirEntry>,
+  prefix?: string
+): AsyncGenerator<DirEntry> {
+  const scope = normalizeListPrefix(prefix);
+  const withSlash = scope === "/" ? "/" : `${scope}/`;
+  const matches: DirEntry[] = [];
+  for (const file of files) {
+    const filePath = normalizeFsPath(file.path);
+    if (scope === "/") {
+      matches.push(
+        file.size === undefined
+          ? { path: filePath }
+          : { path: filePath, size: file.size }
+      );
+      continue;
+    }
+    if (filePath === scope || !filePath.startsWith(withSlash)) {
+      continue;
+    }
+    matches.push(
+      file.size === undefined
+        ? { path: filePath }
+        : { path: filePath, size: file.size }
+    );
+  }
+  matches.sort((left, right) => left.path.localeCompare(right.path));
+  yield* matches;
+}
+
+export function normalizeListPrefix(prefix?: string): string {
+  if (prefix === undefined || prefix === "" || prefix === "/") {
+    return "/";
+  }
+  return normalizeFsPath(prefix);
+}
+
+/**
+ * Existence probe over a flat file-path index. Exact key → file; any
+ * key with this prefix → directory; `""` / `/` → directory; else missing.
+ */
+export function statFromFilePaths(
+  files: Iterable<string>,
+  path: string
+): FileInfo {
+  const normalized = normalizeListPrefix(path);
+  if (normalized === "/") {
+    return { kind: "directory" };
+  }
+  const prefix = `${normalized}/`;
+  for (const file of files) {
+    const filePath = normalizeFsPath(file);
+    if (filePath === normalized) {
+      return { kind: "file" };
+    }
+    if (filePath.startsWith(prefix)) {
+      return { kind: "directory" };
+    }
+  }
+  return { kind: "missing" };
+}
+
+export async function collectList(
+  root: Pick<FileSystem, "list">,
+  prefix?: string
+): Promise<DirEntry[]> {
+  const entries: DirEntry[] = [];
+  if (root.list === undefined) {
+    return entries;
+  }
+  for await (const entry of root.list(prefix)) {
+    entries.push(entry);
+  }
+  return entries;
+}
+
+export async function collectGlob(
+  root: Pick<FileSystem, "glob">,
+  options: { pattern: string; dir?: string }
+): Promise<DirEntry[]> {
+  const entries: DirEntry[] = [];
+  if (root.glob === undefined) {
+    return entries;
+  }
+  for await (const entry of root.glob(options.pattern, options.dir)) {
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * List, then `stat` only when nothing came back. A non-empty listing is
+ * already a directory (a file is not under itself).
+ */
+export async function collectListOrStat(
+  root: Pick<FileSystem, "list" | "stat">,
+  path?: string
+): Promise<{ kind: FileInfo["kind"]; files: DirEntry[] }> {
+  const files = await collectList(root, path);
+  if (files.length > 0) {
+    return { kind: "directory", files };
+  }
+  if (root.stat === undefined) {
+    return { kind: "missing", files };
+  }
+  const probe = path === undefined || path === "" ? "." : path;
+  return { kind: (await root.stat(probe)).kind, files };
+}
+
+export async function* mergeSortedByPath(
+  sources: Array<Iterable<DirEntry> | AsyncIterable<DirEntry>>,
+  options?: { unique?: boolean }
+): AsyncGenerator<DirEntry> {
+  yield* mergeSorted(sources, {
+    compare: (left, right) => left.path.localeCompare(right.path),
+    unique: options?.unique === true,
+  });
+}
+
+function emptyLsNode(absPath: string): LsDirectoryTreeNode {
+  return {
+    absPath,
+    childrenDirs: [],
+    childrenFiles: [],
+    childrenWereProcessed: true,
+    fullSubtreeExtensionCounts: {},
+    numFiles: 0,
+  };
+}
+
+/**
+ * Build the native LS tree from a recursive file listing. Applies the
+ * LocalLsExecutor ingest budget so a huge directory truncates the same way.
+ */
+export function buildLsTree(
+  dir: string,
+  files: readonly DirEntry[]
+): LsDirectoryTreeNode {
+  const rootPath = normalizeListPrefix(dir);
+  const root: LsDirectoryTreeNode = emptyLsNode(rootPath);
+  const dirNodes = new Map<string, LsDirectoryTreeNode>([[rootPath, root]]);
+  const state = {
+    charactersUsed: rootPath.length,
+    budgetExceeded: false,
+  };
+  for (const file of files) {
+    addPathToTree(
+      file.path,
+      rootPath,
+      dirNodes,
+      state,
+      LS_INGEST_CHARACTER_BUDGET
+    );
+  }
+  return root;
+}
+
+function addPathToTree(
+  filePath: string,
+  rootPath: string,
+  dirNodes: Map<string, LsDirectoryTreeNode>,
+  state: { charactersUsed: number; budgetExceeded: boolean },
+  characterBudget: number
+): void {
+  const fileName = posix.basename(filePath);
+  const dirPath = posixParent(filePath);
+  ensureDirectoryPath(dirPath, rootPath, dirNodes, state.budgetExceeded);
+  const parentNode = dirNodes.get(dirPath);
+  if (parentNode === undefined) {
+    return;
+  }
+  const fileCharCost = fileName.length;
+  if (
+    !state.budgetExceeded &&
+    state.charactersUsed + fileCharCost <= characterBudget
+  ) {
+    parentNode.childrenFiles.push({ name: fileName });
+    state.charactersUsed += fileCharCost;
+    return;
+  }
+  if (!state.budgetExceeded) {
+    state.budgetExceeded = true;
+    let currentDir = dirPath;
+    while (currentDir.startsWith(rootPath)) {
+      const node = dirNodes.get(currentDir);
+      if (node !== undefined) {
+        node.childrenWereProcessed = false;
+      }
+      const parentDir = posixParent(currentDir);
+      if (parentDir === currentDir) {
+        break;
+      }
+      currentDir = parentDir;
+    }
+  }
+  const extension = posix.extname(filePath);
+  let currentDir = dirPath;
+  while (currentDir.startsWith(rootPath)) {
+    const node = dirNodes.get(currentDir);
+    if (node !== undefined) {
+      node.fullSubtreeExtensionCounts[extension] =
+        (node.fullSubtreeExtensionCounts[extension] ?? 0) + 1;
+      node.numFiles += 1;
+    }
+    const parentDir = posixParent(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+}
+
+function ensureDirectoryPath(
+  dirPath: string,
+  rootPath: string,
+  dirNodes: Map<string, LsDirectoryTreeNode>,
+  budgetExceeded: boolean
+): void {
+  if (dirNodes.has(dirPath) || dirPath === rootPath) {
+    return;
+  }
+  const parentPath = posixParent(dirPath);
+  if (parentPath !== dirPath && pathIsUnderRoot(parentPath, rootPath)) {
+    ensureDirectoryPath(parentPath, rootPath, dirNodes, budgetExceeded);
+  }
+  const dirNode: LsDirectoryTreeNode = {
+    ...emptyLsNode(dirPath),
+    childrenWereProcessed: !budgetExceeded,
+  };
+  dirNodes.set(dirPath, dirNode);
+  const parentNode = dirNodes.get(parentPath);
+  if (parentNode !== undefined) {
+    parentNode.childrenDirs.push(dirNode);
+  }
+}
+
+function pathIsUnderRoot(path: string, rootPath: string): boolean {
+  return (
+    path === rootPath ||
+    path.startsWith(rootPath === "/" ? "/" : `${rootPath}/`)
+  );
+}
+
+/**
+ * Native LS ignore_globs: a pattern that is not already recursive is
+ * matched at any depth (the same `** /` prefix the Cursor SDK native uses).
+ */
+export function applyIgnores(
+  entries: readonly DirEntry[],
+  ignoreGlobs?: readonly string[]
+): DirEntry[] {
+  if (ignoreGlobs === undefined || ignoreGlobs.length === 0) {
+    return [...entries];
+  }
+  return entries.filter(
+    (entry) => !ignoreGlobs.some((glob) => matchesIgnoreGlob(entry.path, glob))
+  );
+}
+
+function matchesIgnoreGlob(filePath: string, glob: string): boolean {
+  const recursivePrefix = "**".concat("/");
+  const pattern = glob.startsWith(recursivePrefix)
+    ? glob
+    : recursivePrefix + glob;
+  const relative = filePath.replace(/^\//, "");
+  return (
+    minimatch(relative, pattern, { dot: true }) ||
+    minimatch(filePath, pattern, { dot: true })
+  );
+}
+
+export async function lsFromList(
+  root: Pick<FileSystem, "list" | "stat">,
+  path?: string,
+  ignoreGlobs?: readonly string[]
+): Promise<
+  | { status: "success"; value: { directoryTreeRoot: LsDirectoryTreeNode } }
+  | { status: "error"; error: { message: string } }
+> {
+  const listed = await collectListOrStat(root, path);
+  const treePath = path ?? inferListedRoot(listed.files);
+  switch (listed.kind) {
+    case "missing":
+      return {
+        status: "error",
+        error: { message: `Path does not exist: ${treePath}` },
+      };
+    case "file":
+      return {
+        status: "error",
+        error: { message: `Path is not a directory: ${treePath}` },
+      };
+    case "directory":
+      return {
+        status: "success",
+        value: {
+          directoryTreeRoot: buildLsTree(
+            treePath,
+            applyIgnores(listed.files, ignoreGlobs)
+          ),
+        },
+      };
+  }
+}
+
+function inferListedRoot(files: readonly DirEntry[]): string {
+  if (files.length === 0) {
+    return "/";
+  }
+  let prefix = posixParent(files[0]!.path);
+  for (const file of files) {
+    while (
+      prefix !== "/" &&
+      file.path !== prefix &&
+      !file.path.startsWith(`${prefix}/`)
+    ) {
+      const parent = posixParent(prefix);
+      if (parent === prefix) {
+        return "/";
+      }
+      prefix = parent;
+    }
+  }
+  return prefix;
+}
+
+/**
+ * `path.posix.dirname` returns `.` for slash-free paths. Treat that as
+ * the virtual root so LS walks terminate and relative files attach to `/`.
+ */
+function posixParent(path: string): string {
+  const dir = posix.dirname(path);
+  return dir === "." || dir === path ? "/" : dir;
+}

package/src/internal/framework-file-storage.ts

@@ -9,7 +9,9 @@
  * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
  *   holds engine-owned session state — session records, event transcripts,
  *   hosted-execution run logs, the continuation index, and the SDK
- *   conversation mirror — and is never exposed to authors or models.
+ *   conversation mirror — and is never mounted into author code or models.
+ *   The authenticated dashboard may read diagnostic families, but never the
+ *   continuation index.
  *
  * This module puts framework session state on the framework store. The
  * {@link storageKeys} scheme was designed for exactly this: keys are a

package/src/internal/guest-network.ts

@@ -14,8 +14,9 @@
  *
  * Quiet guest Connect (`TypeError: fetch failed` with no errno, Connect
  * `[unknown]`/`[canceled]`/`[unavailable]`, headers/body timeout) is a
- * stall, not a dead NIC. Those become `guest_connect_stalled` so TAS does
- * not treat them as restore-window mystery 503s.
+ * stall, not a dead NIC. Those become `guest_connect_stalled` so TAS
+ * retries the same pod — including when `waitForCompletion` resolves
+ * with that message instead of throwing.
  */
 
 export const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
@@ -112,6 +113,11 @@ export function isQuietGuestConnectStall(error: unknown): boolean {
   return isQuietSignatureAtDepth(error, 0);
 }
 
+/** Message-only form for `waitForCompletion` outcomes that do not throw. */
+export function isQuietGuestConnectStallMessage(message: string): boolean {
+  return QUIET_CONNECT_MESSAGE.test(message);
+}
+
 function errorCode(error: Error): string | undefined {
   const code = (error as NodeJS.ErrnoException).code;
   return typeof code === "string" && code.length > 0 ? code : undefined;

package/src/internal/hosted-delivery.ts

@@ -15,10 +15,12 @@ import {
 } from "./deferred-channel-session.js";
 import {
   formatGuestNetworkServerTiming,
+  GUEST_CONNECT_STALLED,
   GUEST_NETWORK_UNAVAILABLE,
   GuestNetworkUnavailableError,
   type GuestNetworkWaitResult,
   type GuestNetworkWaitStats,
+  isQuietGuestConnectStallMessage,
   waitForGuestNetworkReady,
 } from "./guest-network.js";
 import {
@@ -356,6 +358,13 @@ export function registerHostedDeliveryRoute(input: {
   flushStartLog?(startLogId: string): Promise<void>;
   /** Snapshot of the process log ring at persist time. */
   snapshotLogs?(): LogRingEntry[];
+  /**
+   * Drop the cached SDK agent handle before the HTTP reply. Hosted v2
+   * hibernates this process as soon as the reply lands; leaving the handle
+   * in memory freezes a dead Connect/HTTP2 session that the next wake
+   * then reuses.
+   */
+  evictSdkSession?(sessionId: string): void;
   /**
    * Wait until guest egress works before authored admission/execution.
    * Defaults to {@link waitForGuestNetworkReady}. Tests inject a stub.
@@ -461,8 +470,18 @@ export function registerHostedDeliveryRoute(input: {
         if (unconsumed !== undefined) {
           return finish(unconsumed);
         }
-        const delivery = parseHostedAdmission(await readJsonObject(request));
+        const rawAdmission = await readJsonObject(request);
+        const delivery = parseHostedAdmission(rawAdmission);
         if (delivery === undefined) {
+          const rawKeys =
+            typeof rawAdmission === "object" &&
+            rawAdmission !== null &&
+            !Array.isArray(rawAdmission)
+              ? Object.keys(rawAdmission as Record<string, unknown>)
+              : [];
+          console.info(
+            `[agent-sdk] hosted admission rejected: envelope failed to parse keys=${JSON.stringify(rawKeys)} hasManagedAutomation=${String(rawKeys.includes("managedAutomation"))}`
+          );
           return finish(
             errorResponse(
               400,
@@ -471,6 +490,9 @@ export function registerHostedDeliveryRoute(input: {
             )
           );
         }
+        console.info(
+          `[agent-sdk] hosted admission received deliveryId=${delivery.deliveryId} channelId=${delivery.channelId} channelKind=${delivery.channelKind} eventType=${delivery.eventType} sessionMode=${delivery.sessionMode} managedAutomation=${delivery.managedAutomation === undefined ? "<absent>" : `automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${delivery.managedAutomation.slackChannels === undefined ? "<absent>" : JSON.stringify(delivery.managedAutomation.slackChannels)}`}`
+        );
         recordHostedManagedAutomation(delivery);
         const channel = input.channels.find(
           (candidate) => candidate.id === delivery.channelId
@@ -622,6 +644,7 @@ export function registerHostedDeliveryRoute(input: {
             sessionId: "",
             turnStatus: HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
           });
+          let sessionId = "";
           try {
             const args = input.buildHandlerArgs(
               admitted.send.channelId,
@@ -633,10 +656,19 @@ export function registerHostedDeliveryRoute(input: {
                 key: admitted.send.mailboxContinuationKey,
               },
             });
+            sessionId = session.id;
             const outcome = await session.waitForCompletion();
             // Failed turns drain too: their record/continuation updates must
             // survive the park just like a finished turn's.
             await input.drainSessionDurability?.(session.id);
+            // Evict before the reply: TAS parks and hibernates this process
+            // as soon as the POST returns. A leftover SDK handle freezes a
+            // dead Connect/HTTP2 session that the next wake then reuses.
+            evictHostedSdkSessions(
+              input.evictSdkSession,
+              session.id,
+              execution.sessionPublicId
+            );
             await writeDiag({
               sessionId: session.id,
               turnStatus: outcome.status,
@@ -647,11 +679,14 @@ export function registerHostedDeliveryRoute(input: {
               ),
             });
             if (outcome.status !== "finished") {
+              // waitForCompletion resolves (does not throw) on a quiet
+              // Connect abort. Map that to guest_connect_stalled so TAS
+              // retries the same pod. Real runner failures stay turn_failed.
               return {
                 status: 503,
                 body: {
                   ok: false,
-                  error: "turn_failed",
+                  error: hostedErrorForUnfinishedTurn(outcome.errorMessage),
                   turnStatus: outcome.status,
                   message: outcome.errorMessage,
                 },
@@ -666,6 +701,11 @@ export function registerHostedDeliveryRoute(input: {
               },
             };
           } catch (error) {
+            evictHostedSdkSessions(
+              input.evictSdkSession,
+              sessionId,
+              execution.sessionPublicId
+            );
             await writeDiag({
               sessionId: "",
               turnStatus: "error",
@@ -682,6 +722,35 @@ export function registerHostedDeliveryRoute(input: {
   });
 }
 
+function evictHostedSdkSessions(
+  evict: ((sessionId: string) => void) | undefined,
+  ...ids: Array<string | undefined>
+): void {
+  if (evict === undefined) {
+    return;
+  }
+  const seen = new Set<string>();
+  for (const id of ids) {
+    if (id === undefined || id === "" || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    evict(id);
+  }
+}
+
+function hostedErrorForUnfinishedTurn(
+  errorMessage: string | undefined
+): typeof GUEST_CONNECT_STALLED | "turn_failed" {
+  if (
+    errorMessage !== undefined &&
+    isQuietGuestConnectStallMessage(errorMessage)
+  ) {
+    return GUEST_CONNECT_STALLED;
+  }
+  return "turn_failed";
+}
+
 async function afterHostedWork<T>(
   flushOtel: (() => Promise<void>) | undefined,
   work: () => Promise<T>

package/src/internal/hosted-managed-automation.ts

@@ -17,10 +17,36 @@
 
 import type { HostedAdmissionManagedAutomation } from "./hosted-delivery-protocol.js";
 
-const managedAutomationByDelivery = new Map<
-  string,
-  { managedAutomation: HostedAdmissionManagedAutomation; expiresAt: number }
->();
+type ManagedAutomationEntry = {
+  managedAutomation: HostedAdmissionManagedAutomation;
+  expiresAt: number;
+};
+
+/**
+ * Process-wide slot for the table. Hosted engines run the compiled CLI
+ * (`dist/`), which records at admission, while first-party factory agents
+ * relative-import this file from `src/` and read at finalize — two module
+ * instances in one process. A module-local Map would be recorded in one
+ * copy and read from the other (always undefined, so a fork never sees its
+ * Slack channels or MCP servers); the shared symbol keeps one table.
+ */
+const MANAGED_AUTOMATION_TABLE_KEY = Symbol.for(
+  "cursor.agentkit.hostedManagedAutomationByDelivery"
+);
+
+function managedAutomationTable(): Map<string, ManagedAutomationEntry> {
+  const slots = globalThis as unknown as Record<
+    symbol,
+    Map<string, ManagedAutomationEntry> | undefined
+  >;
+  let table = slots[MANAGED_AUTOMATION_TABLE_KEY];
+  if (table === undefined) {
+    table = new Map();
+    slots[MANAGED_AUTOMATION_TABLE_KEY] = table;
+  }
+  return table;
+}
+
 /** Long enough to outlive a slow review run kicked off by the delivery. */
 const MANAGED_AUTOMATION_TTL_MS = 60 * 60_000;
 const MANAGED_AUTOMATION_MAX_ENTRIES = 10_000;
@@ -30,8 +56,12 @@ export function recordHostedManagedAutomation(delivery: {
   managedAutomation?: HostedAdmissionManagedAutomation;
 }): void {
   if (delivery.managedAutomation === undefined) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation not recorded deliveryId=${delivery.deliveryId}: admission envelope carried no managedAutomation slice (non-managed delivery, or the control plane resolved no MCP servers and no Slack channels)`
+    );
     return;
   }
+  const managedAutomationByDelivery = managedAutomationTable();
   const now = Date.now();
   for (const [key, entry] of managedAutomationByDelivery) {
     if (entry.expiresAt <= now) {
@@ -39,12 +69,19 @@ export function recordHostedManagedAutomation(delivery: {
     }
   }
   if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation table full (${String(managedAutomationByDelivery.size)} entries); clearing before recording deliveryId=${delivery.deliveryId}`
+    );
     managedAutomationByDelivery.clear();
   }
   managedAutomationByDelivery.set(delivery.deliveryId, {
     managedAutomation: delivery.managedAutomation,
     expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
   });
+  const slackChannels = delivery.managedAutomation.slackChannels;
+  console.info(
+    `[agent-sdk] hosted managedAutomation recorded deliveryId=${delivery.deliveryId} automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${slackChannels === undefined ? "<absent>" : JSON.stringify(slackChannels)} ttlMs=${String(MANAGED_AUTOMATION_TTL_MS)} tableSize=${String(managedAutomationByDelivery.size)}`
+  );
 }
 
 /**
@@ -55,11 +92,18 @@ export function recordHostedManagedAutomation(delivery: {
 export function getHostedManagedAutomation(
   deliveryId: string
 ): HostedAdmissionManagedAutomation | undefined {
+  const managedAutomationByDelivery = managedAutomationTable();
   const entry = managedAutomationByDelivery.get(deliveryId);
   if (entry === undefined) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation lookup miss deliveryId=${deliveryId}: no entry (never recorded in this process, or evicted) tableSize=${String(managedAutomationByDelivery.size)} knownDeliveryIds=${JSON.stringify([...managedAutomationByDelivery.keys()].slice(0, 10))}`
+    );
     return undefined;
   }
   if (entry.expiresAt <= Date.now()) {
+    console.info(
+      `[agent-sdk] hosted managedAutomation lookup expired deliveryId=${deliveryId} automationUuid=${entry.managedAutomation.automationUuid} expiredMsAgo=${String(Date.now() - entry.expiresAt)}`
+    );
     managedAutomationByDelivery.delete(deliveryId);
     return undefined;
   }
@@ -68,5 +112,5 @@ export function getHostedManagedAutomation(
 
 /** Drop recorded managed-automation slices (tests only). */
 export function resetHostedManagedAutomationForTest(): void {
-  managedAutomationByDelivery.clear();
+  managedAutomationTable().clear();
 }

package/src/internal/init-project.ts

@@ -77,6 +77,7 @@ const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agents-md": { dir: "agents-md" },
   "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
+  "grokbot-agents": { dir: "grokbot-agents" },
   "pr-autofixer": { dir: "pr-autofixer" },
   "security-help": { dir: "security-help" },
   "security-reviewer": { dir: "security-reviewer" },
@@ -711,6 +712,7 @@ export function printInitGuide(): void {
 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 ./grokbot --template grokbot-agents    # talk to Grok Bot agents
   npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
   npx ${PACKAGE_NAME} init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
@@ -719,8 +721,9 @@ Scaffold a project, then open the playground:
   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
   npx ${PACKAGE_NAME} init ./pr-autofixer --template pr-autofixer # fix PRs on a cloud VM
-  # TTY asks for GitHub repos. Scripts pass --var:
+  # TTY asks the template's questions. Scripts pass --var:
   #   --var repos=acme/widgets,acme/api
+  #   --var agents="Plan Keeper, Chief of Staff"
   cd ./my-agent && agent-sdk dev        # or: npx ${PACKAGE_NAME} dev
 
 Recommended loop once the project exists (from the project directory):