@sema-agent/server 1.314.0 → 1.316.0

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

@@ -0,0 +1,52 @@
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool, PoolClient } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+export interface ApprovalRow {
+    id: string;
+    taskId: string | null;
+    sessionId: string | null;
+    owner: string | null;
+    scope: string | null;
+    toolName: string;
+    args: unknown;
+    status: ApprovalStatus;
+    reason: string | null;
+    decidedBy: string | null;
+    createdAt: string;
+    decidedAt: string | null;
+}
+export declare const PG_APPROVAL_SCHEMA: string[];
+export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+export declare class SqlApprovalStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    private q;
+    private json;
+    createPending(id: string, scope: string | null, ctx: {
+        taskId?: string | null;
+        sessionId?: string | null;
+        owner?: string | null;
+        toolName: string;
+        args: unknown;
+    }): Promise<void>;
+    getStatus(id: string, scope: string | null): Promise<{
+        status: ApprovalStatus;
+        reason: string | null;
+        decidedBy: string | null;
+    } | undefined>;
+    decide(id: string, scope: string | null, decision: "approved" | "denied" | "expired", reason: string | null, decidedBy: string | null): Promise<boolean>;
+    listPending(scope: string | null, owner?: string): Promise<ApprovalRow[]>;
+    get(id: string, scope: string | null): Promise<ApprovalRow | undefined>;
+    getById(id: string): Promise<ApprovalRow | undefined>;
+    listPendingAll(): Promise<ApprovalRow[]>;
+    expireStale(olderThanMs: number): Promise<number>;
+}
+export declare function mapRow(r: Record<string, unknown>): ApprovalRow;
+export declare class TiDBApprovalStore extends SqlApprovalStore {
+    constructor(pool: MySqlPool);
+}
+export declare class PgApprovalStore extends SqlApprovalStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=approval-store-sql.d.ts.map

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

@@ -0,0 +1,119 @@
+import { parseJsonStrict as parseJson, toIsoOrNull as iso } from "./sql-row-helpers.js";
+import { pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+export const PG_APPROVAL_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS approval (
+     id          VARCHAR(64)  NOT NULL,
+     task_id     VARCHAR(64),
+     session_id  VARCHAR(64),
+     owner       VARCHAR(190),
+     -- Single-DB fleet scope guard (tenant isolation). NULLABLE on purpose: a NULL-scope row is an untenanted
+     -- run, and every read/decide path matches it with \`scope IS NOT DISTINCT FROM $n\` (the PG twin of TiDB
+     -- \`<=>\`) so NULL matches only NULL and one tenant's scope NEVER matches another's.
+     scope       VARCHAR(190),
+     tool_name   VARCHAR(190) NOT NULL,
+     args        JSONB,
+     status      VARCHAR(16)  NOT NULL,
+     reason      TEXT,
+     decided_by  VARCHAR(190),
+     created_at  TIMESTAMPTZ(3) NOT NULL,
+     decided_at  TIMESTAMPTZ(3),
+     PRIMARY KEY (id)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_owner_status ON approval (owner, status)`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_status ON approval (status)`,
+    `CREATE INDEX IF NOT EXISTS idx_approval_scope_status ON approval (scope, status)`,
+];
+export async function ensureSchema(pool) {
+    for (const stmt of PG_APPROVAL_SCHEMA)
+        await pool.query(stmt);
+}
+export class SqlApprovalStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    json(value, label) {
+        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
+    }
+    async createPending(id, scope, ctx) {
+        await this.db.query(this.q("INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES (?,?,?,?,?,?,?,'pending',?)", "INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +
+            "VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb,'pending',$8)"), [
+            id,
+            ctx.taskId ?? null,
+            ctx.sessionId ?? null,
+            ctx.owner ?? null,
+            scope,
+            ctx.toolName,
+            ctx.args == null ? null : this.json(ctx.args, "approval args"),
+            new Date(),
+        ]);
+    }
+    async getStatus(id, scope) {
+        const { rows } = await this.db.query(this.q("SELECT status, reason, decided_by FROM approval WHERE id = ? AND scope <=> ?", "SELECT status, reason, decided_by FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
+        const r = rows[0];
+        if (!r)
+            return undefined;
+        return { status: r.status, reason: r.reason ?? null, decidedBy: r.decided_by ?? null };
+    }
+    async decide(id, scope, decision, reason, decidedBy) {
+        const res = await this.db.query(this.q("UPDATE approval SET status = ?, reason = ?, decided_by = ?, decided_at = ? WHERE id = ? AND scope <=> ? AND status = 'pending'", "UPDATE approval SET status = $1, reason = $2, decided_by = $3, decided_at = $4 WHERE id = $5 AND scope IS NOT DISTINCT FROM $6 AND status = 'pending'"), [decision, reason, decidedBy, new Date(), id, scope]);
+        return res.affected === 1;
+    }
+    async listPending(scope, owner) {
+        const { rows } = owner
+            ? await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? AND owner = ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 AND owner = $2 ORDER BY created_at ASC"), [scope, owner])
+            : await this.db.query(this.q("SELECT * FROM approval WHERE status = 'pending' AND scope <=> ? ORDER BY created_at ASC", "SELECT * FROM approval WHERE status = 'pending' AND scope IS NOT DISTINCT FROM $1 ORDER BY created_at ASC"), [scope]);
+        return rows.map(mapRow);
+    }
+    async get(id, scope) {
+        const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ? AND scope <=> ?", "SELECT * FROM approval WHERE id = $1 AND scope IS NOT DISTINCT FROM $2"), [id, scope]);
+        return rows[0] ? mapRow(rows[0]) : undefined;
+    }
+    async getById(id) {
+        const { rows } = await this.db.query(this.q("SELECT * FROM approval WHERE id = ?", "SELECT * FROM approval WHERE id = $1"), [id]);
+        return rows[0] ? mapRow(rows[0]) : undefined;
+    }
+    async listPendingAll() {
+        const { rows } = await this.db.query("SELECT * FROM approval WHERE status = 'pending' ORDER BY created_at ASC");
+        return rows.map(mapRow);
+    }
+    async expireStale(olderThanMs) {
+        const cutoff = new Date(Date.now() - olderThanMs);
+        const res = await this.db.query(this.q("UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = ? " +
+            "WHERE status = 'pending' AND created_at < ?", "UPDATE approval SET status = 'expired', reason = 'timed out before decision', decided_at = $1 " +
+            "WHERE status = 'pending' AND created_at < $2"), [new Date(), cutoff]);
+        return res.affected;
+    }
+}
+export function mapRow(r) {
+    return {
+        id: String(r.id),
+        taskId: r.task_id ?? null,
+        sessionId: r.session_id ?? null,
+        owner: r.owner ?? null,
+        scope: r.scope ?? null,
+        toolName: String(r.tool_name),
+        args: parseJson(r.args),
+        status: r.status,
+        reason: r.reason ?? null,
+        decidedBy: r.decided_by ?? null,
+        createdAt: iso(r.created_at),
+        decidedAt: iso(r.decided_at),
+    };
+}
+export class TiDBApprovalStore extends SqlApprovalStore {
+    constructor(pool) {
+        super(mysqlDriver(pool));
+    }
+}
+export class PgApprovalStore extends SqlApprovalStore {
+    constructor(pool) {
+        super(pgDriver(pool));
+    }
+}
+//# sourceMappingURL=approval-store-sql.js.map

package/dist/plugins/breaker-state-sql.d.ts

@@ -0,0 +1,29 @@
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool, PoolClient } from "pg";
+import type { BreakerSnapshot, BreakerState } from "@sema-agent/core";
+import { type SqlDriver } from "./sql-driver.js";
+export declare const PG_BREAKER_STATE_SCHEMA: string[];
+export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+export declare class SqlBreakerState implements BreakerState {
+    protected readonly db: SqlDriver;
+    private readonly onWriteFail?;
+    private cache;
+    private timer?;
+    private readonly pending;
+    private writeFailStreak;
+    constructor(db: SqlDriver, onWriteFail?: ((streak: number) => void) | undefined);
+    private q;
+    get(key: string): BreakerSnapshot | undefined;
+    set(key: string, snap: BreakerSnapshot): void;
+    private writeThrough;
+    refresh(): Promise<void>;
+    startRefresh(intervalMs?: number): this;
+    stop(): void;
+}
+export declare class TiDBBreakerState extends SqlBreakerState {
+    constructor(pool: MySqlPool, onWriteFail?: (streak: number) => void);
+}
+export declare class PgBreakerState extends SqlBreakerState {
+    constructor(pool: PgPool, onWriteFail?: (streak: number) => void);
+}
+//# sourceMappingURL=breaker-state-sql.d.ts.map

package/dist/plugins/breaker-state-sql.js

@@ -0,0 +1,104 @@
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+export const PG_BREAKER_STATE_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS circuit_breaker (
+     breaker_key VARCHAR(190)   NOT NULL,
+     phase       VARCHAR(16)    NOT NULL,
+     failures    INTEGER        NOT NULL DEFAULT 0,
+     opened_at   TIMESTAMPTZ(3),
+     updated_at  TIMESTAMPTZ(3) NOT NULL,
+     PRIMARY KEY (breaker_key)
+   )`,
+];
+export async function ensureSchema(pool) {
+    for (const stmt of PG_BREAKER_STATE_SCHEMA)
+        await pool.query(stmt);
+}
+export class SqlBreakerState {
+    db;
+    onWriteFail;
+    cache = new Map();
+    timer;
+    pending = new Set();
+    writeFailStreak = 0;
+    constructor(db, onWriteFail) {
+        this.db = db;
+        this.onWriteFail = onWriteFail;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, snap) {
+        this.cache.set(key, snap);
+        this.pending.add(key);
+        void this.writeThrough(key, snap);
+    }
+    async writeThrough(key, snap) {
+        try {
+            await this.db.query(this.q("INSERT INTO circuit_breaker (breaker_key, phase, failures, opened_at, updated_at) VALUES (?,?,?,?,?) " +
+                "ON DUPLICATE KEY UPDATE phase=VALUES(phase), failures=VALUES(failures), opened_at=VALUES(opened_at), updated_at=VALUES(updated_at)", "INSERT INTO circuit_breaker (breaker_key, phase, failures, opened_at, updated_at) VALUES ($1,$2,$3,$4,$5) " +
+                "ON CONFLICT (breaker_key) DO UPDATE SET phase=EXCLUDED.phase, failures=EXCLUDED.failures, opened_at=EXCLUDED.opened_at, updated_at=EXCLUDED.updated_at"), [key, snap.phase, snap.failures, snap.openedAt != null ? new Date(snap.openedAt) : null, new Date()]);
+            this.pending.delete(key);
+            if (this.writeFailStreak > 0) {
+                this.writeFailStreak = 0;
+                try {
+                    this.onWriteFail?.(0);
+                }
+                catch { }
+            }
+        }
+        catch {
+            try {
+                this.onWriteFail?.(++this.writeFailStreak);
+            }
+            catch { }
+        }
+    }
+    async refresh() {
+        try {
+            const pendingAtStart = new Set(this.pending);
+            const guarded = (key) => this.pending.has(key) || pendingAtStart.has(key);
+            const { rows } = await this.db.query("SELECT breaker_key, phase, failures, opened_at FROM circuit_breaker");
+            const seen = new Set();
+            for (const r of rows) {
+                const key = String(r.breaker_key);
+                seen.add(key);
+                if (guarded(key))
+                    continue;
+                this.cache.set(key, {
+                    phase: r.phase,
+                    failures: Number(r.failures),
+                    openedAt: r.opened_at != null ? new Date(r.opened_at).getTime() : undefined,
+                });
+            }
+            for (const key of this.cache.keys())
+                if (!seen.has(key) && !guarded(key))
+                    this.cache.delete(key);
+        }
+        catch {
+        }
+    }
+    startRefresh(intervalMs = 5_000) {
+        this.timer ??= setInterval(() => void this.refresh(), intervalMs);
+        this.timer.unref?.();
+        return this;
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+}
+export class TiDBBreakerState extends SqlBreakerState {
+    constructor(pool, onWriteFail) {
+        super(mysqlDriver(pool), onWriteFail);
+    }
+}
+export class PgBreakerState extends SqlBreakerState {
+    constructor(pool, onWriteFail) {
+        super(pgDriver(pool), onWriteFail);
+    }
+}
+//# sourceMappingURL=breaker-state-sql.js.map

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

@@ -0,0 +1,67 @@
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type Checkpoint, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ResumeOutcome, type ResolveExpectation, type ReopenReason, type RiskDescriptor } from "@sema-agent/core";
+import { type SqlDriver } from "./sql-driver.js";
+export declare const TERMINAL_BACKSTOP_MS: number;
+export declare const TERMINAL_GRACE_MS = 3600000;
+export declare function tokenFingerprint(token: string): string;
+export interface PendingCheckpoint {
+    sessionId: string;
+    scope: string;
+    toolName: string | null;
+    toolCallId: string | null;
+    boundCallId: string | null;
+    boundInputHash: string | null;
+    taskId: string | null;
+    input: unknown;
+    createdAt: number;
+    deadline: number | null;
+    riskDescriptor: RiskDescriptor | null;
+}
+export declare function boundedToolInput(args: unknown): unknown;
+export declare class SqlCheckpointStore implements CheckpointStore {
+    protected readonly db: SqlDriver;
+    protected readonly logger?: {
+        info?(msg: string, meta?: unknown): void;
+    } | undefined;
+    constructor(db: SqlDriver, logger?: {
+        info?(msg: string, meta?: unknown): void;
+    } | undefined);
+    private q;
+    private json;
+    private isDupKey;
+    put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
+    get(token: CheckpointToken): Promise<Checkpoint | null>;
+    resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
+    reopen(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
+    setPendingSteer(token: CheckpointToken, scope: string, steer: {
+        text: string;
+        trusted: boolean;
+    }): Promise<boolean>;
+    expire(token: CheckpointToken, scope: string): Promise<boolean>;
+    reap(scope: string, cutoff: number): Promise<number>;
+    reapExpired(cutoff: number): Promise<number>;
+    listExpiredApprovalGates(cutoff: number, limit?: number): Promise<Array<{
+        sessionId: string;
+        scope: string;
+    }>>;
+    listPending(scope?: string): Promise<PendingCheckpoint[]>;
+    listByScope(scope: string): Promise<CheckpointSummary[]>;
+    findPendingTokenBySession(sessionId: string, scope?: string): Promise<CheckpointToken | null>;
+    peekPendingScope(sessionId: string): Promise<string | null | undefined>;
+    putCtx(sessionId: string, ctx: unknown): Promise<void>;
+    getCtx<T = unknown>(sessionId: string): Promise<T | null>;
+    reapCtx(cutoff: number): Promise<number>;
+    deleteBySession(sessionId: string, owner: string | null): Promise<number>;
+}
+export declare class TiDBCheckpointStore extends SqlCheckpointStore {
+    constructor(pool: MySqlPool, logger?: {
+        info?(msg: string, meta?: unknown): void;
+    });
+}
+export declare class PgCheckpointStore extends SqlCheckpointStore {
+    constructor(pool: PgPool, logger?: {
+        info?(msg: string, meta?: unknown): void;
+    });
+}
+//# sourceMappingURL=checkpoint-store-sql.d.ts.map

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

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import { CheckpointError, validatePendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, } from "@sema-agent/core";
+import { redactDeep } from "../trace/redact.js";
+import { pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+const MAX_TOOL_INPUT_CHARS = 8192;
+export const TERMINAL_BACKSTOP_MS = Math.max(60_000, Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) || 30 * 86_400_000);
+export const TERMINAL_GRACE_MS = 3_600_000;
+export function tokenFingerprint(token) {
+    return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+export function boundedToolInput(args) {
+    if (args === undefined)
+        return null;
+    const redacted = redactDeep(args);
+    const json = JSON.stringify(redacted);
+    if (json === undefined)
+        return null;
+    if (json.length > MAX_TOOL_INPUT_CHARS)
+        return { truncated: true, bytes: json.length };
+    return redacted;
+}
+const DUP_ENTRY = 1062;
+const PG_UNIQUE_VIOLATION = "23505";
+export class SqlCheckpointStore {
+    db;
+    logger;
+    constructor(db, logger) {
+        this.db = db;
+        this.logger = logger;
+    }
+    q(tidb, pg) {
+        return this.db.dialect === "tidb" ? tidb : pg;
+    }
+    json(value, label) {
+        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
+    }
+    isDupKey(e) {
+        return this.db.dialect === "tidb"
+            ? e?.errno === DUP_ENTRY
+            : e?.code === PG_UNIQUE_VIOLATION;
+    }
+    async put(token, cp) {
+        const pa = cp.pendingAction;
+        const version = checkpointVersionOf(cp);
+        const toolInput = boundedToolInput(pa?.args);
+        try {
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at, terminal_at, gate_kind, bound_input_hash, risk_descriptor) " +
+                "VALUES (?,?,?,?,'pending',?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at, terminal_at, gate_kind, bound_input_hash, risk_descriptor) " +
+                "VALUES ($1,$2,$3,$4,'pending',$5,$6,$7::jsonb,$8::jsonb,$9,$10,$11,$12,$13,$14)"), [
+                token,
+                cp.scope,
+                cp.sessionId,
+                version,
+                pa?.toolName ?? null,
+                pa?.toolCallId ?? null,
+                toolInput === null ? null : this.json(toolInput, "approval tool_input"),
+                this.json(cp, "checkpoint"),
+                cp.deadline ?? null,
+                cp.createdAt,
+                Math.max(cp.createdAt + TERMINAL_BACKSTOP_MS, (cp.deadline ?? 0) + TERMINAL_GRACE_MS),
+                cp.gate?.kind ?? null,
+                pa?.boundInputHash ?? null,
+                ((g) => (g?.riskDescriptor ? this.json(g.riskDescriptor, "risk descriptor") : null))(cp.gate),
+            ]);
+        }
+        catch (e) {
+            if (this.isDupKey(e)) {
+                throw new CheckpointError("checkpoint.already_exists", `checkpoint token already exists`);
+            }
+            throw e;
+        }
+    }
+    async get(token) {
+        const { rows } = await this.db.query(this.q("SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer FROM checkpoint WHERE token = ?", "SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer FROM checkpoint WHERE token = $1"), [token]);
+        const r = rows[0];
+        if (!r)
+            return null;
+        const version = Number(r.version);
+        if (version > MAX_SUPPORTED_CHECKPOINT_VERSION) {
+            throw new Error(`checkpoint format version ${version} is newer than this build supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION}) — upgrade the service to resume it`);
+        }
+        const cp = parseJson(r.checkpoint);
+        cp.status = r.status;
+        const outcomeRaw = parseJson(r.outcome);
+        if (outcomeRaw)
+            cp.resolvedOutcome = winnerFromOutcome(outcomeRaw);
+        cp.reopenReason = r.reopen_reason ?? undefined;
+        cp.rev = r.rev == null ? 0 : Number(r.rev);
+        const steerRaw = parseJson(r.pending_steer);
+        if (steerRaw && cp.state)
+            cp.state.pendingSteer = steerRaw;
+        this.logger?.info?.("checkpoint_get", {
+            tokenFp: tokenFingerprint(token),
+            status: cp.status,
+            version,
+            hasWorkspaceHandle: !!cp.state?.workspaceHandle,
+            snapshotId: cp.state?.workspaceHandle?.snapshotId,
+        });
+        return cp;
+    }
+    async resolve(token, scope, outcome, expect) {
+        const params = [this.json(outcome, "checkpoint outcome"), Date.now(), token, scope];
+        if (expect)
+            params.push(expect.rev);
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'resolved', outcome = ?, decided_at = ?, rev = rev + 1, reopen_reason = NULL WHERE token = ? AND scope = ? AND status = 'pending'" +
+            (expect ? " AND rev = ?" : ""), "UPDATE checkpoint SET status = 'resolved', outcome = $1::jsonb, decided_at = $2, rev = rev + 1, reopen_reason = NULL WHERE token = $3 AND scope = $4 AND status = 'pending'" +
+            (expect ? " AND rev = $5" : "")), params);
+        return res.affected === 1;
+    }
+    async reopen(token, scope, reason) {
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'pending', reopen_reason = ?, rev = rev + 1 WHERE token = ? AND scope = ? AND status = 'resolved'", "UPDATE checkpoint SET status = 'pending', reopen_reason = $1, rev = rev + 1 WHERE token = $2 AND scope = $3 AND status = 'resolved'"), [reason, token, scope]);
+        return res.affected === 1;
+    }
+    async setPendingSteer(token, scope, steer) {
+        const clean = validatePendingSteer(steer);
+        const res = await this.db.query(this.q("UPDATE checkpoint SET pending_steer = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET pending_steer = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [this.json(clean, "pending steer"), token, scope]);
+        return res.affected > 0;
+    }
+    async expire(token, scope) {
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE token = ? AND scope = ? AND status = 'pending'", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'"), [Date.now(), token, scope]);
+        return res.affected === 1;
+    }
+    async reap(scope, cutoff) {
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? WHERE scope = ? AND status = 'pending' AND deadline IS NOT NULL AND deadline <= ?", "UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE scope = $2 AND status = 'pending' AND deadline IS NOT NULL AND deadline <= $3"), [Date.now(), scope, cutoff]);
+        return res.affected;
+    }
+    async reapExpired(cutoff) {
+        const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at = ? " +
+            "WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND (gate_kind IS NULL OR gate_kind NOT IN ('human','irreversible_ask') OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= ?))", "UPDATE checkpoint SET status = 'expired', decided_at = $1 " +
+            "WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND (gate_kind IS NULL OR gate_kind NOT IN ('human','irreversible_ask') OR COALESCE(tool_name,'') = 'AskUserQuestion')) OR (terminal_at IS NOT NULL AND terminal_at <= $3))"), [Date.now(), cutoff, cutoff]);
+        return res.affected;
+    }
+    async listExpiredApprovalGates(cutoff, limit = 100) {
+        const { rows } = await this.db.query(this.q("SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ('human','irreversible_ask') " +
+            "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= ? ORDER BY deadline ASC LIMIT ?", "SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND gate_kind IN ('human','irreversible_ask') " +
+            "AND COALESCE(tool_name,'') <> 'AskUserQuestion' AND deadline IS NOT NULL AND deadline <= $1 ORDER BY deadline ASC LIMIT $2"), [cutoff, limit]);
+        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
+    }
+    async listPending(scope) {
+        const base = "SELECT c.session_id, c.scope, c.tool_name, c.tool_call_id, c.tool_input, c.bound_input_hash, c.risk_descriptor, c.created_at, c.deadline, ta.task_id " +
+            "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
+        const { rows } = scope
+            ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at ASC`, [scope])
+            : await this.db.query(`${base} ORDER BY c.created_at ASC`);
+        const out = rows.map((r) => {
+            const toolCallId = r.tool_call_id ?? null;
+            return {
+                sessionId: String(r.session_id),
+                scope: String(r.scope),
+                toolName: r.tool_name ?? null,
+                toolCallId,
+                boundCallId: toolCallId,
+                boundInputHash: r.bound_input_hash ?? null,
+                taskId: r.task_id ?? null,
+                input: r.tool_input ?? null,
+                createdAt: Number(r.created_at),
+                deadline: r.deadline == null ? null : Number(r.deadline),
+                riskDescriptor: parseJson(r.risk_descriptor),
+            };
+        });
+        return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
+    }
+    async listByScope(scope) {
+        const { rows } = await this.db.query(this.q("SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at ASC LIMIT 500", "SELECT checkpoint, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at ASC LIMIT 500"), [scope]);
+        const out = [];
+        for (const r of rows) {
+            const cp = parseJson(r.checkpoint);
+            if (!cp)
+                continue;
+            cp.status = r.status;
+            out.push(summarizeCheckpoint(cp));
+        }
+        return out;
+    }
+    async findPendingTokenBySession(sessionId, scope) {
+        const { rows } = scope
+            ? await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND scope=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND scope=$2 AND status='pending' LIMIT 1"), [sessionId, scope])
+            : await this.db.query(this.q("SELECT token FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT token FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
+        return rows[0] ? String(rows[0].token) : null;
+    }
+    async peekPendingScope(sessionId) {
+        const { rows } = await this.db.query(this.q("SELECT scope FROM checkpoint WHERE session_id=? AND status='pending' LIMIT 1", "SELECT scope FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1"), [sessionId]);
+        if (!rows[0])
+            return undefined;
+        return rows[0].scope ?? null;
+    }
+    async putCtx(sessionId, ctx) {
+        await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at) VALUES (?,?,?) " +
+            "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at = VALUES(updated_at)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at) VALUES ($1,$2::jsonb,$3) " +
+            "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at = EXCLUDED.updated_at"), [sessionId, this.json(ctx, "checkpoint ctx"), Date.now()]);
+    }
+    async getCtx(sessionId) {
+        const { rows } = await this.db.query(this.q("SELECT ctx FROM checkpoint_ctx WHERE session_id=?", "SELECT ctx FROM checkpoint_ctx WHERE session_id=$1"), [sessionId]);
+        return rows[0] ? parseJson(rows[0].ctx) : null;
+    }
+    async reapCtx(cutoff) {
+        const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at < ? " +
+            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT session_id FROM task_active)", "DELETE FROM checkpoint_ctx WHERE updated_at < $1 " +
+            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT session_id FROM task_active)"), [cutoff]);
+        return res.affected;
+    }
+    async deleteBySession(sessionId, owner) {
+        const ownerGuard = this.q("EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = ? AND sm.owner <=> ?)", "EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = $1 AND sm.owner IS NOT DISTINCT FROM $2)");
+        const params = this.db.dialect === "tidb" ? [sessionId, sessionId, owner] : [sessionId, owner];
+        const res = await this.db.query(this.q(`DELETE FROM checkpoint WHERE session_id = ? AND ${ownerGuard}`, `DELETE FROM checkpoint WHERE session_id = $1 AND ${ownerGuard}`), params);
+        await this.db.query(this.q(`DELETE FROM checkpoint_ctx WHERE session_id = ? AND ${ownerGuard}`, `DELETE FROM checkpoint_ctx WHERE session_id = $1 AND ${ownerGuard}`), params);
+        return res.affected;
+    }
+}
+export class TiDBCheckpointStore extends SqlCheckpointStore {
+    constructor(pool, logger) {
+        super(mysqlDriver(pool), logger);
+    }
+}
+export class PgCheckpointStore extends SqlCheckpointStore {
+    constructor(pool, logger) {
+        super(pgDriver(pool), logger);
+    }
+}
+//# sourceMappingURL=checkpoint-store-sql.js.map

package/dist/plugins/file-snapshot-store-sql.d.ts

@@ -0,0 +1,38 @@
+import { type FileSnapshotBounds, type FileSnapshotStore, type FileSnapshotResult, type ExecutionEnv } from "@sema-agent/core";
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type BlobBackend } from "./blob-backend.js";
+import { type SqlDriver } from "./sql-driver.js";
+export declare class SqlFileSnapshotStore implements FileSnapshotStore {
+    protected readonly db: SqlDriver;
+    protected readonly pool: MySqlPool | PgPool;
+    protected readonly bounds: FileSnapshotBounds;
+    private readonly inFlight;
+    private readonly blobs;
+    onSkippedVanished: ((count: number) => void | Promise<void>) | undefined;
+    constructor(db: SqlDriver, pool: MySqlPool | PgPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+    private q;
+    private putBlobRow;
+    putBlob(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
+    snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
+    restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    has(scope: string, key: string): Promise<boolean>;
+    listKeys(scope: string): Promise<string[]>;
+    exportManifest(scope: string, key: string): Promise<Map<string, string> | null>;
+    getBlob(hash: string): Promise<Uint8Array | undefined>;
+    hasBlobs(hashes: string[]): Promise<Set<string>>;
+    blobSizes(hashes: string[]): Promise<Map<string, number>>;
+    reap(scope: string, keepKeys: string[]): Promise<number>;
+    deleteBySession(scope: string): Promise<number>;
+    private gcOrphanBlobs;
+    sweepOrphanBlobs(): Promise<number>;
+    private tx;
+}
+export declare class TiDBFileSnapshotStore extends SqlFileSnapshotStore {
+    constructor(pool: MySqlPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+}
+export declare class PgFileSnapshotStore extends SqlFileSnapshotStore {
+    constructor(pool: PgPool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+}
+//# sourceMappingURL=file-snapshot-store-sql.d.ts.map