Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan0657503510f4
diff --git a/docs/guides/multi-source-brains.md b/docs/guides/multi-source-brains.md
index 39e8580271..16059244e1 100644
--- a/docs/guides/multi-source-brains.md
+++ b/docs/guides/multi-source-brains.md
@@ -253,9 +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. `--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 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.
> **Warning: one shared source has no boundary inside it.** A bot that answers
> everyone with one unscoped token over a single source exposes everything in
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index c333aced65..a9968a8f03 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. 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 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. |
| `--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/docs/protocol/MCP_META_CHANNELS.md b/docs/protocol/MCP_META_CHANNELS.md
index 99d016d15b..f5fbb9c698 100644
--- a/docs/protocol/MCP_META_CHANNELS.md
+++ b/docs/protocol/MCP_META_CHANNELS.md
@@ -140,7 +140,10 @@ beside `arguments` (MCP request-level `_meta`), or inside the tool arguments
`_meta` into the arguments. That call's response carries no
`brain_hot_memory`. Other values, or no value, leave the block as it is. A
channel or shared session should send it on every call. A member's own
-direct-message session can leave it out.
+direct-message session can leave it out. The opt-out removes only this
+`_meta` block: a `context_pack` or `delta` body still lists the connection's
+recent facts, so a channel harness should not call them with a member token
+whose first source is that member's private source.
```json
{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index c0000f2351..62e7cf9efa 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. 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 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.' },
// 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/test/private-pages-grant.test.ts b/test/private-pages-grant.test.ts
index 40a6038606..58daad5a3a 100644
--- a/test/private-pages-grant.test.ts
+++ b/test/private-pages-grant.test.ts
@@ -244,25 +244,45 @@ for (const kind of testBackends()) {
});
});
- test('writes keep hiding private pages: put_page into the private page stays refused for the owner', async () => {
+ test('writes keep hiding private pages: a write to the private page stays refused for the owner while a world page takes it', async () => {
await rescopeToken('alice-example', '--scopes', 'read,write');
- const out = await call(tokens['alice-example'], 'add_tag', { slug: PRIVATE_SLUG, tag: 'renewal' });
- expect(out.isError).toBe(true);
- await rescopeToken('alice-example', '--scopes', 'read');
+ try {
+ const control = await call(tokens['alice-example'], 'add_tag', { slug: TARGET_SLUG, tag: 'renewal' });
+ expect({ isError: control.isError, text: control.text.slice(0, 200) }).toMatchObject({ isError: false });
+ const out = await call(tokens['alice-example'], 'add_tag', { slug: PRIVATE_SLUG, tag: 'renewal' });
+ expect({ isError: out.isError, refused: out.text.includes('"code": "page_not_found"') }).toEqual({ isError: true, refused: true });
+ expect(out.text).not.toContain(SECRET[ALICE]);
+ } finally {
+ await rescopeToken('alice-example', '--scopes', 'read');
+ }
+ });
+
+ test('delta stays world-only for every remote caller, the owner included', async () => {
+ const since = '2000-01-01T00:00:00Z';
+ expect(await local('delta', { since, include_private: true })).toContain(PRIVATE_SLUG);
+ expect(await local('delta', { since })).not.toContain(PRIVATE_SLUG);
+ for (const who of ['alice-example', 'client-alice', 'bot-all', 'floor']) {
+ const out = await call(tokens[who], 'delta', { since, include_private: true });
+ expect({ who, isError: out.isError, listed: out.text.includes(PRIVATE_SLUG) }).toEqual({ who, isError: false, listed: false });
+ for (const secret of Object.values(SECRET)) expect({ who, leaked: out.text.includes(secret) }).toEqual({ who, 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');
await rescopeClient(clients['client-alice'], '--private-pages', 'none');
- for (const owner of ['alice-example', 'client-alice']) {
- for (const [label, op, params] of reads()) {
- const out = await call(tokens[owner], op, params);
- expect({ owner, label, leaked: out.text.includes(SECRET[ALICE]) }).toEqual({ owner, label, leaked: false });
+ try {
+ for (const owner of ['alice-example', 'client-alice']) {
+ for (const [label, op, params] of reads()) {
+ const out = await call(tokens[owner], op, params);
+ expect({ owner, label, leaked: out.text.includes(SECRET[ALICE]) }).toEqual({ owner, label, leaked: false });
+ }
}
+ } finally {
+ await rescopeToken('alice-example', '--private-pages', 'granted-sources');
+ await rescopeClient(clients['client-alice'], '--private-pages', 'granted-sources');
}
- await rescopeToken('alice-example', '--private-pages', 'granted-sources');
- await rescopeClient(clients['client-alice'], '--private-pages', 'granted-sources');
expect((await call(tokens['alice-example'], 'get_page', { slug: PRIVATE_SLUG })).text).toContain(SECRET[ALICE]);
}, 120_000);