@tianshu-ai/tianshu 0.3.0

package/packages/server/dist/core/plugins/registry.js

@@ -0,0 +1,1003 @@
+// Server-side plugin registry: discovers + activates the plugins
+// enabled for a given tenant. Cached per tenant, invalidated on
+// tenant DB pool eviction or via PATCH /api/plugins/:id.
+//
+// State machine for a discovered plugin id:
+//
+//   discovered → enabled-in-config? → activate() resolves
+//        │           │                      │
+//        │           └─ no  → state: "disabled"
+//        │                                  │
+//        │                                  ├─ ok → state: "active"
+//        │                                  │
+//        │                                  └─ throws → state: "failed"
+//        │
+//        └─ manifest.json invalid → state: "failed" (collected by discovery)
+//
+// "client-bundle-missing" is reserved for v1 — we'll set it once
+// dynamic-import client loading lands. Today we always return
+// "active" / "disabled" / "failed".
+//
+// ADR-0004 additions on top of ADR-0003:
+//
+// - Topological activation order based on `requires[]` edges. A
+//   plugin's `activate()` only runs after every plugin providing its
+//   required capabilities is already active. Cycles fail the whole
+//   cycle (each member marked failed); plugins outside the cycle
+//   continue.
+// - Capability registry: a per-tenant map from capability name →
+//   provider entry + value. Sandbox runners are values of type
+//   `SandboxRunner` (registered under `sandbox.shell`); browser
+//   sidecars piggyback on the same runner via `runner.browser`
+//   (registered under `browser.cdp`).
+// - Exclusivity enforcement: capabilities flagged `exclusive: true`
+//   in `KNOWN_CAPABILITIES` reject a second provider; the second
+//   plugin in topo order is marked failed.
+// - Visibility (§17): builtin plugins NOT listed in tenant config
+//   still appear in `listForTenant()` as `state: "disabled"`. Tenant
+//   plugins on disk but not in config also appear as disabled.
+import path from "node:path";
+import { isCapabilityName, KNOWN_CAPABILITIES } from "@tianshu/plugin-sdk";
+import { discoverPlugins } from "./discovery.js";
+import { loadSkillsForPlugin, mirrorSkillsToTenantConfig, } from "./skills.js";
+import { loadPluginSecrets, mergePluginSecrets, } from "./secrets.js";
+import { seedAgentDirs } from "../agent-seeds.js";
+function summariseToolset(args) {
+    let snapshot = null;
+    try {
+        snapshot = args.provider.snapshot ? args.provider.snapshot() : null;
+    }
+    catch (err) {
+        console.warn(`[${args.logTag}] toolset "${args.id}" snapshot() threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let toolCount = snapshot?.tools.length ?? 0;
+    if (toolCount === 0) {
+        try {
+            toolCount = args.provider.listTools().length;
+        }
+        catch {
+            toolCount = 0;
+        }
+    }
+    return {
+        source: args.source,
+        sourceId: args.sourceId,
+        id: args.id,
+        displayName: args.displayName,
+        enabled: args.enabled,
+        providerName: args.provider.name,
+        snapshot,
+        toolCount,
+    };
+}
+export class PluginRegistry {
+    opts;
+    cache = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Idempotent: returns cached if already initialised for this tenant. */
+    async ensureForTenant(ctx) {
+        const cached = this.cache.get(ctx.tenantId);
+        if (cached)
+            return cached.entries;
+        const cfg = readPluginsConfig(ctx);
+        const discovery = discoverPlugins(ctx.tenantId, this.opts.discoveryDirs);
+        const entries = [];
+        // Failed manifests come through as failed entries with whatever id we
+        // could parse from the manifest (if any).
+        for (const f of discovery.failed) {
+            entries.push({
+                manifest: {
+                    id: f.pluginId ?? `(invalid:${f.dir})`,
+                    version: "0.0.0",
+                    displayName: f.pluginId ?? "(invalid manifest)",
+                },
+                source: f.source,
+                dir: f.dir,
+                state: "failed",
+                failedReason: f.issues.join("; "),
+                capabilityInfo: emptyCapabilityInfo(),
+            });
+        }
+        // Compute activation order over the subset enabled in tenant
+        // config. `requires` edges only matter between enabled plugins;
+        // a disabled plugin can't satisfy anything.
+        const enabledIds = new Set(discovery.plugins
+            .filter((p) => cfg[p.manifest.id]?.enabled === true)
+            .map((p) => p.manifest.id));
+        const ordered = topologicalOrder(discovery.plugins, enabledIds);
+        const enabledById = new Map(discovery.plugins.map((p) => [p.manifest.id, p]));
+        // Plugins that aren't enabled show up as disabled rows, with
+        // their capabilityInfo precomputed for the UI.
+        for (const p of discovery.plugins) {
+            if (enabledIds.has(p.manifest.id))
+                continue;
+            entries.push({
+                manifest: p.manifest,
+                source: p.source,
+                dir: p.dir,
+                state: "disabled",
+                capabilityInfo: {
+                    provided: [],
+                    requires: capabilityList(p.manifest.requires),
+                    missing: [],
+                },
+            });
+        }
+        // Cycle members are precomputed so we can fail them in one shot.
+        const cycleMembers = new Set(ordered.cycle);
+        const byCapability = new Map();
+        // Pre-seed host-provided capabilities so plugins requiring
+        // them can resolve. The synthetic provider id `__host__` makes
+        // it obvious in logs that no plugin owns these.
+        for (const [cap, factory] of Object.entries(this.opts.hostCapabilities ?? {})) {
+            if (!isCapabilityName(cap) || !factory)
+                continue;
+            const value = factory(ctx);
+            if (value === undefined || value === null)
+                continue;
+            byCapability.set(cap, {
+                capability: cap,
+                pluginId: "__host__",
+                exclusive: KNOWN_CAPABILITIES[cap].exclusive,
+                value,
+            });
+        }
+        // Activate plugins in topological order.
+        for (const id of ordered.order) {
+            const p = enabledById.get(id);
+            if (!p)
+                continue;
+            // 1) Cycle members fail with a specific reason.
+            if (cycleMembers.has(id)) {
+                entries.push({
+                    manifest: p.manifest,
+                    source: p.source,
+                    dir: p.dir,
+                    state: "failed",
+                    failedReason: `circular requires: ${ordered.cycle.join(" → ")}`,
+                    capabilityInfo: {
+                        provided: [],
+                        requires: capabilityList(p.manifest.requires),
+                        missing: [],
+                    },
+                });
+                continue;
+            }
+            // 2) Resolve requires: every required capability must already
+            //    be in byCapability.
+            const requires = capabilityList(p.manifest.requires);
+            const missing = requires.filter((c) => !byCapability.has(c));
+            if (missing.length > 0) {
+                entries.push({
+                    manifest: p.manifest,
+                    source: p.source,
+                    dir: p.dir,
+                    state: "failed",
+                    failedReason: `requires capability ${missing
+                        .map((c) => `"${c}"`)
+                        .join(", ")} — no provider enabled`,
+                    capabilityInfo: { provided: [], requires, missing },
+                });
+                continue;
+            }
+            // 3) Exclusivity check: if this plugin provides any exclusive
+            //    capability already taken, fail it.
+            const declared = capabilityList(p.manifest.provides);
+            const conflict = declared.find((c) => {
+                const spec = KNOWN_CAPABILITIES[c];
+                return spec.exclusive && byCapability.has(c);
+            });
+            if (conflict) {
+                const owner = byCapability.get(conflict).pluginId;
+                entries.push({
+                    manifest: p.manifest,
+                    source: p.source,
+                    dir: p.dir,
+                    state: "failed",
+                    failedReason: `capability "${conflict}" already provided by plugin ${owner}`,
+                    capabilityInfo: { provided: [], requires, missing: [] },
+                });
+                continue;
+            }
+            // 4) Activate the plugin.
+            const activated = await this.activate(ctx, p, byCapability);
+            entries.push(activated);
+            // 5) On success, register capabilities the plugin actually
+            //    backed (sandboxes contribution + runner.browser for
+            //    browser.cdp). If a declared capability has no backing
+            //    runner, mark the plugin failed.
+            if (activated.state === "active") {
+                const ok = registerProvidedCapabilities(activated, byCapability);
+                if (!ok.ok) {
+                    activated.state = "failed";
+                    activated.failedReason = ok.reason;
+                    delete activated.exports;
+                    activated.capabilityInfo = {
+                        provided: [],
+                        requires,
+                        missing: [],
+                    };
+                    // Roll back any partial registrations from this plugin.
+                    for (const cap of activated.capabilityInfo.provided) {
+                        const owner = byCapability.get(cap);
+                        if (owner?.pluginId === activated.manifest.id)
+                            byCapability.delete(cap);
+                    }
+                }
+            }
+        }
+        // Build the WS dispatch map. Duplicate `wsMessages.type` registrations
+        // mean the second plugin is rejected (state: failed).
+        const byWsType = new Map();
+        for (const e of entries) {
+            if (e.state !== "active" || !e.manifest.contributes?.wsMessages)
+                continue;
+            const wsHandlers = e.exports?.wsHandlers ?? {};
+            for (const ws of e.manifest.contributes.wsMessages) {
+                const existing = byWsType.get(ws.type);
+                if (existing) {
+                    e.state = "failed";
+                    e.failedReason = `ws message type "${ws.type}" already registered by plugin ${existing.entry.manifest.id}`;
+                    delete e.exports;
+                    continue;
+                }
+                const fn = wsHandlers[ws.handler];
+                if (!fn) {
+                    // Manifest claimed a handler that isn't exported. Mark failed
+                    // but keep other plugins alive.
+                    e.state = "failed";
+                    e.failedReason = `wsHandlers["${ws.handler}"] missing in plugin ${e.manifest.id}`;
+                    delete e.exports;
+                    continue;
+                }
+                byWsType.set(ws.type, { entry: e, handler: fn });
+            }
+        }
+        // Sort entries deterministically by id.
+        entries.sort((a, b) => a.manifest.id < b.manifest.id ? -1 : a.manifest.id > b.manifest.id ? 1 : 0);
+        // Mirror host + plugin skills into the tenant config tree.
+        // We collect plugin skills the same way `skillsForTenant` does
+        // and append host skills via the optional loader. The mirror
+        // helper rewrites each entry's filePath to the tenant-config
+        // path so the system prompt's <available_skills> block can
+        // advertise URIs the agent can actually read.
+        const tenantConfigDir = path.join(ctx.workspaceDir, "_tenant", "config");
+        const collected = [];
+        for (const e of entries) {
+            if (e.state !== "active" || !e.manifest.contributes?.skills)
+                continue;
+            const r = loadSkillsForPlugin({
+                pluginId: e.manifest.id,
+                pluginDir: e.dir,
+                contributions: e.manifest.contributes.skills,
+            });
+            collected.push(...r.skills);
+        }
+        if (this.opts.hostSkillsLoader) {
+            collected.push(...this.opts.hostSkillsLoader());
+        }
+        const mirroredSkills = mirrorSkillsToTenantConfig({
+            tenantConfigDir,
+            skills: collected,
+            log: {
+                info: (m, meta) => console.log(`[skill-mirror] ${m}`, meta ?? ""),
+                warn: (m, meta) => console.warn(`[skill-mirror] ${m}`, meta ?? ""),
+            },
+        });
+        this.cache.set(ctx.tenantId, {
+            entries,
+            byWsType,
+            byCapability,
+            mirroredSkills,
+        });
+        return entries;
+    }
+    /**
+     * 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) {
+        return this.cache.get(tenantId)?.mirroredSkills ?? [];
+    }
+    /**
+     * 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) {
+        const cached = this.cache.get(tenantId);
+        this.cache.delete(tenantId);
+        if (!cached)
+            return Promise.resolve();
+        return this.runDeactivations(cached.entries);
+    }
+    async runDeactivations(entries) {
+        // Sequential, reverse-of-entries order. v0 ordering is
+        // reverse id-sort (entries are sorted alphabetically); a
+        // plugin's deactivate() should not rely on another plugin's
+        // capabilities still being up. A future revision may promote
+        // this to true reverse-topological if a real consumer needs
+        // it.
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const e = entries[i];
+            if (e.state !== "active")
+                continue;
+            const fn = e.module?.deactivate;
+            if (typeof fn !== "function")
+                continue;
+            try {
+                await fn();
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.warn(`[plugin:${e.manifest.id}] deactivate() threw: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    /** For routes layer: look up the WS handler for a {tenant, type}. */
+    resolveWsHandler(tenantId, type) {
+        return this.cache.get(tenantId)?.byWsType.get(type);
+    }
+    /** For routes layer: list all plugins (active + disabled + failed). */
+    listForTenant(tenantId) {
+        return this.cache.get(tenantId)?.entries ?? [];
+    }
+    /** For agent / other host code: read the tenant capability registry. */
+    capabilityFor(tenantId, name) {
+        return this.cache.get(tenantId)?.byCapability.get(name)?.value;
+    }
+    /**
+     * 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) {
+        const out = [];
+        const cached = this.cache.get(tenantId);
+        if (!cached)
+            return out;
+        // (0) User-configured MCP toolsets (host-owned). These are
+        // surfaced under a synthetic plugin id of `core` so the agent
+        // logging + plugin manager UI can tell them apart from plugin
+        // contributions.
+        if (this.opts.mcpManager) {
+            for (const provider of this.opts.mcpManager.providersForTenant(tenantId)) {
+                try {
+                    for (const tool of provider.listTools()) {
+                        out.push({ pluginId: "core", tool });
+                    }
+                }
+                catch (err) {
+                    console.warn(`[mcp:user] toolset "${provider.name}" listTools() threw: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        for (const e of cached.entries) {
+            if (e.state !== "active")
+                continue;
+            // (1) Static tool contributions: one AgentTool per
+            // `manifest.contributes.tools[]` entry, looked up by `module`.
+            const toolModules = e.exports?.tools ?? {};
+            for (const t of e.manifest.contributes?.tools ?? []) {
+                const tool = toolModules[t.module];
+                if (!tool) {
+                    // Manifest claimed a tool but exports.tools didn't expose
+                    // the matching module. Mark plugin failed so the operator
+                    // sees it in /api/plugins; skip emission.
+                    e.state = "failed";
+                    e.failedReason = `tools["${t.module}"] missing in plugin ${e.manifest.id}`;
+                    delete e.exports;
+                    continue;
+                }
+                out.push({ pluginId: e.manifest.id, tool });
+            }
+            // (2) Dynamic toolset providers: each provider's listTools()
+            // is read every turn so MCP servers can come/go without a
+            // plugin reactivation. Errors inside listTools() are isolated
+            // (logged + skipped) so a single misbehaving toolset doesn't
+            // black out the agent's other tools.
+            if (e.state !== "active")
+                continue;
+            const providerModules = e.exports?.toolsetProviders ?? {};
+            for (const ts of e.manifest.contributes?.toolsets ?? []) {
+                const provider = providerModules[ts.module];
+                if (!provider) {
+                    e.state = "failed";
+                    e.failedReason = `toolsetProviders["${ts.module}"] missing in plugin ${e.manifest.id}`;
+                    delete e.exports;
+                    continue;
+                }
+                let dynamic = [];
+                try {
+                    dynamic = provider.listTools();
+                }
+                catch (err) {
+                    // Same behaviour as a per-call error inside an AgentTool:
+                    // log and keep going. Don't poison the rest of the run.
+                    console.warn(`[plugins:${e.manifest.id}] toolset "${ts.id}" listTools() threw: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                for (const tool of dynamic) {
+                    out.push({ pluginId: e.manifest.id, tool });
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * 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, tenantId) {
+        if (summary.source === "user") {
+            if (!this.opts.mcpManager)
+                return null;
+            const snaps = this.opts.mcpManager.snapshotsForTenant(tenantId);
+            return snaps.find((s) => s.id === summary.id)?.provider ?? null;
+        }
+        // source === "plugin"
+        const cached = this.cache.get(tenantId);
+        if (!cached)
+            return null;
+        const entry = cached.entries.find((e) => e.manifest.id === summary.sourceId);
+        if (!entry || entry.state !== "active")
+            return null;
+        const ts = entry.manifest.contributes?.toolsets?.find((t) => t.id === summary.id);
+        if (!ts)
+            return null;
+        return entry.exports?.toolsetProviders?.[ts.module] ?? 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.
+     */
+    async refreshStaleToolsets(tenantId, deadlineMs) {
+        const tsets = this.toolsetsForTenant(tenantId);
+        const stale = [];
+        for (const ts of tsets) {
+            const snap = ts.snapshot;
+            const isStale = !snap ||
+                snap.lastError !== undefined ||
+                (snap.tools.length === 0 &&
+                    (snap.endpoint === undefined || snap.lastRefreshAt === undefined));
+            if (!isStale)
+                continue;
+            const provider = this.toolsetProviderFor(ts, tenantId);
+            const refreshFn = provider
+                ?.refresh;
+            if (typeof refreshFn === "function") {
+                stale.push(refreshFn.call(provider).catch(() => undefined));
+            }
+        }
+        if (stale.length === 0)
+            return 0;
+        await Promise.race([
+            Promise.all(stale),
+            new Promise((resolve) => setTimeout(resolve, deadlineMs)),
+        ]);
+        return stale.length;
+    }
+    toolsetsForTenant(tenantId) {
+        const out = [];
+        // (1) Plugin-contributed toolsets. Source: their plugin id.
+        const cached = this.cache.get(tenantId);
+        if (cached) {
+            for (const e of cached.entries) {
+                if (e.state !== "active")
+                    continue;
+                const providers = e.exports?.toolsetProviders ?? {};
+                for (const ts of e.manifest.contributes?.toolsets ?? []) {
+                    const provider = providers[ts.module];
+                    if (!provider)
+                        continue;
+                    out.push(summariseToolset({
+                        source: "plugin",
+                        sourceId: e.manifest.id,
+                        id: ts.id,
+                        displayName: ts.displayName ?? ts.id,
+                        enabled: true,
+                        provider,
+                        logTag: `plugins:${e.manifest.id}`,
+                    }));
+                }
+            }
+        }
+        // (2) User-configured toolsets (host-owned). Source: `"user"`.
+        if (this.opts.mcpManager) {
+            for (const snap of this.opts.mcpManager.snapshotsForTenant(tenantId)) {
+                out.push({
+                    source: "user",
+                    sourceId: "core",
+                    id: snap.id,
+                    displayName: snap.displayName,
+                    enabled: snap.enabled,
+                    providerName: snap.provider?.name ?? snap.displayName,
+                    snapshot: snap.toolsetSnapshot,
+                    toolCount: snap.toolsetSnapshot?.tools.length ?? 0,
+                    // Round-trip the user's stored config so the admin UI can
+                    // show url / upstreamHost / prefix in edit dialogs.
+                    userEntry: {
+                        id: snap.entry.id,
+                        displayName: snap.entry.displayName,
+                        url: snap.entry.url,
+                        prefix: snap.entry.prefix,
+                        upstreamHost: snap.entry.upstreamHost,
+                        enabled: snap.entry.enabled !== false,
+                    },
+                });
+            }
+        }
+        return out;
+    }
+    /**
+     * 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) {
+        const out = [];
+        const cached = this.cache.get(tenantId);
+        if (!cached)
+            return out;
+        for (const e of cached.entries) {
+            if (e.state !== "active" || !e.manifest.contributes?.skills)
+                continue;
+            const result = loadSkillsForPlugin({
+                pluginId: e.manifest.id,
+                pluginDir: e.dir,
+                contributions: e.manifest.contributes.skills,
+            });
+            out.push(...result.skills);
+            for (const f of result.failures) {
+                // Surface skill load failures as plugin-failed so the Plugin
+                // Manager UI shows them; we don't fail the whole plugin
+                // because a missing skill file shouldn't kill its tools.
+                // eslint-disable-next-line no-console
+                console.warn(`[plugin:${f.source.pluginId}] skill ${f.source.contributionId} (${f.filePath}): ${f.reason}`);
+            }
+        }
+        return out;
+    }
+    /**
+     * 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) {
+        const out = [];
+        const cached = this.cache.get(tenantId);
+        if (!cached)
+            return out;
+        for (const e of cached.entries) {
+            if (e.state !== "active")
+                continue;
+            const fragments = e.manifest.contributes?.systemPromptFragments;
+            if (!fragments || fragments.length === 0)
+                continue;
+            for (const f of fragments) {
+                out.push({
+                    pluginId: e.manifest.id,
+                    pluginDisplayName: e.manifest.displayName ?? e.manifest.id,
+                    fragmentId: f.id,
+                    text: f.text,
+                });
+            }
+        }
+        return out.sort((a, b) => {
+            if (a.pluginId !== b.pluginId) {
+                return a.pluginId.localeCompare(b.pluginId);
+            }
+            return a.fragmentId.localeCompare(b.fragmentId);
+        });
+    }
+    /**
+     * 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) {
+        return {
+            get: (name) => this.capabilityFor(tenantId, name),
+            has: (name) => Boolean(this.cache.get(tenantId)?.byCapability.has(name)),
+        };
+    }
+    // ─── internals ─────────────────────────────────────────────────
+    async activate(ctx, p, byCapability) {
+        const requires = capabilityList(p.manifest.requires);
+        if (!p.manifest.server?.entry) {
+            // No server entry → the plugin is client-only. v0 doesn't load
+            // those (we'd need a registry for client-only plugins too); mark
+            // as active with no exports.
+            return {
+                manifest: p.manifest,
+                source: p.source,
+                dir: p.dir,
+                state: "active",
+                capabilityInfo: { provided: [], requires, missing: [] },
+            };
+        }
+        let mod = null;
+        try {
+            mod = await this.opts.resolver.resolve(p.manifest.server.entry);
+        }
+        catch (err) {
+            return failed(p, requires, `module resolve threw: ${describe(err)}`);
+        }
+        if (!mod) {
+            return failed(p, requires, `server.entry "${p.manifest.server.entry}" not registered`);
+        }
+        if (typeof mod.activate !== "function") {
+            return failed(p, requires, "server module does not export activate()");
+        }
+        const pluginCtx = makePluginContext({
+            pluginId: p.manifest.id,
+            ctx,
+            broadcast: this.opts.broadcast,
+            byCapability,
+        });
+        let exports_;
+        try {
+            exports_ = await mod.activate(pluginCtx);
+        }
+        catch (err) {
+            return failed(p, requires, `activate() threw: ${describe(err)}`);
+        }
+        // Drop manifest-declared agent seeds into the tenant's worker
+        // config tree. Idempotent (existing slots are preserved), so
+        // it's safe to run on every activate — including hot reloads
+        // that re-activate a plugin in the same process.
+        const seeds = p.manifest.contributes?.agentSeeds;
+        if (seeds && seeds.length > 0) {
+            try {
+                const r = seedAgentDirs({
+                    tenantId: ctx.tenantId,
+                    pluginId: p.manifest.id,
+                    pluginDir: p.dir,
+                    seeds,
+                });
+                if (r.inserted.length || r.invalid.length) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[plugin:${p.manifest.id}] [tenant:${ctx.tenantId}] agent-seeds inserted=[${r.inserted.join(", ")}] preserved=[${r.preserved.join(", ")}] invalid=[${r.invalid.join(", ")}]`);
+                }
+            }
+            catch (err) {
+                // Don't fail activation just because a seed couldn't be
+                // copied — the worker pool can still run any user-managed
+                // workers already on disk.
+                // eslint-disable-next-line no-console
+                console.warn(`[plugin:${p.manifest.id}] agent-seeds failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return {
+            manifest: p.manifest,
+            source: p.source,
+            dir: p.dir,
+            state: "active",
+            exports: exports_,
+            module: mod,
+            capabilityInfo: { provided: [], requires, missing: [] },
+        };
+    }
+}
+function failed(p, requires, reason) {
+    return {
+        manifest: p.manifest,
+        source: p.source,
+        dir: p.dir,
+        state: "failed",
+        failedReason: reason,
+        capabilityInfo: { provided: [], requires, missing: [] },
+    };
+}
+function describe(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function readPluginsConfig(ctx) {
+    const cfg = ctx.config.plugins;
+    if (!cfg || typeof cfg !== "object" || Array.isArray(cfg))
+        return {};
+    return cfg;
+}
+function readPluginConfig(ctx, pluginId) {
+    const all = readPluginsConfig(ctx);
+    const c = all[pluginId]?.config;
+    const raw = c && typeof c === "object" && !Array.isArray(c)
+        ? c
+        : {};
+    // Splice in any plugin secrets stored under <tenant>/secrets/
+    // BEFORE handing the object to the plugin. The plugin sees a
+    // single flat config blob; the split between config.json and
+    // secrets/ is a host concern.
+    const secrets = loadPluginSecrets(ctx.secretsDir, pluginId);
+    return mergePluginSecrets(raw, secrets);
+}
+function makePluginContext(args) {
+    const { pluginId, ctx, broadcast, byCapability } = args;
+    const log = bindLogger(pluginId, ctx.tenantId);
+    const capabilities = {
+        get: (name) => byCapability.get(name)?.value,
+        has: (name) => byCapability.has(name),
+        on: () => () => {
+            // v0: no-op. Lifecycle events are fired by registry.invalidate
+            // → ensureForTenant rebuilds, but we don't yet plumb listeners
+            // through. ADR-0004 §8 says v0 ships get/has only; on() is
+            // declared so plugins can write code that targets v1 already.
+        },
+    };
+    return {
+        pluginId,
+        tenantId: ctx.tenantId,
+        db: ctx.db,
+        tenantConfig: { defaultModel: ctx.config.defaultModel, branding: ctx.config.branding },
+        // Deprecated alias kept until the next major SDK bump so v0
+        // plugin code that read `ctx.config` still works.
+        config: { defaultModel: ctx.config.defaultModel, branding: ctx.config.branding },
+        log,
+        workspaceDir: ctx.workspaceDir,
+        userHomeDir: (userId) => ctx.userHomeDir(userId),
+        broadcast: (type, payload) => broadcast?.(ctx.tenantId, `${pluginId}:${type}`, payload),
+        capabilities,
+        pluginConfig: readPluginConfig(ctx, pluginId),
+    };
+}
+function bindLogger(pluginId, tenantId) {
+    const prefix = `[plugin:${pluginId}] [tenant:${tenantId}]`;
+    return {
+        info: (msg, meta) => console.log(`${prefix} ${msg}`, meta ?? ""),
+        warn: (msg, meta) => console.warn(`${prefix} ${msg}`, meta ?? ""),
+        error: (msg, meta) => console.error(`${prefix} ${msg}`, meta ?? ""),
+    };
+}
+/** A handler resolver from a plain server-module map (used by tests +
+ *  builtin module wiring). */
+export function moduleMapResolver(map) {
+    return {
+        resolve: (entry) => map[entry] ?? null,
+    };
+}
+/** Build the API surface exposed via /api/p/<plugin-id>/<path>. */
+export function collectRoutesForTenant(registry, tenantId) {
+    const out = [];
+    for (const e of registry.listForTenant(tenantId)) {
+        if (e.state !== "active" || !e.manifest.contributes?.apiRoutes)
+            continue;
+        const routeHandlers = e.exports?.routes ?? {};
+        for (const r of e.manifest.contributes.apiRoutes) {
+            const fn = routeHandlers[r.handler];
+            if (!fn) {
+                e.state = "failed";
+                e.failedReason = `routes["${r.handler}"] missing in plugin ${e.manifest.id}`;
+                delete e.exports;
+                continue;
+            }
+            out.push({
+                pluginId: e.manifest.id,
+                method: r.method,
+                path: r.path,
+                handler: fn,
+            });
+        }
+    }
+    return out;
+}
+// ─── helpers ─────────────────────────────────────────────────────
+function capabilityList(raw) {
+    if (!raw)
+        return [];
+    // Manifest validator already filtered to known names, but be
+    // defensive in case someone constructs a manifest in code (tests).
+    return raw.filter(isCapabilityName);
+}
+function emptyCapabilityInfo() {
+    return { provided: [], requires: [], missing: [] };
+}
+/**
+ * Kahn's algorithm over plugins in the enabled set. Edges are
+ * `requires(provider)` (provider satisfies the required capability),
+ * resolved by scanning every enabled plugin's `provides[]`. We don't
+ * care which specific provider satisfies a capability — any works.
+ */
+function topologicalOrder(plugins, enabledIds) {
+    // capability → ids of providers (within enabled set)
+    const providers = new Map();
+    for (const p of plugins) {
+        if (!enabledIds.has(p.manifest.id))
+            continue;
+        for (const cap of capabilityList(p.manifest.provides)) {
+            const arr = providers.get(cap) ?? [];
+            arr.push(p.manifest.id);
+            providers.set(cap, arr);
+        }
+    }
+    // For each enabled plugin, compute the set of plugin-ids it depends
+    // on (every provider of every required capability). Self-loops are
+    // dropped — a plugin can both provide and require the same capability
+    // (e.g. self-tests); we don't treat that as a cycle.
+    const deps = new Map();
+    for (const p of plugins) {
+        if (!enabledIds.has(p.manifest.id))
+            continue;
+        const set = new Set();
+        for (const cap of capabilityList(p.manifest.requires)) {
+            const provs = providers.get(cap) ?? [];
+            for (const provId of provs) {
+                if (provId !== p.manifest.id)
+                    set.add(provId);
+            }
+        }
+        deps.set(p.manifest.id, set);
+    }
+    const order = [];
+    const remaining = new Map(deps);
+    const ids = [...remaining.keys()].sort();
+    while (remaining.size > 0) {
+        // Pick all plugins with zero remaining deps; sort for determinism.
+        const ready = ids.filter((id) => remaining.has(id) && remaining.get(id).size === 0);
+        if (ready.length === 0)
+            break; // cycle
+        for (const id of ready) {
+            order.push(id);
+            remaining.delete(id);
+            for (const [other, set] of remaining) {
+                if (set.delete(id) && set.size === 0) {
+                    // Will be picked next iteration.
+                }
+                void other;
+            }
+        }
+    }
+    // Anything left is in a cycle.
+    const cycle = [...remaining.keys()].sort();
+    for (const id of cycle)
+        order.push(id);
+    return { order, cycle };
+}
+/**
+ * After a plugin's `activate()` returns successfully, map its
+ * `provides[]` declarations to the actual values it exposes
+ * (sandbox runners, optional browser sidecar) and register them.
+ *
+ * Returns `{ ok: true }` if every declared capability was backed,
+ * or `{ ok: false, reason }` if a backing was missing.
+ *
+ * Side effects: mutates `entry.capabilityInfo.provided` and the
+ * passed-in `byCapability` map.
+ */
+function registerProvidedCapabilities(entry, byCapability) {
+    const declared = capabilityList(entry.manifest.provides);
+    if (declared.length === 0)
+        return { ok: true };
+    const sandboxes = entry.manifest.contributes?.sandboxes ?? [];
+    const sandboxModules = entry.exports?.sandboxes ?? {};
+    // Lazily start the first matching sandbox runner per kind.
+    // We only need one runner per provided sandbox.<kind> capability.
+    // The sandbox module's start() returned the runner object eagerly
+    // inside activate() — we expect plugins to surface ready runners
+    // via exports.sandboxes after their start logic runs in activate.
+    // Convention: exports.sandboxes is keyed by manifest.module string.
+    for (const cap of declared) {
+        if (cap === "sandbox.taskPool") {
+            // Per-task sandbox manager: backed by
+            // exports.taskSandboxPool, not by a sandboxes[] contribution
+            // entry. (A taskPool is a *manager* of per-task runners, not
+            // a single SandboxRunner, so it doesn't fit the
+            // sandboxes[].kind == cap.slice("sandbox.") convention.)
+            const pool = entry.exports?.taskSandboxPool;
+            if (!pool || typeof pool !== "object") {
+                return {
+                    ok: false,
+                    reason: `provides["sandbox.taskPool"] declared but exports.taskSandboxPool missing in plugin ${entry.manifest.id}`,
+                };
+            }
+            byCapability.set(cap, {
+                capability: cap,
+                pluginId: entry.manifest.id,
+                exclusive: KNOWN_CAPABILITIES[cap].exclusive,
+                value: pool,
+            });
+            entry.capabilityInfo.provided.push(cap);
+            continue;
+        }
+        if (cap.startsWith("sandbox.")) {
+            const kind = cap.slice("sandbox.".length);
+            const matching = sandboxes.find((s) => s.kind === kind);
+            if (!matching) {
+                return {
+                    ok: false,
+                    reason: `provides[\"${cap}\"] declared without a backing sandboxes[] entry of kind=${kind}`,
+                };
+            }
+            const runner = sandboxModules[matching.module];
+            if (!runner || typeof runner !== "object") {
+                return {
+                    ok: false,
+                    reason: `sandboxes["${matching.module}"] missing or not an object in plugin ${entry.manifest.id}`,
+                };
+            }
+            byCapability.set(cap, {
+                capability: cap,
+                pluginId: entry.manifest.id,
+                exclusive: KNOWN_CAPABILITIES[cap].exclusive,
+                value: runner,
+            });
+            entry.capabilityInfo.provided.push(cap);
+            continue;
+        }
+        if (cap === "browser.cdp") {
+            // browser.cdp piggybacks on a sandbox runner with a populated
+            // `.browser` field. Find the first runner that exposes one.
+            let sidecar;
+            for (const s of sandboxes) {
+                const runner = sandboxModules[s.module];
+                if (runner && runner.browser) {
+                    sidecar = runner.browser;
+                    break;
+                }
+            }
+            if (!sidecar) {
+                return {
+                    ok: false,
+                    reason: `provides[\"browser.cdp\"] declared but no sandbox runner exposes a .browser sidecar`,
+                };
+            }
+            byCapability.set(cap, {
+                capability: cap,
+                pluginId: entry.manifest.id,
+                exclusive: KNOWN_CAPABILITIES[cap].exclusive,
+                value: sidecar,
+            });
+            entry.capabilityInfo.provided.push(cap);
+            continue;
+        }
+        return {
+            ok: false,
+            reason: `unknown capability "${cap}" in provides[] (KNOWN_CAPABILITIES is the single source of truth)`,
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=registry.js.map