setup-agent 0.0.3 → 0.0.5

package/src/host.ts

@@ -12,6 +12,9 @@ import {
   isAgentPresent,
   isClosed,
   isValidModelAnswer,
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
+  parseEntryPointOptions,
   parsePreviewUrl,
 } from "./protocol";
 import type { Checkout } from "./protocol";
@@ -83,6 +86,16 @@ const useCheckoutHost = (restored: unknown) => {
 
   const ask = (seed: Checkout.InputSeed & { stepId?: string }) => {
     const kind = seed.kind ?? "text";
+    const options =
+      kind === "entry-point"
+        ? parseEntryPointOptions(seed.options)
+        : seed.options;
+    if (kind === "entry-point" && !isValidEntryPointInput(seed)) {
+      throw reject(
+        "invalid-input",
+        "an entry-point input needs a prompt and 1–3 distinct options with descriptions, form factors, placements and triggers; at most one is recommended",
+      );
+    }
     if (kind === "product") {
       if (!seed.product) {
         throw reject("invalid-input", "a product input names a product");
@@ -98,13 +111,36 @@ const useCheckoutHost = (restored: unknown) => {
     }
     if (
       seed.multiple &&
-      (kind !== "choice" || seed.options?.some((option) => option.variants))
+      (kind !== "choice" ||
+        seed.options?.some((option) => option.variants?.length))
     ) {
       throw reject(
         "invalid-input",
         "only a choice whose options have no variants accepts several answers",
       );
     }
+    const unique = (ids: readonly string[]) => new Set(ids).size === ids.length;
+    if (
+      !unique(seed.options?.map((option) => option.id) ?? []) ||
+      seed.options?.some(
+        (option) =>
+          !unique(option.variants?.map((variant) => variant.id) ?? []),
+      )
+    ) {
+      throw reject("invalid-input", "option and variant ids must be unique");
+    }
+    if (
+      seed.options?.some(
+        (option) =>
+          option.id.includes(":") ||
+          option.variants?.some((variant) => variant.id.includes(":")),
+      )
+    ) {
+      throw reject(
+        "invalid-input",
+        'option and variant ids cannot contain ":", which separates them in an answer',
+      );
+    }
     if (
       seed.default !== undefined &&
       !seed.options?.some((option) => option.id === seed.default)
@@ -125,7 +161,7 @@ const useCheckoutHost = (restored: unknown) => {
       ...(seed.preset !== undefined && { preset: seed.preset }),
       prompt: seed.prompt,
       ...(seed.placeholder !== undefined && { placeholder: seed.placeholder }),
-      ...(seed.options !== undefined && { options: seed.options }),
+      ...(options !== undefined && { options }),
       ...(seed.multiple && { multiple: true }),
       ...(kind === "product" && { product: seed.product }),
       ...(seed.default !== undefined && { default: seed.default }),
@@ -214,6 +250,12 @@ const useCheckoutHost = (restored: unknown) => {
             : `"${answer}" names an option without a valid variant`,
         );
       }
+      if (
+        input.kind === "entry-point" &&
+        !isValidEntryPointAnswer(input, answer)
+      ) {
+        throw reject("invalid-answer", "an entry-point answer is an option id");
+      }
       if (input.kind === "model" && !isValidModelAnswer(input, answer)) {
         throw reject(
           "invalid-answer",
@@ -305,8 +347,9 @@ const useCheckoutHost = (restored: unknown) => {
       plan.decidedAt = Date.now();
       plan.feedback = params.feedback.trim();
     },
-    "checkout/cancel": () => {
-      if (state.status === "cancelled") return;
+    "checkout/cancel": ({ id } = {}) => {
+      if (state.createdAt === null || isClosed(state)) return;
+      if (id !== undefined && id !== state.id) return;
       state.status = "cancelled";
       dismissOpenInputs();
     },
@@ -360,11 +403,11 @@ const useCheckoutHost = (restored: unknown) => {
     },
     "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}"`);
+      if (product !== undefined && product.trim() === "") {
+        throw reject(
+          "invalid-input",
+          "a step's product identifier cannot be empty",
+        );
       }
       const id = `s${state.steps.length + 1}`;
       state.steps.push({

package/src/index.ts

@@ -12,8 +12,11 @@ export {
   isClosed,
   isOptionIcon,
   isValidModelAnswer,
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
   openInputs,
   parseChoiceAnswer,
+  parseEntryPointOptions,
   parseModelAnswer,
   parseMultipleAnswer,
   parsePreviewUrl,

package/src/presets.ts

@@ -10,7 +10,7 @@ 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. */
+  /** Options the agent found itself, listed before the preset's own; `only` leaves them out. */
   found?: readonly { id: string; description?: string }[];
   default?: string;
   optional?: boolean;
@@ -139,7 +139,8 @@ export const INPUT_PRESETS: Record<PresetId, Preset> = {
   },
 };
 
-export const isPresetId = (id: string): id is PresetId => id in INPUT_PRESETS;
+export const isPresetId = (id: string): id is PresetId =>
+  Object.hasOwn(INPUT_PRESETS, id);
 
 /** Build the seed for a standard input, throwing on an unknown preset, option or default. */
 export const presetInput = (
@@ -164,7 +165,7 @@ export const presetInput = (
     }
     return { ...option, label: option.id };
   });
-  const options = [...found, ...listed];
+  const options = overrides.only ? listed : [...found, ...listed];
   const fallback = options.some((o) => o.id === preset.default)
     ? preset.default
     : undefined;

package/src/protocol.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import {
+  isValidEntryPointAnswer,
+  isValidEntryPointInput,
+  parseEntryPointOptions,
+  type Checkout,
+} from "./protocol";
+
+const option: Checkout.EntryPointOption = {
+  id: "ticket-sidebar",
+  label: "Ticket sidebar",
+  description: "Draft replies beside the selected support ticket.",
+  entryPoint: {
+    formFactor: "sidebar",
+    placement: "The right side of the ticket detail page",
+    trigger: "Open with the Draft reply button in the ticket toolbar",
+    recommended: true,
+  },
+};
+
+const input: Checkout.Input = {
+  id: "q1",
+  kind: "entry-point",
+  phase: "planning",
+  prompt: "Where should agents draft replies?",
+  options: [option],
+  default: option.id,
+  optional: false,
+  status: "open",
+  createdAt: 1,
+};
+
+describe("entry-point options", () => {
+  it("keeps contextual metadata and permits different placements of the same form factor", () => {
+    const second = {
+      ...option,
+      id: "inbox-sidebar",
+      entryPoint: {
+        ...option.entryPoint,
+        placement: "The inbox list",
+        trigger: "Open with the inbox Assist button",
+        recommended: false,
+      },
+    };
+    expect(parseEntryPointOptions([option, second])).toEqual([option, second]);
+    expect(isValidEntryPointInput(input)).toBe(true);
+    expect(isValidEntryPointAnswer(input, "ticket-sidebar")).toBe(true);
+    expect(isValidEntryPointAnswer(input, "sidebar")).toBe(false);
+    expect(isValidEntryPointAnswer(input, "ticket-sidebar:variant")).toBe(
+      false,
+    );
+    expect(isValidEntryPointAnswer(input, '["ticket-sidebar"]')).toBe(false);
+  });
+
+  it.each(
+    [
+      null,
+      {},
+      [],
+      [null],
+      [option, option],
+      [option, { ...option, id: "another" }],
+      [
+        option,
+        { ...option, id: "b" },
+        { ...option, id: "c" },
+        { ...option, id: "d" },
+      ],
+      [{ ...option, id: "with:variant" }],
+      [{ ...option, id: "x".repeat(65) }],
+      [{ ...option, label: " " }],
+      [{ ...option, description: "" }],
+      [{ ...option, description: "x".repeat(1001) }],
+      [{ ...option, entryPoint: null }],
+      [
+        {
+          ...option,
+          entryPoint: { ...option.entryPoint, formFactor: "drawer" },
+        },
+      ],
+      [{ ...option, entryPoint: { ...option.entryPoint, placement: "" } }],
+      [{ ...option, entryPoint: { ...option.entryPoint, trigger: " " } }],
+      [{ ...option, entryPoint: { ...option.entryPoint, recommended: "yes" } }],
+      [{ ...option, variants: [] }],
+    ].map((value) => ({ value })),
+  )("rejects malformed or ambiguous choices %#", ({ value }) => {
+    expect(parseEntryPointOptions(value)).toBeUndefined();
+  });
+
+  it("types an option with only the fields the parser keeps", () => {
+    const withIcon: Checkout.EntryPointOption = {
+      ...option,
+      // @ts-expect-error an entry-point option carries no icon
+      icon: "sidebar",
+    };
+    const withVariants: Checkout.EntryPointOption = {
+      ...option,
+      // @ts-expect-error an entry-point option carries no variants
+      variants: [],
+    };
+    expect(parseEntryPointOptions([withIcon])).toEqual([option]);
+    expect(parseEntryPointOptions([withVariants])).toBeUndefined();
+  });
+
+  it("strips undeclared payload fields", () => {
+    expect(
+      parseEntryPointOptions([{ ...option, icon: "untrusted", extra: 1 }]),
+    ).toEqual([option]);
+  });
+
+  it("requires an exact default and a single selection", () => {
+    expect(isValidEntryPointInput({ ...input, multiple: true })).toBe(false);
+    expect(isValidEntryPointInput({ ...input, default: "unknown" })).toBe(
+      false,
+    );
+    expect(isValidEntryPointInput({ ...input, prompt: " " })).toBe(false);
+    expect(isValidEntryPointInput({ ...input, kind: "choice" })).toBe(false);
+  });
+
+  it("refuses a help note, which the entry-point card has no place for", () => {
+    expect(
+      isValidEntryPointInput({
+        ...input,
+        help: { summary: "Pick one" },
+      }),
+    ).toBe(false);
+  });
+});

package/src/protocol.ts

@@ -32,7 +32,26 @@ export namespace Checkout {
    * another product depends on. The browser owns the catalog, so it answers
    * with `checkout/add-product`; dismissing the input declines.
    */
-  export type InputKind = "text" | "choice" | "model" | "product";
+  export type InputKind =
+    | "text"
+    | "choice"
+    | "model"
+    | "product"
+    | "entry-point";
+
+  export type EntryPoint = {
+    formFactor: "modal" | "sidebar" | "full-page";
+    placement: string;
+    trigger: string;
+    recommended?: boolean;
+  };
+
+  export type EntryPointOption = {
+    id: string;
+    label: string;
+    description: string;
+    entryPoint: EntryPoint;
+  };
 
   export type ChoiceVariant = { id: string; label: string };
 
@@ -44,6 +63,7 @@ export namespace Checkout {
     icon?: string;
     /** A second pick under this option, such as the language of a framework. */
     variants?: ChoiceVariant[];
+    entryPoint?: EntryPoint;
   };
 
   /** A short nudge for users who need help choosing, with a longer guide to link to. */
@@ -199,7 +219,8 @@ export namespace Checkout {
     "agent/ack": (params: { messageId: string }) => void;
     "checkout/dismiss": (params: { inputId: string }) => void;
     "checkout/plan": (params: PlanDecision) => void;
-    "checkout/cancel": () => void;
+    /** A cancel that names another checkout than the current one is a no-op. */
+    "checkout/cancel": (params?: { id?: string }) => void;
     "checkout/finish": () => void;
     "agent/intro": (params: { kind?: string }) => void;
     "agent/hello": (params: { cwd?: string; kind?: string }) => void;
@@ -282,12 +303,17 @@ export const isClosed = (state: Checkout.State) =>
 export const finishProposed = (state: Checkout.State) =>
   !isClosed(state) && state.completion !== undefined;
 
-/** True when the user messaged the agent after it last proposed to close. */
+/** True while a message the user sent after the agent proposed to close still waits for the agent. */
 export const followedUpSinceProposal = (state: Checkout.State) => {
   const proposedAt = state.completion?.proposedAt;
   return (
     proposedAt !== undefined &&
-    state.log.some((entry) => entry.role === "user" && entry.at > proposedAt)
+    state.log.some(
+      (entry) =>
+        entry.role === "user" &&
+        entry.at > proposedAt &&
+        entry.acknowledgedAt === undefined,
+    )
   );
 };
 
@@ -376,7 +402,9 @@ export const isOptionIcon = (value: string): value is OptionIcon =>
   (OPTION_ICONS as readonly string[]).includes(value);
 
 export const parseChoiceAnswer = (answer: string) => {
-  const [option = "", variant] = answer.split(":", 2);
+  const parts = answer.split(":");
+  if (parts.length > 2) return { option: answer };
+  const [option = "", variant] = parts;
   return { option, ...(variant !== undefined && { variant }) };
 };
 
@@ -430,6 +458,76 @@ export const classifyChoiceAnswer = (
   return kinds.includes("custom") ? "custom" : "option";
 };
 
+const isEntryPointText = (value: unknown, max: number): value is string =>
+  typeof value === "string" && value.trim() !== "" && value.length <= max;
+
+export const parseEntryPointOptions = (
+  value: unknown,
+): Checkout.EntryPointOption[] | undefined => {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 3)
+    return undefined;
+  const options: Checkout.EntryPointOption[] = [];
+  for (const candidate of value) {
+    if (typeof candidate !== "object" || candidate === null) return undefined;
+    const { id, label, description, entryPoint, variants } =
+      candidate as Record<string, unknown>;
+    if (
+      typeof id !== "string" ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(id) ||
+      options.some((option) => option.id === id) ||
+      !isEntryPointText(label, 160) ||
+      !isEntryPointText(description, 1000) ||
+      variants !== undefined ||
+      typeof entryPoint !== "object" ||
+      entryPoint === null
+    )
+      return undefined;
+    const { formFactor, placement, trigger, recommended } =
+      entryPoint as Record<string, unknown>;
+    if (
+      (formFactor !== "modal" &&
+        formFactor !== "sidebar" &&
+        formFactor !== "full-page") ||
+      !isEntryPointText(placement, 400) ||
+      !isEntryPointText(trigger, 400) ||
+      (recommended !== undefined && typeof recommended !== "boolean")
+    )
+      return undefined;
+    options.push({
+      id,
+      label,
+      description,
+      entryPoint: {
+        formFactor,
+        placement,
+        trigger,
+        ...(recommended !== undefined && { recommended }),
+      },
+    });
+  }
+  return options.filter((option) => option.entryPoint.recommended).length <= 1
+    ? options
+    : undefined;
+};
+
+export const isValidEntryPointInput = (input: Checkout.InputSeed) => {
+  const options = parseEntryPointOptions(input.options);
+  return (
+    input.kind === "entry-point" &&
+    isEntryPointText(input.prompt, 1000) &&
+    options !== undefined &&
+    input.multiple === undefined &&
+    input.help === undefined &&
+    (input.default === undefined ||
+      options.some((option) => option.id === input.default))
+  );
+};
+
+export const isValidEntryPointAnswer = (
+  input: Checkout.Input,
+  answer: string,
+) => input.options?.some((option) => option.id === answer) ?? false;
+
 const REASONING_EFFORTS = new Set(["low", "medium", "high"]);
 
 const isReasoningEffort = (