@qilin-agent/system-prompt 3.1.3 → 3.1.4

package/README.i18n.yaml

@@ -5,84 +5,87 @@
 /:
   en: 51d99b2500db958f
   zh: 91f2b113ba7989fd
-/qilin-system-prompt:
-  en: 065edd590b8e1710
-  zh: fcda63918ebdbdcd
-/qilin-system-prompt/summary:
+/qilin-agent-system-prompt:
+  en: e055adfb8078d76e
+  zh: 0ef22d7fa3664d17
+/qilin-agent-system-prompt/summary:
   en: ca3bf8175b50bb4f
   zh: 528223498f6ae517
-/qilin-system-prompt/table-of-contents:
+/qilin-agent-system-prompt/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/qilin-system-prompt/use-this-package:
+/qilin-agent-system-prompt/use-this-package:
   en: b6ad9defa94ac243
   zh: 89f4dd6352cd341e
-/qilin-system-prompt/use-this-package/configure-the-prompt:
-  en: a2fe6e6d6052e932
-  zh: 852918af808a02aa
-/qilin-system-prompt/use-this-package/contribute-a-prompt-section:
+/qilin-agent-system-prompt/use-this-package/configure-the-prompt:
+  en: 186edc62fe4c05aa
+  zh: 34605297e98231ff
+/qilin-agent-system-prompt/use-this-package/contribute-a-prompt-section:
   en: 15d70e3b8eddd636
   zh: a3a67cab60eee86f
-/qilin-system-prompt/use-this-package/contribute-a-prompt-variable:
-  en: 39050b92755ceb21
-  zh: 9ddc7d24914b8f2e
-/qilin-system-prompt/use-this-package/contribute-tool-schemas:
+/qilin-agent-system-prompt/use-this-package/contribute-a-prompt-variable:
+  en: b446eaed75655d68
+  zh: f3de147588f41e35
+/qilin-agent-system-prompt/use-this-package/contribute-tool-schemas:
   en: 009ef267dac2f270
   zh: e79c24bff5cd836f
-/qilin-system-prompt/use-this-package/suppress-runtime-context:
-  en: 61e2c1a3f18b48dd
-  zh: 29ecab2639f60103
-/qilin-system-prompt/understand-the-implementation:
+/qilin-agent-system-prompt/use-this-package/contribute-dynamic-context:
+  en: 4365bc4a5d228bb2
+  zh: 1e23544beca040e0
+/qilin-agent-system-prompt/use-this-package/suppress-runtime-context:
+  en: 9104a137c8fef881
+  zh: 44edd0a101210473
+/qilin-agent-system-prompt/understand-the-implementation:
   en: ce7e776e9d516bdb
   zh: 59d2751743db7795
-/qilin-system-prompt/understand-the-implementation/design-concept:
+/qilin-agent-system-prompt/understand-the-implementation/design-concept:
   en: c91963b89a866fed
   zh: ef9ef4940145778f
-/qilin-system-prompt/understand-the-implementation/source-map:
+/qilin-agent-system-prompt/understand-the-implementation/source-map:
   en: d9575bcb07a1145b
   zh: 0f1a388780d055b1
-/qilin-system-prompt/understand-the-implementation/assembly-and-rendering:
+/qilin-agent-system-prompt/understand-the-implementation/assembly-and-rendering:
   en: 54977e6c431f851e
   zh: ef60007054b97ff0
-/qilin-system-prompt/understand-the-implementation/scoping:
+/qilin-agent-system-prompt/understand-the-implementation/scoping:
   en: 1100ab1dfe961631
   zh: c510275c893951b4
-/qilin-system-prompt/further-exploration:
+/qilin-agent-system-prompt/further-exploration:
   en: e0313b2ec3ae59a7
   zh: 4ff805fed23f3d03
-/qilin-system-prompt/model-experience:
+/qilin-agent-system-prompt/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
-/qilin-system-prompt/model-experience/system-prompt:
+/qilin-agent-system-prompt/model-experience/system-prompt:
   en: cf78b9dd5596495f
   zh: bd44560f8c2435e8
-/qilin-system-prompt/model-experience/system-prompt/what-the-model-sees:
+/qilin-agent-system-prompt/model-experience/system-prompt/what-the-model-sees:
   en: 9927fdee4f8aa8ec
   zh: 3687314c357fa7f4
-/qilin-system-prompt/model-experience/system-prompt/what-the-model-sees/harness-identity:
+/qilin-agent-system-prompt/model-experience/system-prompt/what-the-model-sees/harness-identity:
   en: 40effd71cb503319
   zh: 9969356237a4f398
-/qilin-system-prompt/model-experience/system-prompt/token-effect:
+/qilin-agent-system-prompt/model-experience/system-prompt/token-effect:
   en: 29722e212137deaa
   zh: 92cd0f1a16b10315
-/qilin-system-prompt/model-experience/system-prompt/kv-cache-effect:
+/qilin-agent-system-prompt/model-experience/system-prompt/kv-cache-effect:
   en: 06c93d3134e63dc0
   zh: 344170f0277738e0
-/qilin-system-prompt/model-experience/tool-schemas:
+/qilin-agent-system-prompt/model-experience/tool-schemas:
   en: 3039bc5e7a796b21
   zh: 6b7a9eaf69c9ea53
-/qilin-system-prompt/model-experience/tool-schemas/what-the-model-sees:
-  en: a927ad457ff32a67
-  zh: 901c6155a486dd9a
-/qilin-system-prompt/model-experience/tool-schemas/token-effect:
+/qilin-agent-system-prompt/model-experience/tool-schemas/what-the-model-sees:
+  en: 4b79169eaa1f50af
+  zh: 9acc5a130e05e66c
+/qilin-agent-system-prompt/model-experience/tool-schemas/token-effect:
   en: f3a7d374c55e1720
   zh: 0ee48af678cb875f
-/qilin-system-prompt/model-experience/tool-schemas/kv-cache-effect:
+/qilin-agent-system-prompt/model-experience/tool-schemas/kv-cache-effect:
   en: ebd329e360f0d143
   zh: 9d67fe503a6a095a
-/qilin-system-prompt/known-limitations-and-deferred-work:
+/qilin-agent-system-prompt/known-limitations-and-deferred-work:
   en: 23bb9f59ceb1620c
   zh: be34f1770fa2e027
-/qilin-system-prompt/known-limitations-and-deferred-work/dev-note:
+/qilin-agent-system-prompt/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -67,19 +67,25 @@ Set `interpolate: false` on a section to preserve its text literally, including
 
 ### Contribute a prompt variable
 
-Variables are referenced from section text as `{{name}}` and resolved at each assembly; scoped variables shadow a same-named global for that agent. The loop supplies `model` and `cwd`; any plugin can register the facts it owns.
+Variables are referenced from section or context text as `{{name}}` and resolved at each assembly; scoped variables shadow a same-named global for that agent. The loop supplies `provider` and `model`; plugins can register the facts they own. The working-directory service supplies directory text as literal user context.
 
 ```text
-ctx.systemPrompt.variable('cwd', ({ agent }) => agent?.session.header.cwd)
+ctx.systemPrompt.variable('response_language', () => 'English')
 ```
 
+Custom persona templates must not depend on a built-in `{{cwd}}` variable: the loop does not register it, so unresolved references fail prompt assembly before any model request. Remove the `Your working directory is {{cwd}}.` clause from home, profile, or invocation `personaSuffix` settings and preset `suffix` fields, preserving unrelated text. Omit or clear an otherwise empty suffix. The [working-directory service](../../session/working-directory/README.md) supplies the required current-directory context.
+
 ### Contribute tool schemas
 
 Tool-schema providers are evaluated per assembly and contribute the model-visible `ToolSchema` set; `ToolRuntime` registers itself automatically, so most tools need no manual wiring here. A provider returns the post-restriction visible set plus the pre-restriction name universe used by `toolOrder`.
 
+### Contribute dynamic context
+
+`context()` registers a runtime fact as a `PromptContext`. `interpolate: false` keeps its text literal, and `required: true` keeps it when optional runtime context is disabled or suppressed. The assembly resolves registered contributions in ascending `order`; `refreshContext()` re-resolves them at request admission, so a fact that moved after assembly (a directory change, a permission change) reaches the same request without reassembling sections, tools, or variables.
+
 ### Suppress runtime context
 
-`suppressRuntimeContext()` removes every dynamic runtime-context contribution for the calling scope without disabling the services that own the underlying facts; multiple suppressors compose and the effect restores context when none remains.
+`suppressRuntimeContext()` removes every optional dynamic runtime-context contribution for the calling scope without disabling the services that own the underlying facts; `required: true` contributions remain. Multiple suppressors compose and the effect restores context when none remains.
 
 -----
 

package/README.zh.md

@@ -67,19 +67,25 @@ ctx.systemPrompt.section({
 
 ### 贡献提示词变量
 
-变量在段文本中以 `{{name}}` 引用，并在每次组装时解析；带作用域变量会为该 agent 遮蔽同名全局变量。循环提供 `model` 与 `cwd`；任何插件都可以注册自己拥有的事实。
+变量从段或上下文文本中以 `{{name}}` 引用，每次组装时解析；带作用域的变量会为该 agent 遮蔽同名全局变量。循环提供 `provider` 和 `model`；插件可注册自己拥有的事实。工作目录服务通过不执行插值的用户上下文提供目录文本。
 
 ```text
-ctx.systemPrompt.variable('cwd', ({ agent }) => agent?.session.header.cwd)
+ctx.systemPrompt.variable('response_language', () => 'English')
 ```
 
+自定义 persona 模板不得依赖内置 `{{cwd}}` 变量：循环不注册它，因此无法解析的引用会在任何模型请求之前使提示词组装失败。请从 home、profile 或单次调用的 `personaSuffix` 设置以及 preset 的 `suffix` 字段中移除 `Your working directory is {{cwd}}.` 语句，保留无关文本。后缀没有其他内容时，可省略或清空该字段。[工作目录服务](../../session/working-directory/README.zh.md) 提供必需的当前目录上下文。
+
 ### 贡献工具 schema
 
 工具 schema 提供方在每次组装时求值，并贡献模型可见的 `ToolSchema` 集合；`ToolRuntime` 会自动注册自身，因此大多数工具在此无需手动接线。提供方返回限制后的可见集合，外加 `toolOrder` 使用的限制前名称全集。
 
+### 贡献动态上下文
+
+`context()` 把一条运行时事实注册为 `PromptContext`。`interpolate: false` 保留其字面文本，`required: true` 使其在可选运行时上下文被关闭或抑制时仍然保留。assembly 按 `order` 升序解析已注册贡献；`refreshContext()` 在请求准入时重新解析它们，因此装配之后才变化的事实（目录变更、权限变更）能在同一次请求内到达模型，而无需重新装配 section、tool 或 variable。
+
 ### 抑制运行时上下文
 
-`suppressRuntimeContext()` 移除调用作用域的所有动态运行时上下文贡献，但不禁用拥有底层事实的服务；多个抑制器独立组合，当不再存在抑制器时该 effect 会恢复上下文。
+`suppressRuntimeContext()` 移除调用作用域的**可选**动态运行时上下文贡献，但不禁用拥有底层事实的服务；`required: true` 的贡献会保留。多个抑制器独立组合，当不再存在抑制器时该 effect 会恢复上下文。
 
 -----
 

package/lib/index.js

@@ -43,6 +43,7 @@ const SECTION_ORDERS = {
 	DEPLOYMENT_PERSONA_SUFFIX: 10200
 };
 const CONTEXT_ORDERS = {
+	WORKING_DIRECTORY: 100,
 	SANDBOX_POLICY: 110,
 	APPROVAL_POLICY: 115,
 	SUBAGENT_DELEGATION: 120
@@ -115,7 +116,7 @@ function renderPrompt(assembly) {
 	return assembly.sections.map((section) => section.interpolate === false ? section.text : interpolate(section, assembly.variables, "section")).filter((text) => text.length > 0).join("\n\n");
 }
 /**
-* Render the complete dynamic context snapshot.
+* Render the complete dynamic context snapshot, preserving literal contributions.
 * @param assembly - the assembly whose contexts and variables to render.
 * @returns the current full snapshot, or `''` when no context is active.
 */
@@ -140,14 +141,15 @@ function joinContextSections(sections) {
 *
 * {@link renderContextSnapshot} joins these for the model; a consumer that
 * presents the snapshot uses them to attribute each part to the subsystem that
-* contributed it, without re-splitting the joined prose.
+* contributed it, without re-splitting the joined prose. Contributions with
+* `interpolate: false` preserve literal text instead of resolving prompt variables.
 * @param assembly - the assembly whose contexts and variables to render.
 * @returns one entry per contributing context that rendered to non-empty text.
 */
 function renderContextSections(assembly) {
 	return assembly.contexts.map((context) => ({
 		name: context.name,
-		text: interpolate(context, assembly.variables, "context")
+		text: context.interpolate === false ? context.text : interpolate(context, assembly.variables, "context")
 	})).filter((section) => section.text.length > 0);
 }
 /** Interpolate one section or context and attribute diagnostics to its owning input. */
@@ -176,6 +178,14 @@ function interpolate(input, variables, kind) {
 	}
 	return result + text.slice(last);
 }
+/** Resolve one registered runtime fact without assembling sections or tools. */
+function resolveContext(entry, context) {
+	return {
+		name: entry.name,
+		text: typeof entry.text === "function" ? entry.text(context) : entry.text,
+		...entry.interpolate !== void 0 ? { interpolate: entry.interpolate } : {}
+	};
+}
 /** All prompt registrations owned by one global or scoped layer. */
 var PromptLayer = class {
 	sections;
@@ -269,7 +279,7 @@ var SystemPrompt = class extends Service {
 		return this.layers.effect(this.ctx, (layer) => layer.contexts.insert(context.name, context), { label: "systemPrompt.context()" });
 	}
 	/**
-	* Suppress every dynamic runtime-context contribution in the calling
+	* Suppress optional dynamic runtime-context contributions in the calling
 	* context's scope without changing the services that own or enforce those
 	* facts. Multiple suppressors remain independently disposable.
 	* @returns the exact Cordis effect disposer.
@@ -300,6 +310,39 @@ var SystemPrompt = class extends Service {
 		return this.layers.effect(this.ctx, (layer) => layer.variables.insert(name, provider), { label: "systemPrompt.variable()" });
 	}
 	/**
+	* Refresh accepted registered runtime facts for request admission. Contexts
+	* added only by the assembly waterfall retain their accepted values. Current
+	* suppression removes optional contexts, and missing required registrations
+	* are restored in registry order. Sections, tools, and interpolation variables
+	* retain the accepted assembly; their providers and waterfall do not rerun.
+	* @param assembly - accepted assembly for this scope and step.
+	* @param context - the same scope and current plugin-defined assembly fields.
+	* @returns the accepted assembly with current runtime-context provider text.
+	*/
+	refreshContext(assembly, context = {}) {
+		const providers = this.layers.merge(context.scope, (layer) => layer.contexts);
+		const suppressed = !this.layers.global.runtimeContextSuppressors.isEmpty() || this.layers.chainLayers(context.scope).some((layer) => !layer.runtimeContextSuppressors.isEmpty());
+		const required = new Map([...providers].filter(([, entry]) => entry.required === true));
+		const contexts = [];
+		for (const accepted of assembly.contexts) {
+			const provider = providers.get(accepted.name);
+			required.delete(accepted.name);
+			if (suppressed && provider?.required !== true) continue;
+			contexts.push(provider === void 0 ? accepted : resolveContext(provider, context));
+		}
+		for (const provider of required.values()) {
+			const index = contexts.findIndex((entry) => {
+				const next = providers.get(entry.name);
+				return next !== void 0 && next.order > provider.order;
+			});
+			contexts.splice(index < 0 ? contexts.length : index, 0, resolveContext(provider, context));
+		}
+		return {
+			...assembly,
+			contexts
+		};
+	}
+	/**
 	* Assemble global and scoped providers, detach tool parameters, apply
 	* canonical ordering, then run the assembly waterfall. Scoped sections and
 	* variables shadow globals. The returned waterfall value is authoritative
@@ -346,19 +389,17 @@ var SystemPrompt = class extends Service {
 				if (section.complete === true) completeSection = { ...assembled };
 				return assembled;
 			}),
-			contexts: runtimeContextSuppressed ? [] : [...contextByName.values()].sort((a, b) => a.order - b.order).map((entry) => ({
-				name: entry.name,
-				text: typeof entry.text === "function" ? entry.text(context) : entry.text
-			})),
+			contexts: [...contextByName.values()].filter((entry) => !runtimeContextSuppressed || entry.required === true).sort((a, b) => a.order - b.order).map((entry) => resolveContext(entry, context)),
 			tools: orderTools(collected, this.toolOrder, knownNames),
 			variables
 		};
 		const transformed = await this.ctx.waterfall(scopeTarget(this, scope), "system-prompt/assemble", assembly, context, () => Promise.resolve(assembly));
 		if (completeSection === void 0 && !runtimeContextSuppressed) return transformed;
+		const requiredContexts = new Set([...contextByName.values()].filter((entry) => entry.required === true).map((entry) => entry.name));
 		return {
 			...transformed,
 			sections: completeSection === void 0 ? transformed.sections : [completeSection],
-			contexts: runtimeContextSuppressed ? [] : transformed.contexts
+			contexts: runtimeContextSuppressed ? transformed.contexts.filter((entry) => requiredContexts.has(entry.name)) : transformed.contexts
 		};
 	}
 };

package/lib/types/index.d.ts

@@ -74,8 +74,12 @@ export interface PromptContext {
     readonly name: string;
     /** Contexts are joined in ascending order. */
     readonly order: number;
-    /** Static text or a provider evaluated for each assembly. Empty text contributes nothing. */
+    /** Static text or a provider evaluated at assembly and admission refresh. Empty text contributes nothing. */
     readonly text: string | ((context: AssembleContext) => string);
+    /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
+    readonly interpolate?: boolean;
+    /** Keep this operational context when optional runtime context is disabled. */
+    readonly required?: boolean;
 }
 /** One section of an assembly: {@link PromptSection} with its text resolved. */
 export interface AssembledSection {
@@ -92,6 +96,8 @@ export interface AssembledContext {
     name: string;
     /** The resolved text before variable interpolation. */
     text: string;
+    /** Whether to interpolate prompt variables. Defaults to true; false preserves literal text. */
+    interpolate?: boolean;
 }
 /** Tool schemas visible in one assembly and their pre-restriction name set. */
 export interface ToolProviderResult {
@@ -148,6 +154,7 @@ declare const SECTION_ORDERS: {
 /** Name of a centrally allocated prompt-section position. */
 export type PromptSectionOrderName = keyof typeof SECTION_ORDERS;
 declare const CONTEXT_ORDERS: {
+    readonly WORKING_DIRECTORY: 100;
     readonly SANDBOX_POLICY: 110;
     readonly APPROVAL_POLICY: 115;
     readonly SUBAGENT_DELEGATION: 120;
@@ -169,7 +176,7 @@ export declare const TOOL_ORDER_REST = "<unlisted-tools>";
 export interface Config {
     /** Include the fixed QiLin identity before the deployment persona (default true). */
     includeHarnessIdentity?: boolean;
-    /** Include dynamic runtime-context snapshots in model history (default true). */
+    /** Include optional runtime-context snapshots in model history (default true); required context remains. */
     includeRuntimeContext?: boolean;
     /**
      * Deployment-wide persona prefix template before first-party guidance. A scoped section named
@@ -199,7 +206,7 @@ export interface Config {
  */
 export declare function renderPrompt(assembly: PromptAssembly): string;
 /**
- * Render the complete dynamic context snapshot.
+ * Render the complete dynamic context snapshot, preserving literal contributions.
  * @param assembly - the assembly whose contexts and variables to render.
  * @returns the current full snapshot, or `''` when no context is active.
  */
@@ -218,7 +225,8 @@ export declare function joinContextSections(sections: readonly ContextSnapshotSe
  *
  * {@link renderContextSnapshot} joins these for the model; a consumer that
  * presents the snapshot uses them to attribute each part to the subsystem that
- * contributed it, without re-splitting the joined prose.
+ * contributed it, without re-splitting the joined prose. Contributions with
+ * `interpolate: false` preserve literal text instead of resolving prompt variables.
  * @param assembly - the assembly whose contexts and variables to render.
  * @returns one entry per contributing context that rendered to non-empty text.
  */
@@ -258,7 +266,7 @@ export declare class SystemPrompt extends Service {
      */
     context(context: PromptContext): () => void;
     /**
-     * Suppress every dynamic runtime-context contribution in the calling
+     * Suppress optional dynamic runtime-context contributions in the calling
      * context's scope without changing the services that own or enforce those
      * facts. Multiple suppressors remain independently disposable.
      * @returns the exact Cordis effect disposer.
@@ -281,6 +289,17 @@ export declare class SystemPrompt extends Service {
      * @returns the exact Cordis effect disposer.
      */
     variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void;
+    /**
+     * Refresh accepted registered runtime facts for request admission. Contexts
+     * added only by the assembly waterfall retain their accepted values. Current
+     * suppression removes optional contexts, and missing required registrations
+     * are restored in registry order. Sections, tools, and interpolation variables
+     * retain the accepted assembly; their providers and waterfall do not rerun.
+     * @param assembly - accepted assembly for this scope and step.
+     * @param context - the same scope and current plugin-defined assembly fields.
+     * @returns the accepted assembly with current runtime-context provider text.
+     */
+    refreshContext(assembly: PromptAssembly, context?: AssembleContext): PromptAssembly;
     /**
      * Assemble global and scoped providers, detach tool parameters, apply
      * canonical ordering, then run the assembly waterfall. Scoped sections and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/system-prompt",
   "description": "System prompt assembly registry for the QiLin",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -30,16 +30,16 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/scope": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/kylin": "~4.0.3"
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/llm": "3.1.4"
   },
   "dependencies": {
     "@qilin-agent/schemastery": "~3.18.3"
   },
   "devDependencies": {
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/scope": "3.1.4",
     "@qilin-agent/kylin": "~4.0.3"
   }
 }