Skip to content

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.md
index 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.ts
index 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.ts
index 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, limit
const 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.ts
index 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_NOTICE
import { 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');