Garry's Opinionated OpenClaw/Hermes Agent Brain
05. Agent-facing surface: operations, CLI, MCP
Line numbers refer to gbrain 36bd05806a.
Reference: TypeScript gbrain v0.60.733.0 at garrytan/gbrain (commit 36bd05806a), read only. Eval repo at garrytan/gbrain-evals (commit 9ecc5b20).
Method. The reference checkout has no node_modules, so src/core/operations.ts cannot be imported. The 204-entry manifest was instead read from a copy of the handler-free src/core/operation-manifest.generated.ts in /tmp and parsed with bun. The CLI command table was imported directly (its imports are type-only). Engine calls were mapped with a regex over src/core/ops/*.ts and src/core/verbs.ts: direct engine.X( calls inside each op's literal body. Helper-delegated calls are not followed, so some ops show no direct engine call. Items marked (inferred) were not confirmed by running code.
1. Headline numbers (verified)
| Item | Value | Where |
|---|---|---|
| Operations | 204 | operation-manifest.generated.ts |
| Scope split: read / write / admin / agent / sources_admin | 92 / 60 / 48 / 2 / 2 | scope field |
| Mutating / idempotent | 90 / 169 | |
localOnly / cliOnly / verb |
25 / 18 / 7 | |
Ops with cliHints / with a CLI name (cliHints.name) |
121 / 115 | |
| Named params across all ops | 930 | |
| Area groups | 30 (29 named, plus 5 ops with no area) | operation-load.ts:30 OP_AREAS |
| Output redaction | 112 no_stored_text, 53 retrieval, 39 object form (exempt or localVerbatim) |
ops/contract.ts:820 |
| CLI command records | 132 (46 pre-connect, 12 pre-connect-own-engine, 74 post-connect) | src/cli/command-table.ts:148 |
| CLI records with thin-client refuse / route-then-refuse | 43 / 7 | command-table.ts:483 |
CLI records with a --json document contract |
15 (plus bench and eval export/replay/gate as NDJSON) |
json field |
| Error registry entries | about 790 | src/core/error-registry.ts |
| Memory verbs / protocol_version | 7 / 1 | src/core/verbs.ts:35,41 |
| Verb conformance fixture cases | 24 | test/fixtures/memory-verbs/cases.json |
| Allowed OAuth scopes | 10 | src/core/scope.ts:27 |
2. The operation contract
- Each op is a plain object of type
Operation(src/core/ops/contract.ts:826) withname,description,params(aParamDefmap),callShape,handler(ctx, params),outputRedaction, and optionalmutating,idempotent,scope,requiredScopes,localOnly,cliOnly: {argv},publishGateKey,verb,area,agentCallable,annotations,cliHints,writeInference. src/core/operations.ts:146builds the canonicaloperationsarray by spreading per-domain arrays fromsrc/core/ops/*.tsin a fixed order. The order is contractual becausedocs/TOOL_CATALOG.mdis generated from it.finalizeOperationruns over the array at:245.operation-manifest.generated.tsis the same list minus handlers, emitted byscripts/build-operation-manifest.ts. The CLI and stdio MCP read it so they never load the handler graph.test/operation-manifest.test.tspins freshness and equality with the live registry.- Output redaction is applied at registration.
retrievalops get the canonical secret scanner over the whole response.no_stored_textops return no page, chunk, fact, take or transcript text.{exempt}ops return stored text on purpose and must give a reason.
3. Inventory by area (all 204)
Legend after each name: scope r read, w write, a admin, g agent, s sources_admin. Flags: L localOnly, C cliOnly, V verb. Area names are not a contract (contract.ts:892, operation-load.ts:22), so a Rust port may regroup them.
| Area (count) | Operations |
|---|---|
| pages (31) | get_page:r, put_page:w, delete_page:w, list_pages:r, restore_page:w, purge_deleted_pages:a+LC, capture:w, fetch:r, find_pages:r, edit_page:w, append_page:w, put_pages:w, begin_page_upload:w, upload_page_part:w, get_page_upload:w, commit_page_upload:w, abort_page_upload:w, get_write_request:w, list_write_requests:w, list_write_conflicts:r, cancel_write_request:w, get_versions:r, revert_version:w, promote_guest_note:w, put_raw_data:w, get_raw_data:r, resolve_slugs:r, get_chunks:r, whois:r, list_page_purges:a+C, unpurge_page:a+C |
| jobs (20) | submit_job:a, get_job:a, wait_job:a, list_jobs:a, cancel_job:a, retry_job:a, get_job_progress:a, pause_job:a, resume_job:a, replay_job:a, send_job_message:a, submit_agent:g, get_agent_job:g, get_job_stats:a, watch_job:a, watch_write_request:w, watch_cron:a, accept_wakeshift_terms:w, list_watches:w, unwatch:w |
| skills (15) | list_skills:r, get_skill:r, list_brain_skillpack:r, get_skill_asset:r, put_skill:w, delete_skill:w, set_skill_policy:a, get_skill_policy:a, get_skill_retention:a+LC, prune_skill_revisions:a+LC, retain_skill_revision:a+LC, import_skill_proposal:a+LC, join_brain:r, sync_brain_skills:r, leave_brain:r |
| admin (13) | get_stats:a, get_health:a, run_doctor:a, get_brain_health:r, quarantine_list:a, get_write_attribution:a, get_status_snapshot:a, get_usage:a, code_traversal_cache_clear:a+L, migrate_embeddings:a+LC, run_onboard:a, run_skillopt:a, mute_notice:w |
| takes (11) | takes_list:r, takes_search:r, think:r, takes_scorecard:r, takes_calibration:r, takes_add:w, takes_update:w, takes_resolve:w, takes_supersede:w, takes_remove:w+L, takes_rebuild:w+L |
| search (10) | search:r, query:r, assemble_evidence:r, search_stats:a, search_modes:r, search_tune:a, cache_stats:a, search_exact:r, rate_answer:w, search_by_image:r |
| links (9) | add_link:w, remove_link:w, get_links:r, get_backlinks:r, list_link_sources:r, traverse_graph:r, wanted_pages:r, find_orphans:r, rank_entities:r |
| schema (9) | get_active_schema_pack:r, list_schema_packs:r, schema_stats:r, schema_lint:r, schema_graph:r, schema_explain_type:r, schema_review_orphans:r, schema_apply_mutations:a, reload_schema_pack:a |
| insights (8) | get_calibration_profile:r, get_recent_salience:r, find_anomalies:r, get_recent_transcripts:r+LC, volunteer_context:r, find_contradictions:r, find_experts:r, find_trajectory:r |
| memory-verbs (7) | remember:w+V, entity:r+V, synthesize:r+V, forget:w+V, recall:r+V, context_pack:r+V, delta:r+V |
| memory (6) | confirm_memory:w, extract_facts:w, forget_fact:w, memory_recall:r, memory_write:w, memory_propose:w |
| chronicle (6) | chronicle_day:r, chronicle_on_this_day:r, chronicle_since:r, chronicle_last_seen:r, volunteer_chronicle:r, chronicle_backfill:a+L |
| entities (6) | extract_entities:w, extraction_pending:r, extraction_review:w+LC, entity_identity_link:w+L, entity_identity_unlink:w+L, entity_identity_list:r |
| code (6) | code_callers:r, code_callees:r, code_def:r, code_refs:r, code_blast:r, code_flow:r |
| files (5) | file_list:a+L, file_upload:a+L, file_url:a+L, file_register:a+LC, file_verify:a+LC |
| (no area, 5) | storage_register:w+LC, storage_update:w+LC, sources_inspect:r+LC, connectors_status:r+LC, connector_sync:w+LC |
| sources (5) | sources_add:s, sources_list:r, sources_remove:s, sources_status:r, sources_resolve_path:r |
| questions (5) | questions_pin:w, questions_list:r, questions_status:r, questions_refresh:w, questions_unpin:w |
| ontology (4) | ontology_get:r, ontology_propose:w, ontology_dimensions:r, ontology_conflicts:r |
| loops (4) | open_loops:r, loops_close:w, loops_mute:w, loops_unmute:w |
| tags (3) | add_tag:w, remove_tag:w, get_tags:r |
| storage (3) | storage_find:r, storage_get:r, storage_list:r |
| memory-settings (3) | get_memory_settings:r, set_memory_writeback:a, memory_conversation_mode:w |
| timeline (2) | add_timeline_entry:w, get_timeline:r |
| identity (2) | get_brain_identity:r, whoami:r |
| ingest (2) | log_ingest:w, get_ingest_log:r |
| single entries | advisor:r (advisor), sync_brain:a+L (sync), request_tools:r (discovery), purge_fact:a+C (facts) |
Local-only ops (25): purge_deleted_pages, get_skill_retention, prune_skill_revisions, retain_skill_revision, import_skill_proposal, sync_brain, file_list, file_upload, file_url, file_register, file_verify, storage_register, storage_update, takes_remove, takes_rebuild, sources_inspect, get_recent_transcripts, connectors_status, connector_sync, chronicle_backfill, extraction_review, entity_identity_link, entity_identity_unlink, code_traversal_cache_clear, migrate_embeddings.
CLI-only ops (18) have cliOnly.argv, for example purge_deleted_pages maps to gbrain pages purge-deleted --dry-run --json. Over MCP they return trusted_local_only (cliOnlyRefusal, src/core/ops/callable.ts).
4. The roughly 30 most-used operations
The repo has no usage histogram; the derive-starter-ops.ts script needs production mcp_request_log data. The ranking below is therefore inferred from the starter tier, which the code calls the daily-driver set (src/mcp/surface.ts:93). The starter set has 41 names by hand tally. The MEMORY_VERBS doc says 40. Dropping the skill-catalog and brain-membership ops leaves the 32 below.
| Op | Scope | Engine path (direct calls, else delegate) |
|---|---|---|
| remember | w | verbs.ts:229 submitRememberMutation then persistence/memory-mutations.ts then persistence/journal.ts:289 admitWrite (inferred from the chain) |
| entity | r | verbs.ts:256; name lookup helpers, no direct engine calls |
| synthesize | r | verbs.ts:348; LLM call, cost block; no direct engine calls |
| forget | w | verbs.ts:484 then submitForgetMutation (:381); rewrites each page that carries the claim |
| recall | r | ops/facts.ts:298: listFactsSince, listFactsByEntity, listFactsBySession, listSupersessions, countUnconsolidatedFacts; search arm reuses the search pipeline |
| context_pack | r | ops/facts.ts:714; world-only facts unless trusted local |
| delta | r | ops/facts.ts:955 |
| query | r | ops/search.ts:881: getConfig, searchVector (hybrid) |
| search | r | ops/search.ts:696: getConfig, searchKeyword |
| get_page | r | ops/pages.ts:98: readPageSnapshot, transaction, getPage, getTimeline |
| list_pages | r | ops/pages.ts:515: listPages |
| get_backlinks | r | ops/links.ts:445 (helper) |
| traverse_graph | r | ops/links.ts:567: traverseGraph, traversePathsDetailed |
| list_link_sources | r | ops/links.ts:473: listLinkSources |
| resolve_slugs | r | ops/chunks.ts:21: resolveSlugs |
| get_ingest_log | r | ops/ingest-log.ts:60: getIngestLog |
| put_page | w | ops/pages.ts:345: readPageSnapshot, transaction, plus the persistence write journal (inferred from imports) |
| add_timeline_entry | w | ops/timeline.ts:45 (helper) |
| get_recent_salience | r | ops/salience.ts:25: getRecentSalience |
| find_anomalies | r | ops/salience.ts:69: findAnomalies |
| whoami | r | ops/sources.ts:35; reports identity per transport |
| request_tools | r | ops/request-tools.ts:159: executeRaw (two calls); the only discovery meta-op, agent-callable |
| capture | w | ops/pages.ts:704 (hidden alias of a page write; starter list) |
| edit_page | w | ops/page-edit.ts:11 then persistence/page-edit.ts, persistence/page-mutations.ts |
| submit_agent | g | ops/jobs.ts:364: getConfig; Minions queue |
| get_agent_job | g | ops/jobs.ts:539 |
| cancel_job | a | ops/jobs.ts:750 |
| get_write_request | w | ops/persistence.ts:229 |
| list_write_requests | w | ops/persistence.ts:258 |
| cancel_write_request | w | ops/persistence.ts:325 |
| mute_notice | w | ops/notices.ts:15 |
| memory_conversation_mode | w | ops/memory-settings.ts:204 |
5. The seven memory verbs (MEMORY_VERBS v1)
Source of truth: docs/protocol/MEMORY_VERBS_v1.md (1,311 lines), src/core/verbs.ts. The first four (remember, entity, synthesize, forget) are in verbs.ts and spread first into the operations array (operations.ts:146). recall, context_pack and delta are in ops/facts.ts.
| Verb | Class | Params (* required) | Notes |
|---|---|---|---|
| recall | read | query, question (2,000 char cap), entity, budget_tokens, budget_policy (facts_first or query_first), source_id, source_ids, since, session_id, include_expired, supersessions, limit (per arm), grep, include_pending, return_unit, return_window, min_trust, max_chars | Facts arm plus search arm; question ranks facts by cosine plus term share; estimated tokens ceil(len/4) |
| remember | write | fact, provenance (required, else provenance_required), ttl, entity, kind, visibility, valid_from, request_id, items (up to 20), content_origin, expected_revision, force, share, replaces |
Returns a write receipt; write_pending maps to exit 10 |
| entity | read | name or names (1 to 50), source_id, prefer_source_id, variants | Never errors on a miss (found: false); CI-gated p99 under 100 ms on 20K pages |
| synthesize | read | question*, since, until | LLM call; unavailable error when no LLM is configured; quote check adds QUOTE_NOT_IN_EVIDENCE |
| forget | write | id* (opaque fact_id string), reason, request_id, semantic_review | Idempotent (expired: false on repeat); claim_linked refusal when an unlinked fact shares a claim; facts expire, never delete |
| context_pack | read | entities, budget_tokens, since, session_id, include_private, min_trust, include_quarantined, counterparty, intent, source_id, entity_refs, prefer_source_id | Zero LLM; fan-out capped at 8 entities; world-only for remote callers |
| delta | read | since, since_slug, cursor, entities, budget_tokens, session_id, include_private, min_trust, beliefs | O(changes); session cursors expire after 7 idle days |
Every verb response carries protocol_version: 1 (verbs.ts:230 and the others). RESPONSE_SCHEMAS (verbs.ts:604) and ERROR_SCHEMA (verbs.ts:1105) are the machine-readable shapes. Error envelope: {error, code, message, suggestion, detail?, protocol_version}. Frozen codes: invalid_params, provenance_required, not_found, scope_denied, unavailable, budget_unsatisfiable (reserved, never returned), internal. Versioning rule: names and semantics are frozen; new optional params and fields are additive; a breaking change means a new document.
Read verbs redact credential-shaped text for remote callers (ctx.remote !== false). Remote callers see only visibility = world facts, except a caller bound to the brain owner, which also reads private facts (worldOnlyFacts, src/core/search/private-visibility.ts); source grants and member access still apply to both. The trusted local CLI sees stored text.
6. Surface modes
| Mode | Membership | Source |
|---|---|---|
verbs |
exactly ops with verb === true (7) |
surface.ts:242-247 |
starter |
STARTER_OPS (41 by tally) |
surface.ts:93 |
full |
all 204; default for bare serve |
surface.ts header |
Resolution for stdio: GBRAIN_SURFACE env, then --surface flag, then config mcp_surface, then full (surface.ts:209-230). serve --http ignores GBRAIN_SURFACE (src/commands/serve.ts:294-305). On HTTP the surface is a ceiling: each request resolves min(ceiling, client row ?? default), recomputed per request (MEMORY_VERBS doc). Enforcement is fail-closed through one predicate, isCallable (src/core/ops/callable.ts:25), used by both tools/list and dispatch. A hidden op returns unknown_tool, so a guessed name does not leak.
7. OperationContext and the trust boundary
Key fields (src/core/ops/contract.ts:477-826):
| Field | Meaning |
|---|---|
remote |
Required boolean (:502). Fail closed: only strict false is trusted. CLI sets false (src/cli/main.ts:1456); stdio and HTTP set true |
transport |
'stdio' or 'http'. Locality axis only; localOnly ops run on stdio and are denied on HTTP. Trust must not key off it |
auth |
AuthInfo: clientId, scopes, allowedSources, sourceId, boundTools, member, attest, readsUnscoped |
sourceId |
Required string; defaults to 'default' |
localFederatedSourceIds |
Federated read set; set only by trusted builders (CLI non-explicit tier, stdio without GBRAIN_SOURCE, legacy HTTP bearer with no grant) |
explicitReadBinding |
Stdio GBRAIN_SOURCE or .gbrain-source pin; admits an explicit source_id only |
surfaceCeiling, stdioSurface, isCallable |
Surface state for request_tools and whoami |
takesHoldersAllowList |
Per-token holder filter on takes; default ['world'] for MCP tokens without a row |
brainId, admissionOrigin, sessionId, writeWaitMs, deferEmbeds |
Routing, attribution, write wait; deferEmbeds is server-side only |
sourceScopeOpts (src/core/ops/context.ts:646-669) is the one read-scope ladder: (1) non-empty auth.allowedSources gives {sourceIds}; (2) sourceId === '__all__' gives {} only for remote === false; (3) a scalar sourceId gives {sourceId}; (4) remote with a grant and no source throws permission_denied; (5) otherwise {}. Sentinels: ALL_SOURCES = '__all__' and NO_SOURCES = '__none__' (src/core/source-id.ts:45,54). The comment says not to simplify the __all__ branch.
Scope hierarchy (src/core/scope.ts:162-173): admin implies write, read, sources_admin, users_admin; write implies read; agent, skill_editor, skill_publisher, skills_member_self, memory_confirm stand alone. operationScopesAllowed (:195) also honours agentCallable for request_tools. Local CLI bypasses OAuth scope checks (contract.ts:859).
Dispatch (src/mcp/dispatch.ts:1007, dispatchToolCall): normalise optional params, strip the room declaration, then for remote calls resolve the attested actor and audience, run the requester-scope gate (GST-363), resolve access, call dispatchResolvedCall, then shape the result and enforce the frame cap. unknownToolEnvelope is at :639, errorResult at :883.
8. The write path
Writes do not go straight to the engine. They are admitted as write-request rows by admitWrite (src/core/persistence/journal.ts:289), with states queued, running, recovering, committed, conflict, failed, cancelled (persistence/types.ts:2-4; model.ts:7 adds deferred for RequestState). A receipt carries request_id, and the caller polls with get_write_request. Idempotency comes from request_id plus expected_revision. The journal's SQL includes persistence_counters, SELECT ... FOR UPDATE (LOCK_COUNTERS_SQL), unnest($1::text[]) WITH ORDINALITY and ON CONFLICT (journal.ts:241-243). The Rust port must reproduce these semantics, not the SQL.
9. CLI
- Entry:
src/cli.tsanswers--help,--versionand the hook lanes without loading the dispatcher, then loadssrc/cli/main.ts(2,880 lines,runCli). - Command table:
CLI_COMMANDSatsrc/cli/command-table.ts:148, 132 records.CLI_ONLY(:459) is every record name.THIN_CLIENT_REFUSED_COMMANDS(:483) has 47 entries. Phase tells the dispatcher whether to connect the engine first. - Ops reach the CLI through
cliHints.name(115 ops; 121 ops carry acliHintsobject) viasrc/cli/op-manifest.ts. Hidden ops are excluded from the CLI map. makeContext(src/cli/main.ts:1360) builds the trusted local context:remote: false,admissionOrigin: 'interactive'.- JSON contract: a command with
json: 'document'writes exactly one document to stdout; everything else goes to stderr (src/cli/json-guard.ts). Records withjsonSubcommands(eval) use NDJSON. A non-zero exit without a document gets a fallback{error: "command_failed", code, message, suggestion, exit_code, contract_version: 1}. A signal writeserror: "interrupted". - Errors:
writeCliError(src/cli/cli-error.ts:53) andrenderCliError(src/core/agent-output.ts:868). Human form isError [code]: message, thenFix:, thenWhy:.
Exit codes (src/core/exit-codes.ts:18-112, plus registry entries):
| Exit | Meaning | Constant / source |
|---|---|---|
| 0 | ok | OK_EXIT_CODE |
| 1 | failed; class and retryable in JSON |
FAILED_EXIT_CODE |
| 2 | usage or invalid input (invalid_params, unknown_flag) |
USAGE_EXIT_CODE |
| 3 | confirmation_required; nothing ran |
CONFIRMATION_REQUIRED_EXIT_CODE |
| 10 | write accepted, still pending (write_pending) |
PENDING_WRITE_EXIT_CODE |
| 11 | resumable budget stop | BUDGET_STOP_EXIT_CODE |
| 12 | no results (opt-in via GBRAIN_FAIL_ON_EMPTY=1) |
NO_RESULTS_EXIT_CODE |
| 13 | harness wired, verify pending | HARNESS_PENDING_VERIFY_EXIT_CODE |
| 14 | harness cleanup pending | HARNESS_CLEANUP_PENDING_EXIT_CODE |
| 15 | no edition in force for as_of |
VALID_TIME_NOT_IN_FORCE_EXIT_CODE |
| 16 | host upgrade required | HOST_UPGRADE_REQUIRED_EXIT_CODE |
| 17 / 18 | doctor alert: act / unknown | DOCTOR_ALERT_ACT_EXIT_CODE, DOCTOR_ALERT_UNKNOWN_EXIT_CODE |
| 69 | serve exited unhealthy (opt-in) | SERVE_UNHEALTHY_EXIT_CODE |
| 75 | migration lock held | MIGRATIONS_RUNNING_EXIT_CODE |
| 124 | deadline elapsed | TIMEOUT_EXIT_CODE |
| 130 | interrupted (SIGINT) | INTERRUPTED_EXIT_CODE |
Registry codes default to exit 1 unless an entry sets exit. Of the 45 consent-class entries, 12 set exit 3 explicitly; the rest exit 1 unless they set another value, so exit 3 is not a class-wide rule. The contract's legacy exception: mcp expose and google still exit 2 for confirmation.
Error envelope (docs/protocol/AGENT_OPERATOR_v1.md:598-620): error (frozen legacy value), code (canonical), optional reason, message, suggestion, why, fix (argv, command, mcp call, consent, actor, next, verify), docs, docs_cmd, class (caller, consent, retryable, unavailable, server, host_only), retryable, notices, contract_version: 1. fix.next is one of run, ask_user, tell_user_to_run, wait, report, decided by the table at AGENT_OPERATOR_v1.md:713.
10. MCP server and transports
- stdio:
startMcpServer(src/mcp/server.ts:339) uses the MCP SDK'sListToolsandCallToolhandlers (:443,:460). Requests come in withremote: true,transport: 'stdio'(:496-500). Message cap is 64 MiB (src/mcp/stdio-lifecycle.ts:26).request_toolscan widen the session surface. - Result shape:
ToolResult(src/mcp/dispatch.ts:163) is{content: [{type:'text', text}], isError?, _meta?, structuredContent?}. Notices ride extra text blocks with a fixed prefix and_meta.gbrain_notices. - HTTP:
startHttpTransport(src/mcp/http-transport.ts:212). Routes:/health(:366),/mcp(:356onward). Legacy bearer tokens are matched by SHA-256 hex digest (:76-78). Body cap is 1 MiB (:69, overrideGBRAIN_HTTP_MAX_BODY_BYTES). The OAuth path uses the SDK's 4 MiB limit. - Rate limits (
src/mcp/rate-limit.ts:148-155): per-IP 30 per minute, per-token 60 per minute, LRU of 10,000 keys. Each is overridable by env. - OAuth 2.1 (
src/commands/serve-http-oauth.ts,src/core/oauth-provider.ts): the SDK'smcpAuthRouterprovides/authorize,/token,/register,/revoke(:184). Custom handlers addclient_credentialsbefore the router,/.well-known/oauth-authorization-server(:190),/.well-known/oauth-protected-resource(:216) and/.well-known/gbrain(:223). PKCE S256 is validated by the provider (oauth-provider.ts:573). Client auth methods areclient_secret_post,client_secret_basic,none. Default access-token TTL is 3,600 s and refresh TTL 30 days (oauth-provider.ts:232-235). Hard capTOKEN_TTL_MAX_SECONDS = 7,776,000(src/core/grants/model.ts:20). DCR TTL clamps to at least 300 s (oauth-provider.ts:285).client_credentialsvia DCR is refused unless the operator allows it (:382). - Serve flags:
--http,--port(src/commands/serve.ts:368),--token-ttl(:371),--surface,--advertise,--access read-only(stdio only),--stdio-member.
11. Contract guards and conformance oracles
| Asset | What it pins | Reusable by Rust? |
|---|---|---|
test/operation-manifest.test.ts |
manifest freshness, equality with live registry, handler-free startup | Yes as data: export the manifest as JSON and diff it |
test/operations-*.test.ts (allow-list, trust-boundary, source-isolation matrix, coverage ledger, descriptions) |
authorization and isolation per op | Yes, as black-box cases over the wire |
test/mcp-tool-list-snapshot.test.ts, test/mcp-surface.test.ts |
tools/list per surface | Yes: byte or set compare |
test/memory-verbs-conformance.test.ts (896 lines) with test/fixtures/memory-verbs/cases.json (24 cases) |
verb shape, enums, budget arithmetic, idempotent forget, private facts absent for remote | Yes, best oracle: run over HTTP with gbrain protocol conformance --target (src/commands/protocol.ts:60) |
test/fixtures/agent-contract/v1/*.json and test/agent-contract-goldens.test.ts |
frozen wire envelopes; next is recomputed, never stored |
Yes: the goldens are plain JSON |
test/fixtures/goldens/cli/*.json, test/fixtures/cli-contract/help-baseline.json, test/cli-command-table.test.ts |
command table, help text, dispatch order | Partly; help text is useful, dispatch order is TS-specific |
scripts/check-agent-contract.ts (559 lines) with scripts/agent-contract-baselines/*.tsv (12 files, 129 rows) |
16 source rules; baselines are shrink-only; zero-baseline rules include unregistered-code, code-naming, generic-suggestion, defaulted-suggestion |
No: it is a TypeScript AST scanner. Port the rule list and the registry-code check |
test/fixtures/guards/check-agent-contract.ts |
fixture tree for the scanner (GBRAIN_GUARD_ROOT seam) |
Only as a pattern |
src/core/error-registry.ts to docs/guides/error-codes.md (generated) |
one row per code with class, exit, legacy value | Yes: generate a Rust table from the same source |
eval/runner/mcp-contract.ts (gbrain-evals, BrainBench cat 12) |
trusted vs untrusted inputs across operations | No: imports gbrain/operations in-process over PGLite (:20-23). Needs an over-the-wire rewrite |
Rust engine implications
Must preserve exactly (wire contract)
- Operation names, scope,
localOnly,cliOnly,verb,mutating,idempotent, param names, types and enums. These form the MCP tool schema and are read by agents. - The seven verb names,
protocol_version: 1, the response field names, and the frozen legacy error values alongside canonicalcode. - Exit codes 0, 1, 2, 3, 10, 11, 12, 13, 14, 15, 16, 17, 18, 69, 75, 124, 130, and the envelope with
contract_version: 1. - Fail-closed trust:
remoteis required; only strictfalseis trusted. Source ladder insourceScopeOpts, including the__all__and__none__sentinels. - Scope implication table, PKCE S256, SHA-256 token storage, and the
request_id/expected_revisionidempotency rules. - The surface membership sets:
verbs= the seven verbs;starter= the 41-name set. Monotonicity verbs ⊆ starter ⊆ full is pinned by tests.
Can simplify
- The 132-record CLI table is mostly routing. A Rust
clap-style command tree with one generated op-to-command map covers it. - The lazy module loading, stdout interposer (
cli-force-exit.ts) and Bun fast paths exist only for Bun's module graph. Rust writes stdout synchronously. - The express and SDK middleware order (
test/fixtures/goldens/serve-http/routes.json) is TS-specific. Keep the routes, not the ordering. - The registry can become one generated static table.
Postgres features this surface depends on (engine-side, but reached from ops)
- Write journal: row locks (
FOR UPDATE),unnest ... WITH ORDINALITY,ON CONFLICT, counter tables. Needs an embedded transactional store with single-writer or row-lock semantics. - Config as rows:
mcp_surface,mcp.strict_params,mcp.publish_*are read from the engine config table with file fallback. Rust needs the same DB-over-file precedence. - Access tokens, OAuth clients and codes, and
mcp_request_logare SQL tables. The legacy bearer path also runs raw SQL throughexecuteRaw(inrequest_toolsand wakeshift). - Facts and pages are source-scoped by
source_idon every read; the ladder must be enforced in the storage layer's query builder, not only in ops.
Risks
- 930 params spread over 204 ops; most validation lives in per-op code plus
validate-params.ts(322 lines). A Rust port that validates less will drift from the tools/list schema. - Description strings in the manifest are read by agents and drive behaviour. Treat them as data and copy them verbatim.
- The write path has multi-step receipts,
write_pending, and--accept-pending. Getting exit 10 and the receipt right matters more than the internal journal design. gbrain-evalsimports the TS library directly. Anything that breaks that import breaks the eval harness until it is rewritten over the wire.
Open questions
- Which ops are truly most used? The repo has no histogram. Who can supply production
mcp_request_logcounts so the starter set is re-derived? - Starter tier size: the code tallies 41 names; the MEMORY_VERBS doc says 40. Which is the contract, and is the discrepancy intended?
- Should the Rust engine serve the full 204-op surface in v1, or only
verbsplusstarterwithfulllater? - Is the OAuth 2.1 server (DCR, PKCE,
/revoke) required for v1, or is stdio plus legacy bearer enough for the first release? - Which
cliOnlycommands (purge_fact,file_verify,migrate_embeddings, skill retention) must exist in v1 given they are owner-only? - Per-op engine mapping is partial because helper-delegated calls were not followed. A second pass needs the TypeScript compiler, which is not installed in the reference checkout. Who installs it in a scratch copy?
- Does the Rust port keep write-request receipts and the
deferredstate, or can it admit writes synchronously in v1? - Exit codes 2 versus 3 for
mcp exposeandgoogleare documented as legacy. Should the Rust engine copy the legacy behaviour or the v1 table?