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

package/agent-docs/connector-templates.md

@@ -30,6 +30,7 @@ The file is strict. Top-level fields:
 | `displayName` | object | yes |
 | `description` | string | no |
 | `icon` | string | no |
+| `defaultEnabled` | boolean | no |
 | `template` | object | yes |
 <!-- /generated -->
 

package/agent-docs/plugin-format.md

@@ -37,6 +37,7 @@ file is strict: an unknown key is an error. Fields (agent templates are listed u
 | `skills` | array of object | no |
 | `connectorTemplates` | array of object | no |
 | `agents` | array of object | no |
+| `setupGuides` | array of object | no |
 | `extension` | object | no |
 <!-- /generated -->
 
@@ -51,6 +52,16 @@ Rules that the schema cannot show:
   Omit them to scan the default folders. Names and ids are unique within the plugin.
 - `dependencies`: plugin name plus semver range; no self-dependency.
 - `agents`: at most 64 templates (see `agent-templates`).
+- `setupGuides` (at most 8): setup material shown where a person configures what the plugin
+  brings. Each guide has an `id`, a `place` (`channel-connection`: 新建渠道 and the channel detail;
+  the plugin's extension must provide `channel@1`), a `title` and `steps` (`{ en, zh? }`, plain
+  text, a backtick pair shows as inline code) and `files` (`./` paths ending in `.tmpl`, `.yaml`,
+  `.yml`, `.json` or `.txt`, at most 64 KiB of text, with a `title` and a `language` of `yaml`,
+  `json` or `text`). A step or file may carry `mode` (`long_connection` or `webhook`) to apply to
+  that inbound mode only; ship one file per mode instead of conditionals. The kernel fills
+  `{{publicUrl}}`, `{{webhookUrl}}`, `{{signInCallbackUrl}}`, `{{connectionName}}`, `{{orgName}}`,
+  `{{pluginName}}`, `{{pluginVersion}}` and `{{mode}}` (never a secret); in YAML and JSON put a
+  placeholder inside double quotes. `capybara-plugin pack` refuses any other placeholder.
 - `extension` is written by the packer; never write it by hand.
 
 ## Importing

package/dist/cards.d.ts

@@ -10,6 +10,13 @@ export type ChannelCard = {
     toolName: string;
     appName?: string;
     agentName: string;
+    /**
+     * One line saying what the call does, as the web shows it: the tool's confirmation summary
+     * (e.g. a Platform operation's), else the tool's title and key argument; may be empty.
+     * Never the raw call input (it may hold a whole prompt, and a group sees the card); the
+     * full input is behind `webUrl`. Plain text written by the kernel from model-controlled
+     * values: render it as text, never as markup. The name is kept from when it held the input.
+     */
     inputPreview: string;
     scopes: ("once" | "session" | "always")[];
     expiresAt: string;

package/dist/cards.js

@@ -92,7 +92,7 @@ export function validateChannelCard(card) {
     }
 }
 /**
- * 把模型可控的值（审批标题、输入预览、提问标题、回答摘要）放进代码里，退回文本里它们不会变成链接、强调或 HTML：
+ * 把模型可控的值（审批标题、调用摘要、提问标题、回答摘要）放进代码里，退回文本里它们不会变成链接、强调或 HTML：
  * 单行用行内代码，多行用围栏代码块（以换行开头），分隔符都比值里最长的反引号串更长（CommonMark 6.1 / 4.5）。
  * 选代码而不是给标点加反斜杠：代码是 CommonMark / GFM 里唯一保证内容按原样显示的写法（反斜杠挡不住 GFM 的裸网址
  * 自动链接，各渠道转换器对反斜杠的处理也不一致）。
@@ -119,7 +119,7 @@ const TEXT = {
         connect: (app) => `[Connect] ${app} needs to be connected.`,
         tool: "Tool",
         agent: "Agent",
-        input: "Input",
+        summary: "Summary",
         status: "Status",
         reason: "Reason",
         expires: "Expires",
@@ -149,7 +149,7 @@ const TEXT = {
         connect: (app) => `【连接】需要连接 ${app}。`,
         tool: "工具",
         agent: "Agent",
-        input: "输入",
+        summary: "摘要",
         status: "状态",
         reason: "原因",
         expires: "过期时间",
@@ -187,7 +187,7 @@ export function renderCardAsText(card, locale) {
                 withCode(t.approval, asCode(card.title)),
                 line(t.tool, card.appName ? `${card.appName} / ${card.toolName}` : card.toolName),
                 line(t.agent, card.agentName),
-                line(t.input, asCode(card.inputPreview)),
+                ...(card.inputPreview !== "" ? [line(t.summary, asCode(card.inputPreview))] : []),
                 line(t.status, card.decidedBy ? `${state} (${card.decidedBy})` : state),
             ];
             if (card.state === "denied" && card.denyReason)

package/dist/channel.d.ts

@@ -21,6 +21,21 @@ export interface InboundSender {
     tenantId: string;
     displayName?: string;
     avatarUrl?: string;
+    /**
+     * The sender's time zone on the platform, an IANA name (`Asia/Shanghai`; Slack `users.info`
+     * `user.tz`), when the platform gives one. Include it on `message` events when you can get it
+     * within the acknowledgement deadline (cache it per user); leave it out otherwise. It wins over
+     * the person's account setting and the org default for the run's date and zone (run context
+     * spec §3.4); a name the kernel does not know is ignored.
+     */
+    timeZone?: string;
+    /**
+     * The sender's language on the platform: `zh` / `en` or a BCP 47 tag (`zh-CN`, `en-US`; Slack
+     * `users.info` with `include_locale=true`, `user.locale`), when the platform gives one. The
+     * kernel normalizes it (`zh` and `zh-*` are Chinese, any other tag English); it wins over the
+     * person's latest web UI language and the org default (run context spec §3.4).
+     */
+    locale?: string;
 }
 /**
  * 渠道交给内核的入站事件。插件的约定：
@@ -76,7 +91,11 @@ export interface ChannelSendArgs {
      */
     message: OutboundMessage;
     signal: AbortSignal;
-    /** 连接所属组织的界面语言：插件自己渲染的文案（卡片按钮、降级文本里的固定词）按它选择。 */
+    /**
+     * The recipient's language (the sender's platform language, else their latest web language,
+     * else the org's): the wording the extension renders itself (card buttons, fixed words in the
+     * text fallback) follows it.
+     */
     locale: Locale;
     /**
      * 幂等键（可选）：不超过 40 个 `[A-Za-z0-9_-]` 字符，同一条逻辑消息的每次重试（崩溃后其他副本续投、

package/dist/connector-auth.d.ts

@@ -50,6 +50,7 @@ export declare const ConnectorAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         client_secret_basic: "client_secret_basic";
         client_secret_post: "client_secret_post";
     }>>;
+    tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"oauth_client">;
     ownership: z.ZodLiteral<"org">;
@@ -59,6 +60,7 @@ export declare const ConnectorAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         client_secret_basic: "client_secret_basic";
         client_secret_post: "client_secret_post";
     }>>;
+    tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>], "type">;
 /** 认证预设（{@link ConnectorAuthSchema} 的输出）。 */
 export type ConnectorAuthPreset = z.infer<typeof ConnectorAuthSchema>;

package/dist/connector-auth.js

@@ -23,6 +23,19 @@ const Scopes = z
     .max(200)
     .regex(/^[\x21\x23-\x5B\x5D-\x7E]+$/, "Invalid scope"))
     .max(50);
+/**
+ * More `token_type` values the token endpoint may return for a bearer token (case-insensitive;
+ * `Bearer` and Slack's `user` are always accepted). The token is still sent as
+ * `Authorization: Bearer`. Never `DPoP`: such a token is bound to a key the kernel does not hold.
+ */
+const TokenTypes = z
+    .array(z
+    .string()
+    .min(1)
+    .max(32)
+    .regex(/^[A-Za-z][A-Za-z0-9_.-]*$/, "Invalid token type")
+    .refine((t) => t.toLowerCase() !== "dpop", "DPoP tokens are not bearer tokens"))
+    .max(5);
 /** 认证方式：只有类型与非密钥字段；凭据值走内核的 `credential` / 凭据接口。 */
 export const ConnectorAuthSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("none") }).strict(),
@@ -57,6 +70,7 @@ export const ConnectorAuthSchema = z.discriminatedUnion("type", [
         scopes: Scopes.optional(),
         client: z.enum(["dcr", "manual"]),
         tokenAuthMethod: TokenAuthMethod.optional(),
+        tokenTypes: TokenTypes.optional(),
     })
         .strict()
         .superRefine((a, ctx) => {
@@ -91,6 +105,7 @@ export const ConnectorAuthSchema = z.discriminatedUnion("type", [
         tokenUrl: OAuthUrl,
         scopes: Scopes.optional(),
         tokenAuthMethod: TokenAuthMethod.optional(),
+        tokenTypes: TokenTypes.optional(),
     })
         .strict(),
 ]);

package/dist/device-protocol.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
+ * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ */
+import { type ExecResult, type SandboxActor, type SandboxLimits, type SandboxRoots } from "./sandbox.js";
+/** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */
+export declare const DEVICE_PROTOCOL_VERSION = 1;
+/** The operations the kernel asks a device to run. */
+export type DeviceOp = "create" | "exec" | "readFile" | "writeFile" | "stat" | "killTagged" | "killAll" | "stop";
+/** First frame from the device after the WebSocket opens. */
+export interface DeviceHello {
+    type: "hello";
+    protocol: number;
+    programVersion: string;
+    os: "darwin" | "linux";
+    arch: string;
+    mode: "os" | "docker";
+    roots: SandboxRoots;
+    sessionIsolation: boolean;
+}
+/** Error kinds a device reports for a failed request. */
+export type DeviceErrorKind = "gone" | "fs_gone" | "policy" | "error";
+/** The device's answer to a {@link KernelReq}. */
+export type DeviceRes = {
+    type: "res";
+    id: string;
+    ok: true;
+    result: unknown;
+} | {
+    type: "res";
+    id: string;
+    ok: false;
+    error: {
+        kind: DeviceErrorKind;
+        message: string;
+    };
+};
+/** A request from the kernel. */
+export interface KernelReq {
+    type: "req";
+    id: string;
+    op: DeviceOp;
+    args: unknown;
+    deadlineMs: number;
+}
+/** The kernel gives up on a request (abort or deadline). */
+export interface KernelCancel {
+    type: "cancel";
+    id: string;
+}
+export type DeviceFrame = DeviceHello | DeviceRes | KernelReq | KernelCancel;
+export interface DeviceExecArgs {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    tag: string;
+    actor: SandboxActor;
+    limits: SandboxLimits;
+}
+export type DeviceExecResult = ExecResult;
+export interface DeviceReadFileArgs {
+    path: string;
+    maxBytes: number;
+}
+export type DeviceReadFileResult = {
+    dataB64: string;
+    truncated: boolean;
+} | null;
+export interface DeviceWriteFileArgs {
+    path: string;
+    dataB64: string;
+}
+export type DeviceWriteFileResult = null;
+export interface DeviceStatArgs {
+    path: string;
+}
+export type DeviceStatResult = {
+    size: number;
+    isDir: boolean;
+} | null;
+export interface DeviceKillTaggedArgs {
+    tags: string[];
+}
+export type DeviceKillAllArgs = Record<string, never>;
+export interface DeviceCreateArgs {
+    limits: SandboxLimits;
+}
+export interface DeviceCreateResult {
+    roots: SandboxRoots;
+}
+export interface DeviceStopArgs {
+    reason: "revoked" | "deleted";
+}
+/** A frame that is not valid protocol v1 (or came from the wrong side). */
+export declare class DeviceProtocolError extends Error {
+    constructor(message: string);
+}
+/** Result type per op. */
+export interface DeviceOpResults {
+    create: DeviceCreateResult;
+    exec: DeviceExecResult;
+    readFile: DeviceReadFileResult;
+    writeFile: DeviceWriteFileResult;
+    stat: DeviceStatResult;
+    killTagged: null;
+    killAll: null;
+    stop: null;
+}
+/** Validates the `result` of a successful `res` for `op`; throws {@link DeviceProtocolError}. */
+export declare function parseOpResult<Op extends DeviceOp>(op: Op, result: unknown): DeviceOpResults[Op];
+/**
+ * Parses one WebSocket text frame. `from` is the sender: a device may send `hello` and `res`, the
+ * kernel `req` and `cancel`. Throws {@link DeviceProtocolError} on bad JSON, an unknown `type`,
+ * missing fields or a frame of the wrong direction.
+ */
+export declare function parseDeviceFrame(raw: string, from: "device" | "kernel"): DeviceFrame;

package/dist/device-protocol.js

@@ -0,0 +1,276 @@
+/**
+ * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
+ * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ */
+import { validateSandboxPathShape, } from "./sandbox.js";
+/** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */
+export const DEVICE_PROTOCOL_VERSION = 1;
+const DEVICE_OPS = [
+    "create",
+    "exec",
+    "readFile",
+    "writeFile",
+    "stat",
+    "killTagged",
+    "killAll",
+    "stop",
+];
+/** A frame that is not valid protocol v1 (or came from the wrong side). */
+export class DeviceProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeviceProtocolError";
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(o, k) {
+    const v = o[k];
+    if (typeof v !== "string")
+        throw new DeviceProtocolError(`field "${k}" must be a string`);
+    return v;
+}
+function nonEmptyStr(o, k) {
+    const v = str(o, k);
+    if (v === "")
+        throw new DeviceProtocolError(`field "${k}" must not be empty`);
+    return v;
+}
+function posInt(o, k) {
+    const v = o[k];
+    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
+        throw new DeviceProtocolError(`field "${k}" must be a positive integer`);
+    }
+    return v;
+}
+function obj(v, what) {
+    if (!isRecord(v))
+        throw new DeviceProtocolError(`${what} must be an object`);
+    return v;
+}
+function bool(o, k) {
+    const v = o[k];
+    if (typeof v !== "boolean")
+        throw new DeviceProtocolError(`field "${k}" must be a boolean`);
+    return v;
+}
+function strArray(o, k) {
+    const v = o[k];
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+        throw new DeviceProtocolError(`field "${k}" must be an array of strings`);
+    }
+    return v;
+}
+function parseLimits(v) {
+    const o = obj(v, 'field "limits"');
+    const egress = str(o, "egress");
+    if (egress !== "none" && egress !== "allowlist" && egress !== "open") {
+        throw new DeviceProtocolError(`unknown egress "${egress}"`);
+    }
+    return {
+        cpu: num(o, "cpu"),
+        memoryMb: num(o, "memoryMb"),
+        diskMb: num(o, "diskMb"),
+        egress,
+        allowHosts: strArray(o, "allowHosts"),
+    };
+}
+function num(o, k) {
+    const v = o[k];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new DeviceProtocolError(`field "${k}" must be a number`);
+    }
+    return v;
+}
+function parseRoots(v) {
+    if (!isRecord(v))
+        throw new DeviceProtocolError('field "roots" must be an object');
+    const roots = {};
+    for (const k of ["workspace", "skills", "tmp"]) {
+        const p = str(v, k);
+        if (!p.startsWith("/")) {
+            throw new DeviceProtocolError(`root "${k}" must be an absolute path`);
+        }
+        // the kernel builds paths as `${root}/…` and checks membership by prefix: a root must be a
+        // clean absolute directory path
+        const shape = validateSandboxPathShape(p);
+        if (shape.length > 0)
+            throw new DeviceProtocolError(`root "${k}": ${shape.join("; ")}`);
+        if (p.endsWith("/")) {
+            throw new DeviceProtocolError(`root "${k}" must not end with a slash`);
+        }
+        roots[k] = p;
+    }
+    return roots;
+}
+function parseHello(o) {
+    const os = str(o, "os");
+    if (os !== "darwin" && os !== "linux")
+        throw new DeviceProtocolError(`unsupported os "${os}"`);
+    const mode = str(o, "mode");
+    if (mode !== "os" && mode !== "docker") {
+        throw new DeviceProtocolError(`unsupported mode "${mode}"`);
+    }
+    if (typeof o.sessionIsolation !== "boolean") {
+        throw new DeviceProtocolError('field "sessionIsolation" must be a boolean');
+    }
+    return {
+        type: "hello",
+        protocol: posInt(o, "protocol"),
+        programVersion: str(o, "programVersion"),
+        os,
+        arch: str(o, "arch"),
+        mode,
+        roots: parseRoots(o.roots),
+        sessionIsolation: o.sessionIsolation,
+    };
+}
+function parseRes(o) {
+    const id = nonEmptyStr(o, "id");
+    if (o.ok === true)
+        return { type: "res", id, ok: true, result: o.result };
+    if (o.ok !== false)
+        throw new DeviceProtocolError('field "ok" must be a boolean');
+    const e = o.error;
+    if (!isRecord(e))
+        throw new DeviceProtocolError('field "error" must be an object');
+    const kind = str(e, "kind");
+    if (kind !== "gone" && kind !== "fs_gone" && kind !== "policy" && kind !== "error") {
+        throw new DeviceProtocolError(`unknown error kind "${kind}"`);
+    }
+    return { type: "res", id, ok: false, error: { kind, message: str(e, "message") } };
+}
+function parseReq(o) {
+    const op = str(o, "op");
+    if (!DEVICE_OPS.includes(op))
+        throw new DeviceProtocolError(`unknown op "${op}"`);
+    const args = obj(o.args, 'field "args"');
+    validateArgs(op, args);
+    return {
+        type: "req",
+        id: nonEmptyStr(o, "id"),
+        op: op,
+        args,
+        deadlineMs: posInt(o, "deadlineMs"),
+    };
+}
+function validateArgs(op, a) {
+    switch (op) {
+        case "exec": {
+            nonEmptyStr(a, "command");
+            posInt(a, "timeoutMs");
+            posInt(a, "maxOutputBytes");
+            str(a, "tag");
+            const actor = obj(a.actor, 'field "actor"');
+            str(actor, "accountId");
+            str(actor, "conversationId");
+            parseLimits(a.limits);
+            if (a.cwd !== undefined)
+                str(a, "cwd");
+            if (a.env !== undefined) {
+                const env = obj(a.env, 'field "env"');
+                for (const k of Object.keys(env))
+                    str(env, k);
+            }
+            return;
+        }
+        case "readFile": {
+            str(a, "path");
+            const m = a.maxBytes;
+            if (typeof m !== "number" || !Number.isInteger(m) || m < 0) {
+                throw new DeviceProtocolError('field "maxBytes" must be a non-negative integer');
+            }
+            return;
+        }
+        case "writeFile":
+            str(a, "path");
+            str(a, "dataB64");
+            return;
+        case "stat":
+            str(a, "path");
+            return;
+        case "killTagged":
+            strArray(a, "tags");
+            return;
+        case "killAll":
+            return;
+        case "create":
+            parseLimits(a.limits);
+            return;
+        case "stop": {
+            const r = str(a, "reason");
+            if (r !== "revoked" && r !== "deleted") {
+                throw new DeviceProtocolError(`unknown stop reason "${r}"`);
+            }
+            return;
+        }
+    }
+}
+export function parseOpResult(op, result) {
+    switch (op) {
+        case "exec": {
+            const r = obj(result, "exec result");
+            const exitCode = r.exitCode;
+            if (exitCode !== null && (typeof exitCode !== "number" || !Number.isFinite(exitCode))) {
+                throw new DeviceProtocolError('field "exitCode" must be a number or null');
+            }
+            return {
+                exitCode: exitCode,
+                stdout: str(r, "stdout"),
+                stderr: str(r, "stderr"),
+                truncated: bool(r, "truncated"),
+                timedOut: bool(r, "timedOut"),
+            };
+        }
+        case "readFile": {
+            if (result === null)
+                return null;
+            const r = obj(result, "readFile result");
+            return { dataB64: str(r, "dataB64"), truncated: bool(r, "truncated") };
+        }
+        case "stat": {
+            if (result === null)
+                return null;
+            const r = obj(result, "stat result");
+            return { size: num(r, "size"), isDir: bool(r, "isDir") };
+        }
+        case "create":
+            return { roots: parseRoots(obj(result, "create result").roots) };
+        default:
+            if (result !== null)
+                throw new DeviceProtocolError(`${op} result must be null`);
+            return null;
+    }
+}
+/**
+ * Parses one WebSocket text frame. `from` is the sender: a device may send `hello` and `res`, the
+ * kernel `req` and `cancel`. Throws {@link DeviceProtocolError} on bad JSON, an unknown `type`,
+ * missing fields or a frame of the wrong direction.
+ */
+export function parseDeviceFrame(raw, from) {
+    let o;
+    try {
+        o = JSON.parse(raw);
+    }
+    catch {
+        throw new DeviceProtocolError("frame is not valid JSON");
+    }
+    if (!isRecord(o))
+        throw new DeviceProtocolError("frame must be a JSON object");
+    const type = o.type;
+    switch (type) {
+        case "hello":
+        case "res":
+            if (from !== "device")
+                throw new DeviceProtocolError(`"${type}" must come from the device`);
+            return type === "hello" ? parseHello(o) : parseRes(o);
+        case "req":
+        case "cancel":
+            if (from !== "kernel")
+                throw new DeviceProtocolError(`"${type}" must come from the kernel`);
+            return type === "req" ? parseReq(o) : { type: "cancel", id: nonEmptyStr(o, "id") };
+        default:
+            throw new DeviceProtocolError(`unknown frame type "${String(type)}"`);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.5";
+export declare const SDK_VERSION = "0.1.0-rc.7";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -8,6 +8,7 @@ export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
 export * from "./define-extension.js";
+export * from "./device-protocol.js";
 export * from "./directory.js";
 export * from "./extension-point.js";
 export * from "./file-preview.js";
@@ -22,6 +23,7 @@ export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";
 export * from "./sandbox.js";
 export * from "./secret.js";
+export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.5";
+export const SDK_VERSION = "0.1.0-rc.7";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -8,6 +8,7 @@ export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
 export * from "./define-extension.js";
+export * from "./device-protocol.js";
 export * from "./directory.js";
 export * from "./extension-point.js";
 export * from "./file-preview.js";
@@ -22,6 +23,7 @@ export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";
 export * from "./sandbox.js";
 export * from "./secret.js";
+export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";

package/dist/marketplace.d.ts

@@ -28,6 +28,8 @@ export declare const MARKETPLACE_LIMITS: {
     readonly plugins: 5000;
     readonly permissionKeys: 500;
     readonly urlChars: 2000;
+    /** Bytes of an entry icon (the plugin icon limit, {@link CONNECTOR_TEMPLATE_LIMITS}). */
+    readonly iconBytes: number;
 };
 /** Where a marketplace entry's plugin comes from. */
 export type MarketplaceSource = {
@@ -75,6 +77,18 @@ export interface MarketplaceEntry {
     };
     /** https URL. */
     homepage?: string;
+    /**
+     * The plugin's icon for marketplace lists, before the plugin is imported (display only; an
+     * imported plugin shows its own icon). Either an absolute `https://` URL whose path ends in
+     * `.svg` / `.png`, or `./<path>.svg|png` inside the marketplace's repository, read at the commit
+     * the marketplace was refreshed at (git marketplaces only; ignored in a marketplace fetched over
+     * http). The kernel downloads it on refresh (network rules of the marketplace downloads, never
+     * with the marketplace token), keeps it when it really is an svg / png of at most
+     * {@link MARKETPLACE_LIMITS}`.iconBytes`, and treats a URL's content as fixed: a new icon needs a
+     * new URL. A missing or invalid icon never fails the refresh. `capybara-plugin marketplace
+     * --write` fills it with the repository path of the plugin's `plugin.json` `icon`.
+     */
+    icon?: 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
@@ -103,6 +117,8 @@ export interface MarketplaceParseOptions {
     /** Tests only: allow http on loopback addresses for `git` / `archive` URLs. */
     allowInsecureLoopback?: boolean;
 }
+/** An entry icon's file extension (of the URL's path, or of the repository path). */
+export declare const MARKETPLACE_ICON_RE: RegExp;
 /**
  * The zod schema of `marketplace.json` (https only; non-strict: unknown fields dropped). The JSON
  * Schema is generated with `z.toJSONSchema(MarketplaceManifestSchema, { io: "input" })`.
@@ -117,6 +133,16 @@ 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 icon (see {@link MarketplaceEntry.icon}): `{ url }` for an absolute URL, `{ path }`
+ * (normalized, without the leading `./`) for a path inside the marketplace's repository, `null`
+ * without one.
+ */
+export declare function marketplaceEntryIcon(e: Pick<MarketplaceEntry, "icon">): {
+    url: string;
+} | {
+    path: 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).