@zhin.js/plugin-runtime 1.1.0 → 1.1.1

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

@@ -17,6 +17,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 {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",