setup-agent 0.1.0 → 0.1.2

package/src/cli.ts

@@ -41,6 +41,15 @@ export { diffEvents } from "./stream";
 
 const DEFAULT_COMMAND = "npx setup-agent";
 
+/**
+ * How long "wait <input-id>", "wait plan" and "--wait" block before handing
+ * control back with a "waiting" result, in seconds. Agent shells kill a
+ * command after a limit of their own (two minutes by default in Claude
+ * Code); a wait that returns first lets the agent run it again instead of
+ * reading the kill as the end of the setup.
+ */
+const DEFAULT_WAIT_SECONDS = 100;
+
 export const HELP = `setup-agent <url> [command]
 
 Commands (the url always comes first):
@@ -65,10 +74,13 @@ Commands (the url always comes first):
   ask <prompt> --entry-points '<JSON array>' [--default <id>] [--optional] [--step <step-id>] [--wait]
                                     Ask where users should access the assistant. Each of 1–3 options has id, label, description and entryPoint {formFactor: modal|sidebar|full-page, placement, trigger, recommended?}. Answers one option id.
   wait start                        Block until the user clicks Begin plan in their browser; after a finished or cancelled setup, until the next one begins.
-  wait <input-id>                   Block until the user answers or dismisses an input. A multi-select answer prints as an array.
-  plan (<markdown> | --file <path>) [--wait]
+  wait <input-id> [--timeout <seconds>]
+                                    Block until the user answers or dismisses an input. A multi-select answer prints as an array.
+  plan (<markdown> | --file <path>) [--wait] [--timeout <seconds>]
                                     Propose the plan for the user to approve. --wait blocks until they decide.
-  wait plan                         Block until the user approves the plan or asks for changes.
+  wait plan [--timeout <seconds>]   Block until the user approves the plan or asks for changes.
+                                    wait <input-id>, wait plan and every --wait give up after ${DEFAULT_WAIT_SECONDS}s (--timeout, 0 for no limit) and print
+                                    {"ok":false,"status":"waiting","next":"<command>"}: run "next" again to keep waiting.
   env <input-id> <ENV_VAR> [--file <path>]
                                     Write the API key behind an answered llm-provider input to an env file (default .env.local) as ENV_VAR=<key>, without printing it.
   add-step <title> [--detail <text>] [--product <slug>] [--active]
@@ -166,9 +178,9 @@ const streamSection = (
   noOpen: boolean,
 ) =>
   streaming
-    ? `The command that printed this is the stream. Keep it running in the background until the setup ends: the browser shows you as connected only while it runs, and it is how answers reach you. Each new line of its output is a JSON array of events: ${EVENT_LIST}, plus:
-- "browser.opened" ({id, message}): setup opened the setup page in the user's browser for a question. Tell the user once, in your own conversation, that it waits there.
-- "input.needed" ({id, message, question, options?, answer}): the user may not see the browser right now. Do what its message says: wait for "input.answered", or ask the user in your own conversation with that question and options, then run its "answer" command with their reply. Answered either way, the setup goes on.
+    ? `The command that printed this is the stream. Keep it running in the background until the setup ends: the browser shows you as connected only while it runs. New output does not wake you: read its new lines between your other commands. Each new line is a JSON array of events: ${EVENT_LIST}, plus:
+- "browser.opened" ({id, message}): setup opened the setup page in the user's browser for a question. Tell the user once, in your own conversation, that it waits there, and keep working in the same turn.
+- "input.needed" ({id, message, question, options?, answer}): the user may not see the browser right now. Do what its message says: run "wait <id>" for their answer in the browser, or ask the user in your own conversation with that question and options, then run its "answer" command with their reply. Answered either way, the setup goes on.
 If this command stops, start it again in the background with
   ${cmd} ${url} stream${noOpen ? " --no-open" : ""}
 The URL is the user's link to you from their browser, not one setup: it outlives this one, and their next setup arrives on the same stream.`
@@ -176,6 +188,12 @@ The URL is the user's link to you from their browser, not one setup: it outlives
   ${cmd} ${url} stream
 and keep it running: the browser shows you as connected only while it runs, and it is how answers reach you. The URL is the user's link to you from their browser, not one setup: it outlives this one, and their next setup arrives on the same stream. Each line is a JSON array of events: ${EVENT_LIST}.`;
 
+/** Why the agent must not end its turn mid-setup, and how it waits instead. */
+const keepGoing = (cmd: string, url: string) =>
+  `Run the setup to the end in one go. Do not count on the stream or the browser to wake you: if you end your turn before the install is done, the setup can stay paused until the user types to you, even after they answer in the browser. So never end your turn to wait for an answer, and do not stop after telling the user something. To get an answer, block on it:
+  ${cmd} ${url} wait <input-id>
+("plan --wait" and "ask --wait" block the same way). A wait that prints {"ok":false,"status":"waiting"} has not failed and the setup is not stuck: run its "next" command, right away. "next" only waits; never repeat an "ask" or "plan" to keep waiting, since that asks or submits again. End your turn only to ask the user in your own conversation (an "input.needed" you relay, or a value only they can give), and go on as soon as they reply; or once the install is done and proposed with "done".`;
+
 export const agentInstructions = (
   setupUrl: string,
   options: AgentInstructionsOptions = {},
@@ -188,6 +206,8 @@ export const agentInstructions = (
 
 ${streamSection(cmd, url, streaming, started?.opened === false)}
 
+${keepGoing(cmd, url)}
+
 The user can message you at any time, including while a question is waiting. Read "message.created" events, acknowledge each with "${cmd} ${url} ack <message-id>", and reply using "log" with what you will do. Pending messages are replayed when the stream starts and listed in "status". A message is not an answer or plan approval; keep those decisions explicit.
 
 "log" is a message to the user, and the user reads every one: send it only to reply to their message, to tell them something no question or step conveys (a blocker, a deviation from the plan, a decision you made for them), or once as a wrap-up when the install is finished. Findings go in the plan, progress in step notes, questions in "ask"; do not narrate.
@@ -205,10 +225,10 @@ The setup's products are starting names and guide references. If the setup lists
 When the setup puts an assistant in the app, ask how users should access it after discovering the actual app and before proposing the plan. Skip this question when no product's guide installs an assistant (a standalone library or service setup, for example). Use an entry-point question with only 1–3 sensible alternatives. Describe the actual app's pages, workflow and component placement, not generic placeholder copy. Recommend one clear fit when there is one; two options may use the same form factor in different places. Each option needs a stable id, label, contextual description and entryPoint {"formFactor":"modal"|"sidebar"|"full-page","placement":"where it appears","trigger":"how users open it or navigate to it","recommended":true?}. Write the JSON array for this app and send it with:
   ${cmd} ${url} ask "Where should users access the assistant?" --entry-points '<JSON array>' --wait
 Mark a clear fit with "recommended":true rather than --default, so the user makes the pick. When you ask it, do not submit the plan before the user picks an entry point. Respect the selected placement and trigger in the plan and implementation. Do not ask for a new-versus-existing app setting; discover the app from its files and ask only for an install path when needed.
-Skip a preset the code already answers (a chat route on the AI SDK, a provider key in .env.local) and log why. Ask everything at once, keep investigating, and block with "wait <input-id>" only when nothing else can proceed. A framework answer is "<framework>:<language>", for example "ai-sdk:typescript". A model answer is JSON {"provider","model","reasoningEffort"?}. An answer may carry a "note" from the user; follow it. A choice answer that matches none of the options is the user's own text.
+Skip a preset the code already answers (a chat route on the AI SDK, a provider key in .env.local) and log why. Ask everything at once, keep investigating, and then run "wait <input-id>" for each open question before you write the plan; do not end your turn while they are open. A framework answer is "<framework>:<language>", for example "ai-sdk:typescript". A model answer is JSON {"provider","model","reasoningEffort"?}. An answer may carry a "note" from the user; follow it. A choice answer that matches none of the options is the user's own text.
 Then write the plan as markdown and submit it:
   ${cmd} ${url} plan --file <path> --wait
-Use these headings, each with bullets: "## What I found" (facts as \`- **Label:** value\`: app framework, package manager, agent framework, model provider and model, where components live), "## What I will install" (packages and files, one per bullet), "## Steps" (a numbered list, one line each), and "## Open questions" only if any remain. Keep it under 30 lines; no preamble. "plan --wait" prints {"decision":"approve"} or {"decision":"revise","feedback":"..."}. On revise, address the feedback (ask again if you need to) and submit a new plan; repeat until approved. Do not change the project before approval: the setup refuses steps until then.
+Use these headings, each with bullets: "## What I found" (facts as \`- **Label:** value\`: app framework, package manager, agent framework, model provider and model, where components live), "## What I will install" (packages and files, one per bullet), "## Steps" (a numbered list, one line each), and "## Open questions" only if any remain. Keep it under 30 lines; no preamble. "plan --wait" prints {"decision":"approve"} or {"decision":"revise","feedback":"..."}; when it prints {"ok":false,"status":"waiting"}, the plan is submitted and still with the user, so keep waiting with "wait plan" and do not submit it again. On revise, address the feedback (ask again if you need to) and submit a new plan; repeat until approved. Do not change the project before approval: the setup refuses steps until then.
 
 2. Install. Declare the steps from your plan up front, in order:
   ${cmd} ${url} add-step "<title>" --detail "<one line>"
@@ -416,6 +436,47 @@ const waitForPlan = (client: CheckoutClient, revision: number) =>
     check();
   });
 
+/** The seconds `--timeout` asks a wait to block for; 0 is no limit. */
+const waitSeconds = (flags: Parsed["flags"], fallback: number) => {
+  const value = flagText(flags, "timeout");
+  if (value === undefined) return fallback;
+  const seconds = Number(value);
+  if (!/^\d+(?:\.\d+)?$/.test(value) || !Number.isFinite(seconds)) {
+    return fail("--timeout takes a number of seconds, 0 for no limit");
+  }
+  return seconds;
+};
+
+const TIMED_OUT = Symbol("timed out");
+
+/** `promise`, or `TIMED_OUT` once `seconds` pass first; 0 waits as long as it takes. */
+const within = async <T>(
+  promise: Promise<T>,
+  seconds: number,
+): Promise<T | typeof TIMED_OUT> => {
+  if (seconds === 0) return promise;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<typeof TIMED_OUT>((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), seconds * 1000);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** What a wait prints when the user has not decided yet: the command to run again, now. */
+const stillWaiting = (target: string, next: string) => ({
+  ok: false,
+  status: "waiting",
+  waitingFor: target,
+  next,
+  message: `The user has not answered yet. Run "next" now to keep waiting (it only waits; do not repeat the command you ran, which would ask or submit again), or go on with other work and run it when you need the answer. Do not end your turn: nothing resumes you until you run it.`,
+});
+
 const decided = (plan: Checkout.Plan | undefined, state: Checkout.State) => {
   if (state.status === "cancelled") return { ok: false, status: "cancelled" };
   if (plan === undefined) return fail("the plan disappeared");
@@ -840,6 +901,8 @@ export const runSetupCommand = async (
     fail(error instanceof Error ? error.message : String(error)),
   );
   const commands = client.commands;
+  const waitCommand = (target: string) =>
+    `${options.command ?? DEFAULT_COMMAND} ${shellWord(url)} wait ${target}`;
 
   try {
     switch (command) {
@@ -921,8 +984,15 @@ export const runSetupCommand = async (
           print({ ok: true, revision });
           break;
         }
-        const plan = await waitForPlan(client, revision);
-        print(decided(plan, requireState(client)));
+        const plan = await within(
+          waitForPlan(client, revision),
+          waitSeconds(flags, DEFAULT_WAIT_SECONDS),
+        );
+        print(
+          plan === TIMED_OUT
+            ? stillWaiting("plan", waitCommand("plan"))
+            : decided(plan, requireState(client)),
+        );
         break;
       }
       case "ask": {
@@ -956,7 +1026,15 @@ export const runSetupCommand = async (
           print({ ok: true, inputId });
           break;
         }
-        print(await waitForInput(client, inputId).then(answered));
+        const input = await within(
+          waitForInput(client, inputId),
+          waitSeconds(flags, DEFAULT_WAIT_SECONDS),
+        );
+        print(
+          input === TIMED_OUT
+            ? stillWaiting(inputId, waitCommand(inputId))
+            : answered(input),
+        );
         break;
       }
       case "wait": {
@@ -964,7 +1042,15 @@ export const runSetupCommand = async (
           rest[0] ?? fail("usage: wait start | wait <input-id> | wait plan");
         const state = requireState(client);
         if (target === "start") {
-          const status = await waitForStart(client);
+          // Waiting for the user's next setup is idle time, so it has no limit by default.
+          const status = await within(
+            waitForStart(client),
+            waitSeconds(flags, 0),
+          );
+          if (status === TIMED_OUT) {
+            print(stillWaiting("start", waitCommand("start")));
+            break;
+          }
           print({
             ok: status === "planning" || status === "installing",
             status,
@@ -973,18 +1059,29 @@ export const runSetupCommand = async (
         }
         if (target === "plan") {
           const plan = currentPlan(state) ?? fail("no plan has been proposed");
+          const decision = await within(
+            waitForPlan(client, plan.revision),
+            waitSeconds(flags, DEFAULT_WAIT_SECONDS),
+          );
           print(
-            decided(
-              await waitForPlan(client, plan.revision),
-              requireState(client),
-            ),
+            decision === TIMED_OUT
+              ? stillWaiting("plan", waitCommand("plan"))
+              : decided(decision, requireState(client)),
           );
           break;
         }
         if (!state.inputs.some((input) => input.id === target)) {
           fail(`no input "${target}"`);
         }
-        print(await waitForInput(client, target).then(answered));
+        const input = await within(
+          waitForInput(client, target),
+          waitSeconds(flags, DEFAULT_WAIT_SECONDS),
+        );
+        print(
+          input === TIMED_OUT
+            ? stillWaiting(target, waitCommand(target))
+            : answered(input),
+        );
         break;
       }
       case "env": {

package/src/presets.ts

@@ -134,7 +134,7 @@ export const INPUT_PRESETS: Record<PresetId, Preset> = {
     help: {
       summary:
         "Pick the app the assistant should live in. For a new project, Next.js is the shortest path: the assistant-ui CLI scaffolds the chat route with it. Pick Vite, React Router or TanStack Start when the rest of your stack already uses them, and Expo for a native app.",
-      href: `${DOCS}/docs/installation`,
+      href: `${DOCS}/docs/manual-installation`,
     },
   },
 };

package/src/sdk.test.ts

@@ -67,6 +67,8 @@ describe("setup-agent/sdk", () => {
         `npx my-tool setup https://checkout.test/${session.linkId} stream`,
       );
       expect(out).toContain("run_in_background");
+      expect(out).toContain("never end your turn to wait for it");
+      expect(out).not.toContain("Read its new output as it arrives");
       expect(out).toContain('"input.needed"');
       expect(out).toContain('"browser.opened"');
       expect(out).not.toContain("start a persistent Monitor");

package/src/sdk.ts

@@ -68,7 +68,7 @@ const setupBriefing = (
 
 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.
+2. Its new output does not wake you, so never end your turn to wait for it. Read the new lines between your other commands; each line after this briefing is a JSON array of events. Answers reach you through the blocking "wait" commands below.
 3. Run every other command in another shell: ${command} ${url} <command>.
 4. ${
     canOpen

package/src/stream.test.ts

@@ -7,6 +7,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 = () => {
@@ -129,8 +130,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: `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. Then keep working in the same turn; when you need the answer, block on it with "${WAIT} q1". Do not end your turn to wait: nothing on this stream wakes you.`,
       },
     ]);
 
@@ -160,8 +160,7 @@ 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: `A browser tab for setup was opened 10s ago. Wait for the user there with "${WAIT} q3", or ask the user directly in the terminal: Which registry? Options: pnpm (pnpm), npm (npm).`,
       question: "Which registry?",
       options: [
         { id: "pnpm", label: "pnpm" },

package/src/stream.ts

@@ -167,29 +167,44 @@ export const shellWord = (value: string) =>
 
 const ASK_MESSAGES: Record<
   AskReason,
-  (question: string, context: { agoSeconds: number; page: string }) => string
+  (
+    question: string,
+    context: { agoSeconds: number; page: string; wait: 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}`,
+  "recently-opened": (question, { agoSeconds, wait }) =>
+    `A browser tab for setup was opened ${agoSeconds}s ago. Wait for the user there${wait}, 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}`,
 };
 
+/** 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,
 ): 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: `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.${need.kind === "finish" ? " The answer arrives on this stream." : ` Then keep working in the same turn; when you need the answer, block on it${wait || ' with "wait"'}. Do not end your turn to wait: nothing on this stream wakes you.`}`,
     };
   const question = terminalQuestion(need);
   return {
@@ -199,6 +214,7 @@ const gateEvent = (
     message: ASK_MESSAGES[action.reason](formatTerminalQuestion(question), {
       agoSeconds: Math.round((action.openedAgoMs ?? 0) / 1000),
       page,
+      wait,
     }),
     ...question,
     answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,
@@ -263,7 +279,12 @@ 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),
+        ),
       );
     }
   };