@zhin.js/plugin-runtime 1.1.19 → 1.1.21

package/lib/config-update-declaration.d.ts

@@ -0,0 +1,5 @@
+export interface PluginConfigUpdateDeclaration {
+    readonly featurePaths: readonly (readonly string[])[];
+}
+/** @internal Normalize inert ownership metadata at authoring and snapshot boundaries. */
+export declare function freezePluginConfigUpdate(value: PluginConfigUpdateDeclaration): PluginConfigUpdateDeclaration;

package/lib/config-update-declaration.js

@@ -0,0 +1,15 @@
+/** @internal Normalize inert ownership metadata at authoring and snapshot boundaries. */
+export function freezePluginConfigUpdate(value) {
+    if (!value || typeof value !== 'object' || Object.keys(value).some(key => key !== 'featurePaths') || !Array.isArray(value.featurePaths)) {
+        throw new TypeError('Plugin configUpdate must declare featurePaths');
+    }
+    return Object.freeze({ featurePaths: Object.freeze(Array.from(value.featurePaths, (path) => {
+            if (!Array.isArray(path) || !path.length)
+                throw new TypeError('Plugin configUpdate paths must be safe nonempty paths');
+            const parts = Array.from(path);
+            if (parts.some(part => typeof part !== 'string' || !part || ['__proto__', 'prototype', 'constructor'].includes(part))) {
+                throw new TypeError('Plugin configUpdate paths must be safe nonempty paths');
+            }
+            return Object.freeze(parts);
+        })) });
+}

package/lib/outbound-host.d.ts

@@ -47,8 +47,29 @@ export interface OutboundEndpointInput {
     readonly adapter: string;
     readonly endpointKey: string;
 }
+/**
+ * Per-conversation-kind view of an Endpoint's capability profile (ADR 0044). Structurally the same as
+ * `EndpointKindCapabilities` in `@zhin.js/im-contract`; a missing kind or field means "not supported".
+ */
+export interface OutboundKindCapabilities {
+    readonly feedback?: Readonly<{
+        mode: 'typing' | 'reaction' | 'status-message' | 'none';
+        emoji?: string;
+        text?: string;
+        refreshSeconds?: number;
+    }>;
+    readonly reaction: boolean;
+    readonly edit: boolean;
+    readonly recall: boolean;
+    readonly spool: boolean;
+    /** Messages here must quote an inbound message. */
+    readonly needsReply: boolean;
+    readonly groupInfo: boolean;
+    readonly memberProfile: boolean;
+}
 export interface OutboundEndpointCapabilities {
     readonly operations: readonly OutboundEndpointOperation[];
+    readonly kinds?: Readonly<Partial<Record<'private' | 'group' | 'channel', OutboundKindCapabilities>>>;
 }
 export interface OutboundEditInput {
     readonly message: OutboundMessage;

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

@@ -20,9 +20,11 @@ import type { JsonValue } from './persistent-state.js';
  */
 export type PluginConsoleRpcJson = JsonValue;
 export type PluginConsoleRpcInput = Readonly<Record<string, JsonValue>>;
-export interface PluginConsoleRpcCall {
+export interface PluginConsoleRpcCall<TConfig = Record<string, unknown>> {
     /** Aborted when the Host request times out. Long work must observe it. */
     readonly signal: AbortSignal;
+    /** Validated plugin configuration for this generation, when available. */
+    readonly config?: TConfig;
     /** Authenticated operation view; no snapshot, configuration, resource or private resolver access. */
     readonly runtime?: Readonly<{
         owner: PluginId;
@@ -33,7 +35,10 @@ export interface PluginConsoleRpcCall {
     /** Framework-only request-local notification before a validated durable mutation begins. */
     commitStarted?(): void;
 }
-export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput> {
+export type PluginConsoleRpcCallContext<TMethods = Record<string, unknown>, TKey extends keyof TMethods = keyof TMethods, TConfig = Record<string, unknown>> = PluginConsoleRpcCall<TConfig> & {
+    readonly method?: TKey;
+};
+export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput, TConfig = Record<string, unknown>> {
     /** 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. */
@@ -49,26 +54,29 @@ export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput> {
      * 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>;
+    handler(input: TInput, call: PluginConsoleRpcCall<TConfig>): JsonValue | Promise<JsonValue>;
 }
-export interface PluginConsoleRpcStatus extends PluginConsoleRpcMethod<PluginConsoleRpcInput> {
+export interface PluginConsoleRpcStatus<TConfig = Record<string, unknown>> extends PluginConsoleRpcMethod<PluginConsoleRpcInput, TConfig> {
     /** Allow the demo-scope Console token to read this status. Default `false`. */
     readonly demo?: boolean;
 }
-export interface PluginConsoleRpcDefinition {
+export interface PluginConsoleRpcDefinition<TConfig = Record<string, unknown>> {
     /** Read-only status for the plugin's Console page(s): `plugin.<pluginId>.status`. */
-    readonly status?: PluginConsoleRpcStatus;
+    readonly status?: PluginConsoleRpcStatus<TConfig>;
     /**
      * 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>>;
+    readonly queries?: Readonly<Record<string, PluginConsoleRpcStatus<TConfig>>>;
     /**
      * 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>>;
+    readonly actions?: Readonly<Record<string, PluginConsoleRpcMethod<PluginConsoleRpcInput, TConfig>>>;
+}
+export interface PluginConsoleRpcDefiner<TConfig = Record<string, unknown>> {
+    (definition: PluginConsoleRpcDefinition<TConfig>): PluginConsoleRpc;
 }
 export interface NormalizedPluginConsoleRpcMethod {
     readonly page?: string;
@@ -93,4 +101,7 @@ export declare class PluginConsoleRpcError extends Error {
 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;
+export declare function definePluginConsoleRpc<TConfig = Record<string, unknown>>(definition: PluginConsoleRpcDefinition<TConfig>): PluginConsoleRpc;
+export declare namespace definePluginConsoleRpc {
+    var withConfig: <TConfig = Record<string, unknown>>() => PluginConsoleRpcDefiner<TConfig>;
+}

package/lib/plugin-console-rpc.js

@@ -42,6 +42,13 @@ export function definePluginConsoleRpc(definition) {
         get [generationAdmissionSource]() { return gates; },
     });
 }
+/**
+ * Fix the plugin config type first, then define the Console RPC surface:
+ * `definePluginConsoleRpc.withConfig<MyConfig>()({ status: { handler(_input, call) { ... } } })`
+ */
+definePluginConsoleRpc.withConfig = function withConfig() {
+    return (definition) => definePluginConsoleRpc(definition);
+};
 function normalizeMethod(name, method, demo, readOnly) {
     if (!method || typeof method.handler !== 'function') {
         throw new TypeError(`Plugin Console RPC ${name} must have a handler`);

package/lib/plugin.d.ts

@@ -7,6 +7,9 @@ import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
 import type { PluginEventSubscriptions } from './plugin-events.js';
+import { type PluginConfigUpdateDeclaration } from './config-update-declaration.js';
+export { freezePluginConfigUpdate } from './config-update-declaration.js';
+export type { PluginConfigUpdateDeclaration } from './config-update-declaration.js';
 export interface PluginMetadata {
     readonly displayName?: string;
     readonly icon?: string;
@@ -48,6 +51,8 @@ export interface PluginDefinition<TConfig = unknown> {
     readonly config?: PluginConfigSchema<TConfig>;
     readonly metadata?: PluginMetadata;
     readonly requires?: readonly Token<unknown>[];
+    /** Fields owned by Features; setup must not capture these as mutable business configuration. */
+    readonly configUpdate?: PluginConfigUpdateDeclaration;
     setup?(context: PluginSetupContext<TConfig>): void | Dispose | Promise<void | Dispose>;
 }
 /**

package/lib/plugin.js

@@ -1,3 +1,5 @@
+import { freezePluginConfigUpdate } from './config-update-declaration.js';
+export { freezePluginConfigUpdate } from './config-update-declaration.js';
 const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
 /**
  * Define the canonical `plugin.ts` entry point.
@@ -28,6 +30,7 @@ export function definePlugin(definition) {
         ...definition,
         metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : undefined,
         requires: Object.freeze([...(definition.requires ?? [])]),
+        ...(definition.configUpdate !== undefined ? { configUpdate: freezePluginConfigUpdate(definition.configUpdate) } : {}),
     });
 }
 // The application facade exposes these Host contracts beside definePlugin.

package/lib/snapshot.d.ts

@@ -4,6 +4,7 @@ import type { Dispose } from './dispose.js';
 import type { GenerationHandoff } from './handoff.js';
 import type { CapabilityId, FeatureId, PluginId, TokenId } from './identity.js';
 import type { PluginMetadata } from './plugin.js';
+import { type PluginConfigUpdateDeclaration } from './config-update-declaration.js';
 export interface PluginNodeSnapshot {
     readonly id: PluginId;
     readonly instanceKey: string;
@@ -16,6 +17,7 @@ export interface PluginNodeSnapshot {
     readonly metadata?: PluginMetadata;
     /** Immutable schema declaration belonging to this committed generation. */
     readonly configSchema?: Readonly<Record<string, unknown>>;
+    readonly configUpdate?: PluginConfigUpdateDeclaration;
 }
 export interface RuntimeSnapshot {
     readonly generation: number;

package/lib/snapshot.js

@@ -1,4 +1,5 @@
 import { collectGenerationAdmissions, replaceGenerationAdmissions, } from './admission.js';
+import { freezePluginConfigUpdate } from './config-update-declaration.js';
 export class GenerationConflictError extends Error {
     expected;
     actual;
@@ -214,8 +215,9 @@ export function createSnapshotView(generation, state) {
     return Object.freeze({
         ...state,
         generation,
-        tree: readonlyMap([...state.tree].map(([owner, node]) => [owner, node.configSchema
-                ? Object.freeze({ ...node, configSchema: freezeSchema(structuredClone(node.configSchema)) })
+        tree: readonlyMap([...state.tree].map(([owner, node]) => [owner, node.configSchema || node.configUpdate
+                ? Object.freeze({ ...node, ...(node.configSchema ? { configSchema: freezeSchema(structuredClone(node.configSchema)) } : {}),
+                    ...(node.configUpdate ? { configUpdate: freezePluginConfigUpdate(node.configUpdate) } : {}) })
                 : node])),
         config: readonlyMap(state.config),
         resources: readonlyMap([...state.resources].map(([owner, resources]) => [owner, readonlyMap(resources)])),

package/lib/token.d.ts

@@ -7,6 +7,8 @@ export interface Token<T> {
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
 export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
+/** @internal Verify token identity before accepting a generation-private binding. */
+export declare function isRootPrivateToken(token: Token<unknown>): boolean;
 /** A Root-private capability readable only while projecting its owning Feature. */
 export declare function createFeaturePrivateToken<T>(id: string, feature: FeatureId, description?: string): Token<T>;
 /** @internal The actual candidate Root Scope never enters the Feature context. */

package/lib/token.js

@@ -10,6 +10,8 @@ export function createRootPrivateToken(id, description) {
     rootPrivateTokens.add(token);
     return Object.freeze(token);
 }
+/** @internal Verify token identity before accepting a generation-private binding. */
+export function isRootPrivateToken(token) { return rootPrivateTokens.has(token); }
 /** A Root-private capability readable only while projecting its owning Feature. */
 export function createFeaturePrivateToken(id, feature, description) {
     const token = createRootPrivateToken(id, description);

package/package.json

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