@zhushanwen/session-delivery 0.10.0

package/README.md

@@ -0,0 +1,55 @@
+# @zhushanwen/session-delivery
+
+Session 消息投递内核：零 pi 依赖的策略层，负责排队、合批、去重与 gated flush。
+
+## 设计原则
+
+- **零 pi 依赖**：内核不 import pi 包任何符号。steer/followUp/triggerTurn/streamingBehavior 等 pi 词汇封闭在两侧适配器内。
+- **端口注入**：`DeliveryPort` 是内核与外部世界的唯一接口（isIdle / hasPendingMessages / send / subscribeSettled），调用方负责注入运行时能力。
+- **意图驱动**：调用方声明投递意图（`DeliveryIntent`），内核处理与目标 session 运行状态的冲突。intent → pi 参数的翻译在适配器内。
+
+## 接口
+
+```ts
+import { createDelivery, type DeliveryHandle, type DeliveryPort, type DeliveryConfig } from '@zhushanwen/session-delivery'
+
+const handle = createDelivery(port, config)
+
+// 常规入口：入队 + 合批/去重/gated flush
+handle.send({ payload: { kind: 'text', content: 'hello' } })
+
+// 同步确认变体：入队 + 可达性确认
+await handle.sendChecked({ payload: { kind: 'text', content: 'hello' } })
+
+// 强制投递（shutdown / park 外部重触发 / settled 边沿内部复用）
+handle.flush()
+
+// 队列深度（诊断/测试）
+handle.depth()
+
+// 销毁（清空队列 + 清 timer）
+handle.dispose()
+```
+
+## 策略默认值
+
+| 策略 | 默认值 | 说明 |
+|------|--------|------|
+| `intent` | `'interrupt-at-turn-boundary'` | turn 边界抢占（F1 教训内化） |
+| `busyPolicy` | `'retry-force'` | settled 边沿驱动 flush + watch-dog 30s 复核；无订阅装配退化退避 {100ms, 50}≈5s 后强制发送 |
+| `mergeWindowMs` | `0` | 关；显式设值启用滑动窗口合批 |
+| `backoff` | `{ ms: 100, max: 50 }` | 退避参数 |
+| `watchdogMs` | `30_000` | watch-dog 复核间隔 |
+
+## 约束
+
+- **同 session 单例 handle**：多 handle 并发投递竞态无保护。runtime 装配层必须以 sessionId 为键做单例注册表；extension 侧同理。
+- **subscribeSettled 的退订语义由适配器负责兑现**。pi.on 返回 void 且无 off，适配器需用 disposed 标志包装。
+
+## 开发
+
+```bash
+cd packages/session-delivery
+npx vitest run        # 跑测试
+npx tsc --noEmit      # 类型检查
+```

package/dist/index.d.mts

@@ -0,0 +1,150 @@
+/**
+ * @zhushanwen/session-delivery 类型定义。
+ *
+ * 设计约束：
+ * - 零 pi 依赖：不出现 steer/followUp/triggerTurn/streamingBehavior 等 pi 词汇
+ * - 意图驱动：调用方声明 intent，内核处理与 session 运行状态的冲突
+ * - 判别联合 payload：适配器声明 supportedPayloads 能力
+ */
+/** 投递意图（D3）：turn 边界抢占 / run 结束后注入，均含 idle 唤醒语义。 */
+type DeliveryIntent = 'interrupt-at-turn-boundary' | 'after-run';
+/** 文本 payload（runtime 通路一期唯一支持）。 */
+interface TextPayload {
+    kind: 'text';
+    content: string;
+}
+/** custom message payload（extension 通路支持）。 */
+interface CustomPayload {
+    kind: 'custom';
+    customType: string;
+    content: string;
+    display: boolean;
+    details?: unknown;
+}
+/** 判别联合（D9）：envelope / payload 分离。 */
+type DeliveryPayload = TextPayload | CustomPayload;
+/** 投递消息 envelope。 */
+interface DeliveryMessage {
+    payload: DeliveryPayload;
+    /** 缺省回落 config.intent。 */
+    intent?: DeliveryIntent;
+    /** 去重 key（开 dedupe 时必填）。 */
+    dedupeKey?: string;
+    /** 持久性预留（一期仅 'in-memory'）。 */
+    durability?: 'in-memory';
+}
+/**
+ * port.send 的受理回执（U2 回执口径扩展位）。
+ *
+ * 受理 = 底层通道接受了消息（进入投递路径），**不等于送达事实**——送达判定由
+ * 调用方按自身回执锚点确认（如扩展侧扫描 custom_message entry）。旧 port 实现
+ * 返回 void 不受影响（void = 受理未知，按成功处理，与既有内核语义一致）。
+ */
+interface SendReceipt {
+    /** 受理结果。false = 底层显式拒绝（消息未进入任何通道，走错误重试路径）。 */
+    accepted: boolean;
+    /** 拒绝原因（accepted:false 时携带，进 warn 日志与 reject 链）。 */
+    reason?: string;
+}
+/** 内核与外部世界的唯一接口（D2 端口注入）。 */
+interface DeliveryPort {
+    /** 本通路支持的 payload kind（D9 fail-fast）。 */
+    supportedPayloads: readonly DeliveryPayload['kind'][];
+    /** 主 agent 是否空闲。 */
+    isIdle(): boolean;
+    /** 是否有排队中的消息。 */
+    hasPendingMessages(): boolean;
+    /**
+     * 投递消息（intent → pi 参数的翻译在适配器内部）。
+     * 返回受理回执（U2 扩展位）：显式 `{accepted:false}` = 受理失败（内核按发送失败
+     * 处理）；void / `{accepted:true}` = 受理成功。旧实现返回 void 兼容。
+     */
+    send(msg: DeliveryMessage, intent: DeliveryIntent): Promise<SendReceipt | void> | SendReceipt | void;
+    /** agent_settled 边沿订阅（D8）。缺省时内核退化退避轮询。返回退订函数。 */
+    subscribeSettled?(cb: () => void): () => void;
+}
+/** 内核配置（D4 策略默认值）。 */
+interface DeliveryConfig {
+    /** 默认意图：'interrupt-at-turn-boundary'（D3）。 */
+    intent?: DeliveryIntent;
+    /** busy 策略：'retry-force'（默认）/ 'park'。 */
+    busyPolicy?: 'retry-force' | 'park';
+    /** 合批窗口（ms）：0 = 关；>0 = 滑动窗口合批。 */
+    mergeWindowMs?: number;
+    /** 合批依赖谓词（D4 must-fix #1）。true 时 send() 走合批窗口，false/缺省时立即投。
+     *  禁止用 isIdle 代替。 */
+    mergeHoldActive?: () => boolean;
+    /** 退避参数。 */
+    backoff?: {
+        ms: number;
+        max: number;
+    };
+    /** watch-dog 复核间隔（ms）。默认 30_000。 */
+    watchdogMs?: number;
+    /** 去重配置（条数 LRU）。 */
+    dedupe?: {
+        maxKeys: number;
+    };
+    /**
+     * 投递终态信号（D4）。per-message 契约（ext-simplify-08 D1/B1）：批次内每条消息
+     * 各获一次终态回调，msg 为该条原始消息（非合批 composed 消息）；单消息批次行为
+     * 不变。回调循环边界：回调内 dispose() 后本批剩余条目不再回调（与 dispose「丢弃
+     * 队列不触发 onSettled」契约一致）；回调内再 send() 的新消息走标准 flush 管线
+     * （空闲时可能在回调栈内立即投递）、不参与本批回调循环（契约完备性登记：当前
+     * 消费方两种形态均零可达）。
+     */
+    onSettled?: (msg: DeliveryMessage, outcome: 'delivered' | 'rejected') => void;
+}
+/** 投递句柄（createDelivery 返回）。 */
+interface DeliveryHandle {
+    /** 唯一常规入口（D4 入口收敛）；合批窗口 + 空闲零延迟立即投。 */
+    send(msg: DeliveryMessage, opts?: {
+        merge?: boolean;
+    }): void;
+    /** 入队 + 可达性同步确认。reject = 入队失败。 */
+    sendChecked(msg: DeliveryMessage): Promise<void>;
+    /** 强制投递尝试（shutdown / park 外部重触发 / settled 边沿内部复用）。 */
+    flush(): void;
+    /** 队列深度（诊断/测试）。 */
+    depth(): number;
+    /** 销毁（清空队列 + 清 timer + 退订 settled）。 */
+    dispose(): void;
+}
+
+/**
+ * 投递内核实现：createDelivery。
+ *
+ * 核心行为（design.md §3.3 D4/D8）：
+ * - send() 入队 → dedupe → 合批窗口判定 → 立即投或窗口到期投
+ * - flush() → busy gate（isIdle + hasPendingMessages 双条件，G4）→ port.send
+ * - settled 边沿 → busy 复核通过 → flush；有订阅装配下 busy 只依赖边沿 + watch-dog（不退避强发）
+ * - watch-dog 低频复核（D8 兜底层①：settled 事件丢失的恢复路径）
+ * - port.send 失败 → 消息留在途、按 backoff 有限重试，达上限 settle rejected（D4 错误重试）
+ * - 终态上报 per-message（ext-simplify-08 D1/B1）：onSettled 对批次内每条消息各回调
+ *   一次，msg 为该条原始消息（非 composed 合批消息）；单消息批次行为不变
+ * - sendChecked() 统一经投递循环：resolve 挂钩 port.send 受理结果（busy 时经
+ *   streaming 受理入 pi 队列即回，以此确认可达）；首次受理失败即 reject（入口即拦）
+ * - in-flight 防重：单 handle 至多一个 port.send 在途
+ */
+
+/**
+ * U4 warn 出口注入（设计 docs/architecture/pi-boundary-reliability.md 附录 D §5 U4）：
+ * 装配方接 extensionLogger 使投递失败警告落 `<dataDir>/logs/`（console.warn 走
+ * stderr tee 不到日志盘——排查无痕）。通用包不硬依赖 taiji logger，故以可选注入
+ * 挂载；正式化并入 types.ts 的 DeliveryConfig 属领地外变更，暂以交叉类型承载。
+ */
+interface DeliveryWarnSink {
+    /** 投递失败/异常警告出口。缺省 console.warn（前缀 `[session-delivery]`）。 */
+    warn?: (msg: string, err?: unknown) => void;
+}
+/** createDelivery 配置（DeliveryConfig + warn 出口注入）。 */
+type DeliveryConfigWithWarn = DeliveryConfig & DeliveryWarnSink;
+/**
+ * 创建投递句柄。
+ *
+ * 约束：同 session 必须单例 handle（多 handle 并发投递竞态无保护）。
+ * subscribeSettled 的退订语义由适配器负责兑现。
+ */
+declare function createDelivery(port: DeliveryPort, config?: DeliveryConfigWithWarn): DeliveryHandle;
+
+export { type CustomPayload, type DeliveryConfig, type DeliveryHandle, type DeliveryIntent, type DeliveryMessage, type DeliveryPayload, type DeliveryPort, type SendReceipt, type TextPayload, createDelivery };

package/dist/index.mjs

@@ -0,0 +1,395 @@
+// src/lru.ts
+var LruSet = class {
+  constructor(maxKeys) {
+    this.maxKeys = maxKeys;
+    this.map = /* @__PURE__ */ new Map();
+  }
+  maxKeys;
+  map;
+  /** 是否已包含 key。命中后刷新 LRU 位置。 */
+  has(key) {
+    if (!this.map.has(key)) return false;
+    this.map.delete(key);
+    this.map.set(key);
+    return true;
+  }
+  /** 插入 key。超容量时淘汰最旧。 */
+  add(key) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxKeys) {
+      const first = this.map.keys().next().value;
+      if (first !== void 0) this.map.delete(first);
+    }
+    this.map.set(key);
+  }
+  /** 清空。 */
+  clear() {
+    this.map.clear();
+  }
+};
+
+// src/delivery.ts
+var DEFAULT_CONFIG = {
+  intent: "interrupt-at-turn-boundary",
+  busyPolicy: "retry-force",
+  mergeWindowMs: 0,
+  backoff: { ms: 100, max: 50 },
+  watchdogMs: 3e4
+};
+function isThenable(v) {
+  return !!v && typeof v.then === "function";
+}
+function buildBatchPayload(messages) {
+  if (messages.length === 1) return messages[0];
+  const contents = messages.map((m) => m.payload.content);
+  const content = contents.join("\n\n---\n\n");
+  const first = messages[0];
+  if (first.payload.kind === "custom") {
+    return {
+      ...first,
+      payload: {
+        kind: "custom",
+        customType: first.payload.customType,
+        content,
+        display: first.payload.display,
+        details: {
+          batch: true,
+          items: messages.map(
+            (m) => m.payload.kind === "custom" && m.payload.details !== void 0 ? m.payload.details : m.payload
+          )
+        }
+      }
+    };
+  }
+  return {
+    ...first,
+    payload: { kind: "text", content }
+  };
+}
+function settleChecked(batch, err, checkedPending) {
+  const rejected = /* @__PURE__ */ new Set();
+  if (checkedPending.length === 0) return rejected;
+  const batchSet = new Set(batch);
+  const kept = [];
+  for (const w of checkedPending) {
+    if (!batchSet.has(w.msg)) {
+      kept.push(w);
+      continue;
+    }
+    if (err === void 0) {
+      w.resolve();
+    } else {
+      w.reject(err);
+      rejected.add(w.msg);
+    }
+  }
+  checkedPending.length = 0;
+  checkedPending.push(...kept);
+  return rejected;
+}
+function safeIsIdle(port) {
+  try {
+    return port.isIdle();
+  } catch {
+    return false;
+  }
+}
+function isBusy(port) {
+  if (!safeIsIdle(port)) return true;
+  try {
+    return port.hasPendingMessages();
+  } catch {
+    return true;
+  }
+}
+function resolveWarnSink(config) {
+  return config?.warn ?? ((msg, err) => {
+    console.warn(`[session-delivery] ${msg}`, err ?? "");
+  });
+}
+function createDelivery(port, config) {
+  const cfg = {
+    ...DEFAULT_CONFIG,
+    ...config,
+    backoff: config?.backoff ?? DEFAULT_CONFIG.backoff
+  };
+  const queue = [];
+  const checkedPending = [];
+  let inflightBatch = [];
+  let inFlight = false;
+  let sendAttempts = 0;
+  let mergeTimer;
+  let backoffTimer;
+  let watchdogTimer;
+  let disposed = false;
+  let settledUnsub;
+  let missingKeyWarned = false;
+  const dedupSet = config?.dedupe ? new LruSet(config.dedupe.maxKeys) : null;
+  function clearMergeTimer() {
+    if (mergeTimer !== void 0) {
+      clearTimeout(mergeTimer);
+      mergeTimer = void 0;
+    }
+  }
+  function armMergeTimer() {
+    if (cfg.mergeWindowMs <= 0) return;
+    mergeTimer = setTimeout(() => {
+      mergeTimer = void 0;
+      flush();
+    }, cfg.mergeWindowMs);
+  }
+  function resetMergeTimer() {
+    clearMergeTimer();
+    armMergeTimer();
+  }
+  function ensureSettledSub() {
+    if (settledUnsub || !port.subscribeSettled) return;
+    settledUnsub = port.subscribeSettled(() => {
+      if (disposed) return;
+      if (!isBusy(port)) {
+        flush();
+      }
+    });
+  }
+  function teardownSettledSub() {
+    if (settledUnsub) {
+      settledUnsub();
+      settledUnsub = void 0;
+    }
+  }
+  function startWatchdog() {
+    if (watchdogTimer !== void 0) return;
+    if (!port.subscribeSettled) return;
+    watchdogTimer = setInterval(() => {
+      if (disposed || inFlight) return;
+      if (queue.length === 0) return;
+      if (!isBusy(port)) {
+        flush();
+      }
+    }, cfg.watchdogMs);
+  }
+  function stopWatchdog() {
+    if (watchdogTimer !== void 0) {
+      clearInterval(watchdogTimer);
+      watchdogTimer = void 0;
+    }
+  }
+  function attemptSend() {
+    const batch = inflightBatch;
+    const composed = buildBatchPayload(batch);
+    const intent = composed.intent ?? cfg.intent;
+    try {
+      const result = port.send(composed, intent);
+      if (isThenable(result)) {
+        result.then(
+          (receipt) => onSendReceipt(receipt),
+          (err) => onSendFail(err)
+        );
+      } else {
+        onSendReceipt(result);
+      }
+    } catch (err) {
+      onSendFail(err);
+    }
+  }
+  function onSendReceipt(receipt) {
+    if (receipt !== void 0 && receipt.accepted === false) {
+      onSendFail(new Error(receipt.reason ?? "port.send rejected (accepted:false)"));
+      return;
+    }
+    onSendOk();
+  }
+  function onSendOk() {
+    if (disposed) return;
+    const delivered = inflightBatch;
+    inFlight = false;
+    inflightBatch = [];
+    sendAttempts = 0;
+    settleChecked(delivered, void 0, checkedPending);
+    for (const m of delivered) {
+      if (disposed) break;
+      cfg.onSettled?.(m, "delivered");
+    }
+    pump();
+  }
+  function onSendFail(err) {
+    if (disposed) return;
+    sendAttempts++;
+    const rejected = settleChecked(inflightBatch, err, checkedPending);
+    if (rejected.size > 0) {
+      inflightBatch = inflightBatch.filter((m) => !rejected.has(m));
+    }
+    if (inflightBatch.length === 0) {
+      inFlight = false;
+      inflightBatch = [];
+      sendAttempts = 0;
+      warn("port.send failed", err);
+      pump();
+      return;
+    }
+    if (sendAttempts > cfg.backoff.max) {
+      const rejectedBatch = inflightBatch;
+      inFlight = false;
+      inflightBatch = [];
+      sendAttempts = 0;
+      warn("port.send failed after max retries", err);
+      for (const m of rejectedBatch) {
+        if (disposed) break;
+        cfg.onSettled?.(m, "rejected");
+      }
+      pump();
+      return;
+    }
+    if (sendAttempts === 1) warn("port.send failed, retrying with backoff", err);
+    backoffTimer = setTimeout(() => {
+      backoffTimer = void 0;
+      if (disposed || !inFlight) return;
+      attemptSend();
+    }, cfg.backoff.ms);
+  }
+  function pump() {
+    if (disposed || inFlight) return;
+    if (checkedPending.length > 0) {
+      const msgs = [];
+      for (const w of checkedPending) {
+        const idx = queue.indexOf(w.msg);
+        if (idx !== -1) {
+          queue.splice(idx, 1);
+          msgs.push(w.msg);
+        }
+      }
+      if (msgs.length > 0) {
+        inflightBatch = msgs;
+        inFlight = true;
+        sendAttempts = 0;
+        attemptSend();
+        return;
+      }
+    }
+    if (queue.length > 0) {
+      scheduleFlush(0);
+      return;
+    }
+    if (checkedPending.length === 0) stopWatchdog();
+  }
+  function doSend() {
+    if (disposed || queue.length === 0 || inFlight) return;
+    inFlight = true;
+    inflightBatch = queue.splice(0);
+    sendAttempts = 0;
+    attemptSend();
+  }
+  function scheduleFlush(attempt) {
+    if (disposed || queue.length === 0) return;
+    if (inFlight) return;
+    if (cfg.busyPolicy === "park" && attempt > 0) return;
+    if (backoffTimer !== void 0) {
+      clearTimeout(backoffTimer);
+      backoffTimer = void 0;
+    }
+    if (isBusy(port) && attempt < cfg.backoff.max) {
+      if (port.subscribeSettled) {
+        startWatchdog();
+        return;
+      }
+      backoffTimer = setTimeout(() => {
+        backoffTimer = void 0;
+        scheduleFlush(attempt + 1);
+      }, cfg.backoff.ms);
+      return;
+    }
+    doSend();
+  }
+  const warnSink = resolveWarnSink(config);
+  function warn(msg, err) {
+    warnSink(msg, err);
+  }
+  function passDedupe(msg) {
+    if (!dedupSet) return true;
+    if (!msg.dedupeKey) {
+      if (!missingKeyWarned) {
+        missingKeyWarned = true;
+        warn("dedupe enabled but message has no dedupeKey; delivering without dedupe");
+      }
+      return true;
+    }
+    if (dedupSet.has(msg.dedupeKey)) return false;
+    dedupSet.add(msg.dedupeKey);
+    return true;
+  }
+  function send(msg, opts) {
+    if (disposed) return;
+    if (!port.supportedPayloads.includes(msg.payload.kind)) {
+      warn(`unsupported payload kind: ${msg.payload.kind}`);
+      return;
+    }
+    if (!passDedupe(msg)) return;
+    queue.push(msg);
+    const useMerge = opts?.merge ?? (cfg.mergeWindowMs > 0 && cfg.mergeHoldActive != null && cfg.mergeHoldActive());
+    if (useMerge) {
+      resetMergeTimer();
+      ensureSettledSub();
+      return;
+    }
+    clearMergeTimer();
+    ensureSettledSub();
+    scheduleFlush(0);
+  }
+  async function sendChecked(msg) {
+    if (disposed) throw new Error("delivery handle disposed");
+    if (!port.supportedPayloads.includes(msg.payload.kind)) {
+      throw new Error(`unsupported payload kind: ${msg.payload.kind}`);
+    }
+    if (!passDedupe(msg)) return;
+    queue.push(msg);
+    ensureSettledSub();
+    return new Promise((resolve, reject) => {
+      checkedPending.push({ msg, resolve, reject });
+      if (!inFlight) {
+        const idx = queue.indexOf(msg);
+        if (idx !== -1) queue.splice(idx, 1);
+        inflightBatch = [msg];
+        inFlight = true;
+        sendAttempts = 0;
+        attemptSend();
+      }
+    });
+  }
+  function flush() {
+    if (disposed) return;
+    if (mergeTimer !== void 0) {
+      clearTimeout(mergeTimer);
+      mergeTimer = void 0;
+    }
+    scheduleFlush(0);
+  }
+  function depth() {
+    return queue.length + inflightBatch.length;
+  }
+  function dispose() {
+    disposed = true;
+    if (mergeTimer !== void 0) {
+      clearTimeout(mergeTimer);
+      mergeTimer = void 0;
+    }
+    if (backoffTimer !== void 0) {
+      clearTimeout(backoffTimer);
+      backoffTimer = void 0;
+    }
+    stopWatchdog();
+    teardownSettledSub();
+    queue.length = 0;
+    inflightBatch = [];
+    inFlight = false;
+    for (const w of checkedPending) {
+      w.reject(new Error("delivery handle disposed"));
+    }
+    checkedPending.length = 0;
+    dedupSet?.clear();
+  }
+  return { send, sendChecked, flush, depth, dispose };
+}
+export {
+  createDelivery
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@zhushanwen/session-delivery",
+  "version": "0.10.0",
+  "description": "Session message delivery kernel: zero-pi-dependency strategy layer for queueing, batching, dedup, and gated flush of messages into pi sessions",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}