@cursor/july 0.1.1

package/src/bin/agent-serve.ts

@@ -0,0 +1,949 @@
+#!/usr/bin/env node
+/**
+ * agent-serve CLI.
+ *
+ *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
+ *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
+ *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
+ *   agent-serve trajectory --events <file.ndjson>
+ *   agent-serve init      [dir]
+ *   agent-serve eval        [--dir .] [evalId...]
+ *   agent-serve validate   [--dir .]
+ *   agent-serve slack     <subcommand>
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import {
+  formatDiagnostics,
+  projectInfo,
+  resolveAgentMounts,
+  serve,
+} from "../index.js";
+import { registerAuthoredModuleLoaders } from "../internal/authored-loaders.js";
+import { runChat } from "../internal/chat-client.js";
+import {
+  type AxCliOptions,
+  cmdCall,
+  cmdEval,
+  cmdInit,
+  cmdRun,
+  cmdTrajectory,
+} from "../internal/cli-ax.js";
+import { CLI_COMMAND_NAME as CLI } from "../internal/distribution.js";
+import { runSession } from "../internal/run-client.js";
+import { formatTrajectoryText } from "../internal/trajectory.js";
+import type { AgentProject, AgentServeHandle } from "../types.js";
+
+const HELP = `${CLI} — serve a filesystem-defined Cursor agent over channels
+
+Usage:
+  ${CLI} serve       [--dir <path>] [--port <n>] [--host <host>] [--dev]
+                          [--mode single|multi] [--api-key <key>] [--no-schedules]
+                          [--public-url <url>]
+                          [--cursor-events --repo <owner/name>]...
+  ${CLI} chat        [--url <baseUrl>] [--message <text>] [--json] [--text]
+  ${CLI} run         [--dir <path>] [--message <text>]... [--url <baseUrl>]
+                          [--session <id>] [--continuation-token <t>]
+                          [--events <file.ndjson>] [--no-events] [--text]
+                          [--timeout-ms <n>] [--no-stream]
+  ${CLI} trajectory  --events <file.ndjson> [--text]
+  ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl>]
+                          [--session <id>] [--slug <slug>]
+  ${CLI} init        [dir]
+  ${CLI} eval        [--dir <path>] [evalId...] [--list] [--json]
+                          [--tag <tag>]... [--verbose] [--timeout-ms <n>]
+                          [--no-stream]
+  ${CLI} info        [--dir <path>] [--json]
+  ${CLI} validate    [--dir <path>]
+  ${CLI} login       [--api-key <key>] [--key-name <name>]
+  ${CLI} logout
+  ${CLI} whoami      [--json]
+  ${CLI} slack       <subcommand> …
+  ${CLI} github      <subcommand> …
+
+Commands:
+  serve       Serve agents under /<slug>/... (index at /). On a TTY, press
+              Enter to restart (reloads agent code + Vite HMR child).
+  chat        Talk to a running server (streams the reply). --json prints a trajectory.
+  run         One-shot create→test loop: ephemeral server + JSON trajectory.
+              Writes a single events.ndjson trace (visualize in the playground).
+              Streams tool calls and reply text to stderr when stderr is a TTY.
+  trajectory  Summarize an events.ndjson file into a trajectory.
+  call        Call an authored server tool deterministically (no model turn)
+              via POST /v1/tools/:toolName. --session runs it inside an
+              existing session and records it on that session's event stream.
+  init        Scaffold a project, or print the coding-agent setup guide (no args).
+  eval        Run filesystem evals under evals/**/*.eval.ts (streams on a TTY).
+              Pass evalId args to select: one datapoint (weather/nyc), a whole
+              file (weather → all cases in that file), several of either, or
+              omit to run all.
+  info        Print the discovered agent surface (tools, skills, channels, ...).
+  validate    Check the project(s) and exit non-zero on error diagnostics.
+  login       Sign the host in to Cursor: browser sign-in mints a named,
+              dashboard-revocable API key (only the key is stored). It powers
+              inference, cloud runtime, and cursorAccount MCP connections.
+  logout      Remove the stored Cursor credentials.
+  whoami      Show which Cursor account powers this host (and why).
+  slack       Slack channel pack: init, manifests, doctor (see slack help).
+  github      GitHub webhook pack: forward live deliveries, events, doctor
+              (wraps \`gh webhook forward\`; see github help).
+
+Agent loop:
+  ${CLI} validate --dir .
+  ${CLI} info --dir . --json
+  ${CLI} run --dir . --message "..."
+  ${CLI} eval --dir .
+
+Options:
+  --dir             Project root (defaults to the current directory).
+  --port             Port to listen on (default 3000).
+  --host             Host to bind (default 127.0.0.1).
+  --mode             serve: "multi" (default, slugged /<dir>/v1/*) or "single"
+                     (unslugged /v1/*). Multi also exposes host /v1/health for
+                     ALB/ECS checks; use single when one agent is the whole host.
+  --dev              Dev mode: mounts POST /v1/dev/schedules/:scheduleId and
+                     disables the cron runner (dispatch schedules by hand).
+  --api-key          Cursor API key (defaults to CURSOR_API_KEY, then the
+                     stored \`${CLI} login\` credential).
+  --key-name         login: label for the minted API key (defaults to
+                     "${CLI} (<hostname>)").
+  --state-root       Durable state directory (default <dir>/.agent-serve). Put it
+                     outside any repository whose rules should not reach the agent.
+  --bearer-token     serve: require this bearer token on API routes. chat/run/eval:
+                     send it as the Authorization bearer.
+  --allow-anonymous  serve: admit all HTTP callers (allowAll). For demos behind a
+                     trusted network only; mutually exclusive with --bearer-token.
+  --public-url       serve: base URL where this host is reachable from outside
+                     (e.g. https://agent-serve.example.com). Required for peer
+                     connections (defineConnection({ agent })) on cloud-runtime
+                     turns; local turns always use loopback.
+  --no-schedules     Disable the cron runner outside dev mode.
+  --no-playground    Disable the bundled web playground at /playground (also skips
+                     auto-build / HMR).
+  --no-docs          Disable the documentation site at /docs (also skips its
+                     auto-build).
+  --url              chat/run/eval: base URL of a running agent (skip local host).
+  --message          chat/run: user message (repeatable for run).
+  --input            call: JSON object of tool arguments (default {}).
+  --messages-file   JSON array of strings (run).
+  --session          Existing session id for a follow-up turn.
+  --continuation-token  Token from a prior run/chat response.
+  --events           run: write NDJSON trace to this path (default
+                     <dir>/.agent-serve/traces/<sessionId>.ndjson).
+                     trajectory: read this file.
+  --no-events        run: do not write a trace file.
+  --slug             Agent slug when --dir mounts multiple agents.
+  --timeout-ms       Abort a hung turn after N milliseconds.
+  --tag              eval: only run cases with this tag (repeatable).
+  --list             eval: print discovered cases without running.
+  --verbose          eval: stream t.log lines and reply snippets.
+  --no-stream        run/eval: silence live progress on stderr (JSON still prints).
+  --json             JSON output (info/chat/eval/github; run defaults to JSON).
+  --no-color         chat: force plain output.
+  --cursor-events    serve: pull SCM webhook events from /v0/scm-events. The
+                     stream is read as your Cursor user, so serve requires
+                     sign-in (\`${CLI} login\` / CURSOR_API_KEY) and --repo.
+                     Offset under <state-root>/cursor-events/.
+                     CURSOR_API_BASE_URL overrides.
+  --repo             serve --cursor-events: repo to subscribe to (repeatable).
+                     github forward: owner/repo to forward from (inferred from
+                     the git remote when omitted; last wins).
+  --org              github forward: organization login (org-level hooks).
+  --channel          github: select one channel id when several are declared.
+  --secret           github forward: webhook signing secret (defaults to
+                     GITHUB_WEBHOOK_SECRET). github: --events overrides the
+                     derived webhook event list.
+  --install          github: install the cli/gh-webhook extension if missing.
+  --action           github replay: event action (e.g. opened, synchronize).
+  --conclusion       github replay: CI conclusion (check_run/suite/status).
+  --comment          github replay: comment body for comment events.
+  --context          github replay: commit-status context.
+  --dry-run          github replay: print synthesized payloads, don't POST.
+  --out              github replay: write synthesized payloads as fixtures.
+`;
+
+async function main(argv: string[]): Promise<number> {
+  const [command, ...rest] = argv;
+  if (
+    command === undefined ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    process.stdout.write(HELP);
+    return command === undefined ? 1 : 0;
+  }
+
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      dir: { type: "string", default: "." },
+      port: { type: "string" },
+      host: { type: "string" },
+      mode: { type: "string" },
+      dev: { type: "boolean", default: false },
+      "api-key": { type: "string" },
+      "key-name": { type: "string" },
+      "state-root": { type: "string" },
+      "bearer-token": { type: "string" },
+      "allow-anonymous": { type: "boolean", default: false },
+      "no-schedules": { type: "boolean", default: false },
+      "no-playground": { type: "boolean", default: false },
+      "no-docs": { type: "boolean", default: false },
+      url: { type: "string" },
+      message: { type: "string", multiple: true },
+      input: { type: "string" },
+      "messages-file": { type: "string" },
+      "session-id": { type: "string" },
+      session: { type: "string" },
+      "continuation-token": { type: "string" },
+      events: { type: "string" },
+      "no-events": { type: "boolean", default: false },
+      slug: { type: "string" },
+      "timeout-ms": { type: "string" },
+      tag: { type: "string", multiple: true },
+      list: { type: "boolean", default: false },
+      verbose: { type: "boolean", default: false },
+      text: { type: "boolean", default: false },
+      "no-color": { type: "boolean", default: false },
+      "no-stream": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      name: { type: "string" },
+      env: { type: "string" },
+      "public-url": { type: "string" },
+      "mount-path": { type: "string" },
+      "base-url": { type: "string" },
+      print: { type: "boolean", default: false },
+      transport: { type: "string" },
+      prefix: { type: "string" },
+      "no-prefix": { type: "boolean", default: false },
+      "channel-posts": { type: "boolean", default: false },
+      repo: { type: "string", multiple: true },
+      org: { type: "string" },
+      "cursor-events": { type: "boolean", default: false },
+      secret: { type: "string" },
+      channel: { type: "string" },
+      install: { type: "boolean", default: false },
+      action: { type: "string" },
+      conclusion: { type: "string" },
+      context: { type: "string" },
+      comment: { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+      out: { type: "string" },
+    },
+  });
+  const dir = values.dir ?? ".";
+
+  switch (command) {
+    case "slack": {
+      const { cmdSlack } = await import("../internal/cli-slack.js");
+      const env =
+        values.env === "dev" || values.env === "prod" || values.env === "both"
+          ? values.env
+          : undefined;
+      return cmdSlack(positionals[0], {
+        dir,
+        name: values.name,
+        env,
+        json: values.json,
+        print: values.print,
+        prefix: values.prefix,
+        noPrefix: values["no-prefix"],
+        channelPosts: values["channel-posts"],
+      });
+    }
+    case "github": {
+      const port =
+        values.port === undefined
+          ? undefined
+          : Number.parseInt(values.port, 10);
+      if (
+        port !== undefined &&
+        (Number.isNaN(port) || port < 0 || port > 65535)
+      ) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdGithub } = await import("../internal/cli-github.js");
+      return cmdGithub(positionals[0], {
+        dir,
+        slug: values.slug,
+        channel: values.channel,
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        // `--repo` is repeatable for `serve --cursor-events`; the github
+        // subcommands target a single repo, so the last one wins.
+        repo: values.repo?.at(-1),
+        org: values.org,
+        secret: values.secret,
+        install: values.install,
+        json: values.json,
+        prUrl: positionals[1],
+        action: values.action,
+        conclusion: values.conclusion,
+        context: values.context,
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
+    case "init": {
+      return cmdInit({
+        dir,
+        initTarget: positionals[0],
+      });
+    }
+
+    case "login": {
+      const { cmdLogin } = await import("../internal/cli-cursor.js");
+      return cmdLogin({
+        apiKey: values["api-key"],
+        keyName: values["key-name"],
+      });
+    }
+
+    case "logout": {
+      const { cmdLogout } = await import("../internal/cli-cursor.js");
+      return cmdLogout();
+    }
+
+    case "whoami": {
+      const { cmdWhoami } = await import("../internal/cli-cursor.js");
+      return cmdWhoami({ json: values.json });
+    }
+
+    case "run": {
+      const messages = await loadMessages(
+        values.message,
+        values["messages-file"]
+      );
+      return cmdRun(
+        axFromOptions({
+          dir,
+          messages,
+          sessionId: values["session-id"] ?? values.session,
+          continuationToken: values["continuation-token"],
+          events: values["no-events"]
+            ? false
+            : values.events === undefined
+              ? true
+              : values.events,
+          text: values.text,
+          url: values.url,
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+          timeoutMs: parseTimeoutMs(values["timeout-ms"]),
+          stream: values["no-stream"] ? false : undefined,
+        })
+      );
+    }
+
+    case "call": {
+      return cmdCall(
+        axFromOptions({
+          dir,
+          toolName: positionals[0],
+          toolInput: values.input,
+          sessionId: values["session-id"] ?? values.session,
+          url: values.url,
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+        })
+      );
+    }
+
+    case "trajectory": {
+      if (values.events === undefined) {
+        process.stderr.write("trajectory requires --events <file.ndjson>\n");
+        return 1;
+      }
+      return cmdTrajectory(
+        axFromOptions({
+          dir,
+          events: values.events,
+          text: values.text,
+        })
+      );
+    }
+
+    case "eval": {
+      return cmdEval(
+        axFromOptions({
+          dir,
+          evalIds: positionals,
+          list: values.list,
+          verbose: values.verbose,
+          json: values.json,
+          tags: values.tag,
+          url: values.url,
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+          timeoutMs: parseTimeoutMs(values["timeout-ms"]),
+          stream: values["no-stream"] ? false : undefined,
+        })
+      );
+    }
+
+    case "chat": {
+      if (values.json) {
+        return chatJson({
+          baseUrl: values.url ?? "http://127.0.0.1:3000",
+          message: (values.message as string[] | undefined)?.[0],
+          bearerToken: values["bearer-token"],
+          text: values.text,
+        });
+      }
+      await runChat({
+        baseUrl: values.url ?? "http://127.0.0.1:3000",
+        ...((values.message as string[] | undefined)?.[0] === undefined
+          ? {}
+          : { message: (values.message as string[])[0]! }),
+        ...(values["bearer-token"] === undefined
+          ? {}
+          : { bearerToken: values["bearer-token"] }),
+        ...(values["no-color"] ? { noColor: true } : {}),
+      });
+      return 0;
+    }
+
+    case "validate": {
+      const mounts = await loadMounts(dir);
+      let hasError = false;
+      for (const { slug, project } of mounts) {
+        const label = slug === "" ? project.name : `${slug} (${project.name})`;
+        if (project.diagnostics.length === 0) {
+          process.stdout.write(`ok: ${label} has no diagnostics\n`);
+          continue;
+        }
+        process.stdout.write(
+          `${label}:\n${formatDiagnostics(project.diagnostics)}\n`
+        );
+        hasError ||= project.diagnostics.some((d) => d.severity === "error");
+      }
+      return hasError ? 1 : 0;
+    }
+
+    case "info": {
+      const mounts = await loadMounts(dir);
+      if (values.json) {
+        const payload =
+          mounts.length === 1 && mounts[0]?.slug === ""
+            ? projectInfo(mounts[0].project)
+            : {
+                agents: mounts.map(({ slug, project }) => ({
+                  slug,
+                  ...projectInfo(project),
+                })),
+              };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+      }
+      if (mounts.length > 1 || mounts[0]?.slug !== "") {
+        process.stdout.write(`${mounts.length} agents under ${dir}:\n\n`);
+        for (const { slug, project } of mounts) {
+          const info = projectInfo(project);
+          process.stdout.write(
+            `  /${slug}  —  ${info.name}  (${formatModel(info.model)}, ${info.tools.length} tools, ${info.channels.length} channels)\n`
+          );
+        }
+        const anyError = mounts.some((m) =>
+          m.project.diagnostics.some((d) => d.severity === "error")
+        );
+        return anyError ? 1 : 0;
+      }
+      const project = mounts[0]?.project as AgentProject;
+      const info = projectInfo(project);
+      const lines: string[] = [];
+      lines.push(`agent: ${info.name}`);
+      lines.push(`model: ${formatModel(info.model)}`);
+      lines.push(`mcp: ${info.mcp.path} (${info.mcp.tools.join(", ")})`);
+      if (info.instructions !== undefined) {
+        lines.push(`instructions: ${info.instructions.chars} chars`);
+      }
+      lines.push(
+        section(
+          "tools",
+          info.tools.map((t) => `${t.name} — ${t.description}`)
+        )
+      );
+      lines.push(
+        section(
+          "skills",
+          info.skills.map((s) => `${s.name} — ${s.description}`)
+        )
+      );
+      lines.push(
+        section(
+          "MCP connections",
+          info.connections.map((c) => `${c.name} — ${c.transport}`)
+        )
+      );
+      lines.push(
+        section(
+          "subagents",
+          info.subagents.map((s) => `${s.name} — ${s.description ?? ""}`)
+        )
+      );
+      lines.push(
+        section(
+          "channels",
+          info.channels.map(
+            (c) =>
+              `${c.id}: ${
+                c.routes.map((r) => `${r.method} ${r.url}`).join(", ") ||
+                "(events only)"
+              }`
+          )
+        )
+      );
+      lines.push(
+        section(
+          "schedules",
+          info.schedules.map((s) => `${s.name} (${s.cron}, ${s.kind})`)
+        )
+      );
+      lines.push(section("hooks", info.hooks));
+      if (info.diagnostics.length > 0) {
+        lines.push(`\ndiagnostics:\n${formatDiagnostics(info.diagnostics)}`);
+      }
+      process.stdout.write(
+        `${lines.filter((line) => line !== "").join("\n")}\n`
+      );
+      return info.diagnostics.some((d) => d.severity === "error") ? 1 : 0;
+    }
+
+    case "serve": {
+      const port =
+        values.port === undefined ? 3000 : Number.parseInt(values.port, 10);
+      if (Number.isNaN(port) || port < 0 || port > 65535) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      if (
+        values["allow-anonymous"] === true &&
+        values["bearer-token"] !== undefined
+      ) {
+        process.stderr.write(
+          "--allow-anonymous and --bearer-token are mutually exclusive\n"
+        );
+        return 1;
+      }
+      const mode = values.mode;
+      if (mode !== undefined && mode !== "single" && mode !== "multi") {
+        process.stderr.write(
+          `invalid --mode: ${mode} (expected "single" or "multi")\n`
+        );
+        return 1;
+      }
+      const serveOptions = {
+        port,
+        ...(values.host === undefined ? {} : { host: values.host }),
+        ...(mode === undefined ? {} : { mode: mode as "single" | "multi" }),
+        dev: values.dev,
+        ...(values["api-key"] === undefined
+          ? {}
+          : { apiKey: values["api-key"] }),
+        ...(values["state-root"] === undefined
+          ? {}
+          : { stateRoot: values["state-root"] }),
+        ...(values["bearer-token"] === undefined
+          ? {}
+          : { authToken: values["bearer-token"] }),
+        ...(values["allow-anonymous"] ? { allowAnonymous: true } : {}),
+        ...(values["no-schedules"] ? { schedules: false } : {}),
+        ...(values["no-playground"] ? { playground: false } : {}),
+        ...(values["no-docs"] ? { docs: false } : {}),
+        ...(values["public-url"] === undefined
+          ? {}
+          : { publicUrl: values["public-url"] }),
+        ...(values["cursor-events"]
+          ? { cursorEvents: { repos: values.repo ?? [] } }
+          : {}),
+      };
+      const enterToRestart = process.stdin.isTTY === true;
+      const bannerOpts = {
+        noPlayground: values["no-playground"] === true,
+        dev: values.dev === true,
+        bearerToken: values["bearer-token"] !== undefined,
+        noSchedules: values["no-schedules"] === true,
+      };
+
+      const start = async (): Promise<AgentServeHandle> => {
+        const next = await serve(dir, serveOptions);
+        printServeBanner(next, bannerOpts);
+        if (enterToRestart) {
+          process.stdout.write("  press Enter to restart\n");
+        }
+        return next;
+      };
+
+      let handle = await start();
+      let closing = false;
+      let restarting = false;
+
+      await new Promise<void>((resolve) => {
+        const shutdown = (): void => {
+          if (closing) {
+            return;
+          }
+          closing = true;
+          process.stdout.write("\nshutting down (draining running turns)\n");
+          void handle.close().finally(resolve);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+
+        if (!enterToRestart) {
+          return;
+        }
+
+        process.stdin.resume();
+        process.stdin.on("data", (chunk: string | Buffer) => {
+          const text =
+            typeof chunk === "string" ? chunk : chunk.toString("utf8");
+          if (!isEnterOnly(text) || closing || restarting) {
+            return;
+          }
+          restarting = true;
+          process.stdout.write("\nrestarting…\n");
+          void handle
+            .close()
+            .then(start)
+            .then((next) => {
+              handle = next;
+            })
+            .catch((error: unknown) => {
+              process.stderr.write(
+                `[agent-serve] restart failed: ${
+                  error instanceof Error
+                    ? (error.stack ?? error.message)
+                    : String(error)
+                }\n`
+              );
+              closing = true;
+              resolve();
+            })
+            .finally(() => {
+              restarting = false;
+            });
+        });
+      });
+      return 0;
+    }
+
+    default: {
+      process.stderr.write(`Unknown command "${command}"\n\n${HELP}`);
+      return 1;
+    }
+  }
+}
+
+function axFromOptions(
+  partial: Partial<AxCliOptions> & { dir: string }
+): AxCliOptions {
+  return {
+    dir: partial.dir,
+    ...(partial.cwd === undefined ? {} : { cwd: partial.cwd }),
+    ...(partial.slug === undefined ? {} : { slug: partial.slug }),
+    ...(partial.bearerToken === undefined
+      ? {}
+      : { bearerToken: partial.bearerToken }),
+    ...(partial.stateRoot === undefined
+      ? {}
+      : { stateRoot: partial.stateRoot }),
+    ...(partial.messages === undefined ? {} : { messages: partial.messages }),
+    ...(partial.sessionId === undefined
+      ? {}
+      : { sessionId: partial.sessionId }),
+    ...(partial.continuationToken === undefined
+      ? {}
+      : { continuationToken: partial.continuationToken }),
+    ...(partial.timeoutMs === undefined
+      ? {}
+      : { timeoutMs: partial.timeoutMs }),
+    ...(partial.events === undefined ? {} : { events: partial.events }),
+    ...(partial.text === undefined ? {} : { text: partial.text }),
+    ...(partial.json === undefined ? {} : { json: partial.json }),
+    ...(partial.list === undefined ? {} : { list: partial.list }),
+    ...(partial.verbose === undefined ? {} : { verbose: partial.verbose }),
+    ...(partial.tags === undefined ? {} : { tags: partial.tags }),
+    ...(partial.evalIds === undefined ? {} : { evalIds: partial.evalIds }),
+    ...(partial.initTarget === undefined
+      ? {}
+      : { initTarget: partial.initTarget }),
+    ...(partial.toolName === undefined ? {} : { toolName: partial.toolName }),
+    ...(partial.toolInput === undefined
+      ? {}
+      : { toolInput: partial.toolInput }),
+    ...(partial.url === undefined ? {} : { url: partial.url }),
+    ...(partial.stream === undefined ? {} : { stream: partial.stream }),
+  };
+}
+
+async function loadMessages(
+  messages: string[] | undefined,
+  messagesFile: string | undefined
+): Promise<string[]> {
+  const out: string[] = [];
+  if (messagesFile !== undefined) {
+    const raw = await readFile(resolve(messagesFile), "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      throw new Error("--messages-file must be a JSON array of strings");
+    }
+    for (const item of parsed) {
+      if (typeof item !== "string") {
+        throw new Error("--messages-file entries must be strings");
+      }
+      out.push(item);
+    }
+  }
+  if (messages !== undefined) {
+    out.push(...messages);
+  }
+  return out;
+}
+
+function parseTimeoutMs(value: string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const n = Number.parseInt(value, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new Error(`invalid --timeout-ms: ${value}`);
+  }
+  return n;
+}
+
+async function chatJson(args: {
+  baseUrl: string;
+  message?: string;
+  bearerToken?: string;
+  text?: boolean;
+}): Promise<number> {
+  if (args.message === undefined) {
+    process.stderr.write("chat --json requires --message\n");
+    return 2;
+  }
+  const result = await runSession({
+    baseUrl: args.baseUrl,
+    messages: [args.message],
+    ...(args.bearerToken === undefined
+      ? {}
+      : { bearerToken: args.bearerToken }),
+  });
+  if (args.text) {
+    process.stdout.write(formatTrajectoryText(result.trajectory));
+  } else {
+    console.log(
+      JSON.stringify(
+        {
+          ok: result.ok,
+          sessionId: result.sessionId,
+          continuationToken: result.continuationToken ?? null,
+          trajectory: result.trajectory,
+        },
+        null,
+        2
+      )
+    );
+  }
+  return result.ok ? 0 : 1;
+}
+
+/**
+ * Load mounts the same way `serve` does (multi-agent layout by default).
+ */
+async function loadMounts(
+  dir: string
+): Promise<Array<{ slug: string; project: AgentProject }>> {
+  return resolveAgentMounts(dir);
+}
+
+function section(title: string, items: string[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+  return `${title}:\n${items.map((item) => `  - ${item}`).join("\n")}`;
+}
+
+function isEnterOnly(text: string): boolean {
+  return text.length > 0 && [...text].every((ch) => ch === "\n" || ch === "\r");
+}
+
+function printServeBanner(
+  handle: AgentServeHandle,
+  opts: {
+    noPlayground: boolean;
+    dev: boolean;
+    bearerToken: boolean;
+    noSchedules: boolean;
+  }
+): void {
+  const multi = handle.agents.length > 1 || handle.agents[0]?.slug !== "";
+  if (multi) {
+    process.stdout.write(
+      `${handle.agents.length} agents listening on ${handle.url}\n`
+    );
+    if (!opts.noPlayground) {
+      process.stdout.write(`  index: ${handle.url}/\n`);
+    }
+    for (const agent of handle.agents) {
+      const info = projectInfo(agent.project);
+      const suffix = opts.noPlayground
+        ? `${agent.url}/v1/session`
+        : `${agent.url}/playground`;
+      process.stdout.write(`  /${agent.slug}  ${info.name} — ${suffix}\n`);
+    }
+  } else {
+    const info = projectInfo(handle.project);
+    process.stdout.write(`${info.name} listening on ${handle.url}\n`);
+    if (!opts.noPlayground) {
+      process.stdout.write(`  playground: ${handle.url}/playground\n`);
+    }
+    process.stdout.write(`  POST ${handle.url}/v1/session\n`);
+    process.stdout.write(`  GET  ${handle.url}/v1/session/:sessionId/stream\n`);
+    for (const channel of info.channels) {
+      if (channel.id === "http") {
+        continue;
+      }
+      for (const route of channel.routes) {
+        process.stdout.write(`  ${route.method} ${handle.url}${route.url}\n`);
+      }
+    }
+    if (info.schedules.length > 0) {
+      const scheduleMode = opts.dev
+        ? "dev mode: dispatch with POST /v1/dev/schedules/:scheduleId"
+        : opts.noSchedules
+          ? "disabled"
+          : "running on cron cadence (UTC)";
+      process.stdout.write(
+        `  schedules: ${info.schedules.map((s) => s.name).join(", ")} — ${scheduleMode}\n`
+      );
+    }
+  }
+  if (handle.playgroundDevUrl !== undefined) {
+    process.stdout.write(`  playground (HMR): ${handle.playgroundDevUrl}\n`);
+  }
+  if (handle.docsUrl !== undefined) {
+    process.stdout.write(`  docs: ${handle.docsUrl}\n`);
+  }
+  if (opts.bearerToken) {
+    process.stdout.write(
+      "  auth: bearer token required on API routes (playground has a token field)\n"
+    );
+  }
+  if (
+    opts.dev &&
+    (process.env.GITHUB_WEBHOOK_SECRET === undefined ||
+      process.env.GITHUB_WEBHOOK_SECRET === "") &&
+    handle.agents.some((agent) =>
+      projectInfo(agent.project).channels.some((c) => c.kind === "github")
+    )
+  ) {
+    process.stdout.write(
+      `  github: dev accepts unsigned loopback deliveries (${CLI} github forward works without a secret; set GITHUB_WEBHOOK_SECRET to verify signatures)\n`
+    );
+  }
+}
+
+function formatModel(model: unknown): string {
+  if (model === undefined) {
+    return "(unset)";
+  }
+  if (typeof model === "string") {
+    return model;
+  }
+  return JSON.stringify(model);
+}
+
+/**
+ * The Cursor SDK's Connect/HTTP2 client sometimes emits uncaught stream
+ * or TLS errors (notably `NGHTTP2_FRAME_SIZE_ERROR` on large shell/tool
+ * payloads, and mid-handshake socket disconnects) outside the promise
+ * `run.wait()` returns. Without a listener the unhandled rejection exits
+ * the whole agent-serve process with code 1. Swallow those transport
+ * failures so turns can fail cleanly and the server stays up.
+ */
+function installTransportErrorGuards(): void {
+  const isTransportNoise = (reason: unknown): boolean => {
+    const message =
+      reason instanceof Error
+        ? `${reason.message}\n${reason.stack ?? ""}`
+        : String(reason);
+    const code =
+      reason !== null &&
+      typeof reason === "object" &&
+      "code" in reason &&
+      typeof (reason as { code: unknown }).code === "string"
+        ? (reason as { code: string }).code
+        : undefined;
+    return (
+      code === "ERR_HTTP2_STREAM_ERROR" ||
+      code === "ECONNRESET" ||
+      code === "ECONNREFUSED" ||
+      code === "EPIPE" ||
+      code === "ETIMEDOUT" ||
+      code === "ENOTFOUND" ||
+      code === "EAI_AGAIN" ||
+      message.includes("NGHTTP2_FRAME_SIZE_ERROR") ||
+      message.includes("Stream closed with error code") ||
+      message.includes(
+        "Client network socket disconnected before secure TLS connection was established"
+      ) ||
+      message.includes("socket hang up") ||
+      message.includes("other side closed")
+    );
+  };
+  const log = (label: string, reason: unknown): void => {
+    const text = reason instanceof Error ? reason.message : String(reason);
+    process.stderr.write(
+      `[agent-serve] ${label} (server stays up): ${text.slice(0, 400)}\n`
+    );
+  };
+  process.on("unhandledRejection", (reason) => {
+    if (isTransportNoise(reason)) {
+      log("swallowed unhandledRejection", reason);
+      return;
+    }
+    log("unhandledRejection", reason);
+  });
+  process.on("uncaughtException", (error) => {
+    if (isTransportNoise(error)) {
+      log("swallowed uncaughtException", error);
+      return;
+    }
+    process.stderr.write(
+      `[agent-serve] uncaughtException: ${error.stack ?? error.message}\n`
+    );
+    process.exit(1);
+  });
+}
+
+installTransportErrorGuards();
+
+// Authored agent files are TypeScript imported at runtime; install the tsx
+// loader (and the framework import aliases on compiled runs) before any
+// command touches a project.
+registerAuthoredModuleLoaders()
+  .then(() => main(process.argv.slice(2)))
+  .then(
+    (code) => {
+      // Ephemeral run/eval can leave SDK/HTTP handles open; force exit.
+      process.exit(code);
+    },
+    (error) => {
+      process.stderr.write(
+        `${error instanceof Error ? error.message : String(error)}\n`
+      );
+      process.exit(1);
+    }
+  );