@stigmer/runner 3.0.1

package/src/activities/execute-cursor/prompt-builder.ts

@@ -0,0 +1,349 @@
+/**
+ * Builds the enhanced prompt for the Cursor agent.
+ *
+ * Replicates prompt_builder.py::enhance_system_prompt() but delivers
+ * the content via the first user message (Cursor SDK has no systemPrompt
+ * parameter). On reinvocation, only the approval decisions are sent.
+ *
+ * Sections (in order, conditionally included):
+ * 1. Agent instructions (persona/character)
+ * 2. Available skills metadata
+ * 3. Sub-agent delegation guidance
+ * 4. Workspace context (multi-root only; single-dir is redundant with SDK cwd)
+ * 5. Input files / referenced files
+ * 6. Response rules (only when agent has no custom instructions)
+ * 7. User's actual message
+ */
+
+import { resolve } from "node:path";
+import type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * Marker path segments that identify runner-internal directories. A workspace
+ * dir containing any of these segments is almost certainly the runner's own
+ * app directory, not a user workspace.
+ */
+const RUNNER_PATH_MARKERS = [
+  "/runtimes/cursor-runner/",
+  "/runtimes/agent-runner/",
+  "/node_modules/",
+  "/dist/main.js",
+] as const;
+
+export interface SkillMetadata {
+  name: string;
+  description: string;
+  path: string;
+}
+
+export interface EnhancedPromptOptions {
+  instructions: string;
+  userMessage: string;
+  skills: SkillMetadata[];
+  subAgents: SubAgent[];
+  workspaceDirs: string[];
+  workspaceFileRefs: string[];
+  attachmentPaths: string[];
+  interactionMode?: InteractionMode;
+}
+
+/**
+ * Build the enhanced prompt for the first execution in a session.
+ *
+ * Prepends agent blueprint information before the user's message so the
+ * Cursor agent has full context. This avoids writing files to the workspace.
+ */
+export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
+  const sections: string[] = [];
+
+  const modePrefix = formatInteractionModePrefix(options.interactionMode);
+  if (modePrefix) {
+    sections.push(modePrefix);
+  }
+
+  if (options.instructions) {
+    sections.push(formatInstructions(options.instructions));
+  }
+
+  if (options.skills.length > 0) {
+    sections.push(formatSkillsSection(options.skills));
+  }
+
+  if (options.subAgents.length > 0) {
+    sections.push(formatSubAgentsSection(options.subAgents));
+  }
+
+  const safeDirs = sanitizeWorkspaceDirs(options.workspaceDirs);
+  // Encourage Cursor's built-in `explore` sub-agent for codebase work whenever
+  // there is a workspace to explore — the headless agent otherwise rarely
+  // delegates exploration the way the Cursor IDE does.
+  if (safeDirs.length > 0) {
+    sections.push(formatExplorationGuidance());
+  }
+  if (safeDirs.length > 1) {
+    sections.push(formatWorkspaceContext(safeDirs));
+  }
+
+  if (options.attachmentPaths.length > 0) {
+    sections.push(formatInputFiles(options.attachmentPaths));
+  }
+
+  if (options.workspaceFileRefs.length > 0) {
+    sections.push(formatReferencedFiles(options.workspaceFileRefs));
+  }
+
+  if (!options.instructions) {
+    sections.push(formatResponseRules());
+  }
+
+  sections.push(`<user_request>\n${options.userMessage}\n</user_request>`);
+
+  return sections.join("\n\n---\n\n");
+}
+
+/**
+ * Build the reinvocation prompt after approval decisions.
+ *
+ * Only contains approval instructions, no blueprint (it persists in the resumed
+ * agent's native context). The actions are described in human-meaningful terms
+ * (the resolved approval message, e.g. "Write file: foo.txt") — NOT the opaque
+ * tool-call ids, which mean nothing to the model. A resumed agent re-issues the
+ * approved tool with a fresh id; the approval gate (see approval-state.ts grants)
+ * is what actually lets the re-attempt through.
+ */
+export function buildReinvocationPrompt(
+  pendingApprovals: PendingApproval[],
+  approvalDecisions: Map<string, ApprovalAction>,
+): string {
+  const approved: string[] = [];
+  const skipped: string[] = [];
+
+  for (const pa of pendingApprovals) {
+    const action = approvalDecisions.get(pa.toolCallId);
+    if (action === ApprovalAction.APPROVE) {
+      approved.push(describeApproval(pa));
+    } else if (action === ApprovalAction.SKIP) {
+      skipped.push(describeApproval(pa));
+    }
+  }
+
+  const parts: string[] = [];
+  if (approved.length) {
+    parts.push(
+      "The user reviewed the following action(s) you proposed and APPROVED them. " +
+        "Carry them out now:\n" +
+        approved.map((a) => `- ${a}`).join("\n"),
+    );
+  }
+  if (skipped.length) {
+    parts.push(
+      "The user SKIPPED the following action(s). Do not perform them; continue " +
+        "with the rest of the task without them:\n" +
+        skipped.map((a) => `- ${a}`).join("\n"),
+    );
+  }
+
+  return parts.join("\n\n");
+}
+
+/**
+ * Render a pending approval as a short human-readable action description for the
+ * reinvocation prompt. Prefers the already-resolved approval message; falls back
+ * to the tool name plus a bounded args preview.
+ */
+function describeApproval(pa: PendingApproval): string {
+  if (pa.message) return pa.message;
+  const name = pa.mcpServerSlug ? `${pa.mcpServerSlug}/${pa.toolName}` : pa.toolName;
+  if (!pa.argsPreview) return name;
+  const preview = pa.argsPreview.length > 200
+    ? `${pa.argsPreview.slice(0, 200)}…`
+    : pa.argsPreview;
+  return `${name} (${preview})`;
+}
+
+/**
+ * Filters out workspace directories that appear to be runner-internal paths.
+ * This prevents the prompt from exposing implementation details like
+ * ~/.stigmer/runtimes/cursor-runner/... to the AI model.
+ */
+export function sanitizeWorkspaceDirs(dirs: string[]): string[] {
+  const safe: string[] = [];
+
+  for (const dir of dirs) {
+    const resolved = resolve(dir);
+    if (isRunnerInternalPath(resolved)) {
+      console.warn(
+        `Workspace dir "${dir}" appears to be a runner-internal path — ` +
+        "omitting from prompt to prevent implementation detail leakage.",
+      );
+      continue;
+    }
+    safe.push(dir);
+  }
+
+  return safe;
+}
+
+function isRunnerInternalPath(absolutePath: string): boolean {
+  return RUNNER_PATH_MARKERS.some((marker) => absolutePath.includes(marker));
+}
+
+export function formatInstructions(instructions: string): string {
+  return `<agent_instructions>\n${instructions}\n</agent_instructions>`;
+}
+
+export function formatSkillsSection(skills: SkillMetadata[]): string {
+  const entries = skills.map(
+    (s) => `- **${s.name}**: ${s.description}\n  Path: \`${s.path}\``,
+  );
+  return [
+    "<available_skills>",
+    "You have access to the following skills. When a skill is relevant, read its SKILL.md file using the Read tool and follow the instructions within.",
+    "",
+    ...entries,
+    "</available_skills>",
+  ].join("\n");
+}
+
+export function formatSubAgentsSection(subAgents: SubAgent[]): string {
+  let anyAdvisoryMcp = false;
+  const entries = subAgents.map((sa) => {
+    const parts = [`- **${sa.name}**: ${sa.description}`];
+    if (sa.mcpAccess.length > 0) {
+      anyAdvisoryMcp = true;
+      const servers = sa.mcpAccess.map((a) => a.mcpServer).join(", ");
+      parts.push(`  MCP access (advisory): ${servers}`);
+    }
+    if (sa.modelOverride) {
+      parts.push(`  Model: ${sa.modelOverride}`);
+    }
+    return parts.join("\n");
+  });
+
+  const lines = [
+    "<sub_agent_delegation>",
+    "You can delegate tasks to these specialized sub-agents using the Task tool",
+    "(pass the sub-agent's name as the subagent type). They are registered and",
+    "run independently, each with its own fresh context.",
+    "",
+    "Available sub-agents:",
+    "",
+    ...entries,
+    "",
+    "Delegation rules:",
+    "- Delegate a task to the sub-agent whose specialization matches it.",
+    "- Give a clear, self-contained task description — sub-agents do not share your conversation context.",
+    "- Sub-agents run independently and return their results when done.",
+  ];
+
+  if (anyAdvisoryMcp) {
+    lines.push(
+      "- \"MCP access (advisory)\" lists the tools a sub-agent is intended to use; " +
+        "sub-agents inherit this agent's tool access, so treat it as guidance, not a hard limit.",
+    );
+  }
+
+  lines.push("</sub_agent_delegation>");
+  return lines.join("\n");
+}
+
+/**
+ * Guidance encouraging the agent to use Cursor's built-in `explore` sub-agent
+ * (via the Task tool) for codebase investigation, rather than reading many
+ * files inline. Included only when the agent has a workspace to explore.
+ *
+ * This mirrors how the Cursor IDE aggressively delegates exploration, which the
+ * headless agent otherwise rarely does. Kept concise to limit token overhead
+ * and paired with a "do not over-delegate" guard to avoid trivial spawns.
+ */
+export function formatExplorationGuidance(): string {
+  return [
+    "<codebase_exploration>",
+    "For non-trivial investigation of this codebase, prefer delegating to the",
+    "built-in `explore` sub-agent via the Task tool instead of reading many",
+    "files yourself. Launch one explore task per distinct area you need to",
+    "understand — they run in parallel, return focused findings, and keep your",
+    "main context clean.",
+    "",
+    "Use explore for: locating where functionality lives, tracing how a feature",
+    "works across files, or surveying unfamiliar areas. Do NOT delegate trivial",
+    "single-file reads or small edits you can do directly.",
+    "</codebase_exploration>",
+  ].join("\n");
+}
+
+export function formatWorkspaceContext(dirs: string[]): string {
+  if (dirs.length === 1) {
+    return `<workspace>\nWorking directory: ${dirs[0]}\n</workspace>`;
+  }
+
+  const entries = dirs.map((d, i) => `${i + 1}. ${d}`);
+  return [
+    "<workspace>",
+    "Multi-root workspace with the following directories:",
+    ...entries,
+    "</workspace>",
+  ].join("\n");
+}
+
+export function formatInputFiles(paths: string[]): string {
+  const entries = paths.map((p) => `- \`${p}\``);
+  return [
+    "<input_files>",
+    "The following files have been provided as inputs. Read them when relevant to the task:",
+    ...entries,
+    "</input_files>",
+  ].join("\n");
+}
+
+export function formatReferencedFiles(refs: string[]): string {
+  const entries = refs.map((r) => `- \`${r}\``);
+  return [
+    "<referenced_files>",
+    "The user has referenced the following workspace files. Read them when relevant:",
+    ...entries,
+    "</referenced_files>",
+  ].join("\n");
+}
+
+/**
+ * Returns a system-level directive when the execution is in Plan mode.
+ * Returns `undefined` for Agent mode (default) since no prefix is needed.
+ */
+export function formatInteractionModePrefix(
+  mode: InteractionMode | undefined,
+): string | undefined {
+  if (
+    mode == null ||
+    mode === InteractionMode.UNSPECIFIED ||
+    mode === InteractionMode.AGENT
+  ) {
+    return undefined;
+  }
+
+  if (mode === InteractionMode.PLAN) {
+    return [
+      "<interaction_mode>",
+      "IMPORTANT: You are in Plan mode. Analyze the codebase and produce a detailed plan.",
+      "Do NOT create, edit, or delete any files. Do NOT run commands that modify the filesystem.",
+      "Only read, search, and analyze. Your output should be analysis, recommendations, and",
+      "implementation plans — not code changes.",
+      "</interaction_mode>",
+    ].join("\n");
+  }
+
+  return undefined;
+}
+
+export function formatResponseRules(): string {
+  return [
+    "<response_rules>",
+    "- Be concise and direct in your responses",
+    "- When making code changes, explain what you changed and why",
+    "- If a task is unclear, ask for clarification before proceeding",
+    "- Prefer editing existing files over creating new ones",
+    "</response_rules>",
+  ].join("\n");
+}

package/src/activities/execute-cursor/rejection-capture.ts

@@ -0,0 +1,100 @@
+/**
+ * Captures ConnectError details from process-level unhandledRejection events
+ * and correlates them to the active Cursor execution via AsyncLocalStorage.
+ *
+ * Background: The Cursor SDK has a confirmed bug where ConnectRPC stream
+ * errors escape as process-level unhandledRejection instead of surfacing
+ * through run.stream() or run.wait(). The actual error (e.g.,
+ * [unauthenticated], [unavailable]) carries diagnostic detail that
+ * run.wait() strips to a bare { status: "error" }.
+ *
+ * This module installs a process-level handler that extracts ConnectError
+ * fields and stores them in a Map keyed by executionId. The execute-cursor
+ * activity reads from this Map after run.wait() resolves to enrich the
+ * error message.
+ *
+ * Forum reference:
+ * https://forum.cursor.com/t/agent-send-wait-returns-bare-status-error-while-connectrpc-unauthenticated-leaks-as-unhandledrejection/161203
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface CapturedRejection {
+  code: string;
+  message: string;
+  timestamp: number;
+}
+
+const capturedRejections = new Map<string, CapturedRejection>();
+
+const REJECTION_TTL_MS = 5 * 60 * 1000;
+
+let executionContextRef: AsyncLocalStorage<{ executionId: string }> | null = null;
+
+export function setExecutionContextRef(
+  ctx: AsyncLocalStorage<{ executionId: string }>,
+): void {
+  executionContextRef = ctx;
+}
+
+export function getCapturedRejection(executionId: string): CapturedRejection | undefined {
+  return capturedRejections.get(executionId);
+}
+
+export function clearCapturedRejection(executionId: string): void {
+  capturedRejections.delete(executionId);
+}
+
+function isConnectError(err: unknown): err is Error & { code?: string } {
+  if (!(err instanceof Error)) return false;
+  const name = err.constructor?.name ?? "";
+  return name === "ConnectError"
+    || err.name === "ConnectError"
+    || (typeof (err as unknown as Record<string, unknown>).code === "string"
+      && err.message?.includes("[")
+      && (err.stack?.includes("connectrpc") ?? false));
+}
+
+function extractConnectCode(err: Error & { code?: string }): string {
+  if (typeof err.code === "string") return err.code;
+  const bracketMatch = err.message.match(/\[([a-z_]+)\]/);
+  if (bracketMatch) return bracketMatch[1];
+  return "unknown";
+}
+
+export function handleUnhandledRejection(reason: unknown): void {
+  if (isConnectError(reason)) {
+    const code = extractConnectCode(reason);
+    const executionId = executionContextRef?.getStore()?.executionId;
+
+    if (executionId) {
+      capturedRejections.set(executionId, {
+        code,
+        message: reason.message,
+        timestamp: Date.now(),
+      });
+      console.error(
+        `[rejection-capture] ConnectError correlated to execution=${executionId}, ` +
+        `code=${code}, message=${reason.message}`,
+      );
+    } else {
+      console.error(
+        `[rejection-capture] ConnectError without execution context: ` +
+        `code=${code}, message=${reason.message}`,
+      );
+    }
+  } else {
+    console.error("Unhandled rejection in runner:", reason);
+  }
+
+  evictStaleEntries();
+}
+
+function evictStaleEntries(): void {
+  const now = Date.now();
+  for (const [id, entry] of capturedRejections) {
+    if (now - entry.timestamp > REJECTION_TTL_MS) {
+      capturedRejections.delete(id);
+    }
+  }
+}