@zhin.js/runtime 1.1.5 → 1.1.7

package/lib/config-composer.d.ts

@@ -1,5 +1,7 @@
 import type { RuntimeConfigDocument, PluginId } from '@zhin.js/plugin-runtime';
+import { type ErrorObject } from 'ajv/dist/2020.js';
 import type { ProjectGraph } from './project-graph.js';
+import type { ModuleRuntime } from './module-runtime.js';
 export declare const HOST_CONFIG_SCHEMA: {
     $schema: string;
     type: string;
@@ -204,6 +206,20 @@ export declare const HOST_CONFIG_SCHEMA: {
                                     description: string;
                                     "x-descriptionZh": string;
                                 };
+                                ttlMs: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxQueuedTurns: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
                             };
                         };
                         execSecurity: {
@@ -218,25 +234,224 @@ export declare const HOST_CONFIG_SCHEMA: {
                             description: string;
                             "x-descriptionZh": string;
                         };
-                        execApprovalMode: {
+                        network: {
+                            type: string;
+                            additionalProperties: boolean;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                enabled: {
+                                    type: string;
+                                    default: boolean;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                allowedDomains: {
+                                    type: string;
+                                    items: {
+                                        type: string;
+                                    };
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                            };
+                        };
+                        masterShell: {
                             type: string;
                             enum: string[];
+                            default: string;
                             description: string;
                             "x-descriptionZh": string;
                         };
-                        subagentExecApprovalMode: {
+                        toolBudget: {
+                            type: string;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                extendBy: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                progressWindow: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxTotalIterations: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxSubagentTotalIterations: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxWallClockMs: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxTotalTokens: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                failureStreakLimit: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                repeatLimit: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                autoContinue: {
+                                    type: string;
+                                    enum: string[];
+                                    default: string;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                maxContinuations: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                progressUpdates: {
+                                    type: string;
+                                    enum: string[];
+                                    default: string;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                progressMinIntervalMs: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                progressMaxUpdates: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                            };
+                        };
+                        injectionGuard: {
+                            type: string;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                confirmHighRisk: {
+                                    type: string;
+                                    enum: string[];
+                                    default: string;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                outboundCheck: {
+                                    type: string;
+                                    enum: string[];
+                                    default: string;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                trustedOutputTools: {
+                                    type: string;
+                                    items: {
+                                        type: string;
+                                    };
+                                    default: never[];
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                            };
+                        };
+                        usageQuota: {
+                            type: string;
+                            description: string;
+                            "x-descriptionZh": string;
+                            properties: {
+                                windowMs: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                perUserTokens: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                perGroupTokens: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                perGroupRequestsPerMinute: {
+                                    type: string;
+                                    minimum: number;
+                                    default: number;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                                exemptOwner: {
+                                    type: string;
+                                    default: boolean;
+                                    description: string;
+                                    "x-descriptionZh": string;
+                                };
+                            };
+                        };
+                        subagentTurnMode: {
                             type: string;
                             enum: string[];
+                            default: string;
                             description: string;
                             "x-descriptionZh": string;
                         };
-                        workerExecApprovalMode: {
+                        execApprovalMode: {
                             type: string;
                             enum: string[];
                             description: string;
                             "x-descriptionZh": string;
                         };
-                        taskExecApprovalMode: {
+                        subagentExecApprovalMode: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                            "x-descriptionZh": string;
+                        };
+                        workerExecApprovalMode: {
                             type: string;
                             enum: string[];
                             description: string;
@@ -639,6 +854,7 @@ export interface ComposedConfig {
     readonly effectiveSchema: JsonSchema;
     readonly document: RuntimeConfigDocument;
     readonly views: ReadonlyMap<PluginId, unknown>;
+    readonly ownSchemas: ReadonlyMap<PluginId, JsonSchema>;
 }
 export declare class ConfigSchemaCollisionError extends Error {
     readonly plugin: PluginId;
@@ -655,8 +871,15 @@ export declare class ConfigValidationError extends Error {
 }
 export declare class ConfigComposer {
     private readonly inactivePluginInstanceKeys;
-    constructor(inactivePluginInstanceKeys?: readonly string[]);
+    private readonly modules?;
+    constructor(inactivePluginInstanceKeys?: readonly string[], modules?: Pick<ModuleRuntime, "load"> | undefined);
     compose(graph: ProjectGraph, input?: RuntimeConfigDocument, 
     /** Source config file name, annotated on ConfigValidationError. */
     source?: string): Promise<ComposedConfig>;
 }
+/** Reuses Runtime validation/defaults without mutating the caller's configuration. */
+export declare function parsePluginConfigSchema(schema: JsonSchema, input: unknown): Readonly<{
+    value: unknown;
+    errors: readonly ErrorObject[];
+}>;
+export declare function validatePluginConfigSchema(schema: JsonSchema, input: unknown): readonly ErrorObject[];

package/lib/config-composer.js

@@ -1,7 +1,6 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
 import hostConfigSchema from './host-config-schema.json' with { type: 'json' };
+import { readPluginConfigSchema } from './plugin-config-schema.js';
 function deepFreeze(value) {
     if (value && typeof value === 'object' && !Object.isFrozen(value)) {
         for (const nested of Object.values(value))
@@ -37,8 +36,10 @@ export class ConfigValidationError extends Error {
 }
 export class ConfigComposer {
     inactivePluginInstanceKeys;
-    constructor(inactivePluginInstanceKeys = []) {
+    modules;
+    constructor(inactivePluginInstanceKeys = [], modules) {
         this.inactivePluginInstanceKeys = inactivePluginInstanceKeys;
+        this.modules = modules;
     }
     async compose(graph, input = {}, 
     /** Source config file name, annotated on ConfigValidationError. */
@@ -46,11 +47,11 @@ export class ConfigComposer {
         // Effective schemas include child namespaces for whole-tree validation;
         // ownSchemas retain each package's private configuration contract.
         const ownSchemas = new Map();
-        const rootOwn = await readOwnSchema(graph.root);
+        const rootOwn = await readOwnSchema(graph.root, this.modules);
         ownSchemas.set(graph.root.id, rootOwn);
         const childSchemas = await Promise.all(graph.root.children.map(async (child) => [
             child.instanceKey,
-            await composeNode(child, ownSchemas),
+            await composeNode(child, ownSchemas, this.modules),
         ]));
         // Host-level keys (`http`, `database`, `ai`, `mcp`, `a2a`, `speech`,
         // `htmlRenderer`, `assistant`, `log_level`) are consumed by CLI Root installers /
@@ -74,17 +75,7 @@ export class ConfigComposer {
             },
         });
         const document = structuredClone(input);
-        const ajv = new Ajv2020({
-            allErrors: true,
-            useDefaults: true,
-            strict: true,
-            // 当前内置 schema 无需 union（log_level 的 ['string','number'] 是 type 数组，
-            // 不触发 allowUnionTypes）；保留此项是面向未来插件 schema 可能出现的
-            // anyOf/oneOf 标量 union，避免届时 Ajv strict 模式直接报错。
-            allowUnionTypes: true,
-        });
-        ajv.addKeyword({ keyword: 'x-descriptionZh', schemaType: 'string' });
-        ajv.addKeyword({ keyword: 'x-keyPlaceholder', schemaType: 'string' });
+        const ajv = configurationValidator();
         const validate = ajv.compile(effectiveSchema);
         if (!validate(document)) {
             throw new ConfigValidationError(formatErrors(validate.errors ?? []), source);
@@ -98,6 +89,7 @@ export class ConfigComposer {
             effectiveSchema,
             document: Object.freeze(document),
             views,
+            ownSchemas,
         });
     }
 }
@@ -153,8 +145,8 @@ function injectFrameworkRoleSchema(properties) {
         }),
     });
 }
-async function composeNode(node, ownSchemas) {
-    const own = await readOwnSchema(node);
+async function composeNode(node, ownSchemas, modules) {
+    const own = await readOwnSchema(node, modules);
     ownSchemas.set(node.id, own);
     const properties = { ...schemaProperties(own) };
     // Adapter plugins (schemas declaring array-typed `endpoints`) get
@@ -167,24 +159,14 @@ async function composeNode(node, ownSchemas) {
         if (Object.hasOwn(properties, child.instanceKey)) {
             throw new ConfigSchemaCollisionError(node.id, child.instanceKey);
         }
-        properties[child.instanceKey] = withDefault(await composeNode(child, ownSchemas));
+        properties[child.instanceKey] = withDefault(await composeNode(child, ownSchemas, modules));
     }
     return Object.freeze({ ...own, properties });
 }
-async function readOwnSchema(node) {
-    const file = join(node.package.root, 'schema.json');
-    let value;
-    try {
-        value = JSON.parse(await readFile(file, 'utf8'));
-    }
-    catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-            value = { type: 'object', additionalProperties: false, properties: {} };
-        }
-        else {
-            throw error;
-        }
-    }
+async function readOwnSchema(node, modules) {
+    const file = `${node.package.name} config`;
+    const value = await readPluginConfigSchema(node.package, modules)
+        ?? { type: 'object', additionalProperties: false, properties: {} };
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new TypeError(`${file} must contain a JSON Schema object`);
     }
@@ -204,7 +186,7 @@ async function readOwnSchema(node) {
     if (Object.hasOwn(properties, 'commandNamespace')) {
         throw new ConfigSchemaCollisionError(node.id, 'commandNamespace');
     }
-    return Object.freeze({
+    return deepFreeze({
         $id: `urn:zhin:plugin-config:${encodeURIComponent(String(node.id))}`,
         type: 'object',
         additionalProperties: false,
@@ -275,3 +257,32 @@ function formatErrors(errors) {
         return base;
     });
 }
+/** Reuses Runtime validation/defaults without mutating the caller's configuration. */
+export function parsePluginConfigSchema(schema, input) {
+    const validate = configurationValidator().compile({
+        type: 'object',
+        ...(schema.$defs ? { $defs: schema.$defs } : {}),
+        properties: { candidate: schema },
+    });
+    const candidate = { candidate: structuredClone(input === undefined ? schema.default ?? {} : input) };
+    const valid = validate(candidate);
+    return Object.freeze({ value: candidate.candidate, errors: valid ? [] : structuredClone(validate.errors ?? []) });
+}
+export function validatePluginConfigSchema(schema, input) {
+    return parsePluginConfigSchema(schema, input).errors;
+}
+function configurationValidator() {
+    const ajv = new Ajv2020({
+        allErrors: true,
+        useDefaults: true,
+        strict: true,
+        // 当前内置 schema 无需 union（log_level 的 ['string','number'] 是 type 数组，
+        // 不触发 allowUnionTypes）；保留此项是面向未来插件 schema 可能出现的
+        // anyOf/oneOf 标量 union，避免届时 Ajv strict 模式直接报错。
+        allowUnionTypes: true,
+    });
+    ajv.addKeyword({ keyword: 'x-descriptionZh', schemaType: 'string' });
+    ajv.addKeyword({ keyword: 'x-keyPlaceholder', schemaType: 'string' });
+    ajv.addKeyword({ keyword: 'x-zhin-config', schemaType: 'object' });
+    return ajv;
+}

package/lib/generation-assets.d.ts

@@ -4,6 +4,6 @@ export declare class GenerationAssets {
     private constructor();
     static create(scopeDisposers: Iterable<readonly [PluginId, Dispose]>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
     replaceProjections(features: Iterable<FeatureId>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
-    replaceScopes(scopeOrder: readonly PluginId[], replacements: ReadonlyMap<PluginId, Dispose>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
+    replaceScopes(scopeOrder: readonly PluginId[], replacements: ReadonlyMap<PluginId, Dispose>, projectedFeatures: Iterable<FeatureId>, projectionDisposers: ReadonlyMap<FeatureId, Dispose>): GenerationAssets;
     dispose(): Promise<void>;
 }

package/lib/generation-assets.js

@@ -48,7 +48,7 @@ export class GenerationAssets {
         }
         return new GenerationAssets([...this.#scopeLifetimes.keys()], this.#scopeLifetimes, lifetimes);
     }
-    replaceScopes(scopeOrder, replacements, projectionDisposers) {
+    replaceScopes(scopeOrder, replacements, projectedFeatures, projectionDisposers) {
         const owners = new Set(scopeOrder);
         for (const owner of replacements.keys()) {
             if (!owners.has(owner))
@@ -64,10 +64,14 @@ export class GenerationAssets {
                 throw new Error(`Cannot retain unknown Plugin Scope: ${owner}`);
             lifetimes.set(owner, lifetime);
         }
-        const projectionLifetimes = new Map([...projectionDisposers].map(([feature, dispose]) => [
-            feature,
-            new SharedLifetime(dispose),
-        ]));
+        const projectionLifetimes = new Map(this.#projectionLifetimes);
+        for (const feature of projectedFeatures) {
+            const dispose = projectionDisposers.get(feature);
+            if (dispose)
+                projectionLifetimes.set(feature, new SharedLifetime(dispose));
+            else
+                projectionLifetimes.delete(feature);
+        }
         return new GenerationAssets(scopeOrder, lifetimes, projectionLifetimes);
     }
     dispose() {

package/lib/host-config-schema.json

@@ -121,8 +121,22 @@
                                 "groupMode": {
                                     "type": "string",
                                     "enum": ["supersede", "fifo"],
-                                    "description": "Replace an older queued group turn, or process all turns in arrival order.",
-                                    "x-descriptionZh": "覆盖较早的群聊排队回合，或按到达顺序处理全部回合。"
+                                    "description": "supersede (default): a sender's new message replaces their own unanswered turn; fifo: every message waits in arrival order. Other members' messages always queue.",
+                                    "x-descriptionZh": "supersede（默认）：同一发起人的新消息会替换他自己尚未回复的回合；fifo：全部按到达顺序排队。其他成员的消息总是排队。"
+                                },
+                                "ttlMs": {
+                                    "type": "integer",
+                                    "minimum": 0,
+                                    "default": 180000,
+                                    "description": "A queued turn that waited longer than this is dropped with a short notice. 0 disables expiry.",
+                                    "x-descriptionZh": "排队超过该时长的回合会被丢弃并简短提示；0 表示不过期。"
+                                },
+                                "maxQueuedTurns": {
+                                    "type": "integer",
+                                    "minimum": 0,
+                                    "default": 5,
+                                    "description": "Turns allowed to wait behind the running turn of one conversation; further messages get a short busy reply.",
+                                    "x-descriptionZh": "同一会话中允许排在当前回合之后的回合数；超出时回复一句“正在忙”。"
                                 }
                             }
                         },
@@ -138,10 +152,85 @@
                             "description": "Command allowlist preset used outside full mode.",
                             "x-descriptionZh": "非 full 模式使用的命令白名单预设。"
                         },
+                        "network": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "description": "Network access for IM turns (web_fetch / web_search and networked commands). Off by default; enabled allows HTTPS egress, optionally limited to allowedDomains. When enabled is unset, execPreset: network still enables it for compatibility.",
+                            "x-descriptionZh": "IM 回合的出网权限（web_fetch / web_search 与联网命令）。默认关闭；enabled 开启 HTTPS 出网，allowedDomains 非空时只允许这些域名。未设置 enabled 时兼容旧配置：execPreset: network 视为开启。",
+                            "properties": {
+                                "enabled": {
+                                    "type": "boolean",
+                                    "default": false,
+                                    "description": "Allow HTTPS egress for IM turns.",
+                                    "x-descriptionZh": "是否允许 IM 回合 HTTPS 出网。"
+                                },
+                                "allowedDomains": {
+                                    "type": "array",
+                                    "items": { "type": "string" },
+                                    "description": "When non-empty, only these domains (and their subdomains) are reachable.",
+                                    "x-descriptionZh": "非空时只允许访问这些域名（含子域名）。"
+                                }
+                            }
+                        },
+                        "masterShell": {
+                            "type": "string",
+                            "enum": ["off", "isolated"],
+                            "default": "off",
+                            "description": "Shell access for the master in IM private chats. off: no bash in IM turns. isolated: master DMs run bash inside a Docker container (workspace writable, no network, development allowlist, approval for anything else); fails closed when Docker is unavailable.",
+                            "x-descriptionZh": "IM 私聊中 master 的 Shell 权限。off：IM 会话不提供 bash；isolated：master 私聊在 Docker 容器内执行 bash（工作区可写、无网络、development 白名单、其余命令需审批），宿主无 Docker 时直接失败。"
+                        },
+                        "toolBudget": {
+                            "type": "object",
+                            "description": "Progress-aware tool-call budget. maxIterations is a soft budget extended while the turn makes progress; hard caps always apply.",
+                            "x-descriptionZh": "进度感知的工具调用预算。maxIterations 为软上限，回合有进展时自动延长；硬上限始终生效。",
+                            "properties": {
+                                "extendBy": { "type": "integer", "minimum": 0, "default": 10, "description": "Steps added per extension when progressing; 0 disables.", "x-descriptionZh": "有进展时每次延长的步数；0 关闭。" },
+                                "progressWindow": { "type": "integer", "minimum": 0, "default": 5, "description": "Progress must have happened within this many recent steps.", "x-descriptionZh": "最近多少步内有进展才延长。" },
+                                "maxTotalIterations": { "type": "integer", "minimum": 0, "default": 40, "description": "Hard step cap per turn segment.", "x-descriptionZh": "每段回合的硬步数上限。" },
+                                "maxSubagentTotalIterations": { "type": "integer", "minimum": 0, "default": 30, "description": "Hard step cap for an in-turn sub-agent.", "x-descriptionZh": "回合内子 Agent 的硬步数上限。" },
+                                "maxWallClockMs": { "type": "integer", "minimum": 0, "default": 600000, "description": "Wall-clock cap for the whole turn in ms; 0 disables.", "x-descriptionZh": "整个回合的时间上限（毫秒）；0 关闭。" },
+                                "maxTotalTokens": { "type": "integer", "minimum": 0, "default": 0, "description": "Token cap for the whole turn; 0 disables.", "x-descriptionZh": "整个回合的 Token 上限；0 关闭。" },
+                                "failureStreakLimit": { "type": "integer", "minimum": 0, "default": 3, "description": "Consecutive tool failures that stop extensions.", "x-descriptionZh": "连续失败多少次后不再延长。" },
+                                "repeatLimit": { "type": "integer", "minimum": 0, "default": 2, "description": "Consecutive identical repeated calls that stop extensions.", "x-descriptionZh": "连续重复相同调用多少次后不再延长。" },
+                                "autoContinue": { "type": "string", "enum": ["off", "master_dm", "on"], "default": "master_dm", "description": "Auto-continue a progressing turn that hit its budget: off, only in the master's private chat, or always. Continuations reuse the same turn (same policy and approvals).", "x-descriptionZh": "回合有进展但预算用尽时自动续跑：off 关闭；master_dm 仅主人私聊；on 总是。续跑沿用同一回合的策略与审批。" },
+                                "maxContinuations": { "type": "integer", "minimum": 0, "default": 2, "description": "Maximum automatic continuations per turn.", "x-descriptionZh": "每回合最多自动续跑次数。" },
+                                "progressUpdates": { "type": "string", "enum": ["off", "private", "all"], "default": "private", "description": "Brief natural-language progress updates during long turns: off, private chats only, or all chats (groups opt in).", "x-descriptionZh": "长回合中的简短进度更新：off 关闭；private 仅私聊；all 包括群聊（群聊需显式开启）。" },
+                                "progressMinIntervalMs": { "type": "integer", "minimum": 0, "default": 45000, "description": "Minimum time between progress updates in ms.", "x-descriptionZh": "两次进度更新的最小间隔（毫秒）。" },
+                                "progressMaxUpdates": { "type": "integer", "minimum": 0, "default": 3, "description": "Maximum progress updates per turn; 0 disables.", "x-descriptionZh": "每回合最多进度更新次数；0 关闭。" }
+                            }
+                        },
+                        "injectionGuard": {
+                            "type": "object",
+                            "description": "Prompt-injection defences. After lower-trust content (tool results, web pages, files, sub-agent reports, background messages) enters a turn, high-risk actions (shell, messaging other conversations, config changes, scheduling) need approval; replies are checked for system-prompt, secret and other-session memory leaks.",
+                            "x-descriptionZh": "注入防护。外部内容（工具结果、网页、文件、子 agent 报告、群聊背景消息）进入回合后，高危动作（执行命令、向其他会话发消息、改配置、定时任务）必须审批；出站回复检查系统提示、密钥与其他会话记忆泄露。",
+                            "properties": {
+                                "confirmHighRisk": { "type": "string", "enum": ["external_content", "off"], "default": "external_content", "description": "external_content: high-risk actions after external content always ask for approval (denied in unattended turns). off: disabled.", "x-descriptionZh": "external_content：读取外部内容后的高危动作一律审批（无人值守回合直接拒绝）；off：关闭。" },
+                                "outboundCheck": { "type": "string", "enum": ["redact", "off"], "default": "redact", "description": "redact: mask leaked system-prompt lines, secrets and other sessions' memory in replies and outbound tool messages. off: disabled.", "x-descriptionZh": "redact：在回复和外发工具消息中屏蔽泄露的系统提示、密钥和其他会话记忆；off：关闭。" },
+                                "trustedOutputTools": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tools whose results do not count as external content.", "x-descriptionZh": "结果不算外部内容的工具。" }
+                            }
+                        },
+                        "usageQuota": {
+                            "type": "object",
+                            "description": "Per-user and per-group token quotas and a per-group rate limit. All limits are off (0) by default; the owner is exempt by default. Counters are kept in memory.",
+                            "x-descriptionZh": "按用户 / 按群的 token 配额与群速率限制。默认全部关闭（0），主人默认不受限；计数保存在内存中。",
+                            "properties": {
+                                "windowMs": { "type": "integer", "minimum": 60000, "default": 86400000, "description": "Quota window in ms.", "x-descriptionZh": "配额周期（毫秒）。" },
+                                "perUserTokens": { "type": "integer", "minimum": 0, "default": 0, "description": "Tokens one user may use per window; 0 = unlimited.", "x-descriptionZh": "每个用户每周期可用的 token；0 不限。" },
+                                "perGroupTokens": { "type": "integer", "minimum": 0, "default": 0, "description": "Tokens one group may use per window; 0 = unlimited.", "x-descriptionZh": "每个群每周期可用的 token；0 不限。" },
+                                "perGroupRequestsPerMinute": { "type": "integer", "minimum": 0, "default": 0, "description": "Turns one group may start per minute; 0 = unlimited.", "x-descriptionZh": "每个群每分钟可发起的回合数；0 不限。" },
+                                "exemptOwner": { "type": "boolean", "default": true, "description": "The owner is never limited.", "x-descriptionZh": "主人不受限制。" }
+                            }
+                        },
+                        "subagentTurnMode": {
+                            "type": "string",
+                            "enum": ["off", "sync"],
+                            "default": "off",
+                            "description": "Sub-agents in IM turns. off: no spawn_task. sync: spawn_task runs a sub-agent inside the current turn with at most the parent's permissions (never wider; no bash unless the parent could run it) and approvals routed to the same conversation.",
+                            "x-descriptionZh": "IM 回合中的子 Agent。off：不提供 spawn_task；sync：spawn_task 在当前回合内同步运行子 Agent，权限不超过父回合（父回合不能运行 bash 时子 Agent 也没有），审批发往同一会话。"
+                        },
                         "execApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for main Agent commands.", "x-descriptionZh": "主 Agent 命令的审批策略。" },
                         "subagentExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for sub-Agent commands.", "x-descriptionZh": "子 Agent 命令的审批策略。" },
                         "workerExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for worker commands.", "x-descriptionZh": "Worker 命令的审批策略。" },
-                        "taskExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for task commands.", "x-descriptionZh": "Task 命令的审批策略。" },
                         "toolExecution": {
                             "type": "string",
                             "enum": ["parallel", "sequential", "tiered"],

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';
 export * from './environment.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';
 export * from './environment.js';

package/lib/missing-tool-package.d.ts

@@ -0,0 +1,5 @@
+export declare const TOOL_PACKAGE_INSTALL_HINT = "\u7F3A\u5C11\u4F9D\u8D56 @zhin.js/tool\uFF08tools/ \u4E0B\u7684 defineAgentTool \u9700\u8981\u5B83\uFF09\u3002\u8BF7\u8FD0\u884C: pnpm add @zhin.js/tool";
+/** True only for ERR_MODULE_NOT_FOUND naming the `@zhin.js/tool` package root. */
+export declare function isToolPackageMissing(error: unknown): boolean;
+/** Return an error that carries the exact install command when `@zhin.js/tool` is missing. */
+export declare function withToolPackageInstallHint(error: unknown): unknown;

package/lib/missing-tool-package.js

@@ -0,0 +1,21 @@
+const TOOL_PACKAGE = '@zhin.js/tool';
+const TOOL_ROOT_SPECIFIER = /['"]@zhin\.js\/tool['"]/u;
+export const TOOL_PACKAGE_INSTALL_HINT = `缺少依赖 ${TOOL_PACKAGE}（tools/ 下的 defineAgentTool 需要它）。请运行: pnpm add ${TOOL_PACKAGE}`;
+/** True only for ERR_MODULE_NOT_FOUND naming the `@zhin.js/tool` package root. */
+export function isToolPackageMissing(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const { code, message } = error;
+    return code === 'ERR_MODULE_NOT_FOUND'
+        && typeof message === 'string'
+        && TOOL_ROOT_SPECIFIER.test(message);
+}
+/** Return an error that carries the exact install command when `@zhin.js/tool` is missing. */
+export function withToolPackageInstallHint(error) {
+    if (!isToolPackageMissing(error))
+        return error;
+    const original = error;
+    const augmented = new Error(`${TOOL_PACKAGE_INSTALL_HINT}\n原始错误: ${original.message}`, { cause: error });
+    augmented.code = original.code;
+    return augmented;
+}

package/lib/native-development-runtime.js

@@ -3,6 +3,7 @@ import { readdirSync, statSync, watch as watchDirectory, } from 'node:fs';
 import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { ModuleDependencyIndex, } from './module-dependency-index.js';
+import { withToolPackageInstallHint } from './missing-tool-package.js';
 import { ensureTypeScriptSpecifierRemap } from './typescript-specifier-remap.js';
 const ignoredDirectories = new Set([
     '.git', '.zhin', 'coverage', 'data', 'dist', 'lib', 'node_modules',
@@ -27,6 +28,7 @@ export class NativeDevelopmentModuleRuntime {
     #pendingDependencies;
     #watchRoots;
     #revision = 0;
+    #entryRevisions = new Map();
     #closed = false;
     constructor(options) {
         ensureTypeScriptSpecifierRemap();
@@ -43,16 +45,23 @@ export class NativeDevelopmentModuleRuntime {
         const analysis = this.#pendingDependencies?.get(normalized)
             ?? await this.#dependencies.analyze(normalized);
         const url = pathToFileURL(normalized);
-        url.searchParams.set('zhin-generation', String(this.#revision));
+        if (!this.#entryRevisions.has(normalized))
+            this.#entryRevisions.set(normalized, this.#revision);
+        url.searchParams.set('zhin-generation', String(this.#entryRevisions.get(normalized)));
         let loaded;
         try {
             loaded = await import(url.href);
         }
         catch (error) {
             if (!normalized.endsWith('.tsx') || !isUnsupportedTsxError(error) || !this.#tsxLoader) {
-                throw error;
+                throw withToolPackageInstallHint(error);
+            }
+            try {
+                loaded = await this.#tsxLoader.load(url.href, pathToFileURL(`${this.#projectRoot}${sep}`).href);
+            }
+            catch (tsxError) {
+                throw withToolPackageInstallHint(tsxError);
             }
-            loaded = await this.#tsxLoader.load(url.href, pathToFileURL(`${this.#projectRoot}${sep}`).href);
         }
         if (this.#pendingDependencies)
             this.#pendingDependencies.set(normalized, analysis);
@@ -61,8 +70,12 @@ export class NativeDevelopmentModuleRuntime {
         return loaded;
     }
     invalidate(source) {
+        const impacted = this.#dependencies.affectedSources(source);
         this.#dependencies.invalidate(source);
         this.#revision += 1;
+        for (const entry of new Set([normalizeSourcePath(source), ...impacted])) {
+            this.#entryRevisions.set(entry, this.#revision);
+        }
     }
     affectedSources(source) {
         return this.#dependencies.affectedSources(source);
@@ -86,6 +99,11 @@ export class NativeDevelopmentModuleRuntime {
         // complete project-local import closure.
         if (this.affectedSources(normalized).length > 1)
             return false;
+        // An already loaded ESM entry has the same revisioned import closure as a
+        // capability entry. Its manifest may name plugin.ts or any other filename;
+        // Runtime ownership, rather than directory spelling, chooses its reload.
+        if (this.#entryRevisions.has(normalized) && isExecutableSource(normalized))
+            return false;
         const parts = relative(packageRoot, normalized).split(sep);
         const capability = parts.findIndex((part) => capabilityRoots.has(part));
         if (capability < 0)
@@ -134,6 +152,11 @@ export class NativeDevelopmentModuleRuntime {
         }
         this.#pendingDependencies = undefined;
         this.#dependencies.retain(sources);
+        const retained = new Set(sources.map(normalizeSourcePath));
+        for (const entry of this.#entryRevisions.keys()) {
+            if (!retained.has(entry))
+                this.#entryRevisions.delete(entry);
+        }
     }
     rollbackGeneration() {
         this.#pendingDependencies = undefined;
@@ -170,6 +193,7 @@ export class NativeDevelopmentModuleRuntime {
         this.#watchers.clear();
         this.#pendingDependencies = undefined;
         this.#dependencies.clear();
+        this.#entryRevisions.clear();
         await this.#tsxLoader?.close?.();
     }
     #assertOpen() {

package/lib/plugin-config-schema.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleRuntime } from './module-runtime.js';
+import type { ResolvedPackage } from './package-resolver.js';
+/** One source of truth per package: executable declaration or JSON Schema. */
+export declare function readPluginConfigSchema(pkg: ResolvedPackage, modules?: Pick<ModuleRuntime, 'load'>): Promise<Readonly<Record<string, unknown>> | null>;
+/** Detached declaration metadata for preflight and custom-resolver startup views. */
+export declare function immutableConfigSchema(schema: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;

package/lib/plugin-config-schema.js

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** One source of truth per package: executable declaration or JSON Schema. */
+export async function readPluginConfigSchema(pkg, modules) {
+    const file = resolve(pkg.root, 'schema.json');
+    let fileSchema;
+    try {
+        fileSchema = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    // Isolated plugin code never executes in the composition process.
+    const manifest = pkg.packageJson.zhin;
+    let declaration;
+    if (modules && manifest.type === 'plugin' && manifest.runtime !== 'isolated') {
+        const module = await modules.load(resolve(pkg.root, manifest.entry));
+        declaration = module.default?.config;
+    }
+    if (declaration && fileSchema !== undefined) {
+        throw new TypeError(`${pkg.name} declares both plugin config and schema.json; choose one configuration schema`);
+    }
+    const schema = declaration ? declaration.toJsonSchema() : fileSchema;
+    if (schema === undefined)
+        return null;
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        throw new TypeError(`${pkg.name} configuration must contain a JSON Schema object`);
+    }
+    return immutableConfigSchema(schema);
+}
+/** Detached declaration metadata for preflight and custom-resolver startup views. */
+export function immutableConfigSchema(schema) {
+    const copy = structuredClone(schema);
+    const freeze = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    };
+    freeze(copy);
+    return copy;
+}

package/lib/plugin-scope-assembler.d.ts

@@ -6,7 +6,10 @@ import type { PluginGraphNode } from './project-graph.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import { type PrimaryConfig } from './primary-config.js';
 import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
-export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
+export interface PluginConfigResolver {
+    (node: PluginGraphNode): unknown;
+    schema?(node: PluginGraphNode): Readonly<Record<string, unknown>> | undefined;
+}
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
     readonly generation: number;

package/lib/plugin-scope-assembler.js

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, PluginDatabaseHost, PluginScheduleHost, databaseHostToken, databaseRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, } from '@zhin.js/plugin-runtime';
+import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, PluginDatabaseHost, PluginOutboundHost, PluginScheduleHost, databaseHostToken, databaseRootHostToken, outboundHostToken, outboundRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
 import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
@@ -98,6 +98,9 @@ export class PluginScopeAssembler {
             role: node.parent ? 'child' : 'root',
         });
         let metadata;
+        // Schema composition is Host-owned even when Plugin execution is isolated.
+        // Commit the validated JSON declaration with both kinds of Plugin snapshot.
+        const configSchema = this.configResolver.schema?.(node);
         if (manifest.runtime === 'isolated') {
             if (!node.parent)
                 throw new Error('Root Plugin cannot use runtime: isolated');
@@ -165,9 +168,11 @@ export class PluginScopeAssembler {
             instanceKey: node.instanceKey,
             packageName: node.package.name,
             packageRoot: node.package.root,
+            ...(typeof node.package.packageJson.version === 'string' ? { packageVersion: node.package.packageJson.version } : {}),
             parent: node.parent,
             children: Object.freeze(node.children.map((child) => child.id)),
             metadata,
+            ...(configSchema ? { configSchema } : {}),
         }));
         this.config.set(node.id, config);
         this.resources.set(node.id, scope.snapshot());
@@ -226,17 +231,25 @@ export class PluginScopeAssembler {
     }
     /** Root resources are process-owned; every Plugin Scope receives an owner-bound facade. */
     installOwnerScopedHosts(scope, owner) {
-        const database = scope.has(databaseRootHostToken)
-            ? scope.use(databaseRootHostToken)
+        const root = this.scopes.get(rootPluginId());
+        if (!root)
+            throw new Error('Missing root resource scope');
+        // A retired subtree must close its facades even when the parent remains active.
+        const admission = createGenerationAdmissionGate();
+        if (root.has(outboundRootHostToken)) {
+            scope.provide(outboundHostToken, new PluginOutboundHost(owner, root.use(outboundRootHostToken), admission));
+        }
+        const database = root.has(databaseRootHostToken)
+            ? root.use(databaseRootHostToken)
             : undefined;
         if (database) {
-            scope.provide(databaseHostToken, new PluginDatabaseHost(owner, database));
+            scope.provide(databaseHostToken, new PluginDatabaseHost(owner, database, admission));
         }
-        const schedule = scope.has(scheduleRootHostToken)
-            ? scope.use(scheduleRootHostToken)
+        const schedule = root.has(scheduleRootHostToken)
+            ? root.use(scheduleRootHostToken)
             : undefined;
         if (schedule) {
-            scope.provide(scheduleHostToken, new PluginScheduleHost(owner, schedule));
+            scope.provide(scheduleHostToken, new PluginScheduleHost(owner, schedule, admission));
         }
     }
 }

package/lib/root-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type ControlErrorHandler, type ConfigDocumentPort, type ConfigPatch, type GenerationCommitListener, type PluginId, type RuntimeConfigDocument, type RuntimeSnapshot, type SnapshotReader } from '@zhin.js/plugin-runtime';
+import { type JsonSchema } from './config-composer.js';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers, type EnvironmentLayersPort } from './environment-store.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
@@ -27,6 +28,10 @@ export declare class RootRuntime {
     constructor(options: RootRuntimeOptions);
     get snapshot(): RuntimeSnapshot;
     get snapshots(): SnapshotReader;
+    /** Committed metadata, or validated startup declarations while first login is pending. */
+    get configurationSchemas(): ReadonlyMap<string, JsonSchema>;
+    /** Metadata readiness is independent of account login and generation activation. */
+    whenConfigurationReady(): Promise<void>;
     onGenerationCommit(listener: GenerationCommitListener<RuntimeGenerationState>): () => void;
     get sourceOwnership(): SourceOwnershipIndex;
     start(): Promise<RuntimeSnapshot>;

package/lib/root-runtime.js

@@ -4,6 +4,7 @@ import { isDeepStrictEqual } from 'node:util';
 import { DisposeStack, GenerationHandoffStack, RootController, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
 import { FeatureCatalog, FeatureDiscovery, } from '@zhin.js/feature-kit';
 import { ConfigComposer } from './config-composer.js';
+import { immutableConfigSchema } from './plugin-config-schema.js';
 import { ConfigPatchPlanner } from './config-patch-planner.js';
 import { defineRuntimeEnvironment } from './environment.js';
 import { createEnvStore, defineEnvironmentLayers, } from './environment-store.js';
@@ -39,9 +40,17 @@ export class RootRuntime {
     #isolation;
     #configPatchTail = Promise.resolve();
     #stopResult;
+    #initialConfigSchemas = new Map();
+    #resolveConfigurationReady;
+    #rejectConfigurationReady;
+    #configurationReady = new Promise((resolve, reject) => {
+        this.#resolveConfigurationReady = resolve;
+        this.#rejectConfigurationReady = reject;
+    });
     #controller;
     #disabledPluginInstanceKeys;
     constructor(options) {
+        void this.#configurationReady.catch(() => undefined);
         this.#projectRoot = normalizeSourcePath(options.projectRoot);
         this.#modules = options.modules;
         this.#environment = defineRuntimeEnvironment(options.environment);
@@ -68,6 +77,17 @@ export class RootRuntime {
     get snapshots() {
         return this.#controller.snapshots;
     }
+    /** Committed metadata, or validated startup declarations while first login is pending. */
+    get configurationSchemas() {
+        const snapshot = this.snapshot;
+        return snapshot.generation === 0 ? new Map(this.#initialConfigSchemas)
+            : new Map([...snapshot.tree.values()].flatMap(node => node.configSchema
+                ? [[node.packageRoot, node.configSchema]] : []));
+    }
+    /** Metadata readiness is independent of account login and generation activation. */
+    whenConfigurationReady() {
+        return this.#configurationReady;
+    }
     onGenerationCommit(listener) {
         return this.#controller.onGenerationCommit(listener);
     }
@@ -75,18 +95,24 @@ export class RootRuntime {
         return this.#controller.committed.state.ownership;
     }
     async start() {
-        if (this.#environmentSource) {
-            this.#environmentLayers = defineEnvironmentLayers(await this.#environmentSource.read());
+        try {
+            if (this.#environmentSource) {
+                this.#environmentLayers = defineEnvironmentLayers(await this.#environmentSource.read());
+            }
+            if (this.#configPort) {
+                const snapshot = await this.#configPort.read();
+                this.#configSnapshot = snapshot;
+                this.#configDocument = structuredClone(snapshot.document);
+            }
+            const snapshot = await this.#controller.start(async (current, signal) => {
+                return (await this.#prepare(current, signal)).generation;
+            });
+            return snapshot;
         }
-        if (this.#configPort) {
-            const snapshot = await this.#configPort.read();
-            this.#configSnapshot = snapshot;
-            this.#configDocument = structuredClone(snapshot.document);
+        catch (error) {
+            this.#rejectConfigurationReady(error);
+            throw error;
         }
-        const snapshot = await this.#controller.start(async (current, signal) => {
-            return (await this.#prepare(current, signal)).generation;
-        });
-        return snapshot;
     }
     async reload(target = rootPluginId()) {
         const snapshot = await this.#controller.reload(target, async (current, signal) => {
@@ -118,6 +144,7 @@ export class RootRuntime {
         return new RootProcessRestartExecutor(this, adapter);
     }
     stop() {
+        this.#rejectConfigurationReady(new Error('Runtime stopped before configuration initialization'));
         if (this.#stopResult)
             return this.#stopResult;
         const result = (async () => {
@@ -200,7 +227,7 @@ export class RootRuntime {
         const environmentLayers = environmentChanged && this.#environmentSource
             ? defineEnvironmentLayers(await this.#environmentSource.read())
             : this.#environmentLayers;
-        const inputPlan = await new RuntimeInputPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys)).plan({
+        const inputPlan = await new RuntimeInputPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules)).plan({
             graph: this.#model.graph,
             environment: this.#environment,
             previousDocument: requireConfigDocument(this.#configDocument),
@@ -285,18 +312,39 @@ export class RootRuntime {
             await this.#refreshConfigDocument();
         const activeDocument = document ?? this.#configDocument;
         if (this.#configResolver) {
+            const customResolver = this.#configResolver;
+            const schemas = new Map(graphNodes(graph.root).flatMap(node => {
+                const schema = customResolver.schema?.(node);
+                return schema ? [[node.id, immutableConfigSchema(schema)]] : [];
+            }));
+            const configResolver = node => customResolver(node);
+            configResolver.schema = node => schemas.get(node.id);
+            if (this.snapshot.generation === 0) {
+                this.#initialConfigSchemas = new Map(graphNodes(graph.root).flatMap(node => {
+                    const schema = schemas.get(node.id);
+                    return schema ? [[node.package.root, schema]] : [];
+                }));
+                this.#resolveConfigurationReady();
+            }
             return {
                 graph,
-                configResolver: this.#configResolver,
+                configResolver,
                 primaryConfigDocument: Object.freeze({}),
                 environmentLayers,
             };
         }
-        const composed = await new ConfigComposer(this.#disabledPluginInstanceKeys)
+        const composed = await new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules)
             .compose(graph, activeDocument);
+        if (this.snapshot.generation === 0) {
+            this.#initialConfigSchemas = new Map(graphNodes(graph.root).flatMap(node => {
+                const schema = composed.ownSchemas.get(node.id);
+                return schema ? [[node.package.root, schema]] : [];
+            }));
+            this.#resolveConfigurationReady();
+        }
         return {
             graph,
-            configResolver: this.#configViewResolver(composed.views, environmentLayers),
+            configResolver: this.#configViewResolver(composed.views, environmentLayers, composed.ownSchemas),
             primaryConfigDocument: composed.document,
             environmentLayers,
         };
@@ -317,14 +365,16 @@ export class RootRuntime {
         this.#configSnapshot = snapshot;
         this.#configDocument = structuredClone(snapshot.document);
     }
-    #configViewResolver(views, environmentLayers = this.#environmentLayers) {
-        return (node) => {
+    #configViewResolver(views, environmentLayers = this.#environmentLayers, schemas) {
+        const resolver = (node) => {
             const view = views.get(node.id);
             if (view === undefined)
                 return undefined;
             return createEnvStore(node.id, this.#environment, environmentLayers)
                 .expandMissingAsEmpty(view);
         };
+        resolver.schema = (node) => schemas?.get(node.id);
+        return resolver;
     }
     async #applyConfigPatches(patches) {
         if (!this.#configDocument) {
@@ -344,7 +394,7 @@ export class RootRuntime {
             const graph = await new ProjectGraphService(resolver, {
                 disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
             }).inspect(this.#projectRoot);
-            const planned = await new ConfigPatchPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys)).plan(graph, currentDocument, patches);
+            const planned = await new ConfigPatchPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules)).plan(graph, currentDocument, patches);
             plan = planned;
             if (!planned.documentChanged)
                 return undefined;
@@ -369,7 +419,7 @@ export class RootRuntime {
                 }
                 const inspected = {
                     graph,
-                    configResolver: this.#configViewResolver(planned.views),
+                    configResolver: this.#configViewResolver(planned.views, this.#environmentLayers, planned.ownSchemas),
                     primaryConfigDocument: planned.document,
                     environmentLayers: this.#environmentLayers,
                 };
@@ -590,6 +640,9 @@ class GenerationAssembler {
         };
     }
 }
+function graphNodes(node) {
+    return [node, ...node.children.flatMap(graphNodes)];
+}
 function emptyState() {
     return {
         root: rootPluginId(),

package/lib/slot-generation-preparer.js

@@ -30,14 +30,10 @@ export class SlotGenerationPreparer {
             for (const slot of replacements)
                 capabilities.set(slot.id, slot);
         }
-        // Capability-file HMR projects only the owning Features. The complete
-        // snapshot below is assembled by retaining every other projection.
-        const providers = [...selectedByFeature.keys()].map((feature) => {
-            const provider = this.model.providers.get(feature);
-            if (!provider)
-                throw new Error(`Missing Feature provider for ${feature}`);
-            return provider;
-        });
+        // Snapshot-capturing execution indexes need a current view even when their
+        // own definitions were not edited. Retain only explicitly shareable resources.
+        const providers = [...this.model.providers.values()].filter((provider) => selectedByFeature.has(provider.id) || provider.runtime.retain !== 'when-owner-unchanged');
+        const projectedFeatures = providers.map((provider) => provider.id);
         const projected = await new FeatureProjector(providers).project(current.generation + 1, {
             root: current.root,
             tree: current.tree,
@@ -48,7 +44,7 @@ export class SlotGenerationPreparer {
         try {
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.model.graph, snapshot, this.model.featureIdsByPackageRoot);
-            const assets = this.model.assets.replaceProjections(selectedByFeature.keys(), projected.disposers);
+            const assets = this.model.assets.replaceProjections(projectedFeatures, projected.disposers);
             return prepareRuntimeGeneration({
                 snapshot: projected.state,
                 dispose: () => assets.dispose(),

package/lib/subtree-generation-preparer.d.ts

@@ -1,7 +1,6 @@
-import { type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type PluginId, type RuntimeSnapshot, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { RuntimeEnvironment } from './environment.js';
 import type { EnvironmentLayers } from './environment-store.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';

package/lib/subtree-generation-preparer.js

@@ -71,13 +71,28 @@ export class SubtreeGenerationPreparer {
                 for (const slot of slots)
                     addCapabilitySlot(capabilities, slot);
             }
-            const projected = await new FeatureProjector(this.model.providers.values()).project(current.generation + 1, {
+            // Most indexes capture a complete construction snapshot and must rebuild.
+            // Only an explicitly shareable projection may retain unchanged transports.
+            const affectedFeatures = new Set([...this.model.providers.values()]
+                .filter((provider) => provider.runtime.retain !== 'when-owner-unchanged')
+                .map((provider) => provider.id));
+            for (const [feature, featureRoots] of this.model.rootsByFeature) {
+                if (featureRoots.some((entry) => roots.some((root) => isWithin(entry.owner, root)))) {
+                    affectedFeatures.add(feature);
+                }
+            }
+            for (const slot of [...current.capabilities.values(), ...capabilities.values()]) {
+                if (roots.some((root) => isWithin(slot.owner, root)))
+                    affectedFeatures.add(slot.feature);
+            }
+            const providers = [...this.model.providers.values()].filter((provider) => affectedFeatures.has(provider.id));
+            const projected = await new FeatureProjector(providers).project(current.generation + 1, {
                 root: current.root,
                 tree: plugins.tree,
                 config: plugins.config,
                 resources: plugins.resources,
                 capabilities,
-            }, signal);
+            }, signal, current.projections);
             for (const [feature, dispose] of projected.disposers) {
                 projectionDisposers.set(feature, dispose);
             }
@@ -87,7 +102,7 @@ export class SubtreeGenerationPreparer {
             const replacements = new Map(plugins.createdScopeDisposers());
             // Local prepare still commits a complete immutable generation. The
             // replacement map controls lifetime ownership, not snapshot granularity.
-            const assets = this.model.assets.replaceScopes([...nodes.keys()], replacements, projectionDisposers);
+            const assets = this.model.assets.replaceScopes([...nodes.keys()], replacements, affectedFeatures, projectionDisposers);
             return prepareRuntimeGeneration({
                 snapshot: projected.state,
                 dispose: () => assets.dispose(),

package/lib/topology-generation-preparer.d.ts

@@ -1,7 +1,6 @@
-import { type CapabilityId, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CapabilityId, type PluginId, type RuntimeSnapshot, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { RuntimeEnvironment } from './environment.js';
 import type { EnvironmentLayers } from './environment-store.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';

package/lib/topology-generation-preparer.js

@@ -92,7 +92,7 @@ export class TopologyGenerationPreparer {
             plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, featureTopology.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
-            const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, projectionDisposers);
+            const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, new Set([...this.model.providers.keys(), ...featureTopology.providers.keys()]), projectionDisposers);
             return prepareRuntimeGeneration({
                 snapshot: projected.state,
                 dispose: () => assets.dispose(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -8,7 +8,6 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "development": "./src/index.ts",
       "import": "./lib/index.js"
     }
   },
@@ -20,24 +19,25 @@
     "es-module-lexer": "2.3.1",
     "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/plugin-runtime": "1.1.12",
-    "@zhin.js/feature-kit": "1.1.3"
+    "@zhin.js/feature-kit": "1.1.5",
+    "@zhin.js/plugin-runtime": "1.1.14"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.17",
-    "@zhin.js/agent-feature": "1.1.4",
-    "@zhin.js/command": "1.1.5",
-    "@zhin.js/component": "1.1.4",
-    "@zhin.js/layout": "1.1.4",
-    "@zhin.js/mcp-feature": "1.1.4",
-    "@zhin.js/middleware": "1.1.4",
-    "@zhin.js/page": "1.1.4",
-    "@zhin.js/prompt-section": "1.1.3",
-    "@zhin.js/skill": "1.1.4",
-    "@zhin.js/tool": "1.1.4"
+    "@zhin.js/agent-feature": "1.1.6",
+    "@zhin.js/command": "1.1.7",
+    "@zhin.js/adapter": "1.1.19",
+    "@zhin.js/component": "1.1.6",
+    "@zhin.js/handler": "1.1.5",
+    "@zhin.js/layout": "1.1.6",
+    "@zhin.js/mcp-feature": "1.1.6",
+    "@zhin.js/middleware": "1.1.6",
+    "@zhin.js/page": "1.1.6",
+    "@zhin.js/prompt-section": "1.1.5",
+    "@zhin.js/skill": "1.1.6",
+    "@zhin.js/tool": "1.1.6"
   },
   "repository": {
     "type": "git",
@@ -49,7 +49,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.19.0"
   },
   "license": "MIT",
   "scripts": {