@sema-agent/server 1.185.0

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

@@ -0,0 +1,193 @@
+import { CheckpointError, validatePendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION } from "@sema-agent/core";
+import { redactDeep } from "../trace/redact.js";
+import { tokenFingerprint } from "./tidb-checkpoint-store.js";
+const MAX_TOOL_INPUT_CHARS = 8192;
+const TERMINAL_BACKSTOP_MS = Math.max(60_000, Number(process.env.APPROVAL_TERMINAL_BACKSTOP_MS) || 30 * 86_400_000);
+const TERMINAL_GRACE_MS = 3_600_000;
+const PG_UNIQUE_VIOLATION = "23505";
+function parseJson(v) {
+    if (v == null)
+        return null;
+    return (typeof v === "string" ? JSON.parse(v) : v);
+}
+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;
+}
+export class PgCheckpointStore {
+    pool;
+    logger;
+    constructor(pool, logger) {
+        this.pool = pool;
+        this.logger = logger;
+    }
+    async put(token, cp) {
+        const pa = cp.pendingAction;
+        const version = checkpointVersionOf(cp);
+        const toolInput = boundedToolInput(pa?.args);
+        try {
+            await this.pool.query("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 : JSON.stringify(toolInput),
+                JSON.stringify(cp),
+                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 ? JSON.stringify(g.riskDescriptor) : null))(cp.gate),
+            ]);
+        }
+        catch (e) {
+            if (e?.code === PG_UNIQUE_VIOLATION) {
+                throw new CheckpointError("checkpoint.already_exists", `checkpoint token already exists`);
+            }
+            throw e;
+        }
+    }
+    async get(token) {
+        const res = await this.pool.query("SELECT version, status, checkpoint, outcome, reopen_reason, rev, pending_steer FROM checkpoint WHERE token = $1", [token]);
+        const r = res.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 = [JSON.stringify(outcome), Date.now(), token, scope];
+        if (expect)
+            params.push(expect.rev);
+        const res = await this.pool.query("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.rowCount ?? 0) === 1;
+    }
+    async reopen(token, scope, reason) {
+        const res = await this.pool.query("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.rowCount ?? 0) === 1;
+    }
+    async setPendingSteer(token, scope, steer) {
+        const clean = validatePendingSteer(steer);
+        const res = await this.pool.query("UPDATE checkpoint SET pending_steer = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'", [JSON.stringify(clean), token, scope]);
+        return (res.rowCount ?? 0) > 0;
+    }
+    async expire(token, scope) {
+        const res = await this.pool.query("UPDATE checkpoint SET status = 'expired', decided_at = $1 WHERE token = $2 AND scope = $3 AND status = 'pending'", [Date.now(), token, scope]);
+        return (res.rowCount ?? 0) === 1;
+    }
+    async reap(scope, cutoff) {
+        const res = await this.pool.query("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.rowCount ?? 0;
+    }
+    async reapExpired(cutoff) {
+        const res = await this.pool.query("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.rowCount ?? 0;
+    }
+    async listExpiredApprovalGates(cutoff, limit = 100) {
+        const res = await this.pool.query("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 res.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 res = scope
+            ? await this.pool.query(`${base} AND c.scope=$1 ORDER BY c.created_at ASC`, [scope])
+            : await this.pool.query(`${base} ORDER BY c.created_at ASC`);
+        const out = res.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 res = await this.pool.query("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 res.rows) {
+            const cp = parseJson(r.checkpoint);
+            if (!cp)
+                continue;
+            cp.status = r.status;
+            out.push(summarizeCheckpoint(cp));
+        }
+        return out;
+    }
+    async findPendingTokenBySession(sessionId, scope) {
+        const res = scope
+            ? await this.pool.query("SELECT token FROM checkpoint WHERE session_id=$1 AND scope=$2 AND status='pending' LIMIT 1", [sessionId, scope])
+            : await this.pool.query("SELECT token FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1", [sessionId]);
+        return res.rows[0] ? String(res.rows[0].token) : null;
+    }
+    async peekPendingScope(sessionId) {
+        const res = await this.pool.query("SELECT scope FROM checkpoint WHERE session_id=$1 AND status='pending' LIMIT 1", [sessionId]);
+        if (!res.rows[0])
+            return undefined;
+        return res.rows[0].scope ?? null;
+    }
+    async putCtx(sessionId, ctx) {
+        await this.pool.query("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, JSON.stringify(ctx), Date.now()]);
+    }
+    async getCtx(sessionId) {
+        const res = await this.pool.query("SELECT ctx FROM checkpoint_ctx WHERE session_id=$1", [sessionId]);
+        return res.rows[0] ? parseJson(res.rows[0].ctx) : null;
+    }
+    async reapCtx(cutoff) {
+        const res = await this.pool.query("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.rowCount ?? 0;
+    }
+    async deleteBySession(sessionId, owner) {
+        const ownerGuard = "EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = $1 AND sm.owner IS NOT DISTINCT FROM $2)";
+        const res = await this.pool.query(`DELETE FROM checkpoint WHERE session_id = $1 AND ${ownerGuard}`, [sessionId, owner]);
+        await this.pool.query(`DELETE FROM checkpoint_ctx WHERE session_id = $1 AND ${ownerGuard}`, [sessionId, owner]);
+        return res.rowCount ?? 0;
+    }
+}
+//# sourceMappingURL=pg-checkpoint-store.js.map

package/dist/plugins/pg-checkpoint-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-checkpoint-store.js","sourceRoot":"","sources":["../../src/plugins/pg-checkpoint-store.ts"],"names":[],"mappings":"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"}

package/dist/plugins/pg-cost-quota.d.ts

@@ -0,0 +1,18 @@
+import type { Pool, PoolClient } from "pg";
+import type { QuotaDecision, QuotaTracker } from "../observability/cost-quota.js";
+import { type CounterDegradeHook } from "./write-behind-counter.js";
+export declare class PgCostQuota implements QuotaTracker {
+    private readonly limitMicroUsd;
+    private readonly counter;
+    constructor(pool: Pool, limitMicroUsd: number, windowMs: number, now?: () => number, onDegraded?: CounterDegradeHook, queryTimeoutMs?: number);
+    check(scopeKey: string): QuotaDecision;
+    add(scopeKey: string, micro: number): void;
+    flush(): Promise<void>;
+    refresh(): Promise<void>;
+    reap(): Promise<number>;
+    startRefresh(intervalMs?: number): this;
+    stop(): void;
+}
+export declare const PG_COST_QUOTA_SCHEMA: string[];
+export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
+//# sourceMappingURL=pg-cost-quota.d.ts.map

package/dist/plugins/pg-cost-quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-cost-quota.d.ts","sourceRoot":"","sources":["../../src/plugins/pg-cost-quota.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAe,MAAM,IAAI,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAoC,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAyKtG,qBAAa,WAAY,YAAW,YAAY;IAGtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAFtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;gBAEnC,IAAI,EAAE,IAAI,EAAmB,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,MAAM,EAAE,UAAU,CAAC,EAAE,kBAAkB,EAAE,cAAc,CAAC,EAAE,MAAM;IAI9J,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAKtC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAGtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAGxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAGvB,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAIvC,IAAI,IAAI,IAAI;CAGb;AAKD,eAAO,MAAM,oBAAoB,EAAE,MAAM,EASxC,CAAC;AAGF,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/dist/plugins/pg-cost-quota.js

@@ -0,0 +1,189 @@
+import { DEFAULT_COUNTER_QUERY_TIMEOUT_MS } from "./write-behind-counter.js";
+const SEP = "\u0000";
+class PgWriteBehindCounter {
+    pool;
+    windowMs;
+    now;
+    onDegraded;
+    queryTimeoutMs;
+    pendingDelta = new Map();
+    fleetTotal = new Map();
+    timer;
+    flushing = false;
+    flushStartedAt = 0;
+    failStreak = new Map();
+    constructor(pool, windowMs, now = () => Date.now(), onDegraded, queryTimeoutMs = DEFAULT_COUNTER_QUERY_TIMEOUT_MS) {
+        this.pool = pool;
+        this.windowMs = windowMs;
+        this.now = now;
+        this.onDegraded = onDegraded;
+        this.queryTimeoutMs = queryTimeoutMs;
+    }
+    bump(kind, failed, error) {
+        if (!this.onDegraded)
+            return;
+        const prev = this.failStreak.get(kind) ?? 0;
+        if (!failed && prev === 0)
+            return;
+        const next = failed ? prev + 1 : 0;
+        this.failStreak.set(kind, next);
+        try {
+            this.onDegraded({ table: "cost_quota", kind, streak: next, prevStreak: prev, ...(failed && error !== undefined ? { error: error instanceof Error ? error.message : String(error) } : {}) });
+        }
+        catch {
+        }
+    }
+    bucket() {
+        return Math.floor(this.now() / this.windowMs);
+    }
+    rk(key) {
+        return `${key}${SEP}${this.bucket()}`;
+    }
+    used(key) {
+        const rk = this.rk(key);
+        return (this.fleetTotal.get(rk) ?? 0) + (this.pendingDelta.get(rk) ?? 0);
+    }
+    addLocal(key, n) {
+        if (n <= 0)
+            return;
+        const rk = this.rk(key);
+        this.pendingDelta.set(rk, (this.pendingDelta.get(rk) ?? 0) + n);
+    }
+    retryAfterSec() {
+        return Math.ceil(((this.bucket() + 1) * this.windowMs - this.now()) / 1000);
+    }
+    async flush() {
+        if (this.flushing) {
+            if (this.now() - this.flushStartedAt > 60_000)
+                this.bump("stalled", true, "flush round stalled >60s (hung query?)");
+            return;
+        }
+        this.flushing = true;
+        this.flushStartedAt = this.now();
+        try {
+            await this.flushOnce();
+        }
+        finally {
+            this.flushing = false;
+            this.bump("stalled", false);
+        }
+    }
+    async flushOnce() {
+        let attempted = false;
+        let failure;
+        let hadFailure = false;
+        for (const [rk, delta] of [...this.pendingDelta]) {
+            if (delta <= 0)
+                continue;
+            const sep = rk.lastIndexOf(SEP);
+            const key = rk.slice(0, sep);
+            const windowBucket = Number(rk.slice(sep + 1));
+            attempted = true;
+            try {
+                const q = {
+                    text: "INSERT INTO cost_quota (scope_key, window_bucket, micro, updated_at) VALUES ($1,$2,$3,$4) " +
+                        "ON CONFLICT (scope_key, window_bucket) DO UPDATE SET micro = cost_quota.micro + EXCLUDED.micro, updated_at = EXCLUDED.updated_at",
+                    values: [key, windowBucket, delta, new Date()],
+                    query_timeout: this.queryTimeoutMs,
+                };
+                await this.pool.query(q);
+                const remaining = (this.pendingDelta.get(rk) ?? 0) - delta;
+                if (remaining > 0)
+                    this.pendingDelta.set(rk, remaining);
+                else
+                    this.pendingDelta.delete(rk);
+            }
+            catch (err) {
+                hadFailure = true;
+                failure = err;
+            }
+        }
+        if (attempted)
+            this.bump("flush", hadFailure, failure);
+        await this.refresh();
+        await this.reap();
+    }
+    async refresh() {
+        const b = this.bucket();
+        try {
+            const q = { text: "SELECT scope_key, micro FROM cost_quota WHERE window_bucket = $1", values: [b], query_timeout: this.queryTimeoutMs };
+            const res = await this.pool.query(q);
+            const next = new Map();
+            for (const r of res.rows) {
+                next.set(`${String(r.scope_key)}${SEP}${b}`, Number(r.micro));
+            }
+            this.fleetTotal = next;
+            this.bump("refresh", false);
+        }
+        catch (err) {
+            this.bump("refresh", true, err);
+        }
+    }
+    async reap() {
+        try {
+            const q = { text: "DELETE FROM cost_quota WHERE window_bucket < $1", values: [this.bucket()], query_timeout: this.queryTimeoutMs };
+            const res = await this.pool.query(q);
+            return res.rowCount ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    startRefresh(intervalMs = 5_000) {
+        this.timer ??= setInterval(() => void this.flush(), intervalMs);
+        this.timer.unref?.();
+        return this;
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+}
+export class PgCostQuota {
+    limitMicroUsd;
+    counter;
+    constructor(pool, limitMicroUsd, windowMs, now, onDegraded, queryTimeoutMs) {
+        this.limitMicroUsd = limitMicroUsd;
+        this.counter = new PgWriteBehindCounter(pool, windowMs, now, onDegraded, queryTimeoutMs);
+    }
+    check(scopeKey) {
+        const used = this.counter.used(scopeKey);
+        const allowed = used < this.limitMicroUsd;
+        return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec: allowed ? 0 : this.counter.retryAfterSec() };
+    }
+    add(scopeKey, micro) {
+        this.counter.addLocal(scopeKey, micro);
+    }
+    flush() {
+        return this.counter.flush();
+    }
+    refresh() {
+        return this.counter.refresh();
+    }
+    reap() {
+        return this.counter.reap();
+    }
+    startRefresh(intervalMs) {
+        this.counter.startRefresh(intervalMs);
+        return this;
+    }
+    stop() {
+        this.counter.stop();
+    }
+}
+export const PG_COST_QUOTA_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS cost_quota (
+     scope_key     VARCHAR(190) NOT NULL,
+     window_bucket BIGINT       NOT NULL,
+     micro         BIGINT       NOT NULL DEFAULT 0,
+     updated_at    TIMESTAMPTZ(3) NOT NULL,
+     PRIMARY KEY (scope_key, window_bucket)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_cost_quota_window ON cost_quota (window_bucket)`,
+];
+export async function ensureSchema(pool) {
+    for (const stmt of PG_COST_QUOTA_SCHEMA)
+        await pool.query(stmt);
+}
+//# sourceMappingURL=pg-cost-quota.js.map

package/dist/plugins/pg-cost-quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-cost-quota.js","sourceRoot":"","sources":["../../src/plugins/pg-cost-quota.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,26 @@
+import { type FileSnapshotBounds, type FileSnapshotStore, type FileSnapshotResult, type ExecutionEnv } from "@sema-agent/core";
+import type { Pool } from "pg";
+import { type BlobBackend } from "./blob-backend.js";
+export declare class PgFileSnapshotStore implements FileSnapshotStore {
+    private readonly pool;
+    private readonly bounds;
+    private readonly inFlight;
+    private readonly blobs;
+    constructor(pool: Pool, blobBackend?: BlobBackend, bounds?: FileSnapshotBounds);
+    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>>;
+    reap(scope: string, keepKeys: string[]): Promise<number>;
+    deleteBySession(scope: string): Promise<number>;
+    private gcOrphanBlobs;
+    sweepOrphanBlobs(): Promise<number>;
+    private tx;
+}
+//# sourceMappingURL=pg-file-snapshot-store.d.ts.map

package/dist/plugins/pg-file-snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-file-snapshot-store.d.ts","sourceRoot":"","sources":["../../src/plugins/pg-file-snapshot-store.ts"],"names":[],"mappings":"AAOA,OAAO,EAA2D,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExL,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,qBAAa,mBAAoB,YAAW,iBAAiB;IAM/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAmC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAL3F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAI9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBACP,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,WAAW,EAAmB,MAAM,GAAE,kBAA4C;YAO3H,UAAU;IAWlB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiBrE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6CxH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmCrK,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAcvH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMjD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO1C,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAQ/E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAMtD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAOhD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAYxD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YASvC,aAAa;IAWrB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;YAI3B,EAAE;CAkBjB"}

package/dist/plugins/pg-file-snapshot-store.js

@@ -0,0 +1,181 @@
+import { captureManifest, applyManifest, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
+import { createHash } from "node:crypto";
+import { SqlBlobBackend } from "./blob-backend.js";
+export class PgFileSnapshotStore {
+    pool;
+    bounds;
+    inFlight = new Set();
+    blobs;
+    constructor(pool, blobBackend, bounds = DEFAULT_SNAPSHOT_BOUNDS) {
+        this.pool = pool;
+        this.bounds = bounds;
+        this.blobs = blobBackend ?? new SqlBlobBackend("pg", pool);
+    }
+    async putBlobRow(hash, bytes) {
+        await this.blobs.putBlob(hash, bytes);
+    }
+    async putBlob(hash, bytes) {
+        if (createHash("sha256").update(bytes).digest("hex") !== hash) {
+            return { ok: false, error: { code: "read_failed", message: `putBlob ${hash} fails content-address integrity — nothing stored` } };
+        }
+        try {
+            await this.putBlobRow(hash, bytes);
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "restore_failed", message: `putBlob ${hash} write/upload failed: ${err.message}` } };
+        }
+    }
+    async snapshot(scope, key, env, root, signal) {
+        const flightKey = `${scope} ${key}`;
+        if (this.inFlight.has(flightKey))
+            return { ok: true };
+        this.inFlight.add(flightKey);
+        try {
+            if (await this.has(scope, key))
+                return { ok: true };
+            let cap;
+            try {
+                cap = await captureManifest(env, root, this.bounds, signal, async (hash, bytes) => {
+                    await this.putBlobRow(hash, bytes);
+                });
+            }
+            catch (err) {
+                return { ok: false, error: { code: "restore_failed", message: `snapshot blob write failed: ${err.message}` } };
+            }
+            if (!cap.ok)
+                return { ok: false, error: cap.error };
+            await this.tx(async (c) => {
+                const exists = await c.query("SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1", [scope, key]);
+                if (exists.rows[0])
+                    return;
+                for (const [relPath, hash] of cap.value) {
+                    await c.query("INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES ($1,$2,$3,$4)", [scope, key, relPath, hash]);
+                }
+            });
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "restore_failed", message: `snapshot persist failed: ${err.message}` } };
+        }
+        finally {
+            this.inFlight.delete(flightKey);
+        }
+    }
+    async importManifest(scope, key, manifest, srcGetBlob) {
+        const flightKey = `${scope} ${key}`;
+        if (this.inFlight.has(flightKey))
+            return { ok: true };
+        this.inFlight.add(flightKey);
+        try {
+            if (await this.has(scope, key))
+                return { ok: true };
+            for (const hash of new Set(manifest.values())) {
+                let bytes;
+                try {
+                    bytes = await srcGetBlob(hash);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fetch failed: ${err.message}` } };
+                }
+                if (!bytes)
+                    return { ok: false, error: { code: "read_failed", message: `missing source blob ${hash}` } };
+                if (createHash("sha256").update(bytes).digest("hex") !== hash) {
+                    return { ok: false, error: { code: "read_failed", message: `source blob ${hash} fails content-address integrity` } };
+                }
+                await this.putBlobRow(hash, bytes);
+            }
+            await this.tx(async (c) => {
+                const exists = await c.query("SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1", [scope, key]);
+                if (exists.rows[0])
+                    return;
+                for (const [relPath, hash] of manifest) {
+                    await c.query("INSERT INTO snapshot_manifest (scope, snap_key, rel_path, blob_hash) VALUES ($1,$2,$3,$4)", [scope, key, relPath, hash]);
+                }
+            });
+            return { ok: true };
+        }
+        catch (err) {
+            return { ok: false, error: { code: "restore_failed", message: `import persist failed: ${err.message}` } };
+        }
+        finally {
+            this.inFlight.delete(flightKey);
+        }
+    }
+    async restore(scope, key, env, root, signal) {
+        try {
+            const r = await this.pool.query("SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2", [scope, key]);
+            if (r.rows.length === 0)
+                return { ok: false, error: { code: "not_found", message: `no file snapshot for ${scope}/${key}` } };
+            const manifest = new Map(r.rows.map((row) => [row.rel_path, row.blob_hash]));
+            return await applyManifest(env, root, this.bounds, signal, manifest, (hash) => this.blobs.getBlob(hash));
+        }
+        catch (err) {
+            return { ok: false, error: { code: "restore_failed", message: `restore blob read failed: ${err.message}` } };
+        }
+    }
+    async has(scope, key) {
+        const r = await this.pool.query("SELECT 1 FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2 LIMIT 1", [scope, key]);
+        return Boolean(r.rows[0]);
+    }
+    async listKeys(scope) {
+        const r = await this.pool.query("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = $1", [scope]);
+        return r.rows.map((row) => row.snap_key);
+    }
+    async exportManifest(scope, key) {
+        const r = await this.pool.query("SELECT rel_path, blob_hash FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2", [scope, key]);
+        if (r.rows.length === 0)
+            return null;
+        return new Map(r.rows.map((row) => [row.rel_path, row.blob_hash]));
+    }
+    async getBlob(hash) {
+        return this.blobs.getBlob(hash);
+    }
+    async hasBlobs(hashes) {
+        return this.blobs.hasBlobs(hashes);
+    }
+    async reap(scope, keepKeys) {
+        return this.tx(async (c) => {
+            const keys = await c.query("SELECT DISTINCT snap_key FROM snapshot_manifest WHERE scope = $1", [scope]);
+            const drop = keys.rows.map((k) => k.snap_key).filter((k) => !keepKeys.includes(k));
+            for (const k of drop)
+                await c.query("DELETE FROM snapshot_manifest WHERE scope = $1 AND snap_key = $2", [scope, k]);
+            return drop.length;
+        });
+    }
+    async deleteBySession(scope) {
+        const r = await this.pool.query("DELETE FROM snapshot_manifest WHERE scope = $1", [scope]);
+        return r.rowCount ?? 0;
+    }
+    async gcOrphanBlobs() {
+        const r = await this.pool.query("SELECT blob_hash FROM snapshot_blob WHERE blob_hash NOT IN (SELECT blob_hash FROM snapshot_manifest)").catch(() => undefined);
+        const orphans = (r?.rows ?? []).map((row) => row.blob_hash);
+        if (orphans.length === 0)
+            return 0;
+        return this.blobs.deleteBlobs(orphans);
+    }
+    async sweepOrphanBlobs() {
+        return this.gcOrphanBlobs();
+    }
+    async tx(fn) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            const out = await fn(c);
+            await c.query("COMMIT");
+            return out;
+        }
+        catch (err) {
+            try {
+                await c.query("ROLLBACK");
+            }
+            catch {
+            }
+            throw err;
+        }
+        finally {
+            c.release();
+        }
+    }
+}
+//# sourceMappingURL=pg-file-snapshot-store.js.map