billion-context-dsh 0.1.9 → 0.2.0

package/dist/nudge.d.ts

@@ -10,10 +10,13 @@ import { type UserMessage } from '@deepseek-ai/dsh-llm';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { AcpStateStore } from './state.ts';
 import { type KernelConfigInput } from './config.ts';
+import { type ResolvedPrompts } from './prompts.ts';
 /** Kernel inputs the nudge path shares with the compress tool. */
 export interface NudgeEnvironment extends KernelConfigInput {
     readonly kernel: CompressionCore;
     readonly store: AcpStateStore;
+    /** Resolved prompt templates (optional: falls back to DEFAULT_RESOLVED). */
+    readonly prompts?: ResolvedPrompts;
 }
 export interface NudgeOutcome {
     readonly message: UserMessage;
@@ -38,7 +41,7 @@ export declare function resolveTokenCount(agent: Agent, coreMessages: CoreMessag
  * Computed directly from the surface (not the kernel's ref map, which can
  * drift and hide large tool results) — see buildCompressibleSeqRanges.
  */
-export declare function rangeTable(session: import('@deepseek-ai/dsh-session').Session): string;
+export declare function rangeTable(session: import('@deepseek-ai/dsh-session').Session, prompts?: ResolvedPrompts): string;
 /**
  * Decide and build one nudge message for the agent's next pre-step. Returns
  * null when the kernel recommends no nudge or one was already injected for the
@@ -52,4 +55,4 @@ export declare function buildNudge(agent: Agent, env: NudgeEnvironment, lastNudg
  * when to compress. Full guidance (tools, philosophy, summary rules) lives in
  * the system prompt once, not in every nudge.
  */
-export declare function buildNudgeText(nudge: NudgeDecision, emergency: boolean, session: import('@deepseek-ai/dsh-session').Session): string;
+export declare function buildNudgeText(nudge: NudgeDecision, emergency: boolean, session: import('@deepseek-ai/dsh-session').Session, prompts?: ResolvedPrompts): string;

package/dist/prompts.d.ts

@@ -0,0 +1,85 @@
+/**
+ * M4 — configurable prompt templates: the per-stage model-visible texts
+ * (nudge frames, range table, system prompt, tool descriptions) rendered from
+ * `config.prompts` templates with named placeholders.
+ *
+ * Design: docs/configurable-prompts-design.md (v4).
+ * - placeholders are `{identifier}` only; literal braces like
+ *   `compress({ content: [...] })` are left untouched (spaces/commas break the
+ *   identifier rule);
+ * - resolvePrompts merges user overrides over DEFAULT_PROMPTS per key
+ *   (null/undefined → default, string → override; group-level null → whole
+ *   group default for YAML hosts) and validates unknown placeholders at
+ *   construction time (fail-fast, no silent typos);
+ * - renderTemplate throws when a known placeholder has no value — callers
+ *   must provide every value (e.g. tokens via a typeof fallback).
+ * @module billion-context-dsh/prompts
+ */
+/** 用户可写值:字符串模板,或 null(= 用默认,等价于不写)。YAML 宿主写 null 是合法输入。 */
+export type PromptInput = string | null;
+/** 按组生成"每键可选、可 null"的覆盖类型。 */
+export type PromptOverride<T> = {
+    [K in keyof T]?: PromptInput;
+};
+export interface NudgePrompts {
+    /** 普通档首句。占位符:{pct} */
+    normal: string;
+    /** 紧急档首句。占位符:{pct} */
+    emergency: string;
+    /** 指导行。无占位符 */
+    guidance: string;
+    /** tier 蒸馏行。占位符:{tier} {count} {prevTier} {tokens} {seqs} */
+    tier: string;
+}
+export interface RangeTablePrompts {
+    /** 表头。占位符:{surface} */
+    header: string;
+    /** 标题。占位符:{count}(表格行数) */
+    title: string;
+    /** 每行。占位符:{start} {end} {count} {tokens} */
+    line: string;
+    /** 表尾调用语法。无占位符 */
+    footer: string;
+}
+export interface ToolPrompts {
+    /** 工具描述(纯文本,无占位符) */
+    compress: string;
+    decompress: string;
+    searchContext: string;
+    acpStatus: string;
+}
+export interface AcpPrompts {
+    readonly nudge?: PromptOverride<NudgePrompts>;
+    readonly rangeTable?: PromptOverride<RangeTablePrompts>;
+    readonly tools?: PromptOverride<ToolPrompts>;
+    /** 整段 system prompt 模板;`{philosophy}` 引用 kernel 的 COMPRESS_PHILOSOPHY */
+    readonly systemPrompt?: PromptInput;
+}
+/** 解析结果 —— 所有字段已填满(纯 string,无 null)、已校验。构造一次,全程复用。 */
+export interface ResolvedPrompts {
+    readonly nudge: NudgePrompts;
+    readonly rangeTable: RangeTablePrompts;
+    readonly tools: ToolPrompts;
+    /** 注意:这是【模板】(含 {philosophy}),不是渲染结果。渲染用 renderSystemPrompt。 */
+    readonly systemPromptTemplate: string;
+}
+/**
+ * 纯替换。两个契约:
+ * 1. 未知占位符不可能到达这里(构建期已校验);
+ * 2. 已知占位符缺值 = 编程错误 → throw(绝不静默渲染空串)。
+ */
+export declare function renderTemplate(template: string, vars: Record<string, string | number>): string;
+/**
+ * 深合并 + 校验;引擎构造期调用一次,出错即抛(fail-fast)。
+ * 未传入时返回 DEFAULT_RESOLVED,零校验重跑。
+ */
+export declare function resolvePrompts(input?: AcpPrompts): ResolvedPrompts;
+/** 渲染 system prompt 模板(注入 kernel 压缩哲学)。 */
+export declare function renderSystemPrompt(prompts: ResolvedPrompts): string;
+/**
+ * 默认模板 —— 与 v4 之前的硬编码文案逐字节一致
+ * (回归锚点见 tests/prompts.test.ts 的硬编码字面量快照)。
+ */
+export declare const DEFAULT_PROMPTS: ResolvedPrompts;
+/** 模块级默认缓存:默认参/兜底直接引用,避免每次调用重跑校验。 */
+export declare const DEFAULT_RESOLVED: ResolvedPrompts;

package/dist/system-prompt.d.ts

@@ -4,8 +4,12 @@
  * instead of being re-sent with every nudge. The nudge itself stays a short,
  * advisory notice — ACP is model-driven, the model decides whether and when
  * to compress (never "compress now").
+ *
+ * The text is DEFAULT_PROMPTS.systemPromptTemplate rendered with the kernel's
+ * COMPRESS_PHILOSOPHY; hosts can override the whole section via
+ * `config.prompts.systemPrompt` (see docs/configurable-prompts-design.md).
  * @module billion-context-dsh/system-prompt
  */
-export declare const ACP_SYSTEM_PROMPT = "Active Context Pruning \u2014 model-driven context management\n\nYOU decide whether and when to compress context. Nothing forces you: the injected \"nudge\" is a suggestion, not an order, and you may ignore it when compression would not help. Compress only ranges you have genuinely consumed (read tool outputs, finished explorations, superseded steps) that the current work no longer needs verbatim.\n\nCompression Philosophy:\n- All compression serves the primary task, but be frugal.\n- Context capacity is precious. Save context by compressing consumed outputs, not by avoiding tools.\n- Compress by need, not by percentage.\n- Work from summaries, not raw tool outputs. All listed ranges (user prompts, tool outputs, code, logs, exploration, intermediate steps) should be compressed to summary format \u2014 the ONLY exceptions are protected content, content the current step is actively using, or critical content you cannot reconstruct.\n\nCompression tools (refs are SURFACE SEQS, not ids):\n- compress: replace one or more seq ranges, each with your own dense summary. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated segments in one call (each entry becomes its own block): compress({ content: [{ startSeq: 1, endSeq: 5, summary: '...' }, { startSeq: 12, endSeq: 18, summary: '...' }] }). Keep ranges disjoint \u2014 overlapping entries in one batch are skipped. Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Seq refs must be on the current surface: seqs from older nudges or earlier compresses go stale as the surface moves, so a stale span is auto-remapped to its still-live remainder (the result reports the adjusted span), a fully compressed span is reported as already compressed, and invented/other-session seqs fail with guidance.\n- decompress: recover a compressed block's original content, read-only. decompress({ blockId }).\n- search_context: find information inside compressed blocks BEFORE decompressing. search_context({ query }).\n- acp_status: current context usage and the live compressible-range list. Run it right before compressing \u2014 the only seqs that never go stale are the ones you just read.\n\nTiered compression: each compressed block appears on the surface as one summary node. Compressing that node again DISTILLS the block (tier 2): the parent summary folds into your new summary and the original messages are freed. Distilling a tier-2 block yields tier 3. Distill when a summary itself is consumed \u2014 decompress on the tier-2 block recovers the full originals.\n\nWhen you write a summary, it becomes the ONLY record of that range: keep file paths, signatures, exact values, decisions, and error strings verbatim so a later reader (or you, after decompress) can continue without the original. Never reuse historical seqs \u2014 the surface moves as messages land and compress; verify with acp_status.";
+export declare const ACP_SYSTEM_PROMPT: string;
 /** System-prompt section order: tool guidance lives in 100–199. */
 export declare const ACP_SYSTEM_PROMPT_ORDER = 150;

package/dist/tools.d.ts

@@ -15,11 +15,14 @@ import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { AcpStateStore } from './state.ts';
 import { type KernelConfigInput } from './config.ts';
 import { type AcpWindow } from './window.ts';
+import { type ResolvedPrompts } from './prompts.ts';
 export interface ToolEnvironment extends KernelConfigInput {
     readonly kernel: CompressionCore;
     readonly store: AcpStateStore;
     /** Resolve the effective context window for an agent (optional: status falls back to modelContextLimit). */
     readonly windowFor?: (agent: Agent) => Promise<AcpWindow>;
+    /** Resolved prompt templates (optional: falls back to DEFAULT_RESOLVED). */
+    readonly prompts?: ResolvedPrompts;
 }
 /** Build the four ACP model tools bound to one engine. */
 export declare function makeTools(env: ToolEnvironment): ToolDefinition[];

package/package.json

@@ -1,7 +1,19 @@
 {
 	"name": "billion-context-dsh",
-	"version": "0.1.9",
+	"version": "0.2.0",
 	"description": "Active Context Pruning (ACP) for the DeepSeek Harness — model-driven context management as a CompactionEngine backend.",
+	"keywords": [
+		"deepseek",
+		"harness",
+		"dsh",
+		"dsh-plugin",
+		"acp",
+		"context-management",
+		"context-compression",
+		"llm",
+		"agent",
+		"compaction"
+	],
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -13,11 +25,17 @@
 	},
 	"files": [
 		"dist",
+		"cordis.patch.yml",
 		"README.md",
 		"README.en.md",
 		"LICENSE"
 	],
 	"sideEffects": false,
+	"dsh": {
+		"bundle": {
+			"patch": "./cordis.patch.yml"
+		}
+	},
 	"license": "MIT",
 	"engines": {
 		"node": ">=20"