@cursor/july 0.1.40 → 0.1.42

package/src/internal/listen-port.ts

@@ -0,0 +1,85 @@
+/**
+ * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
+ * whatever was requested) is already taken — a common onboarding failure.
+ */
+
+import { once } from "node:events";
+import type { Server } from "node:http";
+import { CLI_COMMAND_NAME } from "./distribution.js";
+
+/** Default listen port for `serve` / `dev` when `--port` is omitted. */
+export const DEFAULT_SERVE_PORT = 3000;
+
+/** How many ports above the default to try when the default is taken. */
+const DEFAULT_PORT_FALLBACK_SPAN = 20;
+
+export function isAddrInUse(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "EADDRINUSE"
+  );
+}
+
+export function formatPortInUseHint(port: number): string {
+  const next = port === 0 ? 3001 : port + 1;
+  return (
+    `port ${port} is already in use. ` +
+    `Try \`${CLI_COMMAND_NAME} dev --port ${next}\` or \`--port 0\` for any free port.`
+  );
+}
+
+/**
+ * `server.listen` with fallback when the caller used the default port.
+ * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
+ */
+export async function listenHttpServer(args: {
+  server: Server;
+  host: string;
+  port: number;
+  /** True when the caller passed `port` (including 0); skip fallback. */
+  portWasExplicit: boolean;
+  logger: (line: string) => void;
+}): Promise<number> {
+  const { server, host, logger } = args;
+  const startPort = args.port;
+  if (args.portWasExplicit || startPort === 0) {
+    try {
+      server.listen(startPort, host);
+      await once(server, "listening");
+    } catch (error) {
+      if (isAddrInUse(error)) {
+        throw new Error(formatPortInUseHint(startPort));
+      }
+      throw error;
+    }
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error("server listening without an address");
+    }
+    return address.port;
+  }
+
+  const last = startPort + DEFAULT_PORT_FALLBACK_SPAN;
+  for (let port = startPort; port <= last; port++) {
+    try {
+      server.listen(port, host);
+      await once(server, "listening");
+      if (port !== startPort) {
+        logger(
+          `[agent-sdk] port ${startPort} in use; listening on ${port} instead (pass --port to pick)`
+        );
+      }
+      return port;
+    } catch (error) {
+      if (!isAddrInUse(error)) {
+        throw error;
+      }
+      if (port === last) {
+        throw new Error(formatPortInUseHint(port));
+      }
+    }
+  }
+  throw new Error(formatPortInUseHint(last));
+}

package/src/internal/playground/static.ts

@@ -1,5 +1,5 @@
 /**
- * Serves the built Vite playground SPA and the multi-agent index page.
+ * Serves the built Vite playground SPA and the host home page.
  *
  * The playground is a Vite + React app (see `playground/`). `serve` auto-builds
  * `dist/playground/` when the local vite toolchain is present (see
@@ -93,33 +93,111 @@ export function renderPlaygroundAsset(file: string): Response {
   });
 }
 
-/** One row on the multi-agent index page. */
+/** Slack surface summary for the host home / `GET /v1/agents`. */
+export type AgentIndexSlack =
+  | { kind: "cursor-account"; handle: string }
+  | { kind: "socket" };
+
+/** One row on the host home page and `GET /v1/agents`. */
 export interface AgentIndexEntry {
   slug: string;
   name: string;
   model: string;
   tools: number;
   channels: number;
+  slack?: AgentIndexSlack;
+}
+
+export interface HostHomeOptions {
+  /** When false, omit `/docs` from the route list. Default true. */
+  docs?: boolean;
+  /** Same as the serve host's `multi` — mounts `/v1/agents` + host `/v1/health`. */
+  multi?: boolean;
 }
 
-/** Standalone index page listing every mounted agent (multi-agent serving). */
-export function renderAgentsIndexHtml(agents: AgentIndexEntry[]): string {
+/**
+ * Orienting `/` page: mounted agents (playground links) plus live host routes.
+ * Used for both single-agent (empty slug) and multi-agent mounts.
+ */
+export function renderAgentsIndexHtml(
+  agents: AgentIndexEntry[],
+  options: HostHomeOptions = {}
+): string {
+  const docs = options.docs !== false;
+  const multi = options.multi === true;
   const cards = agents
     .map((agent) => {
+      const playground =
+        agent.slug === "" ? "/playground" : `/${agent.slug}/playground`;
+      const slugLabel = agent.slug === "" ? "/" : `/${agent.slug}`;
       const meta = `${agent.model || "—"} · ${agent.tools} tool${
         agent.tools === 1 ? "" : "s"
       } · ${agent.channels} channel${agent.channels === 1 ? "" : "s"}`;
-      return `      <a class="card" href="/${escapeHtml(agent.slug)}/playground">
+      return `      <a class="card" href="${escapeHtml(playground)}">
         <div class="card-name">${escapeHtml(agent.name)}</div>
-        <div class="card-slug">/${escapeHtml(agent.slug)}</div>
+        <div class="card-slug">${escapeHtml(slugLabel)} → playground</div>
         <div class="card-meta">${escapeHtml(meta)}</div>
       </a>`;
     })
     .join("\n");
-  return AGENTS_INDEX_TEMPLATE.replace(
+
+  const routes = hostRouteRows(agents, docs, multi)
+    .map(
+      (row) =>
+        `        <tr><td><a href="${escapeHtml(row.href)}"><code>${escapeHtml(row.path)}</code></a></td><td>${escapeHtml(row.blurb)}</td></tr>`
+    )
+    .join("\n");
+
+  return HOST_HOME_TEMPLATE.replace(
     "<!--CARDS-->",
     cards || '      <div class="card-meta">No agents mounted.</div>'
-  ).replace("<!--COUNT-->", String(agents.length));
+  )
+    .replace("<!--COUNT-->", String(agents.length))
+    .replace("<!--ROUTES-->", routes);
+}
+
+function hostRouteRows(
+  agents: AgentIndexEntry[],
+  docs: boolean,
+  multi: boolean
+): Array<{ path: string; href: string; blurb: string }> {
+  const rows: Array<{ path: string; href: string; blurb: string }> = [
+    { path: "/", href: "/", blurb: "This page" },
+  ];
+  for (const agent of agents) {
+    const base = agent.slug === "" ? "" : `/${agent.slug}`;
+    const label = agent.slug === "" ? agent.name : agent.slug;
+    rows.push({
+      path: `${base}/playground`,
+      href: `${base}/playground`,
+      blurb: `Playground — ${label}`,
+    });
+    rows.push({
+      path: `${base}/v1/health`,
+      href: `${base}/v1/health`,
+      blurb: `Health — ${label}`,
+    });
+  }
+  if (multi) {
+    rows.push({
+      path: "/v1/agents",
+      href: "/v1/agents",
+      blurb: "JSON index of mounted agents",
+    });
+    rows.push({
+      path: "/v1/health",
+      href: "/v1/health",
+      blurb: "Host liveness",
+    });
+  }
+  if (docs) {
+    rows.push({
+      path: "/docs",
+      href: "/docs/",
+      blurb: "Agent SDK documentation",
+    });
+  }
+  return rows;
 }
 
 function escapeHtml(value: string): string {
@@ -137,7 +215,7 @@ function fallbackHtml(baseHref: string): string {
     <base href="${escapeHtml(baseHref)}" />
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>agent-serve playground</title>
+    <title>agent-sdk playground</title>
     <style>
       body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
       .box { max-width: 640px; margin: 64px auto; padding: 0 24px; }
@@ -150,7 +228,7 @@ function fallbackHtml(baseHref: string): string {
     <div class="box">
       <h1>Playground bundle not built</h1>
       <p>
-        The Vite playground has not been built yet. <code>agent-serve serve</code>
+        The Vite playground has not been built yet. <code>agent-sdk serve</code>
         auto-builds it when the local vite toolchain is available; otherwise run
         <code>pnpm run build:playground</code> from <code>packages/agent-serve</code>,
         or <code>pnpm run dev:playground</code> for Vite HMR.
@@ -160,33 +238,46 @@ function fallbackHtml(baseHref: string): string {
 </html>`;
 }
 
-const AGENTS_INDEX_TEMPLATE = `<!doctype html>
+const HOST_HOME_TEMPLATE = `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>agent-serve — agents</title>
+    <title>Agent SDK</title>
     <style>
       :root { color-scheme: dark; }
       body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, -apple-system, sans-serif; }
-      .agents-wrap { max-width: 880px; margin: 0 auto; padding: 48px 24px; }
-      .agents-wrap h1 { font-size: 20px; font-weight: 650; margin: 0 0 2px; }
-      .agents-wrap .sub { color: #8b949e; font-size: 13px; margin-bottom: 28px; }
-      .agents-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 14px; }
+      .wrap { max-width: 880px; margin: 0 auto; padding: 48px 24px; }
+      h1 { font-size: 20px; font-weight: 650; margin: 0 0 2px; }
+      h2 { font-size: 13px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; color: #8b949e; margin: 36px 0 12px; }
+      .sub { color: #8b949e; font-size: 13px; margin-bottom: 28px; }
+      .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 14px; }
       .card { display: block; text-decoration: none; color: inherit; background: #161b22; border: 1px solid #30363d; border-radius: 12px; padding: 16px 18px; transition: border-color 0.12s; }
       .card:hover { border-color: #6cb6ff; }
       .card-name { font-size: 15px; font-weight: 600; }
       .card-slug { font-family: ui-monospace, monospace; font-size: 12px; color: #6cb6ff; margin-top: 2px; }
       .card-meta { color: #6e7681; font-size: 12px; margin-top: 10px; }
+      table.routes { width: 100%; border-collapse: collapse; font-size: 13px; }
+      table.routes td { padding: 8px 0; border-bottom: 1px solid #21262d; vertical-align: top; }
+      table.routes td:first-child { width: 42%; padding-right: 16px; }
+      table.routes code { font-family: ui-monospace, monospace; font-size: 12px; color: #6cb6ff; }
+      table.routes a { text-decoration: none; }
+      table.routes a:hover code { text-decoration: underline; }
+      .muted { color: #8b949e; }
     </style>
   </head>
   <body>
-    <div class="agents-wrap">
-      <h1>agent-serve</h1>
-      <div class="sub"><!--COUNT--> agents mounted</div>
-      <div class="agents-grid">
+    <div class="wrap">
+      <h1>Agent SDK</h1>
+      <div class="sub"><!--COUNT--> agent(s) on this host. Open a playground or use a route below.</div>
+      <h2>Agents</h2>
+      <div class="grid">
 <!--CARDS-->
       </div>
+      <h2>Routes</h2>
+      <table class="routes">
+<!--ROUTES-->
+      </table>
     </div>
   </body>
 </html>`;

package/src/internal/sdk-runner.ts

@@ -171,7 +171,17 @@ export class CursorSdkRunner implements AgentRunner {
     const agentPromise = this.getAgent(request);
     try {
       const agent = await agentPromise;
-      const run = await agent.send(request.prompt, {
+      const sendMessage =
+        request.images !== undefined && request.images.length > 0
+          ? {
+              text: request.prompt,
+              images: request.images.map((image) => ({
+                data: image.data,
+                mimeType: image.mimeType,
+              })),
+            }
+          : request.prompt;
+      const run = await agent.send(sendMessage, {
         onDelta: async ({ update }) => {
           try {
             await request.onUpdate(update);

package/src/internal/server.ts

@@ -99,6 +99,7 @@ import {
   requireSessionOwner,
 } from "./http-channel.js";
 import { validateToolInput } from "./json-schema.js";
+import { DEFAULT_SERVE_PORT, listenHttpServer } from "./listen-port.js";
 import {
   createLocalControlPlane,
   type LocalControlPlane,
@@ -592,52 +593,26 @@ export async function startServer(
           })),
         }),
     });
+  }
 
-    if (playground) {
-      const cursorSlackBySlug = new Map(
-        collectCursorSlackTargets(runtimes).map((target) => [
-          target.runtime.slug,
-          target.agentName,
-        ])
-      );
-      const entries: AgentIndexEntry[] = runtimes.map(({ slug, project }) => {
-        const cursorName = cursorSlackBySlug.get(slug);
-        const hasSocketSlack = project.channels.some(
-          (channel) =>
-            channel.definition.meta?.kind === "slack" &&
-            channel.definition.meta?.slackCursorAccount !== true
-        );
-        const slack =
-          cursorName !== undefined
-            ? {
-                kind: "cursor-account" as const,
-                handle: `@Cursor ${cursorName}`,
-              }
-            : hasSocketSlack
-              ? { kind: "socket" as const }
-              : undefined;
-        return {
-          slug,
-          name: project.name,
-          model:
-            typeof project.agent.model === "string"
-              ? project.agent.model
-              : (project.agent.model?.id ?? ""),
-          tools: project.agent.tools.length,
-          channels: project.channels.length + 1,
-          ...(slack !== undefined ? { slack } : {}),
-        };
-      });
-      const indexHtml = renderAgentsIndexHtml(entries);
-      router.add({
-        method: "GET",
-        pattern: "/",
-        auth: "none",
-        handler: () =>
-          new Response(indexHtml, {
-            headers: { "content-type": "text/html; charset=utf-8" },
-          }),
-      });
+  // Orienting `/` for every layout (single empty-slug and multi).
+  // Lists playground links plus live routes (playground, health, docs).
+  if (playground) {
+    const entries = buildAgentIndexEntries(runtimes);
+    const indexHtml = renderAgentsIndexHtml(entries, {
+      docs: docsSite,
+      multi,
+    });
+    router.add({
+      method: "GET",
+      pattern: "/",
+      auth: "none",
+      handler: () =>
+        new Response(indexHtml, {
+          headers: { "content-type": "text/html; charset=utf-8" },
+        }),
+    });
+    if (multi) {
       router.add({
         method: "GET",
         pattern: "/v1/agents",
@@ -725,10 +700,17 @@ export async function startServer(
   });
 
   const host = options.host ?? "127.0.0.1";
-  const port = options.port ?? 3000;
+  const portWasExplicit = options.port !== undefined;
+  const requestedPort = options.port ?? DEFAULT_SERVE_PORT;
+  let boundPort: number;
   try {
-    server.listen(port, host);
-    await once(server, "listening");
+    boundPort = await listenHttpServer({
+      server,
+      host,
+      port: requestedPort,
+      portWasExplicit,
+      logger,
+    });
   } catch (error) {
     await cursorEventRelay?.stop();
     await cursorSlackRelay?.stop();
@@ -737,7 +719,7 @@ export async function startServer(
   }
   const address = server.address() as AddressInfo;
   const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
-  const url = `http://${displayHost}:${address.port}`;
+  const url = `http://${displayHost}:${boundPort}`;
 
   // Resolve peer + Cursor account MCP connections now that the listen port is
   // known (see resolved-connections.ts for the URL/runtime rules).
@@ -1303,18 +1285,6 @@ function mountAgentRoutes(
       auth: "none",
       handler: (_request, ctx) => renderPlaygroundAsset(ctx.params.file ?? ""),
     });
-    if (!multi) {
-      router.add({
-        method: "GET",
-        pattern: "/",
-        auth: "none",
-        handler: () =>
-          new Response(null, {
-            status: 302,
-            headers: { location: "/playground" },
-          }),
-      });
-    }
   }
 
   for (const route of buildHttpChannelRoutes({
@@ -1900,6 +1870,43 @@ function slackAgentNameFromSlug(slug: string): string {
  * resolved. Duplicate names are a startup error — the backend routes
  * `@Cursor <name> …` by name, so two mounts cannot share one.
  */
+function buildAgentIndexEntries(runtimes: MountedRuntime[]): AgentIndexEntry[] {
+  const cursorSlackBySlug = new Map(
+    collectCursorSlackTargets(runtimes).map((target) => [
+      target.runtime.slug,
+      target.agentName,
+    ])
+  );
+  return runtimes.map(({ slug, project }) => {
+    const cursorName = cursorSlackBySlug.get(slug);
+    const hasSocketSlack = project.channels.some(
+      (channel) =>
+        channel.definition.meta?.kind === "slack" &&
+        channel.definition.meta?.slackCursorAccount !== true
+    );
+    const slack =
+      cursorName !== undefined
+        ? {
+            kind: "cursor-account" as const,
+            handle: `@Cursor ${cursorName}`,
+          }
+        : hasSocketSlack
+          ? { kind: "socket" as const }
+          : undefined;
+    return {
+      slug,
+      name: project.name,
+      model:
+        typeof project.agent.model === "string"
+          ? project.agent.model
+          : (project.agent.model?.id ?? ""),
+      tools: project.agent.tools.length,
+      channels: project.channels.length + 1,
+      slack,
+    };
+  });
+}
+
 function collectCursorSlackTargets(
   runtimes: MountedRuntime[]
 ): CursorSlackTarget[] {