@cursor/july 0.1.2 → 0.1.4

package/src/internal/logs-client.ts

@@ -0,0 +1,442 @@
+/**
+ * `agentkit logs` — follow deploy progress (hosted) then runtime `/v1/logs`.
+ *
+ * Customer-facing output never includes hosting URLs, tokens, or infra jargon.
+ */
+
+import {
+  DeployApiError,
+  type DeploymentDetail,
+  type DeploymentProgress,
+} from "./deploy-client.js";
+import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
+import { resolveProdTarget } from "./resolve-prod-target.js";
+import { stderrPalette } from "./terminal-style.js";
+
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+
+/** Re-read abort state after await (loop narrowing would hide async abort). */
+function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}
+
+export interface LogRingEntry {
+  index: number;
+  at: string;
+  line: string;
+}
+
+export interface LogsResponse {
+  entries: LogRingEntry[];
+  nextAfter: number;
+}
+
+export type LogsProgress =
+  | DeploymentProgress
+  | "queued"
+  | "preparing"
+  | "building"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopping"
+  | "stopped"
+  | "degraded";
+
+const PROGRESS_MESSAGES: Readonly<Record<LogsProgress, string>> = {
+  queued: "Waiting to start…",
+  preparing: "Preparing runtime…",
+  building: "Building and starting agent…",
+  finalizing: "Finishing deployment…",
+  running: "Deployment running",
+  failed: "Deploy failed",
+  stopping: "Stopping deployment…",
+  stopped: "Deployment stopped",
+  degraded: "Deployment degraded",
+};
+
+export function progressMessage(
+  progress: LogsProgress,
+  lastError?: string | null
+): string {
+  if (progress === "failed") {
+    const detail =
+      lastError === null || lastError === undefined || lastError.trim() === ""
+        ? ""
+        : `: ${sanitizeCustomerError(lastError)}`;
+    return `Deploy failed${detail}`;
+  }
+  if (progress === "degraded") {
+    const detail =
+      lastError === null || lastError === undefined || lastError.trim() === ""
+        ? ""
+        : `: ${sanitizeCustomerError(lastError)}`;
+    return `Deployment degraded${detail}`;
+  }
+  return PROGRESS_MESSAGES[progress];
+}
+
+/** Strip obvious hosting internals from error text shown to customers. */
+export function sanitizeCustomerError(message: string): string {
+  return message
+    .replace(/https?:\/\/\S+/gi, "[url]")
+    .replace(/\bpod-[a-z0-9]+\b/gi, "[runtime]")
+    .replace(/\banyrun\b/gi, "runtime")
+    .replace(/\bcursorvm\.com\b/gi, "host")
+    .replace(/\bx-anyrun-[a-z0-9-]+\b/gi, "header")
+    .replace(/\bPROVISIONING\b/g, "building")
+    .replace(/\bPLANNED\b/g, "preparing");
+}
+
+export async function fetchLogs(args: {
+  baseUrl: string;
+  after?: number;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+}): Promise<LogsResponse> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const after = args.after ?? -1;
+  const url = new URL(`${args.baseUrl.replace(/\/$/, "")}/v1/logs`);
+  if (after >= 0) {
+    url.searchParams.set("after", String(after));
+  }
+  const resp = await fetchImpl(url, {
+    headers: mergeRequestHeaders(args.auth),
+    signal: args.signal,
+  });
+  if (!resp.ok) {
+    throw new Error(`Could not fetch logs (HTTP ${resp.status}).`);
+  }
+  const body = (await resp.json()) as {
+    entries?: LogRingEntry[];
+    nextAfter?: number;
+  };
+  const entries = Array.isArray(body.entries) ? body.entries : [];
+  const nextAfter =
+    typeof body.nextAfter === "number"
+      ? body.nextAfter
+      : entries.length === 0
+        ? after
+        : (entries[entries.length - 1]?.index ?? after);
+  return { entries, nextAfter };
+}
+
+export interface RunLogsTailOptions {
+  /** When true, use hosted deploy progress then runtime logs. */
+  prod?: boolean;
+  dir: string;
+  cwd?: string;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  url?: string;
+  bearerToken?: string;
+  once?: boolean;
+  json?: boolean;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  intervalMs?: number;
+  /** stdout writer (test seam). */
+  write?: (text: string) => void;
+  /** stderr writer (test seam). */
+  err?: (text: string) => void;
+  /**
+   * Deploy detail fetcher for `--prod` progress (test seam). Defaults to
+   * management API via resolveProdTarget's auth path.
+   */
+  getDeployment?: () => Promise<DeploymentDetail>;
+  /** After deploy is running, resolve runtime base URL + headers. */
+  resolveRuntime?: () => Promise<{
+    agentUrl: string;
+    headers?: Record<string, string>;
+  }>;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+export async function runLogsTail(options: RunLogsTailOptions): Promise<void> {
+  const write =
+    options.write ?? ((text: string) => void process.stdout.write(text));
+  const err =
+    options.err ?? ((text: string) => void process.stderr.write(text));
+  const sleep = options.sleep ?? sleepMs;
+  const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const c = stderrPalette();
+
+  if (options.prod === true) {
+    await followProdLogs({
+      ...options,
+      write,
+      err,
+      sleep,
+      intervalMs,
+      palette: c,
+    });
+    return;
+  }
+
+  const baseUrl = (options.url ?? "http://127.0.0.1:3000").replace(/\/$/, "");
+  if (options.once !== true) {
+    err(c.dim("Tailing logs… (Ctrl-C to stop)\n"));
+  }
+  await followRuntimeLogs({
+    baseUrl,
+    auth: { bearerToken: options.bearerToken },
+    once: options.once === true,
+    json: options.json === true,
+    fetchImpl: options.fetchImpl,
+    signal: options.signal,
+    intervalMs,
+    write,
+    sleep,
+  });
+}
+
+async function followProdLogs(args: {
+  dir: string;
+  cwd?: string;
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  bearerToken?: string;
+  once?: boolean;
+  json?: boolean;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  intervalMs: number;
+  write: (text: string) => void;
+  err: (text: string) => void;
+  getDeployment?: () => Promise<DeploymentDetail>;
+  resolveRuntime?: () => Promise<{
+    agentUrl: string;
+    headers?: Record<string, string>;
+  }>;
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+  palette: ReturnType<typeof stderrPalette>;
+}): Promise<void> {
+  const resolveRuntime =
+    args.resolveRuntime ??
+    (async () => {
+      const target = await resolveProdTarget({
+        dir: args.dir,
+        cwd: args.cwd,
+        slug: args.slug,
+        team: args.team,
+        apiKey: args.apiKey,
+        fetchImpl: args.fetchImpl,
+        err: () => {},
+      });
+      return { agentUrl: target.agentUrl, headers: target.headers };
+    });
+
+  const getDeployment =
+    args.getDeployment ??
+    (async () => {
+      // Lazy import path via resolveProdTarget side: re-fetch through a
+      // one-shot resolve that throws if not running is wrong for progress.
+      // Callers that omit getDeployment must provide it in production via
+      // cmdLogs (which wires deploy auth).
+      throw new Error(
+        "Internal error: deploy progress requires a deployment lookup."
+      );
+    });
+
+  let lastProgress: string | undefined;
+  const slugHint = args.slug !== undefined && args.slug !== "" ? args.slug : "";
+  if (args.once !== true) {
+    const label = slugHint !== "" ? slugHint : "deployment";
+    args.err(args.palette.dim(`Tailing logs for ${label}… (Ctrl-C to stop)\n`));
+  }
+
+  while (!isAborted(args.signal)) {
+    let detail: DeploymentDetail;
+    try {
+      detail = await getDeployment();
+    } catch (error) {
+      if (isAborted(args.signal)) {
+        return;
+      }
+      throw customerDeployLookupError(error);
+    }
+
+    const progress = resolveProgress(detail);
+
+    if (progress === "failed") {
+      const message = progressMessage(progress, detail.lastError);
+      if (progress !== lastProgress) {
+        lastProgress = progress;
+        emitProgress(args.write, args.json === true, progress, message);
+      }
+      throw new Error(`Deployment "${detail.slug}" failed.`);
+    }
+    if (progress === "stopped") {
+      const message = progressMessage(progress, detail.lastError);
+      if (progress !== lastProgress) {
+        lastProgress = progress;
+        emitProgress(args.write, args.json === true, progress, message);
+      }
+      throw new Error(`Deployment "${detail.slug}" is stopped.`);
+    }
+    if (progress === "running" || progress === "degraded") {
+      // Hand off to runtime logs. Print degraded once; skip a "running" line.
+      if (progress === "degraded" && progress !== lastProgress) {
+        lastProgress = progress;
+        emitProgress(
+          args.write,
+          args.json === true,
+          progress,
+          progressMessage(progress, detail.lastError)
+        );
+      }
+      const runtime = await resolveRuntime();
+      await followRuntimeLogs({
+        baseUrl: runtime.agentUrl,
+        auth: {
+          bearerToken: args.bearerToken,
+          headers: runtime.headers,
+        },
+        once: args.once === true,
+        json: args.json === true,
+        fetchImpl: args.fetchImpl,
+        signal: args.signal,
+        intervalMs: args.intervalMs,
+        write: args.write,
+        sleep: args.sleep,
+      });
+      return;
+    }
+
+    const message = progressMessage(progress, detail.lastError);
+    if (progress !== lastProgress) {
+      lastProgress = progress;
+      emitProgress(args.write, args.json === true, progress, message);
+    }
+
+    if (args.once === true) {
+      return;
+    }
+
+    await args.sleep(args.intervalMs, args.signal);
+  }
+}
+
+function resolveProgress(detail: DeploymentDetail): LogsProgress {
+  if (detail.progress !== undefined) {
+    return detail.progress;
+  }
+  switch (detail.status) {
+    case "pending":
+      return "queued";
+    case "deploying":
+      return "building";
+    case "running":
+      return "running";
+    case "failed":
+      return "failed";
+    case "degraded":
+      return "degraded";
+    case "stopping":
+      return "stopping";
+    case "stopped":
+      return "stopped";
+    default:
+      return "queued";
+  }
+}
+
+function emitProgress(
+  write: (text: string) => void,
+  json: boolean,
+  progress: LogsProgress,
+  message: string
+): void {
+  if (json) {
+    write(`${JSON.stringify({ type: "progress", progress, message })}\n`);
+    return;
+  }
+  write(`${message}\n`);
+}
+
+async function followRuntimeLogs(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  once: boolean;
+  json: boolean;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  intervalMs: number;
+  write: (text: string) => void;
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+}): Promise<void> {
+  let after = -1;
+  for (;;) {
+    if (isAborted(args.signal)) {
+      return;
+    }
+    let batch: LogsResponse;
+    try {
+      batch = await fetchLogs({
+        baseUrl: args.baseUrl,
+        after,
+        auth: args.auth,
+        fetchImpl: args.fetchImpl,
+        signal: args.signal,
+      });
+    } catch (error) {
+      if (isAborted(args.signal)) {
+        return;
+      }
+      throw error instanceof Error ? error : new Error("Could not fetch logs.");
+    }
+
+    for (const entry of batch.entries) {
+      if (args.json) {
+        args.write(
+          `${JSON.stringify({
+            type: "log",
+            index: entry.index,
+            at: entry.at,
+            line: entry.line,
+          })}\n`
+        );
+      } else {
+        args.write(`${entry.line}\n`);
+      }
+    }
+    after = batch.nextAfter;
+
+    if (args.once) {
+      return;
+    }
+    await args.sleep(args.intervalMs, args.signal);
+  }
+}
+
+function customerDeployLookupError(error: unknown): Error {
+  if (error instanceof DeployApiError) {
+    return new Error(
+      `Could not look up deployment: ${sanitizeCustomerError(error.message)}`
+    );
+  }
+  if (error instanceof Error) {
+    return new Error(sanitizeCustomerError(error.message));
+  }
+  return new Error("Could not look up deployment.");
+}
+
+async function sleepMs(ms: number, signal?: AbortSignal): Promise<void> {
+  if (isAborted(signal)) {
+    return;
+  }
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/internal/mcp-endpoint.ts

@@ -106,9 +106,7 @@ export async function handleStatelessMcpRequest(args: {
     // so closing in `finally` never truncates a streamed response.
     return await transport.handleRequest(args.request);
   } catch (error) {
-    logger(
-      `[agent-serve] ${args.label} request failed: ${describeError(error)}`
-    );
+    logger(`[agentkit] ${args.label} request failed: ${describeError(error)}`);
     return new Response(
       JSON.stringify({
         jsonrpc: "2.0",

package/src/internal/open-browser.ts

@@ -0,0 +1,41 @@
+/**
+ * Best-effort browser open; callers should always print the URL as fallback.
+ */
+
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+export function openBrowser(url: string): void {
+  const command =
+    process.platform === "darwin"
+      ? { cmd: "open", args: [url] }
+      : process.platform === "win32"
+        ? {
+            cmd: join(
+              process.env.SYSTEMROOT ?? "C:\\Windows",
+              "System32",
+              "WindowsPowerShell",
+              "v1.0",
+              "powershell.exe"
+            ),
+            args: [
+              "-NoProfile",
+              "-NonInteractive",
+              "-WindowStyle",
+              "Hidden",
+              "-Command",
+              `Start-Process '${url.replace(/'/g, "''")}'`,
+            ],
+          }
+        : { cmd: "xdg-open", args: [url] };
+  try {
+    const child = spawn(command.cmd, command.args, {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Printed URL is the fallback.
+  }
+}

package/src/internal/playground/toolchain.ts

@@ -121,7 +121,7 @@ export async function runPlaygroundBuild(
       "playground vite toolchain unavailable (need playground/ sources and the vite package)"
     );
   }
-  logger("[agent-serve] building playground (vite)...");
+  logger("[agentkit] building playground (vite)...");
   const code = await spawnVite(toolchain, ["build", "--config", VITE_CONFIG], {
     env: process.env,
   });
@@ -133,7 +133,7 @@ export async function runPlaygroundBuild(
       "playground vite build finished but dist/playground/index.html is missing"
     );
   }
-  logger("[agent-serve] playground build complete");
+  logger("[agentkit] playground build complete");
 }
 
 /**
@@ -149,7 +149,7 @@ export async function ensurePlaygroundBundle(
   }
   if (resolvePlaygroundToolchain() === undefined) {
     logger(
-      "[agent-serve] playground bundle missing and vite toolchain unavailable; /playground will show a build hint"
+      "[agentkit] playground bundle missing and vite toolchain unavailable; /playground will show a build hint"
     );
     return;
   }
@@ -198,32 +198,34 @@ export function startPlaygroundDevServer(options: {
     }
   }
 
-  const modeNote = multiAgent
-    ? " (multi-agent)"
-    : options.basePath
-      ? ` (base ${options.basePath})`
-      : "";
-  logger(
-    `[agent-serve] playground HMR starting on http://127.0.0.1:${port}${modeNote}`
-  );
-
+  // Quiet + isolated from the TTY: the serve banner owns the terminal.
+  // Piped stdio keeps Vite from seeing a TTY (so it cannot clearScreen), and
+  // silent logging drops the "VITE ready" / URL spam. Errors still surface via
+  // spawn/exit handlers below.
   const child = spawn(
     process.execPath,
-    [toolchain.viteCli, "--config", VITE_CONFIG],
+    [toolchain.viteCli, "--config", VITE_CONFIG, "--logLevel", "silent"],
     {
       cwd: toolchain.packageRoot,
       env,
-      stdio: "inherit",
+      stdio: ["ignore", "ignore", "pipe"],
     }
   );
 
+  child.stderr?.on("data", (chunk: Buffer) => {
+    const text = chunk.toString().trimEnd();
+    if (text !== "") {
+      logger(`[agentkit] playground: ${text}`);
+    }
+  });
+
   let stopped = false;
   child.on("error", (err) => {
     if (stopped) {
       return;
     }
     logger(
-      `[agent-serve] playground HMR spawn failed: ${err.message} — static /playground still served when built`
+      `[agentkit] playground spawn failed: ${err.message} — static /playground still served when built`
     );
   });
   child.on("exit", (code, signal) => {
@@ -232,7 +234,7 @@ export function startPlaygroundDevServer(options: {
     }
     if (code !== 0 && code !== null) {
       logger(
-        `[agent-serve] playground HMR exited (code ${code}${
+        `[agentkit] playground exited (code ${code}${
           signal ? `, signal ${signal}` : ""
         }) — static /playground still served when built`
       );