setup-agent 0.0.1

package/src/client.ts

@@ -0,0 +1,35 @@
+import { StatewireClient, StatewireHttp } from "statewire";
+import type { Checkout } from "./protocol";
+
+export type CheckoutClient = StatewireClient<
+  Checkout.State | undefined,
+  Checkout.Commands
+>;
+
+/** Attach to a checkout by its base URL and resolve once its state has arrived. */
+export const connectCheckout = (url: string): Promise<CheckoutClient> =>
+  new Promise((resolve, reject) => {
+    const client: CheckoutClient = new StatewireClient({
+      transport: StatewireHttp({ url }),
+      onError: (error) => reject(error),
+    });
+    const settle = () => {
+      if (client.state === undefined) {
+        if (client.connection.status !== "stopped") return;
+        unsubscribe();
+        client.dispose();
+        reject(
+          new Error(
+            `checkout unreachable: ${client.connection.reason}${
+              client.connection.message ? ` (${client.connection.message})` : ""
+            }`,
+          ),
+        );
+        return;
+      }
+      unsubscribe();
+      resolve(client);
+    };
+    const unsubscribe = client.subscribe(settle);
+    settle();
+  });

package/src/host.ts

@@ -0,0 +1,435 @@
+import { resource } from "@assistant-ui/tap";
+import {
+  StatewireReject,
+  getStateHost,
+  useStatewireCommands,
+  useStatewireState,
+} from "statewire/host";
+import {
+  classifyChoiceAnswer,
+  currentPlan,
+  initialCheckoutState,
+  isAgentPresent,
+  isClosed,
+  isValidModelAnswer,
+  parsePreviewUrl,
+} from "./protocol";
+import type { Checkout } from "./protocol";
+
+const reject = (reason: Checkout.RejectionReason, message: string) =>
+  new StatewireReject(message, { payload: { reason } });
+
+const useCheckoutHost = (restored: unknown) => {
+  const [state] = useStatewireState<Checkout.State>(() => {
+    const initial = initialCheckoutState();
+    if (restored === undefined) return initial;
+    const snapshot = restored as Partial<Checkout.State>;
+    if (snapshot.version !== 2) return initial;
+    return {
+      ...initial,
+      ...snapshot,
+      agent: { ...initial.agent, ...snapshot.agent },
+    };
+  });
+
+  const requireOpen = () => {
+    if (state.createdAt === null) {
+      throw reject("not-created", "the checkout has not been created yet");
+    }
+    if (isClosed(state)) {
+      throw reject("closed", `the checkout is ${state.status}`);
+    }
+  };
+
+  const requireStarted = () => {
+    requireOpen();
+    if (state.status === "waiting") {
+      throw reject(
+        "planning-not-started",
+        'ask the user to return to their browser and click "Begin plan"; wait with "wait start"',
+      );
+    }
+  };
+
+  const requireInstalling = () => {
+    requireOpen();
+    if (state.status !== "installing") {
+      throw reject(
+        "plan-required",
+        "steps run once the user has approved a plan; submit one with plan",
+      );
+    }
+  };
+
+  const findStep = (stepId: string) => {
+    const step = state.steps.find((candidate) => candidate.id === stepId);
+    if (!step) throw reject("unknown-step", `no step "${stepId}"`);
+    return step;
+  };
+
+  const findInput = (inputId: string) => {
+    const input = state.inputs.find((candidate) => candidate.id === inputId);
+    if (!input) throw reject("unknown-input", `no input "${inputId}"`);
+    if (input.status !== "open") {
+      throw reject("input-closed", `input "${inputId}" is ${input.status}`);
+    }
+    return input;
+  };
+
+  const touchAgent = () => {
+    state.agent.lastSeenAt = Date.now();
+    state.agent.connected = true;
+  };
+
+  const ask = (seed: Checkout.InputSeed & { stepId?: string }) => {
+    const kind = seed.kind ?? "text";
+    if (kind === "product") {
+      if (!seed.product) {
+        throw reject("invalid-input", "a product input names a product");
+      }
+      if (state.products.some((product) => product.slug === seed.product)) {
+        throw reject(
+          "invalid-input",
+          `"${seed.product}" is already part of this checkout`,
+        );
+      }
+    } else if (kind !== "text" && !seed.options?.length) {
+      throw reject("invalid-input", `a ${kind} input needs options`);
+    }
+    if (
+      seed.multiple &&
+      (kind !== "choice" || seed.options?.some((option) => option.variants))
+    ) {
+      throw reject(
+        "invalid-input",
+        "only a choice whose options have no variants accepts several answers",
+      );
+    }
+    if (
+      seed.default !== undefined &&
+      !seed.options?.some((option) => option.id === seed.default)
+    ) {
+      throw reject(
+        "invalid-input",
+        `no option "${seed.default}" to default to`,
+      );
+    }
+    if (seed.stepId !== undefined) findStep(seed.stepId);
+    const id = `q${state.inputs.length + 1}`;
+    const stepId =
+      seed.stepId ?? state.steps.find((step) => step.status === "active")?.id;
+    state.inputs.push({
+      id,
+      phase: state.status,
+      kind,
+      ...(seed.preset !== undefined && { preset: seed.preset }),
+      prompt: seed.prompt,
+      ...(seed.placeholder !== undefined && { placeholder: seed.placeholder }),
+      ...(seed.options !== undefined && { options: seed.options }),
+      ...(seed.multiple && { multiple: true }),
+      ...(kind === "product" && { product: seed.product }),
+      ...(seed.default !== undefined && { default: seed.default }),
+      ...(seed.help !== undefined && { help: seed.help }),
+      optional: seed.optional ?? false,
+      status: "open",
+      ...(stepId !== undefined && { stepId }),
+      createdAt: Date.now(),
+    });
+    return { inputId: id };
+  };
+
+  const dismissOpenInputs = () => {
+    for (const input of state.inputs) {
+      if (input.status === "open") {
+        input.status = "dismissed";
+        input.answeredAt = Date.now();
+      }
+    }
+  };
+
+  const log = (text: string, stepId?: string) => {
+    state.log.push({
+      id: `l${state.log.length + 1}`,
+      role: "agent",
+      phase: state.status,
+      at: Date.now(),
+      text,
+      ...(stepId !== undefined && { stepId }),
+    });
+  };
+
+  const updateStep = (
+    step: Checkout.Step,
+    status: Checkout.StepStatus,
+    note?: string,
+  ) => {
+    const changed = step.status !== status;
+    step.status = status;
+    if (note !== undefined) step.note = note;
+    if (changed && (status === "done" || status === "skipped")) {
+      log(
+        `${status === "done" ? "Completed" : "Skipped"}: ${step.title}${step.note ? `\n\n${step.note}` : ""}`,
+        step.id,
+      );
+    }
+  };
+
+  const commands = useStatewireCommands<Checkout.Commands>({
+    "checkout/create": ({ id, products, instructions }) => {
+      if (state.id === id) {
+        throw reject("already-created", "the checkout already exists");
+      }
+      const fresh = initialCheckoutState();
+      if (!isAgentPresent(state)) state.agent = fresh.agent;
+      state.id = id;
+      state.status = fresh.status;
+      delete state.completion;
+      state.plans = fresh.plans;
+      state.steps = fresh.steps;
+      state.inputs = fresh.inputs;
+      state.log = fresh.log;
+      state.createdAt = Date.now();
+      state.instructions = instructions?.trim() ?? "";
+      state.products = products.map((product) => ({
+        slug: product.slug,
+        name: product.name,
+        ...(product.guide !== undefined && { guide: product.guide }),
+      }));
+    },
+    "checkout/begin-plan": () => {
+      requireOpen();
+      if (state.status === "waiting") state.status = "planning";
+    },
+    "checkout/answer": ({ inputId, answer, note }) => {
+      requireOpen();
+      const input = findInput(inputId);
+      if (
+        input.kind === "choice" &&
+        classifyChoiceAnswer(input, answer) === "invalid"
+      ) {
+        throw reject(
+          "invalid-answer",
+          input.multiple
+            ? `"${answer}" is not a JSON array of option ids`
+            : `"${answer}" names an option without a valid variant`,
+        );
+      }
+      if (input.kind === "model" && !isValidModelAnswer(input, answer)) {
+        throw reject(
+          "invalid-answer",
+          "a model answer is JSON with provider and model",
+        );
+      }
+      if (input.kind === "product") {
+        throw reject(
+          "invalid-answer",
+          "a product input is answered with checkout/add-product",
+        );
+      }
+      if (input.kind === "text" && answer.trim() === "") {
+        throw reject("invalid-answer", "an answer cannot be empty");
+      }
+      input.status = "answered";
+      input.answeredAt = Date.now();
+      input.answer = answer;
+      if (note !== undefined && note.trim() !== "") input.note = note.trim();
+    },
+    "checkout/add-product": ({ inputId, product }) => {
+      requireOpen();
+      const input = findInput(inputId);
+      if (input.kind !== "product" || input.product !== product.slug) {
+        throw reject(
+          "invalid-answer",
+          `input "${inputId}" does not propose "${product.slug}"`,
+        );
+      }
+      if (!state.products.some((entry) => entry.slug === product.slug)) {
+        state.products.push({
+          slug: product.slug,
+          name: product.name,
+          ...(product.guide !== undefined && { guide: product.guide }),
+        });
+      }
+      input.status = "answered";
+      input.answer = "added";
+      input.answeredAt = Date.now();
+    },
+    "checkout/message": ({ text }) => {
+      requireOpen();
+      if (text.trim() === "")
+        throw reject("empty-message", "a message cannot be empty");
+      const stepId = state.steps.find((step) => step.status === "active")?.id;
+      state.log.push({
+        id: `l${state.log.length + 1}`,
+        role: "user",
+        phase: state.status,
+        ...(stepId !== undefined && { stepId }),
+        at: Date.now(),
+        text: text.trim(),
+      });
+    },
+    "agent/ack": ({ messageId }) => {
+      requireOpen();
+      const message = state.log.find(
+        (entry) => entry.id === messageId && entry.role === "user",
+      );
+      if (!message)
+        throw reject("unknown-message", `no user message "${messageId}"`);
+      message.acknowledgedAt ??= Date.now();
+    },
+    "checkout/dismiss": ({ inputId }) => {
+      requireOpen();
+      const input = findInput(inputId);
+      input.status = "dismissed";
+      input.answeredAt = Date.now();
+    },
+    "checkout/plan": (params) => {
+      requireOpen();
+      const plan = currentPlan(state);
+      if (plan === undefined) {
+        throw reject("no-plan", "the agent has not proposed a plan yet");
+      }
+      if (plan.status !== "proposed") {
+        throw reject("plan-decided", `the plan is already ${plan.status}`);
+      }
+      if (params.decision === "approve") {
+        plan.status = "approved";
+        plan.decidedAt = Date.now();
+        state.status = "installing";
+        return;
+      }
+      if (params.feedback.trim() === "") {
+        throw reject("feedback-required", "say what should change");
+      }
+      plan.status = "changes-requested";
+      plan.decidedAt = Date.now();
+      plan.feedback = params.feedback.trim();
+    },
+    "checkout/cancel": () => {
+      if (state.status === "cancelled") return;
+      state.status = "cancelled";
+      dismissOpenInputs();
+    },
+    "checkout/finish": () => {
+      requireOpen();
+      if (state.completion === undefined) {
+        throw reject(
+          "finish-not-proposed",
+          "the agent has not proposed to finish yet",
+        );
+      }
+      dismissOpenInputs();
+      state.status = "done";
+      log("Setup complete.");
+    },
+    "agent/intro": ({ kind } = {}) => {
+      requireOpen();
+      if (state.agent.introducedAt === null) {
+        state.agent.introducedAt = Date.now();
+      }
+      if (kind !== undefined) state.agent.kind = kind;
+    },
+    "agent/hello": ({ cwd, kind } = {}) => {
+      touchAgent();
+      if (cwd !== undefined) state.agent.cwd = cwd;
+      if (kind !== undefined) state.agent.kind = kind;
+    },
+    "agent/heartbeat": () => {
+      touchAgent();
+    },
+    "agent/bye": () => {
+      state.agent.connected = false;
+    },
+    "agent/plan": ({ markdown }) => {
+      requireStarted();
+      touchAgent();
+      if (markdown.trim() === "") {
+        throw reject("empty-plan", "the plan is empty");
+      }
+      if (state.status === "installing") {
+        throw reject("plan-decided", "the plan is already approved");
+      }
+      const revision = state.plans.length + 1;
+      state.plans.push({
+        revision,
+        markdown: markdown.trim(),
+        status: "proposed",
+        submittedAt: Date.now(),
+      });
+      return { revision };
+    },
+    "agent/add-step": ({ title, detail, product, active }) => {
+      requireInstalling();
+      if (
+        product !== undefined &&
+        !state.products.some((candidate) => candidate.slug === product)
+      ) {
+        throw reject("unknown-product", `no product "${product}"`);
+      }
+      const id = `s${state.steps.length + 1}`;
+      state.steps.push({
+        id,
+        title,
+        ...(detail !== undefined && { detail }),
+        status: active ? "active" : "pending",
+        ...(product !== undefined && { product }),
+        createdAt: Date.now(),
+      });
+      return { stepId: id };
+    },
+    "agent/step": ({ stepId, status, note }) => {
+      requireInstalling();
+      const step = findStep(stepId);
+      updateStep(step, status, note);
+    },
+    "agent/ask": (seed) => {
+      requireStarted();
+      touchAgent();
+      return ask(seed);
+    },
+    "agent/log": ({ text }) => {
+      requireOpen();
+      touchAgent();
+      const stepId = state.steps.find((step) => step.status === "active")?.id;
+      log(text, stepId);
+    },
+    "agent/done": ({ summary, preview } = {}) => {
+      requireInstalling();
+      const previewUrl = parsePreviewUrl(preview?.trim());
+      if (preview !== undefined && !previewUrl) {
+        throw reject(
+          "invalid-preview",
+          "a preview is an http URL on localhost, such as http://localhost:3000",
+        );
+      }
+      touchAgent();
+      for (const step of state.steps) {
+        if (step.status === "pending" || step.status === "active") {
+          updateStep(step, "done");
+        }
+      }
+      log(summary?.trim() || "Everything is installed.");
+      state.completion = {
+        proposedAt: Date.now(),
+        ...(previewUrl && { preview: previewUrl.href }),
+      };
+    },
+  });
+
+  const source = getStateHost(state)!;
+  return {
+    state,
+    commands,
+    snapshot: source.snapshot,
+    subscribe: (listener: () => void) => {
+      source.setOnChange(listener);
+      return () => source.setOnChange(null);
+    },
+  };
+};
+
+/** The checkout statewire host; pass the durable object's restored snapshot. */
+export const CheckoutHost = (restored?: unknown) =>
+  resource(useCheckoutHost)(restored);
+
+export type { Checkout } from "./protocol";

package/src/index.ts

@@ -0,0 +1,26 @@
+export type { Checkout, OptionIcon } from "./protocol";
+export {
+  AGENT_HEARTBEAT_MS,
+  AGENT_PRESENCE_MS,
+  OPTION_ICONS,
+  classifyChoiceAnswer,
+  currentPlan,
+  initialCheckoutState,
+  finishProposed,
+  followedUpSinceProposal,
+  isAgentPresent,
+  isClosed,
+  isOptionIcon,
+  isValidModelAnswer,
+  openInputs,
+  parseChoiceAnswer,
+  parseModelAnswer,
+  parseMultipleAnswer,
+  parsePreviewUrl,
+  planNeedsReview,
+  stepProgress,
+} from "./protocol";
+export { INPUT_PRESETS, isPresetId, presetInput } from "./presets";
+export type { PresetId, PresetOverrides } from "./presets";
+export { connectCheckout } from "./client";
+export type { CheckoutClient } from "./client";

package/src/presets.ts

@@ -0,0 +1,185 @@
+import type { Checkout } from "./protocol";
+
+const TYPESCRIPT = { id: "typescript", label: "TypeScript" };
+const PYTHON = { id: "python", label: "Python" };
+
+const DOCS = "https://www.assistant-ui.com";
+
+export type PresetId = "framework" | "llm-provider" | "project";
+
+export type PresetOverrides = {
+  /** Restrict the options to these ids, in this order; one id locks the choice in. */
+  only?: readonly string[];
+  /** Options the agent found itself, listed before the preset's own. */
+  found?: readonly { id: string; description?: string }[];
+  default?: string;
+  optional?: boolean;
+  stepId?: string;
+};
+
+type Preset = {
+  kind: Checkout.InputKind;
+  prompt: string;
+  options: Checkout.ChoiceOption[];
+  default?: string;
+  help: Checkout.InputHelp;
+};
+
+/** The standard inputs an agent can ask with `ask --preset <id>`. */
+export const INPUT_PRESETS: Record<PresetId, Preset> = {
+  framework: {
+    kind: "choice",
+    prompt: "Which agent framework runs your backend?",
+    options: [
+      {
+        id: "ai-sdk",
+        label: "Vercel AI SDK",
+        description: "Shortest path for Next.js and React",
+        icon: "vercel",
+        variants: [TYPESCRIPT],
+      },
+      {
+        id: "mastra",
+        label: "Mastra",
+        description: "Workflows, memory and tools",
+        icon: "mastra",
+        variants: [TYPESCRIPT],
+      },
+      {
+        id: "langgraph",
+        label: "LangGraph",
+        description: "Stateful graphs, Python or TypeScript",
+        icon: "langgraph",
+        variants: [PYTHON, TYPESCRIPT],
+      },
+    ],
+    help: {
+      summary:
+        "Already on one of these? Pick it. Starting fresh in Next.js, the AI SDK is the shortest path. Mastra adds workflows and memory in TypeScript. LangGraph fits a Python backend or multi-step graphs that pause for a human.",
+      href: `${DOCS}/docs/runtimes/pick-a-runtime`,
+    },
+  },
+  "llm-provider": {
+    kind: "model",
+    prompt: "Which model should the assistant use?",
+    options: [
+      {
+        id: "openai",
+        label: "OpenAI",
+        description: "OPENAI_API_KEY",
+        icon: "openai",
+      },
+      {
+        id: "anthropic",
+        label: "Anthropic",
+        description: "ANTHROPIC_API_KEY",
+        icon: "anthropic",
+      },
+      {
+        id: "google",
+        label: "Google Gemini",
+        description: "GOOGLE_GENERATIVE_AI_API_KEY",
+        icon: "google",
+      },
+      {
+        id: "openrouter",
+        label: "OpenRouter",
+        description: "OPENROUTER_API_KEY",
+        icon: "openrouter",
+      },
+      { id: "xai", label: "xAI", description: "XAI_API_KEY", icon: "xai" },
+      {
+        id: "mistral",
+        label: "Mistral",
+        description: "MISTRAL_API_KEY",
+        icon: "mistral",
+      },
+      {
+        id: "deepseek",
+        label: "DeepSeek",
+        description: "DEEPSEEK_API_KEY",
+        icon: "deepseek",
+      },
+      { id: "groq", label: "Groq", description: "GROQ_API_KEY", icon: "groq" },
+      {
+        id: "fireworks",
+        label: "Fireworks AI",
+        description: "FIREWORKS_API_KEY",
+        icon: "fireworks",
+      },
+    ],
+    default: "openai",
+    help: {
+      summary:
+        "Any of them works with every framework here. Pick the one whose API key you already have, or OpenRouter to reach many models with one key.",
+    },
+  },
+  project: {
+    kind: "choice",
+    prompt: "Which project should this go into?",
+    options: [
+      {
+        id: "new",
+        label: "New project",
+        description: "Start a fresh React app here",
+        variants: [
+          { id: "next", label: "Next.js" },
+          { id: "vite", label: "Vite" },
+          { id: "react-router", label: "React Router" },
+          { id: "tanstack-start", label: "TanStack Start" },
+          { id: "expo", label: "Expo" },
+        ],
+      },
+    ],
+    help: {
+      summary:
+        "Pick the app the assistant should live in. For a new project, Next.js is the shortest path: the assistant-ui CLI scaffolds the chat route with it. Pick Vite, React Router or TanStack Start when the rest of your stack already uses them, and Expo for a native app.",
+      href: `${DOCS}/docs/installation`,
+    },
+  },
+};
+
+export const isPresetId = (id: string): id is PresetId => id in INPUT_PRESETS;
+
+/** Build the seed for a standard input, throwing on an unknown preset, option or default. */
+export const presetInput = (
+  id: PresetId,
+  overrides: PresetOverrides = {},
+): Checkout.InputSeed & { stepId?: string } => {
+  const preset = INPUT_PRESETS[id];
+  const listed = overrides.only
+    ? overrides.only.map((optionId) => {
+        const option = preset.options.find((c) => c.id === optionId);
+        if (!option)
+          throw new Error(`preset "${id}" has no option "${optionId}"`);
+        return option;
+      })
+    : preset.options;
+  const found = (overrides.found ?? []).map((option) => {
+    if (
+      option.id.includes(":") ||
+      preset.options.some((o) => o.id === option.id)
+    ) {
+      throw new Error(`preset "${id}" cannot list "${option.id}" as an option`);
+    }
+    return { ...option, label: option.id };
+  });
+  const options = [...found, ...listed];
+  const fallback = options.some((o) => o.id === preset.default)
+    ? preset.default
+    : undefined;
+  const chosen = overrides.default ?? fallback;
+  if (chosen !== undefined && !options.some((o) => o.id === chosen)) {
+    throw new Error(`preset "${id}" has no option "${chosen}" to default to`);
+  }
+  return {
+    kind: preset.kind,
+    preset: id,
+    prompt: preset.prompt,
+    options,
+    ...(chosen !== undefined && { default: chosen }),
+    help: preset.help,
+    optional: overrides.optional ?? false,
+    ...(overrides.stepId !== undefined && { stepId: overrides.stepId }),
+  };
+};