Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
remember: a service that names a member per call is told both save rules, and the refusal names the exact retry (GST-2243)
garrytan015056d35956
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f64a04ae92..6f2f0204eb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,7 +18,7 @@ identifiers and attribution are available in the pre-removal Git revision- `src/core/verbs.ts`: `remember` takes a `share` boolean on every MCP surface, starter included. A non-boolean `share`, `share: true` with `visibility: "private"`, and a member's `visibility: "world"` (`member_share_required`) are refused with `invalid_params` before anything is saved, so one such item refuses a whole batch.- `src/core/persistence/memory-mutations.ts`: a member's `share: true` saves on the entity page with world visibility; when that page's facts would be private (whatever `visibility` the call passed), the save is refused (`share_target_restricted`), and preparation refuses it again if the page turned restricted after admission. In a batch, items saved before a refused item stay saved, as with other save-time refusals. New and replayed replies carry `page` and `visibility`.-- `src/core/facts/writeback-instructions.ts`, `writeback-config.ts`, `src/mcp/instructions.ts`, the HTTP serves, the stdio serve bound through `mcp.stdio_member` and `memory_conversation_mode`: with ambient writeback on, a member caller is told to omit `visibility` and to pass `share: true` only for facts about the team's work, instead of the brain-wide "pass visibility: world" line its saves would now be refused for.+- `src/core/facts/writeback-instructions.ts`, `writeback-config.ts`, `src/mcp/instructions.ts`, the HTTP serves, the stdio serve bound through `mcp.stdio_member` and `memory_conversation_mode`: with ambient writeback on, a member caller is told to omit `visibility` and to pass `share: true` only for facts about the team's work, instead of the brain-wide "pass visibility: world" line its saves would now be refused for. A credential that may name a member per call (`x-qm-actor` on `remember`, as QM's service does) is told both: the member rule on calls made for a member, `visibility: "world"` on the rest. The `member_share_required` refusal names the exact retry.- `src/core/remember-batch.ts`: `share` is accepted per item and as a shared top-level key, and each item's receipt carries `page` and `visibility`.- `test/mcp-schema-budget.test.ts`: the starter tool-list ceilings and the `remember` budget grow by what `share` costs (+144 characters, 200 headroom kept).- QM's `memory_write` and its per-person contract (`docs/contracts/qm-memory-provider/v1.json`) are unchanged.diff --git a/src/commands/serve-http-mcp.ts b/src/commands/serve-http-mcp.tsindex cf56ed6ba7..31c0ba859b 100644--- a/src/commands/serve-http-mcp.ts+++ b/src/commands/serve-http-mcp.ts@@ -20,7 +20,7 @@ import { httpInstructionTools } from '../mcp/initialize-context.ts';import { installCapabilitiesResource, mcpAdministrationGuidance } from '../mcp/capabilities.ts';import { createSkillResources } from '../mcp/skill-resources.ts';import { resolveAuthCapabilities } from '../core/harness/capabilities.ts';-import { ambientOptsFrom, type WritebackConfig } from '../core/facts/writeback-config.ts';+import { ambientOptsFrom, writebackCaller, type WritebackConfig } from '../core/facts/writeback-config.ts';import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';import { hasScope, operationScopesAllowed } from '../core/scope.ts';import { summarizeMcpParams, dispatchToolCall, requestLogStatusForResult, requestMetaSessionId, hotMemoryOffIn, acceptedPendingReceipt, unknownToolEnvelope, errorResult, dispatchRenderContext, grantBlockedNotices, admitNotices, audienceRefusal, type ToolResult } from '../mcp/dispatch.ts';@@ -219,7 +219,7 @@ function createMcpRequestServer(writebackOpts = ambientOptsFrom(writeback, {remember: rememberOp !== undefined && opAllowedForBoundClient(authInfo, rememberOp),extractFacts: extractFactsOp !== undefined && opAllowedForBoundClient(authInfo, extractFactsOp),- member: !!authInfo?.member,+ ...writebackCaller(authInfo),});}const server = new Server(diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 5adf344a6d..cf9acefc0c 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1494,7 +1494,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.622.0', id: 'purge_cancels_deferred_write_gst1602', text: 'With `persistence.refresh_barrier` on, `gbrain forget <id> --purge` no longer refuses `purge_blocked_pending_recovery` while a write deferred behind a refresh holds the claim in its staged body: the deferred write was never claimed, so the purge cancels it with `purged_content`, as it does a queued one, and removes the content at once instead of up to 15 minutes later.' },{ since: '0.60.623.0', id: 'owner_reads_private_gst2059', text: 'A brain can now name its owner: `gbrain access owner set <member>` (config `access.owner_member`, an enabled member). Every remote credential or stdio server bound to that member reads the whole brain, `visibility: private` pages, privacy-alias pages (`access: private`, ...), derived and pinned-question pages included, through `get_page`, `search`, `query`, `recall` and the other page reads in the sources its grant reads, and `recall` returns its private facts. `readable_by` and folder rules still bind it, and it is not relaxed when it speaks for a shared-room audience. A page the owner\'s credential creates in `default` through `put_page` is not kept to the owner (no `readable_by: [member:<id>]`). Other members, unbound and public callers are unchanged. `_meta.access.relaxation` reads `owner` for such a call, and `gbrain access check --token <name>` reports it. `gbrain repair private-labels` (named runs only) previews the `access: private` labels stamped on ordinary pages with counts per category, keeps real restrictions, and clears the rest in reviewed batches (`--apply --expect <hash>`), recording each change so `--class restore` can put it back. The bulk-ingestion page template no longer writes an `access:` line; what each designation means is in docs/guides/access-designations.md.' },{ since: '0.60.626.0', id: 'record_origin_checkout_lockdown_8888', text: '`gbrain sources record-origin <id>... --remote --apply` now also turns git-lfs downloads and hooks off in each recorded source\'s existing checkout (its `.git/config`: `lfs.fetchexclude=*`, `core.hooksPath=/dev/null`, `lfs.locksverify=false`), not only on later reclones, in the repository\'s shared config, and refuses `write_failed` naming the key when a worktree-scoped or included setting still overrides one; a source already recorded as remote gets the lock-down on the next `--remote --apply` when its checkout lacks it, even when its files now use git-lfs, and a key that holds several values in that config is replaced by the one clone-time value. On a managed brain it takes the same worktree locks a reclone takes, refusing the id `source_busy` while a reclone, refresh or write holds them, and a reclone reads the record under its own locks. A write that fails is reported for its own id (`write_failed`) instead of ending the run. The git-lfs check reads a committed `.gitattributes` under a directory whose name holds a tab, ignores commented-out `filter=lfs` lines, says when a committed rule only declares an LFS filter, records a clone of an empty repository instead of refusing it, and names the cause of an `lfs_unknown` refusal.' },- { since: 'TBD', id: 'remember_share_gst2243', text: 'A member credential\'s `remember` still saves privately on `memory/members/<member>` by default, and can now pass `share: true` to save the fact on its subject\'s page for everyone who reads the source, as every non-member caller does. A member\'s explicit `visibility: "world"`, which used to be saved as private without a word, is now refused (`invalid_params`, reason `member_share_required`) and nothing is saved; `share: true` with `visibility: "private"`, or onto a page whose facts are kept private, is refused too (`share_target_restricted` for the page). Only the brain host can withdraw a shared fact. With ambient writeback on, a member credential\'s instructions say to omit `visibility` and use `share: true` for team facts. Every `remember` reply, for any caller, now names the `page` the fact went to and its `visibility`. QM\'s `memory_write` is unchanged.' },+ { since: 'TBD', id: 'remember_share_gst2243', text: 'A member credential\'s `remember` still saves privately on `memory/members/<member>` by default, and can now pass `share: true` to save the fact on its subject\'s page for everyone who reads the source, as every non-member caller does. A member\'s explicit `visibility: "world"`, which used to be saved as private without a word, is now refused (`invalid_params`, reason `member_share_required`) and nothing is saved; `share: true` with `visibility: "private"`, or onto a page whose facts are kept private, is refused too (`share_target_restricted` for the page). Only the brain host can withdraw a shared fact. With ambient writeback on, a member credential\'s instructions say to omit `visibility` and use `share: true` for team facts, and a credential that may name a member through `x-qm-actor` is told to do so on those calls and pass `visibility: "world"` on the rest. Every `remember` reply, for any caller, now names the `page` the fact went to and its `visibility`. QM\'s `memory_write` is unchanged.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/facts/writeback-config.ts b/src/core/facts/writeback-config.tsindex adc4091bd4..cfd52f71eb 100644--- a/src/core/facts/writeback-config.ts+++ b/src/core/facts/writeback-config.ts@@ -49,6 +49,7 @@import type { BrainEngine } from '../engine.ts';import type { GBrainConfig } from '../config.ts';+import type { AuthInfo } from '../ops/contract.ts';import { validateTtlConfig } from './ttl-parse.ts';export const AUTO_WRITEBACK_KEY = 'memory.auto_writeback';@@ -155,7 +156,7 @@ const lkg = new WeakMap<BrainEngine, WritebackConfig>();*/export function ambientOptsFrom(wb: WritebackConfig,- avail: { remember: boolean; extractFacts: boolean; member?: boolean },+ avail: { remember: boolean; extractFacts: boolean; member?: boolean; actor?: boolean },): AmbientOptsShape | null {if (!wb.enabled || wb.mode === 'off') return null;if (!avail.remember) return null;@@ -164,7 +165,7 @@ export function ambientOptsFrom(transientTtl: wb.transient_ttl,visibility: wb.visibility,extractFactsAvailable: avail.extractFacts,- ...(avail.member ? { member: true } : {}),+ ...(avail.member ? { member: true } : avail.actor ? { actor: true } : {}),};}interface AmbientOptsShape {@@ -173,6 +174,16 @@ interface AmbientOptsShape {visibility: 'world' | 'private';extractFactsAvailable: boolean;member?: boolean;+ actor?: boolean;+}++/**+ * GST-2243: who an HTTP credential writes as, for its instructions: a member-bound credential is one member; a credential+ * that may name a member per call (x-qm-actor on remember) writes as that member on those calls and as itself otherwise.+ */+export function writebackCaller(auth: Pick<AuthInfo, 'member' | 'attest'> | undefined): { member?: true; actor?: true } {+ if (auth?.member) return { member: true };+ return auth?.attest?.ops.includes('remember') ? { actor: true } : {};}/**diff --git a/src/core/facts/writeback-instructions.ts b/src/core/facts/writeback-instructions.tsindex f8c42beb1e..1dde579327 100644--- a/src/core/facts/writeback-instructions.ts+++ b/src/core/facts/writeback-instructions.ts@@ -28,6 +28,8 @@ export interface AmbientWritebackOpts {visibility: 'world' | 'private';/** GST-2243: the caller is one team member, whose remember is private unless it passes share: true. */member?: boolean;+ /** GST-2243: the credential may name the team member a call serves (x-qm-actor); those calls write as that member. */+ actor?: boolean;/** True only when `extract_facts` is actually callable on this transport's* allowed-op set (OV2-14) — never advertise an uncallable tool. The* engine-free harness block cannot probe the serve's surface, so it passes@@ -54,6 +56,8 @@ export function buildAmbientWritebackSection(opts: AmbientWritebackOpts): string: `always save via remember with ttl: "${opts.transientTtl}" — never batch them through extract_facts (it cannot set a ttl, so they would become permanent).`;const visibilityLine = opts.member? 'Omit visibility: your saves stay private to you. Pass share: true only for a fact about the team\'s work, never about a person; every reader of this source then recalls it, and only the brain host can withdraw it.'+ : opts.visibility === 'world' && opts.actor+ ? 'On a save made for a team member (x-qm-actor), omit visibility: it stays private to that member, and share: true shares a fact about the team\'s work with every reader of this source. On any other save, pass visibility: "world" explicitly. "world" means readable by agents authorized on THIS brain — not the public internet. Never widen a private fact on your own.': opts.visibility === 'world'? 'Pass visibility: "world" explicitly on every save. "world" means readable by agents authorized on THIS brain — not the public internet. Never widen a private fact on your own.': 'Pass visibility: "private" explicitly on every save — this brain\'s operator keeps facts private by default (omitting visibility would silently widen: remember defaults to world). Private facts are readable by the local CLI only, not by remote sessions: you, and every other MCP or HTTP session, cannot recall or forget a fact you save as private. Never widen to world on your own.';diff --git a/src/core/verbs.ts b/src/core/verbs.tsindex aa5a673d2b..4b5ced8f39 100644--- a/src/core/verbs.ts+++ b/src/core/verbs.ts@@ -190,7 +190,7 @@ const remember: Operation = {// GST-2243: a member shares only with share: true, so its explicit visibility "world" is refused, never quietly made private.if (p.share !== true && p.visibility === 'world' && ctx.attestedOp !== 'memory_write' && (await import('./access/member-facts.ts')).memberFactPage(ctx)) {throw Object.assign(verbError('invalid_params', 'remember: a member credential shares a fact with share: true, not visibility "world"; nothing was saved.',- 'Facts about the team\'s work: pass share: true and everyone who reads this source recalls them. Facts about a person: drop visibility and they stay on your own member page, recalled by you alone.'),+ 'Retry the same call with share: true in place of visibility "world" to share a fact about the team\'s work with everyone who reads this source, or with no visibility to keep a fact about a person on your own member page. A member shares only this way: pass share: true, never visibility "world".'),{ reason: 'member_share_required' });}if (p.valid_from !== undefined && !isStrictIsoDateTime(p.valid_from)) {diff --git a/src/mcp/http-transport.ts b/src/mcp/http-transport.tsindex 989224fdcb..c4057e443c 100644--- a/src/mcp/http-transport.ts+++ b/src/mcp/http-transport.ts@@ -34,7 +34,7 @@ import type { BrainEngine } from '../core/engine.ts';import { buildToolDefs } from './tool-defs.ts';import { MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from './instructions.ts';import { httpInstructionTools } from './initialize-context.ts';-import { ambientOptsFrom } from '../core/facts/writeback-config.ts';+import { ambientOptsFrom, writebackCaller } from '../core/facts/writeback-config.ts';import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';import { operations, operationsByName, opAllowedForBoundClient } from '../core/operations.ts';import { scopeDeniedError } from '../core/ops/op-fix.ts';@@ -473,7 +473,7 @@ export async function startHttpTransport(opts: HttpTransportOptions) {capabilities: { tools: {}, resources: {} },// #4748: contract (+ opt-in writeback section) + deployment identity.instructions: resolveMcpInstructions(fileConfig, process.env, {- writeback: ambientOptsFrom(writeback, { remember: canWriteOp('remember'), extractFacts: canWriteOp('extract_facts'), member: !!auth.auth?.member }),+ writeback: ambientOptsFrom(writeback, { remember: canWriteOp('remember'), extractFacts: canWriteOp('extract_facts'), ...writebackCaller(auth.auth) }),tools: await httpInstructionTools(engine, fileConfig, { ops: surfacedOps, surface, auth: auth.auth!, allowedOps: surfaceAllowedOps }), // F1...await readInstructionContent(engine),}),diff --git a/test/remember-share-gst2243.test.ts b/test/remember-share-gst2243.test.tsindex 78a2c5ee65..b5d2e3dbfd 100644--- a/test/remember-share-gst2243.test.ts+++ b/test/remember-share-gst2243.test.ts@@ -25,6 +25,8 @@ import { addMember, bindCredential } from '../src/core/access/members.ts';import { prepareMemoryMutation } from '../src/core/persistence/memory-prepare.ts';import { linkMember } from '../src/core/access/actor.ts';import type { AuthInfo } from '../src/core/ops/contract.ts';+import { ambientOptsFrom, writebackCaller } from '../src/core/facts/writeback-config.ts';+import { buildAmbientWritebackSection } from '../src/core/facts/writeback-instructions.ts';import { testBackends } from './helpers/test-backends.ts';import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';@@ -171,6 +173,24 @@ for (const kind of testBackends()) {expect(await factRow('canarymixedtwo')).toBeUndefined();}, 120_000);+ test('a QM service acting for a member is told both cases, and its plain remember with visibility "world" is refused with the exact retry', async () => {+ const opts = ambientOptsFrom({ enabled: true, mode: 'salient', transient_ttl: '3d', visibility: 'world' } as never, { remember: true, extractFacts: true, ...writebackCaller(await verify(tokens.qm!)) });+ const section = buildAmbientWritebackSection(opts!);+ expect(section).toContain('share: true');+ expect(section).toContain('visibility: "world"');+ expect(writebackCaller(await verify(tokens.plain!))).toEqual({});+ expect(writebackCaller(await verify(tokens.alice!))).toEqual({ member: true });+ const world = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, visibility: 'world' });+ expect(world.isError).toBe(true);+ expect(world.all).toContain('member_share_required');+ expect(world.all).toContain('Retry the same call with share: true in place of visibility');+ expect(await factRow('canaryactorworld')).toBeUndefined();+ const retried = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, share: true });+ expect([retried.isError, retried.json.page, retried.json.visibility]).toEqual([false, ACME, 'world']);+ const kept = await remember(who.alice(), 'Acme audit worried me canaryactorkept', { entity: ACME });+ expect([kept.isError, kept.json.page, kept.json.visibility]).toEqual([false, 'memory/members/alice-example', 'private']);+ }, 120_000);+test('QM memory_write, which takes no share, still saves on the member page, and share is on the starter surface', async () => {const out = await call(who.alice(), 'memory_write', { facts: [{ fact: 'Alice prefers async standups canaryqmwrite', provenance: 'qm test' }], idempotency_key: randomUUID() });expect(out.isError).toBe(false);