Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-133: the session-lane census behind doctor `session_lane_budget`. A Supabase-style pooler gives each database role a
* fixed number of session-mode server connections (Supavisor `pool_size`), and every gbrain process on a host opens its own
* pools: serve's ordinary pool, each process's direct pool, a sync's import workers. Nothing counted them together, so one
* host could exhaust the lane (`EMAXCONNSESSION`) with no warning before the first refusal.
*
* One read-only statement over `pg_stat_activity` (no query text) counts this role's client backends in this database by
* `application_name`. Every gbrain pool names its connections `gbrain <kind>:<pid>:<nonce8>` (db.ts), so those backends
* are attributed to a process kind and, through the live `persistence_consumers` row of the same pid and nonce, to a host.
* A transaction-mode pooler's server connections carry the pooler's own name, so they are counted apart (`pooler`), never
* attributed. The limit is `GBRAIN_SESSION_LANE_LIMIT` (the pooler's per-role session limit, which Postgres cannot read)
* or, with no pooler in front, the server's `max_connections` minus its reserved slots. Behind a pooler the count is an
* upper bound: this role's connections that bypass the pooler (a direct `db.<ref>` host) are counted too.
*/
import type { BrainEngine } from './engine.ts';
import { isSupabasePoolerUrl } from './connection-manager.ts';
export const SESSION_LANE_LIMIT_ENV = 'GBRAIN_SESSION_LANE_LIMIT';
/** At or above this share of the limit the check warns: one more process of the usual size passes it. */
export const SESSION_LANE_WARN_RATIO = 0.8;
const POOLER_NAMES = /^(supavisor|pgbouncer|odyssey|pgcat)\b/i;
const GBRAIN_NAME = /^gbrain ([^:]+):(\d+):([0-9a-f]{0,8})$/i;
export interface SessionLaneProcess { application_name: string; kind: string; pid: number; host_id: string | null; connections: number }
export interface SessionLaneCensus {
/** This role's client backends in this database. */
total: number;
/** Named by a gbrain pool, a pooler, or anything else. */
gbrain: number; pooler: number; other: number;
by_kind: Record<string, number>;
by_host: Array<{ host_id: string | null; connections: number }>;
processes: SessionLaneProcess[];
limit: number | null;
limit_source: 'env' | 'max_connections' | null;
/** The backends the limit is compared with: this role's against a per-role limit (a pooler's, or the env limit), every client backend against max_connections. */
used: number;
behind_pooler: boolean;
}
export function sessionLaneLimitFromEnv(env: Record<string, string | undefined>): number | null {
const raw = env[SESSION_LANE_LIMIT_ENV]?.trim();
if (!raw) return null;
const value = Number(raw);
return Number.isInteger(value) && value > 0 ? value : null;
}
/** The census from the read rows (pure: the doctor test drives it with fixed rows). */
export function summarizeSessionLane(input: { rows: Array<{ application_name: string | null; connections: number }>; owners: Array<{ pid: number; nonce: string; host_id: string }>;
serverClients: number; serverLimit: number | null; envLimit: number | null; pooledUrl: boolean }): SessionLaneCensus {
let gbrain = 0, pooler = 0, other = 0;
const byKind: Record<string, number> = {};
const processes: SessionLaneProcess[] = [];
for (const row of input.rows) {
const name = row.application_name ?? '';
const match = GBRAIN_NAME.exec(name);
if (match) {
gbrain += row.connections;
const kind = match[1]!, pid = Number(match[2]);
byKind[kind] = (byKind[kind] ?? 0) + row.connections;
const owner = input.owners.find(o => o.pid === pid && o.nonce.slice(0, 8).toLowerCase() === match[3]!.toLowerCase());
processes.push({ application_name: name, kind, pid, host_id: owner?.host_id ?? null, connections: row.connections });
} else if (POOLER_NAMES.test(name)) pooler += row.connections;
else other += row.connections;
}
processes.sort((a, b) => b.connections - a.connections || a.application_name.localeCompare(b.application_name));
const hosts = new Map<string | null, number>();
for (const p of processes) hosts.set(p.host_id, (hosts.get(p.host_id) ?? 0) + p.connections);
const total = gbrain + pooler + other;
const behindPooler = input.pooledUrl || pooler > 0;
const limit = input.envLimit ?? (behindPooler ? null : input.serverLimit);
return { total, gbrain, pooler, other, by_kind: byKind,
by_host: [...hosts].map(([host_id, connections]) => ({ host_id, connections })).sort((a, b) => b.connections - a.connections),
processes, limit, limit_source: input.envLimit !== null ? 'env' : limit !== null ? 'max_connections' : null,
used: behindPooler || input.envLimit !== null ? total : input.serverClients, behind_pooler: behindPooler };
}
/** Reads the census on a Postgres engine (read-only; no query text leaves the server). `urls`: the configured database URLs (a Supabase pooler among them means the limit is the pooler's). `env`: the caller's environment, which holds the limit. */
export async function readSessionLane(engine: BrainEngine, urls: readonly string[], env: Record<string, string | undefined>): Promise<SessionLaneCensus> {
const rows = await engine.executeRaw<{ application_name: string | null; connections: number | string }>(
`SELECT application_name, count(*)::int AS connections FROM pg_stat_activity
WHERE datname = current_database() AND usename = current_user AND backend_type = 'client backend' GROUP BY application_name`);
const [server] = await engine.executeRaw<{ clients: number | string; max_connections: number | string; reserved: number | string }>(
`SELECT (SELECT count(*) FROM pg_stat_activity WHERE backend_type = 'client backend')::int AS clients,
current_setting('max_connections')::int AS max_connections,
(current_setting('superuser_reserved_connections')::int + COALESCE(NULLIF(current_setting('reserved_connections', true), '')::int, 0)) AS reserved`);
const owners = await engine.executeRaw<{ pid: number; nonce: string; host_id: string }>(
`SELECT pid, nonce, host_id::text AS host_id FROM persistence_consumers WHERE renewed_at > now() - interval '10 minutes'`).catch(() => []);
return summarizeSessionLane({ rows: rows.map(row => ({ application_name: row.application_name, connections: Number(row.connections) })),
owners: owners.map(o => ({ pid: Number(o.pid), nonce: String(o.nonce ?? ''), host_id: o.host_id })),
serverClients: Number(server?.clients ?? 0), serverLimit: server ? Number(server.max_connections) - Number(server.reserved) : null,
envLimit: sessionLaneLimitFromEnv(env), pooledUrl: urls.some(isSupabasePoolerUrl) });
}