setup-agent 0.0.8 → 0.1.0

package/src/sdk.ts

@@ -0,0 +1,145 @@
+/**
+ * `<tool> setup` for coding agents, for a CLI to embed. `runAgentSetup` is
+ * the whole command; route `<tool> setup <url> <step> ...` to
+ * `runSetupCommand` from `setup-agent/cli`. Node only.
+ */
+import { randomInt } from "node:crypto";
+import { detectAgentKind } from "./agents";
+import { agentInstructions } from "./cli";
+import { connectCheckout } from "./client";
+import type { CheckoutClient } from "./client";
+import type { Checkout } from "./protocol";
+import { followSetup, setupPageUrl, shellWord } from "./stream";
+import type { FollowSetupOptions } from "./stream";
+
+/** A random id in the alphabet and length the setup page uses for its own. */
+const createSetupId = () =>
+  Array.from(
+    { length: 12 },
+    () =>
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"[
+        randomInt(62)
+      ]!,
+  ).join("");
+
+export type SetupSession = {
+  linkId: string;
+  setupId: string;
+  /** The URL every setup command takes. */
+  agentUrl: string;
+  /** The page the user follows the setup on. */
+  browserUrl: string;
+  products: Checkout.ProductSeed[];
+};
+
+export type RunAgentSetupOptions = {
+  /** The setup server, such as https://checkout.assistant-ui.com. */
+  server: string;
+  /** The setup app the browser opens, such as https://setup.assistant-ui.com. */
+  setupAppUrl: string;
+  products: Checkout.ProductSeed[];
+  /** How the agent invokes setup commands, before the URL: `npx assistant-ui@latest setup`. */
+  command: string;
+  /** What the product calls this, for the briefing's first line. */
+  name?: string;
+  /** False for `--no-open`: the agent asks the user itself. */
+  canOpen?: boolean;
+  /** Opens the setup page; the default browser by default. */
+  open?: (url: string) => void;
+  /** Called once the session exists, before the briefing prints. */
+  onSession?: (session: SetupSession) => void;
+  write?: (text: string) => void;
+  env?: NodeJS.ProcessEnv;
+  connect?: (url: string) => Promise<CheckoutClient>;
+  stream?: Pick<FollowSetupOptions, "print" | "agent">;
+};
+
+/** What the agent reads first in the output of a setup command that keeps running. */
+const setupBriefing = (
+  session: SetupSession,
+  {
+    command,
+    name = "Setup",
+    canOpen = true,
+  }: Pick<RunAgentSetupOptions, "command" | "name" | "canOpen">,
+) => {
+  const url = shellWord(session.agentUrl);
+  return `${name} is running. This command keeps running: it is the setup's stream.
+
+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.
+3. Run every other command in another shell: ${command} ${url} <command>.
+4. ${
+    canOpen
+      ? "Setup opens the user's browser by itself when you ask the user something; do not open it yourself."
+      : `Setup will not open a browser (--no-open). Give the user ${session.browserUrl} once, or ask in your own conversation.`
+  } On an "input.needed" event, do what its message says; to answer from here, run its "answer" command with the user's reply.
+
+${agentInstructions(session.agentUrl, {
+  command,
+  startedByAgent: {
+    browserUrl: session.browserUrl,
+    streaming: true,
+    opened: canOpen,
+  },
+})}
+Setup page, if the user asks for it: ${session.browserUrl}
+
+Current setup:
+${JSON.stringify({ status: "planning", products: session.products })}
+`;
+};
+
+/**
+ * `<tool> setup` for a coding agent, in one call: opens a new link on the
+ * setup server, creates a setup there and starts planning, prints the
+ * briefing, then streams the setup and opens the browser only when it waits
+ * on the user. Resolves with the running stream; the caller stops it (on
+ * SIGINT, say) and disposes the client.
+ */
+export const runAgentSetup = async (options: RunAgentSetupOptions) => {
+  const connect = options.connect ?? connectCheckout;
+  const linkId = createSetupId();
+  const setupId = createSetupId();
+  const agentUrl = `${options.server.replace(/\/$/, "")}/${linkId}`;
+  const client = await connect(agentUrl);
+  try {
+    const kind = detectAgentKind(options.env);
+    await client.commands["checkout/create"]({
+      id: setupId,
+      products: options.products,
+    });
+    await client.commands["checkout/begin-plan"]();
+    // The agent shows as connected once the stream says hello with the cwd.
+    await client.commands["agent/intro"]({
+      ...(kind !== undefined && { kind }),
+    });
+    const session: SetupSession = {
+      linkId,
+      setupId,
+      agentUrl,
+      browserUrl: setupPageUrl(options.setupAppUrl, linkId, setupId),
+      products: options.products,
+    };
+    options.onSession?.(session);
+    (options.write ?? ((text) => process.stdout.write(text)))(
+      setupBriefing(session, options),
+    );
+    const stream = await followSetup(client, {
+      ...options.stream,
+      agent: { ...(kind !== undefined && { kind }), ...options.stream?.agent },
+      browser: {
+        setupAppUrl: options.setupAppUrl,
+        linkId,
+        answerCommand: `${options.command} ${shellWord(agentUrl)} answer`,
+        ...(options.open && { open: options.open }),
+        ...(options.canOpen !== undefined && { canOpen: options.canOpen }),
+      },
+    });
+    return { session, stream, client };
+  } catch (error) {
+    client.dispose();
+    throw error;
+  }
+};

package/src/stream.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { answerNeed } from "./needs";
+import { initialCheckoutState } from "./protocol";
+import type { Checkout } from "./protocol";
+import { followSetup } from "./stream";
+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";
+
+/** A client whose state the test changes, notifying like a statewire client. */
+const fakeClient = () => {
+  let state: Checkout.State = {
+    ...initialCheckoutState(),
+    id: "s1",
+    createdAt: 1,
+    status: "planning",
+  };
+  const listeners = new Set<() => void>();
+  const calls: string[] = [];
+  const change = (mutate: (draft: Checkout.State) => void) => {
+    const draft = structuredClone(state);
+    mutate(draft);
+    state = draft;
+    for (const listener of listeners) listener();
+  };
+  const commands = new Proxy(
+    {},
+    {
+      get:
+        (_, name: string) =>
+        async (params: { inputId: string; answer: string }) => {
+          calls.push(name);
+          if (name === "checkout/answer")
+            change((draft) => {
+              const input = draft.inputs.find(
+                (entry) => entry.id === params.inputId,
+              )!;
+              input.status = "answered";
+              input.answer = params.answer;
+            });
+        },
+    },
+  );
+  return {
+    client: {
+      get state() {
+        return state;
+      },
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      commands,
+    } as unknown as Parameters<typeof followSetup>[0],
+    calls,
+    change,
+    ask: (prompt: string) =>
+      change((draft) => {
+        draft.inputs.push({
+          id: `q${draft.inputs.length + 1}`,
+          phase: "planning",
+          kind: "choice",
+          prompt,
+          options: [
+            { id: "pnpm", label: "pnpm" },
+            { id: "npm", label: "npm" },
+          ],
+          optional: false,
+          status: "open",
+          createdAt: Date.now(),
+        });
+      }),
+    heartbeat: () =>
+      change((draft) => {
+        draft.browser = { lastSeenAt: Date.now(), connected: true };
+      }),
+  };
+};
+
+describe("followSetup", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ now: 1_000_000 });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  const start = async () => {
+    const fake = fakeClient();
+    const lines: StreamEvent[][] = [];
+    const open = vi.fn();
+    const stream = await followSetup(fake.client, {
+      print: (events) => lines.push(events),
+      agent: { cwd: "/app", kind: "claude" },
+      browser: {
+        setupAppUrl: "https://setup.test",
+        linkId: "abc",
+        answerCommand: ANSWER,
+        open,
+      },
+    });
+    const events = () => lines.flat();
+    return { ...fake, stream, open, events };
+  };
+
+  it("says hello, keeps a heartbeat, and opens no browser before a question", async () => {
+    const t = await start();
+    expect(t.calls).toEqual(["agent/hello"]);
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(t.open).not.toHaveBeenCalled();
+    expect(t.calls.filter((name) => name === "agent/heartbeat")).toHaveLength(
+      12,
+    );
+    expect(t.events()).toEqual([]);
+    await t.stream.stop();
+    expect(t.calls.at(-1)).toBe("agent/bye");
+  });
+
+  it("opens the page for the first question, reopens after a close, guards within 30s, and takes an answer from the agent", async () => {
+    const t = await start();
+
+    t.ask("Which package manager?");
+    await vi.advanceTimersByTimeAsync(300);
+    expect(t.open).toHaveBeenCalledTimes(1);
+    expect(t.open).toHaveBeenCalledWith(PAGE);
+    expect(t.events()).toEqual([
+      {
+        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.',
+      },
+    ]);
+
+    // The page joins, the user answers there and closes the tab.
+    await vi.advanceTimersByTimeAsync(2_000);
+    t.heartbeat();
+    t.change((draft) => {
+      draft.inputs[0]!.status = "answered";
+      draft.inputs[0]!.answer = "pnpm";
+    });
+    await vi.advanceTimersByTimeAsync(40_000);
+    expect(t.events().at(-1)).toMatchObject({
+      event: "input.answered",
+      inputId: "q1",
+    });
+
+    t.ask("Which lockfile?");
+    await vi.advanceTimersByTimeAsync(300);
+    expect(t.open).toHaveBeenCalledTimes(2);
+
+    await vi.advanceTimersByTimeAsync(9_700);
+    t.ask("Which registry?");
+    await vi.advanceTimersByTimeAsync(300);
+    expect(t.open).toHaveBeenCalledTimes(2);
+    const needed = t.events().at(-1);
+    expect(needed).toEqual({
+      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).",
+      question: "Which registry?",
+      options: [
+        { id: "pnpm", label: "pnpm" },
+        { id: "npm", label: "npm" },
+      ],
+      answerFormat: "one option id, or the user's own text",
+      answer: `${ANSWER} q3 <one option id, or the user's own text>`,
+    });
+
+    // The agent asked in its own conversation and answers for the user.
+    await answerNeed(t.client, "q3", "npm");
+    await vi.advanceTimersByTimeAsync(300);
+    expect(t.events().at(-1)).toMatchObject({
+      event: "input.answered",
+      inputId: "q3",
+      answer: "npm",
+    });
+    await t.stream.stop();
+  });
+
+  it("tells the agent when the tab closed with a question waiting", async () => {
+    const t = await start();
+    t.ask("Which package manager?");
+    await vi.advanceTimersByTimeAsync(1_000);
+    t.heartbeat();
+    t.change((draft) => {
+      draft.browser!.connected = false;
+    });
+    await vi.advanceTimersByTimeAsync(8_000);
+    expect(t.events().at(-1)).toMatchObject({
+      event: "input.needed",
+      id: "q1",
+      reason: "browser-closed",
+      message:
+        "The user closed the setup tab. Ask the user directly in the terminal: Which package manager? Options: pnpm (pnpm), npm (npm).",
+    });
+    // A question right after: inside the 30s window, and the tab is known to be gone.
+    t.ask("Which registry?");
+    await vi.advanceTimersByTimeAsync(300);
+    expect(t.events().at(-1)).toMatchObject({
+      id: "q2",
+      reason: "browser-closed",
+    });
+    await t.stream.stop();
+  });
+
+  it("without browser options, streams the way setup-agent always has", async () => {
+    const fake = fakeClient();
+    const lines: StreamEvent[][] = [];
+    const stream = await followSetup(fake.client, {
+      print: (events) => lines.push(events),
+      agent: { cwd: "/app" },
+    });
+    fake.ask("Which package manager?");
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(lines).toEqual([]);
+    await stream.stop();
+  });
+});

package/src/stream.ts

@@ -0,0 +1,314 @@
+import spawn from "cross-spawn";
+import { detectAgentKind } from "./agents";
+import { createBrowserGate } from "./browser";
+import type { AskReason, BrowserGateAction } from "./browser";
+import type { CheckoutClient } from "./client";
+import { formatTerminalQuestion, terminalQuestion } from "./needs";
+import type { TerminalQuestion } from "./needs";
+import {
+  AGENT_HEARTBEAT_MS,
+  classifyChoiceAnswer,
+  parseMultipleAnswer,
+} from "./protocol";
+import type { Checkout } from "./protocol";
+
+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);
+
+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.";
+
+export const diffEvents = (
+  before: Checkout.State,
+  after: Checkout.State,
+): StreamEvent[] => {
+  const events: StreamEvent[] = [];
+  if (before.status === "waiting" && after.status === "planning") {
+    events.push({ event: "planning.started" });
+  }
+  for (const entry of after.log) {
+    if (
+      entry.role === "user" &&
+      entry.acknowledgedAt === undefined &&
+      !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) {
+    const previous = before.inputs.find(
+      (candidate) => candidate.id === input.id,
+    );
+    if (previous?.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) {
+    const previous = before.plans.find(
+      (candidate) => candidate.revision === plan.revision,
+    );
+    if (previous?.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;
+};
+
+export const answerFields = (input: Checkout.Input, answer: string) => ({
+  answer: (input.multiple && parseMultipleAnswer(answer)) || answer,
+  ...(input.note !== undefined && { note: input.note }),
+  ...(input.kind === "choice" &&
+    classifyChoiceAnswer(input, answer) === "custom" && {
+      custom: true as const,
+    }),
+});
+
+/** The setup page that joins a link; the link rides in the fragment, which never reaches a server. */
+export const setupPageUrl = (
+  setupAppUrl: string,
+  linkId: string,
+  setupId: string,
+) => `${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: string) => {
+  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. */
+export const shellWord = (value: string) =>
+  /^[A-Za-z0-9._~%/:@=+,-]+$/.test(value)
+    ? value
+    : `'${value.replaceAll("'", `'\\''`)}'`;
+
+const ASK_MESSAGES: Record<
+  AskReason,
+  (question: string, context: { agoSeconds: number; page: 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}`,
+  "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: BrowserGateAction,
+  answerCommand: string,
+  page: string,
+): StreamEvent => {
+  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) / 1000),
+      page,
+    }),
+    ...question,
+    answer: `${answerCommand} ${need.id} <${question.answerFormat}>`,
+  };
+};
+
+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 const followSetup = async (
+  client: Pick<CheckoutClient, "state" | "subscribe" | "commands">,
+  { print, agent, browser }: FollowSetupOptions = {},
+) => {
+  const write =
+    print ??
+    ((events: StreamEvent[]) => {
+      process.stdout.write(`${JSON.stringify(events)}\n`);
+    });
+  const page = (state: Checkout.State) =>
+    browser && state.id !== null
+      ? setupPageUrl(browser.setupAppUrl, browser.linkId, state.id)
+      : undefined;
+  const gate =
+    browser &&
+    createBrowserGate({
+      url: page,
+      ...(browser.canOpen !== undefined && { canOpen: browser.canOpen }),
+      ...(browser.now !== undefined && { now: browser.now }),
+    });
+  let previous = client.state;
+  if (previous === undefined) throw new Error("the setup has no state");
+  let pending = diffEvents({ ...previous, log: [] }, previous);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const flush = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    if (pending.length > 0) write(pending);
+    pending = [];
+  };
+  const runGate = (state: Checkout.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 === undefined) return;
+    pending.push(...diffEvents(previous!, next));
+    previous = next;
+    runGate(next);
+    if (pending.length > 0 && timer === undefined)
+      timer = setTimeout(flush, 200);
+  });
+  runGate(previous);
+  flush();
+  // Presence lapses without a state change, so the gate also looks every second.
+  const tick =
+    gate &&
+    setInterval(() => {
+      runGate(previous!);
+      flush();
+    }, 1_000);
+  const kind = agent?.kind ?? detectAgentKind();
+  try {
+    await client.commands["agent/hello"]({
+      cwd: agent?.cwd ?? process.cwd(),
+      ...(kind !== undefined && { kind }),
+    });
+  } catch (error) {
+    clearInterval(tick);
+    clearTimeout(timer);
+    unsubscribe();
+    throw error;
+  }
+  const heartbeat = setInterval(() => {
+    void client.commands["agent/heartbeat"]().catch(() => {});
+  }, AGENT_HEARTBEAT_MS);
+  let stopped: Promise<void> | undefined;
+  return {
+    stop: () =>
+      (stopped ??= (async () => {
+        clearInterval(heartbeat);
+        clearInterval(tick);
+        unsubscribe();
+        flush();
+        await client.commands["agent/bye"]().catch(() => {});
+      })()),
+  };
+};