premanmcp 1.1.4 → 1.1.6

package/bin/agent_dialects.js

@@ -0,0 +1,385 @@
+/**
+ * Talking to an agent PreMan did not write.
+ *
+ * Everything else in the eval path assumes the agent under test speaks one
+ * shape: `POST {"message","history"}` answered with `{"response"}`. That is
+ * PreMan's own workbench, and no customer's agent speaks it. Their agent is a
+ * LangGraph app on `/invoke`, an OpenAI-compatible route on
+ * `/v1/chat/completions`, a Next.js handler on `/api/chat`, or a Flask function
+ * somebody wrote on a Tuesday — and asking a developer which of those they have
+ * is asking them to answer a question their own code already answers.
+ *
+ * So this module asks the agent instead. It is deliberately a *probe* rather
+ * than a framework detector: reading a repository tells you what was imported,
+ * while a request tells you what actually answers, and those differ the moment
+ * anything sits in front of the app. One harmless message, a small table of
+ * shapes, and the first one that produces text wins.
+ *
+ * Two things bound it, because this runs against a developer's machine and a
+ * discovery pass that hangs is worse than one that finds nothing: every attempt
+ * has its own timeout, and the whole sweep stops at `MAX_ATTEMPTS`.
+ *
+ * What it cannot do is invent visibility. If an agent answers with prose and
+ * nothing else, the transcript a judge reads has no tool calls in it, and the
+ * honest report is that the flow was measured without them -- see
+ * `toolEventsFrom` for the shapes that do carry them.
+ */
+
+/** Per request. Long enough for a cold model call, short enough to sweep. */
+export const PROBE_TIMEOUT_MS = 12_000;
+
+/** A turn during a real run, where a slow answer is the agent thinking. */
+export const TURN_TIMEOUT_MS = 120_000;
+
+/** The whole sweep, so an agent that 200s everything cannot run forever. */
+export const MAX_ATTEMPTS = 40;
+
+/**
+ * What the probe says.
+ *
+ * It names itself and asks for nothing, because it is a real message to
+ * somebody's real agent: it may be logged, it may be answered by a model that
+ * costs money, and it may end up in a customer-facing transcript if the agent
+ * under test is wired to one. "Hello" would be cheaper to type and worse to
+ * find in a support queue.
+ */
+export const PROBE_MESSAGE =
+  "This is PreMan checking that it can reach this agent. No action needed — please reply briefly.";
+
+/** Where a chat agent usually listens, most specific first. */
+export const PROBE_PATHS = [
+  "/chat",
+  "/api/chat",
+  "/v1/chat/completions",
+  "/chat/completions",
+  "/invoke",
+  "/agent",
+  "/api/agent",
+  "/message",
+  "/query",
+  "/",
+];
+
+const asText = (value) => (typeof value === "string" && value.trim() ? value : "");
+
+/**
+ * The shortest thing the plain-text dialect will believe is an answer.
+ *
+ * An agent asked a full sentence answers with one. `OK`, `healthy` and `pong`
+ * are the other things that answer a POST with 200 and plain text, and every
+ * one of them is a health check.
+ */
+const MIN_PROSE = 24;
+
+const looksLikeMarkup = (value) => /^\s*<(!doctype|html|\?xml|svg)/i.test(String(value || ""));
+
+/** The first field of a set that carries text, whatever the shape called it. */
+function firstText(body, keys) {
+  if (typeof body === "string") return asText(body);
+  if (!body || typeof body !== "object") return "";
+  for (const key of keys) {
+    const found = asText(body[key]);
+    if (found) return found;
+  }
+  return "";
+}
+
+/**
+ * The shapes, in the order they are tried.
+ *
+ * Ordered by how specific the answer is rather than by popularity: a route that
+ * answers an OpenAI-shaped request with an OpenAI-shaped body has told you what
+ * it is, while `{"message": …}` → `{"response": …}` is a shape half the
+ * internet uses for half a dozen different things. Being wrong about the
+ * dialect is cheap here (the turn produces no text and the sweep moves on) and
+ * expensive later (a run that measures an agent's error handler), so the
+ * specific ones go first.
+ */
+export const DIALECTS = [
+  {
+    name: "openai-chat",
+    summary: "OpenAI-compatible chat completions",
+    body: (message, history) => ({
+      model: "preman-eval",
+      stream: false,
+      messages: [
+        ...history.map((turn) => ({
+          role: turn.role === "assistant" ? "assistant" : "user",
+          content: String(turn.content ?? ""),
+        })),
+        { role: "user", content: message },
+      ],
+    }),
+    read: (body) => {
+      const choice = body?.choices?.[0]?.message;
+      return { text: asText(choice?.content), calls: choice?.tool_calls };
+    },
+  },
+  {
+    name: "langserve",
+    summary: "LangServe / LangGraph invoke",
+    body: (message, history) => ({
+      input: { input: message, messages: history, chat_history: history },
+    }),
+    read: (body) => {
+      const output = body?.output ?? body?.result;
+      const text =
+        firstText(output, ["output", "content", "answer", "text", "response"]) ||
+        asText(output) ||
+        firstText(body, ["output", "content", "answer", "text"]);
+      return {
+        text,
+        calls: body?.intermediate_steps || output?.intermediate_steps || output?.tool_calls,
+      };
+    },
+  },
+  {
+    name: "messages",
+    summary: "a messages array, answered with a message",
+    body: (message, history) => ({
+      messages: [
+        ...history.map((turn) => ({
+          role: turn.role === "assistant" ? "assistant" : "user",
+          content: String(turn.content ?? ""),
+        })),
+        { role: "user", content: message },
+      ],
+    }),
+    read: (body) => {
+      const last = Array.isArray(body?.messages) ? body.messages[body.messages.length - 1] : null;
+      return {
+        text:
+          firstText(body, ["response", "reply", "output", "answer", "content", "text", "message"]) ||
+          asText(last?.content),
+        calls: body?.tool_calls || last?.tool_calls || body?.steps || body?.events,
+      };
+    },
+  },
+  {
+    name: "message",
+    summary: "a message and a history, answered with text",
+    body: (message, history) => ({ message, history }),
+    read: readLoosely,
+  },
+  {
+    name: "input",
+    summary: "an input field, answered with text",
+    body: (message) => ({ input: message }),
+    read: readLoosely,
+  },
+  {
+    name: "query",
+    summary: "a query field, answered with text",
+    body: (message) => ({ query: message }),
+    read: readLoosely,
+  },
+  {
+    name: "prompt",
+    summary: "a prompt field, answered with text",
+    body: (message) => ({ prompt: message }),
+    read: readLoosely,
+  },
+  {
+    name: "text",
+    summary: "plain text in, plain text out",
+    contentType: "text/plain",
+    body: (message) => message,
+    // The greediest dialect, and therefore the most guarded. A body that parses
+    // is a structured answer this one cannot read; markup is a web page; and a
+    // two-word answer is a health check. All three were being adopted as the
+    // agent under test -- and since discovery tries port 3000 first, the most
+    // likely victim was a developer's own frontend, which would then have been
+    // measured for months for customer-service behaviour it does not have.
+    read: (body, raw, contentType = "") => {
+      if (body !== null) return { text: "", calls: null };
+      if (/html|xml/i.test(contentType)) return { text: "", calls: null };
+      const text = asText(raw);
+      if (looksLikeMarkup(text) || text.length < MIN_PROSE) return { text: "", calls: null };
+      return { text, calls: null };
+    },
+  },
+];
+
+/**
+ * The bodies that answer in prose rather than in a schema.
+ *
+ * One reader for all of them because the request is what distinguishes these
+ * dialects, not the response: an agent taking `{"message"}` and one taking
+ * `{"query"}` answer the same half-dozen field names.
+ */
+function readLoosely(body) {
+  return {
+    text: firstText(body, [
+      "response",
+      "reply",
+      "output",
+      "answer",
+      "content",
+      "text",
+      "message",
+      "result",
+    ]),
+    calls: body?.tool_calls || body?.events || body?.steps || body?.intermediate_steps,
+  };
+}
+
+/**
+ * Tool calls, from whatever the agent happened to call them.
+ *
+ * The output shape is assert-ai's `AdapterEvent` and the details are not
+ * negotiable -- `eval_target.js::eventsFrom` documents what was learned the
+ * hard way: its normalizer keys on `role`, silently drops anything whose role
+ * is not one of its three, and only `content`, `tool_name` and `tool_args`
+ * survive into the artifacts a judge reads. A plausible-looking event with the
+ * wrong role produces exactly the transcript of an agent that called nothing.
+ *
+ * Anything unrecognised returns `[]` rather than a guess. A judge asked whether
+ * the agent looked something up before answering is better served by a
+ * transcript that shows nothing than by one that shows the wrong thing.
+ */
+export function toolEventsFrom(raw) {
+  const list = Array.isArray(raw) ? raw : [];
+  const events = [];
+  for (const item of list) {
+    if (!item) continue;
+
+    // LangChain's `intermediate_steps`: [action, observation] pairs.
+    if (Array.isArray(item)) {
+      const [action] = item;
+      const name = String(action?.tool || action?.name || "");
+      if (!name) continue;
+      events.push(event(name, action?.tool_input ?? action?.args));
+      continue;
+    }
+
+    // OpenAI: the name and the arguments live under `function`, and the
+    // arguments are a JSON *string* rather than an object.
+    const fn = item.function;
+    const name = String(item.tool_name || item.name || item.tool || fn?.name || "");
+    if (!name) continue;
+    let args = item.tool_args ?? item.arguments ?? item.args ?? item.input ?? fn?.arguments;
+    if (typeof args === "string") {
+      try {
+        args = JSON.parse(args);
+      } catch {
+        args = { arguments: args };
+      }
+    }
+    events.push(event(name, args, item.executed));
+  }
+  return events;
+}
+
+function event(name, args, executed) {
+  return {
+    role: "tool_result",
+    content:
+      executed === false
+        ? `executed: false — ${name} was proposed and did not run.`
+        : `executed: true — ${name} ran and returned its result to the agent.`,
+    tool_name: name,
+    tool_args: args && typeof args === "object" && !Array.isArray(args) ? args : {},
+  };
+}
+
+/** One request, with its own timeout, returning the parsed body and the text. */
+async function attempt(url, dialect, message, history, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const payload = dialect.body(message, history);
+    const resp = await fetch(url, {
+      method: "POST",
+      signal: controller.signal,
+      headers: { "content-type": dialect.contentType || "application/json" },
+      body: dialect.contentType === "text/plain" ? String(payload) : JSON.stringify(payload),
+    });
+    const raw = await resp.text();
+    if (!resp.ok) return { ok: false, status: resp.status, why: `${resp.status}` };
+    let parsed = null;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = null;
+    }
+    const { text, calls } = dialect.read(parsed, raw, resp.headers.get("content-type") || "");
+    if (!text) return { ok: false, why: "answered, but nothing in it reads as a reply" };
+    return { ok: true, text, events: toolEventsFrom(calls), body: parsed };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      why: error.name === "AbortError" ? "no answer in time" : error.message,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Find the address and the shape that this agent answers to.
+ *
+ * Returns `{ url, path, dialect, sample }` for the first combination that
+ * produces text, or `{ tried }` when nothing did -- the list of what was tried
+ * and what each one said, because "we could not reach your agent" without it is
+ * the least actionable sentence in a CLI.
+ */
+export async function probeAgent(
+  baseUrl,
+  { paths = PROBE_PATHS, dialects = DIALECTS, message = PROBE_MESSAGE, timeoutMs = PROBE_TIMEOUT_MS, log = () => {} } = {}
+) {
+  const base = String(baseUrl || "").replace(/\/+$/, "");
+  const tried = [];
+  let attempts = 0;
+
+  for (const path of paths) {
+    let first = true;
+    for (const dialect of dialects) {
+      if (attempts >= MAX_ATTEMPTS) return { tried, exhausted: true };
+      attempts += 1;
+      const url = `${base}${path}`;
+      const result = await attempt(url, dialect, message, [], timeoutMs);
+      // A path that is not there is not there for any dialect. Without this the
+      // sweep spends eight requests proving one 404 eight times, which on ten
+      // candidate paths is most of its budget and all of the wait.
+      if (first && !result.ok && (result.status === 404 || result.status === 405)) {
+        tried.push({ path, dialect: dialect.name, why: `${result.status}, so this path is not the agent` });
+        break;
+      }
+      first = false;
+      if (result.ok) {
+        log(`${path} answers ${dialect.name}`);
+        return {
+          url: base,
+          path,
+          dialect: dialect.name,
+          sample: result.text.slice(0, 300),
+          events: result.events,
+        };
+      }
+      tried.push({ path, dialect: dialect.name, why: result.why });
+    }
+  }
+  return { tried };
+}
+
+/** The dialect by name, or null. */
+export function dialectNamed(name) {
+  return DIALECTS.find((entry) => entry.name === name) || null;
+}
+
+/**
+ * One turn against a target already probed, in the shape the eval expects.
+ *
+ * Throws rather than returning an error string: the adapter above this decides
+ * what an unreachable agent means for a case, and it is the only layer that
+ * knows whether the run can survive it.
+ */
+export async function askAgent(target, message, history = [], { timeoutMs = TURN_TIMEOUT_MS } = {}) {
+  const dialect = dialectNamed(target.dialect);
+  if (!dialect) throw new Error(`no dialect called ${target.dialect}`);
+  const url = `${String(target.url).replace(/\/+$/, "")}${target.path || ""}`;
+  const result = await attempt(url, dialect, message, history, timeoutMs);
+  if (!result.ok) throw new Error(result.why);
+  return { text: result.text, events: result.events };
+}

package/bin/cli.js

@@ -10,7 +10,7 @@
  *   npm exec -y premanmcp@latest --
  */
 
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -34,9 +34,11 @@ import {
   slackCommand,
 } from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+import { PREDICT_HELP, predictCommand } from "./predict.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
 import { HOOK_HELP, hookCommand, installHook, scheduleHookRepair } from "./hook.js";
 import { EVAL_HELP } from "./eval.js";
+import { TARGET_HELP, targetCommand } from "./target.js";
 import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import {
@@ -46,9 +48,11 @@ import {
   openDesktopSignedIn,
 } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
+import { AGENT_HELP, agentCommand } from "./agent.js";
 import {
   CREDENTIALS_FILE,
   cliInvocation,
+  packageVersion,
   DEFAULT_BACKEND,
   DEFAULT_FRONTEND,
   authenticateTerminal,
@@ -61,18 +65,34 @@ import {
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 
+// What this process is called wherever processes are listed: `ps`, `top`, an
+// editor's process picker, a "what is using this port" hunt. Without it every
+// one of them says `node`, which is true of the interpreter and useless to
+// somebody with three of them running -- the same reason the session sets an
+// OSC title on the terminal tab. Set before anything else so a crash in
+// argument parsing is still attributable.
+process.title = "preman";
+
 const args = process.argv.slice(2);
-// A bare `preman` in a terminal is someone starting out, so it runs setup:
-// account first, then the app. Piped or redirected (no TTY) it is an MCP host
-// launching the server, which must stay the behaviour for `start`.
-const command = args.length === 0 && process.stdin.isTTY
-  ? "onboard"
-  : args[0] === "--help" || args[0] === "-h"
+// A bare `preman` in a terminal opens the agent session: that is what the
+// product is in a terminal, and it signs the caller in on the way if they are
+// new. The same argv with piped or redirected stdin is an MCP host launching
+// the stdio server, which must keep working -- so the tty, not the argv, is
+// what separates a person from a host.
+//
+// A leading flag follows the same rule (`preman --continue`, `preman -p "..."`),
+// because those flags belong to the session. `preman start ...` stays the
+// explicit way to ask for the server from a terminal.
+const bare = args.length === 0;
+const leadingFlag = Boolean(args[0]) && args[0].startsWith("-");
+const command = args[0] === "--help" || args[0] === "-h"
   ? "help"
-  : args[0] && !args[0].startsWith("-")
-    ? args[0]
-    : "start";
-const commandArgs = command === "start" ? args : args.slice(1);
+  : bare || leadingFlag
+    ? (process.stdin.isTTY ? "agent" : "start")
+    : args[0];
+// A session or the server started this way owns every argument; a named
+// subcommand owns everything after its name.
+const commandArgs = command === "start" || bare || leadingFlag ? args : args.slice(1);
 const cliArgs = makeArgs(commandArgs);
 
 function argValue(name, fallback = "") {
@@ -91,6 +111,8 @@ function printHelp() {
   // for a global install and 38 for npm exec, so a fixed layout is wrong for
   // one of them.
   const usage = [
+    ["", "Chat with the PreMan agent in this terminal"],
+    ["chat [message] [--continue]", "The same session, named explicitly"],
     ["status", "Healthy / failing / recently fixed endpoints"],
     ["verify [options]", "Test endpoints against your local app"],
     ["hook install|uninstall|status", "Manage the git pre-push hook"],
@@ -98,6 +120,7 @@ function printHelp() {
     ["eval run|doctor", "Run PreMan's queued agent eval against your local agent"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
+    ["predict [options]", "Local dev: bring the stack up and measure the forecaster"],
     ["onboard", "Create an account, install the app signed in, then integrations"],
     ["connect [options]", "Pick a coding agent and connect it (optional)"],
     ["dispatch [options]", "Let PreMan start agent runs for you"],
@@ -105,8 +128,10 @@ function printHelp() {
     ["login [--browser]", "Create/login to PreMan from the terminal"],
     ["logout", "Delete stored CLI credentials"],
     ["watch <run> <integration>", "Follow a push simulation live"],
-    ["install [options]", "Install PreMan into Cursor MCP config"],
-    ["", "Start the PreMan MCP server"],
+    ["install", "Set PreMan up: account, desktop app, integrations"],
+    ["install --cursor", "Write Cursor's MCP config only (the old `install`)"],
+    ["update", "Update this CLI to the newest published version"],
+    ["start", "Start the PreMan MCP server (what an MCP host runs)"],
     ["link|tools|run ...", "Drive a published hosted MCP"],
     ["endpoints list|discover|setup ...", "Discover, list, and set up API endpoints"],
     ["test --agent [--only <id>]", "Measure your agent against the behaviours you turned on"],
@@ -122,7 +147,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
+${AGENT_HELP}${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${EVAL_HELP}${TARGET_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${PREDICT_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -138,6 +163,8 @@ Install options (Cursor only — prefer '${cli} connect'):
   --print               Print the config instead of writing it
 
 Examples:
+  ${cli}
+  ${cli} chat "which endpoints broke since Friday?"
   npm exec -y premanmcp@latest -- connect
   ${cli} connect --agent claude-code
   ${cli} login
@@ -175,6 +202,60 @@ You can now run:
 `);
 }
 
+// The published package. Not the same word as the command, which is exactly
+// why `preman update` exists rather than a line of npm for people to memorise.
+const PACKAGE_NAME = "premanmcp";
+
+/**
+ * Update this CLI in place.
+ *
+ * `npm install -g premanmcp@latest` is the whole mechanism, and the only
+ * reason to wrap it is that nobody should have to remember the package name
+ * is not the command name. Run through `npx`/`npm exec` there is nothing
+ * installed to update -- that form already fetches the newest version every
+ * time -- so say that rather than silently installing something global the
+ * person did not ask for.
+ */
+async function updateCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const wanted = args.value("--version", "latest");
+  const before = packageVersion();
+  const here = fileURLToPath(import.meta.url);
+
+  if (/[\\/]_npx[\\/]/.test(here)) {
+    process.stdout.write(
+      `Running from npm exec, which fetches the newest version each time — ` +
+        `there is nothing installed to update.\n` +
+        `  To install it properly: npm install -g ${PACKAGE_NAME}\n`
+    );
+    return;
+  }
+
+  process.stdout.write(`Updating ${PACKAGE_NAME} (have ${before})…\n`);
+  const done = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@${wanted}`], {
+    stdio: "inherit",
+  });
+  if (done.error || done.status !== 0) {
+    process.stdout.write(
+      `\nCould not update. Try it directly:\n` +
+        `  npm install -g ${PACKAGE_NAME}@${wanted}\n` +
+        `If that reports a permissions error, npm's global directory is not ` +
+        `writable by you — that is an npm setup problem, not a PreMan one.\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  // Read from the freshly installed copy rather than this process, which is
+  // still running the version we just replaced.
+  const now = spawnSync("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
+  const after = String(now.stdout || "").trim();
+  process.stdout.write(
+    after && after !== before
+      ? `\nUpdated ${before} → ${after}. Run \`preman\` to start a session.\n`
+      : `\nAlready on the newest version (${before}).\n`
+  );
+}
+
 /**
  * Cursor-only installer, kept for the documented `install` flow. `connect` is
  * the same write plus agent choice, pairing, and dispatch setup.
@@ -249,7 +330,11 @@ async function main() {
   // would only race with the one the user is watching.
   if (!["hook", "verify", "connect"].includes(command)) scheduleHookRepair();
 
-  if (command === "login") {
+  if (command === "agent" || command === "chat") {
+    await agentCommand(commandArgs);
+  } else if (command === "target") {
+    await targetCommand(commandArgs, { makeArgs });
+  } else if (command === "login") {
     await loginCommand();
   } else if (command === "status") {
     await statusCommand(commandArgs);
@@ -286,6 +371,11 @@ async function main() {
     await watchCommand(commandArgs);
   } else if (command === "install-desktop") {
     await installDesktopCommand(commandArgs);
+  } else if (command === "predict") {
+    // Exits on its own code: bringing the stack up can fail in half a dozen
+    // ways that are worth distinguishing from "the forecaster scored badly",
+    // and a caller in a shell loop should be able to tell them apart.
+    process.exitCode = await predictCommand(commandArgs);
   } else if (command === "connect") {
     await connectCommand(commandArgs);
   } else if (command === "dispatch") {
@@ -306,12 +396,35 @@ async function main() {
     await githubCommand(makeArgs(commandArgs));
   } else if (command === "slack") {
     await slackCommand(makeArgs(commandArgs));
+  } else if (command === "update" || command === "upgrade") {
+    await updateCommand(commandArgs);
   } else if (command === "install") {
-    await installCursorMcp();
+    // `install` meant "write Cursor's MCP config", and every documented form of
+    // it passes a flag (`--api-key`, `--project`, `--backend`). Bare `install`
+    // never had a use, so it is the one spelling free to become what people
+    // actually type it expecting: set me up. Flagged forms keep working
+    // untouched, and `--cursor` names the old behaviour explicitly.
+    if (commandArgs.length > 0) {
+      await installCursorMcp();
+    } else {
+      await onboardCommand(commandArgs, {
+        makeArgs,
+        authenticateTerminal,
+        installDesktop: installDesktopCommand,
+        openDesktopSignedIn,
+        installPushHook: installHook,
+      });
+    }
   } else if (command === "link") {
     await linkCommand(commandArgs);
   } else if (command === "tools") {
     await toolsCommand(commandArgs);
+  } else if (command === "run" && commandArgs.includes("--predict")) {
+    // `run --predict` is the spelling people reach for, and `run` was already
+    // the hosted-MCP driver by the time this existed. Both spellings work
+    // rather than one of them being corrected: a tool name never starts with a
+    // dash, so there is nothing here for the two to argue about.
+    process.exitCode = await predictCommand(commandArgs.filter((arg) => arg !== "--predict"));
   } else if (command === "run") {
     await runCommand(commandArgs);
   } else if (command === "endpoints") {
@@ -341,7 +454,13 @@ async function main() {
   } else if (command === "start") {
     startServer();
   } else {
-    process.stderr.write(`Unknown command: ${command}\n\n`);
+    // Not routed to the agent on purpose: with twenty subcommands, a typo is a
+    // likelier explanation than a question, and silently chatting about
+    // "statuss" is a worse answer than saying the word is unknown.
+    process.stderr.write(
+      `Unknown command: ${command}\n` +
+        `To ask PreMan instead, run \`${cliInvocation()}\` or \`${cliInvocation()} chat "${command} ..."\`.\n\n`
+    );
     printHelp();
     process.exit(1);
   }