Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix(facts): the brain owner gets private facts in query, think, hot memory, delta and question-ranked recall (GST-2089)
garrytan46acb6c2c0af
diff --git a/src/core/context/turn-context.ts b/src/core/context/turn-context.tsindex 8451c57b1d..b8093fd108 100644--- a/src/core/context/turn-context.ts+++ b/src/core/context/turn-context.ts@@ -798,8 +798,8 @@ async function assembleDelta(if (!pastDeadline()) {try {const after = opts.factsAfter ?? (since ? { at: since, id: null } : null);- const visibility = remote ? (['world'] as ('private' | 'world')[]) : undefined;- const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');+ const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');+ const visibility = worldOnlyFacts(remote) ? (['world'] as ('private' | 'world')[]) : undefined;const excludePrivate = await resolveExcludePrivatePages(engine, remote ? undefined : false);const rows = await engine.listFactsKeyset(opts.sourceId,diff --git a/src/core/facts/meta-hook.ts b/src/core/facts/meta-hook.tsindex f7f0a9cc78..c172279e79 100644--- a/src/core/facts/meta-hook.ts+++ b/src/core/facts/meta-hook.ts@@ -44,7 +44,7 @@ import { partitionForActivation, suppressionSummary } from '../eligibility/activimport { trustFields } from '../eligibility/labels.ts';import { quoteFacts } from '../search/transcript-quote.ts';import { eligibilityCacheField, readTrustGeneration } from '../eligibility/generation.ts';-import { callerRelaxesPrivacy, resolveExcludePrivatePages } from '../search/private-visibility.ts';+import { callerRelaxesPrivacy, resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';import { isConfigTruthy } from '../config.ts';import { callerIdentityKey } from '../access/member-facts.ts';@@ -160,7 +160,10 @@ export async function getBrainHotMemoryMeta(// read returns, so it is part of the tier too.const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);// GBRA-218: on a brain with member restrictions a relaxed read still applies the readers part, so it has its own tier.- const tier = ctx.remote === false ? 'all' : !excludePrivate ? 'world+private-pages' : callerRelaxesPrivacy() ? 'world+private-pages-readers' : 'world';+ // GST-2089: the brain owner reads private facts too, so its remote tier is marked apart from every world-only tier.+ const worldOnly = worldOnlyFacts(ctx.remote);+ const pageTier = !excludePrivate ? 'world+private-pages' : callerRelaxesPrivacy() ? 'world+private-pages-readers' : 'world';+ const tier = ctx.remote === false ? 'all' : worldOnly ? pageTier : `private-facts+${pageTier}`;// encodeCacheField (F5): source_id / session_id are caller-controlled and// may contain the '::' delimiter; percent-encode ':' so bumpHotMemoryCache's// split('::') can never mis-slice a component.@@ -215,8 +218,8 @@ export async function getBrainHotMemoryMeta(};// Build a fresh payload. Visibility tier: remote → world-only;- // local → all rows.- const visibility = ctx.remote === false ? undefined : ['world'] as ('world' | 'private')[];+ // local and the brain owner → all rows.+ const visibility = worldOnly ? ['world'] as ('world' | 'private')[] : undefined;// Floor, quarantined pages and needs_rederive apply in SQL; activation// control runs after ranking so the withheld count can be reported.diff --git a/src/core/ops/facts.ts b/src/core/ops/facts.tsindex 9dbe67882c..e12fca7489 100644--- a/src/core/ops/facts.ts+++ b/src/core/ops/facts.ts@@ -365,11 +365,9 @@ const recall: Operation = {const scalarSource = factSources.length === 1 ? factSources[0] : undefined;// Visibility filter: remote callers see world-only facts; the local CLI and (GST-2059) the brain owner see all.- const { resolveExcludePrivatePages, callerIsOwner } = await import('../search/private-visibility.ts');- const visibility =- ctx.remote === false || callerIsOwner()- ? undefined- : ['world'] as ('private' | 'world')[];+ const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');+ const worldOnly = worldOnlyFacts(ctx.remote);+ const visibility = worldOnly ? ['world'] as ('private' | 'world')[] : undefined;const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote); // #4352: fact and page arms alikeconst eligibility = await resolveReadEligibility(ctx, { minTrust: p.min_trust }); // #5575 floor + quarantine/rederive hiding@@ -433,7 +431,7 @@ const recall: Operation = {if (question !== null && !readsNoSource) {ranking = await rankFactsByQuestion(ctx, { question, params: p, factSources, limit, entity: entityParam, sessionId: sessionParam, since, grep, includeExpired,- scope: { sourceIds: factSources, remote: ctx.remote !== false, excludePrivate, minTrust: eligibility.floor, suppressFlagged: eligibility.suppressFlagged } });+ scope: { sourceIds: factSources, worldOnly, excludePrivate, minTrust: eligibility.floor, suppressFlagged: eligibility.suppressFlagged } });({ rows, ambiguousEntity } = ranking);for (const notice of questionRecallNotices(ranking, ctx.brainId)) ctx.emitNotice?.(notice);} else if (p.supersessions === true) {diff --git a/src/core/ops/qm-memory.ts b/src/core/ops/qm-memory.tsindex 21e46fef0e..5e34df66cb 100644--- a/src/core/ops/qm-memory.ts+++ b/src/core/ops/qm-memory.ts@@ -149,7 +149,7 @@ async function recallFacts(ctx: OperationContext, query: string, maxChars: numbeconst { rankFactsByQuestion } = await import('../facts/question-recall.ts');const ranked = query && sources.length ? (await rankFactsByQuestion(ctx, {question: query, params: { question: query }, factSources: sources, limit: MEMORY_RECALL_ARM_LIMIT, entity: null, sessionId: null, since: null, grep: null,- scope: { sourceIds: sources, remote, excludePrivate: read.excludePrivate, minTrust: read.eligibility.floor, suppressFlagged: read.eligibility.suppressFlagged },+ scope: { sourceIds: sources, worldOnly: remote, excludePrivate: read.excludePrivate, minTrust: read.eligibility.floor, suppressFlagged: read.eligibility.suppressFlagged },})).rows : [];const seen = new Set<number>();const rows = [...own, ...ranked].filter(r => !seen.has(r.id) && !!seen.add(r.id));diff --git a/src/core/search/fact-relevance.ts b/src/core/search/fact-relevance.tsindex a417c38b3d..a3b5397958 100644--- a/src/core/search/fact-relevance.ts+++ b/src/core/search/fact-relevance.ts@@ -82,7 +82,9 @@ export const FACTS_ARM_COSINE_MIN = 0.6;export const FACT_ADMISSION_FLOOR_EVIDENCE: Readonly<Record<string, string>> = {};export interface FactPoolScope {- sourceId?: string; sourceIds?: string[]; remote: boolean;+ sourceId?: string; sourceIds?: string[];+ /** World-only facts: worldOnlyFacts(remote) for the caller (private facts only for the local CLI and the brain owner). */+ worldOnly: boolean;/** #5575 read floor and activation control, applied in the pool SQL like every retrieval arm. */minTrust?: TrustTier; suppressFlagged?: boolean;/** Hide facts whose provenance page is private (resolveExcludePrivatePages for the caller). */@@ -151,7 +153,7 @@ function poolPredicate(scope: FactPoolScope, filters: FactPoolFilters | undefinefilters?.includeExpired ? 'f.source_id = ANY($1::text[])' : 'f.source_id = ANY($1::text[]) AND f.expired_at IS NULL AND f.superseded_by IS NULL',filters?.includeExpired ? 'f.source != ALL($2::text[])' : '(f.valid_until IS NULL OR f.valid_until > now()) AND f.source != ALL($2::text[])',quarantinedProvenanceFilterFragment('f'),- ...(scope.remote ? [factVisibilitySql('f', ['world'])] : []),+ ...(scope.worldOnly ? [factVisibilitySql('f', ['world'])] : []),...(scope.excludePrivate ? [privateProvenanceFilterUnderPolicy('f')] : []),projectionEligibleSql('facts', 'f', { floor: scope.minTrust, suppressFlagged: scope.suppressFlagged }),];diff --git a/src/core/search/facts-arm.ts b/src/core/search/facts-arm.tsindex 2c839a5555..380adbb840 100644--- a/src/core/search/facts-arm.ts+++ b/src/core/search/facts-arm.ts@@ -19,7 +19,7 @@*/import type { BrainEngine } from '../engine.ts';import type { PageReadScope, SearchResult } from '../types.ts';-import { resolveExcludePrivatePages } from './private-visibility.ts';+import { resolveExcludePrivatePages, worldOnlyFacts } from './private-visibility.ts';import { admitted, collectFactCandidates, FACTS_ARM_COSINE_MIN, queryTerms, scoreFactCandidates, type FactCandidate as PoolCandidate, type FactPoolScope } from './fact-relevance.ts';import { pageReadFilter } from './read-policy-sql.ts';import { enforceTokenBudget, resultTokens } from './token-budget.ts';@@ -76,7 +76,7 @@ export interface FactsArmScope {type FactCandidate = PoolCandidate;async function poolScope(engine: BrainEngine, scope: FactsArmScope): Promise<FactPoolScope> {- return { ...scope, excludePrivate: await resolveExcludePrivatePages(engine, scope.remote) };+ return { ...scope, worldOnly: worldOnlyFacts(scope.remote), excludePrivate: await resolveExcludePrivatePages(engine, scope.remote) };}const day = (v: Date | string | null) => (v ? new Date(v).toISOString().slice(0, 10) : null);diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.tsindex 65ee019c4d..1082c81b80 100644--- a/src/core/search/private-visibility.ts+++ b/src/core/search/private-visibility.ts@@ -302,6 +302,15 @@ export function callerIsOwner(): boolean {return currentCallerAccess().owner;}+/**+ * GST-2089: whether a fact read stays world-only (visibility = 'world'). Only the trusted local CLI (remote strictly+ * false) and the brain owner (CallerAccess.owner, the page rule) read private facts; provenance, source grants and+ * member access still apply to both. Fact arms decide their visibility list here and nowhere else.+ */+export function worldOnlyFacts(remote: boolean | undefined): boolean {+ return remote !== false && !callerIsOwner();+}+/** The current caller's member identity; empty outside a bound remote read or a local --as, and for an audience of several entries (see callerIdentities). */export function callerIdentity(): readonly string[] {return currentCallerAccess().identity;diff --git a/src/core/think/index.ts b/src/core/think/index.tsindex d81f8f51be..79c21e9ec8 100644--- a/src/core/think/index.ts+++ b/src/core/think/index.ts@@ -37,7 +37,7 @@ import { normalizeModelId } from '../model-id.ts';import { hasAnthropicKey } from '../ai/anthropic-key.ts';import { resolveThinkWindow, trajectoryPointsInWindow } from './temporal-window.ts';import { resolveThinkTemporalContext } from './temporal-context.ts';-import { resolveExcludePrivatePages } from '../search/private-visibility.ts';+import { resolveExcludePrivatePages, worldOnlyFacts } from '../search/private-visibility.ts';import { deliverEvidence, effectivePlan, resolveEvidencePlan, EVIDENCE_BLOCK_CHAR_CAP, THINK_RETURN_UNIT_CONFIG_KEY, type DeliveryMeta } from '../search/evidence-delivery.ts';import { evidenceTitlesEnabled } from '../search/evidence-date.ts';import { startThinkDecide, thinkAbstainResult, type ThinkAbstention } from './decide.ts';@@ -771,7 +771,7 @@ export async function runThink(entitySlug: resolved.slug,...(opts.sourceId !== undefined ? { sourceId: opts.sourceId } : {}),...(opts.allowedSources !== undefined ? { sourceIds: opts.allowedSources } : {}),- ...(opts.remote !== undefined ? { remote: opts.remote } : {}),+ ...(opts.remote !== undefined ? { remote: worldOnlyFacts(opts.remote) } : {}),excludePrivate,kind: 'all',limit: 100,diff --git a/test/access-owner-reads.test.ts b/test/access-owner-reads.test.tsindex 1228fee4e7..9b5422d4ce 100644--- a/test/access-owner-reads.test.ts+++ b/test/access-owner-reads.test.ts@@ -27,6 +27,7 @@ import { bindCredential } from '../src/core/access/members.ts';import { accessCheck } from '../src/commands/access.ts';import { openAsPreview } from '../src/cli/as-preview.ts';import type { AuthInfo } from '../src/core/ops/contract.ts';+import { getBrainHotMemoryMeta, __resetHotMemoryCacheForTests } from '../src/core/facts/meta-hook.ts';import { testBackends } from './helpers/test-backends.ts';import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';@@ -55,6 +56,12 @@ const OPEN = { slug: 'notes/open-plan', canary: 'canaryownopen' };/** Another person's page: member access keeps it from the owner too. */const BOBS = { slug: 'notes/bob-plan', canary: 'canaryownbob' };const PRIVATE_FACT = 'canaryownfact';+/** GST-2089: a private dated fact about a person, which think's trajectory reads. */+const PERSON = 'people/carol-example';+const PRIVATE_TRAJECTORY = 'canaryowntraj';+/** Private facts the owner must not read: one taken from another person's readable_by page, one in a source its grant does not read. */+const BOBS_FACT = 'canaryownbobfact';+const UNGRANTED_FACT = 'canaryownungranted';const pageText = (title: string, canary: string, fm: readonly string[]) =>['---', ...(fm.some(l => l.startsWith('type:')) ? [] : ['type: note']), `title: ${title}`, ...fm, '---', `# ${title}`, '', `Harbor ledger planning notes ${canary} for the roadmap.`].join('\n');@@ -77,13 +84,13 @@ for (const kind of testBackends()) {const tokens: Record<string, string> = {};const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });- async function call(who: string, op: string, params: Record<string, unknown>, header?: string): Promise<{ isError: boolean; text: string; meta: Record<string, unknown> | undefined }> {+ async function call(who: string, op: string, params: Record<string, unknown>, header?: string, extra: { metaHook?: typeof getBrainHotMemoryMeta } = {}): Promise<{ isError: boolean; text: string; meta: Record<string, unknown> | undefined }> {const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;const sourceId = auth.sourceId ?? 'default';const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);const out = await dispatchToolCall(engine, op, { ...params }, {remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],- ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}),+ ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), ...(header ? { onBehalfOf: { header } } : {}), ...extra,});return { isError: out.isError === true, text: out.content.map(c => c.text).join('\n'), meta: out._meta as Record<string, unknown> | undefined };}@@ -116,6 +123,14 @@ for (const kind of testBackends()) {await importFromContent(engine, BOBS.slug, pageText('Bob plan', BOBS.canary, ['readable_by: [bob-example]']), { sourceId: SRC });const fact = await dispatchToolCall(engine, 'remember', { fact: `Harbor ledger planning notes ${PRIVATE_FACT}`, provenance: 'fixture', entity: OPEN.slug, visibility: 'private' }, { remote: false, sourceId: SRC });if (fact.isError) throw new Error(`fixture remember: ${fact.content.map(c => c.text).join(' ')}`);+ // think resolves trajectory entities in its scalar source, which is default for a caller with a source grant.+ for (const sourceId of [SRC, 'default']) await importFromContent(engine, PERSON, ['---', 'type: person', 'title: Carol Example', '---', '# Carol Example', '', 'Carol is a founder.'].join('\n'), { sourceId });+ await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type)+ VALUES ($1, $2, $3, 'event', 'private', '2026-05-01T00:00:00Z', 'fixture', 'job_change')`, [SRC, PERSON, `Carol switched jobs ${PRIVATE_TRAJECTORY}`]);+ for (const [sourceId, canary, provenance] of [[SRC, BOBS_FACT, BOBS.slug], ['default', UNGRANTED_FACT, null]] as const) {+ await engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, valid_from, source, event_type, source_markdown_slug)+ VALUES ($1, $2, $3, 'event', 'private', '2026-06-01T00:00:00Z', 'fixture', 'job_change', $4)`, [sourceId, PERSON, `Harbor ledger planning notes ${canary}`, provenance]);+ }for (const id of [OWNER, 'bob-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);const mint = async (name: string, member?: string, mayActFor?: string[]) => {const minted = await mintLegacyToken(engine, { name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });@@ -154,6 +169,72 @@ for (const kind of testBackends()) {for (const who of ['bob', 'unbound']) expect({ who, seen: (await call(who, 'recall', { query: 'harbor ledger planning notes' })).text.includes(PRIVATE_FACT) }).toEqual({ who, seen: false });}, 120_000);+ /** GST-2089: which fact surfaces show `who` a private fact: the query facts arm, ranked recall, hot memory, delta, context_pack and think's trajectory. */+ async function privateFactsSeenBy(who: string, header?: string, canary = PRIVATE_FACT): Promise<string[]> {+ const seen: string[] = [];+ const surfaces: Array<[string, () => Promise<string>, string]> = [+ ['query', async () => (await call(who, 'query', { query: 'harbor ledger planning notes', expand: false, limit: 20 }, header)).text, canary],+ ['recall question', async () => (await call(who, 'recall', { question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],+ ['recall entity question', async () => (await call(who, 'recall', { entity: OPEN.slug, question: `Harbor ledger planning notes ${canary}` }, header)).text, canary],+ ['hot memory', async () => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null), canary],+ ['delta', async () => (await call(who, 'delta', { since: '2000-01-01T00:00:00Z' }, header)).text, canary],+ ['context_pack', async () => (await call(who, 'context_pack', { entities: OPEN.slug }, header)).text, canary],+ ['think trajectory', async () => (await call(who, 'think', { question: 'When did Carol last switch jobs?' }, header)).text.match(/TRAJECTORY_INJECTED_\d+_POINTS/)?.[0] ?? '', 'TRAJECTORY_INJECTED'],+ ];+ for (const [label, read, shown] of surfaces) if ((await read()).includes(shown)) seen.push(label);+ return seen;+ }+ const FACT_SURFACES = ['query', 'recall question', 'recall entity question', 'hot memory', 'delta', 'context_pack', 'think trajectory'];++ test('fixture control: a trusted local caller gets the private facts on every fact surface', async () => {+ const local = (op: string, params: Record<string, unknown>) => dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC }).then(o => o.content.map(c => c.text).join('\n'));+ expect(await local('recall', { question: `Harbor ledger planning notes ${PRIVATE_FACT}` })).toContain(PRIVATE_FACT);+ expect(await local('think', { question: 'When did Carol last switch jobs?' })).toMatch(/TRAJECTORY_INJECTED_\d+_POINTS/);+ expect(await local('recall', { question: `Harbor ledger planning notes ${BOBS_FACT}` })).toContain(BOBS_FACT);+ expect((await dispatchToolCall(engine, 'recall', { question: `Harbor ledger planning notes ${UNGRANTED_FACT}` }, { remote: false, sourceId: 'default' })).content.map(c => c.text).join('\n')).toContain(UNGRANTED_FACT);+ }, 120_000);++ test('GST-2089: the owner and its delegate get private facts on every fact surface; another member and an unbound token get world-only facts', async () => {+ __resetHotMemoryCacheForTests();+ for (const who of ['owner', 'delegate']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: FACT_SURFACES });+ for (const who of ['bob', 'unbound']) expect({ who, seen: await privateFactsSeenBy(who) }).toEqual({ who, seen: [] });+ }, 240_000);++ test('GST-2089: the owner reads no private fact taken from another person\'s readable_by page or kept in a source its grant does not read', async () => {+ __resetHotMemoryCacheForTests();+ for (const canary of [BOBS_FACT, UNGRANTED_FACT]) expect({ canary, seen: (await privateFactsSeenBy('owner', undefined, canary)).filter(s => s !== 'think trajectory') }).toEqual({ canary, seen: [] });+ expect((await call('owner', 'think', { question: 'When did Carol last switch jobs?' })).text).toContain('TRAJECTORY_INJECTED_1_POINTS');+ }, 240_000);++ test('GST-2089: the owner speaking for itself alone keeps private facts; for a channel audience it gets world-only facts', async () => {+ __resetHotMemoryCacheForTests();+ expect(await privateFactsSeenBy('owner', `member:${OWNER}`)).toEqual(FACT_SURFACES);+ expect(await privateFactsSeenBy('owner', `member:${OWNER},member:bob-example`)).toEqual([]);+ }, 240_000);++ test('GST-2089: hot memory keys on the caller: after the owner warms the entry, the next caller with the same session reads world-only facts', async () => {+ const hot = async (who: string, header?: string) => JSON.stringify((await call(who, 'get_page', { slug: OPEN.slug }, header, { metaHook: getBrainHotMemoryMeta })).meta?.brain_hot_memory ?? null);+ for (const next of [['bob'], ['unbound'], ['owner', `member:${OWNER},member:bob-example`]] as const) {+ __resetHotMemoryCacheForTests();+ expect(await hot('owner')).toContain(PRIVATE_FACT);+ expect({ next, seen: (await hot(next[0], next[1])).includes(PRIVATE_FACT) }).toEqual({ next, seen: false });+ }+ // With privacy relaxed by the operator, the same credential after `gbrain access owner clear` shares the owner's+ // page tier and identity; the fact tier still keeps it off the owner's cached private facts.+ await engine.setConfig('search.remote_private_pages', 'visible');+ __resetPrivateVisibilityCacheForTests();+ __resetHotMemoryCacheForTests();+ try {+ expect(await hot('owner')).toContain(PRIVATE_FACT);+ await clearOwner(engine);+ expect(await hot('owner')).not.toContain(PRIVATE_FACT);+ } finally {+ await setOwner(engine, OWNER);+ await engine.unsetConfig('search.remote_private_pages');+ __resetPrivateVisibilityCacheForTests();+ }+ }, 120_000);+test('another member and an unbound token still see no private page on any path, after the owner read them', async () => {expect(await privateSeenBy('bob')).toEqual({});expect(await privateSeenBy('unbound')).toEqual({});