@sema-agent/server 7.146.0 → 7.147.0

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

@@ -0,0 +1,131 @@
+/**
+ * **SQL 会话店 = 引擎座店 + 部署的会话格**(两方言同一只类;组合座 `store-backend.ts` 装配)。
+ *
+ * ## 两半,一只店
+ *  · **座**(`src/stores-sql/` 的方言店):引擎座表 `session_meta` / `session_event` 的唯一写者 —— 唤醒、追加、fork、导入、暂存、删除。
+ *  · **部署格**(本模块):本服务记在一只会话上的格,全部住旁表 `session_ext`(属主 `session-ext-table.ts`)—— 列表投影的标题 / 置顶 / 行标签、
+ *    换源通告的基线、位置与项目、执行放置那一格与 fork 键。读引擎座表只经它的公布列(身份、属主、化身、时刻、委派判别位);写只写旁表。
+ * 座在它的写事务里锁住根行之后调部署的**事务内钩**({@link createSqlSessionWriteHooks},契约在 `stores-sql/session-write-hooks.ts`)——
+ * 认领、本处写者、导入落 mirror、fork 键都在座的同一事务里由钩判 / 写(同事务两句:锁根行一句、钩的读写各一句)。
+ *
+ * ## 一条列表读口
+ * 列表面(`listSessions` / `listSessionRows` / `sessionSummaryOf`)是一条 SELECT、一只行映射({@link SqlSessionStore.selectListRows}):
+ * `session_meta` LEFT JOIN 旁表(标题 / 置顶;行不在 = 未命名、未置顶)LEFT JOIN run 账本的预览。两方言只差语句文本(窗函数 / `DISTINCT ON`、JSON 标量提取、
+ * LIKE 的转义字面量、布尔的读法)。
+ *
+ * ## 旁表的写序(一条,与执行放置的写序律同一条)
+ * 每个格写者在一只事务里:锁根 `session_meta` 行(行不在 ⇒ 不写)→ 补旁表行(行在不动)→ 要判格的再锁定读那一行 → 一句按 `session_id` 定址的格写。根行先 ⇒ 与座的删除 /
+ * 导入 / 换装同一锁序,外键的补行不会与删除的级联互等;补行先于锁定读 ⇒ 锁定读永远落在一行在的记录上(不拿 InnoDB 间隙锁)。
+ */
+import type { AcquiredSession, PlacedSessionRow, SessionHead, SessionPlacementRecord, SessionStore, SessionTreeEntry } from "@sema-agent/core";
+import type { TiDBSessionStore } from "../stores-sql/tidb-session-store.js";
+import type { SessionWriteHooks } from "../stores-sql/session-write-hooks.js";
+import type { SqlDriver } from "./sql-driver.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import type { SessionSummary } from "./store-contracts.js";
+import type { SessionWorkspace } from "../session-workspace.js";
+/** 座的面:座的公开成员(两方言同形 —— PG 孪生按结构赋给它,组合座里 tsc 判)。 */
+export type SessionSeat = Pick<TiDBSessionStore, "retention" | "placements" | "durability" | "acquire" | "register" | "placementOf" | "listPlaced" | "headOf" | "touch" | "release" | "forget" | "fork" | "forkTo" | "exportEntries" | "listEntryIds" | "exportEntriesStream" | "importEntries" | "replaceEntries" | "beginImportStaging" | "readStagedEntries" | "sweepStagingSessions" | "deleteSession" | "size" | "dispose">;
+/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形)。 */
+export interface SessionListOptions {
+    owner?: string;
+    includeUnowned?: boolean;
+    cursor?: {
+        lastActivityAt: string;
+        sessionId: string;
+    };
+    limit: number;
+    q?: string;
+}
+/**
+ * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
+ *  · `import` —— 判官 {@link judgeImportWrite}(local 店的写锁内同调这一只):认领在 ⇒ 拒 `SessionActiveRunError`;这一处是写者 ⇒ 拒 `SessionWriterPresentError`;放行 ⇒ 这一格落 mirror(写者在别处);
+ *  · `delete` / `retention-delete` —— 认领在 ⇒ 拒 `SessionActiveRunError`(级联随根行带走旁表行,钩不另删);
+ *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
+ */
+export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
+export declare class SqlSessionStore implements SessionStore {
+    private readonly db;
+    /** 座(引擎座表的唯一写者)。 */
+    private readonly seat;
+    /** 托管留存声明 / placement 声明 / 耐久声明:座的声明逐字转发。 */
+    readonly retention: SessionSeat["retention"];
+    readonly placements: SessionSeat["placements"];
+    readonly durability: SessionSeat["durability"];
+    /** 执行席(规则在 `src/execution-placement.ts`;实现与语句的唯一属主 = `execution-placement-sql.ts`)。 */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** `db` = 座的池包成的 SqlDriver(同一只池);`seatOn` 拿部署的事务内钩建座。 */
+    constructor(db: SqlDriver, seatOn: (hooks: SessionWriteHooks) => SessionSeat);
+    acquire(...a: Parameters<SessionSeat["acquire"]>): Promise<AcquiredSession>;
+    register(sessionId: string, owner: string | null): Promise<void>;
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
+    listPlaced(...a: Parameters<SessionSeat["listPlaced"]>): Promise<PlacedSessionRow[]>;
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
+    touch(sessionId: string): Promise<void>;
+    release(sessionId: string): Promise<void>;
+    forget(sessionId: string): void;
+    fork(...a: Parameters<SessionSeat["fork"]>): ReturnType<SessionSeat["fork"]>;
+    forkTo(...a: Parameters<SessionSeat["forkTo"]>): ReturnType<SessionSeat["forkTo"]>;
+    exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    listEntryIds(sessionId: string): Promise<string[] | null>;
+    exportEntriesStream(...a: Parameters<SessionSeat["exportEntriesStream"]>): ReturnType<SessionSeat["exportEntriesStream"]>;
+    importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    beginImportStaging(...a: Parameters<SessionSeat["beginImportStaging"]>): ReturnType<SessionSeat["beginImportStaging"]>;
+    readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
+    sweepStagingSessions(): Promise<number>;
+    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
+    get size(): number;
+    dispose(): 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 its owner column); the side table supplies the title / pin; 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. Keyset on `(updated_at, session_id)`.
+     */
+    listSessions(opts: SessionListOptions): Promise<SessionSummary[]>;
+    /** {@link listSessions} with each row's occupant (owner + incarnation) from the same SELECT — `OwnerAwareSessionStore.listSessionRows`; the incarnation never enters the row. */
+    listSessionRows(opts: SessionListOptions): Promise<Array<SessionRowAnswer<SessionSummary>>>;
+    /** ONE session's list row — {@link listSessions}' projection (same SELECT, same mapper) scoped to one id; `undefined` = not a row of the list face
+     *  (no such session / placed). The run-preview subqueries are scoped to the same id. */
+    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
+    /** {@link sessionSummaryOf} 那一读 + 读到它时行上的住客(写原语的应答行要复核住客,`settleSessionRowWrite`)。 */
+    private listRowOf;
+    /**
+     * The list projection's ONE SELECT + row mapper ({@link listSessions} and {@link sessionSummaryOf} both read through it). `runSessionId` scopes the
+     * two run-preview subqueries to one session (the single-row read); the list leaves them whole. Placeholders are minted in text order (run scope,
+     * then `where`, then the LIMIT), so one builder serves both dialects. `sm.incarnation` is read for the row tag and the answer row's occupant only.
+     * The run-preview JOIN: the LATEST run per session (ties broken by task_id so EXACTLY one row joins) + a count rollup; LEFT JOINs keep sessions with
+     * no runs (preview NULL, run_count 0) and sessions with no side-table row (title NULL, not pinned).
+     */
+    private selectListRows;
+    /**
+     * 会话行格写原语 —— 用户标题 / 置顶的唯一写口(规则与判序:`src/session-row.ts` 头注「写原语」;事务与语句:`session-row-sql.ts`)。应答行在提交 / 回滚之后
+     * 由列表行读另读(含新 `rowTag`)、复核仍是判过的那一位住客。只写列表面上的行(委派分区行 ⇒ `absent`);`updated_at` 不动(改名不是活动)。
+     */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<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 (no side-table row = untitled). */
+    probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
+    /** The auto-titler's write: lands ONLY when title IS NULL (a concurrent/prior title — the user's included — wins; writer order: `src/session-row.ts`).
+     *  Returns whether this call set it. No session row ⇒ `false`. */
+    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** 换源通告的基线读(一行 PK 读;列的三态读法见 `instruction-source-notice.ts`)。旁表行不在 ⇒ 读作「没记过」。语句期限 {@link BASELINE_IO_DEADLINE_MS}(过期 ⇒ 查询自己拒、连接销毁)。 */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。会话行不在 ⇒ 不写。**不**碰 `updated_at`。
+     * 期限:事务里每一句带语句期限 {@link BASELINE_IO_DEADLINE_MS} —— 被行锁卡住的写由查询自己在期限内拒、连接销毁(事务随连接关闭回滚,池里不留卡住的连接);
+     * 调用方的 `withinIoDeadline` 同一只数,是它那一侧的放手。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /** 会话行的位置与项目那一格(域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座)。**住客围栏**:只写化身仍是 `incarnation` 的那一行(锁根行时按化身收窄)—— 行不在、或同 id 已换了住客 ⇒
+     * 不写、不抛。**不**碰 `updated_at`。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
+}
+//# sourceMappingURL=session-store-sql.d.ts.map

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

@@ -0,0 +1,298 @@
+import { escapeLike } from "./sql-escape.js";
+import { jsonColumnText } from "./sql-json-column.js";
+import { pgSafeJsonStringify } from "./pg-safe-json.js";
+import { SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
+import { createSqlExecutionPlacementSeat, markMirrorStatement, readCellOn, readClaimOn, writeCellOn } from "./execution-placement-sql.js";
+import { SessionActiveRunError, judgeImportWrite } from "../execution-placement.js";
+import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
+import { incarnationFromCell } from "../session-incarnation.js";
+import { sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+const rowsOnTxn = (txn) => async (sql, values) => (await txn.query(sql, [...values])).rows;
+export function createSqlSessionWriteHooks(db) {
+    const dialect = db.dialect;
+    return {
+        async beforeCommit(txn, write) {
+            const rows = rowsOnTxn(txn);
+            const root = write.rootSessionId;
+            switch (write.op) {
+                case "import": {
+                    const verdict = await judgeImportWrite(root, { claim: () => readClaimOn(rows, dialect, root), cell: () => readCellOn(rows, dialect, root) });
+                    if (verdict !== "proceed")
+                        return verdict;
+                    await writeCellOn(txn, dialect, root, markMirrorStatement(dialect, root));
+                    return "proceed";
+                }
+                case "delete":
+                case "retention-delete": {
+                    const claim = await readClaimOn(rows, dialect, root);
+                    return claim === null ? "proceed" : { refuse: new SessionActiveRunError(root, claim) };
+                }
+                default: {
+                    const unknownOp = write.op;
+                    throw new Error(`session write hooks: no write ${JSON.stringify(unknownOp)}`);
+                }
+            }
+        },
+        keyedFork: {
+            async record(txn, fork) {
+                const ensure = ensureSessionExtRowStatement(dialect, fork.rootSessionId);
+                await txn.query(ensure.text, [...ensure.values]);
+                const b = binder(dialect);
+                const res = await txn.query(`UPDATE ${SESSION_EXT_TABLE} SET fork_key = ${b.p(fork.forkKey)} WHERE session_id = ${b.p(fork.rootSessionId)}`, b.values);
+                if (res.affected !== 1)
+                    throw new Error(`fork of session ${fork.rootSessionId}: the fork key write matched no row of a row this transaction just created — engine/driver anomaly, refusing to guess`);
+            },
+            async targetOf(sessionId) {
+                const b = binder(dialect);
+                const row = (await db.query(`SELECT sm.owner, se.fork_key FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+                if (row === undefined)
+                    return undefined;
+                return { owner: row.owner === null || row.owner === undefined ? null : String(row.owner), forkKey: row.fork_key === null || row.fork_key === undefined ? null : String(row.fork_key) };
+            },
+        },
+    };
+}
+const BASELINE_STATEMENT = { deadlineMs: BASELINE_IO_DEADLINE_MS };
+async function withLockedSessionExt(db, sessionId, lock, write) {
+    const conn = await db.connect();
+    const query = (sql, params) => conn.query(sql, params, lock.statement);
+    try {
+        await conn.begin();
+        const b = binder(db.dialect);
+        const locked = await query(`SELECT session_id FROM session_meta WHERE session_id = ${b.p(sessionId)}${lock.where === undefined ? "" : ` AND ${lock.where(b.p)}`} FOR UPDATE`, b.values);
+        if (locked.rows.length === 0) {
+            await conn.rollback();
+            return false;
+        }
+        const ensure = ensureSessionExtRowStatement(db.dialect, sessionId);
+        await query(ensure.text, [...ensure.values]);
+        const wrote = await write(query);
+        await conn.commit();
+        return wrote;
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+const pinnedOf = (dialect, v) => (dialect === "pg" ? v === true : Number(v) === 1);
+export class SqlSessionStore {
+    db;
+    seat;
+    retention;
+    placements;
+    durability;
+    executionPlacement;
+    constructor(db, seatOn) {
+        this.db = db;
+        this.seat = seatOn(createSqlSessionWriteHooks(db));
+        this.retention = this.seat.retention;
+        this.placements = this.seat.placements;
+        this.durability = this.seat.durability;
+        this.executionPlacement = createSqlExecutionPlacementSeat(db);
+    }
+    acquire(...a) {
+        return this.seat.acquire(...a);
+    }
+    register(sessionId, owner) {
+        return this.seat.register(sessionId, owner);
+    }
+    placementOf(sessionId) {
+        return this.seat.placementOf(sessionId);
+    }
+    listPlaced(...a) {
+        return this.seat.listPlaced(...a);
+    }
+    headOf(sessionId) {
+        return this.seat.headOf(sessionId);
+    }
+    touch(sessionId) {
+        return this.seat.touch(sessionId);
+    }
+    release(sessionId) {
+        return this.seat.release(sessionId);
+    }
+    forget(sessionId) {
+        this.seat.forget(sessionId);
+    }
+    fork(...a) {
+        return this.seat.fork(...a);
+    }
+    forkTo(...a) {
+        return this.seat.forkTo(...a);
+    }
+    exportEntries(sessionId) {
+        return this.seat.exportEntries(sessionId);
+    }
+    listEntryIds(sessionId) {
+        return this.seat.listEntryIds(sessionId);
+    }
+    exportEntriesStream(...a) {
+        return this.seat.exportEntriesStream(...a);
+    }
+    importEntries(sessionId, owner, entries) {
+        return this.seat.importEntries(sessionId, owner, entries);
+    }
+    replaceEntries(sessionId, owner, entries) {
+        return this.seat.replaceEntries(sessionId, owner, entries);
+    }
+    beginImportStaging(...a) {
+        return this.seat.beginImportStaging(...a);
+    }
+    readStagedEntries(stagingId) {
+        return this.seat.readStagedEntries(stagingId);
+    }
+    sweepStagingSessions() {
+        return this.seat.sweepStagingSessions();
+    }
+    deleteSession(sessionId, owner) {
+        return this.seat.deleteSession(sessionId, owner);
+    }
+    get size() {
+        return this.seat.size;
+    }
+    dispose() {
+        this.seat.dispose();
+    }
+    async listSessions(opts) {
+        return (await this.listSessionRows(opts)).map((a) => a.row);
+    }
+    async listSessionRows(opts) {
+        const dialect = this.db.dialect;
+        return this.selectListRows({
+            limit: opts.limit,
+            where: (p) => {
+                const where = ["sm.placement_kind IS NULL"];
+                if (opts.owner !== undefined)
+                    where.push(opts.includeUnowned ? `(sm.owner = ${p(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${p(opts.owner)}`);
+                if (opts.q) {
+                    const escape = dialect === "pg" ? "'\\'" : "'\\\\'";
+                    where.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${p(`%${escapeLike(opts.q)}%`)}) ESCAPE ${escape})`);
+                }
+                if (opts.cursor) {
+                    const at = new Date(opts.cursor.lastActivityAt);
+                    where.push(`(sm.updated_at < ${p(at)} OR (sm.updated_at = ${p(at)} AND sm.session_id < ${p(opts.cursor.sessionId)}))`);
+                }
+                return where;
+            },
+        });
+    }
+    async sessionSummaryOf(sessionId) {
+        return (await this.listRowOf(sessionId))?.row;
+    }
+    async listRowOf(sessionId) {
+        return (await this.selectListRows({ limit: 1, runSessionId: sessionId, where: (p) => ["sm.placement_kind IS NULL", `sm.session_id = ${p(sessionId)}`] }))[0];
+    }
+    async selectListRows(q) {
+        const dialect = this.db.dialect;
+        const b = binder(dialect);
+        const runWhere = () => (q.runSessionId !== undefined ? ` WHERE session_id = ${b.p(q.runSessionId)}` : "");
+        const runCount = `LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run${runWhere()} GROUP BY session_id) r ON r.session_id = sm.session_id `;
+        const latest = dialect === "pg"
+            ? "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id, result ->> 'runId' AS last_task_run_id FROM task_run" +
+                runWhere() +
+                "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.session_id = sm.session_id "
+            : "LEFT JOIN (SELECT session_id, objective_preview, status, task_id, last_task_run_id FROM (" +
+                "    SELECT session_id, objective_preview, status, task_id, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id, " +
+                "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" +
+                runWhere() +
+                "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id ";
+        const where = q.where(b.p);
+        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, se.title, se.pinned, " +
+            "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
+            "FROM session_meta sm " +
+            `LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            runCount +
+            latest +
+            (where.length ? "WHERE " + where.join(" AND ") + " " : "") +
+            `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${b.p(q.limit)}`;
+        const rows = (await this.db.query(sql, b.values)).rows;
+        return rows.map((r) => {
+            const runId = r.last_task_run_id;
+            const sessionId = String(r.session_id);
+            const owner = r.owner ?? null;
+            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
+            const title = r.title ?? null;
+            const pinned = pinnedOf(dialect, r.pinned);
+            const row = {
+                sessionId,
+                owner,
+                lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
+                firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
+                runCount: Number(r.run_count),
+                objectivePreview: r.objective_preview ?? null,
+                lastStatus: r.status == null ? "" : String(r.status),
+                lastRunId: r.last_run_id ?? null,
+                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
+                title,
+                pinned,
+                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
+            };
+            return { row, occupant: { owner, incarnation } };
+        });
+    }
+    async writeSessionRowCells(sessionId, cells, how) {
+        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
+    }
+    async probeTitle(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT se.title FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        if (row === undefined)
+            return "none";
+        return row.title === null || row.title === undefined ? "untitled" : "titled";
+    }
+    async setTitleIfNull(sessionId, title) {
+        return withLockedSessionExt(this.db, sessionId, {}, async (query) => {
+            const b = binder(this.db.dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
+        });
+    }
+    async readInstructionSource(sessionId) {
+        const b = binder(this.db.dialect);
+        const conn = await this.db.connect();
+        try {
+            const row = (await conn.query(`SELECT instruction_source FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values, BASELINE_STATEMENT)).rows[0];
+            return decodeInstructionSource(row?.instruction_source);
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        const next = encodeInstructionSource(source);
+        await withLockedSessionExt(this.db, sessionId, { statement: BASELINE_STATEMENT }, async (query) => {
+            const b = binder(this.db.dialect);
+            const text = `UPDATE ${SESSION_EXT_TABLE} SET instruction_source = ${b.p(next)} WHERE session_id = ${b.p(sessionId)} AND ${expected.recorded ? `instruction_source = ${b.p(encodeInstructionSource(expected.source))}` : "instruction_source IS NULL"}`;
+            return (await query(text, b.values)).affected > 0;
+        });
+    }
+    async readSessionWorkspace(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT ${jsonColumnText(this.db.dialect, "workspace")} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        const dialect = this.db.dialect;
+        const cell = encodeSessionWorkspaceCell(workspace, dialect === "pg" ? pgSafeJsonStringify : JSON.stringify, sessionId);
+        await withLockedSessionExt(this.db, sessionId, { where: (p) => `incarnation = ${p(incarnation)}` }, async (query) => {
+            const b = binder(dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET workspace = ${b.p(cell)}${dialect === "pg" ? "::jsonb" : ""} WHERE session_id = ${b.p(sessionId)}`, b.values)).affected > 0;
+        });
+    }
+}
+//# sourceMappingURL=session-store-sql.js.map

package/dist/plugins/session-workspace-cell.d.ts

@@ -1,7 +1,7 @@
 import type { SessionWorkspace } from "../session-workspace.js";
 import { type JsonColumnReader } from "./sql-json-column.js";
-/** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
-export declare const SESSION_META_WORKSPACE_COLUMN: {
+/** 列定义的唯一属主(旁表建表句内插它,`session-ext-table.ts`)。 */
+export declare const SESSION_WORKSPACE_COLUMN: {
     readonly name: "workspace";
     readonly mysql: "workspace JSON NULL";
     readonly pg: "workspace JSONB";

package/dist/plugins/session-workspace-cell.js

@@ -2,7 +2,7 @@ import { PROJECT_ID_REGEX } from "@sema-agent/core";
 import { z } from "zod";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { assertJsonColumnWritable, createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
-export const SESSION_META_WORKSPACE_COLUMN = {
+export const SESSION_WORKSPACE_COLUMN = {
     name: "workspace",
     mysql: "workspace JSON NULL",
     pg: "workspace JSONB",
@@ -16,7 +16,7 @@ const SESSION_WORKSPACE_SHAPE = z.object({
 });
 export const readSessionWorkspaceCell = createZodColumnReader(SESSION_WORKSPACE_SHAPE);
 export const SESSION_WORKSPACE_DEGRADED = "server.session-workspace.record-degraded";
-const where = (sessionId) => `session_meta.workspace for session ${sessionId}`;
+const where = (sessionId) => `session_ext.workspace for session ${sessionId}`;
 export function encodeSessionWorkspaceCell(workspace, encode, sessionId) {
     const text = encode(workspace);
     assertJsonColumnWritable(text, readSessionWorkspaceCell, where(sessionId));

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -131,6 +131,16 @@ export interface SqlSharedMemoryStoreOptions {
  * This module keeps no copy of the pattern (nor of the `__` ban): the protocol table's namespace separator is core's to spell.
  */
 export declare function assertStoreId(storeId: string): void;
+/**
+ * MINT-side org scope key admission. The rule is core's own judge ({@link isOrgScopeKey}): `org:` plus one segment spelled by core's
+ * `formatOrgScope`. This module keeps no copy of the grammar, and no width bound of its own — core's segment bound is far inside the
+ * `scope_key` column.
+ *
+ * Called only where a key ENTERS a durable row: {@link SqlSharedMemoryStore.putScopeState} and {@link SqlSharedMemoryStore.putStore}.
+ * The other write methods take the key as a FENCE against the owner already registered for the store id ({@link ownedExactly}: a byte-for-byte
+ * match, loud on a miss), so they never judge its shape: a row stored under a key this judge now refuses stays addressable — it can still be
+ * written to and deleted, which is the way out for an operator who must re-home it under a key core accepts.
+ */
 export declare function assertScopeKey(scopeKey: string): void;
 /**
  * WRITE-side document-path admission: core's own judge ({@link isSharedMemoryDocumentPath} — the SAME predicate core's listing

package/dist/plugins/shared-memory-store-sql.js

@@ -1,11 +1,10 @@
-import { isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
+import { isOrgScopeKey, isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 const isDupKey = isDupKeyError;
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
 export const SHARED_MEMORY_ENTRY_TABLE = "shared_memory_entry";
-const ORG_SCOPE_RE = /^org:\S{1,185}$/;
 const PATH_MAX_CHARS = 512;
 const DESCRIPTION_MAX_CHARS = 512;
 const DEFAULT_MAX_LIST_LIMIT = 500;
@@ -15,10 +14,14 @@ export function assertStoreId(storeId) {
     }
 }
 export function assertScopeKey(scopeKey) {
-    if (!ORG_SCOPE_RE.test(scopeKey)) {
-        throw new Error(`shared-memory scope key ${JSON.stringify(scopeKey)} is not usable: it must match /^org:\\S{1,185}$/`);
+    if (!isOrgScopeKey(scopeKey)) {
+        throw new Error(`shared-memory scope key ${JSON.stringify(scopeKey)} is not usable: core's org scope key rule refuses it (spell the org with core's formatOrgScope: "org:" plus the name's percent-encoded segment)`);
     }
 }
+function ownedExactly(rows, scopeKey) {
+    const row = rows[0];
+    return row !== undefined && String(row.scope_key) === scopeKey;
+}
 export function assertDocumentPath(path) {
     const refuse = (why) => {
         throw new Error(`shared-memory document path ${JSON.stringify(path)} is not usable: ${why}`);
@@ -267,7 +270,6 @@ export class SqlSharedMemoryStore {
     }
     async putDocument(record) {
         assertStoreId(record.storeId);
-        assertScopeKey(record.scopeKey);
         assertDocumentPath(record.path);
         const sizeBytes = Buffer.byteLength(record.content, "utf8");
         if (sizeBytes > SHARED_MEMORY_READ_CAP_BYTES) {
@@ -278,8 +280,8 @@ export class SqlSharedMemoryStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [record.storeId, record.scopeKey]);
-            if (registered.rows.length === 0) {
+            const registered = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [record.storeId, record.scopeKey]);
+            if (!ownedExactly(registered.rows, record.scopeKey)) {
                 unregistered = true;
                 await conn.rollback();
             }
@@ -303,14 +305,13 @@ export class SqlSharedMemoryStore {
     }
     async deleteDocument(storeId, scopeKey, path) {
         assertStoreId(storeId);
-        assertScopeKey(scopeKey);
         let unregistered = false;
         let deleted = false;
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
-            if (registered.rows.length === 0) {
+            const registered = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (!ownedExactly(registered.rows, scopeKey)) {
                 unregistered = true;
                 await conn.rollback();
             }
@@ -334,13 +335,12 @@ export class SqlSharedMemoryStore {
     }
     async deleteStore(storeId, scopeKey) {
         assertStoreId(storeId);
-        assertScopeKey(scopeKey);
         let notOwned = false;
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const owned = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
-            if (owned.rows.length === 0) {
+            const owned = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (!ownedExactly(owned.rows, scopeKey)) {
                 notOwned = true;
                 await conn.rollback();
             }

package/dist/plugins/snapshot-bucket-presence.js

@@ -58,7 +58,7 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock, role =
 export async function ensureSnapshotBuckets(config, logger) {
     const wanted = [
         ["session", config.snapshotBlobStore],
-        ["workspace", config.remoteExec?.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
+        ["workspace", config.remoteExec.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
     ];
     for (const [role, store] of wanted) {
         if (store)

package/dist/plugins/sql-driver.d.ts

@@ -21,9 +21,13 @@
  *     ⚠️ The dup-key predicate ITSELF is NOT store-specific and no longer lives at the call sites:
  *     `sql-errors.ts` owns it ([ref] P1-①; 7+ hand-rolled copies had drifted into three different
  *     recognition sets, so the same driver error got opposite verdicts in different stores).
- *   - per-query timeouts: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig` with
- *     `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
- *     exec; this seam stays on the plain (sql, params) form.
+ *   - per-query timeouts on the POOL form: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig`
+ *     with `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
+ *     exec; the pool form of this seam stays on the plain (sql, params) form.
+ *     A LENT connection ({@link SqlTxConn.query}) takes one optional per-statement deadline
+ *     ({@link SqlStatementOptions}): past it the statement rejects ({@link SqlStatementDeadlineExceeded}) and the lease
+ *     is destroyed first (its session / transaction state is unknown — it never goes back to the pool; the server
+ *     rolls the open transaction back when the connection closes). Same rule on both dialects, one implementation.
  *
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
  * @contract txn.read-semantics — 本仓「事务里的读看到什么」的**唯一**成文处([ref] / [ref] / [ref])
@@ -127,8 +131,20 @@ export interface SqlResult {
 export interface SqlExec {
     query(sql: string, params?: unknown[]): Promise<SqlResult>;
 }
+/** Per-statement options of a lent connection's {@link SqlTxConn.query}. */
+export interface SqlStatementOptions {
+    /** The statement rejects ({@link SqlStatementDeadlineExceeded}) if it has not settled within this many ms; the lease is destroyed first. */
+    readonly deadlineMs?: number;
+}
+/** A lent connection's statement did not settle within its deadline: the connection was destroyed (never pooled again), the statement rejected. Typed so callers triage it without reading the message. */
+export declare class SqlStatementDeadlineExceeded extends Error {
+    readonly deadlineMs: number;
+    constructor(deadlineMs: number);
+}
 /** A pooled connection with transaction control (released by the caller in a `finally`). */
 export interface SqlTxConn extends SqlExec {
+    /** {@link SqlExec.query}, with an optional per-statement deadline (see the file header). */
+    query(sql: string, params?: unknown[], opts?: SqlStatementOptions): Promise<SqlResult>;
     /**
      * The ONE transaction verb ([ref]). What its reads see is NOT decided here — it is decided once per
      * pooled connection at initialization and reported by {@link SqlDriver.facts}. Read the
@@ -200,7 +216,7 @@ export interface SqlEngineFacts {
      *    ({@link PACKET_CAP_UNREAD_LANDING_BYTES}), recorded through `recordFailOpen("server.sql.packet-cap-unread")` (a per-hit
      *    count and one warn line naming the reason). Never `null`: on these engines the wall exists, only its size may be unread.
      *  · **`null`** — PostgreSQL: the extended protocol has no statement-size wall.
-     * Its final judge: the SQL snapshot-blob cap (`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`), which borrows the connection
+     * Its final judge: the SQL snapshot-blob cap (`stores-sql/blob-index-sql.ts` `SqlBlobIndex.put`, the SQL-kept arm), which borrows the connection
      * it will write on through {@link connectJudged}, reads this off it ({@link sqlConnectionFacts}), judges, and writes on that
      * same connection — and when it refuses on a connection opened before the DBA raised the wall, that stale connection is
      * replaced and the write judged once more ({@link connectJudged}). On {@link SqlDriver.facts} the value is the most recently
@@ -305,7 +321,7 @@ export interface SqlWallsReading extends SqlWalls {
 }
 /**
  * 一只 SQL 池的**引擎读口**:方言(SQL 文本轴,装配事实,恒在)+ 此刻的引擎事实(`null` = 没建立)。墙的方言只从这里来 —— 与事实同出一只驱动
- * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobBackend`)各读本池的这一只。
+ * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobIndex`)各读本池的这一只。
  */
 export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
 /**
@@ -317,7 +333,7 @@ export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
 export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
 /**
  * 🔴 **此刻一份写入要装进的墙 —— 唯一判官**。两个读者同调它、不各读 `facts`:提交受理口(`http/request-guards.ts` `refuseSubmitBody`)与 SQL 快照 blob 的缺省帽
- * (`plugins/blob-backend.ts` `sqlBlobCapOf`:店的写前判,读的是**将要执行写入的那条连接**的读口 —— 方言 + 它自己那次初始化的事实;受理口读本池驱动的读口)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出),一种读法:
+ * (`stores-sql/blob-index-sql.ts` `sqlBlobCapOf`:店的写前判,读的是**将要执行写入的那条连接**的读口 —— 方言 + 它自己那次初始化的事实;受理口读本池驱动的读口)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出),一种读法:
  *  · 读口缺席 = 没有 SQL 后端 ⇒ 没有墙(「忘了给」读不成这一臂:后端交出了 SQL 池而没给读口 ⇒ `createHttpServer` 起服拒,见 `ServiceDeps.sqlEngine`);
  *  · 事实在场 ⇒ 事实里的两位,出处逐墙取事实里记的那一份({@link SqlEngineFacts.wallSources}:读到的 `reported`,读失败退文档缺省的 `assumed`);
  *  · 事实缺席(`null`)⇒ 按读口的方言:PG 没有墙(扩展协议没有这两堵墙 —— 方言事实,不随引擎事实缺席);MySQL 协议 ⇒ {@link SQL_FACTS_ABSENT_WALLS}(两堵都 `assumed`;
@@ -373,7 +389,7 @@ export interface SqlDriver extends SqlExec {
 }
 /**
  * 一条**借出的**连接自己的引擎事实 —— 它的初始化回读到的那一份(包墙 `maxPacketBytes` 是这条连接的会话值)。判一条语句装不装得下的地方
- * 只读这里:借出连接 → 读它的墙 → 判 → 在同一条连接上执行(`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`)。
+ * 只读这里:借出连接 → 读它的墙 → 判 → 在同一条连接上执行(`stores-sql/blob-index-sql.ts` `SqlBlobIndex.put`)。
  * 只认本模块的 `mysqlDriver` / `pgDriver` 的 `connect()` 借出的连接;别的连接(测试替身、包装体)没有经过初始化,墙没人读过 ⇒ **响亮抛**,不猜一个数。
  */
 export declare function sqlConnectionFacts(conn: SqlTxConn): SqlEngineFacts;