@capybara-hq/plugin-sdk 0.1.0-rc.2 → 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

@@ -105,7 +105,8 @@ export declare function ui<T extends z.ZodTypeAny>(schema: T, hints: ConfigUiHin
 /**
  * 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`
+ * - 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;

package/dist/config-ui.js

@@ -48,7 +48,8 @@ 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`
+ * - 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;
@@ -68,6 +69,9 @@ export function configJsonSchema(schema) {
             if (js.hot === true)
                 js["x-hot"] = true;
             delete js.hot;
+            if (js.org !== undefined)
+                js["x-org"] = js.org;
+            delete js.org;
             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));
@@ -275,8 +279,21 @@ export function validateConfigUi(schema, level) {
         }
         return node;
     };
-    const visit = (node, path, isRoot) => {
+    const visit = (node, path, isRoot, depth) => {
         const report = (message) => problems.push({ path, message });
+        if (node["x-org"] !== undefined) {
+            const org = node["x-org"];
+            if (level !== "deployment")
+                report(`x-org is only allowed at the deployment level, not ${level}`);
+            else if (depth !== 1)
+                report("x-org is only allowed on a top-level field of the config");
+            else if (org !== "readonly" && org !== "override") {
+                report(`x-org must be "readonly" or "override", not ${JSON.stringify(org)}`);
+            }
+            else if (org === "readonly" && node["x-secret"] === true) {
+                report('x-org "readonly" on a secret field: an org never sees a secret, so there is nothing to show');
+            }
+        }
         const text = (value, what, max, plainOk = false) => {
             if (value === undefined)
                 return;
@@ -316,13 +333,14 @@ export function validateConfigUi(schema, level) {
         if (isObj(props)) {
             for (const [k, child] of Object.entries(props)) {
                 if (isObj(child))
-                    visit(child, path === "" ? k : `${path}.${k}`, false);
+                    visit(child, path === "" ? k : `${path}.${k}`, false, depth + 1);
             }
         }
-        if (isObj(shape.items))
-            visit(shape.items, path === "" ? "items" : `${path}.items`, false);
+        if (isObj(shape.items)) {
+            visit(shape.items, path === "" ? "items" : `${path}.items`, false, depth + 1);
+        }
         if (isObj(shape.additionalProperties)) {
-            visit(shape.additionalProperties, path === "" ? "additionalProperties" : `${path}.additionalProperties`, false);
+            visit(shape.additionalProperties, path === "" ? "additionalProperties" : `${path}.additionalProperties`, false, depth + 1);
         }
     };
     const checkHints = (h, node, isRoot, report, text) => {
@@ -573,7 +591,7 @@ export function validateConfigUi(schema, level) {
                 });
         }
     };
-    visit(schema, "", true);
+    visit(schema, "", true, 0);
     if (hintsBytes > L.hintsBytes) {
         problems.push({
             path: "",

package/dist/ctx.d.ts

@@ -109,7 +109,9 @@ export interface ExtensionContext {
      * manifest's `requires` / `optional`. Without `orgId` it is the deployment-level view and returns
      * synchronously; with `orgId` it returns a Promise, and orgScoped extension points (such as
      * `channel`, `directory`) are filtered by that org's enablement (queried every time, not cached);
-     * `get` rejects with `ExtensionPointUnavailableError` when the provider is not enabled in that org.
+     * with `orgId`, a provider whose effective config is not valid in that org is excluded too;
+     * `get` rejects with `ExtensionPointUnavailableError` when the provider is not enabled in that
+     * org or its config is not valid there.
      * When there is no provider, `get` throws `ExtensionPointUnavailableError` and `list` returns an
      * empty list.
      */

package/dist/directory.d.ts

@@ -15,11 +15,20 @@ export interface Directory {
      * treats the directory as "not configured": the hourly scan, `directory_changed` and the
      * pre-removal recheck are skipped silently (no job, no audit, no warning), and a manual sync by an
      * admin returns 409 `directory.not_configured`. When not implemented, any config that satisfies
-     * the schema counts as configured. Must be a pure function (no requests, never throws).
+     * the schema counts as configured. Must be a pure function (no requests, never throws). `config`
+     * is the effective deployment config for the org (see `listMembers`' `config`).
      */
-    configured?(orgConfig: unknown): boolean;
+    configured?(orgConfig: unknown, config?: unknown): boolean;
     listMembers(args: {
         orgConfig: unknown;
+        /**
+         * The extension's effective deployment config for this org: the platform's deployment config
+         * with the org's copy applied to the overridable fields (`orgAccess(…, "override")`), or the
+         * platform's config (equal to `ctx.config`) while the org follows it. Use it, not `ctx.config`,
+         * for work done for this org. Optional in the type so older extensions compile; the kernel
+         * always passes it.
+         */
+        config?: unknown;
         cursor?: string;
         signal: AbortSignal;
     }): Promise<{

package/dist/extension-point.d.ts

@@ -4,11 +4,15 @@ export type ExtensionPointRef = `${string}@${number}`;
 export type Cardinality = "single" | "multi";
 /** Registry entry of an extension point. */
 export interface ExtensionPointInfo {
+    /** What the extension point is for, in one sentence (served to agents by the Platform tool). */
+    description: string;
     cardinality: Cardinality;
     /** Brokered by the platform API (extensions may not `requires` it; they use it only through `ctx`). */
     brokered: boolean;
     /** Enabled per org (consumers may pass `orgId` to check that the org enabled the provider). */
     orgScoped: boolean;
+    /** The majors of this point the kernel accepts; a plugin providing any other major is refused. */
+    majors: readonly number[];
     /**
      * 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).

package/dist/extension-point.js

@@ -1,4 +1,6 @@
-const info = (cardinality, brokered = false, orgScoped = false, selection) => ({
+const info = (majors, description, cardinality, brokered = false, orgScoped = false, selection) => ({
+    majors,
+    description,
     cardinality,
     brokered,
     orgScoped,
@@ -6,19 +8,19 @@ const info = (cardinality, brokered = false, orgScoped = false, selection) => ({
 });
 /** The registered extension points. */
 export const EXTENSION_POINTS = {
-    sandbox: info("single", true),
-    "config-source": info("single"),
-    "secret-store": info("single", true),
-    "object-store": info("single", true),
-    channel: info("multi", false, true),
-    "model-provider": info("multi", true),
-    "identity-source": info("multi"),
-    directory: info("multi", false, true),
-    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"),
+    sandbox: info([2], "Runs an environment's instance and keeps its files for agents' commands (Docker, E2B).", "single", true),
+    "config-source": info([1], "Supplies deployment configuration from an external store such as Nacos.", "single"),
+    "secret-store": info([1], "Stores and resolves secrets (connector credentials, secret config) outside the database.", "single", true),
+    "object-store": info([1], "Stores files and artifacts in S3-compatible object storage, with presigned uploads.", "single", true),
+    channel: info([1], "Connects an instant-messaging platform (Slack, Lark): inbound events, replies and cards.", "multi", false, true),
+    "model-provider": info([1, 2], "Calls a model vendor's API and streams the result back to the runtime.", "multi", true),
+    "identity-source": info([1], "Signs people in through an external identity provider (SSO).", "multi"),
+    directory: info([1], "Syncs members and departments from an external company directory.", "multi", false, true),
+    counter: info([1], "Counts usage so quotas and reports can be built on it.", "multi"),
+    connector: info([1], "Speaks one protocol (MCP, OpenAPI) to external systems and exposes their tools to agents.", "multi", true),
+    "file-preview": info([1], "Renders previews of files of given types in the conversation UI.", "multi", false, true),
+    "web-search": info([1], "Searches the web for the WebSearch tool; each org picks a default provider.", "multi", true, true, "org-default"),
+    "web-fetch": info([1], "Fetches and extracts web pages for the WebFetch tool; each org picks a default provider.", "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]));