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

package/dist/extensions/inflight.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 模型看到的工具结果：调用进行中提供它的插件实例被撤销（停用 / 卸载 / 升级），排空时限到了仍未结束而被中止。
+ * 模型可见文案，一律英文。
+ */
+export declare const PLUGIN_UNLOADED_TOOL_ERROR = "The plugin that provides this tool was disabled or upgraded while the call was running, so the call was aborted. Retry if the tool is still available.";
+/** 调用落在已撤销（或正在撤销）的插件实例上。 */
+export declare class ExtensionUnloadedError extends Error {
+    readonly plugin: string;
+    constructor(plugin: string);
+}
+/** {@link InflightTracker.enter} 的返回：合并后的信号与离开函数（幂等）。 */
+export interface InflightEntry {
+    signal: AbortSignal;
+    leave(): void;
+}
+/**
+ * 一个插件实例的在途调用计数（本进程内、只跟踪本进程发起的调用）。撤销时：
+ * `close()` 停止接新的 → `drain(ms)` 等在途的结束（或到时限）→ `abort()` 中止余下的。
+ */
+export declare class InflightTracker {
+    private readonly plugin;
+    private n;
+    private closed;
+    private readonly ac;
+    private idle;
+    constructor(plugin: string);
+    /** 进行中的调用数。 */
+    get size(): number;
+    /** Aborted when the instance is aborted (reason is an {@link ExtensionUnloadedError}). */
+    get signal(): AbortSignal;
+    /** Records the start of a call; throws {@link ExtensionUnloadedError} when closed. The returned signal aborts when the caller's signal or the instance aborts. */
+    enter(signal: AbortSignal): InflightEntry;
+    /**
+     * Tracks running `fn`, racing the instance abort: when the instance is aborted it ends right away
+     * with {@link ExtensionUnloadedError} (an `fn` that ignores the signal stays in the background, its
+     * result dropped).
+     */
+    run<T>(signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /** 停止接新的调用（幂等）。 */
+    close(): void;
+    /** 停止接新的，等在途调用全部结束，最多 `ms` 毫秒。 */
+    drain(ms: number): Promise<"drained" | "timeout">;
+    /** 中止余下的在途调用（幂等）；此后 `enter` 抛错。 */
+    abort(): void;
+    /** {@link trackCalls} 的包装缓存（同一实现对象 → 同一个代理），随实例回收。 */
+    readonly tracked: WeakMap<object, unknown>;
+}
+/** {@link trackCalls} 的选项。 */
+export interface TrackOptions {
+    /**
+     * 返回「会话」的方法名（如 connector 的 `open`）：resolve 出的对象在 `close()` 之前一直计入在途，
+     * 会话上的其余方法与实例中止竞速。
+     */
+    sessions?: readonly string[];
+}
+/**
+ * Wraps a provider's extension point implementation (connector / sandbox / model-provider, resolved
+ * live by the kernel each time) in a proxy counted in the instance's in-flight tracker:
+ * - each method call `enter`s, and leaves when the Promise settles, the AsyncIterable finishes (or
+ *   return / throw), or a session `close()`s;
+ * - an `AbortSignal` in the arguments (or the `signal` field of a plain object argument) becomes
+ *   "caller signal ∪ instance abort", so the provider sees the abort when the instance aborts;
+ * - it races the instance abort: a call still running when the drain limit is reached ends with
+ *   {@link ExtensionUnloadedError};
+ * - when the instance is already being revoked (tracker closed) a new call throws
+ *   {@link ExtensionUnloadedError} synchronously.
+ * Non-function properties pass through. The same (tracker, impl) returns the same proxy.
+ */
+export declare function trackCalls<T extends object>(impl: T, tracker: InflightTracker, opts?: TrackOptions): T;

package/dist/extensions/inflight.js

@@ -0,0 +1,277 @@
+/**
+ * 模型看到的工具结果：调用进行中提供它的插件实例被撤销（停用 / 卸载 / 升级），排空时限到了仍未结束而被中止。
+ * 模型可见文案，一律英文。
+ */
+export const PLUGIN_UNLOADED_TOOL_ERROR = "The plugin that provides this tool was disabled or upgraded while the call was running, so the call was aborted. Retry if the tool is still available.";
+/** 调用落在已撤销（或正在撤销）的插件实例上。 */
+export class ExtensionUnloadedError extends Error {
+    plugin;
+    constructor(plugin) {
+        super(`plugin ${plugin} was unloaded`);
+        this.plugin = plugin;
+        this.name = "ExtensionUnloadedError";
+    }
+}
+/**
+ * 一个插件实例的在途调用计数（本进程内、只跟踪本进程发起的调用）。撤销时：
+ * `close()` 停止接新的 → `drain(ms)` 等在途的结束（或到时限）→ `abort()` 中止余下的。
+ */
+export class InflightTracker {
+    plugin;
+    n = 0;
+    closed = false;
+    ac = new AbortController();
+    idle = [];
+    constructor(plugin) {
+        this.plugin = plugin;
+    }
+    /** 进行中的调用数。 */
+    get size() {
+        return this.n;
+    }
+    /** Aborted when the instance is aborted (reason is an {@link ExtensionUnloadedError}). */
+    get signal() {
+        return this.ac.signal;
+    }
+    /** Records the start of a call; throws {@link ExtensionUnloadedError} when closed. The returned signal aborts when the caller's signal or the instance aborts. */
+    enter(signal) {
+        if (this.closed)
+            throw new ExtensionUnloadedError(this.plugin);
+        this.n += 1;
+        let left = false;
+        return {
+            signal: AbortSignal.any([signal, this.ac.signal]),
+            leave: () => {
+                if (left)
+                    return;
+                left = true;
+                this.n -= 1;
+                if (this.n === 0) {
+                    const waiters = this.idle;
+                    this.idle = [];
+                    for (const w of waiters)
+                        w();
+                }
+            },
+        };
+    }
+    /**
+     * Tracks running `fn`, racing the instance abort: when the instance is aborted it ends right away
+     * with {@link ExtensionUnloadedError} (an `fn` that ignores the signal stays in the background, its
+     * result dropped).
+     */
+    async run(signal, fn) {
+        const e = this.enter(signal);
+        let onAbort = () => { };
+        const aborted = new Promise((_, reject) => {
+            onAbort = () => reject(new ExtensionUnloadedError(this.plugin));
+            if (this.ac.signal.aborted)
+                onAbort();
+            else
+                this.ac.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        aborted.catch(() => { });
+        try {
+            const p = (async () => fn(e.signal))();
+            p.catch(() => { });
+            return await Promise.race([p, aborted]);
+        }
+        finally {
+            this.ac.signal.removeEventListener("abort", onAbort);
+            e.leave();
+        }
+    }
+    /** 停止接新的调用（幂等）。 */
+    close() {
+        this.closed = true;
+    }
+    /** 停止接新的，等在途调用全部结束，最多 `ms` 毫秒。 */
+    async drain(ms) {
+        this.close();
+        if (this.n === 0)
+            return "drained";
+        let timer;
+        let resolveIdle = () => { };
+        const idle = new Promise((resolve) => {
+            resolveIdle = () => resolve("drained");
+            this.idle.push(resolveIdle);
+        });
+        try {
+            return await Promise.race([
+                idle,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve("timeout"), Math.max(0, ms));
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            this.idle = this.idle.filter((w) => w !== resolveIdle);
+        }
+    }
+    /** 中止余下的在途调用（幂等）；此后 `enter` 抛错。 */
+    abort() {
+        this.close();
+        if (!this.ac.signal.aborted)
+            this.ac.abort(new ExtensionUnloadedError(this.plugin));
+    }
+    /** {@link trackCalls} 的包装缓存（同一实现对象 → 同一个代理），随实例回收。 */
+    tracked = new WeakMap();
+}
+const isPromiseLike = (v) => typeof v?.then === "function";
+const isAsyncIterable = (v) => typeof v?.[Symbol.asyncIterator] === "function";
+const isPlainObject = (v) => typeof v === "object" && v !== null && Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Wraps a provider's extension point implementation (connector / sandbox / model-provider, resolved
+ * live by the kernel each time) in a proxy counted in the instance's in-flight tracker:
+ * - each method call `enter`s, and leaves when the Promise settles, the AsyncIterable finishes (or
+ *   return / throw), or a session `close()`s;
+ * - an `AbortSignal` in the arguments (or the `signal` field of a plain object argument) becomes
+ *   "caller signal ∪ instance abort", so the provider sees the abort when the instance aborts;
+ * - it races the instance abort: a call still running when the drain limit is reached ends with
+ *   {@link ExtensionUnloadedError};
+ * - when the instance is already being revoked (tracker closed) a new call throws
+ *   {@link ExtensionUnloadedError} synchronously.
+ * Non-function properties pass through. The same (tracker, impl) returns the same proxy.
+ */
+export function trackCalls(impl, tracker, opts = {}) {
+    const hit = tracker.tracked.get(impl);
+    if (hit)
+        return hit;
+    const sessions = new Set(opts.sessions ?? []);
+    const proxy = wrapMethods(impl, tracker, (prop, entry, result) => {
+        if (sessions.has(prop) && isPromiseLike(result)) {
+            return raceAbort(tracker, result).then((v) => {
+                if (typeof v === "object" && v !== null)
+                    return wrapSession(v, tracker, entry);
+                entry.leave();
+                return v;
+            }, (e) => {
+                entry.leave();
+                throw e;
+            });
+        }
+        return settle(tracker, entry, result);
+    });
+    tracker.tracked.set(impl, proxy);
+    return proxy;
+}
+/** 方法代理：每次调用 enter → 替换信号 → 调原方法 → 交给 `after` 决定何时离开。 */
+function wrapMethods(impl, tracker, after) {
+    const fns = new Map();
+    return new Proxy(impl, {
+        get(target, prop, receiver) {
+            const v = Reflect.get(target, prop, receiver);
+            if (typeof v !== "function")
+                return v;
+            let w = fns.get(prop);
+            if (!w) {
+                w = (...args) => {
+                    const entry = tracker.enter(NEVER);
+                    const call = args.map((a) => {
+                        if (a instanceof AbortSignal)
+                            return AbortSignal.any([a, tracker.signal]);
+                        if (isPlainObject(a) && a.signal instanceof AbortSignal) {
+                            return { ...a, signal: AbortSignal.any([a.signal, tracker.signal]) };
+                        }
+                        return a;
+                    });
+                    let r;
+                    try {
+                        r = v.apply(target, call);
+                    }
+                    catch (e) {
+                        entry.leave();
+                        throw e;
+                    }
+                    return after(String(prop), entry, r);
+                };
+                fns.set(prop, w);
+            }
+            return w;
+        },
+    });
+}
+/** 永不中止的信号（{@link InflightTracker.enter} 需要一个调用方信号；这里的中止由参数里的信号负责）。 */
+const NEVER = new AbortController().signal;
+/** 普通结果：Promise settle 时离开（与中止竞速）；AsyncIterable 迭代结束时离开；其余立即离开。 */
+function settle(tracker, entry, r) {
+    if (isPromiseLike(r)) {
+        return raceAbort(tracker, r).finally(() => entry.leave());
+    }
+    if (isAsyncIterable(r))
+        return wrapIterable(r, tracker, entry);
+    entry.leave();
+    return r;
+}
+/** Races the instance abort: rejects with ExtensionUnloadedError on abort (the original Promise stays in the background, its result is dropped). */
+function raceAbort(tracker, p) {
+    const own = Promise.resolve(p);
+    own.catch(() => { });
+    const signal = tracker.signal;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    let onAbort = () => { };
+    const aborted = new Promise((_, reject) => {
+        onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    aborted.catch(() => { });
+    return Promise.race([own, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+}
+/** 流：每次 next 与中止竞速；done / return / throw / 出错时离开。 */
+function wrapIterable(src, tracker, entry) {
+    return {
+        [Symbol.asyncIterator]() {
+            const it = src[Symbol.asyncIterator]();
+            return {
+                async next() {
+                    try {
+                        const r = await raceAbort(tracker, it.next());
+                        if (r.done)
+                            entry.leave();
+                        return r;
+                    }
+                    catch (e) {
+                        entry.leave();
+                        throw e;
+                    }
+                },
+                async return(value) {
+                    entry.leave();
+                    return it.return ? it.return(value) : { done: true, value };
+                },
+                async throw(err) {
+                    entry.leave();
+                    if (it.throw)
+                        return it.throw(err);
+                    throw err;
+                },
+            };
+        },
+    };
+}
+/** 会话：`close()` 时离开（幂等）；其余方法与实例中止竞速（整个会话已计一次在途）。 */
+function wrapSession(session, tracker, entry) {
+    return new Proxy(session, {
+        get(target, prop, receiver) {
+            const v = Reflect.get(target, prop, receiver);
+            if (typeof v !== "function")
+                return v;
+            if (prop === "close") {
+                return async (...args) => {
+                    try {
+                        return await v.apply(target, args);
+                    }
+                    finally {
+                        entry.leave();
+                    }
+                };
+            }
+            return (...args) => {
+                const r = v.apply(target, args);
+                return isPromiseLike(r) ? raceAbort(tracker, r) : r;
+            };
+        },
+    });
+}

package/dist/extensions/installs.d.ts

@@ -0,0 +1,166 @@
+import { type PluginExtensionSection } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type ProvenanceResult } from "../packages/provenance.js";
+import type { ExtensionBlobs } from "./blobs.js";
+import { migrationWarnings, type PackageWarning, type PermissionGroup, type PermissionItem } from "./permission-view.js";
+export { migrationWarnings, type PackageWarning };
+import type { ExtensionSource } from "./sources.js";
+/** 上传 / 拉取一个包后的审阅结果（权限按静态清单与迁移 SQL 计算，不执行插件代码）。 */
+export interface PackageReview {
+    sha256: string;
+    name: string;
+    version: string;
+    permissions: PermissionGroup[];
+    /** 相对该插件当前权限快照多出 / 少了的权限键（没有快照时全部算新增）。 */
+    added: string[];
+    /** `added` 逐项的敏感标记与原因（界面据此高亮，不自己判定）。 */
+    addedItems: PermissionItem[];
+    removed: string[];
+    /** 见 {@link reviewHash}：批准时回传，审阅后权限变了就拒绝。 */
+    reviewHash: string;
+    /**
+     * 审阅警告（敏感，界面高亮；不拒绝）：插件迁移只该做扩展，包里的破坏性语句（删表 / 删列、TRUNCATE、DELETE、
+     * RENAME、改列类型）逐条列出——新旧版本会在不同副本上同时运行，破坏性迁移可能让旧版本出错或丢数据。
+     */
+    warnings: PackageWarning[];
+}
+/** One install record (`extension_installs` plus the package's npm name). */
+export interface ExtensionInstallRow {
+    name: string;
+    sha256: string;
+    version: string;
+    source: "npm" | "file" | "catalog" | "bootstrap";
+    packageName: string;
+    desiredState: "enabled" | "disabled";
+    /** A required bootstrap plugin (enabled in every org; cannot be disabled or uninstalled). */
+    required: boolean;
+    migratedSha: string | null;
+    installedBy: string | null;
+    installedAt: string;
+    updatedBy: string | null;
+    updatedAt: string;
+}
+/** 期望启用的安装记录（各副本据此同步并加载）。 */
+export interface DesiredExtension {
+    name: string;
+    sha256: string;
+    version: string;
+    source: "npm" | "file" | "catalog" | "bootstrap";
+    migratedSha: string | null;
+    /**
+     * Where the package bytes are kept. At startup the host loads the packages kept in PG first: the
+     * object store serving the others may itself be one of them (a bootstrap plugin).
+     */
+    blobStore?: "object" | "pg";
+    /**
+     * The reviewed extension section of the plugin (the migrations path is taken only from here). A
+     * row stored before 0.1.0 holds the old `capybara` section instead; its package is in the old
+     * format and fails to sync with `extension.legacy_format`.
+     */
+    section: PluginExtensionSection;
+}
+/**
+ * Where a package comes from (F-L): catalog / marketplace / app imports all record `catalog`, with
+ * `ref` locating the item or the marketplace entry; the bootstrap step records `bootstrap`
+ * (`ref` `bootstrap:<name>@<version>`).
+ */
+export interface IngestSource {
+    source: "npm" | "file" | "catalog" | "bootstrap";
+    ref: string;
+}
+export interface ExtensionInstallsDeps {
+    db: KernelDb;
+    blobs: ExtensionBlobs;
+    config: () => KernelConfig;
+    /** 配置声明的插件名 → 来源（安装包不能与它们重名，C15）。 */
+    declared: () => ReadonlyMap<string, ExtensionSource>;
+    /** npm 下载的总时限（毫秒），默认 120s。 */
+    npmTimeoutMs?: number;
+}
+/** 插件安装记录与包的导入（上传文件、npm）。本身无状态，多副本共用。 */
+export declare class ExtensionInstalls {
+    private readonly d;
+    constructor(d: ExtensionInstallsDeps);
+    /**
+     * Validates and stores one package and returns the review; audits `extension.package_uploaded`.
+     * Only stores: no install, no desired state change (T14).
+     * - Over `packages.maxBytes` -> `extension.package_too_large`; invalid package ->
+     *   `extension.package_invalid` (details list each problem);
+     * - extension name equal to a config-declared one -> `extension.config_declared`;
+     * - an install record of the same name comes from another npm package -> `extension.name_conflict`
+     *   (a new version of the same package is an upgrade, handled elsewhere).
+     * `actor` null means the CLI (no enterprise admin re-check, audit without an actor).
+     */
+    ingest(actor: string | null, bytes: Uint8Array, src: IngestSource, opts?: {
+        actorTokenId?: string;
+        store?: "object" | "pg";
+        expectPackageName?: string;
+    }): Promise<PackageReview>;
+    /** 上传的 tgz（来源 `file`）。 */
+    ingestFile(actor: string | null, bytes: Uint8Array, opts?: {
+        actorTokenId?: string;
+        store?: "object" | "pg";
+    }): Promise<PackageReview>;
+    /**
+     * Fetches one package from the configured npm registry (verified by `dist.integrity`, see
+     * packages/npm.ts), downloading only, not storing: download failure -> `packages.npm_failed` (502);
+     * over `packages.maxBytes` -> `extension.package_too_large`. Enterprise catalog npm imports use it
+     * too.
+     */
+    fetchNpm(input: {
+        package: string;
+        version?: string;
+    }, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        version: string;
+        integrity: string;
+    }>;
+    /**
+     * Downloads the package of a marketplace npm source (T24, C26): from `tarball` when given (https
+     * required, `marketplaces.allowInsecureLoopback` for tests only; no registry metadata request;
+     * `packages.npmToken` is sent only when the tarball has the registry's origin), otherwise from the
+     * configured npm registry; always verified against the marketplace's sha512, never npm metadata.
+     * Mismatch -> 502 `marketplace.integrity_mismatch` (with prefixes of the expected and actual sha512);
+     * download failure -> 502 `marketplace.fetch_failed`; over `packages.maxBytes` ->
+     * `extension.package_too_large`.
+     */
+    fetchMarketplacePackage(input: {
+        package: string;
+        version: string;
+        integrity: string;
+        tarball?: string;
+    }, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        version: string;
+        integrity: string;
+    }>;
+    /**
+     * The npm provenance of `name@version` from the configured registry (spec §5.5; display only,
+     * see packages/provenance.ts): bounded to {@link PROVENANCE_TIMEOUT_MS} and never throws, a
+     * failure is `{ checked: false, reason }`. `integrity` ties the statement to the tarball.
+     */
+    fetchProvenance(input: {
+        package: string;
+        version: string;
+        integrity?: string;
+    }, signal?: AbortSignal): Promise<ProvenanceResult>;
+    private fetchVerified;
+    /**
+     * Fetches from the configured npm registry (source `npm`, `ref` is `<package>@<version>`). Download
+     * failure -> `packages.npm_failed` (502); over the size limit -> `extension.package_too_large`; the
+     * npm name in the package differs from the requested one -> `extension.package_invalid`.
+     */
+    ingestNpm(actor: string | null, input: {
+        package: string;
+        version?: string;
+    }, opts?: {
+        actorTokenId?: string;
+        store?: "object" | "pg";
+        signal?: AbortSignal;
+    }): Promise<PackageReview>;
+    /** 全部安装记录（按名字）。 */
+    list(): Promise<ExtensionInstallRow[]>;
+    /** Install records desired enabled, with their reviewed extension sections (by name). */
+    desired(): Promise<DesiredExtension[]>;
+}