setup-agent 0.1.1 → 0.2.0

package/src/guide.ts

@@ -0,0 +1,177 @@
+/**
+ * The guide: every text the CLI shows the coding agent and the order of its
+ * intro, fetched from the setup server at `<setup-url>/guide` so a wording
+ * or flow fix ships with a server deploy. Setup is online-only, and the CLI
+ * keeps no copy of the text.
+ *
+ * The guide is data. The CLI prints its texts after stripping control
+ * characters, fills `{{name}}` placeholders with values it computes itself,
+ * and runs intro steps only from `LOCAL_ACTIONS`. Commands it runs, files it
+ * writes and URLs it opens never come from the guide.
+ */
+
+/** The guide format the CLI reads. Bump it only for a change an older CLI cannot read. */
+export const GUIDE_PROTOCOL = 1;
+
+/** Every text the CLI prints from the guide. */
+export const GUIDE_TEXT_KEYS = [
+  "briefing",
+  "intro.status-heading",
+  "stream.briefing",
+  "stream.briefing-footer",
+  "stream.stay-connected",
+  "stream.opened.input",
+  "stream.opened.plan",
+  "stream.opened.finish",
+  "stream.ask.recently-opened",
+  "stream.ask.browser-closed",
+  "stream.ask.no-browser",
+  "wait.waiting",
+  "done.next",
+  "need.plan.question",
+  "need.plan.approve",
+  "need.plan.revise",
+  "need.plan.format",
+  "need.finish.question",
+  "need.finish.question-preview",
+  "need.finish.close",
+  "need.finish.format",
+  "need.input.empty-prompt",
+  "need.input.optional",
+  "need.input.model",
+  "need.product.add",
+  "need.product.decline",
+  "need.format.text",
+  "need.format.product",
+  "need.format.model",
+  "need.format.entry-point",
+  "need.format.choice",
+  "need.format.multiple",
+] as const;
+export type GuideTextKey = (typeof GUIDE_TEXT_KEYS)[number];
+
+/** All a guide can make the CLI do: print one of its texts, print the setup's state, or announce the agent. */
+const LOCAL_ACTIONS = ["print", "print-status", "announce-agent"] as const;
+
+export type GuideStep =
+  | { action: "print"; text: GuideTextKey }
+  | { action: "print-status" }
+  | { action: "announce-agent" };
+
+export type Guide = {
+  protocol: typeof GUIDE_PROTOCOL;
+  texts: Record<GuideTextKey, string>;
+  intro: GuideStep[];
+};
+
+/** Who started the setup (the user's browser, `assistant-ui setup`, or that command as the stream) and whether a browser opens. */
+export type GuideContext = {
+  started: "user" | "agent" | "agent-stream";
+  opened: boolean;
+};
+
+const MAX_GUIDE_BYTES = 256 * 1024;
+const TIMEOUT_MS = 5_000;
+
+/**
+ * `text` without control characters other than tab and line feed (an escape
+ * sequence could rewrite the terminal) and bidirectional overrides.
+ */
+const sanitizeTerminalText = (text: string) =>
+  // oxlint-disable-next-line no-control-regex
+  text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f‪-‮⁦-⁩]/g, "");
+
+/** A guide text with its placeholders filled once; a value is never read for placeholders itself. */
+export const renderText = (
+  guide: Pick<Guide, "texts">,
+  key: GuideTextKey,
+  values: Record<string, string | number> = {},
+) =>
+  guide.texts[key].replace(/\{\{([A-Za-z]+)\}\}/g, (_, name: string) =>
+    String(values[name] ?? ""),
+  );
+
+const isTextKey = (value: unknown): value is GuideTextKey =>
+  (GUIDE_TEXT_KEYS as readonly unknown[]).includes(value);
+
+/** The guide the server sent, or an error saying what this CLI cannot use. */
+export const parseGuide = (value: unknown): Guide => {
+  const guide = value as Partial<Record<keyof Guide, unknown>> | null;
+  if (guide?.protocol !== GUIDE_PROTOCOL)
+    throw new Error(`the guide is not protocol ${GUIDE_PROTOCOL}`);
+  const texts = guide.texts as Record<string, unknown> | undefined;
+  const parsed = {} as Record<GuideTextKey, string>;
+  for (const key of GUIDE_TEXT_KEYS) {
+    const text = texts?.[key];
+    if (typeof text !== "string") throw new Error(`the guide has no "${key}"`);
+    parsed[key] = sanitizeTerminalText(text);
+  }
+  if (!Array.isArray(guide.intro)) throw new Error("the guide has no intro");
+  const intro = guide.intro.map((step: unknown): GuideStep => {
+    const { action, text, ...rest } = (step ?? {}) as Record<string, unknown>;
+    const allowed =
+      (LOCAL_ACTIONS as readonly unknown[]).includes(action) &&
+      Object.keys(rest).length === 0 &&
+      (action === "print" ? isTextKey(text) : text === undefined);
+    if (!allowed)
+      throw new Error(
+        `the guide asks for an action this CLI does not run: ${sanitizeTerminalText(JSON.stringify(step) ?? "").slice(0, 80)}`,
+      );
+    return action === "print"
+      ? { action, text: text as GuideTextKey }
+      : { action: action as "print-status" | "announce-agent" };
+  });
+  return { protocol: GUIDE_PROTOCOL, texts: parsed, intro };
+};
+
+/**
+ * The guide for this setup, from `<setupUrl>/guide`. Setup is online-only:
+ * without the guide the command fails. Redirects are refused, so the guide
+ * only ever comes from the setup URL `parseSetupUrl` accepted.
+ */
+export const loadGuide = async (
+  setupUrl: string,
+  { started, opened }: GuideContext,
+): Promise<Guide> => {
+  const query = new URLSearchParams({
+    protocol: String(GUIDE_PROTOCOL),
+    started,
+    opened: opened ? "1" : "0",
+  });
+  const offline = `Setup needs internet access to ${setupUrl}`;
+  let response: Response;
+  try {
+    response = await fetch(`${setupUrl.replace(/\/$/, "")}/guide?${query}`, {
+      redirect: "error",
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    throw new Error(offline);
+  }
+  if (response.status === 426) {
+    const { supported = [] } = (await response.json().catch(() => ({}))) as {
+      supported?: unknown[];
+    };
+    throw new Error(
+      supported.some((v) => typeof v === "number" && v > GUIDE_PROTOCOL)
+        ? "this setup-agent is older than the setup server supports; run the latest setup-agent"
+        : "this setup-agent is newer than the setup server; try again once the server updates",
+    );
+  }
+  if (!response.ok) throw new Error(`${offline} (HTTP ${response.status})`);
+  try {
+    let body = "";
+    let bytes = 0;
+    const decoder = new TextDecoder();
+    for await (const chunk of response.body ?? []) {
+      bytes += chunk.byteLength;
+      if (bytes > MAX_GUIDE_BYTES) throw new Error("it is too large");
+      body += decoder.decode(chunk, { stream: true });
+    }
+    return parseGuide(JSON.parse(body + decoder.decode()));
+  } catch (error) {
+    throw new Error(
+      `the setup server sent a guide this setup-agent cannot use (${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+};

package/src/host.ts

@@ -50,7 +50,7 @@ const useCheckoutHost = (restored: unknown) => {
     if (state.status === "waiting") {
       throw reject(
         "planning-not-started",
-        'ask the user to return to their browser and click "Begin plan"; wait with "wait start"',
+        'the setup page starts planning on its own once the user opens it; wait with "wait start"',
       );
     }
   };

package/src/index.ts

@@ -28,3 +28,5 @@ export { INPUT_PRESETS, isPresetId, presetInput } from "./presets";
 export type { PresetId, PresetOverrides } from "./presets";
 export { connectCheckout } from "./client";
 export type { CheckoutClient } from "./client";
+export { GUIDE_PROTOCOL, parseGuide } from "./guide";
+export type { Guide, GuideContext, GuideStep, GuideTextKey } from "./guide";

package/src/needs.test.ts

@@ -1,3 +1,4 @@
+import { testGuide } from "./tests/guide-fixture";
 import { describe, expect, it } from "vitest";
 import {
   answerNeed,
@@ -70,7 +71,7 @@ describe("terminalQuestion", () => {
         presetInput("framework") as Checkout.Input,
         presetInput("llm-provider") as Checkout.Input,
       ),
-    ).map(terminalQuestion);
+    ).map((need) => terminalQuestion(need, testGuide));
     expect(framework!.options?.map((option) => option.id)).toEqual([
       "ai-sdk:typescript",
       "mastra:typescript",
@@ -80,10 +81,8 @@ describe("terminalQuestion", () => {
     expect(formatTerminalQuestion(framework!)).toMatch(
       /^Which agent framework runs your backend\? Options: ai-sdk:typescript \(Vercel AI SDK \(TypeScript\): Shortest path/,
     );
-    expect(model!.question).toContain("The API key is not typed here");
-    expect(model!.answerFormat).toBe(
-      "<provider>:<model>, such as openai:gpt-5",
-    );
+    expect(model!.question).toContain("[need.input.model]");
+    expect(model!.answerFormat).toBe("[need.format.model]");
   });
 });
 

package/src/needs.ts

@@ -11,6 +11,8 @@ import {
   parseMultipleAnswer,
 } from "./protocol";
 import type { Checkout } from "./protocol";
+import { renderText } from "./guide";
+import type { Guide, GuideTextKey } from "./guide";
 
 /**
  * Something the setup waits on the user for: an open question, a proposed
@@ -86,49 +88,62 @@ const optionList = (input: Checkout.Input): NeedOption[] =>
       : [entry(option.id, option.label)];
   });
 
-const ANSWER_FORMATS: Record<Checkout.InputKind, string> = {
-  text: "the user's text, as one shell word",
-  product: "add or decline",
-  model: "<provider>:<model>, such as openai:gpt-5",
-  "entry-point": "one option id",
-  choice: "one option id, or the user's own text",
-};
+const ANSWER_FORMATS = {
+  text: "need.format.text",
+  product: "need.format.product",
+  model: "need.format.model",
+  "entry-point": "need.format.entry-point",
+  choice: "need.format.choice",
+} as const satisfies Record<Checkout.InputKind, GuideTextKey>;
 
-export const terminalQuestion = (need: SetupNeed): TerminalQuestion => {
+/** A need as a question for the agent's own conversation, worded by the setup server's `guide`. */
+export const terminalQuestion = (
+  need: SetupNeed,
+  guide: Pick<Guide, "texts">,
+): TerminalQuestion => {
+  const text = (key: GuideTextKey, values?: Record<string, string>) =>
+    renderText(guide, key, values);
   if (need.kind === "plan")
     return {
-      question:
-        "Approve the setup plan? Show the user the plan you proposed and ask whether to go ahead or what to change.",
+      question: text("need.plan.question"),
       options: [
-        { id: "approve", label: "Approve the plan" },
-        { id: "revise", label: "Ask for changes (pass --feedback)" },
+        { id: "approve", label: text("need.plan.approve") },
+        { id: "revise", label: text("need.plan.revise") },
       ],
-      answerFormat: 'approve, or revise --feedback "<what to change>"',
+      answerFormat: text("need.plan.format"),
     };
   if (need.kind === "finish")
     return {
-      question: `Everything is installed${need.completion.preview ? ` and running at ${need.completion.preview}` : ""}. Close the setup, or keep going?`,
-      options: [{ id: "close", label: "Close the setup" }],
-      answerFormat:
-        "close; if the user wants more, do it and run done again instead",
+      question: need.completion.preview
+        ? text("need.finish.question-preview", {
+            preview: need.completion.preview,
+          })
+        : text("need.finish.question"),
+      options: [{ id: "close", label: text("need.finish.close") }],
+      answerFormat: text("need.finish.format"),
     };
   const { input } = need;
   const options =
     input.kind === "product"
       ? [
-          { id: "add", label: `Add ${input.product ?? "the product"}` },
-          { id: "decline", label: "Leave it out" },
+          {
+            id: "add",
+            label: text("need.product.add", {
+              product: input.product ?? "the product",
+            }),
+          },
+          { id: "decline", label: text("need.product.decline") },
         ]
       : input.kind === "text"
         ? undefined
         : optionList(input);
   return {
-    question: `${input.prompt.trim() || "Your agent needs an answer."}${input.optional ? " (optional; --dismiss skips it)" : ""}${input.kind === "model" ? " The API key is not typed here: the user adds it to the project's env file themselves." : ""}`,
+    question: `${input.prompt.trim() || text("need.input.empty-prompt")}${input.optional ? text("need.input.optional") : ""}${input.kind === "model" ? text("need.input.model") : ""}`,
     ...(options && { options }),
     ...(input.multiple && { multiple: true as const }),
-    answerFormat: input.multiple
-      ? "option ids separated by commas, or the user's own text"
-      : ANSWER_FORMATS[input.kind],
+    answerFormat: text(
+      input.multiple ? "need.format.multiple" : ANSWER_FORMATS[input.kind],
+    ),
   };
 };
 

package/src/sdk.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import * as sdk from "./sdk";
-import { initialCheckoutState } from "./protocol";
+import { OPTION_ICONS, initialCheckoutState } from "./protocol";
 import type { Checkout } from "./protocol";
 import type { CheckoutClient } from "./client";
 
@@ -62,18 +62,14 @@ describe("setup-agent/sdk", () => {
           agent: { cwd: "/app" },
         },
       });
-      expect(out).toMatch(/^my-tool setup is running\./);
-      expect(out).toContain(
-        `npx my-tool setup https://checkout.test/${session.linkId} stream`,
+      // The briefing is the server's guide, with this command's values filled in.
+      const url = `https://checkout.test/${session.linkId}`;
+      expect(out).toBe(
+        `[stream.briefing] my-tool setup npx my-tool setup ${url} ${session.browserUrl}[briefing] npx my-tool setup ${url} ${OPTION_ICONS.join(", ")}\n[stream.briefing-footer] ${session.browserUrl}${JSON.stringify({ status: "planning", products: [{ slug: "assistant-ui", name: "assistant-ui" }] })}\n`,
+      );
+      expect(String(vi.mocked(fetch).mock.calls[0]?.[0])).toBe(
+        `${url}/guide?protocol=1&started=agent-stream&opened=1`,
       );
-      expect(out).toContain("run_in_background");
-      expect(out).toContain('"input.needed"');
-      expect(out).toContain('"browser.opened"');
-      expect(out).not.toContain("start a persistent Monitor");
-      expect(out).toContain("opens the user's browser by itself");
-      expect(out).not.toContain("npx setup-agent");
-      expect(out).not.toContain("click Begin plan");
-      expect(out).toContain(session.browserUrl);
       expect(open).not.toHaveBeenCalled();
       expect(calls.map(([name]) => name)).toEqual([
         "checkout/create",

package/src/sdk.ts

@@ -5,7 +5,9 @@
  */
 import { randomInt } from "node:crypto";
 import { detectAgentKind } from "./agents";
-import { agentInstructions } from "./cli";
+import { OPTION_ICONS } from "./protocol";
+import { loadGuide, renderText } from "./guide";
+import type { Guide } from "./guide";
 import { connectCheckout } from "./client";
 import type { CheckoutClient } from "./client";
 import type { Checkout } from "./protocol";
@@ -57,37 +59,19 @@ export type RunAgentSetupOptions = {
 /** What the agent reads first in the output of a setup command that keeps running. */
 const setupBriefing = (
   session: SetupSession,
-  {
-    command,
-    name = "Setup",
-    canOpen = true,
-  }: Pick<RunAgentSetupOptions, "command" | "name" | "canOpen">,
+  guide: Guide,
+  { command, name = "Setup" }: Pick<RunAgentSetupOptions, "command" | "name">,
 ) => {
-  const url = shellWord(session.agentUrl);
-  return `${name} is running. This command keeps running: it is the setup's stream.
-
-1. Keep it running in the background until the setup ends. If you started it in the foreground, stop it and resume it in the background (Claude Code: Bash with run_in_background; Codex and other agents: add > "\${TMPDIR:-/tmp}/setup-${session.linkId}.log" 2>&1 & and read that file):
-  ${command} ${url} stream${canOpen ? "" : " --no-open"}
-2. Read its new output as it arrives. Each line after this briefing is a JSON array of events.
-3. Run every other command in another shell: ${command} ${url} <command>.
-4. ${
-    canOpen
-      ? "Setup opens the user's browser by itself when you ask the user something; do not open it yourself."
-      : `Setup will not open a browser (--no-open). Give the user ${session.browserUrl} once, or ask in your own conversation.`
-  } On an "input.needed" event, do what its message says; to answer from here, run its "answer" command with the user's reply.
-
-${agentInstructions(session.agentUrl, {
-  command,
-  startedByAgent: {
+  const values = {
+    name,
+    cmd: command,
+    url: shellWord(session.agentUrl),
+    linkId: session.linkId,
     browserUrl: session.browserUrl,
-    streaming: true,
-    opened: canOpen,
-  },
-})}
-Setup page, if the user asks for it: ${session.browserUrl}
-
-Current setup:
-${JSON.stringify({ status: "planning", products: session.products })}
+    icons: OPTION_ICONS.join(", "),
+  };
+  return `${renderText(guide, "stream.briefing", values)}${renderText(guide, "briefing", values)}
+${renderText(guide, "stream.briefing-footer", values)}${JSON.stringify({ status: "planning", products: session.products })}
 `;
 };
 
@@ -103,6 +87,11 @@ export const runAgentSetup = async (options: RunAgentSetupOptions) => {
   const linkId = createSetupId();
   const setupId = createSetupId();
   const agentUrl = `${options.server.replace(/\/$/, "")}/${linkId}`;
+  // Online-only: the briefing and the stream's wording come from the setup server.
+  const guide = await loadGuide(agentUrl, {
+    started: "agent-stream",
+    opened: options.canOpen !== false,
+  });
   const client = await connect(agentUrl);
   try {
     const kind = detectAgentKind(options.env);
@@ -124,9 +113,10 @@ export const runAgentSetup = async (options: RunAgentSetupOptions) => {
     };
     options.onSession?.(session);
     (options.write ?? ((text) => process.stdout.write(text)))(
-      setupBriefing(session, options),
+      setupBriefing(session, guide, options),
     );
     const stream = await followSetup(client, {
+      guide,
       ...options.stream,
       agent: { ...(kind !== undefined && { kind }), ...options.stream?.agent },
       browser: {

package/src/stream.test.ts

@@ -1,3 +1,4 @@
+import { testGuide } from "./tests/guide-fixture";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { answerNeed } from "./needs";
 import { initialCheckoutState } from "./protocol";
@@ -7,6 +8,7 @@ import type { StreamEvent } from "./stream";
 
 const PAGE = "https://setup.test/#link=abc&setup=s1";
 const ANSWER = "npx assistant-ui@latest setup https://checkout.test/abc answer";
+const WAIT = "npx assistant-ui@latest setup https://checkout.test/abc wait";
 
 /** A client whose state the test changes, notifying like a statewire client. */
 const fakeClient = () => {
@@ -91,6 +93,7 @@ describe("followSetup", () => {
     const lines: StreamEvent[][] = [];
     const open = vi.fn();
     const stream = await followSetup(fake.client, {
+      guide: testGuide,
       print: (events) => lines.push(events),
       agent: { cwd: "/app", kind: "claude" },
       browser: {
@@ -129,8 +132,7 @@ describe("followSetup", () => {
         event: "browser.opened",
         id: "q1",
         url: PAGE,
-        message:
-          'Opened the setup in the user\'s browser for "Which package manager?". Tell the user once that it is waiting there, and give them https://setup.test/#link=abc&setup=s1 in case it did not open. The answer arrives on this stream.',
+        message: `[stream.opened.input] Which package manager? ${PAGE}  with "${WAIT} q1"`,
       },
     ]);
 
@@ -160,15 +162,14 @@ describe("followSetup", () => {
       event: "input.needed",
       id: "q3",
       reason: "recently-opened",
-      message:
-        "A browser tab for setup was opened 10s ago. Wait for the user there, or ask the user directly in the terminal: Which registry? Options: pnpm (pnpm), npm (npm).",
+      message: `[stream.ask.recently-opened] 10  with "${WAIT} q3" Which registry? Options: pnpm (pnpm), npm (npm).`,
       question: "Which registry?",
       options: [
         { id: "pnpm", label: "pnpm" },
         { id: "npm", label: "npm" },
       ],
-      answerFormat: "one option id, or the user's own text",
-      answer: `${ANSWER} q3 <one option id, or the user's own text>`,
+      answerFormat: "[need.format.choice]",
+      answer: `${ANSWER} q3 <[need.format.choice]>`,
     });
 
     // The agent asked in its own conversation and answers for the user.
@@ -196,7 +197,7 @@ describe("followSetup", () => {
       id: "q1",
       reason: "browser-closed",
       message:
-        "The user closed the setup tab. Ask the user directly in the terminal: Which package manager? Options: pnpm (pnpm), npm (npm).",
+        "[stream.ask.browser-closed] Which package manager? Options: pnpm (pnpm), npm (npm).",
     });
     // A question right after: inside the 30s window, and the tab is known to be gone.
     t.ask("Which registry?");
@@ -212,6 +213,7 @@ describe("followSetup", () => {
     const fake = fakeClient();
     const lines: StreamEvent[][] = [];
     const stream = await followSetup(fake.client, {
+      guide: testGuide,
       print: (events) => lines.push(events),
       agent: { cwd: "/app" },
     });

package/src/stream.ts

@@ -11,6 +11,8 @@ import {
   parseMultipleAnswer,
 } from "./protocol";
 import type { Checkout } from "./protocol";
+import { renderText } from "./guide";
+import type { Guide } from "./guide";
 
 export type StreamEvent =
   | { event: "planning.started" }
@@ -47,14 +49,14 @@ export type StreamEvent =
       answer: string;
     } & TerminalQuestion);
 
-const STAY_CONNECTED =
-  "This setup is over, not your connection. Keep the stream running, tell the user you are connected and waiting for their next setup, and run wait start.";
-
+/** The events between two states, with hints worded by the setup server's `guide`. */
 export const diffEvents = (
   before: Checkout.State,
   after: Checkout.State,
+  guide: Pick<Guide, "texts">,
 ): StreamEvent[] => {
   const events: StreamEvent[] = [];
+  const stayConnected = renderText(guide, "stream.stay-connected");
   if (before.status === "waiting" && after.status === "planning") {
     events.push({ event: "planning.started" });
   }
@@ -110,10 +112,10 @@ export const diffEvents = (
     }
   }
   if (before.status !== "done" && after.status === "done") {
-    events.push({ event: "finished", next: STAY_CONNECTED });
+    events.push({ event: "finished", next: stayConnected });
   }
   if (before.status !== "cancelled" && after.status === "cancelled") {
-    events.push({ event: "cancelled", next: STAY_CONNECTED });
+    events.push({ event: "cancelled", next: stayConnected });
   }
   if (after.id !== null && after.id !== before.id) {
     events.push({
@@ -165,40 +167,57 @@ export const shellWord = (value: string) =>
     ? value
     : `'${value.replaceAll("'", `'\\''`)}'`;
 
-const ASK_MESSAGES: Record<
-  AskReason,
-  (question: string, context: { agoSeconds: number; page: string }) => string
-> = {
-  "recently-opened": (question, { agoSeconds }) =>
-    `A browser tab for setup was opened ${agoSeconds}s ago. Wait for the user there, or ask the user directly in the terminal: ${question}`,
-  "browser-closed": (question) =>
-    `The user closed the setup tab. Ask the user directly in the terminal: ${question}`,
-  "no-browser": (question, { page }) =>
-    `No browser tab is open for this setup. Ask the user directly in the terminal, or give them ${page}: ${question}`,
-};
+const ASK_TEXTS = {
+  "recently-opened": "stream.ask.recently-opened",
+  "browser-closed": "stream.ask.browser-closed",
+  "no-browser": "stream.ask.no-browser",
+} as const satisfies Record<AskReason, string>;
+
+/** The command that blocks on a need, beside the one that answers it: `<cmd> <url> wait`. */
+const waitCommandFor = (answerCommand: string) =>
+  answerCommand.endsWith(" answer")
+    ? `${answerCommand.slice(0, -" answer".length)} wait`
+    : undefined;
 
 /** What the agent reads when setup opened the browser, or when it should ask the user itself. */
 const gateEvent = (
   action: BrowserGateAction,
   answerCommand: string,
   page: string,
+  waitCommand: string | undefined,
+  guide: Pick<Guide, "texts">,
 ): StreamEvent => {
   const { need } = action;
+  // Closing the setup is the user's call after "done"; there is nothing to block on.
+  const wait =
+    waitCommand !== undefined && need.kind !== "finish"
+      ? ` with "${waitCommand} ${need.id}"`
+      : "";
   if (action.type === "open")
     return {
       event: "browser.opened",
       id: need.id,
       url: action.url,
-      message: `Opened the setup in the user's browser for ${need.kind === "input" ? `"${need.input.prompt.trim() || "Your agent needs an answer."}"` : need.kind === "plan" ? "the plan review" : "closing the setup"}. Tell the user once that it is waiting there, and give them ${action.url} in case it did not open. The answer arrives on this stream.`,
+      message: renderText(guide, `stream.opened.${need.kind}`, {
+        url: action.url,
+        wait: wait || ' with "wait"',
+        prompt:
+          need.kind === "input"
+            ? need.input.prompt.trim() ||
+              renderText(guide, "need.input.empty-prompt")
+            : "",
+      }),
     };
-  const question = terminalQuestion(need);
+  const question = terminalQuestion(need, guide);
   return {
     event: "input.needed",
     id: need.id,
     reason: action.reason,
-    message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {
+    message: renderText(guide, ASK_TEXTS[action.reason], {
+      question: formatTerminalQuestion(question),
       agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1000),
       page,
+      wait,
     }),
     ...question,
     answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,
@@ -206,6 +225,8 @@ const gateEvent = (
 };
 
 export type FollowSetupOptions = {
+  /** The setup server's wording for the stream's messages. */
+  guide: Pick<Guide, "texts">;
   /** Writes one line of events; the default prints a JSON array to stdout. */
   print?: (events: StreamEvent[]) => void;
   /** The agent the stream reports in its hello; detected by default. */
@@ -231,7 +252,7 @@ export type FollowSetupOptions = {
  */
 export const followSetup = async (
   client: Pick<CheckoutClient, "state" | "subscribe" | "commands">,
-  { print, agent, browser }: FollowSetupOptions = {},
+  { print, agent, browser, guide }: FollowSetupOptions,
 ) => {
   const write =
     print ??
@@ -251,7 +272,7 @@ export const followSetup = async (
     });
   let previous = client.state;
   if (previous === undefined) throw new Error("the setup has no state");
-  let pending = diffEvents({ ...previous, log: [] }, previous);
+  let pending = diffEvents({ ...previous, log: [] }, previous, guide);
   let timer: ReturnType<typeof setTimeout> | undefined;
   const flush = () => {
     clearTimeout(timer);
@@ -263,14 +284,20 @@ export const followSetup = async (
     for (const action of gate?.update(state) ?? []) {
       if (action.type === "open") (browser!.open ?? openUrl)(action.url);
       pending.push(
-        gateEvent(action, browser!.answerCommand, page(state) ?? ""),
+        gateEvent(
+          action,
+          browser!.answerCommand,
+          page(state) ?? "",
+          waitCommandFor(browser!.answerCommand),
+          guide,
+        ),
       );
     }
   };
   const unsubscribe = client.subscribe(() => {
     const next = client.state;
     if (next === undefined) return;
-    pending.push(...diffEvents(previous!, next));
+    pending.push(...diffEvents(previous!, next, guide));
     previous = next;
     runGate(next);
     if (pending.length > 0 && timer === undefined)