@cursor/july 0.1.62 → 0.1.68

package/src/channels/slack/dispatch.ts

@@ -142,6 +142,13 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    * dropped at parse time (loop safety).
    */
   botMentionGate?: SlackBotMentionGate;
+  /**
+   * When false, do not write `assistant.threads.setStatus` on a coalesced
+   * follow-up. Defaults to `true`. Channels that report progress their own
+   * way turn this off: the chip has no owner to clear it once the default
+   * `message.completed` handler is replaced, so it lingers past the turn.
+   */
+  followUpStatus?: boolean;
   /**
    * When false, skip the built-in `eval` directive. Defaults to true when
    * `host.evals` is present.
@@ -195,6 +202,8 @@ export async function dispatchInboundMessage(args: {
   log?: SlackLog;
   eventId?: string;
   evalCommandsEnabled?: boolean;
+  /** See {@link SlackInboundDispatchDeps.followUpStatus}. Defaults to `true`. */
+  followUpStatus?: boolean;
   /**
    * cursorAccount agent display name — stripped before parsing `eval …`
    * (`OncallBuddy eval list`).
@@ -477,8 +486,9 @@ export async function dispatchInboundMessage(args: {
         event_id: args.eventId,
       }
     );
-    // Coalesce admits leave the active turn running; follow-ups drain into one
-    // boundary turn when it finishes (no mid-turn tool/hook inject).
+    // Coalesce admits leave the active turn running: the follow-up is queued
+    // for the carrier to inject at the next tool boundary, and anything it
+    // does not reach in time drains into the boundary turn instead.
     if (session.coalesced === true) {
       log.info("session busy; coalescing follow-up", {
         kind,
@@ -487,8 +497,32 @@ export async function dispatchInboundMessage(args: {
         continuation,
         event_id: args.eventId,
       });
+      // Queue it for mid-turn injection too. The carrier drains this at the
+      // running turn's next tool boundary; whatever it does not reach in time
+      // still drains into the boundary turn, deduped by sourceTs.
+      try {
+        await args.host.slackNudges?.append({
+          continuationKey: continuation,
+          sourceTs: message.ts,
+          text: media.userText,
+          ...(message.author?.userName === undefined
+            ? {}
+            : { author: message.author.userName }),
+        });
+      } catch (nudgeError) {
+        log.warn("nudge append failed", {
+          error:
+            nudgeError instanceof Error
+              ? nudgeError.message
+              : String(nudgeError),
+          continuation,
+          event_id: args.eventId,
+        });
+      }
       try {
-        await binding.thread.startTyping(FOLLOWUP_TYPING);
+        if (args.followUpStatus !== false) {
+          await binding.thread.startTyping(FOLLOWUP_TYPING);
+        }
       } catch (typingError) {
         log.error(
           `follow-up typing failed: ${
@@ -581,6 +615,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -623,6 +658,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -659,6 +695,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: false,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}

package/src/channels/slack/manifest.ts

@@ -69,6 +69,7 @@ const BOT_SCOPES = [
   "channels:history",
   "chat:write",
   "files:read",
+  "files:write",
   "groups:history",
   "im:history",
   "im:read",

package/src/channels/slack/nudge-store.ts

@@ -202,6 +202,24 @@ export class SlackNudgeStore {
     return (await this.listPending(continuationKey)).length > 0;
   }
 
+  /**
+   * How many follow-ups have reached the agent on this thread. Monotonic
+   * within a continuation, so a caller can spot a delivery by comparing two
+   * readings — unlike {@link hasUndelivered}, which races the carrier: both
+   * run at the same tool boundary, and a queued nudge drained before the
+   * first reading never looks pending at all.
+   */
+  async deliveredCount(continuationKey: string): Promise<number> {
+    if (continuationKey.trim() === "") {
+      return 0;
+    }
+    try {
+      return (await readdir(this.deliveredDir(continuationKey))).length;
+    } catch {
+      return 0;
+    }
+  }
+
   /**
    * Atomically move all pending nudges to delivered and return them.
    * Already-delivered source ts values are dropped (exactly-once).
@@ -238,6 +256,44 @@ export class SlackNudgeStore {
     return delivered;
   }
 
+  /**
+   * Settle a follow-up the caller is handling itself, so the carrier cannot
+   * inject it again. Used by the boundary drain: a follow-up the carrier did
+   * not reach becomes the next turn's prompt, and without this its pending
+   * record survives into that turn and gets injected on top of the ask it
+   * already is.
+   */
+  async markDelivered(
+    continuationKey: string,
+    sourceTs: string
+  ): Promise<void> {
+    const key = continuationKey.trim();
+    const ts = sourceTs.trim();
+    if (key === "" || ts === "") {
+      return;
+    }
+    const pending = await this.listPending(key);
+    const record = pending.find((item) => item.sourceTs === ts);
+    await mkdir(this.deliveredDir(key), { recursive: true });
+    const dest = this.deliveredPath(key, ts);
+    const tmp = `${dest}.${process.pid}.tmp`;
+    try {
+      await writeFile(
+        tmp,
+        `${JSON.stringify(record ?? { continuationKey: key, sourceTs: ts })}\n`,
+        "utf8"
+      );
+      await rename(tmp, dest);
+    } catch {
+      await rm(tmp, { force: true }).catch(() => {});
+    }
+    if (record !== undefined) {
+      await rm(join(this.pendingDir(key), `${record.id}.json`), {
+        force: true,
+      }).catch(() => {});
+    }
+  }
+
   async clear(continuationKey: string): Promise<void> {
     await rm(this.continuationDir(continuationKey), {
       recursive: true,

package/src/channels/slack/slack-channel.ts

@@ -219,6 +219,7 @@ export function slackChannel<const Name extends string = string>(
   const mentionsEnabled = engagement.mentions !== false;
   const directMessagesEnabled = engagement.directMessages !== false;
   const evalCommandsEnabled = options.evalCommands !== false;
+  const followUpStatus = options.followUpStatus !== false;
   const channelPosts = engagement.channelPosts;
   if (channelPosts !== undefined) {
     const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
@@ -296,6 +297,7 @@ export function slackChannel<const Name extends string = string>(
       mentionsEnabled,
       directMessagesEnabled,
       evalCommandsEnabled,
+      followUpStatus,
       // cursorAccount: backend router already refuses externals.
       blockExternals: cursorAccount ? false : blockExternals,
       ...(args.hasContinuationSession === undefined
@@ -484,6 +486,7 @@ export function slackChannel<const Name extends string = string>(
                   artifacts: args.artifacts,
                   log: getLog(),
                   evalCommandsEnabled,
+                  followUpStatus,
                   blockExternals,
                   ...(args.hasContinuationSession === undefined
                     ? {}

package/src/channels/slack/types.ts

@@ -330,11 +330,18 @@ export type SlackBlockActionHandler = (
  */
 export interface SlackChannelPostsOptions {
   /**
-   * Channels to watch: ids (`C…` / `G…`) or `#names`. Must be non-empty
-   * (empty is a definition error). `#names` are resolved to ids via
-   * `conversations.list` when the channel starts; the bot must be a member
-   * of each watched channel to receive its messages. Socket Mode only —
-   * `cursorAccount: true` rejects `engagement.channelPosts`.
+   * Channels to watch: ids (`C…` / `G…`), `#names`, or `"*"` for every
+   * channel the bot is in. Must be non-empty (empty is a definition error).
+   * `#names` are resolved to ids via `conversations.list` when the channel
+   * starts; the bot must be a member of each watched channel to receive its
+   * messages. Socket Mode only — `cursorAccount: true` rejects
+   * `engagement.channelPosts`.
+   *
+   * `"*"` suits agents whose handler decides per message (a thread the agent
+   * is already in, say) rather than per channel. Every delivered message then
+   * reaches {@link SlackChannelOptions.onChannelPost}, and each one costs a
+   * `users.info` external-sender check first unless
+   * {@link SlackAccessPolicy.blockExternals} is off.
    */
   allow: string[];
   /**
@@ -571,6 +578,16 @@ export interface SlackChannelOptions {
    * Defaults to `true`.
    */
   thinkingSteps?: boolean;
+  /**
+   * Write Slack's assistant status chip ("Saw your follow-up…") when a
+   * follow-up coalesces into a running turn. Defaults to `true`.
+   *
+   * Set to `false` on channels that report progress themselves: the chip is
+   * cleared by the default `message.completed` handler, so a channel that
+   * replaces that handler has nothing to take it down and it outlives the
+   * turn.
+   */
+  followUpStatus?: boolean;
   /**
    * Opt in to Slack delivery for human-in-the-loop tool approvals.
    *

package/src/index.ts

@@ -132,6 +132,8 @@ export type {
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {
+  DurableSessionRecord,
+  DurableSessionSummary,
   StorageABTable,
   StorageCasTable,
   StorageConfig,
@@ -144,8 +146,11 @@ export type {
 } from "./storage.js";
 export {
   defineStorage,
+  isDurableSessionRecordKey,
+  parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  summarizeDurableSessionRecord,
 } from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";

package/src/internal/advertise-tools.ts

@@ -0,0 +1,229 @@
+/**
+ * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
+ *
+ * The session engine calls {@link resolveAdvertisedTools} while building
+ * every local turn: for each advertising connection it lists the server's
+ * tools and synthesizes a named 1:1 passthrough server tool per entry —
+ * the server's own names, descriptions, and live schemas — merged into the
+ * authored `agent/tools/` catalog. Because it runs at turn-build time it
+ * covers every way a turn starts (dispatcher sends, follow-ups, reminder
+ * fires that call the engine directly) and survives process restarts,
+ * since nothing is parked in memory between turns.
+ *
+ * Connections with per-session `auth` are listed and called through a
+ * one-off client carrying that session's headers (the registry's cached
+ * per-name client would leak one session's identity into another);
+ * auth-less connections go through the shared `host.mcp` registry, which
+ * also covers serve-resolved transports (Cursor account bridges, peers).
+ *
+ * Everything here fails closed: a listing failure, an invalid tool name,
+ * or a name collision throws, and the engine fails the turn rather than
+ * running it with a silently shrunken toolset.
+ */
+
+import type {
+  DiscoveredConnection,
+  DiscoveredTool,
+  HostMcpCallResult,
+  HostMcpToolInfo,
+  JsonSchemaObject,
+  ResolvedAgent,
+  SessionInfo,
+  ToolDefinition,
+} from "../types.js";
+import { brandDefinition } from "./brand.js";
+import type { HostMcpOneOff } from "./mcp-host.js";
+
+/**
+ * What the resolver needs from the host MCP registry: the shared cached
+ * clients for auth-less connections, and one-off clients (per-session
+ * headers, never cached) for auth'd ones. `McpHost` implements this.
+ */
+export interface AdvertiseHostMcp {
+  listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+  callTool(
+    connectionName: string,
+    toolName: string,
+    args?: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+  oneOff(connection: DiscoveredConnection): HostMcpOneOff;
+}
+
+/**
+ * The rule advertised tool names must match — the same shape discovery
+ * enforces for authored tool filenames (its `NAME_PATTERN`), since both
+ * become the tool name the model sees.
+ */
+export const ADVERTISED_TOOL_NAME_PATTERN: RegExp =
+  /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+const ANY_OBJECT_SCHEMA: JsonSchemaObject = {
+  type: "object",
+  additionalProperties: true,
+};
+
+/** How one advertising connection is listed and called. */
+export interface AdvertisedToolSource {
+  listTools(): Promise<HostMcpToolInfo[]>;
+  callTool(
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+}
+
+/**
+ * Resolve the advertised tools for one session. Returns `[]` when no
+ * connection advertises; throws (failing the turn) when a listing fails
+ * or a definition is invalid.
+ */
+export async function resolveAdvertisedTools(args: {
+  agent: ResolvedAgent;
+  session: SessionInfo;
+  hostMcp: AdvertiseHostMcp;
+  /** Test seam; defaults to {@link sourceForConnection}. */
+  sourceFor?: (
+    connection: DiscoveredConnection,
+    session: SessionInfo,
+    hostMcp: AdvertiseHostMcp
+  ) => Promise<AdvertisedToolSource>;
+}): Promise<DiscoveredTool[]> {
+  const advertising = args.agent.connections.filter(
+    (connection) => connection.advertiseTools === true
+  );
+  if (advertising.length === 0) {
+    return [];
+  }
+  const sourceFor = args.sourceFor ?? sourceForConnection;
+  const claimed = new Set(args.agent.tools.map((tool) => tool.name));
+  const resolved: DiscoveredTool[] = [];
+  for (const connection of advertising) {
+    const source = await sourceFor(connection, args.session, args.hostMcp);
+    let listed: HostMcpToolInfo[];
+    try {
+      listed = await source.listTools();
+    } catch (error) {
+      throw new Error(
+        `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
+        { cause: error }
+      );
+    }
+    for (const info of listed) {
+      resolved.push(toDiscoveredTool(connection, info, claimed, source));
+      claimed.add(info.name);
+    }
+  }
+  return resolved;
+}
+
+/**
+ * The production source for one advertising connection: the shared
+ * `host.mcp` registry client for auth-less connections (which also covers
+ * serve-resolved transports — Cursor account bridges, peers), or a
+ * registry one-off with the session's headers substituted when the
+ * connection has per-session `auth`. The auth callback is evaluated once
+ * per turn, here; the one-off opens a fresh client per operation so one
+ * session's identity can never serve another's call.
+ */
+export async function sourceForConnection(
+  connection: DiscoveredConnection,
+  session: SessionInfo,
+  hostMcp: AdvertiseHostMcp
+): Promise<AdvertisedToolSource> {
+  if (connection.auth === undefined) {
+    return {
+      listTools: () => hostMcp.listTools(connection.name),
+      callTool: (toolName, callArgs) =>
+        hostMcp.callTool(connection.name, toolName, callArgs),
+    };
+  }
+  const transport = connection.transport;
+  if (!("url" in transport)) {
+    // Discovery rejects auth on non-URL transports; guard for callers that
+    // bypass discovery (hand-built projects).
+    throw new Error(
+      `Connection "${connection.name}" has per-session auth but no URL transport.`
+    );
+  }
+  const evaluated = await connection.auth(session);
+  return hostMcp.oneOff({
+    ...connection,
+    transport: {
+      ...transport,
+      headers: { ...transport.headers, ...evaluated.headers },
+    },
+  });
+}
+
+function toDiscoveredTool(
+  connection: DiscoveredConnection,
+  info: HostMcpToolInfo,
+  claimed: ReadonlySet<string>,
+  source: AdvertisedToolSource
+): DiscoveredTool {
+  if (!ADVERTISED_TOOL_NAME_PATTERN.test(info.name)) {
+    throw new Error(
+      `Advertised connection "${connection.name}" serves tool name "${info.name}", which must match ${ADVERTISED_TOOL_NAME_PATTERN} (it becomes the tool name the model sees).`
+    );
+  }
+  if (claimed.has(info.name)) {
+    throw new Error(
+      `Advertised connection "${connection.name}" serves tool "${info.name}", which collides with an authored agent/tools/ tool or another advertised connection.`
+    );
+  }
+  const description =
+    info.description === undefined || info.description.trim() === ""
+      ? `${info.name} — MCP tool on the "${connection.name}" connection, forwarded 1:1.`
+      : info.description;
+  const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
+  const definition: ToolDefinition = brandDefinition("tool", {
+    description,
+    inputSchema,
+    execute: async (input: Record<string, unknown>) =>
+      formatMcpToolResult(
+        connection.name,
+        info.name,
+        await source.callTool(info.name, input ?? {})
+      ),
+  } as unknown as ToolDefinition);
+  return {
+    name: info.name,
+    description,
+    inputSchema,
+    execution: "server",
+    needsApproval: false,
+    definition,
+  };
+}
+
+/**
+ * Render an MCP call result for the model: text parts joined, non-text
+ * parts noted by type, `isError` surfaced as a thrown error so the turn
+ * records a tool error instead of error-shaped prose.
+ */
+export function formatMcpToolResult(
+  connectionName: string,
+  toolName: string,
+  result: HostMcpCallResult
+): string {
+  const parts = result.content.map((item) =>
+    item.type === "text" && typeof item.text === "string"
+      ? item.text
+      : `[${item.type} content omitted]`
+  );
+  const text = parts.join("\n").trim();
+  if (result.isError === true) {
+    throw new Error(
+      text === "" ? `${connectionName} tool ${toolName} failed` : text
+    );
+  }
+  if (text !== "") {
+    return text;
+  }
+  return result.structuredContent !== undefined
+    ? JSON.stringify(result.structuredContent, null, 2)
+    : "(empty result)";
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/internal/cli-deploy.ts

@@ -22,6 +22,7 @@ import {
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
 import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
+import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   AgentServeDeployClient,
   type DeleteAccepted,
@@ -38,6 +39,10 @@ import {
   TERMINAL_DEPLOY_STATUSES,
   validateDeploymentSlug,
 } from "./deploy-client.js";
+import {
+  type AgentDeployManifestV1,
+  buildAgentDeployManifest,
+} from "./deploy-manifest.js";
 import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
 import {
   type ChildAgentDir,
@@ -661,11 +666,19 @@ async function deployOne(
     ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
     publicRoutePaths:
       publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
+    // Offline metadata extraction (Wd): the CP persists this before any VM
+    // starts. Directories without an agent project send no manifest.
+    ...(manifest === undefined ? {} : { manifest: manifest.deployManifest }),
   };
 
   let accepted: DeployAccepted;
   try {
-    accepted = await ctx.client.deploy({ teamId: ctx.teamId, slug, source });
+    accepted = await ctx.client.deploy({
+      teamId: ctx.teamId,
+      slug,
+      source,
+      template: readDeployTemplate(dir),
+    });
   } catch (error) {
     return renderApiError(error, ctx.err);
   }
@@ -851,6 +864,13 @@ interface DeployManifest {
    * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
    */
   httpChannelPublicEndpoint: boolean;
+  /**
+   * The offline deploy manifest (Wd): derived event declarations, channel
+   * kinds, egress, routes, and the full `/v1/info` payload. Attached to the
+   * deploy request so the control plane stores metadata before any VM
+   * starts; servers that predate manifest storage strip the field.
+   */
+  deployManifest: AgentDeployManifestV1;
 }
 
 /**
@@ -875,6 +895,7 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
     httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
       isPublicEndpointPolicy
     ),
+    deployManifest: buildAgentDeployManifest(project),
   };
 }
 

package/src/internal/cli-manifest.ts

@@ -0,0 +1,63 @@
+/**
+ * `july manifest` — print the offline deploy manifest (Wd-1 of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`).
+ *
+ * Loads the agent project from disk and emits the statically-derived
+ * metadata the control plane stores at deploy time: declared GitHub webhook
+ * events, egress domains, public routes, and the full `/v1/info` payload.
+ * Runs entirely offline — no VM, no engine, no network.
+ */
+
+import {
+  buildAgentDeployManifest,
+  parseAgentDeployManifest,
+} from "./deploy-manifest.js";
+import { isAgentProjectDir, loadAgentProject } from "./discovery.js";
+
+export interface CmdManifestOptions {
+  dir: string;
+  /** Compact single-line JSON (machine consumption); default pretty. */
+  json?: boolean;
+  /** Test seams. */
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+}
+
+export async function cmdManifest(
+  options: CmdManifestOptions
+): Promise<number> {
+  const out = options.out ?? ((line: string) => process.stdout.write(line));
+  const err = options.err ?? ((line: string) => process.stderr.write(line));
+
+  if (!(await isAgentProjectDir(options.dir))) {
+    err(
+      `No agent project found at ${options.dir} (expected an agent.ts default-exporting defineAgent({ ... })).\n`
+    );
+    return 1;
+  }
+
+  const project = await loadAgentProject(options.dir);
+  for (const diagnostic of project.diagnostics) {
+    err(`${diagnostic.severity}: ${diagnostic.message}\n`);
+  }
+  if (project.diagnostics.some((d) => d.severity === "error")) {
+    return 1;
+  }
+
+  const manifest = buildAgentDeployManifest(project);
+  // Round-trip through the wire schema so `july manifest` can never emit
+  // something the control plane contract would reject.
+  if (
+    parseAgentDeployManifest(JSON.parse(JSON.stringify(manifest))) === undefined
+  ) {
+    err("internal error: generated manifest failed schema validation\n");
+    return 1;
+  }
+
+  out(
+    options.json === true
+      ? `${JSON.stringify(manifest)}\n`
+      : `${JSON.stringify(manifest, null, 2)}\n`
+  );
+  return 0;
+}

package/src/internal/cli-slack.ts

@@ -402,7 +402,16 @@ function writePendingAdminWait(
       ? poll.oauthAuthorizeUrl
       : undefined;
   ctx.err(`Waiting for a Slack admin to approve the app${appSuffix}.\n\n`);
-  if (requestUrl !== undefined) {
+  if (poll.approvalRequest === "pending") {
+    // Already in the admin queue: nothing to file, so no browser hop.
+    ctx.err(
+      ctx.dim(`  Approval request sent; workspace owners were notified.\n\n`)
+    );
+    if (requestUrl !== undefined) {
+      ctx.err(ctx.dim(`  Send a reminder from:\n\n`));
+      ctx.err(`  ${requestUrl}\n\n`);
+    }
+  } else if (requestUrl !== undefined) {
     ctx.err(
       ctx.dim(
         `  Slack will notify workspace owners once the request is in their queue.\n` +

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

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MAX = 64;
+const TEMPLATE_NAMES = [
+  "agentic-owners",
+  "demo",
+  "pr-autofixer",
+  "security-reviewer",
+  "triage-linear",
+  "triage-jira",
+] as const;
+export type TemplateName = (typeof TEMPLATE_NAMES)[number];
+const NAMES = new Set<string>(TEMPLATE_NAMES);
+
+export function canonicalTemplateName(name: string): string {
+  return name === "triage" ? "triage-linear" : name;
+}
+
+export function isTemplateName(name: string): name is TemplateName {
+  return NAMES.has(name);
+}
+
+/** Raw scaffold marker. Validation depends on the consuming boundary. */
+export function readCursorAgentTemplate(rootDir: string): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(rootDir, "package.json"), "utf8")
+    ) as {
+      cursorAgentTemplate?: unknown;
+    };
+    const stamp = pkg.cursorAgentTemplate;
+    return typeof stamp === "string" ? stamp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readDeployTemplate(rootDir: string): string | undefined {
+  const stamp = readCursorAgentTemplate(rootDir);
+  if (stamp === undefined || stamp.length === 0 || stamp.length > MAX) {
+    return undefined;
+  }
+  const name = canonicalTemplateName(stamp);
+  return isTemplateName(name) ? name : undefined;
+}