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

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]));

package/dist/file-preview.d.ts

@@ -53,6 +53,14 @@ export interface FilePreviewArgs {
      * rejects a file over the previewer's `maxBytes`. The extension never gets a storage key or URL.
      */
     read(): Promise<Uint8Array>;
+    /**
+     * 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;
 }
 /** Checks a `file-preview@1` provider; returns the problems (empty = valid). */
 export declare function validateFilePreviewProvider(p: unknown): string[];

package/dist/hooks.d.ts

@@ -39,8 +39,12 @@ export interface HookScope {
  * `WebFetch` tool.
  */
 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;
+/**
+ * What a reported or requested model call was for: the {@link ModelCallPurpose} values, or
+ * `embedding` for an embedding call an extension made through `ctx.models` (`usage.report`, and
+ * `model.request` with {@link EmbeddingRequestHookPayload}; never `model.response`).
+ */
+export type UsagePurpose = ModelCallPurpose | "embedding";
 /**
  * An image or document of a `model.request` payload. Hook payloads never carry media bytes or
  * attachment ids: each image or document block is replaced by this placeholder.
@@ -74,14 +78,15 @@ export type HookModelRequest = Omit<ModelRequest, "messages"> & {
     messages: HookModelMessage[];
 };
 /**
- * `model.request`: before a model call is sent. A policy hook may deny it. Fires once per attempt of a
- * step (`purpose: "step"`), once for each compaction call (`purpose: "compaction"`, `attempt` 1) and
+ * `model.request` of a chat model call (see {@link ModelRequestHookPayload}): once per attempt of a
+ * step (`purpose: "step"`), once for each compaction call (`purpose: "compaction"`, `attempt` 1),
  * once for each conversation title call (`purpose: "title"`, `runId` "", `step` 0, `attempt` 1; a
- * denial skips the title and is recorded only in the audit log).
+ * denial skips the title and is recorded only in the audit log) and once for each `WebFetch`
+ * extraction call (`purpose: "web_fetch"`).
  * `request` is the request as sent, except that images and documents are placeholders
  * ({@link HookMediaPlaceholder}): no media bytes, no attachment ids.
  */
-export interface ModelRequestHookPayload extends HookScope {
+export interface ModelCallRequestHookPayload extends HookScope {
     purpose: ModelCallPurpose;
     step: number;
     attempt: number;
@@ -89,6 +94,45 @@ export interface ModelRequestHookPayload extends HookScope {
     model: string;
     request: Readonly<HookModelRequest>;
 }
+/**
+ * `model.request` of an embedding call an extension made through `ctx.models.embed`
+ * (`purpose: "embedding"`): fired once per `embed` call, before the first batch is sent, with every
+ * text of the call (the kernel splits them into batches afterwards). A call with no input sends
+ * nothing and fires nothing. There is no conversation: the conversation fields of a chat model call
+ * (`accountId`, `agentId`, `agentVersion`, `conversationId`, `runId`, `parent`, `step`, `attempt`,
+ * `request`) are absent. A policy denial makes `embed` reject (`model.hook_denied`); nothing is sent
+ * to the provider and no usage is recorded.
+ */
+export interface EmbeddingRequestHookPayload {
+    purpose: "embedding";
+    orgId: string;
+    /** The extension that called `ctx.models.embed`. */
+    extension: string;
+    /** The embedding purpose the extension called with (one it declared in `permissions.models`). */
+    embeddingPurpose: string;
+    provider: string;
+    model: string;
+    /** The texts of the call, in order (text only). */
+    input: readonly string[];
+    /** The dimensions the extension asked for, when it asked. */
+    dimensions?: number;
+    /** The input type the extension gave, when it gave one. */
+    inputType?: "query" | "document";
+    accountId?: undefined;
+    agentId?: undefined;
+    agentVersion?: undefined;
+    conversationId?: undefined;
+    runId?: undefined;
+    parent?: undefined;
+}
+/**
+ * `model.request`: before a model call is sent. A policy hook may deny it. Either a chat model call
+ * ({@link ModelCallRequestHookPayload}: steps, compaction, titles, `WebFetch`) or an extension's
+ * embedding call ({@link EmbeddingRequestHookPayload}, `purpose: "embedding"`); tell them apart by
+ * `purpose`. Handlers must accept the absent conversation fields of an embedding call (a policy
+ * hook that throws on one denies the call). Payloads carry no media bytes.
+ */
+export type ModelRequestHookPayload = ModelCallRequestHookPayload | EmbeddingRequestHookPayload;
 /**
  * `model.response`: after a sent model call finished or failed, with its usage when known (step
  * attempts, compaction and title calls, see `purpose`). Not fired for a call the user aborted (the run was
@@ -138,12 +182,18 @@ export interface UsageReportPayload {
      */
     purpose: UsagePurpose;
     orgId: string;
-    accountId: string;
-    agentId: string;
-    conversationId: string;
-    /** A sub-agent's calls report `chat`; `parent` tells them apart. */
-    conversationKind: "chat" | "eval";
-    runId: string;
+    /** Absent for `embedding`. */
+    accountId?: string;
+    /** Absent for `embedding`. */
+    agentId?: string;
+    /** Absent for `embedding`. */
+    conversationId?: string;
+    /** A sub-agent's calls report `chat`; `parent` tells them apart. Absent for `embedding`. */
+    conversationKind?: "chat" | "eval";
+    /** Absent for `embedding`. */
+    runId?: string;
+    /** The calling extension; set for `embedding`. */
+    extension?: string;
     /** Set when the call belongs to a sub-agent: where it was dispatched from. */
     parent?: HookParentScope;
     provider: string;
@@ -169,9 +219,18 @@ export type HookVerdict = void | {
 };
 /**
  * A hook handler. The payload is a deep-frozen copy (mutating it throws). `signal` aborts when the
- * hook runs past `hooks.timeoutMs` or the call it observes is aborted.
+ * hook runs past `hooks.timeoutMs` or the call it observes is aborted. `call.config` is the
+ * extension's effective deployment config for the payload's org (the platform's config with the
+ * org's copy applied to the overridable fields, or `ctx.config` while the org follows it); the
+ * kernel always passes it, and never calls a hook for an org where that config is not valid
+ * (observe hooks are skipped, policy hooks deny).
  */
-export type HookHandler<K extends AvailableHook> = (payload: HookPayloads[K], signal: AbortSignal) => Promise<HookVerdict> | HookVerdict;
+export type HookHandler<K extends AvailableHook> = (payload: HookPayloads[K], signal: AbortSignal, call?: HookCall) => Promise<HookVerdict> | HookVerdict;
+/** The per-call context of a hook handler (see {@link HookHandler}). */
+export interface HookCall {
+    /** The extension's effective deployment config for the payload's org. */
+    config: unknown;
+}
 /**
  * - `policy` (only on {@link POLICY_HOOKS}): policy hooks run serially by plugin name (registration
  *   order within a plugin) before the call; the first `{ deny }`, error or timeout blocks the call and

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.2";
+export declare const SDK_VERSION = "0.1.0-rc.4";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -16,6 +16,7 @@ export * from "./identity.js";
 export * from "./marketplace.js";
 export * from "./model.js";
 export * from "./model-params.js";
+export * from "./org-access.js";
 export * from "./permissions.js";
 export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.2";
+export const SDK_VERSION = "0.1.0-rc.4";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -16,6 +16,7 @@ export * from "./identity.js";
 export * from "./marketplace.js";
 export * from "./model.js";
 export * from "./model-params.js";
+export * from "./org-access.js";
 export * from "./permissions.js";
 export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";

package/dist/marketplace.d.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
 /**
  * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
- * each with one source. One entry is one version: a marketplace that offers several versions lists
- * the plugin once per version, so `(name, marketplaceEntryVersion)` is unique in a manifest.
+ * each with one source. One entry is one version. `capybara-plugin marketplace --write` lists one
+ * entry per plugin, its current version (plugin component management spec §13.2); readers still
+ * accept several versions of a plugin (marketplaces written in the older form), so
+ * `(name, marketplaceEntryVersion)` is unique in a manifest.
  *
  * Sources: a same-repo `path`, a `git` repo, an `npm` package (exact version + sha512, downloads
  * are verified against it, never npm metadata) or an `archive` URL (sha512 or sha256 SRI).
@@ -19,6 +21,10 @@ export declare const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
 export declare const MARKETPLACE_LIMITS: {
     readonly nameChars: 100;
     readonly summaryChars: 280;
+    /** Characters of each `displayName` language (as `plugin.json`'s). */
+    readonly displayNameChars: 100;
+    /** Characters of a `deprecated.reason`. */
+    readonly deprecationReasonChars: 280;
     readonly plugins: 5000;
     readonly permissionKeys: 500;
     readonly urlChars: 2000;
@@ -53,6 +59,11 @@ export interface MarketplaceEntry {
         en: string;
         zh?: string;
     };
+    /** Display name (the plugin's `plugin.json` `displayName`); lists show it, else the name. */
+    displayName?: {
+        zh: string;
+        en: string;
+    };
     /** Exact semver; defaults to the npm source's version, otherwise the plugin's own. */
     version?: string;
     /** Exact semver. */
@@ -64,6 +75,15 @@ export interface MarketplaceEntry {
     };
     /** https URL. */
     homepage?: string;
+    /**
+     * This version is deprecated (`true`, or with a reason shown to admins): browsing lists it under
+     * the plugin's other versions, never as the one to import, and the kernel refuses importing it
+     * (`marketplace.entry_deprecated`). Set by hand on the entry by the marketplace maintainer;
+     * `capybara-plugin marketplace --write` keeps it. `false` is the same as absent.
+     */
+    deprecated?: boolean | {
+        reason?: string;
+    };
     source: MarketplaceSource;
 }
 /** `marketplace.json`. */
@@ -97,3 +117,10 @@ export declare function parseMarketplaceManifest(json: unknown, opts?: Marketpla
 };
 /** The entry's version: `version`, else the npm source's version, else `null` (the plugin's own). */
 export declare function marketplaceEntryVersion(e: MarketplaceEntry): string | null;
+/**
+ * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
+ * deprecated (absent or `false`), else its reason (`null` without one).
+ */
+export declare function marketplaceEntryDeprecation(e: MarketplaceEntry): {
+    reason: string | null;
+} | null;

package/dist/marketplace.js

@@ -2,8 +2,10 @@ import { z } from "zod";
 import { CATALOG_ITEM_NAME_RE, isSafePackagePath, NPM_PACKAGE_NAME_RE, SEMVER_VERSION_RE, SHA512_INTEGRITY_RE, } from "./plugin-package.js";
 /**
  * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
- * each with one source. One entry is one version: a marketplace that offers several versions lists
- * the plugin once per version, so `(name, marketplaceEntryVersion)` is unique in a manifest.
+ * each with one source. One entry is one version. `capybara-plugin marketplace --write` lists one
+ * entry per plugin, its current version (plugin component management spec §13.2); readers still
+ * accept several versions of a plugin (marketplaces written in the older form), so
+ * `(name, marketplaceEntryVersion)` is unique in a manifest.
  *
  * Sources: a same-repo `path`, a `git` repo, an `npm` package (exact version + sha512, downloads
  * are verified against it, never npm metadata) or an `archive` URL (sha512 or sha256 SRI).
@@ -20,6 +22,10 @@ export const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
 export const MARKETPLACE_LIMITS = {
     nameChars: 100,
     summaryChars: 280,
+    /** Characters of each `displayName` language (as `plugin.json`'s). */
+    displayNameChars: 100,
+    /** Characters of a `deprecated.reason`. */
+    deprecationReasonChars: 280,
     plugins: 5000,
     permissionKeys: 500,
     urlChars: 2000,
@@ -123,6 +129,12 @@ function buildSchema(opts) {
             en: z.string().min(1).max(M.summaryChars),
             zh: z.string().min(1).max(M.summaryChars).optional(),
         }),
+        displayName: z
+            .object({
+            zh: z.string().min(1).max(M.displayNameChars),
+            en: z.string().min(1).max(M.displayNameChars),
+        })
+            .optional(),
         version: exactVersion("version").optional(),
         minKernel: exactVersion("minKernel").optional(),
         permissions: z
@@ -132,6 +144,12 @@ function buildSchema(opts) {
         })
             .optional(),
         homepage: urlString(HTTPS_URL_RE).optional(),
+        deprecated: z
+            .union([
+            z.boolean(),
+            z.object({ reason: z.string().min(1).max(M.deprecationReasonChars).optional() }),
+        ])
+            .optional(),
         source,
     });
     return z
@@ -254,3 +272,13 @@ export function marketplaceEntryVersion(e) {
         return e.source.npm.version;
     return null;
 }
+/**
+ * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
+ * deprecated (absent or `false`), else its reason (`null` without one).
+ */
+export function marketplaceEntryDeprecation(e) {
+    const d = e.deprecated;
+    if (d === undefined || d === false)
+        return null;
+    return { reason: d === true ? null : (d.reason ?? null) };
+}

package/dist/model.d.ts

@@ -4,9 +4,32 @@
  * 见 `model-params.ts`）；旧契约 `model-provider@1`（`ModelProviderV1` 等）由内核经适配层继续支持。
  */
 import type { Effort, ModelParameter, ParamValue } from "./model-params.js";
+import type { LocalizedName } from "./plugin-package.js";
+/** What a model does. Absent on a `ModelInfo` means `chat`. */
+export type ModelKind = "chat" | "embedding" | "rerank" | "image_generation" | "video_generation" | "speech_to_text" | "text_to_speech";
+/** Embedding facts of a model whose `kind` is `embedding`. */
+export interface ModelEmbeddingInfo {
+    /** The output dimensions the model can produce (a single entry when not adjustable). */
+    dimensions: number[];
+    defaultDimensions: number;
+    /** Most tokens one input may hold. */
+    maxInputTokens: number;
+    /** Most inputs one `embed` call may carry. */
+    maxBatch: number;
+}
 export interface ModelInfo {
     id: string;
     displayName: string;
+    /** Defaults to `chat`. Chat-only fields below stay required for every kind. */
+    kind?: ModelKind;
+    /** Who made the model (display only). */
+    publisher?: string;
+    /** Display only. */
+    description?: LocalizedName | string;
+    /** ISO date after which the model is retired (display only). */
+    retiresAt?: string;
+    /** Set when `kind` is `embedding`. */
+    embedding?: ModelEmbeddingInfo;
     contextWindow: number;
     maxOutputTokens: number;
     capabilities: {
@@ -206,14 +229,49 @@ export declare class ModelError extends Error {
     /** rate_limited / overloaded / server / timeout / network 为 true。 */
     get retryable(): boolean;
 }
+/**
+ * Options of a model call made for an organization.
+ * `config` is 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 providers compile; the kernel always passes
+ * both.
+ */
+export interface ModelCallOptions {
+    orgId?: string;
+    config?: unknown;
+}
+export interface EmbedRequest {
+    model: string;
+    input: string[];
+    /** One of the model's `embedding.dimensions`; the model's default when absent. */
+    dimensions?: number;
+    inputType?: "query" | "document";
+}
+export interface EmbedResult {
+    /** One vector per input, in input order. */
+    vectors: number[][];
+    usage: {
+        inputTokens: number;
+    };
+}
+/**
+ * Checks an embedding result against its request and the model's embedding facts. Returns null when
+ * valid, else the reason: wrong vector count, wrong dimension, or a non-finite number.
+ */
+export declare function validateEmbedResult(req: EmbedRequest, info: ModelEmbeddingInfo, res: EmbedResult): string | null;
 /** `model-provider@2` 的实现。 */
 export interface ModelProvider {
     /** 每个模型的 `parameters` 须通过 `assertValidDeclarations`，否则内核不使用该供应商。 */
-    listModels(): Promise<ModelInfo[]>;
+    listModels(opts?: ModelCallOptions): Promise<ModelInfo[]>;
     /** 事件序列必须以且仅以一个 message_complete 结束；出错抛 ModelError。 */
     stream(req: ModelRequest, opts: {
         signal: AbortSignal;
-    }): AsyncIterable<ModelStreamEvent>;
+    } & ModelCallOptions): AsyncIterable<ModelStreamEvent>;
+    /** Present only on a provider that lists `embedding` models. */
+    embed?(req: EmbedRequest, opts: {
+        signal: AbortSignal;
+    } & ModelCallOptions): Promise<EmbedResult>;
 }
 /** `model-provider@1` 的实现（旧契约，内核经适配层接入：effort 由 `capabilities.effort` 推导）。 */
 export interface ModelProviderV1 {

package/dist/model.js

@@ -148,5 +148,27 @@ export class ModelError extends Error {
         return isRetryableKind(this.kind);
     }
 }
+/**
+ * Checks an embedding result against its request and the model's embedding facts. Returns null when
+ * valid, else the reason: wrong vector count, wrong dimension, or a non-finite number.
+ */
+export function validateEmbedResult(req, info, res) {
+    if (res.vectors.length !== req.input.length) {
+        return `vector count ${res.vectors.length} does not match input count ${req.input.length}`;
+    }
+    const dims = req.dimensions ?? info.defaultDimensions;
+    for (let i = 0; i < res.vectors.length; i++) {
+        const v = res.vectors[i];
+        if (v.length !== dims) {
+            return `vector ${i} has dimension ${v.length}, expected ${dims}`;
+        }
+        for (const x of v) {
+            if (typeof x !== "number" || !Number.isFinite(x)) {
+                return `vector ${i} holds a non-finite number`;
+            }
+        }
+    }
+    return null;
+}
 export const MODEL_PROVIDER_EXTENSION_POINT = "model-provider@1";
 export const MODEL_PROVIDER_EXTENSION_POINT_V2 = "model-provider@2";

package/dist/org-access.d.ts

@@ -0,0 +1,27 @@
+import type { z } from "zod";
+/**
+ * How an org may treat a deployment config field: `readonly` (the org sees it, never sets it) or
+ * `override` (an org may set its own value). A field without a level is deployment-only.
+ */
+export type OrgAccess = "readonly" | "override";
+/**
+ * Marks a deployment config field with an org access level (Zod 4 meta `{ org: access }`), merging
+ * with existing meta (`secret`, `hot`, `ui`), so `orgAccess(secret(x), …)` and
+ * `secret(orgAccess(x, …))` are the same. `configJsonSchema` publishes it as `"x-org"`.
+ *
+ * The author's promise for `override`: the extension reads the field from the per-call `config`
+ * the kernel passes with each request, not from `ctx.config`, and the field may be absent from
+ * `ctx.config` (the deployment value is the default, which an org may replace per call).
+ *
+ * The per-call config of an org that has its own copy still contains the platform's hidden
+ * (platform-only) secrets, which an org cannot set; it never contains an overridable platform
+ * secret. Never send a hidden secret to an endpoint taken from an overridable field: an org could
+ * point that endpoint at a server it controls.
+ */
+export declare function orgAccess<T extends z.ZodTypeAny>(schema: T, access: OrgAccess): T;
+/**
+ * The org access level of a schema's meta, or undefined when it has none. It sees through
+ * `.optional()`, `.default()`, `.nullable()`, `.prefault()`, `.catch()` and `.readonly()` (the
+ * outermost level wins), so it agrees with the `"x-org"` that `configJsonSchema` publishes.
+ */
+export declare function orgAccessOf(schema: z.ZodTypeAny): OrgAccess | undefined;

package/dist/org-access.js

@@ -0,0 +1,35 @@
+/**
+ * Marks a deployment config field with an org access level (Zod 4 meta `{ org: access }`), merging
+ * with existing meta (`secret`, `hot`, `ui`), so `orgAccess(secret(x), …)` and
+ * `secret(orgAccess(x, …))` are the same. `configJsonSchema` publishes it as `"x-org"`.
+ *
+ * The author's promise for `override`: the extension reads the field from the per-call `config`
+ * the kernel passes with each request, not from `ctx.config`, and the field may be absent from
+ * `ctx.config` (the deployment value is the default, which an org may replace per call).
+ *
+ * The per-call config of an org that has its own copy still contains the platform's hidden
+ * (platform-only) secrets, which an org cannot set; it never contains an overridable platform
+ * secret. Never send a hidden secret to an endpoint taken from an overridable field: an org could
+ * point that endpoint at a server it controls.
+ */
+export function orgAccess(schema, access) {
+    return schema.meta({ ...(schema.meta() ?? {}), org: access });
+}
+/** The wrappers a field's org level is read through, as `configJsonSchema` inherits meta. */
+const WRAPPERS = new Set(["default", "prefault", "optional", "nullable", "readonly", "catch"]);
+/**
+ * The org access level of a schema's meta, or undefined when it has none. It sees through
+ * `.optional()`, `.default()`, `.nullable()`, `.prefault()`, `.catch()` and `.readonly()` (the
+ * outermost level wins), so it agrees with the `"x-org"` that `configJsonSchema` publishes.
+ */
+export function orgAccessOf(schema) {
+    let node = schema;
+    while (node) {
+        const v = node.meta()?.org;
+        if (v === "readonly" || v === "override")
+            return v;
+        const def = node._zod.def;
+        node = WRAPPERS.has(def.type) ? def.innerType : undefined;
+    }
+    return undefined;
+}

package/dist/permissions.d.ts

@@ -22,7 +22,10 @@ export interface ExtensionPermissions {
      * on a replica, calls on these mount points fail closed there.
      */
     policyHooks?: PolicyHook[];
-    /** 预留：模型用途，键须为 `<插件名>.<名称>`。 */
+    /**
+     * Model purposes (`ctx.models`): each key must be `<extension name>.<name>`; an org admin maps
+     * each to a model of its `kind`. `ctx.models.embed` / `describe` accept the `embedding` ones.
+     */
     models?: {
         purpose: string;
         kind: "chat" | "embedding";

package/dist/plugin-manifest.d.ts

@@ -85,6 +85,19 @@ export interface PluginExtensionSection {
         org?: JsonSchema;
     };
 }
+/**
+ * A plugin's description: a string (English) or `{ en, zh? }`, each ≤ 1024 characters. Read it
+ * through {@link pluginDescription}.
+ */
+export type PluginDescription = string | {
+    en: string;
+    zh?: string;
+};
+/** A plugin description as `{ en, zh? }` (a plain string is the English text). */
+export declare function pluginDescription(d: PluginDescription): {
+    en: string;
+    zh?: string;
+};
 /** `.capybara-plugin/plugin.json`. */
 export interface PluginManifest {
     $schema?: string;
@@ -94,8 +107,8 @@ export interface PluginManifest {
     /** Exact semver version. */
     version: string;
     publisher: string;
-    /** ≤ 1024 characters. */
-    description: string;
+    /** A string (English) or `{ en, zh? }`, each ≤ 1024 characters; see {@link pluginDescription}. */
+    description: PluginDescription;
     displayName?: LocalizedName;
     /** `./…` .svg / .png inside the plugin. */
     icon?: string;

package/dist/plugin-manifest.js

@@ -48,6 +48,10 @@ export const PLUGIN_MANIFEST_LIMITS = {
     displayNameChars: 100,
     pathChars: 512,
 };
+/** A plugin description as `{ en, zh? }` (a plain string is the English text). */
+export function pluginDescription(d) {
+    return typeof d === "string" ? { en: d } : { en: d.en, ...(d.zh !== undefined && { zh: d.zh }) };
+}
 const L = PLUGIN_MANIFEST_LIMITS;
 const MAX_ERRORS = 50;
 const ICON_RE = /\.(?:svg|png)$/i;
@@ -116,7 +120,13 @@ const schema = z
         .max(256)
         .regex(SEMVER_VERSION_RE, { message: "version must be an exact semver version" }),
     publisher: text(L.publisherChars, "publisher"),
-    description: text(L.descriptionChars, "description"),
+    description: z.union([
+        text(L.descriptionChars, "description"),
+        z.strictObject({
+            en: text(L.descriptionChars, "description.en"),
+            zh: text(L.descriptionChars, "description.zh").optional(),
+        }),
+    ]),
     displayName: localized.optional(),
     icon: dotPath("icon")
         .regex(ICON_RE, { message: "icon must be a .svg or .png file" })