@apollo-music/dsh-sidecar-terms 0.1.4 → 0.1.7

package/README.md

@@ -7,18 +7,23 @@
 3. 默认对新增命中即时调用 `/resolve`，并只投递尚未出现的原文 `term_delta + rule_delta`；
 4. `tools/post-execute` 在下一次模型生成前 await 工具结果解析，`agent/pre-step` 与 `agent/turn-stopping` 继续作为边界 flush；
 5. request 尚未固定时 inject，step 已开始或已有候选回答时 steer；
-6. steer 修订后不再审计同一 turn 的后续 assistant 输出，避免规则回执自我触发；下一 turn 自动恢复；
+6. 同一上下文周期内，steer 修订后不再审计同一 turn 的后续 assistant 输出，避免规则回执自我触发；下一 turn 自动恢复，压缩后按新周期重建；
 7. 最终答案前只 steer 尚未交付的 canonical term / Rule delta。
 8. Catalog、Resolver、鉴权或网络不可用时失败关闭，不生成离线替代规则。
+9. 压缩或裁剪上下文后，以 `session.deriveMessages()` 返回的当前可见消息重新匹配、重建 audit/inject 计数；仅补回仍有命中且提示词已不在上下文里的 term/rule。
+10. 超过 Resolver 单段上限的消息只在术语审计传输层无损分段；超过 100 段文本或 200 个候选词时分批查询，全部成功后合并投递。DSH 交给模型的原消息不变。
 
 插件固定只读 `https://apollomusic-poc1.fde0.com/kb/terminology`。`apiUrl` 不再是运行时配置项，线上服务返回 `degraded` 也会按错误处理；插件不包含本地术语表或 P0 fallback。
 
 ## 安装
 
-在 DeepSeek Harness 项目中安装：
+当前版本为 `0.1.7`，对应 DeepSeek Harness `0.1.7-rc.2`。
+旧版 `0.1.5` 对应 DSH `0.1.1-rc.2`，升级插件时需同步升级宿主；`0.1.6` 是未发布的源码过渡版本。
+
+在对应版本的 DeepSeek Harness 项目中安装：
 
 ```bash
-npm install @apollo-music/dsh-sidecar-terms@0.1.4
+npm install @apollo-music/dsh-sidecar-terms@0.1.7
 ```
 
 ## 配置
@@ -54,6 +59,9 @@ npm ci
 npm run build:harness-plugin
 ```
 
+发布前可在构建后运行 `npm pack ./integrations/deepseek-harness --ignore-scripts`，
+将生成的 `.tgz` 安装到 DSH 测试项目；这不会发布 npm。
+
 凭据示例：
 
 ```bash
@@ -74,7 +82,30 @@ export APOLLO_TERMINOLOGY_READ_API_KEY='<READ_ONLY_API_KEY>'
 
 `auditReasoning: true` 只匹配每个 step 已提交的完整 reasoning block；流式 `reasoning-delta` 不参与匹配。thinking 原文只发送给 Resolver 做瞬时匹配，不会回注给模型。若部署边界不允许 thinking 离开 Harness 进程，可设为 `false`。
 
-该插件声明依赖 `agents`、`sessions` 与 `tools`；Cordis 会等相关服务存在后再加载。官方 Harness 目前仍处于 Developer Preview，本项目锁定并测试 `0.1.1-rc.2` 的公开 `Agent`、`session/event`、`tools/post-execute`、`agent/pre-step`、`agent/turn-stopping` 接口。包清单显式声明这一组接口的完整 DSH peer 闭包，避免依赖宿主包管理器自动补齐隐式 peer。
+该插件声明依赖 `agents`、`sessions` 与 `tools`；Cordis 会等相关服务存在后再加载。本项目锁定并测试 DSH `0.1.7-rc.2` 的公开 `Agent`、`session/event`、`agent/assistant-stream`、`tools/post-execute`、`agent/pre-step`、`agent/request`、`agent/turn-stopping` 接口。包清单显式声明这一组接口的完整 DSH peer 闭包，避免依赖宿主包管理器自动补齐隐式 peer。
+
+`0.1.6` 使用独立的消息来源 `plugin:apollo-terminology-rules`，与上游将旧插件消息迁移到 v4 会话格式后的来源一致。工具结果现在由 `role: tool` 消息承载；若另一插件替换 canonical `value`，本插件等待 DSH 渲染并提交 `tool/result` 后在 pre-step 审计，不匹配已被替换的旧内容。pre-step 增量保留上游 `startsRequestSeries` 等准入字段。
+
+## 压缩后的重新计数（0.1.7）
+
+这里的“重新计数”指重新建立命中、已投递集合和 audit/inject 指针，不是重新计算模型 token 用量，也不改变 DSH 的压缩策略。
+
+- 摘要、未压缩的近期消息和本轮即将准入的用户消息参与重新匹配；已被替换的原始日志不参与。启动/恢复会话也使用同一可见上下文入口。
+- 自身完整保留的 term/rule 提示词继续算已投递；被压掉且仍有命中的提示词在下一次模型请求前补回。被压掉且不再命中的内容不会复活，自身提示词也不反向触发新命中。
+- 新提示词的来源元数据记录 term/rule ID 和正文 SHA-256；正文被裁剪或修改后不沿用旧回执。摘要里提到某条规则不等于完整规则仍在。保留的 0.1.6 原文提示词按已有来源和固定格式读取 ID。
+- 每次替换开启独立 `contextEpoch`，双指针使用该轮上下文内的递增序号；不把重排后的原日志 seq 当作增量水位。压缩前未完成的查询结果作废，队列里过期的本插件增量移除，其他输入不动。
+- 普通压缩在 `agent/pre-step` 重建；上下文溢出后的同一步重试由 `agent/request` 兜底，在请求构建前提交增量，不改写 provider 请求。已生成候选答案时，最终门禁仍只 steer 剩余增量。
+- 重建必须完成后才能继续生成，不受 `queryIntervalMs` 或普通 `flushOnPreStep: false` 的延迟设置影响；查询失败则阻止该次生成。默认开启的最终门禁维持原有语义。
+
+实现不依赖具体 compaction 插件，而是监听公开的会话 surface replacement。完整设计、一手上游依据和验证记录见仓库 [`docs/DSH_CONTEXT_RECOUNT.md`](https://github.com/fde0-inc/apollo-terminology-knowledge-base/blob/main/docs/DSH_CONTEXT_RECOUNT.md)。
+
+## 验证
+
+无凭据的真实 DSH 运行时回归已纳入 `npm test`（模型和 API 均为测试数据，不联网）：
+
+```bash
+npx tsx --test tests/harness-runtime.test.ts
+```
 
 配置线上只读凭据后验证：
 

package/dist/coordinator.d.ts

@@ -1,6 +1,13 @@
 import { type UserMessage } from "@deepseek-ai/dsh-llm";
 import { TerminologyApi } from "./api.js";
 import type { AgentPort, LoggerPort, PluginConfig, ResolveResponse } from "./types.js";
+/**
+ * Split one audited message for the resolver transport without changing the
+ * message that DSH sends to the model. Chunks preserve order and concatenate
+ * exactly to the original text; natural or serialized-JSON boundaries are
+ * preferred so a multi-word terminology match is not cut unnecessarily.
+ */
+export declare function splitResolverText(text: string): string[];
 interface AuditItem {
     eventSeq: number;
     source: string;
@@ -14,8 +21,14 @@ export declare class TerminologyCoordinator {
     constructor(config: PluginConfig, api: TerminologyApi, logger: LoggerPort);
     attach(agent: AgentPort): void;
     disposeAgent(agent: AgentPort): void;
+    /** Retire all asynchronous work belonging to the now-shadowed context. */
+    invalidateContext(agent: AgentPort): void;
+    /** Start a fresh accounting epoch, crediting only intact visible receipts. */
+    resetContext(agent: AgentPort, retained: readonly UserMessage[]): void;
     dispose(): void;
     observe(agent: AgentPort, item: AuditItem): void;
+    /** Runtime accounting uses an epoch-local sequence, not reordered log seqs. */
+    observeNext(agent: AgentPort, item: Omit<AuditItem, "eventSeq">): void;
     setStepPhase(agent: AgentPort, activeStep: boolean, generationStarted?: boolean): void;
     beginTurn(agent: AgentPort): void;
     shouldAuditAssistant(agent: AgentPort): boolean;
@@ -26,6 +39,7 @@ export declare class TerminologyCoordinator {
     flush(agent: AgentPort, forceSteer?: boolean): Promise<void>;
     flushForPreStep(agent: AgentPort): Promise<UserMessage[]>;
     pointers(agent: AgentPort): {
+        contextEpoch: number;
         auditCursor: number;
         injectCursor: number;
         deliveredRuleIds: string[];

package/dist/coordinator.js

@@ -1,6 +1,67 @@
+import { createHash } from "node:crypto";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { findCatalogMatches } from "./matcher.js";
-const PLUGIN_NAME = "apollo-terminology-rules";
+// This also matches the source produced by DSH's v3-to-v4 session migration
+// for our previously published { kind: "plugin", plugin: "apollo-terminology-rules" }.
+const MESSAGE_SOURCE_KIND = "plugin:apollo-terminology-rules";
+const RESOLVER_TEXT_TARGET_CHARS = 90_000;
+const RESOLVER_MAX_SEGMENTS = 100;
+const RESOLVER_MAX_CANDIDATES = 200;
+const NATURAL_TEXT_BOUNDARIES = [
+    { needle: "\n\n", offset: 2 },
+    { needle: "\n", offset: 1 },
+    { needle: "},{\"", offset: 2 },
+    { needle: "\",\"", offset: 2 },
+    { needle: "。", offset: 1 },
+    { needle: "！", offset: 1 },
+    { needle: "？", offset: 1 },
+    { needle: ". ", offset: 2 },
+    { needle: "! ", offset: 2 },
+    { needle: "? ", offset: 2 },
+    { needle: "; ", offset: 2 },
+    { needle: "；", offset: 1 },
+    { needle: " ", offset: 1 },
+];
+/**
+ * Split one audited message for the resolver transport without changing the
+ * message that DSH sends to the model. Chunks preserve order and concatenate
+ * exactly to the original text; natural or serialized-JSON boundaries are
+ * preferred so a multi-word terminology match is not cut unnecessarily.
+ */
+export function splitResolverText(text) {
+    if (text.length <= RESOLVER_TEXT_TARGET_CHARS)
+        return [text];
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        const targetEnd = Math.min(start + RESOLVER_TEXT_TARGET_CHARS, text.length);
+        if (targetEnd === text.length) {
+            chunks.push(text.slice(start));
+            break;
+        }
+        const preferredStart = start + Math.floor(RESOLVER_TEXT_TARGET_CHARS * 0.75);
+        let end = 0;
+        for (const boundary of NATURAL_TEXT_BOUNDARIES) {
+            const index = text.lastIndexOf(boundary.needle, targetEnd - boundary.needle.length);
+            const candidate = index + boundary.offset;
+            if (index >= preferredStart && candidate > end)
+                end = candidate;
+        }
+        if (end <= start)
+            end = targetEnd;
+        // JavaScript string limits are measured in UTF-16 code units. Avoid
+        // placing a transport boundary between the halves of a surrogate pair.
+        const before = text.charCodeAt(end - 1);
+        const after = text.charCodeAt(end);
+        if (before >= 0xD800 && before <= 0xDBFF
+            && after >= 0xDC00 && after <= 0xDFFF) {
+            end -= 1;
+        }
+        chunks.push(text.slice(start, end));
+        start = end;
+    }
+    return chunks;
+}
 export class TerminologyCoordinator {
     config;
     api;
@@ -16,13 +77,35 @@ export class TerminologyCoordinator {
             this.states.set(agent, createState());
     }
     disposeAgent(agent) {
+        this.invalidateContext(agent);
+        this.states.delete(agent);
+    }
+    /** Retire all asynchronous work belonging to the now-shadowed context. */
+    invalidateContext(agent) {
         const state = this.states.get(agent);
         if (!state)
             return;
         state.disposed = true;
         if (state.queryTimer)
             clearTimeout(state.queryTimer);
-        this.states.delete(agent);
+    }
+    /** Start a fresh accounting epoch, crediting only intact visible receipts. */
+    resetContext(agent, retained) {
+        const epoch = (this.states.get(agent)?.contextEpoch ?? -1) + 1;
+        this.invalidateContext(agent);
+        const state = createState(epoch);
+        for (const message of retained) {
+            const receipt = readVisibleReceipt(message);
+            if (!receipt)
+                continue;
+            for (const id of receipt.ruleIds)
+                state.deliveredRuleIds.add(id);
+            for (const id of receipt.termIds)
+                state.deliveredTermIds.add(id);
+            if (receipt.metadata)
+                state.announcedMetadata = receipt.metadata;
+        }
+        this.states.set(agent, state);
     }
     dispose() {
         for (const agent of this.states.keys())
@@ -32,11 +115,17 @@ export class TerminologyCoordinator {
         const state = this.requireState(agent);
         if (state.disposed || item.eventSeq <= state.auditCursor)
             return;
+        state.nextAuditSeq = Math.max(state.nextAuditSeq, item.eventSeq + 1);
         state.auditQueue.push(item);
         state.processing = state.processing.then(() => this.drainAudit(agent, state)).catch((error) => {
             this.logger.warn("terminology audit deferred: %s", errorMessage(error));
         });
     }
+    /** Runtime accounting uses an epoch-local sequence, not reordered log seqs. */
+    observeNext(agent, item) {
+        const state = this.requireState(agent);
+        this.observe(agent, { ...item, eventSeq: state.nextAuditSeq });
+    }
     setStepPhase(agent, activeStep, generationStarted = false) {
         const state = this.requireState(agent);
         state.activeStep = activeStep;
@@ -62,6 +151,8 @@ export class TerminologyCoordinator {
     }
     confirmOwnMessage(agent, message) {
         const state = this.requireState(agent);
+        if (state.disposed)
+            return;
         const delivery = state.deliveries.get(String(message.id));
         if (!delivery)
             return;
@@ -97,6 +188,7 @@ export class TerminologyCoordinator {
     pointers(agent) {
         const state = this.requireState(agent);
         return {
+            contextEpoch: state.contextEpoch,
             auditCursor: state.auditCursor,
             injectCursor: state.injectCursor,
             deliveredRuleIds: [...state.deliveredRuleIds].sort(),
@@ -109,6 +201,8 @@ export class TerminologyCoordinator {
         if (state.auditQueue.length === 0 || state.disposed)
             return;
         const catalog = await this.api.getCatalog();
+        if (state.disposed)
+            return;
         while (state.auditQueue.length) {
             const item = state.auditQueue.shift();
             if (item.eventSeq <= state.auditCursor)
@@ -165,18 +259,52 @@ export class TerminologyCoordinator {
     async queryOnce(agent, state, mode, captured) {
         const segments = [...state.pendingSegments.values()].sort((a, b) => a.event_seq - b.event_seq);
         const throughSeq = segments.at(-1).event_seq;
+        const resolverSegments = segments.flatMap(({ event_seq, source, text }) => splitResolverText(text).map((chunk) => ({ event_seq, source, text: chunk })));
+        const candidates = [...new Set(segments.flatMap((segment) => segment.candidates ?? []))];
         for (const segment of segments)
             state.pendingSegments.delete(segment.event_seq);
         state.lastQueryAt = Date.now();
         try {
-            const response = await this.api.resolve({
-                session_id: agent.id,
-                audit_through_seq: throughSeq,
-                segments: segments.map(({ event_seq, source, text }) => ({ event_seq, source, text })),
-                candidate_terms: [...new Set(segments.flatMap((segment) => segment.candidates ?? []))],
-                delivered_rule_ids: this.knownRuleIds(state),
-                delivered_term_ids: this.knownTermIds(state),
-            });
+            // A whole-context recount can exceed either transport array limit. Hold
+            // every batch until all succeed; a failed/stale batch cannot partly
+            // advance delivery accounting or leave a half-rebuilt prompt behind.
+            const ruleIds = new Set(this.knownRuleIds(state));
+            const termIds = new Set(this.knownTermIds(state));
+            const rules = new Map();
+            const terms = new Map();
+            let response;
+            const batchCount = Math.max(Math.ceil(resolverSegments.length / RESOLVER_MAX_SEGMENTS), Math.ceil(candidates.length / RESOLVER_MAX_CANDIDATES));
+            for (let batch = 0; batch < batchCount; batch += 1) {
+                const batchSegments = resolverSegments.slice(batch * RESOLVER_MAX_SEGMENTS, (batch + 1) * RESOLVER_MAX_SEGMENTS);
+                const partial = await this.api.resolve({
+                    session_id: agent.id,
+                    audit_through_seq: throughSeq,
+                    // Extra candidate batches still require one non-empty segment.
+                    segments: batchSegments.length ? batchSegments : resolverSegments.slice(0, 1),
+                    candidate_terms: candidates.slice(batch * RESOLVER_MAX_CANDIDATES, (batch + 1) * RESOLVER_MAX_CANDIDATES),
+                    delivered_rule_ids: [...ruleIds].sort(),
+                    delivered_term_ids: [...termIds].sort(),
+                });
+                if (state.disposed)
+                    return;
+                for (const rule of partial.rule_delta) {
+                    rules.set(rule.rule_id, rule);
+                    ruleIds.add(rule.rule_id);
+                }
+                for (const term of partial.term_delta ?? []) {
+                    terms.set(term.term_id, term);
+                    termIds.add(term.term_id);
+                }
+                response = {
+                    ...partial,
+                    hits: [...response?.hits ?? [], ...partial.hits],
+                    unresolved: [...response?.unresolved ?? [], ...partial.unresolved],
+                    rule_delta: [...rules.values()],
+                    term_delta: [...terms.values()],
+                };
+            }
+            if (!response)
+                return;
             const checkpoint = {
                 throughSeq,
                 complete: response.rule_delta.length === 0 && (response.term_delta?.length ?? 0) === 0,
@@ -193,6 +321,8 @@ export class TerminologyCoordinator {
             this.logger.debug("terminology resolved through seq %d: %d hit(s), %d new term(s), %d new rule(s)", throughSeq, response.hits.length, response.term_delta?.length ?? 0, response.rule_delta.length);
         }
         catch (error) {
+            if (state.disposed)
+                return;
             for (const segment of segments)
                 state.pendingSegments.set(segment.event_seq, segment);
             throw error;
@@ -200,9 +330,20 @@ export class TerminologyCoordinator {
     }
     dispatch(agent, state, response, checkpoint, mode) {
         const metadataUpdate = metadataDelta(state.announcedMetadata, response);
+        const text = renderDelta(response, metadataUpdate);
         const message = createUserMessage({
-            content: [{ type: "text", text: renderDelta(response, metadataUpdate) }],
-            source: { kind: "plugin", plugin: PLUGIN_NAME, form: "instructions" },
+            content: [{ type: "text", text }],
+            source: {
+                kind: MESSAGE_SOURCE_KIND,
+                form: "instructions",
+                receipt: {
+                    version: 1,
+                    ruleIds: response.rule_delta.map((rule) => rule.rule_id),
+                    termIds: (response.term_delta ?? []).map((term) => term.term_id),
+                    ...metadataSnapshot(response),
+                    textSha256: textDigest(text),
+                },
+            },
         });
         const effectiveMode = mode === "auto"
             ? (state.activeStep || state.generationStarted ? "steer" : "inject")
@@ -220,6 +361,8 @@ export class TerminologyCoordinator {
         return message;
     }
     promoteUnclaimedInjections(agent, state) {
+        if (state.disposed)
+            return;
         const pendingIds = new Set(agent.inbox.nextStep.map((message) => String(message.id)));
         for (const delivery of state.deliveries.values()) {
             if (delivery.mode === "steer" || delivery.mode === "capture")
@@ -264,10 +407,40 @@ export class TerminologyCoordinator {
     }
 }
 export function isOwnPluginMessage(message) {
-    return message.source.kind === "plugin" && message.source.plugin === PLUGIN_NAME;
+    return message.source.kind === MESSAGE_SOURCE_KIND;
+}
+function readVisibleReceipt(message) {
+    if (message.source.kind !== MESSAGE_SOURCE_KIND)
+        return;
+    if (message.content.length !== 1 || message.content[0].type !== "text")
+        return;
+    const text = message.content[0].text;
+    const receipt = message.source.receipt;
+    if (receipt !== undefined) {
+        if (receipt.version !== 1 || receipt.textSha256 !== textDigest(text))
+            return;
+        return {
+            ruleIds: receipt.ruleIds,
+            termIds: receipt.termIds,
+            metadata: { kbVersion: receipt.kbVersion, catalogRevision: receipt.catalogRevision },
+        };
+    }
+    // 0.1.6 receipts had only our producer kind and the canonical text framing.
+    // Never infer delivered IDs from a summary, user text, or another producer.
+    if (!text.startsWith("[阿波罗术语库：原文增量]\n"))
+        return;
+    return {
+        ruleIds: [...text.matchAll(/^- \[P[01]\] (RULE-[A-Z0-9-]+): /gmu)].map((match) => match[1]),
+        termIds: [...text.matchAll(/^- \[术语 (TERM-[A-Z0-9-]+) \/ (?:locked|contextual|pending|deprecated)\] /gmu)].map((match) => match[1]),
+    };
+}
+function textDigest(text) {
+    return createHash("sha256").update(text).digest("hex");
 }
-function createState() {
+function createState(contextEpoch = 0) {
     return {
+        contextEpoch,
+        nextAuditSeq: 0,
         auditCursor: -1,
         injectCursor: -1,
         auditQueue: [],

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export declare const inject: string[];
 export type Config = PluginConfig;
 export declare const Config: Schema<Config>;
 export declare function apply(ctx: Context, config: Config): void;
-export declare function messageText(message: Message, auditReasoning?: boolean): string;
+export declare function messageText(message: Message, auditReasoning?: boolean, auditToolArguments?: boolean): string;
 export { APOLLO_TERMINOLOGY_API_URL, TerminologyApi } from "./api.js";
 export { TerminologyCoordinator } from "./coordinator.js";
 export { findCatalogMatches, normalizeMatchKey } from "./matcher.js";

package/dist/index.js

@@ -23,11 +23,18 @@ export function apply(ctx, config) {
     const agentsBySession = new Map();
     const attach = (agent) => {
         coordinator.attach(agent);
-        agentsBySession.set(agent.session, agent);
-        for (const event of agent.session.events)
-            observeEvent(agent, event);
+        // Resume from the model-visible projection, never from shadowed raw events.
+        agentsBySession.set(agent.session, { agent, needsRecount: true, seenMessages: new Set(), offered: [] });
     };
     const observeEvent = (agent, event) => {
+        const binding = agentsBySession.get(agent.session);
+        if ("surfaceOp" in event && event.surfaceOp !== "append" && event.type !== "system/message") {
+            // Summary compaction and tool pruning both commit through this seam.
+            // Invalidate synchronously so a late old-context response cannot steer.
+            binding.needsRecount = true;
+            coordinator.invalidateContext(agent);
+            return;
+        }
         switch (event.type) {
             case "turn/start":
                 coordinator.beginTurn(agent);
@@ -41,35 +48,28 @@ export function apply(ctx, config) {
             case "step/end":
                 coordinator.endStep(agent);
                 return;
-            case "assistant/chunk": {
-                const chunk = event.data.chunk;
-                if (chunk.type === "text-delta" || chunk.type === "reasoning-delta" || chunk.type === "tool-call-delta") {
-                    coordinator.markGenerationStarted(agent);
-                }
-                return;
-            }
             case "user/message": {
                 const message = event.data;
+                binding.offered = binding.offered.filter((offered) => offered.id !== message.id);
                 if (isOwnPluginMessage(message)) {
                     coordinator.confirmOwnMessage(agent, message);
                     return;
                 }
-                enqueueMessage(agent, event.seq, "user", message);
+                enqueueMessage(agent, "user", message);
                 return;
             }
             case "assistant/message":
                 coordinator.markGenerationStarted(agent);
                 if (coordinator.shouldAuditAssistant(agent)) {
-                    enqueueMessage(agent, event.seq, "assistant", event.data.message);
+                    enqueueMessage(agent, "assistant", event.data.message);
                 }
                 return;
             case "tool/result":
-                enqueueMessage(agent, event.seq, "tool_result", event.data.message);
+                enqueueMessage(agent, "tool_result", event.data.message);
                 return;
             case "tool/call":
-                if (config.auditToolArguments) {
-                    coordinator.observe(agent, {
-                        eventSeq: event.seq,
+                if (config.auditToolArguments && !binding.needsRecount) {
+                    coordinator.observeNext(agent, {
                         source: "tool_call",
                         text: `${event.data.name}\n${event.data.arguments}`,
                     });
@@ -79,32 +79,94 @@ export function apply(ctx, config) {
                 return;
         }
     };
-    const enqueueMessage = (agent, eventSeq, source, message) => {
-        const text = messageText(message, config.auditReasoning);
+    const enqueueMessage = (agent, source, message, auditArguments = false) => {
+        const binding = agentsBySession.get(agent.session);
+        if (binding.needsRecount || binding.seenMessages.has(String(message.id)))
+            return;
+        binding.seenMessages.add(String(message.id));
+        const text = messageText(message, config.auditReasoning, auditArguments);
         if (text)
-            coordinator.observe(agent, { eventSeq, source, text });
+            coordinator.observeNext(agent, { source, text });
+    };
+    const recount = async (agent, offered, signal, capture = true) => {
+        const binding = agentsBySession.get(agent.session);
+        let messages = offered;
+        let additions = [];
+        let rebuilt = false;
+        try {
+            while (binding.needsRecount) {
+                signal.throwIfAborted();
+                const retained = agent.session.deriveMessages();
+                const retainedIds = new Set(retained.map((message) => message.id));
+                messages = messages.filter((message) => !isOwnPluginMessage(message) && !retainedIds.has(message.id));
+                coordinator.resetContext(agent, retained.filter((message) => message.role === "user" && isOwnPluginMessage(message)));
+                binding.seenMessages.clear();
+                binding.needsRecount = false;
+                // The offered batch has already left the inbox; remove only remaining
+                // sidecar messages there. Recompute their relevance from retained input.
+                for (const pending of [...agent.inbox.nextStep]) {
+                    if (isOwnPluginMessage(pending))
+                        agent.inbox.remove(pending.id);
+                }
+                for (const message of [...retained, ...messages]) {
+                    if (message.role === "user" && isOwnPluginMessage(message))
+                        continue;
+                    enqueueMessage(agent, `context_${message.role}`, message, config.auditToolArguments);
+                }
+                if (capture)
+                    additions = await coordinator.flushForPreStep(agent);
+                else
+                    await coordinator.flush(agent, true);
+                signal.throwIfAborted();
+                rebuilt = true;
+                // Another replacement while querying requires another fresh snapshot.
+            }
+        }
+        catch (error) {
+            binding.needsRecount = true;
+            coordinator.invalidateContext(agent);
+            throw error;
+        }
+        return { messages, additions, rebuilt };
     };
     for (const agent of ctx.agents.list())
         attach(agent);
-    ctx.on("agent/created", ({ agent }) => attach(agent));
+    ctx.on("agent/created", ({ agent }) => {
+        attach(agent);
+        return undefined;
+    });
     ctx.on("agent/disposed", ({ agent }) => {
         agentsBySession.delete(agent.session);
         coordinator.disposeAgent(agent);
     });
     ctx.on("agent/inbox/discarded", ({ agent, message }) => coordinator.markDiscarded(agent, message));
+    ctx.on("agent/assistant-stream", ({ agent, frame }) => {
+        if (frame.type !== "chunk")
+            return;
+        const chunk = frame.chunk;
+        if (chunk.type === "text-delta" || chunk.type === "reasoning-delta" || chunk.type === "tool-call-delta") {
+            coordinator.markGenerationStarted(agent);
+        }
+    });
     ctx.on("tools/post-execute", async (exec, result, next) => {
         const decision = await next();
         const agent = exec.agent;
         if (!agent)
             return decision;
+        if (agentsBySession.get(agent.session)?.needsRecount)
+            return decision;
+        // A canonical value replacement is rendered by the registry after this
+        // waterfall. Audit its committed tool/result at the next pre-step instead
+        // of matching stale content or invoking the tool's renderer a second time.
+        if (decision.kind === "accept" && "value" in decision)
+            return decision;
         const content = decision.kind === "block"
             ? decision.feedback
             : decision.content ?? result.content;
         const text = content.flatMap((block) => blockText(block, config.auditReasoning)).filter(Boolean).join("\n").trim();
         if (!text)
             return decision;
-        coordinator.observe(agent, {
-            eventSeq: Math.max(agent.session.seq, coordinator.pointers(agent).auditCursor + 1),
+        coordinator.observeNext(agent, {
             source: "tool_result",
             text,
         });
@@ -117,30 +179,43 @@ export function apply(ctx, config) {
         };
     });
     ctx.on("session/event", (session, event) => {
-        const agent = agentsBySession.get(session);
-        if (agent)
-            observeEvent(agent, event);
+        const binding = agentsBySession.get(session);
+        if (binding)
+            observeEvent(binding.agent, event);
     });
     ctx.on("agent/pre-step", async (payload, next) => {
         const decision = await next();
         if (decision.kind === "reject")
             return decision;
         coordinator.setStepPhase(payload.agent, false, false);
-        const baseSeq = payload.agent.session.seq;
-        decision.messages.forEach((message, index) => {
+        const prepared = await recount(payload.agent, decision.messages, payload.signal);
+        const binding = agentsBySession.get(payload.agent.session);
+        binding.offered = prepared.messages;
+        prepared.messages.forEach((message) => {
             if (!isOwnPluginMessage(message))
-                enqueueMessage(payload.agent, baseSeq + index, "pre_step", message);
+                enqueueMessage(payload.agent, "pre_step", message);
         });
-        if (!config.flushOnPreStep)
-            return decision;
-        const additions = await coordinator.flushForPreStep(payload.agent);
-        return additions.length
-            ? { kind: "enter", messages: [...decision.messages, ...additions] }
-            : decision;
+        const additions = prepared.rebuilt
+            ? prepared.additions
+            : config.flushOnPreStep ? await coordinator.flushForPreStep(payload.agent) : [];
+        return { ...decision, messages: [...prepared.messages, ...additions] };
+    });
+    ctx.on("agent/request", async ({ agent, signal }, next) => {
+        const route = await next();
+        // Context-overflow recovery retries within the same step, bypassing
+        // pre-step. Commit the rebuilt delta before the driver derives that request.
+        const binding = agentsBySession.get(agent.session);
+        const prepared = await recount(agent, binding.offered, signal);
+        for (const message of prepared.additions) {
+            signal.throwIfAborted();
+            agent.session.append("user/message", message, { surfaceOp: "append" });
+        }
+        return route;
     });
-    ctx.on("agent/turn-stopping", async ({ agent }) => {
+    ctx.on("agent/turn-stopping", async ({ agent, signal }) => {
         if (!config.flushOnTurnStopping)
             return;
+        await recount(agent, [], signal, false);
         await coordinator.flush(agent, true);
     });
     ctx.effect(() => () => coordinator.dispose());
@@ -150,8 +225,10 @@ export function apply(ctx, config) {
         logger.warn("initial terminology catalog fetch failed; live events will retry: %s", error instanceof Error ? error.message : String(error));
     });
 }
-export function messageText(message, auditReasoning = true) {
-    return message.content.flatMap((block) => blockText(block, auditReasoning)).filter(Boolean).join("\n").trim();
+export function messageText(message, auditReasoning = true, auditToolArguments = false) {
+    return message.content.flatMap((block) => block.type === "tool-call" && auditToolArguments
+        ? [`${block.name}\n${block.arguments}`]
+        : blockText(block, auditReasoning)).filter(Boolean).join("\n").trim();
 }
 function blockText(block, auditReasoning) {
     if (block.type === "text")
@@ -160,8 +237,6 @@ function blockText(block, auditReasoning) {
     // Streaming reasoning-delta chunks are lifecycle signals and never enter here.
     if (block.type === "reasoning")
         return auditReasoning ? [block.text] : [];
-    if (block.type === "tool-result")
-        return block.content.flatMap((item) => blockText(item, auditReasoning));
     return [];
 }
 export { APOLLO_TERMINOLOGY_API_URL, TerminologyApi } from "./api.js";

package/dist/types.d.ts

@@ -1,4 +1,21 @@
 import type { UserMessage } from "@deepseek-ai/dsh-llm";
+export interface DeliveryReceipt {
+    version: 1;
+    ruleIds: string[];
+    termIds: string[];
+    kbVersion: string;
+    catalogRevision: number;
+    textSha256: string;
+}
+declare module "@deepseek-ai/dsh-llm" {
+    interface MessageSourceMap {
+        "plugin:apollo-terminology-rules": {
+            kind: "plugin:apollo-terminology-rules";
+            form: "instructions";
+            receipt?: DeliveryReceipt;
+        };
+    }
+}
 export interface PluginConfig {
     apiKeyEnv: string;
     queryIntervalMs: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollo-music/dsh-sidecar-terms",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "DeepSeek Harness sidecar plugin for incremental Apollo terminology and rule injection",
   "type": "module",
   "main": "dist/index.js",
@@ -40,20 +40,27 @@
     "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-brand": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-code-runtime": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-user-approval": "0.1.1-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-storage": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-timeout": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-workspace": "0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "~3.18.4"
   }
 }