@zhin.js/plugin-runtime 1.1.16 → 1.1.18

package/lib/admission.d.ts

@@ -1,13 +1,15 @@
 export declare class GenerationAdmissionGate {
     #private;
     get active(): boolean;
+    /** Root closure fact, bound at first publication and retained after generation retirement. */
+    get stopSignal(): AbortSignal | undefined;
     acquire(): (() => void) | undefined;
     /** Observe the first commit which publishes this generation. */
     onActivate(listener: () => void): () => void;
     /**
      * 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.
+     * synchronous and must not fail. It closes new admission; it does not decide
+     * whether already-owned transports or work should end. Use stopSignal for Root shutdown.
      */
     onDeactivate(listener: () => void): () => void;
     enter<T>(operation: () => T): T | undefined;
@@ -26,4 +28,14 @@ export interface GenerationAdmissionSource {
 }
 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, publishNext: () => void, acquireNext?: () => () => void): void;
+/** One SnapshotStore-owned publication; all gates share that Root's explicit close fact. */
+interface GenerationAdmissionTransition {
+    readonly previous: ReadonlySet<GenerationAdmissionGate>;
+    readonly next: ReadonlySet<GenerationAdmissionGate>;
+    readonly owner: object;
+    readonly publishNext: () => void;
+    readonly acquireNext?: () => () => void;
+    readonly stopSignal: AbortSignal;
+}
+export declare function replaceGenerationAdmissions({ previous, next, owner, publishNext, acquireNext, stopSignal }: GenerationAdmissionTransition): void;
+export {};

package/lib/admission.js

@@ -5,13 +5,14 @@ let admissionLifecycle;
 export class GenerationAdmissionGate {
     #state = { active: false };
     #owner;
+    #stopSignal;
     #activationListeners = new Set();
     #deactivationListeners = new Set();
     static {
         admissionLifecycle = {
             assertClaimable: (gate, owner) => gate.#assertClaimable(owner),
             assertOwner: (gate, owner) => gate.#assertOwner(owner),
-            claim: (gate, owner) => { gate.#owner = owner; },
+            claim: (gate, owner, stopSignal) => { gate.#owner = owner; gate.#stopSignal = stopSignal; },
             activate: (gate, acquire) => gate.#activate(acquire),
             deactivate: (gate) => gate.#deactivate(),
             notifyActivation: (gate) => gate.#notifyActivation(),
@@ -21,6 +22,10 @@ export class GenerationAdmissionGate {
     get active() {
         return this.#state.active;
     }
+    /** Root closure fact, bound at first publication and retained after generation retirement. */
+    get stopSignal() {
+        return this.#stopSignal;
+    }
     acquire() {
         return this.#state.active ? this.#state.acquire?.() : undefined;
     }
@@ -35,8 +40,8 @@ export class GenerationAdmissionGate {
     }
     /**
      * 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.
+     * synchronous and must not fail. It closes new admission; it does not decide
+     * whether already-owned transports or work should end. Use stopSignal for Root shutdown.
      */
     onDeactivate(listener) {
         if (!this.active) {
@@ -136,7 +141,7 @@ export function collectGenerationAdmissions(values) {
     }
     return result;
 }
-export function replaceGenerationAdmissions(previous, next, owner, publishNext, acquireNext) {
+export function replaceGenerationAdmissions({ previous, next, owner, publishNext, acquireNext, stopSignal }) {
     // 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)
@@ -148,7 +153,7 @@ export function replaceGenerationAdmissions(previous, next, owner, publishNext,
     // potentially rejecting ownership check has completed before publication.
     publishNext();
     for (const gate of next)
-        admissionLifecycle.claim(gate, owner);
+        admissionLifecycle.claim(gate, owner, stopSignal);
     for (const gate of previous) {
         if (next.has(gate))
             continue;

package/lib/data-migration.d.ts

@@ -0,0 +1,105 @@
+import type { DeliveryTarget } from './delivery-target.js';
+import type { GenerationAdmissionSource } from './admission.js';
+import type { JsonValue } from './persistent-state.js';
+/** Read-only, owner-namespaced historical data; candidate IDs are opaque to the Host. */
+export interface DataMigrationCandidate {
+    readonly id: string;
+    readonly domain: string;
+    readonly title: string;
+    readonly sourceVersion: string;
+    readonly recordCount: number;
+    readonly beforeDigest: string;
+    readonly status: 'unresolved' | 'canonical' | 'corrupt';
+    /** Display facts only; never a preselected account or recovered authorization. */
+    readonly summary: Readonly<Record<string, JsonValue>>;
+    /** False when the configured persistence cannot supply the required atomic unit. */
+    readonly executable: boolean;
+}
+export interface DataMigrationInventory {
+    readonly revision: string;
+    readonly candidates: readonly DataMigrationCandidate[];
+}
+export interface DataMigrationRequest {
+    readonly signal?: AbortSignal;
+}
+export interface PrepareDataMigrationRequest extends DataMigrationRequest {
+    /** Host-generated operation UUID; reused to reconcile a lost response. */
+    readonly planId: string;
+    readonly candidateId: string;
+    readonly expectedDigest: string;
+    /** Explicit administrator selection, validated by the Host against the account directory. */
+    readonly target: DeliveryTarget;
+}
+/** Domain-prepared exact unit; the Host persists the complete plan before admitting any mutation. */
+export interface DataMigrationPlan {
+    readonly id: string;
+    readonly candidateId: string;
+    readonly domain: string;
+    readonly sourceVersion: string;
+    readonly beforeDigest: string;
+    readonly target: DeliveryTarget;
+    readonly recordCount: number;
+    /** Full lossless before-images and exact domain writes, not a 64 KiB state-store value. */
+    readonly data: JsonValue;
+    readonly description: readonly string[];
+    /** These facts require fresh authorization and must never be activated by a data migration. */
+    readonly authorizationCandidates: readonly JsonValue[];
+}
+export interface ApplyDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+/** Confirmed by the same atomic domain unit as the writes; unknown commits are never blindly retried. */
+export interface DataMigrationReceipt {
+    /** Distinguishes an original commit from its explicit reversal during reconciliation. */
+    readonly operation: 'apply' | 'restore';
+    readonly planId: string;
+    readonly candidateId: string;
+    readonly beforeDigest: string;
+    readonly afterDigest: string;
+    readonly recordCount: number;
+    readonly status: 'applied' | 'already_applied';
+    readonly maintenance: 'paused';
+}
+export interface ResumeDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+export interface RestoreDataMigrationRequest extends ResumeDataMigrationRequest {
+    readonly receipt: DataMigrationReceipt;
+}
+export interface InspectDataMigrationRequest extends DataMigrationRequest {
+    readonly plan: DataMigrationPlan;
+}
+/** Verified current rows plus the durable maintenance journal, never inferred from a missing receipt. */
+export interface DataMigrationInspection {
+    readonly data: 'not_applied' | 'applied' | 'restored' | 'conflict' | 'unknown';
+    readonly maintenance: 'paused' | 'resumed' | 'unknown';
+    /** True only for paused, drained scopes with a verified current recovery baseline; never authorizes data writes. */
+    readonly resumable: boolean;
+    /** A committed write receipt is not evidence that maintenance has resumed. */
+    readonly receipt?: DataMigrationReceipt;
+}
+/** Plugin owns record semantics, maintenance admission/drain and the existing transactional store. */
+export interface PluginDataMigrationProvider extends GenerationAdmissionSource {
+    readonly title: string;
+    preview(request?: DataMigrationRequest): Promise<DataMigrationInventory>;
+    prepare(request: PrepareDataMigrationRequest): Promise<DataMigrationPlan>;
+    /** Enter the selected scope's maintenance, drain work, recheck and commit; leave it paused. */
+    apply(request: ApplyDataMigrationRequest): Promise<DataMigrationReceipt>;
+    /** Pure authoritative inspection; an in-flight mutation or unprovable state remains unknown. */
+    inspect(request: InspectDataMigrationRequest): Promise<DataMigrationInspection>;
+    /** Explicit resumption never starts an account, replays delivery or extends a game deadline. */
+    resume(request: ResumeDataMigrationRequest): Promise<void>;
+    /** Restore only when the actual rows still match the confirmed after-image; remain paused. */
+    restore(request: RestoreDataMigrationRequest): Promise<DataMigrationReceipt>;
+}
+/**
+ * commit_unknown means the data commit result is unconfirmed. invalid_input/conflict/unsupported/
+ * not_found guarantee no data commit by this invocation, but do not imply maintenance was released.
+ * unavailable does not establish either outcome. Inspect before recovery; never blindly replay.
+ */
+export declare class DataMigrationError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'unsupported' | 'unavailable' | 'not_found' | 'commit_unknown';
+    constructor(code: 'invalid_input' | 'conflict' | 'unsupported' | 'unavailable' | 'not_found' | 'commit_unknown', message: string);
+}
+/** Existing owner Resource discovery, not a process-global migration registry. */
+export declare const pluginDataMigrationProviderToken: import("./token.js").Token<PluginDataMigrationProvider>;

package/lib/data-migration.js

@@ -0,0 +1,16 @@
+import { createToken } from './token.js';
+/**
+ * commit_unknown means the data commit result is unconfirmed. invalid_input/conflict/unsupported/
+ * not_found guarantee no data commit by this invocation, but do not imply maintenance was released.
+ * unavailable does not establish either outcome. Inspect before recovery; never blindly replay.
+ */
+export class DataMigrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DataMigrationError';
+    }
+}
+/** Existing owner Resource discovery, not a process-global migration registry. */
+export const pluginDataMigrationProviderToken = createToken('zhin.plugin-data-migration', 'Plugin-owned historical data migration, controlled by authenticated Host operations');

package/lib/database-host.d.ts

@@ -44,6 +44,11 @@ export interface DatabaseHostTable {
     readonly name: string;
     readonly columns?: Readonly<Record<string, unknown>>;
 }
+/** Explicit, additive upgrades applied before SQL models become available. */
+export interface DatabaseTableOptions {
+    /** Names from this table's definition. Existing columns and data remain untouched. */
+    readonly addColumns?: readonly string[];
+}
 export interface DatabaseHostSelectResult {
     readonly rows: readonly unknown[];
     readonly total: number;
@@ -83,7 +88,7 @@ export interface DatabaseHost {
     readonly dialect: string;
     readonly started: boolean;
     /** Register a table schema before `start` (column defs match `@zhin.js/database`). */
-    define(name: string, definition: Record<string, unknown>): void;
+    define(name: string, definition: Record<string, unknown>, options?: DatabaseTableOptions): void;
     /** Names of tables registered via `define` (Console `db:tables`). */
     tables(): readonly string[];
     models: {
@@ -129,7 +134,7 @@ export declare class PluginDatabaseHost extends OwnerScopedResourceHost {
     get [generationAdmissionSource](): readonly GenerationAdmissionGate[];
     get dialect(): string;
     get started(): boolean;
-    define(name: string, definition: Record<string, unknown>): void;
+    define(name: string, definition: Record<string, unknown>, options?: DatabaseTableOptions): void;
     tables(): readonly string[];
     transaction<T>(callback: (transaction: DatabaseHostTransaction) => Promise<T>): Promise<T>;
 }

package/lib/database-host.js

@@ -54,8 +54,10 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
     get started() {
         return this.#host.started;
     }
-    define(name, definition) {
-        this.#operation.setup(() => this.#host.define(this.qualify(name), definition));
+    define(name, definition, options) {
+        this.#operation.setup(() => options === undefined
+            ? this.#host.define(this.qualify(name), definition)
+            : this.#host.define(this.qualify(name), definition, options));
     }
     tables() {
         return this.#operation.setup(() => Object.freeze(this.#host.tables().flatMap((name) => {

package/lib/i18n.d.ts

@@ -0,0 +1,24 @@
+import type { DeliveryTarget } from './delivery-target.js';
+/** Supported display languages. Time zone and command identities are independent. */
+export type Locale = 'zh-CN' | 'en';
+export declare const DEFAULT_LOCALE: Locale;
+export declare const SUPPORTED_LOCALES: readonly ["zh-CN", "en"];
+export declare function isLocale(value: unknown): value is Locale;
+/** Resolve an absent display preference; configuration writes validate with isLocale. */
+export declare function resolveLocale(value: unknown): Locale;
+/** Immutable project language, projected with the operation's generation. */
+export declare const projectLocaleToken: import("./token.js").Token<Locale>;
+/** Root-owned preferences; identity never comes from display names or profile text. */
+export interface UserLocalePreferences {
+    get(endpoint: DeliveryTarget['endpoint'], senderId: string): Promise<Locale | undefined>;
+    set(endpoint: DeliveryTarget['endpoint'], senderId: string, locale: Locale): Promise<void>;
+}
+export declare const userLocalePreferencesToken: import("./token.js").Token<UserLocalePreferences>;
+export type MessageCatalog = Readonly<Record<string, Readonly<Record<Locale, string>>>>;
+export type MessageValues = Readonly<Record<string, string | number>>;
+/**
+ * A package-owned, complete bilingual catalog. No global language or registration.
+ * Placeholder substitution is one pass: user text cannot become another template.
+ * Values remain plain text; HTML/JSX escaping belongs to the existing renderer.
+ */
+export declare function createMessages<const T extends MessageCatalog>(catalog: T): (locale: Locale | undefined, key: keyof T & string, values?: MessageValues) => string;

package/lib/i18n.js

@@ -0,0 +1,38 @@
+import { createToken } from './token.js';
+export const DEFAULT_LOCALE = 'zh-CN';
+export const SUPPORTED_LOCALES = Object.freeze(['zh-CN', 'en']);
+export function isLocale(value) {
+    return value === 'zh-CN' || value === 'en';
+}
+/** Resolve an absent display preference; configuration writes validate with isLocale. */
+export function resolveLocale(value) {
+    return isLocale(value) ? value : DEFAULT_LOCALE;
+}
+/** Immutable project language, projected with the operation's generation. */
+export const projectLocaleToken = createToken('zhin.project-locale');
+export const userLocalePreferencesToken = createToken('zhin.user-locale-preferences');
+/**
+ * A package-owned, complete bilingual catalog. No global language or registration.
+ * Placeholder substitution is one pass: user text cannot become another template.
+ * Values remain plain text; HTML/JSX escaping belongs to the existing renderer.
+ */
+export function createMessages(catalog) {
+    const entries = Object.freeze(Object.fromEntries(Object.entries(catalog).map(([key, value]) => {
+        const keys = (text) => [...new Set([...text.matchAll(/\{([a-zA-Z][\w]*)\}/gu)].map(match => match[1]))].sort();
+        if (typeof value['zh-CN'] !== 'string' || typeof value.en !== 'string'
+            || JSON.stringify(keys(value['zh-CN'])) !== JSON.stringify(keys(value.en))) {
+            throw new TypeError(`Invalid bilingual message catalog entry: ${key}`);
+        }
+        return [key, Object.freeze({ ...value })];
+    })));
+    return (locale, key, values = {}) => {
+        const entry = entries[key];
+        if (!Object.hasOwn(entries, key) || !entry)
+            throw new TypeError(`Unknown message catalog entry: ${key}`);
+        return entry[resolveLocale(locale)].replace(/\{([a-zA-Z][\w]*)\}/gu, (_match, name) => {
+            if (!Object.hasOwn(values, name))
+                throw new TypeError(`Missing message value: ${name}`);
+            return String(values[name]);
+        });
+    };
+}

package/lib/index.d.ts

@@ -5,6 +5,10 @@
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
+/** @internal Shared accepted-owner frame; no additional admission or task registry. */
+export { OwnerOperation } from './owner-operation.js';
+/** @internal Runtime-owned delivery authority; author contexts expose subscriptions only. */
+export { createPluginEventChannel, type PluginEventChannel } from './plugin-events.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionBindable, type GenerationAdmissionSource, } from './admission.js';
 export * from './handoff.js';
@@ -12,6 +16,7 @@ export * from './handoff.js';
 export * from './plugin.js';
 /** @public Root configuration contract shared by Runtime and composition tooling. */
 export * from './plugin-configuration.js';
+export * from './i18n.js';
 export * from './root-config-file.js';
 export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
@@ -39,3 +44,6 @@ export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
 export * from './task-storage.js';
+export * from './plugin-console-rpc.js';
+export * from './data-migration.js';
+export * from './relational-target-migration.js';

package/lib/index.js

@@ -5,6 +5,10 @@
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';
+/** @internal Shared accepted-owner frame; no additional admission or task registry. */
+export { OwnerOperation } from './owner-operation.js';
+/** @internal Runtime-owned delivery authority; author contexts expose subscriptions only. */
+export { createPluginEventChannel } from './plugin-events.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, } from './admission.js';
 export * from './handoff.js';
@@ -12,6 +16,7 @@ export * from './handoff.js';
 export * from './plugin.js';
 /** @public Root configuration contract shared by Runtime and composition tooling. */
 export * from './plugin-configuration.js';
+export * from './i18n.js';
 export * from './root-config-file.js';
 export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
@@ -39,3 +44,6 @@ export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
 export * from './task-storage.js';
+export * from './plugin-console-rpc.js';
+export * from './data-migration.js';
+export * from './relational-target-migration.js';

package/lib/outbound-host.d.ts

@@ -1,5 +1,6 @@
 import type { DeliveryTarget } from './delivery-target.js';
 import type { PluginId } from './identity.js';
+import type { Locale } from './i18n.js';
 import { generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionGate } from './admission.js';
 /**
  * 未锚定 endpoint 的会话地址（结构对齐 `@zhin.js/im-contract` 的
@@ -21,28 +22,24 @@ export interface OutboundConversation {
  * `sendEndpointMessage` (resolve adapter/endpoint → AdapterIndex.send).
  */
 export interface OutboundSendInput {
+    /** Language captured by the originating operation or persisted task. */
+    readonly locale?: Locale;
     readonly adapter: string;
     readonly endpointKey: string;
     readonly conversation: OutboundConversation;
     readonly content: string;
 }
 export interface OutboundReactionInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
     readonly emoji: string;
     readonly sceneType?: string;
     readonly channelId?: string;
 }
 export interface OutboundRemoveReactionInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
     readonly reactionId: string;
 }
 export interface OutboundRecallInput {
-    readonly adapter: string;
-    readonly endpointKey: string;
     readonly message: OutboundMessage;
 }
 export type OutboundEndpointOperation = 'recall' | 'edit' | 'reaction' | 'typing';
@@ -53,11 +50,11 @@ export interface OutboundEndpointInput {
 export interface OutboundEndpointCapabilities {
     readonly operations: readonly OutboundEndpointOperation[];
 }
-export interface OutboundEditInput extends OutboundEndpointInput {
+export interface OutboundEditInput {
     readonly message: OutboundMessage;
     readonly content: unknown;
 }
-export interface OutboundTypingInput extends OutboundEndpointInput {
+export interface OutboundTypingInput {
     readonly conversation: OutboundMessage['conversation'];
     readonly active?: boolean;
 }
@@ -71,9 +68,38 @@ export interface OutboundMessage {
     }>;
     readonly id: string;
 }
+/** Retain a real source Client while its inbound operation is active. Never serialize this input. */
+export interface OutboundCaptureInput {
+    readonly target: DeliveryTarget;
+    readonly client: unknown;
+    readonly signal?: AbortSignal;
+}
+/** Messaging effects bound to one source incarnation, independent of reusable account names. */
+export interface CapturedOutboundOperation {
+    readonly target: DeliveryTarget;
+    readonly signal: AbortSignal;
+    send(content: unknown, options?: Readonly<{
+        locale?: Locale;
+        signal?: AbortSignal;
+    }>): Promise<string | null>;
+    recall?(message: OutboundMessage): Promise<void>;
+    edit?(message: OutboundMessage, content: unknown): Promise<string | null>;
+    addReaction?(message: OutboundMessage, emoji: string, hint?: Readonly<{
+        sceneType?: string;
+        channelId?: string;
+    }>): Promise<string | null>;
+    removeReaction?(message: OutboundMessage, reactionId: string): Promise<void>;
+    typing?(conversation: OutboundMessage['conversation'], active?: boolean): Promise<void>;
+    /** Release the captured source and Root leases on every completion path. */
+    release(): void;
+}
 export interface OutboundHost {
+    /** Creates source-bound effects; ordinary persisted sends continue using sendTarget. */
+    captureOperation?(input: OutboundCaptureInput): CapturedOutboundOperation;
     /** Sends to persisted exact identities, rejecting stale addresses instead of aliasing another bot. */
-    sendTarget?(target: DeliveryTarget, content: unknown): Promise<string | null>;
+    sendTarget?(target: DeliveryTarget, content: unknown, options?: Readonly<{
+        locale?: Locale;
+    }>): Promise<string | null>;
     /** Runs related operations against one IM Runtime snapshot captured at ingress. */
     runWithView?<T>(operation: () => Promise<T>): Promise<T>;
     /** Exact operations declared by one live Endpoint. */
@@ -94,12 +120,16 @@ export interface OutboundHost {
     typing?(input: OutboundTypingInput): Promise<void>;
 }
 /** Root-only process port: requester is supplied by the owner-bound facade. */
-export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget'> {
-    sendTarget?(target: DeliveryTarget, content: unknown, requester: PluginId): Promise<string | null>;
+export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget' | 'captureOperation'> {
+    captureOperation?(input: OutboundCaptureInput, requester: PluginId): CapturedOutboundOperation;
+    sendTarget?(target: DeliveryTarget, content: unknown, requester: PluginId, options?: Readonly<{
+        locale?: Locale;
+    }>): Promise<string | null>;
 }
 /** Preserve the sending plugin as requester, independent of the destination endpoint owner. */
 export declare class PluginOutboundHost implements OutboundHost {
     #private;
+    readonly captureOperation?: OutboundHost['captureOperation'];
     readonly sendTarget?: OutboundHost['sendTarget'];
     readonly runWithView?: OutboundHost['runWithView'];
     readonly capabilities?: OutboundHost['capabilities'];

package/lib/outbound-host.js

@@ -3,6 +3,7 @@ import { generationAdmissionBinder, generationAdmissionSource } from './admissio
 import { OwnerOperation } from './owner-operation.js';
 /** Preserve the sending plugin as requester, independent of the destination endpoint owner. */
 export class PluginOutboundHost {
+    captureOperation;
     sendTarget;
     runWithView;
     capabilities;
@@ -20,6 +21,8 @@ export class PluginOutboundHost {
         this.#host = host;
         this.#admission = admission;
         this.#operation = new OwnerOperation(admission, 'Outbound');
+        const captureOperation = host.captureOperation?.bind(host);
+        this.captureOperation = captureOperation ? input => this.#run(() => captureOperation(input, this.#owner)) : undefined;
         const sendTarget = host.sendTarget?.bind(host);
         const runWithView = host.runWithView?.bind(host);
         const capabilities = host.capabilities?.bind(host);
@@ -28,7 +31,9 @@ export class PluginOutboundHost {
         const recall = host.recall?.bind(host);
         const edit = host.edit?.bind(host);
         const typing = host.typing?.bind(host);
-        this.sendTarget = sendTarget ? async (target, content) => this.#run(() => sendTarget(target, content, this.#owner)) : undefined;
+        this.sendTarget = sendTarget ? async (target, content, options) => this.#run(() => options
+            ? sendTarget(target, content, this.#owner, options)
+            : sendTarget(target, content, this.#owner)) : undefined;
         this.runWithView = runWithView ? (operation) => this.#run(() => runWithView(operation)) : undefined;
         this.capabilities = capabilities ? (input) => this.#run(() => capabilities(input)) : undefined;
         this.addReaction = addReaction ? (input) => this.#run(() => addReaction(input)) : undefined;

package/lib/plugin-console-rpc.d.ts

@@ -0,0 +1,96 @@
+import { type GenerationAdmissionSource } from './admission.js';
+import type { PluginId, FeatureId } from './identity.js';
+import type { JsonValue } from './persistent-state.js';
+/**
+ * Plugin-registered Console RPC (zhinjs/zhin#970).
+ *
+ * A plugin publishes one {@link PluginConsoleRpc} through {@link pluginConsoleRpcToken}. The Host
+ * exposes it on the existing Console RPC envelope as `plugin.<pluginId>.status` and
+ * `plugin.<pluginId>.<action>`, where `<pluginId>` is the owner PluginId (for example
+ * `root/typesafe`). No WebSocket, no new HTTP route, and no generic config writes.
+ *
+ * Authorization follows the Console Page the method is bound to (`page`): the caller must
+ * satisfy that page's `requiredPermissions` / `requiredRoles`, plus the method's own. The full
+ * (admin) token may call everything. Other tokens (`user` / `demo`) may call a method when they
+ * hold every required permission and role. An action is open to them only when it declares its
+ * own `requiredPermissions` / `requiredRoles` / `anyOfPermissions` (the page's requirements apply on
+ * top, but never grant an action by themselves); an unguarded `status` needs `demo: true`.
+ * `anyOfPermissions` is satisfied by holding at least one of the listed permissions (for a new
+ * permission that coexists with an older one, e.g. `ops:approve` beside `tool_approvals:resolve`).
+ */
+export type PluginConsoleRpcJson = JsonValue;
+export type PluginConsoleRpcInput = Readonly<Record<string, JsonValue>>;
+export interface PluginConsoleRpcCall {
+    /** Aborted when the Host request times out. Long work must observe it. */
+    readonly signal: AbortSignal;
+    /** Authenticated operation view; no snapshot, configuration, resource or private resolver access. */
+    readonly runtime?: Readonly<{
+        owner: PluginId;
+        generation: number;
+        operator: boolean;
+        project(feature: FeatureId): unknown;
+    }>;
+    /** Framework-only request-local notification before a validated durable mutation begins. */
+    commitStarted?(): void;
+}
+export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput> {
+    /** Local name of a Page owned by the same plugin (`pages/<page>/index.tsx`). Its access rules apply. */
+    readonly page?: string;
+    /** Extra permissions on top of the page's own requirements. */
+    readonly requiredPermissions?: readonly string[];
+    /** Extra roles on top of the page's own requirements. */
+    readonly requiredRoles?: readonly string[];
+    /**
+     * The caller must also hold at least one of these (in addition to every `requiredPermissions`).
+     * Counts as the method's own requirement for actions.
+     */
+    readonly anyOfPermissions?: readonly string[];
+    /**
+     * Return a small, user-facing JSON shape. Never return raw log records, prompts, chat lines,
+     * secrets or exception text: the Console shows this to ordinary users.
+     */
+    handler(input: TInput, call: PluginConsoleRpcCall): JsonValue | Promise<JsonValue>;
+}
+export interface PluginConsoleRpcStatus extends PluginConsoleRpcMethod<PluginConsoleRpcInput> {
+    /** Allow the demo-scope Console token to read this status. Default `false`. */
+    readonly demo?: boolean;
+}
+export interface PluginConsoleRpcDefinition {
+    /** Read-only status for the plugin's Console page(s): `plugin.<pluginId>.status`. */
+    readonly status?: PluginConsoleRpcStatus;
+    /**
+     * Extra read-only views beside `status`: `plugin.<pluginId>.<name>`. Same access rules as
+     * `status`; use them when one plugin backs several pages with different permissions.
+     */
+    readonly queries?: Readonly<Record<string, PluginConsoleRpcStatus>>;
+    /**
+     * Limited, named actions: `plugin.<pluginId>.<name>`. Non-admin tokens may run one only when the
+     * action declares its own requirements and the token holds them (plus the page's); otherwise
+     * admin-only.
+     */
+    readonly actions?: Readonly<Record<string, PluginConsoleRpcMethod>>;
+}
+export interface NormalizedPluginConsoleRpcMethod {
+    readonly page?: string;
+    readonly requiredPermissions: readonly string[];
+    readonly requiredRoles: readonly string[];
+    /** Empty when the method has no either-of requirement. */
+    readonly anyOfPermissions: readonly string[];
+    readonly demo: boolean;
+    /** `status` and `queries` are read-only; actions are not. */
+    readonly readOnly: boolean;
+    readonly handler: PluginConsoleRpcMethod['handler'];
+}
+/** Value published under {@link pluginConsoleRpcToken}; create it with {@link definePluginConsoleRpc}. */
+export interface PluginConsoleRpc extends GenerationAdmissionSource {
+    readonly methods: ReadonlyMap<string, NormalizedPluginConsoleRpcMethod>;
+}
+/** Safe, user-facing failure. `message` is shown in the Console; never put raw errors in it. */
+export declare class PluginConsoleRpcError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable' | 'forbidden' | 'commit_unknown';
+    constructor(code: PluginConsoleRpcError['code'], message: string);
+}
+export declare const pluginConsoleRpcToken: import("./token.js").Token<PluginConsoleRpc>;
+export declare const PLUGIN_CONSOLE_RPC_STATUS = "status";
+/** Validates and freezes a plugin's Console RPC surface. Throws on invalid names at setup time. */
+export declare function definePluginConsoleRpc(definition: PluginConsoleRpcDefinition): PluginConsoleRpc;