@cursor/july 0.1.2 → 0.1.4

package/src/internal/session-engine.ts

@@ -54,6 +54,7 @@ import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
+import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { createHostPlatforms, type HostPlatforms } from "./host-platforms.js";
@@ -65,6 +66,11 @@ import {
 } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
+import {
+  buildIdentitySection,
+  buildSessionContextBlock,
+  SCHEDULE_CHANNEL_PREFIX,
+} from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
 import type { AgentRunner } from "./sdk-runner.js";
 import { SessionStore } from "./session-store.js";
@@ -77,7 +83,7 @@ import {
 } from "./workspace.js";
 
 export const HTTP_CHANNEL_ID = "http";
-export const SCHEDULE_CHANNEL_PREFIX = "schedule:";
+export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 
 export class SessionBusyError extends Error {
   constructor(sessionId: string) {
@@ -243,7 +249,7 @@ export class SessionEngine {
       (sessionId) => this.sessions.eventFilePath(sessionId),
       (sessionId, error) =>
         this.logger(
-          `[agent-serve] failed to persist events for ${sessionId}: ${describeError(error)}`
+          `[agentkit] failed to persist events for ${sessionId}: ${describeError(error)}`
         )
     );
     this.storage =
@@ -439,7 +445,7 @@ export class SessionEngine {
         }
       } catch (error) {
         this.logger(
-          `[agent-serve] ab "${experiment.name}" enrollment failed (sticky skip): ${describeError(error)}`
+          `[agentkit] ab "${experiment.name}" enrollment failed (sticky skip): ${describeError(error)}`
         );
         variant = null;
       }
@@ -706,7 +712,7 @@ export class SessionEngine {
         this.queueDispatch(sessionId, event);
       } catch (error) {
         this.logger(
-          `[agent-serve] failed to record event for ${sessionId}: ${describeError(error)}`
+          `[agentkit] failed to record event for ${sessionId}: ${describeError(error)}`
         );
       }
     };
@@ -744,7 +750,10 @@ export class SessionEngine {
           // events while sibling parallel tools are still executing.
           if (
             update.type === "tool-call-started" ||
-            update.type === "tool-call-completed"
+            update.type === "tool-call-completed" ||
+            // Nested subagent progress (newer SDKs); string check keeps
+            // typecheck green against older published `@cursor/sdk` pins.
+            (update as { type: string }).type === "tool-call-delta"
           ) {
             await yieldEventLoop();
           }
@@ -847,14 +856,24 @@ export class SessionEngine {
           })
         : undefined;
     let turnPrompt = prompt;
+    if (isFirstTurn) {
+      const contextBlock = buildSessionContextBlock({
+        sessionId: record.sessionId,
+        channelId: record.channelId,
+        channelKind: this.channelsById.get(record.channelId)?.meta?.kind,
+        environment: isDevMode() ? "local dev server" : "hosted deployment",
+      });
+      turnPrompt = `${contextBlock}\n\n${prompt}`;
+    }
     if (runtime === "cloud" && isFirstTurn) {
       const preamble = [
         agent.instructions?.trim() ?? "",
+        buildIdentitySection(agent),
         buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
       ]
         .filter((part) => part !== "")
         .join("\n\n");
-      turnPrompt = preamble === "" ? prompt : `${preamble}\n\n${prompt}`;
+      turnPrompt = `${preamble}\n\n${turnPrompt}`;
     }
     return {
       sessionId: record.sessionId,
@@ -1382,7 +1401,7 @@ export class SessionEngine {
       .then(() => this.dispatchEvent(sessionId, event))
       .catch((error) => {
         this.logger(
-          `[agent-serve] event dispatch failed for ${sessionId}: ${describeError(error)}`
+          `[agentkit] event dispatch failed for ${sessionId}: ${describeError(error)}`
         );
       })
       .then(() => {
@@ -1427,7 +1446,7 @@ export class SessionEngine {
           await handler(event, channelCtx, sessionCtx);
         } catch (error) {
           this.logger(
-            `[agent-serve] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`
+            `[agentkit] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`
           );
         }
       }
@@ -1455,7 +1474,7 @@ export class SessionEngine {
           });
         } catch (error) {
           this.logger(
-            `[agent-serve] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`
+            `[agentkit] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`
           );
         }
       }
@@ -1597,7 +1616,7 @@ export class SessionEngine {
         });
       } catch (error) {
         this.logger(
-          `[agent-serve] ab persistSnapshots.save threw: ${describeError(error)}`
+          `[agentkit] ab persistSnapshots.save threw: ${describeError(error)}`
         );
       }
     } else {
@@ -1806,9 +1825,7 @@ export class SessionEngine {
     try {
       await this.runBulkRestore(storage, policy);
     } catch (error) {
-      this.logger(
-        `[agent-serve] session restore failed: ${describeError(error)}`
-      );
+      this.logger(`[agentkit] session restore failed: ${describeError(error)}`);
     }
   }
 
@@ -1865,7 +1882,7 @@ export class SessionEngine {
             return { record, events };
           } catch (error) {
             this.logger(
-              `[agent-serve] failed to restore session ${record.sessionId}: ${describeError(error)}`
+              `[agentkit] failed to restore session ${record.sessionId}: ${describeError(error)}`
             );
             return undefined;
           }
@@ -1884,7 +1901,7 @@ export class SessionEngine {
           (ndjson === undefined ? 0 : Buffer.byteLength(ndjson, "utf8"));
         if (bytes > budget) {
           this.logger(
-            `[agent-serve] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`
+            `[agentkit] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`
           );
           break outer;
         }
@@ -1894,13 +1911,13 @@ export class SessionEngine {
           restored += 1;
         } catch (error) {
           this.logger(
-            `[agent-serve] failed to restore session ${item.record.sessionId}: ${describeError(error)}`
+            `[agentkit] failed to restore session ${item.record.sessionId}: ${describeError(error)}`
           );
         }
       }
     }
     if (restored > 0) {
-      this.logger(`[agent-serve] restored ${restored} session(s) from storage`);
+      this.logger(`[agentkit] restored ${restored} session(s) from storage`);
     }
   }
 
@@ -1956,7 +1973,7 @@ export class SessionEngine {
     const events = await storage.listSessionEvents(record.sessionId);
     await this.materializeSession(record, eventsNdjson(events));
     this.logger(
-      `[agent-serve] lazily restored session ${record.sessionId} from storage`
+      `[agentkit] lazily restored session ${record.sessionId} from storage`
     );
     return record;
   }

package/src/internal/sessions-client.ts

@@ -0,0 +1,216 @@
+/**
+ * Session list / event fetch for CLI (`sessions`, `session`, chat reattach).
+ *
+ * Customer-facing errors never include hosting URLs or infra jargon.
+ */
+
+import type { SessionEvent, SessionSummary } from "../types.js";
+import { sanitizeCustomerError } from "./logs-client.js";
+import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
+
+export async function listSessions(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<SessionSummary[]> {
+  const baseUrl = args.baseUrl.replace(/\/$/, "");
+  const fetchImpl = args.fetchImpl ?? fetch;
+  let resp: Response;
+  try {
+    resp = await fetchImpl(`${baseUrl}/v1/sessions`, {
+      headers: mergeRequestHeaders(args.auth),
+    });
+  } catch (error) {
+    throw new Error(
+      sanitizeCustomerError(
+        error instanceof Error ? error.message : "Could not list sessions."
+      )
+    );
+  }
+  if (!resp.ok) {
+    throw new Error(`Could not list sessions (HTTP ${resp.status}).`);
+  }
+  const body = (await resp.json()) as { sessions?: unknown };
+  if (!Array.isArray(body.sessions)) {
+    return [];
+  }
+  const out: SessionSummary[] = [];
+  for (const row of body.sessions) {
+    const parsed = parseSessionSummary(row);
+    if (parsed !== undefined) {
+      out.push(parsed);
+    }
+  }
+  return out;
+}
+
+export async function fetchSessionEvents(args: {
+  baseUrl: string;
+  sessionId: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<SessionEvent[]> {
+  const baseUrl = args.baseUrl.replace(/\/$/, "");
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const path = `/v1/session/${encodeURIComponent(args.sessionId)}/events`;
+
+  try {
+    const jsonResp = await fetchImpl(`${baseUrl}${path}?format=json`, {
+      headers: mergeRequestHeaders(args.auth),
+    });
+    if (jsonResp.ok) {
+      const body = (await jsonResp.json()) as { events?: unknown };
+      if (Array.isArray(body.events)) {
+        return body.events as SessionEvent[];
+      }
+    } else if (jsonResp.status === 404) {
+      throw new Error(`Session ${args.sessionId} not found.`);
+    } else if (jsonResp.status === 403) {
+      throw new Error(
+        `Session ${args.sessionId} is not readable by this caller.`
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Session ")) {
+      throw error;
+    }
+    // Fall through to NDJSON.
+  }
+
+  try {
+    const resp = await fetchImpl(`${baseUrl}${path}`, {
+      headers: mergeRequestHeaders(args.auth),
+    });
+    if (resp.status === 404) {
+      throw new Error(`Session ${args.sessionId} not found.`);
+    }
+    if (resp.status === 403) {
+      throw new Error(
+        `Session ${args.sessionId} is not readable by this caller.`
+      );
+    }
+    if (!resp.ok) {
+      throw new Error(`Could not fetch session events (HTTP ${resp.status}).`);
+    }
+    const text = await resp.text();
+    const events: SessionEvent[] = [];
+    for (const line of text.split("\n")) {
+      if (line.trim() === "") {
+        continue;
+      }
+      try {
+        events.push(JSON.parse(line) as SessionEvent);
+      } catch {
+        // skip malformed lines
+      }
+    }
+    return events;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Session ")) {
+      throw error;
+    }
+    if (error instanceof Error && error.message.startsWith("Could not fetch")) {
+      throw new Error(sanitizeCustomerError(error.message));
+    }
+    throw new Error(
+      sanitizeCustomerError(
+        error instanceof Error
+          ? error.message
+          : "Could not fetch session events."
+      )
+    );
+  }
+}
+
+/** Lenient parse so partial stubs / older servers still list by sessionId. */
+function parseSessionSummary(value: unknown): SessionSummary | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const row = value as Record<string, unknown>;
+  if (typeof row.sessionId !== "string" || row.sessionId === "") {
+    return undefined;
+  }
+  const continuationToken =
+    typeof row.continuationToken === "string"
+      ? row.continuationToken
+      : row.continuationToken === null
+        ? null
+        : null;
+  return {
+    sessionId: row.sessionId,
+    channelId: typeof row.channelId === "string" ? row.channelId : "",
+    mode: row.mode === "task" ? "task" : "chat",
+    title: typeof row.title === "string" ? row.title : undefined,
+    turnCount: typeof row.turnCount === "number" ? row.turnCount : 0,
+    running: row.running === true,
+    createdAt: typeof row.createdAt === "string" ? row.createdAt : "",
+    updatedAt: typeof row.updatedAt === "string" ? row.updatedAt : "",
+    continuationToken,
+    externalUrl:
+      typeof row.externalUrl === "string" ? row.externalUrl : undefined,
+  };
+}
+
+/**
+ * Pick the previous (most recently updated) followable session for
+ * `resume` / `chat --resume` when no session id was passed.
+ * Followable = has a non-empty continuation token (task sessions without
+ * one are skipped).
+ */
+export function pickPreviousSession(
+  sessions: readonly SessionSummary[]
+): SessionSummary | undefined {
+  const followable = sessions.filter(
+    (s) => typeof s.continuationToken === "string" && s.continuationToken !== ""
+  );
+  if (followable.length === 0) {
+    return undefined;
+  }
+  return [...followable].sort((a, b) =>
+    b.updatedAt.localeCompare(a.updatedAt)
+  )[0];
+}
+
+/** Look up the most recently updated followable session id. */
+export async function resolvePreviousSessionId(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<string | undefined> {
+  const sessions = await listSessions({
+    baseUrl: args.baseUrl,
+    auth: args.auth,
+    fetchImpl: args.fetchImpl,
+  });
+  return pickPreviousSession(sessions)?.sessionId;
+}
+
+/** Format a sessions table (id, channel, mode, turns, running, updated). */
+export function formatSessionsTable(sessions: SessionSummary[]): string {
+  if (sessions.length === 0) {
+    return "No sessions.\n";
+  }
+  const header = ["SESSION", "CHANNEL", "MODE", "TURNS", "RUNNING", "UPDATED"];
+  const rows = sessions.map((s) => [
+    s.sessionId,
+    s.channelId,
+    s.mode,
+    String(s.turnCount),
+    s.running ? "yes" : "no",
+    s.updatedAt,
+  ]);
+  return `${renderTable(header, rows)}\n`;
+}
+
+function renderTable(header: string[], rows: string[][]): string {
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((row) => (row[i] ?? "").length))
+  );
+  const renderRow = (row: string[]): string =>
+    row
+      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+      .join("  ")
+      .trimEnd();
+  return [renderRow(header), ...rows.map(renderRow)].join("\n");
+}

package/src/internal/storage-coordinator.ts

@@ -317,7 +317,7 @@ export class StorageCoordinator {
       // under at-most-once). The session is unrecoverable; treat as a miss
       // so the conversation can continue rather than failing forever.
       this.logger(
-        `[agent-serve] storage continuation entry points at missing session ${sessionId}; treating as a miss`
+        `[agentkit] storage continuation entry points at missing session ${sessionId}; treating as a miss`
       );
       return undefined;
     }
@@ -488,7 +488,7 @@ export class StorageCoordinator {
       return value == null ? undefined : (value as unknown as ABSnapshot);
     } catch (error) {
       this.logger(
-        `[agent-serve] storage get(ab-snapshot) failed: ${describeError(error)}`
+        `[agentkit] storage get(ab-snapshot) failed: ${describeError(error)}`
       );
       return undefined;
     }
@@ -521,7 +521,7 @@ export class StorageCoordinator {
     clearTimeout(timer);
     if (!drained) {
       this.logger(
-        `[agent-serve] storage shutdown drain timed out after ${CLOSE_DRAIN_TIMEOUT_MS}ms with ${this.pending} write(s) undelivered`
+        `[agentkit] storage shutdown drain timed out after ${CLOSE_DRAIN_TIMEOUT_MS}ms with ${this.pending} write(s) undelivered`
       );
     }
   }
@@ -569,7 +569,7 @@ export class StorageCoordinator {
       return Array.isArray(entries) ? entries : [];
     } catch (error) {
       this.logger(
-        `[agent-serve] storage list(${prefix}) failed: ${describeError(error)}`
+        `[agentkit] storage list(${prefix}) failed: ${describeError(error)}`
       );
       return [];
     }
@@ -583,7 +583,7 @@ export class StorageCoordinator {
       this.dropped += ops.length;
       if (this.dropped <= ops.length || this.dropped % 1_000 < ops.length) {
         this.logger(
-          `[agent-serve] storage queue full (${MAX_PENDING_OPS} pending writes); dropped ${this.dropped} write(s) so far — the sink is too slow for the traffic`
+          `[agentkit] storage queue full (${MAX_PENDING_OPS} pending writes); dropped ${this.dropped} write(s) so far — the sink is too slow for the traffic`
         );
       }
       return;
@@ -600,7 +600,7 @@ export class StorageCoordinator {
           }
         } catch (error) {
           this.logger(
-            `[agent-serve] storage ${op.op}(${op.key}) failed: ${describeError(error)}`
+            `[agentkit] storage ${op.op}(${op.key}) failed: ${describeError(error)}`
           );
         } finally {
           this.pending -= 1;

package/src/internal/stream-progress.ts

@@ -64,6 +64,9 @@ export function createStreamProgress(options?: {
           break;
         }
         case "reasoning.appended": {
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
           if (!thinkingShown) {
             thinkingShown = true;
             write(c.dim("  · thinking…\n"));
@@ -71,6 +74,11 @@ export function createStreamProgress(options?: {
           break;
         }
         case "message.appended": {
+          // Nested subagent deltas stay inside the task chip/indent, not
+          // the parent agent stream.
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
           if (!assistantOpen) {
             write(`${c.green("‹ agent")}  `);
             assistantOpen = true;
@@ -79,6 +87,9 @@ export function createStreamProgress(options?: {
           break;
         }
         case "message.completed": {
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
           closeAssistant();
           break;
         }
@@ -98,9 +109,18 @@ export function createStreamProgress(options?: {
           closeAssistant();
           const now = Date.now();
           for (const call of event.data.calls) {
+            if (call.toolName === "task" && call.parentCallId === undefined) {
+              // Covered by subagent.called; avoid a duplicate bare `task` line.
+              continue;
+            }
             toolStartedAt.set(call.callId, now);
+            const indent =
+              call.parentCallId !== undefined ||
+              event.data.parentCallId !== undefined
+                ? "    "
+                : "  ";
             write(
-              `  ${c.magenta("⚙")} ${c.bold(call.toolName)}${c.dim(
+              `${indent}${c.magenta("⚙")} ${c.bold(call.toolName)}${c.dim(
                 formatArgs(call.args)
               )}\n`
             );
@@ -127,13 +147,21 @@ export function createStreamProgress(options?: {
           break;
         }
         case "action.result": {
+          if (
+            event.data.toolName === "task" &&
+            event.data.parentCallId === undefined
+          ) {
+            break;
+          }
           const started = toolStartedAt.get(event.data.callId);
           toolStartedAt.delete(event.data.callId);
           const dur =
             started === undefined ? "" : c.dim(` ${elapsed(started)}`);
           const mark = event.data.isError ? c.red("✗") : c.magenta("✓");
+          const indent =
+            event.data.parentCallId !== undefined ? "      " : "    ";
           write(
-            `    ${mark} ${c.bold(event.data.toolName)}${dur} ${c.dim(
+            `${indent}${mark} ${c.bold(event.data.toolName)}${dur} ${c.dim(
               truncate(stringify(event.data.output), 90)
             )}\n`
           );
@@ -149,6 +177,12 @@ export function createStreamProgress(options?: {
           );
           break;
         }
+        case "subagent.completed": {
+          write(
+            `  ${c.magenta("✓")} ${c.bold(event.data.name ?? "subagent")} ${c.dim("done")}\n`
+          );
+          break;
+        }
         case "turn.completed": {
           closeAssistant();
           const usage = event.data.usage;

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);
+}