@zhin.js/plugin-runtime 1.0.0 → 1.1.0

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

@@ -0,0 +1,29 @@
+/**
+ * Plugin-contributed Agent tool registered against the Agent Host.
+ * Captured at setup() time — execute closures must never call plugin locators.
+ */
+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[];
+    readonly permissions?: readonly string[];
+    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

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

package/lib/database-host.d.ts

@@ -1,12 +1,15 @@
+export interface DatabaseHostSelection {
+    where(query: Record<string, unknown>): DatabaseHostSelection;
+    orderBy(field: string, direction?: 'ASC' | 'DESC'): DatabaseHostSelection;
+    limit(count: number): DatabaseHostSelection;
+    then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
 /**
  * Minimal model surface shared by lottery / rss / group-suite memory stores
  * and the Host-backed `@zhin.js/database` adapter.
  */
 export interface DatabaseHostModel {
-    select(): {
-        where(query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-        then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
-    };
+    select(...fields: string[]): DatabaseHostSelection;
     insert(row: Record<string, unknown>): Promise<unknown>;
     delete(): {
         where(query: Record<string, unknown>): Promise<unknown>;

package/lib/inbox.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseHost } from './database-host.js';
+/**
+ * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
+ * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
+ * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
+ * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ */
+export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
+export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";
+export declare const INBOX_TABLE_NOTICE = "unified_inbox_notice";
+export declare const INBOX_MESSAGE_DEFINITION: Record<string, unknown>;
+export declare const INBOX_REQUEST_DEFINITION: Record<string, unknown>;
+export declare const INBOX_NOTICE_DEFINITION: Record<string, unknown>;
+export declare const INBOX_TABLE_DEFINITIONS: Readonly<Record<string, Record<string, unknown>>>;
+/**
+ * 在 DatabaseHost 上注册三张收件箱表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export declare function defineInboxTables(host: Pick<DatabaseHost, 'define' | 'tables' | 'started'>): void;
+/**
+ * 写一行收件箱记录；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export declare function insertInboxRow(host: Pick<DatabaseHost, 'models'>, table: string, row: Record<string, unknown>): Promise<boolean>;
+/** Console SSE 事件 fan-out 的最小结构（@zhin.js/host-http ConsoleEventHub 满足该形状）。 */
+export interface RuntimeEventPublisher {
+    publish(type: string, data: unknown): void;
+}
+/**
+ * Root 级事件发布口（console hub）。basic/cli console-api-installer 提供；
+ * 适配器等插件经 CapabilityContext.use 解析后 publish endpoint:request/notice 等事件。
+ */
+export declare const runtimeEventPublisherToken: import("./token.js").Token<RuntimeEventPublisher>;

package/lib/inbox.js

@@ -0,0 +1,99 @@
+import { createToken } from './token.js';
+/**
+ * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
+ * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
+ * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
+ * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ */
+export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
+export const INBOX_TABLE_REQUEST = 'unified_inbox_request';
+export const INBOX_TABLE_NOTICE = 'unified_inbox_notice';
+export const INBOX_MESSAGE_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_message_id: { type: 'text', nullable: false },
+    channel_id: { type: 'text', nullable: false },
+    channel_type: { type: 'text', nullable: false },
+    channel_name: { type: 'text', nullable: true },
+    channel_parent_type: { type: 'text', nullable: true },
+    channel_parent_id: { type: 'text', nullable: true },
+    sender_id: { type: 'text', nullable: false },
+    sender_name: { type: 'text', nullable: true },
+    sender_payload: { type: 'text', nullable: false },
+    content: { type: 'text', nullable: false },
+    raw: { type: 'text', nullable: true },
+    created_at: { type: 'integer', nullable: false },
+};
+export const INBOX_REQUEST_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_request_id: { type: 'text', nullable: false },
+    type: { type: 'text', nullable: false },
+    scene_type: { type: 'text', nullable: true },
+    scene_id: { type: 'text', nullable: false },
+    sub_type: { type: 'text', nullable: true },
+    actor_id: { type: 'text', nullable: false },
+    actor_name: { type: 'text', nullable: true },
+    comment: { type: 'text', nullable: true },
+    created_at: { type: 'integer', nullable: false },
+    resolved: { type: 'integer', nullable: false, default: 0 },
+    resolved_at: { type: 'integer', nullable: true },
+    consumed: { type: 'integer', nullable: false, default: 0 },
+    consumed_at: { type: 'integer', nullable: true },
+};
+export const INBOX_NOTICE_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    adapter: { type: 'text', nullable: false },
+    endpoint_id: { type: 'text', nullable: false },
+    platform_notice_id: { type: 'text', nullable: false },
+    type: { type: 'text', nullable: false },
+    scene_type: { type: 'text', nullable: true },
+    scene_id: { type: 'text', nullable: false },
+    sub_type: { type: 'text', nullable: true },
+    actor_id: { type: 'text', nullable: true },
+    actor_name: { type: 'text', nullable: true },
+    target_id: { type: 'text', nullable: true },
+    target_name: { type: 'text', nullable: true },
+    payload: { type: 'text', nullable: false },
+    created_at: { type: 'integer', nullable: false },
+    consumed: { type: 'integer', nullable: false, default: 0 },
+    consumed_at: { type: 'integer', nullable: true },
+};
+export const INBOX_TABLE_DEFINITIONS = Object.freeze({
+    [INBOX_TABLE_MESSAGE]: INBOX_MESSAGE_DEFINITION,
+    [INBOX_TABLE_REQUEST]: INBOX_REQUEST_DEFINITION,
+    [INBOX_TABLE_NOTICE]: INBOX_NOTICE_DEFINITION,
+});
+/**
+ * 在 DatabaseHost 上注册三张收件箱表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export function defineInboxTables(host) {
+    if (host.started)
+        return;
+    const existing = new Set(host.tables());
+    for (const [name, definition] of Object.entries(INBOX_TABLE_DEFINITIONS)) {
+        if (!existing.has(name))
+            host.define(name, definition);
+    }
+}
+/**
+ * 写一行收件箱记录；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export async function insertInboxRow(host, table, row) {
+    const model = host.models.get(table);
+    if (!model)
+        return false;
+    await model.insert(row);
+    return true;
+}
+/**
+ * Root 级事件发布口（console hub）。basic/cli console-api-installer 提供；
+ * 适配器等插件经 CapabilityContext.use 解析后 publish endpoint:request/notice 等事件。
+ */
+export const runtimeEventPublisherToken = createToken('zhin.runtime.event-publisher', 'Runtime event publisher (console SSE hub fan-out)');

package/lib/index.d.ts

@@ -9,5 +9,8 @@ export * from './snapshot.js';
 export * from './token.js';
 export * from './schedule-host.js';
 export * from './database-host.js';
+export * from './agent-tools-host.js';
 export * from './html-renderer.js';
 export * from './outbound-host.js';
+export * from './inbox.js';
+export * from './system-log.js';

package/lib/index.js

@@ -9,5 +9,8 @@ export * from './snapshot.js';
 export * from './token.js';
 export * from './schedule-host.js';
 export * from './database-host.js';
+export * from './agent-tools-host.js';
 export * from './html-renderer.js';
 export * from './outbound-host.js';
+export * from './inbox.js';
+export * from './system-log.js';

package/lib/root-controller.d.ts

@@ -4,6 +4,11 @@ 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 ControlErrorHandler = (error: unknown) => void;
+export interface GenerationCommitEvent {
+    readonly previous: RuntimeSnapshot;
+    readonly current: RuntimeSnapshot;
+}
+export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
 export declare class RootController {
     #private;
     private readonly onControlError;
@@ -11,6 +16,8 @@ export declare class RootController {
     constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
     get state(): RootState;
     get generation(): number;
+    /** Observe successful generation commits, including the initial start. */
+    onGenerationCommit(listener: GenerationCommitListener): () => void;
     start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
     transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
     reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;

package/lib/root-controller.js

@@ -4,6 +4,7 @@ export class RootController {
     snapshots;
     #state = 'idle';
     #tail = Promise.resolve();
+    #generationCommitListeners = new Set();
     constructor(initial, onControlError = () => undefined) {
         this.onControlError = onControlError;
         this.snapshots = new SnapshotStore(initial);
@@ -14,6 +15,13 @@ export class RootController {
     get generation() {
         return this.snapshots.current.generation;
     }
+    /** Observe successful generation commits, including the initial start. */
+    onGenerationCommit(listener) {
+        this.#generationCommitListeners.add(listener);
+        return () => {
+            this.#generationCommitListeners.delete(listener);
+        };
+    }
     start(prepare) {
         return this.#enqueue(async () => {
             if (this.#state !== 'idle') {
@@ -27,11 +35,9 @@ export class RootController {
                     activated = true;
                     await prepared.handoff.activateNext();
                 }
-                const handoff = prepared.handoff;
-                const snapshot = this.snapshots.commit(0, prepared);
-                prepared = undefined;
                 this.#state = 'running';
-                this.#openNext(handoff);
+                const snapshot = this.#commitGeneration(0, prepared);
+                prepared = undefined;
                 return snapshot;
             }
             catch (error) {
@@ -59,10 +65,8 @@ export class RootController {
                     activated = true;
                     await prepared.handoff.activateNext();
                 }
-                const handoff = prepared.handoff;
-                const snapshot = this.snapshots.commit(previous.value.generation, prepared);
+                const snapshot = this.#commitGeneration(previous.value.generation, prepared);
                 prepared = undefined;
-                this.#openNext(handoff);
                 return snapshot;
             }
             catch (error) {
@@ -93,17 +97,38 @@ export class RootController {
         this.#tail = result.catch(() => undefined);
         return result;
     }
+    #commitGeneration(expectedGeneration, prepared) {
+        const previous = this.snapshots.current;
+        const snapshot = this.snapshots.commit(expectedGeneration, prepared);
+        this.#openNext(prepared.handoff);
+        const event = Object.freeze({ previous, current: snapshot });
+        const listeners = [...this.#generationCommitListeners];
+        queueMicrotask(() => {
+            for (const listener of listeners) {
+                try {
+                    listener(event);
+                }
+                catch (error) {
+                    this.#reportControlError(error);
+                }
+            }
+        });
+        return snapshot;
+    }
     #openNext(handoff) {
         try {
             handoff?.openNext();
         }
         catch (error) {
-            try {
-                this.onControlError(error);
-            }
-            catch {
-                // Error reporting cannot roll back an already committed generation.
-            }
+            this.#reportControlError(error);
+        }
+    }
+    #reportControlError(error) {
+        try {
+            this.onControlError(error);
+        }
+        catch {
+            // Error reporting cannot roll back an already committed generation.
         }
     }
     async #rollback(prepared, state, transactionError) {

package/lib/system-log.d.ts

@@ -0,0 +1,19 @@
+import type { DatabaseHost } from './database-host.js';
+/**
+ * 系统日志表（console logs 页数据源）定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ */
+export declare const SYSTEM_LOG_TABLE = "SystemLog";
+export declare const SYSTEM_LOG_DEFINITION: Record<string, unknown>;
+/**
+ * 在 DatabaseHost 上注册系统日志表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export declare function defineSystemLogTable(host: Pick<DatabaseHost, 'define' | 'tables' | 'started'>): void;
+/**
+ * 写一行系统日志；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export declare function insertSystemLogRow(host: Pick<DatabaseHost, 'models'>, row: Record<string, unknown>): Promise<boolean>;

package/lib/system-log.js

@@ -0,0 +1,37 @@
+/**
+ * 系统日志表（console logs 页数据源）定义与写入辅助。
+ *
+ * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ */
+export const SYSTEM_LOG_TABLE = 'SystemLog';
+export const SYSTEM_LOG_DEFINITION = {
+    id: { type: 'integer', primary: true, autoIncrement: true },
+    level: { type: 'text', nullable: false },
+    name: { type: 'text', nullable: false },
+    message: { type: 'text', nullable: false },
+    source: { type: 'text', nullable: false },
+    timestamp: { type: 'date', nullable: false },
+};
+/**
+ * 在 DatabaseHost 上注册系统日志表（幂等：已定义或已启动的 host 跳过）。
+ * 必须在 host.start() 之前调用（define 在 started 后会抛错）。
+ */
+export function defineSystemLogTable(host) {
+    if (host.started)
+        return;
+    if (!host.tables().includes(SYSTEM_LOG_TABLE)) {
+        host.define(SYSTEM_LOG_TABLE, SYSTEM_LOG_DEFINITION);
+    }
+}
+/**
+ * 写一行系统日志；表未注册（或 host 未启动导致 model 缺失）时返回 false。
+ * 写失败向上抛，由调用方决定降级策略。
+ */
+export async function insertSystemLogRow(host, row) {
+    const model = host.models.get(SYSTEM_LOG_TABLE);
+    if (!model)
+        return false;
+    await model.insert(row);
+    return true;
+}

package/package.json

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