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

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

@@ -1,6 +1,7 @@
 import type { Kysely } from "kysely";
 import type { ExtensionPointRef } from "./extension-point.js";
 import type { AvailableHook, HookHandler, HookOptions } from "./hooks.js";
+import type { ModelEmbeddingInfo, ModelKind } from "./model.js";
 import type { ObjectHead, PresignedUpload, PresignGetOptions } from "./storage.js";
 import type { ToolHandler, ToolSpec } from "./tool.js";
 import type { EmbedClaims, UiActionArgs, UiActionResult, UiRenderArgs, UiView } from "./ui.js";
@@ -58,6 +59,65 @@ export interface ExtensionStorage {
         ttlSeconds: number;
     }): Promise<PresignedUpload>;
 }
+/** A `ctx.models.embed` request: texts embedded for one org with the model mapped to a purpose. */
+export interface ExtensionEmbedRequest {
+    orgId: string;
+    /** A purpose this extension declared in `permissions.models` with `kind: "embedding"`. */
+    purpose: string;
+    /** The texts, one vector each; split into batches by the model's `maxBatch` by the kernel. */
+    input: string[];
+    /** One of the model's `embedding.dimensions`; the model's default when absent. */
+    dimensions?: number;
+    inputType?: "query" | "document";
+    /**
+     * Aborts this call (e.g. the tool call's `signal`); combined with `ctx.signal`. Batches not yet
+     * sent are not sent; batches already answered are still recorded as usage.
+     */
+    signal?: AbortSignal;
+}
+/** A `ctx.models.embed` result. */
+export interface ExtensionEmbedResult {
+    /** One vector per input, in input order. */
+    vectors: number[][];
+    /** The model that made them (a changed model invalidates stored vectors). */
+    model: {
+        provider: string;
+        id: string;
+    };
+    dimensions: number;
+}
+/** The model a purpose maps to in an org (`ctx.models.describe`). */
+export interface ExtensionModelTarget {
+    provider: string;
+    id: string;
+    kind: ModelKind;
+    /** Present for an embedding model. */
+    embedding?: ModelEmbeddingInfo;
+}
+/**
+ * Models by purpose (`permissions.models`): the purpose → model mapping is chosen by org admins
+ * (and the deployment default by the super admin), never by the extension. Only purposes this
+ * extension declared with `kind: "embedding"` are accepted (`model.purpose_unknown` otherwise), and
+ * only for an org that enabled the extension (`extension.not_enabled`). Usage is recorded by the
+ * kernel and reported through `usage.report` (purpose `embedding`).
+ */
+export interface ExtensionModels {
+    /**
+     * Embeds `input` with the org's effective model for `purpose`. Rejects with `model.unconfigured`
+     * when the purpose maps to no model the org can use, `validation_failed` for dimensions the model
+     * lacks, and a `ModelError` when the provider fails (a result of the wrong count or dimension is a
+     * `ModelError` of kind `server`). Not retried by the kernel. Each call fires the `model.request`
+     * hook first (`purpose: "embedding"`, every text of the call): when a policy hook denies it, the
+     * call rejects with an error whose `code` is `model.hook_denied` (HTTP 403 if it escapes an
+     * extension route), and nothing is sent or billed.
+     */
+    embed(req: ExtensionEmbedRequest): Promise<ExtensionEmbedResult>;
+    /** The org's effective model for `purpose`, or null when it maps to no model the org can use. */
+    describe(req: {
+        orgId: string;
+        purpose: string;
+    }): Promise<ExtensionModelTarget | null>;
+}
 /** 传给插件 `setup` 的上下文。不提供定时器与进程内共享状态；kv 写入必须带 TTL。 */
 export interface ExtensionContext {
     kv: {
@@ -94,6 +154,8 @@ export interface ExtensionContext {
     };
     /** 对象存储（需 `permissions.storage`，见 {@link ExtensionStorage}）。 */
     storage: ExtensionStorage;
+    /** Models by purpose (requires `permissions.models`, see {@link ExtensionModels}). */
+    models: ExtensionModels;
     /** 已切到本插件 schema（withSchema）的 Kysely 实例。 */
     db: Kysely<any>;
     http: {
@@ -109,7 +171,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.
      */