setup-agent 0.0.8 → 0.1.0

package/src/needs.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import {
+  answerNeed,
+  formatTerminalQuestion,
+  pendingNeeds,
+  terminalQuestion,
+} from "./needs";
+import { presetInput } from "./presets";
+import { initialCheckoutState } from "./protocol";
+import type { Checkout } from "./protocol";
+
+const stateWith = (...inputs: Partial<Checkout.Input>[]): Checkout.State => ({
+  ...initialCheckoutState(),
+  id: "s1",
+  createdAt: 1,
+  status: "planning",
+  plans: [{ revision: 3, markdown: "x", status: "proposed", submittedAt: 1 }],
+  inputs: inputs.map((input, index) => ({
+    id: `q${index + 1}`,
+    phase: "planning",
+    kind: "text",
+    prompt: "Where?",
+    optional: false,
+    status: "open",
+    createdAt: index + 1,
+    ...input,
+  })),
+});
+
+/** Records the commands an answer sends. */
+const clientFor = (state: Checkout.State) => {
+  const calls: [string, unknown][] = [];
+  const commands = new Proxy(
+    {},
+    {
+      get: (_, name: string) => async (params: unknown) =>
+        void calls.push([name, params]),
+    },
+  ) as Parameters<typeof answerNeed>[0]["commands"];
+  return { client: { state, commands }, calls };
+};
+
+describe("pendingNeeds", () => {
+  it("lists open inputs, a proposed plan and a proposal to close, until a follow-up or the end", () => {
+    const state = stateWith({}, { status: "answered" });
+    state.completion = { proposedAt: 9 };
+    expect(pendingNeeds(state).map((need) => need.id)).toEqual([
+      "q1",
+      "plan",
+      "finish",
+    ]);
+    state.log.push({
+      id: "l1",
+      role: "user",
+      phase: "installing",
+      at: 10,
+      text: "more",
+      acknowledgedAt: 11,
+    });
+    expect(pendingNeeds(state).map((need) => need.id)).toEqual(["q1", "plan"]);
+    state.status = "done";
+    expect(pendingNeeds(state)).toEqual([]);
+  });
+});
+
+describe("terminalQuestion", () => {
+  it("names variants as the ids the answer takes, and never asks for an API key", () => {
+    const [framework, model] = pendingNeeds(
+      stateWith(
+        presetInput("framework") as Checkout.Input,
+        presetInput("llm-provider") as Checkout.Input,
+      ),
+    ).map(terminalQuestion);
+    expect(framework!.options?.map((option) => option.id)).toEqual([
+      "ai-sdk:typescript",
+      "mastra:typescript",
+      "langgraph:python",
+      "langgraph:typescript",
+    ]);
+    expect(formatTerminalQuestion(framework!)).toMatch(
+      /^Which agent framework runs your backend\? Options: ai-sdk:typescript \(Vercel AI SDK \(TypeScript\): Shortest path/,
+    );
+    expect(model!.question).toContain("The API key is not typed here");
+    expect(model!.answerFormat).toBe(
+      "<provider>:<model>, such as openai:gpt-5",
+    );
+  });
+});
+
+describe("answerNeed", () => {
+  it("sends each kind of answer in the shape the setup takes", async () => {
+    const { client, calls } = clientFor(
+      stateWith(
+        {},
+        {
+          kind: "choice",
+          multiple: true,
+          options: [
+            { id: "slack", label: "Slack" },
+            { id: "email", label: "Email" },
+          ],
+        },
+        presetInput("llm-provider") as Checkout.Input,
+        { kind: "product", product: "cloud" },
+        { optional: true },
+      ),
+    );
+    await answerNeed(client, "q1", "apps/web", { note: " from chat " });
+    await answerNeed(client, "q2", "slack, email");
+    await answerNeed(
+      client,
+      "q3",
+      '{"provider":"anthropic","model":"claude-sonnet-5","apiKey":"sk-x"}',
+    );
+    await answerNeed(client, "q4", "add");
+    await answerNeed(client, "q5", undefined, { dismiss: true });
+    await answerNeed(client, "plan", "revise", { feedback: "use pnpm" });
+    await answerNeed(client, "plan", "approve");
+    expect(calls).toEqual([
+      [
+        "checkout/answer",
+        { inputId: "q1", answer: "apps/web", note: "from chat" },
+      ],
+      ["checkout/answer", { inputId: "q2", answer: '["slack","email"]' }],
+      [
+        "checkout/answer",
+        {
+          inputId: "q3",
+          answer: JSON.stringify({
+            provider: "anthropic",
+            model: "claude-sonnet-5",
+          }),
+        },
+      ],
+      [
+        "checkout/add-product",
+        { inputId: "q4", product: { slug: "cloud", name: "cloud" } },
+      ],
+      ["checkout/dismiss", { inputId: "q5" }],
+      [
+        "checkout/plan",
+        { id: "s1", revision: 3, decision: "revise", feedback: "use pnpm" },
+      ],
+      ["checkout/plan", { id: "s1", revision: 3, decision: "approve" }],
+    ]);
+  });
+
+  it("refuses an answer the setup would before sending it, and closes only a current proposal", async () => {
+    const { client, calls } = clientFor(
+      stateWith(
+        presetInput("framework") as Checkout.Input,
+        presetInput("llm-provider") as Checkout.Input,
+        {
+          status: "answered",
+        },
+      ),
+    );
+    await expect(answerNeed(client, "q1", "langgraph")).rejects.toThrow(
+      "langgraph:python",
+    );
+    await expect(answerNeed(client, "q2", "nope:x")).rejects.toThrow(
+      "providers",
+    );
+    await expect(answerNeed(client, "q3", "x")).rejects.toThrow(
+      "already answered",
+    );
+    await expect(answerNeed(client, "plan", "revise")).rejects.toThrow(
+      "--feedback",
+    );
+    await expect(answerNeed(client, "finish", "close")).rejects.toThrow(
+      "no proposal to close",
+    );
+    client.state.completion = { proposedAt: 9 };
+    await answerNeed(client, "finish", "close");
+    expect(calls).toEqual([["checkout/finish", undefined]]);
+    await expect(
+      answerNeed(client, "q1", undefined, { dismiss: true }),
+    ).rejects.toThrow("required");
+  });
+});

package/src/needs.ts

@@ -0,0 +1,273 @@
+import type { CheckoutClient } from "./client";
+import {
+  classifyChoiceAnswer,
+  currentPlan,
+  finishProposed,
+  isClosed,
+  isValidEntryPointAnswer,
+  isValidModelAnswer,
+  parseModelAnswer,
+  openInputs,
+  parseMultipleAnswer,
+} from "./protocol";
+import type { Checkout } from "./protocol";
+
+/**
+ * Something the setup waits on the user for: an open question, a proposed
+ * plan, or the agent's proposal to close. `id` is what `answer` takes: the
+ * input id, `plan` or `finish`.
+ */
+export type SetupNeed =
+  | { id: string; kind: "input"; input: Checkout.Input }
+  | { id: "plan"; kind: "plan"; plan: Checkout.Plan }
+  | { id: "finish"; kind: "finish"; completion: Checkout.Completion };
+
+/** What the setup waits on the user for right now, oldest first. */
+export const pendingNeeds = (state: Checkout.State): SetupNeed[] => {
+  if (state.createdAt === null || isClosed(state)) return [];
+  const needs: SetupNeed[] = openInputs(state).map((input) => ({
+    id: input.id,
+    kind: "input",
+    input,
+  }));
+  const plan = currentPlan(state);
+  if (plan?.status === "proposed")
+    needs.push({ id: "plan", kind: "plan", plan });
+  // Any message after the proposal, acknowledged or not, means more work first.
+  if (
+    finishProposed(state) &&
+    !state.log.some(
+      (entry) =>
+        entry.role === "user" && entry.at > state.completion!.proposedAt,
+    )
+  )
+    needs.push({ id: "finish", kind: "finish", completion: state.completion! });
+  return needs;
+};
+
+/** Tells one need from a later one with the same id, such as a new plan revision. */
+export const needKey = (need: SetupNeed) =>
+  need.kind === "input"
+    ? `input:${need.input.id}:${need.input.createdAt}`
+    : need.kind === "plan"
+      ? `plan:${need.plan.revision}:${need.plan.submittedAt}`
+      : `finish:${need.completion.proposedAt}`;
+
+type NeedOption = { id: string; label: string; description?: string };
+
+/** A need as a question the agent can put to the user in its own conversation. */
+export type TerminalQuestion = {
+  question: string;
+  options?: NeedOption[];
+  multiple?: true;
+  /** The shape of the answer, as the `answer` command takes it. */
+  answerFormat: string;
+};
+
+/** Options as the ids an answer names: `<option>:<variant>` for an option with variants. */
+const optionList = (input: Checkout.Input): NeedOption[] =>
+  (input.options ?? []).flatMap((option) => {
+    const where = option.entryPoint
+      ? ` (${option.entryPoint.formFactor}; ${option.entryPoint.placement}; ${option.entryPoint.trigger})`
+      : "";
+    const description = `${option.description ?? ""}${where}`.trim();
+    const entry = (id: string, label: string) => ({
+      id,
+      label,
+      ...(description && { description }),
+    });
+    return option.variants?.length
+      ? option.variants.map((variant) =>
+          entry(
+            `${option.id}:${variant.id}`,
+            `${option.label} (${variant.label})`,
+          ),
+        )
+      : [entry(option.id, option.label)];
+  });
+
+const ANSWER_FORMATS: Record<Checkout.InputKind, string> = {
+  text: "the user's text, as one shell word",
+  product: "add or decline",
+  model: "<provider>:<model>, such as openai:gpt-5",
+  "entry-point": "one option id",
+  choice: "one option id, or the user's own text",
+};
+
+export const terminalQuestion = (need: SetupNeed): TerminalQuestion => {
+  if (need.kind === "plan")
+    return {
+      question:
+        "Approve the setup plan? Show the user the plan you proposed and ask whether to go ahead or what to change.",
+      options: [
+        { id: "approve", label: "Approve the plan" },
+        { id: "revise", label: "Ask for changes (pass --feedback)" },
+      ],
+      answerFormat: 'approve, or revise --feedback "<what to change>"',
+    };
+  if (need.kind === "finish")
+    return {
+      question: `Everything is installed${need.completion.preview ? ` and running at ${need.completion.preview}` : ""}. Close the setup, or keep going?`,
+      options: [{ id: "close", label: "Close the setup" }],
+      answerFormat:
+        "close; if the user wants more, do it and run done again instead",
+    };
+  const { input } = need;
+  const options =
+    input.kind === "product"
+      ? [
+          { id: "add", label: `Add ${input.product ?? "the product"}` },
+          { id: "decline", label: "Leave it out" },
+        ]
+      : input.kind === "text"
+        ? undefined
+        : optionList(input);
+  return {
+    question: `${input.prompt.trim() || "Your agent needs an answer."}${input.optional ? " (optional; --dismiss skips it)" : ""}${input.kind === "model" ? " The API key is not typed here: the user adds it to the project's env file themselves." : ""}`,
+    ...(options && { options }),
+    ...(input.multiple && { multiple: true as const }),
+    answerFormat: input.multiple
+      ? "option ids separated by commas, or the user's own text"
+      : ANSWER_FORMATS[input.kind],
+  };
+};
+
+/** The question as one line: the prompt, then its options. */
+export const formatTerminalQuestion = ({
+  question,
+  options,
+  multiple,
+}: TerminalQuestion) =>
+  options
+    ? `${question} Options${multiple ? ", any number" : ""}: ${options
+        .map(
+          (option) =>
+            `${option.id} (${option.label}${option.description ? `: ${option.description}` : ""})`,
+        )
+        .join(", ")}.`
+    : question;
+
+const ids = (input: Checkout.Input) =>
+  optionList(input)
+    .map((option) => option.id)
+    .join(", ");
+
+/** `value` as the wire answer `input` takes, or an error naming the shape it needs. */
+const wireAnswer = (input: Checkout.Input, value: string) => {
+  const trimmed = value.trim();
+  if (input.kind === "model") {
+    const at = trimmed.indexOf(":");
+    const json = trimmed.startsWith("{")
+      ? trimmed
+      : JSON.stringify({
+          provider: trimmed.slice(0, at),
+          model: trimmed.slice(at + 1),
+        });
+    if (at <= 0 && !trimmed.startsWith("{"))
+      throw new Error(
+        `a model answer is "<provider>:<model>", such as openai:gpt-5`,
+      );
+    if (!isValidModelAnswer(input, json))
+      throw new Error(
+        `a model answer names one of the providers: ${ids(input)}`,
+      );
+    // Only the documented fields; anything else (a key, say) never reaches the setup.
+    return JSON.stringify(parseModelAnswer(json));
+  }
+  if (input.kind === "entry-point") {
+    if (!isValidEntryPointAnswer(input, trimmed))
+      throw new Error(`an entry-point answer is one of: ${ids(input)}`);
+    return trimmed;
+  }
+  if (input.kind === "choice") {
+    const answer =
+      input.multiple && parseMultipleAnswer(trimmed) === undefined
+        ? JSON.stringify(
+            trimmed
+              .split(",")
+              .map((entry) => entry.trim())
+              .filter(Boolean),
+          )
+        : trimmed;
+    if (classifyChoiceAnswer(input, answer) === "invalid")
+      throw new Error(
+        `"${value}" names an option without a valid variant; pick from: ${ids(input)}`,
+      );
+    return answer;
+  }
+  if (trimmed === "") throw new Error("an answer cannot be empty");
+  return value;
+};
+
+/**
+ * Answers a need from the agent's side, with what the user said in the
+ * agent's own conversation: an input, the plan (`approve` or `revise` with
+ * feedback) or the proposal to close (`close`).
+ */
+export const answerNeed = async (
+  client: Pick<CheckoutClient, "state" | "commands">,
+  id: string,
+  value: string | undefined,
+  options: { note?: string; feedback?: string; dismiss?: boolean } = {},
+) => {
+  const state = client.state;
+  if (state === undefined) throw new Error("the setup has no state");
+  const { commands } = client;
+  if (id === "plan") {
+    const plan = currentPlan(state);
+    if (plan === undefined) throw new Error("no plan has been proposed");
+    const feedback = options.feedback?.trim();
+    if (value !== "approve" && (value !== "revise" || !feedback))
+      throw new Error(
+        'answer the plan with approve, or revise --feedback "<what to change>"',
+      );
+    await commands["checkout/plan"]({
+      ...(state.id !== null && { id: state.id }),
+      revision: plan.revision,
+      ...(value === "approve"
+        ? { decision: "approve" as const }
+        : { decision: "revise" as const, feedback: feedback! }),
+    });
+    return { ok: true, id, decision: value };
+  }
+  if (id === "finish") {
+    if (!pendingNeeds(state).some((need) => need.id === "finish"))
+      throw new Error(
+        "no proposal to close is waiting; finish the user's follow-up and run done again",
+      );
+    if (value !== "close")
+      throw new Error(
+        "answer finish with close; if the user wants more, do it and run done again",
+      );
+    await commands["checkout/finish"]();
+    return { ok: true, id, status: "done" };
+  }
+  const input = state.inputs.find((candidate) => candidate.id === id);
+  if (input === undefined) throw new Error(`no input "${id}"`);
+  if (input.status !== "open")
+    throw new Error(`input "${id}" is already ${input.status}`);
+  if (options.dismiss && !input.optional)
+    throw new Error(`input "${id}" is required; answer it instead`);
+  if (options.dismiss || (input.kind === "product" && value === "decline")) {
+    await commands["checkout/dismiss"]({ inputId: id });
+    return { ok: true, id, status: "dismissed" };
+  }
+  if (value === undefined) throw new Error(`usage: answer ${id} <answer>`);
+  if (input.kind === "product") {
+    if (value !== "add")
+      throw new Error("answer a product with add or decline");
+    const slug = input.product ?? "";
+    await commands["checkout/add-product"]({
+      inputId: id,
+      product: { slug, name: slug },
+    });
+  } else {
+    const note = options.note?.trim();
+    await commands["checkout/answer"]({
+      inputId: id,
+      answer: wireAnswer(input, value),
+      ...(note && { note }),
+    });
+  }
+  return { ok: true, id, status: "answered" };
+};

package/src/protocol.ts

@@ -174,6 +174,15 @@ export namespace Checkout {
       /** When the command was first run against this checkout, before the agent joined the stream. */
       introducedAt: number | null;
     };
+    /**
+     * The setup page in the user's browser, while one has joined the link.
+     * Absent on hosts older than browser presence.
+     */
+    browser?: {
+      lastSeenAt: number | null;
+      /** False once the page said goodbye; heartbeats set it again. */
+      connected: boolean;
+    };
     /** Every revision in order; the last one is current. */
     plans: Plan[];
     steps: Step[];
@@ -231,6 +240,10 @@ export namespace Checkout {
     "agent/hello": (params: { cwd?: string; kind?: string }) => void;
     "agent/heartbeat": () => void;
     "agent/bye": () => void;
+    /** The setup page is open and joined; sent every BROWSER_HEARTBEAT_MS. */
+    "browser/heartbeat": () => void;
+    /** The setup page is closing. */
+    "browser/bye": () => void;
     "agent/plan": (params: { markdown: string }) => { revision: number };
     "agent/add-step": (params: {
       title: string;
@@ -276,6 +289,9 @@ export namespace Checkout {
 
 export const AGENT_PRESENCE_MS = 15_000;
 export const AGENT_HEARTBEAT_MS = 5_000;
+/** A background tab's timers slow down, so a browser counts as present for longer than an agent. */
+export const BROWSER_PRESENCE_MS = 20_000;
+export const BROWSER_HEARTBEAT_MS = 5_000;
 
 export const initialCheckoutState = (): Checkout.State => ({
   version: 2,
@@ -291,6 +307,7 @@ export const initialCheckoutState = (): Checkout.State => ({
     kind: null,
     introducedAt: null,
   },
+  browser: { lastSeenAt: null, connected: false },
   plans: [],
   steps: [],
   inputs: [],

package/src/sdk.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from "vitest";
+import * as sdk from "./sdk";
+import { initialCheckoutState } from "./protocol";
+import type { Checkout } from "./protocol";
+import type { CheckoutClient } from "./client";
+
+describe("setup-agent/sdk", () => {
+  it("exports only what a CLI embeds setup with", () => {
+    expect(Object.keys(sdk)).toEqual(["runAgentSetup"]);
+  });
+
+  it("runs a whole agent setup: session, briefing, then a stream that opens the page on the first question", async () => {
+    vi.useFakeTimers({ now: 5_000_000 });
+    try {
+      let state: Checkout.State = initialCheckoutState();
+      const listeners = new Set<() => void>();
+      const calls: [string, unknown][] = [];
+      const commands = new Proxy(
+        {},
+        {
+          get: (_, name: string) => async (params: unknown) => {
+            calls.push([name, params]);
+            if (name === "checkout/create") {
+              const { id, products } = params as {
+                id: string;
+                products: Checkout.Product[];
+              };
+              state = { ...state, id, products, createdAt: Date.now() };
+            }
+            if (name === "checkout/begin-plan")
+              state = { ...state, status: "planning" };
+          },
+        },
+      );
+      const client = {
+        get state() {
+          return state;
+        },
+        subscribe: (listener: () => void) => {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+        commands,
+        dispose: vi.fn(),
+      } as unknown as CheckoutClient;
+      const connect = vi.fn(async () => client);
+      const open = vi.fn();
+      let out = "";
+      const lines: unknown[] = [];
+      const { session, stream } = await sdk.runAgentSetup({
+        server: "https://checkout.test",
+        setupAppUrl: "https://setup.test",
+        products: [{ slug: "assistant-ui", name: "assistant-ui" }],
+        command: "npx my-tool setup",
+        name: "my-tool setup",
+        env: {},
+        connect,
+        open,
+        write: (text) => (out += text),
+        stream: {
+          print: (events) => lines.push(...events),
+          agent: { cwd: "/app" },
+        },
+      });
+      expect(out).toMatch(/^my-tool setup is running\./);
+      expect(out).toContain(
+        `npx my-tool setup https://checkout.test/${session.linkId} stream`,
+      );
+      expect(out).toContain("run_in_background");
+      expect(out).toContain('"input.needed"');
+      expect(out).toContain('"browser.opened"');
+      expect(out).not.toContain("start a persistent Monitor");
+      expect(out).toContain("opens the user's browser by itself");
+      expect(out).not.toContain("npx setup-agent");
+      expect(out).not.toContain("click Begin plan");
+      expect(out).toContain(session.browserUrl);
+      expect(open).not.toHaveBeenCalled();
+      expect(calls.map(([name]) => name)).toEqual([
+        "checkout/create",
+        "checkout/begin-plan",
+        "agent/intro",
+        "agent/hello",
+      ]);
+      expect(connect).toHaveBeenCalledTimes(1);
+
+      state = {
+        ...state,
+        inputs: [
+          {
+            id: "q1",
+            phase: "planning",
+            kind: "text",
+            prompt: "Which project?",
+            optional: false,
+            status: "open",
+            createdAt: Date.now(),
+          },
+        ],
+      };
+      for (const listener of listeners) listener();
+      await vi.advanceTimersByTimeAsync(300);
+      expect(open).toHaveBeenCalledWith(session.browserUrl);
+      expect(lines).toEqual([
+        expect.objectContaining({ event: "browser.opened", id: "q1" }),
+      ]);
+      await stream.stop();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});