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

package/dist/config/nacos-source.js

@@ -0,0 +1,229 @@
+import { createHash } from "node:crypto";
+import { setTimeout as sleepFor } from "node:timers/promises";
+import { parse, YAMLParseError } from "yaml";
+import { ConfigError } from "./types.js";
+const LONG_POLL_MS = 30_000;
+/** 在令牌有效期的这个比例处续期。 */
+const TOKEN_RENEW_RATIO = 0.8;
+/** 登录响应缺少 tokenTtl 时假定的有效期（Nacos 默认 18000s）。 */
+const DEFAULT_TOKEN_TTL_S = 18_000;
+const LISTEN_TIMEOUT_MS = LONG_POLL_MS + 10_000;
+function normalizeServer(server) {
+    const withScheme = /^https?:\/\//i.test(server) ? server : `http://${server}`;
+    return withScheme.replace(/\/+$/, "");
+}
+function md5(text) {
+    return createHash("md5").update(text).digest("hex");
+}
+/**
+ * 从 Nacos 读取 YAML 配置并可长轮询监听变更。错误信息含 server 与 dataId，但不含响应体、YAML 内容或凭据。
+ * 鉴权见 `NacosSourceOptions.auth`：令牌按需续期（每次请求前检查是否到了续期时刻），不起定时器。
+ */
+export function createNacosSource(opts) {
+    const server = normalizeServer(opts.server);
+    const group = opts.group ?? "DEFAULT_GROUP";
+    const doFetch = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const backoffMs = opts.backoffMs ?? 1_000;
+    const where = `Nacos '${server}' dataId '${opts.dataId}'`;
+    /** 最近一次读到的内容 md5：load() 记录，watch() 据此起步，避免漏掉 load 与 watch 之间的变更。 */
+    let lastMd5;
+    const auth = opts.auth;
+    /** 用户名密码方式登录得到的令牌与应续期的时刻。 */
+    let token;
+    /** 进行中的登录：并发请求共享同一次登录。 */
+    let loggingIn;
+    /**
+     * 用户名密码登录，返回 accessToken。错误信息含 server，不含凭据与响应体。
+     * 只受自身超时约束、不接调用方的中止信号：并发请求共享同一次登录，不能因其中一个调用方取消而让其他调用方失败。
+     */
+    async function login(creds) {
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const failed = (why) => new ConfigError(`Nacos '${server}' login failed: ${why}`);
+        let res;
+        try {
+            res = await doFetch(`${server}/nacos/v1/auth/login`, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({ username: creds.username, password: creds.password }),
+                signal: timeout,
+            });
+        }
+        catch {
+            throw failed(timeout.aborted ? `timed out after ${timeoutMs}ms` : "cannot reach server");
+        }
+        if (res.status !== 200) {
+            await res.body?.cancel().catch(() => { });
+            throw failed(`HTTP ${res.status}`);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            throw failed("non-JSON response");
+        }
+        if (typeof body.accessToken !== "string" || body.accessToken === "") {
+            throw failed("response has no accessToken");
+        }
+        const ttlS = typeof body.tokenTtl === "number" && body.tokenTtl > 0 ? body.tokenTtl : DEFAULT_TOKEN_TTL_S;
+        token = { value: body.accessToken, renewAt: Date.now() + ttlS * 1000 * TOKEN_RENEW_RATIO };
+        return body.accessToken;
+    }
+    /** 当前可用的令牌：无鉴权返回 undefined；用户名密码方式在未登录、到续期时刻或 `force` 时重新登录。 */
+    async function accessToken(force = false) {
+        if (!auth)
+            return undefined;
+        if ("accessToken" in auth)
+            return auth.accessToken;
+        if (!force && token && Date.now() < token.renewAt)
+            return token.value;
+        loggingIn ??= login(auth).finally(() => {
+            loggingIn = undefined;
+        });
+        return loggingIn;
+    }
+    /**
+     * 带令牌发请求：`accessToken` 作为查询参数附加到 URL。用户名密码方式收到 403 时重新登录并重试一次。
+     * 网络错误原样抛出（由调用方转成带上下文的 ConfigError）。
+     */
+    async function authedFetch(url, init) {
+        const withToken = (t) => t === undefined
+            ? url
+            : `${url}${url.includes("?") ? "&" : "?"}${new URLSearchParams({ accessToken: t })}`;
+        const sent = await accessToken();
+        const res = await doFetch(withToken(sent), init);
+        if (res.status !== 403 || !auth || !("username" in auth))
+            return res;
+        await res.body?.cancel().catch(() => { });
+        // 别的并发请求可能已换了新令牌：直接用新的；否则强制重新登录
+        const fresh = token && token.value !== sent ? token.value : await accessToken(true);
+        return doFetch(withToken(fresh), init);
+    }
+    async function fetchText(signal) {
+        const qs = new URLSearchParams({ dataId: opts.dataId, group, namespaceId: opts.namespace });
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+        let res;
+        try {
+            res = await authedFetch(`${server}/nacos/v2/cs/config?${qs}`, { signal: combined });
+        }
+        catch (e) {
+            if (e instanceof ConfigError)
+                throw e;
+            if (timeout.aborted)
+                throw new ConfigError(`${where} timed out after ${timeoutMs}ms`);
+            throw new ConfigError(`cannot reach ${where}`);
+        }
+        if (res.status !== 200) {
+            throw new ConfigError(`${where} returned HTTP ${res.status}`);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            if (timeout.aborted)
+                throw new ConfigError(`${where} timed out after ${timeoutMs}ms`);
+            throw new ConfigError(`${where} returned a non-JSON response`);
+        }
+        if (body.code !== 0 || typeof body.data !== "string") {
+            throw new ConfigError(`${where} returned no config content (code ${String(body.code)})`);
+        }
+        return body.data;
+    }
+    function parseYaml(text) {
+        try {
+            return parse(text) ?? {};
+        }
+        catch (e) {
+            if (e instanceof YAMLParseError) {
+                const pos = e.linePos?.[0];
+                const at = pos ? ` at line ${pos.line}, column ${pos.col}` : "";
+                throw new ConfigError(`invalid YAML from ${where}${at}`);
+            }
+            throw new ConfigError(`invalid YAML from ${where}`);
+        }
+    }
+    async function listen(md5Sent, signal) {
+        const entry = [opts.dataId, group, md5Sent, opts.namespace].join("\u0002");
+        const body = new URLSearchParams({ "Listening-Configs": `${entry}\u0001` });
+        let res;
+        try {
+            res = await authedFetch(`${server}/nacos/v1/cs/configs/listener`, {
+                method: "POST",
+                headers: {
+                    "Long-Pulling-Timeout": String(LONG_POLL_MS),
+                    "content-type": "application/x-www-form-urlencoded",
+                },
+                body,
+                signal: AbortSignal.any([signal, AbortSignal.timeout(LISTEN_TIMEOUT_MS)]),
+            });
+        }
+        catch (e) {
+            if (e instanceof ConfigError)
+                throw e;
+            throw new ConfigError(`cannot reach ${where} (listener)`);
+        }
+        if (res.status !== 200)
+            throw new ConfigError(`${where} listener returned HTTP ${res.status}`);
+        return (await res.text()).trim().length > 0;
+    }
+    return {
+        async load() {
+            const text = await fetchText();
+            lastMd5 = md5(text);
+            return parseYaml(text);
+        },
+        watch(onChange, onError) {
+            const ac = new AbortController();
+            const report = (e) => {
+                if (ac.signal.aborted)
+                    return;
+                const err = e instanceof ConfigError ? e : new ConfigError(`watch failed for ${where}`);
+                try {
+                    onError?.(err);
+                }
+                catch {
+                    // 错误回调自身的异常不能打断监听循环
+                }
+            };
+            void (async () => {
+                while (!ac.signal.aborted) {
+                    try {
+                        if (lastMd5 === undefined)
+                            lastMd5 = md5(await fetchText(ac.signal));
+                        if (!(await listen(lastMd5, ac.signal)))
+                            continue;
+                        const text = await fetchText(ac.signal);
+                        const next = md5(text);
+                        if (next === lastMd5)
+                            continue;
+                        lastMd5 = next;
+                        const raw = parseYaml(text);
+                        if (ac.signal.aborted)
+                            return;
+                        try {
+                            onChange(raw);
+                        }
+                        catch (e) {
+                            throw new ConfigError(`onChange handler failed for ${where}: ${e instanceof Error ? e.name : "error"}`);
+                        }
+                    }
+                    catch (e) {
+                        if (ac.signal.aborted)
+                            return;
+                        report(e);
+                        try {
+                            await sleepFor(backoffMs, undefined, { signal: ac.signal });
+                        }
+                        catch {
+                            return;
+                        }
+                    }
+                }
+            })();
+            return () => ac.abort();
+        },
+    };
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+/** 配置字段的元信息：是否可热更新、是否敏感、说明。 */
+export interface FieldMeta {
+    [key: string]: unknown;
+    hot?: boolean;
+    secret?: boolean;
+    description: string;
+}
+/**
+ * 构造给 Zod 4 `.meta()` 使用的字段元信息。
+ * 用法：`z.string().meta(meta({ secret: true, description: "..." }))`。
+ */
+export declare function meta(opts: FieldMeta): FieldMeta;
+/** `runtime.maxRunSeconds` 的默认值。 */
+export declare const DEFAULT_MAX_RUN_SECONDS = 900;
+/** `sandbox.limits.maxCommandSeconds` 的默认值。 */
+export declare const DEFAULT_MAX_COMMAND_SECONDS = 7200;
+/** access token 寿命上限（秒）；会话吊销标记的 TTL 按它计算，与实例当前配置无关。 */
+export declare const ACCESS_TOKEN_TTL_MAX_SECONDS = 3600;
+/** `attachments.requestMediaBytes` 的上限（24 MiB）：base64 后约 32 MiB，是常见供应商的请求上限。 */
+export declare const REQUEST_MEDIA_BYTES_MAX = 25165824;
+/**
+ * 沙箱出站白名单的默认值（`sandbox.limits.allowHosts`）：常用的包仓库与源码托管（git clone、归档下载、
+ * raw 文件、release 附件）。不预置 `deb.debian.org`：沙箱用户是 uid 1000、没有 sudo，装不了 apt 包，
+ * 放行它只多一个出口；需要系统包的部署把它们装进镜像。组织可以替换这份清单（`sandboxEgress`，Ruling M19）。
+ */
+export declare const DEFAULT_SANDBOX_ALLOW_HOSTS: string[];
+/** `packages.maxBytes` 的默认值（插件包 tgz 的大小上限）；`check:plugin-pack` 用同一个值。 */
+export declare const PACKAGES_MAX_BYTES_DEFAULT = 52428800;
+/**
+ * The default of `marketplaces.official.url`: the official plugins repository, a git marketplace
+ * (spec §5.5). `marketplaces.official.enabled` is on by default; offline deployments and tests turn
+ * it off.
+ */
+export declare const MARKETPLACE_OFFICIAL_URL_DEFAULT = "https://github.com/capybara-hq/plugins.git";
+/** 每个清单来源最多的镜像数。 */
+export declare const MARKETPLACE_MAX_MIRRORS = 5;
+/**
+ * Why a `marketplaces.allowedHosts` entry is refused, or undefined: a hostname or an IP address
+ * (IPv6 without brackets), never a port, scheme or path (entries are compared with the URL's
+ * hostname only).
+ */
+export declare function allowedHostProblem(entry: string): string | undefined;
+/**
+ * Why an `http.trustProxy` list entry is refused, or undefined when it is an IP, a CIDR or a named
+ * range. A /0 prefix is refused: it trusts every address, so any client could forge the header.
+ */
+export declare function trustProxyEntryProblem(entry: string): string | undefined;
+export declare const KernelConfigSchema: z.ZodObject<{
+    db: z.ZodPrefault<z.ZodObject<{
+        url: z.ZodString;
+        poolMax: z.ZodDefault<z.ZodNumber>;
+        connectTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    redis: z.ZodPrefault<z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    masterKey: z.ZodString;
+    masterKeyPrevious: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    extensionConfig: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    extensionHost: z.ZodPrefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        drainSeconds: z.ZodDefault<z.ZodNumber>;
+        disposeTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        reloadSetupTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        migrationTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        reconcileIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    packages: z.ZodPrefault<z.ZodObject<{
+        npmRegistry: z.ZodDefault<z.ZodURL>;
+        npmToken: z.ZodOptional<z.ZodString>;
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    bootstrap: z.ZodPrefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    catalog: z.ZodPrefault<z.ZodObject<{
+        staleInstallMinutes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    marketplaces: z.ZodPrefault<z.ZodObject<{
+        official: z.ZodPrefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            url: z.ZodDefault<z.ZodURL>;
+            mirrors: z.ZodDefault<z.ZodArray<z.ZodURL>>;
+        }, z.core.$strip>>;
+        refreshIntervalMinutes: z.ZodDefault<z.ZodNumber>;
+        maxIndexBytes: z.ZodDefault<z.ZodNumber>;
+        allowInsecureLoopback: z.ZodDefault<z.ZodBoolean>;
+        allowPrivateHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowedHosts: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    }, z.core.$strip>>;
+    net: z.ZodPrefault<z.ZodObject<{
+        httpsProxy: z.ZodOptional<z.ZodString>;
+        noProxy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    extensionPermissions: z.ZodDefault<z.ZodObject<{
+        autoApprove: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    http: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        trustProxy: z.ZodDefault<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>, unknown>>;
+        replicaId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        publicUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    roles: z.ZodDefault<z.ZodPreprocess<z.ZodArray<z.ZodEnum<{
+        api: "api";
+        gateway: "gateway";
+        worker: "worker";
+    }>>, unknown>>;
+    auth: z.ZodDefault<z.ZodObject<{
+        accessTokenTtlSeconds: z.ZodDefault<z.ZodNumber>;
+        refreshTokenTtlDays: z.ZodDefault<z.ZodNumber>;
+        cookieSecure: z.ZodDefault<z.ZodBoolean>;
+        setupToken: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>>;
+        loginSources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        trustedIdentitySources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    runtime: z.ZodDefault<z.ZodObject<{
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        maxRunSeconds: z.ZodDefault<z.ZodNumber>;
+        streamIdleMs: z.ZodDefault<z.ZodNumber>;
+        maxOutputTokens: z.ZodDefault<z.ZodNumber>;
+        compactionThreshold: z.ZodDefault<z.ZodNumber>;
+        keepRecentTurns: z.ZodDefault<z.ZodNumber>;
+        workerConcurrency: z.ZodDefault<z.ZodNumber>;
+        orgConcurrency: z.ZodDefault<z.ZodNumber>;
+        jobLockMs: z.ZodDefault<z.ZodNumber>;
+        stalledIntervalMs: z.ZodDefault<z.ZodNumber>;
+        sseHeartbeatMs: z.ZodDefault<z.ZodNumber>;
+        sseRecheckMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    tools: z.ZodDefault<z.ZodObject<{
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        breakerFailures: z.ZodDefault<z.ZodNumber>;
+        breakerOpenSeconds: z.ZodDefault<z.ZodNumber>;
+        outputSpillChars: z.ZodDefault<z.ZodNumber>;
+        outputPreviewChars: z.ZodDefault<z.ZodNumber>;
+        outputRetentionDays: z.ZodDefault<z.ZodNumber>;
+        approvalTimeoutHours: z.ZodDefault<z.ZodNumber>;
+        searchThresholdTools: z.ZodDefault<z.ZodNumber>;
+        searchThresholdTokens: z.ZodDefault<z.ZodNumber>;
+        driftIntervalHours: z.ZodDefault<z.ZodNumber>;
+        maxResultReadChars: z.ZodDefault<z.ZodNumber>;
+        oauthAllowInsecureLoopback: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    channels: z.ZodDefault<z.ZodObject<{
+        leaseTtlMs: z.ZodDefault<z.ZodNumber>;
+        scanIntervalMs: z.ZodDefault<z.ZodNumber>;
+        shareSlack: z.ZodDefault<z.ZodNumber>;
+        retryBaseMs: z.ZodDefault<z.ZodNumber>;
+        deliveryConcurrency: z.ZodDefault<z.ZodNumber>;
+        deliveryIdleMs: z.ZodDefault<z.ZodNumber>;
+        webhookBaseUrl: z.ZodOptional<z.ZodURL>;
+        webhookMaxBodyBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    storage: z.ZodDefault<z.ZodObject<{
+        purgeDeletedOrgsAfterDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    attachments: z.ZodPrefault<z.ZodObject<{
+        maxBytes: z.ZodDefault<z.ZodNumber>;
+        allowedTypes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            "application/pdf": "application/pdf";
+            "image/gif": "image/gif";
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+            "image/webp": "image/webp";
+            "text/csv": "text/csv";
+            "text/markdown": "text/markdown";
+            "text/plain": "text/plain";
+        }>>>;
+        maxPerMessage: z.ZodDefault<z.ZodNumber>;
+        unboundTtlHours: z.ZodDefault<z.ZodNumber>;
+        requestMediaBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    subagents: z.ZodPrefault<z.ZodObject<{
+        maxConcurrentPerRun: z.ZodDefault<z.ZodNumber>;
+        maxDispatchesPerRun: z.ZodDefault<z.ZodNumber>;
+        maxTokensPerRun: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    sandbox: z.ZodPrefault<z.ZodObject<{
+        image: z.ZodDefault<z.ZodString>;
+        lockWaitSeconds: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentCommands: z.ZodDefault<z.ZodNumber>;
+        deliverMaxBytes: z.ZodDefault<z.ZodNumber>;
+        limits: z.ZodPrefault<z.ZodObject<{
+            cpu: z.ZodDefault<z.ZodNumber>;
+            memoryMb: z.ZodDefault<z.ZodNumber>;
+            diskMb: z.ZodDefault<z.ZodNumber>;
+            maxCommandSeconds: z.ZodDefault<z.ZodNumber>;
+            suspendAfterIdleMinutes: z.ZodDefault<z.ZodNumber>;
+            destroyAfterInactiveDays: z.ZodDefault<z.ZodNumber>;
+            maxRunningMinutes: z.ZodDefault<z.ZodNumber>;
+            egress: z.ZodDefault<z.ZodEnum<{
+                allowlist: "allowlist";
+                none: "none";
+                open: "open";
+            }>>;
+            allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    evals: z.ZodPrefault<z.ZodObject<{
+        orgConcurrency: z.ZodDefault<z.ZodNumber>;
+        workerConcurrency: z.ZodDefault<z.ZodNumber>;
+        defaultTokenCap: z.ZodDefault<z.ZodNumber>;
+        maxTokenCap: z.ZodDefault<z.ZodNumber>;
+        maxCasesPerSet: z.ZodDefault<z.ZodNumber>;
+        maxCaseBytes: z.ZodDefault<z.ZodNumber>;
+        judgeMaxOutputTokens: z.ZodDefault<z.ZodNumber>;
+        maxConsecutiveErrors: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    hooks: z.ZodPrefault<z.ZodObject<{
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        usageReportConcurrency: z.ZodDefault<z.ZodNumber>;
+        usageReportKeepHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    log: z.ZodPrefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            debug: "debug";
+            error: "error";
+            info: "info";
+            warn: "warn";
+        }>>;
+        format: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            json: "json";
+            pretty: "pretty";
+        }>>;
+        loki: z.ZodPrefault<z.ZodObject<{
+            url: z.ZodOptional<z.ZodURL>;
+            username: z.ZodOptional<z.ZodString>;
+            password: z.ZodOptional<z.ZodString>;
+            labels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type KernelConfig = z.infer<typeof KernelConfigSchema>;