@cursor/july 0.1.2 → 0.1.3

package/src/internal/chat-client.ts

@@ -8,12 +8,30 @@
 
 import { createInterface } from "node:readline";
 import type { SessionEvent } from "../types.js";
+import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
+import { fetchSessionEvents, listSessions } from "./sessions-client.js";
 
-export interface ChatClientOptions {
+export interface ChatClientOptions extends RequestAuth {
   baseUrl: string;
-  bearerToken?: string;
-  /** One-shot: send this message, stream the reply, then exit. */
+  /**
+   * Optional opening user message. On a TTY (without `oneShot`), this seeds
+   * the first turn and then the REPL stays open for follow-ups. With
+   * `oneShot` (or a non-TTY stdin), send it and exit.
+   */
   message?: string;
+  /**
+   * Reattach to an existing session. Looks up the current continuation
+   * token via `GET /v1/sessions` when `--continuation-token` is omitted,
+   * replays the transcript, then accepts follow-ups.
+   */
+  sessionId?: string;
+  /** Optional; when omitted with `sessionId`, resolved from `/v1/sessions`. */
+  continuationToken?: string;
+  /**
+   * Exit after the opening `--message` instead of entering the REPL.
+   * Implied when stdin is not a TTY.
+   */
+  oneShot?: boolean;
   /** Force plain output even on a TTY. */
   noColor?: boolean;
   logger?: (line: string) => void;
@@ -61,6 +79,10 @@ function makePalette(enabled: boolean): Palette {
 /** 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 auth: RequestAuth = {
+    bearerToken: options.bearerToken,
+    headers: options.headers,
+  };
   const colorEnabled =
     !options.noColor && process.stdout.isTTY === true && !process.env.NO_COLOR;
   const c = makePalette(colorEnabled);
@@ -68,11 +90,11 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
     process.stdout.write(s);
   };
 
-  const health = await getJson(baseUrl, "/v1/health", options.bearerToken);
+  const health = await getJson(baseUrl, "/v1/health", auth);
   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);
+  const info = await getJson(baseUrl, "/v1/info", auth);
   if (info && typeof info === "object") {
     const model = (info as { model?: unknown }).model;
     const tools = (info as { tools?: unknown[] }).tools ?? [];
@@ -86,22 +108,43 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
   }
   write("\n");
 
-  let sessionId: string | undefined;
-  let continuationToken: string | undefined;
+  let sessionId: string | undefined = options.sessionId;
+  let continuationToken: string | undefined = options.continuationToken;
   // 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`);
+  if (options.sessionId !== undefined) {
+    const attached = await attachSession({
+      baseUrl,
+      auth,
+      sessionId: options.sessionId,
+      continuationToken: options.continuationToken,
+      agentName,
+      palette: c,
+      write,
+    });
+    sessionId = attached.sessionId;
+    continuationToken = attached.continuationToken;
+    nextEventIndex = attached.nextEventIndex;
+  } else if (options.continuationToken !== undefined) {
+    throw new Error(
+      "--continuation-token requires --session (session id to reattach to)"
+    );
+  }
+
+  const runTurn = async (
+    message: string,
+    opts: { echoUser?: boolean } = {}
+  ): Promise<void> => {
+    // REPL lines are already echoed by readline; only reprint for seeded
+    // `--message` / one-shot so the transcript still shows the user turn.
+    if (opts.echoUser !== false) {
+      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
-      );
+      const created = await postJson(baseUrl, "/v1/session", { message }, auth);
       sessionId = str(created?.sessionId);
       continuationToken = str(created?.continuationToken);
     } else {
@@ -109,13 +152,13 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
         baseUrl,
         `/v1/session/${sessionId}`,
         { message, continuationToken },
-        options.bearerToken
+        auth
       );
       if (resp?.ok === false) {
         write(`${c.red("error")} ${str(resp.error)}: ${str(resp.message)}\n\n`);
         return;
       }
-      continuationToken = str(resp?.continuationToken);
+      continuationToken = str(resp?.continuationToken) ?? continuationToken;
     }
     if (sessionId === undefined) {
       write(`${c.red("error")} server did not return a session id\n\n`);
@@ -125,16 +168,21 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
       baseUrl,
       sessionId,
       startIndex,
-      bearerToken: options.bearerToken,
+      auth,
+      agentName,
       palette: c,
       write,
     });
     write("\n");
   };
 
+  const oneShot = options.oneShot === true || process.stdin.isTTY !== true;
+
   if (options.message !== undefined) {
     await runTurn(options.message);
-    return;
+    if (oneShot) {
+      return;
+    }
   }
 
   write(c.dim("Type a message and press Enter. Ctrl-D or /quit to exit.\n\n"));
@@ -156,7 +204,7 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
         return;
       }
       rl.pause();
-      runTurn(text)
+      runTurn(text, { echoUser: false })
         .catch((err) => {
           write(`${c.red("error")} ${describe(err)}\n\n`);
         })
@@ -172,11 +220,139 @@ export async function runChat(options: ChatClientOptions): Promise<void> {
   });
 }
 
+/**
+ * Resolve the current continuation token for a session via `GET /v1/sessions`.
+ * Throws when the session is missing or not followable.
+ */
+export async function lookupSessionContinuation(args: {
+  baseUrl: string;
+  sessionId: string;
+  auth?: RequestAuth;
+}): Promise<string> {
+  const sessions = await listSessions({
+    baseUrl: args.baseUrl,
+    auth: args.auth,
+  });
+  const match = sessions.find((s) => s.sessionId === args.sessionId);
+  if (match === undefined) {
+    throw new Error(
+      `Session ${args.sessionId} not found in /v1/sessions (wrong id, or not owned by this caller). ` +
+        `Pass --continuation-token if you have it.`
+    );
+  }
+  const token = str(match.continuationToken);
+  if (token === undefined) {
+    throw new Error(
+      `Session ${args.sessionId} has no continuation token` +
+        (match.mode === "task" ? " (task sessions are not followable)." : ".")
+    );
+  }
+  return token;
+}
+
+async function attachSession(args: {
+  baseUrl: string;
+  auth: RequestAuth;
+  sessionId: string;
+  continuationToken?: string;
+  agentName: string;
+  palette: Palette;
+  write: (s: string) => void;
+}): Promise<{
+  sessionId: string;
+  continuationToken: string;
+  nextEventIndex: number;
+}> {
+  const { palette: c, write } = args;
+  let continuationToken = args.continuationToken;
+
+  if (continuationToken === undefined || continuationToken === "") {
+    continuationToken = await lookupSessionContinuation({
+      baseUrl: args.baseUrl,
+      sessionId: args.sessionId,
+      auth: args.auth,
+    });
+  }
+
+  const events = await fetchSessionEvents({
+    baseUrl: args.baseUrl,
+    sessionId: args.sessionId,
+    auth: args.auth,
+  });
+  if (events.length > 0) {
+    write(
+      c.dim(
+        `reattached ${args.sessionId} · replaying ${events.length} events\n\n`
+      )
+    );
+    renderTranscript(events, args.agentName, c, write);
+    write("\n");
+  } else {
+    write(c.dim(`reattached ${args.sessionId}\n\n`));
+  }
+
+  const lastIndex =
+    events.length === 0
+      ? -1
+      : Math.max(
+          ...events.map((e) => (typeof e.index === "number" ? e.index : -1))
+        );
+
+  return {
+    sessionId: args.sessionId,
+    continuationToken,
+    nextEventIndex: lastIndex + 1,
+  };
+}
+
+/** Compact historical transcript for reattach (final messages + tool calls). */
+function renderTranscript(
+  events: SessionEvent[],
+  agentName: string,
+  c: Palette,
+  write: (s: string) => void
+): void {
+  for (const event of events) {
+    if (event.type === "message.received") {
+      write(`${c.cyan("› you")}  ${event.data.text}\n`);
+      continue;
+    }
+    if (event.type === "message.completed") {
+      const text = event.data.text?.trim() ?? "";
+      if (text !== "" && event.data.finishReason !== "tool_call") {
+        write(`${c.green(`‹ ${agentName}`)}  ${text}\n`);
+      }
+      continue;
+    }
+    if (event.type === "actions.requested") {
+      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.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 === "turn.completed") {
+      write(c.dim("  ─ turn done\n"));
+    }
+  }
+}
+
 interface StreamTurnArgs {
   baseUrl: string;
   sessionId: string;
   startIndex: number;
-  bearerToken: string | undefined;
+  auth: RequestAuth | undefined;
+  agentName: string;
   palette: Palette;
   write: (s: string) => void;
 }
@@ -191,7 +367,7 @@ const TERMINAL_TYPES = new Set([
 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) });
+  const resp = await fetch(url, { headers: mergeRequestHeaders(args.auth) });
   if (!resp.ok || resp.body === null) {
     write(`${c.red("error")} stream failed (${resp.status})\n`);
     return args.startIndex;
@@ -242,28 +418,46 @@ async function streamTurn(args: StreamTurnArgs): Promise<number> {
         }
         continue;
       }
-      if (event.type === "reasoning.appended" && !thinkingShown) {
+      if (
+        event.type === "reasoning.appended" &&
+        event.data.parentCallId === undefined &&
+        !thinkingShown
+      ) {
         thinkingShown = true;
         write(c.dim("  · thinking…\n"));
         continue;
       }
       if (event.type === "message.appended") {
+        if (event.data.parentCallId !== undefined) {
+          continue;
+        }
         if (!assistantOpen) {
-          write(`${c.green("‹ agent")}  `);
+          write(`${c.green(`‹ ${args.agentName}`)}  `);
           assistantOpen = true;
         }
         write(event.data.delta);
         continue;
       }
       if (event.type === "message.completed") {
+        if (event.data.parentCallId !== undefined) {
+          continue;
+        }
         closeAssistant();
         continue;
       }
       if (event.type === "actions.requested") {
         closeAssistant();
         for (const call of event.data.calls) {
+          if (call.toolName === "task" && call.parentCallId === undefined) {
+            continue;
+          }
+          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`
           );
@@ -290,9 +484,17 @@ async function streamTurn(args: StreamTurnArgs): Promise<number> {
         continue;
       }
       if (event.type === "action.result") {
+        if (
+          event.data.toolName === "task" &&
+          event.data.parentCallId === undefined
+        ) {
+          continue;
+        }
         const label = event.data.isError ? c.red("✗") : c.magenta("→");
+        const indent =
+          event.data.parentCallId !== undefined ? "      " : "    ";
         write(
-          `    ${label} ${c.dim(truncate(stringify(event.data.output), 100))}\n`
+          `${indent}${label} ${c.dim(truncate(stringify(event.data.output), 100))}\n`
         );
         continue;
       }
@@ -338,20 +540,14 @@ async function streamTurn(args: StreamTurnArgs): Promise<number> {
 // 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
+  auth: RequestAuth | undefined
 ): Promise<Record<string, unknown> | undefined> {
   try {
     const resp = await fetch(`${baseUrl}${path}`, {
-      headers: authHeaders(bearerToken),
+      headers: mergeRequestHeaders(auth),
     });
     const text = await resp.text();
     return text ? (JSON.parse(text) as Record<string, unknown>) : undefined;
@@ -364,18 +560,37 @@ async function postJson(
   baseUrl: string,
   path: string,
   body: unknown,
-  bearerToken: string | undefined
+  auth: RequestAuth | undefined
 ): Promise<Record<string, unknown> | undefined> {
   const resp = await fetch(`${baseUrl}${path}`, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      ...authHeaders(bearerToken),
+      ...mergeRequestHeaders(auth),
     },
     body: JSON.stringify(body),
   });
   const text = await resp.text();
-  return text ? (JSON.parse(text) as Record<string, unknown>) : undefined;
+  let parsed: Record<string, unknown> | undefined;
+  if (text) {
+    try {
+      parsed = JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      parsed = { message: text };
+    }
+  }
+  if (!resp.ok) {
+    const anyrunReason = resp.headers.get("x-anyrun-failure-reason");
+    const message =
+      (typeof parsed?.message === "string" && parsed.message !== ""
+        ? parsed.message
+        : undefined) ??
+      (typeof parsed?.error === "string" ? parsed.error : undefined) ??
+      anyrunReason ??
+      `HTTP ${resp.status}`;
+    return { ok: false, error: "http_error", message, status: resp.status };
+  }
+  return parsed;
 }
 
 function str(value: unknown): string | undefined {