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

package/dist/extension-point.js

@@ -1,21 +1,26 @@
-const info = (cardinality, brokered = false, orgScoped = false) => ({
+const info = (majors, description, cardinality, brokered = false, orgScoped = false, selection) => ({
+    majors,
+    description,
     cardinality,
     brokered,
     orgScoped,
+    ...(selection ? { 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),
+    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

@@ -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;
 /**
@@ -168,9 +169,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,8 +1,9 @@
-export declare const SDK_VERSION = "0.1.0-rc.1";
+export declare const SDK_VERSION = "0.1.0-rc.3";
 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";
@@ -15,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";
@@ -26,3 +28,4 @@ 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.1";
+export const SDK_VERSION = "0.1.0-rc.3";
 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";
@@ -15,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";
@@ -26,3 +28,4 @@ export * from "./storage.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.js";
+export * from "./web.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/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/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,7 +75,29 @@ 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;
+    };
 }
+/**
+ * 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;
@@ -84,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

@@ -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";
@@ -47,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;
@@ -87,6 +92,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 +104,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({
@@ -107,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" })