@retinue/agentkit 0.1.0

package/dist/adapters/postgres/knowledge.js

@@ -0,0 +1,255 @@
+/**
+ * pgvector `KnowledgeStore` and `VectorIndex` (#135).
+ *
+ * One table backs both ports, which is the point of splitting them: a deployment on pgvector answers both from
+ * `knowledge_chunks`, and a deployment on a dedicated vector database answers them from two systems, with
+ * nothing above changing.
+ *
+ * **AC-3 is a `WHERE` clause, and it is the reason this adapter exists rather than a filter above it.** The
+ * permission predicate is in the same statement as the nearest-neighbour scan, so an unauthorised chunk is
+ * never a candidate. Filtering afterwards leaks through result counts — ask for ten, get three, and you have
+ * learned that seven exist you may not see. `EXPLAIN` shows the predicate inside the scan, which is what the
+ * test asserts.
+ *
+ * **`replaceSource` is one transaction-shaped pair of statements.** Delete-then-insert, in that order, so a
+ * changed document's old chunks are never searchable alongside its new ones. Appending would leave a stale
+ * chunk that cites text no longer in the document.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { stripStopwords } from "../../persistence/index.js";
+import { VECTOR_DIMENSIONS } from "./migrations.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : v);
+const toChunk = (r) => ({
+    id: r.id,
+    sourceType: r.source_type,
+    sourceId: r.source_id,
+    chunkIndex: Number(r.chunk_index),
+    content: r.content,
+    tokenCount: Number(r.token_count),
+    authSubject: r.auth_subject,
+    embeddingModel: {
+        modelId: r.embedding_model,
+        version: r.embedding_version,
+        dimensions: Number(r.embedding_dims),
+    },
+    ...(r.locator === null ? {} : { locator: r.locator }),
+    createdAt: iso(r.created_at),
+});
+const COLUMNS = `id, source_type, source_id, chunk_index, content, token_count, auth_subject,
+                 embedding_model, embedding_version, embedding_dims, locator, created_at`;
+/**
+ * pgvector's literal form: `[0.1,0.2,...]`.
+ *
+ * Built as a string rather than passed as an array, because node-postgres has no vector type and would send an
+ * array as `{...}` — which pgvector rejects. `Number.isFinite` is checked because a `NaN` in a vector makes
+ * every distance `NaN`, and the symptom is a search that returns nothing rather than an error.
+ */
+export const toVectorLiteral = (embedding) => {
+    if (embedding.length !== VECTOR_DIMENSIONS)
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `embedding has ${embedding.length} dimensions but the schema declares ${VECTOR_DIMENSIONS}`,
+            retryable: false,
+        });
+    for (const value of embedding)
+        if (!Number.isFinite(value))
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: "embedding contains a non-finite value",
+                retryable: false,
+            });
+    return `[${embedding.join(",")}]`;
+};
+export const createPostgresKnowledgeStore = (sql) => ({
+    async replaceSource({ tenantId, sourceType, sourceId, chunks }) {
+        for (const chunk of chunks) {
+            if (chunk.embedding.length !== chunk.embeddingModel.dimensions)
+                // Caught before the write: a vector of the wrong length would score against whatever prefix overlapped,
+                // which looks like bad relevance rather than a bug.
+                throw new AgentPlatformError({
+                    code: "invalid_input",
+                    message: `chunk ${chunk.id} has ${chunk.embedding.length} dimensions but its model declares ${chunk.embeddingModel.dimensions}`,
+                    retryable: false,
+                });
+        }
+        // Delete first. Old chunks must never be searchable next to new ones: a stale chunk cites text that is no
+        // longer in the document, which is worse than the document being briefly absent.
+        const removedRows = await sql.query(`DELETE FROM knowledge_chunks
+        WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3
+        RETURNING id`, [tenantId, sourceType, sourceId]);
+        for (const chunk of chunks) {
+            await sql.query(`INSERT INTO knowledge_chunks (tenant_id, id, source_type, source_id, chunk_index, content,
+                                        token_count, auth_subject, embedding, embedding_model,
+                                        embedding_version, embedding_dims, locator, created_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::vector,$10,$11,$12,$13,$14)
+         -- A re-run of the same batch overwrites its own rows rather than failing: an interrupted re-index is
+         -- resumed by running it again, and that has to be safe (AC-5).
+         ON CONFLICT (tenant_id, id) DO UPDATE SET
+           chunk_index = EXCLUDED.chunk_index,
+           content = EXCLUDED.content,
+           token_count = EXCLUDED.token_count,
+           auth_subject = EXCLUDED.auth_subject,
+           embedding = EXCLUDED.embedding,
+           embedding_model = EXCLUDED.embedding_model,
+           embedding_version = EXCLUDED.embedding_version,
+           embedding_dims = EXCLUDED.embedding_dims,
+           locator = EXCLUDED.locator`, [
+                tenantId,
+                chunk.id,
+                sourceType,
+                sourceId,
+                chunk.chunkIndex,
+                chunk.content,
+                chunk.tokenCount,
+                chunk.authSubject,
+                toVectorLiteral(chunk.embedding),
+                chunk.embeddingModel.modelId,
+                chunk.embeddingModel.version,
+                chunk.embeddingModel.dimensions,
+                chunk.locator ?? null,
+                chunk.createdAt,
+            ]);
+        }
+        return { written: chunks.length, removed: removedRows.length };
+    },
+    async listBySource({ tenantId, sourceType, sourceId, limit, cursor }) {
+        // Cursored on `chunk_index`, which is contiguous within a source and therefore exact -- and "the chunks of
+        // this document" is an ordered thing, so the order must be the document's.
+        const after = cursor === undefined ? -1 : Number.parseInt(cursor, 10);
+        const from = Number.isSafeInteger(after) ? after : -1;
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM knowledge_chunks
+        WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3 AND chunk_index > $4
+        ORDER BY chunk_index
+        LIMIT $5`, [tenantId, sourceType, sourceId, from, limit + 1]);
+        const items = rows.slice(0, limit).map(toChunk);
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: String(last.chunkIndex) }
+            : { items };
+    },
+    async get({ tenantId, id }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM knowledge_chunks WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        // A foreign id yields no row, so it is null without a comparison anyone could get wrong.
+        return rows[0] === undefined ? null : toChunk(rows[0]);
+    },
+    async deleteSource({ tenantId, sourceType, sourceId }) {
+        const rows = await sql.query(`DELETE FROM knowledge_chunks
+        WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3
+        RETURNING id`, [tenantId, sourceType, sourceId]);
+        return { removed: rows.length };
+    },
+    async listStaleSources({ tenantId, current, limit, cursor }) {
+        const rows = await sql.query(`SELECT source_type, source_id, COUNT(*) AS chunk_count
+         FROM knowledge_chunks
+        WHERE tenant_id = $1
+          -- Anything not embedded by exactly this model. Derived from what is *stored*, which is what makes an
+          -- interrupted re-index resumable: it asks again rather than remembering where it was.
+          AND NOT (embedding_model = $2 AND embedding_version = $3 AND embedding_dims = $4)
+          AND ($5::text IS NULL OR (source_type || ' ' || source_id) > $5::text)
+        GROUP BY source_type, source_id
+        -- Stable order, so a resumed re-index does not revisit sources it finished and skip ones it did not.
+        ORDER BY source_type, source_id
+        LIMIT $6`, [tenantId, current.modelId, current.version, current.dimensions, cursor ?? null, limit + 1]);
+        const items = rows.slice(0, limit).map((r) => ({
+            sourceType: r.source_type,
+            sourceId: r.source_id,
+            chunkCount: Number(r.chunk_count),
+        }));
+        const last = items[items.length - 1];
+        return rows.length > limit && last !== undefined
+            ? { items, nextCursor: `${last.sourceType} ${last.sourceId}` }
+            : { items };
+    },
+});
+export const createPostgresVectorIndex = (sql) => ({
+    async search({ tenantId, embedding, authSubjects, limit, minScore, sourceTypes }) {
+        // An empty subject list means "no subjects", which correctly returns nothing. Short-circuited so the
+        // database is not asked a question whose answer is already known -- and so `= ANY('{}')` semantics are
+        // never relied on.
+        if (authSubjects.length === 0)
+            return [];
+        const rows = await sql.query(`SELECT ${COLUMNS},
+              -- Cosine *distance* is 0 (identical) to 2 (opposite); the ports normalise to a 0-1 score where
+              -- higher is closer, so a caller never has to know the metric.
+              1 - (embedding <=> $2::vector) / 2 AS score
+         FROM knowledge_chunks
+        WHERE tenant_id = $1
+          -- AC-3: the permission predicate is in the same statement as the scan, so an unauthorised chunk is
+          -- never a candidate. EXPLAIN shows it inside the scan, which is what the test asserts.
+          AND auth_subject = ANY($3::text[])
+          AND ($4::text[] IS NULL OR source_type = ANY($4::text[]))
+          AND ($5::float8 IS NULL OR 1 - (embedding <=> $2::vector) / 2 >= $5::float8)
+        ORDER BY embedding <=> $2::vector, id
+        LIMIT $6`, [
+            tenantId,
+            toVectorLiteral(embedding),
+            authSubjects,
+            sourceTypes === undefined ? null : [...sourceTypes],
+            minScore ?? null,
+            limit,
+        ]);
+        return rows.map((r) => ({ chunk: toChunk(r), score: Number(r.score) }));
+    },
+});
+/** Re-exported so a caller comparing a stored chunk's model to the current one does it the same way. */
+export const sameEmbeddingModel = (a, b) => a.modelId === b.modelId && a.version === b.version && a.dimensions === b.dimensions;
+/**
+ * Postgres full-text `KeywordIndex` (#136).
+ *
+ * Over `knowledge_chunks.content_tsv`, the same rows the vector index searches, so a chunk cannot be visible to
+ * one signal and invisible to the other.
+ *
+ * **`websearch_to_tsquery`, not `to_tsquery`.** The latter throws on ordinary user input — an unbalanced quote,
+ * a bare `&`, a trailing operator — and a search box that errors on a stray character is a search box that
+ * errors. `websearch_to_tsquery` accepts anything and interprets quotes and `or` the way a person expects.
+ *
+ * **The score is normalised against the best hit in the result set**, not against an absolute. `ts_rank_cd`
+ * has no upper bound and its scale depends on the corpus, so an absolute threshold would mean different things
+ * in different tenants — and fusing an unbounded score with a bounded cosine similarity would let the
+ * unbounded one dominate whenever it happened to be larger.
+ */
+export const createPostgresKeywordIndex = (sql) => ({
+    async search({ tenantId, query, authSubjects, limit, minScore, sourceTypes }) {
+        // "No subjects" means nothing, not everything. Short-circuited so the database is never asked a question
+        // whose answer is already known.
+        if (authSubjects.length === 0)
+            return [];
+        // Stopwords come off the query, not the index. `simple` is chosen over `english` so identifiers survive
+        // (`english` stems, which destroys `ERR-4021`), and the price of `simple` is that it keeps stopwords —
+        // paid here rather than by matching every document that says "the".
+        const terms = stripStopwords(query);
+        if (terms === "")
+            return [];
+        const rows = await sql.query(`WITH q AS (SELECT websearch_to_tsquery('simple', $2) AS tsq),
+            scored AS (
+              SELECT ${COLUMNS},
+                     -- cd = cover density: it rewards query terms appearing close together, which is what
+                     -- distinguishes a chunk *about* the terms from one that mentions them separately.
+                     ts_rank_cd(content_tsv, q.tsq) AS rank
+                FROM knowledge_chunks, q
+               WHERE tenant_id = $1
+                 -- AC-3, for the keyword signal too: the permission predicate is in the same statement as the
+                 -- match, so an excluded chunk is never a candidate and never influences the ranking of the
+                 -- ones that are.
+                 AND auth_subject = ANY($3::text[])
+                 AND ($4::text[] IS NULL OR source_type = ANY($4::text[]))
+                 AND content_tsv @@ q.tsq
+            )
+       SELECT *, rank / NULLIF(MAX(rank) OVER (), 0) AS normalised
+         FROM scored
+        ORDER BY rank DESC, id
+        LIMIT $5`, [tenantId, terms, authSubjects, sourceTypes === undefined ? null : [...sourceTypes], limit]);
+        return rows
+            .map((r) => {
+            const normalised = r.normalised;
+            return {
+                chunk: toChunk(r),
+                // `NULLIF(...,0)` yields null when every rank is zero, which cannot happen for a matching row but is
+                // cheaper to handle than to prove impossible.
+                score: normalised === null ? 0 : Number(normalised),
+            };
+        })
+            .filter((h) => minScore === undefined || h.score >= minScore);
+    },
+});
+//# sourceMappingURL=knowledge.js.map

package/dist/adapters/postgres/memory.d.ts

@@ -0,0 +1,14 @@
+import type { BlobStore } from "../../persistence/index.js";
+import type { PrincipalMemoryStore } from "../../principal-memory/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresPrincipalMemoryStore: (sql: SqlExecutor, options?: {
+    readonly clock?: () => string;
+}) => PrincipalMemoryStore;
+/**
+ * The tool-output offload. Stores the **value**, because that is what the port does: `put(value)`
+ * returns a ref and `get(ref)` must hand the value back. The `blob_refs` metadata-and-pointer table
+ * the SPEC described cannot implement this — there is nothing in the port to fetch bytes with — and
+ * belongs to `FileMetadataStore` (#129) or `ArtifactStore` (#133) instead.
+ */
+export declare const createPostgresBlobStore: (sql: SqlExecutor) => BlobStore;
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/postgres/memory.js

@@ -0,0 +1,194 @@
+/**
+ * PostgreSQL `PrincipalMemoryStore` and `BlobStore` (#102) — per-user memory and the tool-output
+ * offload. Completes the Postgres column at 19/19.
+ *
+ * Per-user memory is the feature most visibly broken by memory-only storage: a user says "remember
+ * this" and it is gone after the next deploy. Two properties carry the weight, and both are enforced
+ * in the statement rather than by convention:
+ *
+ * - **Cross-principal isolation is structural.** Every method takes `principalId` and every statement
+ *   filters on it as part of the primary key. There is no method that *could* read across principals,
+ *   which is a stronger guarantee than a policy that each query remembers to apply.
+ * - **A disabled entry is never a retrieval candidate.** `retrieve` filters `disabled_at IS NULL`, and
+ *   the index it reads is partial on the same predicate — an index cannot return what it does not
+ *   contain. A user switching a memory off and having it still shape answers is the failure this
+ *   prevents, and it is a privacy failure, not a correctness nicety.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { asId } from "../../core/ids.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Memory ${id} not found`, retryable: false });
+const conflict = (m) => new AgentPlatformError({ code: "conflict", message: m, retryable: false });
+const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const toEntry = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    principalId: r.principal_id,
+    text: r.text,
+    tags: json(r.tags) ?? [],
+    salience: Number(r.salience),
+    version: Number(r.version),
+    createdAt: iso(r.created_at),
+    updatedAt: iso(r.updated_at),
+    ...(r.disabled_at === null ? {} : { disabledAt: iso(r.disabled_at) }),
+});
+const MEMORY_COLUMNS = `tenant_id, principal_id, id, text, tags, salience, version,
+         created_at, updated_at, disabled_at`;
+export const createPostgresPrincipalMemoryStore = (sql, options = {}) => {
+    const clock = options.clock ?? (() => new Date().toISOString());
+    return {
+        async put({ tenantId, principalId, id, text, tags, salience }) {
+            const now = clock();
+            // Version incremented and created_at preserved server-side, matching the reference adapter.
+            // Doing it in the statement means two concurrent puts on one id cannot both compute version 2.
+            const rows = await sql.query(`INSERT INTO principal_memory
+           (tenant_id, principal_id, id, text, tags, salience, version, created_at, updated_at)
+         VALUES ($1, $2, COALESCE($3, 'mem-' || nextval('blob_ref_seq')), $4, $5::jsonb, $6, 1,
+                 $7::timestamptz, $7::timestamptz)
+         ON CONFLICT (tenant_id, principal_id, id) DO UPDATE
+            SET text       = excluded.text,
+                tags       = excluded.tags,
+                salience   = excluded.salience,
+                version    = principal_memory.version + 1,
+                updated_at = excluded.updated_at
+         RETURNING ${MEMORY_COLUMNS}`, [
+                tenantId,
+                principalId,
+                id ?? null,
+                text,
+                JSON.stringify(tags ?? []),
+                salience ?? 1,
+                now,
+            ]);
+            const row = rows[0];
+            // Unreachable: the upsert always returns a row. Throwing rather than returning a fabricated
+            // entry, because a caller that thinks a memory was stored when it was not is worse than an error.
+            if (!row)
+                throw conflict(`Could not store memory for ${principalId}`);
+            return toEntry(row);
+        },
+        async get({ tenantId, principalId, id }) {
+            const rows = await sql.query(`SELECT ${MEMORY_COLUMNS} FROM principal_memory
+          WHERE tenant_id = $1 AND principal_id = $2 AND id = $3`, [tenantId, principalId, id]);
+            const row = rows[0];
+            return row ? toEntry(row) : null;
+        },
+        async list({ tenantId, principalId, limit, cursor }) {
+            // Keyset on (created_at, id): the cursor names a row, and paging resumes strictly after it, so
+            // a concurrent put cannot shift a page boundary the way an OFFSET would.
+            const rows = await sql.query(`WITH anchor AS (
+           SELECT created_at, id FROM principal_memory
+            WHERE tenant_id = $1 AND principal_id = $2 AND id = $3
+         )
+         SELECT ${MEMORY_COLUMNS} FROM principal_memory
+          WHERE tenant_id = $1 AND principal_id = $2
+            AND ($3::text IS NULL
+                 OR (created_at, id) > ((SELECT created_at FROM anchor), (SELECT id FROM anchor)))
+          ORDER BY created_at, id
+          LIMIT $4`, [tenantId, principalId, cursor ?? null, limit + 1]);
+            const hasMore = rows.length > limit;
+            const items = (hasMore ? rows.slice(0, limit) : rows).map(toEntry);
+            const last = items[items.length - 1];
+            const page = hasMore && last ? { items, nextCursor: last.id } : { items };
+            return page;
+        },
+        async update({ tenantId, principalId, id, expectedVersion, patch }) {
+            // The version guard is in the WHERE clause, so a stale write matches no row rather than
+            // overwriting a newer one. COALESCE leaves an omitted patch field untouched.
+            //
+            // `disabled` is three-valued on the way in: undefined leaves it alone, true stamps now, false
+            // clears it. Expressed as a CASE because COALESCE cannot distinguish "set to null" from "leave".
+            const rows = await sql.query(`UPDATE principal_memory
+            SET text        = COALESCE($5, text),
+                tags        = COALESCE($6::jsonb, tags),
+                salience    = COALESCE($7, salience),
+                disabled_at = CASE
+                                WHEN $8::boolean IS NULL THEN disabled_at
+                                WHEN $8::boolean THEN $9::timestamptz
+                                ELSE NULL
+                              END,
+                version     = version + 1,
+                updated_at  = $9::timestamptz
+          WHERE tenant_id = $1 AND principal_id = $2 AND id = $3 AND version = $4
+          RETURNING ${MEMORY_COLUMNS}`, [
+                tenantId,
+                principalId,
+                id,
+                expectedVersion,
+                patch.text ?? null,
+                patch.tags === undefined ? null : JSON.stringify(patch.tags),
+                patch.salience ?? null,
+                patch.disabled ?? null,
+                clock(),
+            ]);
+            const row = rows[0];
+            if (row)
+                return toEntry(row);
+            // No row: either it does not exist, or the version was stale. The distinction is the caller's
+            // next move — retry with a fresh read, versus stop.
+            const current = await this.get({ tenantId, principalId, id });
+            if (!current)
+                throw notFound(id);
+            throw conflict(`Memory ${id} version ${expectedVersion} is stale (current ${current.version})`);
+        },
+        async delete({ tenantId, principalId, id }) {
+            // Hard delete, as the port documents: a deleted entry cannot resurface in a later prompt. A
+            // soft delete would leave the text on disk after a user asked for it to be gone.
+            await sql.query(`DELETE FROM principal_memory WHERE tenant_id = $1 AND principal_id = $2 AND id = $3`, [tenantId, principalId, id]);
+        },
+        async retrieve({ tenantId, principalId, query, limit }) {
+            const q = query?.trim();
+            // Active only, matched against text or any tag, most salient first.
+            //
+            // `strpos` on lowercased text, deliberately **not** `ILIKE '%' || $3 || '%'`. Binding the query
+            // as a parameter stops SQL injection but does nothing about `LIKE` metacharacters: a query of
+            // "%" would still be a wildcard and return every memory the principal has. The reference
+            // adapter uses `String.includes`, which is literal, so ILIKE also made the two adapters
+            // disagree. `strpos` is a literal substring search and matches `includes` exactly.
+            //
+            // Neither form can use an index for a leading-wildcard search, so nothing is lost by it — see
+            // the open question on #102 about whether substring matching is the intended semantics at all.
+            const rows = await sql.query(`SELECT ${MEMORY_COLUMNS} FROM principal_memory
+          WHERE tenant_id = $1
+            AND principal_id = $2
+            AND disabled_at IS NULL
+            AND ($3::text IS NULL
+                 OR strpos(lower(text), lower($3::text)) > 0
+                 OR EXISTS (
+                      SELECT 1 FROM jsonb_array_elements_text(tags) AS t(tag)
+                       WHERE strpos(lower(tag), lower($3::text)) > 0
+                    ))
+          ORDER BY salience DESC, created_at, id
+          LIMIT $4`, [tenantId, principalId, q === undefined || q === "" ? null : q, limit]);
+            return rows.map(toEntry);
+        },
+    };
+};
+/**
+ * The tool-output offload. Stores the **value**, because that is what the port does: `put(value)`
+ * returns a ref and `get(ref)` must hand the value back. The `blob_refs` metadata-and-pointer table
+ * the SPEC described cannot implement this — there is nothing in the port to fetch bytes with — and
+ * belongs to `FileMetadataStore` (#129) or `ArtifactStore` (#133) instead.
+ */
+export const createPostgresBlobStore = (sql) => ({
+    async put({ tenantId, value }) {
+        // The ref is generated in-statement from a sequence, so it is durable and unique without a
+        // read-then-write. The reference adapter's process-local counter would, after a restart, hand out
+        // a ref that already belongs to someone else's value.
+        const rows = await sql.query(`INSERT INTO blobs (tenant_id, ref, value)
+       VALUES ($1, 'blob:' || $1 || ':' || nextval('blob_ref_seq'), $2::jsonb)
+       RETURNING ref`, [tenantId, JSON.stringify(value ?? null)]);
+        const row = rows[0];
+        if (!row)
+            throw conflict(`Could not store a blob for ${tenantId}`);
+        return asId(row.ref);
+    },
+    async get({ tenantId, ref }) {
+        // Tenant-scoped by primary key, so a ref from one tenant cannot resolve another's value even if
+        // it is guessed or leaked — the port's docstring calls that out specifically.
+        const rows = await sql.query(`SELECT value FROM blobs WHERE tenant_id = $1 AND ref = $2`, [tenantId, ref]);
+        const row = rows[0];
+        return row === undefined ? null : json(row.value);
+    },
+});
+//# sourceMappingURL=memory.js.map

package/dist/adapters/postgres/message-store.d.ts

@@ -0,0 +1,11 @@
+import type { AgentManifest } from "../../agents/index.js";
+import type { MessageId, RunId, TenantId } from "../../core/ids.js";
+import type { AgentStore, ConversationBindingStore, MessageStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresMessageStore: (sql: SqlExecutor) => MessageStore;
+export declare const createPostgresAgentStore: (sql: SqlExecutor) => AgentStore & {
+    put(tenantId: string, manifest: AgentManifest): Promise<void>;
+};
+export declare const createPostgresConversationBindingStore: (sql: SqlExecutor) => ConversationBindingStore;
+export type { MessageId, RunId, TenantId };
+//# sourceMappingURL=message-store.d.ts.map

package/dist/adapters/postgres/message-store.js

@@ -0,0 +1,145 @@
+/**
+ * PostgreSQL `MessageStore`, `AgentStore` and `ConversationBindingStore` (#96) — the stores that make
+ * a conversation durable rather than a thing that exists until the next deploy.
+ *
+ * Paging uses the same `(created_at, id)` composite cursor as `createPostgresConversationStore`. That
+ * pairing is the whole of AC-2: a timestamp alone lets a concurrently-inserted row sharing the same
+ * `created_at` slip between pages, and `OFFSET` shifts every subsequent page when a row lands early.
+ * The `id` tiebreak plus a keyset comparison makes the sequence stable while the conversation is
+ * still being written to.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { parseMessagePart } from "../../core/validation.js";
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const invalid = (message) => new AgentPlatformError({ code: "invalid_input", message, retryable: false });
+/**
+ * Validate on read. A hand-edited or half-migrated `parts` column otherwise flows into a client's
+ * stream, where the failure surfaces far from its cause — so the error names the message that carries
+ * the bad payload (AC-5).
+ */
+const toMessage = (r) => {
+    const stored = typeof r.parts === "string" ? JSON.parse(r.parts) : r.parts;
+    if (!Array.isArray(stored))
+        throw invalid(`Message ${r.id} has a non-array parts column`);
+    // There is no whole-message validator, so each part goes through `parseMessagePart`. Wrapping the
+    // failure keeps the message id in the error — otherwise a bad row reports only "invalid part" and
+    // leaves you grepping a table for it (AC-5).
+    let parts;
+    try {
+        parts = stored.map(parseMessagePart);
+    }
+    catch (cause) {
+        throw invalid(`Message ${r.id} has an invalid stored part: ${cause.message}`);
+    }
+    return {
+        id: r.id,
+        conversationId: r.conversation_id,
+        ...(r.run_id === null ? {} : { runId: r.run_id }),
+        role: r.role,
+        parts,
+        createdAt: iso(r.created_at),
+    };
+};
+const encodeCursor = (r) => Buffer.from(JSON.stringify({ c: iso(r.created_at), i: r.id })).toString("base64");
+const decodeCursor = (cursor) => JSON.parse(Buffer.from(cursor, "base64").toString("utf8"));
+export const createPostgresMessageStore = (sql) => ({
+    /**
+     * On the port as of #157, no longer a "test-only affordance".
+     *
+     * The signature changed from `(tenantId, message)` to the object form every other port method uses — a
+     * positional pair was the shape a test-only helper could get away with, and it is the wrong shape for
+     * something callers depend on.
+     *
+     * Messages stay immutable: `DO NOTHING` on conflict, no update, no delete. Editing one would rewrite history a
+     * client has already streamed and a model has already been shown, and a repeat of the same id is a retry
+     * rather than an error.
+     */
+    async append({ tenantId, message }) {
+        await sql.query(`INSERT INTO messages (tenant_id, id, conversation_id, run_id, role, parts, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7::timestamptz)
+       ON CONFLICT (tenant_id, id) DO NOTHING`, [
+            tenantId,
+            message.id,
+            message.conversationId,
+            message.runId ?? null,
+            message.role,
+            JSON.stringify(message.parts),
+            message.createdAt,
+        ]);
+    },
+    async findById({ tenantId, id }) {
+        const rows = await sql.query(`SELECT * FROM messages WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toMessage(row) : null;
+    },
+    async listByConversation({ tenantId, conversationId, limit, cursor, newestFirst }) {
+        const params = [tenantId, conversationId, limit + 1];
+        let where = `tenant_id = $1 AND conversation_id = $2`;
+        // The comparator and the sort flip together — #167. Split apart they produce a page that scans one way and
+        // pages the other, which returns rows before the cursor and looks like duplicates.
+        const descending = newestFirst === true;
+        if (cursor) {
+            const { c, i } = decodeCursor(cursor);
+            // Keyset, not OFFSET: strictly past (created_at, id) in the direction being read, so an insert landing
+            // earlier in the ordering cannot shift this page or duplicate a row into the next one.
+            where += descending
+                ? ` AND (created_at, id) < ($4::timestamptz, $5)`
+                : ` AND (created_at, id) > ($4::timestamptz, $5)`;
+            params.push(c, i);
+        }
+        const rows = await sql.query(`SELECT * FROM messages WHERE ${where}
+       ORDER BY created_at ${descending ? "DESC" : "ASC"}, id ${descending ? "DESC" : "ASC"}
+       LIMIT $3`, params);
+        const hasMore = rows.length > limit;
+        const items = (hasMore ? rows.slice(0, limit) : rows).map(toMessage);
+        const last = hasMore ? rows[limit - 1] : undefined;
+        const page = last ? { items, nextCursor: encodeCursor(last) } : { items };
+        return page;
+    },
+});
+export const createPostgresAgentStore = (sql) => ({
+    async put(tenantId, manifest) {
+        await sql.query(`INSERT INTO agents (tenant_id, id, version, manifest, created_at, updated_at)
+       VALUES ($1, $2, $3, $4::jsonb, now(), now())
+       ON CONFLICT (tenant_id, id, version) DO UPDATE
+          SET manifest = excluded.manifest, updated_at = now()`, [tenantId, manifest.id, manifest.version, JSON.stringify(manifest)]);
+    },
+    async findByVersion({ tenantId, agentId, version }) {
+        // Tenant-scoped, unlike the in-memory adapter before #91 fixed it: a manifest is owned by the
+        // tenant that registered it, and the key leads with tenant_id so a cross-tenant read is a miss.
+        const rows = await sql.query(`SELECT manifest FROM agents WHERE tenant_id = $1 AND id = $2 AND version = $3`, [tenantId, agentId, version]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        return (typeof row.manifest === "string" ? JSON.parse(row.manifest) : row.manifest);
+    },
+});
+const toBinding = (r) => ({
+    conversationId: r.conversation_id,
+    agentId: r.agent_id,
+    agentVersionPolicy: r.agent_version_policy,
+    // Absent rather than null for a `latest` binding: the type makes it optional, and a null here
+    // would round-trip as a present-but-empty version.
+    ...(r.agent_version === null ? {} : { agentVersion: r.agent_version }),
+});
+export const createPostgresConversationBindingStore = (sql) => ({
+    async bind({ tenantId, conversationId, agentId, agentVersionPolicy, agentVersion }) {
+        // Idempotent by conversation: re-binding is a legitimate operation (an agent upgrade), not a
+        // conflict, so the last write wins rather than erroring.
+        await sql.query(`INSERT INTO conversation_bindings
+         (tenant_id, conversation_id, agent_id, agent_version_policy, agent_version, bound_at)
+       VALUES ($1, $2, $3, $4, $5, now())
+       ON CONFLICT (tenant_id, conversation_id) DO UPDATE
+          SET agent_id             = excluded.agent_id,
+              agent_version_policy = excluded.agent_version_policy,
+              agent_version        = excluded.agent_version,
+              bound_at             = excluded.bound_at`, [tenantId, conversationId, agentId, agentVersionPolicy, agentVersion ?? null]);
+    },
+    async get({ tenantId, conversationId }) {
+        const rows = await sql.query(`SELECT conversation_id, agent_id, agent_version_policy, agent_version
+         FROM conversation_bindings WHERE tenant_id = $1 AND conversation_id = $2`, [tenantId, conversationId]);
+        const row = rows[0];
+        return row ? toBinding(row) : null;
+    },
+});
+//# sourceMappingURL=message-store.js.map