@capybara-hq/plugin-sdk 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/agent-template.d.ts

@@ -21,6 +21,62 @@ export interface AgentTemplate {
     maxSteps?: number;
     /** Skill names preloaded (pinned) in the sub-agent. */
     skills?: string[];
+    /** Further skill names the agent uses (not preloaded; P4-1). */
+    selectedSkills?: string[];
+    /** Connectors the agent needs: a connector template of the plugin, or a described need. */
+    connectors?: AgentTemplateConnector[];
+    /** The sub-agents the agent gets in its roster. */
+    subagents?: AgentTemplateSubagents;
+    /** `provider/model`: the concrete model an org template was saved with. */
+    modelRef?: string;
+    /** The agent profile's quick actions (same shape and limits). */
+    quickActions?: AgentTemplateQuickAction[];
+    /** The agent's instruction files. */
+    instructionFiles?: AgentTemplateInstructionFile[];
+}
+/** A quick action of the agent profile. */
+export interface AgentTemplateQuickAction {
+    title: string;
+    body: string;
+}
+/** An instruction file of the agent. */
+export interface AgentTemplateInstructionFile {
+    name: string;
+    content: string;
+}
+/**
+ * A connector entry of a template: a connector template id (`<id>` or `<plugin>:<id>`) or a need.
+ * `policies` tighten the connector's tools by tool name (`ask` / `deny`), applied once it is bound.
+ */
+export type AgentTemplateConnector = {
+    template: string;
+    tools?: string[];
+    policies?: Record<string, "ask" | "deny">;
+} | {
+    needs: {
+        protocol: "mcp" | "openapi";
+        endpoint: string;
+        tools: string[];
+        label: string;
+    };
+    policies?: Record<string, "ask" | "deny">;
+};
+/** A sub-agent type described inside a template. */
+export interface AgentTemplateInlineSubagent {
+    name: string;
+    description: string;
+    instructions: string;
+    /** Tool keys allowed (an allowlist; `[]` = no tools); absent = all of the agent's tools. */
+    tools?: string[];
+    /** Skill names. */
+    skills: string[];
+    model: AgentTemplateTier;
+}
+export interface AgentTemplateSubagents {
+    general?: boolean;
+    /** Template types as the roster writes them (`<plugin>:<name>` or `<name>`). */
+    types?: string[];
+    inline?: AgentTemplateInlineSubagent[];
 }
 /** Limits of agent templates. */
 export declare const AGENT_TEMPLATE_LIMITS: {
@@ -33,9 +89,38 @@ export declare const AGENT_TEMPLATE_LIMITS: {
     readonly skills: 3;
     /** Entries of `tools` and of `disallowedTools`. */
     readonly tools: 200;
+    /** Entries of `selectedSkills`. */
+    readonly selectedSkills: 32;
+    /** Entries of `connectors`. */
+    readonly connectors: 16;
+    /** `subagents.types` plus `subagents.inline`. */
+    readonly subagentTypes: 16;
+    /** Characters of one inline sub-agent's instructions. */
+    readonly inlineInstructionsChars: 100000;
+    /** Tools named by a connector entry (its `tools`, and the keys of its `policies`). */
+    readonly connectorTools: 200;
+    /** Quick actions, as the agent profile limits them. */
+    readonly quickActions: 9;
+    readonly quickActionTitleChars: 40;
+    readonly quickActionBodyChars: 20000;
+    /** Instruction files and their joined size, as the agent limits them. */
+    readonly instructionFiles: 20;
+    readonly instructionFilesChars: 100000;
 };
+/** One frontmatter key of an agent template, for documentation (served to agents by `Platform`). */
+export interface AgentTemplateField {
+    name: string;
+    type: string;
+    required: boolean;
+    /** What it does, with its limit. */
+    description: string;
+}
+/** The frontmatter keys `parseAgentTemplate` reads (the body is the instructions). */
+export declare const AGENT_TEMPLATE_FIELDS: readonly AgentTemplateField[];
 /** The name rule of a template (the catalog item name rule). */
 export declare const AGENT_TEMPLATE_NAME_RE: RegExp;
+/** The name rule of an instruction file (the agent's rule, mirrored). */
+export declare const AGENT_TEMPLATE_INSTRUCTION_FILE_NAME_RE: RegExp;
 /**
  * Parses an agent template file. Returns the template, or every problem found (English, for the
  * plugin author or an admin). Keys the format does not define are ignored. Never throws.

package/dist/agent-template.js

@@ -17,14 +17,130 @@ export const AGENT_TEMPLATE_LIMITS = {
     skills: 3,
     /** Entries of `tools` and of `disallowedTools`. */
     tools: 200,
+    /** Entries of `selectedSkills`. */
+    selectedSkills: 32,
+    /** Entries of `connectors`. */
+    connectors: 16,
+    /** `subagents.types` plus `subagents.inline`. */
+    subagentTypes: 16,
+    /** Characters of one inline sub-agent's instructions. */
+    inlineInstructionsChars: 100_000,
+    /** Tools named by a connector entry (its `tools`, and the keys of its `policies`). */
+    connectorTools: 200,
+    /** Quick actions, as the agent profile limits them. */
+    quickActions: 9,
+    quickActionTitleChars: 40,
+    quickActionBodyChars: 20_000,
+    /** Instruction files and their joined size, as the agent limits them. */
+    instructionFiles: 20,
+    instructionFilesChars: 100_000,
 };
+/** The frontmatter keys `parseAgentTemplate` reads (the body is the instructions). */
+export const AGENT_TEMPLATE_FIELDS = [
+    {
+        name: "name",
+        type: "string",
+        required: true,
+        description: "`^[a-z0-9][a-z0-9-]{0,63}$`; the type name is `<plugin>:<name>`.",
+    },
+    {
+        name: "description",
+        type: "string",
+        required: true,
+        description: "When to use it; at most 4096 characters.",
+    },
+    {
+        name: "tools",
+        type: "array of tool keys",
+        required: false,
+        description: "Allowlist (at most 200); omitted = the parent's tools, `[]` = none.",
+    },
+    {
+        name: "disallowedTools",
+        type: "array of tool keys",
+        required: false,
+        description: "Tool keys removed (at most 200).",
+    },
+    {
+        name: "toolPolicies",
+        type: "object",
+        required: false,
+        description: "Tool key to `ask` or `deny`; can only tighten.",
+    },
+    {
+        name: "model",
+        type: "`inherit` \\| `fast` \\| `standard` \\| `capable`",
+        required: false,
+        description: "A purpose tier, never a model id; default `inherit`.",
+    },
+    {
+        name: "effort",
+        type: "`low` \\| `medium` \\| `high` \\| `xhigh` \\| `max`",
+        required: false,
+        description: "Reasoning effort.",
+    },
+    {
+        name: "maxSteps",
+        type: "integer",
+        required: false,
+        description: "Step limit; the kernel caps it.",
+    },
+    {
+        name: "skills",
+        type: "array of skill names",
+        required: false,
+        description: "At most 3, preloaded (pinned).",
+    },
+    {
+        name: "selectedSkills",
+        type: "array of skill names",
+        required: false,
+        description: "At most 32 further skills the agent may use.",
+    },
+    {
+        name: "connectors",
+        type: "array of objects",
+        required: false,
+        description: "At most 16: `{ template, tools?, policies? }` for a connector template (`<id>` or `<plugin>:<id>`), or `{ needs: { protocol, endpoint, tools, label }, policies? }` for a described need.",
+    },
+    {
+        name: "subagents",
+        type: "object",
+        required: false,
+        description: "`{ general?, types?, inline? }`: the sub-agents in its roster (at most 16 types plus inline).",
+    },
+    {
+        name: "modelRef",
+        type: "string",
+        required: false,
+        description: "`provider/model`; set on org templates saved from an agent.",
+    },
+    {
+        name: "quickActions",
+        type: "array of objects",
+        required: false,
+        description: "At most 9 `{ title, body }` shortcuts.",
+    },
+    {
+        name: "instructionFiles",
+        type: "array of objects",
+        required: false,
+        description: "At most 20 `{ name, content }` files.",
+    },
+];
 /** The name rule of a template (the catalog item name rule). */
 export const AGENT_TEMPLATE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const TIERS = ["inherit", "fast", "standard", "capable"];
 const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
-const FRONTMATTER_MAX_CHARS = 64 * 1024;
+/** Room for sub-agents described inline (up to 16 x 100 000 characters of instructions, P4-1). */
+const FRONTMATTER_MAX_CHARS = 2 * 1024 * 1024;
 /** The kernel's tool key rule (model-visible keys): no dots, no whitespace, at most 64 chars. */
 const TOOL_KEY_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+const distinct = (v) => new Set(v).size === v.length;
+const NAME_REF_RE = /^[a-z0-9][a-z0-9-]{0,63}(:[a-z0-9][a-z0-9-]{0,63})?$/;
+const MODEL_REF_RE = /^[^/\s]+\/\S+$/;
+/** The name rule of an instruction file (the agent's rule, mirrored). */
+export const AGENT_TEMPLATE_INSTRUCTION_FILE_NAME_RE = /^[^/\\]{1,64}\.md$/;
 const chars = (s) => [...s].length;
 const isToolKey = (v) => typeof v === "string" && TOOL_KEY_RE.test(v);
 const toolList = (v) => Array.isArray(v) &&
@@ -112,12 +228,255 @@ export function parseAgentTemplate(text) {
     }
     if (fm.skills !== undefined) {
         const s = fm.skills;
-        if (Array.isArray(s) && s.length <= L.skills && s.every(isSkillName))
+        if (Array.isArray(s) && s.length <= L.skills && s.every(isSkillName) && distinct(s))
             out.skills = s;
         else
             errors.push(`skills must list at most ${L.skills} skill names`);
     }
+    if (fm.selectedSkills !== undefined) {
+        const s = fm.selectedSkills;
+        if (Array.isArray(s) && s.length <= L.selectedSkills && s.every(isSkillName) && distinct(s)) {
+            out.selectedSkills = s;
+        }
+        else
+            errors.push(`selectedSkills must list at most ${L.selectedSkills} skill names`);
+    }
+    if (fm.connectors !== undefined) {
+        const c = readConnectors(fm.connectors, errors);
+        if (c)
+            out.connectors = c;
+    }
+    if (fm.subagents !== undefined) {
+        const s = readSubagents(fm.subagents, errors);
+        if (s)
+            out.subagents = s;
+    }
+    if (fm.modelRef !== undefined) {
+        if (typeof fm.modelRef === "string" &&
+            fm.modelRef.length <= 200 &&
+            MODEL_REF_RE.test(fm.modelRef)) {
+            out.modelRef = fm.modelRef;
+        }
+        else
+            errors.push("modelRef must be <provider>/<model>");
+    }
+    if (fm.quickActions !== undefined) {
+        const q = readQuickActions(fm.quickActions, errors);
+        if (q)
+            out.quickActions = q;
+    }
+    if (fm.instructionFiles !== undefined) {
+        const f = readInstructionFiles(fm.instructionFiles, errors);
+        if (f)
+            out.instructionFiles = f;
+    }
     if (errors.length > 0)
         return { errors };
     return { template: out };
 }
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isStr = (v, max) => typeof v === "string" && v.trim() !== "" && chars(v) <= max;
+const strList = (v, max, itemMax) => Array.isArray(v) && v.length <= max && v.every((x) => isStr(x, itemMax));
+const connectorPolicies = (v) => isObj(v) &&
+    Object.keys(v).length <= AGENT_TEMPLATE_LIMITS.connectorTools &&
+    Object.entries(v).every(([k, p]) => isStr(k, 128) && (p === "ask" || p === "deny"));
+const connectorPoliciesRule = `must map at most ${AGENT_TEMPLATE_LIMITS.connectorTools} tool names to ask or deny`;
+function readConnectors(v, errors) {
+    const L = AGENT_TEMPLATE_LIMITS;
+    if (!Array.isArray(v) || v.length > L.connectors) {
+        errors.push(`connectors must be a list of at most ${L.connectors} entries`);
+        return undefined;
+    }
+    const out = [];
+    let ok = true;
+    v.forEach((e, i) => {
+        const at = `connectors[${i}]`;
+        if (!isObj(e)) {
+            errors.push(`${at} must be { template } or { needs }`);
+            ok = false;
+        }
+        else if ("template" in e) {
+            if (typeof e.template !== "string" || !NAME_REF_RE.test(e.template)) {
+                errors.push(`${at}.template must be a connector template id (<id> or <plugin>:<id>)`);
+                ok = false;
+            }
+            else if (e.tools !== undefined && !strList(e.tools, L.connectorTools, 128)) {
+                errors.push(`${at}.tools must list at most ${L.connectorTools} tool names`);
+                ok = false;
+            }
+            else if (e.policies !== undefined && !connectorPolicies(e.policies)) {
+                errors.push(`${at}.policies ${connectorPoliciesRule}`);
+                ok = false;
+            }
+            else {
+                out.push({
+                    template: e.template,
+                    ...(e.tools !== undefined && { tools: e.tools }),
+                    ...(e.policies !== undefined && {
+                        policies: { ...e.policies },
+                    }),
+                });
+            }
+        }
+        else if ("needs" in e) {
+            const n = e.needs;
+            if (!isObj(n)) {
+                errors.push(`${at}.needs must be an object`);
+                ok = false;
+            }
+            else if (n.protocol !== "mcp" && n.protocol !== "openapi") {
+                errors.push(`${at}.needs.protocol must be mcp or openapi`);
+                ok = false;
+            }
+            else if (!isStr(n.endpoint, 2048)) {
+                errors.push(`${at}.needs.endpoint must be a non-empty string of at most 2048 characters`);
+                ok = false;
+            }
+            else if (!strList(n.tools, L.connectorTools, 128)) {
+                errors.push(`${at}.needs.tools must list at most ${L.connectorTools} tool names`);
+                ok = false;
+            }
+            else if (!isStr(n.label, 80)) {
+                errors.push(`${at}.needs.label must be a non-empty string of at most 80 characters`);
+                ok = false;
+            }
+            else if (e.policies !== undefined && !connectorPolicies(e.policies)) {
+                errors.push(`${at}.policies ${connectorPoliciesRule}`);
+                ok = false;
+            }
+            else {
+                out.push({
+                    needs: {
+                        protocol: n.protocol,
+                        endpoint: n.endpoint,
+                        tools: n.tools,
+                        label: n.label,
+                    },
+                    ...(e.policies !== undefined && {
+                        policies: { ...e.policies },
+                    }),
+                });
+            }
+        }
+        else {
+            errors.push(`${at} must have template or needs`);
+            ok = false;
+        }
+    });
+    return ok ? out : undefined;
+}
+function readSubagents(v, errors) {
+    const L = AGENT_TEMPLATE_LIMITS;
+    if (!isObj(v)) {
+        errors.push("subagents must be an object");
+        return undefined;
+    }
+    const out = {};
+    const n0 = errors.length;
+    if (v.general !== undefined) {
+        if (typeof v.general === "boolean")
+            out.general = v.general;
+        else
+            errors.push("subagents.general must be true or false");
+    }
+    if (v.types !== undefined) {
+        if (Array.isArray(v.types) &&
+            v.types.every((t) => typeof t === "string" && NAME_REF_RE.test(t)) &&
+            distinct(v.types)) {
+            out.types = v.types;
+        }
+        else
+            errors.push("subagents.types must list sub-agent type names");
+    }
+    if (v.inline !== undefined) {
+        if (!Array.isArray(v.inline))
+            errors.push("subagents.inline must be a list");
+        else {
+            const inline = [];
+            v.inline.forEach((e, i) => {
+                const at = `subagents.inline[${i}]`;
+                if (!isObj(e)) {
+                    errors.push(`${at} must be an object`);
+                    return;
+                }
+                const before = errors.length;
+                if (typeof e.name !== "string" || !AGENT_TEMPLATE_NAME_RE.test(e.name)) {
+                    errors.push(`${at}.name must match ^[a-z0-9][a-z0-9-]{0,63}$`);
+                }
+                if (!isStr(e.description, L.descriptionChars)) {
+                    errors.push(`${at}.description must be a non-empty string of at most ${L.descriptionChars} characters`);
+                }
+                if (typeof e.instructions !== "string" ||
+                    e.instructions.trim() === "" ||
+                    chars(e.instructions) > L.inlineInstructionsChars) {
+                    errors.push(`${at}.instructions must be a non-empty string of at most ${L.inlineInstructionsChars} characters`);
+                }
+                if (e.tools !== undefined && !toolList(e.tools)) {
+                    errors.push(`${at}.tools must be ${toolListRule}`);
+                }
+                if (!(Array.isArray(e.skills) &&
+                    e.skills.length <= L.skills &&
+                    e.skills.every(isSkillName) &&
+                    distinct(e.skills))) {
+                    errors.push(`${at}.skills must list at most ${L.skills} skill names`);
+                }
+                if (!TIERS.includes(e.model)) {
+                    errors.push(`${at}.model must be one of ${TIERS.join(", ")}`);
+                }
+                if (errors.length === before)
+                    inline.push(e);
+            });
+            out.inline = inline;
+        }
+    }
+    if ((out.types?.length ?? 0) + (out.inline?.length ?? 0) > L.subagentTypes) {
+        errors.push(`subagents.types and subagents.inline together must be at most ${L.subagentTypes}`);
+    }
+    return errors.length === n0 ? out : undefined;
+}
+function readQuickActions(v, errors) {
+    const L = AGENT_TEMPLATE_LIMITS;
+    if (!Array.isArray(v) || v.length > L.quickActions) {
+        errors.push(`quickActions must be a list of at most ${L.quickActions} entries`);
+        return undefined;
+    }
+    const n0 = errors.length;
+    const out = [];
+    v.forEach((e, i) => {
+        if (isObj(e) &&
+            isStr(e.title, L.quickActionTitleChars) &&
+            isStr(e.body, L.quickActionBodyChars)) {
+            out.push({ title: e.title, body: e.body });
+        }
+        else {
+            errors.push(`quickActions[${i}] must have a title (at most ${L.quickActionTitleChars} characters) and a body (at most ${L.quickActionBodyChars})`);
+        }
+    });
+    return errors.length === n0 ? out : undefined;
+}
+function readInstructionFiles(v, errors) {
+    const L = AGENT_TEMPLATE_LIMITS;
+    if (!Array.isArray(v) || v.length > L.instructionFiles) {
+        errors.push(`instructionFiles must be a list of at most ${L.instructionFiles} entries`);
+        return undefined;
+    }
+    const n0 = errors.length;
+    const out = [];
+    let total = 0;
+    v.forEach((e, i) => {
+        if (isObj(e) &&
+            typeof e.name === "string" &&
+            AGENT_TEMPLATE_INSTRUCTION_FILE_NAME_RE.test(e.name) &&
+            typeof e.content === "string") {
+            total += chars(e.content);
+            out.push({ name: e.name, content: e.content });
+        }
+        else {
+            errors.push(`instructionFiles[${i}] must have a name (<name>.md) and a content string`);
+        }
+    });
+    if (errors.length === n0 && total > L.instructionFilesChars) {
+        errors.push(`instructionFiles must total at most ${L.instructionFilesChars} characters`);
+    }
+    return errors.length === n0 ? out : undefined;
+}

package/dist/config-ui.d.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import type { LocalizedName } from "./plugin-package.js";
+/**
+ * Config UI hints (extension config forms spec §3): declarative presentation hints attached to an
+ * extension's config schema with {@link ui}, serialized as `x-ui` into the JSON Schema
+ * ({@link configJsonSchema}) and drawn by one generic renderer in the web app. Hints never change
+ * what validates: the zod schema stays the single source of truth for shape and validation.
+ */
+/** A JSON Schema object (as produced by {@link configJsonSchema}). */
+export type JsonSchema = Record<string, unknown>;
+/** The input widget of a field. */
+export type ConfigWidget = "text" | "textarea" | "url" | "number" | "select" | "radio" | "switch" | "checkbox" | "tristate" | "tags" | "json";
+/** A labelled value of an enum (or boolean) field. */
+export interface ConfigUiOption {
+    value: string | number | boolean;
+    label: LocalizedName;
+    help?: LocalizedName;
+}
+/** A root-level section that fields join with `section`. */
+export interface ConfigUiSection {
+    id: string;
+    label: LocalizedName;
+    help?: LocalizedName;
+}
+/** A prefilled item offered when adding an item to an array of objects. */
+export interface ConfigUiPreset {
+    id: string;
+    label: LocalizedName;
+    help?: LocalizedName;
+    /** Prefilled item fields; never a secret. */
+    values: Record<string, unknown>;
+}
+/** A secret drawn inside each item of an array, stored at a fixed record path keyed by an item field. */
+export interface ConfigUiItemSecret {
+    /** Dot path, from the schema root, of a `secret(z.record(z.string(), z.string()))` field. */
+    path: string;
+    /** The item's string field whose value is the record key (e.g. `name`). */
+    keyBy: string;
+    label: LocalizedName;
+    help?: LocalizedName;
+    placeholder?: string | LocalizedName;
+    /** The item field the input is drawn after (default: last). */
+    after?: string;
+}
+/** Presentation hints of one config schema node (zod meta `ui`, JSON Schema `x-ui`). */
+export interface ConfigUiHints {
+    label?: LocalizedName;
+    help?: LocalizedName;
+    placeholder?: string | LocalizedName;
+    /** Shown after a number input ("tokens", "ms"). */
+    unit?: LocalizedName;
+    /** Sort key among siblings (default: declaration order). */
+    order?: number;
+    /** Root-level section id (`sections` on the root). */
+    section?: string;
+    /** Collapsed under "Advanced" in its object or item. */
+    advanced?: boolean;
+    widget?: ConfigWidget;
+    options?: ConfigUiOption[];
+    /** Objects (and array items): fields stacked (default) or one compact row. */
+    layout?: "stack" | "row";
+    /** Arrays: how each item is drawn and added. */
+    item?: {
+        /** `{field}` template from the item's own scalar fields, e.g. "{name}". */
+        title?: string;
+        subtitle?: string;
+        addLabel?: LocalizedName;
+        reorder?: boolean;
+    };
+    presets?: ConfigUiPreset[];
+    secrets?: ConfigUiItemSecret[];
+    /** Root only. */
+    sections?: ConfigUiSection[];
+    /** Root only: localized messages for custom issues (`params: { ui: key }`). */
+    messages?: Record<string, LocalizedName>;
+}
+/** Limits of config UI hints and of the JSON Schemas a plugin package carries. */
+export declare const CONFIG_UI_LIMITS: {
+    /** Characters per language of a `label` (also `unit`, `item.addLabel`). */
+    readonly labelChars: 100;
+    /** Characters per language of a `help` (also `messages` values). */
+    readonly helpChars: 500;
+    /** Characters (per language) of a `placeholder`. */
+    readonly placeholderChars: 200;
+    /** UTF-8 bytes of all `x-ui` JSON of one schema. */
+    readonly hintsBytes: number;
+    /** Options per node. */
+    readonly options: 200;
+    /** Presets per node. */
+    readonly presets: 20;
+    /** Root sections. */
+    readonly sections: 20;
+    /**
+     * UTF-8 bytes of each JSON Schema in `plugin.json` `extension.configSchemas` (96 KiB: two of
+     * them must fit in the 256 KiB `plugin.json` text with the rest of the manifest).
+     */
+    readonly configSchemaBytes: number;
+};
+/**
+ * Attaches config UI hints to a schema (zod meta `ui`), merging with existing meta (`secret`,
+ * `hot`, `description`). Returns the same schema type. Convention: put `ui()` outermost, after
+ * `.default()` / `.optional()`.
+ */
+export declare function ui<T extends z.ZodTypeAny>(schema: T, hints: ConfigUiHints): T;
+/**
+ * An extension config schema as a JSON Schema for forms (the input side, defaults included, no
+ * `$schema`):
+ * - meta `secret: true` becomes `"x-secret": true`, `hot: true` becomes `"x-hot": true`, `org`
+ *   (`orgAccess`) becomes `"x-org"`, `ui`
+ *   becomes `"x-ui"` (a JSON copy of the hints); `title` / `description` are filled from
+ *   `x-ui.label.en` / `x-ui.help.en` when the node has none;
+ * - unrepresentable types become `{ "x-unsupported": true }` instead of throwing;
+ * - under a secret node no value is published: `default` / `examples` / `const` / `enum` and
+ *   `x-ui.options` / `x-ui.presets` are removed from it and all its descendants.
+ */
+export declare function configJsonSchema(schema: z.ZodTypeAny): JsonSchema;
+/** One problem of the hints of a config schema. */
+export interface ConfigUiProblem {
+    /**
+     * Dot path of the node holding the hint: property names, with `items` / `additionalProperties`
+     * for array items and record values (`endpoints.items.models`); `""` is the root.
+     */
+    path: string;
+    message: string;
+}
+/**
+ * Validates the `x-ui` hints of a JSON Schema produced by {@link configJsonSchema} (spec §3.3) at
+ * a config level. Pure; used by the packer, `capybara-plugin check` and the kernel. Returns every
+ * problem (empty = valid); never throws. Problem paths are dot paths of the node holding the hint.
+ */
+export declare function validateConfigUi(schema: JsonSchema, level: "deployment" | "org" | "connection"): ConfigUiProblem[];