@tai42/studio-sdk 0.2.0

package/src/schema-editor/lint.ts

@@ -0,0 +1,70 @@
+/**
+ * The pure parse + structural lint behind the `SchemaEditor` module. It never throws:
+ * a malformed value IS the result it reports. Full meta-schema validation stays
+ * server-side (the backend 400s carry the detail); this is the fast, loud client
+ * guard that keeps an obviously-broken schema from ever leaving the dialog.
+ */
+
+/** The parse/lint outcome for one editor text buffer. */
+export interface SchemaLintResult {
+  /**
+   * The parsed schema dict when the text is a syntactically valid JSON object, or
+   * `null` when the text is empty or does not parse. Carries the parsed object even
+   * when a lint (e.g. a missing `title`) fails, so the preview can still show the
+   * authored shape — the consumer gates on {@link valid}, never on this alone.
+   */
+  readonly schema: Record<string, unknown> | null;
+  /**
+   * True when the text is empty or a valid schema. False when the text is non-empty
+   * but fails to parse or fails a structural lint — the consumer blocks submit.
+   */
+  readonly valid: boolean;
+  /** A loud, human-readable message when {@link valid} is false; else `undefined`. */
+  readonly error: string | undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parse and structurally lint a JSON-Schema editor buffer.
+ *
+ *  - Empty text is VALID (an unset, optional schema) with a `null` schema.
+ *  - Malformed JSON is INVALID; the parser message is surfaced verbatim.
+ *  - A top-level value that is not a JSON object (an array or a scalar) is INVALID.
+ *  - When `requireTitle`, a top-level string `"title"` is REQUIRED (the
+ *    `response_format` contract the backend enforces); its absence is INVALID.
+ *
+ * The parsed object is returned untouched — no key is normalized, reordered, or
+ * dropped — so a schema carrying `$defs`/`anyOf` round-trips exactly.
+ */
+export function lintSchemaText(text: string, requireTitle: boolean): SchemaLintResult {
+  const trimmed = text.trim();
+  if (trimmed === '') return { schema: null, valid: true, error: undefined };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (error) {
+    return {
+      schema: null,
+      valid: false,
+      error: error instanceof Error ? error.message : 'Invalid JSON.',
+    };
+  }
+
+  if (!isPlainObject(parsed)) {
+    return { schema: null, valid: false, error: 'The schema must be a JSON object.' };
+  }
+
+  if (requireTitle && typeof parsed.title !== 'string') {
+    return {
+      schema: parsed,
+      valid: false,
+      error: 'A top-level "title" string is required for this schema.',
+    };
+  }
+
+  return { schema: parsed, valid: true, error: undefined };
+}

package/src/schema-form/SchemaForm.tsx

@@ -0,0 +1,107 @@
+/**
+ * `SchemaForm` — the controlled, JSON-Schema-driven auto-form. Given a schema
+ * (as Pydantic v2 emits) plus a value and `onChange`, it renders the form and
+ * emits a plain JS value; the CALLER owns the submit button. It is the
+ * load-bearing renderer reused by the tools run panel and the interactions form
+ * answer format, which is why it lives in the SDK (features cannot import each
+ * other).
+ *
+ * SAFETY: every schema-derived string (title, description, enum label, notice)
+ * is rendered as TEXT through the DS components — React escapes it. No markdown,
+ * no HTML, no `dangerouslySetInnerHTML` sink ever touches a schema-supplied
+ * string. Pinned by a test.
+ *
+ * MEDIA UPLOADS: a string field renders as a file-upload / drag-drop control
+ * (instead of a text box) when its schema carries media annotations, so an
+ * image/file input stays a JSON-serializable string that round-trips through the
+ * normal submit path. The annotation contract:
+ *   - `contentEncoding: "base64"` + `contentMediaType` (e.g. `"image/*"`,
+ *     `"application/pdf"`) → the emitted value is the raw base64 body (no
+ *     `data:` prefix); `contentMediaType` also constrains the accepted MIME.
+ *   - `format: "data-url"` (optionally with `contentMediaType`) → the emitted
+ *     value is a full `data:<mime>;base64,<body>` URL.
+ *   - `contentMaxBytes` pins a per-field size cap (bytes); otherwise the
+ *     {@link SchemaFormProps.maxUploadBytes} prop, else {@link DEFAULT_MAX_UPLOAD_BYTES}.
+ * An over-cap value or a MIME that does not match `contentMediaType` is REJECTED
+ * with a visible error — never silently truncated or accepted. The cap holds on
+ * EVERY input path (file picker, the paste fallback, and `validateAgainstSchema`),
+ * measured against the value's DECODED byte size. A text fallback (paste a
+ * URL/base64) stays available. The uploaded filename renders ESCAPED.
+ *
+ * `contentMaxBytes` is a NONSTANDARD JSON-Schema extension keyword (a standard
+ * validator ignores it); these client-side caps are UX guards, and the SERVER
+ * MUST independently validate the decoded size. The base64 decoding and cap
+ * checks live in the sibling `media` module.
+ */
+import type { ReactNode } from 'react';
+
+import { CompletionProviderContext, MaxUploadBytesContext } from './context';
+import { FieldNode } from './field-node';
+import { DEFAULT_MAX_UPLOAD_BYTES } from './media';
+import { stackClass } from './styles';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+// -- Public API --------------------------------------------------------------
+
+/**
+ * Fetch argument-value suggestions for a string field. `argName` is the field's
+ * path within the form (a property key at the root, a dotted path when nested);
+ * `partial` is the value typed so far. The caller owns the source (e.g. an MCP
+ * `completion/complete` call) — SchemaForm only routes string fields through the
+ * completion-backed input when a provider is supplied.
+ */
+export type CompletionProvider = (argName: string, partial: string) => Promise<string[]>;
+
+export interface SchemaFormProps {
+  readonly schema: JsonSchema;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly errors?: SchemaFormErrors;
+  readonly idPrefix?: string;
+  /**
+   * Optional. When supplied, every string field renders through the
+   * completion-backed input (argument autocomplete); when omitted, string fields
+   * render as a plain text input — the default, unchanged behaviour.
+   */
+  readonly completionProvider?: CompletionProvider;
+  /**
+   * Optional. Default byte cap for media-upload fields (see the module
+   * doc-comment). A field's own `contentMaxBytes` annotation overrides it;
+   * absent both, {@link DEFAULT_MAX_UPLOAD_BYTES} applies.
+   */
+  readonly maxUploadBytes?: number;
+}
+
+/**
+ * Render a controlled form for `schema`. The root is usually an object (a tool's
+ * input schema); a scalar/array/union root renders as a single field group.
+ */
+export function SchemaForm({
+  schema,
+  value,
+  onChange,
+  errors,
+  idPrefix = 'schema-form',
+  completionProvider,
+  maxUploadBytes = DEFAULT_MAX_UPLOAD_BYTES,
+}: SchemaFormProps): ReactNode {
+  return (
+    <CompletionProviderContext.Provider value={completionProvider}>
+      <MaxUploadBytesContext.Provider value={maxUploadBytes}>
+        <div className={stackClass} data-testid={idPrefix}>
+          <FieldNode
+            schema={schema}
+            root={schema}
+            value={value}
+            onChange={onChange}
+            path=""
+            label={undefined}
+            required
+            errors={errors}
+            idPrefix={idPrefix}
+          />
+        </div>
+      </MaxUploadBytesContext.Provider>
+    </CompletionProviderContext.Provider>
+  );
+}

package/src/schema-form/array-field.tsx

@@ -0,0 +1,110 @@
+/**
+ * The array field renderer. Each item is a nested {@link FieldNode}; edits map
+ * the list to a new array (add appends a seeded item, remove filters by index).
+ * The whole list re-renders as one controlled value, so index keys are correct.
+ */
+import type { ReactNode } from 'react';
+
+import { CloseIcon } from '../components/icons';
+import { Button } from '../components/primitives';
+import { classifySchema } from './classify';
+import { defaultValueForSchema } from './default-value';
+import { FieldGroup } from './field-group';
+import { FieldNode } from './field-node';
+import type { JsonSchema, SchemaFormErrors } from './types';
+
+export function ArrayField({
+  heading,
+  description,
+  error,
+  items,
+  root,
+  value,
+  onChange,
+  path,
+  errors,
+  idPrefix,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  items: JsonSchema;
+  root: JsonSchema;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  path: string;
+  errors: SchemaFormErrors | undefined;
+  idPrefix: string;
+}): ReactNode {
+  const list = Array.isArray(value) ? (value as unknown[]) : [];
+  const addItem = (): void => {
+    onChange([...list, newItemValue(items, root)]);
+  };
+  const removeItem = (index: number): void => {
+    onChange(list.filter((_, position) => position !== index));
+  };
+  const setItem = (index: number, next: unknown): void => {
+    onChange(list.map((item, position) => (position === index ? next : item)));
+  };
+
+  return (
+    <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
+      {list.length === 0 ? <span className="tai-field-hint">No items</span> : null}
+      {list.map((item, index) => (
+        <div
+          // Index keys are correct here: items have no stable identity and the
+          // whole list re-renders as one controlled value on every edit.
+          key={index}
+          className="tai-row"
+        >
+          {/* The item takes the row's spare width; the Remove button keeps its own. */}
+          <div style={{ flex: 1 }}>
+            <FieldNode
+              schema={items}
+              root={root}
+              value={item}
+              onChange={(next) => {
+                setItem(index, next);
+              }}
+              path={`${path}[${String(index)}]`}
+              label={`Item ${String(index + 1)}`}
+              required
+              errors={errors}
+              idPrefix={idPrefix}
+            />
+          </div>
+          <Button
+            type="button"
+            variant="secondary"
+            aria-label={`Remove item ${String(index + 1)}`}
+            onClick={() => {
+              removeItem(index);
+            }}
+          >
+            <CloseIcon />
+            Remove
+          </Button>
+        </div>
+      ))}
+      <div>
+        <Button type="button" variant="secondary" onClick={addItem}>
+          Add item
+        </Button>
+      </div>
+    </FieldGroup>
+  );
+}
+
+function newItemValue(schema: JsonSchema, root: JsonSchema): unknown {
+  const seeded = defaultValueForSchema(schema, root);
+  if (seeded !== undefined) return seeded;
+  const classified = classifySchema(schema, root);
+  switch (classified.model.kind) {
+    case 'string':
+      return '';
+    case 'boolean':
+      return false;
+    default:
+      return undefined;
+  }
+}

package/src/schema-form/classify.ts

@@ -0,0 +1,302 @@
+/**
+ * The single source of truth for "what kind of field is this schema?". Both the
+ * renderer and the validator classify through here so a construct is treated
+ * identically everywhere. Classification resolves `$ref`, normalizes `anyOf`/
+ * `oneOf` (null-union → nullable single field; multi-member → variant selector),
+ * and lands every unrecognized construct on the explicit `unsupported` kind —
+ * a field is never silently dropped.
+ */
+import {
+  isNullSchema,
+  resolveRef,
+  scalarLabel,
+  typeList,
+  unionMembers,
+  variantLabel,
+  variantTag,
+  type EnumOption,
+} from './resolve';
+import type { JsonSchema } from './types';
+
+/**
+ * How a string field accepts binary content as a JSON-serializable string.
+ * Derived from a field's JSON-Schema media annotations (see the `SchemaForm` module).
+ */
+export interface MediaUpload {
+  /**
+   * `base64` — the emitted value is the raw base64 body (no `data:` prefix),
+   * matching `contentEncoding: "base64"`. `data-url` — the emitted value is a
+   * full `data:<mime>;base64,<body>` URL, matching `format: "data-url"`.
+   */
+  readonly encoding: 'base64' | 'data-url';
+  /**
+   * The `contentMediaType` constraint (e.g. `image/*`, `application/pdf`), used
+   * for MIME validation and the file picker's `accept`. `undefined` for a bare
+   * `format: "data-url"` field with no declared type.
+   */
+  readonly mediaType: string | undefined;
+  /** A per-field byte cap from `contentMaxBytes`, if the schema pins one. */
+  readonly maxBytes: number | undefined;
+}
+
+/** One selectable variant of a union field. */
+export interface UnionVariant {
+  readonly label: string;
+  /** The discriminator tag value, or `undefined` for a non-discriminated union. */
+  readonly tag: unknown;
+  /** The variant schema as written (unresolved — the renderer resolves it). */
+  readonly schema: JsonSchema;
+}
+
+/** The renderer-facing classification of a schema node. */
+export type FieldModel =
+  | { readonly kind: 'const'; readonly value: unknown }
+  | { readonly kind: 'enum'; readonly options: readonly EnumOption[] }
+  | {
+      readonly kind: 'string';
+      readonly format: string | undefined;
+      /** Present when media annotations opt the field into the upload control. */
+      readonly media: MediaUpload | undefined;
+    }
+  | { readonly kind: 'number'; readonly integer: boolean }
+  | { readonly kind: 'boolean' }
+  | { readonly kind: 'array'; readonly items: JsonSchema }
+  | {
+      readonly kind: 'object';
+      readonly properties: readonly (readonly [string, JsonSchema])[];
+      readonly required: ReadonlySet<string>;
+    }
+  | {
+      readonly kind: 'union';
+      readonly variants: readonly UnionVariant[];
+      readonly discriminator: string | undefined;
+    }
+  | { readonly kind: 'unsupported'; readonly reason: string };
+
+/** A fully classified field: its model plus resolved metadata. */
+export interface ClassifiedField {
+  readonly model: FieldModel;
+  /** True when JSON `null` is an accepted value (a null-union member). */
+  readonly nullable: boolean;
+  /** The effective (ref-resolved) schema this classification describes. */
+  readonly schema: JsonSchema;
+  readonly title: string | undefined;
+  readonly description: string | undefined;
+}
+
+function firstString(...values: readonly unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Detect the media-upload annotations on a (ref-resolved) string schema. A field
+ * opts into the upload control when it carries `contentEncoding: "base64"` plus a
+ * `contentMediaType`, OR `format: "data-url"`. Anything else is a plain string.
+ */
+function mediaUpload(schema: JsonSchema): MediaUpload | undefined {
+  const mediaType =
+    typeof schema.contentMediaType === 'string' ? schema.contentMediaType : undefined;
+  const maxBytes =
+    typeof schema.contentMaxBytes === 'number' && schema.contentMaxBytes > 0
+      ? schema.contentMaxBytes
+      : undefined;
+  if (schema.format === 'data-url') {
+    return { encoding: 'data-url', mediaType, maxBytes };
+  }
+  if (schema.contentEncoding === 'base64' && mediaType !== undefined) {
+    return { encoding: 'base64', mediaType, maxBytes };
+  }
+  return undefined;
+}
+
+function unsupported(
+  schema: JsonSchema,
+  reason: string,
+  title: string | undefined,
+  description: string | undefined,
+): ClassifiedField {
+  return { model: { kind: 'unsupported', reason }, nullable: false, schema, title, description };
+}
+
+/**
+ * Classify a schema node (resolving `$ref` first). `wrapper` metadata (a
+ * ref-site title/description) is threaded down so a `{ $ref, title }` or a
+ * null-union wrapper keeps its property-level label.
+ */
+export function classifySchema(raw: JsonSchema, root: JsonSchema): ClassifiedField {
+  const resolved = resolveRef(raw, root);
+  const title = firstString(raw.title, resolved.title);
+  const description = firstString(raw.description, resolved.description);
+
+  // const pins a single value.
+  if ('const' in resolved) {
+    return {
+      model: { kind: 'const', value: resolved.const },
+      nullable: false,
+      schema: resolved,
+      title,
+      description,
+    };
+  }
+
+  // enum → a fixed choice list.
+  if (resolved.enum !== undefined) {
+    const options: EnumOption[] = resolved.enum.map((value) => ({
+      value,
+      label: scalarLabel(value),
+    }));
+    const nullable = resolved.enum.some((value) => value === null);
+    return { model: { kind: 'enum', options }, nullable, schema: resolved, title, description };
+  }
+
+  // anyOf/oneOf union normalization.
+  const members = unionMembers(resolved);
+  if (members !== undefined) {
+    const nonNull = members.filter((member) => !isNullSchema(resolveRef(member, root)));
+    const nullable = nonNull.length !== members.length;
+    const soleNonNull = nonNull[0];
+    if (soleNonNull === undefined) {
+      return unsupported(resolved, 'union with no non-null members', title, description);
+    }
+    if (nonNull.length === 1) {
+      const inner = classifySchema(soleNonNull, root);
+      // Media annotations (`contentEncoding`/`contentMediaType`/`format: data-url`)
+      // that land on the OUTER null-union wrapper of an OPTIONAL field would
+      // otherwise be lost when delegating to the inner string member, silently
+      // degrading an optional upload field to a plain text box. Re-detect them on
+      // the wrapper and attach to the inner string model.
+      const model =
+        inner.model.kind === 'string' && inner.model.media === undefined
+          ? { ...inner.model, media: mediaUpload(resolved) }
+          : inner.model;
+      return {
+        model,
+        nullable: nullable || inner.nullable,
+        schema: inner.schema,
+        title: title ?? inner.title,
+        description: description ?? inner.description,
+      };
+    }
+    const discriminator = resolved.discriminator?.propertyName;
+    const variants: UnionVariant[] = nonNull.map((member, index) => {
+      const tag = discriminator === undefined ? undefined : variantTag(member, discriminator, root);
+      return { label: variantLabel(member, index, tag, root), tag, schema: member };
+    });
+    return {
+      model: { kind: 'union', variants, discriminator },
+      nullable,
+      schema: resolved,
+      title,
+      description,
+    };
+  }
+
+  // allOf: Pydantic wraps a single $ref this way; a multi-member intersection is
+  // not a form-renderable construct.
+  if (resolved.allOf !== undefined) {
+    const soleAllOf = resolved.allOf[0];
+    if (resolved.allOf.length === 1 && soleAllOf !== undefined) {
+      const inner = classifySchema(soleAllOf, root);
+      return {
+        model: inner.model,
+        nullable: inner.nullable,
+        schema: inner.schema,
+        title: title ?? inner.title,
+        description: description ?? inner.description,
+      };
+    }
+    return unsupported(resolved, 'allOf intersection of multiple schemas', title, description);
+  }
+
+  // Type-driven classification.
+  const types = typeList(resolved);
+  const nonNullTypes = types.filter((type) => type !== 'null');
+  const nullableByType = nonNullTypes.length !== types.length;
+
+  if (nonNullTypes.length === 0) {
+    return unsupported(resolved, 'schema declares no renderable type', title, description);
+  }
+  if (nonNullTypes.length > 1) {
+    return unsupported(
+      resolved,
+      `multiple JSON types (${nonNullTypes.join(', ')}) without a discriminator`,
+      title,
+      description,
+    );
+  }
+
+  const type = nonNullTypes[0];
+  if (type === undefined) {
+    return unsupported(resolved, 'schema declares no renderable type', title, description);
+  }
+  switch (type) {
+    case 'string':
+      return {
+        model: { kind: 'string', format: resolved.format, media: mediaUpload(resolved) },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    case 'number':
+      return {
+        model: { kind: 'number', integer: false },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    case 'integer':
+      return {
+        model: { kind: 'number', integer: true },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    case 'boolean':
+      return {
+        model: { kind: 'boolean' },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    case 'array': {
+      if (resolved.items === undefined) {
+        return unsupported(resolved, 'array without an items schema', title, description);
+      }
+      return {
+        model: { kind: 'array', items: resolved.items },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    }
+    case 'object': {
+      if (resolved.properties === undefined) {
+        return unsupported(
+          resolved,
+          'free-form object (additionalProperties map) is not supported',
+          title,
+          description,
+        );
+      }
+      const properties: (readonly [string, JsonSchema])[] = Object.entries(resolved.properties);
+      const required = new Set(resolved.required ?? []);
+      return {
+        model: { kind: 'object', properties, required },
+        nullable: nullableByType,
+        schema: resolved,
+        title,
+        description,
+      };
+    }
+    default:
+      return unsupported(resolved, `unrecognized type "${String(type)}"`, title, description);
+  }
+}

package/src/schema-form/context.ts

@@ -0,0 +1,17 @@
+/**
+ * Ambient React contexts for the schema-form tree: the optional argument
+ * completion provider and the default media-upload byte cap. A field deep in the
+ * tree reads these here rather than every intermediate node drilling the prop.
+ */
+import { createContext } from 'react';
+
+import { DEFAULT_MAX_UPLOAD_BYTES } from './media';
+import type { CompletionProvider } from './SchemaForm';
+
+// Ambient completion provider for the whole form. A string field deep in the
+// tree reads it here rather than every intermediate node drilling the prop.
+export const CompletionProviderContext = createContext<CompletionProvider | undefined>(undefined);
+
+// Ambient default upload cap for the whole form; a media field reads it here so
+// intermediate object/array nodes never drill the prop.
+export const MaxUploadBytesContext = createContext<number>(DEFAULT_MAX_UPLOAD_BYTES);

package/src/schema-form/default-value.ts

@@ -0,0 +1,65 @@
+/**
+ * `defaultValueForSchema` — the initial form value for a schema, honoring
+ * `default`/`const` and seeding required nested structure.
+ *
+ * Inclusion rules keep the seed honest:
+ *  - a REQUIRED property is seeded (objects → a nested seed, arrays → `[]`); a
+ *    required scalar with no default is left ABSENT so validation flags it
+ *    rather than inventing a value;
+ *  - an OPTIONAL property is included only when it carries an explicit
+ *    `default` — an optional object/array is NOT auto-materialized, so its own
+ *    required children can't raise spurious errors on a field the user never
+ *    opted into.
+ */
+import { classifySchema } from './classify';
+import type { JsonSchema } from './types';
+
+/** The explicit `default` (wrapper takes precedence over the resolved node), if any. */
+function explicitDefault(
+  raw: JsonSchema,
+  resolved: JsonSchema,
+): { present: boolean; value: unknown } {
+  if ('default' in raw) return { present: true, value: raw.default };
+  if ('default' in resolved) return { present: true, value: resolved.default };
+  return { present: false, value: undefined };
+}
+
+/**
+ * The initial value for a schema. `root` carries the `$defs` document for
+ * `$ref` resolution and defaults to the schema itself (the common
+ * whole-tool-schema call).
+ */
+export function defaultValueForSchema(schema: JsonSchema, root: JsonSchema = schema): unknown {
+  const classified = classifySchema(schema, root);
+  const explicit = explicitDefault(schema, classified.schema);
+  if (explicit.present) return explicit.value;
+
+  const { model } = classified;
+  switch (model.kind) {
+    case 'const':
+      return model.value;
+    case 'object': {
+      const result: Record<string, unknown> = {};
+      for (const [name, propSchema] of model.properties) {
+        if (model.required.has(name)) {
+          const seeded = defaultValueForSchema(propSchema, root);
+          if (seeded !== undefined) result[name] = seeded;
+          continue;
+        }
+        const propClassified = classifySchema(propSchema, root);
+        const propDefault = explicitDefault(propSchema, propClassified.schema);
+        if (propDefault.present) result[name] = propDefault.value;
+      }
+      return result;
+    }
+    case 'array':
+      return [];
+    case 'enum':
+    case 'string':
+    case 'number':
+    case 'boolean':
+    case 'union':
+    case 'unsupported':
+      return undefined;
+  }
+}