@zhin.js/plugin-runtime 1.1.3 → 1.1.5

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/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

@@ -16,10 +16,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

@@ -16,10 +16,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,13 +19,13 @@ 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 endpointKey: string;
     readonly messageId: string;
     readonly emoji: string;
     readonly sceneType?: string;
@@ -33,13 +33,13 @@ export interface OutboundReactionInput {
 }
 export interface OutboundRemoveReactionInput {
     readonly adapter: string;
-    readonly endpointId: string;
+    readonly endpointKey: string;
     readonly messageId: string;
     readonly reactionId: string;
 }
 export interface OutboundRecallInput {
     readonly adapter: string;
-    readonly endpointId: string;
+    readonly endpointKey: string;
     readonly messageId: string;
 }
 export interface OutboundHost {

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/snapshot.d.ts

@@ -32,11 +32,13 @@ 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 {
@@ -44,7 +46,9 @@ export declare class SnapshotStore {
     constructor(initial: SnapshotState);
     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

@@ -8,13 +8,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)
@@ -26,6 +32,7 @@ export class SnapshotLease {
 export class SnapshotStore {
     #current;
     #retired = new Set();
+    #leases = new WeakSet();
     #closed = false;
     constructor(initial) {
         this.#current = {
@@ -43,10 +50,15 @@ export class SnapshotStore {
             throw new Error('SnapshotStore is closed');
         const record = this.#current;
         record.leases += 1;
-        return new SnapshotLease(record.snapshot, () => {
+        const lease = new SnapshotLease(record.snapshot, () => {
             record.leases -= 1;
             this.#disposeIfReady(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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "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');