setup-agent 0.0.8 → 0.1.0

package/README.md

@@ -17,6 +17,8 @@ npx setup-agent <url> add-step "Install the packages" --detail "pnpm add ..." --
 npx setup-agent <url> step s1 done --note "installed"
 npx setup-agent <url> env q2 OPENAI_API_KEY --file .env.local   # write the key behind a model answer without seeing it
 npx setup-agent <url> done --summary "installed the thread and a chat route" --preview http://localhost:3000
+npx setup-agent <url> answer q3 pnpm   # the user answered in the agent's own chat; also: answer plan approve, answer finish close
+npx setup-agent <url> stream --setup-app-url https://setup.assistant-ui.com   # also open the setup page when the setup waits on the user
 ```
 
 ## Phases
@@ -41,6 +43,35 @@ Two standard choices and a legacy project choice ship as presets (`setup-agent`
 
 `--only` restricts a preset to some of its options and leaves out `--choices` (a single id locks the choice in) and `--default` preselects one.
 
+## SDK
+
+`setup-agent/sdk` is what a CLI embeds to offer `<tool> setup` to coding agents; `npx assistant-ui@latest setup` is built on it. The `setup-agent` bin is a thin wrapper around the same code.
+
+```ts
+import { runAgentSetup } from "setup-agent/sdk";
+
+const { stream, client } = await runAgentSetup({
+  server: "https://checkout.assistant-ui.com",
+  setupAppUrl: "https://setup.assistant-ui.com",
+  products: [{ slug: "assistant-ui", name: "assistant-ui" }],
+  command: "npx my-tool setup", // the agent runs `npx my-tool setup <url> <command>`
+  name: "my-tool setup",
+});
+process.on("SIGINT", () => stream.stop().finally(() => client.dispose()));
+```
+
+`runAgentSetup` starts a session, prints the briefing and keeps running as the stream. Route `<tool> setup <url> ...` to `runSetupCommand(argv, { command, browser: { setupAppUrl } })` from `setup-agent/cli` for the other steps.
+
+The browser opens only when the setup waits on the user (an open input, a proposed plan, a proposal to close). The joined page sends `browser/heartbeat` every 5s and `browser/bye` on pagehide; it counts as present for 20s after a beat. Setup:
+
+- opens the page for the first need, one tab for everything waiting;
+- opens nothing while a joined page is present;
+- never opens a second tab within 30s of the last, and never reopens a tab that has not joined (30s after opening one that never joined, it hands what waits to the agent); it prints `input.needed` (`reason: "recently-opened"`) so the agent can ask in its own chat;
+- prints `input.needed` (`reason: "browser-closed"`) when the page leaves with something waiting, or a need arrives inside the 30s after it left; a later need reopens it once that 30s guard has expired;
+- under `--no-open` (with `--setup-app-url` for the bin), prints `input.needed` (`reason: "no-browser"`) for every need.
+
+Each `input.needed` carries the question, its options and the `answer` command. On a worker without browser presence, setup opens once and then leaves the rest to the agent.
+
 ## Workspace
 
 The package lives in `packages/setup-agent`; its Cloudflare worker lives in `apps/checkout-worker`. Build the worker dependencies with `pnpm turbo build --filter="checkout-worker^..."`, then run `pnpm --filter checkout-worker dev`. The worker consumes the published `@statewire/cloudflare` adapter.

package/dist/agents.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A coding agent a person can hand a setup to. `launch` is set when the
+ * agent has a terminal command that opens an interactive session with a
+ * first prompt; the others are handed the prompt to paste.
+ */
+export type CodingAgent = {
+    kind: string;
+    name: string;
+    launch?: {
+        /** Command names to try in order; the first one on PATH runs. */
+        commands: readonly string[];
+        args: (prompt: string) => string[];
+        install: string;
+    };
+};
+/** The coding agents people use most, in the order the picker lists them. */
+export declare const CODING_AGENTS: readonly CodingAgent[];
+/** The coding agent this process runs under, from the variables each one exports to its shell. */
+export declare const detectAgentKind: (env?: NodeJS.ProcessEnv) => string | undefined;
+/** True when a person typed the command into a terminal rather than an agent running it from its shell. */
+export declare const isDirectInvocation: (env?: NodeJS.ProcessEnv, stdin?: {
+    isTTY?: boolean | undefined;
+}, stdout?: {
+    isTTY?: boolean | undefined;
+}) => boolean;
+/** The first of `commands` found on PATH, or `undefined`. */
+export declare const findCommand: (commands: readonly string[], env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * Starts `agent` in this terminal with `prompt` as its first message and
+ * resolves with its exit code; `undefined` when its command is not installed.
+ */
+export declare const runCodingAgent: (agent: CodingAgent, prompt: string) => Promise<number | undefined>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QACP,iEAAiE;QACjE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;QACnC,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAqG/C,CAAC;AA2CF,kGAAkG;AAClG,eAAO,MAAM,eAAe,GAC1B,MAAK,MAAM,CAAC,UAAwB,KACnC,MAAM,GAAG,SAaX,CAAC;AAEF,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,GAC7B,MAAK,MAAM,CAAC,UAAwB,EACpC,QAAO;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAkB,EACtD,SAAQ;IAAE,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAmB,YAInC,CAAC;AAExB,6DAA6D;AAC7D,eAAO,MAAM,WAAW,GACtB,UAAU,SAAS,MAAM,EAAE,EAC3B,MAAK,MAAM,CAAC,UAAwB,KACnC,MAAM,GAAG,SAoBX,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,QAAQ,MAAM,KACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAgB5B,CAAC"}

package/dist/agents.js

@@ -0,0 +1,221 @@
+import spawn from "cross-spawn";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+// src/agents.ts
+/** The coding agents people use most, in the order the picker lists them. */
+const CODING_AGENTS = [
+	{
+		kind: "claude",
+		name: "Claude Code",
+		launch: {
+			commands: ["claude"],
+			args: (prompt) => [prompt],
+			install: "npm install -g @anthropic-ai/claude-code"
+		}
+	},
+	{
+		kind: "codex",
+		name: "Codex",
+		launch: {
+			commands: ["codex"],
+			args: (prompt) => [prompt],
+			install: "npm install -g @openai/codex"
+		}
+	},
+	{
+		kind: "cursor",
+		name: "Cursor",
+		launch: {
+			commands: ["cursor-agent", "agent"],
+			args: (prompt) => [prompt],
+			install: "curl https://cursor.com/install -fsS | bash"
+		}
+	},
+	{
+		kind: "gemini",
+		name: "Gemini CLI",
+		launch: {
+			commands: ["gemini"],
+			args: (prompt) => ["-i", prompt],
+			install: "npm install -g @google/gemini-cli"
+		}
+	},
+	{
+		kind: "copilot",
+		name: "Copilot CLI",
+		launch: {
+			commands: ["copilot"],
+			args: (prompt) => ["-i", prompt],
+			install: "npm install -g @github/copilot"
+		}
+	},
+	{
+		kind: "amp",
+		name: "Amp"
+	},
+	{
+		kind: "opencode",
+		name: "OpenCode",
+		launch: {
+			commands: ["opencode"],
+			args: (prompt) => ["--prompt", prompt],
+			install: "npm install -g opencode-ai"
+		}
+	},
+	{
+		kind: "cline",
+		name: "Cline"
+	},
+	{
+		kind: "aider",
+		name: "Aider"
+	},
+	{
+		kind: "goose",
+		name: "Goose"
+	},
+	{
+		kind: "warp",
+		name: "Warp"
+	},
+	{
+		kind: "windsurf",
+		name: "Windsurf"
+	},
+	{
+		kind: "kiro",
+		name: "Kiro",
+		launch: {
+			commands: ["kiro-cli"],
+			args: (prompt) => ["chat", prompt],
+			install: "curl -fsSL https://cli.kiro.dev/install | bash"
+		}
+	},
+	{
+		kind: "junie",
+		name: "Junie"
+	},
+	{
+		kind: "qwen",
+		name: "Qwen Code",
+		launch: {
+			commands: ["qwen"],
+			args: (prompt) => ["-i", prompt],
+			install: "npm install -g @qwen-code/qwen-code"
+		}
+	},
+	{
+		kind: "roo",
+		name: "Roo Code"
+	},
+	{
+		kind: "zed",
+		name: "Zed"
+	},
+	{
+		kind: "augment",
+		name: "Augment",
+		launch: {
+			commands: ["auggie"],
+			args: (prompt) => [prompt],
+			install: "npm install -g @augmentcode/auggie"
+		}
+	},
+	{
+		kind: "droid",
+		name: "Factory Droid",
+		launch: {
+			commands: ["droid"],
+			args: (prompt) => [prompt],
+			install: "curl -fsSL https://app.factory.ai/cli | sh"
+		}
+	},
+	{
+		kind: "crush",
+		name: "Crush"
+	}
+];
+/** The variables each agent exports to the shells it runs commands in. */
+const AGENT_ENV = [
+	["claude", "CLAUDECODE"],
+	["claude", "CLAUDE_CODE"],
+	["codex", "CODEX_SANDBOX"],
+	["codex", "CODEX_SANDBOX_NETWORK_DISABLED"],
+	["codex", "CODEX_CI"],
+	["codex", "CODEX_THREAD_ID"],
+	["cursor", "CURSOR_AGENT"],
+	["gemini", "GEMINI_CLI"],
+	["qwen", "QWEN_CODE"],
+	["copilot", "COPILOT_AGENT"],
+	["copilot", "COPILOT_CLI"],
+	["opencode", "OPENCODE_CLIENT"],
+	["augment", "AUGMENT_AGENT"],
+	["junie", "JUNIE_DATA"]
+];
+/** `AI_AGENT` values name the agent first, such as `claude-code_2-1-3_agent` or `github-copilot`. */
+const AI_AGENT_PREFIXES = [
+	["claude", "claude"],
+	["codex", "codex"],
+	["cursor", "cursor"],
+	["gemini", "gemini"],
+	["github-copilot", "copilot"],
+	["github_copilot", "copilot"],
+	["copilot", "copilot"],
+	["opencode", "opencode"],
+	["augment", "augment"],
+	["auggie", "augment"],
+	["qwen", "qwen"],
+	["amp", "amp"],
+	["goose", "goose"],
+	["junie", "junie"],
+	["droid", "droid"],
+	["factory", "droid"],
+	["kiro", "kiro"],
+	["cline", "cline"],
+	["crush", "crush"]
+];
+/** The coding agent this process runs under, from the variables each one exports to its shell. */
+const detectAgentKind = (env = process.env) => {
+	const named = env.AI_AGENT?.trim().toLowerCase();
+	if (named) return AI_AGENT_PREFIXES.find(([prefix]) => named.startsWith(prefix) && (named.length === prefix.length || /[-_ ./0-9]/.test(named[prefix.length])))?.[1] ?? "other";
+	return AGENT_ENV.find(([, variable]) => env[variable])?.[0];
+};
+/** True when a person typed the command into a terminal rather than an agent running it from its shell. */
+const isDirectInvocation = (env = process.env, stdin = process.stdin, stdout = process.stdout) => detectAgentKind(env) === void 0 && stdin.isTTY === true && stdout.isTTY === true;
+/** The first of `commands` found on PATH, or `undefined`. */
+const findCommand = (commands, env = process.env) => {
+	const directories = (env.PATH ?? "").split(delimiter).filter(Boolean);
+	const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+	return commands.find((command) => directories.some((directory) => extensions.some((extension) => {
+		try {
+			accessSync(join(directory, command + extension), constants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	})));
+};
+/**
+* Starts `agent` in this terminal with `prompt` as its first message and
+* resolves with its exit code; `undefined` when its command is not installed.
+*/
+const runCodingAgent = (agent, prompt) => {
+	const launch = agent.launch;
+	if (!launch) return Promise.resolve(void 0);
+	const command = findCommand(launch.commands);
+	if (command === void 0) return Promise.resolve(void 0);
+	const child = spawn(command, launch.args(prompt), { stdio: "inherit" });
+	return new Promise((resolve) => {
+		child.on("error", (error) => {
+			if (error.code === "ENOENT") resolve(void 0);
+			else {
+				process.stderr.write(`${error.message}\n`);
+				resolve(1);
+			}
+		});
+		child.on("exit", (status) => resolve(status ?? 1));
+	});
+};
+export { CODING_AGENTS, detectAgentKind, findCommand, isDirectInvocation, runCodingAgent };
+
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","names":[],"sources":["../src/agents.ts"],"sourcesContent":["import spawn from \"cross-spawn\";\nimport { accessSync, constants } from \"node:fs\";\nimport { delimiter, join } from \"node:path\";\n\n/**\n * A coding agent a person can hand a setup to. `launch` is set when the\n * agent has a terminal command that opens an interactive session with a\n * first prompt; the others are handed the prompt to paste.\n */\nexport type CodingAgent = {\n  kind: string;\n  name: string;\n  launch?: {\n    /** Command names to try in order; the first one on PATH runs. */\n    commands: readonly string[];\n    args: (prompt: string) => string[];\n    install: string;\n  };\n};\n\n/** The coding agents people use most, in the order the picker lists them. */\nexport const CODING_AGENTS: readonly CodingAgent[] = [\n  {\n    kind: \"claude\",\n    name: \"Claude Code\",\n    launch: {\n      commands: [\"claude\"],\n      args: (prompt) => [prompt],\n      install: \"npm install -g @anthropic-ai/claude-code\",\n    },\n  },\n  {\n    kind: \"codex\",\n    name: \"Codex\",\n    launch: {\n      commands: [\"codex\"],\n      args: (prompt) => [prompt],\n      install: \"npm install -g @openai/codex\",\n    },\n  },\n  {\n    kind: \"cursor\",\n    name: \"Cursor\",\n    launch: {\n      commands: [\"cursor-agent\", \"agent\"],\n      args: (prompt) => [prompt],\n      install: \"curl https://cursor.com/install -fsS | bash\",\n    },\n  },\n  {\n    kind: \"gemini\",\n    name: \"Gemini CLI\",\n    launch: {\n      commands: [\"gemini\"],\n      args: (prompt) => [\"-i\", prompt],\n      install: \"npm install -g @google/gemini-cli\",\n    },\n  },\n  {\n    kind: \"copilot\",\n    name: \"Copilot CLI\",\n    launch: {\n      commands: [\"copilot\"],\n      args: (prompt) => [\"-i\", prompt],\n      install: \"npm install -g @github/copilot\",\n    },\n  },\n  { kind: \"amp\", name: \"Amp\" },\n  {\n    kind: \"opencode\",\n    name: \"OpenCode\",\n    launch: {\n      commands: [\"opencode\"],\n      args: (prompt) => [\"--prompt\", prompt],\n      install: \"npm install -g opencode-ai\",\n    },\n  },\n  { kind: \"cline\", name: \"Cline\" },\n  { kind: \"aider\", name: \"Aider\" },\n  { kind: \"goose\", name: \"Goose\" },\n  { kind: \"warp\", name: \"Warp\" },\n  { kind: \"windsurf\", name: \"Windsurf\" },\n  {\n    kind: \"kiro\",\n    name: \"Kiro\",\n    launch: {\n      commands: [\"kiro-cli\"],\n      args: (prompt) => [\"chat\", prompt],\n      install: \"curl -fsSL https://cli.kiro.dev/install | bash\",\n    },\n  },\n  { kind: \"junie\", name: \"Junie\" },\n  {\n    kind: \"qwen\",\n    name: \"Qwen Code\",\n    launch: {\n      commands: [\"qwen\"],\n      args: (prompt) => [\"-i\", prompt],\n      install: \"npm install -g @qwen-code/qwen-code\",\n    },\n  },\n  { kind: \"roo\", name: \"Roo Code\" },\n  { kind: \"zed\", name: \"Zed\" },\n  {\n    kind: \"augment\",\n    name: \"Augment\",\n    launch: {\n      commands: [\"auggie\"],\n      args: (prompt) => [prompt],\n      install: \"npm install -g @augmentcode/auggie\",\n    },\n  },\n  {\n    kind: \"droid\",\n    name: \"Factory Droid\",\n    launch: {\n      commands: [\"droid\"],\n      args: (prompt) => [prompt],\n      install: \"curl -fsSL https://app.factory.ai/cli | sh\",\n    },\n  },\n  { kind: \"crush\", name: \"Crush\" },\n];\n\n/** The variables each agent exports to the shells it runs commands in. */\nconst AGENT_ENV: readonly [kind: string, variable: string][] = [\n  [\"claude\", \"CLAUDECODE\"],\n  [\"claude\", \"CLAUDE_CODE\"],\n  [\"codex\", \"CODEX_SANDBOX\"],\n  [\"codex\", \"CODEX_SANDBOX_NETWORK_DISABLED\"],\n  [\"codex\", \"CODEX_CI\"],\n  [\"codex\", \"CODEX_THREAD_ID\"],\n  [\"cursor\", \"CURSOR_AGENT\"],\n  [\"gemini\", \"GEMINI_CLI\"],\n  [\"qwen\", \"QWEN_CODE\"],\n  [\"copilot\", \"COPILOT_AGENT\"],\n  [\"copilot\", \"COPILOT_CLI\"],\n  [\"opencode\", \"OPENCODE_CLIENT\"],\n  [\"augment\", \"AUGMENT_AGENT\"],\n  [\"junie\", \"JUNIE_DATA\"],\n];\n\n/** `AI_AGENT` values name the agent first, such as `claude-code_2-1-3_agent` or `github-copilot`. */\nconst AI_AGENT_PREFIXES: readonly [prefix: string, kind: string][] = [\n  [\"claude\", \"claude\"],\n  [\"codex\", \"codex\"],\n  [\"cursor\", \"cursor\"],\n  [\"gemini\", \"gemini\"],\n  [\"github-copilot\", \"copilot\"],\n  [\"github_copilot\", \"copilot\"],\n  [\"copilot\", \"copilot\"],\n  [\"opencode\", \"opencode\"],\n  [\"augment\", \"augment\"],\n  [\"auggie\", \"augment\"],\n  [\"qwen\", \"qwen\"],\n  [\"amp\", \"amp\"],\n  [\"goose\", \"goose\"],\n  [\"junie\", \"junie\"],\n  [\"droid\", \"droid\"],\n  [\"factory\", \"droid\"],\n  [\"kiro\", \"kiro\"],\n  [\"cline\", \"cline\"],\n  [\"crush\", \"crush\"],\n];\n\n/** The coding agent this process runs under, from the variables each one exports to its shell. */\nexport const detectAgentKind = (\n  env: NodeJS.ProcessEnv = process.env,\n): string | undefined => {\n  const named = env.AI_AGENT?.trim().toLowerCase();\n  if (named) {\n    // The name, or the name followed by a separator and a version or role.\n    const match = AI_AGENT_PREFIXES.find(\n      ([prefix]) =>\n        named.startsWith(prefix) &&\n        (named.length === prefix.length ||\n          /[-_ ./0-9]/.test(named[prefix.length]!)),\n    );\n    return match?.[1] ?? \"other\";\n  }\n  return AGENT_ENV.find(([, variable]) => env[variable])?.[0];\n};\n\n/** True when a person typed the command into a terminal rather than an agent running it from its shell. */\nexport const isDirectInvocation = (\n  env: NodeJS.ProcessEnv = process.env,\n  stdin: { isTTY?: boolean | undefined } = process.stdin,\n  stdout: { isTTY?: boolean | undefined } = process.stdout,\n) =>\n  detectAgentKind(env) === undefined &&\n  stdin.isTTY === true &&\n  stdout.isTTY === true;\n\n/** The first of `commands` found on PATH, or `undefined`. */\nexport const findCommand = (\n  commands: readonly string[],\n  env: NodeJS.ProcessEnv = process.env,\n): string | undefined => {\n  // Empty entries (the working directory) are skipped on purpose: a project\n  // must not be able to plant its own `claude` next to the user.\n  const directories = (env.PATH ?? \"\").split(delimiter).filter(Boolean);\n  const extensions =\n    process.platform === \"win32\"\n      ? (env.PATHEXT ?? \".EXE;.CMD;.BAT\").split(\";\")\n      : [\"\"];\n  return commands.find((command) =>\n    directories.some((directory) =>\n      extensions.some((extension) => {\n        try {\n          accessSync(join(directory, command + extension), constants.X_OK);\n          return true;\n        } catch {\n          return false;\n        }\n      }),\n    ),\n  );\n};\n\n/**\n * Starts `agent` in this terminal with `prompt` as its first message and\n * resolves with its exit code; `undefined` when its command is not installed.\n */\nexport const runCodingAgent = (\n  agent: CodingAgent,\n  prompt: string,\n): Promise<number | undefined> => {\n  const launch = agent.launch;\n  if (!launch) return Promise.resolve(undefined);\n  const command = findCommand(launch.commands);\n  if (command === undefined) return Promise.resolve(undefined);\n  const child = spawn(command, launch.args(prompt), { stdio: \"inherit\" });\n  return new Promise((resolve) => {\n    child.on(\"error\", (error: NodeJS.ErrnoException) => {\n      if (error.code === \"ENOENT\") resolve(undefined);\n      else {\n        process.stderr.write(`${error.message}\\n`);\n        resolve(1);\n      }\n    });\n    child.on(\"exit\", (status) => resolve(status ?? 1));\n  });\n};\n"],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,40 @@
+import type { SetupNeed } from "./needs.js";
+import type { Checkout } from "./protocol.js";
+/** Within this long of opening a tab, setup never opens another. */
+export declare const BROWSER_REOPEN_GUARD_MS = 30000;
+/** A page silent this long after it was present counts as closed; one heartbeat gap is not enough. */
+export declare const BROWSER_CLOSE_GRACE_MS: number;
+/**
+ * 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 declare const createBrowserGate: ({ url, canOpen, 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;
+}) => {
+    update: (state: Checkout.State) => BrowserGateAction[];
+};
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAgB;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAmB;AAE3C,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,sGAAsG;AACtG,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,wBAI/B;IACD,0EAA0E;IAC1E,GAAG,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,KAAK,MAAM,GAAG,SAAS,CAAC;IACnD,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;oBAwCmB,QAAQ,CAAC,KAAK,KAAG,iBAAiB,EAAE;CAkEvD,CAAC"}

package/dist/browser.js

@@ -0,0 +1,91 @@
+import { BROWSER_HEARTBEAT_MS, BROWSER_PRESENCE_MS } from "./protocol.js";
+import { needKey, pendingNeeds } from "./needs.js";
+// src/browser.ts
+/** Within this long of opening a tab, setup never opens another. */
+const BROWSER_REOPEN_GUARD_MS = 3e4;
+/** A page silent this long after it was present counts as closed; one heartbeat gap is not enough. */
+const BROWSER_CLOSE_GRACE_MS = BROWSER_HEARTBEAT_MS + 1e3;
+/**
+* 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.
+*/
+const createBrowserGate = ({ url, canOpen = true, now = Date.now }) => {
+	const handled = /* @__PURE__ */ new Set();
+	/** Needs the agent was already told to ask about. */
+	const told = /* @__PURE__ */ new Set();
+	let openedAt;
+	let joinedSinceOpen = false;
+	let lastBeat;
+	let beatArrivedAt;
+	let present = false;
+	let absentSince;
+	let closedReported = true;
+	let joinTimeoutReported = true;
+	const trackPresence = (browser) => {
+		if (browser === void 0) return;
+		const time = now();
+		if (browser.lastSeenAt !== lastBeat) {
+			beatArrivedAt = browser.lastSeenAt === null ? void 0 : time;
+			lastBeat = browser.lastSeenAt;
+		}
+		if (browser.connected && beatArrivedAt !== void 0 && time - beatArrivedAt < 2e4) {
+			present = joinedSinceOpen = true;
+			absentSince = void 0;
+			closedReported = false;
+		} else if (present || absentSince !== void 0) {
+			absentSince ??= browser.connected && beatArrivedAt !== void 0 ? Math.min(time, beatArrivedAt + BROWSER_PRESENCE_MS) : time;
+			present = false;
+		}
+	};
+	return { update: (state) => {
+		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);
+		const looksPresent = present || absentSince !== void 0 && time - absentSince < BROWSER_CLOSE_GRACE_MS;
+		const closed = !looksPresent && absentSince !== void 0;
+		const ask = (need, reason) => {
+			told.add(needKey(need));
+			return {
+				type: "ask",
+				reason,
+				need,
+				...reason === "recently-opened" && { openedAgoMs: time - openedAt }
+			};
+		};
+		const actions = [];
+		if (closed && !closedReported) {
+			closedReported = true;
+			for (const need of needs) if (handled.has(needKey(need))) actions.push(ask(need, "browser-closed"));
+		}
+		if (!joinTimeoutReported && !joinedSinceOpen && time - openedAt >= 3e4) {
+			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) : void 0;
+		if (target === void 0) return [...actions, ...fresh.map((need) => ask(need, "no-browser"))];
+		if (openedAt === void 0 || time - openedAt >= 3e4 && joinedSinceOpen) {
+			openedAt = time;
+			joinedSinceOpen = false;
+			joinTimeoutReported = false;
+			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))];
+	} };
+};
+export { BROWSER_CLOSE_GRACE_MS, BROWSER_REOPEN_GUARD_MS, createBrowserGate };
+
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 import type { CheckoutClient } from "./client.js";
 import type { Checkout } from "./protocol.js";
+export { diffEvents } from "./stream.js";
 export declare const HELP: string;
 /**
  * The normalized setup URL, or an error saying why it is refused. A setup URL
@@ -8,57 +9,32 @@ export declare const HELP: string;
  * no credentials, query or fragment, and hold only address characters.
  */
 export declare const parseSetupUrl: (value: string) => string;
-export declare const agentInstructions: (setupUrl: string) => string;
-export declare const INSTRUCTIONS: (setupUrl: string) => string;
+export type AgentInstructionsOptions = {
+    /** How the agent invokes the setup commands, before the URL; `npx setup-agent` by default. */
+    command?: string;
+    /**
+     * The agent started this setup with `assistant-ui setup`, which already
+     * began planning; there is no Begin plan click to wait for.
+     */
+    startedByAgent?: {
+        browserUrl: string;
+        /** False when the browser was not opened for the user; the agent then hands them the link. */
+        opened?: boolean;
+        /**
+         * The command that printed this briefing is the stream: it keeps running
+         * and opens the browser only when the setup waits on the user.
+         */
+        streaming?: boolean;
+    };
+};
+export declare const agentInstructions: (setupUrl: string, options?: AgentInstructionsOptions) => string;
+export declare const INSTRUCTIONS: (setupUrl: string, options?: AgentInstructionsOptions) => string;
 type Parsed = {
     positional: string[];
     flags: Map<string, string | true>;
 };
-/** The coding agent this process runs under, from the variables each one exports to its shell. */
-export declare const detectAgentKind: (env?: NodeJS.ProcessEnv) => string | undefined;
-/** True when a person typed the command into a terminal rather than an agent running it from its shell. */
-export declare const isDirectInvocation: (env?: NodeJS.ProcessEnv, stdin?: {
-    isTTY?: boolean | undefined;
-}, stdout?: {
-    isTTY?: boolean | undefined;
-}) => boolean;
-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[];
-};
-export declare const diffEvents: (before: Checkout.State, after: Checkout.State) => StreamEvent[];
+export { CODING_AGENTS, detectAgentKind, findCommand, isDirectInvocation, runCodingAgent, } from "./agents.js";
+export type { CodingAgent } from "./agents.js";
 /** Resolves once a setup is planning or installing, or once the one being waited on is cancelled; a setup already closed when the wait begins is over, so the wait is for the next one. */
 export declare const waitForStart: (client: Pick<CheckoutClient, "state" | "subscribe">) => Promise<Checkout.Status>;
 export declare const askSeed: (rest: readonly string[], flags: Parsed["flags"]) => Checkout.InputSeed & {
@@ -73,6 +49,19 @@ export declare const upsertEnvLine: (content: string, key: string, value: string
  * still deposited; it is read after, so lines written meanwhile survive.
  */
 export declare const writeEnvSecret: (file: string, key: string, take: () => Promise<string>, projectRoot?: string) => Promise<void>;
-export declare const main: (argv: readonly string[]) => Promise<undefined>;
-export {};
+export type RunSetupCommandOptions = {
+    /** How the agent invokes these commands, before the URL; `npx setup-agent` by default. */
+    command?: string;
+    /** Lets "stream" open the setup page when the setup waits on the user, as `--setup-app-url` does. */
+    browser?: {
+        setupAppUrl: string;
+        canOpen?: boolean;
+    };
+};
+export declare const main: (argv: readonly string[]) => Promise<void>;
+/**
+ * Runs one setup command (`<url> <command> ...`) the way `npx setup-agent`
+ * does, for a CLI that embeds setup as its own command.
+ */
+export declare const runSetupCommand: (argv: readonly string[], options?: RunSetupCommandOptions) => Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAiB;AA2B/C,OAAO,KAAK,EAAE,QAAQ,EAAE,sBAAmB;AAI3C,OAAO,EAAE,UAAU,EAAE,oBAAiB;AAItC,eAAO,MAAM,IAAI,QAoChB,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,KAAG,MA6B7C,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,8FAA8F;QAC9F,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAuCF,eAAO,MAAM,iBAAiB,GAC5B,UAAU,MAAM,EAChB,UAAS,wBAA6B,WA6CvC,CAAC;AAEF,eAAO,MAAM,YAAY,aAhDb,MAAM,YACP,wBAAwB,WA+CU,CAAC;AAE9C,KAAK,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAAE,CAAC;AAuB1E,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,oBAAiB;AAClB,YAAY,EAAE,WAAW,EAAE,oBAAiB;AAuG5C,2LAA2L;AAC3L,eAAO,MAAM,YAAY,GACvB,QAAQ,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,CAAC,6BAiBjD,CAAC;AAwDL,eAAO,MAAM,OAAO,GAClB,MAAM,SAAS,MAAM,EAAE,EACvB,OAAO,MAAM,CAAC,OAAO,CAAC,KACrB,QAAQ,CAAC,SAAS,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CA+HxC,CAAC;AAQF,+EAA+E;AAC/E,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,WAqBxE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,KAAK,MAAM,EACX,MAAM,MAAM,OAAO,CAAC,MAAM,CAAC,EAC3B,oBAA2B,kBAsD5B,CAAC;AAgHF,MAAM,MAAM,sBAAsB,GAAG;IACnC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,OAAO,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAkCF,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,kBAA0B,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,SAAS,MAAM,EAAE,EACvB,UAAS,sBAA2B,kBAwRrC,CAAC"}