Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: pre-landing review fixes (pass 2): pinned questions stay out of the private-pages grant
garrytane1011657aa15
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.mdindex 16059244e1..87ff89e39e 100644--- a/docs/guides/multi-source-brains.md+++ b/docs/guides/multi-source-brains.md@@ -253,12 +253,12 @@ it, before any member's bot connects:A token with no source grant, a federated source the grant does not name,and a request's `source_ids` never add a source; `context_pack`, `delta`- and writes keep hiding private pages. In a named source the grant opens- every page remote reads treat as private, not only `visibility: private`:- pages with a privacy alias (`access`, `confidentiality`), atoms, concepts- and events derived from private or unknown origins, and pages whose- declared lineage is private. `--private-pages none` hides them again on the- next request, and `gbrain auth list` shows each token's setting.+ and writes keep hiding private pages. In a named source the grant also+ opens pages with a privacy alias (`access`, `confidentiality`), atoms,+ concepts and events derived from private or unknown origins, and pages+ whose declared lineage is private; pinned questions stay owner-only.+ `--private-pages none` hides them again on the next request, and+ `gbrain auth list` shows each token's setting.> **Warning: one shared source has no boundary inside it.** A bot that answers> everyone with one unscoped token over a single source exposes everything indiff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.mdindex a9968a8f03..b643bc87f2 100644--- a/docs/mcp/ADMIN.md+++ b/docs/mcp/ADMIN.md@@ -428,7 +428,7 @@ gbrain auth rescope --client CLIENT_ID --private-pages none # hide them again| `--takes-holders` | `a,b` or `none` | Takes-holder allow-list for a token or client (default `world`); `none` hides every take. || `--operations` | `op,...`, `none` or `all` | Operation snapshot; `none` refuses every operation. Client only: `all` stores no snapshot and clears the profile, so the scopes and the surface alone decide, including operations later upgrades add (tokens: `--reset-default operations`). || `--scopes` | `read,write,...` | Replaces the scopes. |-| `--private-pages` | `granted-sources` or `none` | Whether remote reads see `visibility: private` pages. `none` (the default for every token and client) hides them, as before. `granted-sources` shows them only in the sources this grant names: a token's `--sources` list, or a client's write source plus its read sources. The no-grant floor, federated sources the grant does not name, a client's bound source and a request's `source_id` / `source_ids` never add a source. `context_pack`, `delta` and every write keep hiding private pages. In a named source it opens every page remote reads treat as private, not only `visibility: private`: privacy-alias pages (`access`, `confidentiality`), atoms, concepts and events derived from private or unknown origins, and pages with private declared lineage. Stored in its own column, not in the legacy permissions JSON. |+| `--private-pages` | `granted-sources` or `none` | Whether remote reads see `visibility: private` pages. `none` (the default for every token and client) hides them, as before. `granted-sources` shows them only in the sources this grant names: a token's `--sources` list, or a client's write source plus its read sources. The no-grant floor, federated sources the grant does not name, a client's bound source and a request's `source_id` / `source_ids` never add a source. `context_pack`, `delta` and every write keep hiding private pages. In a named source it also opens privacy-alias pages (`access`, `confidentiality`), atoms, concepts and events derived from private or unknown origins, and pages with private declared lineage; pinned questions stay owner-only. Stored in its own column, not in the legacy permissions JSON. || `--reset-default` | `sources,takes-holders,operations` | Token only: restores the `auth create` default for those axes: no source grant (the historical `default` floor), holders `world`, no operation snapshot. || `--refresh-operations` | with optional `--add op,...` or `--all-new` | Token only: previews operations added since the snapshot. Without `--add` or `--all-new` nothing is widened. || `--if-version` | `N` | Refuses unless the stored grant revision is `N`; the refusal names the current revision. |diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 62e7cf9efa..4ff22f9fe7 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1296,7 +1296,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// GBRA-199. since: '0.60.503.0' is stamped at the merge slot.{ since: '0.60.503.0', id: 'registration_lists_verbs_gbra199', text: 'New MCP registrations gbrain writes now list only the seven memory verbs (`recall`, `remember`, `entity`, …) and `request_tools` in tools/list: `gbrain setup claude-code|codex`, `gbrain bootstrap hooks`, the readiness and `gbrain init` registration lines (`serve --surface starter --advertise verbs`: the starter tools stay callable) and `gbrain mcp expose` (its `serve --http` runs with `--surface full --advertise verbs`, so clients without their own surface see that list and every operation stays callable). `request_tools` lists the rest and returns any tool\'s full schema, and a tool it describes joins the session\'s list. The initialize instructions follow the listed tools, so they point agents at `recall` instead of `search`. Existing registrations and exposures keep their listing, and an explicit `--surface full` (or starter, or verbs) lists that whole surface. New `gbrain serve --advertise <verbs|starter|full>` sets the listing per server and wins over config `mcp.advertised_surface`; a listing narrower than the callable set now always includes `request_tools`. Remote harness and bot clients get the same listing: a new `gbrain mcp provision` grant with the memory-reader, memory-writer or coding-agent profile and a new `gbrain agent register` daily-driver or coding-agent client keep the full callable surface but list the verbs and `request_tools` (`auth list-clients` shows `full (set by install)`); `gbrain auth rescope-client <id> --surface full` lists everything, and clients the operator pinned before keep their listing. Plugin manifests and a bare `serve` are unchanged.' },{ since: '0.60.452.0', id: 'sources_add_federation_warning_gbra156', text: '`gbrain sources add` without `--federated` or `--no-federated` now warns on stderr that the new source is not federated, so a remote token or agent connection with no source grant cannot read its pages, and names `gbrain sources federate <id>` and `gbrain auth rescope --token <name> --sources <id>`. The stored default is still non-federated.' },- { since: 'TBD', id: 'private_pages_granted_sources_gbra156', text: 'Access tokens and OAuth clients have a new private-pages grant, `none` for every existing and new token and client, so remote reads still hide `visibility: private` pages until the brain host opts a connection in: `gbrain auth rescope --token <name> --private-pages granted-sources` (or `--client <id>`) lets it read private pages in the sources its grant names, and only those; in a named source that covers every page remote reads treat as private (privacy-alias pages and atoms, concepts and events derived from private or unknown origins), not only `visibility: private`. A token with no source grant, federated sources the grant does not name and a request\'s `source_ids` never add one; `context_pack`, `delta` and writes keep hiding private pages. `--private-pages none` turns it off on the next request.' },+ { since: 'TBD', id: 'private_pages_granted_sources_gbra156', text: 'Access tokens and OAuth clients have a new private-pages grant, `none` for every existing and new token and client, so remote reads still hide `visibility: private` pages until the brain host opts a connection in: `gbrain auth rescope --token <name> --private-pages granted-sources` (or `--client <id>`) lets it read private pages in the sources its grant names, and only those; in a named source that also covers privacy-alias pages and atoms, concepts and events derived from private or unknown origins, while pinned questions stay owner-only. A token with no source grant, federated sources the grant does not name and a request\'s `source_ids` never add one; `context_pack`, `delta` and writes keep hiding private pages. `--private-pages none` turns it off on the next request.' },// GBRA-187 harness-eval items (HARN-2, HARN-5). `since` is stamped at the merge slot.{ since: '0.60.456.0', id: 'skillpack_skill_name', text: 'list_brain_skillpack now names each skill `name` instead of `slug`, and get_skill with source_id returns `name` too, matching the get_skill parameter it feeds. A skill name is not a page slug; clients that read `skills[].slug` read `skills[].name` instead.' },{ since: '0.60.456.0', id: 'openclaw_core_scaffold', text: '`gbrain skillpack scaffold --harness openclaw` now installs five brain-first skills (query, brain-ops, capture, data-loss-gate, resolve-before-asking) instead of the full bundle, because OpenClaw lists every workspace skill in every prompt. `--all` installs the full bundle; existing workspaces are not changed.' },diff --git a/src/core/engine-sql/pages.ts b/src/core/engine-sql/pages.tsindex 453d3164d0..398c84b376 100644--- a/src/core/engine-sql/pages.ts+++ b/src/core/engine-sql/pages.ts@@ -1011,7 +1011,7 @@ export async function getVersions<B extends boolean = true>(opts?: GetVersionsOpts<B>,): Promise<PageVersionRows<B>> {const privacy = opts?.excludePrivate- ? trustedSql(`AND ${orPrivateReadableSource('p.source_id', `${privatePagesFilterFragment('p')} AND ${privateSnapshotFilterFragment('pv')}`)}`) : sqlFragment``;+ ? trustedSql(`AND ${orPrivateReadableSource('p', `${privatePagesFilterFragment('p')} AND ${privateSnapshotFilterFragment('pv')}`)}`) : sqlFragment``;const scope = opts?.sourceIds && opts.sourceIds.length > 0? sqlFragment`AND p.source_id = ANY(${opts.sourceIds}::text[])`: opts?.sourceId ? sqlFragment`AND p.source_id = ${opts.sourceId}` : sqlFragment``;diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.tsindex 0e1e8b49e0..23fab521af 100644--- a/src/core/search/private-visibility.ts+++ b/src/core/search/private-visibility.ts@@ -87,30 +87,32 @@ export function privateReadableSources(): readonly string[] {}/**- * `visiblePredicate`, widened to rows whose source (`sourceIdSql`, a- * code-provided column reference) is in the current private-readable set.- * The ids are embedded as literals: each passed isValidSourceId, whose- * alphabet has no quote or backslash.+ * `visiblePredicate`, widened to pages (`pageAlias`, a code-provided alias)+ * whose source is in the current private-readable set. A page carrying the+ * `pinned_question` marker never widens: pinned questions stay owner-private+ * (src/core/questions/pages.ts). The ids are embedded as literals: each passed+ * isValidSourceId, whose alphabet has no quote or backslash.*/-export function orPrivateReadableSource(sourceIdSql: string, visiblePredicate: string): string {+export function orPrivateReadableSource(pageAlias: string, visiblePredicate: string): string {const ids = privateReadableSources();if (ids.length === 0) return visiblePredicate;- return `(${sourceIdSql} IN (${ids.map(id => `'${id}'`).join(', ')}) OR ${visiblePredicate})`;+ return `((${pageAlias}.source_id IN (${ids.map(id => `'${id}'`).join(', ')}) AND NOT COALESCE(${pageAlias}.frontmatter ? 'pinned_question', false)) OR ${visiblePredicate})`;}/** privatePagesFilterFragment for a remote read: a page in a private-readable source passes. Read sites only; derived-visibility decisions keep the plain fragment. */export function privatePagesFilterForCaller(pageAlias: string): string {- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragment(pageAlias));+ return orPrivateReadableSource(pageAlias, privatePagesFilterFragment(pageAlias));}/** privatePagesFilterFragmentFast for a remote read. */export function privatePagesFilterFastForCaller(pageAlias: string): string {- return orPrivateReadableSource(`${pageAlias}.source_id`, privatePagesFilterFragmentFast(pageAlias));+ return orPrivateReadableSource(pageAlias, privatePagesFilterFragmentFast(pageAlias));}-/** isPrivatePage for a remote read: false for a page whose `source_id` is private-readable; a row without `source_id` keeps the plain rule. */+/** isPrivatePage for a remote read: false for a page whose `source_id` is private-readable, unless it carries the `pinned_question` marker; a row without `source_id` keeps the plain rule. */export function isPrivatePageForCaller(page: { type?: string | null; frontmatter?: unknown; source_id?: string | null }): boolean {if (!isPrivatePage(page)) return false;+ if (typeof page.frontmatter === 'object' && page.frontmatter !== null && (page.frontmatter as Record<string, unknown>).pinned_question != null) return true;return !(typeof page.source_id === 'string' && privateReadableSources().includes(page.source_id));}diff --git a/src/core/verbs/entity-card.ts b/src/core/verbs/entity-card.tsindex 081b41d1ce..580e0879b6 100644--- a/src/core/verbs/entity-card.ts+++ b/src/core/verbs/entity-card.ts@@ -309,7 +309,7 @@ export async function selectEntityCandidates(const { orPrivateReadableSource, privatePagesFilterFragment, privatePagesFilterForCaller } = await import('../search/private-visibility.ts');// Predicate text lives ONCE (private-visibility.ts) — both card queries// below select `FROM pages` unaliased, so qualify with the table name.- const privatePredicate = scope.excludePrivate ? ` AND ${orPrivateReadableSource('pages.source_id', privatePagesFilterFragment('pages'))}` : '';+ const privatePredicate = scope.excludePrivate ? ` AND ${orPrivateReadableSource('pages', privatePagesFilterFragment('pages'))}` : '';const norm = normalizeAlias(trimmed);const titleLc = trimmed.toLowerCase();diff --git a/test/private-pages-grant.test.ts b/test/private-pages-grant.test.tsindex 58daad5a3a..56faed48dc 100644--- a/test/private-pages-grant.test.ts+++ b/test/private-pages-grant.test.ts@@ -268,6 +268,30 @@ for (const kind of testBackends()) {}});+ test('in a granted source the grant opens privacy-alias pages and derived atoms, never a pinned question', async () => {+ const extra: Array<[string, string, string]> = [+ ['drafts/harbor-memo', 'canaryaliaspriv', ['---', 'type: note', 'title: Harbor memo', 'confidentiality: secret', '---', '# Harbor memo', '', 'Harbor memo canaryaliaspriv.'].join('\n')],+ ['atoms/harbor-atom', 'canaryatompriv', ['---', 'type: atom', 'title: Harbor atom', '---', '# Harbor atom', '', 'Harbor atom canaryatompriv.'].join('\n')],+ ['questions/harbor-pin', 'canarypinpriv', ['---', 'type: question', 'title: Harbor pin', 'visibility: private', 'pinned_question: pin-example', '---', '# Harbor pin', '', 'Owner note canarypinpriv.'].join('\n')],+ ];+ for (const [slug, , body] of extra) await importFromContent(engine, slug, body, { sourceId: ALICE });+ for (const [slug, canary] of extra) expect({ slug, seen: (await local('get_page', { slug })).includes(canary) }).toEqual({ slug, seen: true });+ for (const owner of ['alice-example', 'client-alice']) {+ for (const [slug, canary] of extra) {+ const out = await call(tokens[owner], 'get_page', { slug });+ expect({ owner, slug, seen: out.text.includes(canary) }).toEqual({ owner, slug, seen: !slug.startsWith('questions/') });+ }+ const listed = await call(tokens[owner], 'list_pages', { slug_prefix: 'questions/' });+ expect({ owner, listed: listed.text.includes('questions/harbor-pin') }).toEqual({ owner, listed: false });+ }+ for (const other of ['bob-example', 'floor', 'alice-none']) {+ for (const [slug, canary] of extra) {+ const out = await call(tokens[other], 'get_page', { slug, source_id: ALICE });+ expect({ other, slug, leaked: out.text.includes(canary) }).toEqual({ other, slug, leaked: false });+ }+ }+ });+test('a rescope back to none hides the pages on the next call (token and client)', async () => {expect((await call(tokens['alice-example'], 'get_page', { slug: PRIVATE_SLUG })).text).toContain(SECRET[ALICE]);await rescopeToken('alice-example', '--private-pages', 'none');