setup-agent 0.0.1

package/dist/presets.js

@@ -0,0 +1,175 @@
+//#region src/presets.ts
+const TYPESCRIPT = {
+	id: "typescript",
+	label: "TypeScript"
+};
+const PYTHON = {
+	id: "python",
+	label: "Python"
+};
+const DOCS = "https://www.assistant-ui.com";
+/** The standard inputs an agent can ask with `ask --preset <id>`. */
+const INPUT_PRESETS = {
+	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`
+		}
+	}
+};
+const isPresetId = (id) => id in INPUT_PRESETS;
+/** Build the seed for a standard input, throwing on an unknown preset, option or default. */
+const presetInput = (id, overrides = {}) => {
+	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 options = [...(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
+		};
+	}), ...listed];
+	const fallback = options.some((o) => o.id === preset.default) ? preset.default : void 0;
+	const chosen = overrides.default ?? fallback;
+	if (chosen !== void 0 && !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 !== void 0 && { default: chosen },
+		help: preset.help,
+		optional: overrides.optional ?? false,
+		...overrides.stepId !== void 0 && { stepId: overrides.stepId }
+	};
+};
+//#endregion
+export { INPUT_PRESETS, isPresetId, presetInput };
+
+//# sourceMappingURL=presets.js.map

package/dist/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","names":["Checkout","TYPESCRIPT","id","label","PYTHON","DOCS","PresetId","PresetOverrides","only","found","description","default","optional","stepId","Preset","kind","InputKind","prompt","options","ChoiceOption","help","InputHelp","INPUT_PRESETS","Record","framework","icon","variants","summary","href","project","isPresetId","presetInput","overrides","InputSeed","preset","listed","map","optionId","option","find","c","Error","includes","some","o","fallback","undefined","chosen"],"sources":["../src/presets.ts"],"sourcesContent":["import type { Checkout } from \"./protocol\";\n\nconst TYPESCRIPT = { id: \"typescript\", label: \"TypeScript\" };\nconst PYTHON = { id: \"python\", label: \"Python\" };\n\nconst DOCS = \"https://www.assistant-ui.com\";\n\nexport type PresetId = \"framework\" | \"llm-provider\" | \"project\";\n\nexport type PresetOverrides = {\n  /** Restrict the options to these ids, in this order; one id locks the choice in. */\n  only?: readonly string[];\n  /** Options the agent found itself, listed before the preset's own. */\n  found?: readonly { id: string; description?: string }[];\n  default?: string;\n  optional?: boolean;\n  stepId?: string;\n};\n\ntype Preset = {\n  kind: Checkout.InputKind;\n  prompt: string;\n  options: Checkout.ChoiceOption[];\n  default?: string;\n  help: Checkout.InputHelp;\n};\n\n/** The standard inputs an agent can ask with `ask --preset <id>`. */\nexport const INPUT_PRESETS: Record<PresetId, Preset> = {\n  framework: {\n    kind: \"choice\",\n    prompt: \"Which agent framework runs your backend?\",\n    options: [\n      {\n        id: \"ai-sdk\",\n        label: \"Vercel AI SDK\",\n        description: \"Shortest path for Next.js and React\",\n        icon: \"vercel\",\n        variants: [TYPESCRIPT],\n      },\n      {\n        id: \"mastra\",\n        label: \"Mastra\",\n        description: \"Workflows, memory and tools\",\n        icon: \"mastra\",\n        variants: [TYPESCRIPT],\n      },\n      {\n        id: \"langgraph\",\n        label: \"LangGraph\",\n        description: \"Stateful graphs, Python or TypeScript\",\n        icon: \"langgraph\",\n        variants: [PYTHON, TYPESCRIPT],\n      },\n    ],\n    help: {\n      summary:\n        \"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.\",\n      href: `${DOCS}/docs/runtimes/pick-a-runtime`,\n    },\n  },\n  \"llm-provider\": {\n    kind: \"model\",\n    prompt: \"Which model should the assistant use?\",\n    options: [\n      {\n        id: \"openai\",\n        label: \"OpenAI\",\n        description: \"OPENAI_API_KEY\",\n        icon: \"openai\",\n      },\n      {\n        id: \"anthropic\",\n        label: \"Anthropic\",\n        description: \"ANTHROPIC_API_KEY\",\n        icon: \"anthropic\",\n      },\n      {\n        id: \"google\",\n        label: \"Google Gemini\",\n        description: \"GOOGLE_GENERATIVE_AI_API_KEY\",\n        icon: \"google\",\n      },\n      {\n        id: \"openrouter\",\n        label: \"OpenRouter\",\n        description: \"OPENROUTER_API_KEY\",\n        icon: \"openrouter\",\n      },\n      { id: \"xai\", label: \"xAI\", description: \"XAI_API_KEY\", icon: \"xai\" },\n      {\n        id: \"mistral\",\n        label: \"Mistral\",\n        description: \"MISTRAL_API_KEY\",\n        icon: \"mistral\",\n      },\n      {\n        id: \"deepseek\",\n        label: \"DeepSeek\",\n        description: \"DEEPSEEK_API_KEY\",\n        icon: \"deepseek\",\n      },\n      { id: \"groq\", label: \"Groq\", description: \"GROQ_API_KEY\", icon: \"groq\" },\n      {\n        id: \"fireworks\",\n        label: \"Fireworks AI\",\n        description: \"FIREWORKS_API_KEY\",\n        icon: \"fireworks\",\n      },\n    ],\n    default: \"openai\",\n    help: {\n      summary:\n        \"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.\",\n    },\n  },\n  project: {\n    kind: \"choice\",\n    prompt: \"Which project should this go into?\",\n    options: [\n      {\n        id: \"new\",\n        label: \"New project\",\n        description: \"Start a fresh React app here\",\n        variants: [\n          { id: \"next\", label: \"Next.js\" },\n          { id: \"vite\", label: \"Vite\" },\n          { id: \"react-router\", label: \"React Router\" },\n          { id: \"tanstack-start\", label: \"TanStack Start\" },\n          { id: \"expo\", label: \"Expo\" },\n        ],\n      },\n    ],\n    help: {\n      summary:\n        \"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.\",\n      href: `${DOCS}/docs/installation`,\n    },\n  },\n};\n\nexport const isPresetId = (id: string): id is PresetId => id in INPUT_PRESETS;\n\n/** Build the seed for a standard input, throwing on an unknown preset, option or default. */\nexport const presetInput = (\n  id: PresetId,\n  overrides: PresetOverrides = {},\n): Checkout.InputSeed & { stepId?: string } => {\n  const preset = INPUT_PRESETS[id];\n  const listed = overrides.only\n    ? overrides.only.map((optionId) => {\n        const option = preset.options.find((c) => c.id === optionId);\n        if (!option)\n          throw new Error(`preset \"${id}\" has no option \"${optionId}\"`);\n        return option;\n      })\n    : preset.options;\n  const found = (overrides.found ?? []).map((option) => {\n    if (\n      option.id.includes(\":\") ||\n      preset.options.some((o) => o.id === option.id)\n    ) {\n      throw new Error(`preset \"${id}\" cannot list \"${option.id}\" as an option`);\n    }\n    return { ...option, label: option.id };\n  });\n  const options = [...found, ...listed];\n  const fallback = options.some((o) => o.id === preset.default)\n    ? preset.default\n    : undefined;\n  const chosen = overrides.default ?? fallback;\n  if (chosen !== undefined && !options.some((o) => o.id === chosen)) {\n    throw new Error(`preset \"${id}\" has no option \"${chosen}\" to default to`);\n  }\n  return {\n    kind: preset.kind,\n    preset: id,\n    prompt: preset.prompt,\n    options,\n    ...(chosen !== undefined && { default: chosen }),\n    help: preset.help,\n    optional: overrides.optional ?? false,\n    ...(overrides.stepId !== undefined && { stepId: overrides.stepId }),\n  };\n};\n"],"mappings":";AAEA,MAAMC,aAAa;CAAEC,IAAI;CAAcC,OAAO;AAAa;AAC3D,MAAMC,SAAS;CAAEF,IAAI;CAAUC,OAAO;AAAS;AAE/C,MAAME,OAAO;;AAuBb,MAAaiB,gBAA0C;CACrDE,WAAW;EACTT,MAAM;EACNE,QAAQ;EACRC,SAAS;GACP;IACEhB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;IACNC,UAAU,CAACzB,UAAU;GACvB;GACA;IACEC,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;IACNC,UAAU,CAACzB,UAAU;GACvB;GACA;IACEC,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;IACNC,UAAU,CAACtB,QAAQH,UAAU;GAC/B;EAAC;EAEHmB,MAAM;GACJO,SACE;GACFC,MAAM,GAAGvB,KAAI;EACf;CACF;CACA,gBAAgB;EACdU,MAAM;EACNE,QAAQ;EACRC,SAAS;GACP;IACEhB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IAAEvB,IAAI;IAAOC,OAAO;IAAOO,aAAa;IAAee,MAAM;GAAM;GACnE;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;GACA;IAAEvB,IAAI;IAAQC,OAAO;IAAQO,aAAa;IAAgBe,MAAM;GAAO;GACvE;IACEvB,IAAI;IACJC,OAAO;IACPO,aAAa;IACbe,MAAM;GACR;EAAC;EAEHd,SAAS;EACTS,MAAM,EACJO,SACE,6IACJ;CACF;CACAE,SAAS;EACPd,MAAM;EACNE,QAAQ;EACRC,SAAS,CACP;GACEhB,IAAI;GACJC,OAAO;GACPO,aAAa;GACbgB,UAAU;IACR;KAAExB,IAAI;KAAQC,OAAO;IAAU;IAC/B;KAAED,IAAI;KAAQC,OAAO;IAAO;IAC5B;KAAED,IAAI;KAAgBC,OAAO;IAAe;IAC5C;KAAED,IAAI;KAAkBC,OAAO;IAAiB;IAChD;KAAED,IAAI;KAAQC,OAAO;IAAO;GAAC;EAEjC,CAAC;EAEHiB,MAAM;GACJO,SACE;GACFC,MAAM,GAAGvB,KAAI;EACf;CACF;AACF;AAEA,MAAayB,cAAc5B,OAA+BA,MAAMoB;;AAGhE,MAAaS,eACX7B,IACA8B,YAA6B,CAAC,MACe;CAC7C,MAAME,SAASZ,cAAcpB;CAC7B,MAAMiC,SAASH,UAAUxB,OACrBwB,UAAUxB,KAAK4B,KAAKC,aAAa;EAC/B,MAAMC,SAASJ,OAAOhB,QAAQqB,MAAMC,MAAMA,EAAEtC,OAAOmC,QAAQ;EAC3D,IAAI,CAACC,QACH,MAAM,IAAIG,MAAM,WAAWvC,GAAE,mBAAoBmC,SAAQ,EAAG;EAC9D,OAAOC;CACT,CAAC,IACDJ,OAAOhB;CAUX,MAAMA,UAAU,CAAC,IATFc,UAAUvB,SAAS,CAAA,EAAA,CAAI2B,KAAKE,WAAW;EACpD,IACEA,OAAOpC,GAAGwC,SAAS,GAAG,KACtBR,OAAOhB,QAAQyB,MAAMC,MAAMA,EAAE1C,OAAOoC,OAAOpC,EAAE,GAE7C,MAAM,IAAIuC,MAAM,WAAWvC,GAAE,iBAAkBoC,OAAOpC,GAAE,eAAgB;EAE1E,OAAO;GAAE,GAAGoC;GAAQnC,OAAOmC,OAAOpC;EAAG;CACvC,CACoBO,GAAO,GAAG0B,MAAM;CACpC,MAAMU,WAAW3B,QAAQyB,MAAMC,MAAMA,EAAE1C,OAAOgC,OAAOvB,OAAO,IACxDuB,OAAOvB,UACPmC,KAAAA;CACJ,MAAMC,SAASf,UAAUrB,WAAWkC;CACpC,IAAIE,WAAWD,KAAAA,KAAa,CAAC5B,QAAQyB,MAAMC,MAAMA,EAAE1C,OAAO6C,MAAM,GAC9D,MAAM,IAAIN,MAAM,WAAWvC,GAAE,mBAAoB6C,OAAM,gBAAiB;CAE1E,OAAO;EACLhC,MAAMmB,OAAOnB;EACbmB,QAAQhC;EACRe,QAAQiB,OAAOjB;EACfC;EACA,GAAI6B,WAAWD,KAAAA,KAAa,EAAEnC,SAASoC,OAAO;EAC9C3B,MAAMc,OAAOd;EACbR,UAAUoB,UAAUpB,YAAY;EAChC,GAAIoB,UAAUnB,WAAWiC,KAAAA,KAAa,EAAEjC,QAAQmB,UAAUnB,OAAO;CACnE;AACF"}

package/dist/protocol.d.ts

@@ -0,0 +1,289 @@
+//#region src/protocol.d.ts
+declare namespace Checkout {
+  type StepStatus = "pending" | "active" | "done" | "skipped" | "blocked";
+  /** A unit of install work the agent declared; the catalog seeds none. */
+  type Step = {
+    id: string;
+    title: string;
+    detail?: string;
+    status: StepStatus;
+    note?: string;
+    /** The product this step belongs to, when the agent said. */
+    product?: string;
+    createdAt: number;
+  };
+  type Product = {
+    slug: string;
+    name: string;
+    /** The install reference the agent fetches while planning. */
+    guide?: string;
+  };
+  type InputStatus = "open" | "answered" | "dismissed";
+  /**
+   * product: the agent proposes adding a product to this checkout, such as one
+   * another product depends on. The browser owns the catalog, so it answers
+   * with `checkout/add-product`; dismissing the input declines.
+   */
+  type InputKind = "text" | "choice" | "model" | "product";
+  type ChoiceVariant = {
+    id: string;
+    label: string;
+  };
+  type ChoiceOption = {
+    id: string;
+    label: string;
+    description?: string;
+    /** A name from OPTION_ICONS, or the key of a brand mark on a preset option; unknown keys render without one. */
+    icon?: string;
+    /** A second pick under this option, such as the language of a framework. */
+    variants?: ChoiceVariant[];
+  };
+  /** A short nudge for users who need help choosing, with a longer guide to link to. */
+  type InputHelp = {
+    summary: string;
+    href?: string;
+  };
+  /**
+   * The answer to a model input, stored as JSON text. The API key itself is
+   * never part of it: the browser deposits it with the checkout and the
+   * agent's `env` command writes it straight to a file.
+   */
+  type ModelAnswer = {
+    provider: string;
+    model: string;
+    reasoningEffort?: "low" | "medium" | "high";
+  };
+  /**
+   * A choice answer is an option id, `<option>:<variant>` when the option has
+   * variants, or the user's own text when none of the options fit; a multiple
+   * choice answers a JSON array of those. A model answer is a JSON-encoded
+   * ModelAnswer whose provider is one of the options.
+   */
+  type Input = {
+    phase: Status;
+    id: string;
+    kind: InputKind;
+    /** The standard input this was built from, when it was. */
+    preset?: string;
+    prompt: string;
+    placeholder?: string;
+    options?: ChoiceOption[];
+    /** The user may pick any number of options; the answer is a JSON array. */
+    multiple?: true;
+    /** The slug a product input proposes. */
+    product?: string;
+    default?: string;
+    help?: InputHelp;
+    optional: boolean;
+    status: InputStatus;
+    answer?: string;
+    /** A remark the user attached to the answer. */
+    note?: string;
+    stepId?: string;
+    createdAt: number;
+    answeredAt?: number;
+  };
+  type LogEntry = {
+    phase: Status;
+    id: string;
+    role: "agent" | "user";
+    acknowledgedAt?: number;
+    at: number;
+    text: string;
+    /** The step that was active when the line was posted; none while planning. */
+    stepId?: string;
+  };
+  type PlanStatus = "proposed" | "approved" | "changes-requested";
+  /** One revision of the agent's plan. Markdown the browser renders. */
+  type Plan = {
+    revision: number;
+    markdown: string;
+    status: PlanStatus;
+    submittedAt: number;
+    decidedAt?: number;
+    /** What the user asked to change, when they did. */
+    feedback?: string;
+  };
+  /**
+   * waiting: no agent has joined. planning: the agent investigates and
+   * proposes a plan. installing: the plan is approved and steps run.
+   */
+  type Status = "waiting" | "planning" | "installing" | "done" | "cancelled";
+  /**
+   * The agent's proposal to close the checkout. Only the user closes it, and
+   * they may keep messaging the agent instead; a later `done` renews it.
+   * `preview` is the loopback URL of a dev server the agent left running for
+   * the user to try before they close.
+   */
+  type Completion = {
+    proposedAt: number;
+    preview?: string;
+  };
+  type State = {
+    version: 2;
+    /** The id the browser gave the current checkout; a create with another id replaces it on the same link. */
+    id: string | null;
+    status: Status;
+    completion?: Completion;
+    createdAt: number | null;
+    products: Product[];
+    instructions: string;
+    agent: {
+      lastSeenAt: number | null;
+      /** False once the agent's stream said goodbye; heartbeats set it again. */
+      connected: boolean;
+      cwd: string | null;
+      /** The coding agent that ran the command, as the CLI detected it from its environment. */
+      kind: string | null;
+      /** When the command was first run against this checkout, before the agent joined the stream. */
+      introducedAt: number | null;
+    };
+    /** Every revision in order; the last one is current. */
+    plans: Plan[];
+    steps: Step[];
+    inputs: Input[];
+    log: LogEntry[];
+  };
+  type ProductSeed = {
+    slug: string;
+    name: string;
+    guide?: string;
+  };
+  type InputSeed = {
+    kind?: InputKind;
+    preset?: string;
+    prompt: string;
+    placeholder?: string;
+    options?: ChoiceOption[];
+    multiple?: true;
+    product?: string;
+    default?: string;
+    help?: InputHelp;
+    optional?: boolean;
+  };
+  type PlanDecision = {
+    decision: "approve";
+  } | {
+    decision: "revise";
+    feedback: string;
+  };
+  type Commands = {
+    "checkout/create": (params: {
+      id: string;
+      products: ProductSeed[];
+      instructions?: string;
+    }) => void;
+    "checkout/begin-plan": () => void;
+    "checkout/answer": (params: {
+      inputId: string;
+      answer: string;
+      note?: string;
+    }) => void;
+    "checkout/add-product": (params: {
+      inputId: string;
+      product: ProductSeed;
+    }) => void;
+    "checkout/message": (params: {
+      text: string;
+    }) => void;
+    "agent/ack": (params: {
+      messageId: string;
+    }) => void;
+    "checkout/dismiss": (params: {
+      inputId: string;
+    }) => void;
+    "checkout/plan": (params: PlanDecision) => void;
+    "checkout/cancel": () => void;
+    "checkout/finish": () => void;
+    "agent/intro": (params: {
+      kind?: string;
+    }) => void;
+    "agent/hello": (params: {
+      cwd?: string;
+      kind?: string;
+    }) => void;
+    "agent/heartbeat": () => void;
+    "agent/bye": () => void;
+    "agent/plan": (params: {
+      markdown: string;
+    }) => {
+      revision: number;
+    };
+    "agent/add-step": (params: {
+      title: string;
+      detail?: string;
+      product?: string;
+      /** Start the step in the same call. */
+      active?: boolean;
+    }) => {
+      stepId: string;
+    };
+    "agent/step": (params: {
+      stepId: string;
+      status: StepStatus;
+      note?: string;
+    }) => void;
+    "agent/ask": (params: InputSeed & {
+      stepId?: string;
+    }) => {
+      inputId: string;
+    };
+    "agent/log": (params: {
+      text: string;
+    }) => void;
+    "agent/done": (params?: {
+      summary?: string;
+      preview?: string;
+    }) => void;
+  };
+  type RejectionReason = "already-created" | "not-created" | "closed" | "planning-not-started" | "plan-required" | "no-plan" | "plan-decided" | "finish-not-proposed" | "feedback-required" | "empty-plan" | "unknown-step" | "unknown-product" | "unknown-input" | "input-closed" | "invalid-input" | "invalid-answer" | "invalid-preview" | "empty-message" | "unknown-message";
+}
+declare const AGENT_PRESENCE_MS = 15000;
+declare const AGENT_HEARTBEAT_MS = 5000;
+declare const initialCheckoutState: () => Checkout.State;
+declare const isAgentPresent: (state: Checkout.State, now?: number) => boolean;
+declare const isClosed: (state: Checkout.State) => boolean;
+/** True while the agent's proposal to close waits for the user. */
+declare const finishProposed: (state: Checkout.State) => boolean;
+/** True when the user messaged the agent after it last proposed to close. */
+declare const followedUpSinceProposal: (state: Checkout.State) => boolean;
+/**
+ * The URL a preview names, or `undefined` unless it is an http(s) URL on this
+ * machine's loopback interface. The browser opens it, so nothing else passes.
+ */
+declare const parsePreviewUrl: (value: string | undefined) => URL | undefined;
+declare const openInputs: (state: Checkout.State) => Checkout.Input[];
+/** The current plan revision, or `undefined` before the agent proposed one. */
+declare const currentPlan: (state: Checkout.State) => Checkout.Plan | undefined;
+/** True while a proposed plan waits for the user's decision. */
+declare const planNeedsReview: (state: Checkout.State) => boolean;
+/** The icons an agent can put on its own options, by name. */
+declare const OPTION_ICONS: readonly ["code", "terminal", "braces", "git-branch", "package", "database", "server", "cloud", "globe", "monitor", "smartphone", "key", "lock", "shield", "brain", "sparkles", "bot", "workflow", "file", "folder", "book", "table", "image", "video", "mic", "speech", "paperclip", "message", "mail", "bell", "calendar", "clock", "user", "users", "settings", "wrench", "plug", "link", "palette", "search", "zap", "check", "question"];
+type OptionIcon = (typeof OPTION_ICONS)[number];
+declare const isOptionIcon: (value: string) => value is OptionIcon;
+declare const parseChoiceAnswer: (answer: string) => {
+  variant?: string;
+  option: string;
+};
+/** The entries of a multiple choice answer, or `undefined` when the text is not a JSON array of strings. */
+declare const parseMultipleAnswer: (answer: string) => string[] | undefined;
+type ChoiceAnswerKind = "option" | "custom" | "invalid";
+/**
+ * "option" when `answer` names one of the input's options (with a variant
+ * when the option has them), "custom" for the user's own text, "invalid"
+ * for an option named without its variant or with an unknown one. A
+ * multiple choice is classified entry by entry: "invalid" when any entry is
+ * or the array is empty, "custom" when any entry is the user's own text.
+ */
+declare const classifyChoiceAnswer: (input: Checkout.Input, answer: string) => ChoiceAnswerKind;
+/** The model answer an input holds, or `undefined` when the text is not one. */
+declare const parseModelAnswer: (answer: string) => Checkout.ModelAnswer | undefined;
+/** Whether `answer` is a model answer naming one of the input's providers. */
+declare const isValidModelAnswer: (input: Checkout.Input, answer: string) => boolean;
+declare const stepProgress: (state: Checkout.State) => {
+  total: number;
+  done: number;
+};
+//#endregion
+export { AGENT_HEARTBEAT_MS, AGENT_PRESENCE_MS, Checkout, OPTION_ICONS, OptionIcon, classifyChoiceAnswer, currentPlan, finishProposed, followedUpSinceProposal, initialCheckoutState, isAgentPresent, isClosed, isOptionIcon, isValidModelAnswer, openInputs, parseChoiceAnswer, parseModelAnswer, parseMultipleAnswer, parsePreviewUrl, planNeedsReview, stepProgress };
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","names":[],"sources":["../src/protocol.ts"],"mappings":";kBAAiB;OACH;;OAQA;IACV;IACA;IACA;IACA,QAAQ;IACR;;IAEA;IACA;;OAGU;IACV;IACA;;IAEA;;OAGU;;;;;;OAOA;OAEA;IAAkB;IAAY;;OAE9B;IACV;IACA;IACA;;IAEA;;IAEA,WAAW;;;OAID;IAAc;IAAiB;;;;;;;OAO/B;IACV;IACA;IACA;;;;;;;;OASU;IACV,OAAO;IACP;IACA,MAAM;;IAEN;IACA;IACA;IACA,UAAU;;IAEV;;IAEA;IACA;IACA,OAAO;IACP;IACA,QAAQ;IACR;;IAEA;IACA;IACA;IACA;;OAGU;IACV,OAAO;IACP;IACA;IACA;IACA;IACA;;IAEA;;OAGU;;OAGA;IACV;IACA;IACA,QAAQ;IACR;IACA;;IAEA;;;;;;OAOU;;;;;;;OAaA;IAAe;IAAoB;;OAEnC;IACV;;IAEA;IACA,QAAQ;IACR,aAAa;IACb;IACA,UAAU;IACV;IACA;MACE;;MAEA;MACA;;MAEA;;MAEA;;;IAGF,OAAO;IACP,OAAO;IACP,QAAQ;IACR,KAAK;;OAGK;IAAgB;IAAc;IAAc;;OAE5C;IACV,OAAO;IACP;IACA;IACA;IACA,UAAU;IACV;IACA;IACA;IACA,OAAO;IACP;;OAGU;IACN;;IACA;IAAoB;;OAEd;IACV,oBAAoB;MAClB;MACA,UAAU;MACV;;IAEF;IACA,oBAAoB;MAClB;MACA;MACA;;IAEF,yBAAyB;MACvB;MACA,SAAS;;IAEX,qBAAqB;MAAU;;IAC/B,cAAc;MAAU;;IACxB,qBAAqB;MAAU;;IAC/B,kBAAkB,QAAQ;IAC1B;IACA;IACA,gBAAgB;MAAU;;IAC1B,gBAAgB;MAAU;MAAc;;IACxC;IACA;IACA,eAAe;MAAU;;MAAyB;;IAClD,mBAAmB;MACjB;MACA;MACA;;MAEA;;MACM;;IACR,eAAe;MACb;MACA,QAAQ;MACR;;IAEF,cAAc,QAAQ;MAAc;;MAClC;;IAEF,cAAc;MAAU;;IACxB,eAAe;MAAW;MAAkB;;;OAGlC;;cAsBD;cACA;cAEA,4BAA2B,SAAS;cAoBpC,iBAAkB,OAAO,SAAS,OAAO;cAKzC,WAAY,OAAO,SAAS;;cAI5B,iBAAkB,OAAO,SAAS;;cAIlC,0BAA2B,OAAO,SAAS;;;;;cAc3C,kBAAmB,8BAAyB;cAe5C,aAAc,OAAO,SAAS,UAAK,SAAA;;cAInC,cAAe,OAAO,SAAS,UAAQ,SAAS;;cAIhD,kBAAmB,OAAO,SAAS;;cAInC;KA8CD,qBAAqB;cAEpB,eAAgB,kBAAgB,SAAS;cAGzC,oBAAqB;;;;;cAMrB,sBAAuB;KAa/B;;;;;;;;cAwBQ,uBACX,OAAO,SAAS,OAChB,mBACC;;cAiBU,mBACX,mBACC,SAAS;;cAuBC,qBAAsB,OAAO,SAAS,OAAO;cAQ7C,eAAgB,OAAO,SAAS"}

package/dist/protocol.js

@@ -0,0 +1,184 @@
+//#region src/protocol.ts
+const AGENT_PRESENCE_MS = 15e3;
+const AGENT_HEARTBEAT_MS = 5e3;
+const initialCheckoutState = () => ({
+	version: 2,
+	id: null,
+	status: "waiting",
+	createdAt: null,
+	products: [],
+	instructions: "",
+	agent: {
+		lastSeenAt: null,
+		connected: false,
+		cwd: null,
+		kind: null,
+		introducedAt: null
+	},
+	plans: [],
+	steps: [],
+	inputs: [],
+	log: []
+});
+const isAgentPresent = (state, now = Date.now()) => state.agent.connected && state.agent.lastSeenAt !== null && now - state.agent.lastSeenAt < 15e3;
+const isClosed = (state) => state.status === "done" || state.status === "cancelled";
+/** True while the agent's proposal to close waits for the user. */
+const finishProposed = (state) => !isClosed(state) && state.completion !== void 0;
+/** True when the user messaged the agent after it last proposed to close. */
+const followedUpSinceProposal = (state) => {
+	const proposedAt = state.completion?.proposedAt;
+	return proposedAt !== void 0 && state.log.some((entry) => entry.role === "user" && entry.at > proposedAt);
+};
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/**
+* The URL a preview names, or `undefined` unless it is an http(s) URL on this
+* machine's loopback interface. The browser opens it, so nothing else passes.
+*/
+const parsePreviewUrl = (value) => {
+	if (!value) return void 0;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+	if (url.username !== "" || url.password !== "") return void 0;
+	return LOOPBACK_HOSTS.has(url.hostname) || url.hostname.endsWith(".localhost") ? url : void 0;
+};
+const openInputs = (state) => state.inputs.filter((input) => input.status === "open");
+/** The current plan revision, or `undefined` before the agent proposed one. */
+const currentPlan = (state) => state.plans.at(-1);
+/** True while a proposed plan waits for the user's decision. */
+const planNeedsReview = (state) => !isClosed(state) && currentPlan(state)?.status === "proposed";
+/** The icons an agent can put on its own options, by name. */
+const OPTION_ICONS = [
+	"code",
+	"terminal",
+	"braces",
+	"git-branch",
+	"package",
+	"database",
+	"server",
+	"cloud",
+	"globe",
+	"monitor",
+	"smartphone",
+	"key",
+	"lock",
+	"shield",
+	"brain",
+	"sparkles",
+	"bot",
+	"workflow",
+	"file",
+	"folder",
+	"book",
+	"table",
+	"image",
+	"video",
+	"mic",
+	"speech",
+	"paperclip",
+	"message",
+	"mail",
+	"bell",
+	"calendar",
+	"clock",
+	"user",
+	"users",
+	"settings",
+	"wrench",
+	"plug",
+	"link",
+	"palette",
+	"search",
+	"zap",
+	"check",
+	"question"
+];
+const isOptionIcon = (value) => OPTION_ICONS.includes(value);
+const parseChoiceAnswer = (answer) => {
+	const [option = "", variant] = answer.split(":", 2);
+	return {
+		option,
+		...variant !== void 0 && { variant }
+	};
+};
+/** The entries of a multiple choice answer, or `undefined` when the text is not a JSON array of strings. */
+const parseMultipleAnswer = (answer) => {
+	let value;
+	try {
+		value = JSON.parse(answer);
+	} catch {
+		return;
+	}
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : void 0;
+};
+const classifyChoiceEntry = (input, answer) => {
+	const { option, variant } = parseChoiceAnswer(answer);
+	const match = input.options?.find((candidate) => candidate.id === option);
+	if (!match) return answer.trim() === "" ? "invalid" : "custom";
+	if (!match.variants || match.variants.length === 0) return variant === void 0 ? "option" : "invalid";
+	return match.variants.some((candidate) => candidate.id === variant) ? "option" : "invalid";
+};
+/**
+* "option" when `answer` names one of the input's options (with a variant
+* when the option has them), "custom" for the user's own text, "invalid"
+* for an option named without its variant or with an unknown one. A
+* multiple choice is classified entry by entry: "invalid" when any entry is
+* or the array is empty, "custom" when any entry is the user's own text.
+*/
+const classifyChoiceAnswer = (input, answer) => {
+	if (!input.multiple) return classifyChoiceEntry(input, answer);
+	const entries = parseMultipleAnswer(answer);
+	if (!entries || entries.length === 0) return "invalid";
+	const kinds = entries.map((entry) => classifyChoiceEntry(input, entry));
+	if (kinds.includes("invalid")) return "invalid";
+	return kinds.includes("custom") ? "custom" : "option";
+};
+const REASONING_EFFORTS = /* @__PURE__ */ new Set([
+	"low",
+	"medium",
+	"high"
+]);
+const isReasoningEffort = (value) => typeof value === "string" && REASONING_EFFORTS.has(value);
+/** The model answer an input holds, or `undefined` when the text is not one. */
+const parseModelAnswer = (answer) => {
+	let value;
+	try {
+		value = JSON.parse(answer);
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null) return void 0;
+	const { provider, model, reasoningEffort } = value;
+	if (typeof provider !== "string" || typeof model !== "string" || provider === "" || model === "") return;
+	if (reasoningEffort === void 0) return {
+		provider,
+		model
+	};
+	if (!isReasoningEffort(reasoningEffort)) return void 0;
+	return {
+		provider,
+		model,
+		reasoningEffort
+	};
+};
+/** Whether `answer` is a model answer naming one of the input's providers. */
+const isValidModelAnswer = (input, answer) => {
+	const parsed = parseModelAnswer(answer);
+	return parsed !== void 0 && (input.options?.some((option) => option.id === parsed.provider) ?? false);
+};
+const stepProgress = (state) => ({
+	total: state.steps.length,
+	done: state.steps.filter((step) => step.status === "done" || step.status === "skipped").length
+});
+//#endregion
+export { AGENT_HEARTBEAT_MS, AGENT_PRESENCE_MS, OPTION_ICONS, classifyChoiceAnswer, currentPlan, finishProposed, followedUpSinceProposal, initialCheckoutState, isAgentPresent, isClosed, isOptionIcon, isValidModelAnswer, openInputs, parseChoiceAnswer, parseModelAnswer, parseMultipleAnswer, parsePreviewUrl, planNeedsReview, stepProgress };
+
+//# sourceMappingURL=protocol.js.map