dsh-compact-relay 0.3.2 → 0.3.4

package/lib/actions/support.js

@@ -0,0 +1,76 @@
+/**
+ * 动作层胶水 —— 多个动作共用的「运行时细节」，不含业务判断。
+ *
+ * 以前这些片段在 actions/better-compact.js 与 actions/handoff.js 里各写一遍
+ * （test-compact 也有一份信号组合），而且取消语义必须一致：
+ * 用户取消 ↔ 网络错误 ↔ 已提交/落盘状态不明的错误，文案与错误码不能各说各话。
+ *
+ * 放 actions 层（不是 core/dsh）：这里要碰 deps.inflight（动作登记表）和
+ * core/errors 的错误包装，是「动作怎么跑」的公共约定，不是纯函数能力。
+ */
+import { actionError } from '../core/errors.js';
+
+/**
+ * 组合两个 AbortSignal（任一为 undefined 时直接返回另一个）。
+ *
+ * 用途：用户取消信号（输入）与事务 idle 信号（runMaintenance 给的）合并；
+ * 交接里是「inflight 取消信号」与「命令信号」合并。
+ * @param {AbortSignal|undefined} a
+ * @param {AbortSignal|undefined} b
+ * @returns {AbortSignal|undefined}
+ */
+export function combinedSignal(a, b) {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return AbortSignal.any([a, b]);
+}
+
+/**
+ * 登记「进行中的动作」，拿 AbortController（取消按钮真正能 abort 模型调用）。
+ * deps.inflight 是可选的（测试/旧装配没有就不登记）。
+ * @param {{inflight?:object}} deps
+ * @param {string} agentId
+ * @param {'compact'|'handoff'} kind
+ * @returns {AbortController|null}
+ */
+export function beginInflight(deps, agentId, kind) {
+  return deps.inflight !== undefined && typeof deps.inflight.begin === 'function'
+    ? deps.inflight.begin(agentId, kind)
+    : null;
+}
+
+/**
+ * 注销进行中的动作（必须放 finally，任何失败/取消都不能把登记漏在表里）。
+ * @param {{inflight?:object}} deps
+ * @param {string} agentId
+ * @param {AbortController|null} controller
+ */
+export function finishInflight(deps, agentId, controller) {
+  if (controller !== null && typeof deps.inflight.finish === 'function') {
+    deps.inflight.finish(agentId, controller);
+  }
+}
+
+/**
+ * 取消收口：信号已中止、但错误不是「取消/已提交/落盘不明」时，统一包装成
+ * cancelled（宿主 HTTP 层据此回「历史没改」）。
+ *
+ * P2-1：commit/persistence 表示历史可能已改或落盘状态不明，绝不能谎报「历史没改」；
+ * 这类错误原样抛出。返回错误给调用方 throw（保持各自 try/catch 结构不变）。
+ *
+ * @param {unknown} error 原始错误
+ * @param {AbortSignal|undefined} signal 合并后的信号
+ * @param {string} message 该动作的取消文案（用户可见，调用方给）
+ * @returns {unknown} 要抛出的错误
+ */
+export function cancelErrorOf(error, signal, message) {
+  if (
+    signal?.aborted === true &&
+    error?.code !== 'cancelled' &&
+    error?.code !== 'commit' &&
+    error?.code !== 'persistence'
+  ) {
+    return actionError('cancelled', message, error);
+  }
+  return error;
+}

package/lib/actions/test-compact.js

@@ -7,20 +7,12 @@
 import { actionError } from '../core/errors.js';
 import { TEST_INSTRUCTION } from '../core/prompts.js';
 import { selectTestRange } from '../core/ranges.js';
-import { replaceRangeWithSummary } from '../dsh/compact-transaction.js';
-import { runIdle } from '../dsh/idle.js';
+import { sumShadowedTokens } from '../core/tokens.js';
 import { measurePressure } from '../dsh/pressure.js';
 import { firstCompactableIdx } from '../dsh/session-view.js';
-import { summarize } from '../dsh/summarizer.js';
+import { runCompaction } from './compact-run.js';
 import { withLock } from './lock.js';
 
-function tokenCountOf(nodes, shadowedSeqs) {
-  const wanted = new Set(shadowedSeqs);
-  return nodes
-    .filter((node) => wanted.has(node.seq))
-    .reduce((sum, node) => sum + (node.heuristicTokens ?? node.tokens ?? 0), 0);
-}
-
 /**
  * @param {{ctx:object, cfg:object, lock:object, engine:object}} deps
  * @param {{agent:object, signal?:AbortSignal, confirm?:boolean, commandId?:string}} input
@@ -44,7 +36,7 @@ export async function testCompact(deps, { agent, signal, confirm = false, comman
       throw actionError('range', '找不到配对平衡的小范围（会话太短，或工具有未配对调用）');
     }
 
-    const shadowedTokenCount = tokenCountOf(nodes, range.shadowedSeqs);
+    const shadowedTokenCount = sumShadowedTokens(nodes, range.shadowedSeqs);
     const freshRange = { ...range, shadowedTokenCount };
 
     if (!confirm) {
@@ -58,36 +50,15 @@ export async function testCompact(deps, { agent, signal, confirm = false, comman
       };
     }
 
-    const flush =
-      typeof deps.ctx.sessions?.flush === 'function' ? () => deps.ctx.sessions.flush(session) : undefined;
-    const estimateMessage =
-      typeof deps.ctx?.tokenMeter?.estimateMessage === 'function'
-        ? (message) => deps.ctx.tokenMeter.estimateMessage(message)
-        : undefined;
-
-    const outcome = await runIdle(agent, (idleSignal) => {
-      const combined = signal === undefined ? idleSignal : AbortSignal.any([signal, idleSignal]);
-      return replaceRangeWithSummary({
-        session,
-        range: freshRange,
-        engine: deps.engine,
-        signal: combined,
-        sourceCommandId: commandId,
-        estimateMessage,
-        summarize: ({ shadowedSeqs, signal: innerSignal }) =>
-          summarize({
-            ctx: deps.ctx,
-            engine: deps.engine,
-            agent,
-            shadowedSeqs,
-            endSeq: freshRange.endSeq,
-            instruction: TEST_INSTRUCTION,
-            requiredSections: [], // /bctest 是短段落摘要，不做六段校验
-            maxTokens: deps.cfg.summary.maxTokens,
-            signal: innerSignal,
-          }),
-        flush,
-      });
+    // 和正式精压走同一条执行路径，只是范围小、摘要指令不同、不做六段校验。
+    const outcome = await runCompaction(deps, {
+      agent,
+      session,
+      range: freshRange,
+      instruction: TEST_INSTRUCTION,
+      requiredSections: [], // /bctest 是短段落摘要，不做六段校验
+      signal,
+      commandId,
     });
 
     return {

package/lib/adapters/http.js

@@ -205,7 +205,8 @@ export function registerHttp(webCtx, deps) {
           }
           const limit = Number(url.searchParams.get('limit') ?? 20);
           const listed = listHandoffDocs(deps, { limit });
-          return send(res, 200, { ok: true, dir: listed.dir, items: listed.items });
+          // 0.3.4（BUG-006）：带 total（全量份数），客户端据此显示「共 N 份」/加载更多。
+          return send(res, 200, { ok: true, dir: listed.dir, items: listed.items, total: listed.total });
         } catch (error) {
           try {
             send(res, 500, { ok: false, message: errorText(error) });

package/lib/adapters/prompt.js

@@ -0,0 +1,72 @@
+/**
+ * 模型入口（0.3.4）——「当前在可压缩区间」的动态提示。
+ *
+ * BUG-010：0.3.1 的 `mark_stage` 工具在 427 个真实会话里 0 次调用。根因不是模型
+ * 不听话，而是工具描述承诺「系统会告诉你容量」但系统从没说过 —— 条件不可判断。
+ * 现在宿主每轮把一条 runtime context 注入 system prompt，告诉模型当前容量落在
+ * 可压缩区间；模型据此判断「刚完成一个自然节点」时该不该调 `mark_compress_point`。
+ *
+ * 约束：
+ *  - `systemPrompt.context` 的 text 回调必须是**同步**函数 → 只读
+ *    `dsh/state-hub.js` 维护的内存缓存，不 await、不 measure；
+ *  - 拿不到会话/缓存/阈值就返回空串（宿主不会展示空 context）；
+ *  - 全程 try/catch：提示是锦上添花，任何异常都不能影响宿主组装 prompt。
+ */
+import {
+  COMPRESS_CUE_NAME,
+  COMPRESS_CUE_ORDER,
+  compressCueText,
+} from '../core/compress-cue.js';
+import { compressionMinRatio } from '../core/policy.js';
+
+/** 供测试/文档引用的 context 名称。 */
+export { COMPRESS_CUE_NAME };
+
+/**
+ * 计算某个 agent 本轮该显示的动态提示（同步、异常安全）。
+ * @param {{context?:object, deps?:object, hub?:object}} input
+ *   context 是宿主传给 systemPrompt.context text 回调的对象（context.agent 是当前 agent）
+ * @returns {string} 提示文本；不适用/异常返回 ''
+ */
+export function compressCueFor({ context, deps, hub } = {}) {
+  try {
+    // 只认会话 id（agent.id 与 session.id 不同，缓存也按 sessionId 键控）。
+    const sessionId = context?.agent?.session?.id;
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return '';
+
+    const cached = hub?.latestState?.(sessionId);
+    if (cached === undefined || cached === null) return '';
+
+    const thresholds = deps?.cfg?.thresholds;
+    if (thresholds === null || typeof thresholds !== 'object') return '';
+    if (!Number.isFinite(thresholds.compactRatio)) return '';
+    if (!Number.isFinite(cached.ratio) || !Number.isFinite(cached.window) || cached.window <= 0) return '';
+
+    // 最小线是「配置值 vs 动态下限（保留尾部 + 最小可压 token）/窗口」的较大者（纯函数）。
+    const minRatio = compressionMinRatio(thresholds, deps?.cfg?.retention, cached.window);
+    return compressCueText({
+      ratio: cached.ratio,
+      minRatio,
+      compactRatio: thresholds.compactRatio,
+      compressHint: cached.compressHint ?? null,
+    });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 注册动态提示（root-scope，所有 agent 生效）。
+ * @param {object} ctx 根上下文（需要 systemPrompt 服务）
+ * @param {object} deps
+ * @param {object} hub createStateHub 的返回值（要 latestState）
+ * @returns {Function|undefined} disposer（没有 systemPrompt 服务时返回 undefined）
+ */
+export function registerCompressCue(ctx, deps, hub) {
+  if (typeof ctx?.systemPrompt?.context !== 'function') return undefined;
+  return ctx.systemPrompt.context({
+    name: COMPRESS_CUE_NAME,
+    order: COMPRESS_CUE_ORDER,
+    text: (context) => compressCueFor({ context, deps, hub }),
+  });
+}

package/lib/adapters/tool.js

@@ -1,8 +1,13 @@
 /**
- * 工具入口（0.3.1）—— 让模型判断「这里适合压缩」并记录一个断点。
+ * 工具入口（0.3.1，0.3.4 改名 mark_compress_point）—— 让模型记录一个「压缩节点」。
  *
  * 用户手动标记已删除（作者 2026-10-20 拍板）；现在只有模型这条自动判断路径，
  * 环上把判断位置画成「断点1」（正常区/压缩区分界）。
+ *
+ * BUG-010 复盘：旧描述 `mark_stage` 写「系统会告诉你容量」但系统从没说过，
+ * 模型无法判断条件 → 427 个真实会话 0 次调用。0.3.4 起由宿主每轮注入可压缩区间
+ * 提示（lib/adapters/prompt.js），工具描述只描述「它自己会做什么」：
+ * 服务端工具会返回当前容量并复核区间，太低/到线都拒绝且不改历史。
  */
 import { markCompressHint } from '../actions/compress-hint.js';
 import engine from '../dsh/engine.js';
@@ -14,14 +19,13 @@ import engine from '../dsh/engine.js';
 export function registerTool(ctx, deps) {
   ctx.tools.register(
     engine.defineTool({
-      name: 'mark_stage',
+      name: 'mark_compress_point',
       description:
-        '判断「这里适合压缩」并在指示灯上留一个断点（正常区/压缩区的分界）。' +
-        '只在同时满足以下条件时调用：① 当前上下文容量已经超过「最小压缩线」（低于它压缩不划算，系统会告诉你）；' +
-        '② 还没到「压缩线」（到了系统自己会标记）；③ 当前工作刚好到了一个自然的小节点——一个明确的任务/阶段刚完成，' +
-        '适合把之前的旧历史压成摘要、继续往下做。' +
-        '不要每个小步骤都调；不要为了凑数调用。每次判断只记一条，压缩或交接后旧记录自动失效。' +
-        '调用后告诉用户「我在当前进度处做了一个「这里适合压缩」的判断」。',
+        '记录一个「压缩节点」：在指示灯环上标出「这里适合把前面的旧历史压成摘要」。' +
+        '在你刚完成一个明确的任务/阶段、并且认为之后可以安全地压缩旧历史继续往下做时调用。' +
+        '不确定当前是否合适时也可以调用：工具会返回当前上下文容量并做判断，' +
+        '容量太低（压缩不划算）或已经到压缩线（直接建议用户压缩即可）会被拒绝，拒绝不会改动任何历史。' +
+        '不需要每个小步骤都调用。每次判断只记一条，压缩或交接后旧记录自动失效。',
       parameters: {},
       output: {
         schema: { type: 'string' },