setup-agent 0.0.8 → 0.1.0

package/src/agents.ts

@@ -0,0 +1,243 @@
+import spawn from "cross-spawn";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/**
+ * 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 const CODING_AGENTS: readonly CodingAgent[] = [
+  {
+    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: readonly [kind: string, variable: string][] = [
+  ["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: readonly [prefix: string, kind: string][] = [
+  ["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. */
+export const detectAgentKind = (
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined => {
+  const named = env.AI_AGENT?.trim().toLowerCase();
+  if (named) {
+    // The name, or the name followed by a separator and a version or role.
+    const match = AI_AGENT_PREFIXES.find(
+      ([prefix]) =>
+        named.startsWith(prefix) &&
+        (named.length === prefix.length ||
+          /[-_ ./0-9]/.test(named[prefix.length]!)),
+    );
+    return match?.[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. */
+export const isDirectInvocation = (
+  env: NodeJS.ProcessEnv = process.env,
+  stdin: { isTTY?: boolean | undefined } = process.stdin,
+  stdout: { isTTY?: boolean | undefined } = process.stdout,
+) =>
+  detectAgentKind(env) === undefined &&
+  stdin.isTTY === true &&
+  stdout.isTTY === true;
+
+/** The first of `commands` found on PATH, or `undefined`. */
+export const findCommand = (
+  commands: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined => {
+  // Empty entries (the working directory) are skipped on purpose: a project
+  // must not be able to plant its own `claude` next to the user.
+  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.
+ */
+export const runCodingAgent = (
+  agent: CodingAgent,
+  prompt: string,
+): Promise<number | undefined> => {
+  const launch = agent.launch;
+  if (!launch) return Promise.resolve(undefined);
+  const command = findCommand(launch.commands);
+  if (command === undefined) return Promise.resolve(undefined);
+  const child = spawn(command, launch.args(prompt), { stdio: "inherit" });
+  return new Promise((resolve) => {
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") resolve(undefined);
+      else {
+        process.stderr.write(`${error.message}\n`);
+        resolve(1);
+      }
+    });
+    child.on("exit", (status) => resolve(status ?? 1));
+  });
+};

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))];
+    },
+  };
+};

package/src/cli.test.ts

@@ -602,6 +602,28 @@ describe("begin planning", () => {
 });
 
 describe("agent instructions", () => {
+  it("goes straight to planning for a setup the agent started", () => {
+    const browserUrl =
+      "https://setup.assistant-ui.com/#link=abc12345&setup=def67890";
+    const started = agentInstructions("https://setup.test/abc12345", {
+      startedByAgent: { browserUrl },
+    });
+    expect(started).not.toContain("click Begin plan");
+    expect(started).not.toContain("wait start\nKeep the stream running");
+    expect(started).toContain("there is no Begin plan click to wait for");
+    expect(started).toContain(browserUrl);
+    expect(started).toContain("a setup you opened in the user's browser");
+    const opened = agentInstructions("https://setup.test/abc12345");
+    expect(opened).toContain("click Begin plan");
+    expect(opened).toContain("a setup the user opened in their browser");
+  });
+
+  it("asks what to set up when the setup has no products", () => {
+    expect(agentInstructions("https://setup.test/s")).toContain(
+      "If the setup lists no products, first ask the user what to set up",
+    );
+  });
+
   it("prints a setup URL as one quoted shell word", () => {
     const instructions = agentInstructions("https://checkout.test/a'b;c");
     expect(instructions).toContain(
@@ -1199,3 +1221,59 @@ describe("model key handoff", () => {
     },
   );
 });
+
+describe("answer", () => {
+  it("answers an input for the user from the agent's side", async () => {
+    const state: Checkout.State = {
+      ...initialCheckoutState(),
+      id: "setup-a",
+      createdAt: 1,
+      status: "planning",
+      inputs: [
+        {
+          id: "q1",
+          phase: "planning",
+          kind: "text",
+          prompt: "Where?",
+          optional: false,
+          status: "open",
+          createdAt: 2,
+        },
+      ],
+    };
+    const answer = vi.fn(async () => {});
+    connectCheckoutMock.mockResolvedValue({
+      state,
+      commands: { "checkout/answer": answer },
+      dispose: vi.fn(),
+    } as unknown as Awaited<ReturnType<typeof connectCheckout>>);
+    const stdout = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    onTestFinished(() => {
+      stdout.mockRestore();
+      connectCheckoutMock.mockReset();
+    });
+    await main([
+      "https://checkout.test/session",
+      "answer",
+      "q1",
+      "apps/web",
+      "--note",
+      "said in chat",
+    ]);
+    expect(answer).toHaveBeenCalledWith({
+      inputId: "q1",
+      answer: "apps/web",
+      note: "said in chat",
+    });
+    expect(stdout).toHaveBeenCalledWith(
+      `${JSON.stringify({ ok: true, id: "q1", status: "answered" })}\n`,
+    );
+  });
+});
+
+describe("help", () => {
+  it("documents answer in the help", () => {
+    expect(HELP).toContain("answer <input-id> <answer>");
+    expect(HELP).toContain("--setup-app-url");
+  });
+});