@capybara-hq/plugin-sdk 0.0.0-stage → 0.1.0-rc.0

package/dist/file-preview.js

@@ -0,0 +1,72 @@
+/** File previewer extension point ref (UI refresh spec §5.8). */
+export const FILE_PREVIEW_EXTENSION_POINT = "file-preview@1";
+/** Largest file a previewer may declare (`FilePreviewer.maxBytes`): 20 MiB. */
+export const FILE_PREVIEW_MAX_BYTES = 20 * 1024 * 1024;
+const ID_RE = /^[a-z0-9-]{1,40}$/;
+const TITLE_MAX = 100;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const strings = (v) => Array.isArray(v) && v.every((s) => typeof s === "string" && s !== "" && s.length <= 100);
+/** Checks a `file-preview@1` provider; returns the problems (empty = valid). */
+export function validateFilePreviewProvider(p) {
+    if (!isObj(p))
+        return ["provider must be an object"];
+    if (!Array.isArray(p.previewers) || p.previewers.length === 0)
+        return ["previewers must be a non-empty array"];
+    const out = [];
+    const seen = new Set();
+    p.previewers.forEach((v, i) => {
+        const at = `previewers[${i}]`;
+        if (!isObj(v)) {
+            out.push(`${at} must be an object`);
+            return;
+        }
+        if (typeof v.id !== "string" || !ID_RE.test(v.id))
+            out.push(`${at}.id must match ${ID_RE.source}`);
+        else if (seen.has(v.id))
+            out.push(`${at}.id "${v.id}" is a duplicate`);
+        else
+            seen.add(v.id);
+        const t = v.title;
+        if (!isObj(t) ||
+            [t.zh, t.en].some((s) => typeof s !== "string" || s === "" || s.length > TITLE_MAX))
+            out.push(`${at}.title needs non-empty zh and en of at most ${TITLE_MAX} characters`);
+        const a = v.accepts;
+        if (!isObj(a) ||
+            (a.mimeTypes !== undefined && !strings(a.mimeTypes)) ||
+            (a.extensions !== undefined && !strings(a.extensions)) ||
+            (a.mimeTypes?.length ?? 0) +
+                (a.extensions?.length ?? 0) ===
+                0)
+            out.push(`${at}.accepts needs at least one MIME type or extension`);
+        if (typeof v.maxBytes !== "number" ||
+            !Number.isInteger(v.maxBytes) ||
+            v.maxBytes < 1 ||
+            v.maxBytes > FILE_PREVIEW_MAX_BYTES)
+            out.push(`${at}.maxBytes must be an integer from 1 to ${FILE_PREVIEW_MAX_BYTES}`);
+        const hasRender = typeof v.render === "function";
+        const hasEmbed = v.embed !== undefined;
+        if (hasRender === hasEmbed)
+            out.push(`${at} must have exactly one of render or embed`);
+        else if (hasEmbed && (typeof v.embed !== "string" || v.embed === ""))
+            out.push(`${at}.embed must be the id of a ui contribution`);
+    });
+    return out;
+}
+const baseType = (t) => (t.split(";")[0] ?? "").trim().toLowerCase();
+/** Whether a previewer takes this file: its type or extension is accepted and it is within `maxBytes`. */
+export function previewerAccepts(p, file) {
+    if (file.size > p.maxBytes)
+        return false;
+    const type = baseType(file.contentType);
+    const typeOk = (p.accepts.mimeTypes ?? []).some((m) => {
+        const want = m.toLowerCase();
+        return want.endsWith("/*") ? type.startsWith(want.slice(0, -1)) : type === want;
+    });
+    if (typeOk)
+        return true;
+    const name = file.name.toLowerCase();
+    return (p.accepts.extensions ?? []).some((e) => {
+        const ext = e.toLowerCase().replace(/^\.?/, ".");
+        return name.endsWith(ext) && name.length > ext.length;
+    });
+}

package/dist/frontmatter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reads a Markdown file that starts with YAML frontmatter between `---` lines (SKILL.md, agent
+ * templates): the frontmatter mapping and the body after it. Tolerates a BOM and CRLF (CRLF in the
+ * body becomes LF). `file` names the file in the errors (English); frontmatter longer than
+ * `maxChars` is not parsed. Not exported from the package.
+ */
+export declare function readFrontmatter(text: string, file: string, maxChars: number): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+} | {
+    errors: string[];
+};

package/dist/frontmatter.js

@@ -0,0 +1,36 @@
+import { parse as parseYaml } from "yaml";
+/**
+ * Reads a Markdown file that starts with YAML frontmatter between `---` lines (SKILL.md, agent
+ * templates): the frontmatter mapping and the body after it. Tolerates a BOM and CRLF (CRLF in the
+ * body becomes LF). `file` names the file in the errors (English); frontmatter longer than
+ * `maxChars` is not parsed. Not exported from the package.
+ */
+export function readFrontmatter(text, file, maxChars) {
+    const src = (text.startsWith("\uFEFF") ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+    const lines = src.split("\n");
+    if (lines[0]?.trimEnd() !== "---") {
+        return { errors: [`${file} must start with YAML frontmatter delimited by '---' lines`] };
+    }
+    const end = lines.findIndex((l, i) => i > 0 && l.trimEnd() === "---");
+    if (end < 0)
+        return { errors: [`${file} frontmatter is not closed by a '---' line`] };
+    const front = lines.slice(1, end).join("\n");
+    if (front.length > maxChars) {
+        return {
+            errors: [`frontmatter must be at most ${maxChars} characters`],
+        };
+    }
+    const body = lines.slice(end + 1).join("\n");
+    let data;
+    try {
+        data = parseYaml(front, { uniqueKeys: true, maxAliasCount: 50 });
+    }
+    catch (e) {
+        const first = (e instanceof Error ? e.message : String(e)).split("\n")[0];
+        return { errors: [`frontmatter is not valid YAML: ${first}`] };
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return { errors: ["frontmatter must be a YAML mapping"] };
+    }
+    return { frontmatter: data, body };
+}

package/dist/hooks.d.ts

@@ -0,0 +1,194 @@
+import type { ContentBlock, ModelRequest, ModelUsage } from "./model.js";
+/**
+ * Hook mount points a plugin can register on through `ctx.hooks.on` (from M7). The other names in
+ * `HOOK_MOUNT_POINTS` (`session.*`, `agent.preStep`) stay reserved: they validate in a manifest but
+ * cannot be registered yet.
+ */
+export declare const HOOKS_AVAILABLE: readonly ["model.request", "model.response", "tool.preExecute", "tool.postExecute", "usage.report"];
+/** A mount point that `ctx.hooks.on` accepts. */
+export type AvailableHook = (typeof HOOKS_AVAILABLE)[number];
+/** Where a sub-agent was dispatched from: the parent conversation, its run and the `agent` call. */
+export interface HookParentScope {
+    conversationId: string;
+    runId: string;
+    /**
+     * The `agent` call's id; `skill-<seq>` for a person's forked skill invocation, which has no
+     * tool call in the parent's log.
+     */
+    callId: string;
+}
+/**
+ * Who and where a model or tool hook fires for. Hooks fire in chat conversations and in
+ * sub-agents' conversations (never in eval replays).
+ */
+export interface HookScope {
+    orgId: string;
+    accountId: string;
+    agentId: string;
+    agentVersion: number;
+    conversationId: string;
+    runId: string;
+    /** Set when the call belongs to a sub-agent: where it was dispatched from. */
+    parent?: HookParentScope;
+}
+/**
+ * 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).
+ */
+export type ModelCallPurpose = "step" | "compaction" | "title";
+/** What a reported model call was for (the same values as {@link ModelCallPurpose}). */
+export type UsagePurpose = ModelCallPurpose;
+/**
+ * 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.
+ * `size` is the size of the bytes sent to the provider, in bytes (0 when unknown).
+ */
+export interface HookMediaPlaceholder {
+    type: "media_omitted";
+    kind: "image" | "document";
+    mediaType: string;
+    size: number;
+}
+/** A content block of a `model.request` payload: image and document blocks become placeholders. */
+export type HookContentBlock = Exclude<ContentBlock, {
+    type: "image";
+} | {
+    type: "document";
+}> | HookMediaPlaceholder;
+/** A message of a `model.request` payload (see {@link HookContentBlock}). */
+export type HookModelMessage = {
+    role: "user";
+    content: HookContentBlock[];
+} | {
+    role: "assistant";
+    content: HookContentBlock[];
+} | {
+    role: "system";
+    content: string;
+};
+/** The request of a `model.request` payload: the request sent to the provider, without media bytes. */
+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
+ * 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).
+ * `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 {
+    purpose: ModelCallPurpose;
+    step: number;
+    attempt: number;
+    provider: string;
+    model: string;
+    request: Readonly<HookModelRequest>;
+}
+/**
+ * `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
+ * stopped while the call was in flight), nor for a call that was never sent (denied, or failed
+ * before sending), so a `model.request` can have no matching `model.response`.
+ */
+export interface ModelResponseHookPayload extends HookScope {
+    purpose: ModelCallPurpose;
+    step: number;
+    attempt: number;
+    provider: string;
+    model: string;
+    outcome: "ok" | "failed";
+    content: readonly ContentBlock[];
+    stopReason: string | null;
+    usage: ModelUsage | null;
+    latencyMs: number;
+    errorCode?: string;
+}
+/** `tool.preExecute`: before a tool call runs. A policy hook may deny it. */
+export interface ToolPreHookPayload extends HookScope {
+    step: number;
+    callId: string;
+    toolKey: string;
+    specHash: string;
+    input: unknown;
+}
+/** `tool.postExecute`: after a tool call finished, with the result the model sees. */
+export interface ToolPostHookPayload extends ToolPreHookPayload {
+    isError: boolean;
+    content: string;
+    durationMs: number;
+}
+/**
+ * `usage.report`: the usage of one model call that the event log recorded (chat runs and full-run eval
+ * replays, see `conversationKind`), delivered through a queue **at least once**: a failed or
+ * interrupted delivery is retried (up to 5 times, 2 s doubling), possibly on another replica, so
+ * handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Delivered only while the
+ * organization has the plugin enabled; the verdict is ignored.
+ */
+export interface UsageReportPayload {
+    eventId: string;
+    /**
+     * A run step's call, a compaction call, or a conversation title call (`title`: no run, so
+     * `runId` is ""). All are billed.
+     */
+    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;
+    /** Set when the call belongs to a sub-agent: where it was dispatched from. */
+    parent?: HookParentScope;
+    provider: string;
+    model: string;
+    usage: ModelUsage;
+    occurredAt: string;
+}
+/** Payload type of each mount point. */
+export interface HookPayloads {
+    "model.request": ModelRequestHookPayload;
+    "model.response": ModelResponseHookPayload;
+    "tool.preExecute": ToolPreHookPayload;
+    "tool.postExecute": ToolPostHookPayload;
+    "usage.report": UsageReportPayload;
+}
+/**
+ * What a hook returns: nothing, or `{ deny: reason }`. A deny only takes effect for a `policy` hook
+ * on a mount point in {@link POLICY_HOOKS}; it is ignored everywhere else. Hooks never rewrite the
+ * request or the result.
+ */
+export type HookVerdict = void | {
+    deny: string;
+};
+/**
+ * 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.
+ */
+export type HookHandler<K extends AvailableHook> = (payload: HookPayloads[K], signal: AbortSignal) => Promise<HookVerdict> | HookVerdict;
+/**
+ * - `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
+ *   the rest are skipped. The model sees your deny reason (sanitized, at most 500 characters), but
+ *   only a generic sentence for an error or a timeout.
+ * - `observe`: dispatched after the policy hooks, concurrently and fire-and-forget, whether or not
+ *   the call was denied; the call never waits for them. Verdicts, errors and timeouts are ignored
+ *   (logged as throttled warnings). Each call keeps the `hooks.timeoutMs` limit and its abort signal;
+ *   when too many observe calls of one plugin are in flight on a replica, new ones are dropped.
+ *
+ * A `policy` hook must also be declared in `permissions.policyHooks`. Policy hooks fail closed: when
+ * a plugin that declares a policy hook on a mount point is enabled and approved but not loaded on the
+ * replica that handles a call (setup failed, pending configuration, import failed), the call is
+ * denied with a generic reason. Observe hooks of a plugin that is not loaded are simply skipped.
+ */
+export interface HookOptions {
+    mode: "observe" | "policy";
+}
+/** Mount points where a `policy` hook may deny the call. */
+export declare const POLICY_HOOKS: readonly ["model.request", "tool.preExecute"];
+/** A mount point that accepts `policy` hooks (`permissions.policyHooks`). */
+export type PolicyHook = (typeof POLICY_HOOKS)[number];

package/dist/hooks.js

@@ -0,0 +1,14 @@
+/**
+ * Hook mount points a plugin can register on through `ctx.hooks.on` (from M7). The other names in
+ * `HOOK_MOUNT_POINTS` (`session.*`, `agent.preStep`) stay reserved: they validate in a manifest but
+ * cannot be registered yet.
+ */
+export const HOOKS_AVAILABLE = [
+    "model.request",
+    "model.response",
+    "tool.preExecute",
+    "tool.postExecute",
+    "usage.report",
+];
+/** Mount points where a `policy` hook may deny the call. */
+export const POLICY_HOOKS = ["model.request", "tool.preExecute"];

package/dist/identity.d.ts

@@ -0,0 +1,44 @@
+/** 外部身份；登录、渠道入站、通讯录三处用同一个 (source, externalId) 键。 */
+export interface ExternalIdentity {
+    /**
+     * `"<插件名>:<租户 id>"`，必须与 `tenantId` 一致。第三方登录时内核核对
+     * `source === \`${插件名}:${tenantId}\``，不一致按身份源出错拒绝。
+     */
+    source: string;
+    externalId: string;
+    tenantId: string;
+    email?: string;
+    emailVerified: boolean;
+    displayName: string;
+    avatarUrl?: string;
+}
+/**
+ * 第三方登录（`identity-source@1`）。state、nonce 与 PKCE 都由内核生成并保存在服务端：
+ * 插件把 `codeChallenge` / `codeChallengeMethod` 放进授权地址（`code_challenge` / `code_challenge_method`），
+ * 回调换 token 时带上 `codeVerifier`（`code_verifier`）。平台不支持 PKCE 时忽略这几个字段即可。
+ */
+export interface IdentitySource {
+    label: {
+        zh: string;
+        en: string;
+    };
+    authorizeUrl(args: {
+        config: unknown;
+        redirectUri: string;
+        state: string;
+        nonce: string;
+        /** PKCE challenge（base64url(SHA-256(codeVerifier))）；内核总会提供，旧内核不提供。 */
+        codeChallenge?: string;
+        /** PKCE challenge 的算法；内核只用 `"S256"`。 */
+        codeChallengeMethod?: "S256";
+    }): string;
+    callback(args: {
+        config: unknown;
+        redirectUri: string;
+        query: Record<string, string>;
+        nonce: string;
+        signal: AbortSignal;
+        /** 与本次发起的 `codeChallenge` 对应的 PKCE verifier；内核总会提供，旧内核不提供。 */
+        codeVerifier?: string;
+    }): Promise<ExternalIdentity>;
+}

package/dist/identity.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export declare const SDK_VERSION = "0.1.0-rc.0";
+export * from "./agent-template.js";
+export * from "./bootstrap.js";
+export * from "./cards.js";
+export * from "./channel.js";
+export * from "./connector.js";
+export * from "./connector-auth.js";
+export * from "./ctx.js";
+export * from "./define-extension.js";
+export * from "./directory.js";
+export * from "./extension-point.js";
+export * from "./file-preview.js";
+export * from "./hooks.js";
+export * from "./identity.js";
+export * from "./marketplace.js";
+export * from "./model.js";
+export * from "./model-params.js";
+export * from "./permissions.js";
+export * from "./plugin-manifest.js";
+export * from "./plugin-package.js";
+export * from "./sandbox.js";
+export * from "./secret.js";
+export * from "./skill.js";
+export * from "./skill-invocation.js";
+export * from "./storage.js";
+export * from "./tool.js";
+export * from "./ui.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+export const SDK_VERSION = "0.1.0-rc.0";
+export * from "./agent-template.js";
+export * from "./bootstrap.js";
+export * from "./cards.js";
+export * from "./channel.js";
+export * from "./connector.js";
+export * from "./connector-auth.js";
+export * from "./ctx.js";
+export * from "./define-extension.js";
+export * from "./directory.js";
+export * from "./extension-point.js";
+export * from "./file-preview.js";
+export * from "./hooks.js";
+export * from "./identity.js";
+export * from "./marketplace.js";
+export * from "./model.js";
+export * from "./model-params.js";
+export * from "./permissions.js";
+export * from "./plugin-manifest.js";
+export * from "./plugin-package.js";
+export * from "./sandbox.js";
+export * from "./secret.js";
+export * from "./skill.js";
+export * from "./skill-invocation.js";
+export * from "./storage.js";
+export * from "./tool.js";
+export * from "./ui.js";

package/dist/marketplace.d.ts

@@ -0,0 +1,99 @@
+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.
+ *
+ * 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).
+ *
+ * The committed JSON Schema (`schemas/marketplace.v1.schema.json`) is generated from
+ * {@link MarketplaceManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
+ * `check:package-schemas`. Cross-field rules (unique `(name, version)`, `version` equal to the npm
+ * source's, `sensitive` ⊆ `keys`) are decided only by {@link parseMarketplaceManifest}. Unknown
+ * fields are dropped (forward compatible: a newer manifest does not make an older kernel reject it).
+ */
+/** Manifest format version. */
+export declare const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
+/** Limits of the marketplace manifest. */
+export declare const MARKETPLACE_LIMITS: {
+    readonly nameChars: 100;
+    readonly summaryChars: 280;
+    readonly plugins: 5000;
+    readonly permissionKeys: 500;
+    readonly urlChars: 2000;
+};
+/** Where a marketplace entry's plugin comes from. */
+export type MarketplaceSource = {
+    path: string;
+} | {
+    git: {
+        url: string;
+        ref?: string;
+        commit?: string;
+        path?: string;
+    };
+} | {
+    npm: {
+        package: string;
+        version: string;
+        integrity: string;
+    };
+} | {
+    archive: {
+        url: string;
+        integrity: string;
+    };
+};
+/** One plugin version listed by a marketplace. */
+export interface MarketplaceEntry {
+    /** Catalog item name (`^[a-z0-9][a-z0-9-]{0,63}$`). */
+    name: string;
+    summary: {
+        en: string;
+        zh?: string;
+    };
+    /** Exact semver; defaults to the npm source's version, otherwise the plugin's own. */
+    version?: string;
+    /** Exact semver. */
+    minKernel?: string;
+    /** Display only (a mismatch with the computed permissions warns, never rejects). */
+    permissions?: {
+        keys: string[];
+        sensitive: string[];
+    };
+    /** https URL. */
+    homepage?: string;
+    source: MarketplaceSource;
+}
+/** `marketplace.json`. */
+export interface MarketplaceManifest {
+    $schema?: string;
+    schemaVersion: 1;
+    /** Display name, unrelated to the repo name. */
+    name: string;
+    owner?: {
+        name: string;
+        url?: string;
+    };
+    description?: string;
+    plugins: MarketplaceEntry[];
+}
+export interface MarketplaceParseOptions {
+    /** Tests only: allow http on loopback addresses for `git` / `archive` URLs. */
+    allowInsecureLoopback?: boolean;
+}
+/**
+ * The zod schema of `marketplace.json` (https only; non-strict: unknown fields dropped). The JSON
+ * Schema is generated with `z.toJSONSchema(MarketplaceManifestSchema, { io: "input" })`.
+ */
+export declare const MarketplaceManifestSchema: z.ZodType<MarketplaceManifest>;
+/**
+ * Validates and parses `marketplace.json` (unknown fields dropped). Invalid input returns
+ * `{ errors }` (`<path>: <reason>`, at most 50); never throws.
+ */
+export declare function parseMarketplaceManifest(json: unknown, opts?: MarketplaceParseOptions): MarketplaceManifest | {
+    errors: string[];
+};
+/** 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;