@tai42/studio-sdk 25.0.1 → 26.0.0

package/src/components/extension-config-editor.tsx

@@ -0,0 +1,307 @@
+/**
+ * `ExtensionConfigEditor` — the settings form of one drafted extension, driven by
+ * the extension's declared `config_schema`.
+ *
+ * The schema's top-level properties split in two: a property whose node `$ref`s the
+ * JSON Schema meta-schema holds a JSON Schema and is authored with a `SchemaEditor`;
+ * every other property is authored by one `SchemaForm`. A top-level setting whose
+ * seeded value holds an `!ENV` marker is sealed: it renders as a read-only row naming
+ * the variables, is emitted exactly as seeded, and counts as valid (the server checks
+ * the resolved value). A schema this editor cannot render — a meta-schema `$ref` below
+ * the top level, or a `$ref` outside the document — shows an error and reports invalid.
+ *
+ * It reports `{ config, valid }` through `onChange` on mount and on every edit.
+ */
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+
+import { collectEnvRefs } from '../env-markers';
+import { SchemaEditor, type SchemaEditorChange } from '../schema-editor';
+import { defaultValueForSchema } from '../schema-form/default-value';
+import { JSON_SCHEMA_META_URI } from '../schema-form/json-schema-meta';
+import { SchemaForm } from '../schema-form/SchemaForm';
+import type { JsonSchema } from '../schema-form/types';
+import { validateAgainstSchema } from '../schema-form/validate';
+import { ErrorState } from './primitives';
+
+export interface ExtensionConfigChange {
+  readonly config: Record<string, unknown>;
+  readonly valid: boolean;
+}
+
+export interface ExtensionConfigEditorProps {
+  /** The extension's name; it names the settings group. */
+  readonly name: string;
+  /** The extension's declared `config_schema`. */
+  readonly schema: JsonSchema;
+  /** The element's stored settings when editing, else `undefined`. Read once, on mount. */
+  readonly value: Record<string, unknown> | undefined;
+  readonly onChange: (next: ExtensionConfigChange) => void;
+  readonly disabled?: boolean;
+  readonly idPrefix: string;
+}
+
+type SchemaSettings = Readonly<Record<string, SchemaEditorChange>>;
+
+const isMetaRef = (node: JsonSchema): boolean => node.$ref === JSON_SCHEMA_META_URI;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The sub-schemas of a node, each with its path. */
+function childNodes(node: JsonSchema, path: string): [JsonSchema, string][] {
+  const children: [JsonSchema, string][] = [];
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    children.push([child, `${path}.${key}`]);
+  }
+  if (node.items !== undefined) children.push([node.items, `${path}[]`]);
+  if (isRecord(node.additionalProperties)) {
+    children.push([node.additionalProperties, `${path}.*`]);
+  }
+  for (const keyword of ['anyOf', 'oneOf', 'allOf'] as const) {
+    (node[keyword] ?? []).forEach((child, index) => {
+      children.push([child, `${path}.${keyword}[${String(index)}]`]);
+    });
+  }
+  for (const keyword of ['$defs', 'definitions'] as const) {
+    for (const [key, child] of Object.entries(node[keyword] ?? {})) {
+      children.push([child, `${path}.${keyword}.${key}`]);
+    }
+  }
+  return children;
+}
+
+/** Why a (non top-level-setting) node cannot be rendered here, or `null`. */
+function nestedReason(node: JsonSchema, path: string): string | null {
+  if (isMetaRef(node)) return `a JSON Schema setting is nested at ${path}`;
+  if (node.$ref !== undefined && !node.$ref.startsWith('#')) {
+    return `the reference ${node.$ref} at ${path} is outside this schema`;
+  }
+  for (const [child, childPath] of childNodes(node, path)) {
+    const reason = nestedReason(child, childPath);
+    if (reason !== null) return reason;
+  }
+  return null;
+}
+
+/** Why the declared schema cannot be rendered here, or `null` when it can. A
+ *  meta-schema `$ref` is accepted only as a top-level property's own node. */
+function unrenderableReason(schema: JsonSchema): string | null {
+  if (isMetaRef(schema)) return 'the whole settings value is a JSON Schema';
+  if (schema.$ref !== undefined && !schema.$ref.startsWith('#')) {
+    return `the reference ${schema.$ref} at $ is outside this schema`;
+  }
+  const topProperties = schema.properties ?? {};
+  for (const [child, childPath] of childNodes(schema, '$')) {
+    const key = childPath.slice(2);
+    if (topProperties[key] === child && isMetaRef(child)) continue;
+    const reason = nestedReason(child, childPath);
+    if (reason !== null) return reason;
+  }
+  return null;
+}
+
+interface Split {
+  readonly formSchema: JsonSchema;
+  readonly schemaKeys: readonly string[];
+  readonly sealed: Readonly<Record<string, unknown>>;
+}
+
+function splitSchema(schema: JsonSchema, seed: Record<string, unknown> | undefined): Split {
+  const properties = schema.properties ?? {};
+  const sealed: Record<string, unknown> = {};
+  if (seed !== undefined) {
+    for (const key of Object.keys(properties)) {
+      if (key in seed && collectEnvRefs(seed[key]).size > 0) sealed[key] = seed[key];
+    }
+  }
+  const schemaKeys: string[] = [];
+  const rest: Record<string, JsonSchema> = {};
+  for (const [key, node] of Object.entries(properties)) {
+    if (key in sealed) continue;
+    if (isMetaRef(node)) schemaKeys.push(key);
+    else rest[key] = node;
+  }
+  const formSchema: JsonSchema = {
+    ...schema,
+    properties: rest,
+    required: (schema.required ?? []).filter((key) => key in rest),
+  };
+  return { formSchema, schemaKeys, sealed };
+}
+
+function settingLabel(schema: JsonSchema, key: string): string {
+  return schema.properties?.[key]?.title ?? key;
+}
+
+/** The read-only row of a sealed setting: its label and the env variables it names. */
+function SealedRow({ label, value }: { readonly label: string; readonly value: unknown }) {
+  const names = [...collectEnvRefs(value)].join(', ');
+  return (
+    <div className="tai-stack tai-stack-1">
+      <span className="tai-field-label">{label}</span>
+      <span className="tai-muted">{`Env reference ${names}, kept as written.`}</span>
+    </div>
+  );
+}
+
+function SettingsGroup({
+  name,
+  disabled,
+  children,
+}: {
+  readonly name: string;
+  readonly disabled?: boolean | undefined;
+  readonly children: ReactNode;
+}) {
+  return (
+    <fieldset
+      className="tai-stack tai-stack-2"
+      style={{ border: 'none', margin: 0, padding: 0 }}
+      disabled={disabled}
+    >
+      <legend className="tai-field-label">{`${name} settings`}</legend>
+      {children}
+    </fieldset>
+  );
+}
+
+/** Keeps the latest `onChange` so the report effect runs on value changes only. */
+function useLatest<T>(current: T): { readonly current: T } {
+  const ref = useRef(current);
+  useEffect(() => {
+    ref.current = current;
+  });
+  return ref;
+}
+
+export function ExtensionConfigEditor({
+  name,
+  schema,
+  value,
+  onChange,
+  disabled,
+  idPrefix,
+}: ExtensionConfigEditorProps): ReactNode {
+  const [reason] = useState(() => unrenderableReason(schema));
+  if (reason !== null) {
+    return <UnrenderableSettings name={name} reason={reason} value={value} onChange={onChange} />;
+  }
+  return (
+    <RenderableSettings
+      name={name}
+      schema={schema}
+      value={value}
+      onChange={onChange}
+      disabled={disabled}
+      idPrefix={idPrefix}
+    />
+  );
+}
+
+function UnrenderableSettings({
+  name,
+  reason,
+  value,
+  onChange,
+}: {
+  readonly name: string;
+  readonly reason: string;
+  readonly value: Record<string, unknown> | undefined;
+  readonly onChange: (next: ExtensionConfigChange) => void;
+}): ReactNode {
+  const latest = useLatest(onChange);
+  useEffect(() => {
+    latest.current({ config: value ?? {}, valid: false });
+  }, [latest, value]);
+  return (
+    <SettingsGroup name={name}>
+      <ErrorState message={`The settings of ${name} cannot be edited here: ${reason}.`} />
+    </SettingsGroup>
+  );
+}
+
+function RenderableSettings({
+  name,
+  schema,
+  value,
+  onChange,
+  disabled,
+  idPrefix,
+}: ExtensionConfigEditorProps): ReactNode {
+  const [split] = useState(() => splitSchema(schema, value));
+  const { formSchema, schemaKeys, sealed } = split;
+  const [formValue, setFormValue] = useState<unknown>(() => {
+    if (value === undefined) return defaultValueForSchema(formSchema);
+    const seeded: Record<string, unknown> = {};
+    for (const [key, stored] of Object.entries(value)) {
+      if (!schemaKeys.includes(key) && !(key in sealed)) seeded[key] = stored;
+    }
+    return seeded;
+  });
+  const [schemaSettings, setSchemaSettings] = useState<SchemaSettings>(() => {
+    const seeded: Record<string, SchemaEditorChange> = {};
+    for (const key of schemaKeys) {
+      const stored = value?.[key];
+      seeded[key] = { schema: isRecord(stored) ? stored : null, valid: true };
+    }
+    return seeded;
+  });
+
+  const formErrors = validateAgainstSchema(formSchema, formValue);
+  const required = new Set(schema.required ?? []);
+  const valid =
+    Object.keys(formErrors).length === 0 &&
+    schemaKeys.every((key) => {
+      const setting = schemaSettings[key];
+      return (
+        setting !== undefined && setting.valid && (!required.has(key) || setting.schema !== null)
+      );
+    });
+
+  const latest = useLatest(onChange);
+  useEffect(() => {
+    const config: Record<string, unknown> = { ...(isRecord(formValue) ? formValue : {}) };
+    for (const key of schemaKeys) {
+      const setting = schemaSettings[key]?.schema;
+      if (setting !== null && setting !== undefined) config[key] = setting;
+    }
+    Object.assign(config, sealed);
+    latest.current({ config, valid });
+  }, [latest, formValue, schemaSettings, schemaKeys, sealed, valid]);
+
+  const hasFormFields = Object.keys(formSchema.properties ?? {}).length > 0;
+  return (
+    <SettingsGroup name={name} disabled={disabled}>
+      {Object.entries(sealed).map(([key, sealedValue]) => (
+        <SealedRow key={key} label={settingLabel(schema, key)} value={sealedValue} />
+      ))}
+      {hasFormFields ? (
+        <SchemaForm
+          schema={formSchema}
+          value={formValue}
+          onChange={setFormValue}
+          errors={formErrors}
+          idPrefix={`${idPrefix}-form`}
+        />
+      ) : null}
+      {schemaKeys.map((key) => {
+        const node = schema.properties?.[key];
+        return (
+          <SchemaEditor
+            key={key}
+            value={schemaSettings[key]?.schema ?? null}
+            onChange={(change) => {
+              setSchemaSettings((current) => ({ ...current, [key]: change }));
+            }}
+            requireTitle={false}
+            label={settingLabel(schema, key)}
+            description={node?.description}
+            disabled={disabled}
+            idPrefix={`${idPrefix}-${key}`}
+          />
+        );
+      })}
+    </SettingsGroup>
+  );
+}

package/src/components/extension-grouping.ts

@@ -1,30 +1,10 @@
 /**
- * Pure catalog-shaping helpers for the extensions surface — the SHARED grouping
- * source for both the read-only extensions catalog (`features/extensions`) and the
- * `ExtensionPicker`. Kept free of React so the grouping logic is unit-tested
- * directly.
- *
- * The `/api/extensions` catalog is a flat list of `{ name, kind, multiple }` entries. Two
- * independent groupings live here:
- *  - `groupIntoFamilies` groups a tool's composed branch VARIANTS (which share a
- *    base tool name and append underscore suffixes — `tool`, `tool_a`, `tool_a_b`)
- *    back into one FAMILY keyed by that base name (the catalog view);
- *  - `groupByKind` groups the catalog by extension KIND (the picker view), each
- *    group carrying the served `multiple` flag of its kind.
- * `kindVariant` maps each serialized `kind` value to a design-system Badge variant.
+ * Pure catalog-shaping helpers for the extension catalog: `groupByKind` groups the flat
+ * `{ name, kind, multiple }` list by kind, each group carrying its kind's served
+ * `multiple` flag. Kept free of React so it is unit-tested directly.
  */
 import type { Extension } from '@tai42/api-client';
 
-import type { BadgeProps } from './badge';
-
-/** One base tool and every extension entry that branches from it. */
-export interface ExtensionFamily {
-  /** The base tool name (the segment before the first underscore). */
-  readonly base: string;
-  /** The family's entries, ordered by full name. */
-  readonly members: readonly Extension[];
-}
-
 /** One extension `kind` and every catalog entry of that kind. */
 export interface ExtensionKindGroup {
   /** The serialized kind value (`wrapper` / `transformer` / `backend`). */
@@ -37,41 +17,7 @@ export interface ExtensionKindGroup {
 }
 
 /**
- * The base tool name a variant belongs to: the substring before the first
- * underscore, or the whole name when it has none. `tool`, `tool_a`, `tool_a_b`
- * all resolve to `tool`; `x_chain` and `x_batch` both resolve to `x`.
- */
-export function baseNameOf(name: string): string {
-  const separator = name.indexOf('_');
-  return separator === -1 ? name : name.slice(0, separator);
-}
-
-/**
- * Group a flat extension list into families keyed by base tool name. Families
- * are ordered by base name and each family's members by full name, so the render
- * order is stable regardless of the server's list order.
- */
-export function groupIntoFamilies(extensions: readonly Extension[]): ExtensionFamily[] {
-  const byBase = new Map<string, Extension[]>();
-  for (const extension of extensions) {
-    const base = baseNameOf(extension.name);
-    const members = byBase.get(base);
-    if (members) {
-      members.push(extension);
-    } else {
-      byBase.set(base, [extension]);
-    }
-  }
-  return [...byBase.entries()]
-    .map(([base, members]) => ({
-      base,
-      members: [...members].sort((a, b) => a.name.localeCompare(b.name)),
-    }))
-    .sort((a, b) => a.base.localeCompare(b.base));
-}
-
-/**
- * Group a flat extension list by `kind`, for the picker. Groups are ordered by
+ * Group a flat extension list by `kind`. Groups are ordered by
  * kind and each group's members by name, so the render order is stable regardless
  * of the server's list order. Each group carries its kind's served `multiple`; a kind
  * whose entries disagree is a catalog fault and throws.
@@ -99,18 +45,3 @@ export function groupByKind(extensions: readonly Extension[]): ExtensionKindGrou
     }))
     .sort((a, b) => a.kind.localeCompare(b.kind));
 }
-
-/**
- * Map a serialized extension `kind` to a Badge variant. Known skeleton kinds get
- * a themed color; any unrecognized kind falls back to the neutral variant (the
- * Badge itself also neutral-fallbacks, but choosing here keeps the mapping
- * explicit and testable).
- */
-export function kindVariant(kind: string): NonNullable<BadgeProps['variant']> {
-  const known: Record<string, NonNullable<BadgeProps['variant']>> = {
-    wrapper: 'primary',
-    transformer: 'success',
-    backend: 'warning',
-  };
-  return known[kind] ?? 'neutral';
-}

package/src/components/extension-picker.tsx

@@ -6,24 +6,25 @@
  * live in the SDK). It is PRESENTATIONAL: the caller fetches `available` and owns
  * the selected `value`; this component fetches nothing.
  *
- * The catalog is GROUPED by `kind`. A kind the catalog serves as not `multiple` is
+ * The catalog is GROUPED by `kind`: each kind is a group `Field` named
+ * "Kind: <kind>", described "(single-select)" when it is single-select. A kind the catalog serves as not `multiple` is
  * SINGLE-SELECT — checking one of its extensions replaces any other of that kind
  * already in the combo; a `multiple` kind is freely multi-select. Selection order is preserved (the combo is ordered — the
  * stacking order that produces the branch tool name), so a newly-checked extension
  * appends to the end and unchecking removes in place.
  *
  * SAFETY: an extension name AND its kind are server-supplied, so every name/kind
- * renders as TEXT through the DS `Checkbox`/`Badge` (React escapes it) — never an
+ * renders as TEXT through the DS `Checkbox`/`Field` (React escapes it) — never an
  * HTML sink. Pinned by a test.
  *
  * Geometry and ink come from the design-system layout classes (`tai-stack`,
- * `tai-row`, `tai-muted`); the component carries no palette of its own.
+ * `tai-row`) and `Field`; the component carries no palette of its own.
  */
 import type { Extension } from '@tai42/api-client';
 
-import { Badge } from './badge';
 import { Checkbox } from './checkbox';
-import { groupByKind, kindVariant } from './extension-grouping';
+import { groupByKind } from './extension-grouping';
+import { Field } from './field';
 import { EmptyState } from './primitives';
 
 export interface ExtensionPickerProps {
@@ -81,13 +82,12 @@ export function ExtensionPicker({
   return (
     <div data-testid={idPrefix} className="tai-stack">
       {groups.map((group) => (
-        <div key={group.kind} className="tai-stack tai-stack-2">
-          {/* The kind heading is a layout row, not prose: its badge names the kind
-              and the single-select qualifier rides beside it as secondary text. */}
-          <div className="tai-row">
-            <Badge variant={kindVariant(group.kind)}>{group.kind}</Badge>
-            {group.multiple ? null : <span className="tai-muted">(single-select)</span>}
-          </div>
+        <Field
+          key={group.kind}
+          group
+          label={`Kind: ${group.kind}`}
+          description={group.multiple ? undefined : '(single-select)'}
+        >
           <div className="tai-row">
             {group.members.map((extension) => (
               <Checkbox
@@ -101,7 +101,7 @@ export function ExtensionPicker({
               />
             ))}
           </div>
-        </div>
+        </Field>
       ))}
     </div>
   );

package/src/components/fleet-report.tsx

@@ -23,6 +23,11 @@
  * server-supplied string (a worker name, an error/detail message) renders as escaped
  * React text, never an HTML sink.
  *
+ * Whatever the status, a `spanReleaseError` (the config store did not release its exclusive
+ * write span after the persist) renders its own `role="alert"` panel with the store's
+ * error: the change landed, but a later write can block or be refused until the writer
+ * process exits.
+ *
  * Whatever the status, a worker whose reload named recycle-class settings awaiting a
  * respawn is listed in a warning status panel beside it: the reload applied every other
  * change, and those settings take effect only when that worker restarts.
@@ -79,9 +84,9 @@ const OUTCOME_STATUS: Record<FleetFailureOutcome, StatusTone> = {
 };
 
 /**
- * Render a fleet broadcast's failure state and its workers awaiting a respawn. Returns
- * `null` for an absent report or a converged one with no worker awaiting a respawn
- * (nothing to warn about) so callers can always mount it unconditionally beside their
+ * Render a fleet broadcast's failure state, an unreleased write span, and its workers
+ * awaiting a respawn. Returns `null` for an absent report or a converged one with no
+ * unreleased span and no worker awaiting a respawn (nothing to warn about) so callers can always mount it unconditionally beside their
  * own success line.
  */
 export interface FleetReportProps {
@@ -235,6 +240,26 @@ function AwaitingRespawnReport({
   );
 }
 
+/**
+ * The loud panel for a write span the config store did not release: the change landed,
+ * but the store may hold the span until the writer process exits.
+ */
+function SpanReleaseReport({ error }: { readonly error: string }): ReactNode {
+  return (
+    <div role="alert" className="tai-error-state tai-stack tai-stack-2">
+      <strong className="tai-status tai-status-err">
+        <XCircleIcon />
+        The config store did not release its write lock
+      </strong>
+      <p>
+        The change was saved, but the store may hold its write lock until the server process that
+        wrote it exits. Until then another config change can wait or be refused.
+      </p>
+      <p className="tai-code-block tai-code-block-wrap">{error}</p>
+    </div>
+  );
+}
+
 function FailureReport({
   summary,
   action,
@@ -269,10 +294,19 @@ function FailureReport({
 
 export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
   if (summary === null) return null;
-  if (summary.status === 'converged' && summary.awaiting.length === 0) return null;
+  if (
+    summary.status === 'converged' &&
+    summary.awaiting.length === 0 &&
+    summary.spanReleaseError === null
+  ) {
+    return null;
+  }
   return (
     <>
       <FailureReport summary={summary} action={action} />
+      {summary.spanReleaseError !== null ? (
+        <SpanReleaseReport error={summary.spanReleaseError} />
+      ) : null}
       {summary.awaiting.length > 0 ? <AwaitingRespawnReport awaiting={summary.awaiting} /> : null}
     </>
   );

package/src/components/holder-kinds.ts

@@ -0,0 +1,60 @@
+/**
+ * The holder kinds the platform itself reports, and the route each one lands on. A
+ * plugin may register a link only for a kind outside this table.
+ */
+import type { ReferenceHolder } from '@tai42/api-client';
+
+import type { RouteSearchByToken, RouteToken } from '../navigation/types';
+
+/** A route token with its search, typed together. */
+export type CoreHolderRoute = {
+  [T in RouteToken]: { readonly token: T; readonly search: RouteSearchByToken[T] };
+}[RouteToken];
+
+/** A locator field the holder's kind always carries; its absence is a malformed holder. */
+function locatorField<T extends 'string' | 'number'>(
+  holder: ReferenceHolder,
+  key: string,
+  type: T,
+): T extends 'string' ? string : number {
+  const value = holder.locator[key];
+  if (typeof value !== type) {
+    throw new Error(`a “${holder.kind}” holder carries no ${type} locator “${key}”`);
+  }
+  return value as T extends 'string' ? string : number;
+}
+
+const CORE_ROUTES: Readonly<Record<string, (holder: ReferenceHolder) => CoreHolderRoute>> = {
+  preset: (h) => ({ token: 'presets', search: { preset: h.name } }),
+  'preset version': (h) => ({
+    token: 'presets',
+    search: { preset: h.name, version: locatorField(h, 'version', 'number') },
+  }),
+  hook: (h) => ({ token: 'hooks', search: { hook: h.name } }),
+  schedule: (h) => ({ token: 'scheduling', search: { schedule: h.name } }),
+  'conversation route': (h) => ({ token: 'conversations', search: { route: h.name } }),
+  'conversation config': (h) => ({
+    token: 'conversations',
+    search: { config: `${locatorField(h, 'target_kind', 'string')}:${h.name}` },
+  }),
+  'tool extensions': () => ({ token: 'manifest', search: {} }),
+  'parked interactions': () => ({ token: 'interactions', search: {} }),
+  'answered continuations': () => ({ token: 'interactions', search: {} }),
+  'state records': () => ({ token: 'states', search: {} }),
+  'pending save': () => ({ token: 'states', search: {} }),
+  'state declaration': (h) => ({ token: 'states', search: { state: h.name, tab: 'declaration' } }),
+  'state template': (h) => ({ token: 'states', search: { template: h.name } }),
+  'api key': () => ({ token: 'settings', search: {} }),
+  principal: () => ({ token: 'settings', search: {} }),
+  role: () => ({ token: 'settings', search: {} }),
+  setting: () => ({ token: 'settings', search: {} }),
+};
+
+/** Every kind the platform reports; a plugin cannot register a link for one. */
+export const CORE_HOLDER_KINDS: ReadonlySet<string> = new Set(Object.keys(CORE_ROUTES));
+
+/** The route a core holder lands on, or `null` for a kind outside the core table. */
+export function coreHolderRoute(holder: ReferenceHolder): CoreHolderRoute | null {
+  const route = Object.hasOwn(CORE_ROUTES, holder.kind) ? CORE_ROUTES[holder.kind] : undefined;
+  return route === undefined ? null : route(holder);
+}