Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: capacity notice runs get_brain_health over MCP; refusal value counts lifecycle changes and reads rates once a minute
garrytan47b3a83db23b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8417be4762..064a4721a8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,11 +16,11 @@ identifiers and attribution are available in the pre-removal Git revision### Itemized changes-- `src/core/persistence/capacity-snapshot.ts`: `write_capacity_low` says the write was saved and names doctor's read-only check (actor `agent`) as its fix, with no cap raise in the notice.+- `src/core/persistence/capacity-snapshot.ts`: `write_capacity_low` says the write was saved and names doctor's read-only check (actor `agent`) as its fix, with no cap raise in the notice; over MCP that fix is the read-scope `get_brain_health` call, so a remote agent runs it instead of relaying a command to its user.- `src/core/persistence/capacity-forecast.ts`: `recommended_limit` (doctor `persistence_capacity`, the notice snapshot, `gbrain sync status` and `/metrics`) covers one more year at the 7-day mean gross and net rates instead of the larger of the mean and the last 24 hours.-- `src/core/persistence/limits.ts`: `oneYearCapacity` (every `write_quota_exhausted`, `write_quota_insufficient` and background-pause refusal, and doctor's fallback) uses the scope's 7-day window over the forecast's window length while the scope admitted anything that week, and keeps the latest-1,000 sample for a scope idle all week; the compacted-size SQL moves to `receipt-bytes.ts` so both reads count the same net bytes.+- `src/core/persistence/limits.ts`: `oneYearCapacity` (every `write_quota_exhausted`, `write_quota_insufficient` and background-pause refusal, and doctor's fallback) uses the scope's 7-day window over the forecast's window length while the scope admitted anything that week, and keeps the latest-1,000 sample for a scope idle all week. Like the forecast, the brain and the local CLI writer count the week's source lifecycle changes. A scope's rates are read at most once a minute per brain, because these refusals run under the counter locks and a paused background producer is refused on every retry. The compacted-size SQL moves to `receipt-bytes.ts` so both reads count the same net bytes.- Docs: `docs/guides/write-refusals.md` (`write_capacity_low` row), `docs/guides/concurrent-writes.md` (the notice, the mean-rate value, and returning a raised `persistence.receipt_retention_days` to the default before raising a cap), `docs/guides/repair.md` (unset the 90-day retention once a failed-writes recovery is done), `docs/architecture/key-files/core-persistence-capacity.md`.-- Tests: `test/persistence-capacity-notices.test.ts` (the notice's fix and wording; a burst of 28 admissions in the last day over a 10-a-day week recommends the mean-rate value, ids exactly and receipt bytes under the mean-rate ceiling; after 1,000 admissions in one hour on a 100-a-week principal, a real `write_quota_exhausted` refusal names exactly the value doctor recommends, ids and receipt bytes, on PGLite and Postgres).+- Tests: `test/persistence-capacity-notices.test.ts` (the notice's fix and wording; a burst of 28 admissions in the last day over a 10-a-day week recommends the mean-rate value, ids exactly and receipt bytes under the mean-rate ceiling; after 1,000 admissions in one hour on a 100-a-week principal, a real `write_quota_exhausted` refusal names exactly the value doctor recommends, ids and receipt bytes, on PGLite and Postgres; the notice rendered over HTTP and stdio runs `get_brain_health`; a week of lifecycle changes moves the brain's value to doctor's; repeated refusals within a minute walk the window once per scope).## [0.60.621.0] - 2026-11-09**A page a member-bound credential creates in the `default` source is now readable only by that member.** A token bound with `gbrain auth rescope --member <id>` and no `--sources` writes to `default`, the source every credential without a source grant reads, and so does a token granted `--sources default` and an OAuth client left at its registration default. Its `put_page` (and every page write through the same path) used to create an ordinary page there, which another member and an unbound token read through `get_page`, `search`, `query`, `recall` and `list_pages`; its `remember` facts were already kept on the member's own page. A page such a credential creates is now written with `readable_by: [member:<id>]`, in the database row on a repo-less brain and in the file on a repo brain; rewriting it without `readable_by` keeps the stored readers, and the member widens it by naming readers. An edit to an existing page that names no readers leaves it shared, and `POST /ingest`, which cannot keep a page to a member, refuses such a credential with `permission_denied`. Member-bound credentials whose write source is another source (the documented `--sources private-<member>,default` shape) and unbound credentials write exactly as before, apart from slugs a member now creates. Pages derived from such a page (extracted atoms, chronicle events, `derived_from` pages, and a synthesized concept that uses it) follow the rule for pages with readers and are readable by no remote caller, the writer included. A page that teammates should read, such as a shared `people/` or `companies/` entity page or a page in a folder a rule already scopes to a group, names its readers when it is created; otherwise the first member to create a slug keeps it, and every other remote credential writing that slug (another member, an unbound token, a shared agent) gets `page_not_found`. The operator widens such a page from the brain host by adding `readable_by` to it (the local CLI is not member-scoped). A member-bound `put_page` over a page deleted within the last 72 hours is a create, so it is kept to the member too. Pages written before this release keep whatever readers they have: `gbrain access who-can-read <slug>` shows who reads one.diff --git a/src/core/persistence/capacity-snapshot.ts b/src/core/persistence/capacity-snapshot.tsindex 6272bc83a3..31776c377c 100644--- a/src/core/persistence/capacity-snapshot.ts+++ b/src/core/persistence/capacity-snapshot.ts@@ -111,7 +111,7 @@ function lowNotice(rows: CapacityAttention[]): Notice {return { code: 'write_capacity_low', kind: 'info',why: `This write was saved and writes still work. Write capacity is running low: ${rows.map(describe).join('; ')}; admission refuses only at the cap. `+ 'gbrain doctor --only persistence_capacity --json reads the forecast and the remedy for the brain host.',- fix: { argv: [...VERIFY.argv], consent: [], actor: 'agent', requires_exclusive: false,+ fix: { argv: [...VERIFY.argv], mcp: VERIFY.mcp, consent: [], actor: 'agent', requires_exclusive: false,why: 'Reads which cap is running low, its forecast and the remedy, read-only; nothing needs to change for this write.', verify: VERIFY,docs: 'docs/guides/concurrent-writes.md#quota-near-exhaustion' } };}diff --git a/src/core/persistence/limits.ts b/src/core/persistence/limits.tsindex 04993f8962..a0c4ba906d 100644--- a/src/core/persistence/limits.ts+++ b/src/core/persistence/limits.ts@@ -1,6 +1,7 @@import { opError, type OperationError } from '../ops/contract.ts';import { PAGE_BODY_CONFIG_KEYS, pageRecoveryBytes, segmentedPageCeiling } from '../page-body/limits.ts';import { DEFAULT_JOURNAL_LIMITS, principalKey, type JournalLimits, type Principal, type SqlEngine } from './model.ts';+import { engineKey } from '../engine-key.ts';import { COMPACTED_HEADROOM_BYTES, COMPACTED_RECEIPT_BYTES_SQL, EFFECT_BYTES_SQL, RECEIPT_RESERVATION_FLOOR } from './receipt-bytes.ts';/** Fallback compacted receipt size when no receipt is sampled; a compacted put_page measures about 3.9 KB. */@@ -72,8 +73,8 @@ export function recommendedLimit(resource: CapacityResource, used: number, limitconst WINDOW_WALK_ROWS = 200_000;/*** A cumulative cap value that covers one more year, never less than double the current cap. GST-2107: while the scope- * admitted anything in the last 7 days it uses the window's mean rates over the window `readCapacityForecast` uses- * (7 days, or the brain's age, at least a day), so an admission refusal names the same value as doctor and one bulk hour+ * admitted anything in the last 7 days it uses the window's mean rates, source lifecycle changes included, over the window+ * `readCapacityForecast` uses (7 days, or the brain's age, at least a day), so an admission refusal names the same value as doctor and one bulk hour* is not projected for a year. A scope idle for a week is sized from its latest 1,000 admissions, however old. Receipt* bytes use measured reservations: what receipts reserve while the retention window holds them, and their compacted size* after (`recommendedLimit`).@@ -81,26 +82,23 @@ const WINDOW_WALK_ROWS = 200_000;export async function oneYearCapacity(engine:SqlEngine,scope:string,setting:'LifetimeIds'|'TerminalBytes',used:number,limit:number):Promise<number> {const principal=/^principal:([^:]+):(.+)$/.exec(scope);const where=principal ? 'WHERE principal_kind=$1 AND principal_id=$2' : '';- const [sample]=await engine.executeRaw<{admissions:number;age_seconds:number|null;gross:number|null;net:number|null;- window_ids?:number|null;window_gross?:number|null;window_net?:number|null;window_span_days?:number|null;brain_age_days?:number|null}>(`WITH recent AS (- SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where} ORDER BY sequence DESC LIMIT 1000),- w AS (SELECT * FROM (SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where}- ORDER BY sequence DESC LIMIT ${WINDOW_WALK_ROWS}) walk WHERE created_at>now()-interval '7 days'),- e AS (SELECT request_id,SUM(${EFFECT_BYTES_SQL}) AS bytes FROM persistence_effects WHERE request_id IN (SELECT id FROM w) GROUP BY request_id)- SELECT (SELECT count(*)::int FROM recent) AS admissions,(SELECT EXTRACT(EPOCH FROM (now()-min(created_at)))::float8 FROM recent) AS age_seconds,- (SELECT avg(terminal_reservation)::float8 FROM recent) AS gross,- (SELECT avg(LEAST(terminal_reservation,octet_length(authority::text)+COALESCE(octet_length(outcome::text),0)+COALESCE(octet_length(error_detail::text),0)+${COMPACTED_HEADROOM_BYTES}))::float8 FROM recent) AS net,- (SELECT count(*)::int FROM w) AS window_ids,(SELECT EXTRACT(EPOCH FROM now()-min(created_at))/86400 FROM w)::float8 AS window_span_days,(SELECT COALESCE(SUM(terminal_reservation),0)::float8 FROM w) AS window_gross,- (SELECT COALESCE(SUM(${COMPACTED_RECEIPT_BYTES_SQL('w', 'e')}),0)::float8 FROM w LEFT JOIN e ON e.request_id=w.id) AS window_net,- (SELECT EXTRACT(EPOCH FROM now()-created_at)/86400 FROM persistence_requests ORDER BY sequence LIMIT 1)::float8 AS brain_age_days`,- principal ? [principal[1],principal[2]] : []);+ const params=principal ? [principal[1],principal[2]] : [];+ // Refusals run under the counter locks, and a paused background producer is refused on every retry, so a scope's+ // rates are read once a minute per brain (its oldest request names the brain) rather than walking the window each time.+ const [oldest]=await engine.executeRaw<{id:string}>('SELECT id::text AS id FROM persistence_requests ORDER BY sequence LIMIT 1');+ const cache=rateSamples.get(engineKey(engine)) ?? new Map<string,{at:number;brain:string|undefined;sample:RateSample}>();+ rateSamples.set(engineKey(engine),cache);+ const hit=cache.get(scope);+ const sample=hit && hit.brain===oldest?.id && Date.now()-hit.at<RATE_SAMPLE_TTL_MS ? hit.sample : await readRateSample(engine,scope,where,params);+ if(sample!==hit?.sample) cache.set(scope,{at:Date.now(),brain:oldest?.id,sample});const retention=await readReceiptRetentionDays(engine).catch(()=>DEFAULT_RECEIPT_RETENTION_DAYS);- const windowIds=Number(sample.window_ids ?? 0);+ const windowIds=Number(sample.window_ids ?? 0)+Number(sample.topology_ids ?? 0);if(windowIds>0) {// A week busier than the walk reads the walk's own span, so the rate is never diluted over days it did not read.- const windowDays=windowIds>=WINDOW_WALK_ROWS ? Math.max(1/24,Number(sample.window_span_days ?? 0)) : Math.min(7,Math.max(1,Number(sample.brain_age_days ?? 7)));+ const windowDays=Number(sample.window_ids ?? 0)>=WINDOW_WALK_ROWS ? Math.max(1/24,Number(sample.window_span_days ?? 0)) : Math.min(7,Math.max(1,Number(sample.brain_age_days ?? 7)));+ const topologyBytes=Number(sample.topology_bytes ?? 0);return setting==='LifetimeIds' ? recommendedLimit('lifetime_ids',used,limit,{perDay:windowIds/windowDays},retention)- : recommendedLimit('terminal_bytes',used,limit,{perDay:Number(sample.window_gross)/windowDays,netPerDay:Number(sample.window_net)/windowDays},retention);+ : recommendedLimit('terminal_bytes',used,limit,{perDay:(Number(sample.window_gross)+topologyBytes)/windowDays,netPerDay:(Number(sample.window_net)+topologyBytes)/windowDays},retention);}const perDay=sample.admissions/Math.max(1/24,(sample.age_seconds ?? 0)/86_400);const measured=(value:number|null|undefined,fallback:number)=>Number.isFinite(Number(value)) && Number(value)>0 ? Number(value) : fallback;@@ -108,6 +106,31 @@ export async function oneYearCapacity(engine:SqlEngine,scope:string,setting:'Lif: recommendedLimit('terminal_bytes',used,limit,{perDay:perDay*measured(sample.gross,RECEIPT_RESERVATION_FLOOR),netPerDay:perDay*measured(sample.net,RETAINED_RECEIPT_BYTES)},retention);}+type RateSample={admissions:number;age_seconds:number|null;gross:number|null;net:number|null;window_ids?:number|null;window_gross?:number|null;+ window_net?:number|null;window_span_days?:number|null;brain_age_days?:number|null;topology_ids?:number|null;topology_bytes?:number|null};+const RATE_SAMPLE_TTL_MS=60_000;+const rateSamples=new WeakMap<object,Map<string,{at:number;brain:string|undefined;sample:RateSample}>>();++/** The scope's admission sample and 7-day window; lifecycle changes count for the brain and for the local CLI writer, as in readCapacityForecast. */+async function readRateSample(engine:SqlEngine,scope:string,where:string,params:string[]):Promise<RateSample> {+ const topologyWhere=scope==='brain' ? '' : params[0]==='local_cli' ? 'AND principal_id::text=$2' : 'AND false';+ const [sample]=await engine.executeRaw<RateSample>(`WITH recent AS (+ SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where} ORDER BY sequence DESC LIMIT 1000),+ w AS (SELECT * FROM (SELECT id,created_at,terminal_reservation,authority,outcome,error_detail,client_request_id FROM persistence_requests ${where}+ ORDER BY sequence DESC LIMIT ${WINDOW_WALK_ROWS}) walk WHERE created_at>now()-interval '7 days'),+ e AS (SELECT request_id,SUM(${EFFECT_BYTES_SQL}) AS bytes FROM persistence_effects WHERE request_id IN (SELECT id FROM w) GROUP BY request_id)+ SELECT (SELECT count(*)::int FROM recent) AS admissions,(SELECT EXTRACT(EPOCH FROM (now()-min(created_at)))::float8 FROM recent) AS age_seconds,+ (SELECT avg(terminal_reservation)::float8 FROM recent) AS gross,+ (SELECT avg(LEAST(terminal_reservation,octet_length(authority::text)+COALESCE(octet_length(outcome::text),0)+COALESCE(octet_length(error_detail::text),0)+${COMPACTED_HEADROOM_BYTES}))::float8 FROM recent) AS net,+ (SELECT count(*)::int FROM w) AS window_ids,(SELECT EXTRACT(EPOCH FROM now()-min(created_at))/86400 FROM w)::float8 AS window_span_days,(SELECT COALESCE(SUM(terminal_reservation),0)::float8 FROM w) AS window_gross,+ (SELECT COALESCE(SUM(${COMPACTED_RECEIPT_BYTES_SQL('w', 'e')}),0)::float8 FROM w LEFT JOIN e ON e.request_id=w.id) AS window_net,+ (SELECT EXTRACT(EPOCH FROM now()-created_at)/86400 FROM persistence_requests ORDER BY sequence LIMIT 1)::float8 AS brain_age_days,+ (SELECT count(*)::int FROM persistence_topology_changes WHERE created_at>now()-interval '7 days' ${topologyWhere}) AS topology_ids,+ (SELECT COALESCE(SUM(terminal_bytes),0)::float8 FROM persistence_topology_changes WHERE created_at>now()-interval '7 days' ${topologyWhere}) AS topology_bytes`,+ params);+ return sample!;+}+/*** Upload sessions (Wave B, spec 6.2): staged bytes and open sessions per principal and per brain, counted in* persistence_counters under their own keys (`principal:<kind>:<id>:staged` and `brain:staged` in intent_bytes,diff --git a/test/persistence-capacity-notices.test.ts b/test/persistence-capacity-notices.test.tsindex ec345ceea2..c59bb42618 100644--- a/test/persistence-capacity-notices.test.ts+++ b/test/persistence-capacity-notices.test.ts@@ -15,6 +15,7 @@ import { __resetCapacityNoticesForTests, cachedCapacitySnapshot, CAPACITY_NOTICEimport { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';import { renderCapacityMetrics } from '../src/commands/serve-http-metrics.ts';import { NOTICE_CODES } from '../src/core/error-registry.ts';+import { renderNotice } from '../src/core/agent-output.ts';import { readCapacityForecast } from '../src/core/persistence/capacity-forecast.ts';import { oneYearCapacity, recommendedLimit } from '../src/core/persistence/limits.ts';import { editRequest, freshBrainFactory, requestFixture } from './helpers/persistence-request-fixture.ts';@@ -69,6 +70,11 @@ for (const kind of testBackends()) {expect(first[0]!.why).toContain('81%');expect(first[0]!.why).toContain('This write was saved');expect(first[0]!.why).not.toContain('config set');+ // A remote agent reads the rendered notice: over MCP its fix is the read-scope get_brain_health call, never a step to relay.+ for (const transport of ['http', 'stdio'] as const) {+ const fix = renderNotice(first[0]!, { transport, isCallable: tool => tool === 'get_brain_health', preapproved: () => true }).fix;+ expect(fix).toMatchObject({ actor: 'agent', next: 'run', mcp: { tool: 'get_brain_health' } });+ }expect(await capacityNotices(engine, { throttle: true, now: t0 + 1000 })).toEqual([]);expect(codes(await capacityNotices(engine, { throttle: false, now: t0 + 1000 }))).toEqual(['write_capacity_low']);expect(codes(await capacityNotices(engine, { throttle: true, now: t0 + CAPACITY_NOTICE_INTERVAL_MS }))).toEqual(['write_capacity_low']);@@ -150,6 +156,43 @@ for (const kind of testBackends()) {expect(await oneYearCapacity(engine, principal, 'TerminalBytes', terminal.used, terminal.limit)).toBe(terminal.recommended_limit);});+ check('the one-year value counts the week\'s lifecycle changes, as doctor does (GST-2107)', async engine => {+ const fixture = await requestFixture(engine);+ for (let i = 0; i < 14; i++) await fixture.admit(`week-${i}`);+ await engine.transaction(async tx => {+ await declarePersistenceProtocol(tx);+ await tx.executeRaw(`INSERT INTO persistence_topology_changes(principal_id,request_id,digest,operation,source_id,state,terminal_bytes)+ SELECT gen_random_uuid(),gen_random_uuid(),'d','source_add','source-a','committed',2048 FROM generate_series(1,56)`);+ });+ await engine.setConfig('persistence.limits.brain_lifetime_ids', '10');+ await engine.setConfig('persistence.limits.brain_terminal_bytes', '1');+ const forecast = await readCapacityForecast(engine);+ for (const [resource, setting] of [['lifetime_ids', 'LifetimeIds'], ['terminal_bytes', 'TerminalBytes']] as const) {+ const doctor = forecast.rows.find(r => r.scope === 'brain' && r.resource === resource)!;+ expect(await oneYearCapacity(engine, 'brain', setting, doctor.used, doctor.limit)).toBe(doctor.recommended_limit);+ }+ });++ check('repeated refusals within a minute reuse one rate read per scope, as a paused producer retries under the counter locks', async engine => {+ const fixture = await requestFixture(engine);+ for (let i = 0; i < 3; i++) await fixture.admit(`rate-${i}`);+ let walks = 0;+ const counted = { ...engine, executeRaw: (sql: string, params?: unknown[]) => {+ if (sql.includes('LIMIT 200000')) walks++;+ return engine.executeRaw(sql, params);+ } } as unknown as BrainEngine;+ const first = await oneYearCapacity(counted, 'brain', 'LifetimeIds', 3, 10);+ expect(await oneYearCapacity(counted, 'brain', 'LifetimeIds', 3, 10)).toBe(first);+ expect(await oneYearCapacity(counted, 'brain', 'TerminalBytes', 3, 10)).toBeGreaterThan(0);+ expect(walks).toBe(1);+ await fixture.admit('rate-new');+ expect(await oneYearCapacity(counted, 'brain', 'LifetimeIds', 4, 10)).toBeGreaterThanOrEqual(first);+ expect(walks).toBe(1);+ const principal = (await readCapacityForecast(engine)).rows.find(r => r.scope.startsWith('principal:'))!.scope;+ await oneYearCapacity(counted, principal, 'LifetimeIds', 4, 10);+ expect(walks).toBe(2);+ });+check('writes within a minute share one snapshot; the next minute reads again', async engine => {await requestFixture(engine).then(r => r.admit('one'));await engine.setConfig('persistence.limits.principal_lifetime_ids', '1000');