@zhin.js/plugin-runtime 1.1.3 → 1.1.6

package/lib/admission.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
+ * External callbacks may enter while the owning Resource is present in the
+ * committed snapshot; candidate and retired Resources fail closed.
+ */
+export declare class GenerationAdmissionGate {
+    constructor();
+    get active(): boolean;
+    acquire(): (() => void) | undefined;
+    /**
+     * Observe retirement of the generation that owns this gate. The callback is
+     * synchronous and must not fail; it is intended for closing process-owned
+     * ingress transports such as WebSocket connections.
+     */
+    onDeactivate(listener: () => void): () => void;
+    enter<T>(operation: () => T): T | undefined;
+}
+export declare function createGenerationAdmissionGate(): GenerationAdmissionGate;
+/** Resource hook used by CapabilityContext to bind an ingress dependency. */
+export declare const generationAdmissionBinder: unique symbol;
+export interface GenerationAdmissionBindable<T> {
+    [generationAdmissionBinder](gate: GenerationAdmissionGate): T;
+}
+/** Snapshot value hook used to declare lifecycle-owned ingress gates. */
+export declare const generationAdmissionSource: unique symbol;
+export interface GenerationAdmissionSource {
+    readonly [generationAdmissionSource]: readonly GenerationAdmissionGate[];
+}
+export declare function bindGenerationAdmission<T>(value: T, gate: GenerationAdmissionGate): T;
+export declare function collectGenerationAdmissions(values: Iterable<unknown>): ReadonlySet<GenerationAdmissionGate>;
+export declare function replaceGenerationAdmissions(previous: ReadonlySet<GenerationAdmissionGate>, next: ReadonlySet<GenerationAdmissionGate>, owner: object, acquireNext?: () => () => void): void;

package/lib/admission.js

@@ -0,0 +1,133 @@
+/**
+ * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
+ * External callbacks may enter while the owning Resource is present in the
+ * committed snapshot; candidate and retired Resources fail closed.
+ */
+export class GenerationAdmissionGate {
+    constructor() {
+        admissionState.set(this, { active: false });
+        admissionDeactivationListeners.set(this, new Set());
+    }
+    get active() {
+        return admissionState.get(this)?.active === true;
+    }
+    acquire() {
+        const state = admissionState.get(this);
+        return state?.active ? state.acquire?.() : undefined;
+    }
+    /**
+     * Observe retirement of the generation that owns this gate. The callback is
+     * synchronous and must not fail; it is intended for closing process-owned
+     * ingress transports such as WebSocket connections.
+     */
+    onDeactivate(listener) {
+        const listeners = admissionDeactivationListeners.get(this);
+        if (!listeners)
+            throw new Error('Unknown generation admission gate');
+        if (!this.active) {
+            listener();
+            return () => undefined;
+        }
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    }
+    enter(operation) {
+        const release = this.acquire();
+        if (!release)
+            return undefined;
+        try {
+            const result = operation();
+            if (isPromiseLike(result))
+                return Promise.resolve(result).finally(release);
+            release();
+            return result;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+}
+const admissionState = new WeakMap();
+const admissionOwners = new WeakMap();
+const admissionDeactivationListeners = new WeakMap();
+export function createGenerationAdmissionGate() {
+    return new GenerationAdmissionGate();
+}
+/** Resource hook used by CapabilityContext to bind an ingress dependency. */
+export const generationAdmissionBinder = Symbol('GenerationAdmissionBinder');
+/** Snapshot value hook used to declare lifecycle-owned ingress gates. */
+export const generationAdmissionSource = Symbol('GenerationAdmissionSource');
+export function bindGenerationAdmission(value, gate) {
+    if (!isObject(value))
+        return value;
+    const binder = value[generationAdmissionBinder];
+    return typeof binder === 'function' ? binder.call(value, gate) : value;
+}
+export function collectGenerationAdmissions(values) {
+    const result = new Set();
+    for (const value of values) {
+        if (value instanceof GenerationAdmissionGate) {
+            result.add(value);
+            continue;
+        }
+        if (!isObject(value))
+            continue;
+        const gates = value[generationAdmissionSource];
+        if (!Array.isArray(gates))
+            continue;
+        for (const gate of gates) {
+            if (!(gate instanceof GenerationAdmissionGate)) {
+                throw new TypeError('Generation admission source returned an invalid gate');
+            }
+            result.add(gate);
+        }
+    }
+    return result;
+}
+export function replaceGenerationAdmissions(previous, next, owner, acquireNext) {
+    // Validate the complete switch before changing ownership or visibility. A
+    // rejected cross-Root gate must leave both generations exactly untouched.
+    for (const gate of next)
+        assertClaimableAdmission(gate, owner);
+    for (const gate of previous) {
+        assertAdmissionOwner(gate, owner);
+    }
+    for (const gate of next)
+        admissionOwners.set(gate, owner);
+    for (const gate of previous) {
+        if (next.has(gate))
+            continue;
+        admissionState.set(gate, { active: false });
+        for (const listener of admissionDeactivationListeners.get(gate) ?? []) {
+            try {
+                listener();
+            }
+            catch {
+                // Admission publication is an infallible pointer switch. Transport
+                // cleanup reports through its own lifecycle and cannot veto commit.
+            }
+        }
+    }
+    for (const gate of next) {
+        admissionState.set(gate, { active: true, acquire: acquireNext });
+    }
+}
+function assertClaimableAdmission(gate, owner) {
+    const current = admissionOwners.get(gate);
+    if (current && current !== owner) {
+        throw new Error('Generation admission gate belongs to another SnapshotStore');
+    }
+}
+function assertAdmissionOwner(gate, owner) {
+    if (admissionOwners.get(gate) !== owner) {
+        throw new Error('SnapshotStore does not own generation admission gate');
+    }
+}
+function isObject(value) {
+    return (typeof value === 'object' && value !== null) || typeof value === 'function';
+}
+function isPromiseLike(value) {
+    return isObject(value)
+        && typeof value.then === 'function';
+}

package/lib/component-host.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Outbound template context — conversation + incoming message metadata
+ * available as top-level variables inside `${expr}` template expressions.
+ *
+ * Templates can reference e.g. `${sender.name}`, `${adapter}`,
+ * `${content}`, `${messageId}`, `${timestamp}`.
+ */
+export interface TemplateContext {
+    /** Adapter feature name (e.g. 'qq', 'sandbox'). */
+    readonly adapter: string;
+    /** Endpoint instance id. */
+    readonly endpoint: string;
+    /** Conversation kind: 'private' | 'group' | 'channel'. */
+    readonly kind: string;
+    /** Native conversation id. */
+    readonly conversationId: string;
+    /** Sender info (absent for scheduled / cross-channel sends). */
+    readonly sender?: Readonly<{
+        readonly id: string;
+        readonly name?: string;
+        readonly roles?: readonly string[];
+    }>;
+    /** Incoming message text content. */
+    readonly content?: string;
+    /** Structured message segments (images, mentions, quotes, etc.). */
+    readonly segments?: readonly Readonly<{
+        type: string;
+        data?: Record<string, unknown>;
+    }>[];
+    /** Platform native message id. */
+    readonly messageId?: string;
+    /** Message arrival timestamp in ms. */
+    readonly timestamp?: number;
+    /** Endpoint instance name (e.g. ICQQ uin, sandbox bot name). */
+    readonly endpointId?: string;
+    /** Whether the bot was @mentioned. */
+    readonly mentioned?: boolean;
+}
+/**
+ * Thin Host Resource for Plugin Runtime outbound template compilation.
+ * Evaluates `${expr}` template expressions in a sandboxed VM context
+ * (same security boundary as the legacy ComponentFeature pipeline).
+ *
+ * Implemented by the CLI Host; absent when not wired — consumers must
+ * pass text through unchanged.
+ */
+export interface ComponentHost {
+    compileTemplate(text: string, context: TemplateContext): string;
+}
+export declare const componentHostToken: import("./token.js").Token<ComponentHost>;

package/lib/component-host.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const componentHostToken = createToken('zhin.component.host', 'Plugin Runtime template compilation host');

package/lib/handoff.d.ts

@@ -1,30 +1,24 @@
-import type { RuntimeSnapshot } from './snapshot.js';
 export interface GenerationHandoff {
-    quiescePrevious(previous: RuntimeSnapshot): void | Promise<void>;
-    activateNext(): void | Promise<void>;
+    activateNext(signal: AbortSignal): void | Promise<void>;
     deactivateNext(): void | Promise<void>;
-    resumePrevious(): void | Promise<void>;
-    openNext(): void;
 }
 export interface GenerationHandoffParticipant {
-    quiescePrevious?(previous: RuntimeSnapshot): void | Promise<void>;
-    activateNext?(): void | Promise<void>;
+    activateNext?(signal: AbortSignal): void | Promise<void>;
     deactivateNext?(): void | Promise<void>;
-    resumePrevious?(): void | Promise<void>;
-    openNext?(): void;
 }
 export interface GenerationHandoffRegistry {
     add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
 }
+/** A transaction failed and its internal compensation also failed. */
+export declare class GenerationCompensationError extends AggregateError {
+    constructor(errors: readonly unknown[], message: string, options?: ErrorOptions);
+}
 /** Composes owner-ordered Resource handoffs and compensates partial progress. */
 export declare class GenerationHandoffStack implements GenerationHandoffRegistry, GenerationHandoff {
     #private;
     get size(): number;
     add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
     seal(): GenerationHandoff | undefined;
-    quiescePrevious(previous: RuntimeSnapshot): Promise<void>;
-    activateNext(): Promise<void>;
+    activateNext(signal: AbortSignal): Promise<void>;
     deactivateNext(): Promise<void>;
-    resumePrevious(): Promise<void>;
-    openNext(): void;
 }

package/lib/handoff.js

@@ -1,8 +1,14 @@
 import { DisposeStack } from './dispose.js';
+/** A transaction failed and its internal compensation also failed. */
+export class GenerationCompensationError extends AggregateError {
+    constructor(errors, message, options) {
+        super(errors, message, options);
+        this.name = 'GenerationCompensationError';
+    }
+}
 /** Composes owner-ordered Resource handoffs and compensates partial progress. */
 export class GenerationHandoffStack {
     #participants = [];
-    #quiesced = [];
     #activated = [];
     #sealed = false;
     get size() {
@@ -18,27 +24,13 @@ export class GenerationHandoffStack {
         this.#sealed = true;
         return this.size > 0 ? this : undefined;
     }
-    async quiescePrevious(previous) {
-        this.#assertSealed();
-        try {
-            for (const participant of [...this.#participants].reverse()) {
-                if (!participant.quiescePrevious)
-                    continue;
-                await participant.quiescePrevious(previous);
-                this.#quiesced.push(participant);
-            }
-        }
-        catch (error) {
-            await compensate(error, () => this.resumePrevious(), 'Quiesce and resume both failed');
-        }
-    }
-    async activateNext() {
+    async activateNext(signal) {
         this.#assertSealed();
         try {
             for (const participant of this.#participants) {
                 if (!participant.activateNext)
                     continue;
-                await participant.activateNext();
+                await participant.activateNext(signal);
                 this.#activated.push(participant);
             }
         }
@@ -49,22 +41,6 @@ export class GenerationHandoffStack {
     async deactivateNext() {
         await unwind(this.#activated, (participant) => participant.deactivateNext?.(), 'One or more next-generation Resources failed to deactivate');
     }
-    async resumePrevious() {
-        await unwind(this.#quiesced, (participant) => participant.resumePrevious?.(), 'One or more previous-generation Resources failed to resume');
-    }
-    openNext() {
-        const errors = [];
-        for (const participant of this.#participants) {
-            try {
-                participant.openNext?.();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, 'One or more Resources failed to open');
-    }
     #assertSealed() {
         if (!this.#sealed)
             throw new Error('GenerationHandoffStack is not sealed');
@@ -75,7 +51,7 @@ async function compensate(primary, rollback, message) {
         await rollback();
     }
     catch (rollbackError) {
-        throw new AggregateError([primary, rollbackError], message, { cause: rollbackError });
+        throw new GenerationCompensationError([primary, rollbackError], message, { cause: rollbackError });
     }
     throw primary;
 }

package/lib/identity.d.ts

@@ -18,6 +18,15 @@ 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;
+/**
+ * Capability localName 的单段校验（`/` 分隔前的一段）。
+ *
+ * - `$name`：动态参数段（ASCII）
+ * - ASCII kebab / snake：`hello` / `lottery-today` / `voice_stt`
+ * - Unicode 名：须含至少一个非 ASCII 字符，且不得含 ASCII 大写（拉丁仍走 kebab/snake）
+ */
+export declare function isCapabilityLocalSegment(segment: string): boolean;
+export declare function isCapabilityLocalName(localName: string): boolean;
 /**
  * Database-safe owner encoding used by process-wide plugin resources.
  *

package/lib/identity.js

@@ -1,7 +1,14 @@
 const namespacePattern = /^[a-z][a-z0-9.-]*$/;
+/** Plugin instanceKey 仍限 ASCII kebab（配置键 / PluginId 路径段）。 */
 const localNamePattern = /^[a-z0-9][a-z0-9-]*$/;
-const capabilityLocalSegment = String.raw `(?:[a-z0-9][a-z0-9-]*|\$[a-z][a-zA-Z0-9]*)`;
-const capabilityLocalNamePattern = new RegExp(`^${capabilityLocalSegment}(?:/${capabilityLocalSegment})*$`);
+/** 动态参数段（`[name].ts` → `$name`），标识符仍为 ASCII。 */
+const dynamicCapabilitySegment = /^\$[a-z][a-zA-Z0-9]*$/u;
+/**
+ * 静态 Capability / 命令路径段：ASCII kebab 或 snake（Host / agent tools 如 `voice_stt`），
+ * 或含非 ASCII 字母的 Unicode 名（如 `赞我`）。
+ */
+const asciiNameSegment = /^[a-z0-9][a-z0-9_-]*$/u;
+const unicodeNameSegment = /^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u;
 function assertNamespace(value, label) {
     if (!namespacePattern.test(value)) {
         throw new TypeError(`Invalid ${label}: ${value}`);
@@ -24,6 +31,31 @@ export function childPluginId(parent, instanceKey) {
     }
     return `${parent}/${instanceKey}`;
 }
+/**
+ * Capability localName 的单段校验（`/` 分隔前的一段）。
+ *
+ * - `$name`：动态参数段（ASCII）
+ * - ASCII kebab / snake：`hello` / `lottery-today` / `voice_stt`
+ * - Unicode 名：须含至少一个非 ASCII 字符，且不得含 ASCII 大写（拉丁仍走 kebab/snake）
+ */
+export function isCapabilityLocalSegment(segment) {
+    if (!segment || segment.includes('/') || segment.includes('\0'))
+        return false;
+    if (dynamicCapabilitySegment.test(segment))
+        return true;
+    if (asciiNameSegment.test(segment))
+        return true;
+    if (/[A-Z]/.test(segment))
+        return false;
+    if (!/[^\x00-\x7F]/u.test(segment))
+        return false;
+    return unicodeNameSegment.test(segment);
+}
+export function isCapabilityLocalName(localName) {
+    if (!localName)
+        return false;
+    return localName.split('/').every(isCapabilityLocalSegment);
+}
 /**
  * Database-safe owner encoding used by process-wide plugin resources.
  *
@@ -38,7 +70,7 @@ export function pluginOwnerResourceKey(owner) {
         .join('_')}_`;
 }
 export function capabilityId(owner, feature, localName) {
-    if (!capabilityLocalNamePattern.test(localName)) {
+    if (!isCapabilityLocalName(localName)) {
         throw new TypeError(`Invalid capability local name: ${localName}`);
     }
     return `${owner}\0${feature}\0${localName}`;

package/lib/index.d.ts

@@ -2,6 +2,7 @@
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionBindable, type GenerationAdmissionSource, } from './admission.js';
 export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
@@ -16,10 +17,12 @@ export * from './token.js';
 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：`componentHostToken`（承诺 semver）。 */
+export * from './component-host.js';
 /** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
+/** @public 跨通道发送辅助：`createOutboundSender` / `sendTo`（承诺 semver）。 */
+export * from './outbound-sender.js';
 export * from './inbox.js';
 export * from './system-log.js';

package/lib/index.js

@@ -2,6 +2,7 @@
 export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
+export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, } from './admission.js';
 export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
@@ -16,10 +17,12 @@ export * from './token.js';
 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：`componentHostToken`（承诺 semver）。 */
+export * from './component-host.js';
 /** @public Host token：`outboundHostToken`（承诺 semver）。 */
 export * from './outbound-host.js';
+/** @public 跨通道发送辅助：`createOutboundSender` / `sendTo`（承诺 semver）。 */
+export * from './outbound-sender.js';
 export * from './inbox.js';
 export * from './system-log.js';

package/lib/outbound-host.d.ts

@@ -19,28 +19,38 @@ export interface OutboundConversation {
  */
 export interface OutboundSendInput {
     readonly adapter: string;
-    readonly endpointId: string;
+    readonly endpointKey: string;
     readonly conversation: OutboundConversation;
     readonly content: string;
 }
 export interface OutboundReactionInput {
     readonly adapter: string;
-    readonly endpointId: string;
-    readonly messageId: string;
+    readonly endpointKey: string;
+    readonly message: OutboundMessage;
     readonly emoji: string;
     readonly sceneType?: string;
     readonly channelId?: string;
 }
 export interface OutboundRemoveReactionInput {
     readonly adapter: string;
-    readonly endpointId: string;
-    readonly messageId: string;
+    readonly endpointKey: string;
+    readonly message: OutboundMessage;
     readonly reactionId: string;
 }
 export interface OutboundRecallInput {
     readonly adapter: string;
-    readonly endpointId: string;
-    readonly messageId: string;
+    readonly endpointKey: string;
+    readonly message: OutboundMessage;
+}
+/** Structured message identity; structurally compatible with IM MessageRef. */
+export interface OutboundMessage {
+    readonly conversation: OutboundConversation & Readonly<{
+        readonly endpoint: Readonly<{
+            readonly id: string;
+            readonly adapter: string;
+        }>;
+    }>;
+    readonly id: string;
 }
 export interface OutboundHost {
     /** Returns platform message id when available (activity-feedback needs it). */

package/lib/outbound-sender.d.ts

@@ -0,0 +1,70 @@
+import type { Token } from './token.js';
+import { type OutboundConversation, type OutboundHost, type OutboundSendInput } from './outbound-host.js';
+/**
+ * 构造群临时会话地址（如 QQ 群临时私聊）。
+ *
+ * ```ts
+ * await message.$sendTo(tempSession('12345', '67890'), '通过群临时会话私信');
+ * await sender.send(tempSession('12345', '67890'), '通知');
+ * ```
+ */
+export declare function tempSession(userId: string, fromGroupId: string): OutboundConversation;
+/**
+ * 构造频道子通道地址（如 QQ 频道内的子频道）。
+ *
+ * ```ts
+ * await message.$sendTo(guildChannel('channel-1', 'guild-1'), '频道通知');
+ * ```
+ */
+export declare function guildChannel(channelId: string, guildId: string, threadId?: string): OutboundConversation;
+/**
+ * 结构兼容 CapabilityContext.use()、Scope.use()、EndpointCommandUse 的最小访问器。
+ */
+export type UseAccessor = <T>(token: Token<T>) => T;
+/**
+ * 预绑定 adapter + endpoint 的发送器。
+ *
+ * ```ts
+ * const sender = createOutboundSender(context.use, 'root/icqq', 'main');
+ * await sender.send('group', '67890', 'hello');
+ * await sender.send({ kind: 'private', id: '12345' }, 'DM');
+ * ```
+ */
+export interface OutboundSender {
+    send(kind: OutboundConversation['kind'], id: string, content: string): Promise<string | null>;
+    send(conversation: OutboundConversation, content: string): Promise<string | null>;
+    readonly host: OutboundHost;
+    readonly adapter: string;
+    readonly endpointKey: string;
+}
+/**
+ * 创建预绑定 adapter + endpoint 的发送器。
+ *
+ * 在 defineCommand 中：
+ * ```ts
+ * const sender = createOutboundSender(context.use, 'root/telegram', 'main');
+ * await sender.send('group', 'chat123', 'hello');
+ * ```
+ *
+ * 在 definePlugin setup 中：
+ * ```ts
+ * const sender = createOutboundSender(
+ *   (token) => context.resources.use(token),
+ *   config.adapter,
+ *   config.endpointKey,
+ * );
+ * ```
+ */
+export declare function createOutboundSender(use: UseAccessor, adapter: string, endpointKey: string): OutboundSender;
+/**
+ * 一次性发送：解析 OutboundHost 并发送到指定目标。
+ *
+ * ```ts
+ * await sendTo(context.use, {
+ *   adapter: 'root/icqq',
+ *   endpointKey: 'main',
+ *   conversation: { kind: 'group', id: '67890' },
+ * }, 'hello');
+ * ```
+ */
+export declare function sendTo(use: UseAccessor, target: Omit<OutboundSendInput, 'content'>, content: string): Promise<string | null>;

package/lib/outbound-sender.js

@@ -0,0 +1,85 @@
+import { outboundHostToken } from './outbound-host.js';
+// ── 会话地址构造器 ──────────────────────────────────────────────────
+/**
+ * 构造群临时会话地址（如 QQ 群临时私聊）。
+ *
+ * ```ts
+ * await message.$sendTo(tempSession('12345', '67890'), '通过群临时会话私信');
+ * await sender.send(tempSession('12345', '67890'), '通知');
+ * ```
+ */
+export function tempSession(userId, fromGroupId) {
+    return { kind: 'private', id: userId, parent: { kind: 'group', id: fromGroupId } };
+}
+/**
+ * 构造频道子通道地址（如 QQ 频道内的子频道）。
+ *
+ * ```ts
+ * await message.$sendTo(guildChannel('channel-1', 'guild-1'), '频道通知');
+ * ```
+ */
+export function guildChannel(channelId, guildId, threadId) {
+    return {
+        kind: 'channel',
+        id: channelId,
+        parent: { kind: 'channel', id: guildId },
+        ...(threadId ? { threadId } : {}),
+    };
+}
+/**
+ * 创建预绑定 adapter + endpoint 的发送器。
+ *
+ * 在 defineCommand 中：
+ * ```ts
+ * const sender = createOutboundSender(context.use, 'root/telegram', 'main');
+ * await sender.send('group', 'chat123', 'hello');
+ * ```
+ *
+ * 在 definePlugin setup 中：
+ * ```ts
+ * const sender = createOutboundSender(
+ *   (token) => context.resources.use(token),
+ *   config.adapter,
+ *   config.endpointKey,
+ * );
+ * ```
+ */
+export function createOutboundSender(use, adapter, endpointKey) {
+    const host = use(outboundHostToken);
+    return Object.freeze({
+        host,
+        adapter,
+        endpointKey,
+        send(kindOrConversation, idOrContent, maybeContent) {
+            if (typeof kindOrConversation === 'string' && maybeContent !== undefined) {
+                return host.send({
+                    adapter,
+                    endpointKey,
+                    conversation: { kind: kindOrConversation, id: idOrContent },
+                    content: maybeContent,
+                });
+            }
+            return host.send({
+                adapter,
+                endpointKey,
+                conversation: kindOrConversation,
+                content: idOrContent,
+            });
+        },
+    });
+}
+/**
+ * 一次性发送：解析 OutboundHost 并发送到指定目标。
+ *
+ * ```ts
+ * await sendTo(context.use, {
+ *   adapter: 'root/icqq',
+ *   endpointKey: 'main',
+ *   conversation: { kind: 'group', id: '67890' },
+ * }, 'hello');
+ * ```
+ */
+export async function sendTo(use, target, content) {
+    const host = use(outboundHostToken);
+    return host.send({ ...target, content });
+}

package/lib/plugin.d.ts

@@ -18,6 +18,7 @@ export interface PluginInstanceView {
     readonly role: 'root' | 'child';
 }
 export interface PluginSetupContext<TConfig = unknown> {
+    readonly signal: AbortSignal;
     readonly plugin: PluginInstanceView;
     readonly config: ConfigView<TConfig>;
     readonly resources: Scope;

package/lib/root-controller.d.ts

@@ -1,21 +1,25 @@
 import type { PluginId } from './identity.js';
-import { SnapshotStore, type PreparedGeneration, type RuntimeSnapshot, type SnapshotState } from './snapshot.js';
+import { type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
 export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
-export type PrepareGeneration = (current: RuntimeSnapshot) => PreparedGeneration | Promise<PreparedGeneration>;
-export type PrepareTransaction = (current: RuntimeSnapshot) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
+export type PrepareGeneration = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | Promise<PreparedGeneration>;
+export type PrepareTransaction = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
 export type ControlErrorHandler = (error: unknown) => void;
 export interface GenerationCommitEvent {
     readonly previous: RuntimeSnapshot;
     readonly current: RuntimeSnapshot;
 }
 export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
+export declare class RootIntegrityError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
 export declare class RootController {
     #private;
     private readonly onControlError;
-    readonly snapshots: SnapshotStore;
+    readonly snapshots: SnapshotReader;
     constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
     get state(): RootState;
     get generation(): number;
+    get snapshot(): RuntimeSnapshot;
     /** Observe successful generation commits, including the initial start. */
     onGenerationCommit(listener: GenerationCommitListener): () => void;
     start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;

package/lib/root-controller.js

@@ -1,19 +1,43 @@
+import { GenerationCompensationError } from './handoff.js';
 import { SnapshotStore, } from './snapshot.js';
+export class RootIntegrityError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'RootIntegrityError';
+    }
+}
 export class RootController {
     onControlError;
     snapshots;
+    #snapshotStore;
     #state = 'idle';
     #tail = Promise.resolve();
+    #stopResult;
+    #stopRequested = false;
+    #activeTransaction;
     #generationCommitListeners = new Set();
     constructor(initial, onControlError = () => undefined) {
         this.onControlError = onControlError;
-        this.snapshots = new SnapshotStore(initial);
+        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error));
+        const store = this.#snapshotStore;
+        this.snapshots = Object.freeze({
+            acquire: () => {
+                if (this.#state !== 'running' || this.#stopRequested) {
+                    throw new RootIntegrityError(`Root is not accepting generation operations (${this.#state})`);
+                }
+                return store.acquire();
+            },
+            owns: (lease) => store.owns(lease),
+        });
     }
     get state() {
         return this.#state;
     }
     get generation() {
-        return this.snapshots.current.generation;
+        return this.#snapshotStore.current.generation;
+    }
+    get snapshot() {
+        return this.#snapshotStore.current;
     }
     /** Observe successful generation commits, including the initial start. */
     onGenerationCommit(listener) {
@@ -29,12 +53,15 @@ export class RootController {
             }
             let prepared;
             let activated = false;
+            const transaction = new AbortController();
+            this.#activeTransaction = transaction;
             try {
-                prepared = await prepare(this.snapshots.current);
+                prepared = await prepare(this.#snapshotStore.current, transaction.signal);
                 if (prepared.handoff) {
                     activated = true;
-                    await prepared.handoff.activateNext();
+                    await prepared.handoff.activateNext(transaction.signal);
                 }
+                this.#assertPublishable('idle');
                 this.#state = 'running';
                 const snapshot = this.#commitGeneration(0, prepared);
                 prepared = undefined;
@@ -44,6 +71,10 @@ export class RootController {
                 this.#state = 'failed';
                 return this.#rollback(prepared, { activated }, error);
             }
+            finally {
+                if (this.#activeTransaction === transaction)
+                    this.#activeTransaction = undefined;
+            }
         });
     }
     transact(prepare) {
@@ -53,26 +84,28 @@ export class RootController {
             }
             const previous = this.snapshots.acquire();
             let prepared;
-            let quiesced = false;
             let activated = false;
+            const transaction = new AbortController();
+            this.#activeTransaction = transaction;
             try {
-                prepared = await prepare(previous.value);
+                prepared = await prepare(previous.value, transaction.signal);
                 if (!prepared)
                     return previous.value;
                 if (prepared.handoff) {
-                    quiesced = true;
-                    await prepared.handoff.quiescePrevious(previous.value);
                     activated = true;
-                    await prepared.handoff.activateNext();
+                    await prepared.handoff.activateNext(transaction.signal);
                 }
+                this.#assertPublishable('running');
                 const snapshot = this.#commitGeneration(previous.value.generation, prepared);
                 prepared = undefined;
                 return snapshot;
             }
             catch (error) {
-                return this.#rollback(prepared, { quiesced, activated }, error);
+                return this.#rollback(prepared, { activated }, error);
             }
             finally {
+                if (this.#activeTransaction === transaction)
+                    this.#activeTransaction = undefined;
                 previous.release();
             }
         });
@@ -81,16 +114,26 @@ export class RootController {
         return this.transact(prepare);
     }
     stop() {
-        return this.#enqueue(async () => {
+        if (this.#stopResult)
+            return this.#stopResult;
+        this.#stopRequested = true;
+        this.#activeTransaction?.abort(new Error('Root lifecycle is stopping'));
+        const result = this.#enqueue(async () => {
             if (this.#state === 'stopped')
                 return;
             if (this.#state !== 'running' && this.#state !== 'failed') {
                 throw new Error(`Cannot stop RootController from ${this.#state}`);
             }
             this.#state = 'stopping';
-            await this.snapshots.close();
-            this.#state = 'stopped';
+            try {
+                await this.#snapshotStore.close();
+            }
+            finally {
+                this.#state = 'stopped';
+            }
         });
+        this.#stopResult = result;
+        return result;
     }
     #enqueue(operation) {
         const result = this.#tail.then(operation, operation);
@@ -98,9 +141,8 @@ export class RootController {
         return result;
     }
     #commitGeneration(expectedGeneration, prepared) {
-        const previous = this.snapshots.current;
-        const snapshot = this.snapshots.commit(expectedGeneration, prepared);
-        this.#openNext(prepared.handoff);
+        const previous = this.#snapshotStore.current;
+        const snapshot = this.#snapshotStore.commit(expectedGeneration, prepared);
         const event = Object.freeze({ previous, current: snapshot });
         const listeners = [...this.#generationCommitListeners];
         queueMicrotask(() => {
@@ -115,14 +157,6 @@ export class RootController {
         });
         return snapshot;
     }
-    #openNext(handoff) {
-        try {
-            handoff?.openNext();
-        }
-        catch (error) {
-            this.#reportControlError(error);
-        }
-    }
     #reportControlError(error) {
         try {
             this.onControlError(error);
@@ -141,14 +175,6 @@ export class RootController {
                 errors.push(error);
             }
         }
-        if (prepared && state.quiesced) {
-            try {
-                await prepared.handoff?.resumePrevious();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-        }
         if (prepared) {
             try {
                 await prepared.dispose();
@@ -157,9 +183,22 @@ export class RootController {
                 errors.push(error);
             }
         }
-        if (errors.length > 1) {
-            throw new AggregateError(errors, 'Generation transaction and rollback both failed');
+        if (errors.length > 1 || transactionError instanceof GenerationCompensationError) {
+            const aggregate = new AggregateError(errors, 'Generation transaction and rollback both failed');
+            this.#failIntegrity(aggregate);
+            throw new RootIntegrityError('Root integrity failed while rolling back a generation transaction', { cause: aggregate });
         }
         throw transactionError;
     }
+    #failIntegrity(error) {
+        if (this.#state === 'stopped' || this.#state === 'stopping')
+            return;
+        this.#state = 'failed';
+        this.#reportControlError(error);
+    }
+    #assertPublishable(expected) {
+        if (this.#state !== expected || this.#stopRequested) {
+            throw new RootIntegrityError(`Root cannot publish a generation after admission entered ${this.#stopRequested ? 'stopping' : this.#state}`);
+        }
+    }
 }

package/lib/snapshot.d.ts

@@ -32,19 +32,29 @@ export declare class GenerationConflictError extends Error {
     readonly actual: number;
     constructor(expected: number, actual: number);
 }
+declare const snapshotLeaseAuthority: unique symbol;
 export declare class SnapshotLease {
     #private;
     readonly value: RuntimeSnapshot;
     private readonly releaseRecord;
-    constructor(value: RuntimeSnapshot, releaseRecord: () => void);
+    constructor(value: RuntimeSnapshot, releaseRecord: () => void, authority: typeof snapshotLeaseAuthority);
+    get active(): boolean;
     release(): void;
 }
-export declare class SnapshotStore {
+/** Read-only operation seam exposed by a Root lifecycle. */
+export interface SnapshotReader {
+    acquire(): SnapshotLease;
+    owns(lease: SnapshotLease): boolean;
+}
+export declare class SnapshotStore implements SnapshotReader {
     #private;
-    constructor(initial: SnapshotState);
+    private readonly onDisposalError;
+    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void);
     get current(): RuntimeSnapshot;
     acquire(): SnapshotLease;
+    owns(lease: SnapshotLease): boolean;
     commit(expectedGeneration: number, prepared: PreparedGeneration): RuntimeSnapshot;
     close(): Promise<void>;
 }
 export declare function createSnapshotView(generation: number, state: SnapshotState): RuntimeSnapshot;
+export {};

package/lib/snapshot.js

@@ -1,3 +1,4 @@
+import { collectGenerationAdmissions, replaceGenerationAdmissions, } from './admission.js';
 export class GenerationConflictError extends Error {
     expected;
     actual;
@@ -8,13 +9,19 @@ export class GenerationConflictError extends Error {
         this.name = 'GenerationConflictError';
     }
 }
+const snapshotLeaseAuthority = Symbol('SnapshotLeaseAuthority');
 export class SnapshotLease {
     value;
     releaseRecord;
     #released = false;
-    constructor(value, releaseRecord) {
+    constructor(value, releaseRecord, authority) {
         this.value = value;
         this.releaseRecord = releaseRecord;
+        if (authority !== snapshotLeaseAuthority)
+            throw new TypeError('SnapshotLease is owned by SnapshotStore');
+    }
+    get active() {
+        return !this.#released;
     }
     release() {
         if (this.#released)
@@ -24,16 +31,24 @@ export class SnapshotLease {
     }
 }
 export class SnapshotStore {
+    onDisposalError;
     #current;
     #retired = new Set();
+    #leases = new WeakSet();
     #closed = false;
-    constructor(initial) {
-        this.#current = {
-            snapshot: createSnapshotView(0, initial),
+    constructor(initial, onDisposalError = () => undefined) {
+        this.onDisposalError = onDisposalError;
+        const snapshot = createSnapshotView(0, initial);
+        const admissions = collectSnapshotAdmissions(snapshot);
+        const record = {
+            snapshot,
             dispose: () => undefined,
+            admissions,
             leases: 0,
             retired: false,
         };
+        replaceGenerationAdmissions(new Set(), admissions, this, () => this.#retain(record));
+        this.#current = record;
     }
     get current() {
         return this.#current.snapshot;
@@ -42,11 +57,12 @@ export class SnapshotStore {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
         const record = this.#current;
-        record.leases += 1;
-        return new SnapshotLease(record.snapshot, () => {
-            record.leases -= 1;
-            this.#disposeIfReady(record);
-        });
+        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority);
+        this.#leases.add(lease);
+        return lease;
+    }
+    owns(lease) {
+        return this.#leases.has(lease);
     }
     commit(expectedGeneration, prepared) {
         // The caller owns a candidate until this method succeeds. This lets the
@@ -58,14 +74,19 @@ export class SnapshotStore {
             throw new GenerationConflictError(expectedGeneration, this.#current.snapshot.generation);
         }
         const previous = this.#current;
-        // Commit only swaps the active pointer. The previous record may still be
-        // serving in-flight work, so disposal is deferred to its final lease.
-        this.#current = {
-            snapshot: createSnapshotView(expectedGeneration + 1, prepared.snapshot),
+        const snapshot = createSnapshotView(expectedGeneration + 1, prepared.snapshot);
+        const admissions = collectSnapshotAdmissions(snapshot);
+        const next = {
+            snapshot,
             dispose: prepared.dispose,
+            admissions,
             leases: 0,
             retired: false,
         };
+        replaceGenerationAdmissions(previous.admissions, admissions, this, () => this.#retain(next));
+        // Commit only swaps the active pointer. The previous record may still be
+        // serving in-flight work, so disposal is deferred to its final lease.
+        this.#current = next;
         previous.retired = true;
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
@@ -75,6 +96,7 @@ export class SnapshotStore {
         if (this.#closed)
             return;
         this.#closed = true;
+        replaceGenerationAdmissions(this.#current.admissions, new Set(), this);
         this.#current.retired = true;
         this.#retired.add(this.#current);
         this.#disposeIfReady(this.#current);
@@ -88,9 +110,25 @@ export class SnapshotStore {
             return;
         if (!record.disposing) {
             record.disposing = Promise.resolve().then(record.dispose);
-            void record.disposing.then(() => record.drain?.resolve(), (error) => record.drain?.reject(error));
+            void record.disposing.then(() => record.drain?.resolve(), (error) => {
+                record.drain?.reject(error);
+                this.onDisposalError(error);
+            });
         }
     }
+    #retain(record) {
+        record.leases += 1;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            record.leases -= 1;
+            if (record.leases < 0)
+                throw new Error('Snapshot lease underflow');
+            this.#disposeIfReady(record);
+        };
+    }
     #waitForDisposal(record) {
         if (record.disposing)
             return record.disposing;
@@ -106,6 +144,12 @@ export class SnapshotStore {
         return record.drain.promise;
     }
 }
+function collectSnapshotAdmissions(snapshot) {
+    return collectGenerationAdmissions([
+        ...snapshot.projections.values(),
+        ...[...snapshot.resources.values()].flatMap((resources) => [...resources.values()]),
+    ]);
+}
 export function createSnapshotView(generation, state) {
     // Object.freeze(Map) does not disable Map#set. ReadonlyMapView removes the
     // mutator interface at runtime, including from provider projection hooks.

package/package.json

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

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

@@ -1,38 +0,0 @@
-/**
- * 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`). */
-    readonly name: string;
-    readonly description: string;
-    /** zod object schema or JSON Schema; drives the deferred catalog + arg validation. */
-    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';
-    /** Plugin/tool origin label (e.g. plugin name) for diagnostics. */
-    readonly source?: string;
-    execute(input: Record<string, unknown>): unknown | Promise<unknown>;
-}
-/**
- * Generation-owned Agent tool registry provided by the Agent Host.
- * Absent when AI is not installed/enabled — plugins must guard with `has()`.
- */
-export interface AgentToolsHost {
-    /** Register a tool for every Agent turn of this generation; returns disposal. */
-    register(tool: AgentToolRegistration): () => void;
-}
-export declare const agentToolsHostToken: import("./token.js").Token<AgentToolsHost>;

package/lib/agent-tools-host.js

@@ -1,2 +0,0 @@
-import { createToken } from './token.js';
-export const agentToolsHostToken = createToken('zhin.agent-tools.host', 'Plugin Runtime agent tools host');