@stigmer/runner 3.0.1

package/src/activities/execute-cursor/session-lifecycle.ts

@@ -0,0 +1,429 @@
+/**
+ * Maps Stigmer Session lifecycle to Cursor Agent lifecycle.
+ *
+ * SessionSpec.harness_state_id stores the Cursor agentId. This module handles
+ * creating new agents (first execution), resuming existing agents
+ * (subsequent executions), graceful fallback on resume failure, and
+ * cleaning up agents (session deletion).
+ *
+ * Two execution modes:
+ *
+ * - Local mode: Agent.create({ local: { cwd } }) with explicit
+ *   platform.workspaceRef/stateRoot for deterministic store keying.
+ *   Produces agent- prefixed IDs.
+ *
+ * - Cloud mode (feature-flagged): Agent.create({ cloud: { repos } })
+ *   for git-backed workspaces. Produces bc- prefixed IDs. No platform
+ *   options — cloud state lives on Cursor's servers, not local SQLite.
+ *
+ * Key SDK limitation: mcpServers are NOT persisted across Agent.resume().
+ * They must be passed again on every resume call.
+ *
+ * Platform store keying (local only): The Cursor SDK defaults to
+ * process.cwd() for its internal state root lookup. In cloud sandboxes,
+ * process.cwd() is the runner's app directory, not the workspace — causing
+ * Agent.resume() to fail with "Agent not found". We pass explicit
+ * platform.workspaceRef and platform.stateRoot derived from the Stigmer
+ * sessionId to ensure deterministic store lookup regardless of process.cwd().
+ *
+ * Durability model: the SDK's local SQLite store (agent records, runs,
+ * checkpoints) is the source of truth for conversation continuation. It is
+ * persisted under the durable workspace volume (see resolvePlatformOptions)
+ * so Agent.resume() survives pod restart, reschedule, and snapshot restore.
+ * When resume nonetheless fails (store lost, corrupted, or agent unknown),
+ * this module creates a fresh agent and the caller starts a new turn from
+ * the user message plus re-injected instructions — there is no separate
+ * continuation store.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { Agent } from "@cursor/sdk";
+import type { SDKAgent, CursorAgentPlatformOptions, AgentDefinition } from "@cursor/sdk";
+import type { CursorMcpServerConfig } from "./mcp-resolver.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CURSOR_SDK_STATE_DIR = ".stigmer/cursor-sdk-state";
+
+/**
+ * Cursor SDK setting sources loaded for LOCAL agents.
+ *
+ * The Stigmer HITL approval gate is a `.cursor/hooks.json` preToolUse hook
+ * written into the workspace (see workspace-setup.ts). The Cursor SDK only
+ * loads workspace ("project") hooks when the "project" setting source is
+ * enabled — internally `includeProjectHooks = settingSources.includes("project")`
+ * (and the hooks subsystem itself is only constructed when a project/user
+ * source is present). The SDK default is `[]` ("inline config only"), which
+ * silently drops the hook and disables the entire approval gate. We must opt
+ * in to "project" so the hook loads and tool calls are actually gated.
+ *
+ * Side effect: this also loads other workspace `.cursor/*` config (rules,
+ * mcp.json, commands). For runner-provisioned workspaces that is inert; for
+ * sessions running on a user's own repo their project config is now honored.
+ *
+ * Cloud agents always load project settings server-side, so this is local-only.
+ */
+const LOCAL_SETTING_SOURCES = ["project"] as const;
+
+// ---------------------------------------------------------------------------
+// Public types — local mode
+// ---------------------------------------------------------------------------
+
+export interface CreateAgentOptions {
+  apiKey: string;
+  model: string;
+  workspaceDirs: string[];
+  sessionId: string;
+  /** Durable workspace volume root; the SDK state store lives under it. */
+  workspaceRootDir: string;
+  mcpServers?: Record<string, CursorMcpServerConfig>;
+  /**
+   * Custom sub-agents registered with the Cursor SDK so the parent can delegate
+   * to them by name via the Task tool. Not persisted across resume, so it must
+   * be re-supplied on every create/resume (mirrors mcpServers).
+   */
+  agents?: Record<string, AgentDefinition>;
+}
+
+export interface ResumeAgentOptions {
+  apiKey: string;
+  agentId: string;
+  sessionId: string;
+  /** Durable workspace volume root; the SDK state store lives under it. */
+  workspaceRootDir: string;
+  model?: string;
+  mcpServers?: Record<string, CursorMcpServerConfig>;
+  /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+  agents?: Record<string, AgentDefinition>;
+}
+
+// ---------------------------------------------------------------------------
+// Public types — cloud mode
+// ---------------------------------------------------------------------------
+
+export interface CloudRepo {
+  url: string;
+  startingRef?: string;
+}
+
+export interface CreateCloudAgentOptions {
+  apiKey: string;
+  model?: string;
+  repos: CloudRepo[];
+  sessionId: string;
+  mcpServers?: Record<string, CursorMcpServerConfig>;
+  /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+  agents?: Record<string, AgentDefinition>;
+}
+
+export interface ResumeCloudAgentOptions {
+  apiKey: string;
+  agentId: string;
+  model?: string;
+  mcpServers?: Record<string, CursorMcpServerConfig>;
+  /** Custom sub-agents — see {@link CreateAgentOptions.agents}. */
+  agents?: Record<string, AgentDefinition>;
+}
+
+// ---------------------------------------------------------------------------
+// Public types — resolution result
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated reason explaining how the agent was resolved.
+ *
+ * Drives prompt selection in execute-cursor.ts:
+ * - created_first_execution: first turn, fresh agent
+ * - resumed_successfully: subsequent turn, agent alive (native context)
+ * - created_after_resume_failure: agent unknown/lost, fresh agent (no prior context)
+ */
+export type AgentResolutionReason =
+  | "created_first_execution"
+  | "resumed_successfully"
+  | "created_after_resume_failure";
+
+/**
+ * Result of resolveAgent() — carries the agent handle plus metadata that
+ * downstream phases use for prompt selection, harness_state_id persistence, and
+ * diagnostic logging.
+ */
+export interface AgentResolution {
+  agent: SDKAgent;
+  agentId: string;
+  isNew: boolean;
+  resumed: boolean;
+  mode: "local" | "cloud";
+  reason: AgentResolutionReason;
+  /** Non-empty only when reason is "created_after_resume_failure". */
+  resumeFailureDetail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Local agent functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute deterministic platform options for a Stigmer session.
+ *
+ * workspaceRef is a synthetic identifier (not a filesystem path) that
+ * ensures the SDK's platform cache key is stable across activity
+ * invocations regardless of process.cwd().
+ *
+ * stateRoot is a session-isolated directory under the durable workspace
+ * volume ({workspaceRootDir}/.stigmer/cursor-sdk-state/{sessionId}) where
+ * the SDK persists its SQLite stores (agent records, runs, checkpoints).
+ * Placing it on the workspace volume (rather than $HOME) makes native
+ * Agent.resume() survive pod restart/reschedule and snapshot restore, and
+ * keys it by sessionId so sessions sharing one volume (e.g. the child agent
+ * executions of a workflow sandbox) never collide. Created eagerly to
+ * prevent ENOENT on first SDK write.
+ *
+ * Both inputs are required and must be non-empty: the stateRoot is keyed by
+ * sessionId, so an empty sessionId would collapse every session sharing the
+ * volume onto the same store and corrupt their conversation state.
+ */
+export function resolvePlatformOptions(
+  sessionId: string,
+  workspaceRootDir: string,
+): CursorAgentPlatformOptions {
+  if (!sessionId) {
+    throw new Error(
+      "resolvePlatformOptions: sessionId is required but was empty. The Cursor SDK " +
+      "state store is keyed by sessionId; an empty value would collide across sessions " +
+      "sharing a workspace volume (e.g. a workflow sandbox's child agent executions).",
+    );
+  }
+  if (!workspaceRootDir) {
+    throw new Error(
+      "resolvePlatformOptions: workspaceRootDir is required but was empty. The Cursor " +
+      "SDK state store must live on the durable workspace volume to survive restarts.",
+    );
+  }
+  const stateRoot = join(workspaceRootDir, CURSOR_SDK_STATE_DIR, sessionId);
+  mkdirSync(stateRoot, { recursive: true });
+  return {
+    workspaceRef: `stigmer-session:${sessionId}`,
+    stateRoot,
+  };
+}
+
+/**
+ * Create a new local Cursor Agent for the first execution in a session.
+ *
+ * Supports multi-workspace: passes string[] when multiple dirs, string when single.
+ */
+export async function createAgent(options: CreateAgentOptions): Promise<SDKAgent> {
+  const cwd = options.workspaceDirs.length === 1
+    ? options.workspaceDirs[0]
+    : options.workspaceDirs;
+
+  const platform = resolvePlatformOptions(options.sessionId, options.workspaceRootDir);
+  console.log(
+    `createAgent: sessionId=${options.sessionId}, workspaceRef=${platform.workspaceRef}, ` +
+    `stateRoot=${platform.stateRoot}, process.cwd=${process.cwd()}`,
+  );
+
+  return Agent.create({
+    apiKey: options.apiKey,
+    model: { id: options.model },
+    local: { cwd, settingSources: [...LOCAL_SETTING_SOURCES] },
+    mcpServers: options.mcpServers as Record<string, any>,
+    agents: options.agents,
+    platform,
+  });
+}
+
+/**
+ * Resume an existing local Cursor Agent for subsequent executions.
+ *
+ * Throws on failure — the caller (resolveAgent) decides whether to
+ * propagate or fall back to a fresh agent with continuation context.
+ */
+export async function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent> {
+  const platform = resolvePlatformOptions(options.sessionId, options.workspaceRootDir);
+  console.log(
+    `resumeAgent: agentId=${options.agentId}, sessionId=${options.sessionId}, ` +
+    `workspaceRef=${platform.workspaceRef}, stateRoot=${platform.stateRoot}, ` +
+    `process.cwd=${process.cwd()}`,
+  );
+
+  return Agent.resume(options.agentId, {
+    apiKey: options.apiKey,
+    model: options.model ? { id: options.model } : undefined,
+    // settingSources are not persisted across resume, so the "project" source
+    // (which loads the HITL approval hook) must be re-supplied every turn.
+    local: { settingSources: [...LOCAL_SETTING_SOURCES] },
+    mcpServers: options.mcpServers as Record<string, any>,
+    agents: options.agents,
+    platform,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Cloud agent functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new cloud Cursor Agent for git-backed sessions.
+ *
+ * Cloud agents (bc- prefix) run on Cursor's servers with cloned repos.
+ * No platform options — cloud state lives server-side, not in local SQLite.
+ * Model is optional — Cursor resolves the caller's configured default
+ * when omitted.
+ */
+export async function createCloudAgent(options: CreateCloudAgentOptions): Promise<SDKAgent> {
+  console.log(
+    `createCloudAgent: sessionId=${options.sessionId}, ` +
+    `repos=${options.repos.map((r) => r.url).join(", ")}`,
+  );
+
+  return Agent.create({
+    apiKey: options.apiKey,
+    model: options.model ? { id: options.model } : undefined,
+    cloud: { repos: options.repos },
+    mcpServers: options.mcpServers as Record<string, any>,
+    agents: options.agents,
+  });
+}
+
+/**
+ * Resume an existing cloud Cursor Agent for subsequent executions.
+ *
+ * Throws on failure — the caller (resolveAgent) decides whether to
+ * propagate or fall back to a fresh cloud agent with continuation context.
+ * No platform options — cloud state lives server-side.
+ */
+export async function resumeCloudAgent(options: ResumeCloudAgentOptions): Promise<SDKAgent> {
+  console.log(
+    `resumeCloudAgent: agentId=${options.agentId}`,
+  );
+
+  return Agent.resume(options.agentId, {
+    apiKey: options.apiKey,
+    model: options.model ? { id: options.model } : undefined,
+    mcpServers: options.mcpServers as Record<string, any>,
+    agents: options.agents,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Unified resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a Cursor Agent for execution: resume if possible, create with
+ * graceful fallback if resume fails.
+ *
+ * The mode parameter determines which create/resume functions are used:
+ * - "local": createAgent / resumeAgent (with platform options)
+ * - "cloud": createCloudAgent / resumeCloudAgent (no platform options)
+ *
+ * When harnessStateId is non-empty (subsequent execution):
+ *   1. Attempt Agent.resume with mode-appropriate options.
+ *   2. On success: return { resumed: true, reason: "resumed_successfully" }.
+ *   3. On failure: log warning, create a fresh agent, return
+ *      { resumed: false, reason: "created_after_resume_failure" }.
+ *      The fresh agent has no prior conversation context; the caller
+ *      starts a new turn from the user message and re-injected instructions.
+ *
+ * When harnessStateId is empty (first execution):
+ *   Create a new agent; return { reason: "created_first_execution" }.
+ *
+ * Agent creation failures always propagate — if we cannot create an agent
+ * at all, that is an unrecoverable infrastructure error.
+ */
+export async function resolveAgent(
+  harnessStateId: string,
+  options: CreateAgentOptions | CreateCloudAgentOptions,
+  mode: "local" | "cloud" = "local",
+): Promise<AgentResolution> {
+  if (harnessStateId) {
+    try {
+      const agent = mode === "cloud"
+        ? await resumeCloudAgent({
+            apiKey: options.apiKey,
+            agentId: harnessStateId,
+            model: options.model,
+            mcpServers: options.mcpServers,
+            agents: options.agents,
+          })
+        : await resumeAgent({
+            apiKey: options.apiKey,
+            agentId: harnessStateId,
+            sessionId: (options as CreateAgentOptions).sessionId,
+            workspaceRootDir: (options as CreateAgentOptions).workspaceRootDir,
+            model: options.model,
+            mcpServers: options.mcpServers,
+            agents: options.agents,
+          });
+
+      return {
+        agent,
+        agentId: agent.agentId,
+        isNew: false,
+        resumed: true,
+        mode,
+        reason: "resumed_successfully",
+      };
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `resolveAgent: resume failed for ${mode} agent "${harnessStateId}", ` +
+        `creating fresh agent (no prior context). ` +
+        `sessionId=${options.sessionId}, error: ${detail}`,
+      );
+
+      const agent = mode === "cloud"
+        ? await createCloudAgent(options as CreateCloudAgentOptions)
+        : await createAgent(options as CreateAgentOptions);
+
+      console.log(
+        `resolveAgent: fallback ${mode} agent created. ` +
+        `oldAgentId=${harnessStateId}, newAgentId=${agent.agentId}, ` +
+        `sessionId=${options.sessionId}`,
+      );
+
+      return {
+        agent,
+        agentId: agent.agentId,
+        isNew: true,
+        resumed: false,
+        mode,
+        reason: "created_after_resume_failure",
+        resumeFailureDetail: detail,
+      };
+    }
+  }
+
+  const agent = mode === "cloud"
+    ? await createCloudAgent(options as CreateCloudAgentOptions)
+    : await createAgent(options as CreateAgentOptions);
+
+  return {
+    agent,
+    agentId: agent.agentId,
+    isNew: true,
+    resumed: false,
+    mode,
+    reason: "created_first_execution",
+  };
+}
+
+/**
+ * Dispose a Cursor Agent when a session is deleted.
+ * Best-effort: logs and swallows errors.
+ */
+export async function disposeAgent(agentId: string, apiKey: string): Promise<void> {
+  try {
+    await Agent.archive(agentId, { apiKey });
+  } catch (err) {
+    console.warn(
+      `Failed to archive Cursor agent ${agentId}:`,
+      err instanceof Error ? err.message : err,
+    );
+  }
+}

package/src/activities/execute-cursor/skill-resolver.ts

@@ -0,0 +1,176 @@
+/**
+ * Resolves skill resources and writes them to the platform-managed directory.
+ *
+ * - Fetches skills via gRPC (by reference)
+ * - Writes SKILL.md to .stigmer/skills/{name}/SKILL.md
+ * - Downloads and extracts ZIP artifacts (references/, scripts/, etc.)
+ * - Uses a platform-managed directory outside the workspace
+ * - Creates a symlink from the workspace to the platform dir
+ * - Returns metadata for prompt injection
+ */
+
+import { mkdir, writeFile, symlink, readlink, unlink, rm } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { SkillMetadata } from "./prompt-builder.js";
+import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
+import { extractZipFileEntries } from "../../shared/zip-extract.js";
+
+const STIGMER_LOCAL_STATE_DIR = ".stigmer";
+const SKILLS_SUBDIR = "skills";
+
+export interface SkillResolverOptions {
+  sessionId: string;
+  primaryWorkspaceDir: string;
+}
+
+/**
+ * Resolve skill references into written SKILL.md files and prompt metadata.
+ *
+ * Platform mount pattern: skills are written to
+ * ~/.stigmer/sessions/{sessionId}/platform/skills/{name}/SKILL.md
+ * with a symlink from {workspace}/.stigmer -> the platform dir.
+ */
+export async function resolveSkills(
+  client: StigmerClient,
+  skillRefs: ApiResourceReference[],
+  options: SkillResolverOptions,
+): Promise<SkillMetadata[]> {
+  console.log(
+    `[resolveSkills] sessionId=${options.sessionId}, ` +
+    `primaryWorkspaceDir=${options.primaryWorkspaceDir ?? "(undefined)"}, ` +
+    `skillRefCount=${skillRefs.length}, ` +
+    `refs=[${skillRefs.map(r => `${r.org || "(default)"}/${r.slug}`).join(", ")}]`,
+  );
+
+  if (skillRefs.length === 0) return [];
+
+  const platformDir = getPlatformDir(options.sessionId);
+  const skillsDir = join(platformDir, SKILLS_SUBDIR);
+  await mkdir(skillsDir, { recursive: true });
+
+  await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
+  console.log(
+    `[resolveSkills] symlink created: ${join(options.primaryWorkspaceDir, STIGMER_LOCAL_STATE_DIR)} -> ${platformDir}`,
+  );
+
+  const results: SkillMetadata[] = [];
+
+  for (const ref of skillRefs) {
+    try {
+      const skill = await client.getSkillByReference(ref);
+
+      let artifactBytes: Uint8Array | undefined;
+      if (skill.status?.artifactStorageKey) {
+        try {
+          const resp = await client.getSkillArtifact(skill.status.artifactStorageKey);
+          if (resp.artifact && resp.artifact.length > 0) {
+            artifactBytes = resp.artifact;
+          }
+        } catch (err) {
+          console.warn(
+            `[resolveSkills] artifact download failed for ${ref.slug}, ` +
+            `falling back to SKILL.md only: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
+
+      const meta = await writeSkill(skill, skillsDir, options.primaryWorkspaceDir, artifactBytes);
+      if (meta) {
+        results.push(meta);
+        console.log(`[resolveSkills] wrote skill: ${meta.name} -> ${meta.path}`);
+      } else {
+        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
+      }
+    } catch (err) {
+      console.warn(
+        `[resolveSkills] failed to resolve skill ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  console.log(
+    `[resolveSkills] completed: ${results.length}/${skillRefs.length} skills resolved`,
+  );
+
+  return results;
+}
+
+async function writeSkill(
+  skill: Skill,
+  skillsDir: string,
+  workspaceDir: string,
+  artifactBytes?: Uint8Array,
+): Promise<SkillMetadata | null> {
+  const spec = skill.spec;
+  if (!spec?.skillMd) return null;
+
+  const name = spec.name || skill.metadata?.slug || "unknown";
+  const skillDir = join(skillsDir, name);
+  await mkdir(skillDir, { recursive: true });
+
+  const skillMdPath = join(skillDir, "SKILL.md");
+  await writeFile(skillMdPath, spec.skillMd, "utf-8");
+
+  if (artifactBytes && artifactBytes.length > 0) {
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md"] });
+    for (const entry of entries) {
+      const filePath = join(skillDir, entry.path);
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, entry.content, "utf-8");
+    }
+  }
+
+  const relativePath = join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md");
+
+  return {
+    name,
+    description: spec.description || `Skill: ${name}`,
+    path: relativePath,
+  };
+}
+
+/**
+ * Ensure .stigmer symlink in the workspace points to the platform dir.
+ *
+ * The Cursor SDK reads files from the workspace CWD, so we need the
+ * .stigmer directory to be accessible there. Unlike the Python runner
+ * which intercepts file paths, Cursor reads directly from the filesystem.
+ */
+async function ensureStigmerSymlink(
+  workspaceDir: string,
+  platformDir: string,
+): Promise<void> {
+  const linkPath = join(workspaceDir, STIGMER_LOCAL_STATE_DIR);
+
+  try {
+    const existing = await readlink(linkPath);
+    if (existing === platformDir) return;
+    await unlink(linkPath);
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      // No existing symlink
+    } else if (err.code === "EINVAL") {
+      // Exists but is not a symlink — remove the directory
+      await rm(linkPath, { recursive: true, force: true });
+    } else {
+      throw err;
+    }
+  }
+
+  await symlink(platformDir, linkPath, "dir");
+}
+
+/**
+ * Clean up platform-managed skill directory for a session.
+ */
+export async function cleanupSkills(sessionId: string): Promise<void> {
+  const platformDir = getPlatformDir(sessionId);
+  try {
+    await rm(platformDir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}

package/src/activities/execute-cursor/subagent-config.ts

@@ -0,0 +1,62 @@
+/**
+ * Maps Stigmer SubAgent blueprints to Cursor SDK custom sub-agent definitions.
+ *
+ * The Cursor SDK registers custom sub-agents via `AgentOptions.agents`
+ * (`Record<name, AgentDefinition>`). Once registered, the parent agent can
+ * delegate to them by name through the Task tool. This is the capability that
+ * makes blueprint sub-agents actually invokable on the Cursor harness — parity
+ * with the native deepagents harness, which compiles them into the graph.
+ *
+ * Known limitations (Cursor SDK, not Stigmer):
+ * - Per-sub-agent MCP tool filtering is NOT supported: custom sub-agents
+ *   inherit the parent agent's MCP config (`SDKCustomSubagentDefinition` has no
+ *   `mcpServers` field). A blueprint's `mcp_access` is therefore surfaced only
+ *   as advisory prompt context, not enforced as an isolation boundary.
+ * - Built-in kinds (`explore`, `shell`, `generalPurpose`) are provided by
+ *   Cursor's own runtime and must NOT be registered here — doing so would
+ *   shadow the native ones. They are encouraged via prompt guidance instead.
+ *
+ * Because the SDK does not persist agent configuration across `Agent.resume()`
+ * (the same constraint that applies to `mcpServers`), the result of this
+ * mapper must be supplied on every create AND resume call so the delegation
+ * capability survives across turns.
+ */
+
+import type { AgentDefinition } from "@cursor/sdk";
+import type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+
+/**
+ * Build the Cursor SDK `agents` map from blueprint sub-agents.
+ *
+ * Returns `undefined` (rather than an empty object) when there are no usable
+ * entries, so callers can omit the `agents` option entirely.
+ *
+ * @param subAgents Blueprint sub-agents from `Agent.spec.sub_agents`.
+ */
+export function buildCursorSubAgentDefinitions(
+  subAgents: readonly SubAgent[],
+): Record<string, AgentDefinition> | undefined {
+  if (subAgents.length === 0) return undefined;
+
+  const agents: Record<string, AgentDefinition> = {};
+  for (const sa of subAgents) {
+    const name = sa.name?.trim();
+    // The name is the SDK registration key and the handle the model uses to
+    // delegate. Skip entries without one rather than register an unaddressable
+    // sub-agent.
+    if (!name) continue;
+
+    // instructions is the sub-agent's system prompt. The proto requires it
+    // (min_len 10), but fall back defensively so a malformed blueprint still
+    // produces an invokable sub-agent instead of being silently dropped.
+    const prompt = sa.instructions?.trim() || sa.description?.trim() || name;
+
+    agents[name] = {
+      description: sa.description ?? "",
+      prompt,
+      model: sa.modelOverride ? { id: sa.modelOverride } : "inherit",
+    };
+  }
+
+  return Object.keys(agents).length > 0 ? agents : undefined;
+}