setup-agent 0.0.9 → 0.1.0

package/dist/stream.d.ts

@@ -0,0 +1,93 @@
+import type { AskReason } from "./browser.js";
+import type { CheckoutClient } from "./client.js";
+import type { TerminalQuestion } from "./needs.js";
+import type { Checkout } from "./protocol.js";
+export type StreamEvent = {
+    event: "planning.started";
+} | {
+    event: "message.created";
+    messageId: string;
+    text: string;
+} | {
+    event: "input.answered";
+    inputId: string;
+    prompt: string;
+    /** The entries of a multiple choice answer, else the answer text. */
+    answer: string | string[];
+    note?: string;
+    /** True when a choice answer is, or a multiple one contains, the user's own text rather than an option. */
+    custom?: true;
+} | {
+    event: "input.dismissed";
+    inputId: string;
+    prompt: string;
+} | {
+    event: "plan.approved";
+    revision: number;
+} | {
+    event: "plan.changes-requested";
+    revision: number;
+    feedback: string;
+} | {
+    event: "finished";
+    next: string;
+} | {
+    event: "cancelled";
+    next: string;
+} | {
+    event: "setup.created";
+    products: string[];
+} | {
+    event: "browser.opened";
+    /** The need the tab opened for: an input id, plan or finish. */
+    id: string;
+    url: string;
+    message: string;
+} | ({
+    event: "input.needed";
+    id: string;
+    reason: AskReason;
+    message: string;
+    /** The command that answers it, with the answer's shape in angle brackets. */
+    answer: string;
+} & TerminalQuestion);
+export declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
+export declare const answerFields: (input: Checkout.Input, answer: string) => {
+    custom?: true;
+    note?: string;
+    answer: string | string[];
+};
+/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */
+export declare const setupPageUrl: (setupAppUrl: string, linkId: string, setupId: string) => string;
+/** `value` as one shell word, quoted only when it holds more than plain URL characters. */
+export declare const shellWord: (value: string) => string;
+export type FollowSetupOptions = {
+    /** 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. */
+    agent?: {
+        cwd?: string;
+        kind?: string;
+    };
+    /** Opens the setup page when the setup waits on the user; without it, the stream never opens one. */
+    browser?: {
+        setupAppUrl: string;
+        linkId: string;
+        /** The command that answers a need, before the need id: `npx assistant-ui@latest setup <url> answer`. */
+        answerCommand: string;
+        open?: (url: string) => void;
+        /** False for `--no-open`: the agent is told to ask instead. */
+        canOpen?: boolean;
+        now?: () => number;
+    };
+};
+/**
+ * Follows a setup as the agent: says hello, keeps the agent present with
+ * heartbeats, prints what changed as stream events, and opens the browser
+ * only when the setup waits on the user. Resolves with `stop`, which says
+ * goodbye; the caller disposes the client.
+ */
+export declare const followSetup: (client: Pick<CheckoutClient, "state" | "subscribe" | "commands">, { print, agent, browser }?: FollowSetupOptions) => Promise<{
+    stop: () => Promise<void>;
+}>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"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"}

package/dist/stream.js

@@ -0,0 +1,184 @@
+import { detectAgentKind } from "./agents.js";
+import { AGENT_HEARTBEAT_MS, classifyChoiceAnswer, parseMultipleAnswer } from "./protocol.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) => {
+	const events = [];
+	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",
+		messageId: entry.id,
+		text: entry.text
+	});
+	for (const input of after.inputs) {
+		if (before.inputs.find((candidate) => candidate.id === input.id)?.status === input.status) continue;
+		if (input.status === "answered") {
+			const answer = input.answer ?? "";
+			events.push({
+				event: "input.answered",
+				inputId: input.id,
+				prompt: input.prompt,
+				...answerFields(input, answer)
+			});
+		} else if (input.status === "dismissed" && after.status !== "cancelled") events.push({
+			event: "input.dismissed",
+			inputId: input.id,
+			prompt: input.prompt
+		});
+	}
+	for (const plan of after.plans) {
+		if (before.plans.find((candidate) => candidate.revision === plan.revision)?.status === plan.status || plan.status === "proposed") continue;
+		if (plan.status === "approved") events.push({
+			event: "plan.approved",
+			revision: plan.revision
+		});
+		else events.push({
+			event: "plan.changes-requested",
+			revision: plan.revision,
+			feedback: plan.feedback ?? ""
+		});
+	}
+	if (before.status !== "done" && after.status === "done") events.push({
+		event: "finished",
+		next: STAY_CONNECTED
+	});
+	if (before.status !== "cancelled" && after.status === "cancelled") events.push({
+		event: "cancelled",
+		next: STAY_CONNECTED
+	});
+	if (after.id !== null && after.id !== before.id) events.push({
+		event: "setup.created",
+		products: after.products.map((product) => product.slug)
+	});
+	return events;
+};
+const answerFields = (input, answer) => ({
+	answer: input.multiple && parseMultipleAnswer(answer) || answer,
+	...input.note !== void 0 && { note: input.note },
+	...input.kind === "choice" && classifyChoiceAnswer(input, answer) === "custom" && { custom: true }
+});
+/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */
+const setupPageUrl = (setupAppUrl, linkId, setupId) => `${setupAppUrl.replace(/\/$/, "")}/#link=${linkId}&setup=${setupId}`;
+/**
+* Opens `url` in the user's default browser without waiting for it.
+* `SETUP_AGENT_BROWSER` names another program to run with the URL instead,
+* such as a test driver.
+*/
+const openUrl = (url) => {
+	const custom = process.env.SETUP_AGENT_BROWSER?.trim();
+	const [command, args] = custom ? [custom, [url]] : process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+	const child = spawn(command, args, {
+		detached: true,
+		stdio: "ignore"
+	});
+	child.on("error", () => {});
+	child.unref();
+};
+/** `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}`
+};
+/** What the agent reads when setup opened the browser, or when it should ask the user itself. */
+const gateEvent = (action, answerCommand, page) => {
+	const { need } = action;
+	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.`
+	};
+	const question = terminalQuestion(need);
+	return {
+		event: "input.needed",
+		id: need.id,
+		reason: action.reason,
+		message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {
+			agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1e3),
+			page
+		}),
+		...question,
+		answer: `${answerCommand} ${need.id} <${question.answerFormat}>`
+	};
+};
+/**
+* Follows a setup as the agent: says hello, keeps the agent present with
+* heartbeats, prints what changed as stream events, and opens the browser
+* 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 write = print ?? ((events) => {
+		process.stdout.write(`${JSON.stringify(events)}\n`);
+	});
+	const page = (state) => browser && state.id !== null ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id) : void 0;
+	const gate = browser && createBrowserGate({
+		url: page,
+		...browser.canOpen !== void 0 && { canOpen: browser.canOpen },
+		...browser.now !== void 0 && { now: browser.now }
+	});
+	let previous = client.state;
+	if (previous === void 0) throw new Error("the setup has no state");
+	let pending = diffEvents({
+		...previous,
+		log: []
+	}, previous);
+	let timer;
+	const flush = () => {
+		clearTimeout(timer);
+		timer = void 0;
+		if (pending.length > 0) write(pending);
+		pending = [];
+	};
+	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) ?? ""));
+		}
+	};
+	const unsubscribe = client.subscribe(() => {
+		const next = client.state;
+		if (next === void 0) return;
+		pending.push(...diffEvents(previous, next));
+		previous = next;
+		runGate(next);
+		if (pending.length > 0 && timer === void 0) timer = setTimeout(flush, 200);
+	});
+	runGate(previous);
+	flush();
+	const tick = gate && setInterval(() => {
+		runGate(previous);
+		flush();
+	}, 1e3);
+	const kind = agent?.kind ?? detectAgentKind();
+	try {
+		await client.commands["agent/hello"]({
+			cwd: agent?.cwd ?? process.cwd(),
+			...kind !== void 0 && { kind }
+		});
+	} catch (error) {
+		clearInterval(tick);
+		clearTimeout(timer);
+		unsubscribe();
+		throw error;
+	}
+	const heartbeat = setInterval(() => {
+		client.commands["agent/heartbeat"]().catch(() => {});
+	}, AGENT_HEARTBEAT_MS);
+	let stopped;
+	return { stop: () => stopped ??= (async () => {
+		clearInterval(heartbeat);
+		clearInterval(tick);
+		unsubscribe();
+		flush();
+		await client.commands["agent/bye"]().catch(() => {});
+	})() };
+};
+export { answerFields, diffEvents, followSetup, setupPageUrl, shellWord };
+
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "setup-agent",
-  "version": "0.0.9",
+  "version": "0.1.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/",
@@ -25,6 +25,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
+    },
     "./host": {
       "types": "./dist/host.d.ts",
       "default": "./dist/host.js"

package/src/browser.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from "vitest";
+import {
+  BROWSER_CLOSE_GRACE_MS,
+  BROWSER_REOPEN_GUARD_MS,
+  createBrowserGate,
+} from "./browser";
+import { initialCheckoutState } from "./protocol";
+import type { Checkout } from "./protocol";
+
+const PAGE = "https://setup.test/#link=abc&setup=s1";
+const open = { type: "open", url: PAGE };
+
+/** A gate on a fake clock, with a setup the test asks questions on and a tab it opens and closes. */
+const fixture = (options: { canOpen?: boolean; tracked?: boolean } = {}) => {
+  let clock = 1_000_000;
+  const state: Checkout.State = {
+    ...initialCheckoutState(),
+    id: "s1",
+    createdAt: 1,
+    status: "planning",
+  };
+  if (options.tracked === false) delete state.browser;
+  const gate = createBrowserGate({
+    url: () => PAGE,
+    now: () => clock,
+    ...(options.canOpen !== undefined && { canOpen: options.canOpen }),
+  });
+  return {
+    state,
+    advance: (ms: number) => (clock += ms),
+    update: () => gate.update(structuredClone(state)),
+    ask: (prompt = "Which project?") =>
+      state.inputs.push({
+        id: `q${state.inputs.length + 1}`,
+        phase: "planning",
+        kind: "text",
+        prompt,
+        optional: false,
+        status: "open",
+        createdAt: clock,
+      }),
+    answerAll: () =>
+      state.inputs.forEach((input) => (input.status = "answered")),
+    heartbeat: () => (state.browser = { lastSeenAt: clock, connected: true }),
+    bye: () => (state.browser!.connected = false),
+  };
+};
+
+describe("createBrowserGate", () => {
+  it("opens nothing until the setup needs the user, then one tab for everything waiting", () => {
+    const t = fixture();
+    expect(t.update()).toEqual([]);
+    t.advance(60_000);
+    expect(t.update()).toEqual([]);
+    t.ask();
+    t.ask();
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        ...open,
+        need: expect.objectContaining({ id: "q1" }),
+      }),
+    ]);
+    expect(t.update()).toEqual([]);
+  });
+
+  it("opens nothing while a joined tab is present", () => {
+    const t = fixture();
+    t.heartbeat();
+    t.update();
+    t.ask();
+    expect(t.update()).toEqual([]);
+  });
+
+  it("never opens a second tab within 30 seconds, nor reopens one that never joined", () => {
+    const t = fixture();
+    t.ask();
+    t.update();
+    t.advance(12_000);
+    t.ask();
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        type: "ask",
+        reason: "recently-opened",
+        openedAgoMs: 12_000,
+      }),
+    ]);
+    // 30s on, the tab never joined: what waits is handed to the agent once.
+    t.advance(18_000);
+    // q2 was already handed over at 12s, so only q1 is.
+    expect(t.update().map((action) => action.need.id)).toEqual(["q1"]);
+    expect(t.update()).toEqual([]);
+    // It is still not a close, so a later need is not a reason to reopen.
+    t.advance(65_000);
+    t.ask();
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        type: "ask",
+        reason: "recently-opened",
+        openedAgoMs: 95_000,
+      }),
+    ]);
+  });
+
+  it("reports a known-closed tab as closed inside the window, then reopens for the next need", () => {
+    const t = fixture();
+    t.ask();
+    t.update();
+    t.advance(2_000);
+    t.heartbeat();
+    t.update();
+    t.answerAll();
+    t.bye();
+    t.update();
+    t.advance(BROWSER_CLOSE_GRACE_MS);
+    expect(t.update()).toEqual([]);
+    t.ask();
+    expect(t.update()).toEqual([
+      expect.objectContaining({ type: "ask", reason: "browser-closed" }),
+    ]);
+    t.answerAll();
+    t.advance(BROWSER_REOPEN_GUARD_MS);
+    t.ask();
+    expect(t.update()).toEqual([expect.objectContaining(open)]);
+  });
+
+  it("counts a tab that stopped beating as closed, and tells the agent once when a question was waiting", () => {
+    const t = fixture();
+    t.ask();
+    t.update();
+    t.advance(1_000);
+    t.heartbeat();
+    t.update();
+    // No goodbye: the beats just stop. One missed beat is not a close.
+    t.advance(20_000 + 1_000);
+    expect(t.update()).toEqual([]);
+    t.advance(BROWSER_CLOSE_GRACE_MS);
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        type: "ask",
+        reason: "browser-closed",
+        need: expect.objectContaining({ id: "q1" }),
+      }),
+    ]);
+    expect(t.update()).toEqual([]);
+    t.advance(BROWSER_REOPEN_GUARD_MS);
+    t.ask();
+    expect(t.update()).toEqual([expect.objectContaining(open)]);
+  });
+
+  it("asks the agent for every question under --no-open", () => {
+    const t = fixture({ canOpen: false });
+    t.ask();
+    t.ask();
+    expect(
+      t.update().map((action) => action.type === "ask" && action.reason),
+    ).toEqual(["no-browser", "no-browser"]);
+  });
+
+  it("on a host without browser presence, opens once and then lets the agent ask", () => {
+    const t = fixture({ tracked: false });
+    t.ask();
+    expect(t.update()).toEqual([expect.objectContaining(open)]);
+    t.advance(120_000);
+    t.ask();
+    expect(
+      t.update().map((action) => action.type === "ask" && action.reason),
+    ).toEqual(["recently-opened", "recently-opened"]);
+  });
+
+  it("treats a proposed plan and a proposal to close as needs", () => {
+    const t = fixture();
+    t.state.plans.push({
+      revision: 1,
+      markdown: "x",
+      status: "proposed",
+      submittedAt: 1,
+    });
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        need: expect.objectContaining({ id: "plan" }),
+      }),
+    ]);
+    t.state.plans[0]!.status = "approved";
+    t.state.status = "installing";
+    t.state.completion = { proposedAt: 5 };
+    expect(t.update()).toEqual([
+      expect.objectContaining({
+        need: expect.objectContaining({ id: "finish" }),
+      }),
+    ]);
+  });
+});

package/src/browser.ts

@@ -0,0 +1,146 @@
+import { needKey, pendingNeeds } from "./needs";
+import type { SetupNeed } from "./needs";
+import { BROWSER_HEARTBEAT_MS, BROWSER_PRESENCE_MS } from "./protocol";
+import type { Checkout } from "./protocol";
+
+/** Within this long of opening a tab, setup never opens another. */
+export const BROWSER_REOPEN_GUARD_MS = 30_000;
+/** A page silent this long after it was present counts as closed; one heartbeat gap is not enough. */
+export const BROWSER_CLOSE_GRACE_MS = BROWSER_HEARTBEAT_MS + 1_000;
+
+/**
+ * Why the agent should ask the user itself:
+ * - recently-opened: a tab was opened moments ago, or opened and never joined;
+ * - browser-closed: the user closed the setup tab (and it may not reopen yet);
+ * - no-browser: setup may not open a browser (`--no-open`).
+ */
+export type AskReason = "recently-opened" | "browser-closed" | "no-browser";
+
+export type BrowserGateAction =
+  | { type: "open"; url: string; need: SetupNeed }
+  | { type: "ask"; reason: AskReason; need: SetupNeed; openedAgoMs?: number };
+
+/**
+ * Decides when setup opens the user's browser: only once the setup waits on
+ * the user, never while a joined tab is present, never twice within the
+ * guard window, and again for a later need once a joined tab went away.
+ * Presence is measured on this machine's clock from when each heartbeat
+ * arrived, so a skewed server clock does not matter.
+ */
+export const createBrowserGate = ({
+  url,
+  canOpen = true,
+  now = Date.now,
+}: {
+  /** The setup page for a state; `undefined` when there is none to open. */
+  url: (state: Checkout.State) => string | undefined;
+  /** False for `--no-open`: the agent is told to ask instead. */
+  canOpen?: boolean;
+  now?: () => number;
+}) => {
+  const handled = new Set<string>();
+  /** Needs the agent was already told to ask about. */
+  const told = new Set<string>();
+  let openedAt: number | undefined;
+  let joinedSinceOpen = false;
+  let lastBeat: number | null | undefined;
+  let beatArrivedAt: number | undefined;
+  let present = false;
+  let absentSince: number | undefined;
+  let closedReported = true;
+  let joinTimeoutReported = true;
+
+  const trackPresence = (browser: Checkout.State["browser"]) => {
+    if (browser === undefined) return;
+    const time = now();
+    if (browser.lastSeenAt !== lastBeat) {
+      // Every beat, the first one included, counts from when it arrived here.
+      beatArrivedAt = browser.lastSeenAt === null ? undefined : time;
+      lastBeat = browser.lastSeenAt;
+    }
+    if (
+      browser.connected &&
+      beatArrivedAt !== undefined &&
+      time - beatArrivedAt < BROWSER_PRESENCE_MS
+    ) {
+      present = joinedSinceOpen = true;
+      absentSince = undefined;
+      closedReported = false;
+    } else if (present || absentSince !== undefined) {
+      // A page that went quiet left when its last beat expired, not when this noticed.
+      absentSince ??=
+        browser.connected && beatArrivedAt !== undefined
+          ? Math.min(time, beatArrivedAt + BROWSER_PRESENCE_MS)
+          : time;
+      present = false;
+    }
+  };
+
+  return {
+    update: (state: Checkout.State): BrowserGateAction[] => {
+      trackPresence(state.browser);
+      const time = now();
+      const needs = pendingNeeds(state);
+      const keys = new Set(needs.map(needKey));
+      for (const key of handled) if (!keys.has(key)) handled.delete(key);
+      for (const key of told) if (!keys.has(key)) told.delete(key);
+      // Present, or gone too briefly to call it closed.
+      const looksPresent =
+        present ||
+        (absentSince !== undefined &&
+          time - absentSince < BROWSER_CLOSE_GRACE_MS);
+      const closed = !looksPresent && absentSince !== undefined;
+      const ask = (need: SetupNeed, reason: AskReason): BrowserGateAction => {
+        told.add(needKey(need));
+        return {
+          type: "ask",
+          reason,
+          need,
+          ...(reason === "recently-opened" && {
+            openedAgoMs: time - openedAt!,
+          }),
+        };
+      };
+      const actions: BrowserGateAction[] = [];
+      if (closed && !closedReported) {
+        // The tab closed while the user had something to answer there.
+        closedReported = true;
+        for (const need of needs)
+          if (handled.has(needKey(need)))
+            actions.push(ask(need, "browser-closed"));
+      }
+
+      if (
+        !joinTimeoutReported &&
+        !joinedSinceOpen &&
+        time - openedAt! >= BROWSER_REOPEN_GUARD_MS
+      ) {
+        // The opened tab never joined: it did not open, or the user left it.
+        joinTimeoutReported = true;
+        for (const need of needs)
+          if (handled.has(needKey(need)) && !told.has(needKey(need)))
+            actions.push(ask(need, "recently-opened"));
+      }
+
+      const fresh = needs.filter((need) => !handled.has(needKey(need)));
+      for (const need of fresh) handled.add(needKey(need));
+      if (fresh.length === 0 || looksPresent) return actions;
+      const target = canOpen ? url(state) : undefined;
+      if (target === undefined)
+        return [...actions, ...fresh.map((need) => ask(need, "no-browser"))];
+      if (
+        openedAt === undefined ||
+        (time - openedAt >= BROWSER_REOPEN_GUARD_MS && joinedSinceOpen)
+      ) {
+        openedAt = time;
+        joinedSinceOpen = false;
+        joinTimeoutReported = false;
+        // One tab shows every waiting question.
+        return [...actions, { type: "open", url: target, need: fresh[0]! }];
+      }
+      const reason =
+        closed && joinedSinceOpen ? "browser-closed" : "recently-opened";
+      return [...actions, ...fresh.map((need) => ask(need, reason))];
+    },
+  };
+};