jishushell 0.6.5 → 0.6.18

package/dist/services/capabilities/contract.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lightweight capability protocol contract.
+ *
+ * This file defines the small closed vocabulary Core is allowed to match on.
+ * Provider app ids stay free-form, but `kind + interface` is the only
+ * structured matching protocol for category-token requires. Concrete
+ * capability names remain exact-match strings and are intentionally not
+ * broadened by this helper unless the caller has already decided the require
+ * is a category-token contract require.
+ */
+export declare const CAPABILITY_KINDS: readonly ["llm", "search", "browser", "mcp", "files", "knowledge", "ui", "terminal"];
+export type CapabilityKind = typeof CAPABILITY_KINDS[number];
+export declare const CAPABILITY_INTERFACES_BY_KIND: {
+    readonly llm: readonly ["openai-compatible"];
+    readonly search: readonly ["searxng-json"];
+    readonly browser: readonly ["cdp-ws"];
+    readonly mcp: readonly ["mcp-http", "mcp-sse", "mcp-stdio"];
+    readonly files: readonly ["web-file-manager"];
+    readonly knowledge: readonly ["kb-search"];
+    readonly ui: readonly ["web-ui"];
+    readonly terminal: readonly ["terminal"];
+};
+export type CapabilityInterface = typeof CAPABILITY_INTERFACES_BY_KIND[CapabilityKind][number];
+export interface CapabilityContract {
+    /** Fixed capability class Core knows how to present/apply. */
+    kind: CapabilityKind;
+    /** Wire format/protocol contract; not a provider brand or app id. */
+    interface: CapabilityInterface;
+}
+export interface CapabilityLike {
+    capability?: unknown;
+    kind?: unknown;
+    interface?: unknown;
+    protocol?: unknown;
+}
+export interface CapabilityRequireLike extends CapabilityLike {
+    capability?: unknown;
+}
+export interface CapabilityProviderLike extends CapabilityLike {
+    capability?: unknown;
+}
+export declare function isCapabilityKind(value: unknown): value is CapabilityKind;
+export declare function isCapabilityInterfaceForKind(kind: CapabilityKind, value: unknown): value is CapabilityInterface;
+export declare function categoryFromCapabilityName(capability: string): CapabilityKind | null;
+export declare function isCategoryToken(value: string): boolean;
+export declare function isContractRequire(require: CapabilityRequireLike): boolean;
+export declare function resolveCapabilityContract(input: CapabilityLike): CapabilityContract | null;
+export declare function capabilityMatchesRequire(require: CapabilityRequireLike, provider: CapabilityProviderLike): boolean;
+export declare function knownProviderKindFromCapabilityName(capability: string): string | undefined;
+export declare function providerKindFromCapabilityName(capability: string): string;

package/dist/services/capabilities/contract.js

@@ -0,0 +1,129 @@
+/**
+ * Lightweight capability protocol contract.
+ *
+ * This file defines the small closed vocabulary Core is allowed to match on.
+ * Provider app ids stay free-form, but `kind + interface` is the only
+ * structured matching protocol for category-token requires. Concrete
+ * capability names remain exact-match strings and are intentionally not
+ * broadened by this helper unless the caller has already decided the require
+ * is a category-token contract require.
+ */
+export const CAPABILITY_KINDS = [
+    "llm",
+    "search",
+    "browser",
+    "mcp",
+    "files",
+    "knowledge",
+    "ui",
+    "terminal",
+];
+export const CAPABILITY_INTERFACES_BY_KIND = {
+    llm: ["openai-compatible"],
+    search: ["searxng-json"],
+    browser: ["cdp-ws"],
+    mcp: ["mcp-http", "mcp-sse", "mcp-stdio"],
+    files: ["web-file-manager"],
+    knowledge: ["kb-search"],
+    ui: ["web-ui"],
+    terminal: ["terminal"],
+};
+const KIND_SET = new Set(CAPABILITY_KINDS);
+export function isCapabilityKind(value) {
+    return typeof value === "string" && KIND_SET.has(value);
+}
+export function isCapabilityInterfaceForKind(kind, value) {
+    return typeof value === "string"
+        && CAPABILITY_INTERFACES_BY_KIND[kind].includes(value);
+}
+export function categoryFromCapabilityName(capability) {
+    const dash = capability.indexOf("-");
+    if (dash <= 0)
+        return null;
+    const head = capability.slice(0, dash);
+    return isCapabilityKind(head) ? head : null;
+}
+export function isCategoryToken(value) {
+    // `llm` / `search` / ... are the only require.capability values that opt
+    // into contract matching. `llm-ollama` is not a category token.
+    return isCapabilityKind(value);
+}
+export function isContractRequire(require) {
+    const capability = typeof require.capability === "string" ? require.capability : "";
+    // Exact-vs-contract boundary:
+    // - `capability: llm-ollama` means "bind that exact provider capability".
+    // - `capability: llm` + interface means "bind any provider implementing the
+    //   requested LLM wire contract".
+    // Do not let kind/interface metadata on concrete requires widen matching.
+    return capability ? isCategoryToken(capability) : false;
+}
+function inferLegacyInterface(kind, capability, protocol) {
+    switch (kind) {
+        case "llm":
+            return "openai-compatible";
+        case "search":
+            return capability === "search-searxng" || capability === "search"
+                ? "searxng-json"
+                : null;
+        case "browser":
+            return "cdp-ws";
+        case "files":
+            return "web-file-manager";
+        case "knowledge":
+            return "kb-search";
+        case "ui":
+            return "web-ui";
+        case "terminal":
+            return "terminal";
+        case "mcp": {
+            const normalized = typeof protocol === "string" ? protocol.trim().toLowerCase() : "";
+            if (normalized === "sse")
+                return "mcp-sse";
+            if (normalized === "stdio")
+                return "mcp-stdio";
+            return "mcp-http";
+        }
+    }
+}
+export function resolveCapabilityContract(input) {
+    const capability = typeof input.capability === "string" ? input.capability : "";
+    const explicitKind = isCapabilityKind(input.kind) ? input.kind : null;
+    const legacyKind = capability
+        ? (isCapabilityKind(capability) ? capability : categoryFromCapabilityName(capability))
+        : null;
+    const kind = explicitKind ?? legacyKind;
+    if (!kind)
+        return null;
+    if (isCapabilityInterfaceForKind(kind, input.interface)) {
+        return { kind, interface: input.interface };
+    }
+    const inferred = inferLegacyInterface(kind, capability, input.protocol);
+    return inferred ? { kind, interface: inferred } : null;
+}
+export function capabilityMatchesRequire(require, provider) {
+    const requireCapability = typeof require.capability === "string" ? require.capability : "";
+    const providerCapability = typeof provider.capability === "string" ? provider.capability : "";
+    if (!requireCapability || !providerCapability)
+        return false;
+    if (!isContractRequire(require)) {
+        return providerCapability === requireCapability;
+    }
+    const reqContract = resolveCapabilityContract(require);
+    const providerContract = resolveCapabilityContract(provider);
+    if (reqContract && providerContract) {
+        return providerContract.kind === reqContract.kind
+            && providerContract.interface === reqContract.interface;
+    }
+    return providerCapability === requireCapability;
+}
+export function knownProviderKindFromCapabilityName(capability) {
+    // Compatibility shim for old LLM capability names. This is intentionally
+    // narrower than capability `id`: `id` is provider-local metadata, while
+    // providerKind feeds the embedded LLM proxy's provider-specific behavior.
+    const m = capability.match(/^llm-(ollama|vllm|sglang)$/);
+    return m ? m[1] : undefined;
+}
+export function providerKindFromCapabilityName(capability) {
+    return knownProviderKindFromCapabilityName(capability) ?? "custom";
+}
+//# sourceMappingURL=contract.js.map

package/dist/services/capabilities/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/services/capabilities/contract.ts"],"names":[],"mappings":"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"}

package/dist/services/capabilities/endpoint-validator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * §12 of the app-interconnect design — `validateCapabilityEndpoint`.
+ *
+ * Runs in the transactor's Validate step (§10.3 step 1d), once per resolved
+ * binding, before any persist hook touches durable state. Catches three
+ * classes of registry tampering / drift that the LLM-proxy SSRF guard
+ * (`validateUpstreamUrl`) does NOT cover for non-`proxy-upstream` paths:
+ *
+ *   1. **Fresh re-resolve mismatch**: re-resolve the provider's endpoint
+ *      from its spec, compare host/port/path against the registry entry.
+ *      If they diverge, the registry was tampered after registration.
+ *   2. **Out-of-LAN host**: provider must be on loopback or a private
+ *      LAN range (reuses `isPrivateHost` from llm-proxy/ssrf).
+ *   3. **Protocol whitelist by category**: each category locks the set
+ *      of allowed protocols (see PROTOCOL_WHITELIST below).
+ *
+ * Failure throws `ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400)`.
+ *
+ * **All five inputs are provider-side**, never consumer-side. Callers
+ * looking up the provider spec/provide from the registry entry are
+ * responsible for the lookup; this module only validates.
+ *
+ * Capabilities matching `*-terminal` are skipped entirely — terminals
+ * have no network endpoint to validate.
+ */
+import type { AppSpec, AppProvide } from "../../types.js";
+import type { CapabilityEntry } from "./registry.js";
+import type { CapabilityKind } from "./contract.js";
+export type EndpointCategory = CapabilityKind | "default";
+/**
+ * Validate that `registryEntry` is safe to apply for the given category.
+ * Throws `INVALID_CAPABILITY_ENDPOINT (400)` on any failure; returns void
+ * on success.
+ */
+export declare function validateCapabilityEndpoint(providerSpec: AppSpec, providerInstanceId: string, providerProvide: AppProvide, registryEntry: CapabilityEntry, category: EndpointCategory): void;
+/**
+ * Look up the `providerProvide` block from a registry entry, by matching
+ * `entry.capability` against `spec.provides[].capability`. Returns
+ * `undefined` if no match — caller decides whether that's a hard error or
+ * a soft "skip validation" path (e.g. legacy instances with synthesized specs).
+ */
+export declare function findProviderProvide(spec: AppSpec, capability: string): AppProvide | undefined;

package/dist/services/capabilities/endpoint-validator.js

@@ -0,0 +1,114 @@
+import { resolveProvideEndpoint } from "../app-common/provide-resolver.js";
+import { isPrivateHost } from "../llm-proxy/ssrf.js";
+import { ConnectionError } from "../connections/resolver.js";
+const PROTOCOL_WHITELIST = {
+    llm: new Set(["http", "https"]),
+    search: new Set(["http", "https"]),
+    browser: new Set(["ws", "wss", "http", "https"]),
+    mcp: new Set(["http", "https", "ws", "sse"]),
+    files: new Set(["http", "https"]),
+    knowledge: new Set(["http", "https"]),
+    ui: new Set(["http", "https"]),
+    terminal: new Set(["tcp"]),
+    default: new Set(["http", "https", "ws", "wss", "tcp"]),
+};
+/**
+ * Validate that `registryEntry` is safe to apply for the given category.
+ * Throws `INVALID_CAPABILITY_ENDPOINT (400)` on any failure; returns void
+ * on success.
+ */
+export function validateCapabilityEndpoint(providerSpec, providerInstanceId, providerProvide, registryEntry, category) {
+    const cap = providerProvide.capability ?? registryEntry.capability;
+    // *-terminal capabilities have no reachable endpoint; skip entirely.
+    if (/-terminal$/.test(cap))
+        return;
+    // 1. Fresh re-resolve — registryEntry must match what the provider's
+    //    spec currently resolves to. If anything has been tampered (host,
+    //    port, path) the resolved address in apply hooks would already be
+    //    pointing somewhere unexpected; reject before write.
+    //
+    //    Edge case: canonical specs from `apps/<id>/resolved-spec.yaml`
+    //    always carry `tasks`. The `hasTasks` guard remains as defence in
+    //    depth in case a future migrator writes a degenerate snapshot;
+    //    host / protocol / visibility checks below still apply.
+    const hasTasks = Array.isArray(providerSpec.tasks) && providerSpec.tasks.length > 0;
+    if (hasTasks) {
+        const fresh = resolveProvideEndpoint(providerInstanceId, providerSpec, providerProvide);
+        if (!fresh) {
+            throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Cannot re-resolve endpoint for provider '${providerInstanceId}' capability '${cap}'`, { providerInstanceId, capability: cap, reason: "fresh-resolve-failed" });
+        }
+        const freshPath = fresh.path ?? "";
+        const registryPath = registryEntry.path ?? "";
+        if (fresh.host !== registryEntry.host ||
+            fresh.hostPort !== registryEntry.hostPort ||
+            freshPath !== registryPath) {
+            throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Registry endpoint for provider '${providerInstanceId}' capability '${cap}' does not match current runtime endpoint`, {
+                providerInstanceId,
+                capability: cap,
+                reason: "fresh-resolve-mismatch",
+                details: {
+                    registry: {
+                        host: registryEntry.host,
+                        hostPort: registryEntry.hostPort,
+                        path: registryPath,
+                    },
+                    current: {
+                        host: fresh.host,
+                        hostPort: fresh.hostPort,
+                        path: freshPath,
+                    },
+                },
+            });
+        }
+    }
+    // 1b. Spec vs registry protocol 一致性检查。
+    //     spec 侧 protocol 来自 providerProvide.protocol（两种 spec 都带该字段），
+    //     registry 侧来自 registryEntry.protocol。若两者不一致说明 registry 在注册
+    //     后被篡改（或写入时出错），consumer 端将被导向错误协议，需要拒绝。
+    //     legacy synthetic spec（hasTasks=false）同样执行该检查，因为 provide.protocol
+    //     字段存在于 provide 块上，而非 task 上。
+    //
+    //     trim()+toLowerCase() 必须与 capability sync 的协议规范化完全
+    //     对齐，否则 yaml 里 `protocol: " http "` 之类的写法会让 spec 侧拿到带空格
+    //     的值，而 registry 侧已被 normalize 成 "http"，
+    //     两者比对会误判为篡改。
+    const specProtocol = (providerProvide.protocol ?? "http").trim().toLowerCase();
+    const registryProtocol = String(registryEntry.protocol ?? "").trim().toLowerCase();
+    if (specProtocol !== registryProtocol) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Registry protocol '${registryProtocol}' for provider '${providerInstanceId}' capability '${cap}' does not match spec protocol '${specProtocol}'`, {
+            providerInstanceId,
+            capability: cap,
+            reason: "protocol-spec-mismatch",
+            details: { specProtocol, registryProtocol },
+        });
+    }
+    // 2. Host must be loopback or LAN. We're only ever supposed to bind
+    //    Connections-tab providers to local apps; a public hostname here is
+    //    either a misconfiguration or active SSRF.
+    if (!isPrivateHost(registryEntry.host)) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider host '${registryEntry.host}' is not in the loopback/LAN range`, { providerInstanceId, capability: cap, reason: "host-not-private", host: registryEntry.host });
+    }
+    // 3. Protocol must be in the category-specific whitelist.
+    const allowed = PROTOCOL_WHITELIST[category] ?? PROTOCOL_WHITELIST.default;
+    const protocol = String(registryEntry.protocol ?? "").toLowerCase();
+    if (!protocol || !allowed.has(protocol)) {
+        throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Protocol '${protocol || "(empty)"}' is not allowed for category '${category}'`, {
+            providerInstanceId,
+            capability: cap,
+            reason: "protocol-not-whitelisted",
+            protocol,
+            category,
+            allowed: Array.from(allowed),
+        });
+    }
+}
+/**
+ * Look up the `providerProvide` block from a registry entry, by matching
+ * `entry.capability` against `spec.provides[].capability`. Returns
+ * `undefined` if no match — caller decides whether that's a hard error or
+ * a soft "skip validation" path (e.g. legacy instances with synthesized specs).
+ */
+export function findProviderProvide(spec, capability) {
+    return spec.provides?.find((p) => p.capability === capability);
+}
+//# sourceMappingURL=endpoint-validator.js.map

package/dist/services/capabilities/endpoint-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-validator.js","sourceRoot":"","sources":["../../../src/services/capabilities/endpoint-validator.ts"],"names":[],"mappings":"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"}

package/dist/services/capabilities/health.d.ts

@@ -0,0 +1,16 @@
+import type { CapabilityEntry, CapabilityStatus } from "./registry.js";
+/**
+ * Probe an entry. Cached for 30s per (instanceId, capability) pair.
+ */
+export declare function probe(entry: CapabilityEntry): Promise<CapabilityStatus>;
+/**
+ * Force-refresh the cached probe for a specific entry. Called after
+ * provider start/stop transitions so the UI sees the new status without
+ * waiting for the 30s TTL.
+ */
+export declare function invalidate(entry: CapabilityEntry): void;
+/**
+ * Drop the entire probe cache — used during tests and when registry is
+ * rebuilt at startup.
+ */
+export declare function clearCache(): void;

package/dist/services/capabilities/health.js

@@ -0,0 +1,121 @@
+/**
+ * Capability health prober (§5.6).
+ *
+ * Probes a registered capability endpoint to confirm the provider is
+ * actually listening, before the resolver hands its address to consumers
+ * via Connections binding. Prevents stale registry entries from breaking
+ * downstream apps (e.g. an Ollama instance that was registered then died
+ * — without health probing the consumer would dial a closed port).
+ *
+ * Probe strategy is derived from the entry's protocol when no explicit
+ * `health` spec is provided on the provide:
+ *   - http/https → HEAD on `path || "/"` with 5s timeout
+ *   - ws/wss     → TCP connect on hostPort
+ *   - tcp        → TCP connect on hostPort
+ *   - terminal/  → no-op probe (always "unknown" → status not changed)
+ *     other     → no-op probe
+ *
+ * Results are cached for 30s per capability+instance to avoid hammering
+ * providers on every Connections UI refresh.
+ */
+import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
+import { connect as tcpConnect } from "net";
+const PROBE_TIMEOUT_MS = 5_000;
+const CACHE_TTL_MS = 30_000;
+const _cache = new Map();
+function cacheKey(entry) {
+    return `${entry.instanceId}::${entry.capability}`;
+}
+async function probeHttp(entry) {
+    return new Promise((resolve) => {
+        const isHttps = entry.protocol === "https";
+        const lib = isHttps ? httpsRequest : httpRequest;
+        const path = entry.path && entry.path !== "/" ? entry.path : "/";
+        const req = lib({
+            host: entry.host,
+            port: entry.hostPort,
+            method: "HEAD",
+            path,
+            timeout: PROBE_TIMEOUT_MS,
+        }, (res) => {
+            // Any HTTP response (even 404) means the provider is listening.
+            res.resume();
+            // 5xx responses suggest the provider is up but unhealthy. Treat
+            // them as "running" anyway — the failure mode of "consumer can't
+            // talk to provider" surfaces through the consumer's own error
+            // path; the registry only certifies the port is open.
+            resolve("running");
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            resolve("stopped");
+        });
+        req.on("error", () => resolve("stopped"));
+        req.end();
+    });
+}
+async function probeTcp(entry) {
+    return new Promise((resolve) => {
+        const sock = tcpConnect({ host: entry.host, port: entry.hostPort });
+        let resolved = false;
+        const finish = (status) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                sock.destroy();
+            }
+            catch { /* noop */ }
+            resolve(status);
+        };
+        sock.setTimeout(PROBE_TIMEOUT_MS);
+        sock.once("connect", () => finish("running"));
+        sock.once("timeout", () => finish("stopped"));
+        sock.once("error", () => finish("stopped"));
+    });
+}
+/**
+ * Probe an entry. Cached for 30s per (instanceId, capability) pair.
+ */
+export async function probe(entry) {
+    const key = cacheKey(entry);
+    const hit = _cache.get(key);
+    if (hit && Date.now() - hit.ts < CACHE_TTL_MS)
+        return hit.status;
+    let status = "unknown";
+    const protocol = (entry.protocol || "").toLowerCase();
+    switch (protocol) {
+        case "http":
+        case "https":
+            status = await probeHttp(entry);
+            break;
+        case "tcp":
+        case "ws":
+        case "wss":
+            status = await probeTcp(entry);
+            break;
+        default:
+            // terminal / mcp / sse / unknown — no portable probe; trust registry.
+            status = entry.status;
+            break;
+    }
+    _cache.set(key, { status, ts: Date.now() });
+    return status;
+}
+/**
+ * Force-refresh the cached probe for a specific entry. Called after
+ * provider start/stop transitions so the UI sees the new status without
+ * waiting for the 30s TTL.
+ */
+export function invalidate(entry) {
+    _cache.delete(cacheKey(entry));
+}
+/**
+ * Drop the entire probe cache — used during tests and when registry is
+ * rebuilt at startup.
+ */
+export function clearCache() {
+    _cache.clear();
+}
+//# sourceMappingURL=health.js.map

package/dist/services/capabilities/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/services/capabilities/health.ts"],"names":[],"mappings":"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"}

package/dist/services/capabilities/registry.d.ts

@@ -0,0 +1,56 @@
+import type { CapabilityInterface, CapabilityKind } from "./contract.js";
+export type CapabilityStatus = "running" | "stopped" | "unknown";
+export interface CapabilityEntry {
+    /** Provider instance id that owns this registry entry. */
+    instanceId: string;
+    name?: string;
+    /** Provider-local id from AppSpec provides[].id; metadata only, not matching. */
+    capabilityId?: string;
+    /** URL/registry/exact-match key. Concrete requires match this exactly. */
+    capability: string;
+    /** Structured category for category-token matching and Panel presentation. */
+    kind?: CapabilityKind;
+    /** Wire protocol contract paired with kind; not a provider brand. */
+    interface?: CapabilityInterface;
+    /** LLM proxy provider hint such as "ollama"; never derived from capabilityId. */
+    providerKind?: string;
+    /** Advertised upstream host for Core/proxy use; not a durable identity. */
+    host: string;
+    /** Canonical host-side access port resolved from runtime.ports[].hostPort. */
+    hostPort: number;
+    /** Top-level AppSpec provide path. endpoint.path is intentionally unsupported. */
+    path?: string;
+    /** Human/debug address derived from host + hostPort + path; not a fact source. */
+    address: string;
+    /** Top-level AppSpec provide protocol. endpoint.protocol is intentionally unsupported. */
+    protocol: string;
+    visibility?: "external" | "internal" | string;
+    /** Observed route state written by the lifecycle-status observer. */
+    status: CapabilityStatus;
+    lastSeenRunningAt?: string;
+    registeredAt: string;
+    updatedAt?: string;
+    toolSchema?: import("../../types.js").ToolSchema;
+    auth?: import("../../types.js").AppProvideAuth;
+}
+export interface CapabilityRegistryFile {
+    version: 2;
+    generatedAt?: string;
+    providersByCapability: Record<string, CapabilityEntry[]>;
+}
+export declare function readRegistry(): CapabilityRegistryFile;
+export declare function listProviders(capability: string): CapabilityEntry[];
+export declare function getProviderEntry(instanceId: string, capability: string): CapabilityEntry | undefined;
+/**
+ * Return every capability entry currently registered for an instance.
+ *
+ * Used by the lifecycle status observer (Step 4) to find a running route
+ * candidate before it performs the real Core proxy HTTP probe. Registry
+ * presence means "routable"; it is not the final proof of `ready`.
+ *
+ * Read-only and side-effect free.
+ */
+export declare function listProvidersForInstance(instanceId: string): CapabilityEntry[];
+export declare function replaceProvidersForApp(instanceId: string, entries: CapabilityEntry[]): void;
+export declare function replaceAllProviders(providersByCapability: Record<string, CapabilityEntry[]>): void;
+export declare function snapshot(): CapabilityRegistryFile;