@cursor/july 0.1.1

package/src/internal/session-store.ts

@@ -0,0 +1,147 @@
+/**
+ * Persisted session registry. Each session lives at
+ * `<stateRoot>/sessions/<sessionId>/` with a `session.json` record, an
+ * `events.ndjson` log, and a `workspace/` directory. Continuation keys are
+ * indexed in memory (hydrated by scanning session records on first use) so
+ * channels can address sessions by their channel-local token.
+ */
+
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { SessionRecord } from "../types.js";
+import { isSafeSessionId } from "./auth.js";
+
+export class SessionStore {
+  private readonly cache = new Map<string, SessionRecord>();
+  private readonly continuationIndex = new Map<string, string>();
+  private hydrated: Promise<void> | undefined;
+
+  constructor(private readonly sessionsDir: string) {}
+
+  sessionDir(sessionId: string): string {
+    if (!isSafeSessionId(sessionId)) {
+      throw new Error(`Invalid session id: ${sessionId}`);
+    }
+    return join(this.sessionsDir, sessionId);
+  }
+
+  workspaceDir(sessionId: string): string {
+    return join(this.sessionDir(sessionId), "workspace");
+  }
+
+  eventFilePath(sessionId: string): string {
+    return join(this.sessionDir(sessionId), "events.ndjson");
+  }
+
+  private recordPath(sessionId: string): string {
+    return join(this.sessionDir(sessionId), "session.json");
+  }
+
+  private continuationKeyOf(channelId: string, key: string): string {
+    return `${channelId}\n${key}`;
+  }
+
+  private async hydrate(): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await readdir(this.sessionsDir);
+    } catch {
+      return;
+    }
+    for (const sessionId of entries) {
+      if (!isSafeSessionId(sessionId) || this.cache.has(sessionId)) {
+        continue;
+      }
+      const record = await this.readRecord(sessionId);
+      if (record !== undefined) {
+        this.cache.set(sessionId, record);
+        this.indexRecord(record);
+      }
+    }
+  }
+
+  private async ensureHydrated(): Promise<void> {
+    this.hydrated ??= this.hydrate();
+    await this.hydrated;
+  }
+
+  private async readRecord(
+    sessionId: string
+  ): Promise<SessionRecord | undefined> {
+    if (!isSafeSessionId(sessionId)) {
+      return undefined;
+    }
+    try {
+      const raw = await readFile(this.recordPath(sessionId), "utf8");
+      return JSON.parse(raw) as SessionRecord;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private indexRecord(record: SessionRecord): void {
+    if (record.continuationKey !== null) {
+      this.continuationIndex.set(
+        this.continuationKeyOf(record.channelId, record.continuationKey),
+        record.sessionId
+      );
+    }
+  }
+
+  async get(sessionId: string): Promise<SessionRecord | undefined> {
+    if (!isSafeSessionId(sessionId)) {
+      return undefined;
+    }
+    const cached = this.cache.get(sessionId);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const record = await this.readRecord(sessionId);
+    if (record !== undefined) {
+      this.cache.set(sessionId, record);
+      this.indexRecord(record);
+    }
+    return record;
+  }
+
+  async list(): Promise<SessionRecord[]> {
+    await this.ensureHydrated();
+    return [...this.cache.values()].sort((a, b) =>
+      a.createdAt.localeCompare(b.createdAt)
+    );
+  }
+
+  async findByContinuation(
+    channelId: string,
+    key: string
+  ): Promise<SessionRecord | undefined> {
+    await this.ensureHydrated();
+    const sessionId = this.continuationIndex.get(
+      this.continuationKeyOf(channelId, key)
+    );
+    return sessionId === undefined ? undefined : this.get(sessionId);
+  }
+
+  async save(record: SessionRecord): Promise<void> {
+    const previous = this.cache.get(record.sessionId);
+    if (
+      previous !== undefined &&
+      previous.continuationKey !== null &&
+      previous.continuationKey !== record.continuationKey
+    ) {
+      this.continuationIndex.delete(
+        this.continuationKeyOf(previous.channelId, previous.continuationKey)
+      );
+    }
+    this.cache.set(record.sessionId, record);
+    this.indexRecord(record);
+
+    const dir = this.sessionDir(record.sessionId);
+    await mkdir(dir, { recursive: true });
+    const finalPath = this.recordPath(record.sessionId);
+    const tmpPath = `${finalPath}.${randomBytes(4).toString("hex")}.tmp`;
+    await writeFile(tmpPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    await rename(tmpPath, finalPath);
+  }
+}

package/src/internal/session-urls.ts

@@ -0,0 +1,40 @@
+/** Absolute playground deep-link for a session on this agent mount. */
+export function playgroundUrlForSession(
+  request: Request,
+  base: string,
+  sessionId: string
+): string {
+  const url = new URL(request.url);
+  const mount = normalizeMountBase(base);
+  return `${url.origin}${mount}/playground?sessionId=${encodeURIComponent(sessionId)}`;
+}
+
+/** Absolute NDJSON event-trace URL for a session on this agent mount. */
+export function eventsUrlForSession(
+  requestUrl: string,
+  base: string,
+  sessionId: string
+): string {
+  const url = new URL(requestUrl);
+  const mount = normalizeMountBase(base);
+  return `${url.origin}${mount}/v1/session/${encodeURIComponent(sessionId)}/events`;
+}
+
+/** Playground + trace URLs for a custom channel response body. */
+export function sessionUrlsForRequest(
+  request: Request,
+  base: string,
+  sessionId: string
+): { playgroundUrl: string; traceUrl: string } {
+  return {
+    playgroundUrl: playgroundUrlForSession(request, base, sessionId),
+    traceUrl: eventsUrlForSession(request.url, base, sessionId),
+  };
+}
+
+function normalizeMountBase(base: string): string {
+  if (base === "") {
+    return "";
+  }
+  return base.startsWith("/") ? base : `/${base}`;
+}

package/src/internal/stream-progress.ts

@@ -0,0 +1,254 @@
+/**
+ * Live terminal rendering of session events for `run` / `eval`.
+ * Writes to a caller-provided sink (usually stderr) so stdout can stay JSON.
+ */
+
+import type { SessionEvent } from "../types.js";
+
+export interface StreamProgress {
+  onEvent(event: SessionEvent): void;
+  close(): void;
+}
+
+export function createStreamProgress(options?: {
+  write?: (s: string) => void;
+  color?: boolean;
+}): StreamProgress {
+  const write = options?.write ?? ((s: string) => process.stderr.write(s));
+  const color =
+    options?.color ??
+    (process.stderr.isTTY === true && process.env.NO_COLOR === undefined);
+  const c = makePalette(color);
+
+  let assistantOpen = false;
+  let thinkingShown = false;
+  const turnStartedAt = new Map<string, number>();
+  const toolStartedAt = new Map<string, number>();
+  let turnClock = 0;
+
+  const closeAssistant = (): void => {
+    if (assistantOpen) {
+      write("\n");
+      assistantOpen = false;
+    }
+  };
+
+  const elapsed = (since: number): string => `${Date.now() - since}ms`;
+
+  return {
+    onEvent(event: SessionEvent): void {
+      switch (event.type) {
+        case "session.started": {
+          write(c.dim(`session ${event.sessionId}\n`));
+          break;
+        }
+        case "agent.bound": {
+          closeAssistant();
+          write(`  ${c.cyan("agent")} ${c.bold(event.data.sdkAgentId)}\n`);
+          if (event.data.url !== undefined) {
+            write(`  ${c.dim(event.data.url)}\n`);
+          }
+          break;
+        }
+        case "turn.started": {
+          turnClock = Date.now();
+          if (event.turnId !== undefined) {
+            turnStartedAt.set(event.turnId, turnClock);
+          }
+          write(c.dim(`  turn ${event.turnId ?? "?"} started\n`));
+          break;
+        }
+        case "message.received": {
+          thinkingShown = false;
+          write(`${c.bold("› user")}  ${truncate(event.data.text, 120)}\n`);
+          break;
+        }
+        case "reasoning.appended": {
+          if (!thinkingShown) {
+            thinkingShown = true;
+            write(c.dim("  · thinking…\n"));
+          }
+          break;
+        }
+        case "message.appended": {
+          if (!assistantOpen) {
+            write(`${c.green("‹ agent")}  `);
+            assistantOpen = true;
+          }
+          write(event.data.delta);
+          break;
+        }
+        case "message.completed": {
+          closeAssistant();
+          break;
+        }
+        case "step.started": {
+          write(c.dim(`  · step ${event.data.stepId}\n`));
+          break;
+        }
+        case "step.completed": {
+          write(
+            c.dim(
+              `  · step ${event.data.stepId} (${event.data.durationMs}ms)\n`
+            )
+          );
+          break;
+        }
+        case "actions.requested": {
+          closeAssistant();
+          const now = Date.now();
+          for (const call of event.data.calls) {
+            toolStartedAt.set(call.callId, now);
+            write(
+              `  ${c.magenta("⚙")} ${c.bold(call.toolName)}${c.dim(
+                formatArgs(call.args)
+              )}\n`
+            );
+          }
+          break;
+        }
+        case "action.approval_requested": {
+          closeAssistant();
+          write(
+            `    ${c.yellow("⏸")} ${c.bold(event.data.toolName)} ${c.dim(
+              "awaiting human approval"
+            )}\n`
+          );
+          break;
+        }
+        case "action.approval_resolved": {
+          const mark =
+            event.data.decision === "approve" ? c.green("✓") : c.red("✗");
+          write(
+            `    ${mark} ${c.bold(event.data.toolName)} ${c.dim(
+              event.data.decision === "approve" ? "approved" : "denied"
+            )}\n`
+          );
+          break;
+        }
+        case "action.result": {
+          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("✓");
+          write(
+            `    ${mark} ${c.bold(event.data.toolName)}${dur} ${c.dim(
+              truncate(stringify(event.data.output), 90)
+            )}\n`
+          );
+          break;
+        }
+        case "subagent.called": {
+          closeAssistant();
+          const detail = event.data.description
+            ? ` — ${truncate(event.data.description, 60)}`
+            : "";
+          write(
+            `  ${c.magenta("task")} ${c.bold(event.data.name ?? "subagent")}${c.dim(detail)}\n`
+          );
+          break;
+        }
+        case "turn.completed": {
+          closeAssistant();
+          const usage = event.data.usage;
+          const tokens = usage
+            ? ` · in ${usage.inputTokens} out ${usage.outputTokens} tok`
+            : "";
+          const turnStart =
+            event.turnId !== undefined
+              ? turnStartedAt.get(event.turnId)
+              : turnClock || undefined;
+          const wall =
+            turnStart !== undefined && turnStart > 0
+              ? ` · ${elapsed(turnStart)} wall`
+              : turnClock > 0
+                ? ` · ${elapsed(turnClock)} wall`
+                : "";
+          write(c.dim(`  ─ turn done${tokens}${wall}\n`));
+          if (event.turnId !== undefined) {
+            turnStartedAt.delete(event.turnId);
+          }
+          break;
+        }
+        case "turn.failed": {
+          closeAssistant();
+          write(`${c.red("  ✗ turn failed")} ${event.data.message}\n`);
+          break;
+        }
+        case "session.failed": {
+          closeAssistant();
+          write(`${c.red("  ✗ session failed")} ${event.data.message}\n`);
+          break;
+        }
+        case "session.waiting":
+        case "session.completed": {
+          closeAssistant();
+          break;
+        }
+        default:
+          break;
+      }
+    },
+    close: closeAssistant,
+  };
+}
+
+type Palette = {
+  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;
+
+function makePalette(enabled: boolean): Palette {
+  if (!enabled) {
+    return {
+      dim: IDENTITY,
+      bold: IDENTITY,
+      cyan: IDENTITY,
+      green: IDENTITY,
+      red: IDENTITY,
+      magenta: IDENTITY,
+      yellow: IDENTITY,
+    };
+  }
+  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"),
+  };
+}
+
+function stringify(value: unknown): string {
+  if (value === undefined || value === null) {
+    return "(no output)";
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function formatArgs(args: unknown): string {
+  if (args === undefined || args === null) {
+    return "";
+  }
+  const text = typeof args === "string" ? args : JSON.stringify(args);
+  return text === "{}" ? "" : `(${truncate(text, 80)})`;
+}
+
+function truncate(text: string, max: number): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}

package/src/internal/tool-result.ts

@@ -0,0 +1,54 @@
+import type { SDKCustomToolResult } from "@cursor/sdk";
+import type { ToolExecuteResult } from "../types.js";
+
+/**
+ * Normalize a custom tool's return value for the SDK.
+ *
+ * Plain objects are round-tripped through JSON so fields whose value is
+ * `undefined` are dropped (JSON semantics). Without this, a return like
+ * `{ action: undefined }` reaches the SDK's protobuf `Struct.fromJson`,
+ * which throws `cannot decode google.protobuf.Value from JSON undefined` —
+ * the tool has already executed, but the model only sees an opaque encode
+ * error and typically retries the call.
+ */
+export function normalizeToolResult(
+  result: ToolExecuteResult | undefined
+): SDKCustomToolResult {
+  if (result === undefined) {
+    return "";
+  }
+  if (typeof result === "string") {
+    return result;
+  }
+  try {
+    return JSON.parse(JSON.stringify(result)) as SDKCustomToolResult;
+  } catch {
+    return result as SDKCustomToolResult;
+  }
+}
+
+/**
+ * Pull a channel-friendly error string out of a normalized tool result
+ * (error envelopes with `{ content: [{ type: "text", text }] }`, or a
+ * bare string). Used for {@link import("../types.js").ToolCallOutcome.errorMessage}.
+ */
+export function toolCallErrorMessage(result: unknown): string | undefined {
+  if (typeof result === "string" && result.trim() !== "") {
+    return result;
+  }
+  if (
+    result === null ||
+    typeof result !== "object" ||
+    !("content" in result) ||
+    !Array.isArray((result as { content: unknown }).content)
+  ) {
+    return undefined;
+  }
+  const texts = (
+    result as { content: Array<{ type?: string; text?: string }> }
+  ).content
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text!.trim())
+    .filter((text) => text !== "");
+  return texts.length === 0 ? undefined : texts.join("\n");
+}