@tai42/studio-sdk 17.1.2 → 18.0.0

package/dist/testing.d.ts

@@ -28,16 +28,18 @@ export declare function flushResizeObservers(): void;
  */
 export declare function flushResizeObserversFor(target: Element): void;
 /**
- * Makes `element` report itself as horizontally overflowing (or not). jsdom runs
- * no layout, so `scrollWidth` and `clientWidth` are both 0 and every
- * overflow test reads as "fits"; this shadows the prototype getters with own,
- * configurable values so a test can drive either state. Call it again with the
- * opposite flag to flip the element back.
+ * Makes `element` report itself as overflowing (or not) on `axis`. jsdom runs no
+ * layout, so `scroll*` and `client*` are both 0 and every overflow test reads as
+ * "fits"; this shadows the prototype getters with own, configurable values so a
+ * test can drive either state. Call it again with the opposite flag to flip the
+ * element back.
  *
  * @param element - the element whose scroll metrics to fake.
- * @param overflowing - true to report content wider than the box.
+ * @param overflowing - true to report content larger than the box on `axis`.
+ * @param axis - the dimension to fake: `horizontal` (width, the default) or
+ *   `vertical` (height).
  */
-export declare function setElementOverflow(element: HTMLElement, overflowing: boolean): void;
+export declare function setElementOverflow(element: HTMLElement, overflowing: boolean, axis?: 'horizontal' | 'vertical'): void;
 /**
  * jsdom omits a handful of browser APIs the Studio components reach for while a
  * test drives them. Installing every stub in one place keeps each feature's

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,0FAA0F;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,qFAAqF;AACrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAuE7E;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAK7D;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,GAAG,IAAI,CAMnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CA4GxC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,KAAK;IAC7B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC,CAQA"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,0FAA0F;AAC1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,qFAAqF;AACrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAuE7E;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAK7D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,OAAO,EACpB,IAAI,GAAE,YAAY,GAAG,UAAyB,GAC7C,IAAI,CAQN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CA4GxC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,KAAK;IAC7B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC,CAQA"}

package/dist/testing.js

@@ -88,24 +88,27 @@ export function flushResizeObserversFor(target) {
         live.callback([resizeObserverEntry(target)], live.observer);
     }
 }
-/** The faked widths: equal reads as "fits", unequal as "scrolls". */
-const FITTING_WIDTH = 100;
-const OVERFLOWING_SCROLL_WIDTH = 400;
+/** The faked extents: equal reads as "fits", unequal as "scrolls". */
+const FITTING_EXTENT = 100;
+const OVERFLOWING_SCROLL_EXTENT = 400;
 /**
- * Makes `element` report itself as horizontally overflowing (or not). jsdom runs
- * no layout, so `scrollWidth` and `clientWidth` are both 0 and every
- * overflow test reads as "fits"; this shadows the prototype getters with own,
- * configurable values so a test can drive either state. Call it again with the
- * opposite flag to flip the element back.
+ * Makes `element` report itself as overflowing (or not) on `axis`. jsdom runs no
+ * layout, so `scroll*` and `client*` are both 0 and every overflow test reads as
+ * "fits"; this shadows the prototype getters with own, configurable values so a
+ * test can drive either state. Call it again with the opposite flag to flip the
+ * element back.
  *
  * @param element - the element whose scroll metrics to fake.
- * @param overflowing - true to report content wider than the box.
+ * @param overflowing - true to report content larger than the box on `axis`.
+ * @param axis - the dimension to fake: `horizontal` (width, the default) or
+ *   `vertical` (height).
  */
-export function setElementOverflow(element, overflowing) {
-    Object.defineProperty(element, 'clientWidth', { configurable: true, value: FITTING_WIDTH });
-    Object.defineProperty(element, 'scrollWidth', {
+export function setElementOverflow(element, overflowing, axis = 'horizontal') {
+    const [client, scroll] = axis === 'vertical' ? ['clientHeight', 'scrollHeight'] : ['clientWidth', 'scrollWidth'];
+    Object.defineProperty(element, client, { configurable: true, value: FITTING_EXTENT });
+    Object.defineProperty(element, scroll, {
         configurable: true,
-        value: overflowing ? OVERFLOWING_SCROLL_WIDTH : FITTING_WIDTH,
+        value: overflowing ? OVERFLOWING_SCROLL_EXTENT : FITTING_EXTENT,
     });
 }
 /**

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tai42/studio-sdk",
-  "version": "17.1.2",
+  "version": "18.0.0",
   "description": "The Studio plugin contract, shared UI components, and hooks that every feature builds on.",
   "license": "Apache-2.0",
   "author": "tai42 <oss@tai42.ai>",
@@ -73,7 +73,7 @@
   },
   "devDependencies": {
     "@microsoft/api-extractor": "7.58.12",
-    "@tai42/jq-studio": "^0.1.3",
+    "@tai42/jq-studio": "^0.1.6",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.6",
@@ -96,7 +96,7 @@
     "@radix-ui/react-select": "^2.3.2",
     "@radix-ui/react-tabs": "^1.1.21",
     "@radix-ui/react-tooltip": "^1.2.11",
-    "@tai42/api-client": "17.1.2"
+    "@tai42/api-client": "18.0.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json && node scripts/copy-assets.mjs",

package/src/components/execution-key-picker.tsx

@@ -0,0 +1,116 @@
+/**
+ * Picks the api key a fire / recurring run RUNS AS. Shared by every fire-path form
+ * (hooks, trigger links, schedules). Presentational and prop-driven — the host
+ * feature owns the api-key list query and hands it in, so this component (and the
+ * SDK) stay free of a data-fetching library, exactly as {@link ToolPicker} does.
+ *
+ * The server decides authorization; this only lists the pickable keys and renders
+ * the read's loading / empty / error states. The host form renders the server's
+ * refusal verbatim elsewhere.
+ */
+import type { TokensPayload } from '@tai42/api-client';
+import type { ReactNode } from 'react';
+
+import { errorMessage } from '../errors';
+import { Field } from './field';
+import { ErrorState } from './primitives';
+import { Select } from './select';
+
+/**
+ * The subset of the api-key list query this picker reads. A caller's TanStack
+ * `UseQueryResult<TokensPayload>` satisfies it structurally, so the SDK names no
+ * query library.
+ */
+export interface ExecutionKeyQuery {
+  readonly data: TokensPayload | undefined;
+  readonly isPending: boolean;
+  readonly isError: boolean;
+  readonly isSuccess: boolean;
+  readonly error: unknown;
+  readonly refetch: () => void;
+}
+
+/** Resolved, and holding no key at all. */
+export function isExecutionKeyListEmpty(query: ExecutionKeyQuery): boolean {
+  return query.isSuccess && (query.data?.length ?? 0) === 0;
+}
+
+/** The mint's stable fingerprint (never key material), nested under `policy_data`. */
+function keyFingerprint(key: TokensPayload[number]): string | undefined {
+  const data = key.policy_data;
+  if (typeof data !== 'object' || data === null) return undefined;
+  const value = (data as Record<string, unknown>).key_fingerprint;
+  return typeof value === 'string' ? value : undefined;
+}
+
+/** A key's label: its id, plus whichever of description / fingerprint it has. */
+function keyLabel(key: TokensPayload[number]): string {
+  const suffix = [key.description, keyFingerprint(key)]
+    .filter((part) => part !== undefined && part !== '')
+    .join(' · ');
+  return suffix === '' ? key.user_id : `${key.user_id} — ${suffix}`;
+}
+
+/** One option per `user_id` (what a binding names), first occurrence wins. */
+function pickableKeys(keys: TokensPayload): TokensPayload {
+  const seen = new Set<string>();
+  return keys.filter((key) => {
+    if (seen.has(key.user_id)) return false;
+    seen.add(key.user_id);
+    return true;
+  });
+}
+
+export interface ExecutionKeyPickerProps {
+  /** The api-key list read the host feature owns and hands in. */
+  readonly query: ExecutionKeyQuery;
+  readonly value: string;
+  readonly onValueChange: (value: string) => void;
+  /** The host form's required-field error, shown under the control. */
+  readonly error?: string | undefined;
+}
+
+export function ExecutionKeyPicker({
+  query,
+  value,
+  onValueChange,
+  error,
+}: ExecutionKeyPickerProps): ReactNode {
+  const listEmpty = isExecutionKeyListEmpty(query);
+
+  return (
+    <Field
+      label="Execution key"
+      description="The api key this fire runs AS. Every tool call it makes is authorized against that key's live grants — prefer a least-privilege service key over a human's broad one."
+      // Suppressed: the empty note / the ErrorState already say it.
+      error={listEmpty || query.isError ? undefined : error}
+      // Only the Select branch claims the field's control id; the error and
+      // empty branches render no labelable element, so `for` would dangle.
+      group={query.isError || listEmpty}
+    >
+      {query.isError ? (
+        <ErrorState
+          message={errorMessage(query.error)}
+          onRetry={() => {
+            query.refetch();
+          }}
+        />
+      ) : listEmpty ? (
+        <p role="status" style={{ margin: 0, color: 'var(--tai-color-text-muted)' }}>
+          No api keys available to run as. Mint one on the settings API-keys tab first.
+        </p>
+      ) : (
+        <Select
+          options={pickableKeys(query.data ?? []).map((key) => ({
+            value: key.user_id,
+            label: keyLabel(key),
+          }))}
+          value={value}
+          placeholder={query.isPending ? 'Loading keys…' : 'Select an execution key'}
+          disabled={query.isPending}
+          onValueChange={onValueChange}
+        />
+      )}
+    </Field>
+  );
+}

package/src/components/json-tree-nodes.tsx

@@ -40,8 +40,19 @@ const summaryStyle: CSSProperties = {
   cursor: 'pointer',
 };
 
-/** The copy control sits at the far end of a disclosure's row. */
-const nodeCopyStyle: CSSProperties = { marginLeft: 'auto' };
+/**
+ * A disclosure and its copy control share one row: the disclosure fills it and the
+ * copy control sits at the far end, top-aligned with the summary so it stays on the
+ * summary's line even when the open node's children run tall below it.
+ */
+const nodeRowStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 'var(--tai-space-2)',
+};
+
+/** The disclosure takes the row's width, leaving the copy control at its end. */
+const nodeDetailsStyle: CSSProperties = { flex: 1, minWidth: 0 };
 
 /**
  * The per-node copy button's geometry: borrows `tai-icon-btn` for the focus ring,
@@ -89,11 +100,7 @@ export function CopyButton({ value, label, variant }: CopyButtonProps): ReactEle
     };
   }, []);
 
-  const handleClick = (event: ReactMouseEvent<HTMLButtonElement>): void => {
-    // Inside a `<summary>` a click both toggles the disclosure natively and reaches
-    // the summary's own toggle handler; neither should fire for a copy.
-    event.preventDefault();
-    event.stopPropagation();
+  const handleClick = (): void => {
     void copy(value).then((ok) => {
       if (!ok || !mounted.current) return;
       setCopied(true);
@@ -117,7 +124,7 @@ export function CopyButton({ value, label, variant }: CopyButtonProps): ReactEle
     <button
       type="button"
       className="tai-icon-btn"
-      style={{ ...nodeCopyStyle, ...nodeCopyButtonStyle }}
+      style={nodeCopyButtonStyle}
       aria-label={copied ? COPIED_LABEL : label}
       onClick={handleClick}
     >
@@ -196,23 +203,34 @@ export function JsonNode({ name, value, depth, path }: NodeProps): ReactElement
       setOpen(path, !open);
     };
 
-    return (
-      <details open={open}>
+    const disclosure = (
+      <details open={open} style={depth > 0 ? nodeDetailsStyle : undefined}>
         <summary style={summaryStyle} onClick={handleToggle}>
           {name !== undefined ? <span className="tai-syntax-key">{name}: </span> : null}
           <span className="tai-muted">{summary}</span>
-          {/* The root's copy-node control would duplicate the toolbar's copy-whole. */}
-          {depth > 0 ? (
-            <CopyButton
-              value={value}
-              variant="icon"
-              label={name !== undefined ? `Copy ${name}` : COPY_LABEL}
-            />
-          ) : null}
         </summary>
         {open ? <NodeChildren value={value} count={count} depth={depth} path={path} /> : null}
       </details>
     );
+
+    // The root's copy-node control would duplicate the toolbar's copy-whole.
+    if (depth === 0) return disclosure;
+
+    // The copy control is a SIBLING of the disclosure, never a child of its
+    // interactive `<summary>`, so no interactive control nests inside another
+    // (WCAG 4.1.2 name/role/value — a nested-interactive control has no reliable
+    // accessible role). Both the disclosure toggle and the copy button stay
+    // independently keyboard operable.
+    return (
+      <div style={nodeRowStyle}>
+        {disclosure}
+        <CopyButton
+          value={value}
+          variant="icon"
+          label={name !== undefined ? `Copy ${name}` : COPY_LABEL}
+        />
+      </div>
+    );
   }
 
   return (

package/src/components/overflow-measure.ts

@@ -7,12 +7,23 @@
 
 export const SCROLL_REGION_CLASS = 'tai-scroll-region';
 
-export function overflows(element: HTMLElement): boolean {
-  return element.scrollWidth > element.clientWidth;
+/**
+ * The axis a scroll region is measured on. A prose table or a code line scrolls
+ * SIDEWAYS (`horizontal`, the default); a bounded, capped-height list scrolls
+ * DOWN (`vertical`). Both wear the same conditional region attributes — only the
+ * dimension read to decide whether they overflow differs.
+ */
+export type OverflowAxis = 'horizontal' | 'vertical';
+
+export function overflows(element: HTMLElement, axis: OverflowAxis = 'horizontal'): boolean {
+  return axis === 'vertical'
+    ? element.scrollHeight > element.clientHeight
+    : element.scrollWidth > element.clientWidth;
 }
 
 /**
- * Whether the element should carry the region attributes right now.
+ * Whether the element should carry the region attributes right now, measured on
+ * `axis`.
  *
  * A region that stops overflowing keeps its tab stop for as long as it holds
  * focus: taking `tabindex` off the focused element drops the reader onto the
@@ -20,8 +31,8 @@ export function overflows(element: HTMLElement): boolean {
  * already has the stop can be the active element, so this can hold a stop open
  * but never invent one.
  */
-export function needsRegion(element: HTMLElement): boolean {
-  return overflows(element) || element.ownerDocument.activeElement === element;
+export function needsRegion(element: HTMLElement, axis: OverflowAxis = 'horizontal'): boolean {
+  return overflows(element, axis) || element.ownerDocument.activeElement === element;
 }
 
 /** A tracked scrollable surface, with the name it wears while it scrolls. */

package/src/components/scroll-region.tsx

@@ -34,6 +34,7 @@ import {
 import {
   clearScrollRegionAttributes,
   needsRegion,
+  type OverflowAxis,
   refreshRegions,
   SCROLL_REGION_CLASS,
   type TrackedSurface,
@@ -46,12 +47,20 @@ import {
   uniquelyNamed,
 } from './prose-regions';
 
+export type { OverflowAxis } from './overflow-measure';
+
 export interface ScrollRegionProps {
   /** The region's accessible name, applied only while it actually scrolls. */
   readonly label: string;
   readonly children: ReactNode;
   readonly className?: string;
   readonly style?: CSSProperties;
+  /**
+   * The dimension overflow is measured on. `horizontal` (the default) fits a pane
+   * that scrolls sideways; `vertical` fits a bounded, capped-height box that scrolls
+   * down. The caller styles the box's own overflow to match.
+   */
+  readonly axis?: OverflowAxis;
   /**
    * The one arbitrary attribute this component forwards. The measured attributes
    * — `tabindex`, `role` and `aria-label` — are the component's own and appear
@@ -118,10 +127,13 @@ export interface OverflowRegionAttributes {
  *
  * @param ref - a consumer ref that wants the same element, or `undefined`.
  * @param label - its accessible name, applied only while it actually scrolls.
+ * @param axis - the dimension to measure overflow on (`horizontal` by default;
+ *   `vertical` for a bounded, capped-height box that scrolls down).
  */
 export function useOverflowRegion(
   ref: Ref<HTMLElement> | undefined,
   label: string,
+  axis: OverflowAxis = 'horizontal',
 ): OverflowRegionAttributes {
   const [scrollable, setScrollable] = useState(false);
 
@@ -132,7 +144,7 @@ export function useOverflowRegion(
       const detachConsumer = attachRef(ref, box);
 
       const measure = (): void => {
-        setScrollable(needsRegion(box));
+        setScrollable(needsRegion(box, axis));
       };
 
       // The box gives resize; its children give the overflowing width. The
@@ -177,7 +189,7 @@ export function useOverflowRegion(
         detachConsumer();
       };
     },
-    [ref],
+    [ref, axis],
   );
 
   if (!scrollable) return { ref: measuredRef };
@@ -189,10 +201,11 @@ export function ScrollRegion({
   children,
   className,
   style,
+  axis,
   'data-testid': testId,
   ref,
 }: ScrollRegionProps) {
-  const region = useOverflowRegion(ref, label);
+  const region = useOverflowRegion(ref, label, axis);
 
   return (
     <div

package/src/components/subject-section.tsx

@@ -0,0 +1,177 @@
+/**
+ * The optional-subject sub-form shared by every form that keys a run's state to a
+ * conversation subject (the add-schedule dialog and the tool run panel). A collapsible
+ * block whose target / kind / key fields render only while expanded, so a form's default
+ * (collapsed) shape sends no subject.
+ *
+ * Presentational and prop-driven, like {@link ExecutionKeyPicker}: the host feature owns
+ * the conversation-targets query (the SDK holds no data-fetching library) and hands the
+ * resolved `targetOptions` in. {@link useSubjectFields} owns the field state; the host
+ * feature wraps it with its own targets query under its own query-key namespace. The
+ * caption and the two placeholders are the only copy that differs between hosts, so they
+ * are props.
+ */
+import type { StateSubject } from '@tai42/api-client';
+import { type ReactNode, useState } from 'react';
+
+import { Field } from './field';
+import { TextInput } from './inputs';
+import { Select } from './select';
+
+/** One conversation-target option: `target_kind:target_name` value, `kind · name` label. */
+export interface SubjectTargetOption {
+  readonly value: string;
+  readonly label: string;
+}
+
+/** The message a partially-filled subject is refused with (all three fields or none). */
+export const SUBJECT_INCOMPLETE_MESSAGE = 'A subject needs a target, a kind, and a key.';
+
+/** Map the conversation routes read to the target select's options. */
+export function toSubjectTargetOptions(
+  routes: readonly { readonly target_kind: string; readonly target_name: string }[],
+): SubjectTargetOption[] {
+  return routes.map((route) => ({
+    value: `${route.target_kind}:${route.target_name}`,
+    label: `${route.target_kind} · ${route.target_name}`,
+  }));
+}
+
+/**
+ * Build a {@link StateSubject} from the sub-form values: `null` when untouched (no
+ * subject), a subject when target, kind and key are all set, or a loud failure when only
+ * some are — never a silently dropped partial subject. The target splits on its FIRST
+ * colon, so a target name may itself contain one.
+ */
+export function buildSubject(v: {
+  readonly target: string;
+  readonly kind: string;
+  readonly key: string;
+}): { ok: true; subject: StateSubject | null } | { ok: false; message: string } {
+  const touched = v.target !== '' || v.kind.trim() !== '' || v.key.trim() !== '';
+  if (!touched) return { ok: true, subject: null };
+  const separator = v.target.indexOf(':');
+  const targetKind = separator < 0 ? '' : v.target.slice(0, separator);
+  const targetName = separator < 0 ? '' : v.target.slice(separator + 1);
+  if (targetKind === '' || targetName === '' || v.kind.trim() === '' || v.key.trim() === '') {
+    return { ok: false, message: SUBJECT_INCOMPLETE_MESSAGE };
+  }
+  // The target is chosen from the conversation-routes options, so its kind is one of the
+  // route target kinds; the value carries it as text and this narrows it to the subject's
+  // union without a runtime schema (the SDK holds no api-client value import).
+  return {
+    ok: true,
+    subject: {
+      target_kind: targetKind as StateSubject['target_kind'],
+      target_name: targetName,
+      kind: v.kind.trim(),
+      key: v.key.trim(),
+    },
+  };
+}
+
+/** Subject field state + setters + the collapse toggle. The host feature owns the
+ *  open-gated conversation-targets query and derives `targetOptions` from it. */
+export function useSubjectFields() {
+  const [target, setTarget] = useState('');
+  const [kind, setKind] = useState('');
+  const [key, setKey] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const [open, setOpen] = useState(false);
+  return { target, setTarget, kind, setKind, key, setKey, error, setError, open, setOpen };
+}
+
+export interface SubjectSectionProps {
+  readonly open: boolean;
+  readonly onToggle: () => void;
+  readonly target: string;
+  readonly onTargetChange: (value: string) => void;
+  readonly kind: string;
+  readonly onKindChange: (value: string) => void;
+  readonly subjectKey: string;
+  readonly onKeyChange: (value: string) => void;
+  readonly error: string | null;
+  readonly targetOptions: readonly SubjectTargetOption[];
+  /** The block's descriptive caption, shown under the expanded header. */
+  readonly caption: string;
+  /** The target select's empty-choice placeholder. */
+  readonly targetPlaceholder: string;
+  /** The Subject key field's helper description. */
+  readonly subjectKeyDescription: string;
+}
+
+export function SubjectSection({
+  open,
+  onToggle,
+  target,
+  onTargetChange,
+  kind,
+  onKindChange,
+  subjectKey,
+  onKeyChange,
+  error,
+  targetOptions,
+  caption,
+  targetPlaceholder,
+  subjectKeyDescription,
+}: SubjectSectionProps): ReactNode {
+  return (
+    <div>
+      <button
+        type="button"
+        className="tai-btn tai-btn-ghost"
+        aria-expanded={open}
+        onClick={onToggle}
+      >
+        Subject (optional)
+      </button>
+      {open ? (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 'var(--tai-space-3)',
+            marginTop: 'var(--tai-space-3)',
+          }}
+        >
+          <p style={{ margin: 0, color: 'var(--tai-color-text-muted)' }}>{caption}</p>
+          <Field label="Target">
+            <Select
+              value={target}
+              onValueChange={onTargetChange}
+              aria-label="Subject target"
+              placeholder={targetPlaceholder}
+              options={targetOptions}
+            />
+          </Field>
+          <Field
+            label="Subject kind"
+            description="The subject family the state declares (e.g. person)."
+          >
+            <TextInput
+              value={kind}
+              placeholder="e.g. person"
+              onChange={(event) => {
+                onKindChange(event.target.value);
+              }}
+            />
+          </Field>
+          <Field label="Subject key" description={subjectKeyDescription}>
+            <TextInput
+              value={subjectKey}
+              placeholder="e.g. a-42"
+              onChange={(event) => {
+                onKeyChange(event.target.value);
+              }}
+            />
+          </Field>
+          {error !== null ? (
+            <p role="alert" style={{ margin: 0, color: 'var(--tai-color-err-text)' }}>
+              {error}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/tool-picker.tsx

@@ -38,6 +38,11 @@ import { ALL_TAGS, SelectedToolBadges, TagFilterField, ToolSelect } from './tool
 
 export { BADGES_NOTE } from './tool-picker-parts';
 
+/** The trigger copy when the picker has no option to offer at all (after exclusions).
+ *  Shown only once the list has settled — a still-loading picker keeps its own
+ *  placeholder — so it never misreads a pending fetch as "nothing to pick". */
+const NO_TOOLS_AVAILABLE = 'No tools available';
+
 export interface ToolPickerProps {
   readonly toolNames: readonly string[];
   readonly value: string | null;
@@ -94,6 +99,13 @@ export function ToolPicker({
   const excluded = new Set(excludeNames ?? []);
   const available = toolNames.filter((name) => !excluded.has(name));
 
+  // A settled, empty option set (not a load in progress) is a "nothing to pick"
+  // state: the trigger reads the empty copy and cannot open onto an empty popup. The
+  // caller's `disabled` still marks a loading picker, which keeps its own placeholder.
+  const noneAvailable = available.length === 0;
+  const pickerDisabled = disabled === true || noneAvailable;
+  const pickerPlaceholder = noneAvailable && disabled !== true ? NO_TOOLS_AVAILABLE : placeholder;
+
   // Distinct tags across the available tools, sorted, feeding the filter control.
   const allTags =
     tagsByTool === undefined
@@ -113,9 +125,9 @@ export function ToolPicker({
       filtered={filtered}
       value={value}
       onChange={onChange}
-      placeholder={placeholder}
+      placeholder={pickerPlaceholder}
       ariaLabel={ariaLabel}
-      disabled={disabled}
+      disabled={pickerDisabled}
       displayNames={displayNames}
       agentToolNames={agentToolNames}
     />