diff --git a/ui/src/settings/StructuredValueEditor.vue b/ui/src/settings/StructuredValueEditor.vue
index 29c212da7..e8a145b4c 100644
--- a/ui/src/settings/StructuredValueEditor.vue
+++ b/ui/src/settings/StructuredValueEditor.vue
@@ -7,12 +7,26 @@ import { Checkbox } from "@/components/ui/checkbox";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Textarea } from "@/components/ui/textarea";
+import { blankFromSchema, fieldHint, fieldPlaceholder, fieldTitle, schemaAt, type SchemaProperty } from "./resource-schema";
+/**
+ * The document editor, driven by the value it was given and annotated by the
+ * schema the descriptor carries.
+ *
+ * The value decides which fields exist (this walks what is stored, so a
+ * document with a field the schema has not caught up with still edits); the
+ * schema decides what those fields are called, what example a formatted field
+ * shows, what prose qualifies it, and what a newly added row starts as. A
+ * descriptor with no schema, or one describing nothing, renders exactly as it
+ * did before there was a reader.
+ */
const props = withDefaults(defineProps<{
modelValue: unknown;
path?: string;
+ rootPath?: string;
+ schema?: SchemaProperty | null;
locked?: boolean;
-}>(), { path: "value", locked: false });
+}>(), { path: "value", rootPath: "", schema: null, locked: false });
const emit = defineEmits<{ "update:modelValue": [value: unknown] }>();
const isArray = computed(() => Array.isArray(props.modelValue));
@@ -20,6 +34,12 @@ const isObject = computed(() => props.modelValue !== null && typeof props.modelV
const entries = computed(() => Object.entries((props.modelValue ?? {}) as Record
));
const readOnly = computed(() => props.locked || /(^|\.)(has_credential|credential_configured|headers_configured)$/.test(props.path));
+/** The schema node for this editor, and for one of its keys. */
+const property = computed(() => schemaAt(props.schema, props.path, props.rootPath));
+function propertyFor(key: string): SchemaProperty | null {
+ return schemaAt(props.schema, `${props.path}.${key}`, props.rootPath);
+}
+
function label(value: string): string {
return value.replaceAll("_", " ").replace(/^./, (character) => character.toUpperCase());
}
@@ -55,28 +75,13 @@ function setArray(index: number, value: unknown): void {
emit("update:modelValue", current);
}
+// A new row comes from the schema rather than from the path that holds it: the
+// editor used to carry a literal skeleton per array path (a repository, an MCP
+// server), which went stale the moment the document changed and said nothing
+// about fields it did not know.
function addArray(): void {
const current = props.modelValue as unknown[];
- const sample = current[0];
- let value: unknown = Array.isArray(sample) ? [] : sample && typeof sample === "object" ? {} : "";
- if (props.path === "repositories") value = {
- owner: "", name: "", base: "main", gate: [], protect: [], ecosystem: "go", preflight: [], test_glob: "",
- persistent_storage: false, max_retries: 0, allow_concurrent: false, review_enabled: false,
- };
- else if (props.path.endsWith("mcp_servers")) value = {
- name: "", transport: "stdio", command: "", args: [], work_dir: "", url: "",
- sse_endpoint: "", message_endpoint: "", headers_configured: false,
- };
- else if (props.path.endsWith("gate") || props.path.endsWith("preflight")) value = [];
- else if (props.path.endsWith("allowed_user_ids")) value = 0;
- else if (props.path.endsWith("personas")) value = { name: "", prompt: "" };
- else if (props.path === "schedules") value = {
- id: "", pool: "sequential", detail: "", kind: "workflow",
- schedule: { kind: "interval", interval: 3600000000000, start: "0001-01-01T00:00:00Z" },
- target: {}, payload: { text: "" }, next_run: "0001-01-01T00:00:00Z",
- created: "0001-01-01T00:00:00Z", updated: "0001-01-01T00:00:00Z",
- };
- emit("update:modelValue", [...current, value]);
+ emit("update:modelValue", [...current, blankFromSchema(property.value?.items)]);
}
function removeArray(index: number): void {
@@ -92,7 +97,13 @@ function scalar(value: string | number): void {
-
+
-
+
+
+
{{ fieldHint(property) }}
+
diff --git a/ui/src/settings/resource-schema.ts b/ui/src/settings/resource-schema.ts
new file mode 100644
index 000000000..b411062e1
--- /dev/null
+++ b/ui/src/settings/resource-schema.ts
@@ -0,0 +1,140 @@
+/**
+ * Reading the JSON Schema a control-plane descriptor advertises.
+ *
+ * The descriptor's schema is derived in internal/app/controlplane/schema.go
+ * from the Go type of the document itself, so it is structure only: keys,
+ * types, and the `format`/`title`/`doc` annotations a field declares in its own
+ * tags. It carries no prose of its own -- field descriptions have one home in
+ * internal/webui/config_schema.go -- so everything here treats a missing
+ * annotation as absent rather than inventing one.
+ *
+ * The live editor is value-driven (it walks the document it was given), so this
+ * is metadata layered onto fields that exist, never a field list. A document
+ * whose schema describes no properties renders exactly as it did before.
+ */
+
+/** One node of the derived schema. Only what the derivation emits is read. */
+export interface SchemaProperty {
+ type?: string;
+ format?: string;
+ title?: string;
+ description?: string;
+ properties?: Record
;
+ items?: SchemaProperty;
+ additionalProperties?: SchemaProperty | boolean;
+}
+
+/**
+ * parseSchema reads a descriptor's schema_json. A descriptor that carries none,
+ * or carries one this reader cannot parse, reports null: an unreadable schema
+ * costs a placeholder, never a field.
+ */
+export function parseSchema(json: string | null | undefined): SchemaProperty | null {
+ if (!json) return null;
+ try {
+ const parsed: unknown = JSON.parse(json);
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+ return parsed as SchemaProperty;
+ } catch {
+ return null;
+ }
+}
+
+function isKeyed(property: SchemaProperty): boolean {
+ return property.type === "object" && !property.properties && typeof property.additionalProperties === "object";
+}
+
+/**
+ * schemaAt resolves the property that describes one editor path.
+ *
+ * Paths are the editor's own (`repositories.0.owner`): dotted, with an array
+ * item addressed by its index. `rootPath` is stripped first, because the
+ * editor's path starts at the document rather than inside it -- the schema
+ * describes the document, not a field of it.
+ */
+export function schemaAt(
+ schema: SchemaProperty | null,
+ path: string,
+ rootPath = "",
+): SchemaProperty | null {
+ if (!schema) return null;
+ const root = rootPath.split(".").filter(Boolean);
+ let segments = path.split(".").filter(Boolean);
+ if (root.length && root.every((segment, index) => segments[index] === segment)) {
+ segments = segments.slice(root.length);
+ }
+
+ let current: SchemaProperty | null = schema;
+ for (const segment of segments) {
+ if (!current) return null;
+ if (/^\d+$/.test(segment)) {
+ current = current.items ?? null;
+ continue;
+ }
+ const named = current.properties?.[segment];
+ if (named) {
+ current = named;
+ continue;
+ }
+ // A keyed collection's keys belong to the operator, so the value's
+ // schema describes whatever key they typed.
+ current = typeof current.additionalProperties === "object" ? current.additionalProperties : null;
+ }
+ return current;
+}
+
+/** fieldTitle is the schema's own label for a key, or the dashed-key fallback
+ * the editor has always used. */
+export function fieldTitle(key: string, property: SchemaProperty | null | undefined): string {
+ if (property?.title) return property.title;
+ return key.replaceAll("_", " ").replace(/^./, (character) => character.toUpperCase());
+}
+
+/**
+ * fieldPlaceholder offers an example only where the schema declares a format
+ * the field's value must match. A duration column is a string to the document
+ * and a duration to the operator, and the example is what says so.
+ */
+export function fieldPlaceholder(property: SchemaProperty | null | undefined): string | undefined {
+ if (property?.format === "duration") return "1m0s";
+ if (property?.format === "date-time") return "2026-01-01T00:00:00Z";
+ return undefined;
+}
+
+/** fieldHint is the schema's own prose for a field, empty when it has none. */
+export function fieldHint(property: SchemaProperty | null | undefined): string {
+ return property?.description ?? "";
+}
+
+/** isKeyedCollection reports a document whose keys are the operator's: a map
+ * with no fixed properties, which the schema marks with additionalProperties. */
+export function isKeyedCollection(property: SchemaProperty | null | undefined): boolean {
+ return Boolean(property) && isKeyed(property as SchemaProperty);
+}
+
+/**
+ * blankFromSchema synthesises a new row from the schema rather than from the
+ * path that happens to hold it.
+ *
+ * The editor used to carry a literal template per array path -- a repository
+ * skeleton, an MCP server skeleton -- which went stale the moment the document
+ * was reshaped, and said nothing about the fields it did not know. A blank from
+ * the schema cannot be stale, because the schema is derived from the document.
+ * What it loses is the seeded convenience value (a default branch name, say):
+ * a schema that wants those emits a default, which is the same single source of
+ * truth this reader exists to honour.
+ */
+export function blankFromSchema(property: SchemaProperty | null | undefined): unknown {
+ if (!property) return "";
+ if (property.type === "object") {
+ const blank: Record = {};
+ for (const [key, child] of Object.entries(property.properties ?? {})) {
+ blank[key] = blankFromSchema(child);
+ }
+ return blank;
+ }
+ if (property.type === "array") return [];
+ if (property.type === "boolean") return false;
+ if (property.type === "integer" || property.type === "number") return 0;
+ return "";
+}
diff --git a/ui/test/resource-schema.test.ts b/ui/test/resource-schema.test.ts
new file mode 100644
index 000000000..fff3a7a45
--- /dev/null
+++ b/ui/test/resource-schema.test.ts
@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const { blankFromSchema, fieldHint, fieldPlaceholder, fieldTitle, isKeyedCollection, parseSchema, schemaAt } = await import(
+ "../src/settings/resource-schema.ts"
+);
+
+// The shapes the control-plane descriptors actually advertise (derived in
+// internal/app/controlplane/schema.go), plus the two degenerate ones.
+const objectSchema = {
+ type: "object",
+ properties: {
+ email: { type: "object", properties: { listen_addr: { type: "string", title: "Listen address" } } },
+ rate_limit: {
+ type: "object",
+ properties: {
+ window: { type: "string", format: "duration" },
+ max_requests: { type: "integer", description: "0 disables rate limiting." },
+ },
+ },
+ },
+};
+const arraySchema = {
+ type: "array",
+ items: { type: "object", properties: { owner: { type: "string" }, base: { type: "string" } } },
+};
+const keyedSchema = { type: "object", additionalProperties: { type: "object", properties: { class: { type: "string" } } } };
+const bareSchema = { type: "object" };
+
+test("parseSchema tolerates a missing or unparseable schema", () => {
+ assert.equal(parseSchema(undefined), null);
+ assert.equal(parseSchema(""), null);
+ assert.equal(parseSchema("{"), null);
+ assert.deepEqual(parseSchema(JSON.stringify(bareSchema)), bareSchema);
+});
+
+test("schemaAt walks nested fields, array items and keyed-collection values", () => {
+ assert.deepEqual(schemaAt(objectSchema, "channel-settings.rate_limit.window", "channel-settings"), {
+ type: "string",
+ format: "duration",
+ });
+ assert.deepEqual(schemaAt(arraySchema, "repositories.0.owner", "repositories"), { type: "string" });
+ assert.deepEqual(schemaAt(keyedSchema, "providers.anything.class", "providers"), { type: "string" });
+ assert.deepEqual(schemaAt(objectSchema, "channel-settings", "channel-settings"), objectSchema);
+});
+
+test("schemaAt answers nothing for a path the schema does not describe", () => {
+ assert.equal(schemaAt(objectSchema, "channel-settings.telegram.token", "channel-settings"), null);
+ assert.equal(schemaAt(null, "channel-settings.email", "channel-settings"), null);
+ assert.equal(schemaAt(bareSchema, "channel-settings.email.listen_addr", "channel-settings"), null);
+});
+
+test("fieldTitle prefers the schema title over the dashed-key fallback", () => {
+ assert.equal(fieldTitle("listen_addr", { title: "Listen address" }), "Listen address");
+ assert.equal(fieldTitle("listen_addr", { type: "string" }), "Listen addr");
+ assert.equal(fieldTitle("listen_addr", null), "Listen addr");
+});
+
+test("fieldPlaceholder offers a duration only where the schema says duration", () => {
+ assert.equal(fieldPlaceholder({ type: "string", format: "duration" }), "1m0s");
+ assert.equal(fieldPlaceholder({ type: "string", format: "date-time" }), "2026-01-01T00:00:00Z");
+ assert.equal(fieldPlaceholder({ type: "string" }), undefined);
+ assert.equal(fieldPlaceholder({ type: "integer" }), undefined);
+ assert.equal(fieldPlaceholder(null), undefined);
+});
+
+test("fieldHint carries the schema's own prose, and nothing when it has none", () => {
+ assert.equal(fieldHint({ description: "0 disables rate limiting." }), "0 disables rate limiting.");
+ assert.equal(fieldHint({ type: "integer" }), "");
+ assert.equal(fieldHint(null), "");
+});
+
+test("isKeyedCollection is the schema signal that keys are the operator's", () => {
+ assert.equal(isKeyedCollection(keyedSchema), true);
+ assert.equal(isKeyedCollection(objectSchema), false);
+ assert.equal(isKeyedCollection(bareSchema), false);
+ assert.equal(isKeyedCollection(null), false);
+});
+
+test("blankFromSchema synthesises a new row from the schema, not from a path", () => {
+ assert.deepEqual(blankFromSchema(arraySchema.items), { owner: "", base: "" });
+ assert.deepEqual(blankFromSchema(keyedSchema), {});
+ assert.deepEqual(blankFromSchema({ type: "array", items: { type: "string" } }), []);
+ assert.equal(blankFromSchema({ type: "boolean" }), false);
+ assert.equal(blankFromSchema({ type: "integer" }), 0);
+ assert.equal(blankFromSchema({ type: "string", format: "duration" }), "");
+ assert.equal(blankFromSchema(null), "");
+});
+
+test("the live editor reads the schema, and no longer hardcodes document shapes", async () => {
+ const editor = await readFile(new URL("../src/settings/StructuredValueEditor.vue", import.meta.url), "utf8");
+ assert.match(editor, /fieldPlaceholder/, "the editor offers the duration placeholder from the schema");
+ assert.match(editor, /fieldTitle/, "labels come from the schema title");
+ assert.match(editor, /blankFromSchema/, "a new row is synthesised from the schema");
+ for (const stale of ["base: \"main\"", "ecosystem: \"go\"", "transport: \"stdio\"", "interval: 3600000000000"]) {
+ assert.ok(!editor.includes(stale), `the editor still hardcodes a document shape: ${stale}`);
+ }
+});
+
+test("the resource card hands the derived schema to the editor", async () => {
+ const card = await readFile(new URL("../src/settings/StructuredResourceCard.vue", import.meta.url), "utf8");
+ assert.match(card, /parseSchema/, "the card parses the descriptor's schema");
+ assert.match(card, /:schema=/, "the card passes it down");
+});