@tai42/studio-sdk 30.0.1 → 31.0.0

package/src/components/tool-picker.tsx

@@ -1,16 +1,23 @@
 /**
  * `ToolPicker` — a controlled single-select over the tool names a host offers, built
- * on the DS `Select` so features share one picker instead of each re-implementing
- * a listbox (the same reason `SchemaForm` lives in the SDK). It is
+ * on the DS `SearchableSelect` so features share one picker instead of each
+ * re-implementing a listbox (the same reason `SchemaForm` lives in the SDK). It is
  * PRESENTATIONAL: the host owns the tool list read and hands it in as `query`, and
  * owns the selected value; this component fetches nothing.
  *
+ * Opening the picker opens a search box: typing narrows the options to the tools whose
+ * label contains the text, ignoring case. The label carries the display name and the
+ * raw name, so either finds the tool.
+ *
  * The picker owns its `Field` (with `label`) and draws the read's states in it: pending
- * (a disabled `Select` reading "Loading tools…"), error (`ErrorState` with Retry, or the
+ * (a disabled select reading "Loading tools…"), error (`ErrorState` with Retry, or the
  * host's `errorNote` line where the same failure is drawn with Retry elsewhere), refused
- * (a 403 with `forbiddenNote` set), and loaded with nothing to offer (the host's
- * `emptyNote`, then its `emptyAction`). The host's `error` shows, and the `Field` claims
- * its control id, exactly while a `Select` renders.
+ * (a 403 where the host sets no `errorNote`: the session may not list tools, so a text
+ * input takes the tool's name, with a note saying why there is no list; the server
+ * checks the name on save), and loaded with
+ * nothing to offer (the host's `emptyNote`, then its `emptyAction`). The host's `error`
+ * shows, and the `Field` claims its control id, exactly while a select or the typed
+ * entry renders.
  *
  * Optional extensions, each inert unless supplied:
  *  - `excludeNames` removes names from the options (e.g. a preset cannot be
@@ -30,8 +37,8 @@
  *  - `displayNames` (from the tool-meta overlay) overlays a human name onto the
  *    LABEL: a mapped option reads `Display Name (raw_name)`, an unmapped name (or a
  *    mapping equal to the raw name) reads the bare raw name. The value stays the raw
- *    name and grouping/filtering/exclusion key off raw names alone, so a display
- *    name is purely cosmetic.
+ *    name and grouping/tag filtering/exclusion key off raw names alone; the display
+ *    name only labels the option, and so is what the search reads with the raw name.
  *  - `badgesByTool` (native ∪ overlay, from the tool-meta merge) surfaces the
  *    SELECTED tool's DECLARED capability badges as read-only chips beneath the
  *    select. Badges are INFORMATIONAL — the tooltip says so — never a gate, so they
@@ -40,7 +47,7 @@
  * SAFETY: a tool name, a tag, a display name, AND a badge are server-supplied, so
  * every one renders as TEXT (React escapes it) — never an HTML sink. Pinned by a test.
  */
-import { type ReactNode, useId, useState } from 'react';
+import { type ReactNode, useId, useMemo, useState } from 'react';
 
 import { errorMessage, isForbiddenError } from '../errors';
 import { Badge } from './badge';
@@ -49,6 +56,7 @@ import { ErrorState } from './primitives';
 import type { SelectOption } from './select';
 import { SelectedToolBadges } from './selected-tool-badges';
 import { ALL_TAGS, TagFilterField } from './tag-filter-field';
+import { ToolNameEntry } from './tool-name-entry';
 import { ToolSelect } from './tool-select';
 
 export { BADGES_NOTE } from './selected-tool-badges';
@@ -79,12 +87,11 @@ export interface ToolPickerProps {
   /** Drawn after `emptyNote` in the empty state (e.g. a link to where tools come from). */
   readonly emptyAction?: ReactNode;
   /**
-   * Drawn in place of the `ErrorState` and the control when the read fails, with no
-   * Retry: for a host that already draws the same read's failure with Retry elsewhere.
+   * Drawn in place of the `ErrorState` and the control when the read fails, a 403
+   * included, with no Retry: for a host that already draws the same read's failure
+   * elsewhere. Such a host draws no typed entry on a 403.
    */
   readonly errorNote?: string;
-  /** Drawn on a 403 of the read in place of the error state (the no-grant state). */
-  readonly forbiddenNote?: string;
   /** Flags a stored value the loaded list does not carry (see the module docs). */
   readonly unlistedLabel?: string;
   readonly disabled?: boolean;
@@ -94,13 +101,12 @@ export interface ToolPickerProps {
   readonly label?: string;
   /** Handed to the picker's `Field` (with `label`). */
   readonly description?: string;
-  /** The host's field error, shown under the control while a `Select` renders (with `label`). */
+  /** The host's field error, shown under the control while one renders (with `label`). */
   readonly error?: string;
   /**
-   * Accessible name for the tool listbox when `label` renders none and no
-   * enclosing `Field` names it. `label` wins where both are given: it names the
-   * control from visible text, and the `Select` drops a caller name it would
-   * otherwise override.
+   * Accessible name for the control when `label` renders none and no enclosing
+   * `Field` names it. `label` wins where both are given: it names the control from
+   * visible text, and the control drops a caller name it would otherwise override.
    */
   readonly 'aria-label'?: string;
   /** Names removed from the options (the server remains the authority). */
@@ -129,7 +135,6 @@ type PickerPhase = 'refused' | 'error' | 'unlisted' | 'empty' | 'select';
 
 interface PickerState {
   readonly phase: PickerPhase;
-  readonly available: readonly string[];
   /** The stored value, or `null` for none. */
   readonly stored: string | null;
   readonly pending: boolean;
@@ -150,23 +155,31 @@ function phaseOf(
   return empty ? 'empty' : 'select';
 }
 
+/** The loaded names the picker offers: the read's data without `excludeNames`. */
+function availableNames(
+  data: readonly string[] | undefined,
+  excludeNames: readonly string[] | undefined,
+): readonly string[] {
+  const excluded = new Set(excludeNames ?? []);
+  return (data ?? []).filter((name) => !excluded.has(name));
+}
+
 function pickerState(
   query: ToolListQuery,
+  available: readonly string[],
   value: string | null,
-  excludeNames: readonly string[] | undefined,
-  forbiddenNote: string | undefined,
   unlistedLabel: string | undefined,
+  errorNote: string | undefined,
 ): PickerState {
-  const excluded = new Set(excludeNames ?? []);
-  const available = (query.data ?? []).filter((name) => !excluded.has(name));
   const stored = value !== null && value !== '' ? value : null;
   const loaded = query.isSuccess && !query.isError;
   const unlisted =
     unlistedLabel !== undefined && loaded && stored !== null && !available.includes(stored);
   const empty = loaded && available.length === 0;
-  const refused = forbiddenNote !== undefined && query.isError && isForbiddenError(query.error);
+  // A host with `errorNote` draws the read's failure itself, a 403 included.
+  const refused = errorNote === undefined && query.isError && isForbiddenError(query.error);
   const phase = phaseOf(refused, query.isError, unlisted, empty);
-  return { phase, available, stored, pending: !loaded && !query.isError, unlisted, empty };
+  return { phase, stored, pending: !loaded && !query.isError, unlisted, empty };
 }
 
 /** The distinct tags across `names`, sorted, feeding the filter control. */
@@ -181,21 +194,31 @@ function tagsAcross(
 
 /** The tag filter's choices, and the available names the chosen tag keeps. */
 function tagView(
-  state: PickerState,
+  available: readonly string[],
+  listed: boolean,
   tagsByTool: Readonly<Record<string, readonly string[]>> | undefined,
   tagFilter: string,
 ): { readonly allTags: readonly string[]; readonly filtered: readonly string[] } {
-  if (tagsByTool === undefined) return { allTags: [], filtered: state.available };
-  const listed = !state.pending && state.phase !== 'error' && state.phase !== 'refused';
+  if (tagsByTool === undefined) return { allTags: [], filtered: available };
   return {
-    allTags: listed ? tagsAcross(state.available, tagsByTool) : [],
+    allTags: listed ? tagsAcross(available, tagsByTool) : [],
     filtered:
       tagFilter === ALL_TAGS
-        ? state.available
-        : state.available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter)),
+        ? available
+        : available.filter((name) => (tagsByTool[name] ?? []).includes(tagFilter)),
   };
 }
 
+/** The option drawn ahead of the list's own: an unlisted value, flagged with `unlistedLabel`. */
+function leadingOption(
+  phase: PickerPhase,
+  stored: string | null,
+  unlistedLabel: string | undefined,
+): SelectOption | undefined {
+  if (stored === null || phase !== 'unlisted') return undefined;
+  return { value: stored, label: `${stored} (${unlistedLabel ?? ''})` };
+}
+
 function MutedLine({ text }: { readonly text: string }): ReactNode {
   return (
     <p role="status" style={MUTED_LINE}>
@@ -222,7 +245,6 @@ export function ToolPicker({
   emptyNote,
   emptyAction,
   errorNote,
-  forbiddenNote,
   unlistedLabel,
   disabled,
   placeholder = 'Select a tool…',
@@ -239,12 +261,26 @@ export function ToolPicker({
 }: ToolPickerProps) {
   const [tagFilter, setTagFilter] = useState<string>(ALL_TAGS);
   const unlistedId = useId();
-  const state = pickerState(query, value, excludeNames, forbiddenNote, unlistedLabel);
+  // Memoised so a host re-render hands the select the same options, and an open
+  // list keeps its rows instead of re-indexing every tool.
+  const available = useMemo(
+    () => availableNames(query.data, excludeNames),
+    [query.data, excludeNames],
+  );
+  const state = pickerState(query, available, value, unlistedLabel, errorNote);
   const { phase, stored } = state;
 
-  const { allTags, filtered } = tagView(state, tagsByTool, tagFilter);
+  const listed = !state.pending && phase !== 'error' && phase !== 'refused';
+  const { allTags, filtered } = useMemo(
+    () => tagView(available, listed, tagsByTool, tagFilter),
+    [available, listed, tagsByTool, tagFilter],
+  );
 
-  const select = (options: readonly string[], leading: SelectOption | undefined): ReactNode => (
+  const leading = useMemo(
+    () => leadingOption(phase, stored, unlistedLabel),
+    [phase, stored, unlistedLabel],
+  );
+  const select = (options: readonly string[]): ReactNode => (
     <ToolSelect
       tagsByTool={tagsByTool}
       filtered={options}
@@ -266,26 +302,23 @@ export function ToolPicker({
     </>
   );
 
-  // Only a rendered `Select` claims the field's control id; with none the host's
+  // Only a rendered control claims the field's control id; with none the host's
   // error is hidden and the note in its place says why the field is empty.
-  const selectRenders =
-    phase === 'unlisted' || phase === 'select' || (phase === 'refused' && stored !== null);
+  const controlRenders = phase === 'unlisted' || phase === 'select' || phase === 'refused';
   const contentByPhase: Record<PickerPhase, () => ReactNode> = {
-    // A stored value stays as the sole, unflagged option: without the list the form claims nothing about it.
     refused: () => (
-      <>
-        {stored !== null ? select([], { value: stored, label: stored }) : null}
-        <MutedLine text={forbiddenNote ?? ''} />
-      </>
+      <ToolNameEntry
+        value={stored}
+        onChange={onChange}
+        disabled={disabled === true}
+        ariaLabel={ariaLabel}
+      />
     ),
     error: () =>
       errorNote !== undefined ? <MutedLine text={errorNote} /> : <ReadError query={query} />,
     unlisted: () => (
       <>
-        {select(filtered, {
-          value: stored ?? '',
-          label: `${stored ?? ''} (${unlistedLabel ?? ''})`,
-        })}
+        {select(filtered)}
         {state.empty ? emptyState : null}
         <p id={unlistedId} className="tai-field-hint" style={{ margin: 0 }}>
           <Badge variant="warning">{unlistedLabel}</Badge> {stored} is {unlistedLabel}. Pick
@@ -294,7 +327,7 @@ export function ToolPicker({
       </>
     ),
     empty: () => emptyState,
-    select: () => select(filtered, undefined),
+    select: () => select(filtered),
   };
   const content = contentByPhase[phase]();
 
@@ -312,8 +345,8 @@ export function ToolPicker({
         <Field
           label={label}
           description={description}
-          error={selectRenders ? error : undefined}
-          group={!selectRenders}
+          error={controlRenders ? error : undefined}
+          group={!controlRenders}
         >
           {content}
         </Field>

package/src/components/tool-select.tsx

@@ -1,14 +1,17 @@
 /**
- * `ToolPicker`'s tool `Select`: grouped by tag or flat, with the option-label and
- * grouping helpers it renders from.
+ * `ToolPicker`'s tool select: a `SearchableSelect`, grouped by tag or flat, with the
+ * option-label and grouping helpers it renders from. Its search matches the option
+ * label, which carries both the display name and the raw name (`toolDisplayLabel`).
  */
-import type { ReactNode } from 'react';
+import { type ReactNode, useMemo } from 'react';
 
 import { toolDisplayLabel } from '../hooks/useToolDisplayNames';
-import { Select, type SelectGroup, type SelectOption } from './select';
+import { SearchableSelect } from './searchable-select';
+import type { SelectGroup, SelectOption } from './select';
 
 const NO_DISPLAY_NAMES: Readonly<Record<string, string>> = {};
 const UNTAGGED = 'Untagged';
+const SEARCH_LABEL = 'Search tools';
 
 /** The group a tool sorts into: its alphabetically-first tag, else "Untagged". */
 function groupFor(name: string, tagsByTool: Readonly<Record<string, readonly string[]>>): string {
@@ -73,8 +76,31 @@ interface ToolSelectProps {
   readonly ariaDescribedBy: string | undefined;
 }
 
+/** The select's options: tag groups when `tagsByTool` is present, else one flat run,
+ *  with `leading` ahead of either. */
+function toolListing(
+  filtered: readonly string[],
+  tagsByTool: Readonly<Record<string, readonly string[]>> | undefined,
+  displayNames: Readonly<Record<string, string>> | undefined,
+  agentToolNames: ReadonlySet<string> | undefined,
+  leading: SelectOption | undefined,
+): { readonly groups: readonly SelectGroup[] } | { readonly options: readonly SelectOption[] } {
+  if (tagsByTool !== undefined) {
+    const groups = buildGroups(filtered, tagsByTool, displayNames, agentToolNames);
+    return {
+      groups:
+        leading === undefined ? groups : [{ label: leading.label, options: [leading] }, ...groups],
+    };
+  }
+  const options = filtered.map((name) => ({
+    value: name,
+    label: optionLabel(name, displayNames, agentToolNames),
+  }));
+  return { options: leading === undefined ? options : [leading, ...options] };
+}
+
 /** The tool select: grouped by tag when `tagsByTool` is present, else a flat list.
- *  Either branch is a `Select`, which claims the enclosing `Field`'s control id. */
+ *  Either branch is a `SearchableSelect`, which claims the enclosing `Field`'s control id. */
 export function ToolSelect({
   tagsByTool,
   filtered,
@@ -88,38 +114,23 @@ export function ToolSelect({
   leading,
   ariaDescribedBy,
 }: ToolSelectProps): ReactNode {
-  if (tagsByTool !== undefined) {
-    const groups = buildGroups(filtered, tagsByTool, displayNames, agentToolNames);
-    return (
-      <Select
-        groups={
-          leading === undefined ? groups : [{ label: leading.label, options: [leading] }, ...groups]
-        }
-        value={value ?? ''}
-        onValueChange={onChange}
-        placeholder={placeholder}
-        aria-label={ariaLabel}
-        aria-describedby={ariaDescribedBy}
-        disabled={disabled}
-      />
-    );
-  }
-  const options = filtered.map((name) => ({
-    value: name,
-    label: optionLabel(name, displayNames, agentToolNames),
-  }));
-  return (
-    <Select
-      // Keep Radix controlled even when the caller's value is null: `''` matches no
-      // item (placeholder still shows) and avoids the uncontrolled→controlled warning
-      // a subsequent selection would otherwise trigger.
-      options={leading === undefined ? options : [leading, ...options]}
-      value={value ?? ''}
-      onValueChange={onChange}
-      placeholder={placeholder}
-      aria-label={ariaLabel}
-      aria-describedby={ariaDescribedBy}
-      disabled={disabled}
-    />
+  // Memoised so a host re-render keeps the indexed options of an open list.
+  const listing = useMemo(
+    () => toolListing(filtered, tagsByTool, displayNames, agentToolNames, leading),
+    [filtered, tagsByTool, displayNames, agentToolNames, leading],
+  );
+  const shared = {
+    value: value ?? '',
+    onValueChange: onChange,
+    placeholder,
+    'aria-label': ariaLabel,
+    'aria-describedby': ariaDescribedBy,
+    disabled,
+    searchLabel: SEARCH_LABEL,
+  };
+  return 'groups' in listing ? (
+    <SearchableSelect {...shared} groups={listing.groups} />
+  ) : (
+    <SearchableSelect {...shared} options={listing.options} />
   );
 }

package/src/hooks/useSystemKinds.tsx

@@ -7,8 +7,9 @@
  * for it; the kind-status table then reports that kind's `state` as `off` (rather
  * than `active` / `default`). A write affordance for an OFF feature reads this and
  * hides itself BEFORE the user acts, instead of learning OFF only from a write's 501
- * refusal — the reactive `isFeatureDisabled` swallow stays as the backstop for a
- * stale table.
+ * refusal. A write's 501 refusal is the backstop for a stale table: the surface that
+ * saw it reports it through `useReportFeatureOff`, and the provider then reads that
+ * kind as OFF for every surface in the app, with the refusal's own message.
  *
  * A PLAIN fetch state machine (`loading` / `ready` / `failed`), NOT TanStack Query:
  * the SDK is the shared leaf across the plugin boundary and holds no query context,
@@ -21,8 +22,10 @@ import {
   createContext,
   createElement,
   type ReactNode,
+  useCallback,
   useContext,
   useEffect,
+  useMemo,
   useState,
 } from 'react';
 
@@ -34,7 +37,14 @@ export type SystemKindsState =
   | { readonly status: 'ready'; readonly kinds: readonly KindStatus[] }
   | { readonly status: 'failed'; readonly error: unknown };
 
-const SystemKindsContext = createContext<SystemKindsState | null>(null);
+interface SystemKindsContextValue {
+  readonly state: SystemKindsState;
+  /** Kinds a write refusal revealed OFF, each with the refusal's message. */
+  readonly refusedOff: ReadonlyMap<string, string>;
+  readonly reportOff: (kind: string, message: string) => void;
+}
+
+const SystemKindsContext = createContext<SystemKindsContextValue | null>(null);
 
 /**
  * Fetch the kind-status table once the caller is authenticated and hold it as SDK
@@ -47,8 +57,12 @@ export function SystemKindsProvider({ children }: { children: ReactNode }) {
   const { isAuthenticated } = useAuth();
   const api = useApi();
   const [state, setState] = useState<SystemKindsState>({ status: 'loading' });
+  const [refusedOff, setRefusedOff] = useState<ReadonlyMap<string, string>>(() => new Map());
 
   useEffect(() => {
+    // A sign-in, a sign-out or a new API client starts from the table alone: what
+    // refusals revealed for an earlier session or another client is not carried over.
+    setRefusedOff(new Map());
     if (!isAuthenticated) {
       // No credential → nothing to read. Reset to the neutral `loading` state so the
       // next sign-in re-fetches cleanly; every kind reads not-off meanwhile.
@@ -70,28 +84,71 @@ export function SystemKindsProvider({ children }: { children: ReactNode }) {
     };
   }, [api, isAuthenticated]);
 
-  return createElement(SystemKindsContext.Provider, { value: state }, children);
+  const reportOff = useCallback((kind: string, message: string) => {
+    setRefusedOff((current) => {
+      if (current.get(kind) === message) return current;
+      const next = new Map(current);
+      next.set(kind, message);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo<SystemKindsContextValue>(
+    () => ({ state, refusedOff, reportOff }),
+    [state, refusedOff, reportOff],
+  );
+  return createElement(SystemKindsContext.Provider, { value }, children);
 }
 
+const NO_REFUSALS: ReadonlyMap<string, string> = new Map();
+
 /**
  * The live kind-status state. Falls back to `loading` when no provider is mounted, so
  * a consumer rendered outside the shell reads every kind as not-off rather than
  * throwing — the fail-open default this proactive-hiding idiom relies on.
  */
 export function useSystemKinds(): SystemKindsState {
-  return useContext(SystemKindsContext) ?? { status: 'loading' };
+  return useContext(SystemKindsContext)?.state ?? { status: 'loading' };
+}
+
+/** The kinds a write refusal revealed OFF in this session (none without a provider). */
+function useRefusedOff(): ReadonlyMap<string, string> {
+  return useContext(SystemKindsContext)?.refusedOff ?? NO_REFUSALS;
+}
+
+/**
+ * Record that a write refusal revealed `kind` OFF, with the refusal's own `message`,
+ * so every surface's `useFeatureOff(kind)` reads OFF from then on. Calling the
+ * returned function with no `SystemKindsProvider` mounted throws: the refusal would
+ * otherwise reach no other surface.
+ */
+export function useReportFeatureOff(): (kind: string, message: string) => void {
+  const context = useContext(SystemKindsContext);
+  return useCallback(
+    (kind: string, message: string) => {
+      if (context === null) {
+        throw new Error(
+          `A ${kind} refusal was reported with no <SystemKindsProvider> mounted to hold it.`,
+        );
+      }
+      context.reportOff(kind, message);
+    },
+    [context],
+  );
 }
 
 /**
- * Whether `kind` is reported OFF by the kind-status table — the single proactive
- * predicate a write affordance folds in to hide itself before a doomed write. It is
- * `true` ONLY once the table is `ready` AND that kind's row carries `state: 'off'`;
- * while the table is loading/failed, no provider is mounted, or the kind is unknown,
- * it is `false` (treat as not-off until known — under-hiding is safe, the reactive
- * 501 backstop still catches a genuinely-off feature).
+ * Whether `kind` is OFF — the single predicate a write affordance folds in to hide
+ * itself before a doomed write. It is `true` once the table is `ready` AND that kind's
+ * row carries `state: 'off'`, or once a write refusal revealed the kind OFF
+ * ({@link useReportFeatureOff}). Otherwise — the table loading/failed, no provider
+ * mounted, the kind unknown — it is `false` (not-off until known: under-hiding is
+ * safe, a write's 501 refusal still reveals a genuinely-off feature).
  */
 export function useFeatureOff(kind: string): boolean {
   const state = useSystemKinds();
+  const refused = useRefusedOff().has(kind);
+  if (refused) return true;
   if (state.status !== 'ready') return false;
   return state.kinds.some((row) => row.kind === kind && row.state === 'off');
 }
@@ -99,13 +156,16 @@ export function useFeatureOff(kind: string): boolean {
 /**
  * The OFF row's server `detail` for `kind` — the proactive counterpart to a write
  * refusal's message, so a proactively-hidden surface shows the SERVER's own
- * remediation line rather than a client-composed env-var string. `null` whenever the
- * kind is not reported OFF (table loading/failed, no provider, unknown kind, or the
- * kind is on), mirroring `useFeatureOff`'s not-off-until-known default.
+ * remediation line rather than a client-composed env-var string; for a kind only a
+ * write refusal revealed OFF, that refusal's message. `null` whenever the kind is not
+ * OFF, mirroring `useFeatureOff`'s not-off-until-known default.
  */
 export function useFeatureOffMessage(kind: string): string | null {
   const state = useSystemKinds();
-  if (state.status !== 'ready') return null;
-  const row = state.kinds.find((entry) => entry.kind === kind && entry.state === 'off');
-  return row ? row.detail : null;
+  const refused = useRefusedOff().get(kind);
+  if (state.status === 'ready') {
+    const row = state.kinds.find((entry) => entry.kind === kind && entry.state === 'off');
+    if (row) return row.detail;
+  }
+  return refused ?? null;
 }