@zhin.js/plugin-runtime 1.1.0 → 1.1.2

package/README.md

@@ -12,6 +12,11 @@ import {
 } from '@zhin.js/plugin-runtime';
 ```
 
+`PluginSetupContext.addFeature(feature, localName, definition)` 是约定目录之外的内存
+Capability 写入口。它仍由上层 Runtime 交给对应 Feature provider 校验和投影；Feature
+通过 `authoring.setupMethod` 和 module augmentation 提供强类型 `addCommand`、
+`addComponent`、`addTool` 等别名。底座只保存通用注册记录，不理解 IM。
+
 ## 生命周期
 
 ```text

package/lib/agent-tools-host.d.ts

@@ -1,6 +1,10 @@
 /**
  * Plugin-contributed Agent tool registered against the Agent Host.
  * Captured at setup() time — execute closures must never call plugin locators.
+ *
+ * Access vocabulary (platforms / scopes / permissions / hidden) mirrors the
+ * `@zhin.js/tool` ToolIndex descriptor and is enforced per message by the
+ * Agent runtime via Core `canAccessTool` — one predicate for both paths.
  */
 export interface AgentToolRegistration {
     /** Runtime tool name exposed to the model (e.g. `lottery_sync`). */
@@ -10,7 +14,12 @@ export interface AgentToolRegistration {
     readonly inputSchema?: unknown;
     readonly keywords?: readonly string[];
     readonly tags?: readonly string[];
+    /** Limit to these adapter platforms (e.g. `['icqq']`); empty = all. */
+    readonly platforms?: readonly string[];
+    /** Limit to these channel scopes; empty = all. */
+    readonly scopes?: readonly ('private' | 'group' | 'channel')[];
     readonly permissions?: readonly string[];
+    /** Registered but never offered to the model (callable by name only). */
     readonly hidden?: boolean;
     /** Per-tool approval policy; stacks with ExecPolicy. */
     readonly approval?: 'never' | 'always';

package/lib/capability.d.ts

@@ -6,5 +6,16 @@ export interface CapabilitySlot<T = unknown> {
     readonly localName: string;
     readonly source: string;
     readonly definition: T;
+    /** Setup-owned slots follow their Plugin Scope instead of file-slot HMR. */
+    readonly origin?: 'setup';
+}
+/** A capability declared imperatively while its owning Plugin is assembled. */
+export interface SetupCapabilityRegistration<T = unknown> {
+    readonly id: CapabilityId;
+    readonly owner: PluginId;
+    readonly feature: FeatureId;
+    readonly localName: string;
+    readonly source: string;
+    readonly definition: T;
 }
 export declare function createCapabilitySlot<T>(input: Omit<CapabilitySlot<T>, 'id'>): Readonly<CapabilitySlot<T>>;

package/lib/database-host.d.ts

@@ -1,3 +1,4 @@
+import { type PluginId } from './identity.js';
 export interface DatabaseHostSelection {
     where(query: Record<string, unknown>): DatabaseHostSelection;
     orderBy(field: string, direction?: 'ASC' | 'DESC'): DatabaseHostSelection;
@@ -17,6 +18,11 @@ export interface DatabaseHostModel {
     update(patch: Record<string, unknown>): {
         where(query: Record<string, unknown>): Promise<unknown>;
     };
+    /**
+     * DB 侧计数（聚合下推，避免为计数整表加载）。
+     * 可选：轻量 test/memory host 可不实现，调用方降级为 select 计数。
+     */
+    count?(where?: Record<string, unknown>): Promise<number>;
 }
 export type DatabaseHostType = 'related' | 'document' | 'keyvalue';
 export interface DatabaseHostTable {
@@ -78,4 +84,43 @@ export interface DatabaseHost {
     start(): Promise<void>;
     stop(): Promise<void>;
 }
-export declare const databaseHostToken: import("./token.js").Token<DatabaseHost>;
+/**
+ * Persistence surface visible to a plugin. Names are logical to the owner;
+ * the Runtime maps them to private physical table names before they reach the
+ * process-wide DatabaseHost.
+ */
+export interface PluginDatabaseHost {
+    readonly owner: PluginId;
+    readonly dialect: string;
+    readonly started: boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+    models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+}
+/**
+ * Maps a plugin's logical resource name to its process-wide physical name.
+ * Root keeps its historical bare names so existing projects do not need a
+ * database migration merely to adopt scoped child plugins.
+ */
+export declare function qualifyPluginResourceName(owner: PluginId, name: string): string;
+/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
+export declare function unqualifyPluginResourceName(owner: PluginId, name: string): string | undefined;
+/** Creates a tenant facade without exposing Console administration or raw DB access. */
+export declare function createPluginDatabaseHost(owner: PluginId, host: DatabaseHost): PluginDatabaseHost;
+/**
+ * Recovers a process host from the standard root token or a scoped facade.
+ * This keeps custom RootRuntime installers written against the pre-facade
+ * token working while child scopes begin receiving tenant boundaries.
+ */
+export declare function unwrapPluginDatabaseHost(host: DatabaseHost | PluginDatabaseHost): DatabaseHost | undefined;
+/**
+ * Plugin-facing scoped persistence token. Runtime replaces this binding for
+ * every Plugin Scope; plugin code must never receive the process-wide host.
+ * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
+ * facade cannot accidentally enumerate a descendant's tables.
+ */
+export declare const databaseHostToken: import("./token.js").Token<PluginDatabaseHost>;
+/** Root-only process host for CLI composition and Console administration. */
+export declare const databaseRootHostToken: import("./token.js").Token<DatabaseHost>;

package/lib/database-host.js

@@ -1,2 +1,71 @@
+import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
 import { createToken } from './token.js';
-export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime database host');
+const resourcePrefix = '__zhin_plugin__';
+const resourceSeparator = '__';
+const roots = new WeakMap();
+/**
+ * Maps a plugin's logical resource name to its process-wide physical name.
+ * Root keeps its historical bare names so existing projects do not need a
+ * database migration merely to adopt scoped child plugins.
+ */
+export function qualifyPluginResourceName(owner, name) {
+    assertLogicalResourceName(name);
+    if (owner === rootPluginId())
+        return name;
+    return `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}${name}`;
+}
+/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
+export function unqualifyPluginResourceName(owner, name) {
+    if (owner === rootPluginId())
+        return name.startsWith(resourcePrefix) ? undefined : name;
+    const prefix = `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}`;
+    return name.startsWith(prefix) ? name.slice(prefix.length) : undefined;
+}
+/** Creates a tenant facade without exposing Console administration or raw DB access. */
+export function createPluginDatabaseHost(owner, host) {
+    const facade = Object.freeze({
+        owner,
+        get dialect() { return host.dialect; },
+        get started() { return host.started; },
+        define(name, definition) {
+            host.define(qualifyPluginResourceName(owner, name), definition);
+        },
+        tables() {
+            return Object.freeze(host.tables().flatMap((name) => {
+                const logical = unqualifyPluginResourceName(owner, name);
+                return logical === undefined ? [] : [logical];
+            }));
+        },
+        models: Object.freeze({
+            get(name) {
+                return host.models.get(qualifyPluginResourceName(owner, name));
+            },
+        }),
+    });
+    roots.set(facade, host);
+    return facade;
+}
+/**
+ * Recovers a process host from the standard root token or a scoped facade.
+ * This keeps custom RootRuntime installers written against the pre-facade
+ * token working while child scopes begin receiving tenant boundaries.
+ */
+export function unwrapPluginDatabaseHost(host) {
+    if ('getRawDatabase' in host)
+        return host;
+    return roots.get(host);
+}
+function assertLogicalResourceName(name) {
+    if (!name || name.startsWith(resourcePrefix)) {
+        throw new TypeError(`Invalid plugin resource name: ${name}`);
+    }
+}
+/**
+ * Plugin-facing scoped persistence token. Runtime replaces this binding for
+ * every Plugin Scope; plugin code must never receive the process-wide host.
+ * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
+ * facade cannot accidentally enumerate a descendant's tables.
+ */
+export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime scoped database host');
+/** Root-only process host for CLI composition and Console administration. */
+export const databaseRootHostToken = createToken('zhin.database.root-host', 'Plugin Runtime root database host');

package/lib/generation-store.d.ts

@@ -0,0 +1,32 @@
+import { DisposeStack, type Dispose } from './dispose.js';
+/**
+ * Minimal structural view of a plugin setup context: anything owning a
+ * generation-scoped lifecycle (e.g. PluginSetupContext) can provide values.
+ */
+export interface GenerationStoreContext {
+    readonly lifecycle: DisposeStack;
+}
+export interface GenerationStore<T> {
+    /**
+     * Publish `value` as the current generation's value. The registration is
+     * removed automatically when `context.lifecycle` disposes (generation end);
+     * the returned Dispose unregisters manually and is idempotent.
+     */
+    provide(context: GenerationStoreContext, value: T): Dispose;
+    /** Latest live value; throws a store-named error when none was provided. */
+    use(): T;
+    /** Latest live value, or `undefined` when none was provided. */
+    tryUse(): T | undefined;
+    /** Drop every registration across all generations. Mainly for tests. */
+    clear(): void;
+}
+/**
+ * Generation-scoped replacement for module-level `let _x` singletons.
+ *
+ * Provided values form a stack: the newest live registration wins, and when a
+ * generation ends its registration is removed via `context.lifecycle`,
+ * re-exposing the previous generation's value. This structurally prevents
+ * stale references to an already disposed generation (the repeater singleton
+ * / rss `_db` class of bugs).
+ */
+export declare function createGenerationStore<T>(name: string): GenerationStore<T>;

package/lib/generation-store.js

@@ -0,0 +1,38 @@
+/**
+ * Generation-scoped replacement for module-level `let _x` singletons.
+ *
+ * Provided values form a stack: the newest live registration wins, and when a
+ * generation ends its registration is removed via `context.lifecycle`,
+ * re-exposing the previous generation's value. This structurally prevents
+ * stale references to an already disposed generation (the repeater singleton
+ * / rss `_db` class of bugs).
+ */
+export function createGenerationStore(name) {
+    const registrations = [];
+    const unregister = (registration) => {
+        const index = registrations.lastIndexOf(registration);
+        if (index >= 0)
+            registrations.splice(index, 1);
+    };
+    return {
+        provide(context, value) {
+            const registration = Object.freeze({ value });
+            registrations.push(registration);
+            context.lifecycle.add(() => unregister(registration));
+            return () => unregister(registration);
+        },
+        use() {
+            const latest = registrations[registrations.length - 1];
+            if (!latest) {
+                throw new Error(`Generation store "${name}" has no live value — call provide(context, value) during plugin setup`);
+            }
+            return latest.value;
+        },
+        tryUse() {
+            return registrations[registrations.length - 1]?.value;
+        },
+        clear() {
+            registrations.length = 0;
+        },
+    };
+}

package/lib/identity.d.ts

@@ -18,5 +18,13 @@ export declare function tokenId(value: string): TokenId;
 export declare function featureId(value: string): FeatureId;
 export declare function rootPluginId(): PluginId;
 export declare function childPluginId(parent: PluginId, instanceKey: string): PluginId;
+/**
+ * Database-safe owner encoding used by process-wide plugin resources.
+ *
+ * Each path segment is length-prefixed and the final underscore is followed
+ * by a resource separator. A parent owner therefore cannot match a child
+ * owner merely because their PluginId has a common path prefix.
+ */
+export declare function pluginOwnerResourceKey(owner: PluginId): string;
 export declare function capabilityId(owner: PluginId, feature: FeatureId, localName: string): CapabilityId;
 export {};

package/lib/identity.js

@@ -24,6 +24,19 @@ export function childPluginId(parent, instanceKey) {
     }
     return `${parent}/${instanceKey}`;
 }
+/**
+ * Database-safe owner encoding used by process-wide plugin resources.
+ *
+ * Each path segment is length-prefixed and the final underscore is followed
+ * by a resource separator. A parent owner therefore cannot match a child
+ * owner merely because their PluginId has a common path prefix.
+ */
+export function pluginOwnerResourceKey(owner) {
+    return `${String(owner)
+        .split('/')
+        .map((segment) => `${segment.length}_${segment}`)
+        .join('_')}_`;
+}
 export function capabilityId(owner, feature, localName) {
     if (!capabilityLocalNamePattern.test(localName)) {
         throw new TypeError(`Invalid capability local name: ${localName}`);

package/lib/index.d.ts

@@ -1,16 +1,25 @@
+/** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export * from './generation-store.js';
 export * from './handoff.js';
+/** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';
+/** @internal Runtime 内部：SnapshotStore / RuntimeSnapshot。 */
 export * from './snapshot.js';
 export * from './token.js';
+/** @public Host token：`scheduleHostToken`（承诺 semver）。 */
 export * from './schedule-host.js';
+/** @public Host token：`databaseHostToken`（承诺 semver）。 */
 export * from './database-host.js';
+/** @public Host token：`agentToolsHostToken`（experimental）。 */
 export * from './agent-tools-host.js';
 export * from './html-renderer.js';
+/** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
 export * from './inbox.js';
 export * from './system-log.js';

package/lib/index.js

@@ -1,16 +1,25 @@
+/** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export * from './generation-store.js';
 export * from './handoff.js';
+/** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';
+/** @internal Runtime 内部：SnapshotStore / RuntimeSnapshot。 */
 export * from './snapshot.js';
 export * from './token.js';
+/** @public Host token：`scheduleHostToken`（承诺 semver）。 */
 export * from './schedule-host.js';
+/** @public Host token：`databaseHostToken`（承诺 semver）。 */
 export * from './database-host.js';
+/** @public Host token：`agentToolsHostToken`（experimental）。 */
 export * from './agent-tools-host.js';
 export * from './html-renderer.js';
+/** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
 export * from './inbox.js';
 export * from './system-log.js';

package/lib/plugin.d.ts

@@ -1,6 +1,6 @@
 import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
-import type { PluginId } from './identity.js';
+import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
 export interface PluginMetadata {
     readonly displayName?: string;
@@ -23,6 +23,11 @@ export interface PluginSetupContext<TConfig = unknown> {
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
     readonly handoff: GenerationHandoffRegistry;
+    /**
+     * Registers an in-memory definition through the same validation and
+     * projection transaction used by convention-discovered capabilities.
+     */
+    addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
 export interface PluginDefinition<TConfig = unknown> {
     readonly name: string;

package/lib/schedule-host.d.ts

@@ -1,9 +1,12 @@
+import { type PluginId } from './identity.js';
 /**
  * Thin Host Resource for Plugin Runtime cron jobs.
  * Implementations typically wrap `@zhin.js/schedule` CalendarScheduler (solar cron).
  */
 export interface ScheduleJobRegistration {
     readonly id: string;
+    /** Runtime-assigned owner for diagnostics and Console inventory. */
+    readonly owner?: PluginId;
     /** 6-field solar cron: `秒 分 时 日 月 周` */
     readonly cron: string;
     readonly description?: string;
@@ -16,6 +19,25 @@ export interface ScheduleHost {
         readonly id: string;
         readonly cron: string;
         readonly description?: string;
+        readonly owner?: PluginId;
     }[];
 }
-export declare const scheduleHostToken: import("./token.js").Token<ScheduleHost>;
+/** Scoped scheduling surface exposed to a Plugin setup function. */
+export interface PluginScheduleHost {
+    readonly owner: PluginId;
+    register(job: ScheduleJobRegistration): () => void;
+    list(): readonly {
+        readonly id: string;
+        readonly cron: string;
+        readonly description?: string;
+    }[];
+}
+export declare function qualifyPluginScheduleId(owner: PluginId, id: string): string;
+export declare function unqualifyPluginScheduleId(owner: PluginId, id: string): string | undefined;
+export declare function createPluginScheduleHost(owner: PluginId, host: ScheduleHost): PluginScheduleHost;
+/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
+export declare function unwrapPluginScheduleHost(host: ScheduleHost | PluginScheduleHost): ScheduleHost;
+/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+export declare const scheduleHostToken: import("./token.js").Token<PluginScheduleHost>;
+/** Root-only process scheduler for CLI composition and Console administration. */
+export declare const scheduleRootHostToken: import("./token.js").Token<ScheduleHost>;

package/lib/schedule-host.js

@@ -1,2 +1,52 @@
+import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
 import { createToken } from './token.js';
-export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime solar cron host');
+const jobPrefix = '__zhin_plugin__';
+const jobSeparator = '__';
+const roots = new WeakMap();
+export function qualifyPluginScheduleId(owner, id) {
+    assertLogicalJobId(id);
+    if (owner === rootPluginId())
+        return id;
+    return `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}${id}`;
+}
+export function unqualifyPluginScheduleId(owner, id) {
+    if (owner === rootPluginId())
+        return id.startsWith(jobPrefix) ? undefined : id;
+    const prefix = `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}`;
+    return id.startsWith(prefix) ? id.slice(prefix.length) : undefined;
+}
+export function createPluginScheduleHost(owner, host) {
+    const facade = Object.freeze({
+        owner,
+        register(job) {
+            return host.register({ ...job, id: qualifyPluginScheduleId(owner, job.id), owner });
+        },
+        list() {
+            return Object.freeze(host.list().flatMap((job) => {
+                const id = unqualifyPluginScheduleId(owner, job.id);
+                if (id === undefined)
+                    return [];
+                return [Object.freeze({
+                        id,
+                        cron: job.cron,
+                        ...(job.description === undefined ? {} : { description: job.description }),
+                    })];
+            }));
+        },
+    });
+    roots.set(facade, host);
+    return facade;
+}
+/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
+export function unwrapPluginScheduleHost(host) {
+    return roots.get(host) ?? host;
+}
+function assertLogicalJobId(id) {
+    if (!id || id.startsWith(jobPrefix)) {
+        throw new TypeError(`Invalid plugin schedule id: ${id}`);
+    }
+}
+/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime scoped solar cron host');
+/** Root-only process scheduler for CLI composition and Console administration. */
+export const scheduleRootHostToken = createToken('zhin.schedule.root-host', 'Plugin Runtime root solar cron host');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",
@@ -16,7 +16,7 @@
     "lib"
   ],
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3"
   },
   "engines": {