Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Stable connector identity (#5686).
*
* A connector checkpoint, its admission `configHash`, the publication change
* check and the attachments preview key all derive from the PARSED connector
* config, never from raw `sources.config`: the cycle writes bookkeeping stamps
* (`last_source_cycle_at`, `last_full_cycle_at`) into that blob after every
* run, and other writers pin keys there too. The digest covers every parsed
* leaf except an explicit list of credential-delivery fields, so a field added
* to a parser later joins the identity by default. The resolved account a
* credential belongs to is checked separately against the connector state
* pin (`connector-state.ts`), because excluded credential fields can change
* which account a sweep reads.
*
* #6561: a leaf a parser starts emitting with a default that preserves the
* earlier behavior (Google `contactsDir: 'people'`) declares that default as
* `elideWhen`, and is left out of the digest while it holds it, so unchanged
* sources keep the pre-field checkpoint key. Releases that hashed the default
* wrote checkpoints under the non-elided digest; it stays addressable as an
* alias (`aliasDigests`, `connectorCheckpointKeys`) so those rows are loaded
* by the upgrade migration and never orphaned.
*/
import { digest } from './digest.ts';
import { parseGoogleSourceConfig } from '../google/source-config.ts';
import { parseGitHubSourceConfig } from '../github-source-config.ts';
import type { GitHubSourceConfig } from '../github-source.ts';
import { DEFAULT_CONTACTS_DIR, type GoogleSourceConfig } from '../google/types.ts';
import { parseMeetingsSourceConfig } from '../meetings/source-config.ts';
import type { MeetingsSourceConfig } from '../meetings/types.ts';
import { parseSlackSourceConfig } from '../slack/source-config.ts';
import type { SlackSourceConfig } from '../slack/types.ts';
import { parseIMessageSourceConfig } from '../imessage/source-config.ts';
import type { IMessageSourceConfig } from '../imessage/types.ts';
import { assertNever } from '../types.ts';
import type { ConnectorKind } from './connector-kinds.ts';
export { CONNECTOR_KINDS_SQL, CONNECTOR_SOURCE_KINDS, isConnectorSourceKind, type ConnectorKind } from './connector-kinds.ts';
export type ConnectorConfig = GoogleSourceConfig | GitHubSourceConfig | MeetingsSourceConfig | SlackSourceConfig | IMessageSourceConfig;
type LeafClass = 'identity' | 'excluded';
/** An identity leaf left out of the digest while it holds the default it was introduced with (#6561). */
interface ElidedLeaf { elideWhen: unknown }
type Rule = LeafClass | ElidedLeaf | ((config: GitHubSourceConfig) => LeafClass);
const underAuto = (config: GitHubSourceConfig): LeafClass => config.scope === 'auto' ? 'identity' : 'excluded';
/**
* Every leaf each parser returns, classified. The unit test enumerates parser
* output and fails on a leaf missing here; an unlisted leaf still joins the
* identity at runtime, never the exclusion list.
*/
export const CONNECTOR_LEAF_RULES: { google: Record<string, LeafClass | ElidedLeaf>; github: Record<string, Rule>; meetings: Record<string, LeafClass>; slack: Record<string, LeafClass>;
imessage: Record<string, LeafClass> } = {
google: {
account: 'identity', services: 'identity', historyDays: 'identity', futureDays: 'identity', calendarId: 'identity', dir: 'identity',
contactsDir: { elideWhen: DEFAULT_CONTACTS_DIR },
access: 'excluded', tokenCommand: 'excluded', tokenEnv: 'excluded', loopsExcludeLabels: 'excluded',
},
github: {
scope: 'identity', repos: 'identity', dir: 'identity',
// Under `scope: auto` the repo set is whatever the authenticated identity can see.
tokenEnv: config => config.scope === 'auto' && !config.app ? 'identity' : 'excluded',
app: underAuto, 'app.appId': underAuto, 'app.installId': underAuto, 'app.pemPath': 'excluded',
},
meetings: {
provider: 'identity', historyDays: 'identity', lookbackDays: 'identity', transcript: 'identity', record: 'identity', dir: 'identity', privateOnly: 'identity',
// The key's location and the schedule never change what a sweep reads; the account pin covers a swapped key.
tokenEnv: 'excluded', syncIntervalMin: 'excluded',
},
slack: {
channels: 'identity', historyDays: 'identity', lookbackDays: 'identity', timezone: 'identity', record: 'identity', dir: 'identity', privateOnly: 'identity', skip: 'identity',
// Where the token lives, the schedule and the per-run request cap never change what a sweep reads; the account pin covers a swapped token.
tokenEnv: 'excluded', syncIntervalMin: 'excluded', maxRequests: 'excluded',
},
imessage: {
historyDays: 'identity', lookbackDays: 'identity', timezone: 'identity',
// Where the helper token lives and the schedule never change what a sweep reads.
tokenEnv: 'excluded', syncIntervalMin: 'excluded',
},
};
/** Leaf paths of a parsed config: nested objects flatten to dotted keys; arrays and null are leaves. */
export function connectorConfigLeaves(config: object): Record<string, unknown> {
const leaves: Record<string, unknown> = {};
const walk = (value: Record<string, unknown>, prefix: string) => {
for (const [key, child] of Object.entries(value)) {
if (child === undefined) continue;
const path = prefix ? `${prefix}.${key}` : key;
if (child !== null && typeof child === 'object' && !Array.isArray(child)) walk(child as Record<string, unknown>, path);
else leaves[path] = child;
}
};
walk(config as Record<string, unknown>, '');
return leaves;
}
const leafRule = (kind: ConnectorKind, path: string): Rule | undefined => (CONNECTOR_LEAF_RULES[kind] as Record<string, Rule>)[path];
export function classifyConnectorLeaf(kind: ConnectorKind, config: ConnectorConfig, path: string): LeafClass | undefined {
const rule = leafRule(kind, path);
if (typeof rule === 'function') return rule(config as GitHubSourceConfig);
return typeof rule === 'object' ? 'identity' : rule;
}
/**
* The identity-bearing leaves, canonicalized: set-valued lists sorted and de-duplicated. An elided leaf holding
* its default is left out unless `elide` is false (the digest releases before #6561 computed).
*/
export function connectorIdentityLeaves(kind: ConnectorKind, config: ConnectorConfig, elide = true): Record<string, unknown> {
const identity: Record<string, unknown> = {};
for (const [path, value] of Object.entries(connectorConfigLeaves(config))) {
if (classifyConnectorLeaf(kind, config, path) === 'excluded') continue;
const rule = leafRule(kind, path);
if (elide && typeof rule === 'object' && value === rule.elideWhen) continue;
identity[path] = (path === 'services' || path === 'repos') && Array.isArray(value) ? [...new Set(value.map(String))].sort() : value;
}
return identity;
}
/** `digest` addresses the checkpoint; `aliasDigests` are earlier releases' digests of the same config (#6561). */
export interface ConnectorIdentity { kind: ConnectorKind; config: ConnectorConfig; digest: string; aliasDigests: string[] }
export function parseConnectorConfig(kind: ConnectorKind, raw: Record<string, unknown>, localPath: string | null): ConnectorConfig {
switch (kind) {
case 'google': return parseGoogleSourceConfig(raw, localPath ?? '');
case 'github': return parseGitHubSourceConfig(raw, localPath ?? '');
case 'meetings': return parseMeetingsSourceConfig(raw, localPath ?? '');
case 'slack': return parseSlackSourceConfig(raw, localPath ?? '');
case 'imessage': return parseIMessageSourceConfig(raw);
default: return assertNever(kind);
}
}
/** The parsed connector config plus its identity digest. The raw config is never an identity. */
export function connectorIdentity(kind: ConnectorKind, raw: Record<string, unknown>, localPath: string | null): ConnectorIdentity {
const config = parseConnectorConfig(kind, raw, localPath);
const canonical = digest({ kind, identity: connectorIdentityLeaves(kind, config) });
const interim = digest({ kind, identity: connectorIdentityLeaves(kind, config, false) });
return { kind, config, digest: canonical, aliasDigests: interim === canonical ? [] : [interim] };
}
/** True when `configHash` (frozen on an admitted write) names this identity under its canonical or an alias digest. */
export function connectorIdentityMatches(identity: Pick<ConnectorIdentity, 'digest' | 'aliasDigests'>, configHash: string): boolean {
return configHash === identity.digest || identity.aliasDigests.includes(configHash);
}
export function connectorCheckpointKey(sourceId: string, incarnation: string, identity: Pick<ConnectorIdentity, 'kind' | 'digest'>): string {
return digest({ sourceId, incarnation, connector: identity.kind, identity: identity.digest });
}
/** Every key a source's checkpoint may live under: the canonical key first, then its alias keys. */
export function connectorCheckpointKeys(sourceId: string, incarnation: string, identity: Pick<ConnectorIdentity, 'kind' | 'digest' | 'aliasDigests'>): string[] {
return [identity.digest, ...identity.aliasDigests].map(d => connectorCheckpointKey(sourceId, incarnation, { kind: identity.kind, digest: d }));
}
/** Legacy and current connector intent namespaces; every filter on connector kinds uses these. */
export const CONNECTOR_INTENT_PREFIXES = ['connector_v2_', 'managed_connector_'] as const;
export function isConnectorIntentKind(kind: unknown): boolean {
return typeof kind === 'string' && CONNECTOR_INTENT_PREFIXES.some(prefix => kind.startsWith(prefix));
}
/** SQL predicate over a `persistence_requests` alias accepting both connector namespaces. */
export function connectorIntentSql(alias = 'persistence_requests'): string {
return `(${alias}.intent->>'kind' LIKE 'connector\\_v2\\_%' OR ${alias}.intent->>'kind' LIKE 'managed\\_connector\\_%')`;
}
/** Checkpoint receipts in either namespace (the migration reads legacy ones). */
export const CONNECTOR_CHECKPOINT_KINDS = ['connector_v2_checkpoint', 'managed_connector_checkpoint'] as const;