@retinue/agentkit 0.1.0

package/dist/adapters/postgres/flows.js

@@ -0,0 +1,206 @@
+/**
+ * Flow definitions and executions in Postgres — #187, #186.
+ *
+ * Two things are enforced by the schema rather than by this file, because a rule in code is a rule one code path
+ * can miss:
+ *
+ * - **A version cannot be overwritten.** `(tenant_id, flow_id, version)` is the primary key and the insert has no
+ *   `ON CONFLICT`, so a second write of the same version is a constraint violation. An execution pins a version
+ *   and reads it for its whole life; a definition that could change under it would change an automation's shape
+ *   halfway through.
+ * - **A save cannot move an execution backwards.** The update carries `WHERE steps <= $n`, so a stale document
+ *   from a slower worker updates nothing. A flow that goes backwards re-performs external writes, which is the
+ *   failure the whole module exists to prevent — and doing it in the `WHERE` means two concurrent saves are
+ *   ordered by the database rather than by whichever read happened first.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const int = (value) => (typeof value === "number" ? value : Number.parseInt(value, 10));
+const iso = (value) => (value instanceof Date ? value.toISOString() : value);
+const toDefinition = (row) => ({
+    flowId: row.flow_id,
+    version: int(row.version),
+    name: row.name,
+    kind: row.kind === "team" ? "team" : "flow",
+    // `jsonb` comes back parsed from `pg`, and as a string from some executors. Handling both means the adapter
+    // works under PGlite and a pool without a second code path for "which driver is this".
+    definition: typeof row.definition === "string" ? JSON.parse(row.definition) : row.definition,
+    createdAt: iso(row.created_at),
+    ...(row.created_by === null ? {} : { createdBy: row.created_by }),
+});
+const take = (limit) => Math.max(1, Math.min(limit ?? 50, 500));
+export const createPostgresFlowDefinitionStore = (sql) => ({
+    async put({ tenantId, definition }) {
+        try {
+            await sql.query(`INSERT INTO flow_definitions (tenant_id, flow_id, version, name, kind, definition, created_at, created_by)
+         VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7::timestamptz, $8)`, [
+                tenantId,
+                definition.flowId,
+                definition.version,
+                definition.name,
+                definition.kind,
+                JSON.stringify(definition.definition),
+                definition.createdAt,
+                definition.createdBy ?? null,
+            ]);
+        }
+        catch (error) {
+            /**
+             * Translated, not passed through.
+             *
+             * The port's contract is that overwriting a version is refused; a caller should not have to recognise a
+             * Postgres unique-violation code to know that happened. Anything else is rethrown, because swallowing an
+             * unrelated failure here would report a conflict for a disk that is full.
+             */
+            const code = error.code;
+            if (code === "23505" || /duplicate key|unique/i.test(String(error.message))) {
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `${definition.flowId} version ${definition.version} already exists — publish a new version instead`,
+                    retryable: false,
+                });
+            }
+            throw error;
+        }
+    },
+    async get({ tenantId, flowId, version }) {
+        const rows = await sql.query(`SELECT flow_id, version, name, kind, definition, created_at, created_by
+         FROM flow_definitions WHERE tenant_id = $1 AND flow_id = $2 AND version = $3`, [tenantId, flowId, version]);
+        return rows[0] === undefined ? null : toDefinition(rows[0]);
+    },
+    async latest({ tenantId, flowId }) {
+        const rows = await sql.query(`SELECT flow_id, version, name, kind, definition, created_at, created_by
+         FROM flow_definitions WHERE tenant_id = $1 AND flow_id = $2
+         ORDER BY version DESC LIMIT 1`, [tenantId, flowId]);
+        return rows[0] === undefined ? null : toDefinition(rows[0]);
+    },
+    async list({ tenantId, limit, cursor }) {
+        const size = take(limit);
+        /**
+         * The latest version per flow, in one query.
+         *
+         * `DISTINCT ON` rather than a window function or a join against a grouped subquery: it is the shortest
+         * statement that says "one row per flow_id, the highest version", and a caller asking what flows exist means
+         * distinct flows rather than every version of every one.
+         */
+        const rows = await sql.query(`SELECT * FROM (
+         SELECT DISTINCT ON (flow_id) flow_id, version, name, kind, definition, created_at, created_by
+           FROM flow_definitions WHERE tenant_id = $1
+           ORDER BY flow_id, version DESC
+       ) latest
+       WHERE ($2::text IS NULL OR flow_id > $2)
+       ORDER BY flow_id
+       LIMIT $3`, [tenantId, cursor ?? null, size + 1]);
+        const page = rows.slice(0, size).map(toDefinition);
+        return {
+            items: page,
+            ...(rows.length > size && page.length > 0 ? { nextCursor: page[page.length - 1].flowId } : {}),
+        };
+    },
+});
+const toExecution = (row) => ({
+    id: row.id,
+    flowId: row.flow_id,
+    flowVersion: int(row.flow_version),
+    runId: row.run_id,
+    status: row.status,
+    currentStep: row.current_step,
+    steps: int(row.steps),
+    execution: typeof row.execution === "string" ? JSON.parse(row.execution) : row.execution,
+    ...(row.waiting_signal === null ? {} : { waitingSignal: row.waiting_signal }),
+    ...(row.waiting_run_id === null ? {} : { waitingRunId: row.waiting_run_id }),
+    startedAt: iso(row.started_at),
+    ...(row.finished_at === null ? {} : { finishedAt: iso(row.finished_at) }),
+});
+const EXECUTION_COLUMNS = `id, flow_id, flow_version, run_id, status, current_step, steps, execution,
+         waiting_signal, waiting_run_id, started_at, finished_at`;
+export const createPostgresFlowExecutionStore = (sql) => ({
+    async create({ tenantId, execution }) {
+        try {
+            await sql.query(`INSERT INTO flow_executions
+           (tenant_id, id, flow_id, flow_version, run_id, status, current_step, steps, execution,
+            waiting_signal, waiting_run_id, started_at, finished_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12::timestamptz, $13::timestamptz)`, [
+                tenantId,
+                execution.id,
+                execution.flowId,
+                execution.flowVersion,
+                execution.runId,
+                execution.status,
+                execution.currentStep,
+                execution.steps,
+                JSON.stringify(execution.execution),
+                execution.waitingSignal ?? null,
+                execution.waitingRunId ?? null,
+                execution.startedAt,
+                execution.finishedAt ?? null,
+            ]);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "23505" || /duplicate key|unique/i.test(String(error.message))) {
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `flow execution ${execution.id} already exists`,
+                    retryable: false,
+                });
+            }
+            throw error;
+        }
+    },
+    async save({ tenantId, execution }) {
+        /**
+         * `steps <= $8` in the predicate, so the database orders two concurrent saves.
+         *
+         * `<=` and not `<`: parking on a question completes no step, so an equal count is a legitimate status change.
+         * Rejecting it would make "waiting" unrecordable, which is a whole class of state that could never be stored.
+         */
+        await sql.query(`UPDATE flow_executions
+          SET status = $3, current_step = $4, steps = $5, execution = $6::jsonb,
+              waiting_signal = $7, waiting_run_id = $10, finished_at = $9::timestamptz
+        WHERE tenant_id = $1 AND id = $2 AND steps <= $8`, [
+            tenantId,
+            execution.id,
+            execution.status,
+            execution.currentStep,
+            execution.steps,
+            JSON.stringify(execution.execution),
+            execution.waitingSignal ?? null,
+            execution.steps,
+            execution.finishedAt ?? null,
+            execution.waitingRunId ?? null,
+        ]);
+    },
+    async get({ tenantId, executionId }) {
+        const rows = await sql.query(`SELECT ${EXECUTION_COLUMNS} FROM flow_executions WHERE tenant_id = $1 AND id = $2`, [tenantId, executionId]);
+        return rows[0] === undefined ? null : toExecution(rows[0]);
+    },
+    async waitingOnSignal({ tenantId, signal, limit }) {
+        // `status = 'waiting'` in the predicate, not only the signal: a signal must not resume an execution that
+        // never asked for it, and a stale `waiting_signal` on a running row is exactly that.
+        const rows = await sql.query(`SELECT ${EXECUTION_COLUMNS} FROM flow_executions
+        WHERE tenant_id = $1 AND status = 'waiting' AND waiting_signal = $2
+        ORDER BY started_at LIMIT $3`, [tenantId, signal, take(limit)]);
+        return rows.map(toExecution);
+    },
+    async waitingOnRun({ tenantId, runId }) {
+        // `status = 'waiting'` as well as the id: a stale `waiting_run_id` on a running execution is not something a
+        // settled run should resume, because it is not waiting for one.
+        const rows = await sql.query(`SELECT ${EXECUTION_COLUMNS} FROM flow_executions
+        WHERE tenant_id = $1 AND status = 'waiting' AND waiting_run_id = $2
+        LIMIT 1`, [tenantId, runId]);
+        return rows[0] === undefined ? null : toExecution(rows[0]);
+    },
+    async listByFlow({ tenantId, flowId, limit, cursor }) {
+        const size = take(limit);
+        const rows = await sql.query(`SELECT ${EXECUTION_COLUMNS} FROM flow_executions
+        WHERE tenant_id = $1 AND flow_id = $2 AND ($3::text IS NULL OR id > $3)
+        ORDER BY started_at DESC, id
+        LIMIT $4`, [tenantId, flowId, cursor ?? null, size + 1]);
+        const page = rows.slice(0, size).map(toExecution);
+        return {
+            items: page,
+            ...(rows.length > size && page.length > 0 ? { nextCursor: page[page.length - 1].id } : {}),
+        };
+    },
+});
+//# sourceMappingURL=flows.js.map

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

@@ -0,0 +1,5 @@
+import type { ApprovalGrantStore, InteractionStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresInteractionStore: (sql: SqlExecutor) => InteractionStore;
+export declare const createPostgresApprovalGrantStore: (sql: SqlExecutor) => ApprovalGrantStore;
+//# sourceMappingURL=hitl.d.ts.map

package/dist/adapters/postgres/hitl.js

@@ -0,0 +1,247 @@
+/**
+ * PostgreSQL `InteractionStore` and `ApprovalGrantStore` (#99) — durable questions, approvals and
+ * standing grants.
+ *
+ * Approvals gate every external write, so the two failure modes are asymmetric but both bad: a lost
+ * approval blocks the work forever, and a *replayed* one authorises the same side effect twice — a
+ * duplicate publish, a duplicate charge. The second is why `idempotency_key` carries a unique index
+ * and why resolution is a compare-and-set rather than a read-then-write.
+ *
+ * **Resolution is guarded in the statement.** `UPDATE … WHERE answered_at IS NULL RETURNING *`: zero
+ * rows means someone already resolved it, so the store reads back to distinguish "already resolved"
+ * from "no such interaction". A read-then-write would let two concurrent answers both report
+ * `alreadyResolved: false`, and the harness is explicit about what that costs — the continuation gets
+ * queued twice.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Interaction ${id} not found`, retryable: false });
+const iso = (v) => (v instanceof Date ? v.toISOString() : new Date(v).toISOString());
+const isoOrUndefined = (v) => (v === null ? undefined : iso(v));
+/** jsonb arrives parsed from PGlite and as text from some drivers; normalise both. */
+const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const toQuestion = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    runId: r.run_id,
+    questions: json(r.questions),
+    createdAt: iso(r.created_at),
+    // Spread-in rather than assigned: the type marks both optional, and writing `answeredAt: undefined`
+    // would put the key in the object with an undefined value, which `toEqual` treats differently.
+    ...(r.answered_at === null ? {} : { answeredAt: iso(r.answered_at) }),
+    ...(r.answers === null || r.answers === undefined
+        ? {}
+        : { answers: json(r.answers) }),
+});
+const QUESTION_COLUMNS = `tenant_id, id, run_id, questions, created_at, answered_at, answers`;
+const toApproval = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    runId: r.run_id,
+    toolName: r.tool_name,
+    normalizedInput: json(r.normalized_input),
+    riskCategory: r.risk_category,
+    summary: r.summary,
+    ...(r.estimated_cost_minor_units === null
+        ? {}
+        : { estimatedCostMinorUnits: r.estimated_cost_minor_units }),
+    expiresAt: iso(r.expires_at),
+    idempotencyKey: r.idempotency_key,
+    ...(r.decided_at === null ? {} : { decidedAt: iso(r.decided_at) }),
+    ...(r.decision === null ? {} : { decision: r.decision }),
+    ...(r.consumed_at === null ? {} : { consumedAt: iso(r.consumed_at) }),
+});
+const APPROVAL_COLUMNS = `tenant_id, id, run_id, tool_name, normalized_input, risk_category, summary,
+         estimated_cost_minor_units, expires_at, idempotency_key, decided_at, decision, consumed_at`;
+export const createPostgresInteractionStore = (sql) => {
+    const readQuestion = async (tenantId, id) => {
+        const rows = await sql.query(`SELECT ${QUESTION_COLUMNS} FROM interaction_questions WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toQuestion(row) : null;
+    };
+    const readApproval = async (tenantId, id) => {
+        const rows = await sql.query(`SELECT ${APPROVAL_COLUMNS} FROM interaction_approvals WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        const row = rows[0];
+        return row ? toApproval(row) : null;
+    };
+    return {
+        async createQuestion({ tenantId, question }) {
+            await sql.query(`INSERT INTO interaction_questions (tenant_id, id, run_id, questions, created_at, answered_at, answers)
+         VALUES ($1, $2, $3, $4::jsonb, $5::timestamptz, $6::timestamptz, $7::jsonb)
+         ON CONFLICT (tenant_id, id) DO NOTHING`, [
+                tenantId,
+                question.id,
+                question.runId,
+                JSON.stringify(question.questions),
+                question.createdAt,
+                question.answeredAt ?? null,
+                question.answers === undefined ? null : JSON.stringify(question.answers),
+            ]);
+        },
+        async findPendingQuestion({ tenantId, runId }) {
+            const rows = await sql.query(`SELECT ${QUESTION_COLUMNS} FROM interaction_questions
+          WHERE tenant_id = $1 AND run_id = $2 AND answered_at IS NULL
+          ORDER BY created_at, id
+          LIMIT 1`, [tenantId, runId]);
+            const row = rows[0];
+            return row ? toQuestion(row) : null;
+        },
+        /**
+         * The newest answered question for the run — #163. Ordered by `answered_at` rather than `created_at`: a run
+         * that asked twice has both answered, and the one to tell the model about is the one just answered.
+         */
+        async findAnsweredQuestion({ tenantId, runId }) {
+            const rows = await sql.query(`SELECT ${QUESTION_COLUMNS} FROM interaction_questions
+          WHERE tenant_id = $1 AND run_id = $2 AND answered_at IS NOT NULL
+          ORDER BY answered_at DESC, id DESC
+          LIMIT 1`, [tenantId, runId]);
+            const row = rows[0];
+            return row ? toQuestion(row) : null;
+        },
+        async answerQuestion({ tenantId, interactionId, answers, at }) {
+            // The guard is `answered_at IS NULL`, so exactly one of two concurrent answers can win. The
+            // loser gets zero rows and reports alreadyResolved, which is what keeps the continuation from
+            // being queued twice.
+            const rows = await sql.query(`UPDATE interaction_questions
+            SET answered_at = $3::timestamptz, answers = $4::jsonb
+          WHERE tenant_id = $1 AND id = $2 AND answered_at IS NULL
+          RETURNING ${QUESTION_COLUMNS}`, [tenantId, interactionId, at, JSON.stringify(answers)]);
+            const row = rows[0];
+            if (row)
+                return { question: toQuestion(row), alreadyResolved: false };
+            const existing = await readQuestion(tenantId, interactionId);
+            if (!existing)
+                throw notFound(interactionId);
+            return { question: existing, alreadyResolved: true };
+        },
+        async createApproval({ tenantId, approval }) {
+            await sql.query(`INSERT INTO interaction_approvals
+           (tenant_id, id, run_id, tool_name, normalized_input, risk_category, summary,
+            estimated_cost_minor_units, expires_at, idempotency_key, decided_at, decision, consumed_at)
+         VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8, $9::timestamptz, $10, $11::timestamptz, $12,
+                 $13::timestamptz)
+         ON CONFLICT (tenant_id, id) DO NOTHING`, [
+                tenantId,
+                approval.id,
+                approval.runId,
+                approval.toolName,
+                JSON.stringify(approval.normalizedInput ?? null),
+                approval.riskCategory,
+                approval.summary,
+                approval.estimatedCostMinorUnits ?? null,
+                approval.expiresAt,
+                approval.idempotencyKey,
+                approval.decidedAt ?? null,
+                approval.decision ?? null,
+                approval.consumedAt ?? null,
+            ]);
+        },
+        async findPendingApproval({ tenantId, runId }) {
+            const rows = await sql.query(`SELECT ${APPROVAL_COLUMNS} FROM interaction_approvals
+          WHERE tenant_id = $1 AND run_id = $2 AND decided_at IS NULL
+          ORDER BY expires_at, id
+          LIMIT 1`, [tenantId, runId]);
+            const row = rows[0];
+            return row ? toApproval(row) : null;
+        },
+        async decideApproval({ tenantId, interactionId, decision, at }) {
+            // AC-5 lives here: a denied approval can never become granted, because the second decision
+            // matches no row and the store returns the stored one unchanged.
+            const rows = await sql.query(`UPDATE interaction_approvals
+            SET decided_at = $3::timestamptz, decision = $4
+          WHERE tenant_id = $1 AND id = $2 AND decided_at IS NULL
+          RETURNING ${APPROVAL_COLUMNS}`, [tenantId, interactionId, at, decision]);
+            const row = rows[0];
+            if (row)
+                return { approval: toApproval(row), alreadyResolved: false };
+            const existing = await readApproval(tenantId, interactionId);
+            if (!existing)
+                throw notFound(interactionId);
+            return { approval: existing, alreadyResolved: true };
+        },
+        async findApproval({ tenantId, interactionId }) {
+            return readApproval(tenantId, interactionId);
+        },
+        async findDecidedApproval({ tenantId, runId }) {
+            const rows = await sql.query(`SELECT ${APPROVAL_COLUMNS} FROM interaction_approvals
+          WHERE tenant_id = $1 AND run_id = $2 AND decided_at IS NOT NULL AND consumed_at IS NULL
+          ORDER BY decided_at, id
+          LIMIT 1`, [tenantId, runId]);
+            const row = rows[0];
+            return row ? toApproval(row) : null;
+        },
+        async claimApproval({ tenantId, interactionId, at }) {
+            // The whole of `allow-once` is this WHERE clause. `consumed_at IS NULL` is what makes the claim
+            // exclusive under concurrency, and `decided_at IS NOT NULL` is what stops an undecided
+            // interaction from being claimable at all — an unwired dependency must never become permission.
+            const rows = await sql.query(`UPDATE interaction_approvals
+            SET consumed_at = $3::timestamptz
+          WHERE tenant_id = $1 AND id = $2 AND decided_at IS NOT NULL AND consumed_at IS NULL
+          RETURNING ${APPROVAL_COLUMNS}`, [tenantId, interactionId, at]);
+            const row = rows[0];
+            if (row)
+                return { approval: toApproval(row), claimed: true };
+            const existing = await readApproval(tenantId, interactionId);
+            if (!existing)
+                throw notFound(interactionId);
+            return { approval: existing, claimed: false };
+        },
+    };
+};
+const toGrant = (r) => ({
+    id: r.id,
+    tenantId: r.tenant_id,
+    scope: r.scope,
+    toolNameOrCategory: r.tool_name_or_category,
+    ...(r.conversation_id === null ? {} : { conversationId: r.conversation_id }),
+    grantedAt: iso(r.granted_at),
+    ...(isoOrUndefined(r.expires_at) === undefined ? {} : { expiresAt: iso(r.expires_at) }),
+    ...(isoOrUndefined(r.revoked_at) === undefined ? {} : { revokedAt: iso(r.revoked_at) }),
+});
+const GRANT_COLUMNS = `tenant_id, id, scope, tool_name_or_category, conversation_id,
+         granted_at, expires_at, revoked_at`;
+export const createPostgresApprovalGrantStore = (sql) => ({
+    async grant({ tenantId, grant }) {
+        await sql.query(`INSERT INTO approval_grants
+         (tenant_id, id, scope, tool_name_or_category, conversation_id, granted_at, expires_at, revoked_at)
+       VALUES ($1, $2, $3, $4, $5, $6::timestamptz, $7::timestamptz, $8::timestamptz)
+       ON CONFLICT (tenant_id, id) DO UPDATE
+          SET scope = excluded.scope,
+              tool_name_or_category = excluded.tool_name_or_category,
+              conversation_id = excluded.conversation_id,
+              granted_at = excluded.granted_at,
+              expires_at = excluded.expires_at,
+              revoked_at = excluded.revoked_at`, [
+            tenantId,
+            grant.id,
+            grant.scope,
+            grant.toolNameOrCategory,
+            grant.conversationId ?? null,
+            grant.grantedAt,
+            grant.expiresAt ?? null,
+            grant.revokedAt ?? null,
+        ]);
+    },
+    async findActive({ tenantId, toolNameOrCategory, now, conversationId }) {
+        // The scope predicate is the safety-critical part. A conversation-scoped grant must match only
+        // its own conversation and must not match at all when no conversation is supplied — otherwise a
+        // one-conversation approval silently becomes a standing one. Expressed as SQL rather than
+        // filtered afterwards so the index can serve it and no code path can skip it.
+        const rows = await sql.query(`SELECT ${GRANT_COLUMNS} FROM approval_grants
+        WHERE tenant_id = $1
+          AND tool_name_or_category = $2
+          AND revoked_at IS NULL
+          AND (expires_at IS NULL OR expires_at > $3::timestamptz)
+          AND (scope <> 'conversation' OR ($4::text IS NOT NULL AND conversation_id = $4::text))
+        ORDER BY granted_at DESC, id
+        LIMIT 1`, [tenantId, toolNameOrCategory, now, conversationId ?? null]);
+        const row = rows[0];
+        return row ? toGrant(row) : null;
+    },
+    async revoke({ tenantId, grantId, at }) {
+        // Silent on a missing grant, matching the reference adapter: revoking something that is not there
+        // has already achieved its purpose, and throwing would make idempotent revocation impossible.
+        await sql.query(`UPDATE approval_grants SET revoked_at = $3::timestamptz
+        WHERE tenant_id = $1 AND id = $2 AND revoked_at IS NULL`, [tenantId, grantId, at]);
+    },
+});
+//# sourceMappingURL=hitl.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * PostgreSQL adapters — the production reference storage. Implements the storage ports over a
+ * `SqlExecutor`; verified by the shared conformance harness.
+ */
+import type { AdapterCapability } from "../../persistence/index.js";
+export * from "./sql.js";
+export * from "./migrations.js";
+export * from "./schema.js";
+export * from "./conversation-store.js";
+export * from "./run-store.js";
+export * from "./run-event-log.js";
+export * from "./checkpoint-store.js";
+export * from "./message-store.js";
+export * from "./session-state.js";
+export * from "./transaction.js";
+export * from "./run-coordinator.js";
+export * from "./unit-of-work.js";
+export * from "./hitl.js";
+export * from "./usage.js";
+export * from "./usage-limits.js";
+export * from "./config.js";
+export * from "./memory.js";
+export * from "./pg-executor.js";
+/** Capabilities a PostgreSQL deployment can advertise (docs/02 capability declarations). */
+export declare const POSTGRES_CAPABILITIES: readonly AdapterCapability[];
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./rollups.js";
+export * from "./evaluation.js";
+export * from "./retention.js";
+export * from "./file-content.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/postgres/index.js

@@ -0,0 +1,35 @@
+export * from "./sql.js";
+export * from "./migrations.js";
+export * from "./schema.js";
+export * from "./conversation-store.js";
+export * from "./run-store.js";
+export * from "./run-event-log.js";
+export * from "./checkpoint-store.js";
+export * from "./message-store.js";
+export * from "./session-state.js";
+export * from "./transaction.js";
+export * from "./run-coordinator.js";
+export * from "./unit-of-work.js";
+export * from "./hitl.js";
+export * from "./usage.js";
+export * from "./usage-limits.js";
+export * from "./config.js";
+export * from "./memory.js";
+export * from "./pg-executor.js";
+/** Capabilities a PostgreSQL deployment can advertise (docs/02 capability declarations). */
+export const POSTGRES_CAPABILITIES = [
+    "transactions",
+    "row-level-security",
+    "full-text-search",
+    "distributed-locking",
+];
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./rollups.js";
+export * from "./evaluation.js";
+export * from "./retention.js";
+export * from "./file-content.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * 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 type { EmbeddingModelRef, KeywordIndex, KnowledgeStore, VectorIndex } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+/**
+ * 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 declare const toVectorLiteral: (embedding: readonly number[]) => string;
+export declare const createPostgresKnowledgeStore: (sql: SqlExecutor) => KnowledgeStore;
+export declare const createPostgresVectorIndex: (sql: SqlExecutor) => VectorIndex;
+/** Re-exported so a caller comparing a stored chunk's model to the current one does it the same way. */
+export declare const sameEmbeddingModel: (a: EmbeddingModelRef, b: EmbeddingModelRef) => boolean;
+/**
+ * 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 declare const createPostgresKeywordIndex: (sql: SqlExecutor) => KeywordIndex;
+//# sourceMappingURL=knowledge.d.ts.map