@retinue/agentkit 0.1.0 → 0.3.0

package/dist/adapters/postgres/migrations.js

@@ -1419,6 +1419,204 @@ export const MIGRATIONS = [
             `ALTER TABLE runs DROP COLUMN IF EXISTS input`,
         ],
     },
+    {
+        /**
+         * A tenant's connections to third-party providers — REQ-063 (#259), task #261.
+         *
+         * **Every secret column holds ciphertext.** The table is deliberately shaped so that only
+         * `secret_ciphertext` could ever contain one: the username of a basic credential, the header name of a
+         * custom-header one and every vendor identifier live in `metadata`, readable, because a connection list is
+         * a screen a person looks at and rendering it must not need a key.
+         *
+         * `key_id` is what makes rotation possible. A design without it has a first key that is permanent:
+         * re-sealing every row needs the old key, which a process that has retired it no longer has.
+         *
+         * `revoked_at` rather than a delete, because "who connected this and when was it removed" is a question a
+         * security review asks. `purge` is the one hard delete, and it exists for `docs/18`: a soft-deleted
+         * credential is still a credential, and "we kept it for the audit trail" is not an answer to "delete my
+         * data".
+         */
+        id: "0032_connections",
+        up: [
+            `CREATE TABLE IF NOT EXISTS connections (
+         tenant_id text NOT NULL,
+         id text NOT NULL,
+         provider text NOT NULL,
+         label text,
+         mode text NOT NULL,
+         scheme text NOT NULL,
+         metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+         granted_scopes text[],
+         secret_key_id text NOT NULL,
+         secret_algorithm text NOT NULL,
+         secret_nonce text NOT NULL,
+         secret_ciphertext text NOT NULL,
+         expires_at timestamptz,
+         created_at timestamptz NOT NULL DEFAULT now(),
+         updated_at timestamptz NOT NULL DEFAULT now(),
+         revoked_at timestamptz,
+         PRIMARY KEY (tenant_id, id)
+       )`,
+            // Listing a tenant's live connections for one provider is the hot path: it happens on every resolution
+            // of a bare `<provider>` ref.
+            `CREATE INDEX IF NOT EXISTS connections_tenant_provider_idx
+         ON connections (tenant_id, provider, created_at)
+         WHERE revoked_at IS NULL`,
+        ],
+        down: [`DROP TABLE IF EXISTS connections`],
+    },
+    {
+        /**
+         * A tenant's *own* OAuth app registration, in the same table — task #263.
+         *
+         * Same shape as a connection in every respect that matters: tenant-scoped, provider-keyed, one sealed
+         * secret, metadata beside it, revocable, and covered by the same retention promise. A discriminator rather
+         * than a second table means one cipher, one RLS policy, one retention path and one conformance suite.
+         *
+         * Defaulted to `'connection'`, so every existing row keeps meaning what it meant.
+         */
+        id: "0033_connection_kind",
+        up: [
+            `ALTER TABLE connections ADD COLUMN IF NOT EXISTS kind text NOT NULL DEFAULT 'connection'`,
+            // A tenant has at most one registered app per provider; two would make "which client issued this token"
+            // ambiguous, and #263's AC-4 turns on that question being answerable.
+            `CREATE UNIQUE INDEX IF NOT EXISTS connections_one_app_per_provider_idx
+         ON connections (tenant_id, provider)
+         WHERE kind = 'oauth-app' AND revoked_at IS NULL`,
+        ],
+        down: [
+            `DROP INDEX IF EXISTS connections_one_app_per_provider_idx`,
+            `ALTER TABLE connections DROP COLUMN IF EXISTS kind`,
+        ],
+    },
+    {
+        /**
+         * `waiting-for-connection` — the third pause, task #264.
+         *
+         * The CHECK constraint mirrors `RUN_STATUSES`, so a new status has to be added in **both** places or every
+         * write of it is rejected by the database. Found by `run-events-retention.test.ts`, which iterates every
+         * status and inserts one — a test that exists precisely so the two lists cannot drift apart silently.
+         *
+         * Dropped and recreated rather than altered: Postgres has no `ALTER CONSTRAINT` for a CHECK's expression,
+         * and `IF EXISTS`/`IF NOT EXISTS` keep both statements re-runnable, which `migrate` requires.
+         */
+        id: "0034_run_status_waiting_for_connection",
+        up: [
+            `ALTER TABLE runs DROP CONSTRAINT IF EXISTS runs_status_check`,
+            `ALTER TABLE runs ADD CONSTRAINT runs_status_check CHECK (status IN (
+         'queued', 'running', 'waiting-for-question', 'waiting-for-approval',
+         'waiting-for-connection', 'retry-pending', 'completed', 'failed', 'cancelled'
+       ))`,
+        ],
+        down: [
+            `ALTER TABLE runs DROP CONSTRAINT IF EXISTS runs_status_check`,
+            `ALTER TABLE runs ADD CONSTRAINT runs_status_check CHECK (status IN (
+         'queued', 'running', 'waiting-for-question', 'waiting-for-approval',
+         'retry-pending', 'completed', 'failed', 'cancelled'
+       ))`,
+        ],
+    },
+    {
+        /**
+         * The knowledge graph — REQ-064 (#270), task #271.
+         *
+         * In `MIGRATIONS` rather than beside the pgvector ones, because none of this needs the extension: entities
+         * and edges are ordinary rows, and the embeddings they were derived from live in `knowledge_chunks`. A
+         * deployment without pgvector can still run GraphRAG's `graph-local`, which is a real configuration.
+         *
+         * **Contributions are the stored truth; the merged rows are a cache.** `knowledge_graph_contributions`
+         * records what each source asserted, and the entity and relationship tables are rebuilt from it on write.
+         * That is what makes pruning correct with no reference counting: an entity exists exactly while some
+         * contribution names it, and re-indexing one document withdraws only that document's claims.
+         */
+        id: "0035_knowledge_graph",
+        up: [
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_settings (
+         tenant_id text PRIMARY KEY,
+         enabled boolean NOT NULL DEFAULT false,
+         updated_at timestamptz NOT NULL DEFAULT now()
+       )`,
+            // Stored independently of the tenant switch — a source marked while GraphRAG is off keeps its flag, so
+            // enabling the tenant later picks it up without re-marking anything.
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_sources (
+         tenant_id text NOT NULL,
+         source_type text NOT NULL,
+         source_id text NOT NULL,
+         enabled boolean NOT NULL DEFAULT false,
+         PRIMARY KEY (tenant_id, source_type, source_id)
+       )`,
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_contributions (
+         tenant_id text NOT NULL,
+         source_type text NOT NULL,
+         source_id text NOT NULL,
+         entities jsonb NOT NULL,
+         relationships jsonb NOT NULL,
+         updated_at timestamptz NOT NULL DEFAULT now(),
+         PRIMARY KEY (tenant_id, source_type, source_id)
+       )`,
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_entities (
+         tenant_id text NOT NULL,
+         id text NOT NULL,
+         name text NOT NULL,
+         type text NOT NULL,
+         description text,
+         surface_forms text[] NOT NULL,
+         provenance text[] NOT NULL,
+         PRIMARY KEY (tenant_id, id),
+         -- Provenance is structural, so the database says so too. A graph claim with no chunk behind it is one
+         -- the retriever would present as cited, and an application-level check is one a future writer skips.
+         CONSTRAINT knowledge_graph_entities_provenance CHECK (cardinality(provenance) > 0)
+       )`,
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_relationships (
+         tenant_id text NOT NULL,
+         id text NOT NULL,
+         from_id text NOT NULL,
+         to_id text NOT NULL,
+         type text NOT NULL,
+         description text,
+         weight integer NOT NULL DEFAULT 1,
+         provenance text[] NOT NULL,
+         PRIMARY KEY (tenant_id, id),
+         CONSTRAINT knowledge_graph_relationships_provenance CHECK (cardinality(provenance) > 0)
+       )`,
+            `CREATE INDEX IF NOT EXISTS knowledge_graph_entities_type_idx
+         ON knowledge_graph_entities (tenant_id, type)`,
+            // Traversal reads edges by either endpoint, so both directions are indexed. One index on `from_id` would
+            // make half of every neighbourhood query a sequential scan.
+            `CREATE INDEX IF NOT EXISTS knowledge_graph_relationships_from_idx
+         ON knowledge_graph_relationships (tenant_id, from_id)`,
+            `CREATE INDEX IF NOT EXISTS knowledge_graph_relationships_to_idx
+         ON knowledge_graph_relationships (tenant_id, to_id)`,
+            /*
+             * Communities — #272. `fingerprint` is what the cluster contains; `summary_fingerprint` is what the
+             * summary was written against. A community is stale exactly when they differ, which makes staleness a
+             * comparison rather than a timestamp somebody has to interpret.
+             */
+            `CREATE TABLE IF NOT EXISTS knowledge_graph_communities (
+         tenant_id text NOT NULL,
+         id text NOT NULL,
+         level integer NOT NULL,
+         entity_ids text[] NOT NULL,
+         relationship_ids text[] NOT NULL,
+         chunk_ids text[] NOT NULL,
+         fingerprint text NOT NULL,
+         summary text,
+         summary_fingerprint text,
+         summarised_at timestamptz,
+         PRIMARY KEY (tenant_id, id)
+       )`,
+            `CREATE INDEX IF NOT EXISTS knowledge_graph_communities_level_idx
+         ON knowledge_graph_communities (tenant_id, level, id)`,
+        ],
+        down: [
+            `DROP TABLE IF EXISTS knowledge_graph_communities`,
+            `DROP TABLE IF EXISTS knowledge_graph_relationships`,
+            `DROP TABLE IF EXISTS knowledge_graph_entities`,
+            `DROP TABLE IF EXISTS knowledge_graph_contributions`,
+            `DROP TABLE IF EXISTS knowledge_graph_sources`,
+            `DROP TABLE IF EXISTS knowledge_graph_settings`,
+        ],
+    },
 ];
 /**
  * pgvector migrations, applied separately (#135).

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

@@ -93,7 +93,19 @@ export const createPostgresRunStore = (sql) => {
          * A live lease held by *another* worker excludes the row; the current holder re-claiming is
          * allowed (idempotent re-entry after a transient failure).
          */
-        async claim({ tenantId, id, workerId, leaseMs, now }) {
+        async claim({ tenantId, id, workerId, leaseMs, now, maxConcurrent }) {
+            /**
+             * The per-tenant concurrency cap, **in the same statement as the claim** — #265.
+             *
+             * A correlated subquery rather than a count read beforehand, and that is the whole point. Reading the
+             * count and then updating is check-then-act across processes: two workers both read "3 of 4 used", both
+             * claim, and the tenant runs at 5. Inside the `WHERE`, the count is evaluated against the row versions
+             * this statement locks, so the two claims serialise and the second one's subquery sees the first.
+             *
+             * `id <> $2` keeps the run from counting against itself, so recovering an expired lease is never blocked
+             * by the limit it is trying to restore. A non-positive or absent limit is passed as NULL and the clause
+             * short-circuits to true.
+             */
             const rows = await sql.query(`UPDATE runs
             SET status           = 'running',
                 claimed_by       = $3,
@@ -109,10 +121,22 @@ export const createPostgresRunStore = (sql) => {
                  OR claimed_by = $3
                  OR lease_expires_at IS NULL
                  OR lease_expires_at <= $4::timestamptz)
-          RETURNING *`, [tenantId, id, workerId, now, String(leaseMs)]);
+            AND ($6::int IS NULL
+                 OR (SELECT count(*) FROM runs live
+                      WHERE live.tenant_id = $1
+                        AND live.id <> $2
+                        AND live.status = 'running'
+                        AND live.lease_expires_at > $4::timestamptz) < $6::int)
+          RETURNING *`, [tenantId, id, workerId, now, String(leaseMs), maxConcurrent !== undefined && maxConcurrent > 0 ? maxConcurrent : null]);
             const row = rows[0];
             return row ? toRun(row) : null;
         },
+        async countLive({ tenantId, now }) {
+            const rows = await sql.query(`SELECT count(*) AS live FROM runs
+          WHERE tenant_id = $1 AND status = 'running' AND lease_expires_at > $2::timestamptz`, [tenantId, now]);
+            // Postgres returns count() as bigint, which the driver hands back as a string.
+            return Number(rows[0]?.live ?? 0);
+        },
         /** False when the claim was lost (reaped or stolen) so the worker aborts rather than continuing. */
         async keepalive({ tenantId, id, workerId, leaseMs, now }) {
             const rows = await sql.query(`UPDATE runs

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

@@ -3,12 +3,55 @@
  *
  * A `SchemaManager` over the reversible migrations: it provisions a fresh database on startup
  * (`auto`), logs the diff and refuses (`plan`), or leaves the schema to managed migrations
- * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op,
- * so concurrent workers never double-provision.
+ * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op.
+ *
+ * **Concurrent callers do not double-provision, and one of them may still fail.** Measured for #252: two
+ * simultaneous `apply()` runs against one database leave the ledger correct (every migration recorded once,
+ * `ON CONFLICT DO NOTHING` doing its job) and crash the loser with
+ * `duplicate key value violates unique constraint "pg_type_typname_nsp_index"` — Postgres's own type catalogue,
+ * racing on DDL. The data is safe; the process is not, and the error names nothing an operator can act on.
+ *
+ * Both callers therefore take a **session advisory lock** on a single checked-out connection before applying:
+ * `retinue migrate` since #252, and `auto` mode at startup since #266. The callers serialise instead of racing.
+ *
+ * ## How the lock reaches a manager written against `SqlExecutor` — #266, AC-2
+ *
+ * It does not. `SqlExecutor` has only `query`, and a `pg_advisory_lock` taken through a pool-backed executor
+ * would be held by a connection nobody gets back — `pool.query` picks a different one per call, so the unlock
+ * would land on a different session and the lock would leak until the process exited.
+ *
+ * So `provisionSchema` takes an **optional `ConnectionOpener`** and builds the manager over the locked
+ * connection when it has one. Three options were weighed and this is why:
+ *
+ * - *Widen `SqlExecutor`* — rejected. Every adapter that will never need a session lock would have to answer
+ *   for one, and PGlite genuinely cannot.
+ * - *Lock in the host's boot path* — rejected as the primary mechanism, though `boot.ts` is where the opener
+ *   comes from. It puts the correctness of provisioning in the caller, so every future host has to remember,
+ *   and the one that forgets fails only under concurrency.
+ * - *An optional opener here* — chosen. The knowledge stays with the thing being protected, a caller that has
+ *   an opener is protected without asking, and a caller that has none behaves exactly as before.
+ *
+ * **A caller with no opener still works** (AC-3): PGlite and the in-memory paths are single-process, so there
+ * is nothing to serialise, and requiring a lock they cannot provide would be a new dependency for the one case
+ * that never needed it. The result reports which happened, so "unlocked" is visible rather than assumed.
  */
 import { type Migration } from "./migrations.js";
 import type { SqlExecutor } from "./sql.js";
+import type { ConnectionOpener } from "./transaction.js";
 export type SchemaMode = "auto" | "plan" | "off";
+/**
+ * The advisory-lock key migrations serialise on — #252, and #266's AC-4.
+ *
+ * **Exported and shared, rather than agreed.** The CLI defined this itself, which meant AC-4 — "the key matches
+ * the CLI's, or the two do not serialise against each other" — was a property of two constants happening to be
+ * equal. Two constants that must be equal are one constant; a copy that drifts produces two locks and no
+ * serialisation, and the symptom is the original crash returning with the fix apparently in place.
+ *
+ * Arbitrary, and it has to be: Postgres advisory locks are a flat 64-bit namespace with no registry, so the
+ * only protection against collision is picking something nobody else would. Derived from the ASCII of
+ * "retinue" so it is reproducible rather than a magic number somebody will tidy up.
+ */
+export declare const MIGRATION_LOCK = 125780070329973;
 export type SchemaChange = {
     readonly id: string;
     readonly statements: readonly string[];
@@ -26,6 +69,14 @@ export type ProvisionResult = {
     readonly mode: SchemaMode;
     readonly applied: readonly string[];
     readonly planned: readonly SchemaChange[];
+    /**
+     * Whether the apply was serialised by an advisory lock — #266.
+     *
+     * Reported so "unlocked" is a visible fact rather than an assumption. `false` is correct and expected for a
+     * single-process caller; on a pool-backed deployment it means the opener was not passed, which is the
+     * configuration mistake this field exists to make findable.
+     */
+    readonly locked: boolean;
 };
 /**
  * Startup provisioning per mode. `off` (Postgres default) leaves the schema to managed
@@ -35,5 +86,13 @@ export declare const provisionSchema: (sql: SqlExecutor, options?: {
     readonly mode?: SchemaMode;
     readonly log?: (message: string) => void;
     readonly migrations?: readonly Migration[];
+    /**
+     * Opens one connection and holds it — the primitive an advisory lock needs, and the one `SqlExecutor`
+     * deliberately does not have. See the header for why this is a parameter rather than a widened port.
+     *
+     * Optional: a single-process caller has nothing to serialise. Supplying it is what turns concurrent
+     * `auto`-mode provisioning from "one worker crashes" into "one applies, the rest find nothing to do".
+     */
+    readonly open?: ConnectionOpener;
 }) => Promise<ProvisionResult>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/adapters/postgres/schema.js

@@ -3,10 +3,52 @@
  *
  * A `SchemaManager` over the reversible migrations: it provisions a fresh database on startup
  * (`auto`), logs the diff and refuses (`plan`), or leaves the schema to managed migrations
- * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op,
- * so concurrent workers never double-provision.
+ * (`off`, the default for Postgres). Forward-only and idempotent — running it twice is a no-op.
+ *
+ * **Concurrent callers do not double-provision, and one of them may still fail.** Measured for #252: two
+ * simultaneous `apply()` runs against one database leave the ledger correct (every migration recorded once,
+ * `ON CONFLICT DO NOTHING` doing its job) and crash the loser with
+ * `duplicate key value violates unique constraint "pg_type_typname_nsp_index"` — Postgres's own type catalogue,
+ * racing on DDL. The data is safe; the process is not, and the error names nothing an operator can act on.
+ *
+ * Both callers therefore take a **session advisory lock** on a single checked-out connection before applying:
+ * `retinue migrate` since #252, and `auto` mode at startup since #266. The callers serialise instead of racing.
+ *
+ * ## How the lock reaches a manager written against `SqlExecutor` — #266, AC-2
+ *
+ * It does not. `SqlExecutor` has only `query`, and a `pg_advisory_lock` taken through a pool-backed executor
+ * would be held by a connection nobody gets back — `pool.query` picks a different one per call, so the unlock
+ * would land on a different session and the lock would leak until the process exited.
+ *
+ * So `provisionSchema` takes an **optional `ConnectionOpener`** and builds the manager over the locked
+ * connection when it has one. Three options were weighed and this is why:
+ *
+ * - *Widen `SqlExecutor`* — rejected. Every adapter that will never need a session lock would have to answer
+ *   for one, and PGlite genuinely cannot.
+ * - *Lock in the host's boot path* — rejected as the primary mechanism, though `boot.ts` is where the opener
+ *   comes from. It puts the correctness of provisioning in the caller, so every future host has to remember,
+ *   and the one that forgets fails only under concurrency.
+ * - *An optional opener here* — chosen. The knowledge stays with the thing being protected, a caller that has
+ *   an opener is protected without asking, and a caller that has none behaves exactly as before.
+ *
+ * **A caller with no opener still works** (AC-3): PGlite and the in-memory paths are single-process, so there
+ * is nothing to serialise, and requiring a lock they cannot provide would be a new dependency for the one case
+ * that never needed it. The result reports which happened, so "unlocked" is visible rather than assumed.
  */
 import { MIGRATION_LEDGER, MIGRATIONS, appliedMigrationIds } from "./migrations.js";
+/**
+ * The advisory-lock key migrations serialise on — #252, and #266's AC-4.
+ *
+ * **Exported and shared, rather than agreed.** The CLI defined this itself, which meant AC-4 — "the key matches
+ * the CLI's, or the two do not serialise against each other" — was a property of two constants happening to be
+ * equal. Two constants that must be equal are one constant; a copy that drifts produces two locks and no
+ * serialisation, and the symptom is the original crash returning with the fix apparently in place.
+ *
+ * Arbitrary, and it has to be: Postgres advisory locks are a flat 64-bit namespace with no registry, so the
+ * only protection against collision is picking something nobody else would. Derived from the ASCII of
+ * "retinue" so it is reproducible rather than a magic number somebody will tidy up.
+ */
+export const MIGRATION_LOCK = 0x72_65_74_69_6e_75; // "retinu"
 export const createSchemaManager = (sql, migrations = MIGRATIONS) => {
     // Read-only: if the tracking table doesn't exist yet, nothing has been applied. `plan()` and
     // `currentVersion()` therefore have no side effects; only `apply()` creates the table.
@@ -48,23 +90,66 @@ export const createSchemaManager = (sql, migrations = MIGRATIONS) => {
  */
 export const provisionSchema = async (sql, options = {}) => {
     const mode = options.mode ?? "off";
-    const manager = createSchemaManager(sql, options.migrations);
     const log = options.log ?? (() => { });
     if (mode === "off") {
-        return { mode, applied: [], planned: [] };
+        return { mode, applied: [], planned: [], locked: false };
     }
-    const planned = await manager.plan();
     if (mode === "plan") {
+        /**
+         * Read-only, and takes **no lock** — the same decision `retinue migrate --dry-run` makes.
+         *
+         * `plan()` and `currentVersion()` are documented as side-effect free; only `apply()` creates the ledger.
+         * Taking a lock here would serialise every booting worker behind a read that changes nothing, and a dry
+         * run that waited on a migration lock would be a dry run with a production dependency.
+         */
+        const planned = await createSchemaManager(sql, options.migrations).plan();
         if (planned.length === 0)
             log("schema is up to date; no changes to apply");
         else
             log(`schema plan — ${planned.length} pending migration(s): ${planned.map((c) => c.id).join(", ")}`);
-        return { mode, applied: [], planned };
+        return { mode, applied: [], planned, locked: false };
     }
     // auto
-    await manager.apply();
-    if (planned.length)
-        log(`provisioned schema: applied ${planned.map((c) => c.id).join(", ")}`);
-    return { mode, applied: planned.map((c) => c.id), planned };
+    if (options.open === undefined) {
+        /**
+         * No opener: apply directly, exactly as before.
+         *
+         * Correct for PGlite and the in-memory paths, which are single-process. On a pool-backed deployment with
+         * several workers this is the path that produces the original crash, which is why `locked: false` is
+         * reported rather than left to be inferred.
+         */
+        const manager = createSchemaManager(sql, options.migrations);
+        const planned = await manager.plan();
+        await manager.apply();
+        if (planned.length)
+            log(`provisioned schema: applied ${planned.map((c) => c.id).join(", ")}`);
+        return { mode, applied: planned.map((c) => c.id), planned, locked: false };
+    }
+    return await options.open(async (locked) => {
+        /**
+         * The lock, the plan and the apply all on **one** connection.
+         *
+         * The plan has to be read inside the lock, not outside it: a plan computed before waiting on the lock is
+         * a plan the winner has already invalidated, so the loser would apply migrations that are now recorded
+         * and race on the DDL anyway. Reading it here is what makes the loser report "nothing to apply".
+         */
+        await locked.query("select pg_advisory_lock($1)", [MIGRATION_LOCK]);
+        try {
+            const manager = createSchemaManager(locked, options.migrations);
+            const planned = await manager.plan();
+            if (planned.length === 0) {
+                log(`schema already at ${manager.targetVersion()}; nothing to apply`);
+                return { mode, applied: [], planned, locked: true };
+            }
+            await manager.apply();
+            log(`provisioned schema: applied ${planned.map((c) => c.id).join(", ")}`);
+            return { mode, applied: planned.map((c) => c.id), planned, locked: true };
+        }
+        finally {
+            // Released explicitly, and by the session ending if the process dies mid-migration — which is the
+            // property that makes a crash during provisioning recoverable without an operator clearing a lock.
+            await locked.query("select pg_advisory_unlock($1)", [MIGRATION_LOCK]);
+        }
+    });
 };
 //# sourceMappingURL=schema.js.map

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

@@ -6,4 +6,5 @@
  * for realtime" are two decisions, not one.
  */
 export * from "./realtime.js";
+export * from "./rate-limit.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/redis/index.js

@@ -6,4 +6,5 @@
  * for realtime" are two decisions, not one.
  */
 export * from "./realtime.js";
+export * from "./rate-limit.js";
 //# sourceMappingURL=index.js.map

package/dist/adapters/redis/rate-limit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The rate-limit counter in Redis — task #248, AC-2 and AC-3.
+ *
+ * The real implementation. An in-memory one exists for tests and is explicitly *not* usable in a deployment: two
+ * workers each holding their own `Map` would each allow the full rate, so a limit of 60/minute becomes 60×N.
+ *
+ * ## One script, not INCR then EXPIRE
+ *
+ * The obvious version is `INCR key` followed by `EXPIRE key ttl`. It is wrong, and not subtly: a process that
+ * dies, is killed, or loses its connection between the two leaves a key with **no TTL**, and that tenant is
+ * refused for ever — a permanent outage caused by the rate limiter, with no way to notice except a customer
+ * reporting it. Redis has no combined increment-and-expire command, so this is one `EVAL`, which Redis runs
+ * atomically.
+ *
+ * `PEXPIRE … NX` inside the script would also work and is not used: the key's TTL is a constant derived from the
+ * window, so setting it every increment is idempotent and one fewer thing to reason about.
+ *
+ * ## Why the key carries the window start
+ *
+ * `windowStartMs` truncates, so the key is a pure function of the moment — every process derives the same key for
+ * the same instant without coordinating, and an old window's key expires on its own rather than needing a sweep.
+ * It also makes the TTL safe to set unconditionally: a key is only ever written for the window it names.
+ */
+import type { RateLimitStore } from "../../usage/index.js";
+/**
+ * The one command needed, structurally — the reasoning `RedisPublishClient` gives.
+ *
+ * `eval` rather than `defineCommand`/`evalsha`: this runs once per admitted run, not in a tight loop, and a
+ * script cache miss would need a fallback path that is more code than the saving is worth.
+ */
+export interface RedisEvalClient {
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+/** Namespaced, so a counter cannot collide with BullMQ's keys, the realtime channels, or another app's. */
+export declare const rateLimitKey: (tenantId: string, windowStartMs: number) => string;
+/**
+ * Increment and set the expiry in one atomic step, returning the count after incrementing.
+ *
+ * The TTL is the window plus a second of slack. The slack matters: a client whose clock is a few hundred
+ * milliseconds behind the server may still be admitting against a window Redis has already expired, and the
+ * result would be a counter that silently restarts mid-window — the failure being prevented, arriving by a
+ * different route.
+ */
+export declare const RATE_LIMIT_SCRIPT = "\nlocal count = redis.call('INCR', KEYS[1])\nredis.call('EXPIRE', KEYS[1], ARGV[1])\nreturn count\n";
+export declare const createRedisRateLimitStore: (client: RedisEvalClient) => RateLimitStore;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/adapters/redis/rate-limit.js

@@ -0,0 +1,55 @@
+/**
+ * The rate-limit counter in Redis — task #248, AC-2 and AC-3.
+ *
+ * The real implementation. An in-memory one exists for tests and is explicitly *not* usable in a deployment: two
+ * workers each holding their own `Map` would each allow the full rate, so a limit of 60/minute becomes 60×N.
+ *
+ * ## One script, not INCR then EXPIRE
+ *
+ * The obvious version is `INCR key` followed by `EXPIRE key ttl`. It is wrong, and not subtly: a process that
+ * dies, is killed, or loses its connection between the two leaves a key with **no TTL**, and that tenant is
+ * refused for ever — a permanent outage caused by the rate limiter, with no way to notice except a customer
+ * reporting it. Redis has no combined increment-and-expire command, so this is one `EVAL`, which Redis runs
+ * atomically.
+ *
+ * `PEXPIRE … NX` inside the script would also work and is not used: the key's TTL is a constant derived from the
+ * window, so setting it every increment is idempotent and one fewer thing to reason about.
+ *
+ * ## Why the key carries the window start
+ *
+ * `windowStartMs` truncates, so the key is a pure function of the moment — every process derives the same key for
+ * the same instant without coordinating, and an old window's key expires on its own rather than needing a sweep.
+ * It also makes the TTL safe to set unconditionally: a key is only ever written for the window it names.
+ */
+/** Namespaced, so a counter cannot collide with BullMQ's keys, the realtime channels, or another app's. */
+export const rateLimitKey = (tenantId, windowStartMs) => `agentkit:ratelimit:${tenantId}:${windowStartMs}`;
+/**
+ * Increment and set the expiry in one atomic step, returning the count after incrementing.
+ *
+ * The TTL is the window plus a second of slack. The slack matters: a client whose clock is a few hundred
+ * milliseconds behind the server may still be admitting against a window Redis has already expired, and the
+ * result would be a counter that silently restarts mid-window — the failure being prevented, arriving by a
+ * different route.
+ */
+export const RATE_LIMIT_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+redis.call('EXPIRE', KEYS[1], ARGV[1])
+return count
+`;
+export const createRedisRateLimitStore = (client) => ({
+    async consume({ tenantId, windowStartMs, windowSeconds }) {
+        const count = await client.eval(RATE_LIMIT_SCRIPT, 1, rateLimitKey(tenantId, windowStartMs), windowSeconds + 1);
+        /**
+         * Coerced, and a non-numeric reply is a failure rather than a zero.
+         *
+         * `eval` is typed `unknown` because the client is structural. Treating an unexpected reply as `0` would make
+         * a broken Redis look like an empty counter and admit everything — a rate limiter that fails open silently.
+         * A throw is the right direction here: admission already refuses on a thrown error.
+         */
+        const used = typeof count === "number" ? count : Number(count);
+        if (!Number.isFinite(used))
+            throw new Error(`rate limit: Redis returned ${JSON.stringify(count)} for INCR, which is not a count`);
+        return used;
+    },
+});
+//# sourceMappingURL=rate-limit.js.map

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

@@ -12,6 +12,11 @@
  * client to the small interfaces here, so this package stays deployable without one.
  */
 import type { AdapterCapability } from "../../persistence/index.js";
+/**
+ * #261. Aliased rather than reimplemented, like every other store here: Supabase *is* Postgres, and a second
+ * implementation would make "identical results" something to prove per port rather than by identity.
+ */
+export { createPostgresConnectionStore as createSupabaseConnectionStore } from "../postgres/connections.js";
 export { createPostgresConversationStore as createSupabaseConversationStore } from "../postgres/conversation-store.js";
 export { createPostgresSessionStateStore as createSupabaseSessionStateStore, createPostgresThreadSummaryStore as createSupabaseThreadSummaryStore, } from "../postgres/session-state.js";
 export { createPostgresConversationBindingStore as createSupabaseConversationBindingStore, createPostgresMessageStore as createSupabaseMessageStore, createPostgresAgentStore as createSupabaseAgentStore, } from "../postgres/message-store.js";
@@ -57,6 +62,7 @@ export { createPostgresArtifactExportStore as createSupabaseArtifactExportStore
 export { createPostgresUsageRollupStore as createSupabaseUsageRollupStore } from "../postgres/rollups.js";
 export { createPostgresEvaluationStore as createSupabaseEvaluationStore } from "../postgres/evaluation.js";
 export { createPostgresKnowledgeStore as createSupabaseKnowledgeStore, createPostgresVectorIndex as createSupabaseVectorIndex, createPostgresKeywordIndex as createSupabaseKeywordIndex, } from "../postgres/knowledge.js";
+export { createPostgresGraphStore as createSupabaseGraphStore } from "../postgres/graph.js";
 export * from "./rls.js";
 export * from "./realtime.js";
 /**
@@ -85,4 +91,13 @@ export declare const SUPABASE_CAPABILITIES: readonly AdapterCapability[];
  */
 export { createPostgresFlowDefinitionStore as createSupabaseFlowDefinitionStore } from "../postgres/flows.js";
 export { createPostgresFlowExecutionStore as createSupabaseFlowExecutionStore } from "../postgres/flows.js";
+/**
+ * The Supabase Vault `SecretCipher` — task #268.
+ *
+ * Exported from the Supabase adapters rather than from `connections/`, because it is Supabase-specific and
+ * needs a `SqlExecutor`: putting it in the general entry would make every consumer of the connections module
+ * import a database type it has no use for.
+ */
+export { createSupabaseVaultCipher, SUPABASE_VAULT, vaultRotationIsExternal } from "../../connections/vault-cipher.js";
+export type { VaultCipherOptions } from "../../connections/vault-cipher.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/supabase/index.js

@@ -1,4 +1,9 @@
 // Conversation and session
+/**
+ * #261. Aliased rather than reimplemented, like every other store here: Supabase *is* Postgres, and a second
+ * implementation would make "identical results" something to prove per port rather than by identity.
+ */
+export { createPostgresConnectionStore as createSupabaseConnectionStore } from "../postgres/connections.js";
 export { createPostgresConversationStore as createSupabaseConversationStore } from "../postgres/conversation-store.js";
 export { createPostgresSessionStateStore as createSupabaseSessionStateStore, createPostgresThreadSummaryStore as createSupabaseThreadSummaryStore, } from "../postgres/session-state.js";
 export { createPostgresConversationBindingStore as createSupabaseConversationBindingStore, createPostgresMessageStore as createSupabaseMessageStore, createPostgresAgentStore as createSupabaseAgentStore, } from "../postgres/message-store.js";
@@ -48,6 +53,8 @@ export { createPostgresArtifactExportStore as createSupabaseArtifactExportStore
 export { createPostgresUsageRollupStore as createSupabaseUsageRollupStore } from "../postgres/rollups.js";
 export { createPostgresEvaluationStore as createSupabaseEvaluationStore } from "../postgres/evaluation.js";
 export { createPostgresKnowledgeStore as createSupabaseKnowledgeStore, createPostgresVectorIndex as createSupabaseVectorIndex, createPostgresKeywordIndex as createSupabaseKeywordIndex, } from "../postgres/knowledge.js";
+// #271. Aliased like the three above: the graph is ordinary Postgres rows, so Supabase needs no second one.
+export { createPostgresGraphStore as createSupabaseGraphStore } from "../postgres/graph.js";
 export * from "./rls.js";
 export * from "./realtime.js";
 /**
@@ -81,4 +88,12 @@ export const SUPABASE_CAPABILITIES = [
  */
 export { createPostgresFlowDefinitionStore as createSupabaseFlowDefinitionStore } from "../postgres/flows.js";
 export { createPostgresFlowExecutionStore as createSupabaseFlowExecutionStore } from "../postgres/flows.js";
+/**
+ * The Supabase Vault `SecretCipher` — task #268.
+ *
+ * Exported from the Supabase adapters rather than from `connections/`, because it is Supabase-specific and
+ * needs a `SqlExecutor`: putting it in the general entry would make every consumer of the connections module
+ * import a database type it has no use for.
+ */
+export { createSupabaseVaultCipher, SUPABASE_VAULT, vaultRotationIsExternal } from "../../connections/vault-cipher.js";
 //# sourceMappingURL=index.js.map