@cursor/july 0.1.1

package/src/internal/bounded-int.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared validation for optional config ceilings (playground windows, etc.).
+ */
+
+export function normalizePositiveInt(
+  value: unknown,
+  options: {
+    /** e.g. `evals.config.ts: maxPlaygroundRuns` */
+    label: string;
+    max: number;
+    /** Override the default "exceeds the hard limit" message body after the label. */
+    maxMessage?: string;
+  }
+): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `${options.label} must be a positive integer (got ${String(value)})`
+    );
+  }
+  if (value > options.max) {
+    throw new Error(
+      options.maxMessage ??
+        `${options.label} ${value} exceeds the hard limit of ${options.max}`
+    );
+  }
+  return value;
+}

package/src/internal/brand.ts

@@ -0,0 +1,29 @@
+import type { BrandedDefinition, DefinitionKind } from "../types.js";
+
+export const DEFINITION_BRAND_FIELD = "__agentServe";
+
+export function brandDefinition<K extends DefinitionKind, T extends object>(
+  kind: K,
+  definition: T
+): T & BrandedDefinition<K> {
+  return { ...definition, [DEFINITION_BRAND_FIELD]: kind } as T &
+    BrandedDefinition<K>;
+}
+
+export function getDefinitionKind(value: unknown): DefinitionKind | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const kind = (value as Record<string, unknown>)[DEFINITION_BRAND_FIELD];
+  if (typeof kind !== "string") {
+    return undefined;
+  }
+  return kind as DefinitionKind;
+}
+
+export function isDefinitionOfKind<K extends DefinitionKind>(
+  value: unknown,
+  kind: K
+): value is BrandedDefinition<K> {
+  return getDefinitionKind(value) === kind;
+}

package/src/internal/chat-client.ts

@@ -0,0 +1,407 @@
+/**
+ * `agent-serve chat` — a minimal terminal client for a served agent. It
+ * drives only the public HTTP API (create session, follow-up, NDJSON
+ * stream), so it works against any agent-serve server and demonstrates the
+ * same wire protocol the playground and curl use. Renders streamed
+ * assistant text live, tool calls inline, and a per-turn usage footer.
+ */
+
+import { createInterface } from "node:readline";
+import type { SessionEvent } from "../types.js";
+
+export interface ChatClientOptions {
+  baseUrl: string;
+  bearerToken?: string;
+  /** One-shot: send this message, stream the reply, then exit. */
+  message?: string;
+  /** Force plain output even on a TTY. */
+  noColor?: boolean;
+  logger?: (line: string) => void;
+}
+
+interface 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"),
+  };
+}
+
+/** Run the terminal chat client. Resolves when the session/REPL ends. */
+export async function runChat(options: ChatClientOptions): Promise<void> {
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const colorEnabled =
+    !options.noColor && process.stdout.isTTY === true && !process.env.NO_COLOR;
+  const c = makePalette(colorEnabled);
+  const write = (s: string): void => {
+    process.stdout.write(s);
+  };
+
+  const health = await getJson(baseUrl, "/v1/health", options.bearerToken);
+  const agentName =
+    typeof health?.name === "string" ? health.name : "agent-serve";
+  write(`${c.bold(agentName)} ${c.dim(`· ${baseUrl}`)}\n`);
+  const info = await getJson(baseUrl, "/v1/info", options.bearerToken);
+  if (info && typeof info === "object") {
+    const model = (info as { model?: unknown }).model;
+    const tools = (info as { tools?: unknown[] }).tools ?? [];
+    const modelText =
+      typeof model === "string" ? model : JSON.stringify(model ?? "");
+    write(
+      c.dim(
+        `model ${modelText} · ${tools.length} tool${tools.length === 1 ? "" : "s"}\n`
+      )
+    );
+  }
+  write("\n");
+
+  let sessionId: string | undefined;
+  let continuationToken: string | undefined;
+  // Highest event index rendered so far; a follow-up streams from here so it
+  // shows only the new turn, not the replayed transcript.
+  let nextEventIndex = 0;
+
+  const runTurn = async (message: string): Promise<void> => {
+    write(`${c.cyan("› you")}  ${message}\n`);
+    const startIndex = sessionId === undefined ? 0 : nextEventIndex;
+    if (sessionId === undefined) {
+      const created = await postJson(
+        baseUrl,
+        "/v1/session",
+        { message },
+        options.bearerToken
+      );
+      sessionId = str(created?.sessionId);
+      continuationToken = str(created?.continuationToken);
+    } else {
+      const resp = await postJson(
+        baseUrl,
+        `/v1/session/${sessionId}`,
+        { message, continuationToken },
+        options.bearerToken
+      );
+      if (resp?.ok === false) {
+        write(`${c.red("error")} ${str(resp.error)}: ${str(resp.message)}\n\n`);
+        return;
+      }
+      continuationToken = str(resp?.continuationToken);
+    }
+    if (sessionId === undefined) {
+      write(`${c.red("error")} server did not return a session id\n\n`);
+      return;
+    }
+    nextEventIndex = await streamTurn({
+      baseUrl,
+      sessionId,
+      startIndex,
+      bearerToken: options.bearerToken,
+      palette: c,
+      write,
+    });
+    write("\n");
+  };
+
+  if (options.message !== undefined) {
+    await runTurn(options.message);
+    return;
+  }
+
+  write(c.dim("Type a message and press Enter. Ctrl-D or /quit to exit.\n\n"));
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  await new Promise<void>((resolve) => {
+    const prompt = (): void => {
+      rl.setPrompt(c.cyan("› "));
+      rl.prompt();
+    };
+    prompt();
+    rl.on("line", (line) => {
+      const text = line.trim();
+      if (text === "") {
+        prompt();
+        return;
+      }
+      if (text === "/quit" || text === "/exit") {
+        rl.close();
+        return;
+      }
+      rl.pause();
+      runTurn(text)
+        .catch((err) => {
+          write(`${c.red("error")} ${describe(err)}\n\n`);
+        })
+        .finally(() => {
+          rl.resume();
+          prompt();
+        });
+    });
+    rl.on("close", () => {
+      write(c.dim("\nbye\n"));
+      resolve();
+    });
+  });
+}
+
+interface StreamTurnArgs {
+  baseUrl: string;
+  sessionId: string;
+  startIndex: number;
+  bearerToken: string | undefined;
+  palette: Palette;
+  write: (s: string) => void;
+}
+
+const TERMINAL_TYPES = new Set([
+  "session.waiting",
+  "session.completed",
+  "session.failed",
+]);
+
+/** Streams a turn to the terminal; returns the next event index to resume at. */
+async function streamTurn(args: StreamTurnArgs): Promise<number> {
+  const { palette: c, write } = args;
+  const url = `${args.baseUrl}/v1/session/${args.sessionId}/stream?startIndex=${args.startIndex}`;
+  const resp = await fetch(url, { headers: authHeaders(args.bearerToken) });
+  if (!resp.ok || resp.body === null) {
+    write(`${c.red("error")} stream failed (${resp.status})\n`);
+    return args.startIndex;
+  }
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let assistantOpen = false;
+  let thinkingShown = false;
+  let lastIndex = args.startIndex - 1;
+
+  const closeAssistant = (): void => {
+    if (assistantOpen) {
+      write("\n");
+      assistantOpen = false;
+    }
+  };
+
+  for (;;) {
+    const chunk = await reader.read();
+    if (chunk.done) {
+      break;
+    }
+    buffer += decoder.decode(chunk.value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    let stop = false;
+    for (const line of lines) {
+      if (line.trim() === "") {
+        continue;
+      }
+      let event: SessionEvent;
+      try {
+        event = JSON.parse(line) as SessionEvent;
+      } catch {
+        continue;
+      }
+      if (typeof event.index === "number") {
+        lastIndex = event.index;
+      }
+      if (event.type === "agent.bound") {
+        closeAssistant();
+        const { sdkAgentId, url } = event.data;
+        write(`  ${c.cyan("agent")} ${c.bold(sdkAgentId)}\n`);
+        if (url !== undefined) {
+          write(`  ${c.dim(url)}\n`);
+        }
+        continue;
+      }
+      if (event.type === "reasoning.appended" && !thinkingShown) {
+        thinkingShown = true;
+        write(c.dim("  · thinking…\n"));
+        continue;
+      }
+      if (event.type === "message.appended") {
+        if (!assistantOpen) {
+          write(`${c.green("‹ agent")}  `);
+          assistantOpen = true;
+        }
+        write(event.data.delta);
+        continue;
+      }
+      if (event.type === "message.completed") {
+        closeAssistant();
+        continue;
+      }
+      if (event.type === "actions.requested") {
+        closeAssistant();
+        for (const call of event.data.calls) {
+          write(
+            `  ${c.magenta("⚙")} ${c.bold(call.toolName)}${c.dim(
+              formatArgs(call.args)
+            )}\n`
+          );
+        }
+        continue;
+      }
+      if (event.type === "action.approval_requested") {
+        closeAssistant();
+        write(
+          `    ${c.yellow("⏸")} ${c.bold(event.data.toolName)} ${c.dim(
+            "awaiting human approval"
+          )}\n`
+        );
+        continue;
+      }
+      if (event.type === "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`
+        );
+        continue;
+      }
+      if (event.type === "action.result") {
+        const label = event.data.isError ? c.red("✗") : c.magenta("→");
+        write(
+          `    ${label} ${c.dim(truncate(stringify(event.data.output), 100))}\n`
+        );
+        continue;
+      }
+      if (event.type === "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`
+        );
+        continue;
+      }
+      if (event.type === "turn.completed") {
+        closeAssistant();
+        const usage = event.data.usage;
+        const tokens = usage
+          ? ` · in ${usage.inputTokens} out ${usage.outputTokens} tok`
+          : "";
+        write(c.dim(`  ─ turn done${tokens}\n`));
+        continue;
+      }
+      if (event.type === "turn.failed") {
+        closeAssistant();
+        write(`${c.red("  ✗ turn failed")} ${event.data.message}\n`);
+        continue;
+      }
+      if (TERMINAL_TYPES.has(event.type)) {
+        closeAssistant();
+        stop = true;
+        break;
+      }
+    }
+    if (stop) {
+      break;
+    }
+  }
+  await reader.cancel().catch(() => {});
+  return lastIndex + 1;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers (built-in fetch; node 22+)
+// ---------------------------------------------------------------------------
+
+function authHeaders(bearerToken: string | undefined): Record<string, string> {
+  return bearerToken === undefined
+    ? {}
+    : { authorization: `Bearer ${bearerToken}` };
+}
+
+async function getJson(
+  baseUrl: string,
+  path: string,
+  bearerToken: string | undefined
+): Promise<Record<string, unknown> | undefined> {
+  try {
+    const resp = await fetch(`${baseUrl}${path}`, {
+      headers: authHeaders(bearerToken),
+    });
+    const text = await resp.text();
+    return text ? (JSON.parse(text) as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function postJson(
+  baseUrl: string,
+  path: string,
+  body: unknown,
+  bearerToken: string | undefined
+): Promise<Record<string, unknown> | undefined> {
+  const resp = await fetch(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...authHeaders(bearerToken),
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await resp.text();
+  return text ? (JSON.parse(text) as Record<string, unknown>) : undefined;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+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;
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}