@capybara-hq/plugin-sdk 0.1.0-rc.0 → 0.1.0-rc.2

package/README.md

@@ -14,8 +14,8 @@ npm packages; the host provides it at runtime.
 npm install @capybara-hq/plugin-sdk
 ```
 
-- Writing an extension: [.agents/skills/writing-extensions](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-extensions)
-  and the reference plugin [plugins/example-counter](https://github.com/capybara-hq/core/tree/main/plugins/example-counter).
+- Writing an extension: [.agents/skills/writing-extensions](https://github.com/capybara-hq/plugins/tree/main/.agents/skills/writing-extensions)
+  in capybara-hq/plugins and its reference plugin [plugins/example-counter](https://github.com/capybara-hq/plugins/tree/main/plugins/example-counter).
 - Writing a plugin (manifest, skills, connector templates, dependencies, marketplaces):
   [.agents/skills/writing-plugins](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-plugins).
 - The repository: [capybara-hq/core](https://github.com/capybara-hq/core).

package/dist/agent-template.js

@@ -1,7 +1,7 @@
 /**
  * Agent templates (`agents/<name>.md` in a plugin; sub-agents spec §16.1): Markdown with YAML
  * frontmatter, the body being the instructions. A template is a type an agent with the builtin
- * `agent` tool can dispatch as a sub-agent (`<plugin>:<name>` in its roster). Used by the kernel,
+ * `Agent` tool can dispatch as a sub-agent (`<plugin>:<name>` in its roster). Used by the kernel,
  * the packer and `capybara-plugin check`.
  */
 import { readFrontmatter } from "./frontmatter.js";

package/dist/config-ui.d.ts

@@ -0,0 +1,130 @@
+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`, `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[];

package/dist/config-ui.js

@@ -0,0 +1,584 @@
+import { z } from "zod";
+/** Limits of config UI hints and of the JSON Schemas a plugin package carries. */
+export const CONFIG_UI_LIMITS = {
+    /** Characters per language of a `label` (also `unit`, `item.addLabel`). */
+    labelChars: 100,
+    /** Characters per language of a `help` (also `messages` values). */
+    helpChars: 500,
+    /** Characters (per language) of a `placeholder`. */
+    placeholderChars: 200,
+    /** UTF-8 bytes of all `x-ui` JSON of one schema. */
+    hintsBytes: 64 * 1024,
+    /** Options per node. */
+    options: 200,
+    /** Presets per node. */
+    presets: 20,
+    /** Root sections. */
+    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).
+     */
+    configSchemaBytes: 96 * 1024,
+};
+/**
+ * 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 function ui(schema, hints) {
+    return schema.meta({ ...(schema.meta() ?? {}), ui: hints });
+}
+/** zod types JSON Schema cannot express: emitted as `{}` with `x-unsupported`. */
+const UNSUPPORTED = new Set([
+    "bigint",
+    "date",
+    "symbol",
+    "undefined",
+    "void",
+    "nan",
+    "map",
+    "set",
+    "function",
+    "promise",
+    "custom",
+    "file",
+]);
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * 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`, `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 function configJsonSchema(schema) {
+    const out = z.toJSONSchema(schema, {
+        io: "input",
+        unrepresentable: "any",
+        override: (ctx) => {
+            const js = ctx.jsonSchema;
+            const def = ctx.zodSchema._zod.def;
+            if (js.secret === true)
+                js["x-secret"] = true;
+            delete js.secret;
+            if (js.hot === true)
+                js["x-hot"] = true;
+            delete js.hot;
+            if ("ui" in js) {
+                // A JSON copy: hints are data, and the scrub must never mutate the schema's meta.
+                const hints = JSON.parse(JSON.stringify(js.ui ?? null));
+                delete js.ui;
+                if (isObj(hints)) {
+                    js["x-ui"] = hints;
+                    const label = isObj(hints.label) ? hints.label.en : undefined;
+                    const help = isObj(hints.help) ? hints.help.en : undefined;
+                    if (js.title === undefined && typeof label === "string")
+                        js.title = label;
+                    if (js.description === undefined && typeof help === "string")
+                        js.description = help;
+                }
+            }
+            if (UNSUPPORTED.has(def.type))
+                js["x-unsupported"] = true;
+        },
+    });
+    delete out.$schema;
+    scrubSecrets(out);
+    return out;
+}
+/** Keywords that would reveal values: never emitted for a secret. */
+const VALUE_KEYWORDS = ["default", "examples", "const", "enum"];
+/** Hints that would reveal values: never emitted for a secret. */
+const VALUE_HINTS = ["options", "presets"];
+/** Keywords whose value maps names to sub-schemas: their keys are field names, not keywords. */
+const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/**
+ * Removes value-revealing keywords from secret nodes and all their descendants (`inSecret` passed
+ * down). Only the keywords default / examples / const / enum are skipped as data; keys inside
+ * `properties` and other maps are field names, so fields named default / enum are traversed.
+ */
+function scrubSecrets(node, inSecret = false) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            scrubSecrets(n, inSecret);
+        return;
+    }
+    if (!isObj(node))
+        return;
+    const secret = inSecret || node["x-secret"] === true;
+    if (secret) {
+        for (const k of VALUE_KEYWORDS)
+            delete node[k];
+        const hints = node["x-ui"];
+        if (isObj(hints))
+            for (const k of VALUE_HINTS)
+                delete hints[k];
+    }
+    for (const [k, v] of Object.entries(node)) {
+        if (k === "x-ui")
+            continue;
+        if (SCHEMA_MAPS.has(k) && isObj(v)) {
+            for (const child of Object.values(v))
+                scrubSecrets(child, secret);
+        }
+        else if (!VALUE_KEYWORDS.includes(k)) {
+            scrubSecrets(v, secret);
+        }
+    }
+}
+const WIDGETS = new Set([
+    "text",
+    "textarea",
+    "url",
+    "number",
+    "select",
+    "radio",
+    "switch",
+    "checkbox",
+    "tristate",
+    "tags",
+    "json",
+]);
+const HINT_KEYS = new Set([
+    "label",
+    "help",
+    "placeholder",
+    "unit",
+    "order",
+    "section",
+    "advanced",
+    "widget",
+    "options",
+    "layout",
+    "item",
+    "presets",
+    "secrets",
+    "sections",
+    "messages",
+]);
+/** The only hints a secret node may carry. */
+const SECRET_HINT_KEYS = new Set(["label", "help", "placeholder", "order", "section", "advanced"]);
+const ITEM_KEYS = new Set(["title", "subtitle", "addLabel", "reorder"]);
+const utf8Bytes = (s) => new TextEncoder().encode(s).length;
+/** The JSON types a node accepts (`type`, a type list, or the branches of a nullable `anyOf`). */
+function typesOf(node) {
+    const t = node.type;
+    if (typeof t === "string")
+        return new Set([t]);
+    if (Array.isArray(t))
+        return new Set(t.filter((x) => typeof x === "string"));
+    const branches = (node.anyOf ?? node.oneOf);
+    if (Array.isArray(branches)) {
+        const out = new Set();
+        for (const b of branches)
+            if (isObj(b))
+                for (const x of typesOf(b))
+                    out.add(x);
+        return out;
+    }
+    if ("const" in node)
+        return new Set([jsonType(node.const)]);
+    if (Array.isArray(node.enum))
+        return new Set(node.enum.map(jsonType));
+    return new Set();
+}
+/** The non-null shape of a node: itself, or the one non-null branch of a nullable `anyOf`. */
+function shapeOf(node) {
+    const branches = (node.anyOf ?? node.oneOf);
+    if (node.type === undefined && Array.isArray(branches)) {
+        const rest = branches.filter((b) => isObj(b) && b.type !== "null");
+        if (rest.length === 1 && rest[0] !== undefined)
+            return rest[0];
+    }
+    return node;
+}
+function jsonType(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    if (typeof v === "number")
+        return Number.isInteger(v) ? "integer" : "number";
+    return typeof v;
+}
+/** The enum values of a node (`enum`, `const`, or `anyOf` / `oneOf` branches of those), or null. */
+function enumOf(node) {
+    if (Array.isArray(node.enum))
+        return node.enum;
+    if ("const" in node)
+        return [node.const];
+    const branches = (node.anyOf ?? node.oneOf);
+    if (Array.isArray(branches)) {
+        const out = [];
+        for (const b of branches) {
+            if (!isObj(b))
+                return null;
+            if (b.type === "null")
+                continue;
+            const e = enumOf(b);
+            if (e === null)
+                return null;
+            out.push(...e);
+        }
+        return out.length > 0 ? out : null;
+    }
+    return null;
+}
+const isNumberType = (types) => types.has("number") || types.has("integer");
+const only = (types, ...allowed) => types.size > 0 && [...types].every((t) => t === "null" || allowed.includes(t));
+const isScalar = (node) => {
+    const types = typesOf(node);
+    return !types.has("object") && !types.has("array");
+};
+/** Does `value` fit the JSON type (and enum) of `node`? */
+function fits(node, value) {
+    const types = typesOf(node);
+    const t = jsonType(value);
+    const typeOk = types.size === 0 || types.has(t) || (t === "integer" && types.has("number"));
+    if (!typeOk)
+        return false;
+    const e = enumOf(node);
+    return e === null || e.some((x) => x === value);
+}
+function properties(node) {
+    const p = shapeOf(node).properties;
+    return isObj(p) ? p : {};
+}
+function itemsOf(node) {
+    const i = shapeOf(node).items;
+    return isObj(i) ? i : null;
+}
+/**
+ * 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 function validateConfigUi(schema, level) {
+    const problems = [];
+    const L = CONFIG_UI_LIMITS;
+    const rootHints = isObj(schema["x-ui"]) ? schema["x-ui"] : {};
+    const sectionIds = new Set(Array.isArray(rootHints.sections)
+        ? rootHints.sections.flatMap((s) => (isObj(s) && typeof s.id === "string" ? [s.id] : []))
+        : []);
+    let hintsBytes = 0;
+    const resolvePath = (dotPath) => {
+        let node = schema;
+        for (const seg of dotPath.split(".")) {
+            if (node === null)
+                return null;
+            const props = properties(node);
+            node = Object.hasOwn(props, seg) ? (props[seg] ?? null) : null;
+        }
+        return node;
+    };
+    const visit = (node, path, isRoot) => {
+        const report = (message) => problems.push({ path, message });
+        const text = (value, what, max, plainOk = false) => {
+            if (value === undefined)
+                return;
+            if (plainOk && typeof value === "string") {
+                if (value.trim() === "")
+                    report(`${what} must not be empty`);
+                else if (value.length > max)
+                    report(`${what} must be at most ${max} characters`);
+                return;
+            }
+            if (!isObj(value)) {
+                report(`${what} must be { zh, en }${plainOk ? " or a string" : ""}`);
+                return;
+            }
+            for (const lang of ["zh", "en"]) {
+                const v = value[lang];
+                if (typeof v !== "string" || v.trim() === "")
+                    report(`${what}.${lang} must not be empty`);
+                else if (v.length > max)
+                    report(`${what}.${lang} must be at most ${max} characters`);
+            }
+            for (const k of Object.keys(value)) {
+                if (k !== "zh" && k !== "en")
+                    report(`${what} has an unknown key "${k}"`);
+            }
+        };
+        const raw = node["x-ui"];
+        if (raw !== undefined) {
+            hintsBytes += utf8Bytes(JSON.stringify(raw));
+            if (!isObj(raw))
+                report("x-ui must be an object");
+            else
+                checkHints(raw, node, isRoot, report, text);
+        }
+        const shape = shapeOf(node);
+        const props = shape.properties;
+        if (isObj(props)) {
+            for (const [k, child] of Object.entries(props)) {
+                if (isObj(child))
+                    visit(child, path === "" ? k : `${path}.${k}`, false);
+            }
+        }
+        if (isObj(shape.items))
+            visit(shape.items, path === "" ? "items" : `${path}.items`, false);
+        if (isObj(shape.additionalProperties)) {
+            visit(shape.additionalProperties, path === "" ? "additionalProperties" : `${path}.additionalProperties`, false);
+        }
+    };
+    const checkHints = (h, node, isRoot, report, text) => {
+        const shape = shapeOf(node);
+        const types = typesOf(node);
+        const isArray = types.has("array");
+        const items = itemsOf(node);
+        const itemProps = items !== null && typesOf(items).has("object") ? properties(items) : null;
+        for (const k of Object.keys(h)) {
+            if (!HINT_KEYS.has(k))
+                report(`x-ui has an unknown hint "${k}"`);
+        }
+        if (node["x-secret"] === true) {
+            const bad = Object.keys(h).filter((k) => HINT_KEYS.has(k) && !SECRET_HINT_KEYS.has(k));
+            if (bad.length > 0) {
+                report(`a secret field allows only label, help, placeholder, order, section and advanced hints, not ${bad.join(", ")}`);
+            }
+        }
+        text(h.label, "label", L.labelChars);
+        text(h.help, "help", L.helpChars);
+        text(h.placeholder, "placeholder", L.placeholderChars, true);
+        text(h.unit, "unit", L.labelChars);
+        if (h.order !== undefined && (typeof h.order !== "number" || !Number.isFinite(h.order))) {
+            report("order must be a number");
+        }
+        if (h.advanced !== undefined && typeof h.advanced !== "boolean") {
+            report("advanced must be a boolean");
+        }
+        if (h.section !== undefined) {
+            if (typeof h.section !== "string" || !sectionIds.has(h.section)) {
+                report(`section "${String(h.section)}" is not an id of the root's sections`);
+            }
+        }
+        if (!isRoot && h.sections !== undefined)
+            report("sections are allowed only on the root");
+        if (!isRoot && h.messages !== undefined)
+            report("messages are allowed only on the root");
+        if (isRoot && h.sections !== undefined) {
+            if (!Array.isArray(h.sections))
+                report("sections must be an array");
+            else {
+                if (h.sections.length > L.sections)
+                    report(`at most ${L.sections} sections`);
+                const ids = new Set();
+                h.sections.forEach((s, i) => {
+                    if (!isObj(s) || typeof s.id !== "string" || s.id === "") {
+                        report(`sections[${i}].id must be a non-empty string`);
+                        return;
+                    }
+                    if (ids.has(s.id))
+                        report(`duplicate section id "${s.id}"`);
+                    ids.add(s.id);
+                    text(s.label, `sections[${i}].label`, L.labelChars);
+                    if (s.label === undefined)
+                        report(`sections[${i}].label is required`);
+                    text(s.help, `sections[${i}].help`, L.helpChars);
+                });
+            }
+        }
+        if (isRoot && h.messages !== undefined) {
+            if (!isObj(h.messages))
+                report("messages must be an object");
+            else
+                for (const [k, v] of Object.entries(h.messages))
+                    text(v, `messages.${k}`, L.helpChars);
+        }
+        // widget fits the type
+        if (h.widget !== undefined) {
+            const w = h.widget;
+            const enumValues = enumOf(shape);
+            const ok = typeof w === "string" &&
+                WIDGETS.has(w) &&
+                (w === "json" ||
+                    (["switch", "checkbox", "tristate"].includes(w) && only(types, "boolean")) ||
+                    (["select", "radio"].includes(w) && enumValues !== null) ||
+                    (w === "tags" && isArray && items !== null && only(typesOf(items), "string")) ||
+                    (["url", "textarea", "text"].includes(w) && only(types, "string")) ||
+                    (w === "number" && isNumberType(types) && only(types, "number", "integer")));
+            if (!ok)
+                report(`widget "${String(w)}" does not fit this field's type`);
+        }
+        // options: members of the enum (or booleans), each once
+        if (h.options !== undefined) {
+            if (!Array.isArray(h.options))
+                report("options must be an array");
+            else {
+                if (h.options.length > L.options)
+                    report(`at most ${L.options} options`);
+                const allowed = enumOf(shape) ??
+                    (isArray && items !== null ? enumOf(items) : null) ??
+                    (only(types, "boolean") ? [true, false] : null);
+                const seen = [];
+                h.options.forEach((o, i) => {
+                    if (!isObj(o)) {
+                        report(`options[${i}] must be an object`);
+                        return;
+                    }
+                    if (allowed === null)
+                        report(`options[${i}]: this field has no enum to label`);
+                    else if (!allowed.some((v) => v === o.value)) {
+                        report(`options[${i}].value ${JSON.stringify(o.value)} is not a value of the field`);
+                    }
+                    if (seen.some((v) => v === o.value)) {
+                        report(`options[${i}].value ${JSON.stringify(o.value)} is listed twice`);
+                    }
+                    seen.push(o.value);
+                    text(o.label, `options[${i}].label`, L.labelChars);
+                    if (o.label === undefined)
+                        report(`options[${i}].label is required`);
+                    text(o.help, `options[${i}].help`, L.helpChars);
+                });
+            }
+        }
+        // layout
+        if (h.layout !== undefined) {
+            if (h.layout !== "stack" && h.layout !== "row")
+                report('layout must be "stack" or "row"');
+            else if (h.layout === "row") {
+                const target = isArray && items !== null && typesOf(items).has("object")
+                    ? items
+                    : types.has("object")
+                        ? node
+                        : null;
+                if (target === null)
+                    report('layout "row" applies only to objects and arrays of objects');
+                else {
+                    const nonScalar = Object.entries(properties(target))
+                        .filter(([, p]) => !isScalar(p))
+                        .map(([k]) => k);
+                    if (nonScalar.length > 0) {
+                        report(`layout "row" needs scalar fields; not scalar: ${nonScalar.join(", ")}`);
+                    }
+                }
+            }
+        }
+        // item / presets / secrets: arrays only; presets and secrets: arrays of objects
+        for (const k of ["item", "presets", "secrets"]) {
+            if (h[k] === undefined)
+                continue;
+            if (!isArray)
+                report(`${k} applies only to arrays`);
+            else if (k !== "item" && itemProps === null) {
+                report(`${k} applies only to arrays of objects`);
+            }
+        }
+        if (isObj(h.item) && isArray) {
+            for (const k of Object.keys(h.item)) {
+                if (!ITEM_KEYS.has(k))
+                    report(`item has an unknown key "${k}"`);
+            }
+            for (const k of ["title", "subtitle"]) {
+                const tpl = h.item[k];
+                if (tpl === undefined)
+                    continue;
+                if (typeof tpl !== "string") {
+                    report(`item.${k} must be a string`);
+                    continue;
+                }
+                for (const m of tpl.matchAll(/\{([^{}]*)\}/g)) {
+                    const field = m[1] ?? "";
+                    const p = itemProps !== null && Object.hasOwn(itemProps, field) ? itemProps[field] : null;
+                    if (p === null || p === undefined || !isScalar(p)) {
+                        report(`item.${k} names "${field}", which is not a scalar field of the item`);
+                    }
+                }
+            }
+            text(h.item.addLabel, "item.addLabel", L.labelChars);
+            if (h.item.reorder !== undefined && typeof h.item.reorder !== "boolean") {
+                report("item.reorder must be a boolean");
+            }
+        }
+        else if (h.item !== undefined && isArray) {
+            report("item must be an object");
+        }
+        if (h.presets !== undefined && itemProps !== null) {
+            if (!Array.isArray(h.presets))
+                report("presets must be an array");
+            else {
+                if (h.presets.length > L.presets)
+                    report(`at most ${L.presets} presets`);
+                const ids = new Set();
+                h.presets.forEach((p, i) => {
+                    if (!isObj(p) || typeof p.id !== "string" || p.id === "") {
+                        report(`presets[${i}].id must be a non-empty string`);
+                        return;
+                    }
+                    if (ids.has(p.id))
+                        report(`duplicate preset id "${p.id}"`);
+                    ids.add(p.id);
+                    text(p.label, `presets[${i}].label`, L.labelChars);
+                    if (p.label === undefined)
+                        report(`presets[${i}].label is required`);
+                    text(p.help, `presets[${i}].help`, L.helpChars);
+                    if (!isObj(p.values)) {
+                        report(`presets[${i}].values must be an object`);
+                        return;
+                    }
+                    for (const [k, v] of Object.entries(p.values)) {
+                        const prop = Object.hasOwn(itemProps, k) ? itemProps[k] : undefined;
+                        if (prop === undefined)
+                            report(`presets[${i}].values.${k} is not a field of the item`);
+                        else if (prop["x-secret"] === true) {
+                            report(`presets[${i}].values.${k} is a secret; presets never carry secrets`);
+                        }
+                        else if (!fits(prop, v)) {
+                            report(`presets[${i}].values.${k} does not match the field's type or values`);
+                        }
+                    }
+                });
+            }
+        }
+        if (h.secrets !== undefined && itemProps !== null) {
+            if (level !== "deployment") {
+                report("secrets drawn per item are allowed only in the deployment config");
+            }
+            if (!Array.isArray(h.secrets))
+                report("secrets must be an array");
+            else
+                h.secrets.forEach((s, i) => {
+                    if (!isObj(s)) {
+                        report(`secrets[${i}] must be an object`);
+                        return;
+                    }
+                    const target = typeof s.path === "string" ? resolvePath(s.path) : null;
+                    const ap = target === null ? null : shapeOf(target).additionalProperties;
+                    if (target === null ||
+                        target["x-secret"] !== true ||
+                        !typesOf(target).has("object") ||
+                        !isObj(ap) ||
+                        ap.type !== "string") {
+                        report(`secrets[${i}].path "${String(s.path)}" is not a secret record of strings (secret(z.record(z.string(), z.string())))`);
+                    }
+                    const keyProp = typeof s.keyBy === "string" && Object.hasOwn(itemProps, s.keyBy)
+                        ? itemProps[s.keyBy]
+                        : undefined;
+                    if (keyProp === undefined || !only(typesOf(keyProp), "string")) {
+                        report(`secrets[${i}].keyBy "${String(s.keyBy)}" is not a string field of the item`);
+                    }
+                    if (s.after !== undefined &&
+                        (typeof s.after !== "string" || !Object.hasOwn(itemProps, s.after))) {
+                        report(`secrets[${i}].after "${String(s.after)}" is not a field of the item`);
+                    }
+                    text(s.label, `secrets[${i}].label`, L.labelChars);
+                    if (s.label === undefined)
+                        report(`secrets[${i}].label is required`);
+                    text(s.help, `secrets[${i}].help`, L.helpChars);
+                    text(s.placeholder, `secrets[${i}].placeholder`, L.placeholderChars, true);
+                });
+        }
+    };
+    visit(schema, "", true);
+    if (hintsBytes > L.hintsBytes) {
+        problems.push({
+            path: "",
+            message: `x-ui hints total ${hintsBytes} bytes; at most ${L.hintsBytes} (64 KiB) per schema`,
+        });
+    }
+    return problems;
+}

package/dist/extension-point.d.ts

@@ -9,6 +9,11 @@ export interface ExtensionPointInfo {
     brokered: boolean;
     /** Enabled per org (consumers may pass `orgId` to check that the org enabled the provider). */
     orgScoped: boolean;
+    /**
+     * How the kernel picks one provider among several: `org-default` means each org chooses its
+     * default provider (absent: no selection, every enabled provider is used).
+     */
+    selection?: "org-default";
 }
 /** The registered extension points. */
 export declare const EXTENSION_POINTS: Record<string, ExtensionPointInfo>;

package/dist/extension-point.js

@@ -1,7 +1,8 @@
-const info = (cardinality, brokered = false, orgScoped = false) => ({
+const info = (cardinality, brokered = false, orgScoped = false, selection) => ({
     cardinality,
     brokered,
     orgScoped,
+    ...(selection ? { selection } : {}),
 });
 /** The registered extension points. */
 export const EXTENSION_POINTS = {
@@ -16,6 +17,8 @@ export const EXTENSION_POINTS = {
     counter: info("multi"),
     connector: info("multi", true),
     "file-preview": info("multi", false, true),
+    "web-search": info("multi", true, true, "org-default"),
+    "web-fetch": info("multi", true, true, "org-default"),
 };
 /** Cardinality of the registered extension points (derived from EXTENSION_POINTS). */
 export const EXTENSION_POINT_CARDINALITY = Object.fromEntries(Object.entries(EXTENSION_POINTS).map(([k, v]) => [k, v.cardinality]));

package/dist/hooks.d.ts

@@ -7,12 +7,12 @@ import type { ContentBlock, ModelRequest, ModelUsage } from "./model.js";
 export declare const HOOKS_AVAILABLE: readonly ["model.request", "model.response", "tool.preExecute", "tool.postExecute", "usage.report"];
 /** A mount point that `ctx.hooks.on` accepts. */
 export type AvailableHook = (typeof HOOKS_AVAILABLE)[number];
-/** Where a sub-agent was dispatched from: the parent conversation, its run and the `agent` call. */
+/** Where a sub-agent was dispatched from: the parent conversation, its run and the `Agent` call. */
 export interface HookParentScope {
     conversationId: string;
     runId: string;
     /**
-     * The `agent` call's id; `skill-<seq>` for a person's forked skill invocation, which has no
+     * The `Agent` call's id; `skill-<seq>` for a person's forked skill invocation, which has no
      * tool call in the parent's log.
      */
     callId: string;
@@ -35,9 +35,10 @@ export interface HookScope {
  * What a model call is for: `step` is a run step's call (the agent's turn), `compaction` is the call
  * that summarizes earlier history before a step when the context grows too large, `title` is the call
  * that writes a conversation's title after its first completed run (no run: `runId` is "", `step` 0,
- * `attempt` 1).
+ * `attempt` 1), `web_fetch` is the call that extracts an answer from a fetched web page for the
+ * `WebFetch` tool.
  */
-export type ModelCallPurpose = "step" | "compaction" | "title";
+export type ModelCallPurpose = "step" | "compaction" | "title" | "web_fetch";
 /** What a reported model call was for (the same values as {@link ModelCallPurpose}). */
 export type UsagePurpose = ModelCallPurpose;
 /**
@@ -111,6 +112,7 @@ export interface ModelResponseHookPayload extends HookScope {
 export interface ToolPreHookPayload extends HookScope {
     step: number;
     callId: string;
+    /** The model-visible key: a builtin name, `mcp__<slug>__<tool>` or `plugin__<plugin>__<tool>`; split it with `parseToolKey`. */
     toolKey: string;
     specHash: string;
     input: unknown;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export declare const SDK_VERSION = "0.1.0-rc.0";
+export declare const SDK_VERSION = "0.1.0-rc.2";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
 export * from "./channel.js";
+export * from "./config-ui.js";
 export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
@@ -24,4 +25,6 @@ export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
 export * from "./tool.js";
+export * from "./tool-key.js";
 export * from "./ui.js";
+export * from "./web.js";

package/dist/index.js

@@ -1,8 +1,9 @@
-export const SDK_VERSION = "0.1.0-rc.0";
+export const SDK_VERSION = "0.1.0-rc.2";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
 export * from "./channel.js";
+export * from "./config-ui.js";
 export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
@@ -24,4 +25,6 @@ export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";
 export * from "./tool.js";
+export * from "./tool-key.js";
 export * from "./ui.js";
+export * from "./web.js";

package/dist/plugin-manifest.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type JsonSchema } from "./config-ui.js";
 import { type ConnectorTemplateSpec, type LocalizedName, type StaticExtensionManifest } from "./plugin-package.js";
 /**
  * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
@@ -74,6 +75,15 @@ export interface PluginExtensionSection {
     migrations?: string;
     /** `./ui`. */
     ui?: string;
+    /**
+     * The config JSON Schemas (`configJsonSchema`, with `x-ui` hints), written by the packer so an
+     * extension not loaded on a replica still gets its form; each ≤
+     * {@link CONFIG_UI_LIMITS}`.configSchemaBytes`. Not part of the `manifest_mismatch` comparison.
+     */
+    configSchemas?: {
+        deployment?: JsonSchema;
+        org?: JsonSchema;
+    };
 }
 /** `.capybara-plugin/plugin.json`. */
 export interface PluginManifest {

package/dist/plugin-manifest.js

@@ -1,6 +1,7 @@
 import semver from "semver";
 import { z } from "zod";
 import { AGENT_TEMPLATE_LIMITS } from "./agent-template.js";
+import { CONFIG_UI_LIMITS } from "./config-ui.js";
 import { defineExtension, EXTENSION_NAME_RE } from "./define-extension.js";
 import { CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, isSafePackagePath, SEMVER_VERSION_RE, validateConnectorTemplate, } from "./plugin-package.js";
 import { hasUpperBound } from "./semver-range.js";
@@ -87,6 +88,11 @@ const staticExtensionManifest = z.strictObject({
     ui: z.array(z.record(z.string(), z.unknown())).optional(),
     config: z.strictObject({ deployment: configFields, org: configFields }),
 });
+const configSchemaJson = z
+    .record(z.string(), z.unknown())
+    .refine((v) => new TextEncoder().encode(JSON.stringify(v)).length <= CONFIG_UI_LIMITS.configSchemaBytes, {
+    message: `must be at most ${CONFIG_UI_LIMITS.configSchemaBytes} bytes of JSON (${CONFIG_UI_LIMITS.configSchemaBytes / 1024} KiB)`,
+});
 const extensionSection = z.strictObject({
     entry: dotPath("entry").refine((p) => p.endsWith(".mjs"), {
         message: "entry must be a .mjs file",
@@ -94,6 +100,9 @@ const extensionSection = z.strictObject({
     manifest: staticExtensionManifest,
     migrations: dotPath("migrations").optional(),
     ui: dotPath("ui").optional(),
+    configSchemas: z
+        .strictObject({ deployment: configSchemaJson.optional(), org: configSchemaJson.optional() })
+        .optional(),
 });
 const schema = z
     .strictObject({

package/dist/secret.d.ts

@@ -1,5 +1,8 @@
 import type { z } from "zod";
-/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+/**
+ * Marks a schema as a secret field (Zod 4 meta `{ secret: true }`), merging with existing meta
+ * (`ui` hints, `hot`), so `secret(ui(x, …))` and `ui(secret(x), …)` are the same.
+ */
 export declare function secret<T extends z.ZodTypeAny>(schema: T): T;
 /** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
 export declare function isSecret(schema: z.ZodTypeAny): boolean;

package/dist/secret.js

@@ -1,6 +1,9 @@
-/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+/**
+ * Marks a schema as a secret field (Zod 4 meta `{ secret: true }`), merging with existing meta
+ * (`ui` hints, `hot`), so `secret(ui(x, …))` and `ui(secret(x), …)` are the same.
+ */
 export function secret(schema) {
-    return schema.meta({ secret: true });
+    return schema.meta({ ...(schema.meta() ?? {}), secret: true });
 }
 /** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
 export function isSecret(schema) {

package/dist/skill-invocation.d.ts

@@ -37,7 +37,7 @@ export declare function renderSkillBody(body: string, invocation: SkillInvocatio
 export interface RenderSkillInvocationInput {
     /**
      * The name the person typed after `/` (`fix-issue`, or `<plugin>:<name>`): used in the lead, the
-     * `name="…"` attribute and the `skill_load` argument (where the qualified form resolves).
+     * `name="…"` attribute and the `Skill` argument (where the qualified form resolves).
      */
     name: string;
     /**
@@ -53,9 +53,9 @@ export interface RenderSkillInvocationInput {
     args: string;
     /** Decided by the caller from the agent's tools and the version's manifest. */
     lines: {
-        /** The version has files besides SKILL.md: `load` when the agent has `skill_load`. */
+        /** The version has files besides SKILL.md: `load` when the agent has `Skill`. */
         files?: "load" | "unavailable";
-        /** The body has shell injections and the agent has `sandbox_bash`. */
+        /** The body has shell injections and the agent has `Bash`. */
         shellHint?: boolean;
     };
     /** false: leave out the lead sentence (a forked skill's task for the sub-agent). Default true. */

package/dist/skill-invocation.js

@@ -180,13 +180,13 @@ export function renderSkillInvocation(i) {
     }
     parts.push(`<skill_invocation name="${escapeAttr(i.name)}" version="${i.version}">\n${body}\n</skill_invocation>`);
     if (i.lines.files === "load") {
-        parts.push(`Its files are not in the sandbox yet: call skill_load with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
+        parts.push(`Its files are not in the sandbox yet: call Skill with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
     }
     else if (i.lines.files === "unavailable") {
         parts.push("Its other files are not available in this conversation.");
     }
     if (i.lines.shellHint) {
-        parts.push("Lines written as !`command` were meant to run before you read this; run those commands with sandbox_bash if you need their output.");
+        parts.push("Lines written as !`command` were meant to run before you read this; run those commands with Bash if you need their output.");
     }
     return parts.join("\n\n");
 }

package/dist/tool-key.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model-visible tool key grammar (aligned with Claude Code):
+ *
+ * - builtin: `^[A-Z][A-Za-z]{1,31}$` (PascalCase), e.g. `Edit`
+ * - connector: `mcp__<slug>__<tool>`, e.g. `mcp__crm__search_accounts`
+ * - extension: `plugin__<plugin>__<tool>`, e.g. `plugin__todo__write`
+ *
+ * Pure functions only; extensions that match keys (hooks) use `parseToolKey` instead of splitting.
+ */
+export type ParsedToolKey = {
+    kind: "builtin";
+    name: string;
+} | {
+    kind: "connector";
+    slug: string;
+    tool: string;
+} | {
+    kind: "extension";
+    plugin: string;
+    tool: string;
+};
+export declare const BUILTIN_TOOL_NAME_RE: RegExp;
+/** Parse a tool key; `null` when it fits none of the three forms. */
+export declare function parseToolKey(key: string): ParsedToolKey | null;
+/** `mcp__<slug>__<tool>` */
+export declare function connectorToolKey(slug: string, tool: string): string;
+/** `plugin__<plugin>__<tool>` */
+export declare function extensionToolKey(plugin: string, tool: string): string;

package/dist/tool-key.js

@@ -0,0 +1,40 @@
+/**
+ * Model-visible tool key grammar (aligned with Claude Code):
+ *
+ * - builtin: `^[A-Z][A-Za-z]{1,31}$` (PascalCase), e.g. `Edit`
+ * - connector: `mcp__<slug>__<tool>`, e.g. `mcp__crm__search_accounts`
+ * - extension: `plugin__<plugin>__<tool>`, e.g. `plugin__todo__write`
+ *
+ * Pure functions only; extensions that match keys (hooks) use `parseToolKey` instead of splitting.
+ */
+export const BUILTIN_TOOL_NAME_RE = /^[A-Z][A-Za-z]{1,31}$/;
+const SEP = "__";
+/** Parse a tool key; `null` when it fits none of the three forms. */
+export function parseToolKey(key) {
+    if (!key.includes(SEP)) {
+        return BUILTIN_TOOL_NAME_RE.test(key) ? { kind: "builtin", name: key } : null;
+    }
+    const first = key.indexOf(SEP);
+    const family = key.slice(0, first);
+    if (family !== "mcp" && family !== "plugin")
+        return null;
+    const rest = key.slice(first + SEP.length);
+    const second = rest.indexOf(SEP);
+    if (second <= 0)
+        return null;
+    const owner = rest.slice(0, second);
+    const tool = rest.slice(second + SEP.length);
+    if (tool === "")
+        return null;
+    return family === "mcp"
+        ? { kind: "connector", slug: owner, tool }
+        : { kind: "extension", plugin: owner, tool };
+}
+/** `mcp__<slug>__<tool>` */
+export function connectorToolKey(slug, tool) {
+    return `mcp${SEP}${slug}${SEP}${tool}`;
+}
+/** `plugin__<plugin>__<tool>` */
+export function extensionToolKey(plugin, tool) {
+    return `plugin${SEP}${plugin}${SEP}${tool}`;
+}

package/dist/web.d.ts

@@ -0,0 +1,80 @@
+/** Web search extension point ref (`web-search@1`). */
+export declare const WEB_SEARCH_EXTENSION_POINT = "web-search@1";
+/** Web fetch extension point ref (`web-fetch@1`). */
+export declare const WEB_FETCH_EXTENSION_POINT = "web-fetch@1";
+/** One search hit. */
+export interface WebSearchResult {
+    title: string;
+    /** Absolute http / https URL. */
+    url: string;
+    /** Plain text or markdown, trimmed by the provider. */
+    snippet?: string;
+    /** ISO 8601 date or datetime, when known. */
+    publishedAt?: string;
+}
+/** A web search provider (`web-search@1`). The kernel passes the org's decrypted `orgConfig`. */
+export interface WebSearchProvider {
+    /** False when this org's config lacks what the provider needs. */
+    configured?(orgConfig: unknown): boolean;
+    search(args: {
+        query: string;
+        /** Hints only: the kernel filters the results again. */
+        allowedDomains?: string[];
+        blockedDomains?: string[];
+        maxResults: number;
+        orgConfig: unknown;
+        signal: AbortSignal;
+    }): Promise<{
+        results: WebSearchResult[];
+    }>;
+}
+/** A fetched page, converted to markdown. */
+export interface WebFetchPage {
+    /** After redirects; equal to the requested URL when there were none. */
+    finalUrl: string;
+    title?: string;
+    markdown: string;
+    contentType?: string;
+}
+/**
+ * A web fetch provider (`web-fetch@1`).
+ *
+ * The kernel checks the URL it passes and the returned `finalUrl` without DNS: it refuses IP
+ * literals in private, loopback, link-local or reserved ranges and single-label or `localhost`
+ * names. A provider that fetches from inside the deployment (rather than through a remote
+ * service) must also refuse non-public addresses after DNS resolution, for the URL and for every
+ * redirect it follows. It may reuse the kernel's rules: {@link isPublicHostname} on
+ * `new URL(url).hostname` (never a hand-parsed host), and on each resolved address it connects
+ * to (an IPv6 address in brackets, as in a URL).
+ */
+export interface WebFetchProvider {
+    /** False when this org's config lacks what the provider needs. */
+    configured?(orgConfig: unknown): boolean;
+    fetch(args: {
+        /** Already validated and upgraded by the kernel. */
+        url: string;
+        orgConfig: unknown;
+        signal: AbortSignal;
+    }): Promise<WebFetchPage>;
+}
+/**
+ * Why a web provider call failed: `not_found` (404 / no content), `blocked` (the site refused the
+ * provider), `auth` (bad credentials), `rate_limited`, `unavailable` (provider down, 5xx, timeout),
+ * `invalid` (the provider rejected the query or URL).
+ */
+export type WebProviderErrorKind = "not_found" | "blocked" | "auth" | "rate_limited" | "unavailable" | "invalid";
+/** Thrown by web providers; the kernel maps `kind` to fixed, model-visible error text. */
+export declare class WebProviderError extends Error {
+    readonly kind: WebProviderErrorKind;
+    constructor(message: string, opts: {
+        kind: WebProviderErrorKind;
+    });
+}
+/**
+ * Whether a URL hostname can name a public internet host. Pure, no DNS: false for `localhost`,
+ * single-label names, `*.localhost` / `*.local` / `*.internal`, and IP literals (IPv6 in brackets,
+ * as in a URL) in private, loopback, link-local, CGNAT, multicast, unspecified, documentation and
+ * reserved ranges, including IPv4-mapped IPv6. A name that resolves to a private address is not
+ * detected here.
+ */
+export declare function isPublicHostname(host: string): boolean;

package/dist/web.js

@@ -0,0 +1,135 @@
+/** Web search extension point ref (`web-search@1`). */
+export const WEB_SEARCH_EXTENSION_POINT = "web-search@1";
+/** Web fetch extension point ref (`web-fetch@1`). */
+export const WEB_FETCH_EXTENSION_POINT = "web-fetch@1";
+/** Thrown by web providers; the kernel maps `kind` to fixed, model-visible error text. */
+export class WebProviderError extends Error {
+    kind;
+    constructor(message, opts) {
+        super(message);
+        this.name = "WebProviderError";
+        this.kind = opts.kind;
+    }
+}
+function ipv4Octets(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!m)
+        return undefined;
+    const o = m.slice(1).map(Number);
+    return o.every((n) => n <= 255) ? o : undefined;
+}
+function isPublicIpv4(o) {
+    const [a, b, c] = o;
+    if (a === 0 || a === 10 || a === 127)
+        return false;
+    if (a === 100 && b >= 64 && b <= 127)
+        return false; // CGNAT
+    if (a === 169 && b === 254)
+        return false;
+    if (a === 172 && b >= 16 && b <= 31)
+        return false;
+    if (a === 192 && b === 168)
+        return false;
+    if (a === 192 && b === 0 && (c === 0 || c === 2))
+        return false; // IETF protocol, TEST-NET-1
+    if (a === 192 && b === 88 && c === 99)
+        return false; // 6to4 relay
+    if (a === 198 && (b === 18 || b === 19))
+        return false; // benchmarking
+    if (a === 198 && b === 51 && c === 100)
+        return false; // TEST-NET-2
+    if (a === 203 && b === 0 && c === 113)
+        return false; // TEST-NET-3
+    if (a >= 224)
+        return false; // multicast, reserved, broadcast
+    return true;
+}
+/** Parses an IPv6 literal (no brackets) into eight 16-bit groups, or undefined. */
+function ipv6Groups(host) {
+    let s = host;
+    const zone = s.indexOf("%");
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(s);
+    if (tail) {
+        const o = ipv4Octets(tail[1]);
+        if (!o)
+            return undefined;
+        s = `${s.slice(0, tail.index)}${((o[0] << 8) | o[1]).toString(16)}:${((o[2] << 8) | o[3]).toString(16)}`;
+    }
+    if (!/^[0-9a-f:]+$/i.test(s) || s.split("::").length > 2)
+        return undefined;
+    const [head = "", rest] = s.split("::");
+    const h = head === "" ? [] : head.split(":");
+    const t = rest === undefined || rest === "" ? [] : rest.split(":");
+    const parts = [...h, ...t];
+    if (!parts.every((p) => /^[0-9a-f]{1,4}$/i.test(p)))
+        return undefined;
+    let groups;
+    if (rest === undefined) {
+        if (h.length !== 8)
+            return undefined;
+        groups = h;
+    }
+    else {
+        if (h.length + t.length > 7)
+            return undefined;
+        groups = [...h, ...new Array(8 - h.length - t.length).fill("0"), ...t];
+    }
+    return groups.map((g) => Number.parseInt(g, 16));
+}
+function isPublicIpv6(g) {
+    const [g0, g1, g2, g3, g4, g5, g6, g7] = g;
+    const zeros5 = g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0;
+    if (zeros5 && g5 === 0 && g6 === 0 && (g7 === 0 || g7 === 1))
+        return false; // :: and ::1
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): judge the embedded address.
+    if (zeros5 && (g5 === 0xffff || g5 === 0)) {
+        return isPublicIpv4([g6 >> 8, g6 & 255, g7 >> 8, g7 & 255]);
+    }
+    if ((g0 & 0xfe00) === 0xfc00)
+        return false; // unique local fc00::/7
+    if ((g0 & 0xffc0) === 0xfe80)
+        return false; // link-local fe80::/10
+    if ((g0 & 0xffc0) === 0xfec0)
+        return false; // site-local (deprecated)
+    if ((g0 & 0xff00) === 0xff00)
+        return false; // multicast
+    if (g0 === 0x2001 && g1 === 0x0db8)
+        return false; // documentation
+    if (g0 === 0x0064 && g1 === 0xff9b)
+        return isPublicIpv4([g6 >> 8, g6 & 255, g7 >> 8, g7 & 255]); // NAT64
+    if (g0 === 0x2002)
+        return isPublicIpv4([g1 >> 8, g1 & 255, g2 >> 8, g2 & 255]); // 6to4
+    return true;
+}
+/**
+ * Whether a URL hostname can name a public internet host. Pure, no DNS: false for `localhost`,
+ * single-label names, `*.localhost` / `*.local` / `*.internal`, and IP literals (IPv6 in brackets,
+ * as in a URL) in private, loopback, link-local, CGNAT, multicast, unspecified, documentation and
+ * reserved ranges, including IPv4-mapped IPv6. A name that resolves to a private address is not
+ * detected here.
+ */
+export function isPublicHostname(host) {
+    let h = host.trim().toLowerCase();
+    if (h.endsWith("."))
+        h = h.slice(0, -1);
+    if (h === "")
+        return false;
+    if (h.startsWith("[")) {
+        if (!h.endsWith("]"))
+            return false;
+        const g = ipv6Groups(h.slice(1, -1));
+        return g !== undefined && isPublicIpv6(g);
+    }
+    const o = ipv4Octets(h);
+    if (o)
+        return isPublicIpv4(o);
+    if (/^[\d.]+$/.test(h))
+        return false; // malformed or shorthand numeric host
+    if (!h.includes("."))
+        return false;
+    if (h === "localhost" || /\.(localhost|local|internal)$/.test(h))
+        return false;
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.2",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {

package/schemas/plugin.v1.schema.json

@@ -310,6 +310,26 @@
           "minLength": 3,
           "maxLength": 512,
           "pattern": "^\\.\\/"
+        },
+        "configSchemas": {
+          "type": "object",
+          "properties": {
+            "deployment": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            },
+            "org": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {}
+            }
+          },
+          "additionalProperties": false
         }
       },
       "required": [