@cursor/july 0.1.2 → 0.1.4

package/src/internal/cli-github.ts

@@ -196,7 +196,7 @@ async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
       );
       return 1;
     }
-    process.stderr.write(`[agent-serve] inferred --repo ${repo}\n`);
+    process.stderr.write(`[agentkit] inferred --repo ${repo}\n`);
   }
 
   const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
@@ -219,30 +219,30 @@ async function cmdGithubForward(options: GithubCliOptions): Promise<number> {
   });
 
   process.stderr.write(
-    `[agent-serve] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`
+    `[agentkit] forwarding ${org !== undefined ? `org ${org}` : `repo ${repo}`} to ${targets.length} channel${targets.length === 1 ? "" : "s"}:\n`
   );
   for (const target of targets) {
     process.stderr.write(
-      `[agent-serve]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`
+      `[agentkit]   → ${targetLabel(target)}  ${target.url}  (${target.events.join(", ")})\n`
     );
   }
   if (fanout) {
     process.stderr.write(
-      `[agent-serve] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`
+      `[agentkit] fan-out proxy on ${forwardUrl} (union events: ${events.join(", ")})\n`
     );
   }
   if (secret === undefined || secret === "") {
     process.stderr.write(
-      "[agent-serve] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n"
+      "[agentkit] no signing secret — deliveries are unsigned. A `serve --dev` github channel accepts them; set GITHUB_WEBHOOK_SECRET on both sides to verify signatures (required for a non-dev target).\n"
     );
   }
   const envToken = detectGitHubEnvTokenOverride();
   if (envToken !== undefined) {
     process.stderr.write(
-      `[agent-serve] warning: ${githubEnvTokenHint(envToken)}\n`
+      `[agentkit] warning: ${githubEnvTokenHint(envToken)}\n`
     );
   }
-  process.stderr.write(`[agent-serve] running: gh ${redact(args)}\n`);
+  process.stderr.write(`[agentkit] running: gh ${redact(args)}\n`);
 
   try {
     return await spawnGh(args);
@@ -318,7 +318,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
   );
   if (unsupported.length > 0) {
     process.stderr.write(
-      `[agent-serve] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
+      `[agentkit] cannot synthesize (skipped): ${unsupported.join(", ")}\n`
     );
   }
   if (eventsToReplay.length === 0) {
@@ -364,9 +364,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
       check,
     });
     if ("error" in result) {
-      process.stderr.write(
-        `[agent-serve] skipping ${event}: ${result.error}\n`
-      );
+      process.stderr.write(`[agentkit] skipping ${event}: ${result.error}\n`);
       continue;
     }
     synthesized.push(result);
@@ -378,7 +376,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
 
   const secret = options.secret ?? process.env.GITHUB_WEBHOOK_SECRET;
   process.stderr.write(
-    `[agent-serve] replaying ${ref.label} (${synthesized
+    `[agentkit] replaying ${ref.label} (${synthesized
       .map((s) => s.eventName)
       .join(
         ", "
@@ -401,7 +399,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
 
     if (options.out !== undefined) {
       const file = await writeReplayFixture(options.out, event);
-      process.stderr.write(`[agent-serve] wrote ${file}\n`);
+      process.stderr.write(`[agentkit] wrote ${file}\n`);
     }
 
     const label = eventLabel(event);
@@ -436,7 +434,7 @@ async function cmdGithubReplay(options: GithubCliOptions): Promise<number> {
               `${delivery.label} ${delivery.status || "ERR"}${delivery.ok ? "" : " (rejected)"}`
           )
           .join(", ") || "(no matching channel)";
-      process.stderr.write(`[agent-serve]   ${label} → ${summary}\n`);
+      process.stderr.write(`[agentkit]   ${label} → ${summary}\n`);
     }
   }
 
@@ -747,7 +745,7 @@ async function ensureWebhookExtension(
     };
   }
   process.stderr.write(
-    `[agent-serve] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`
+    `[agentkit] installing ${GITHUB_WEBHOOK_EXTENSION}@${GITHUB_WEBHOOK_EXTENSION_PIN}…\n`
   );
   if (
     (await tryExec({

package/src/internal/cursor/account-mcp.ts

@@ -231,7 +231,7 @@ export class CursorAccountMcpBridge {
             )
             .join(", ");
           this.logger(
-            `[agent-serve] Cursor account MCP connection "${ref.name}": ${
+            `[agentkit] Cursor account MCP connection "${ref.name}": ${
               catalog.servers.length === 0
                 ? "no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the `servers` filter"
                 : summary
@@ -242,7 +242,7 @@ export class CursorAccountMcpBridge {
           );
           if (needsAuth.length > 0) {
             this.logger(
-              `[agent-serve] Cursor account MCP connection "${ref.name}": ${needsAuth
+              `[agentkit] Cursor account MCP connection "${ref.name}": ${needsAuth
                 .map((server) => server.serverIdentifier)
                 .join(
                   ", "
@@ -252,7 +252,7 @@ export class CursorAccountMcpBridge {
         })
         .catch((error: unknown) => {
           this.logger(
-            `[agent-serve] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
+            `[agentkit] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
           );
         });
     }

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

@@ -445,7 +445,7 @@ export class CursorBackendClient {
       value: body.data.accessToken,
       expiresAtMs: jwtExpiryMs(body.data.accessToken),
     };
-    this.logger("[agent-serve] cursor account: minted a fresh access token");
+    this.logger("[agentkit] cursor account: minted a fresh access token");
     return body.data.accessToken;
   }
 }

package/src/internal/cursor/credentials.ts

@@ -23,6 +23,7 @@ import { z } from "zod";
 import { CLI_COMMAND_NAME } from "../distribution.js";
 
 export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
+export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
 
 /** Backend API base URL (`CURSOR_API_BASE_URL` override for local dev). */
@@ -32,6 +33,19 @@ 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.
+ */
+export function cursorExternalApiUrl(): string {
+  return trimTrailingSlash(
+    process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_EXTERNAL_API_URL
+  );
+}
+
 /** Website base URL for the login deep link (`CURSOR_WEBSITE_URL` override). */
 export function cursorWebsiteUrl(): string {
   return trimTrailingSlash(
@@ -59,18 +73,23 @@ const storedCredentialsSchema: z.ZodObject<
 export type StoredCredentials = z.infer<typeof storedCredentialsSchema>;
 
 /**
- * `~/.config/agent-serve/credentials.json` (0600), honoring
- * `XDG_CONFIG_HOME`. `AGENT_SERVE_CONFIG_DIR` pins the directory outright
- * (tests, containers).
+ * `~/.config/agent-serve/` (honoring `XDG_CONFIG_HOME`), the host-level
+ * config directory for credentials and the update-check cache.
+ * `AGENT_SERVE_CONFIG_DIR` pins the directory outright (tests, containers).
  */
-export function credentialsFilePath(): string {
-  const configDir =
+export function configDirPath(): string {
+  return (
     process.env.AGENT_SERVE_CONFIG_DIR ??
     join(
       process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"),
       "agent-serve"
-    );
-  return join(configDir, "credentials.json");
+    )
+  );
+}
+
+/** `<configDir>/credentials.json` (0600). */
+export function credentialsFilePath(): string {
+  return join(configDirPath(), "credentials.json");
 }
 
 export async function readStoredCredentials(): Promise<

package/src/internal/cursor/github-credentials.ts

@@ -148,14 +148,14 @@ export class CursorGithubCredentialProvider {
         this.scheduleRefresh();
       }
       this.logger(
-        `[agent-serve] GitHub auth: refreshed Cursor account credential for ${this.repos.length} repo(s)`
+        `[agentkit] GitHub auth: refreshed Cursor account credential for ${this.repos.length} repo(s)`
       );
       return result.token;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (this.cached !== undefined && this.now() < this.cached.expiresAtMs) {
         this.logger(
-          `[agent-serve] GitHub auth: Cursor account credential refresh failed; using the current lease: ${message}`
+          `[agentkit] GitHub auth: Cursor account credential refresh failed; using the current lease: ${message}`
         );
         this.cached.refreshAtMs = Math.min(
           this.cached.expiresAtMs,
@@ -207,7 +207,7 @@ export class CursorGithubCredentialProvider {
     this.refreshTimer = setTimeout(() => {
       void this.getToken().catch((error: unknown) => {
         this.logger(
-          `[agent-serve] GitHub auth: Cursor account credential refresh failed: ${
+          `[agentkit] GitHub auth: Cursor account credential refresh failed: ${
             error instanceof Error ? error.message : String(error)
           }`
         );

package/src/internal/cursor-event-relay.ts

@@ -263,7 +263,7 @@ export class CursorEventRelay {
       if (!this.loggedSkippedRepos.has(event.repo)) {
         this.loggedSkippedRepos.add(event.repo);
         this.options.logger(
-          `[agent-serve] cursor-events: skipping events for ${event.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`
+          `[agentkit] cursor-events: skipping events for ${event.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`
         );
       }
       return false;

package/src/internal/cursor-relay-core.ts

@@ -12,6 +12,8 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { LOG_PREFIX } from "./distribution.js";
+
 const OFFSET_SNAPSHOT_VERSION = 1 as const;
 const DEFAULT_POLL_WAIT_MS = 25_000;
 const DEFAULT_POLL_LIMIT = 100;
@@ -98,7 +100,7 @@ interface PollResponse<TEvent> {
  * anchor/poll/dedupe/offset loop, and backoff — is shared.
  */
 export interface RelayAdapter<TEvent extends { offset: string }> {
-  /** Log fragment, e.g. `cursor-events` → `[agent-serve] cursor-events: …`. */
+  /** Log fragment, e.g. `cursor-events` → `[agentkit] cursor-events: …`. */
   readonly logPrefix: string;
   /** Subscription registration path, e.g. `/v0/scm-events/subscriptions`. */
   readonly subscribePath: string;
@@ -231,7 +233,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
 
   private log(line: string): void {
     this.options.logger(
-      `[agent-serve] ${this.options.adapter.logPrefix}: ${line}`
+      `${LOG_PREFIX} ${this.options.adapter.logPrefix}: ${line}`
     );
   }
 

package/src/internal/cursor-slack-relay.ts

@@ -122,7 +122,7 @@ export function createCursorSlackApiCaller(args: {
       };
     } catch (error) {
       args.logger?.(
-        `[agent-serve] cursor-slack: ${method} proxy call failed: ${describeRelayError(error)}`
+        `[agentkit] cursor-slack: ${method} proxy call failed: ${describeRelayError(error)}`
       );
       return { ok: false, error: "cursor_backend_unreachable" };
     }

package/src/internal/deploy-client.ts

@@ -27,6 +27,18 @@ export type DeploymentStatus =
   | "stopping"
   | "stopped";
 
+/** Customer-safe deploy progress (no hosting phase / infra names). */
+export type DeploymentProgress =
+  | "queued"
+  | "preparing"
+  | "building"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "degraded";
+
 export const TERMINAL_DEPLOY_STATUSES: ReadonlySet<DeploymentStatus> = new Set([
   "running",
   "degraded",
@@ -118,6 +130,11 @@ export interface Deployment {
   agentPath?: string;
   desiredState?: string;
   status: DeploymentStatus;
+  /**
+   * Customer-safe deploy progress (no hosting internals). Present on newer
+   * backends; older responses omit it.
+   */
+  progress?: DeploymentProgress;
   generation: number;
   observedGeneration?: number | null;
   engineGeneration?: number | null;
@@ -131,7 +148,8 @@ export interface Deployment {
   cursorEventRepos?: string[];
   /** Normalized egress allowlist for the engine pod. */
   egressAllowedDomains?: string[];
-  serviceAccountId?: number | null;
+  /** Service-account id (`sa_…`); null on legacy rows. */
+  serviceAccountId?: string | number | null;
   /** Masked pod credential; the raw key is never returned. */
   podCredentialMaskedKey?: string | null;
   /** Names of the secrets set on the deployment (values never returned). */
@@ -196,6 +214,19 @@ const deploymentSchema = z.object({
     "stopping",
     "stopped",
   ]),
+  progress: z
+    .enum([
+      "queued",
+      "preparing",
+      "building",
+      "finalizing",
+      "running",
+      "failed",
+      "stopping",
+      "stopped",
+      "degraded",
+    ])
+    .optional(),
   generation: z.number(),
   observedGeneration: z.number().nullable().optional(),
   engineGeneration: z.number().nullable().optional(),
@@ -207,8 +238,9 @@ const deploymentSchema = z.object({
   lastReconciledAt: z.string().nullable().optional(),
   cursorEventRepos: z.array(z.string()).optional(),
   egressAllowedDomains: z.array(z.string()).optional(),
-  // Null on legacy rows that predate service-account-backed deploys.
-  serviceAccountId: z.number().nullable().optional(),
+  // String ids (`sa_…`) in prod; older mocks/fixtures used numbers. Null on
+  // legacy rows that predate service-account-backed deploys.
+  serviceAccountId: z.union([z.string(), z.number()]).nullable().optional(),
   podCredentialMaskedKey: z.string().nullable().optional(),
   secretNames: z.array(z.string()).optional(),
 });
@@ -552,13 +584,22 @@ function mapErrorResponse(
         `${serverError ?? "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`,
         403
       );
-    case 404:
+    case 404: {
+      // Fastify's route-not-found envelope means we hit the wrong host
+      // (api2 vs api.cursor.com), not a missing deployment / closed gate.
+      if (/Route \S+ not found/i.test(bodyText)) {
+        return new DeployApiError(
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          404
+        );
+      }
       return new DeployApiError(
         context.slug === undefined
           ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`
           : `Deployment${slugPart} was not found — check the slug and --team, or the agent_serve_mvp feature gate may not be enabled for your team.`,
         404
       );
+    }
     case 409:
       return new DeployApiError(
         `A concurrent deploy or stop is changing deployment${slugPart}; retry in a moment.`,

package/src/internal/deploy-source.ts

@@ -0,0 +1,133 @@
+/**
+ * Infer `agentkit deploy` git source fields from a local checkout.
+ *
+ * From an agent directory inside a git repo with an `origin` remote, the
+ * CLI can fill `--repo` / `--ref` / `--path` so `agentkit deploy` (no
+ * flags) is enough. Explicit flags always win.
+ */
+
+import { execFile } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** Injectable git runner (cwd + args → stdout, or undefined on failure). */
+export type GitRunner = (
+  args: readonly string[],
+  cwd: string
+) => Promise<string | undefined>;
+
+export interface InferredDeploySource {
+  gitRepoUrl?: string;
+  gitRef?: string;
+  /** Agent directory relative to the repo root (posix). Omitted at root. */
+  agentPath?: string;
+}
+
+const defaultGitRunner: GitRunner = async (args, cwd) => {
+  try {
+    const { stdout } = await execFileAsync("git", [...args], { cwd });
+    const trimmed = stdout.trim();
+    return trimmed === "" ? undefined : trimmed;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Normalize a git remote URL to the https form the control plane accepts
+ * (`https://host/owner/repo`, no `.git` suffix). Returns undefined for
+ * unrecognized shapes.
+ */
+export function httpsGitRepoUrlFromRemote(remote: string): string | undefined {
+  let url = remote.trim();
+  if (url === "") {
+    return undefined;
+  }
+  if (url.startsWith("git@")) {
+    // git@host:owner/repo.git → https://host/owner/repo.git
+    url = `https://${url.slice("git@".length).replace(":", "/")}`;
+  } else if (url.startsWith("ssh://git@")) {
+    url = `https://${url.slice("ssh://git@".length)}`;
+  } else if (!/^https?:\/\//i.test(url)) {
+    return undefined;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const path = parsed.pathname
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "")
+    .replace(/^\/+/, "");
+  if (path === "" || !path.includes("/")) {
+    return undefined;
+  }
+  // Use hostname (not host) so ssh://git@github.com:22/… does not keep :22.
+  return `https://${parsed.hostname}/${path}`;
+}
+
+/**
+ * Path of `dir` relative to `gitRoot`, using `/` separators. Undefined when
+ * `dir` is outside the root; omitted (undefined) when `dir` *is* the root
+ * so the control plane treats the agent as living at the repo root.
+ */
+export function agentPathRelativeToGitRoot(
+  dir: string,
+  gitRoot: string
+): string | undefined {
+  const absDir = resolve(dir);
+  const absRoot = resolve(gitRoot);
+  const rel = relative(absRoot, absDir);
+  if (rel === "") {
+    return undefined;
+  }
+  // Outside the repo (or a Windows drive mismatch) → cannot infer.
+  if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+    return undefined;
+  }
+  return rel.split(sep).join("/");
+}
+
+/**
+ * Probe the git checkout containing `dir` for deploy source fields.
+ * Missing pieces stay undefined (static deploy / server defaults).
+ */
+export async function inferDeployGitSource(
+  dir: string,
+  options?: { git?: GitRunner }
+): Promise<InferredDeploySource> {
+  const git = options?.git ?? defaultGitRunner;
+  const absDir = resolve(dir);
+
+  const gitRoot = await git(["rev-parse", "--show-toplevel"], absDir);
+  if (gitRoot === undefined) {
+    return {};
+  }
+
+  const remote = await git(["remote", "get-url", "origin"], gitRoot);
+  const gitRepoUrl =
+    remote === undefined ? undefined : httpsGitRepoUrlFromRemote(remote);
+
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], gitRoot);
+  let gitRef: string | undefined;
+  if (branch !== undefined && branch !== "HEAD") {
+    gitRef = branch;
+  } else {
+    // Detached HEAD — pin the exact commit so the control plane still
+    // has something concrete to build.
+    gitRef = await git(["rev-parse", "HEAD"], gitRoot);
+  }
+
+  const agentPath = agentPathRelativeToGitRoot(absDir, gitRoot);
+
+  return {
+    gitRepoUrl,
+    gitRef,
+    agentPath,
+  };
+}

package/src/internal/discovery.ts

@@ -61,6 +61,7 @@ import {
 } from "./hosting.js";
 import { toolInputJsonSchema } from "./json-schema.js";
 import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
+import { withIdentityPreamble } from "./workspace.js";
 
 const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
 const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -105,23 +106,26 @@ export async function isAgentProjectDir(dir: string): Promise<boolean> {
   return hasFlatLayoutMarkers(resolved);
 }
 
+/** One immediate child agent directory under a multi-agent parent. */
+export interface ChildAgentDir {
+  slug: string;
+  dir: string;
+}
+
 /**
- * Discover the agent projects directly under `rootDir` (one level deep):
- * each immediate child directory that is itself an agent project becomes a
- * mounted agent, keyed by a slug derived from its directory name. Used for
- * multi-agent serving, where one server hosts many agents under
- * `/<slug>/...`. Throws when no child projects are found.
+ * List agent projects directly under `rootDir` (one level deep) without
+ * loading them. Empty when the path is missing or has no child agents.
+ * Slug rules match {@link loadAgentProjects} / multi-agent serve.
  */
-export async function loadAgentProjects(
-  rootDir: string,
-  options: LoadAgentProjectOptions = {}
-): Promise<Array<{ slug: string; project: AgentProject }>> {
+export async function listChildAgentDirs(
+  rootDir: string
+): Promise<ChildAgentDir[]> {
   const resolved = resolve(rootDir);
   if (!(await isDirectory(resolved))) {
-    throw new Error(`Agent projects directory does not exist: ${resolved}`);
+    return [];
   }
 
-  const results: Array<{ slug: string; project: AgentProject }> = [];
+  const results: ChildAgentDir[] = [];
   const seenSlugs = new Set<string>();
   for (const entry of await sortedEntries(resolved)) {
     if (!entry.isDirectory() || entry.name.startsWith(".")) {
@@ -139,14 +143,40 @@ export async function loadAgentProjects(
       throw new Error(`Duplicate agent slug "${slug}" under ${resolved}.`);
     }
     seenSlugs.add(slug);
-    results.push({ slug, project: await loadAgentProject(childDir, options) });
+    results.push({ slug, dir: childDir });
+  }
+  return results;
+}
+
+/**
+ * Discover the agent projects directly under `rootDir` (one level deep):
+ * each immediate child directory that is itself an agent project becomes a
+ * mounted agent, keyed by a slug derived from its directory name. Used for
+ * multi-agent serving, where one server hosts many agents under
+ * `/<slug>/...`. Throws when no child projects are found.
+ */
+export async function loadAgentProjects(
+  rootDir: string,
+  options: LoadAgentProjectOptions = {}
+): Promise<Array<{ slug: string; project: AgentProject }>> {
+  const resolved = resolve(rootDir);
+  if (!(await isDirectory(resolved))) {
+    throw new Error(`Agent projects directory does not exist: ${resolved}`);
   }
 
-  if (results.length === 0) {
+  const children = await listChildAgentDirs(resolved);
+  if (children.length === 0) {
     throw new Error(
       `No agent projects found directly under ${resolved}. Each agent should be a subdirectory with its own agent/ directory (or flat-layout markers).`
     );
   }
+  const results: Array<{ slug: string; project: AgentProject }> = [];
+  for (const child of children) {
+    results.push({
+      slug: child.slug,
+      project: await loadAgentProject(child.dir, options),
+    });
+  }
   return results;
 }
 
@@ -287,12 +317,19 @@ async function loadAgent(
   options: { name: string; isRoot: boolean }
 ): Promise<ResolvedAgent> {
   const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
-  const instructions = await loadInstructions(
+  const name = config?.name ?? options.name;
+  const authoredInstructions = await loadInstructions(
     ctx,
     agentDir,
     config,
     options.isRoot
   );
+  // Root agents without authored instructions stay undefined (diagnostic
+  // already recorded). Subagents still get the identity line alone.
+  const instructions =
+    authoredInstructions === undefined && options.isRoot
+      ? undefined
+      : withIdentityPreamble(name, authoredInstructions);
 
   // Subagents run as Cursor SDK custom subagents (prompt + description +
   // model); their other slots are inert today, so don't load them — just
@@ -300,7 +337,7 @@ async function loadAgent(
   if (!options.isRoot) {
     await warnUnsupportedSubagentSlots(ctx, agentDir);
     return {
-      name: config?.name ?? options.name,
+      name,
       ...(config?.description === undefined
         ? {}
         : { description: config.description }),
@@ -347,7 +384,7 @@ async function loadAgent(
   }
 
   return {
-    name: config?.name ?? options.name,
+    name,
     description: config?.description,
     // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
     model: isValidModelSetting(config?.model) ? config.model : DEFAULT_MODEL,

package/src/internal/distribution.ts

@@ -25,6 +25,14 @@ export const LEGACY_PACKAGE_NAME = "@anysphere/agent-serve";
  */
 export const AGENTKIT_PACKAGE_NAME = "@cursor/agentkit";
 
+/**
+ * Bracketed product tag for stderr / ServeOptions.logger lines
+ * (`[agentkit] …`, `[agentkit/slack] …`).
+ */
+export const LOG_PRODUCT = "agentkit";
+export const LOG_PREFIX: string = `[${LOG_PRODUCT}]`;
+export const SLACK_LOG_PREFIX: string = `[${LOG_PRODUCT}/slack]`;
+
 /**
  * Command name this CLI was invoked as. Both bins point at the same entry;
  * keep help text and hints copy-pasteable for whichever the user typed.

package/src/internal/docs-site.ts

@@ -109,11 +109,11 @@ export async function ensureDocsSiteBundle(
   const toolchain = resolveDocsToolchain();
   if (toolchain === undefined) {
     logger(
-      "[agent-serve] docs site missing and vitepress toolchain unavailable; /docs will show a build hint"
+      "[agentkit] docs site missing and vitepress toolchain unavailable; /docs will show a build hint"
     );
     return;
   }
-  logger("[agent-serve] building docs site (vitepress)...");
+  logger("[agentkit] building docs site (vitepress)...");
   const code = await new Promise<number>((resolve, reject) => {
     const child = spawn(
       process.execPath,
@@ -131,7 +131,7 @@ export async function ensureDocsSiteBundle(
       "docs vitepress build finished but dist/docs/index.html is missing"
     );
   }
-  logger("[agent-serve] docs site build complete");
+  logger("[agentkit] docs site build complete");
 }
 
 interface DocsToolchain {