@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/caching-session-store.js

@@ -1,97 +1,30 @@
 import { assertPlacementAdmission } from "./session-placement.js";
-/**
- * Warm/sticky cache in front of a durable {@link SessionStore} (Option A).
- *
- * Keeps a woken session in memory and **reuses the same storage instance across turns**, so a hot
- * session is not re-read from TiDB every short turn (treats the cattle like a warm pet while it's
- * active). Idle sessions expire after `ttlSec`; `release` evicts immediately.
- *
- * ⚠️ **Session affinity is REQUIRED** when this cache is enabled (`SESSION_CACHE_TTL_SEC>0`): route a
- * given sessionId to the same instance. Under affinity the cached storage is the sole writer, so its
- * in-memory leaf is always current and consistent with TiDB (write-through; F2 CAS still applies).
- * Without affinity a concurrent write from another instance makes this cache stale; that surfaces as
- * a `SessionError("conflict")` on the next append — the async run driver calls `evict()` on conflict
- * (defense-in-depth) and the entry also expires after `ttlSec`, but those are backstops, not the
- * guarantee. If you cannot guarantee affinity, set `SESSION_CACHE_TTL_SEC=0` to disable the cache.
- *
- * Orthogonal to the F3 branch-floor change: floor bounds the *cold wake* size; this cache removes
- * *repeated* re-reads of an active session.
- */
 export class CachingSessionStore {
     inner;
     cache = new Map();
     pending = new Map();
     ttlMs;
     timer;
-    /** Delegated tenant-ownership ops, present only if the inner store exposes them (the TiDB store does). */
     ownerOf;
     register;
-    /** Delegated SessionRepo seam (§0.5) — list/fork/delete operate on the DURABLE tables directly (they bypass the
-     *  warm cache by design; a fork/delete must read/write durable state, not a possibly-stale cached view). */
     listSessions;
     fork;
     deleteSession;
-    /** K-5c (core 1.155 SessionStore.noteTaskRun seam) — core's Runner calls it at runTask START to record the latest
-     *  run per session (→ listSessions `lastRunId`). MUST be forwarded: the local backend's Runner store is THIS cache
-     *  wrapper, so without forwarding `noteTaskRun?.()` silently no-ops and lastRunId stays null (review BLOCKER). Pure
-     *  pass-through to the inner store's in-mem map — no cache interaction. (TiDB/PG don't implement it → not bound.)
-     *  Return type matches core's `SessionStore.noteTaskRun?(): void | Promise<void>` (review: don't narrow to void). */
     noteTaskRun;
-    /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
     setTitleIfNull;
     probeTitle;
-    /** E18 — delegate the leaf read straight to inner (a cache-bypassing single SELECT; the resume-at turn-capture
-     *  reads the DURABLE leaf, not a possibly-stale cached view — same discipline as the §0.5 repo ops above). */
     getLeafId;
-    /** [1196] 六轮复审:owner+leafId 原子快照透传(cache-bypassing,getLeafId 同姿势)。 */
     getHead;
-    /** 2c session-sync — delegated export/import seam, DURABLE (bypasses the warm cache exactly like
-     *  list/fork: an export reads the full durable log, an import writes durable state). */
     exportEntries;
-    /** 2c session-sync P1d-α (PULL streaming) — delegated ids-only projection + keyset-paged entry STREAM, DURABLE
-     *  (read straight from the durable log, bypassing the warm cache, like exportEntries). The stream's per-batch query
-     *  discipline (one pooled query per page) lives in the inner store; this wrapper just forwards. */
     listEntryIds;
     exportEntriesStream;
-    /** 轴A #1(1.254):core B-17 forget 面(evict 本地 + 转发 inner 可选面)。 */
     forget;
     importEntries;
-    /** [2024](cli 取证)2c session-sync P1d-β — delegated STAGED import seam. 此前 staging 族不在本类的逐方法
-     *  转发白名单里 ⇒ 默认部署(SESSION_CACHE_TTL_SEC=300 把真店包进本类)PUSH Phase A 恒 501
-     *  `capability.session_store_required`,而 capabilities().sessionSync 谓词三项(backend/exportEntries/
-     *  fileSnapshotStore)都被转发了 ⇒ 照报 true(能力面谎)。转发形:handle 的 `commit` 是唯一写真 id 的
-     *  时刻,成功后逐出该 id 的暖 handle + S25 指纹(importEntries/replaceEntries 同纪律);`abort` 只丢
-     *  staging 行、不碰真 id ⇒ 不逐出。 */
     beginImportStaging;
-    /** Staging 清扫面(kernel `ImportStagingStore.sweepStagingSessions`)。当下 reaper 走 `backend.session()`
-     *  裸店、不经本包装,但 security.ts 的 OwnerAwareSessionStore 契约列了它 —— 经 sessionStorage 消费的
-     *  未来调用方不该静默 no-op,与 beginImportStaging 同批补齐(同一类白名单缺口)。 */
     sweepStagingSessions;
-    /** 2c session-sync (§7/§8) — delegated IDEMPOTENT replace; like importEntries it writes durable state under
-     *  `sessionId`, so a stale warm handle for that id is evicted on success (next acquire re-wakes from the new log). */
     replaceEntries;
-    /**
-     * #270 车1 —— 内层店的 `retention` **声明**(core `RetentionDeclaring`)。
-     *
-     * 🔴 为什么这一格必须转发,而且方向比别的转发更要命:生产默认 `SESSION_CACHE_TTL_SEC=300` 会把真店
-     * 包进本类,于是 boot 递给 `assertRetentionCapability` 的就是**包装层**。core 对缺席是 fail-closed
-     * 读 `"none"` —— 不转发 ⇒ 一个真 managed 的 SQL 部署在 locked policy 下**被拒启**,而拒启文案会指着
-     * 一只其实完全合格的店(「stores that cannot delete」)。转发是**只读快照**而不是 getter:声明是店的
-     * 构造期常量,一个会变的声明本身就是缺陷。缺席则不设(保持 fail-closed 的缺席读法)。
-     */
     retention;
-    /**
-     * #292 C18 —— 内层店的 **placement 声明**转发。
-     *
-     * 🔴 这一格与 {@link retention} 是同一条教训的同一族(而且更狠):生产默认 `SESSION_CACHE_TTL_SEC=300`
-     * 把真店包进本类,于是 boot 递给 core 的就是**包装层**。core 的铸造门判「row store ∧ **session 店声明**」
-     * ⇒ 不转发 = 整条 subagent 转录持久化在默认部署上**静默不生效**(placement 参数被合法忽略、子代转录
-     * 退回普通会话、声明的 durable tier 变成一句空话),而且没有任何一处会报错。
-     * 只读快照而非 getter:声明是店的构造期常量(会变的声明本身就是缺陷)。
-     */
     placements;
-    /** #292:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
-     *  是包装层,不转发 = 分区腿静默不可用、暖命中的 claim 关门静默失效。缺席则不设(诚实降级)。 */
     listPlaced;
     placementOf;
     constructor(inner, opts) {
@@ -100,7 +33,6 @@ export class CachingSessionStore {
         const declared = inner.retention;
         if (declared !== undefined)
             this.retention = declared;
-        // #292:声明 + 两只读面逐字转发(理由见各自的字段注)。
         if (inner.placements !== undefined)
             this.placements = inner.placements;
         if (typeof inner.listPlaced === "function")
@@ -122,7 +54,7 @@ export class CachingSessionStore {
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
         if (ownerAware.noteTaskRun)
-            this.noteTaskRun = ownerAware.noteTaskRun.bind(inner); // K-5c: pass-through so the Runner's noteTaskRun reaches the inner map (review BLOCKER fix)
+            this.noteTaskRun = ownerAware.noteTaskRun.bind(inner);
         if (ownerAware.getLeafId)
             this.getLeafId = ownerAware.getLeafId.bind(inner);
         if (ownerAware.getHead)
@@ -133,39 +65,29 @@ export class CachingSessionStore {
             this.listEntryIds = ownerAware.listEntryIds.bind(inner);
         if (ownerAware.exportEntriesStream)
             this.exportEntriesStream = ownerAware.exportEntriesStream.bind(inner);
-        // 历史复审轴A #1(1.254,core B-17 缝):core prepare-task 在 reconcile 冲突重试/prepare-throw 清理时
-        // 调 `sessions.forget?.()`,缺席=无 fallback(B-17 判例:绝不代之以 release)——本店此前无 forget,
-        // tidb+cache 形态下运行内冲突自愈失效(暖缓存命中同一 stale 实例→重试预算耗尽→该 run 以 conflict 败;
-        // runs.ts evictIfConflict 只兜 run 后)。补齐=evict 本地缓存 + 转发 inner 可选面(fork-routing 店同款)。
         this.forget = (sessionId) => {
             this.evict(sessionId);
             return inner.forget?.(sessionId);
         };
         if (ownerAware.importEntries) {
-            // An import writes durable state under `sessionId`; if a stale handle for that id is warm, drop it so the
-            // next acquire re-wakes from the freshly-imported durable log (mirrors the deleteSession evict discipline).
             const imp = ownerAware.importEntries.bind(inner);
             this.importEntries = async (sessionId, owner, entries) => {
                 await imp(sessionId, owner, entries);
                 if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId); // S25: a warm entry was live → stale-affinity fingerprint
+                    opts.onConflictEvict?.(sessionId);
                 this.evict(sessionId);
             };
         }
         if (ownerAware.replaceEntries) {
-            // A replace REWRITES durable state under `sessionId` (purge + re-import); evict any warm handle so the next
-            // acquire re-wakes from the replaced log (same discipline as importEntries / deleteSession above).
             const rep = ownerAware.replaceEntries.bind(inner);
             this.replaceEntries = async (sessionId, owner, entries) => {
                 await rep(sessionId, owner, entries);
                 if (this.cache.has(sessionId))
-                    opts.onConflictEvict?.(sessionId); // S25
+                    opts.onConflictEvict?.(sessionId);
                 this.evict(sessionId);
             };
         }
         if (ownerAware.beginImportStaging) {
-            // [2024] staged import(P1d-β)经包装店贯通:handle 逐字段代理,只有 `commit`(唯一写真 id 的时刻)
-            // 加了成功后逐出——与上面 importEntries/replaceEntries 完全同款的纪律;abort 不写真 id,不逐出。
             const begin = ownerAware.beginImportStaging.bind(inner);
             this.beginImportStaging = (realSessionId, token) => {
                 const h = begin(realSessionId, token);
@@ -176,7 +98,7 @@ export class CachingSessionStore {
                     commit: async (owner, o) => {
                         const r = await h.commit(owner, o);
                         if (this.cache.has(realSessionId))
-                            opts.onConflictEvict?.(realSessionId); // S25: a warm entry was live → stale-affinity fingerprint
+                            opts.onConflictEvict?.(realSessionId);
                         this.evict(realSessionId);
                         return r;
                     },
@@ -187,8 +109,6 @@ export class CachingSessionStore {
         if (ownerAware.sweepStagingSessions)
             this.sweepStagingSessions = ownerAware.sweepStagingSessions.bind(inner);
         if (ownerAware.deleteSession) {
-            // A durable delete must also drop the deleted session from THIS warm cache (else a stale cached handle
-            // could keep serving a purged session until its idle TTL). Wrap to evict on success.
             const del = ownerAware.deleteSession.bind(inner);
             this.deleteSession = async (sessionId, owner) => {
                 const removed = await del(sessionId, owner);
@@ -210,28 +130,13 @@ export class CachingSessionStore {
             return fresh;
         }
         const hit = this.cache.get(sessionId);
-        // 🔴 #292 义务 6(claim 关门)在**暖命中**上的半场:一次 claim 形 acquire 撞上缓存里的 placed 会话,
-        // 若按下面的「命中即返回」放行,包装层就成了义务的一个**旁路**——同一条 id 在冷缓存上被拒、在暖
-        // 缓存上被接受,而生产默认恰恰是暖的。判据仍吃**持久化元组**(一次 PK 探针,只在声明了分区的内层
-        // 店 + 非 requireExisting 的形上付),绝不用缓存里的影子事实当准入依据。
         if (hit && opts?.requireExisting !== true && this.placements !== undefined && this.placementOf !== undefined) {
             assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
         }
         if (hit) {
-            // A warm cache hit means the session EXISTS → it satisfies `requireExisting` (no need to re-open the durable
-            // log). design/114 Phase3: the fail-loud only ever fires on a genuinely-missing (uncached) session below.
-            // 🟡 Affinity caveat (doc-as-intentional, LOW): under the REQUIRED session affinity (see the class header), the
-            // cached instance is the sole writer, so a warm handle can't be stale w.r.t. a purge — a same-instance E21
-            // delete evicts this entry (deleteSession wrapper). Only an out-of-band / cross-instance purge that VIOLATES
-            // affinity could leave a stale hit that satisfies requireExisting until the idle TTL expires. Bypassing the
-            // cache for strict acquires would add a DB round-trip to EVERY warm-resume (the hot path) to close an
-            // affinity-violation-only window — not worth it; the affinity contract already governs cross-instance writes.
             hit.expiresAt = Date.now() + this.ttlMs;
             return hit.acquired;
         }
-        // design/114 Phase3 (F1): a `requireExisting` acquire can REJECT (not_found) and never creates — it MUST bypass
-        // the shared create-dedup `pending`, else a concurrent create-capable waiter would inherit the not_found rejection
-        // instead of creating-on-miss. Forward the option to the inner (durable) store, which does the fail-loud.
         if (opts?.requireExisting) {
             const a = await this.inner.acquire(sessionId, opts);
             this.store(a);
@@ -239,12 +144,6 @@ export class CachingSessionStore {
         }
         const inflight = this.pending.get(sessionId);
         if (inflight) {
-            // 🔴 #292(codex 对抗复审 R1-[high],验真后修):**in-flight 合并也要逐调用者复判**准入。
-            // 病:两个并发调用一冷一后到,后到者直接拿走**首个**调用者的 promise —— 于是
-            //  · 可信 placement 创建先到 + claim 形后到 ⇒ 后者当场附着到一条 placed 转录上(义务 6 被绕过);
-            //  · 顺序反过来 ⇒ placement 创建方拿到一只**普通**会话(镜像方向的 squat 判本该拒,却被合并吞掉)。
-            // 内层 SQL 店自己有逐调用者复判(它的 pending 分支同款),但**默认生产形是本包装层**,而本层在
-            // 到达内层之前就把第二个调用者截断了 —— 判据被一层缓存挡在门外,正是本类反复吃过的那一类亏。
             const acquired = await inflight;
             if (this.placements !== undefined && this.placementOf !== undefined) {
                 assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
@@ -271,7 +170,6 @@ export class CachingSessionStore {
         this.cache.delete(sessionId);
         await this.inner.release(sessionId);
     }
-    /** Drop a session from the warm cache (e.g. after a cross-instance write conflict). */
     evict(sessionId) {
         this.cache.delete(sessionId);
     }