@gavinc-cn/touchstone-dsh 0.1.1 → 0.2.0

package/dshdriver.py

@@ -143,9 +143,30 @@ def available(timeout=HEALTH_TIMEOUT):
         return False
 
 
+def live_snapshot(timeout=10):
+    """`/live` 的**原始响应**：`{sessions: [...], complete?: bool}`。
+
+    `complete`（A 批 2026-10-08 起真插件会上报）＝插件是否已枚举宿主已有会话：
+    只有它为 true，**空表**才具备「宿主里确实没有会话」的语义（见 dshevents._align）。
+    旧装机副本没有该字段 ⇒ `complete` 缺省按未声明处理（空表＝未知）。
+
+    为什么单列一个读口（2026-10-08 修正）：`live()` 返回的是**行表**（历史调用点
+    server.py 直接迭代），而中枢对齐需要「行表 + 完整性声明」两件东西。旧写法拿
+    `live()` 的返回值当 dict 取 `.get("sessions")` ⇒ `/live` 非空时必抛
+    AttributeError，被 `except` 吞掉后中枢**永久「未对齐」**（`aligned()` 恒 False ⇒
+    看板 recover 不搬列、调和器缺席归位不触发）。契约由
+    `tests/test_session_visibility.py::test_live_readers_contract` 钉死。
+    """
+    return _request("GET", "/live", timeout=timeout) or {}
+
+
 def live():
-    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。"""
-    return _request("GET", "/live", timeout=10).get("sessions", [])
+    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。
+
+    返回**行表 list**（历史契约：server.py 的外部会话汇总直接迭代）；需要「完整性
+    声明」的调用方（dshevents._align）用 `live_snapshot()`。
+    """
+    return list((live_snapshot() or {}).get("sessions") or [])
 
 
 def status(session_id):
@@ -245,9 +266,17 @@ def fork(session_id, at_seq=None):
     return _request("POST", "/fork", payload, timeout=60)
 
 
-def rename(session_id, title):
-    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title}`。"""
-    return _request("POST", "/rename", {"session_id": session_id, "title": title})
+def rename(session_id, title, timeout=REQUEST_TIMEOUT):
+    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title, [external]}`。
+
+    `title` 是**宿主接受值**（可能被 `normalizeSessionTitle` 规范化/按 UTF-8 字节预算
+    截断），调用方据此回写卡面可保证两侧逐字一致（见 board.rename_card_session）。
+
+    `timeout` 可缩短：卡面改名是 best-effort 的同步链路（`PATCH /board/cards/<cid>`），
+    不能让驱动侧僵死把 HTTP worker 拖满默认 120s。
+    """
+    return _request("POST", "/rename", {"session_id": session_id, "title": title},
+                    timeout=timeout)
 
 
 def set_model(session_id, model, provider="", reasoning_effort=""):
@@ -355,6 +384,46 @@ def unarchive(session_id, timeout=30):
     return archive(session_id, archived=False, timeout=timeout)
 
 
+# ---------- 看管声明（外部会话投递通道，C 批 T5 2026-10-10） ----------
+
+# 看管声明超时（秒）：`/watch` 是驱动侧**纯内存写**，正常毫秒级返回；而投递前置闸
+# （`chat._external_preflight`）是在 HTTP 请求线程上同步调用它的——不能沿用普通请求
+# 的 120s，否则驱动僵死会把用户的一次「发送」卡住两分钟。2s 与「声明不成功即拒投」
+# 的语义相称（设计 §5.1）。
+WATCH_TIMEOUT = 2
+
+# 旧插件没有 `/watch` 端点时的状态码（未知驱动端点，见插件 _serve 的兜底 404）。
+# 平台据此把「外部会话投递」降级为拒投并给「插件过旧」文案，池内一切功能不受影响。
+WATCH_UNSUPPORTED = 404
+
+
+def watch_session(session_id, on=True):
+    """声明 / 撤销「平台看管该会话」（驱动 `POST /watch`，幂等）。返回看管是否生效。
+
+    为什么需要（C 批设计 §3.1）：外部会话（用户在 dsh GUI 里直跑/接管、`/live` 里
+    `owned:false`）既不在驱动池、也没有平台持有者，驱动侧因此不可能靠「在不在池内」
+    推断平台是否有意投递——**范围必须由平台显式划定**（宿主里与 Touchstone 无关的
+    会话多得是，无差别放开等于允许平台向任意会话注入消息与答案）。平台只对**平台确实
+    要投递的**会话声明看管：有看板卡的会话由 `board._ensure_watch` 常态声明；任务侧
+    会话在宿主上报为外部态（`owned:false`）时，由消息前置闸 `chat._external_preflight`
+    与作答/审批送达前的 `board._watch_before_delivery` 补声明。驱动据此放行 `/prompt`·
+    `/steer`·`/answer`·`/approval` 的池外分支。
+
+    幂等：重复声明同一 sid 不报错，驱动回执给的是 `watched` 的**当前实际状态**
+    （而非「这次有没有改动」），故本函数返回 `bool(resp["watched"])`——调用方按
+    「True 才算声明成功」处置。`on=False` 撤销（卡删除/归档后的回收，见
+    `board._watch_prune`）。
+
+    失败语义：**异常照抛**（`DshDriverError`：旧插件 404 / 驱动不可达 / 令牌错），
+    「是否吞异常降级」由调用方决定——`board._ensure_watch` 选择留痕 + 返回 False
+    且不重试（看管失败 ⇒ 投递前置闸拒投，见 `chat._external_preflight`）。
+    """
+    resp = _request("POST", "/watch",
+                    {"session_id": session_id, "on": bool(on)},
+                    timeout=WATCH_TIMEOUT)
+    return bool((resp or {}).get("watched"))
+
+
 def apply_session_defaults(session_id, model="", provider="",
                            reasoning_effort="", permission_mode="", log=None):
     """把项目级默认（思考等级 / 权限档）应用到刚建或刚续的会话上（best-effort）。

package/dshevents.py

@@ -61,6 +61,11 @@ class EventHub:
         # 与 `_sessions` 同样遵守「断连=未知」不变量——None 时调用方一律不动作。
         self._archived = None
         self._connected = False
+        # 快照对齐是否**可信**（2026-10-08 批次，B）：只有「(重)连时拿到过权威快照」
+        # 才置 True——空快照且插件未声明完整时保留旧表但置 False（见 `_align`）。
+        # 读口 `aligned()` = connected ∧ _aligned：调用方据此决定「能否按缺席推断
+        # 会话已结束」（`board._iw_once`）与「能否按实况搬列」（`board.recover`）。
+        self._aligned = False
         self._last_seq = 0
         self._frames = 0
         self._reconnects = 0
@@ -101,6 +106,22 @@ class EventHub:
         with self._cond:
             return self._connected
 
+    def aligned(self):
+        """注册表是否**可信**（= 链路在线 ∧ 曾用插件权威快照对齐过）。
+
+        为什么需要它（2026-10-08 批次 B，bug_report/20261008_1935）：
+        插件重新 apply（热重载）时驱动实例重建、`/live` 会短暂返回空表——旧实现
+        `self._sessions = fresh` 直接清空注册表，调用方随即把「未知」当成
+        「会话已结束/空闲」：`board.recover()` 把**正在运行的卡**搬去待审核，
+        且调和器此后再也读不到该会话 ⇒ 不自愈。现在空快照保留旧表并置
+        `_aligned=False`，本读口给出「是否可信」的单点判据：
+          - False ⇒ 一律不据实况写列（未知 ≠ 空闲，同「断连=未知」不变量）；
+          - True ⇒ 会话不在注册表即可判「已结束」（`board._iw_once` 的补口）。
+        插件半（A 批次）在 `/live` 里声明 `complete` 后，真·零会话的宿主也能可信。
+        """
+        with self._cond:
+            return bool(self._connected and self._aligned)
+
     def get(self, sid):
         """单会话实时态；未连接或未知会话返回 None（＝未知，不是空闲）。
 
@@ -146,6 +167,7 @@ class EventHub:
         """诊断信息（/api 健康与测试断言用）。"""
         with self._cond:
             return {"connected": self._connected, "sessions": len(self._sessions),
+                    "aligned": bool(self._connected and self._aligned),
                     "last_seq": self._last_seq, "frames": self._frames,
                     "reconnects": self._reconnects, "changed": self._changed,
                     "archived": None if self._archived is None else len(self._archived),
@@ -226,8 +248,20 @@ class EventHub:
         新的状态轮询」。归档集取不到时保持「未知」（None），调用方一律不动作。
         """
         try:
-            rows = (dshdriver.live() or {}).get("sessions") or []
-        except Exception:                          # noqa: BLE001 — 对齐失败不阻断重连
+            # 用 live_snapshot()（原始 dict）而不是 live()（行表 list）——2026-10-08 修正：
+            # 旧写法 `dshdriver.live() or {}` 把行表当 dict 取 `.get("sessions")`，
+            # `/live` 非空时必抛 AttributeError 被下面 except 吞掉 ⇒ 中枢**永久未对齐**
+            # （aligned() 恒 False，C/D 两处补口在真机等于失效）。契约见
+            # tests/test_session_visibility.py::test_live_readers_contract。
+            resp = dshdriver.live_snapshot() or {}
+            rows = resp.get("sessions") or []
+            # 插件完整声明（A 批次后新增，旧插件缺省 None＝未声明）：只有它才让
+            # 「空表」具备「宿主里确实没有会话」的语义，否则空表一律按未知处理。
+            complete = resp.get("complete") is True
+        except Exception as exc:                   # noqa: BLE001 — 对齐失败不阻断重连
+            self._set_aligned(False)               # 取不到快照＝不能确认任何事
+            print(f"[dshevents] /live 对齐失败（{exc}）：保留 {len(self._sessions)} 条"
+                  f"既有会话、标记未对齐", flush=True)
             return
         try:
             archived = {str(s) for s in (dshdriver.archived() or []) if s}
@@ -265,11 +299,34 @@ class EventHub:
                     "inbox": old.get("inbox") or [],
                     "updated_at": now,
                 }
-            self._sessions = fresh
+            # —— 快照可信判定（2026-10-08 批次 B）——
+            # 非空快照 = 权威整表；空快照只有插件声明完整（complete）才算权威空。
+            # 其余情况（热重载后驱动实例重建、不重枚举已有会话 ⇒ 空表）＝**未知**：
+            # 旧表原样保留（宁可多等不可误放行），只把可信标志置 False——
+            # 调用方一律不据此推断忙/闲，也绝不据「缺席」判会话已结束。
+            trusted = bool(fresh) or complete
+            if trusted:
+                self._sessions = fresh
+            kept = len(self._sessions)
+            self._aligned = trusted
             if archived is not None:
                 self._archived = archived
             self._changed += 1
             self._cond.notify_all()
+        if not trusted and kept:
+            # 留痕（插件形态落 <库目录>/plugin-backend.log）：这是可诊断的降级态，
+            # 不是静默——旧表保留期间看板列不做忙/闲写入，直到下一次权威快照。
+            print(f"[dshevents] /live 空快照且插件未声明完整：保留 {kept} 条既有会话、"
+                  f"标记未对齐（热重载后驱动实例重建的已知形态，见 "
+                  f"bug_report/20261008_1935）", flush=True)
+
+    def _set_aligned(self, value):
+        """置「快照可信」标志（变更才唤醒订阅者；调用方持锁外语义同 `_set_connected`）。"""
+        with self._cond:
+            if self._aligned != bool(value):
+                self._aligned = bool(value)
+                self._changed += 1
+                self._cond.notify_all()
 
     def _set_connected(self, value):
         with self._cond:
@@ -401,6 +458,11 @@ def connected():
     return HUB.connected()
 
 
+def aligned():
+    """注册表可信读口（在线 ∧ 曾用权威快照对齐）；未对齐 ⇒ 调用方不写列、不推断。"""
+    return HUB.aligned()
+
+
 def get(sid):
     return HUB.get(sid)