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

package/agent-docs/agent-templates.md

@@ -1,4 +1,4 @@
-# Agent templates
+# Authoring: agent templates
 
 An agent template describes a whole agent: instructions, tools, skills, connectors and the
 sub-agents it may dispatch. A member creates a private agent from a template; org admins can also

package/agent-docs/concepts.md

@@ -2,6 +2,10 @@
 
 Read this first. It explains the vocabulary the other topics use.
 
+The other topics are for *authoring*: writing an extension, building a plugin, skills, templates,
+connector templates, tool naming and extension points. To *use* the platform (install, switch on,
+configure, manage), use the operations: `browse`, `search`, `describe` and `call`.
+
 ## Platform and org
 
 - The **platform** is one deployment. The **super admin** runs it: imports plugins into the

package/agent-docs/connector-templates.md

@@ -1,4 +1,4 @@
-# Connector templates
+# Authoring: connector templates
 
 A connector template is a ready-made connection to an external system: a protocol connector
 (`connector-mcp`, `connector-openapi`), a preset endpoint and the auth shape. An org installs it

package/agent-docs/extension-points/channel.md

@@ -1,4 +1,4 @@
-# Extension point: channel
+# Authoring: extension point channel
 
 <!-- generated:extension-point -->
 - Name: `channel` (a ref is `channel@<major>`)

package/agent-docs/extension-points/config-source.md

@@ -1,4 +1,4 @@
-# Extension point: config-source
+# Authoring: extension point config-source
 
 <!-- generated:extension-point -->
 - Name: `config-source` (a ref is `config-source@<major>`)

package/agent-docs/extension-points/connector.md

@@ -1,4 +1,4 @@
-# Extension point: connector
+# Authoring: extension point connector
 
 <!-- generated:extension-point -->
 - Name: `connector` (a ref is `connector@<major>`)

package/agent-docs/extension-points/counter.md

@@ -1,4 +1,4 @@
-# Extension point: counter
+# Authoring: extension point counter
 
 <!-- generated:extension-point -->
 - Name: `counter` (a ref is `counter@<major>`)

package/agent-docs/extension-points/directory.md

@@ -1,4 +1,4 @@
-# Extension point: directory
+# Authoring: extension point directory
 
 <!-- generated:extension-point -->
 - Name: `directory` (a ref is `directory@<major>`)

package/agent-docs/extension-points/file-preview.md

@@ -1,4 +1,4 @@
-# Extension point: file-preview
+# Authoring: extension point file-preview
 
 <!-- generated:extension-point -->
 - Name: `file-preview` (a ref is `file-preview@<major>`)

package/agent-docs/extension-points/identity-source.md

@@ -1,4 +1,4 @@
-# Extension point: identity-source
+# Authoring: extension point identity-source
 
 <!-- generated:extension-point -->
 - Name: `identity-source` (a ref is `identity-source@<major>`)

package/agent-docs/extension-points/model-provider.md

@@ -1,4 +1,4 @@
-# Extension point: model-provider
+# Authoring: extension point model-provider
 
 <!-- generated:extension-point -->
 - Name: `model-provider` (a ref is `model-provider@<major>`)

package/agent-docs/extension-points/object-store.md

@@ -1,4 +1,4 @@
-# Extension point: object-store
+# Authoring: extension point object-store
 
 <!-- generated:extension-point -->
 - Name: `object-store` (a ref is `object-store@<major>`)

package/agent-docs/extension-points/sandbox.md

@@ -1,4 +1,4 @@
-# Extension point: sandbox
+# Authoring: extension point sandbox
 
 <!-- generated:extension-point -->
 - Name: `sandbox` (a ref is `sandbox@<major>`)

package/agent-docs/extension-points/secret-store.md

@@ -1,4 +1,4 @@
-# Extension point: secret-store
+# Authoring: extension point secret-store
 
 <!-- generated:extension-point -->
 - Name: `secret-store` (a ref is `secret-store@<major>`)

package/agent-docs/extension-points/web-fetch.md

@@ -1,4 +1,4 @@
-# Extension point: web-fetch
+# Authoring: extension point web-fetch
 
 <!-- generated:extension-point -->
 - Name: `web-fetch` (a ref is `web-fetch@<major>`)

package/agent-docs/extension-points/web-search.md

@@ -1,4 +1,4 @@
-# Extension point: web-search
+# Authoring: extension point web-search
 
 <!-- generated:extension-point -->
 - Name: `web-search` (a ref is `web-search@<major>`)

package/agent-docs/extensions.md

@@ -1,4 +1,4 @@
-# Writing an extension
+# Authoring: writing an extension
 
 An extension is TypeScript code a plugin ships. It runs in the platform's process with full
 trust: approval by the super admin is governance, not a sandbox. It sees only the SDK's `ctx`

package/agent-docs/plugin-format.md

@@ -1,4 +1,4 @@
-# Plugin format
+# Authoring: the plugin format
 
 A plugin is a directory, packed into a `.tgz` with `capybara-plugin pack` (the published
 `@capybara-hq/plugin-tools`; `npx capybara-plugin check` runs the checks).

package/agent-docs/skills.md

@@ -1,4 +1,4 @@
-# Skills
+# Authoring: skills
 
 A skill is a folder with a `SKILL.md` (the Agent Skills format) and any files it needs. The agent
 sees only the skill's `name` and `description` until it loads the skill, so the description is

package/agent-docs/tool-naming.md

@@ -1,4 +1,4 @@
-# Tool naming
+# Authoring: tool naming
 
 The model-visible tool key grammar:
 

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: {

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;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.3";
+export declare const SDK_VERSION = "0.1.0-rc.5";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.3";
+export const SDK_VERSION = "0.1.0-rc.5";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";

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/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/package.json

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