Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Pinned-question rows: reads, idempotent pin, state changes and the durable
* refresh lease. SQL runs through `engine.executeRaw` on the pinned_questions
* table (not a canonical-writer table, so no coordinator capability is needed);
* the question page itself is written by ./pages.ts through the coordinator.
*/
import type { BrainEngine } from '../engine.ts';
import { formatQuestionId, type QuestionScope } from './identity.ts';
export type PinState = 'active' | 'inactive' | 'archived';
export type InactiveReason = 'awaiting_consent' | 'migrated_disabled' | 'migrated_zero_budget' | 'migrated_enabled';
export type PublishMode = 'publish' | 'draft';
export type SentenceOrigin = 'model' | 'owner';
export interface AnswerSentence {
id: string;
text: string;
origin: SentenceOrigin;
}
export interface PinRow {
id: number;
source_id: string;
slug: string;
question: string;
scope_slug_prefix: string | null;
scope_entity: string | null;
state: PinState;
inactive_reason: InactiveReason | null;
publish_mode: PublishMode;
model: string | null;
cooldown_days: number | null;
origin: string;
created_by: string;
revision: number;
answer_revision: number;
answer: AnswerSentence[];
answer_model: string | null;
last_refresh_at: Date | null;
last_attempt_at: Date | null;
last_error: string | null;
watermark_generation: number | null;
watermark_fact_id: number | null;
watermark_at: Date | null;
lease_token: string | null;
lease_owner: string | null;
lease_expires_at: Date | null;
refresh_attempts: number;
spend_usd: number;
created_at: Date;
archived_at: Date | null;
}
const COLUMNS = `id, source_id, slug, question, scope_slug_prefix, scope_entity, state, inactive_reason, publish_mode, model,
cooldown_days, origin, created_by, revision, answer_revision, answer, answer_model, last_refresh_at, last_attempt_at,
last_error, watermark_generation, watermark_fact_id, watermark_at, lease_token, lease_owner, lease_expires_at,
refresh_attempts, spend_usd, created_at, archived_at`;
const date = (v: unknown): Date | null => v === null || v === undefined ? null : v instanceof Date ? v : new Date(String(v));
const num = (v: unknown): number | null => v === null || v === undefined ? null : Number(v);
export function parseAnswer(raw: unknown): AnswerSentence[] {
if (typeof raw !== 'string' || raw === '') return [];
try {
const parsed = JSON.parse(raw);
if (!Array.isArray(parsed)) return [];
return parsed.filter((s): s is AnswerSentence => s && typeof s.id === 'string' && typeof s.text === 'string'
&& (s.origin === 'model' || s.origin === 'owner'));
} catch {
return [];
}
}
export function toPinRow(r: Record<string, unknown>): PinRow {
return {
id: Number(r.id), source_id: String(r.source_id), slug: String(r.slug), question: String(r.question),
scope_slug_prefix: (r.scope_slug_prefix as string | null) ?? null, scope_entity: (r.scope_entity as string | null) ?? null,
state: r.state as PinState, inactive_reason: (r.inactive_reason as InactiveReason | null) ?? null,
publish_mode: r.publish_mode === 'draft' ? 'draft' : 'publish', model: (r.model as string | null) ?? null,
cooldown_days: num(r.cooldown_days), origin: String(r.origin), created_by: String(r.created_by),
revision: Number(r.revision), answer_revision: Number(r.answer_revision), answer: parseAnswer(r.answer),
answer_model: (r.answer_model as string | null) ?? null, last_refresh_at: date(r.last_refresh_at),
last_attempt_at: date(r.last_attempt_at), last_error: (r.last_error as string | null) ?? null,
watermark_generation: num(r.watermark_generation), watermark_fact_id: num(r.watermark_fact_id), watermark_at: date(r.watermark_at),
lease_token: (r.lease_token as string | null) ?? null, lease_owner: (r.lease_owner as string | null) ?? null,
lease_expires_at: date(r.lease_expires_at), refresh_attempts: Number(r.refresh_attempts ?? 0),
spend_usd: Number(r.spend_usd ?? 0), created_at: date(r.created_at)!, archived_at: date(r.archived_at),
};
}
export function pinId(row: Pick<PinRow, 'source_id' | 'slug'>): string {
return formatQuestionId(row.source_id, row.slug);
}
export function pinScope(row: Pick<PinRow, 'source_id' | 'scope_slug_prefix' | 'scope_entity'>): QuestionScope {
return {
source: row.source_id,
...(row.scope_slug_prefix ? { slug_prefix: row.scope_slug_prefix } : {}),
...(row.scope_entity ? { entity: row.scope_entity } : {}),
};
}
export async function getPin(engine: BrainEngine, sourceId: string, slug: string, opts: { forUpdate?: boolean } = {}): Promise<PinRow | null> {
const rows = await engine.executeRaw<Record<string, unknown>>(
`SELECT ${COLUMNS} FROM pinned_questions WHERE source_id = $1 AND slug = $2${opts.forUpdate ? ' FOR UPDATE' : ''}`, [sourceId, slug]);
return rows[0] ? toPinRow(rows[0]) : null;
}
export async function listPins(engine: BrainEngine, opts: { sourceIds?: string[]; includeArchived?: boolean; states?: PinState[] } = {}): Promise<PinRow[]> {
const params: unknown[] = [];
const where: string[] = [];
if (opts.sourceIds) { params.push(opts.sourceIds); where.push(`source_id = ANY($${params.length}::text[])`); }
if (opts.states) { params.push(opts.states); where.push(`state = ANY($${params.length}::text[])`); }
else if (!opts.includeArchived) where.push(`state <> 'archived'`);
const rows = await engine.executeRaw<Record<string, unknown>>(
`SELECT ${COLUMNS} FROM pinned_questions ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY source_id, created_at, id`, params);
return rows.map(toPinRow);
}
export interface PinInsert {
sourceId: string;
slug: string;
question: string;
scope: QuestionScope;
state: PinState;
inactiveReason: InactiveReason | null;
publishMode: PublishMode;
createdBy: string;
}
/** Idempotent insert keyed on (source_id, slug). Returns the row and whether it was created. */
export async function insertPin(engine: BrainEngine, p: PinInsert): Promise<{ row: PinRow; created: boolean }> {
const inserted = await engine.executeRaw<Record<string, unknown>>(
`INSERT INTO pinned_questions (source_id, slug, question, scope_slug_prefix, scope_entity, state, inactive_reason, publish_mode, created_by)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
ON CONFLICT (source_id, slug) DO NOTHING RETURNING ${COLUMNS}`,
[p.sourceId, p.slug, p.question, p.scope.slug_prefix ?? null, p.scope.entity ?? null, p.state, p.inactiveReason, p.publishMode, p.createdBy]);
if (inserted[0]) return { row: toPinRow(inserted[0]), created: true };
return { row: (await getPin(engine, p.sourceId, p.slug))!, created: false };
}
/** State change that bumps the pin revision, so an in-flight refresh revalidating at commit sees it. */
export async function updatePinState(engine: BrainEngine, id: number, patch: {
state?: PinState; inactiveReason?: InactiveReason | null; publishMode?: PublishMode;
}): Promise<PinRow> {
const rows = await engine.executeRaw<Record<string, unknown>>(
`UPDATE pinned_questions SET
state = COALESCE($2, state),
inactive_reason = CASE WHEN $3::boolean THEN $4 ELSE inactive_reason END,
publish_mode = COALESCE($5, publish_mode),
archived_at = CASE WHEN COALESCE($2, state) = 'archived' THEN COALESCE(archived_at, now()) ELSE NULL END,
lease_token = CASE WHEN COALESCE($2, state) = 'archived' THEN NULL ELSE lease_token END,
lease_expires_at = CASE WHEN COALESCE($2, state) = 'archived' THEN NULL ELSE lease_expires_at END,
revision = revision + 1, updated_at = now()
WHERE id = $1 RETURNING ${COLUMNS}`,
[id, patch.state ?? null, patch.inactiveReason !== undefined, patch.inactiveReason ?? null, patch.publishMode ?? null]);
return toPinRow(rows[0]!);
}
/**
* Durable refresh lease. A second worker (or a duplicate cycle) gets null
* while a live lease exists; an expired lease (a crashed worker) is taken over.
*/
export async function acquireLease(engine: BrainEngine, id: number, token: string, owner: string, ttlMs: number): Promise<PinRow | null> {
const rows = await engine.executeRaw<Record<string, unknown>>(
`UPDATE pinned_questions SET lease_token = $2, lease_owner = $3,
lease_expires_at = now() + ($4::double precision * interval '1 millisecond'),
last_attempt_at = now(), refresh_attempts = refresh_attempts + 1
WHERE id = $1 AND state <> 'archived' AND (lease_token IS NULL OR lease_expires_at IS NULL OR lease_expires_at < now())
RETURNING ${COLUMNS}`, [id, token, owner, ttlMs]);
return rows[0] ? toPinRow(rows[0]) : null;
}
/** Ends a refresh attempt without publishing: keeps the previous answer, records the cause and spend. */
export async function releaseLease(engine: BrainEngine, id: number, token: string, outcome: { error: string | null; spendUsd: number }): Promise<void> {
await engine.executeRaw(
`UPDATE pinned_questions SET lease_token = NULL, lease_owner = NULL, lease_expires_at = NULL,
last_error = $3, spend_usd = spend_usd + $4, updated_at = now()
WHERE id = $1 AND lease_token = $2`, [id, token, outcome.error, outcome.spendUsd]);
}
export async function addSpend(engine: BrainEngine, id: number, usd: number): Promise<void> {
if (usd > 0) await engine.executeRaw('UPDATE pinned_questions SET spend_usd = spend_usd + $2 WHERE id = $1', [id, usd]);
}