@intentface/latch-drizzle 0.9.1 → 0.11.0

package/dist/agent-store.js

@@ -1,5 +1,6 @@
 import { desc, eq, inArray, and, like, sql } from "drizzle-orm";
 import { parseAgentRef } from "@intentface/latch-agent-builder";
+import { isUniqueViolation } from "./adapter.shared.js";
 import * as sqliteSchema from "./schema.js";
 import * as pgSchema from "./schema.pg.js";
 /**
@@ -10,12 +11,101 @@ import * as pgSchema from "./schema.pg.js";
 function newId() {
     return `agt_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`;
 }
+function newVersionId() {
+    return `agv_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`;
+}
+function newActivationId() {
+    return `aga_${crypto.randomUUID().replace(/-/g, "").slice(0, 20)}`;
+}
+/**
+ * How many times a publish retries when a concurrent one takes its number.
+ *
+ * Each contended round lets exactly one writer through, so a loser may need as
+ * many attempts as there are concurrent publishers. Real contention here is a
+ * couple of humans clicking Publish, so this is far above what can be reached —
+ * it exists only so the loop is bounded rather than as a tuned value.
+ */
+const PUBLISH_ATTEMPTS = 20;
+/**
+ * Jittered pause between publish retries. Without it, losers re-read and re-try
+ * in lockstep and collide again; a few random milliseconds desynchronises them.
+ */
+const publishBackoff = () => new Promise((r) => setTimeout(r, Math.floor(Math.random() * 5) + 1));
+/**
+ * Stable JSON for EQUALITY ONLY (never for storage): object keys sorted at every
+ * depth, and absent/null/empty-array treated alike.
+ *
+ * That last part is what makes "publishing an unchanged record appends nothing"
+ * actually hold. The same record reaches this function in three spellings — a
+ * caller's `AgentRecord` (absent keys are `undefined`), a row round-tripped
+ * through the live table (empty arrays are stored `null`), and the migration's
+ * backfilled v1 (built by `json_object`, so every absent column is an explicit
+ * `null`). Without flattening those, a no-op publish right after the backfill
+ * would append a duplicate version.
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v === undefined || v === null)
+                continue;
+            if (Array.isArray(v) && v.length === 0)
+                continue;
+            out[key] = canonicalize(v);
+        }
+        return out;
+    }
+    return value;
+}
+const canonical = (rec) => JSON.stringify(canonicalize(rec));
+/**
+ * Which top-level record fields differ between two versions. Compared through
+ * `canonicalize`, so the same spelling rules that decide "did anything change at
+ * all" also decide "which field changed" — otherwise a record could publish
+ * (unchanged overall) yet report fields as changed, or vice versa.
+ *
+ * `undefined` for the first version: there is nothing to have changed from.
+ */
+function changedFieldsBetween(prev, next) {
+    if (!prev)
+        return undefined;
+    const a = canonicalize(prev);
+    const b = canonicalize(next);
+    const fields = [...new Set([...Object.keys(a), ...Object.keys(b)])]
+        .sort()
+        .filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
+    return fields.length ? fields : undefined;
+}
+/**
+ * A stored version payload back into an `AgentRecord`. Nulls become absent
+ * (see `canonicalize`) so a backfilled row and a published one round-trip to
+ * the same record. JSON columns arrive parsed from both dialects; a string is
+ * tolerated for hosts whose driver hands back raw text.
+ */
+function recordFromJson(value) {
+    const raw = (typeof value === "string" ? JSON.parse(value) : value);
+    const out = {};
+    for (const [key, v] of Object.entries(raw ?? {})) {
+        if (v === null || v === undefined)
+            continue;
+        out[key] = v;
+    }
+    if (!Array.isArray(out.connections))
+        out.connections = [];
+    return out;
+}
 /** Column value (INTEGER) ↔ AgentRecord.maxSteps: NULL=default, 0=unlimited, N=cap. */
 const maxStepsToCol = (m) => m === "unlimited" ? 0 : typeof m === "number" ? m : null;
 const maxStepsFromCol = (v) => v == null ? undefined : v === 0 ? "unlimited" : v;
 const ownerKeyOf = (segments) => segments.map(encodeURIComponent).join("/");
 function createStore(queries, opts) {
     const ownerKey = (p, scope) => ownerKeyOf(opts.owner(p, scope));
+    // The user-scope owner key is already per-person wherever the host's user
+    // scope carries a user id, so it is the right default editor identity.
+    const editorKey = (p) => opts.editorKey?.(p) ?? ownerKeyOf(opts.owner(p, "user"));
     const recordOf = (row) => ({
         name: row.name,
         title: row.title ?? undefined,
@@ -30,6 +120,18 @@ function createStore(queries, opts) {
         attachedEvals: (row.attachedEvals ?? undefined),
         scope: row.scope,
     });
+    /** The matched ROW, for callers that need more than the record (see `resolve`). */
+    async function findRow(p, name, scope) {
+        // Personal wins over org on a name clash — unless pinned to one scope.
+        const owners = scope === "org"
+            ? [ownerKey(p, "org")]
+            : scope === "user"
+                ? [ownerKey(p, "user")]
+                : [ownerKey(p, "user"), ownerKey(p, "org")];
+        const rows = await queries.byOwners(owners, name);
+        const personal = rows.find((r) => r.owner === ownerKey(p, "user"));
+        return personal ?? rows[0];
+    }
     async function find(p, name, scope) {
         // Personal wins over org on a name clash — unless pinned to one scope.
         const owners = scope === "org"
@@ -49,9 +151,10 @@ function createStore(queries, opts) {
             // it), so a same-named record in the OTHER scope can never shadow the
             // agent the binding was created for.
             const ref = parseAgentRef(name);
-            const rec = await find(principal, ref.name, ref.scope);
-            if (!rec)
+            const row = await findRow(principal, ref.name, ref.scope);
+            if (!row)
                 return undefined;
+            const rec = recordOf(row);
             const decorate = opts.decorateResolve ?? ((cfg) => cfg);
             const sel = rec.tools;
             const approvalEntries = Object.entries(sel?.approval ?? {});
@@ -80,6 +183,10 @@ function createStore(queries, opts) {
                 ]
                 : undefined;
             return decorate({
+                // Which stored version this config is a copy of — recorded on the run
+                // and emitted as a trace tag, so an answer can be traced back to the
+                // configuration that produced it.
+                configVersion: row.publishedVersion ?? undefined,
                 model: opts.modelFor(rec.modelId),
                 instructions: rec.instructions,
                 connections: rec.connections,
@@ -129,23 +236,209 @@ function createStore(queries, opts) {
         async listMemoryEnabledNames() {
             return queries.memoryEnabledNames();
         },
-        async upsert(principal, rec) {
+        async upsert(principal, rec, opts) {
+            await publish(ownerKey(principal, rec.scope), rec, {
+                author: editorKey(principal),
+                ...opts,
+            });
+        },
+        async remove(principal, scope, name) {
+            const owner = ownerKey(principal, scope);
+            // Live row first: an interrupted delete then leaves orphan version rows
+            // (harmless — nothing resolves them) rather than a live agent whose
+            // history has silently vanished.
+            await queries.remove(owner, name);
+            await queries.removeVersions(owner, name);
+            await queries.removeActivations(owner, name);
+            await queries.removeDrafts(owner, name);
+        },
+        async listVersions(principal, name, scope) {
+            const owner = ownerKey(principal, scope);
+            const [rows, live] = await Promise.all([
+                queries.versions(owner, name),
+                queries.byOwners([owner], name),
+            ]);
+            const publishedVersion = live[0]?.publishedVersion ?? null;
+            return rows.map((r) => ({
+                version: r.version,
+                author: r.author ?? undefined,
+                source: (r.source ?? undefined),
+                message: r.changeMessage ?? undefined,
+                changedFields: (r.changedFields ?? undefined),
+                createdAt: r.createdAt,
+                published: r.version === publishedVersion,
+            }));
+        },
+        async getVersion(principal, name, scope, version) {
+            const row = await queries.versionAt(ownerKey(principal, scope), name, version);
+            return row ? recordFromJson(row.record) : undefined;
+        },
+        async activateVersion(principal, name, scope, version, opts) {
+            const owner = ownerKey(principal, scope);
+            const row = await queries.versionAt(owner, name, version);
+            if (!row)
+                throw new Error(`No version ${version} of agent "${name}".`);
+            // Pin the scope to the one asked for: it decides the owner key, and a
+            // record stored under a since-changed scope must not write elsewhere.
+            const rec = { ...recordFromJson(row.record), name, scope };
+            const now = Date.now();
+            // Pointer move only — no version is appended. Flipping between two
+            // configurations must not grow history by one duplicate row each time.
             await queries.upsert({
                 id: newId(),
-                owner: ownerKey(principal, rec.scope),
+                owner,
                 rec,
                 maxSteps: maxStepsToCol(rec.maxSteps),
+                now,
+                publishedVersion: version,
+            });
+            await recordActivation(owner, name, version, opts?.actor ?? editorKey(principal), "activate", now);
+        },
+        async listActivations(principal, name, scope, limit) {
+            const rows = await queries.activations(ownerKey(principal, scope), name, limit);
+            return rows.map((r) => ({
+                version: r.version,
+                actor: r.actor ?? undefined,
+                source: (r.source ?? undefined),
+                createdAt: r.createdAt,
+            }));
+        },
+        async getDraft(principal, name, scope) {
+            const row = await queries.draft(ownerKey(principal, scope), name, editorKey(principal));
+            if (!row)
+                return undefined;
+            return {
+                record: recordFromJson(row.record),
+                baseVersion: row.baseVersion ?? undefined,
+                updatedAt: row.updatedAt,
+            };
+        },
+        async saveDraft(principal, name, scope, rec, baseVersion) {
+            await queries.upsertDraft({
+                owner: ownerKey(principal, scope),
+                name,
+                editor: editorKey(principal),
+                // Pin identity to the arguments: a draft keyed (owner, name, editor)
+                // whose record claimed another name would publish to the wrong agent.
+                rec: { ...rec, name, scope },
+                baseVersion: baseVersion ?? null,
                 now: Date.now(),
             });
         },
-        async remove(principal, scope, name) {
-            await queries.remove(ownerKey(principal, scope), name);
+        async discardDraft(principal, name, scope) {
+            await queries.removeDraft(ownerKey(principal, scope), name, editorKey(principal));
+        },
+        async listDrafts(principal) {
+            const mine = editorKey(principal);
+            const owners = [ownerKey(principal, "user"), ownerKey(principal, "org")];
+            const rows = await queries.draftsByOwners(owners);
+            return rows.map((r) => ({
+                name: r.name,
+                scope: r.owner === owners[1] ? "org" : "user",
+                mine: r.editor === mine,
+                updatedAt: r.updatedAt,
+            }));
         },
     };
+    /** Append to the publish timeline. Never fails the write it follows. */
+    async function recordActivation(owner, name, version, actor, source, now) {
+        try {
+            await queries.insertActivation({
+                id: newActivationId(),
+                owner,
+                name,
+                version,
+                actor: actor ?? null,
+                source,
+                now,
+            });
+        }
+        catch (error) {
+            // The timeline is an audit trail, not a correctness invariant: the live
+            // row and the version are already written, and losing one entry must not
+            // turn a successful publish into a failed one.
+            console.warn(`Could not record agent activation for "${name}":`, error);
+        }
+    }
+    /**
+     * Write the live row and append a version — the one path by which a record
+     * becomes current.
+     *
+     * Two ordering rules, neither of which needs a transaction (this store also
+     * serves better-sqlite3, whose transaction API rejects an async callback, and
+     * libsql, which opens one on a NEW connection — see `createSqliteAdapter`):
+     *
+     * 1. The VERSION row is written before the live row. Interrupted that way,
+     *    history holds a version nothing points at — visible, inert, superseded by
+     *    the next publish. The reverse order would leave the live row claiming a
+     *    `published_version` that does not exist, breaking history and rollback.
+     * 2. The version NUMBER is `max + 1` read outside any lock, so two concurrent
+     *    publishes can choose the same one. The UNIQUE (owner, name, version)
+     *    index rejects the loser, which re-reads the head and retries — the same
+     *    "let the index arbitrate" discipline the rest of this package uses.
+     */
+    async function publish(owner, rec, opts) {
+        const target = canonical(rec);
+        for (let attempt = 1; attempt <= PUBLISH_ATTEMPTS; attempt++) {
+            const head = (await queries.versions(owner, rec.name, 1))[0];
+            const now = Date.now();
+            // Unchanged content appends nothing, so history stays a list of real
+            // changes. The live row is still written: it reconciles a row that drifted
+            // from its version (a direct DB edit, an interrupted earlier publish).
+            if (head && canonical(recordFromJson(head.record)) === target) {
+                await queries.upsert({
+                    id: newId(),
+                    owner,
+                    rec,
+                    maxSteps: maxStepsToCol(rec.maxSteps),
+                    now,
+                    publishedVersion: head.version,
+                });
+                return;
+            }
+            const version = (head?.version ?? 0) + 1;
+            const message = opts?.message?.trim();
+            try {
+                await queries.insertVersion({
+                    id: newVersionId(),
+                    owner,
+                    name: rec.name,
+                    version,
+                    rec,
+                    author: opts?.author ?? null,
+                    source: opts?.source ?? "api",
+                    changedFields: changedFieldsBetween(head ? recordFromJson(head.record) : undefined, rec) ?? null,
+                    changeMessage: message || null,
+                    now,
+                });
+            }
+            catch (error) {
+                // Someone else took this number: back off, re-read the head, try again.
+                if (isUniqueViolation(error) && attempt < PUBLISH_ATTEMPTS) {
+                    await publishBackoff();
+                    continue;
+                }
+                throw error;
+            }
+            await queries.upsert({
+                id: newId(),
+                owner,
+                rec,
+                maxSteps: maxStepsToCol(rec.maxSteps),
+                now,
+                publishedVersion: version,
+            });
+            // A publish is also an activation: recording both here and in
+            // `activateVersion` is what makes the timeline complete.
+            await recordActivation(owner, rec.name, version, opts?.author, "publish", now);
+            return;
+        }
+        throw new Error(`Could not publish agent "${rec.name}": ${PUBLISH_ATTEMPTS} version numbers were taken concurrently.`);
+    }
 }
 /** Shared upsert `set` payload (column shapes match across dialects). */
 function upsertValues(row) {
-    const { id, owner, rec, maxSteps, now } = row;
+    const { id, owner, rec, maxSteps, now, publishedVersion } = row;
     return {
         insert: {
             id,
@@ -162,6 +455,7 @@ function upsertValues(row) {
             attachedEvals: rec.attachedEvals?.length ? rec.attachedEvals : null,
             maxSteps,
             scope: rec.scope,
+            publishedVersion,
             createdAt: now,
             updatedAt: now,
         },
@@ -177,13 +471,32 @@ function upsertValues(row) {
             attachedEvals: rec.attachedEvals?.length ? rec.attachedEvals : null,
             maxSteps,
             scope: rec.scope,
+            publishedVersion,
             updatedAt: now,
         },
     };
 }
+/** Shared version-row insert payload (column shapes match across dialects). */
+function versionValues(row) {
+    return {
+        id: row.id,
+        owner: row.owner,
+        name: row.name,
+        version: row.version,
+        record: row.rec,
+        author: row.author,
+        source: row.source,
+        changedFields: row.changedFields,
+        changeMessage: row.changeMessage,
+        createdAt: row.now,
+    };
+}
 /** `AgentBuilderStore` on a Drizzle SQLite database (libsql / better-sqlite3 / Turso). */
 export function createSqliteAgentBuilderStore(db, opts) {
     const t = sqliteSchema.agents;
+    const v = sqliteSchema.agentVersions;
+    const a = sqliteSchema.agentActivations;
+    const d = sqliteSchema.agentDrafts;
     return createStore({
         async byOwners(owners, name) {
             const where = name ? and(inArray(t.owner, owners), eq(t.name, name)) : inArray(t.owner, owners);
@@ -205,11 +518,109 @@ export function createSqliteAgentBuilderStore(db, opts) {
         async remove(owner, name) {
             await db.delete(t).where(and(eq(t.owner, owner), eq(t.name, name)));
         },
+        async versions(owner, name, limit) {
+            const q = db
+                .select({
+                version: v.version,
+                record: v.record,
+                author: v.author,
+                source: v.source,
+                changedFields: v.changedFields,
+                changeMessage: v.changeMessage,
+                createdAt: v.createdAt,
+            })
+                .from(v)
+                .where(and(eq(v.owner, owner), eq(v.name, name)))
+                .orderBy(desc(v.version));
+            return (limit ? await q.limit(limit) : await q);
+        },
+        async versionAt(owner, name, version) {
+            const rows = (await db
+                .select({
+                version: v.version,
+                record: v.record,
+                author: v.author,
+                source: v.source,
+                changedFields: v.changedFields,
+                changeMessage: v.changeMessage,
+                createdAt: v.createdAt,
+            })
+                .from(v)
+                .where(and(eq(v.owner, owner), eq(v.name, name), eq(v.version, version)))
+                .limit(1));
+            return rows[0];
+        },
+        async insertVersion(row) {
+            await db.insert(v).values(versionValues(row));
+        },
+        async removeVersions(owner, name) {
+            await db.delete(v).where(and(eq(v.owner, owner), eq(v.name, name)));
+        },
+        async insertActivation(row) {
+            await db.insert(a).values({
+                id: row.id,
+                owner: row.owner,
+                name: row.name,
+                version: row.version,
+                actor: row.actor,
+                source: row.source,
+                createdAt: row.now,
+            });
+        },
+        async activations(owner, name, limit) {
+            const q = db
+                .select({ version: a.version, actor: a.actor, source: a.source, createdAt: a.createdAt })
+                .from(a)
+                .where(and(eq(a.owner, owner), eq(a.name, name)))
+                .orderBy(desc(a.createdAt));
+            return (limit ? await q.limit(limit) : await q);
+        },
+        async removeActivations(owner, name) {
+            await db.delete(a).where(and(eq(a.owner, owner), eq(a.name, name)));
+        },
+        async draft(owner, name, editor) {
+            const rows = (await db
+                .select()
+                .from(d)
+                .where(and(eq(d.owner, owner), eq(d.name, name), eq(d.editor, editor)))
+                .limit(1));
+            return rows[0];
+        },
+        async upsertDraft(row) {
+            await db
+                .insert(d)
+                .values({
+                owner: row.owner,
+                name: row.name,
+                editor: row.editor,
+                record: row.rec,
+                baseVersion: row.baseVersion,
+                updatedAt: row.now,
+            })
+                .onConflictDoUpdate({
+                target: [d.owner, d.name, d.editor],
+                set: { record: row.rec, baseVersion: row.baseVersion, updatedAt: row.now },
+            });
+        },
+        async removeDraft(owner, name, editor) {
+            await db
+                .delete(d)
+                .where(and(eq(d.owner, owner), eq(d.name, name), eq(d.editor, editor)));
+        },
+        async draftsByOwners(owners) {
+            return (await db.select().from(d).where(inArray(d.owner, owners)));
+        },
+        async removeDrafts(owner, name) {
+            await db.delete(d).where(and(eq(d.owner, owner), eq(d.name, name)));
+        },
     }, opts);
 }
 /** `AgentBuilderStore` on a Drizzle Postgres database (node-postgres / postgres-js / PGlite). */
 export function createPostgresAgentBuilderStore(db, opts) {
     const t = pgSchema.agents;
+    const v = pgSchema.agentVersions;
+    const a = pgSchema.agentActivations;
+    const d = pgSchema.agentDrafts;
     return createStore({
         async byOwners(owners, name) {
             const where = name ? and(inArray(t.owner, owners), eq(t.name, name)) : inArray(t.owner, owners);
@@ -231,6 +642,101 @@ export function createPostgresAgentBuilderStore(db, opts) {
         async remove(owner, name) {
             await db.delete(t).where(and(eq(t.owner, owner), eq(t.name, name)));
         },
+        async versions(owner, name, limit) {
+            const q = db
+                .select({
+                version: v.version,
+                record: v.record,
+                author: v.author,
+                source: v.source,
+                changedFields: v.changedFields,
+                changeMessage: v.changeMessage,
+                createdAt: v.createdAt,
+            })
+                .from(v)
+                .where(and(eq(v.owner, owner), eq(v.name, name)))
+                .orderBy(desc(v.version));
+            return (limit ? await q.limit(limit) : await q);
+        },
+        async versionAt(owner, name, version) {
+            const rows = (await db
+                .select({
+                version: v.version,
+                record: v.record,
+                author: v.author,
+                source: v.source,
+                changedFields: v.changedFields,
+                changeMessage: v.changeMessage,
+                createdAt: v.createdAt,
+            })
+                .from(v)
+                .where(and(eq(v.owner, owner), eq(v.name, name), eq(v.version, version)))
+                .limit(1));
+            return rows[0];
+        },
+        async insertVersion(row) {
+            await db.insert(v).values(versionValues(row));
+        },
+        async removeVersions(owner, name) {
+            await db.delete(v).where(and(eq(v.owner, owner), eq(v.name, name)));
+        },
+        async insertActivation(row) {
+            await db.insert(a).values({
+                id: row.id,
+                owner: row.owner,
+                name: row.name,
+                version: row.version,
+                actor: row.actor,
+                source: row.source,
+                createdAt: row.now,
+            });
+        },
+        async activations(owner, name, limit) {
+            const q = db
+                .select({ version: a.version, actor: a.actor, source: a.source, createdAt: a.createdAt })
+                .from(a)
+                .where(and(eq(a.owner, owner), eq(a.name, name)))
+                .orderBy(desc(a.createdAt));
+            return (limit ? await q.limit(limit) : await q);
+        },
+        async removeActivations(owner, name) {
+            await db.delete(a).where(and(eq(a.owner, owner), eq(a.name, name)));
+        },
+        async draft(owner, name, editor) {
+            const rows = (await db
+                .select()
+                .from(d)
+                .where(and(eq(d.owner, owner), eq(d.name, name), eq(d.editor, editor)))
+                .limit(1));
+            return rows[0];
+        },
+        async upsertDraft(row) {
+            await db
+                .insert(d)
+                .values({
+                owner: row.owner,
+                name: row.name,
+                editor: row.editor,
+                record: row.rec,
+                baseVersion: row.baseVersion,
+                updatedAt: row.now,
+            })
+                .onConflictDoUpdate({
+                target: [d.owner, d.name, d.editor],
+                set: { record: row.rec, baseVersion: row.baseVersion, updatedAt: row.now },
+            });
+        },
+        async removeDraft(owner, name, editor) {
+            await db
+                .delete(d)
+                .where(and(eq(d.owner, owner), eq(d.name, name), eq(d.editor, editor)));
+        },
+        async draftsByOwners(owners) {
+            return (await db.select().from(d).where(inArray(d.owner, owners)));
+        },
+        async removeDrafts(owner, name) {
+            await db.delete(d).where(and(eq(d.owner, owner), eq(d.name, name)));
+        },
     }, opts);
 }
 //# sourceMappingURL=agent-store.js.map