Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Per-source connector state row (#5686, #5600): one `op_checkpoints` row per
* source incarnation (`op='managed-connector-state'`, fingerprint
* `digest({sourceId, incarnation})`), independent of the identity digest so a
* content-config change or a checkpoint reset never loses it. It holds the
* resolved account pin, the pending receipts a run ended with, the upgrade
* recovery disclosure and the last run's counts. The connector session writes
* it only while it holds the connector sync lease; the upgrade migration seeds
* `upgrade_recovery`. The 7-day checkpoint purge never touches it.
*
* `first_attempt_at` (#5673, DX O1) is the autopilot dispatch gate: it is
* stamped once, before the first provider call of a validated, non-preview
* explicit or scheduled sync of a managed or unmanaged connector source, even
* when that run later fails.
*/
import type { BrainEngine } from '../engine.ts';
import { digest } from './digest.ts';
import { parseSourceConfig } from '../sources-load.ts';
import { assertNever } from '../types.ts';
export const CONNECTOR_STATE_OP = 'managed-connector-state';
export type ConnectorAccount =
| { kind: 'google'; email: string }
| { kind: 'github'; installationId: number | null; login: string | null }
| { kind: 'meetings'; provider: string; userId: string; email: string | null }
| { kind: 'slack'; teamId: string; enterpriseId: string | null };
export interface ConnectorPendingEntry {
/** The page slug, or `__managed_connector_checkpoint__` for a checkpoint save. */
itemRef: string;
requestId: string;
/** The stable request identity the retry-pointer path keys on. */
baseRequestId: string;
admittedAt: string;
}
export interface ConnectorRunCounts {
page_admissions: number;
skipped_unchanged: number;
pending: number;
checkpoint_admissions: number;
stopped_on_wait_budget: boolean;
dropped_upstream: number;
finished_at: string;
/** #6831: items the pages guard refused as purged content this run; each was skipped and the run went on. */
purged_skipped?: number;
}
/** #6831: one connector item whose content matches a page purge tombstone, skipped instead of written. */
export interface ConnectorPurgedItem {
slug: string;
/** The refused receipt, or null when the item was screened out before admission. */
request_id: string | null;
at: string;
}
/**
* #6831: the last connector run that ended on an error instead of finishing.
* `consecutive` counts runs in a row that ended this way; a run that finishes clears it.
*/
export interface ConnectorRunFailure {
code: string;
message: string;
slug: string | null;
request_id: string | null;
at: string;
consecutive: number;
}
export type UpgradeRecovery = 'resumed' | 'rewalking_once' | 'none';
export interface ConnectorState {
version: 1;
account: ConnectorAccount | null;
pinned_at: string | null;
/** Earlier account continuity cannot be proven (a migrated source pinned on its first post-upgrade run). */
continuity_unverified: boolean;
pending: ConnectorPendingEntry[];
upgrade_recovery: UpgradeRecovery;
resumed_from: string | null;
last_run: ConnectorRunCounts | null;
/**
* Fix wave 4 (DX O1, #5673): the first recorded sync attempt, written before
* the first provider call of an explicit or scheduled sync (managed and
* unmanaged), including one that later fails. Autopilot dispatches only
* connector sources that have one; checkpoint-row existence never counts.
*/
first_attempt_at?: string | null;
/**
* #6803: the last account check refused with `connector_account_changed`.
* Autopilot skips the source (unavailable-path) while the connector config
* still digests to `config_digest`; a sync that passes the check clears it.
*/
account_mismatch?: ConnectorAccountMismatch | null;
/** #6831: the most recent purged items connector runs skipped (newest first, at most CONNECTOR_PURGED_LIMIT). */
purged_items?: ConnectorPurgedItem[];
/** #6831: set while the source's connector runs keep ending on an error; cleared by a run that finishes. */
last_failure?: ConnectorRunFailure | null;
}
/** #6831: how many skipped purged items the state row keeps. */
export const CONNECTOR_PURGED_LIMIT = 20;
/** #6831: this many connector runs in a row that ended on an error read as a stopped source in `sources status` and doctor. */
export const CONNECTOR_STOPPED_RUNS = 3;
export interface ConnectorAccountMismatch {
at: string;
detail: 'account_changed' | 'account_unresolved';
/** `connectorConfigDigest` of the config the refused run read (credential settings included). */
config_digest: string;
}
export const emptyConnectorState = (): ConnectorState => ({ version: 1, account: null, pinned_at: null, continuity_unverified: false,
pending: [], upgrade_recovery: 'none', resumed_from: null, last_run: null, first_attempt_at: null, account_mismatch: null, purged_items: [], last_failure: null });
export function connectorStateKey(sourceId: string, incarnation: string): string {
return digest({ sourceId, incarnation });
}
export async function readManagedConnectorState(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, incarnation: string): Promise<ConnectorState> {
const [row] = await engine.executeRaw<{ completed_keys: ConnectorState[] }>(
'SELECT completed_keys FROM op_checkpoints WHERE op=$1 AND fingerprint=$2', [CONNECTOR_STATE_OP, connectorStateKey(sourceId, incarnation)]);
const stored = row?.completed_keys?.[0];
return stored?.version === 1 ? { ...emptyConnectorState(), ...stored } : emptyConnectorState();
}
/**
* Upserts the state row. With `lease`, the write happens only while that
* connector sync lease is still held (checked in the same statement) and
* returns false otherwise; the upgrade migration seeds rows without a lease.
*/
export async function writeManagedConnectorState(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, incarnation: string, state: ConnectorState,
lease?: { id: string; token: string; acquiredAt: string }): Promise<boolean> {
// FOR SHARE holds the lease row for this statement: a concurrent takeover waits, and one already made fails the match.
const rows = await engine.executeRaw<{ op: string }>(`WITH lease AS (SELECT id FROM gbrain_cycle_locks
WHERE id=$4 AND acquisition_token=$5::uuid AND extract(epoch from acquired_at)::text=$6 AND ttl_expires_at>now() FOR SHARE)
INSERT INTO op_checkpoints(op,fingerprint,completed_keys)
SELECT $1,$2,$3::text::jsonb WHERE $4::text IS NULL OR EXISTS (SELECT 1 FROM lease)
ON CONFLICT(op,fingerprint) DO UPDATE SET completed_keys=EXCLUDED.completed_keys,updated_at=now() RETURNING op`,
[CONNECTOR_STATE_OP, connectorStateKey(sourceId, incarnation), JSON.stringify([state]), lease?.id ?? null, lease?.token ?? null, lease?.acquiredAt ?? null]);
return rows.length > 0;
}
/**
* Records the source's first sync attempt once (idempotent, one statement: an
* existing stamp and every other state field are kept, so it never races the
* lease holder's state write). Returns false when the source does not exist.
*/
export async function recordConnectorSyncAttempt(engine: Pick<BrainEngine, 'executeRaw'>, sourceId: string, at = new Date().toISOString()): Promise<boolean> {
const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
if (!source) return false;
await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES($1,$2,$3::text::jsonb)
ON CONFLICT(op,fingerprint) DO UPDATE SET completed_keys=jsonb_set(op_checkpoints.completed_keys, ARRAY['0','first_attempt_at'], to_jsonb($4::text), true), updated_at=now()
WHERE op_checkpoints.completed_keys->0->>'first_attempt_at' IS NULL`,
[CONNECTOR_STATE_OP, connectorStateKey(sourceId, source.incarnation), JSON.stringify([{ ...emptyConnectorState(), first_attempt_at: at }]), at]);
return true;
}
/**
* v181 (fix wave 4): records an attempt for every connector source the
* pre-upgrade freshness loop dispatched (active, non-null local_path and not
* `syncEnabled=false`), so the new gate idles no source autopilot synced.
*/
export async function seedConnectorDispatchAttempts(engine: Pick<BrainEngine, 'executeRaw'>): Promise<number> {
const rows = await engine.executeRaw<{ id: string; config: unknown }>(
'SELECT id,config FROM sources WHERE local_path IS NOT NULL AND archived IS NOT TRUE');
let seeded = 0;
const at = new Date().toISOString();
for (const row of rows) {
// parseSourceConfig, as the dispatch loops read it (string-wrapped configs included). The syncEnabled test is
// isSyncDisabledConfig's (sync-policy.ts), inlined so the schema-migration closure stays small.
const config = parseSourceConfig(row.config);
if (config.kind !== 'google' && config.kind !== 'github') continue;
if (config.syncEnabled === false) continue;
await recordConnectorSyncAttempt(engine, row.id, at);
seeded++;
}
return seeded;
}
/** Connector source ids (google, github) with a recorded sync attempt: the autopilot dispatch gate. */
export async function attemptedConnectorSourceIds(engine: Pick<BrainEngine, 'executeRaw'>): Promise<Set<string>> {
// Every source: only connector syncs stamp the field, and a string-wrapped config would miss a kind filter here.
const sources = await engine.executeRaw<{ id: string; incarnation: string }>('SELECT id,incarnation::text AS incarnation FROM sources');
if (sources.length === 0) return new Set();
const keys = new Map(sources.map(source => [connectorStateKey(source.id, source.incarnation), source.id]));
const rows = await engine.executeRaw<{ fingerprint: string }>(`SELECT fingerprint FROM op_checkpoints
WHERE op=$1 AND fingerprint=ANY($2::text[]) AND completed_keys->0->>'version'='1' AND completed_keys->0->>'first_attempt_at' IS NOT NULL`,
[CONNECTOR_STATE_OP, [...keys.keys()]]);
return new Set(rows.map(row => keys.get(row.fingerprint)!));
}
/** Account pins compare the resolved identity only; the recorded display never includes credentials. */
export function sameConnectorAccount(a: ConnectorAccount, b: ConnectorAccount): boolean {
if (a.kind !== b.kind) return false;
switch (a.kind) {
case 'google': return a.email === (b as typeof a).email;
case 'github': {
const other = b as typeof a;
return (a.installationId ?? null) === (other.installationId ?? null) && (a.login ?? null)?.toLowerCase() === (other.login ?? null)?.toLowerCase();
}
case 'meetings': {
const other = b as typeof a;
return a.provider === other.provider && a.userId === other.userId;
}
case 'slack': {
const other = b as typeof a;
return a.teamId === other.teamId && (a.enterpriseId ?? null) === (other.enterpriseId ?? null);
}
default: return assertNever(a);
}
}
export function describeConnectorAccount(account: ConnectorAccount): string {
switch (account.kind) {
case 'google': return account.email;
case 'github': return [account.installationId !== null ? `installation ${account.installationId}` : null, account.login ? `login ${account.login}` : null]
.filter(Boolean).join(', ') || 'no installation or login';
case 'meetings': return `${account.provider} user ${account.userId}${account.email ? ` (${account.email})` : ''}`;
case 'slack': return `Slack workspace ${account.teamId}${account.enterpriseId ? ` (enterprise ${account.enterpriseId})` : ''}`;
default: return assertNever(account);
}
}