Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

feat(qm): contract v3 personal tools, structuredContent for attested reads, recall arm (GST-1158 B1, F2, F5)

garrytan061c9ff6d100
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db2f561cf2..5f80e9fa46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,16 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
+**An attested call to the tools QM's agent uses in a person's own DM now answers in `structuredContent`, and those tools are in a new contract, `v3.json`, with frozen result shapes.** `query`, `get_page`, `get_timeline`, `get_backlinks`, `find_experts`, `whois`, `entity`, `context_pack`, `volunteer_context`, `get_write_request` and `forget_fact` called with `x-qm-actor` put their result in `structuredContent` and their refusals in `structuredContent.error`, so QM decodes every answer from one place. `docs/contracts/qm-memory-provider/v3.json` keeps all of v2 and adds each of those tools with its served input schema and the fields every success carries; other fields may appear and are ignored. `get_write_request` freezes the seven write-request states, and a state outside them means unknown, not published. Each `memory_recall` fact now says which read found it (`arm`: `own` or `ranked`). Nothing became attestable by default: the operator still lists each tool in `--attest-ops`. `v1.json` and `v2.json` are unchanged.
+
+| Situation | Before | Now |
+|---|---|---|
+| Attested call to a v3 personal tool | JSON text in `content` only; a refusal had no `structuredContent.error` | the same JSON in `content` plus the result in `structuredContent` (a list as `structuredContent.results`); refusals carry `structuredContent.error` |
+| Attested `context_pack` | JSON in `content` | `content` is the rendered pack text; the rest of the result is in `structuredContent` |
+| Attested personal read over the result cap once `structuredContent` is counted | sent | refused whole with `result_too_large` |
+| `memory_recall` fact rows | `{id, text, date, kind}` | add `arm`: `own` or `ranked`; no score |
+| The same tools without `x-qm-actor` | as above | unchanged |
+
**An attested call can no longer write pages directly: `add_timeline_entry`, `add_link`, `put_page` and `edit_page` are not attestable.** They write to pages that everyone who reads the page sees, so a trusted system acting as one person could put that person's words in front of a whole audience with no one approving them. They now wait for owner-approved proposals, the way `capture` and take writes already do. An operator whose `--attest-ops` list names one of them sees `gbrain auth rescope` refuse the list, and each attested call to it is refused (`actor_not_attested`, reason `op_not_attested`); a queued attested write of one fails when it publishes. Unattested calls, and credentials bound to a member, are unchanged. `v2.json` lists the new deferred operations; `v1.json` is unchanged.
**A `memory_recall` that names sources reads as that scope, never as the attested person, so a shared turn can no longer recall one member's private facts into a shared channel.** `memory_recall` gains `source_id` and `source_ids`. Named, the read drops the person's own recent facts and every member-page fact, keeps restricted pages hidden and never relaxes `visibility: private`. The contract for it is the new `docs/contracts/qm-memory-provider/v2.json`; `v1.json` stays byte-identical and a test holds it there. Three smaller provider fixes ride along.
diff --git a/docs/architecture/key-files/access.md b/docs/architecture/key-files/access.md
index 9b6d84eef0..d7024d0f76 100644
--- a/docs/architecture/key-files/access.md
+++ b/docs/architecture/key-files/access.md
@@ -4,4 +4,4 @@
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). A derivative of a page that names readers is hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and before and after every managed pass (`performManagedSync`: sync, drain, `sources refresh`, git conversion), read with `git show` at the synced commit; a database with no revision yet replays each committed `access.yml` since the `access.approved` baseline, so a rebuild holds a removal a plain commit made); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v283 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`. Shared agents (B, GBRA-231): `audience.ts` parses the audience a harness asserts (`X-Gbrain-On-Behalf-Of` or request-level `_meta.on_behalf_of`, 1-50 principals, `guest` = the empty identity; the same key inside tool arguments is refused) and appends each assertion to `access-audience-YYYY-Www.jsonl`. Dispatch resolves it on every remote call through `caller.ts` (`resolveAudienceIdentities`: every entry must be in the credential's live `may_act_for`, then name an enabled member or existing group); the caller-access record then carries `audienceIdentities`, and `accessAllowedForAllSql` needs one readers conjunct per identity, folder rules the intersection of each entry's satisfied set (`folderAccessForAll`). Privacy relaxes only for a one-member audience. Writes carry the audience as `WriteAuthority.actingFor` (re-resolved at publication) and agent jobs as `grant.actingFor`. Every remote response carries `_meta.access` (`appliedAccessSummary`), which `whoami` returns as `access.applied`; doctor `access_may_act_for_wildcard` (`checks/shared-agent-access.ts`) warns on `*`. Tests: `test/access-on-behalf-of.test.ts` (both engines), `test/e2e/serve-http-on-behalf-of.test.ts`. Attested actor (C1, GST-359): `actor-model.ts` (dependency-free: `x-qm-actor`, `acting_user`, `EXTERNAL_ID_RE` = 1-256 visible ASCII, `attestRightFrom`: the right counts only for a member-less credential whose token is legacy or `client_credentials`, read from `oauth_tokens.grant_type`) and `actor.ts`. `resolveAttestedActor` runs in dispatch before any work: an invalid id refuses `actor_not_attested` (`invalid_actor_id`) before any lookup, then the right, the op list (`attest_ops`, default `get_write_request,memory_recall,memory_write`), `acting_user` = header (stripped), and `actorCoverage` (the one coverage test: live right plus a live link in `access_member_links` to an enabled member, compared exactly) or `actor_unlinked`. `ACTOR_DEFERRED_OPS` (`capture`, `extract_facts`, take writes, `list_write_conflicts`) are never attestable until each is keyed to the member: refused by `parseAttestOps`, `bindCredential`, every call and the stored re-check, which also re-checks `attest_ops` for a queued write's operation and each job tool call. Under the header serve-http lists only attested tools and refuses `resources/read`. `attestedCallerAccess` is a one-member audience with privacy never relaxed (no granted sources, no hatch), never B's `may_act_for` path. Writes store `WriteAuthority.actingFor = {system, external_id, member}` and jobs `grant.actor`; `storedActorIdentity` re-resolves both through `actorCoverage` and refuses when the member changed. `linkMember` / `unlinkMember` / `listMemberLinks` back `gbrain access member link|unlink|links`; `--attest-actor` / `--attest-ops` on `auth rescope` (`members.ts`) only for a member-less legacy token or confidential client-credentials client. Migration v286. Tests: `test/access-qm-actor.test.ts` (both engines), `test/e2e/serve-http-qm-actor.test.ts`. Member facts (C2, GST-359): `member-facts.ts`. A remote `remember` from an attested actor or a lone-member credential (`callerMember`, never an audience of several) writes to `memory/members/<member>` (`memberFactPage`; `persistence/memory-prepare.ts` creates the page with `readable_by: [member:<id>]`), `visibility: private`, `infer_entity` off, the entity kept as `entity_slug`. A member id whose page slug `slugifyPath` would change (`a--b`, `zed-`) is refused (`invalid_params`). The page must name that member alone (`memberPageIsOwn`, checked at submission and again in preparation, `memberPageNotOwned`), and remote writes under `memory/members/` go only to the caller's own page (`assertMemberPageWriter`, called from `ops/context.ts` `enforceClientSlugFence`, so every remote page write passes it; trusted local callers are unaffected). Reads widen a world-only fact list only by `memberFactAdmitSql` (a private fact on the caller's own live member page whose readers and folder rules admit the caller; `factVisibilitySql` in `engine-sql/facts.ts` and `search/fact-relevance.ts`), and `privateProvenanceFilterUnderPolicy` judges a member-page fact's source page as the caller (every other fact keeps the empty identity, so a fact from a page that names readers stays hidden from every remote caller). Writers never cross pages: `facts/single-prepare.ts` (`SingleFactIntent.page_slug`) and `trust/supersede-handlers.ts` dedup, supersede and contest only within the member page, and no other write matches a fact there (`onMemberPageSql`); consolidation skips facts whose page names readers (`readersSourcedFactSql`). Per-person keys: `callerIdentityKey` joins the hot-memory cache key (`facts/meta-hook.ts`, `::xid=`), `callerSessionKey` the `delta` cursor (`ops/facts.ts`), `sameAttestedActor` gates receipts (`persistence/authority.ts` `ownRequestAccessible`) and replays (`persistence/journal.ts`), and `get_agent_job` and the owner-fenced `get_job`, `wait_job`, `get_job_progress`, `list_jobs` and `cancel_job` match the job's `grant.actor` (system, external id, member; `jobActorSql` in `minions/types.ts`), so a job with an actor reads as missing to the bare client and to other actors. Tests: `test/access-member-facts.test.ts` (both engines), `test/access-member-sweep.test.ts` (every attestable op as Bob, the bare client and an unbound credential; `test/helpers/member-sweep.ts`), `test/e2e/serve-http-member-sweep.test.ts` (two members over a real `serve --http` on a keyless repo-less brain).
-- `src/core/ops/qm-memory.ts` (GST-359 D) — QM's memory provider pair. `memory_recall` reads the attested person's own last-24-hour facts on their member page (`listFactsSince` with `sourceMarkdownSlug`), then `rankFactsByQuestion` over the facts they may read, renders one plain line per fact (`plainFactText` strips fence and heading markers) and cuts at a line within `max_chars` (`boundFactLines`). `memory_write` validates 1-20 facts, derives each request id from uuidv5(member, idempotency_key) (`memoryWriteRequestId`) and saves through `remember`'s handler with `ctx.attestedOp = 'memory_write'`, which the stored write authority keeps (`WriteAuthority.attestedOp`) so publication and receipt reads re-check that operation's attest right. `qmMemoryToolResult` (dispatch) moves the result into `structuredContent` and leaves the model text in `content`; `unlinkedRecallResult` is the empty success dispatch's `actorRefusal` returns for an unlinked person. Contract fixture: `scripts/build-qm-memory-contract.ts` writes `docs/contracts/qm-memory-provider/v1.json` (a `regen:all` artifact). Tests: `test/qm-memory-tools.test.ts` (both engines), `test/qm-memory-contract.test.ts` (drift), `test/e2e/serve-http-qm-memory.test.ts` (keyless `serve --http`).
+- `src/core/ops/qm-memory.ts` (GST-359 D) — QM's memory provider pair. `memory_recall` reads the attested person's own last-24-hour facts on their member page (`listFactsSince` with `sourceMarkdownSlug`), then `rankFactsByQuestion` over the facts they may read, renders one plain line per fact (`plainFactText` strips fence and heading markers) and cuts at a line within `max_chars` (`boundFactLines`). `memory_write` validates 1-20 facts, derives each request id from uuidv5(member, idempotency_key) (`memoryWriteRequestId`) and saves through `remember`'s handler with `ctx.attestedOp = 'memory_write'`, which the stored write authority keeps (`WriteAuthority.attestedOp`) so publication and receipt reads re-check that operation's attest right. `qmMemoryToolResult` (dispatch) moves the result into `structuredContent` and leaves the model text in `content`; GST-1158 F2 does the same for an attested call to a contract v3 personal tool (`QM_PERSONAL_OPS`), keeping its JSON in `content` (a list as `structuredContent.results`; context_pack's text alone, like memory_recall), and dispatch measures that frame against the result cap again; each memory_recall fact carries `arm` (`own` or `ranked`, F5); `unlinkedRecallResult` is the empty success dispatch's `actorRefusal` returns for an unlinked person. Contract fixture: `scripts/build-qm-memory-contract.ts` writes `docs/contracts/qm-memory-provider/v1.json`, `v2.json` and `v3.json` (a `regen:all` artifact; v3 adds the personal tools with frozen result shapes). Tests: `test/qm-memory-tools.test.ts` (both engines), `test/qm-personal-tools.test.ts` (v3 tools over dispatch, both engines), `test/qm-memory-contract.test.ts` (drift), `test/e2e/serve-http-qm-memory.test.ts` (keyless `serve --http`).
diff --git a/docs/contracts/qm-memory-provider/README.md b/docs/contracts/qm-memory-provider/README.md
index ac762541ca..c465a9835f 100644
--- a/docs/contracts/qm-memory-provider/README.md
+++ b/docs/contracts/qm-memory-provider/README.md
@@ -6,9 +6,23 @@ limits, the `x-qm-actor` header and actor id pattern, every error code and
`actor_not_attested` reason with its fix, the operations not attestable yet, and
the `x-qm-audience` header, refused until wave 2.
-It is generated from the live operation registry by
+`v2.json` adds the scope read (`source_id` / `source_ids` on `memory_recall`).
+`v3.json` keeps all of v2 and adds `personal_tools`: the tools QM's agent calls in
+a person's own DM, read as that person (`query`, `get_page`, `get_timeline`,
+`get_backlinks`, `find_experts`, `whois`, `entity`, `context_pack`,
+`volunteer_context`, `get_write_request`, `forget_fact`). Each entry carries the
+served input schema and a frozen result shape: the fields every success carries,
+with other fields allowed and ignored. `get_write_request` freezes the write-request
+states, and a state not listed means unknown, not published. v3 also adds each
+`memory_recall` fact's `arm` (`own` or `ranked`). None of the v3 tools is a
+default attested operation (only `get_write_request` is): the brain operator lists
+each one in the client's `--attest-ops`. No v3 tool is marked as a shared-scope
+read yet; a later version adds those markings.
+
+They are generated from the live operation registry by
`bun scripts/build-qm-memory-contract.ts` (part of `bun run regen:all`), and
-`test/qm-memory-contract.test.ts` fails when the committed file drifts.
+`test/qm-memory-contract.test.ts` fails when a committed file drifts.
-A change to the shape is a new file, `v2.json`; `v1.json` stays until QM moves.
+A change to the shape is a new file; a published file never changes, and
+`v1.json` stays byte-identical until QM moves.
Operator setup is in [docs/guides/qm.md](../../guides/qm.md).
diff --git a/docs/contracts/qm-memory-provider/v3.json b/docs/contracts/qm-memory-provider/v3.json
new file mode 100644
index 0000000000..1803aa6a35
--- /dev/null
+++ b/docs/contracts/qm-memory-provider/v3.json
@@ -0,0 +1,1389 @@
+{
+ "contract": "gbrain.qm-memory-provider",
+ "version": 3,
+ "transport": {
+ "protocol": "mcp",
+ "session": "stateless",
+ "session_header_issued": false,
+ "success_codes_in": "structuredContent",
+ "unknown_arguments": "an argument a read tool does not declare is ignored and reported only in _meta.warnings ([{code: \"unknown_param\", param, suggestion?}]), never in content; a write tool refuses it with invalid_params"
+ },
+ "actor": {
+ "header": "x-qm-actor",
+ "argument": "acting_user",
+ "argument_rule": "optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential; never chooses the person on its own",
+ "actor_id": {
+ "pattern": "^[\\x21-\\x7e]{1,256}$",
+ "case_folding": false
+ },
+ "system": "qm",
+ "default_attest_ops": [
+ "get_write_request",
+ "memory_recall",
+ "memory_write"
+ ],
+ "deferred_ops": [
+ "add_link",
+ "add_timeline_entry",
+ "capture",
+ "edit_page",
+ "extract_facts",
+ "list_write_conflicts",
+ "put_page",
+ "takes_add",
+ "takes_resolve",
+ "takes_supersede",
+ "takes_update"
+ ],
+ "audit": "the audit trail and stored writes record the canonical external id as sent, with its linked member"
+ },
+ "tools": [
+ {
+ "name": "memory_recall",
+ "description": "Facts for the person this call serves, one per line: their own recent facts first, then facts matching query. Never page bodies. For QM; agents use recall.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "What the turn is about; ranks the facts."
+ },
+ "max_chars": {
+ "type": "integer",
+ "description": "Text cap in UTF-16 code units, 200-12000 (default 6000)."
+ },
+ "acting_user": {
+ "type": "string",
+ "description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Read this one source as its audience (a shared scope): never the person's own facts."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Read only these sources as their audience (a shared scope): never the person's own facts.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": [
+ "query"
+ ]
+ }
+ },
+ {
+ "name": "memory_write",
+ "description": "Save facts for the person this call serves, readable by them alone. Needs an attested person. The same idempotency_key replays the first receipt. For QM; agents use remember.",
+ "scope": "write",
+ "mutating": true,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "facts": {
+ "type": "array",
+ "description": "1-20 facts.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "fact": {
+ "type": "string",
+ "description": "One claim."
+ },
+ "provenance": {
+ "type": "string",
+ "description": "Where it came from (<=200 chars)."
+ },
+ "kind": {
+ "type": "string",
+ "description": "Default fact.",
+ "enum": [
+ "event",
+ "preference",
+ "commitment",
+ "belief",
+ "fact"
+ ]
+ },
+ "valid_from": {
+ "type": "string",
+ "description": "When it became true (ISO 8601)."
+ }
+ },
+ "required": [
+ "fact",
+ "provenance"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "idempotency_key": {
+ "type": "string",
+ "description": "1-128 visible ASCII characters; the same key replays this write."
+ },
+ "acting_user": {
+ "type": "string",
+ "description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
+ }
+ },
+ "required": [
+ "facts",
+ "idempotency_key"
+ ]
+ }
+ }
+ ],
+ "personal_tools": {
+ "read_as": "the attested person (x-qm-actor): what that person may read, their own restricted pages included, so use these tools only in the person's own conversations; no tool here is marked as a shared-scope read yet",
+ "opt_in": "only get_write_request is in default_attest_ops: the brain operator lists each other tool in the client's --attest-ops (gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>), or it is refused with actor_not_attested reason op_not_attested",
+ "structured_content": "an attested success carries the result in structuredContent and keeps it as JSON in content (notice blocks follow it); a list arrives as structuredContent.results; context_pack's text alone fills content, as memory_recall's does; an unattested call to the same tool gets no structuredContent",
+ "result_rule": "each result lists the fields every success carries; other fields may appear and must be ignored",
+ "tools": [
+ {
+ "name": "context_pack",
+ "description": "Core memory, budget-packed cards, open threads and hot facts for up to 8 entities, zero LLM. Call at session start and after compaction.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "string",
+ "description": "Comma-separated names or slugs (max 8)."
+ },
+ "budget_tokens": {
+ "type": "number",
+ "description": "Token budget; cards pack first."
+ },
+ "since": {
+ "type": "string",
+ "description": "Open-thread events after this ISO time."
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Opaque session id."
+ },
+ "include_private": {
+ "type": "boolean",
+ "description": "Local trusted callers only."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "include_quarantined": {
+ "type": "boolean",
+ "description": "Admin or memory_confirm: quarantined cards."
+ },
+ "counterparty": {
+ "type": "string",
+ "description": "Person or company (name or slug): adds a pulled brief of dated items about them."
+ },
+ "intent": {
+ "type": "string",
+ "description": "With counterparty: the task the brief is for.",
+ "enum": [
+ "meeting",
+ "reply"
+ ]
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Resolve entities in this source only. Default: your source first, then every source you can read."
+ },
+ "entity_refs": {
+ "type": "array",
+ "description": "Source-qualified entities: [{\"source_id\":\"wiki\",\"slug\":\"people/alice-example\"}].",
+ "items": {
+ "type": "object",
+ "properties": {
+ "source_id": {
+ "type": "string"
+ },
+ "slug": {
+ "type": "string"
+ }
+ },
+ "required": [],
+ "additionalProperties": false
+ }
+ },
+ "prefer_source_id": {
+ "type": "string",
+ "description": "Source to try first (thin clients send .gbrain-source here); never narrows."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "result": {
+ "content": "the rendered pack text alone, as memory_recall's; it is not repeated in structuredContent",
+ "structured_content": {
+ "protocol_version": "number",
+ "entities": [
+ "string"
+ ],
+ "cards": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string"
+ }
+ ],
+ "open_threads": "array",
+ "facts": [
+ {
+ "fact": "string",
+ "kind": "string",
+ "fact_id": "string"
+ }
+ ],
+ "entity_facts": "array"
+ }
+ }
+ },
+ {
+ "name": "entity",
+ "description": "Person/company/account card, zero LLM. Previews are not evidence: fetch the page before stating status or dates. Miss: found:false with near matches (create_safety). Facts: recall.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Name, alias or slug."
+ },
+ "names": {
+ "type": "array",
+ "description": "Or up to 50 names/codes at once: compact rows.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Read only this source. Default: your source first, then every source you can read."
+ },
+ "prefer_source_id": {
+ "type": "string",
+ "description": "Source to try first (thin clients send .gbrain-source here); never narrows."
+ },
+ "variants": {
+ "type": "boolean",
+ "description": "false: exact names only. Default true: with no exact match, one unambiguous name variant (card.match says which)."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "protocol_version": "number",
+ "found": "boolean"
+ },
+ "optional": {
+ "card": "object when found: card.entity holds slug, source_id, title and type",
+ "suggestions": "array of {slug, title} when not found",
+ "ambiguous": "true: the name matched several entities"
+ },
+ "with_names": {
+ "protocol_version": "number",
+ "results": [
+ {
+ "name": "string",
+ "found": "boolean"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "name": "find_experts",
+ "description": "Answers 'who in my brain knows about <topic>'. Returns ranked person/company pages by expertise depth (sub-linear match score), relationship recency (exp decay with 6-month half-life), and salience. Use this for questions like 'who should I talk to about X', 'who knows about Y', 'find me someone who's worked on Z', or any expertise-routing intent. Filters at SQL to person + company pages — does NOT return notes or articles. Pair with --explain (CLI) to surface the per-result factor breakdown.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "topic": {
+ "type": "string",
+ "description": "The topic to route. Free-form natural language."
+ },
+ "limit": {
+ "type": "number",
+ "description": "Max results (default 5)."
+ },
+ "explain": {
+ "type": "boolean",
+ "description": "Include factor breakdown per result (expertise, recency, salience)."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string",
+ "score": "number"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "name": "forget_fact",
+ "description": "Forget a fact by recording a durable withdrawal in its source and visibility. Strikes the Markdown facts fence when writable; otherwise keeps the withdrawal in the database. Stale imports cannot reactivate the same normalized claim. This retracts memory; original prose, files and backups may retain the text. Idempotent on already-expired or unknown ids.",
+ "scope": "write",
+ "mutating": true,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "request_id": {
+ "type": "string",
+ "description": "Reuse only to retry."
+ },
+ "id": {
+ "type": "number",
+ "description": "Fact id to forget."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional reason; written to the fence row's context cell as \"forgotten: <reason>\". Default: \"forgotten\"."
+ }
+ },
+ "required": [
+ "id"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "id": "number",
+ "request_id": "string",
+ "state": "\"queued\" | \"running\" | \"recovering\" | \"committed\" | \"conflict\" | \"failed\" | \"cancelled\""
+ },
+ "optional": {
+ "expired": "boolean: the fact is withdrawn"
+ },
+ "note": "withdraws only a fact on the person's own member page (any other id is fact_not_found); send request_id (a UUID) so a retry replays the same withdrawal; a state other than committed is read with get_write_request"
+ }
+ },
+ {
+ "name": "get_backlinks",
+ "description": "Links to a page, ≤500/call; group:\"page\" by referrer, newest first.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Page slug."
+ },
+ "status": {
+ "type": "string",
+ "description": "Default live.",
+ "enum": [
+ "live",
+ "all"
+ ]
+ },
+ "as_of": {
+ "type": "string",
+ "description": "YYYY-MM-DD"
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "all_sources": {
+ "type": "boolean",
+ "description": "Same as source_id __all__."
+ },
+ "type": {
+ "type": "string",
+ "description": "Referrer type."
+ },
+ "group": {
+ "type": "string",
+ "description": "Per page.",
+ "enum": [
+ "page"
+ ]
+ },
+ "limit": {
+ "type": "number",
+ "description": "≤5000"
+ },
+ "cursor": {
+ "type": "string",
+ "description": "Next."
+ },
+ "all": {
+ "type": "boolean",
+ "description": "Local CLI only: every row, paging internally."
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "from_slug": "string",
+ "from_source_id": "string",
+ "to_slug": "string",
+ "to_source_id": "string",
+ "link_type": "string"
+ }
+ ]
+ },
+ "optional": {
+ "results[].truncated": "true on the last row when more remain",
+ "results[].next_cursor": "string on that row: pass it as cursor"
+ },
+ "with_group_page": {
+ "rows": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string"
+ }
+ ],
+ "total": "number",
+ "truncated": "boolean",
+ "cursor": "string | null"
+ }
+ }
+ },
+ {
+ "name": "get_page",
+ "description": "Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Page slug."
+ },
+ "fuzzy": {
+ "type": "boolean",
+ "description": "Fuzzy match."
+ },
+ "include_content": {
+ "type": "boolean",
+ "description": "Markdown + revision."
+ },
+ "content_only": {
+ "type": "boolean",
+ "description": "Round-trip fields."
+ },
+ "body": {
+ "type": "string",
+ "description": "auto: whole up to 256 KB, else outline + window; a window's edit_target is edit_page `within`. none: revision + size + tail_sha256 (append_page expected_tail_sha256).",
+ "enum": [
+ "auto",
+ "full",
+ "none",
+ "outline",
+ "window"
+ ]
+ },
+ "lines": {
+ "type": "object",
+ "description": "Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.",
+ "properties": {
+ "from": {
+ "type": "number"
+ },
+ "count": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "from",
+ "count"
+ ],
+ "additionalProperties": false
+ },
+ "bytes": {
+ "type": "object",
+ "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start). One window selector only: not with lines, around_chunk_id or cursor.",
+ "properties": {
+ "offset": {
+ "type": "number"
+ },
+ "length": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "offset",
+ "length"
+ ],
+ "additionalProperties": false
+ },
+ "around_chunk_id": {
+ "type": "number",
+ "description": "Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor."
+ },
+ "context_lines": {
+ "type": "number",
+ "description": "Lines around around_chunk_id (20)."
+ },
+ "cursor": {
+ "type": "string",
+ "description": "next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id."
+ },
+ "max_bytes": {
+ "type": "number",
+ "description": "Window bytes (40000)."
+ },
+ "view": {
+ "type": "string",
+ "description": "markdown: page the round-trip content.",
+ "enum": [
+ "read",
+ "markdown"
+ ]
+ },
+ "outline_from": {
+ "type": "number",
+ "description": "Outline next_from_index."
+ },
+ "section": {
+ "type": "string",
+ "description": "Only the section under this heading (case-insensitive, first match), with its heading_path."
+ },
+ "grep": {
+ "type": "string",
+ "description": "Only the paragraphs containing this text (case-insensitive substring, not a regex), with line numbers and total_matches."
+ },
+ "context": {
+ "type": "number",
+ "description": "Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5)."
+ },
+ "include_deleted": {
+ "type": "boolean",
+ "description": "Soft-deleted too."
+ },
+ "include_timeline_entries": {
+ "type": "boolean",
+ "description": "Timeline rows."
+ },
+ "grammar_diagnostics": {
+ "type": "boolean",
+ "description": "Also return every line-grammar finding for the page."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "include_quarantined": {
+ "type": "boolean",
+ "description": "Admin: quarantined body."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "known_as_of": {
+ "type": "string",
+ "description": "Recorded time: the page as this brain had recorded it at this ISO 8601 instant (2026-10-01T12:00:00Z), from the belief ledger. Not as_of, which is valid time (a date)."
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "slug": "string",
+ "source_id": "string",
+ "type": "string",
+ "title": "string",
+ "revision": "string"
+ },
+ "optional": {
+ "compiled_truth": "string: a whole read",
+ "timeline": "string: a whole read",
+ "body": "\"none\" | \"outline\" | \"window\": a partial read (a page over the inline size, or the body argument); it carries no compiled_truth",
+ "truncated": "boolean: a partial read left text out",
+ "resolved_slug": "string: the slug an alias resolved to"
+ },
+ "note": "a page the person may not read answers page_not_found, the same as a missing one"
+ }
+ },
+ {
+ "name": "get_timeline",
+ "description": "Get timeline entries for a page, optionally filtered by date window. To change or remove an entry, edit its bullet in the page's Timeline section with edit_page (expected_revision from get_page include_content:true): the row follows the page.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Slug of the page whose timeline entries to return."
+ },
+ "after": {
+ "type": "string",
+ "description": "Return entries on or after this date (YYYY-MM-DD)"
+ },
+ "before": {
+ "type": "string",
+ "description": "Return entries on or before this date (YYYY-MM-DD)"
+ },
+ "since": {
+ "type": "string",
+ "description": "Alias for after; accepted for agent callers"
+ },
+ "until": {
+ "type": "string",
+ "description": "Alias for before; accepted for agent callers"
+ },
+ "limit": {
+ "type": "number",
+ "description": "Maximum number of timeline entries to return"
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "id": "number",
+ "date": "string",
+ "summary": "string",
+ "source": "string",
+ "detail": "string"
+ }
+ ]
+ },
+ "note": "a page the person may not read answers an empty list"
+ }
+ },
+ {
+ "name": "get_write_request",
+ "description": "Your write's receipt by request_id (after write_pending or a lost reply). Poll at retry_after_ms until final.",
+ "scope": "write",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "request_id": {
+ "type": "string",
+ "description": "The id you sent, or the receipt's."
+ },
+ "applied": {
+ "type": "boolean",
+ "description": "Also return applied: searchable yet, the gap, the write watermark."
+ }
+ },
+ "required": [
+ "request_id"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "request_id": "string",
+ "state": "\"queued\" | \"running\" | \"recovering\" | \"committed\" | \"conflict\" | \"failed\" | \"cancelled\"",
+ "retry_after_ms": "number | null",
+ "operation": "string",
+ "source_id": "string",
+ "slug": "string | null",
+ "created_at": "string",
+ "updated_at": "string"
+ },
+ "optional": {
+ "write_error": "string: why a write ended without publishing",
+ "outcome": "object: the published write's result"
+ },
+ "states": {
+ "known": [
+ "queued",
+ "running",
+ "recovering",
+ "committed",
+ "conflict",
+ "failed",
+ "cancelled"
+ ],
+ "terminal": [
+ "committed",
+ "conflict",
+ "failed",
+ "cancelled"
+ ],
+ "published": "committed",
+ "unknown": "a state not listed here means unknown, not published: never report the write as saved; poll again or report it as unknown",
+ "poll": "until a terminal state, after retry_after_ms when it is set"
+ }
+ }
+ },
+ {
+ "name": "query",
+ "description": "Hybrid search for concept/landscape questions and people/companies/projects by topic; adds fact rows. expand: one LLM call (expansion recovers synonyms; rarely helps). Still top-K; return_unit: sections or conversations. Lists: list_pages. Exact tokens: `search` is cheaper. Personal: get_recent_salience, find_anomalies; transcripts: `gbrain transcripts recent`. Do NOT assume 'crazy' means impressive (often difficult or emotionally charged). Needs an embedding key (else keyword-only); expansion needs a chat key. Fact rows: use follow_up. fields: \"full\" adds diagnostics.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Question or topic (required unless image)."
+ },
+ "image": {
+ "type": "string",
+ "description": "Base64 image."
+ },
+ "image_mime": {
+ "type": "string",
+ "description": "MIME type of image."
+ },
+ "limit": {
+ "type": "number",
+ "description": "Default 10/25/50 by search mode."
+ },
+ "offset": {
+ "type": "number",
+ "description": "Rows to skip."
+ },
+ "types": {
+ "type": "array",
+ "description": "Page types, e.g. ['person'].",
+ "items": {
+ "type": "string"
+ }
+ },
+ "where": {
+ "type": "object",
+ "description": "Frontmatter equality, e.g. {status: \"active\"}; a list matches any."
+ },
+ "snippet_chars": {
+ "type": "number",
+ "description": "Chars per row (0 = full)."
+ },
+ "return_unit": {
+ "type": "string",
+ "description": "Default auto: whole conversations.",
+ "enum": [
+ "chunk",
+ "window",
+ "section",
+ "page",
+ "auto"
+ ]
+ },
+ "return_window": {
+ "type": "number",
+ "description": "Window radius 1-3."
+ },
+ "token_budget": {
+ "type": "number",
+ "description": "Evidence token cap."
+ },
+ "expand": {
+ "type": "boolean",
+ "description": "Default off; one LLM call, rarely helps."
+ },
+ "detail": {
+ "type": "string",
+ "description": "low (compiled truth), medium (default) or high (all chunks)."
+ },
+ "fields": {
+ "type": "string",
+ "description": "lean (remote default) or full.",
+ "enum": [
+ "lean",
+ "full"
+ ]
+ },
+ "mode": {
+ "type": "string",
+ "description": "Local callers only."
+ },
+ "lang": {
+ "type": "string",
+ "description": "Code language."
+ },
+ "symbol_kind": {
+ "type": "string",
+ "description": "Code symbol type."
+ },
+ "near_symbol": {
+ "type": "string",
+ "description": "Anchor code symbol."
+ },
+ "walk_depth": {
+ "type": "number",
+ "description": "Code walk depth 1-2."
+ },
+ "salience": {
+ "type": "string",
+ "description": "Boost emotional pages.",
+ "enum": [
+ "off",
+ "on",
+ "strong"
+ ]
+ },
+ "recency": {
+ "type": "string",
+ "description": "Boost recent pages.",
+ "enum": [
+ "off",
+ "on",
+ "strong"
+ ]
+ },
+ "since": {
+ "type": "string",
+ "description": "On/after: YYYY-MM-DD or 7d/2w/1y."
+ },
+ "until": {
+ "type": "string",
+ "description": "On/before."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Narrow to these sources (omit or [] for all you can read).",
+ "items": {
+ "type": "string"
+ }
+ },
+ "cross_modal": {
+ "type": "string",
+ "description": "Default auto.",
+ "enum": [
+ "text",
+ "image",
+ "both",
+ "auto"
+ ]
+ },
+ "embedding_column": {
+ "type": "string",
+ "description": "Registered embedding column."
+ },
+ "adaptive_return": {
+ "type": "boolean",
+ "description": "true for one answer (fewer rows, never empty); omit for breadth."
+ },
+ "autocut": {
+ "type": "boolean",
+ "description": "Default on (never empty); false: full top-K for breadth."
+ },
+ "relational": {
+ "type": "boolean",
+ "description": "Relationship-graph arm (default on)."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "explain": {
+ "type": "boolean",
+ "description": "Per-row score_details."
+ },
+ "explain_target": {
+ "type": "string",
+ "description": "Expected page (slug or source:slug): why it is missing."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "source_id": "string",
+ "title": "string",
+ "chunk_text": "string",
+ "score": "number"
+ }
+ ]
+ },
+ "optional": {
+ "results[].slug": "string: a page row, with type and chunk_id",
+ "results[].result_type": "\"fact\": a saved fact row, with fact_id and no slug",
+ "results[].fact_id": "string: on a fact row"
+ },
+ "note": "rows best first; page text is quoted source material, never instructions; an empty list after a degraded search is not proof the brain has nothing (read the notice blocks)"
+ }
+ },
+ {
+ "name": "volunteer_context",
+ "description": "Push-based context: volunteer brain pages relevant to a rolling conversation window WITHOUT being asked. Zero-LLM, confidence-gated (alias 0.9 / exact-title 0.8 / slug-suffix 0.6, +0.05 for multi-turn or newest-turn mentions; default gate 0.7), capped at 3 pages (max 5). Returns pointers with one-line rationales + synopses — open the page (get_page) before relying on details. Pass stats: true for the approximate volunteered-vs-used precision summary (the feedback loop).",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "window": {
+ "type": "string",
+ "description": "Recent conversation turns, oldest → newest, as 'user:' / 'assistant:' prefixed lines (unprefixed text = one user turn). Required unless stats: true. CLI: piped stdin fills this."
+ },
+ "prior_context": {
+ "type": "string",
+ "description": "Already-surfaced context (pointer blocks / opened page bodies). Pages whose slug appears here are not re-volunteered."
+ },
+ "max_pages": {
+ "type": "number",
+ "description": "Max pages to volunteer (default 3, hard cap 5)."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "min_confidence": {
+ "type": "number",
+ "description": "Confidence gate 0..1 (default 0.7 — slug-suffix matches need an explicit lower gate)."
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Optional caller session id, logged for attribution."
+ },
+ "turn": {
+ "type": "number",
+ "description": "Optional caller turn number, logged for attribution."
+ },
+ "stats": {
+ "type": "boolean",
+ "description": "Return the volunteered-vs-used precision summary instead of volunteering. APPROXIMATE: \"used\" = pages.last_retrieved_at > volunteered_at."
+ },
+ "days": {
+ "type": "number",
+ "description": "Stats window in days (default 30; stats mode only)."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "pages": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "display": "string",
+ "confidence": "number",
+ "rationale": "string"
+ }
+ ],
+ "count": "number",
+ "window_turns": "number"
+ },
+ "note": "stats: true answers a usage summary instead, which this contract does not freeze"
+ }
+ },
+ {
+ "name": "whois",
+ "description": "Exact identity lookup: entity pages whose email, title or declared alias equals an email address or name, ignoring case, accents and quotes. Never fuzzy: empty matches means no exact match; ambiguous means several.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Email address or name, e.g. '[email protected]'."
+ },
+ "types": {
+ "type": "array",
+ "description": "Page types; default: the schema pack's entity types.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source; '__all__' spans your sources."
+ }
+ },
+ "required": [
+ "query"
+ ]
+ },
+ "personal_only": true,
+ "result": {
+ "structured_content": {
+ "query": "string",
+ "query_kind": "\"email\" | \"name\"",
+ "matches": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string",
+ "match": "string"
+ }
+ ],
+ "ambiguous": "boolean"
+ },
+ "optional": {
+ "truncated": "true: more candidates share the key than were returned",
+ "note": "string"
+ },
+ "note": "exact, never fuzzy: no matches means no exact match; ambiguous: true means several, so ask which one and never take the first"
+ }
+ }
+ ]
+ },
+ "memory_recall": {
+ "limits": {
+ "max_chars": {
+ "min": 200,
+ "max": 12000,
+ "default": 6000,
+ "whole_number": true,
+ "unit": "UTF-16 code units (JavaScript string length)"
+ },
+ "query_chars_ranked": 2000,
+ "own_recent_window_hours": 24
+ },
+ "arguments_checked": "query and max_chars are checked before any read, also for an unlinked person (invalid_params)",
+ "content": {
+ "line": "- <fact> (<YYYY-MM-DD>; <kind>)",
+ "never": [
+ "page bodies",
+ "fence markers",
+ "heading markers",
+ "line breaks or control characters inside a fact"
+ ],
+ "bounded_by": "max_chars: as many whole lines as fit; facts left out set structuredContent.truncated, with no marker line, because every line is one fact"
+ },
+ "order": [
+ "own facts from the last 24 hours, newest first",
+ "facts the person may read, ranked by query"
+ ],
+ "ranking": "keyword-only unless an embedding provider is configured (no embedding call on a keyless brain)",
+ "structured_content": {
+ "facts": [
+ {
+ "id": "string",
+ "text": "string",
+ "date": "YYYY-MM-DD",
+ "kind": "string",
+ "arm": "\"own\" | \"ranked\""
+ }
+ ],
+ "truncated": "boolean",
+ "code": "actor_unlinked (only on unlinked_recall)"
+ },
+ "arm": "own: the person's own fact from the last 24 hours; ranked: matched by query (a fact found both ways is own); a call that names sources answers ranked rows only",
+ "scope_read": {
+ "arguments": [
+ "source_id",
+ "source_ids"
+ ],
+ "rule": "a call that names sources is read as their audience, never as the person: no own facts first and no member-page fact; a page restricted to named readers stays hidden; privacy is never relaxed",
+ "sources": "narrowed inside the credential's read grant like recall's source_ids; a source outside it is permission_denied; source_id and source_ids together read their intersection, and an empty intersection reads nothing",
+ "without_sources": "the person read above (own recent facts, then what the person may read across the read grant): use it only for the person's own conversations"
+ }
+ },
+ "unlinked_recall": {
+ "isError": false,
+ "content": [
+ {
+ "type": "text",
+ "text": ""
+ }
+ ],
+ "structuredContent": {
+ "facts": [],
+ "truncated": false,
+ "code": "actor_unlinked"
+ }
+ },
+ "memory_write": {
+ "limits": {
+ "facts": {
+ "min": 1,
+ "max": 20
+ },
+ "provenance_chars": 200,
+ "idempotency_key": {
+ "pattern": "^[\\x21-\\x7e]{1,128}$"
+ },
+ "kinds": [
+ "event",
+ "preference",
+ "commitment",
+ "belief",
+ "fact"
+ ],
+ "provenance": "one line: no line breaks or control characters, and not starting with qm: (gbrain adds qm:<actor id> itself)",
+ "valid_from": "YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS[.fraction]][Z|±HH:MM], a real calendar day in years 0001-9999"
+ },
+ "validation": "every fact is checked before any is saved: one bad fact refuses the whole call with invalid_params and the idempotency_key stays unused",
+ "saved_as": {
+ "page": "memory/members/<member>",
+ "readers": [
+ "member:<member>"
+ ],
+ "visibility": "private",
+ "provenance": "qm:<actor id>; <caller provenance>"
+ },
+ "request_id": "uuidv5(uuidv5(namespace, \"member:<member>\"), idempotency_key) for the first fact; later facts derive from it",
+ "replay": "the same idempotency_key from the same person returns the first receipt; from another person it is a separate write",
+ "retries": "never retried server-side; a write still publishing answers pending",
+ "committed": {
+ "content": "Saved <N> fact(s).",
+ "structuredContent": {
+ "status": "committed",
+ "request_id": "uuid",
+ "fact_ids": [
+ "string"
+ ]
+ },
+ "fact_ids": "distinct; facts repeating one claim in a call share one id, and <N> counts distinct facts"
+ },
+ "pending": {
+ "content": "Accepted <N> fact(s); <M> still publishing.",
+ "structuredContent": {
+ "status": "pending",
+ "request_id": "uuid",
+ "fact_ids": [
+ "string"
+ ],
+ "pending_request_ids": [
+ "uuid"
+ ]
+ },
+ "poll": "get_write_request {request_id}"
+ }
+ },
+ "errors": {
+ "shape": {
+ "isError": true,
+ "content": "one JSON text block with top-level code, message, suggestion and optional reason and fix",
+ "structuredContent": {
+ "error": {
+ "code": "string",
+ "message": "string",
+ "reason": "string?",
+ "write_error": "string?",
+ "fix": "object?"
+ }
+ }
+ },
+ "applies_to": "every refusal of memory_recall and memory_write, and of a personal tool called with x-qm-actor, including the transport's scope and unknown-tool refusals",
+ "codes": [
+ {
+ "code": "actor_not_attested",
+ "class": "host_only",
+ "summary": "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.",
+ "suggestion": "Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.",
+ "docs": "docs/guides/write-refusals.md#actor_not_attested",
+ "reasons": [
+ {
+ "reason": "no_attest_right",
+ "fixed_by": "brain_operator",
+ "fix": "gbrain auth rescope --client <id> --attest-actor qm on the brain host; a client that already holds the right takes a new token with grant_type=client_credentials."
+ },
+ {
+ "reason": "op_not_attested",
+ "fixed_by": "brain_operator",
+ "fix": "gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>; a deferred operation cannot be attested yet."
+ },
+ {
+ "reason": "argument_mismatch",
+ "fixed_by": "calling_harness",
+ "fix": "Send acting_user equal to the x-qm-actor header (with no header, on a credential bound to a member: that member id or a canonical id linked to it), or omit it."
+ },
+ {
+ "reason": "argument_without_attestation",
+ "fixed_by": "calling_harness",
+ "fix": "Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member never sends acting_user alone."
+ },
+ {
+ "reason": "invalid_actor_id",
+ "fixed_by": "calling_harness",
+ "fix": "Send the canonical id unchanged: 1-256 visible ASCII characters, no spaces."
+ },
+ {
+ "reason": "actor_required",
+ "fixed_by": "calling_harness",
+ "fix": "memory_write saves only as an attested person: send x-qm-actor from a credential holding the attest right."
+ },
+ {
+ "reason": "audience_not_supported",
+ "fixed_by": "calling_harness",
+ "fix": "Send the call without x-qm-audience; channel turns are refused until wave 2 and nothing is read or written."
+ }
+ ],
+ "note": "With no x-qm-actor header, acting_user is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it); the call then runs exactly as the credential."
+ },
+ {
+ "code": "actor_unlinked",
+ "class": "host_only",
+ "summary": "An attested call named a person whose canonical id is not linked to an enabled member of this brain (never linked, unlinked, or the member is disabled or removed), so nothing was read or written.",
+ "suggestion": "The brain operator links the id to its member: gbrain access member link <member> --qm <id> (or enables the member).",
+ "docs": "docs/guides/write-refusals.md#actor_unlinked",
+ "note": "Refuses memory_write. memory_recall answers it as a success instead (unlinked_recall)."
+ },
+ {
+ "code": "on_behalf_of_invalid_audience",
+ "class": "caller",
+ "summary": "A shared agent's request named its audience (the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of) in a form gbrain does not accept: empty, more than 50 entries, an entry that is not a member id, group:<id> or guest, or a header and _meta that name different audiences. Nothing was read.",
+ "suggestion": "Fix the harness code that sets the audience: 1-50 entries, each a member id, group:<id> or guest, the same in the header and _meta when both are sent.",
+ "docs": "docs/guides/write-refusals.md#on_behalf_of_invalid_audience",
+ "note": "Sent when x-qm-actor is combined with an on_behalf_of audience (X-Gbrain-On-Behalf-Of or request-level _meta.on_behalf_of). QM classifies it as a failed call."
+ },
+ {
+ "code": "invalid_params",
+ "class": "caller",
+ "summary": "A parameter is missing, has the wrong type, or has an invalid value.",
+ "docs": "docs/guides/error-codes.md#invalid_params",
+ "note": "Bad arguments, refused before anything is saved. A reused idempotency_key with different facts carries write_error idempotency_conflict; a claim the person forgot carries the fact_withdrawn message."
+ },
+ {
+ "code": "scope_denied",
+ "class": "host_only",
+ "summary": "The connection lacks the scope this memory verb requires.",
+ "docs": "docs/guides/error-codes.md#scope_denied",
+ "note": "The write is not authorized, including a member page whose readers name anyone but its member (squatted or widened): nothing is saved."
+ },
+ {
+ "code": "insufficient_scope",
+ "class": "host_only",
+ "summary": "The connection lacks the OAuth scope the operation requires.",
+ "docs": "docs/guides/error-codes.md#insufficient_scope",
+ "note": "The credential lacks the OAuth scope the tool needs (memory_write needs write); refused by the transport before the call runs."
+ },
+ {
+ "code": "unknown_tool",
+ "class": "caller",
+ "summary": "The named tool does not exist or is not callable on this connection.",
+ "docs": "docs/guides/error-codes.md#unknown_tool",
+ "note": "The tool is not callable on this connection (its surface or bound-operation list leaves it out)."
+ },
+ {
+ "code": "not_found",
+ "class": "caller",
+ "summary": "The requested resource does not exist or is not visible to this caller.",
+ "docs": "docs/guides/error-codes.md#not_found",
+ "note": "get_write_request for a receipt that is not this person's, or forget for a fact that is not on this person's own member page."
+ },
+ {
+ "code": "fact_not_found",
+ "class": "caller",
+ "summary": "Fact not found.",
+ "docs": "docs/guides/error-codes.md#fact_not_found",
+ "note": "forget_fact for a fact that is not on this person's own member page."
+ },
+ {
+ "code": "unavailable",
+ "class": "unavailable",
+ "summary": "A required dependency or capability cannot serve this request.",
+ "docs": "docs/guides/error-codes.md#unavailable",
+ "note": "memory_recall could not read the fact candidates (a database failure); retry the same call."
+ },
+ {
+ "code": "permission_denied",
+ "class": "host_only",
+ "summary": "This caller is not authorized for the operation.",
+ "docs": "docs/guides/error-codes.md#permission_denied",
+ "note": "memory_recall named a source (source_id or source_ids) outside the credential's read grant; nothing was read."
+ },
+ {
+ "code": "page_not_found",
+ "class": "caller",
+ "summary": "No page with that slug exists in the selected source.",
+ "docs": "docs/guides/error-codes.md#page_not_found",
+ "note": "get_page for a page that does not exist or that the person may not read; one answer for both."
+ },
+ {
+ "code": "result_too_large",
+ "class": "caller",
+ "summary": "The tool's result is larger than this connection can carry in one response, so it was replaced by this error; nothing was cut.",
+ "suggestion": "Ask for less in one call: a window (get_page body: 'window'), a page of rows (limit / from_index), or metadata only (get_versions include_body: false).",
+ "docs": "docs/guides/windowed-reads.md#result_too_large",
+ "note": "A personal read whose answer, with structuredContent, is over the connection's result cap; nothing was returned. Ask for less: get_page body: \"outline\" or \"window\", or a smaller limit."
+ }
+ ]
+ },
+ "wave_2": {
+ "audience_header": "x-qm-audience",
+ "encoding": "base64url of a JSON array of canonical ids",
+ "status": "refused until wave 2",
+ "refusal": {
+ "code": "actor_not_attested",
+ "reason": "audience_not_supported",
+ "tools_call": "errors.shape, with or without x-qm-actor",
+ "other_methods": "JSON-RPC error -32600 whose data carries code and reason (tools/list, resources/list, resources/read)"
+ }
+ }
+}
diff --git a/docs/guides/qm.md b/docs/guides/qm.md
index c8cf081af1..9540c73343 100644
--- a/docs/guides/qm.md
+++ b/docs/guides/qm.md
@@ -4,7 +4,8 @@ QM, a trusted system that already knows who each person is, keeps per-person
memory in a brain through two MCP tools: `memory_recall` reads what the person may
read, and `memory_write` saves facts only they read back. Both run as the person QM
names in the `x-qm-actor` header. The wire contract QM vendors is
-[`docs/contracts/qm-memory-provider/v1.json`](../contracts/qm-memory-provider/README.md).
+[`docs/contracts/qm-memory-provider/v1.json`](../contracts/qm-memory-provider/README.md);
+`v2.json` adds the scope read and `v3.json` the personal tools for the person's own DM.
## Set up on the brain host
@@ -18,6 +19,14 @@ gbrain access member link alice-example --qm U0ALICE # the canonical
Add `forget` with `--attest-ops forget,get_write_request,memory_recall,memory_write` if QM
should withdraw facts; an attested `forget` reaches only facts on the person's own
page, and any other id is `not_found`.
+The personal tools in [contract v3](../contracts/qm-memory-provider/README.md) (`query`,
+`get_page`, `get_timeline`, `get_backlinks`, `find_experts`, `whois`, `entity`,
+`context_pack`, `volunteer_context`, `forget_fact`) are opt-in the same way: the
+default stays `get_write_request,memory_recall,memory_write`, so list each one QM uses,
+for example `--attest-ops forget_fact,get_page,get_write_request,memory_recall,memory_write,query,whois`.
+They read as the person, their own restricted pages included, so grant them only to
+the client that serves the person's own DM, never to a client that serves shared
+rooms.
Direct page writes (`add_timeline_entry`, `add_link`, `put_page`, `edit_page`) are not
attestable: a person's words reach a shared page only through an owner-approved proposal,
which is not served yet. `--attest-ops` refuses them, and a list that already names one
@@ -52,7 +61,14 @@ a repo exists, saved facts go through the same git-first writer door as `remembe
answers `status: "pending"` with a `request_id` for `get_write_request`.
On success the result is in `structuredContent`, and `content` holds only the text
-for the model. A person not yet linked gets an empty `memory_recall` with
+for the model. Each fact in `structuredContent.facts` carries `arm`: `own` (the
+person's own recent fact) or `ranked` (matched by `query`); a recall that names
+sources has only `ranked` rows. An attested call to a v3 personal tool also gets its
+result in `structuredContent` (a list as `structuredContent.results`), while
+`content` keeps the JSON; `context_pack`'s `content` is its rendered text alone. The
+same tools called without `x-qm-actor` answer as before, with no `structuredContent`.
+A personal read whose answer, counted with `structuredContent`, is over the
+connection's result cap is refused whole (`result_too_large`). A person not yet linked gets an empty `memory_recall` with
`structuredContent.code: "actor_unlinked"` (its arguments are still checked
first). Every refusal, including the transport's scope and unknown-tool ones,
carries `structuredContent.error`. A request carrying `x-qm-audience` (channel
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index 2789e58730..3ce5c80845 100644
--- a/docs/mcp/ADMIN.md
+++ b/docs/mcp/ADMIN.md
@@ -255,7 +255,9 @@ read back only by that member, written remotely by no one else), and `delta` cur
(`get_write_request`, `list_write_requests`, `cancel_write_request`) and agent
jobs (`submit_agent`, `get_agent_job`) belong to the person they were made for.
QM's memory pair, `memory_recall` and `memory_write`, reads and saves that
-person's facts ([QM guide](../guides/qm.md)); `forget` and `forget_fact` withdraw
+person's facts ([QM guide](../guides/qm.md)); the personal tools of its contract v3
+(`query`, `get_page`, `whois`, `context_pack` and the rest) stay out of the default
+list, so add each to `--attest-ops` only for the client serving the person's own DM; `forget` and `forget_fact` withdraw
only a fact on the person's own page (also for a credential bound to a member).
A request carrying `x-qm-audience` is refused (`audience_not_supported`). Not attestable yet, because what they
read or write is not yet kept to the person: `list_write_conflicts`, `capture`,
diff --git a/scripts/build-qm-memory-contract.ts b/scripts/build-qm-memory-contract.ts
index 1b36dac3fa..e36def120c 100644
--- a/scripts/build-qm-memory-contract.ts
+++ b/scripts/build-qm-memory-contract.ts
@@ -6,6 +6,8 @@
* bun scripts/build-qm-memory-contract.ts --check exit 1 when a committed fixture is stale
* A change to the shape is a new version; v1.json stays byte-identical until QM moves. GST-1094 v2 adds the scope read
* (source_id / source_ids on memory_recall), GST-900's member-bound acting_user rule and _meta-only unknown-param warnings.
+ * GST-1158 F1 v3 adds the personal tools (own DM, read as the attested person) with frozen result shapes, forget_fact
+ * among them, and each memory_recall fact's arm (F5).
*/
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
@@ -13,12 +15,15 @@ import { operations } from '../src/core/operations.ts';
import { paramDefToSchema } from '../src/mcp/tool-defs.ts';
import { CODES } from '../src/core/error-registry.ts';
import { ACTOR_ARGUMENT, ACTOR_DEFERRED_OPS, ACTOR_HEADER, DEFAULT_ATTEST_OPS, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER } from '../src/core/access/actor-model.ts';
-import { IDEMPOTENCY_KEY_RE, MEMORY_RECALL_MAX_CHARS, MEMORY_RECALL_QUERY_CHARS, MEMORY_WRITE_KINDS, MEMORY_WRITE_MAX_FACTS, MEMORY_WRITE_PROVENANCE_MAX, OWN_RECENT_WINDOW_HOURS, QM_MEMORY_OPS, unlinkedRecallResult } from '../src/core/ops/qm-memory.ts';
+import { IDEMPOTENCY_KEY_RE, MEMORY_RECALL_MAX_CHARS, MEMORY_RECALL_QUERY_CHARS, MEMORY_WRITE_KINDS, MEMORY_WRITE_MAX_FACTS, MEMORY_WRITE_PROVENANCE_MAX, OWN_RECENT_WINDOW_HOURS, QM_MEMORY_OPS, QM_PERSONAL_OPS, unlinkedRecallResult } from '../src/core/ops/qm-memory.ts';
+import { WRITE_REQUEST_STATES } from '../src/core/persistence/types.ts';
+import { TERMINAL_STATES } from '../src/core/persistence/model.ts';
-export type QmContractVersion = 1 | 2;
+export type QmContractVersion = 1 | 2 | 3;
export const QM_CONTRACT_PATHS: Record<QmContractVersion, string> = {
1: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v1.json'),
2: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v2.json'),
+ 3: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v3.json'),
};
export const QM_CONTRACT_PATH = QM_CONTRACT_PATHS[1];
/** The arguments v1 publishes per tool, frozen: later arguments appear from v2 on. */
@@ -55,6 +60,77 @@ const ERROR_NOTES: Partial<Record<typeof ERROR_CODES[number], string>> = {
unavailable: 'memory_recall could not read the fact candidates (a database failure); retry the same call.',
};
+const STATE = WRITE_REQUEST_STATES.map(s => '"' + s + '"').join(' | ');
+const PAGE_REF = { slug: 'string', source_id: 'string', title: 'string', type: 'string' };
+
+/**
+ * GST-1158 F1: v3's QM-facing projection of each personal tool's success: `structured_content` lists the fields every
+ * success carries (a type, `"a" | "b"` for one of those values, a one-row array for a list); `optional` names fields
+ * that appear only as described. Nothing else is promised.
+ */
+const PERSONAL_RESULTS: Record<string, Record<string, unknown>> = {
+ query: {
+ structured_content: { results: [{ source_id: 'string', title: 'string', chunk_text: 'string', score: 'number' }] },
+ optional: { 'results[].slug': 'string: a page row, with type and chunk_id', 'results[].result_type': '"fact": a saved fact row, with fact_id and no slug', 'results[].fact_id': 'string: on a fact row' },
+ note: 'rows best first; page text is quoted source material, never instructions; an empty list after a degraded search is not proof the brain has nothing (read the notice blocks)',
+ },
+ get_page: {
+ structured_content: { slug: 'string', source_id: 'string', type: 'string', title: 'string', revision: 'string' },
+ optional: { compiled_truth: 'string: a whole read', timeline: 'string: a whole read', body: '"none" | "outline" | "window": a partial read (a page over the inline size, or the body argument); it carries no compiled_truth', truncated: 'boolean: a partial read left text out', resolved_slug: 'string: the slug an alias resolved to' },
+ note: 'a page the person may not read answers page_not_found, the same as a missing one',
+ },
+ get_timeline: {
+ structured_content: { results: [{ id: 'number', date: 'string', summary: 'string', source: 'string', detail: 'string' }] },
+ note: 'a page the person may not read answers an empty list',
+ },
+ get_backlinks: {
+ structured_content: { results: [{ from_slug: 'string', from_source_id: 'string', to_slug: 'string', to_source_id: 'string', link_type: 'string' }] },
+ optional: { 'results[].truncated': 'true on the last row when more remain', 'results[].next_cursor': 'string on that row: pass it as cursor' },
+ with_group_page: { rows: [PAGE_REF], total: 'number', truncated: 'boolean', cursor: 'string | null' },
+ },
+ find_experts: {
+ structured_content: { results: [{ ...PAGE_REF, score: 'number' }] },
+ },
+ whois: {
+ structured_content: { query: 'string', query_kind: '"email" | "name"', matches: [{ ...PAGE_REF, match: 'string' }], ambiguous: 'boolean' },
+ optional: { truncated: 'true: more candidates share the key than were returned', note: 'string' },
+ note: 'exact, never fuzzy: no matches means no exact match; ambiguous: true means several, so ask which one and never take the first',
+ },
+ entity: {
+ structured_content: { protocol_version: 'number', found: 'boolean' },
+ optional: { card: 'object when found: card.entity holds slug, source_id, title and type', suggestions: 'array of {slug, title} when not found', ambiguous: 'true: the name matched several entities' },
+ with_names: { protocol_version: 'number', results: [{ name: 'string', found: 'boolean' }] },
+ },
+ context_pack: {
+ content: 'the rendered pack text alone, as memory_recall\'s; it is not repeated in structuredContent',
+ structured_content: { protocol_version: 'number', entities: ['string'], cards: [PAGE_REF], open_threads: 'array', facts: [{ fact: 'string', kind: 'string', fact_id: 'string' }], entity_facts: 'array' },
+ },
+ volunteer_context: {
+ structured_content: { pages: [{ slug: 'string', source_id: 'string', display: 'string', confidence: 'number', rationale: 'string' }], count: 'number', window_turns: 'number' },
+ note: 'stats: true answers a usage summary instead, which this contract does not freeze',
+ },
+ get_write_request: {
+ structured_content: { request_id: 'string', state: STATE, retry_after_ms: 'number | null', operation: 'string', source_id: 'string', slug: 'string | null', created_at: 'string', updated_at: 'string' },
+ optional: { write_error: 'string: why a write ended without publishing', outcome: 'object: the published write\'s result' },
+ states: {
+ known: [...WRITE_REQUEST_STATES], terminal: WRITE_REQUEST_STATES.filter(s => TERMINAL_STATES.has(s)), published: 'committed',
+ unknown: 'a state not listed here means unknown, not published: never report the write as saved; poll again or report it as unknown',
+ poll: 'until a terminal state, after retry_after_ms when it is set',
+ },
+ },
+ forget_fact: {
+ structured_content: { id: 'number', request_id: 'string', state: STATE },
+ optional: { expired: 'boolean: the fact is withdrawn' },
+ note: 'withdraws only a fact on the person\'s own member page (any other id is fact_not_found); send request_id (a UUID) so a retry replays the same withdrawal; a state other than committed is read with get_write_request',
+ },
+};
+
+/** v3 error notes beside v2's: the codes the personal tools add. */
+const V3_ERROR_NOTES: Record<string, string> = {
+ page_not_found: 'get_page for a page that does not exist or that the person may not read; one answer for both.',
+ result_too_large: 'A personal read whose answer, with structuredContent, is over the connection\'s result cap; nothing was returned. Ask for less: get_page body: "outline" or "window", or a smaller limit.',
+};
+
/** v2 changes to v1's fix rows (GST-900: a member-bound credential may name its own member). */
const V2_REASON_FIXES: Partial<typeof ACTOR_REASON_FIXES> = {
argument_mismatch: { fixed_by: 'calling_harness', fix: 'Send acting_user equal to the x-qm-actor header (with no header, on a credential bound to a member: that member id or a canonical id linked to it), or omit it.' },
@@ -75,10 +151,11 @@ function toolEntry(name: string, version: QmContractVersion) {
export function buildQmMemoryContract(version: QmContractVersion): Record<string, unknown> {
const unlinked = unlinkedRecallResult();
const v2 = version > 1;
- const codes = v2 ? [...ERROR_CODES, 'permission_denied' as const] : ERROR_CODES;
+ const v3 = version > 2;
+ const codes: readonly (keyof typeof CODES)[] = v3 ? [...ERROR_CODES, 'permission_denied', 'page_not_found', 'result_too_large'] : v2 ? [...ERROR_CODES, 'permission_denied'] : ERROR_CODES;
const notes: Record<string, string | undefined> = v2 ? { ...ERROR_NOTES,
actor_not_attested: 'With no x-qm-actor header, acting_user is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it); the call then runs exactly as the credential.',
- permission_denied: 'memory_recall named a source (source_id or source_ids) outside the credential\'s read grant; nothing was read.' } : ERROR_NOTES;
+ permission_denied: 'memory_recall named a source (source_id or source_ids) outside the credential\'s read grant; nothing was read.', ...(v3 ? V3_ERROR_NOTES : {}) } : ERROR_NOTES;
return {
contract: 'gbrain.qm-memory-provider', version,
transport: { protocol: 'mcp', session: 'stateless', session_header_issued: false, success_codes_in: 'structuredContent',
@@ -92,13 +169,21 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<string
audit: 'the audit trail and stored writes record the canonical external id as sent, with its linked member',
},
tools: [...QM_MEMORY_OPS].sort().map(name => toolEntry(name, version)),
+ ...(v3 ? { personal_tools: {
+ read_as: 'the attested person (x-qm-actor): what that person may read, their own restricted pages included, so use these tools only in the person\'s own conversations; no tool here is marked as a shared-scope read yet',
+ opt_in: 'only get_write_request is in default_attest_ops: the brain operator lists each other tool in the client\'s --attest-ops (gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>), or it is refused with actor_not_attested reason op_not_attested',
+ structured_content: 'an attested success carries the result in structuredContent and keeps it as JSON in content (notice blocks follow it); a list arrives as structuredContent.results; context_pack\'s text alone fills content, as memory_recall\'s does; an unattested call to the same tool gets no structuredContent',
+ result_rule: 'each result lists the fields every success carries; other fields may appear and must be ignored',
+ tools: [...QM_PERSONAL_OPS].sort().map(name => ({ ...toolEntry(name, version), personal_only: true, result: PERSONAL_RESULTS[name] })),
+ } } : {}),
memory_recall: {
limits: { max_chars: { ...MEMORY_RECALL_MAX_CHARS, whole_number: true, unit: 'UTF-16 code units (JavaScript string length)' }, query_chars_ranked: MEMORY_RECALL_QUERY_CHARS, own_recent_window_hours: OWN_RECENT_WINDOW_HOURS },
arguments_checked: 'query and max_chars are checked before any read, also for an unlinked person (invalid_params)',
content: { line: '- <fact> (<YYYY-MM-DD>; <kind>)', never: ['page bodies', 'fence markers', 'heading markers', 'line breaks or control characters inside a fact'], bounded_by: 'max_chars: as many whole lines as fit; facts left out set structuredContent.truncated, with no marker line, because every line is one fact' },
order: ['own facts from the last ' + OWN_RECENT_WINDOW_HOURS + ' hours, newest first', 'facts the person may read, ranked by query'],
ranking: 'keyword-only unless an embedding provider is configured (no embedding call on a keyless brain)',
- structured_content: { facts: [{ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string' }], truncated: 'boolean', code: 'actor_unlinked (only on unlinked_recall)' },
+ structured_content: { facts: [{ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string', ...(v3 ? { arm: '"own" | "ranked"' } : {}) }], truncated: 'boolean', code: 'actor_unlinked (only on unlinked_recall)' },
+ ...(v3 ? { arm: 'own: the person\'s own fact from the last ' + OWN_RECENT_WINDOW_HOURS + ' hours; ranked: matched by query (a fact found both ways is own); a call that names sources answers ranked rows only' } : {}),
...(v2 ? { scope_read: {
arguments: ['source_id', 'source_ids'],
rule: 'a call that names sources is read as their audience, never as the person: no own facts first and no member-page fact; a page restricted to named readers stays hidden; privacy is never relaxed',
@@ -121,7 +206,7 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<string
},
errors: {
shape: { isError: true, content: 'one JSON text block with top-level code, message, suggestion and optional reason and fix', structuredContent: { error: { code: 'string', message: 'string', reason: 'string?', write_error: 'string?', fix: 'object?' } } },
- applies_to: 'every refusal of memory_recall and memory_write, including the transport\'s scope and unknown-tool refusals',
+ applies_to: v3 ? 'every refusal of memory_recall and memory_write, and of a personal tool called with x-qm-actor, including the transport\'s scope and unknown-tool refusals' : 'every refusal of memory_recall and memory_write, including the transport\'s scope and unknown-tool refusals',
codes: codes.map(code => {
const entry: { class: string; summary: string; suggestion?: string; reasons?: readonly string[]; docs?: string } = CODES[code];
return { code, class: entry.class, summary: (v2 ? undefined : V1_SUMMARIES[code]) ?? entry.summary, ...(entry.suggestion ? { suggestion: entry.suggestion } : {}), docs: entry.docs ?? 'docs/guides/error-codes.md#' + code,
@@ -140,7 +225,7 @@ export function renderQmMemoryContract(version: QmContractVersion): string {
if (import.meta.main) {
let stale = false;
- for (const version of [1, 2] as const) {
+ for (const version of [1, 2, 3] as const) {
const path = QM_CONTRACT_PATHS[version];
const fresh = renderQmMemoryContract(version);
if (process.argv.includes('--check')) {
diff --git a/src/commands/serve-http-mcp.ts b/src/commands/serve-http-mcp.ts
index 8fbfb508c4..440c234e22 100644
--- a/src/commands/serve-http-mcp.ts
+++ b/src/commands/serve-http-mcp.ts
@@ -335,7 +335,7 @@ async function callMcpTool(ctx: ServeHttpContext, state: McpRequestState, reques
if (statusMode && hasScope(authInfo.scopes, 'read')) return statusToolResult(statusMode, 'http');
const op = mcpOperations.find(o => o.name === name);
if (!op) {
- return qmMemoryToolResult(name, await rejectUnknownMcpOperation(ctx, state, name, requestMetaSessionId(request.params)));
+ return qmMemoryToolResult(name, await rejectUnknownMcpOperation(ctx, state, name, requestMetaSessionId(request.params)), state.actorHeader != null);
}
// Scope enforcement (v0.28: hasScope replaces exact-string-match so
@@ -351,7 +351,7 @@ async function callMcpTool(ctx: ServeHttpContext, state: McpRequestState, reques
// denial first would tell the operator to widen the grant for nothing.
const scopeSatisfied = op.cliOnly !== undefined || operationScopesAllowed(authInfo.scopes, op);
if (!scopeSatisfied) {
- return qmMemoryToolResult(name, await rejectInsufficientMcpScope(ctx, state, name, requiredScope, requestMetaSessionId(request.params)));
+ return qmMemoryToolResult(name, await rejectInsufficientMcpScope(ctx, state, name, requiredScope, requestMetaSessionId(request.params)), state.actorHeader != null);
}
// F8: redact request payload by default (declared keys only via the
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 228296895c..f643f73f15 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1416,6 +1416,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: 'TBD', id: 'member_bound_acting_user_gst900', text: 'A credential bound to a member may now send `acting_user` with no `x-qm-actor` header: its own member id, or a canonical id linked to that member, is dropped and the call runs exactly as the credential; any other value is refused (`actor_not_attested` reason `argument_mismatch`). A credential bound to no member is still refused (`argument_without_attestation`).' },
{ since: 'TBD', id: 'recall_max_chars_harn15', text: '`recall` now takes `max_chars` (a whole number from 200 to 12000, as `memory_recall`): it keeps the whole facts, then results, whose text fits, adds no marker and returns `truncated`; without it `recall` is unchanged.' },
{ since: 'TBD', id: 'attest_direct_page_writes_deferred_gst1158', text: 'An attested call (`x-qm-actor`) may no longer run `add_timeline_entry`, `add_link`, `put_page` or `edit_page`: they write pages every reader of the page sees, so they wait for owner-approved proposals. `gbrain auth rescope --attest-ops` refuses a list that names one, a credential whose list already names one is refused for it on every attested call (`actor_not_attested`, reason `op_not_attested`), and a queued attested write of one fails when it publishes. Unattested calls and member-bound credentials are unchanged.' },
+ { since: 'TBD', id: 'qm_personal_structured_gst1158', text: 'An attested call (`x-qm-actor`) to `query`, `get_page`, `get_timeline`, `get_backlinks`, `find_experts`, `whois`, `entity`, `context_pack`, `volunteer_context`, `get_write_request` or `forget_fact` now also answers with its result in `structuredContent` (a list as `structuredContent.results`) and its refusals with `structuredContent.error`; `content` keeps the JSON, except `context_pack`, whose `content` is now its rendered text alone. A personal read whose answer, counted with `structuredContent`, is over the result cap is refused whole (`result_too_large`). Each `memory_recall` fact in `structuredContent.facts` gains `arm` (`own` or `ranked`). The same tools without `x-qm-actor` are unchanged, and none of them joined the default attested operations.' },
{ since: 'TBD', id: 'unknown_param_meta_only_harn15', text: 'A read that ignores a parameter the tool does not declare (`mcp.strict_params` `warn`, the default) no longer adds a `[gbrain notice unknown_param kind=info]` text block to the result: the warning is only in `_meta.warnings` (`{code: \'unknown_param\', param, suggestion?}`), so a harness that stores tool output in its turns never stores it. Writes still refuse unknown parameters, and `reject` mode is unchanged.' },
];
diff --git a/src/core/ops/qm-memory.ts b/src/core/ops/qm-memory.ts
index b73e73d702..a53a28fa89 100644
--- a/src/core/ops/qm-memory.ts
+++ b/src/core/ops/qm-memory.ts
@@ -30,6 +30,13 @@ import { uuidV5 } from '../persistence/preconditions.ts';
import { isStrictIsoDateTime } from '../utils.ts';
export const QM_MEMORY_OPS: ReadonlySet<string> = new Set(['memory_recall', 'memory_write']);
+/** GST-1158 F1: the personal tools contract v3 adds, read or written as the attested person (own DM only); opt-in per client. */
+export const QM_PERSONAL_OPS: ReadonlySet<string> = new Set([
+ 'query', 'get_page', 'get_timeline', 'get_backlinks', 'find_experts', 'whois', 'entity', 'context_pack', 'volunteer_context',
+ 'get_write_request', 'forget_fact',
+]);
+/** Results whose `text` is the model's text: it alone fills `content` and leaves `structuredContent`. */
+const TEXT_RESULT_OPS: ReadonlySet<string> = new Set(['memory_recall', 'memory_write', 'context_pack']);
export const MEMORY_RECALL_MAX_CHARS = { min: 200, max: 12_000, default: 6_000 } as const;
/** Own facts written within this window lead the answer. */
export const OWN_RECENT_WINDOW_HOURS = 24;
@@ -50,7 +57,8 @@ export const QM_MEMORY_REQUEST_NAMESPACE = '6b3e9f2a-41c7-4d58-9a0e-2f7c5d1b8e63
const actorParam: ParamDef = { type: 'string', description: `Set by the trusted system: equal to the ${ACTOR_HEADER} header, or omit.`, fullSurfaceOnly: true };
-export interface RecallFact { id: string; text: string; date: string; kind: string }
+/** GST-1158 F5: `arm` says which read found the fact: the person's own recent facts, or the query ranking. */
+export interface RecallFact { id: string; text: string; date: string; kind: string; arm: 'own' | 'ranked' }
/** Fact text as one plain line: fence and heading markers and rules removed, every line break and control character a space. */
export function plainFactText(text: string): string {
@@ -150,11 +158,11 @@ async function recallFacts(ctx: OperationContext, query: string, maxChars: numbe
scope: { sourceIds: sources, remote, excludePrivate: read.excludePrivate, minTrust: read.eligibility.floor, suppressFlagged: read.eligibility.suppressFlagged },
})).rows : [];
const seen = new Set<number>();
- const rows = [...own, ...ranked].filter(r => !seen.has(r.id) && !!seen.add(r.id));
+ const rows = [...own.map(r => ({ ...r, arm: 'own' as const })), ...ranked.map(r => ({ ...r, arm: 'ranked' as const }))].filter(r => !seen.has(r.id) && !!seen.add(r.id));
// The date as the database writes it: a driver's timestamp parse reads years 1-99 as 19xx.
const written = new Map(rows.length ? (await ctx.engine.executeRaw<{ id: number | string; d: string }>(
`SELECT id, to_char(COALESCE(valid_from, created_at) AT TIME ZONE 'UTC', 'YYYY-MM-DD') AS d FROM facts WHERE id = ANY($1::bigint[])`, [rows.map(r => r.id)])).map(r => [Number(r.id), r.d]) : []);
- const plain = rows.map(r => ({ id: String(r.id), text: plainFactText(r.fact), date: isoDate(written.get(Number(r.id)) ?? r.valid_from ?? r.created_at), kind: String(r.kind) }));
+ const plain = rows.map(r => ({ id: String(r.id), text: plainFactText(r.fact), date: isoDate(written.get(Number(r.id)) ?? r.valid_from ?? r.created_at), kind: String(r.kind), arm: r.arm }));
const { redactRetrievalOutput } = await import('../search/output-redaction.ts');
const facts: RecallFact[] = (remote ? redactRetrievalOutput(plain, {}, { uncapped: true }).results : plain).filter(f => f.text);
const { kept, text } = boundFactLines(facts.map(f => `- ${f.text} (${f.date}; ${f.kind})`), maxChars);
@@ -310,9 +318,12 @@ const memory_write: Operation = {
* in `_meta.gbrain_notices`, so memory_recall's text stays within max_chars) and the result in `structuredContent`.
* A refusal keeps its JSON text block and gains `structuredContent.error` (code, message, reason, fix), as the actor
* refusals carry it, so QM classifies every error from structuredContent. Dry runs and every other tool pass through.
+ * GST-1158 F2: a personal tool (QM_PERSONAL_OPS) is rewritten the same way only for an attested person (`personal`):
+ * `content` keeps its JSON and notice blocks, an array result arrives as `structuredContent.results`, and
+ * context_pack's text fills `content` as memory_recall's does.
*/
-export function qmMemoryToolResult<T extends { content: Array<{ type: 'text'; text: string }>; isError?: boolean; structuredContent?: Record<string, unknown> }>(name: string, out: T): T {
- if (!QM_MEMORY_OPS.has(name)) return out;
+export function qmMemoryToolResult<T extends { content: Array<{ type: 'text'; text: string }>; isError?: boolean; structuredContent?: Record<string, unknown> }>(name: string, out: T, personal = false): T {
+ if (!QM_MEMORY_OPS.has(name) && !(personal && QM_PERSONAL_OPS.has(name))) return out;
let result: unknown;
try { result = JSON.parse(out.content[0]?.text ?? ''); } catch { return out; }
if (out.isError) {
@@ -321,6 +332,8 @@ export function qmMemoryToolResult<T extends { content: Array<{ type: 'text'; te
return { ...out, structuredContent: { error: { code: env.code, message: env.message, ...(env.reason ? { reason: env.reason } : {}), ...(env.write_error ? { write_error: env.write_error } : {}), ...(env.fix ? { fix: env.fix } : {}) } } };
}
if (!result || typeof result !== 'object' || 'dry_run' in result) return out;
+ if (Array.isArray(result)) return { ...out, structuredContent: { results: result } };
+ if (!TEXT_RESULT_OPS.has(name)) return { ...out, structuredContent: result as Record<string, unknown> };
const { text, ...structured } = result as Record<string, unknown>;
return { ...out, content: [{ type: 'text', text: typeof text === 'string' ? text : '' }], structuredContent: structured };
}
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index 1c9727cc2e..600d297891 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -18,7 +18,7 @@ import { withCallerAccess } from '../core/search/private-visibility.ts';
import { appliedAccessSummary, remoteCallerAccess } from '../core/access/caller.ts';
import { audienceInArguments, audienceInArgumentsError, logAudienceAssertion, parseAudience, type AudienceAuditEvent, type AudienceChannels, type AudiencePrincipal } from '../core/access/audience.ts';
import { ACTOR_ARGUMENT, actorNotAttested, EXTERNAL_ID_RE, resolveAttestedActor, type ActorChannels } from '../core/access/actor.ts';
-import { qmMemoryToolResult, recallArguments, unlinkedRecallResult } from '../core/ops/qm-memory.ts';
+import { QM_PERSONAL_OPS, qmMemoryToolResult, recallArguments, unlinkedRecallResult } from '../core/ops/qm-memory.ts';
import { resolveBrainId } from '../core/brain-resolver.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { VERB_NAMES, MEMORY_VERBS_VERSION } from '../core/verbs.ts';
@@ -951,7 +951,12 @@ export async function dispatchToolCall(
const out = await withRequestIdentityMemo(() => dispatchResolvedCall(engine, name, callParams, resolved));
// _meta.access (MCP_META_CHANNELS.md): the view this call was answered under, for the harness; own producer, isolated.
try { out._meta = { ...(out._meta ?? {}), access: await appliedAccessSummary(engine, opts.auth, [opts.sourceId, ...(opts.localFederatedSourceIds ?? [])]) }; } catch { /* the key is absent */ }
- return qmMemoryToolResult(name, out);
+ const personal = !!attested?.actor;
+ const shaped = qmMemoryToolResult(name, out, personal);
+ // GST-1158 F2: a personal read's structuredContent repeats its JSON, so the final frame is measured again.
+ if (!personal || shaped === out || shaped.isError || !QM_PERSONAL_OPS.has(name) || op?.mutating !== false) return shaped;
+ const over = await frameOverCap(shaped, { remote: true, transport: opts.transport === 'stdio' ? 'stdio' : 'http', engine, config: opts.config ?? loadConfig() });
+ return over ? qmMemoryToolResult(name, errorResult(resultTooLargeError(name, callParams ?? {}, over), opts, { op: name, mutating: false, idempotent: op.idempotent === true }), true) : shaped;
});
};
if (name === 'search' || name === 'query') return withSearchConnectionBudget(() => withRequestConfigSnapshot(engine, run));
diff --git a/src/mcp/http-transport.ts b/src/mcp/http-transport.ts
index 6fcfd79823..3dfbfe8555 100644
--- a/src/mcp/http-transport.ts
+++ b/src/mcp/http-transport.ts
@@ -542,7 +542,7 @@ export async function startHttpTransport(opts: HttpTransportOptions) {
// Frozen v1 pair: `error: permission_denied` stays; `code: insufficient_scope`.
const denial = scopeDeniedError({ op: toolName, required: [op.scope ?? 'read', ...(op.requiredScopes ?? [])], auth: auth.auth,
transport: 'http', message: `Tool requires ${op.scope ?? 'read'} scope`, legacy_error: 'permission_denied' });
- return Response.json({ jsonrpc: '2.0', id, result: qmMemoryToolResult(toolName, errorResult(denial, { remote: true, transport: 'http', auth: auth.auth }, { op: toolName })) },
+ return Response.json({ jsonrpc: '2.0', id, result: qmMemoryToolResult(toolName, errorResult(denial, { remote: true, transport: 'http', auth: auth.auth }, { op: toolName }), req.headers.get(ACTOR_HEADER) != null) },
{ headers: corsHeaders(origin) });
}
// v0.28: thread per-token takes-holder allow-list so takes_list /
diff --git a/test/qm-memory-contract.test.ts b/test/qm-memory-contract.test.ts
index a02dba7e03..8e62de780d 100644
--- a/test/qm-memory-contract.test.ts
+++ b/test/qm-memory-contract.test.ts
@@ -1,5 +1,5 @@
/**
- * GST-359 D: the QM memory-provider contract fixtures (docs/contracts/qm-memory-provider/v1.json and v2.json).
+ * GST-359 D: the QM memory-provider contract fixtures (docs/contracts/qm-memory-provider/v1.json, v2.json and v3.json).
*
* 1. Protects: the committed fixture QM vendors equals what the live registry, actor model and error registry produce,
* and it pins the r3 contract values (actor id pattern, stateless session, success codes in structuredContent).
@@ -15,7 +15,9 @@ import { ACTOR_REASON_FIXES, QM_CONTRACT_PATH, QM_CONTRACT_PATHS, renderQmMemory
import { CODES } from '../src/core/error-registry.ts';
import { operations } from '../src/core/operations.ts';
import { buildToolDefs } from '../src/mcp/tool-defs.ts';
-import { unlinkedRecallResult } from '../src/core/ops/qm-memory.ts';
+import { QM_PERSONAL_OPS, unlinkedRecallResult } from '../src/core/ops/qm-memory.ts';
+import { WRITE_REQUEST_STATES } from '../src/core/persistence/types.ts';
+import { DEFAULT_ATTEST_OPS } from '../src/core/access/actor-model.ts';
/** The v1 bytes QM vendored for the 11-06 tag (GBRA-108, GST-359): v1 never changes while QM depends on it. */
const V1_SHA256 = 'c80a7a5f8133f875ef90a2b5052a53c4d2bb0ab95facfa3975ba626c00daae78';
@@ -101,3 +103,88 @@ describe('QM memory-provider contract v2 (GST-1094 scope read, GST-900)', () =>
expect(fixture.memory_write).toEqual(v1.memory_write);
});
});
+
+describe('QM memory-provider contract v3 (GST-1158 F1: personal tools, frozen result shapes, forget_fact)', () => {
+ const fixture = JSON.parse(readFileSync(QM_CONTRACT_PATHS[3], 'utf8'));
+ const v2 = JSON.parse(readFileSync(QM_CONTRACT_PATHS[2], 'utf8'));
+ const personal = (name: string) => fixture.personal_tools.tools.find((t: { name: string }) => t.name === name);
+
+ test('the committed fixture matches the live registry (regenerate with bun scripts/build-qm-memory-contract.ts)', () => {
+ expect(readFileSync(QM_CONTRACT_PATHS[3], 'utf8')).toBe(renderQmMemoryContract(3));
+ });
+
+ test('it keeps everything v2 has; only the version, recall\'s fact rows and the error list grow', () => {
+ expect(fixture.version).toBe(3);
+ for (const key of Object.keys(v2)) {
+ if (key === 'version' || key === 'memory_recall' || key === 'errors') continue;
+ expect(fixture[key]).toEqual(v2[key]);
+ }
+ const { structured_content: recallShape, arm: _arm, ...recallRest } = fixture.memory_recall;
+ const { structured_content: v2Shape, ...v2Rest } = v2.memory_recall;
+ expect(recallRest).toEqual(v2Rest);
+ expect({ ...recallShape, facts: [{ ...recallShape.facts[0], arm: undefined }] }).toEqual({ ...v2Shape, facts: [{ ...v2Shape.facts[0], arm: undefined }] });
+ expect(fixture.errors.shape).toEqual(v2.errors.shape);
+ for (const code of v2.errors.codes) expect(fixture.errors.codes.find((c: { code: string }) => c.code === code.code)).toBeDefined();
+ expect(v2.personal_tools).toBeUndefined();
+ expect(v2.memory_recall.structured_content.facts[0].arm).toBeUndefined();
+ });
+
+ test('memory_recall fact rows carry their arm, own or ranked, and no score', () => {
+ expect(fixture.memory_recall.structured_content.facts[0]).toEqual({ id: 'string', text: 'string', date: 'YYYY-MM-DD', kind: 'string', arm: '"own" | "ranked"' });
+ expect(fixture.memory_recall.arm).toContain('ranked rows only');
+ expect(JSON.stringify(fixture.memory_recall)).not.toContain('score');
+ });
+
+ test('it lists every personal tool, personal-only and opt-in, with the schema MCP serves', () => {
+ const names = fixture.personal_tools.tools.map((t: { name: string }) => t.name);
+ expect(names).toEqual([...QM_PERSONAL_OPS].sort());
+ expect(names).toEqual(['context_pack', 'entity', 'find_experts', 'forget_fact', 'get_backlinks', 'get_page', 'get_timeline', 'get_write_request', 'query', 'volunteer_context', 'whois']);
+ const served = buildToolDefs(operations.filter(o => QM_PERSONAL_OPS.has(o.name)));
+ for (const tool of fixture.personal_tools.tools) {
+ const def = served.find(d => d.name === tool.name)!;
+ expect({ description: tool.description, ...tool.input_schema }).toEqual({ description: def.description, ...def.inputSchema });
+ expect(tool.personal_only).toBe(true);
+ expect(tool.result.structured_content).toBeDefined();
+ }
+ expect(fixture.actor.default_attest_ops).toEqual([...DEFAULT_ATTEST_OPS]);
+ expect(fixture.actor.default_attest_ops).toEqual(['get_write_request', 'memory_recall', 'memory_write']);
+ expect(fixture.personal_tools.opt_in).toContain('--attest-ops');
+ expect(fixture.personal_tools.result_rule).toContain('must be ignored');
+ for (const name of names) expect(fixture.actor.deferred_ops).not.toContain(name);
+ });
+
+ test('the frozen fields are present: every result names the fields QM decodes', () => {
+ const fields = (name: string) => Object.keys(personal(name).result.structured_content);
+ expect(fields('query')).toEqual(['results']);
+ expect(Object.keys(personal('query').result.structured_content.results[0])).toEqual(['source_id', 'title', 'chunk_text', 'score']);
+ expect(fields('get_page')).toEqual(['slug', 'source_id', 'type', 'title', 'revision']);
+ expect(Object.keys(personal('get_timeline').result.structured_content.results[0])).toEqual(['id', 'date', 'summary', 'source', 'detail']);
+ expect(Object.keys(personal('get_backlinks').result.structured_content.results[0])).toEqual(['from_slug', 'from_source_id', 'to_slug', 'to_source_id', 'link_type']);
+ expect(Object.keys(personal('find_experts').result.structured_content.results[0])).toEqual(['slug', 'source_id', 'title', 'type', 'score']);
+ expect(fields('whois')).toEqual(['query', 'query_kind', 'matches', 'ambiguous']);
+ expect(fields('entity')).toEqual(['protocol_version', 'found']);
+ expect(fields('context_pack')).toEqual(['protocol_version', 'entities', 'cards', 'open_threads', 'facts', 'entity_facts']);
+ expect(personal('context_pack').result.content).toContain('text');
+ expect(fields('volunteer_context')).toEqual(['pages', 'count', 'window_turns']);
+ expect(fields('get_write_request')).toEqual(['request_id', 'state', 'retry_after_ms', 'operation', 'source_id', 'slug', 'created_at', 'updated_at']);
+ expect(fields('forget_fact')).toEqual(['id', 'request_id', 'state']);
+ });
+
+ test('get_write_request freezes the write-request states, and an unknown state means unknown, not published', () => {
+ const states = personal('get_write_request').result.states;
+ expect(states.known).toEqual([...WRITE_REQUEST_STATES]);
+ expect(states.known).toEqual(['queued', 'running', 'recovering', 'committed', 'conflict', 'failed', 'cancelled']);
+ expect(states.terminal).toEqual(['committed', 'conflict', 'failed', 'cancelled']);
+ expect(states.published).toBe('committed');
+ expect(states.unknown).toContain('unknown, not published');
+ expect(personal('get_write_request').result.structured_content.state).toBe(WRITE_REQUEST_STATES.map(s => '"' + s + '"').join(' | '));
+ expect(personal('forget_fact').result.structured_content.state).toBe(personal('get_write_request').result.structured_content.state);
+ });
+
+ test('the personal tools add the refusal codes they answer with, each registered', () => {
+ const codes = fixture.errors.codes.map((c: { code: string }) => c.code);
+ for (const code of ['page_not_found', 'result_too_large']) expect(codes).toContain(code);
+ for (const c of fixture.errors.codes) expect(CODES[c.code as keyof typeof CODES]).toBeDefined();
+ expect(fixture.errors.applies_to).toContain('personal');
+ });
+});
diff --git a/test/qm-memory-tools.test.ts b/test/qm-memory-tools.test.ts
index 0aff9c570e..c162544988 100644
--- a/test/qm-memory-tools.test.ts
+++ b/test/qm-memory-tools.test.ts
@@ -360,7 +360,7 @@ for (const kind of testBackends()) {
expect(new Set(ids).size).toBe(ids.length);
expect(Object.keys(out.structured!).sort()).toEqual(['facts', 'truncated']);
expect(out.structured!.truncated).toBe(false);
- expect(out.structured!.facts[at('canaryownrecent')]).toEqual({ id: expect.any(String), text: 'Alice moved standup to Tuesdays canaryownrecent', date: expect.stringMatching(/^\d{4}-\d{2}-\d{2}$/), kind: 'fact' });
+ expect(out.structured!.facts[at('canaryownrecent')]).toEqual({ id: expect.any(String), text: 'Alice moved standup to Tuesdays canaryownrecent', date: expect.stringMatching(/^\d{4}-\d{2}-\d{2}$/), kind: 'fact', arm: 'own' });
expect(out.out._meta?.brain_hot_memory).toBeUndefined();
for (const as of [bob, { token: 'bob' }, { token: 'qm' }, { token: 'plain' }]) {
const other = await recall(as, 'budget ledger standup Tuesdays');
@@ -432,6 +432,25 @@ for (const kind of testBackends()) {
expect(unlinked.structured).toEqual({ facts: [], truncated: false, code: 'actor_unlinked' });
}, 120_000);
+ test('each recalled fact names its arm: own for the person\'s recent facts, ranked for query matches, ranked only under a scope read (GST-1158 F5)', async () => {
+ for (const [fact, provenance] of [['Alice charts the harbor tide canaryarmown', 'turn 50'], ['Alice charted the harbor tide last year canaryarmold', 'turn 49']]) {
+ expect((await write(alice, [{ fact, provenance }])).structured?.status).toBe('committed');
+ }
+ await engine.executeRaw("UPDATE facts SET created_at = now() - interval '3 days', valid_from = now() - interval '3 days' WHERE source_id = $1 AND fact LIKE '%canaryarmold%'", [SRC]);
+ await engine.insertFact({ fact: 'Acme harbor tide tables canaryarmranked', kind: 'fact', entity_slug: ACME, source: 'test', visibility: 'world' }, { source_id: SRC });
+ const out = await recall(alice, 'harbor tide', { max_chars: 12_000 });
+ expect(out.isError).toBe(false);
+ const arm = (needle: string) => out.structured!.facts.find((f: { text: string }) => f.text.includes(needle))?.arm;
+ expect({ own: arm('canaryarmown'), old: arm('canaryarmold'), world: arm('canaryarmranked') }).toEqual({ own: 'own', old: 'ranked', world: 'ranked' });
+ for (const f of out.structured!.facts) expect(Object.keys(f).sort()).toEqual(['arm', 'date', 'id', 'kind', 'text']);
+ const firstRanked = out.structured!.facts.findIndex((f: { arm: string }) => f.arm === 'ranked');
+ expect(out.structured!.facts.slice(firstRanked).every((f: { arm: string }) => f.arm === 'ranked')).toBe(true);
+ const asScope = await recall(alice, 'harbor tide', { max_chars: 12_000, source_id: SRC });
+ expect(asScope.structured!.facts.length).toBeGreaterThan(0);
+ expect(asScope.structured!.facts.every((f: { arm: string }) => f.arm === 'ranked')).toBe(true);
+ expect(asScope.all).not.toContain('canaryarmown');
+ }, 120_000);
+
test('generic recall takes max_chars: whole facts in order, no marker, structured truncated, invalid values refused; without it recall is unchanged (HARN-15)', async () => {
const ENTITY = 'companies/harn-recall-example';
for (let i = 0; i < 12; i++) {
diff --git a/test/qm-personal-tools.test.ts b/test/qm-personal-tools.test.ts
new file mode 100644
index 0000000000..d79aad537b
--- /dev/null
+++ b/test/qm-personal-tools.test.ts
@@ -0,0 +1,236 @@
+/**
+ * GST-1158 F2: an attested call to a contract v3 personal tool answers with its result in structuredContent.
+ *
+ * 1. Protects: each v3 personal tool (query, get_page, get_timeline, get_backlinks, find_experts, whois, entity,
+ * context_pack, volunteer_context, get_write_request, forget_fact) called as an attested person returns its parsed
+ * result in structuredContent (an array as structuredContent.results), holding every field v3.json freezes, while
+ * content keeps the JSON (context_pack: its text alone, as memory_recall); its refusals carry structuredContent.error;
+ * a read whose answer with structuredContent passes the result cap is refused whole; unattested callers and other
+ * tools are unchanged.
+ * 2. Fails when: a v3 tool's structuredContent is missing or drops a frozen field, content changes for a non-text tool,
+ * a refusal lacks structuredContent.error, an attested frame over the cap is sent, or the rewrite reaches an
+ * unattested call or a tool outside v3.
+ * 3. Existing coverage: test/qm-memory-tools.test.ts pins the memory pair; test/qm-memory-contract.test.ts pins v3.json.
+ * 4. Real seams: OAuth client-credentials tokens verified by the provider, MCP dispatch with x-qm-actor, a repo-less
+ * brain on PGLite and Postgres; writes through the persistence coordinator; no embedding provider (keyless).
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { importFromContent } from '../src/core/import-file.ts';
+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
+import { sqlQueryForEngine } from '../src/core/sql-query.ts';
+import { dispatchToolCall, type ToolResult } from '../src/mcp/dispatch.ts';
+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
+import { addMember, bindCredential } from '../src/core/access/members.ts';
+import { linkMember } from '../src/core/access/actor.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+import { QM_PERSONAL_OPS } from '../src/core/ops/qm-memory.ts';
+import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { startHttpTransport } from '../src/mcp/http-transport.ts';
+import { RateLimiter } from '../src/mcp/rate-limit.ts';
+import { QM_CONTRACT_PATHS } from '../scripts/build-qm-memory-contract.ts';
+import type { AuthInfo } from '../src/core/ops/contract.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+
+const SRC = 'source-a';
+const ALICE_ID = 'U0ALICE';
+const PERSON = 'people/bob-example';
+const COMPANY = 'companies/acme-example';
+const BIG = 'notes/big-example';
+
+/** Checks a value against a v3 frozen shape: a type string, a one-row array of shapes, or an object of shapes. */
+function conforms(shape: unknown, value: unknown, at = '$'): string[] {
+ if (Array.isArray(shape)) {
+ if (!Array.isArray(value)) return [at + ' is not an array'];
+ return value.flatMap((v, i) => conforms(shape[0], v, at + '[' + i + ']'));
+ }
+ if (shape && typeof shape === 'object') {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return [at + ' is not an object'];
+ return Object.entries(shape).flatMap(([k, s]) => k in (value as object) ? conforms(s, (value as Record<string, unknown>)[k], at + '.' + k) : [at + '.' + k + ' is missing']);
+ }
+ const ok = String(shape).split(' | ').some(t => {
+ if (t.startsWith('"')) return value === JSON.parse(t);
+ if (t === 'null') return value === null;
+ if (t === 'array') return Array.isArray(value);
+ if (t === 'object') return !!value && typeof value === 'object' && !Array.isArray(value);
+ return typeof value === t;
+ });
+ return ok ? [] : [at + ' is ' + JSON.stringify(value) + ', not ' + String(shape)];
+}
+
+const v3 = JSON.parse(readFileSync(QM_CONTRACT_PATHS[3], 'utf8'));
+const frozen = (op: string) => v3.personal_tools.tools.find((t: { name: string }) => t.name === op).result;
+
+for (const kind of testBackends()) {
+ describe('contract v3 personal tools over MCP dispatch (' + kind + ', repo-less)', () => {
+ let engine: BrainEngine;
+ let close: () => Promise<void>;
+ const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
+ const tokens: Record<string, string> = {};
+ let receipt = '';
+ let factId = 0;
+
+ async function call(token: string, op: string, params: Record<string, unknown>, actor: string | null = ALICE_ID) {
+ const out: ToolResult = await dispatchToolCall(engine, op, { ...params }, {
+ remote: true, transport: 'http', auth: await provider().verifyAccessToken(tokens[token]!) as unknown as AuthInfo, sourceId: SRC,
+ ...(actor !== null ? { actor: { header: actor } } : {}), writeWaitMs: 30_000,
+ });
+ let json: unknown = undefined;
+ try { json = JSON.parse(out.content[0]?.text ?? ''); } catch { /* plain text */ }
+ return { out, json, structured: out.structuredContent as Record<string, any> | undefined };
+ }
+ const local = (op: string, params: Record<string, unknown>) => dispatchToolCall(engine, op, params, { remote: false, sourceId: SRC });
+
+ beforeAll(async () => {
+ if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
+ else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
+ __resetPrivateVisibilityCacheForTests();
+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);
+ await addMember(engine, 'alice-example');
+ await importFromContent(engine, PERSON, '---\ntype: person\ntitle: Bob Example\nemail: [email protected]\n---\n# Bob Example\n\nBob Example keeps the harbor ledger at [[' + COMPANY + ']].\n', { sourceId: SRC });
+ await importFromContent(engine, COMPANY, '---\ntype: company\ntitle: Acme Example\n---\n# Acme Example\n\nAcme Example harbor ledger budget notes.\n', { sourceId: SRC });
+ await importFromContent(engine, BIG, '---\ntype: note\ntitle: Big Example\n---\n# Big Example\n\n' + 'harbor ledger row '.repeat(8_000) + '\n', { sourceId: SRC });
+ expect((await local('add_timeline_entry', { slug: COMPANY, date: '2026-09-02', summary: 'Acme Example opened a harbor office' })).isError).toBeFalsy();
+ expect((await local('add_link', { from: PERSON, to: COMPANY, link_type: 'works_at' })).isError).toBeFalsy();
+ const register = async (name: string) => {
+ const c = await provider().registerClientManual('v3-' + name + '-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
+ tokens[name] = (await provider().exchangeClientCredentials(c.clientId, c.clientSecret ?? '')).access_token;
+ return c.clientId;
+ };
+ await bindCredential(engine, { kind: 'client', id: await register('qm') }, { attestActor: 'qm', attestOps: [...QM_PERSONAL_OPS, 'memory_recall', 'memory_write', 'get_links'] });
+ await register('plain');
+ await linkMember(engine, 'alice-example', 'qm', ALICE_ID);
+ const saved = await call('qm', 'memory_write', { facts: [{ fact: 'Alice prefers the harbor ledger review on Mondays', provenance: 'turn 1' }], idempotency_key: randomUUID() });
+ receipt = saved.structured!.request_id;
+ factId = Number(saved.structured!.fact_ids[0]);
+ }, 120_000);
+
+ afterAll(async () => {
+ await disposePersistenceConsumer(engine).catch(() => undefined);
+ await close?.();
+ });
+
+ test('each personal tool answers an attested call with its parsed result in structuredContent, holding every frozen field', async () => {
+ const cases: Array<[string, Record<string, unknown>, string?]> = [
+ ['query', { query: 'harbor ledger' }],
+ ['get_page', { slug: PERSON }],
+ ['get_timeline', { slug: COMPANY }],
+ ['get_backlinks', { slug: COMPANY }],
+ ['get_backlinks', { slug: COMPANY, group: 'page' }, 'with_group_page'],
+ ['find_experts', { topic: 'harbor ledger' }],
+ ['whois', { query: '[email protected]' }],
+ ['whois', { query: 'Nobody Example' }],
+ ['entity', { name: 'Bob Example' }],
+ ['entity', { name: 'Nobody Example' }],
+ ['entity', { names: ['Bob Example', 'Nobody Example'] }, 'with_names'],
+ ['context_pack', { entities: 'Bob Example' }],
+ ['volunteer_context', { window: 'user: I am meeting Bob Example about the Acme Example harbor ledger' }],
+ ['get_write_request', { request_id: receipt }],
+ ['forget_fact', { id: factId, request_id: randomUUID() }],
+ ];
+ const seen = new Set<string>();
+ for (const [op, params, variant] of cases) {
+ const { out, json, structured } = await call('qm', op, params);
+ expect({ op, isError: out.isError === true }).toEqual({ op, isError: false });
+ expect({ op, has: structured !== undefined }).toEqual({ op, has: true });
+ const result = frozen(op);
+ const shape = variant ? result[variant] : result.structured_content;
+ expect({ op, params, problems: conforms(shape, structured) }).toEqual({ op, params, problems: [] });
+ if (op === 'context_pack') {
+ expect(out.content).toHaveLength(1);
+ expect(typeof out.content[0]!.text).toBe('string');
+ expect(out.content[0]!.text).toContain('Bob Example');
+ expect(structured!.text).toBeUndefined();
+ } else {
+ expect(structured).toEqual(Array.isArray(json) ? { results: json } : json as Record<string, unknown>);
+ }
+ seen.add(op);
+ }
+ expect([...seen].sort()).toEqual([...QM_PERSONAL_OPS].sort());
+ const rows = (await call('qm', 'query', { query: 'harbor ledger' })).structured!.results;
+ expect(rows.length).toBeGreaterThan(0);
+ expect((await call('qm', 'whois', { query: '[email protected]' })).structured).toMatchObject({ ambiguous: false, matches: [{ slug: PERSON, source_id: SRC }] });
+ expect((await call('qm', 'get_write_request', { request_id: receipt })).structured!.state).toBe('committed');
+ expect(frozen('get_write_request').states.known).toContain('committed');
+ }, 120_000);
+
+ test('a refusal of a personal tool under attestation carries structuredContent.error with its code', async () => {
+ const cases: Array<[string, Record<string, unknown>, string]> = [
+ ['get_page', { slug: 'people/nobody-example' }, 'page_not_found'],
+ ['get_write_request', { request_id: randomUUID() }, 'not_found'],
+ ['forget_fact', { id: 987_654_321 }, 'fact_not_found'],
+ ['query', {}, 'invalid_params'],
+ ];
+ for (const [op, params, code] of cases) {
+ const { out, json } = await call('qm', op, params);
+ expect({ op, isError: out.isError, code: (json as Record<string, unknown>).code }).toEqual({ op, isError: true, code });
+ expect(out.structuredContent?.error).toMatchObject({ code, message: (json as Record<string, unknown>).message });
+ expect(v3.errors.codes.map((c: { code: string }) => c.code)).toContain(code);
+ }
+ }, 60_000);
+
+ test('unattested calls and tools outside v3 are unchanged: no structuredContent, the same JSON content', async () => {
+ const plain = await call('plain', 'get_page', { slug: PERSON }, null);
+ expect(plain.out.isError).toBeFalsy();
+ expect(plain.structured).toBeUndefined();
+ expect((plain.json as Record<string, unknown>).slug).toBe(PERSON);
+ const missing = await call('plain', 'get_page', { slug: 'people/nobody-example' }, null);
+ expect(missing.out.isError).toBe(true);
+ expect(missing.structured).toBeUndefined();
+ const attestedOther = await call('qm', 'get_links', { slug: PERSON });
+ expect(attestedOther.out.isError).toBeFalsy();
+ expect(attestedOther.structured).toBeUndefined();
+ expect(Array.isArray(attestedOther.json)).toBe(true);
+ const plainQuery = await call('plain', 'query', { query: 'harbor ledger' }, null);
+ expect(plainQuery.structured).toBeUndefined();
+ expect(Array.isArray(plainQuery.json)).toBe(true);
+ }, 60_000);
+
+ test('the transport\'s scope refusal of a personal tool carries structuredContent.error under x-qm-actor, and not without it', async () => {
+ const legacy = await mintLegacyToken(engine, { name: 'v3-read-' + randomUUID().slice(0, 8), scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
+ await bindCredential(engine, { kind: 'token', id: legacy.id }, { attestActor: 'qm', attestOps: [...QM_PERSONAL_OPS] });
+ const server = await startHttpTransport({ port: 0, engine, surface: 'full', limiters: {
+ ip: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
+ token: new RateLimiter({ limit: 10_000, windowMs: 60_000, lruCap: 100 }),
+ } });
+ try {
+ const post = async (headers: Record<string, string>) => {
+ const res = await fetch('http://127.0.0.1:' + server.port + '/mcp', {
+ method: 'POST', headers: { authorization: 'Bearer ' + legacy.token, 'content-type': 'application/json', ...headers },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 9, method: 'tools/call', params: { name: 'forget_fact', arguments: { id: factId } } }),
+ });
+ return (await res.json() as { result: Record<string, any> }).result;
+ };
+ const attested = await post({ 'x-qm-actor': ALICE_ID });
+ expect(attested.isError).toBe(true);
+ expect(attested.structuredContent.error).toMatchObject({ code: 'insufficient_scope' });
+ const bare = await post({});
+ expect(bare.isError).toBe(true);
+ expect(bare.structuredContent).toBeUndefined();
+ } finally {
+ server.stop(true);
+ }
+ }, 60_000);
+
+ test('an attested read whose answer with structuredContent passes the result cap is refused whole; the unattested read still fits', async () => {
+ await engine.setConfig('mcp.max_result_bytes_http', String(256 * 1024));
+ try {
+ const plain = await call('plain', 'get_page', { slug: BIG, body: 'full' }, null);
+ expect(plain.out.isError).toBeFalsy();
+ const attested = await call('qm', 'get_page', { slug: BIG, body: 'full' });
+ expect({ isError: attested.out.isError, code: (attested.json as Record<string, unknown>).code }).toEqual({ isError: true, code: 'result_too_large' });
+ expect(attested.out.structuredContent?.error).toMatchObject({ code: 'result_too_large' });
+ const window = await call('qm', 'get_page', { slug: BIG, body: 'outline' });
+ expect(window.out.isError).toBeFalsy();
+ expect(conforms(frozen('get_page').structured_content, window.structured)).toEqual([]);
+ expect(window.structured!.body).toBe('outline');
+ } finally {
+ await engine.setConfig('mcp.max_result_bytes_http', String(1024 * 1024));
+ }
+ }, 60_000);
+ });
+}