Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(access): a channel audience applies the read policy under the hatch on an unrestricted brain; dedupe notice row

garrytan9432bea9f72d
diff --git a/docs/tutorials/company-brain.md b/docs/tutorials/company-brain.md
index 4f07158370..919c3af65f 100644
--- a/docs/tutorials/company-brain.md
+++ b/docs/tutorials/company-brain.md
@@ -157,7 +157,7 @@ X-Gbrain-On-Behalf-Of: alice-example, bob-example, guest # a channel with a no
"_meta": { "on_behalf_of": ["alice-example"] } # request-level _meta, a sibling of arguments (stdio and HTTP)
```
-A page is returned only when every audience entry may read it (`guest` reads no restricted page, `group:team-a` counts as one entry for a large channel), within the agent's own source grant. The agent's `--private-pages granted-sources` and the operator hatches relax `visibility: private` only when the audience is exactly one member; a channel never sees a private page. The audience is read on every call, so a DM followed by a channel turn gets each its own view. An entry outside `may_act_for` refuses `on_behalf_of_not_permitted` (the operator widens the list with the command it prints), a disabled or unknown member refuses `on_behalf_of_unknown_member`, and an audience inside tool arguments, where conversation text could set it, refuses `on_behalf_of_in_arguments`. Every response carries the applied view in `_meta.access`, and `whoami` returns it as `access.applied` for a model whose harness hides `_meta`. Writes and `submit_agent` jobs keep the audience they were made for and re-check it before they commit or call a tool. A local stdio server takes its list from `gbrain config set mcp.stdio_may_act_for <list>`. `*` permits any member and `gbrain doctor` warns about it (`access_may_act_for_wildcard`). Each assertion is appended to `~/.gbrain/audit/access-audience-YYYY-Www.jsonl`. Where each person runs their own agent, a credential bound to that person's member stays the simpler setup. Shared agents work the same on a repo-less brain: `may_act_for` and the audience are database and request state.
+A page is returned only when every audience entry may read it (`guest` reads no restricted page, `group:team-a` counts as one entry for a large channel), within the agent's own source grant. The agent's `--private-pages granted-sources` and the operator hatches relax `visibility: private` only when the audience is exactly one member; a channel never sees a private page. The audience is read on every call, so a DM followed by a channel turn gets each its own view. An entry outside `may_act_for` refuses `on_behalf_of_not_permitted` (the operator widens the list with the command it prints), a disabled or unknown member refuses `on_behalf_of_unknown_member`, and an audience inside tool arguments, where conversation text could set it, refuses `on_behalf_of_in_arguments`. Every response carries the applied view in `_meta.access`, and `whoami` returns it as `access.applied` for a model whose harness hides `_meta`. Writes and `submit_agent` jobs keep the audience they were made for and re-check it before they commit or call a tool. A local stdio server takes its list from `gbrain config set mcp.stdio_may_act_for <list>`. `*` permits any member, lets the harness learn which member and group ids exist from the refusals, and `gbrain doctor` warns about it (`access_may_act_for_wildcard`). Each assertion is appended to `~/.gbrain/audit/access-audience-YYYY-Www.jsonl`. Where each person runs their own agent, a credential bound to that person's member stays the simpler setup. Shared agents work the same on a repo-less brain: `may_act_for` and the audience are database and request state.
For most company-brain installs (10+ teammates each with their own AI client), Model A is the right starting point. If you're running the fat-agent-serves-everyone pattern from the personal-brain tutorial, Model B is genuinely simpler. You can also mix: separate sources for the obviously-different ones (customer notes vs internal-only) AND a `partners/<slug>/` convention inside the shared source for per-person workspace.
diff --git a/scripts/.bench-run-gbra231.sh b/scripts/.bench-run-gbra231.sh
new file mode 100644
index 0000000000..9f58691ecf
--- /dev/null
+++ b/scripts/.bench-run-gbra231.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+export PATH="$HOME/.bun/bin:$PATH"
+mkdir -p bench-out
+nproc; uptime
+for i in 1 2 3 4 5 6 7 8; do
+ if [ $((i % 2)) -eq 1 ]; then order="b parent"; else order="parent b"; fi
+ for side in $order; do
+ dir=.; [ "$side" = parent ] && dir=../parent
+ (cd "$dir" && bun scripts/bench-member-access.ts --pages 5000 --queries 60 --shares 0,0.2,0.8 --json 2>>"$OLDPWD/bench-out/$side-$i.err" | tail -1) > "bench-out/$side-$i.json"
+ echo "run $i $side done $(date -u +%H:%M:%S)"
+ done
+done
+uptime
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 9c8fffb60c..d0adde4d5c 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1272,7 +1272,6 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: 'TBD', id: 'member_read_access_gbra218', text: 'A page whose frontmatter names readers (`readable_by: [alice-example, group:team-a]`) is now read remotely only by a token, OAuth client or stdio server bound to a listed member (`gbrain access member add`, `gbrain auth rescope --token <name> --member <id>`, config `mcp.stdio_member`). Every other remote caller gets the same `not_found` as for a missing page, including unbound credentials, a `--private-pages granted-sources` bot and both escape hatches (`GBRAIN_REMOTE_PRIVATE_PAGES=1`, `search.remote_private_pages=visible`), which relax only `visibility: private`. A malformed `readable_by` reads as nobody, and a page derived from a restricted page reads as nobody remotely. Pages that already named `readable_by` before this upgrade read as nobody remotely until `gbrain repair access` (preview, then `--apply`). The local CLI is unchanged; `--as <member>` previews one member\'s view.' },
{ since: 'TBD', id: 'member_access_hatch_scope_gbra218', text: 'On a brain where any page names readers or any member exists, the escape hatches no longer turn the remote read filter off: remote reads still hide pages the caller\'s member is not listed on, and secondary surfaces that use the identity-free filter (proactive brief, retrieval reflex, entity resolution, known-as-of) hide every restricted page and keep hiding `visibility: private` pages under a hatch. A brain with no restriction keeps the old hatch behaviour exactly. A credential bound to a disabled or removed member is refused at verification (`access_member_disabled`).' },
{ since: 'TBD', id: 'shared_agent_audience_gbra231', text: 'A shared agent can now read as the people a turn serves: its harness names the audience in the `X-Gbrain-On-Behalf-Of` header or request-level `_meta.on_behalf_of` (member ids, `group:<id>`, `guest`), and the call returns only pages every entry may read, within the agent\'s own source grant; a channel audience (more than one member, a group or a guest) never sees a `visibility: private` page. Each entry must be in the credential\'s `may_act_for` (`gbrain auth rescope --token <name> --may-act-for <list>`; for stdio, config `mcp.stdio_may_act_for`), which earlier releases stored without enforcing. An audience inside tool arguments is refused (`on_behalf_of_in_arguments`). Every remote MCP response now carries `_meta.access` (member, groups, audience, policy revisions, privacy relaxation), and `whoami` returns it as `access.applied`.' },
- { since: 'TBD', id: 'shared_agent_audience_gbra231', text: 'A shared agent can now read as the people a turn serves: its harness names the audience in the `X-Gbrain-On-Behalf-Of` header or request-level `_meta.on_behalf_of` (member ids, `group:<id>`, `guest`), and the call returns only pages every entry may read, within the agent\'s own source grant; a channel audience (more than one member, a group or a guest) never sees a `visibility: private` page. Each entry must be in the credential\'s `may_act_for` (`gbrain auth rescope --token <name> --may-act-for <list>`; for stdio, config `mcp.stdio_may_act_for`), which earlier releases stored without enforcing. An audience inside tool arguments is refused (`on_behalf_of_in_arguments`). Every remote MCP response now carries `_meta.access` (member, groups, audience, policy revisions, privacy relaxation), and `whoami` returns it as `access.applied`.' },
{ since: 'TBD', id: 'folder_access_rules_gbra218', text: 'A source can now keep whole folders to named members with folder rules (`gbrain access rule add --prefix partners/alice-example/ --readers alice-example,group:team-a --source <id>`, preview then `--yes`). On a repo-less source the rules live in the database; on a git-backed source they live in `.gbrain/access.yml`, committed through `gbrain git commit-push` and applied on sync. A remote read of a page under a rule needs the caller\'s member to be listed on every rule covering it, on top of the page\'s own `readable_by`; no hatch, grant or `--as` relaxes it. Narrowing applies at once; a change that widens (removing a rule or a reader) is held until `gbrain access apply --source <id>` previews it and `--yes --expect <plan_hash>` approves it. While an apply is unfinished its prefixes read as nobody remotely (`access_policy_pending`, fixed by `gbrain access resume --source <id>`). `gbrain export` carries each source\'s applied rules under `.gbrain/`, and `gbrain import` installs them before any page (`--access-policy <source>` picks one source\'s rules from a multi-source export). Remote callers cannot write `.gbrain/` pages. Nothing changes on a source with no folder rule.' },
];
diff --git a/src/core/search/private-visibility.ts b/src/core/search/private-visibility.ts
index 4bd014d1d9..83003b79a8 100644
--- a/src/core/search/private-visibility.ts
+++ b/src/core/search/private-visibility.ts
@@ -764,7 +764,8 @@ export async function accessRestrictionsPresent(engine: BrainEngine): Promise<bo
* member-access restriction, where the hatches keep their pre-GBRA-218
* meaning. With restrictions present the fragment still applies under a
* hatch: caller-aware fragments relax only their privacy part, and the
- * member-access part (accessAllowedSql) stays mandatory.
+ * member-access part (accessAllowedSql) stays mandatory. A shared-agent audience the hatch does not relax (a
+ * channel: several entries, a group or a guest) always applies it, restrictions or not.
*/
export async function resolveExcludePrivatePages(
engine: BrainEngine,
@@ -772,5 +773,7 @@ export async function resolveExcludePrivatePages(
): Promise<boolean> {
if (remote === false) return currentCallerAccess().applyRemoteReadPolicy;
if (!await remotePrivacyRelaxed(engine)) return true;
+ const access = currentCallerAccess();
+ if (access.audience?.length && access.hidePrivate) return true;
return accessRestrictionsPresent(engine);
}
diff --git a/test/access-on-behalf-of.test.ts b/test/access-on-behalf-of.test.ts
index d3bf5cfbf9..0bdd4413d7 100644
--- a/test/access-on-behalf-of.test.ts
+++ b/test/access-on-behalf-of.test.ts
@@ -448,3 +448,35 @@ for (const kind of testBackends()) {
}, 60_000);
});
}
+
+describe('shared agents on an unrestricted brain (pglite, repo-less)', () => {
+ test('a channel audience never sees a private page under the operator hatch before any member exists', async () => {
+ const engine = new PGLiteEngine();
+ await engine.connect({ engine: 'pglite' } as never);
+ await engine.initSchema();
+ try {
+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', ['obo-open-src']);
+ await importFromContent(engine, 'notes/quiet', '---\ntype: note\ntitle: Quiet\nvisibility: private\n---\n# Quiet\n\nHarbor ledger canaryoboopenquiet.', { sourceId: 'obo-open-src', noEmbed: true });
+ await addGroup(engine, 'room-a');
+ await addGroup(engine, 'room-b');
+ const minted = await mintLegacyToken(engine, { name: 'chan-bot', scopes: ['read'], takesHolders: ['world'], sourceGrant: ['obo-open-src'] });
+ await bindCredential(engine, { kind: 'token', id: minted.id }, { mayActFor: ['guest', 'group:room-a', 'group:room-b'] });
+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
+ await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
+ __resetPrivateVisibilityCacheForTests();
+ const auth = await provider.verifyAccessToken(minted.token) as unknown as AuthInfo;
+ const read = async (op: string, params: Record<string, unknown>, header?: string) => (await dispatchToolCall(engine, op, params, {
+ remote: true, transport: 'http', auth, sourceId: 'obo-open-src', takesHoldersAllowList: ['world'], ...(header ? { onBehalfOf: { header } } : {}) })).content.map(c => c.text).join('\n');
+ expect(await read('get_page', { slug: 'notes/quiet' })).toContain('canaryoboopenquiet');
+ for (const header of ['guest', 'group:room-a, group:room-b', 'group:room-a']) {
+ expect(await read('get_page', { slug: 'notes/quiet' }, header)).not.toContain('canaryoboopenquiet');
+ expect(await read('search', { query: 'harbor ledger', match: 'keyword', fields: 'full' }, header)).not.toContain('canaryoboopenquiet');
+ expect(await read('list_pages', {}, header)).not.toContain('notes/quiet');
+ }
+ });
+ } finally {
+ __resetPrivateVisibilityCacheForTests();
+ await engine.disconnect();
+ }
+ }, 120_000);
+});