@cursor/july 0.1.2 → 0.1.3

package/src/internal/terminal-style.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny ANSI helpers for CLI progress output. Respects `NO_COLOR` and
+ * only enables when the target stream is a TTY.
+ */
+
+import { clearScreenDown, cursorTo } from "node:readline";
+
+export interface TerminalPalette {
+  dim: (s: string) => string;
+  bold: (s: string) => string;
+  cyan: (s: string) => string;
+  green: (s: string) => string;
+  red: (s: string) => string;
+  magenta: (s: string) => string;
+  yellow: (s: string) => string;
+}
+
+const IDENTITY = (s: string): string => s;
+
+const PLAIN: TerminalPalette = {
+  dim: IDENTITY,
+  bold: IDENTITY,
+  cyan: IDENTITY,
+  green: IDENTITY,
+  red: IDENTITY,
+  magenta: IDENTITY,
+  yellow: IDENTITY,
+};
+
+export function colorEnabledFor(
+  stream: NodeJS.WriteStream = process.stdout
+): boolean {
+  return stream.isTTY === true && process.env.NO_COLOR === undefined;
+}
+
+export function makePalette(enabled: boolean): TerminalPalette {
+  if (!enabled) {
+    return PLAIN;
+  }
+  const wrap =
+    (code: string) =>
+    (s: string): string =>
+      `\u001b[${code}m${s}\u001b[0m`;
+  return {
+    dim: wrap("2"),
+    bold: wrap("1"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    red: wrap("31"),
+    magenta: wrap("35"),
+    yellow: wrap("33"),
+  };
+}
+
+/** Palette for human-facing stdout (init summaries, next steps). */
+export function stdoutPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stdout));
+}
+
+/** Palette for human-facing stderr (login progress, warnings). */
+export function stderrPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stderr));
+}
+
+/** Wipe the terminal before a `dev` Enter-to-restart cycle. */
+export function clearTerminal(
+  stream: NodeJS.WriteStream = process.stdout
+): void {
+  if (stream.isTTY !== true) {
+    return;
+  }
+  cursorTo(stream, 0, 0);
+  clearScreenDown(stream);
+}

package/src/internal/trajectory.ts

@@ -17,6 +17,16 @@ export interface TrajectoryToolCall {
   isError: boolean;
   /** Present when the tool required human approval before execute. */
   approvalDecision?: "approve" | "deny";
+  /** Parent task/subagent call id when this tool ran inside a subagent. */
+  parentCallId?: string;
+}
+
+export interface TrajectorySubagent {
+  callId: string;
+  name?: string;
+  description?: string;
+  /** Nested tool calls streamed while this subagent was running. */
+  toolCalls: TrajectoryToolCall[];
 }
 
 export interface TrajectoryTurn {
@@ -25,7 +35,7 @@ export interface TrajectoryTurn {
   assistantText: string;
   reasoningText?: string;
   toolCalls: TrajectoryToolCall[];
-  subagents: Array<{ callId: string; name?: string; description?: string }>;
+  subagents: TrajectorySubagent[];
   usage?: TurnUsage;
   result?: string;
   failed: boolean;
@@ -95,12 +105,20 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         break;
       }
       case "message.completed": {
+        // Nested subagent text must not overwrite the parent turn reply.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
         if (event.turnId !== undefined && event.data.text !== "") {
           ensureTurn(event.turnId).assistantText = event.data.text;
         }
         break;
       }
       case "reasoning.appended": {
+        // Nested subagent thinking stays off the parent turn transcript.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
         if (event.turnId !== undefined) {
           ensureTurn(event.turnId).reasoningText = event.data.text;
         }
@@ -112,14 +130,28 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         }
         const turn = ensureTurn(event.turnId);
         for (const call of event.data.calls) {
+          const parentCallId = call.parentCallId ?? event.data.parentCallId;
+          // Keep bare top-level `task` in toolCalls so evals like
+          // `calledTool("task")` / `notCalledTool("task")` keep working.
+          // Nested progress also appears under `subagents`.
           const entry: TrajectoryToolCall = {
             callId: call.callId,
             toolName: call.toolName,
             isError: false,
-            ...(call.args === undefined ? {} : { args: call.args }),
+            args: call.args,
+            parentCallId,
           };
           pendingCalls.set(call.callId, entry);
-          turn.toolCalls.push(entry);
+          if (parentCallId !== undefined) {
+            let sub = turn.subagents.find((s) => s.callId === parentCallId);
+            if (sub === undefined) {
+              sub = { callId: parentCallId, toolCalls: [] };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
         }
         break;
       }
@@ -141,24 +173,49 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
           pending.isError = event.data.isError;
           pending.toolName = event.data.toolName;
         } else if (event.turnId !== undefined) {
-          ensureTurn(event.turnId).toolCalls.push({
+          const turn = ensureTurn(event.turnId);
+          const entry: TrajectoryToolCall = {
             callId: event.data.callId,
             toolName: event.data.toolName,
             output: event.data.output,
             isError: event.data.isError,
-          });
+            parentCallId: event.data.parentCallId,
+          };
+          if (event.data.parentCallId !== undefined) {
+            let sub = turn.subagents.find(
+              (s) => s.callId === event.data.parentCallId
+            );
+            if (sub === undefined) {
+              sub = {
+                callId: event.data.parentCallId,
+                toolCalls: [],
+              };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
         }
         break;
       }
       case "subagent.called": {
         if (event.turnId !== undefined) {
-          ensureTurn(event.turnId).subagents.push({
-            callId: event.data.callId,
-            ...(event.data.name === undefined ? {} : { name: event.data.name }),
-            ...(event.data.description === undefined
-              ? {}
-              : { description: event.data.description }),
-          });
+          const turn = ensureTurn(event.turnId);
+          const existing = turn.subagents.find(
+            (s) => s.callId === event.data.callId
+          );
+          if (existing !== undefined) {
+            existing.name = event.data.name;
+            existing.description = event.data.description;
+          } else {
+            turn.subagents.push({
+              callId: event.data.callId,
+              name: event.data.name,
+              description: event.data.description,
+              toolCalls: [],
+            });
+          }
         }
         break;
       }
@@ -202,7 +259,13 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
 
   const turns = turnOrder.map((id) => turnsById.get(id)!);
   const turnsFailed = turns.filter((t) => t.failed).length;
-  const toolCallCount = turns.reduce((n, t) => n + t.toolCalls.length, 0);
+  const toolCallCount = turns.reduce(
+    (n, t) =>
+      n +
+      t.toolCalls.length +
+      t.subagents.reduce((m, s) => m + s.toolCalls.length, 0),
+    0
+  );
   const lastGood = [...turns].reverse().find((t) => t.assistantText !== "");
   return {
     sessionId,
@@ -270,6 +333,21 @@ export function formatTrajectoryText(trajectory: Trajectory): string {
         lines.push(`    ${truncate(stringify(call.output), 160)}`);
       }
     }
+    for (const sub of turn.subagents) {
+      const label = sub.name ?? "subagent";
+      const detail =
+        sub.description !== undefined
+          ? ` — ${truncate(sub.description, 80)}`
+          : "";
+      lines.push(`  task ${label}${detail}`);
+      for (const call of sub.toolCalls) {
+        const mark = call.isError ? "✗" : "→";
+        lines.push(`    ${mark} ${call.toolName}${formatArgs(call.args)}`);
+        if (call.output !== undefined) {
+          lines.push(`      ${truncate(stringify(call.output), 160)}`);
+        }
+      }
+    }
     if (turn.assistantText.length > 0) {
       lines.push(`  agent: ${truncate(turn.assistantText, 400)}`);
     }

package/src/internal/workspace.ts

@@ -15,6 +15,7 @@ import type {
   ResolvedAgent,
 } from "../types.js";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+import { buildIdentitySection } from "./prompt-context.js";
 
 export interface MaterializeWorkspaceOptions {
   agent: ResolvedAgent;
@@ -31,6 +32,41 @@ export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;
 }
 
+/**
+ * Always-on identity line prepended when composing instructions. Sourced from
+ * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
+ * so agents know who they are without restating it in authored prose.
+ */
+export function buildIdentityPreamble(name: string): string {
+  const trimmed = name.trim();
+  if (trimmed === "") {
+    return "";
+  }
+  return `You are ${trimmed}. That is your name; use it when people ask who you are.`;
+}
+
+/**
+ * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
+ * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
+ */
+export function withIdentityPreamble(
+  name: string,
+  instructions: string | undefined
+): string | undefined {
+  const preamble = buildIdentityPreamble(name);
+  const body = instructions?.trim() ?? "";
+  if (preamble === "" && body === "") {
+    return undefined;
+  }
+  if (preamble === "") {
+    return body === "" ? undefined : body;
+  }
+  if (body === "") {
+    return preamble;
+  }
+  return `${preamble}\n\n${body}`;
+}
+
 /**
  * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
  *
@@ -96,12 +132,14 @@ export async function materializeWorkspace(
   const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
     includeScripts: false,
   });
-  const agentsMd = [agent.instructions?.trim() ?? "", agentToolsSection]
+  const agentsMd = [
+    agent.instructions?.trim() ?? "",
+    buildIdentitySection(agent),
+    agentToolsSection,
+  ]
     .filter((part) => part !== "")
     .join("\n\n");
-  if (agentsMd !== "") {
-    await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
-  }
+  await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
 
   for (const tool of agent.tools) {
     if (tool.execution !== "agent" || tool.script === undefined) {

package/src/types.ts

@@ -588,6 +588,11 @@ export interface ActionCall {
   callId: string;
   toolName: string;
   args?: unknown;
+  /**
+   * When set, this tool call belongs to a nested subagent turn whose
+   * parent `task` tool call id is `parentCallId`.
+   */
+  parentCallId?: string;
 }
 
 /** Human decision for a parked {@link ToolConfig.needsApproval} tool call. */
@@ -622,14 +627,30 @@ export type SessionEventPayload =
   | { type: "turn.started"; data: Record<string, never> }
   | { type: "step.started"; data: { stepId: number } }
   | { type: "step.completed"; data: { stepId: number; durationMs: number } }
-  | { type: "reasoning.appended"; data: { delta: string; text: string } }
-  | { type: "reasoning.completed"; data: { durationMs?: number } }
-  | { type: "message.appended"; data: { delta: string; text: string } }
+  | {
+      type: "reasoning.appended";
+      data: { delta: string; text: string; parentCallId?: string };
+    }
+  | {
+      type: "reasoning.completed";
+      data: { durationMs?: number; parentCallId?: string };
+    }
+  | {
+      type: "message.appended";
+      data: { delta: string; text: string; parentCallId?: string };
+    }
   | {
       type: "message.completed";
-      data: { text: string; finishReason: "stop" | "tool_call" };
+      data: {
+        text: string;
+        finishReason: "stop" | "tool_call";
+        parentCallId?: string;
+      };
+    }
+  | {
+      type: "actions.requested";
+      data: { calls: ActionCall[]; parentCallId?: string };
     }
-  | { type: "actions.requested"; data: { calls: ActionCall[] } }
   | {
       /**
        * A server tool with {@link ToolConfig.needsApproval} is parked until
@@ -641,6 +662,7 @@ export type SessionEventPayload =
         callId: string;
         toolName: string;
         args?: unknown;
+        parentCallId?: string;
       };
     }
   | {
@@ -650,6 +672,7 @@ export type SessionEventPayload =
         toolName: string;
         decision: ApprovalDecision;
         by?: string;
+        parentCallId?: string;
       };
     }
   | {
@@ -659,6 +682,7 @@ export type SessionEventPayload =
         toolName: string;
         output?: unknown;
         isError: boolean;
+        parentCallId?: string;
       };
     }
   | {
@@ -1551,7 +1575,10 @@ export interface ResolvedAgent {
   name: string;
   description?: string;
   model?: ModelSetting;
-  /** Composed system prompt (instructions.md / instructions.ts / agent.ts). */
+  /**
+   * Composed system prompt: identity preamble from {@link name}, then
+   * authored `instructions.md` / `.ts` / dir (or inline `agent.ts`).
+   */
   instructions?: string;
   /** Execution runtime. Root agents default to `"local"`. */
   runtime: AgentRuntime;
@@ -1776,6 +1803,15 @@ export interface ServeOptions {
    * {@link authToken}. Authored `auth` arrays still win.
    */
   allowAnonymous?: boolean;
+  /**
+   * Allow {@link allowAnonymous} together with
+   * `githubChannel({ cursorAccount })`. Without this opt-in, `serve` refuses
+   * to start because every admitted anonymous caller could drive sessions
+   * that hold the signed-in account's repo-scoped GitHub credential. Set it
+   * only when the network boundary already authenticates callers (e.g. an
+   * SSO/Okta proxy in front of the host).
+   */
+  allowAnonymousCursorGithub?: boolean;
   /**
    * Public base URL where this server is reachable from outside the host
    * (e.g. `https://agents.example.com`). Used to resolve peer