paseo-prompt-kit 0.5.2

package/client/settings/custom-actions.ts

@@ -0,0 +1,79 @@
+import { actionPackSchema, type ActionPack } from "../../shared/action-registry/schema.js";
+import type { ActionSummary } from "../../shared/rpc.js";
+import type { PromptKitSettings } from "../../shared/settings.js";
+import { MAX_ENABLED_ACTIONS, enabledActions } from "../actions/enabled.js";
+
+export type ParsedAction = { ok: true; pack: ActionPack } | { ok: false; error: string };
+
+/** JSON as the editor shows it. */
+export function formatPack(pack: ActionPack): string {
+  return JSON.stringify(pack, null, 2);
+}
+
+/** `base`, or `base-2`, `base-3`… so a sample never collides with a loaded action. */
+export function freeActionId(base: string, taken: ReadonlySet<string>): string {
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n += 1) {
+    const id = `${base}-${n}`;
+    if (!taken.has(id)) return id;
+  }
+}
+
+/**
+ * Editor text → a pack that can be stored, or the reason it cannot. `takenIds`
+ * holds every loaded action id except the one being edited.
+ */
+export function parseCustomAction(text: string, takenIds: ReadonlySet<string>): ParsedAction {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    return { ok: false, error: `Not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const parsed = actionPackSchema.safeParse(json);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const path = issue?.path.join(".") ?? "";
+    return { ok: false, error: `${path === "" ? "The pack" : `"${path}"`}: ${issue?.message ?? "invalid"}` };
+  }
+  if (takenIds.has(parsed.data.id)) {
+    return { ok: false, error: `Another action already uses the id "${parsed.data.id}".` };
+  }
+  return { ok: true, pack: parsed.data };
+}
+
+/**
+ * The settings change that stores `pack` in place of `replacingId` (null adds it).
+ * A renamed action keeps its switch; a new one starts off when the enabled set is full.
+ */
+export function storeCustomAction(
+  current: PromptKitSettings,
+  actions: readonly ActionSummary[],
+  pack: ActionPack,
+  replacingId: string | null,
+): Partial<PromptKitSettings> {
+  const customActions =
+    replacingId === null
+      ? [...current.customActions, pack]
+      : current.customActions.map((existing) => (existing.id === replacingId ? pack : existing));
+
+  const actionEnabled = { ...current.actionEnabled };
+  if (replacingId !== null && replacingId !== pack.id && replacingId in actionEnabled) {
+    actionEnabled[pack.id] = actionEnabled[replacingId]!;
+    delete actionEnabled[replacingId];
+  }
+  if (replacingId === null) {
+    const full = enabledActions(actions, current).length >= MAX_ENABLED_ACTIONS;
+    if (full && pack.enabledByDefault) actionEnabled[pack.id] = false;
+  }
+  return { customActions, actionEnabled };
+}
+
+/** The settings change that deletes a custom action and its switch. */
+export function removeCustomAction(current: PromptKitSettings, id: string): Partial<PromptKitSettings> {
+  const { [id]: _removed, ...actionEnabled } = current.actionEnabled;
+  return {
+    customActions: current.customActions.filter((pack) => pack.id !== id),
+    actionEnabled,
+  };
+}

package/client/settings/draft.ts

@@ -0,0 +1,82 @@
+import { useCallback, useMemo, useState } from "react";
+import type { SettingsState } from "@getpaseo/plugin/client";
+import type { promptKitSettings, PromptKitSettings } from "../../shared/settings.js";
+import { announceSettingsSaved } from "./settings-saved.js";
+import { findSaveProblem } from "./validation.js";
+
+type ReadySettings = Extract<SettingsState<typeof promptKitSettings.schema>, { status: "ready" }>;
+
+export type SettingsPatch =
+  | Partial<PromptKitSettings>
+  | ((current: PromptKitSettings) => Partial<PromptKitSettings>);
+
+export interface SettingsDraft {
+  /** What the screen shows: the draft when one exists, else the host document. */
+  readonly values: PromptKitSettings;
+  readonly dirty: boolean;
+  readonly saving: boolean;
+  /** The host's last save failure, cleared by the next edit or save. */
+  readonly saveError: string | null;
+  /** Why the draft cannot be saved as it stands; null when Save is allowed. */
+  readonly problem: string | null;
+  /** True right after a successful save, until the next edit. */
+  readonly justSaved: boolean;
+  /** Bumps on discard/save; uncontrolled inputs key on it. */
+  readonly epoch: number;
+  patch(update: SettingsPatch): void;
+  discard(): void;
+  save(): Promise<void>;
+}
+
+/** Draft over the host document; functional patches; revision pinned at first edit. */
+export function useSettingsDraft(settings: ReadySettings): SettingsDraft {
+  const [draft, setDraft] = useState<{ values: PromptKitSettings; revision: string } | null>(null);
+  const [justSaved, setJustSaved] = useState(false);
+  const [epoch, setEpoch] = useState(0);
+
+  const values = draft?.values ?? settings.values;
+  const revision = draft?.revision ?? settings.revision;
+  const problem = useMemo(() => findSaveProblem(values), [values]);
+
+  const patch = useCallback(
+    (update: SettingsPatch) => {
+      setJustSaved(false);
+      setDraft((previous) => {
+        const base = previous ?? { values: settings.values, revision: settings.revision };
+        const changes = typeof update === "function" ? update(base.values) : update;
+        return { ...base, values: { ...base.values, ...changes } };
+      });
+    },
+    [settings.values, settings.revision],
+  );
+
+  const discard = useCallback(() => {
+    setDraft(null);
+    setJustSaved(false);
+    setEpoch((current) => current + 1);
+  }, []);
+
+  const save = useCallback(async () => {
+    if (draft === null || problem !== null) return;
+    const ok = await settings.save(draft.values, revision);
+    if (ok) {
+      announceSettingsSaved();
+      setDraft(null);
+      setJustSaved(true);
+      setEpoch((current) => current + 1);
+    }
+  }, [draft, problem, revision, settings]);
+
+  return {
+    values,
+    dirty: draft !== null,
+    saving: settings.saving,
+    saveError: settings.saveError,
+    problem,
+    justSaved,
+    epoch,
+    patch,
+    discard,
+    save,
+  };
+}

package/client/settings/model-filter.ts

@@ -0,0 +1,33 @@
+export interface ModelOption {
+  readonly label: string;
+  readonly value: string;
+}
+
+/** Lists at or below this length get no filter row. */
+export const MODEL_FILTER_THRESHOLD = 8;
+
+/**
+ * Pure: options whose name or id contains the query, case-insensitive. The option equal to
+ * `keep` (the current selection) stays, so the host dropdown still shows it.
+ */
+export function filterModels(
+  options: readonly ModelOption[],
+  query: string,
+  keep: string | null = null,
+): readonly ModelOption[] {
+  const needle = query.trim().toLowerCase();
+  if (needle === "") return options;
+  return options.filter(
+    (option) =>
+      option.value === keep ||
+      option.label.toLowerCase().includes(needle) ||
+      option.value.toLowerCase().includes(needle),
+  );
+}
+
+/** Hint for the filter row: how many of the models the dropdown now lists. */
+export function describeFilter(total: number, shown: number, query: string): string {
+  return query.trim() === ""
+    ? `Type part of a name or id to shorten the Model list below (${total} models).`
+    : `${shown} of ${total} models match.`;
+}

package/client/settings/read-settings.ts

@@ -0,0 +1,45 @@
+import { settingsRpc } from "@getpaseo/plugin";
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import {
+  promptKitSettings,
+  promptKitSettingsSchema,
+  type PromptKitSettings,
+} from "../../shared/settings.js";
+
+export type SettingsRead =
+  | { status: "ready"; values: PromptKitSettings }
+  | { status: "invalid"; error: string };
+
+type Rpc = PluginClientContext["rpc"];
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Reads the persisted settings through the host settings API. Every failure —
+ * unreadable document or schema mismatch — is reported as `invalid` so callers
+ * refuse instead of falling back to defaults the user never chose.
+ *
+ * Whether a *dedicated* selection is usable depends on the live provider
+ * catalog, so that check belongs to the rewrite path
+ * (`validateDedicatedSelection`), not here. Reporting an incomplete selection as
+ * an unreadable document would also hide the pill, because the pill's enabled
+ * set cannot be computed from a document the reader refuses.
+ */
+export function createSettingsReader(rpc: Rpc): () => Promise<SettingsRead> {
+  const read = settingsRpc(promptKitSettings.id).read;
+  return async () => {
+    try {
+      const result = await rpc(read, {});
+      if (result.status !== "ready") return { status: "invalid", error: result.error };
+      const parsed = promptKitSettingsSchema.safeParse(result.values);
+      if (!parsed.success) {
+        return { status: "invalid", error: "PromptKit settings are invalid." };
+      }
+      return { status: "ready", values: parsed.data };
+    } catch (error) {
+      return { status: "invalid", error: message(error) };
+    }
+  };
+}

package/client/settings/readiness.ts

@@ -0,0 +1,84 @@
+import type { ProviderCatalogOutput } from "../../shared/rpc.js";
+import { resolveLanguage } from "../../shared/language-registry/registry.js";
+import type { PromptKitSettings } from "../../shared/settings.js";
+import { validateDedicatedSelection } from "./selection.js";
+
+type Providers = ProviderCatalogOutput["providers"];
+
+/** Status line: would a rewrite run, over which path, and if not why. Computed from the draft. */
+export type Readiness =
+  | { kind: "ready"; path: string; detail: string }
+  | { kind: "blocked"; path: string; reason: string }
+  | { kind: "checking"; path: string; detail: string };
+
+export interface ReadinessInput {
+  values: PromptKitSettings;
+  /** Null while the catalog has not been read yet. */
+  providers: Providers | null;
+  /** Null while the action list has not been read yet. */
+  enabledActionCount: number | null;
+}
+
+function pathLabel(values: PromptKitSettings): string {
+  const transport = values.transport === "api" ? "Direct API" : "Provider CLI";
+  if (values.transport === "api") {
+    const mapped = Object.keys(values.apiEndpointByProvider).length;
+    const viaMapping = `agent model via ${mapped} mapped provider${mapped === 1 ? "" : "s"}`;
+    if (values.apiEndpointId === null) return `${transport} · ${mapped > 0 ? viaMapping : "no endpoint"}`;
+    const selected = `${transport} · ${values.apiEndpointId} · ${values.apiModel ?? "no model"}`;
+    return mapped > 0 ? `${selected} · ${viaMapping}` : selected;
+  }
+  if (values.modelMode === "dedicated") {
+    const provider = values.dedicatedProvider ?? "no provider";
+    const model = values.dedicatedModel ?? "no model";
+    return `${transport} · ${provider} · ${model}`;
+  }
+  return `${transport} · current agent model`;
+}
+
+export function describeReadiness(input: ReadinessInput): Readiness {
+  const { values, providers, enabledActionCount } = input;
+  const path = pathLabel(values);
+
+  if (enabledActionCount === 0) {
+    return {
+      kind: "blocked",
+      path,
+      reason: "No action is enabled, so the Composer shows no PromptKit pill.",
+    };
+  }
+
+  if (resolveLanguage(values.outputLanguage) === undefined) {
+    return {
+      kind: "blocked",
+      path,
+      reason: `No output language is loaded with the id "${values.outputLanguage}".`,
+    };
+  }
+
+  if (values.transport === "cli" && values.modelMode === "dedicated" && providers === null) {
+    return { kind: "checking", path, detail: "Reading the provider catalog…" };
+  }
+
+  const problem = validateDedicatedSelection(values, providers ?? []);
+  if (problem !== null) return { kind: "blocked", path, reason: problem };
+
+  if (values.transport === "api") {
+    return {
+      kind: "ready",
+      path,
+      detail:
+        values.apiEndpointId !== null
+          ? "One HTTP request to the selected endpoint. No CLI is started."
+          : "Each mapped provider's agent model is sent to its endpoint; other providers are refused.",
+    };
+  }
+  return {
+    kind: "ready",
+    path,
+    detail:
+      values.modelMode === "dedicated"
+        ? "The dedicated provider's CLI runs headlessly in a scratch directory."
+        : "The agent's own provider CLI runs the model the Composer shows.",
+  };
+}

package/client/settings/sections/actions-section.tsx

@@ -0,0 +1,75 @@
+import { SettingsAction, SettingsCard, SettingsRow, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import type { ActionSummary, ActionsListOutput } from "../../../shared/rpc.js";
+import type { PromptKitSettings } from "../../../shared/settings.js";
+import { MAX_ENABLED_ACTIONS, enabledActions } from "../../actions/enabled.js";
+import type { SettingsPatch } from "../draft.js";
+
+export interface ActionsSectionProps {
+  /** Null while the registry has not answered yet. */
+  actions: readonly ActionSummary[] | null;
+  /** Packs the registry refused, e.g. a custom action reusing a bundled id. */
+  rejected: ActionsListOutput["rejected"];
+  error: string | null;
+  values: PromptKitSettings;
+  disabled: boolean;
+  patch(update: SettingsPatch): void;
+  reload(): void;
+}
+
+function hintFor(action: ActionSummary): string {
+  return action.custom ? `Custom · ${action.description}` : action.description;
+}
+
+/** Per-action enable switches, at most `MAX_ENABLED_ACTIONS` on; a lone action has no switch. */
+export function ActionsSection({ actions, rejected, error, values, disabled, patch, reload }: ActionsSectionProps) {
+  const enabledCount = actions === null ? 0 : enabledActions(actions, values).length;
+  return (
+    <SettingsSection
+      title="Actions"
+      info={`One enabled action makes the pill rewrite at once; two or more make it a menu to choose from. Up to ${MAX_ENABLED_ACTIONS} can be on. Add your own under Custom actions.`}
+    >
+      <SettingsCard>
+        {error !== null ? (
+          <SettingsAction
+            label="Could not load actions"
+            error={error}
+            actionLabel="Retry"
+            disabled={disabled}
+            onPress={reload}
+          />
+        ) : actions === null ? (
+          <SettingsRow label="Loading actions…" />
+        ) : actions.length === 0 ? (
+          <SettingsRow
+            label="No action pack is loaded"
+            hint="Add one under Custom actions below."
+          />
+        ) : actions.length === 1 && enabledCount === 1 ? (
+          <SettingsRow label={actions[0]!.title} hint={`Always on · ${hintFor(actions[0]!)}`} />
+        ) : (
+          actions.map((action) => {
+            const on = enabledActions([action], values).length === 1;
+            const full = !on && enabledCount >= MAX_ENABLED_ACTIONS;
+            return (
+              <SettingsSwitch
+                key={action.id}
+                label={action.title}
+                hint={full ? `${MAX_ENABLED_ACTIONS} actions are on; turn one off first.` : hintFor(action)}
+                value={on}
+                disabled={disabled || full}
+                onValueChange={(next) =>
+                  patch((current) => ({
+                    actionEnabled: { ...current.actionEnabled, [action.id]: next },
+                  }))
+                }
+              />
+            );
+          })
+        )}
+        {rejected.map((entry) => (
+          <SettingsRow key={`rejected-${entry.source}-${entry.reason}`} label={`Not loaded: ${entry.source}`} error={entry.reason} />
+        ))}
+      </SettingsCard>
+    </SettingsSection>
+  );
+}

package/client/settings/sections/advanced-section.tsx

@@ -0,0 +1,127 @@
+import { useState } from "react";
+import { SettingsCard, SettingsInput, SettingsRow, SettingsSection } from "@getpaseo/plugin/client/ui";
+import type { PluginTheme } from "@getpaseo/plugin";
+import { CLI_FAMILY_IDS, isCliFamilyId } from "../../../shared/cli-families.js";
+import type { ProviderCatalogOutput } from "../../../shared/rpc.js";
+import { TIMEOUT_MS, type PromptKitSettings } from "../../../shared/settings.js";
+import type { SettingsPatch } from "../draft.js";
+import { Button } from "../ui/button.js";
+import { ProviderMapCard } from "./provider-map-card.js";
+import { describeTimeout } from "../validation.js";
+
+type Providers = ProviderCatalogOutput["providers"];
+
+export interface AdvancedSectionProps {
+  theme: PluginTheme;
+  values: PromptKitSettings;
+  providers: Providers | null;
+  disabled: boolean;
+  epoch: number;
+  patch(update: SettingsPatch): void;
+}
+
+const NONE = "";
+
+/** Timeout, secrets dir, per-provider maps. Collapsed by default. */
+export function AdvancedSection({ theme, values, providers, disabled, epoch, patch }: AdvancedSectionProps) {
+  const [open, setOpen] = useState(false);
+  const timeout = describeTimeout(values.timeoutMs);
+
+  return (
+    <SettingsSection
+      title="Advanced"
+      info="Timeout, where secrets.json lives, and per-provider overrides. Most setups never need these."
+      trailing={
+        <Button
+          theme={theme}
+          label={open ? "Hide" : "Show"}
+          onPress={() => setOpen((current) => !current)}
+          testID="prompt-kit-advanced-toggle"
+        />
+      }
+    >
+      {open ? (
+        <>
+          <SettingsCard>
+            <SettingsInput
+              key={`${epoch}-timeout`}
+              label="Timeout (ms)"
+              hint={timeout.note ?? `How long one rewrite may run. Default ${TIMEOUT_MS.default.toLocaleString()} ms.`}
+              error={timeout.error}
+              initialValue={String(values.timeoutMs)}
+              placeholder={String(TIMEOUT_MS.default)}
+              disabled={disabled}
+              onChangeText={(text) => {
+                const parsed = Number(text.trim());
+                patch({ timeoutMs: Number.isFinite(parsed) ? parsed : Number.NaN });
+              }}
+            />
+          </SettingsCard>
+
+          {values.transport === "cli" ? (
+            <ProviderMapCard
+              title="CLI per provider"
+              hint="Paseo names most providers after their CLI, so the family is read from the id and no entry is needed. Map only a provider whose id does not say which CLI runs it; an unresolved provider is refused, never guessed."
+              providers={providers}
+              map={values.providerCli}
+              targets={CLI_FAMILY_IDS.map((family) => ({ label: family, value: family }))}
+              emptyTargetsLabel="No CLI family is available."
+              errorFor={(providerId, family) =>
+                isCliFamilyId(family) ? null : `"${family}" is not a supported CLI.`
+              }
+              disabled={disabled}
+              onSet={(providerId, family) =>
+                patch((current) => ({
+                  providerCli: isCliFamilyId(family)
+                    ? { ...current.providerCli, [providerId]: family }
+                    : current.providerCli,
+                }))
+              }
+              onRemove={(providerId) =>
+                patch((current) => {
+                  const next = { ...current.providerCli };
+                  delete next[providerId];
+                  return { providerCli: next };
+                })
+              }
+            />
+          ) : (
+            <ProviderMapCard
+              title="Endpoint per provider"
+              hint="When you press the pill in an agent of a mapped provider, that agent's own model is sent to the endpoint over HTTP instead of through its CLI. A mapped provider ignores the Model chosen under API endpoint."
+              providers={providers}
+              map={values.apiEndpointByProvider}
+              targets={values.apiEndpoints.map((endpoint) => ({ label: endpoint.label, value: endpoint.id }))}
+              emptyTargetsLabel="Add an endpoint above first."
+              disabled={disabled}
+              onSet={(providerId, endpointId) =>
+                patch((current) => ({
+                  apiEndpointByProvider: { ...current.apiEndpointByProvider, [providerId]: endpointId },
+                }))
+              }
+              onRemove={(providerId) =>
+                patch((current) => {
+                  const next = { ...current.apiEndpointByProvider };
+                  delete next[providerId];
+                  return { apiEndpointByProvider: next };
+                })
+              }
+            />
+          )}
+        </>
+      ) : (
+        <SettingsCard>
+          <SettingsRow
+            label={`Timeout ${values.timeoutMs.toLocaleString()} ms · ${
+              values.transport === "cli"
+                ? `${Object.keys(values.providerCli).length} CLI override${Object.keys(values.providerCli).length === 1 ? "" : "s"}`
+                : `${Object.keys(values.apiEndpointByProvider).length} mapped provider${Object.keys(values.apiEndpointByProvider).length === 1 ? "" : "s"}`
+            }`}
+            hint="Press Show to change these."
+            error={timeout.error}
+          />
+        </SettingsCard>
+      )}
+    </SettingsSection>
+  );
+}