@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/tidb-session-storage.js

@@ -4,6 +4,17 @@ import { toIso } from "./sql-row-helpers.js";
 function isDupKey(err) {
     return Boolean(err) && err.code === "ER_DUP_ENTRY";
 }
+/**
+ * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ *
+ * - `appendEntry` / `setLeafId` persist with an **atomic compare-and-set** on `leaf_seq` + `leaf_id`
+ *   (core's F2 optimistic-lock seam): a write only lands if the branch leaf is still what the entry
+ *   was built against. Two stateless runners that both woke the same session can't silently fork —
+ *   the loser gets `SessionError("conflict")` (catch with `isSessionConflict`).
+ * - The in-memory base tree is the wake-time snapshot; every write is also mirrored into it so the
+ *   live harness keeps reading a consistent view. Wake is **bounded** to `[floor .. leaf]` (F3,
+ *   core 1.6.0 branch-floor seam); older history is covered by the last compaction's summary.
+ */
 export class TiDBSessionStorage extends BaseSessionStorage {
     pool;
     sessionId;
@@ -16,14 +27,29 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         this.leafSeq = leafSeq;
         this.floorSeq = floorSeq;
     }
+    /**
+     * [976] S3 RB-14 pull seam — `SessionStorage.getEpochAnchor?()`: the nearest epoch carrier BELOW the
+     * bounded-wake floor. core's `Session.getPromptEpoch()` (≥1.305) calls this only when the in-window
+     * branch walk finds no carrier — i.e. a rewind/resumeAt cut inside the kept tail, where the compaction
+     * restatement is a DESCENDANT of the cut and the root pin sits under the floor. Semantics per core's
+     * ruling: highest-seq valid carrier below the floor (not an ancestor-chain walk — fallback of last
+     * resort); malformed rows are skipped (#13: fall back to the older valid pin — the write gate refuses
+     * malformed carriers, so these only exist via out-of-band writes); none ⇒ undefined = a genuine
+     * pre-epoch session (core mints legacy_migration, the correct meaning). core re-normalizes whatever we
+     * return, so this stays honest even if the two sides ever disagree on strictness.
+     */
     async getEpochAnchor() {
         if (this.floorSeq <= 0)
-            return undefined;
+            return undefined; // full load — the walk already reaches the root pin
+        // Keyset-paged scan to EXHAUSTION (codex HIGH): a long-lived session upgraded across the epoch
+        // release carries 100+ pre-epoch compactions with NO restatement between the floor and the older
+        // valid pin — a bounded LIMIT would run dry on them and return undefined, which here specifically
+        // means "genuinely pre-epoch" and would let the caller mint a migration epoch over a durable anchor.
         let cursor = this.floorSeq;
         for (;;) {
             const [rows] = await this.pool.query("SELECT seq, payload FROM session_event WHERE session_id = ? AND seq < ? AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100", [this.sessionId, cursor]);
             if (rows.length === 0)
-                return undefined;
+                return undefined; // exhausted — a genuine pre-epoch session
             for (const r of rows) {
                 const e = (typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload);
                 const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
@@ -33,7 +59,27 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             cursor = Number(rows[rows.length - 1].seq);
         }
     }
+    /**
+     * Rebuild a session from its event log (= wake). Returns null if the session does not exist.
+     *
+     * F3 bounded load: only `[floor .. leaf]` is read, where floor = the last compaction's
+     * `firstKeptEntryId` (everything older is represented by that compaction's summary, so it never
+     * enters context). No compaction yet → floor=null → full load (the session is still short).
+     *
+     * This is the durable, bounded-READ equivalent of core's `boundedTail(pathEntries)` (1.42.0): that
+     * helper trims a FULL-loaded path in memory, whereas we compute the floor seq first and only `SELECT
+     * seq >= floorSeq` — so the head never leaves cold storage. Our sessions are LINEAR (no fork), so
+     * seq-order == root→leaf path-order and our `seq >= floorSeq` tail is byte-identical to
+     * `boundedTail(path).tail`; the resulting floored `BaseSessionStorage.buildContext()` matches a
+     * full-tree wake (core's `session-floor.test.ts`). If branching is ever added, switch to `boundedTail`.
+     */
     static async wake(pool, sessionId) {
+        // KNOWN/ACCEPTED (audit B): meta + floor + events are three queries, not one snapshot — a writer
+        // appending between them can make this wake see MORE events than the meta row described (never
+        // fewer: seq is append-only and `seq >= floorSeq` reads the tail). That's only reachable when two
+        // actors drive the same session concurrently, which the task_active session lock already
+        // serializes; the persist path then re-CASes leaf_id/leaf_seq, so a stale wake loses cleanly there. A
+        // single-snapshot read would need a repeatable-read txn per wake — not worth it for this guard rail.
         const [metaRows] = await pool.query("SELECT created_at, leaf_id, leaf_seq FROM session_meta WHERE session_id = ?", [sessionId]);
         const meta = metaRows[0];
         if (!meta)
@@ -44,6 +90,7 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         const metadata = { id: sessionId, createdAt: toIso(meta.created_at) };
         return new TiDBSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, Number(meta.leaf_seq), floorEntryId, floorSeq);
     }
+    /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). */
     static async computeFloor(pool, sessionId) {
         const [compRows] = await pool.query("SELECT payload FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1", [sessionId]);
         if (!compRows[0])
@@ -53,10 +100,12 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         if (!fk)
             return { floorEntryId: null, floorSeq: 0 };
         const [seqRows] = await pool.query("SELECT seq FROM session_event WHERE session_id = ? AND entry_id = ?", [sessionId, fk]);
+        // firstKeptEntryId missing from the log (shouldn't happen) → degrade to full load.
         if (!seqRows[0])
             return { floorEntryId: null, floorSeq: 0 };
         return { floorEntryId: fk, floorSeq: Number(seqRows[0].seq) };
     }
+    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — fall back to the durable log. */
     async getEntry(id) {
         const inMem = await super.getEntry(id);
         if (inMem)
@@ -72,10 +121,16 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         this.recordEntry(entry);
     }
     async setLeafId(leafId, opts) {
+        // A leaf move is itself a persisted `leaf` entry whose parent is the current leaf.
         const leafEntry = this.createLeafEntry(leafId);
         await this.persist(leafEntry, opts);
         this.recordEntry(leafEntry);
     }
+    /**
+     * Atomically: CAS the meta leaf (+bump leaf_seq), then append the event at the new seq.
+     * The `(session_id, seq)` primary key is the backstop — a racing writer that grabbed the same
+     * seq makes our INSERT fail with a duplicate-key, which we translate to a conflict too.
+     */
     async persist(entry, opts) {
         const newLeaf = leafIdAfterEntry(entry);
         const conditional = opts !== undefined && opts.expectedLeafId !== undefined;
@@ -92,17 +147,21 @@ export class TiDBSessionStorage extends BaseSessionStorage {
             }
             const [seqRows] = await conn.query("SELECT leaf_seq, owner FROM session_meta WHERE session_id = ?", [this.sessionId]);
             const seq = Number(seqRows[0].leaf_seq);
+            // codex-2(S2 批):S2 发射的 owner 必须取**本事务当前行**——wake 快照在「wake 后被 delete+reclaim」
+            // 窗口里是陈旧 A,而旧 A 条目仍在=假匹配,新租户 leaf 泄进旧流。事务内同 SELECT 捎带=commit 时刻
+            // 真 owner,零额外查询;reclaim 后=B ⇒ notifyLocal 对 A 条目 drop(围栏真闭合)。
             const commitOwner = seqRows[0].owner ?? null;
             await conn.query("INSERT INTO session_event (session_id, seq, entry_id, parent_id, type, payload, ts) VALUES (?,?,?,?,?,?,?)", [this.sessionId, seq, entry.id, entry.parentId ?? null, entry.type, JSON.stringify(entry), new Date(entry.timestamp)]);
             await conn.commit();
             this.leafSeq = seq;
-            emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq);
+            emitLeafAdvance(this.sessionId, newLeaf, commitOwner, seq); // S2 fast path — post-commit only, fire-and-forget (session-leaf-bus 契约)
         }
         catch (err) {
             try {
                 await conn.rollback();
             }
             catch {
+                /* ignore rollback error */
             }
             if (err instanceof SessionError)
                 throw err;

package/dist/plugins/tidb-session-store.d.ts

@@ -1,24 +1,55 @@
+/**
+ * TiDB-backed Session event-log center (L1) — the durable "persistence center".
+ *
+ * Implements core's `SessionStore`. `acquire` rebuilds a session from its append-only event log
+ * (= wake/resume), so any stateless runner instance can continue it. Cross-instance write safety is
+ * enforced by the storage layer's compare-and-set (core's F2 seam); crash consistency (orphan
+ * tool-call after a mid-turn crash) is handled by the Runner calling `reconcileInterruptedSession`
+ * on acquire (core's F1).
+ *
+ * Persistence only. **Tenant authorization (who may wake which session) lives in the service layer**
+ * (`src/security.ts`), which uses `ownerOf` / `register` below. The store does not infer identity.
+ */
 import { type AcquiredSession, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import type { SessionSummary } from "./store-contracts.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
     constructor(pool: Pool);
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
     }): Promise<AcquiredSession>;
     private load;
+    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** Owner principal of a session, `null` if registered ownerless, `undefined` if no such session. */
     ownerOf(sessionId: string): Promise<string | null | undefined>;
     touch(sessionId: string): Promise<void>;
+    /** E18 — the session's current leaf `SessionTreeEntry.id` (`session_meta.leaf_id`, set transactionally on every
+     *  persist). A single SELECT, NO acquire/lock/CAS — safe to call mid-run (write-safety is the append-time CAS, not
+     *  an acquire lease) and cache-bypassing (the resume-at turn-capture reads it without touching the warm session).
+     *  Returns the leaf id, or null when the session has none / no such session. */
     getLeafId(sessionId: string): Promise<string | null>;
+    /** [1196] 六轮复审:owner+leafId **单行原子快照**(SSE watch 探针的租户围栏读)——两独立 SELECT 在
+     *  delete/reclaim 缝里可拼出「旧 owner+新 leaf」混世代组合;单 SELECT 单行=天然一致。undefined=无此会话。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
+    /** Durable history is retained; just drop any in-flight cache entry. */
     release(sessionId: string): Promise<void>;
+    /**
+     * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity.
+     * Session IDENTITY/enumeration comes from `session_meta` (owner-filtered on the service's OWN owner column);
+     * a LEFT JOIN onto the `task_run` runs ledger supplies run-level PREVIEW (latest run's objective/status,
+     * run count) but never gates which sessions exist — a session with zero runs still lists (preview null/0).
+     * Keyset on `(updated_at, session_id)`; `updated_at` is the session's last-activity marker (touch on every
+     * run/append). The shipped {@link SessionSummary} shape is preserved (additive): `lastActivityAt` =
+     * `session_meta.updated_at`, `firstActivityAt` = `session_meta.created_at`.
+     */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -28,21 +59,132 @@ export declare class TiDBSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires
+     *  before the Runner's session acquire — the titler retries), "untitled" / "titled" as read. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
+    /** Write-once auto-title: lands ONLY when title IS NULL (a concurrent/prior title wins;
+     *  the user-facing rename layer is BFF-side). Returns whether this call set it. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /**
+     * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
+     * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is
+     * re-densified from 0 in the new session. The new leaf = the source leaf (session_meta.leaf_id).
+     * Returns the new sessionId, or null if the source does not exist (the route maps that to 404).
+     *
+     * 🔴 FULL history, NOT `wake().getEntries()` (adversarial-review MEDIUM): `wake` loads only the bounded tail
+     * `[floor..leaf]` from the latest compaction floor (F3), so forking via it would copy only the active tail of a
+     * COMPACTED session and SILENTLY LOSE all pre-compaction history (contradicting the whole-history-copy intent).
+     * We instead SELECT the entire `session_event` log ordered by seq — every durable entry, compaction floor
+     * bypassed — and re-seq it dense from 0 into the new session, ids/parents/payload byte-verbatim.
+     */
     fork(sourceId: string, owner: string | null): Promise<string | null>;
+    /**
+     * 2c session-sync — EXPORT a session's full durable entry log for cross-backend migration. This is the
+     * READ half of {@link fork}, surfaced as the core `SessionRepo.exportEntries` seam: the WHOLE `session_event` log,
+     * oldest-first, ids/parents/payload/ts VERBATIM, with the compaction floor BYPASSED (NOT `wake().getEntries()`,
+     * which returns only the bounded `[floor..leaf]` tail and would silently truncate pre-floor history — see fork's
+     * note at :149-152). Returns `null` if the source does not exist (no `session_meta` row), mirroring fork's null
+     * semantics; an existing-but-empty session returns `[]`. The owner is NOT exported — import re-stamps it (§9).
+     */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    /**
+     * 2c session-sync P1d-α (PULL streaming) — the IDS-ONLY projection of {@link exportEntries}: the entry ids of the
+     * WHOLE durable log, oldest-first (`SELECT entry_id … ORDER BY seq ASC`), with no payloads. Small even for a huge
+     * session, so the PULL `GET /sync/manifest` can carry it (and feed it to `classifySyncRelationshipByIds`) instead of
+     * the entries. Returns `null` if the source does not exist (no `session_meta` row), mirroring {@link exportEntries}.
+     */
     listEntryIds(sessionId: string): Promise<string[] | null>;
+    /**
+     * 2c session-sync P1d-α (PULL streaming) — STREAM the WHOLE durable log (compaction floor bypassed), oldest-first,
+     * as an async generator that KEYSET-PAGES the `session_event` table: mysql2 buffers a plain SELECT, so a 1M-row
+     * session would OOM if read in one shot. Instead the generator loops `… WHERE seq > cursor ORDER BY seq ASC LIMIT K`
+     * (K = `opts.batchSize ?? 500`), advancing the cursor to the last `seq` of each batch, until a SHORT page (fewer than
+     * K rows) ends the stream. Each batch is its OWN `pool.query` (a pooled connection acquired + released per batch), so
+     * a slow NDJSON consumer can NEVER pin one connection across the whole stream (the clay-mandated concurrency
+     * discipline). Start cursor = `opts.afterSeq ?? -1` (seq is 0-based dense, so `> -1` = from seq 0).
+     *
+     * Resolves to `null` (NOT an empty async-iterable) when the session does not exist — checked via `session_meta`
+     * EAGERLY here (before returning the iterable), exactly like {@link exportEntries}, so a missing session is distinct
+     * from a real-but-empty one (an empty stream). payload is parsed like {@link exportEntries} (string → JSON.parse,
+     * object passthrough). The check is eager (the method is async) because a generator body is lazy — it can't decide
+     * `null` vs. iterable on its own first pull.
+     */
     exportEntriesStream(sessionId: string, opts?: {
         afterSeq?: number;
         batchSize?: number;
     }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    /**
+     * 2c session-sync — IMPORT a verbatim entry log (from another backend's {@link exportEntries}) into a
+     * (typically NEW) `sessionId`. This is the WRITE half of {@link fork}, surfaced as `SessionRepo.importEntries`,
+     * with two 2c-mandated differences from fork:
+     *   (a) OWNER RE-STAMP (§9): `owner` is the AUTHENTICATED importing principal passed by the caller; the bundle's
+     *       own owner is NEVER trusted (a local push is always owner=null → would become an ownerless cloud session
+     *       any anonymous caller could attach to). Mirrors the fork route's server-side `scope.gateOwner`.
+     *   (b) the single INVARIANT GATE is core's {@link validateEntriesForImport} (unique ids / parent-before-child /
+     *       exactly-one-root / leaf-resolvable / structural refs present) — we persist its VERBATIM output and do NOT
+     *       re-implement any of those checks in SQL ([[core-service-boundary]]; the same discipline fork's hand-SQL
+     *       was warned about). A violation throws `SessionError("invalid_session")` and NOTHING is written.
+     * The write itself mirrors fork: re-seq dense from 0, entry_id/parent_id/payload/ts verbatim, in ONE txn with
+     * `session_meta` LAST as the commit point (a mid-import crash leaves orphan events with no meta = invisible to
+     * wake, never a half-session). The leaf is the replayed leaf (core's `leafIdAfterEntry`), matching core's import.
+     */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /**
+     * 2c session-sync (§7/§8) — IDEMPOTENT REPLACE: purge any existing conversation log for `sessionId` then re-import
+     * `entries` verbatim under `owner`, ALL in ONE txn. Unlike {@link importEntries} (a plain INSERT that crashes on a
+     * duplicate PK when the session already exists at the destination), replace is safe to run OVER an existing session
+     * — the §7 fast-forward path and a §8 retry-to-completion both land on it. The validate gate runs FIRST (fail-closed,
+     * before any write), then DELETE events + the OWNER-GUARDED meta delete (defense-in-depth, mirrors {@link deleteSession}
+     * — a wrong-owner caller can never replace another tenant's session), then the SAME shared insert body importEntries
+     * uses (so there is ONE source of the insert logic, no copy-paste drift). session_meta is still written LAST = commit
+     * point, so a mid-replace crash (post-delete, pre-insert) leaves orphan-free state (no meta = invisible to wake).
+     */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /**
+     * Shared insert half of {@link importEntries} / {@link replaceEntries} (ONE source of the insert logic, no drift):
+     * write the validated entries re-seq dense from 0 (entry_id/parent_id/type/ts verbatim), THEN session_meta LAST as
+     * the commit point. Runs inside the caller's open transaction (`conn`) so the caller owns begin/commit/rollback.
+     * `validated` is the OUTPUT of {@link validateEntriesForImport} (the caller runs the gate before opening the txn).
+     */
     private insertValidatedLog;
+    /**
+     * 2c session-sync P1d-β (PUSH streaming, §15) — begin a STAGED import into `realSessionId` under the shadow id
+     * `${realSessionId}#stg-${token}`. The route mints the uuidv7 `token` (the store never calls uuidv7/Date.now itself
+     * → the staging id is deterministic + the route owns the lease key). Returns a {@link TiDBStagingHandle} the route
+     * streams entry batches into ({@link StagingHandle.appendBatch}) then commits ({@link StagingHandle.commit}, the
+     * atomic swap) or aborts. No row is touched here — the handle is a stateless cursor over this pool.
+     */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
+    /**
+     * 2c session-sync P1d-β (staged-row inspection) — read the rows STAGED under `stagingId` (NO session_meta probe — a
+     * staging id has no meta row by construction, so {@link exportEntries} would return null), oldest-first. The Phase-B
+     * import gate is now the per-line {@link StreamingImportValidator} (core 1.143.0) run during the stream, so this
+     * is no longer the validation path; it remains the staged-row inspection seam (tests/diagnostics). Returns `[]` for an
+     * empty/unknown staging id.
+     */
     readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
+    /**
+     * 2c session-sync P1d-β (§4) — reaper for ABANDONED staging sessions: DELETE session_event rows under a staging id
+     * (`session_id LIKE '%#stg-%'`) that has NO session_meta (never committed → invisible orphans) AND whose OLDEST
+     * staged row is older than the grace window (an IN-FLIGHT stream keeps appending fresh `ts` rows → its MIN(ts) is
+     * recent → it is NOT reaped, exactly like sweepOrphanBlobs' created_at grace). Per-staging-id, so a slow but live
+     * stream is never reaped while another abandoned one is. Returns the affected row count. Driven by main.ts's reaper.
+     */
     sweepStagingSessions(): Promise<number>;
+    /**
+     * E21 — purge a session's CONVERSATION HISTORY (session_meta + session_event). Idempotent: a missing
+     * session is a no-op (returns false). The service's OWN run-ledger / checkpoint / tool-result rows are
+     * purged separately by the route's `purgeSession` coordinator — this method owns only the session
+     * abstraction's tables (the `SessionRepo.delete` half).
+     *
+     * `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
+     * route already owner-gates; `<=>` so a legacy null-owner session matches owner=null). session_event carries
+     * no owner column, so its purge is GATED on the owner-matched meta delete: if the meta DELETE matched 0 rows
+     * (wrong owner / already gone) we skip the event delete — so a wrong-owner caller can never strand-delete
+     * another tenant's events. Meta is deleted FIRST (mirrors core BUG-2: once it's gone, wake is `null`
+     * regardless of leftover events; if a crash interleaves, orphan events with NO meta are invisible, never a
+     * half-session), and the event purge only runs after that owner-matched commit point.
+     */
     deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;