setup-agent 0.1.1 → 0.2.0

package/dist/stream.js

@@ -1,12 +1,14 @@
 import { detectAgentKind } from "./agents.js";
 import { AGENT_HEARTBEAT_MS, classifyChoiceAnswer, parseMultipleAnswer } from "./protocol.js";
+import { renderText } from "./guide.js";
 import { formatTerminalQuestion, terminalQuestion } from "./needs.js";
 import { createBrowserGate } from "./browser.js";
 import spawn from "cross-spawn";
 // src/stream.ts
-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.";
-const diffEvents = (before, after) => {
+/** The events between two states, with hints worded by the setup server's `guide`. */
+const diffEvents = (before, after, guide) => {
 	const events = [];
+	const stayConnected = renderText(guide, "stream.stay-connected");
 	if (before.status === "waiting" && after.status === "planning") events.push({ event: "planning.started" });
 	for (const entry of after.log) if (entry.role === "user" && entry.acknowledgedAt === void 0 && !before.log.some((previous) => previous.id === entry.id)) events.push({
 		event: "message.created",
@@ -43,11 +45,11 @@ const diffEvents = (before, after) => {
 	}
 	if (before.status !== "done" && after.status === "done") events.push({
 		event: "finished",
-		next: STAY_CONNECTED
+		next: stayConnected
 	});
 	if (before.status !== "cancelled" && after.status === "cancelled") events.push({
 		event: "cancelled",
-		next: STAY_CONNECTED
+		next: stayConnected
 	});
 	if (after.id !== null && after.id !== before.id) events.push({
 		event: "setup.created",
@@ -79,28 +81,37 @@ const openUrl = (url) => {
 };
 /** `value` as one shell word, quoted only when it holds more than plain URL characters. */
 const shellWord = (value) => /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
-const ASK_MESSAGES = {
-	"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"
 };
+/** The command that blocks on a need, beside the one that answers it: `<cmd> <url> wait`. */
+const waitCommandFor = (answerCommand) => answerCommand.endsWith(" answer") ? `${answerCommand.slice(0, -7)} wait` : void 0;
 /** What the agent reads when setup opened the browser, or when it should ask the user itself. */
-const gateEvent = (action, answerCommand, page) => {
+const gateEvent = (action, answerCommand, page, waitCommand, guide) => {
 	const { need } = action;
+	const wait = waitCommand !== void 0 && 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) / 1e3),
-			page
+			page,
+			wait
 		}),
 		...question,
 		answer: `${answerCommand} ${need.id} <${question.answerFormat}>`
@@ -112,7 +123,7 @@ const gateEvent = (action, answerCommand, page) => {
 * only when the setup waits on the user. Resolves with `stop`, which says
 * goodbye; the caller disposes the client.
 */
-const followSetup = async (client, { print, agent, browser } = {}) => {
+const followSetup = async (client, { print, agent, browser, guide }) => {
 	const write = print ?? ((events) => {
 		process.stdout.write(`${JSON.stringify(events)}\n`);
 	});
@@ -127,7 +138,7 @@ const followSetup = async (client, { print, agent, browser } = {}) => {
 	let pending = diffEvents({
 		...previous,
 		log: []
-	}, previous);
+	}, previous, guide);
 	let timer;
 	const flush = () => {
 		clearTimeout(timer);
@@ -138,13 +149,13 @@ const followSetup = async (client, { print, agent, browser } = {}) => {
 	const runGate = (state) => {
 		for (const action of gate?.update(state) ?? []) {
 			if (action.type === "open") (browser.open ?? openUrl)(action.url);
-			pending.push(gateEvent(action, browser.answerCommand, page(state) ?? ""));
+			pending.push(gateEvent(action, browser.answerCommand, page(state) ?? "", waitCommandFor(browser.answerCommand), guide));
 		}
 	};
 	const unsubscribe = client.subscribe(() => {
 		const next = client.state;
 		if (next === void 0) return;
-		pending.push(...diffEvents(previous, next));
+		pending.push(...diffEvents(previous, next, guide));
 		previous = next;
 		runGate(next);
 		if (pending.length > 0 && timer === void 0) timer = setTimeout(flush, 200);

package/dist/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","names":[],"sources":["../src/stream.ts"],"sourcesContent":["import spawn from \"cross-spawn\";\nimport { detectAgentKind } from \"./agents\";\nimport { createBrowserGate } from \"./browser\";\nimport type { AskReason, BrowserGateAction } from \"./browser\";\nimport type { CheckoutClient } from \"./client\";\nimport { formatTerminalQuestion, terminalQuestion } from \"./needs\";\nimport type { TerminalQuestion } from \"./needs\";\nimport {\n  AGENT_HEARTBEAT_MS,\n  classifyChoiceAnswer,\n  parseMultipleAnswer,\n} from \"./protocol\";\nimport type { Checkout } from \"./protocol\";\n\nexport type StreamEvent =\n  | { event: \"planning.started\" }\n  | { event: \"message.created\"; messageId: string; text: string }\n  | {\n      event: \"input.answered\";\n      inputId: string;\n      prompt: string;\n      /** The entries of a multiple choice answer, else the answer text. */\n      answer: string | string[];\n      note?: string;\n      /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */\n      custom?: true;\n    }\n  | { event: \"input.dismissed\"; inputId: string; prompt: string }\n  | { event: \"plan.approved\"; revision: number }\n  | { event: \"plan.changes-requested\"; revision: number; feedback: string }\n  | { event: \"finished\"; next: string }\n  | { event: \"cancelled\"; next: string }\n  | { event: \"setup.created\"; products: string[] }\n  | {\n      event: \"browser.opened\";\n      /** The need the tab opened for: an input id, plan or finish. */\n      id: string;\n      url: string;\n      message: string;\n    }\n  | ({\n      event: \"input.needed\";\n      id: string;\n      reason: AskReason;\n      message: string;\n      /** The command that answers it, with the answer's shape in angle brackets. */\n      answer: string;\n    } & TerminalQuestion);\n\nconst STAY_CONNECTED =\n  \"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.\";\n\nexport const diffEvents = (\n  before: Checkout.State,\n  after: Checkout.State,\n): StreamEvent[] => {\n  const events: StreamEvent[] = [];\n  if (before.status === \"waiting\" && after.status === \"planning\") {\n    events.push({ event: \"planning.started\" });\n  }\n  for (const entry of after.log) {\n    if (\n      entry.role === \"user\" &&\n      entry.acknowledgedAt === undefined &&\n      !before.log.some((previous) => previous.id === entry.id)\n    ) {\n      events.push({\n        event: \"message.created\",\n        messageId: entry.id,\n        text: entry.text,\n      });\n    }\n  }\n  for (const input of after.inputs) {\n    const previous = before.inputs.find(\n      (candidate) => candidate.id === input.id,\n    );\n    if (previous?.status === input.status) continue;\n    if (input.status === \"answered\") {\n      const answer = input.answer ?? \"\";\n      events.push({\n        event: \"input.answered\",\n        inputId: input.id,\n        prompt: input.prompt,\n        ...answerFields(input, answer),\n      });\n    } else if (input.status === \"dismissed\" && after.status !== \"cancelled\") {\n      events.push({\n        event: \"input.dismissed\",\n        inputId: input.id,\n        prompt: input.prompt,\n      });\n    }\n  }\n  for (const plan of after.plans) {\n    const previous = before.plans.find(\n      (candidate) => candidate.revision === plan.revision,\n    );\n    if (previous?.status === plan.status || plan.status === \"proposed\") {\n      continue;\n    }\n    if (plan.status === \"approved\") {\n      events.push({ event: \"plan.approved\", revision: plan.revision });\n    } else {\n      events.push({\n        event: \"plan.changes-requested\",\n        revision: plan.revision,\n        feedback: plan.feedback ?? \"\",\n      });\n    }\n  }\n  if (before.status !== \"done\" && after.status === \"done\") {\n    events.push({ event: \"finished\", next: STAY_CONNECTED });\n  }\n  if (before.status !== \"cancelled\" && after.status === \"cancelled\") {\n    events.push({ event: \"cancelled\", next: STAY_CONNECTED });\n  }\n  if (after.id !== null && after.id !== before.id) {\n    events.push({\n      event: \"setup.created\",\n      products: after.products.map((product) => product.slug),\n    });\n  }\n  return events;\n};\n\nexport const answerFields = (input: Checkout.Input, answer: string) => ({\n  answer: (input.multiple && parseMultipleAnswer(answer)) || answer,\n  ...(input.note !== undefined && { note: input.note }),\n  ...(input.kind === \"choice\" &&\n    classifyChoiceAnswer(input, answer) === \"custom\" && {\n      custom: true as const,\n    }),\n});\n\n/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */\nexport const setupPageUrl = (\n  setupAppUrl: string,\n  linkId: string,\n  setupId: string,\n) => `${setupAppUrl.replace(/\\/$/, \"\")}/#link=${linkId}&setup=${setupId}`;\n\n/**\n * Opens `url` in the user's default browser without waiting for it.\n * `SETUP_AGENT_BROWSER` names another program to run with the URL instead,\n * such as a test driver.\n */\nconst openUrl = (url: string) => {\n  const custom = process.env.SETUP_AGENT_BROWSER?.trim();\n  const [command, args] = custom\n    ? [custom, [url]]\n    : process.platform === \"darwin\"\n      ? [\"open\", [url]]\n      : process.platform === \"win32\"\n        ? [\"rundll32\", [\"url.dll,FileProtocolHandler\", url]]\n        : [\"xdg-open\", [url]];\n  const child = spawn(command, args, { detached: true, stdio: \"ignore\" });\n  child.on(\"error\", () => {});\n  child.unref();\n};\n\n/** `value` as one shell word, quoted only when it holds more than plain URL characters. */\nexport const shellWord = (value: string) =>\n  /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value)\n    ? value\n    : `'${value.replaceAll(\"'\", `'\\\\''`)}'`;\n\nconst ASK_MESSAGES: Record<\n  AskReason,\n  (question: string, context: { agoSeconds: number; page: string }) => string\n> = {\n  \"recently-opened\": (question, { agoSeconds }) =>\n    `A browser tab for setup was opened ${agoSeconds}s ago. Wait for the user there, or ask the user directly in the terminal: ${question}`,\n  \"browser-closed\": (question) =>\n    `The user closed the setup tab. Ask the user directly in the terminal: ${question}`,\n  \"no-browser\": (question, { page }) =>\n    `No browser tab is open for this setup. Ask the user directly in the terminal, or give them ${page}: ${question}`,\n};\n\n/** What the agent reads when setup opened the browser, or when it should ask the user itself. */\nconst gateEvent = (\n  action: BrowserGateAction,\n  answerCommand: string,\n  page: string,\n): StreamEvent => {\n  const { need } = action;\n  if (action.type === \"open\")\n    return {\n      event: \"browser.opened\",\n      id: need.id,\n      url: action.url,\n      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.`,\n    };\n  const question = terminalQuestion(need);\n  return {\n    event: \"input.needed\",\n    id: need.id,\n    reason: action.reason,\n    message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {\n      agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1000),\n      page,\n    }),\n    ...question,\n    answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,\n  };\n};\n\nexport type FollowSetupOptions = {\n  /** Writes one line of events; the default prints a JSON array to stdout. */\n  print?: (events: StreamEvent[]) => void;\n  /** The agent the stream reports in its hello; detected by default. */\n  agent?: { cwd?: string; kind?: string };\n  /** Opens the setup page when the setup waits on the user; without it, the stream never opens one. */\n  browser?: {\n    setupAppUrl: string;\n    linkId: string;\n    /** The command that answers a need, before the need id: `npx assistant-ui@latest setup <url> answer`. */\n    answerCommand: string;\n    open?: (url: string) => void;\n    /** False for `--no-open`: the agent is told to ask instead. */\n    canOpen?: boolean;\n    now?: () => number;\n  };\n};\n\n/**\n * Follows a setup as the agent: says hello, keeps the agent present with\n * heartbeats, prints what changed as stream events, and opens the browser\n * only when the setup waits on the user. Resolves with `stop`, which says\n * goodbye; the caller disposes the client.\n */\nexport const followSetup = async (\n  client: Pick<CheckoutClient, \"state\" | \"subscribe\" | \"commands\">,\n  { print, agent, browser }: FollowSetupOptions = {},\n) => {\n  const write =\n    print ??\n    ((events: StreamEvent[]) => {\n      process.stdout.write(`${JSON.stringify(events)}\\n`);\n    });\n  const page = (state: Checkout.State) =>\n    browser && state.id !== null\n      ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id)\n      : undefined;\n  const gate =\n    browser &&\n    createBrowserGate({\n      url: page,\n      ...(browser.canOpen !== undefined && { canOpen: browser.canOpen }),\n      ...(browser.now !== undefined && { now: browser.now }),\n    });\n  let previous = client.state;\n  if (previous === undefined) throw new Error(\"the setup has no state\");\n  let pending = diffEvents({ ...previous, log: [] }, previous);\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const flush = () => {\n    clearTimeout(timer);\n    timer = undefined;\n    if (pending.length > 0) write(pending);\n    pending = [];\n  };\n  const runGate = (state: Checkout.State) => {\n    for (const action of gate?.update(state) ?? []) {\n      if (action.type === \"open\") (browser!.open ?? openUrl)(action.url);\n      pending.push(\n        gateEvent(action, browser!.answerCommand, page(state) ?? \"\"),\n      );\n    }\n  };\n  const unsubscribe = client.subscribe(() => {\n    const next = client.state;\n    if (next === undefined) return;\n    pending.push(...diffEvents(previous!, next));\n    previous = next;\n    runGate(next);\n    if (pending.length > 0 && timer === undefined)\n      timer = setTimeout(flush, 200);\n  });\n  runGate(previous);\n  flush();\n  // Presence lapses without a state change, so the gate also looks every second.\n  const tick =\n    gate &&\n    setInterval(() => {\n      runGate(previous!);\n      flush();\n    }, 1_000);\n  const kind = agent?.kind ?? detectAgentKind();\n  try {\n    await client.commands[\"agent/hello\"]({\n      cwd: agent?.cwd ?? process.cwd(),\n      ...(kind !== undefined && { kind }),\n    });\n  } catch (error) {\n    clearInterval(tick);\n    clearTimeout(timer);\n    unsubscribe();\n    throw error;\n  }\n  const heartbeat = setInterval(() => {\n    void client.commands[\"agent/heartbeat\"]().catch(() => {});\n  }, AGENT_HEARTBEAT_MS);\n  let stopped: Promise<void> | undefined;\n  return {\n    stop: () =>\n      (stopped ??= (async () => {\n        clearInterval(heartbeat);\n        clearInterval(tick);\n        unsubscribe();\n        flush();\n        await client.commands[\"agent/bye\"]().catch(() => {});\n      })()),\n  };\n};\n"],"mappings":"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"}
+{"version":3,"file":"stream.js","names":[],"sources":["../src/stream.ts"],"sourcesContent":["import spawn from \"cross-spawn\";\nimport { detectAgentKind } from \"./agents\";\nimport { createBrowserGate } from \"./browser\";\nimport type { AskReason, BrowserGateAction } from \"./browser\";\nimport type { CheckoutClient } from \"./client\";\nimport { formatTerminalQuestion, terminalQuestion } from \"./needs\";\nimport type { TerminalQuestion } from \"./needs\";\nimport {\n  AGENT_HEARTBEAT_MS,\n  classifyChoiceAnswer,\n  parseMultipleAnswer,\n} from \"./protocol\";\nimport type { Checkout } from \"./protocol\";\nimport { renderText } from \"./guide\";\nimport type { Guide } from \"./guide\";\n\nexport type StreamEvent =\n  | { event: \"planning.started\" }\n  | { event: \"message.created\"; messageId: string; text: string }\n  | {\n      event: \"input.answered\";\n      inputId: string;\n      prompt: string;\n      /** The entries of a multiple choice answer, else the answer text. */\n      answer: string | string[];\n      note?: string;\n      /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */\n      custom?: true;\n    }\n  | { event: \"input.dismissed\"; inputId: string; prompt: string }\n  | { event: \"plan.approved\"; revision: number }\n  | { event: \"plan.changes-requested\"; revision: number; feedback: string }\n  | { event: \"finished\"; next: string }\n  | { event: \"cancelled\"; next: string }\n  | { event: \"setup.created\"; products: string[] }\n  | {\n      event: \"browser.opened\";\n      /** The need the tab opened for: an input id, plan or finish. */\n      id: string;\n      url: string;\n      message: string;\n    }\n  | ({\n      event: \"input.needed\";\n      id: string;\n      reason: AskReason;\n      message: string;\n      /** The command that answers it, with the answer's shape in angle brackets. */\n      answer: string;\n    } & TerminalQuestion);\n\n/** The events between two states, with hints worded by the setup server's `guide`. */\nexport const diffEvents = (\n  before: Checkout.State,\n  after: Checkout.State,\n  guide: Pick<Guide, \"texts\">,\n): StreamEvent[] => {\n  const events: StreamEvent[] = [];\n  const stayConnected = renderText(guide, \"stream.stay-connected\");\n  if (before.status === \"waiting\" && after.status === \"planning\") {\n    events.push({ event: \"planning.started\" });\n  }\n  for (const entry of after.log) {\n    if (\n      entry.role === \"user\" &&\n      entry.acknowledgedAt === undefined &&\n      !before.log.some((previous) => previous.id === entry.id)\n    ) {\n      events.push({\n        event: \"message.created\",\n        messageId: entry.id,\n        text: entry.text,\n      });\n    }\n  }\n  for (const input of after.inputs) {\n    const previous = before.inputs.find(\n      (candidate) => candidate.id === input.id,\n    );\n    if (previous?.status === input.status) continue;\n    if (input.status === \"answered\") {\n      const answer = input.answer ?? \"\";\n      events.push({\n        event: \"input.answered\",\n        inputId: input.id,\n        prompt: input.prompt,\n        ...answerFields(input, answer),\n      });\n    } else if (input.status === \"dismissed\" && after.status !== \"cancelled\") {\n      events.push({\n        event: \"input.dismissed\",\n        inputId: input.id,\n        prompt: input.prompt,\n      });\n    }\n  }\n  for (const plan of after.plans) {\n    const previous = before.plans.find(\n      (candidate) => candidate.revision === plan.revision,\n    );\n    if (previous?.status === plan.status || plan.status === \"proposed\") {\n      continue;\n    }\n    if (plan.status === \"approved\") {\n      events.push({ event: \"plan.approved\", revision: plan.revision });\n    } else {\n      events.push({\n        event: \"plan.changes-requested\",\n        revision: plan.revision,\n        feedback: plan.feedback ?? \"\",\n      });\n    }\n  }\n  if (before.status !== \"done\" && after.status === \"done\") {\n    events.push({ event: \"finished\", next: stayConnected });\n  }\n  if (before.status !== \"cancelled\" && after.status === \"cancelled\") {\n    events.push({ event: \"cancelled\", next: stayConnected });\n  }\n  if (after.id !== null && after.id !== before.id) {\n    events.push({\n      event: \"setup.created\",\n      products: after.products.map((product) => product.slug),\n    });\n  }\n  return events;\n};\n\nexport const answerFields = (input: Checkout.Input, answer: string) => ({\n  answer: (input.multiple && parseMultipleAnswer(answer)) || answer,\n  ...(input.note !== undefined && { note: input.note }),\n  ...(input.kind === \"choice\" &&\n    classifyChoiceAnswer(input, answer) === \"custom\" && {\n      custom: true as const,\n    }),\n});\n\n/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */\nexport const setupPageUrl = (\n  setupAppUrl: string,\n  linkId: string,\n  setupId: string,\n) => `${setupAppUrl.replace(/\\/$/, \"\")}/#link=${linkId}&setup=${setupId}`;\n\n/**\n * Opens `url` in the user's default browser without waiting for it.\n * `SETUP_AGENT_BROWSER` names another program to run with the URL instead,\n * such as a test driver.\n */\nconst openUrl = (url: string) => {\n  const custom = process.env.SETUP_AGENT_BROWSER?.trim();\n  const [command, args] = custom\n    ? [custom, [url]]\n    : process.platform === \"darwin\"\n      ? [\"open\", [url]]\n      : process.platform === \"win32\"\n        ? [\"rundll32\", [\"url.dll,FileProtocolHandler\", url]]\n        : [\"xdg-open\", [url]];\n  const child = spawn(command, args, { detached: true, stdio: \"ignore\" });\n  child.on(\"error\", () => {});\n  child.unref();\n};\n\n/** `value` as one shell word, quoted only when it holds more than plain URL characters. */\nexport const shellWord = (value: string) =>\n  /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value)\n    ? value\n    : `'${value.replaceAll(\"'\", `'\\\\''`)}'`;\n\nconst ASK_TEXTS = {\n  \"recently-opened\": \"stream.ask.recently-opened\",\n  \"browser-closed\": \"stream.ask.browser-closed\",\n  \"no-browser\": \"stream.ask.no-browser\",\n} as const satisfies Record<AskReason, string>;\n\n/** The command that blocks on a need, beside the one that answers it: `<cmd> <url> wait`. */\nconst waitCommandFor = (answerCommand: string) =>\n  answerCommand.endsWith(\" answer\")\n    ? `${answerCommand.slice(0, -\" answer\".length)} wait`\n    : undefined;\n\n/** What the agent reads when setup opened the browser, or when it should ask the user itself. */\nconst gateEvent = (\n  action: BrowserGateAction,\n  answerCommand: string,\n  page: string,\n  waitCommand: string | undefined,\n  guide: Pick<Guide, \"texts\">,\n): StreamEvent => {\n  const { need } = action;\n  // Closing the setup is the user's call after \"done\"; there is nothing to block on.\n  const wait =\n    waitCommand !== undefined && need.kind !== \"finish\"\n      ? ` with \"${waitCommand} ${need.id}\"`\n      : \"\";\n  if (action.type === \"open\")\n    return {\n      event: \"browser.opened\",\n      id: need.id,\n      url: action.url,\n      message: renderText(guide, `stream.opened.${need.kind}`, {\n        url: action.url,\n        wait: wait || ' with \"wait\"',\n        prompt:\n          need.kind === \"input\"\n            ? need.input.prompt.trim() ||\n              renderText(guide, \"need.input.empty-prompt\")\n            : \"\",\n      }),\n    };\n  const question = terminalQuestion(need, guide);\n  return {\n    event: \"input.needed\",\n    id: need.id,\n    reason: action.reason,\n    message: renderText(guide, ASK_TEXTS[action.reason], {\n      question: formatTerminalQuestion(question),\n      agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1000),\n      page,\n      wait,\n    }),\n    ...question,\n    answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,\n  };\n};\n\nexport type FollowSetupOptions = {\n  /** The setup server's wording for the stream's messages. */\n  guide: Pick<Guide, \"texts\">;\n  /** Writes one line of events; the default prints a JSON array to stdout. */\n  print?: (events: StreamEvent[]) => void;\n  /** The agent the stream reports in its hello; detected by default. */\n  agent?: { cwd?: string; kind?: string };\n  /** Opens the setup page when the setup waits on the user; without it, the stream never opens one. */\n  browser?: {\n    setupAppUrl: string;\n    linkId: string;\n    /** The command that answers a need, before the need id: `npx assistant-ui@latest setup <url> answer`. */\n    answerCommand: string;\n    open?: (url: string) => void;\n    /** False for `--no-open`: the agent is told to ask instead. */\n    canOpen?: boolean;\n    now?: () => number;\n  };\n};\n\n/**\n * Follows a setup as the agent: says hello, keeps the agent present with\n * heartbeats, prints what changed as stream events, and opens the browser\n * only when the setup waits on the user. Resolves with `stop`, which says\n * goodbye; the caller disposes the client.\n */\nexport const followSetup = async (\n  client: Pick<CheckoutClient, \"state\" | \"subscribe\" | \"commands\">,\n  { print, agent, browser, guide }: FollowSetupOptions,\n) => {\n  const write =\n    print ??\n    ((events: StreamEvent[]) => {\n      process.stdout.write(`${JSON.stringify(events)}\\n`);\n    });\n  const page = (state: Checkout.State) =>\n    browser && state.id !== null\n      ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id)\n      : undefined;\n  const gate =\n    browser &&\n    createBrowserGate({\n      url: page,\n      ...(browser.canOpen !== undefined && { canOpen: browser.canOpen }),\n      ...(browser.now !== undefined && { now: browser.now }),\n    });\n  let previous = client.state;\n  if (previous === undefined) throw new Error(\"the setup has no state\");\n  let pending = diffEvents({ ...previous, log: [] }, previous, guide);\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const flush = () => {\n    clearTimeout(timer);\n    timer = undefined;\n    if (pending.length > 0) write(pending);\n    pending = [];\n  };\n  const runGate = (state: Checkout.State) => {\n    for (const action of gate?.update(state) ?? []) {\n      if (action.type === \"open\") (browser!.open ?? openUrl)(action.url);\n      pending.push(\n        gateEvent(\n          action,\n          browser!.answerCommand,\n          page(state) ?? \"\",\n          waitCommandFor(browser!.answerCommand),\n          guide,\n        ),\n      );\n    }\n  };\n  const unsubscribe = client.subscribe(() => {\n    const next = client.state;\n    if (next === undefined) return;\n    pending.push(...diffEvents(previous!, next, guide));\n    previous = next;\n    runGate(next);\n    if (pending.length > 0 && timer === undefined)\n      timer = setTimeout(flush, 200);\n  });\n  runGate(previous);\n  flush();\n  // Presence lapses without a state change, so the gate also looks every second.\n  const tick =\n    gate &&\n    setInterval(() => {\n      runGate(previous!);\n      flush();\n    }, 1_000);\n  const kind = agent?.kind ?? detectAgentKind();\n  try {\n    await client.commands[\"agent/hello\"]({\n      cwd: agent?.cwd ?? process.cwd(),\n      ...(kind !== undefined && { kind }),\n    });\n  } catch (error) {\n    clearInterval(tick);\n    clearTimeout(timer);\n    unsubscribe();\n    throw error;\n  }\n  const heartbeat = setInterval(() => {\n    void client.commands[\"agent/heartbeat\"]().catch(() => {});\n  }, AGENT_HEARTBEAT_MS);\n  let stopped: Promise<void> | undefined;\n  return {\n    stop: () =>\n      (stopped ??= (async () => {\n        clearInterval(heartbeat);\n        clearInterval(tick);\n        unsubscribe();\n        flush();\n        await client.commands[\"agent/bye\"]().catch(() => {});\n      })()),\n  };\n};\n"],"mappings":";;;;;;;;AAoDA,MAAa,cACX,QACA,OACA,UACkB;CAClB,MAAM,SAAwB,CAAC;CAC/B,MAAM,gBAAgB,WAAW,OAAO,uBAAuB;CAC/D,IAAI,OAAO,WAAW,aAAa,MAAM,WAAW,YAClD,OAAO,KAAK,EAAE,OAAO,mBAAmB,CAAC;CAE3C,KAAK,MAAM,SAAS,MAAM,KACxB,IACE,MAAM,SAAS,UACf,MAAM,mBAAmB,KAAA,KACzB,CAAC,OAAO,IAAI,MAAM,aAAa,SAAS,OAAO,MAAM,EAAE,GAEvD,OAAO,KAAK;EACV,OAAO;EACP,WAAW,MAAM;EACjB,MAAM,MAAM;CACd,CAAC;CAGL,KAAK,MAAM,SAAS,MAAM,QAAQ;EAIhC,IAHiB,OAAO,OAAO,MAC5B,cAAc,UAAU,OAAO,MAAM,EAE7B,CAAC,EAAE,WAAW,MAAM,QAAQ;EACvC,IAAI,MAAM,WAAW,YAAY;GAC/B,MAAM,SAAS,MAAM,UAAU;GAC/B,OAAO,KAAK;IACV,OAAO;IACP,SAAS,MAAM;IACf,QAAQ,MAAM;IACd,GAAG,aAAa,OAAO,MAAM;GAC/B,CAAC;EACH,OAAO,IAAI,MAAM,WAAW,eAAe,MAAM,WAAW,aAC1D,OAAO,KAAK;GACV,OAAO;GACP,SAAS,MAAM;GACf,QAAQ,MAAM;EAChB,CAAC;CAEL;CACA,KAAK,MAAM,QAAQ,MAAM,OAAO;EAI9B,IAHiB,OAAO,MAAM,MAC3B,cAAc,UAAU,aAAa,KAAK,QAElC,CAAC,EAAE,WAAW,KAAK,UAAU,KAAK,WAAW,YACtD;EAEF,IAAI,KAAK,WAAW,YAClB,OAAO,KAAK;GAAE,OAAO;GAAiB,UAAU,KAAK;EAAS,CAAC;OAE/D,OAAO,KAAK;GACV,OAAO;GACP,UAAU,KAAK;GACf,UAAU,KAAK,YAAY;EAC7B,CAAC;CAEL;CACA,IAAI,OAAO,WAAW,UAAU,MAAM,WAAW,QAC/C,OAAO,KAAK;EAAE,OAAO;EAAY,MAAM;CAAc,CAAC;CAExD,IAAI,OAAO,WAAW,eAAe,MAAM,WAAW,aACpD,OAAO,KAAK;EAAE,OAAO;EAAa,MAAM;CAAc,CAAC;CAEzD,IAAI,MAAM,OAAO,QAAQ,MAAM,OAAO,OAAO,IAC3C,OAAO,KAAK;EACV,OAAO;EACP,UAAU,MAAM,SAAS,KAAK,YAAY,QAAQ,IAAI;CACxD,CAAC;CAEH,OAAO;AACT;AAEA,MAAa,gBAAgB,OAAuB,YAAoB;CACtE,QAAS,MAAM,YAAY,oBAAoB,MAAM,KAAM;CAC3D,GAAI,MAAM,SAAS,KAAA,KAAa,EAAE,MAAM,MAAM,KAAK;CACnD,GAAI,MAAM,SAAS,YACjB,qBAAqB,OAAO,MAAM,MAAM,YAAY,EAClD,QAAQ,KACV;AACJ;;AAGA,MAAa,gBACX,aACA,QACA,YACG,GAAG,YAAY,QAAQ,OAAO,EAAE,EAAE,SAAS,OAAO,SAAS;;;;;;AAOhE,MAAM,WAAW,QAAgB;CAC/B,MAAM,SAAS,QAAQ,IAAI,qBAAqB,KAAK;CACrD,MAAM,CAAC,SAAS,QAAQ,SACpB,CAAC,QAAQ,CAAC,GAAG,CAAC,IACd,QAAQ,aAAa,WACnB,CAAC,QAAQ,CAAC,GAAG,CAAC,IACd,QAAQ,aAAa,UACnB,CAAC,YAAY,CAAC,+BAA+B,GAAG,CAAC,IACjD,CAAC,YAAY,CAAC,GAAG,CAAC;CAC1B,MAAM,QAAQ,MAAM,SAAS,MAAM;EAAE,UAAU;EAAM,OAAO;CAAS,CAAC;CACtE,MAAM,GAAG,eAAe,CAAC,CAAC;CAC1B,MAAM,MAAM;AACd;;AAGA,MAAa,aAAa,UACxB,4BAA4B,KAAK,KAAK,IAClC,QACA,IAAI,MAAM,WAAW,KAAK,OAAO,EAAE;AAEzC,MAAM,YAAY;CAChB,mBAAmB;CACnB,kBAAkB;CAClB,cAAc;AAChB;;AAGA,MAAM,kBAAkB,kBACtB,cAAc,SAAS,SAAS,IAC5B,GAAG,cAAc,MAAM,GAAG,EAAiB,EAAE,SAC7C,KAAA;;AAGN,MAAM,aACJ,QACA,eACA,MACA,aACA,UACgB;CAChB,MAAM,EAAE,SAAS;CAEjB,MAAM,OACJ,gBAAgB,KAAA,KAAa,KAAK,SAAS,WACvC,UAAU,YAAY,GAAG,KAAK,GAAG,KACjC;CACN,IAAI,OAAO,SAAS,QAClB,OAAO;EACL,OAAO;EACP,IAAI,KAAK;EACT,KAAK,OAAO;EACZ,SAAS,WAAW,OAAO,iBAAiB,KAAK,QAAQ;GACvD,KAAK,OAAO;GACZ,MAAM,QAAQ;GACd,QACE,KAAK,SAAS,UACV,KAAK,MAAM,OAAO,KAAK,KACvB,WAAW,OAAO,yBAAyB,IAC3C;EACR,CAAC;CACH;CACF,MAAM,WAAW,iBAAiB,MAAM,KAAK;CAC7C,OAAO;EACL,OAAO;EACP,IAAI,KAAK;EACT,QAAQ,OAAO;EACf,SAAS,WAAW,OAAO,UAAU,OAAO,SAAS;GACnD,UAAU,uBAAuB,QAAQ;GACzC,YAAY,KAAK,OAAO,OAAO,eAAe,KAAK,GAAI;GACvD;GACA;EACF,CAAC;EACD,GAAG;EACH,QAAQ,GAAG,cAAc,GAAG,KAAK,GAAG,IAAI,SAAS,aAAa;CAChE;AACF;;;;;;;AA4BA,MAAa,cAAc,OACzB,QACA,EAAE,OAAO,OAAO,SAAS,YACtB;CACH,MAAM,QACJ,WACE,WAA0B;EAC1B,QAAQ,OAAO,MAAM,GAAG,KAAK,UAAU,MAAM,EAAE,GAAG;CACpD;CACF,MAAM,QAAQ,UACZ,WAAW,MAAM,OAAO,OACpB,aAAa,QAAQ,aAAa,QAAQ,QAAQ,MAAM,EAAE,IAC1D,KAAA;CACN,MAAM,OACJ,WACA,kBAAkB;EAChB,KAAK;EACL,GAAI,QAAQ,YAAY,KAAA,KAAa,EAAE,SAAS,QAAQ,QAAQ;EAChE,GAAI,QAAQ,QAAQ,KAAA,KAAa,EAAE,KAAK,QAAQ,IAAI;CACtD,CAAC;CACH,IAAI,WAAW,OAAO;CACtB,IAAI,aAAa,KAAA,GAAW,MAAM,IAAI,MAAM,wBAAwB;CACpE,IAAI,UAAU,WAAW;EAAE,GAAG;EAAU,KAAK,CAAC;CAAE,GAAG,UAAU,KAAK;CAClE,IAAI;CACJ,MAAM,cAAc;EAClB,aAAa,KAAK;EAClB,QAAQ,KAAA;EACR,IAAI,QAAQ,SAAS,GAAG,MAAM,OAAO;EACrC,UAAU,CAAC;CACb;CACA,MAAM,WAAW,UAA0B;EACzC,KAAK,MAAM,UAAU,MAAM,OAAO,KAAK,KAAK,CAAC,GAAG;GAC9C,IAAI,OAAO,SAAS,QAAQ,CAAC,QAAS,QAAQ,QAAA,CAAS,OAAO,GAAG;GACjE,QAAQ,KACN,UACE,QACA,QAAS,eACT,KAAK,KAAK,KAAK,IACf,eAAe,QAAS,aAAa,GACrC,KACF,CACF;EACF;CACF;CACA,MAAM,cAAc,OAAO,gBAAgB;EACzC,MAAM,OAAO,OAAO;EACpB,IAAI,SAAS,KAAA,GAAW;EACxB,QAAQ,KAAK,GAAG,WAAW,UAAW,MAAM,KAAK,CAAC;EAClD,WAAW;EACX,QAAQ,IAAI;EACZ,IAAI,QAAQ,SAAS,KAAK,UAAU,KAAA,GAClC,QAAQ,WAAW,OAAO,GAAG;CACjC,CAAC;CACD,QAAQ,QAAQ;CAChB,MAAM;CAEN,MAAM,OACJ,QACA,kBAAkB;EAChB,QAAQ,QAAS;EACjB,MAAM;CACR,GAAG,GAAK;CACV,MAAM,OAAO,OAAO,QAAQ,gBAAgB;CAC5C,IAAI;EACF,MAAM,OAAO,SAAS,cAAc,CAAC;GACnC,KAAK,OAAO,OAAO,QAAQ,IAAI;GAC/B,GAAI,SAAS,KAAA,KAAa,EAAE,KAAK;EACnC,CAAC;CACH,SAAS,OAAO;EACd,cAAc,IAAI;EAClB,aAAa,KAAK;EAClB,YAAY;EACZ,MAAM;CACR;CACA,MAAM,YAAY,kBAAkB;EAClC,OAAY,SAAS,kBAAkB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;CAC1D,GAAG,kBAAkB;CACrB,IAAI;CACJ,OAAO,EACL,YACG,aAAa,YAAY;EACxB,cAAc,SAAS;EACvB,cAAc,IAAI;EAClB,YAAY;EACZ,MAAM;EACN,MAAM,OAAO,SAAS,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;CACrD,EAAA,CAAG,EACP;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setup-agent",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A live setup shared between a browser and the coding agent installing the products in it, on Statewire",
   "license": "MIT",
   "homepage": "https://www.assistant-ui.com/",
@@ -51,7 +51,7 @@
     "statewire": "^0.22.1"
   },
   "peerDependencies": {
-    "@assistant-ui/tap": "^0.9.25"
+    "@assistant-ui/tap": "^0.9.26"
   },
   "peerDependenciesMeta": {
     "@assistant-ui/tap": {
@@ -59,8 +59,8 @@
     }
   },
   "devDependencies": {
-    "@assistant-ui/tap": "0.9.25",
-    "@assistant-ui/x-buildutils": "0.0.32",
+    "@assistant-ui/tap": "0.9.26",
+    "@assistant-ui/x-buildutils": "0.0.33",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^26.6.5",
     "@types/react": "^19.3.0",

package/src/cli.test.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { connectCheckout } from "./client";
 import { initialCheckoutState, type Checkout } from "./protocol";
+import { testGuide } from "./tests/guide-fixture";
 import { describe, expect, it, onTestFinished, vi } from "vitest";
 import {
   chmod,
@@ -19,10 +20,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   HELP,
-  INSTRUCTIONS,
   main,
   askSeed,
-  agentInstructions,
   diffEvents,
   detectAgentKind,
   isDirectInvocation,
@@ -41,21 +40,115 @@ vi.mock("./client", async (importOriginal) => ({
   connectCheckout: connectCheckoutMock,
 }));
 
-describe("the agent's briefing", () => {
-  it("preserves the published instructions export and setup-created event wording", () => {
-    expect(INSTRUCTIONS).toBe(agentInstructions);
-    expect(typeof HELP).toBe("string");
-    expect(INSTRUCTIONS("https://example.test/session")).toContain(
-      '"setup.created"',
-    );
-    expect(INSTRUCTIONS("https://example.test/session")).not.toContain(
-      '"checkout.created"',
+describe("waiting on the user", () => {
+  // Under the two minutes Claude Code's shell gives a command by default.
+  const DEFAULT_WAIT_SECONDS = 100;
+  const URL = "https://checkout.test/session";
+
+  const connect = () => {
+    const listeners = new Set<() => void>();
+    const state: Checkout.State = {
+      ...initialCheckoutState(),
+      id: "setup-a",
+      createdAt: 1,
+      status: "planning",
+      inputs: [
+        {
+          id: "q1",
+          phase: "planning",
+          kind: "text",
+          prompt: "Which project?",
+          optional: false,
+          status: "open",
+          createdAt: 2,
+        },
+      ],
+    };
+    const client = {
+      state,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      commands: {},
+      dispose: vi.fn(),
+    };
+    connectCheckoutMock.mockResolvedValue(
+      client as unknown as Awaited<ReturnType<typeof connectCheckout>>,
     );
+    const stdout = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    vi.useFakeTimers();
+    onTestFinished(() => {
+      vi.useRealTimers();
+      stdout.mockRestore();
+      connectCheckoutMock.mockReset();
+    });
+    const printed = () =>
+      JSON.parse(String(stdout.mock.lastCall?.[0] ?? "null")) as unknown;
+    const answer = (value: string) => {
+      state.inputs[0]!.status = "answered";
+      state.inputs[0]!.answer = value;
+      for (const listener of listeners) listener();
+    };
+    return { state, printed, answer };
+  };
+
+  it("hands the turn back with the command to run again before an agent shell kills the wait", async () => {
+    const t = connect();
+    const run = main([URL, "wait", "q1"]);
+    await vi.advanceTimersByTimeAsync(DEFAULT_WAIT_SECONDS * 1000 - 1);
+    expect(t.printed()).toBeNull();
+    await vi.advanceTimersByTimeAsync(1);
+    await run;
+    expect(t.printed()).toMatchObject({
+      ok: false,
+      status: "waiting",
+      waitingFor: "q1",
+      next: `npx setup-agent ${URL} wait q1`,
+    });
   });
 
-  it("describes a setup without the wording of a purchase", () => {
-    const briefing = HELP + INSTRUCTIONS("https://example.test/session");
-    expect(briefing).not.toMatch(/\b(?:cart|shop|checkout|purchase)\b/i);
+  it("hands back a plan wait as wait plan, so the agent does not submit the plan again", async () => {
+    const t = connect();
+    t.state.plans.push({
+      revision: 1,
+      markdown: "## Steps",
+      status: "proposed",
+      submittedAt: 3,
+    });
+    const run = main([URL, "wait", "plan"]);
+    await vi.advanceTimersByTimeAsync(DEFAULT_WAIT_SECONDS * 1000);
+    await run;
+    expect(t.printed()).toMatchObject({
+      ok: false,
+      status: "waiting",
+      waitingFor: "plan",
+      next: `npx setup-agent ${URL} wait plan`,
+    });
+  });
+
+  it("prints the answer when it arrives in time", async () => {
+    const t = connect();
+    const run = main([URL, "wait", "q1"]);
+    await vi.advanceTimersByTimeAsync(5_000);
+    t.answer("apps/web");
+    await run;
+    expect(t.printed()).toMatchObject({
+      ok: true,
+      inputId: "q1",
+      status: "answered",
+      answer: "apps/web",
+    });
+  });
+
+  it("waits as long as it takes with --timeout 0", async () => {
+    const t = connect();
+    const run = main([URL, "wait", "q1", "--timeout", "0"]);
+    await vi.advanceTimersByTimeAsync(DEFAULT_WAIT_SECONDS * 1000 * 5);
+    expect(t.printed()).toBeNull();
+    t.answer("apps/web");
+    await run;
+    expect(t.printed()).toMatchObject({ ok: true, answer: "apps/web" });
   });
 });
 
@@ -437,10 +530,10 @@ describe("chat stream events", () => {
         },
       ],
     };
-    expect(diffEvents(before, after)).toEqual([
+    expect(diffEvents(before, after, testGuide)).toEqual([
       { event: "message.created", messageId: "l2", text: "Use pnpm" },
     ]);
-    expect(diffEvents(after, after)).toEqual([]);
+    expect(diffEvents(after, after, testGuide)).toEqual([]);
   });
 });
 
@@ -465,7 +558,9 @@ describe("begin planning", () => {
       ...before,
       inputs: [{ ...asked, status: "answered", answer, answeredAt: 2 }],
     });
-    expect(diffEvents(before, answered('["slack","email"]'))).toEqual([
+    expect(
+      diffEvents(before, answered('["slack","email"]'), testGuide),
+    ).toEqual([
       {
         event: "input.answered",
         inputId: "q1",
@@ -473,7 +568,9 @@ describe("begin planning", () => {
         answer: ["slack", "email"],
       },
     ]);
-    expect(diffEvents(before, answered('["email","Discord"]'))).toEqual([
+    expect(
+      diffEvents(before, answered('["email","Discord"]'), testGuide),
+    ).toEqual([
       {
         event: "input.answered",
         inputId: "q1",
@@ -490,18 +587,18 @@ describe("begin planning", () => {
       ...waiting,
       agent: { ...waiting.agent, connected: true, lastSeenAt: 1 },
     };
-    expect(diffEvents(waiting, connected)).toEqual([]);
+    expect(diffEvents(waiting, connected, testGuide)).toEqual([]);
     const planning: Checkout.State = { ...connected, status: "planning" };
-    expect(diffEvents(connected, planning)).toEqual([
+    expect(diffEvents(connected, planning, testGuide)).toEqual([
       { event: "planning.started" },
     ]);
-    expect(diffEvents(planning, planning)).toEqual([]);
-    expect(diffEvents(waiting, { ...waiting, status: "done" })).toEqual([
-      { event: "finished", next: expect.stringContaining("Keep the stream") },
-    ]);
-    expect(diffEvents(waiting, { ...waiting, status: "cancelled" })).toEqual([
-      { event: "cancelled", next: expect.stringContaining("Keep the stream") },
-    ]);
+    expect(diffEvents(planning, planning, testGuide)).toEqual([]);
+    expect(
+      diffEvents(waiting, { ...waiting, status: "done" }, testGuide),
+    ).toEqual([{ event: "finished", next: "[stream.stay-connected]" }]);
+    expect(
+      diffEvents(waiting, { ...waiting, status: "cancelled" }, testGuide),
+    ).toEqual([{ event: "cancelled", next: "[stream.stay-connected]" }]);
   });
 
   it("announces the next setup the browser creates on the same link", () => {
@@ -516,13 +613,13 @@ describe("begin planning", () => {
       id: "c2",
       products: [{ slug: "cloud", name: "Cloud" }],
     };
-    expect(diffEvents(done, next)).toEqual([
+    expect(diffEvents(done, next, testGuide)).toEqual([
       { event: "setup.created", products: ["cloud"] },
     ]);
-    expect(diffEvents(next, next)).toEqual([]);
-    expect(diffEvents(initialCheckoutState(), initialCheckoutState())).toEqual(
-      [],
-    );
+    expect(diffEvents(next, next, testGuide)).toEqual([]);
+    expect(
+      diffEvents(initialCheckoutState(), initialCheckoutState(), testGuide),
+    ).toEqual([]);
   });
 
   it.each(["planning", "cancelled"] as const)(
@@ -601,90 +698,6 @@ describe("begin planning", () => {
   );
 });
 
-describe("agent instructions", () => {
-  it("goes straight to planning for a setup the agent started", () => {
-    const browserUrl =
-      "https://setup.assistant-ui.com/#link=abc12345&setup=def67890";
-    const started = agentInstructions("https://setup.test/abc12345", {
-      startedByAgent: { browserUrl },
-    });
-    expect(started).not.toContain("click Begin plan");
-    expect(started).not.toContain("wait start\nKeep the stream running");
-    expect(started).toContain("there is no Begin plan click to wait for");
-    expect(started).toContain(browserUrl);
-    expect(started).toContain("a setup you opened in the user's browser");
-    const opened = agentInstructions("https://setup.test/abc12345");
-    expect(opened).toContain("click Begin plan");
-    expect(opened).toContain("a setup the user opened in their browser");
-  });
-
-  it("asks what to set up when the setup has no products", () => {
-    expect(agentInstructions("https://setup.test/s")).toContain(
-      "If the setup lists no products, first ask the user what to set up",
-    );
-  });
-
-  it("prints a setup URL as one quoted shell word", () => {
-    const instructions = agentInstructions("https://checkout.test/a'b;c");
-    expect(instructions).toContain(
-      "npx setup-agent 'https://checkout.test/a'\\''b;c' stream",
-    );
-    expect(instructions).not.toContain(
-      "npx setup-agent https://checkout.test/a'",
-    );
-    expect(agentInstructions("https://checkout.test/s")).toContain(
-      "npx setup-agent https://checkout.test/s stream",
-    );
-  });
-
-  it("discovers related products and asks contextual entry points before the plan", () => {
-    const instructions = agentInstructions(
-      "http://localhost:18892/checkout/session",
-    );
-    expect(instructions).toContain(
-      "products are starting names and guide references",
-    );
-    expect(instructions).toContain(
-      "The starting list does not restrict the implementation",
-    );
-    expect(instructions).toContain("only 1–3 sensible alternatives");
-    expect(instructions).toContain(
-      "two options may use the same form factor in different places",
-    );
-    expect(instructions).toContain("--entry-points '<JSON array>'");
-    expect(instructions).not.toContain("--product assistant-ui");
-    expect(instructions.indexOf("--entry-points")).toBeLessThan(
-      instructions.indexOf("plan --file"),
-    );
-  });
-
-  it("waits for the entry-point answer before the plan is submitted", () => {
-    const ask = agentInstructions("http://localhost:18892/checkout/session")
-      .split("\n")
-      .find((line) => line.includes("--entry-points '<JSON array>'"));
-    expect(ask?.trim().endsWith("--wait")).toBe(true);
-    expect(ask).not.toContain("--default");
-  });
-
-  it("skips the entry-point question for a setup that puts no assistant in the app", () => {
-    const instructions = agentInstructions(
-      "http://localhost:18892/checkout/session",
-    );
-    expect(instructions).toContain(
-      "When the setup puts an assistant in the app, ask how users should access it",
-    );
-    expect(instructions).toContain(
-      "Skip this question when no product's guide installs an assistant",
-    );
-    expect(instructions).toContain(
-      "When you ask it, do not submit the plan before the user picks an entry point.",
-    );
-    expect(instructions).not.toContain(
-      "recommendation. Do not submit the plan before the user picks an entry point.",
-    );
-  });
-});
-
 describe("writeEnvSecret", () => {
   const tempDir = async () => {
     const dir = await mkdtemp(join(tmpdir(), "setup-agent-"));