@tianshu-ai/tianshu 0.3.0

package/packages/server/dist/core/plugins/registry.d.ts

@@ -0,0 +1,269 @@
+import type { AgentTool, CapabilityName, PluginManifest, PluginRouteHandler, PluginServerExports, PluginServerModule, PluginWsHandler } from "@tianshu/plugin-sdk";
+import type { TenantContext } from "../tenant-context.js";
+import { type LoadedSkill } from "./skills.js";
+export type PluginState = "active" | "disabled" | "failed" | "client-bundle-missing";
+export interface ActivePluginEntry {
+    manifest: PluginManifest;
+    source: "builtin" | "tenant";
+    dir: string;
+    state: PluginState;
+    failedReason?: string;
+    /** Available iff state === "active" */
+    exports?: PluginServerExports;
+    /**
+     * The resolved server module. Held so `invalidate()` can call
+     * the plugin's `deactivate()` hook before dropping the cache;
+     * without this, e.g. microsandbox VMs would orphan when a tenant
+     * disables the plugin or evicts its DB pool entry.
+     */
+    module?: PluginServerModule;
+    /** Capability inventory for this plugin, computed at activation
+     *  time. Always present; empty arrays when nothing applies. */
+    capabilityInfo: PluginCapabilityInfo;
+}
+export interface PluginCapabilityInfo {
+    /** Capabilities this plugin provided successfully (registered in
+     *  `byCapability`). Empty for non-active plugins. */
+    provided: CapabilityName[];
+    /** Capabilities the manifest's `requires[]` listed. Always present
+     *  regardless of state. */
+    requires: CapabilityName[];
+    /** Subset of `requires` that no other plugin provided in this
+     *  tenant. For active plugins this is always empty (we wouldn't
+     *  have activated). For failed plugins it explains why. */
+    missing: CapabilityName[];
+}
+export interface ProvidedCapability {
+    capability: CapabilityName;
+    pluginId: string;
+    exclusive: boolean;
+    value: unknown;
+}
+/**
+ * Cross-source view of one MCP toolset surfaced through
+ * `toolsetsForTenant()`. Either contributed by a plugin or
+ * configured by the user; the consumer (admin UI / agent loop)
+ * decides what to do with that distinction.
+ */
+export interface ToolsetSummary {
+    /** Where the toolset came from. */
+    source: "plugin" | "user";
+    /** Plugin id when source==plugin; literal `"core"` when source==user. */
+    sourceId: string;
+    /** Local id within the source. */
+    id: string;
+    /** Display label for the admin UI. */
+    displayName: string;
+    /** False only for user entries explicitly marked enabled=false. */
+    enabled: boolean;
+    /** ToolsetProvider's `name` (often == displayName but sometimes
+     *  finer-grained, e.g. McpToolset(name="playwright")). */
+    providerName: string;
+    /** McpToolset.snapshot() output when the provider exposes
+     *  snapshot(); null otherwise. */
+    snapshot: import("@tianshu/plugin-sdk").McpToolsetSnapshot | null;
+    /** Reflected tool count (snapshot.tools.length when known, else
+     *  derived via listTools()). */
+    toolCount: number;
+    /** Verbatim user-config entry. Only present for source==user. */
+    userEntry?: {
+        id: string;
+        displayName?: string;
+        url: string;
+        prefix?: string;
+        upstreamHost?: string;
+        enabled: boolean;
+    };
+}
+export interface ServerPluginModuleResolver {
+    /**
+     * Given a plugin's `manifest.server.entry` string, return the
+     * corresponding module. The host (server bin) wires the resolver up
+     * with a static map of builtin entries; v1 will add dynamic
+     * `import()` for tenant plugins.
+     */
+    resolve(entry: string): Promise<PluginServerModule | null> | PluginServerModule | null;
+}
+export interface RegistryOpts {
+    resolver: ServerPluginModuleResolver;
+    /**
+     * Optional host-owned MCP manager. When present, user-configured
+     * MCP toolsets (`tenant config.mcp.servers[]`) are merged into
+     * `toolsForTenant()` alongside plugin-contributed ones, and
+     * surface in `toolsetsForTenant()` with `source: "user"`.
+     *
+     * Optional so tests / older wirings still work without it.
+     */
+    mcpManager?: import("../mcp-manager.js").McpManager;
+    /** Optional discovery override (for tests). */
+    discoveryDirs?: {
+        builtinConfigDir?: string;
+        home?: string;
+    };
+    /** Optional broadcast hook for the plugin context. Default no-op. */
+    broadcast?: (tenantId: string, type: string, payload: unknown) => void;
+    /**
+     * Capabilities the host itself provides (i.e. not coming from a
+     * plugin's `provides[]`). Pre-seeded into every tenant's
+     * capability map BEFORE plugin activation so plugins listing the
+     * same name in `requires[]` can pick them up.
+     *
+     * Each entry is a factory: it gets the tenant context and
+     * returns the capability value to expose. This lets host-side
+     * capabilities bind per-tenant state (db, config) without the
+     * plugin needing to know about it.
+     *
+     * Today the only entry is `host.agentLoop` (the workboard plugin
+     * uses it to run LLM workers). Adding new ones is a host change,
+     * not a plugin change.
+     */
+    hostCapabilities?: Partial<Record<CapabilityName, (ctx: TenantContext) => unknown>>;
+    /**
+     * Optional loader for skills shipped with the host repo (under
+     * `<server-package>/skills/`). Wired by the boot sequence so
+     * `ensureForTenant` can mirror them into the tenant config tree
+     * alongside plugin skills, and so `mirroredSkillsForTenant`
+     * returns a single unified list. Without this loader the
+     * registry just mirrors plugin skills, which keeps tests
+     * dependency-free.
+     */
+    hostSkillsLoader?: () => readonly LoadedSkill[];
+}
+export declare class PluginRegistry {
+    private readonly opts;
+    private readonly cache;
+    constructor(opts: RegistryOpts);
+    /** Idempotent: returns cached if already initialised for this tenant. */
+    ensureForTenant(ctx: TenantContext): Promise<ActivePluginEntry[]>;
+    /**
+     * Plugin + host skills, with `filePath` pointing at the
+     * mirrored copy under `_tenant/config/skills/_host/...`.
+     * Replaces `skillsForTenant` for runtime callers (system
+     * prompt, tool factories). The original method is kept for
+     * tests that pre-date the mirror layer.
+     */
+    mirroredSkillsForTenant(tenantId: string): LoadedSkill[];
+    /**
+     * Drop a tenant's cached registry. Calls each active plugin's
+     * `deactivate()` hook (best-effort, sequential) so plugins can
+     * release resources — sandbox VMs, child processes, file
+     * watchers, etc. — before the next `ensureForTenant()` rebuilds
+     * everything from scratch.
+     *
+     * Returns a promise so callers that want to ensure deactivation
+     * finished before re-entering `ensureForTenant` can await it. The
+     * existing `void`-returning callers (e.g. tenant softDelete on
+     * pool eviction) ignore the promise and that's fine — the host
+     * just won't wait for slow shutdowns to land.
+     */
+    invalidate(tenantId: string): Promise<void>;
+    private runDeactivations;
+    /** For routes layer: look up the WS handler for a {tenant, type}. */
+    resolveWsHandler(tenantId: string, type: string): {
+        entry: ActivePluginEntry;
+        handler: PluginWsHandler;
+    } | undefined;
+    /** For routes layer: list all plugins (active + disabled + failed). */
+    listForTenant(tenantId: string): ActivePluginEntry[];
+    /** For agent / other host code: read the tenant capability registry. */
+    capabilityFor<T = unknown>(tenantId: string, name: CapabilityName): T | undefined;
+    /**
+     * Collect every tool every active plugin contributed for this
+     * tenant. Each entry pairs the tool object with its source
+     * plugin id (used for logging / Plugin Manager UI). The agent
+     * loop further filters by each tool's `available()` gate before
+     * registering with pi-ai.
+     */
+    toolsForTenant(tenantId: string): Array<{
+        pluginId: string;
+        tool: AgentTool;
+    }>;
+    /**
+     * Collect every toolset provider every active plugin contributed
+     * for this tenant. Powers the global `/admin/mcp` view, which
+     * lists every connected MCP server (or other dynamic toolset)
+     * across plugins. Each entry includes the snapshot if the
+     * provider exposes one.
+     */
+    /**
+     * Look up the live ToolsetProvider behind a toolset summary, so
+     * routes can call refresh() on it. Returns null when the source
+     * has gone away (plugin disabled, user entry deleted) since the
+     * summary was generated.
+     */
+    toolsetProviderFor(summary: {
+        source: "plugin" | "user";
+        sourceId: string;
+        id: string;
+    }, tenantId: string): import("@tianshu/plugin-sdk").ToolsetProvider | null;
+    /**
+     * Re-probe every toolset whose snapshot looks stale (no
+     * endpoint, errored last attempt, or empty after a never-yet
+     * refresh). Used by both the chat handler (per-turn warmup so
+     * MCP tools that came online after plugin activation — e.g.
+     * Playwright once the sandbox boots — reach the agent surface
+     * without a manual /admin/mcp refresh) and the admin servers
+     * route (so the page render reflects fresh state).
+     *
+     * Refreshes run in parallel and the whole helper resolves no
+     * later than `deadlineMs`. We swallow per-toolset errors so a
+     * single broken upstream doesn't poison the warmup pass; the
+     * snapshot keeps `lastError` for the admin UI to surface.
+     *
+     * Returns the number of refresh() calls actually issued so
+     * callers can log / decide whether the call was worth it.
+     */
+    refreshStaleToolsets(tenantId: string, deadlineMs: number): Promise<number>;
+    toolsetsForTenant(tenantId: string): ToolsetSummary[];
+    /**
+     * Collect every skill contributed by every active plugin for
+     * this tenant. The host adds its own self-shipped skills on top
+     * of these (they live under `<repoRoot>/skills/`, not in any
+     * plugin). Caller filters by `when:` predicate against the
+     * current tool/capability set; see `filterSkillsForTenant`.
+     */
+    skillsForTenant(tenantId: string): LoadedSkill[];
+    /**
+     * Static system-prompt fragments contributed by every active
+     * plugin in this tenant. Each entry carries the plugin id +
+     * displayName so the host can wrap fragments in a section
+     * header before injection. Order: stable by plugin id, then
+     * by contribution id, so the resulting prompt is
+     * deterministic across reloads.
+     */
+    systemPromptFragmentsForTenant(tenantId: string): Array<{
+        pluginId: string;
+        pluginDisplayName: string;
+        fragmentId: string;
+        text: string;
+    }>;
+    /**
+     * Build a small read-only capability lookup handle scoped to one
+     * tenant. Same shape as `PluginContext.capabilities` but for
+     * host-side consumers (agent loop, tool factories) that don't
+     * have a `PluginContext`.
+     */
+    hostCapabilities(tenantId: string): HostCapabilityHandle;
+    private activate;
+}
+/**
+ * Read-only capability lookup handle for host code (agent loop,
+ * tool builders). Subset of `CapabilityHandle` from the SDK — we
+ * intentionally don't expose `on()` event subscription here so
+ * registry-mutation paths stay inside the registry itself.
+ */
+export interface HostCapabilityHandle {
+    get<T = unknown>(name: CapabilityName): T | undefined;
+    has(name: CapabilityName): boolean;
+}
+/** A handler resolver from a plain server-module map (used by tests +
+ *  builtin module wiring). */
+export declare function moduleMapResolver(map: Record<string, PluginServerModule>): ServerPluginModuleResolver;
+/** Build the API surface exposed via /api/p/<plugin-id>/<path>. */
+export declare function collectRoutesForTenant(registry: PluginRegistry, tenantId: string): Array<{
+    pluginId: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    handler: PluginRouteHandler;
+}>;
+//# sourceMappingURL=registry.d.ts.map

package/packages/server/dist/core/plugins/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/registry.ts"],"names":[],"mappings":"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"}