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

package/dist/files/previewers.d.ts

@@ -0,0 +1,100 @@
+import { type FilePreviewer, type Logger, type UiView } from "@capybara-hq/plugin-sdk";
+import type { ConversationFiles } from "../conversations/files.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import type { StorageService } from "../storage/storage.service.js";
+/** Time limit of a previewer's render (UI refresh spec §5.3: 10 s on the conversation page). */
+export declare const FILE_PREVIEW_TIMEOUT_MS = 10000;
+/** A previewer that takes a file, as listed for the conversation page. */
+export interface PreviewerItem {
+    plugin: string;
+    id: string;
+    title: {
+        zh: string;
+        en: string;
+    };
+    kind: "view" | "embed";
+    /** The most bytes the previewer takes: the web caps what it posts to an embed at this. */
+    maxBytes: number;
+}
+/** A previewer in the org's order (the admin list). */
+export interface OrgPreviewerItem extends PreviewerItem {
+    accepts: FilePreviewer["accepts"];
+    maxBytes: number;
+    position: number;
+    disabled: boolean;
+}
+export interface PreviewerRegistryDeps {
+    db: KernelDb;
+    host: Pick<ExtensionHost, "list">;
+    /** Extensions enabled in the org (queried every time). */
+    enabledPlugins(orgId: string): Promise<Set<string>>;
+    files: Pick<ConversationFiles, "file">;
+    storage: Pick<StorageService, "kernel">;
+    log: Pick<Logger, "warn">;
+    /** Default {@link FILE_PREVIEW_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * `file-preview@1` (UI refresh spec §5.8): which previewers take a file, in the org's order
+ * (`capybara.file_previewers` rows first by position, then the rest in provider order; disabled ones
+ * dropped; only extensions enabled in the org), and rendering a view previewer through a read grant
+ * for that one file (valid only during the call, capped at the previewer's `maxBytes`; the extension
+ * never gets a storage key or URL). Providers are validated when they are provided (`ctx.provide`).
+ * Not Nest-dependent; no state across requests.
+ */
+export declare class PreviewerRegistry {
+    private readonly d;
+    private readonly timeoutMs;
+    constructor(d: PreviewerRegistryDeps);
+    /** Every previewer loaded on this replica, in provider order (load order, then list order). */
+    private loaded;
+    /** The org's previewers (enabled extensions only) in its order, disabled ones included. */
+    private ordered;
+    /** The admin list: every previewer of the org's enabled extensions, in order. */
+    list(orgId: string): Promise<OrgPreviewerItem[]>;
+    /**
+     * Sets the org's order: `items` first in the given order (with their `disabled`), the rest after
+     * them in provider order. An item naming no previewer of an enabled extension, or named twice →
+     * 400 `validation_failed`. Only rows of previewers this replica knows are replaced: rows of an
+     * extension that is disabled now (or not loaded here yet) keep their order and `disabled`.
+     * Audited as `org.file_previewers.updated`.
+     */
+    put(orgId: string, items: {
+        plugin: string;
+        id: string;
+        disabled: boolean;
+    }[], actor?: {
+        accountId?: string;
+        tokenId?: string;
+    }): Promise<OrgPreviewerItem[]>;
+    /** Previewers that take this file (viewer must read the conversation), in the org's order. */
+    forFile(orgId: string, conversationId: string, viewer: string, fileId: string): Promise<PreviewerItem[]>;
+    private accepting;
+    /**
+     * Renders a view previewer for one file: 404 `ui.not_found` when it does not take the file (or is
+     * disabled, not enabled, an embed); the render's errors as for plugin views (504 / 502).
+     */
+    render(t: {
+        orgId: string;
+        accountId: string;
+        conversationId: string;
+        fileId: string;
+        plugin: string;
+        id: string;
+        locale: "zh" | "en";
+    }): Promise<UiView>;
+    /**
+     * Whether an embed token for a `file-preview` contribution may be issued for this file: the
+     * viewer reads the conversation, the file is in it, and an enabled previewer of that extension
+     * with `embed: contribution` takes it. Conversation / file not found throws 404.
+     */
+    embedAllowed(t: {
+        orgId: string;
+        accountId: string;
+        conversationId: string;
+        fileId: string;
+        plugin: string;
+        contribution: string;
+    }): Promise<boolean>;
+}

package/dist/files/previewers.js

@@ -0,0 +1,250 @@
+import { FILE_PREVIEW_EXTENSION_POINT, previewerAccepts, validateUiView, } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { callExtension } from "../ui/views.js";
+/** Time limit of a previewer's render (UI refresh spec §5.3: 10 s on the conversation page). */
+export const FILE_PREVIEW_TIMEOUT_MS = 10_000;
+const notFound = () => new ApiError("ui.not_found", "Previewer not found");
+const item = (l) => ({
+    plugin: l.plugin,
+    id: l.previewer.id,
+    title: { zh: l.previewer.title.zh, en: l.previewer.title.en },
+    kind: l.previewer.embed !== undefined ? "embed" : "view",
+    maxBytes: l.previewer.maxBytes,
+});
+/** Reads a stream into one buffer; more than `max` bytes → throws (the grant's cap). */
+async function readAtMost(body, max) {
+    const reader = body.getReader();
+    const chunks = [];
+    let n = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            n += value.byteLength;
+            if (n > max)
+                throw new Error(`the file is larger than this previewer's maxBytes (${max})`);
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const out = new Uint8Array(n);
+    let at = 0;
+    for (const c of chunks) {
+        out.set(c, at);
+        at += c.byteLength;
+    }
+    return out;
+}
+/**
+ * `file-preview@1` (UI refresh spec §5.8): which previewers take a file, in the org's order
+ * (`capybara.file_previewers` rows first by position, then the rest in provider order; disabled ones
+ * dropped; only extensions enabled in the org), and rendering a view previewer through a read grant
+ * for that one file (valid only during the call, capped at the previewer's `maxBytes`; the extension
+ * never gets a storage key or URL). Providers are validated when they are provided (`ctx.provide`).
+ * Not Nest-dependent; no state across requests.
+ */
+export class PreviewerRegistry {
+    d;
+    timeoutMs;
+    constructor(d) {
+        this.d = d;
+        this.timeoutMs = d.timeoutMs ?? FILE_PREVIEW_TIMEOUT_MS;
+    }
+    /** Every previewer loaded on this replica, in provider order (load order, then list order). */
+    loaded() {
+        return this.d.host
+            .list("file-preview")
+            .filter((e) => e.capability === FILE_PREVIEW_EXTENSION_POINT)
+            .flatMap((e) => e.impl.previewers.map((previewer) => ({
+            plugin: e.plugin,
+            previewer,
+            inflight: e.inflight,
+        })));
+    }
+    /** The org's previewers (enabled extensions only) in its order, disabled ones included. */
+    async ordered(orgId) {
+        const enabled = await this.d.enabledPlugins(orgId);
+        const loaded = this.loaded().filter((l) => enabled.has(l.plugin));
+        if (loaded.length === 0)
+            return [];
+        const rows = await this.d.db
+            .selectFrom("file_previewers")
+            .select(["plugin", "previewer_id", "position", "disabled"])
+            .where("org_id", "=", orgId)
+            .execute();
+        const rowOf = new Map(rows.map((r) => [`${r.plugin}/${r.previewer_id}`, r]));
+        const keyed = loaded.map((l, i) => {
+            const r = rowOf.get(`${l.plugin}/${l.previewer.id}`);
+            return { l, r, i };
+        });
+        keyed.sort((a, b) => {
+            if (a.r && b.r)
+                return a.r.position - b.r.position || a.i - b.i;
+            if (a.r)
+                return -1;
+            if (b.r)
+                return 1;
+            return a.i - b.i;
+        });
+        return keyed.map(({ l, r }) => ({ ...l, disabled: r?.disabled ?? false }));
+    }
+    /** The admin list: every previewer of the org's enabled extensions, in order. */
+    async list(orgId) {
+        return (await this.ordered(orgId)).map((l, position) => ({
+            ...item(l),
+            accepts: l.previewer.accepts,
+            position,
+            disabled: l.disabled,
+        }));
+    }
+    /**
+     * Sets the org's order: `items` first in the given order (with their `disabled`), the rest after
+     * them in provider order. An item naming no previewer of an enabled extension, or named twice →
+     * 400 `validation_failed`. Only rows of previewers this replica knows are replaced: rows of an
+     * extension that is disabled now (or not loaded here yet) keep their order and `disabled`.
+     * Audited as `org.file_previewers.updated`.
+     */
+    async put(orgId, items, actor = {}) {
+        const known = new Set((await this.ordered(orgId)).map((l) => `${l.plugin}/${l.previewer.id}`));
+        const seen = new Set();
+        for (const i of items) {
+            const k = `${i.plugin}/${i.id}`;
+            if (!known.has(k) || seen.has(k)) {
+                throw new ApiError("validation_failed", `${k} is not a previewer of an extension enabled in this organization, or is listed twice`);
+            }
+            seen.add(k);
+        }
+        await this.d.db.transaction().execute(async (trx) => {
+            if (known.size > 0) {
+                await trx
+                    .deleteFrom("file_previewers")
+                    .where("org_id", "=", orgId)
+                    .where(sql `plugin || '/' || previewer_id`, "in", [...known])
+                    .execute();
+            }
+            if (items.length > 0) {
+                await trx
+                    .insertInto("file_previewers")
+                    .values(items.map((i, position) => ({
+                    org_id: orgId,
+                    plugin: i.plugin,
+                    previewer_id: i.id,
+                    position,
+                    disabled: i.disabled,
+                })))
+                    .execute();
+            }
+            await audit(trx, {
+                ...(actor.accountId !== undefined && { actorAccountId: actor.accountId }),
+                ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+                orgId,
+                action: "org.file_previewers.updated",
+                detail: { items },
+            });
+        });
+        return this.list(orgId);
+    }
+    /** Previewers that take this file (viewer must read the conversation), in the org's order. */
+    async forFile(orgId, conversationId, viewer, fileId) {
+        const file = await this.d.files.file(orgId, conversationId, viewer, fileId);
+        return (await this.accepting(orgId, file)).map(item);
+    }
+    async accepting(orgId, file) {
+        return (await this.ordered(orgId)).filter((l) => !l.disabled && previewerAccepts(l.previewer, file));
+    }
+    /**
+     * Renders a view previewer for one file: 404 `ui.not_found` when it does not take the file (or is
+     * disabled, not enabled, an embed); the render's errors as for plugin views (504 / 502).
+     */
+    async render(t) {
+        const file = await this.d.files.file(t.orgId, t.conversationId, t.accountId, t.fileId);
+        const l = (await this.accepting(t.orgId, file)).find((x) => x.plugin === t.plugin && x.previewer.id === t.id);
+        const render = l?.previewer.render;
+        if (!l || render === undefined)
+            throw notFound();
+        const maxBytes = l.previewer.maxBytes;
+        const store = this.d.storage.kernel(t.orgId);
+        let open = true;
+        const expired = () => new Error("the file read grant has expired");
+        const fields = { plugin: t.plugin, previewer: t.id, orgId: t.orgId };
+        let view;
+        // The grant ends when the kernel stops waiting (return, throw, timeout, unload), whether or not
+        // the render has settled; read() also refuses once its signal aborted, since an object store
+        // need not honour an already-aborted signal.
+        try {
+            view = await callExtension({
+                log: this.d.log,
+                plugin: t.plugin,
+                what: "file preview",
+                fields,
+                timeoutMs: this.timeoutMs,
+                failCode: "ui.render_failed",
+                failMessage: `Plugin ${t.plugin} failed to preview the file with ${t.id}`,
+                fn: (signal) => l.inflight.run(signal, async (s) => {
+                    try {
+                        return await render.call(l.previewer, {
+                            orgId: t.orgId,
+                            accountId: t.accountId,
+                            conversationId: t.conversationId,
+                            locale: t.locale,
+                            signal: s,
+                            file: {
+                                id: file.id,
+                                name: file.name,
+                                contentType: file.contentType,
+                                size: file.size,
+                            },
+                            read: async () => {
+                                if (!open || s.aborted)
+                                    throw expired();
+                                if (file.size > maxBytes) {
+                                    throw new Error(`the file is larger than this previewer's maxBytes (${maxBytes})`);
+                                }
+                                const got = await store.get(file.objectKey, { signal: s });
+                                if (!got)
+                                    throw new Error("the file is no longer available");
+                                if (!open || s.aborted) {
+                                    await got.body.cancel().catch(() => { });
+                                    throw expired();
+                                }
+                                const bytes = await readAtMost(got.body, maxBytes);
+                                if (!open || s.aborted)
+                                    throw expired();
+                                return bytes;
+                            },
+                        });
+                    }
+                    finally {
+                        open = false;
+                    }
+                }),
+            });
+        }
+        finally {
+            open = false;
+        }
+        const problems = validateUiView(view);
+        if (problems.length > 0) {
+            this.d.log.warn("file previewer returned an invalid view", {
+                ...fields,
+                problems: problems.slice(0, 10),
+            });
+            throw new ApiError("ui.invalid_view", `Plugin ${t.plugin} returned an invalid view`);
+        }
+        return view;
+    }
+    /**
+     * Whether an embed token for a `file-preview` contribution may be issued for this file: the
+     * viewer reads the conversation, the file is in it, and an enabled previewer of that extension
+     * with `embed: contribution` takes it. Conversation / file not found throws 404.
+     */
+    async embedAllowed(t) {
+        const file = await this.d.files.file(t.orgId, t.conversationId, t.accountId, t.fileId);
+        return (await this.accepting(t.orgId, file)).some((l) => l.plugin === t.plugin && l.previewer.embed === t.contribution);
+    }
+}

package/dist/http/api.module.d.ts

@@ -0,0 +1,114 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type DynamicModule } from "@nestjs/common";
+import type { Redis } from "ioredis";
+import type { CatalogService } from "../catalog/catalog.service.js";
+import type { MarketplacesService } from "../catalog/marketplaces.service.js";
+import type { PluginImport } from "../catalog/plugin-import.js";
+import type { ChannelConnections } from "../channels/connections.service.js";
+import type { KernelConfig } from "../config/schema.js";
+import type { AttachmentsService } from "../conversations/attachments.service.js";
+import { type RunControl } from "../conversations/conversations.service.js";
+import type { EventBus, EventLog } from "../conversations/event-log.js";
+import type { Keyring } from "../ctx/secrets.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type EvalQueue } from "../evals/runs.service.js";
+import type { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import type { ExtensionAdmin } from "../extensions/admin-view.js";
+import type { ExtensionDeploymentConfigService } from "../extensions/deployment-config.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import type { ExtensionInstalls } from "../extensions/installs.js";
+import type { OrgExtensionConfigs } from "../extensions/org-config.js";
+import type { KernelIdentity } from "../kernel.js";
+import type { PricesService } from "../models/prices.js";
+import type { ModelPurposesService } from "../models/purposes.js";
+import type { ProviderRegistry } from "../runtime/providers.js";
+import type { SandboxService } from "../sandbox/sandbox.service.js";
+import type { SkillChangesService } from "../skills/changes.service.js";
+import type { SkillsService } from "../skills/skills.service.js";
+import type { StorageService } from "../storage/storage.service.js";
+import type { ApprovalsService } from "../tools/approvals.service.js";
+import type { ConnectorContent } from "../tools/connector-content.js";
+import type { Credentials } from "../tools/credentials.js";
+import type { ToolDrift } from "../tools/drift.js";
+import type { ToolOutputs } from "../tools/outputs.js";
+import type { QuestionsService } from "../tools/questions.service.js";
+import type { ToolRegistry } from "../tools/registry.js";
+/** 内核 API 的依赖：由 createKernel 传入，ApiModule 据此构造各领域服务。 */
+export interface ApiDeps {
+    db: KernelDb;
+    redis: Redis;
+    keyring: Keyring;
+    /** 取当前配置（热更新后返回新配置）。 */
+    config: () => KernelConfig;
+    log: Logger;
+    host: ExtensionHost;
+    /** The same instance as `Kernel.orgExtensionConfigs`. */
+    orgExtensionConfigs: OrgExtensionConfigs;
+    /** 内核总线（命名空间 `kernel`，插件名不能取 `kernel`，不会与插件冲突）。 */
+    bus: EventBus;
+    /** 会话事件日志（与运行 worker 共用同一实例）。 */
+    eventLog: EventLog;
+    /** 模型供应商注册表（与运行 worker 共用同一实例）。 */
+    registry: ProviderRegistry;
+    /** 运行投递与中止。 */
+    runs: RunControl;
+    /** 连接器凭据（与 `Kernel.tools.credentials` 同一实例）。 */
+    credentials: Credentials;
+    /** 工具注册表（与 `Kernel.tools.registry` 同一实例）。 */
+    toolRegistry: ToolRegistry;
+    /** 工具调用审批（与 `Kernel.tools.approvals` 同一实例）。 */
+    approvals: ApprovalsService;
+    /** 工具调用的输入请求（与 `Kernel.tools.questions` 同一实例）。 */
+    questions: QuestionsService;
+    /** 工具定义漂移检测（与 `Kernel.tools.drift` 同一实例；手动刷新走同一套比对）。 */
+    drift: ToolDrift;
+    /** 工具输出存档（与 `Kernel.tools.outputs` 同一实例；网页的运行标签读全文）。 */
+    outputs: ToolOutputs;
+    /** 连接器的 prompts / resources（斜杠命令、@ 资源引用与消息附件）。 */
+    connectorContent: ConnectorContent;
+    /** 外部身份、绑定、第三方登录与离职处理（与 `Kernel.identity` 同一组实例）。 */
+    identity: KernelIdentity;
+    /** 渠道连接（与 `Kernel.channels.connections` 同一实例）。 */
+    channels: ChannelConnections;
+    /** 对话附件（与 `Kernel.attachments` 同一实例）。 */
+    attachments: AttachmentsService;
+    /** 对象存储（与 `Kernel.storage` 同一实例；产物下载用）。 */
+    storage: StorageService;
+    /** 按对话的沙箱（与 `Kernel.sandbox` 同一实例；上下文标签读状态）。 */
+    sandbox: SandboxService;
+    /** 技能库（与 `Kernel.skills` 同一实例）。 */
+    skills: SkillsService;
+    /** agent 自写技能与技能变更审批（与 `Kernel.skillChanges` 同一实例）。 */
+    skillChanges: SkillChangesService;
+    /** 模型价格表（与 `Kernel.prices` 同一实例）。 */
+    prices: PricesService;
+    /** 模型用途映射（与 `Kernel.purposes` 同一实例；评测 worker 的评委也用它）。 */
+    purposes: ModelPurposesService;
+    /** Extension package imports and install records (the same instance as `Kernel.extensionInstalls`). */
+    extensionInstalls: ExtensionInstalls;
+    /** Deployment-level extension admin: list and web approval (the same instance as `Kernel.extensionAdmin`). */
+    extensionAdmin: ExtensionAdmin;
+    /** Deployment-level extension install / enable / disable / uninstall (the same instance as `Kernel.extensionAdminOps`). */
+    extensionAdminOps: ExtensionAdminOps;
+    /** Deployment-level extension config (the same instance as `Kernel.extensionDeploymentConfigs`). */
+    extensionDeploymentConfigs: ExtensionDeploymentConfigService;
+    /** The enterprise catalog (the same instance as `Kernel.catalog`). */
+    catalog: CatalogService;
+    /** Plugin (app bundle) import (the same instance as `Kernel.pluginImport`). */
+    pluginImport: PluginImport;
+    /** Marketplaces (the same instance as `Kernel.marketplaces`). */
+    marketplaces: MarketplacesService;
+    /** 评测队列的生产方（与 worker 同一队列名）。 */
+    evalQueue: Pick<EvalQueue, "enqueue">;
+    /** 删除 agent 后投递销毁它各对话的沙箱（一次性维护任务）；不给时留给不活跃销毁扫描。 */
+    sandboxDestroy?: {
+        destroy(conversationIds: string[]): Promise<void>;
+    };
+}
+/**
+ * 内核 API 模块（`/api/v1/*`），只在角色含 `api` 时挂载。
+ * 全局守卫 `AuthGuard` 默认拒绝：未标注 `@Public()` 的路由一律要求凭据（含根模块的健康检查，它们显式标了 `@Public()`）。
+ */
+export declare class ApiModule {
+    static register(deps: ApiDeps): DynamicModule;
+}