@retinue/agentkit 0.3.0 → 0.3.1

package/dist/server/bin.d.ts

@@ -15,5 +15,58 @@
  * `migrate` and `doctor` deliberately need **no** app module: a database is provisioned before an application
  * exists, and a diagnostic that cannot run until everything else is configured is a diagnostic nobody can use.
  */
+/**
+ * The advisory-lock key comes from `schema.ts` — #252's AC-2, and #266's AC-4.
+ *
+ * It used to be defined here. That made "the CLI and `auto` mode use the same key" a property of two constants
+ * happening to be equal, and a copy that drifted would produce two locks, no serialisation, and the original
+ * crash returning with the fix apparently in place. Two constants that must be equal are one constant.
+ */
+/**
+ * Create the configured schema if it is not there, before anything tries to use it.
+ *
+ * `migrate` is the command that owns provisioning, so the namespace it was told to provision into is
+ * its job too — and the reason is worse than a missing-schema error. **Postgres does not error.**
+ * `SET search_path TO retinue, public` succeeds when `retinue` does not exist: a missing entry is
+ * skipped, not rejected. `CREATE TABLE conversations` then lands in the first schema that *does*
+ * exist, which is `public` — so all 34 platform migrations would silently be created alongside the
+ * product's tables, reporting success the whole way. Verified against a real Postgres 17: the SET
+ * returns, the CREATE returns, and `information_schema` says `public`.
+ *
+ * That is the failure this function exists to prevent, and it is why it runs before the pool rather
+ * than relying on a connection error that never comes.
+ *
+ * On its own connection with the **default** search path, which is the part that is easy to get wrong.
+ * A connection configured for `retinue` cannot be the one that creates `retinue` — `openPostgres`
+ * destroys it during setup, before a statement of ours runs.
+ *
+ * `IF NOT EXISTS` and nothing else: no owner, no grants, no drop. Provisioning a namespace is additive;
+ * deciding who may use it is a deployment's decision and not a migration's.
+ */
+/**
+ * Which `migrate` invocations must change nothing.
+ *
+ * Its own function because it is the link between a flag and a side effect, and that link is invisible
+ * to a test of either end: sabotaging it to `false` — so `--dry-run` provisions a schema — broke
+ * nothing, while every assertion about `ensureSchema` itself stayed green. The list is also the same
+ * one the read-only branch below uses, so a third flag added to one and not the other cannot silently
+ * become a writing dry run.
+ */
+export declare const READ_ONLY_FLAGS: readonly ["--status", "--dry-run"];
+export declare const isReadOnly: (flags: ReadonlySet<string>) => boolean;
+export declare const ensureSchema: (config: {
+    readonly databaseUrl: string;
+    readonly databaseSchema?: string;
+}, { create, connect, }: {
+    readonly create: boolean;
+    readonly connect?: (settings: {
+        readonly databaseUrl: string;
+    }) => Promise<{
+        readonly sql: {
+            query<Row>(text: string, params?: readonly unknown[]): Promise<Row[]>;
+        };
+        readonly end: () => Promise<void>;
+    }>;
+}) => Promise<boolean>;
 export declare const main: (argv: readonly string[], env?: NodeJS.ProcessEnv) => Promise<number>;
 //# sourceMappingURL=bin.d.ts.map

package/dist/server/bin.js

@@ -29,15 +29,20 @@ const USAGE = `retinue <command>
   doctor             Check configuration, database, schema and Redis. Reports every failure.
 
 Configuration comes from the environment; see .env.example.`;
-/** Opened lazily and per command, so `doctor` and `migrate` never load a driver they do not use. */
-const postgres = async (url) => {
-    const { Pool } = await import("pg");
-    const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
-    // A connect timeout, because the default is *none*: `doctor` against a refused port sat silently instead of
-    // reporting the failure it exists to report. Short, since every command here either connects immediately or
-    // is misconfigured.
-    const pool = new Pool({ connectionString: url, connectionTimeoutMillis: 5_000 });
-    return { sql: createPgExecutor(pool), open: createPoolOpener(pool), end: () => pool.end() };
+/**
+ * Opened lazily and per command, so `doctor` and `migrate` never load a driver they do not use.
+ *
+ * The pool itself comes from `pool.ts`, which is also what the API host and the worker use — the schema
+ * a deployment configures has to be the same one migrations run against, and that is only true while
+ * there is one place that decides it.
+ *
+ * A connect timeout, because the default is *none*: `doctor` against a refused port sat silently instead
+ * of reporting the failure it exists to report. Short, since every command here either connects
+ * immediately or is misconfigured.
+ */
+const postgres = async (config) => {
+    const { openPostgres } = await import("./pool.js");
+    return openPostgres({ ...config, connectionTimeoutMillis: 5_000 });
 };
 /**
  * The advisory-lock key comes from `schema.ts` — #252's AC-2, and #266's AC-4.
@@ -46,12 +51,85 @@ const postgres = async (url) => {
  * happening to be equal, and a copy that drifted would produce two locks, no serialisation, and the original
  * crash returning with the fix apparently in place. Two constants that must be equal are one constant.
  */
+/**
+ * Create the configured schema if it is not there, before anything tries to use it.
+ *
+ * `migrate` is the command that owns provisioning, so the namespace it was told to provision into is
+ * its job too — and the reason is worse than a missing-schema error. **Postgres does not error.**
+ * `SET search_path TO retinue, public` succeeds when `retinue` does not exist: a missing entry is
+ * skipped, not rejected. `CREATE TABLE conversations` then lands in the first schema that *does*
+ * exist, which is `public` — so all 34 platform migrations would silently be created alongside the
+ * product's tables, reporting success the whole way. Verified against a real Postgres 17: the SET
+ * returns, the CREATE returns, and `information_schema` says `public`.
+ *
+ * That is the failure this function exists to prevent, and it is why it runs before the pool rather
+ * than relying on a connection error that never comes.
+ *
+ * On its own connection with the **default** search path, which is the part that is easy to get wrong.
+ * A connection configured for `retinue` cannot be the one that creates `retinue` — `openPostgres`
+ * destroys it during setup, before a statement of ours runs.
+ *
+ * `IF NOT EXISTS` and nothing else: no owner, no grants, no drop. Provisioning a namespace is additive;
+ * deciding who may use it is a deployment's decision and not a migration's.
+ */
+/**
+ * Which `migrate` invocations must change nothing.
+ *
+ * Its own function because it is the link between a flag and a side effect, and that link is invisible
+ * to a test of either end: sabotaging it to `false` — so `--dry-run` provisions a schema — broke
+ * nothing, while every assertion about `ensureSchema` itself stayed green. The list is also the same
+ * one the read-only branch below uses, so a third flag added to one and not the other cannot silently
+ * become a writing dry run.
+ */
+export const READ_ONLY_FLAGS = ["--status", "--dry-run"];
+export const isReadOnly = (flags) => READ_ONLY_FLAGS.some((flag) => flags.has(flag));
+export const ensureSchema = async (config, { create, 
+// Injectable so a test can run this against a real Postgres — PGlite — without a live server. The
+// default is the same `postgres` every command here uses.
+connect = (settings) => postgres(settings), }) => {
+    if (config.databaseSchema === undefined)
+        return true;
+    const { sql, end } = await connect({ databaseUrl: config.databaseUrl });
+    try {
+        if (create) {
+            // Validated as an unquoted identifier by `loadConfig` — the only reason this concatenation is safe,
+            // and the reason that check refuses anything Postgres would need quoted.
+            await sql.query(`CREATE SCHEMA IF NOT EXISTS ${config.databaseSchema}`);
+            console.log(`schema: ${config.databaseSchema} ready`);
+            return true;
+        }
+        /**
+         * The read-only paths report instead of creating, and that is not fussiness.
+         *
+         * `--dry-run` and `--status` are documented a few lines below as side-effect free — the note says
+         * `public` has 0 tables after a dry run against a fresh database — and a reader deciding whether to
+         * trust a dry run is exactly the reader who must not find it provisioned a schema. Creating one is
+         * a small side effect and a large broken promise.
+         */
+        const rows = await sql.query(`select exists (select 1 from pg_namespace where nspname = $1) as exists`, [config.databaseSchema]);
+        if (rows[0]?.exists === true)
+            return true;
+        console.error(`schema: ${config.databaseSchema} does not exist. Postgres will not complain — it skips a missing ` +
+            `entry in search_path — so tables would be created in the next schema on the path instead, ` +
+            `silently. Run \`retinue migrate\`, which creates it, or unset RETINUE_DATABASE_SCHEMA to use the ` +
+            `connection's own schema deliberately.`);
+        return false;
+    }
+    finally {
+        await end();
+    }
+};
 const migrate = async (flags, env = process.env) => {
     const config = loadConfig(env);
-    const { sql, open, end } = await postgres(config.databaseUrl);
+    // Before the pool, because a missing schema does not fail: `SET search_path` skips an entry that does
+    // not exist and every CREATE lands in `public` instead, silently. The read-only flags report rather
+    // than create — see `ensureSchema`.
+    if (!(await ensureSchema(config, { create: !isReadOnly(flags) })))
+        return 1;
+    const { sql, open, end } = await postgres(config);
     try {
         const { createSchemaManager, MIGRATION_LOCK } = await import("../entries/adapters-postgres.js");
-        if (flags.has("--status") || flags.has("--dry-run")) {
+        if (isReadOnly(flags)) {
             // Read-only paths take no lock. `plan()` and `currentVersion()` are documented as side-effect free — only
             // `apply()` creates the ledger table — which is what makes a dry run honest rather than a dry run that
             // provisions one table. Verified: after `--dry-run` against a fresh database, `public` has 0 tables.
@@ -116,8 +194,8 @@ const migrate = async (flags, env = process.env) => {
 const doctor = async (env = process.env) => {
     const results = await runChecks({
         env,
-        connectPostgres: async (url) => {
-            const { sql, end } = await postgres(url);
+        connectPostgres: async (settings) => {
+            const { sql, end } = await postgres(settings);
             return { query: (text, params) => sql.query(text, params), end };
         },
         connectRedis: async (url) => {

package/dist/server/cli-worker.js

@@ -25,9 +25,12 @@ export const runWorker = async (env = process.env) => {
     const { config, sql } = await boot({
         env,
         connect: async (loaded) => {
-            const { Pool } = await import("pg");
-            const { createPgExecutor } = await import("../entries/adapters-postgres.js");
-            return { sql: createPgExecutor(new Pool({ connectionString: loaded.databaseUrl })) };
+            const { openPostgres } = await import("./pool.js");
+            // Through the shared pool for the schema, which matters most here: the worker is the process whose
+            // writes nobody watches, so a worker in `public` while the host is in `retinue` is a split brain
+            // that shows up as runs that vanish rather than as an error.
+            const { sql } = await openPostgres(loaded);
+            return { sql };
         },
     });
     /**

package/dist/server/cli.js

@@ -38,12 +38,14 @@ export const runApiHost = async (env = process.env) => {
     const { config, sql, runner } = await boot({
         env,
         connect: async (loaded) => {
-            const { Pool } = await import("pg");
-            const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
-            const pool = new Pool({ connectionString: loaded.databaseUrl });
+            const { openPostgres } = await import("./pool.js");
             // `open` is what lets `boot` build a transaction scope. Without it the API host had no runner and
             // `sendMessage` could not claim a conversation — #254.
-            return { sql: createPgExecutor(pool), open: createPoolOpener(pool) };
+            //
+            // The whole config is passed, not just the URL: `databaseSchema` has to reach the pool or the host
+            // reads and writes `public` while migrations ran somewhere else.
+            const { sql, open } = await openPostgres(loaded);
+            return { sql, open };
         },
     });
     const deps = await app.deps({ config, sql, ...(runner === undefined ? {} : { runner }) });

package/dist/server/config.d.ts

@@ -4,6 +4,16 @@ export type RetinueConfig = {
     readonly redisUrl: string;
     /** How the schema is provisioned at boot. `off` in production, so managed migrations stay in control. */
     readonly schemaMode: SchemaMode;
+    /**
+     * The Postgres schema the platform's own tables live in, or `undefined` for the connection's default.
+     *
+     * Exists because a deployment may be sharing a database with a product that owns `public` — which is
+     * exactly the ShareFlow case: its adapters qualify every one of their queries as `public.`, so with this
+     * set to `retinue` one pool serves both, platform tables in one schema and product tables in the other.
+     * Without it the platform's 35 migrations land in `public` alongside the product's, and the first name
+     * they share is a migration that fails or, worse, one that succeeds against the wrong table.
+     */
+    readonly databaseSchema?: string;
     readonly port: number;
     readonly workerConcurrency: number;
     readonly logLevel: "debug" | "info" | "warn" | "error";
@@ -38,5 +48,5 @@ export declare const loadConfig: (env: Env) => RetinueConfig;
  * test that asserts the error names every missing variable is what found it.
  */
 export declare const REQUIRED_VARIABLES: readonly ["RETINUE_DATABASE_URL", "RETINUE_REDIS_URL"];
-export declare const OPTIONAL_VARIABLES: readonly ["SCHEMA_MODE", "WORKER_CONCURRENCY", "LOG_LEVEL", "PORT"];
+export declare const OPTIONAL_VARIABLES: readonly ["SCHEMA_MODE", "DATABASE_SCHEMA", "WORKER_CONCURRENCY", "LOG_LEVEL", "PORT"];
 //# sourceMappingURL=config.d.ts.map

package/dist/server/config.js

@@ -76,6 +76,20 @@ export const loadConfig = (env) => {
     if (!SCHEMA_MODES.includes(rawSchemaMode)) {
         fail(named("SCHEMA_MODE"), `must be one of ${SCHEMA_MODES.join(", ")}, got "${rawSchemaMode}"`);
     }
+    /**
+     * A schema name, validated as an identifier rather than quoted.
+     *
+     * `SET search_path` takes no parameters — it is not a value position, so there is no placeholder to bind
+     * and the name is concatenated into SQL. That makes this the one config value where a lax check is a SQL
+     * injection with the deployment's own credentials, so the pattern is deliberately narrow: what Postgres
+     * accepts unquoted, and nothing else. A rejected name fails boot, where it is one line to fix.
+     */
+    const rawSchema = lookup("DATABASE_SCHEMA");
+    const databaseSchema = rawSchema === undefined || rawSchema.trim() === "" ? undefined : rawSchema.trim();
+    if (databaseSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(databaseSchema)) {
+        fail(named("DATABASE_SCHEMA"), `must be an unquoted Postgres identifier — letters, digits, underscore and $, not starting with a ` +
+            `digit — got "${databaseSchema.slice(0, 24)}"`);
+    }
     const positiveInt = (suffix, fallback) => {
         // `PORT` has no prefix — it is the conventional name and always has been, so it is read directly.
         const variable = suffix === "PORT" ? "PORT" : named(suffix);
@@ -103,6 +117,9 @@ export const loadConfig = (env) => {
         databaseUrl,
         redisUrl,
         schemaMode: rawSchemaMode,
+        // Spread, not `databaseSchema: undefined` — `exactOptionalPropertyTypes` is on, so an explicit
+        // undefined is a different type from an absent key.
+        ...(databaseSchema === undefined ? {} : { databaseSchema }),
         port,
         workerConcurrency,
         logLevel: rawLogLevel,
@@ -120,6 +137,7 @@ export const loadConfig = (env) => {
 export const REQUIRED_VARIABLES = ["RETINUE_DATABASE_URL", "RETINUE_REDIS_URL"];
 export const OPTIONAL_VARIABLES = [
     "SCHEMA_MODE",
+    "DATABASE_SCHEMA",
     "WORKER_CONCURRENCY",
     "LOG_LEVEL",
     "PORT",

package/dist/server/doctor.d.ts

@@ -39,8 +39,19 @@ export declare const describeUrl: (value: string) => string;
 export declare const scrub: (message: string) => string;
 export type DoctorDeps = {
     readonly env?: Readonly<Record<string, string | undefined>>;
-    /** Injected so the checks are testable without a database or a Redis. */
-    readonly connectPostgres?: (url: string) => Promise<{
+    /**
+     * Injected so the checks are testable without a database or a Redis.
+     *
+     * Takes the whole connection setting rather than a URL, because `databaseSchema` changes the answer:
+     * the schema probe counts applied migrations, and reading `public` when the deployment configured
+     * `retinue` reports "0 of 35 applied → run migrate" about a schema that is fully migrated. The
+     * comment below already names that class of bug — a diagnostic sending an operator to fix the wrong
+     * thing — and a URL-only signature is how this one would have got in.
+     */
+    readonly connectPostgres?: (settings: {
+        readonly databaseUrl: string;
+        readonly databaseSchema?: string;
+    }) => Promise<{
         query(text: string, params?: readonly unknown[]): Promise<unknown>;
         end(): Promise<void>;
     }>;

package/dist/server/doctor.js

@@ -179,7 +179,7 @@ export const runChecks = async (deps = {}) => {
          */
         let reachable = false;
         try {
-            sql = await withTimeout("postgres", connectPostgres(config.databaseUrl));
+            sql = await withTimeout("postgres", connectPostgres(config));
             await withTimeout("postgres", sql.query("select 1"));
             reachable = true;
             results.push({ name: "postgres", ok: true, detail: `reachable at ${describeUrl(config.databaseUrl)}` });

package/dist/server/pool.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one place a `pg.Pool` is built for this host — REQ-041 (#190).
+ *
+ * There were four: `bin.ts` for `migrate`/`doctor`, `cli.ts` for the API host, `cli-worker.ts` for the
+ * worker, and the driver `doctor` is handed. Four copies of "how this deployment connects" is three
+ * copies too many, and the one that drifts is the one nobody exercises — the worker, whose writes are
+ * the ones that must land in the same schema as everything else.
+ *
+ * **What it adds over `new Pool`.** `RETINUE_DATABASE_SCHEMA` names the schema the platform's tables
+ * live in, and honouring it takes two things that must agree:
+ *
+ *  - `pool.on("connect")` sets `search_path` on **every** connection, because `createPgExecutor` runs
+ *    each query through `pool.query`, which takes a different connection per call. A pooled connection
+ *    carries whatever `search_path` its last user left, so setting it once at startup means the first
+ *    few statements land in the right schema and the rest land wherever. That failure is not loud: it
+ *    is a table created in `public` by a migration that reported success.
+ *  - `createPoolOpener(pool, …)` sets it again per checkout, which is what the transaction scope uses.
+ *    Redundant on paper and deliberately kept: the opener is the path that holds `SELECT … FOR UPDATE`
+ *    across statements, and it must not depend on a listener having fired.
+ *
+ * **`public` stays on the path** after the named schema. Two things need it: the `vector` type is
+ * pinned to `public` so it resolves from any schema (see the note in `migrations.ts`), and ShareFlow's
+ * adapters qualify all 70 of their queries as `public.`, which is what lets one pool serve a platform
+ * schema and a product schema at once.
+ */
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+import type { ConnectionOpener } from "../adapters/postgres/transaction.js";
+export type PostgresConnection = {
+    readonly sql: SqlExecutor;
+    readonly open: ConnectionOpener;
+    readonly end: () => Promise<void>;
+};
+export type PoolSettings = {
+    readonly databaseUrl: string;
+    readonly databaseSchema?: string;
+    /** Left unset by the host and the worker, which is node-postgres's default of no timeout. */
+    readonly connectionTimeoutMillis?: number;
+};
+/**
+ * The `search_path` for a named schema, or `undefined` to leave the connection's own.
+ *
+ * Exported because it is the only string in this file that ends up in SQL, and a test that pins it is
+ * cheaper than reading two call sites to find out what a deployment actually gets.
+ */
+export declare const searchPathFor: (schema: string | undefined) => string | undefined;
+export declare const openPostgres: (settings: PoolSettings) => Promise<PostgresConnection>;
+//# sourceMappingURL=pool.d.ts.map

package/dist/server/pool.js

@@ -0,0 +1,73 @@
+/**
+ * The one place a `pg.Pool` is built for this host — REQ-041 (#190).
+ *
+ * There were four: `bin.ts` for `migrate`/`doctor`, `cli.ts` for the API host, `cli-worker.ts` for the
+ * worker, and the driver `doctor` is handed. Four copies of "how this deployment connects" is three
+ * copies too many, and the one that drifts is the one nobody exercises — the worker, whose writes are
+ * the ones that must land in the same schema as everything else.
+ *
+ * **What it adds over `new Pool`.** `RETINUE_DATABASE_SCHEMA` names the schema the platform's tables
+ * live in, and honouring it takes two things that must agree:
+ *
+ *  - `pool.on("connect")` sets `search_path` on **every** connection, because `createPgExecutor` runs
+ *    each query through `pool.query`, which takes a different connection per call. A pooled connection
+ *    carries whatever `search_path` its last user left, so setting it once at startup means the first
+ *    few statements land in the right schema and the rest land wherever. That failure is not loud: it
+ *    is a table created in `public` by a migration that reported success.
+ *  - `createPoolOpener(pool, …)` sets it again per checkout, which is what the transaction scope uses.
+ *    Redundant on paper and deliberately kept: the opener is the path that holds `SELECT … FOR UPDATE`
+ *    across statements, and it must not depend on a listener having fired.
+ *
+ * **`public` stays on the path** after the named schema. Two things need it: the `vector` type is
+ * pinned to `public` so it resolves from any schema (see the note in `migrations.ts`), and ShareFlow's
+ * adapters qualify all 70 of their queries as `public.`, which is what lets one pool serve a platform
+ * schema and a product schema at once.
+ */
+/**
+ * The `search_path` for a named schema, or `undefined` to leave the connection's own.
+ *
+ * Exported because it is the only string in this file that ends up in SQL, and a test that pins it is
+ * cheaper than reading two call sites to find out what a deployment actually gets.
+ */
+export const searchPathFor = (schema) => schema === undefined || schema === "" ? undefined : `${schema}, public`;
+export const openPostgres = async (settings) => {
+    const { Pool } = await import("pg");
+    const { createPgExecutor, createPoolOpener } = await import("../entries/adapters-postgres.js");
+    const searchPath = searchPathFor(settings.databaseSchema);
+    const pool = new Pool({
+        connectionString: settings.databaseUrl,
+        ...(settings.connectionTimeoutMillis === undefined
+            ? {}
+            : { connectionTimeoutMillis: settings.connectionTimeoutMillis }),
+    });
+    if (searchPath !== undefined) {
+        /**
+         * Queued on the client, not awaited — which is what makes it correct rather than racy.
+         *
+         * node-postgres queues queries per client in order, so this `SET` is ahead of whatever the borrower
+         * runs next on that same connection. An `await` here would have nothing to attach to: `connect` is
+         * an event, and the pool hands the client out regardless of what a listener is still doing.
+         *
+         * A failure is surfaced rather than swallowed, and it is worth being precise about what it can and
+         * cannot catch. It means the role may not *use* the schema. It does **not** mean the schema is
+         * missing: `SET search_path TO retinue, public` succeeds when `retinue` does not exist, because a
+         * missing entry is skipped rather than rejected, and every write then lands in `public` with no
+         * error anywhere. Nothing at this layer can see that — which is why `retinue migrate` creates the
+         * schema before anything connects, and why this listener is not the guard against it.
+         */
+        pool.on("connect", (client) => {
+            void client.query(`SET search_path TO ${searchPath}`).catch((error) => {
+                client.end();
+                pool.emit("error", error instanceof Error
+                    ? new Error(`could not SET search_path TO ${searchPath}: ${error.message}`, { cause: error })
+                    : new Error(`could not SET search_path TO ${searchPath}`), client);
+            });
+        });
+    }
+    return {
+        sql: createPgExecutor(pool),
+        open: createPoolOpener(pool, searchPath),
+        end: () => pool.end(),
+    };
+};
+//# sourceMappingURL=pool.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retinue/agentkit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A provider-neutral, durable AI agent runtime for TypeScript: agents, tools, approvals, context, knowledge and persistence behind ports.",
   "license": "MIT",
   "type": "module",