mirror of
https://github.com/garrytan/gbrain.git
synced 2026-08-15 01:12:20 +00:00
Garry TanandClaude Fable 5
6a905a1e5b
* feat(writer): surface writer_lint findings in the put_page payload (T11/WP6)
put_page's writer_lint block grows from counts-only to an actionable
summary: errors-first top_findings (cap 5, per-finding fix hint, message
truncation), details_truncated, and a by_validator histogram. Contract per
amendment 28: lint ran with zero findings keeps the key present (zeroed);
a lint crash returns {status: 'lint_error'}, distinguishable from lint-off
(key absent).
validators/index.ts exports BUILTIN_VALIDATORS as the single registry
(ENG-12): registerBuiltinValidators, runPostWriteLint, and the new
FIX_HINTS map all derive from it. The payload plumbing lives in
post-write.ts (summarizeWriterLint + writerLintForPutPage) so every
outcome mapping is unit-testable without mocking the op handler.
New test pins the previously-unpinned payload shapes end-to-end on PGLite
plus FIX_HINTS completeness against the registry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP1 honest catalog — gate/scope/bound-aware tools/list + localOnly transport backstop
The advertised list is now exactly what the calling token can use: tools/list
filters per request by token scope, the bound-client fence predicate (shared
with dispatch via opAllowedForBoundClient so list and deny cannot drift), and
the publish gates (hidden while off; read failure hides the gated ops, never
fails the list). localOnly ops are confined to the stdio local pipe by a new
dispatch-layer backstop keyed on transport locality; the legacy bearer
transport also stops listing them. Denials carry the machine-readable
config_key detail grammar.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP2 _meta.retrieval channel + model-visible empty-result block + concept hint (E1)
search/query publish their already-computed retrieval meta (counts, vector
arm, cache, budget, degradation stages) through a per-key _meta side channel;
empty results additionally carry a second text content block so the model
sees the diagnosis in every harness while deployed thin-clients keep parsing
content[0] unchanged. The concept-shaped hint (TODOS P2) rides the same
channel on the search op. Producer isolation: a metaHook failure can no
longer drop handler-emitted keys. Convention doc: docs/protocol/MCP_META_CHANNELS.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(verbs): synthesize compose status + extractive fallback (WP2/T5, E2, ENG-10/19)
Stop dropping runThink's failure signal at the synthesize verb. runThink now
stamps a typed synthesis_status (ok | empty_answer | not_json | no_llm |
model_unusable | llm_error) and catches client.create() throws (429/timeout/
5xx/network) into llm_error instead of crashing the call — explicit-model
AIConfigError (#1698), BudgetExhausted, and AbortError stay hard throws.
Verb precedence (registry refinement): compose failure + non-empty gather ->
extractive fallback (synthesis_status: extractive_fallback; answer digests +
cites ONLY gathered pages via composeExtractiveFallback — empty gather NEVER
produces an answer, ENG-19); compose failure + empty gather -> typed
verbError('unavailable', 'retrieved 0 pages; compose failed: <code>'); no-LLM
stays the [c10] unavailable error regardless of gather. Every success response
now carries additive synthesis_status / pages_gathered / takes_gathered /
warnings; RESPONSE_SCHEMAS extended additively (protocol_version stays 1);
MEMORY_VERBS_v1.md gains the compose-status subsection (+ llms-full rebuild).
The think op inherits the new ThinkResult fields via its existing spread.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(minions): T10 minions visibility — snapshot v2, submit-time queue probes, get_agent_job
WP5 of the MCP truthful-surface wave (amendments 16, 24-27, ENG-13/16/18/20):
- get_status_snapshot schema_version 1->2: additive queue (status counts +
per-queue depth + oldest_waiting_age_seconds, generalizing the doctor
oldest-age SQL past embed-backfill) and workers (supervisor liveness via
pidfile + DB-lock ladder, last_completed_at) sections, each fail-soft to
{error: 'unavailable'} without failing the snapshot. Thin-client
`gbrain status` renders the remote payload for workers/queue and degrades
gracefully against old (v1) servers.
- submit_job/submit_agent attach queue_state from a time-bounded (~1.5s),
fail-open probe (probeQueueState in supervisor.ts, reusing
queryWedgeSignals + supervisor DB-lock liveness + worker registry + the
autopilot pause marker). Warnings fire on dead lane, over-threshold depth
(GBRAIN_QUEUE_WAITING_THRESHOLD), and migration pause; a probe failure
degrades to {probe_failed: true} and never errors a paid submission.
- NEW get_agent_job op (scope 'agent', now a first-class Operation scope
union member; the `'agent' as any` cast on submit_agent is gone):
clientId required on every transport, fail-closed JSONB ownership WHERE,
uniform not_found for foreign/missing ids (ErrorCode comment widened),
trimmed view + claim-order queue_position for waiting jobs.
- computeQueueHealthCheck now returns structured details
{depth, oldest_age_seconds, worker_alive}; messages unchanged.
No migration DDL in this lane: the wedge index (queue, status, updated_at)
lands with the wave's single migration in another lane; new queries note
the index prefix they will ride.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(search): fail-loud retrieval core — degraded[] stamp, allSettled salvage, minKeep budget, short-TTL degraded cache (WP2/T3)
Lane B of the MCP consumer-feedback wave (amendments 5-8, D6, D14.2,
ENG-2/5/6/7/15, FOV-2):
- types.ts: HybridSearchMeta gains degraded[] (CLOSED exported stage
vocabulary DEGRADED_STAGES + enumerated DEGRADED_REASONS — raw
exception text never rides the wire, D6) and retrieved_count
(pre-budget hit count); token_budget gains truncated.
- hybrid.ts: Promise.all → Promise.allSettled on BOTH the embed fan-out
and the searchVector fan-out (ENG-15). Salvage semantics: variant
embed fails → original survives (expansion_partial); ORIGINAL fails
with variants ok → salvage variant lists, skip cosine re-score
(expansion_partial + rescore_skipped); all fail → keyword-only
(embed_unavailable/embed_timeout). Keyword-only-config and image/
unified branches stamp their degradation too (no silent bypass).
GBRAIN_SEARCH_SALVAGE=off (env-only, ENG-7) restores all-or-nothing
embeds + the strict budget wrapper.
- token-budget.ts: packToBudget UNCHANGED (frozen verb consumers);
enforceTokenBudget gains the minKeep:1 failsafe — first-result-
exceeds-budget keeps ONE result with chunk_text truncated on a COPY
(never mutating the shared SearchResult); sub-title-cost budgets keep
a title-only copy; dropped=N-1 + truncated reported (ENG-2/FOV-2).
- hybridSearchCached: both meta rebuilds become spread-carry (ENG-5) so
no inner key can silently drop again; hit path stamps cache 'hit'
(hit-with-offset included); rows lacking the degradation stamp emit
degraded:[{stage:'cache_prestamp'}] instead of claiming clean;
degraded-but-embeddable result sets cache with a short TTL (60s,
D14.2/ENG-6 — total embed outage stays uncacheable by construction).
- mode.ts: KNOBS_HASH_VERSION 15→16 (degradation-stamp epoch).
- telemetry.ts: empty_result rollup keyed by cause (vector_disabled /
budget_dropped_all / keyword_zero) riding reserved
(date,'empty_result',cause) rows — zero new DDL; surfaced via
readSearchStats.empty_results and diverted from call/intent/mode
aggregates.
- tests: token-budget minKeep flip + direct packToBudget strict-edge
pins (context_pack-shaped fixture); ENG-15 three-branch salvage suite
+ vector-arm + kill-switch; meta-key-parity (bare ⊆ cached, hit and
miss); cache_prestamp fixture; short-TTL + null-embedding-skip;
empty-cause telemetry suite; KNOBS_HASH_VERSION pins updated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP3 discovery — complete param schemas, strict/warn arg validation, one schema mapper
T6 — descriptors + strict/warn validation:
- Backfill descriptions on all 36 previously-undescribed params across 24
non-localOnly ops (search.query / query.query / resolve_slugs.partial
first), house style with inline examples where a name is guessably wrong.
- CI walker in test/mcp-tool-defs.test.ts fails on any non-localOnly op
param lacking a non-empty description (localOnly exempt).
- Extract normalizeOptionalParams + validateParams into
src/mcp/validate-params.ts (call order normalize→validate preserved, doc
comments verbatim; dispatch re-exports; server.ts second caller updated).
- New config key mcp.strict_params ('warn' default | 'reject'), resolved
dual-plane (DB > file > warn) once per dispatch. Unknown top-level keys
(allowlist: _meta, dry_run) warn-collect into _meta.warnings
[{code:'unknown_param', param, suggestion?}] + a model-visible second
content block in warn mode; reject mode returns invalid_params with the
did-you-mean in `suggestion` only — the raw unknown key never reaches
`message`, the one field persisted to mcp_request_log.error_message.
- Enum membership violations return invalid_params in BOTH modes, naming
the allowed values (never echoing the submitted value).
- unknown_tool did-you-mean via one shared envelope builder for all three
deny paths (hidden/nonexistent/localOnly-over-HTTP); candidates are the
caller-visible surface minus localOnly minus publish-gated ops, so hidden
names never leak and hidden-vs-nonexistent stays byte-identical (pinned).
- query op's plain "requires either query or image" throw is now
OperationError('invalid_params', ...).
- serve-http logs 'success_with_warnings' when a result carries non-empty
_meta.warnings (warn contents never logged) — amendment 13 observability.
T7 — one schema mapper:
- buildToolDefs(ops, {strictParams}): strict emission closes each schema
with additionalProperties:false and declares the _meta/dry_run
passthrough keys (D14.1, no clobber of real dry_run params); default
emission stays byte-identical (both states pinned).
- serve-http ListTools unified onto buildToolDefs with a per-request
dual-plane strict_params read (restart-free flip); stdio + legacy bearer
transports resolve once at startup from the file plane (flip needs a
restart there — deliberate, per plan).
- gbrain --tools-json rebuilt on buildToolDefs additively: legacy
name/description/parameters keys preserved verbatim, full JSON Schema
added under a new per-tool `schema` key.
Rider: test/file-upload-engine-context.test.ts now dispatches localOnly
file ops with transport:'stdio' — it pins engine ownership, and the WP1/D7
localOnly backstop (earlier commit on this branch) correctly denies its
old transport-less dispatch.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): WP4 starter surface, per-client ceiling-bounded unlock, request_tools
T8 — per-client surface persistence:
- Migration v127: oauth_clients.surface + surface_set_by (open value
space, amendment 18) + the ENG-10 wedge index
idx_minion_jobs_queue_status_updated (queue, status, updated_at);
mirrored in schema.sql / schema-embedded.ts / pglite-schema.ts and the
forward-reference bootstrap probe sets of BOTH engines (v121 mask
class), pinned by test/schema-bootstrap-coverage.test.ts.
- verifyAccessToken gains a NEW top degrade-ladder rung (drop the
surface columns first, keep the v85 fence column); missingOAuthColumn
probes BOTH new names (ENG-9). AuthInfo threads surface + surfaceSetBy.
- McpSurface widens to 'verbs' | 'starter' | 'full'. STARTER_OPS is
composed programmatically (spread of VERB_NAMES — seven verbs, ENG-1 —
+ the FOV-6b fallback daily set from BRAIN_TOOL_ALLOWLIST + the FOV-4
agent lane + whoami + request_tools) with a provenance note; the
production-histogram derivation corrects it later. Monotonicity
verbs ⊆ starter ⊆ full pinned; 'verbs' semantics untouched.
- D2 CEILING: serve-http resolves min(server --surface ceiling, client
row surface ?? mcp.default_surface_dcr ?? ceiling) PER REQUEST
(amendment 20); unknown row values ignored with warn-once per client.
GBRAIN_MCP_FORCE_SURFACE kill switch min()s in on top, NARROW-ONLY
(FOV-6a), pinned next to the D2 ceiling test.
- gbrain auth rescope-client --surface verbs|starter|full|clear
(surface_set_by='operator'; 'clear' nulls both) + the admin endpoint
mirror; EVERY surface mutation (CLI, admin, request_tools persist)
writes an mcp_request_log operation='surface_change' audit row with a
raw-object params payload via executeRawJsonb (ENG-8, amendment 32).
T9 — request_tools meta-op (contract-first):
- scope 'read' + mutating + agentCallable (FOV-4 scope carve-out in
serve-http list + call); listed on starter+full only (D4). No args →
area-grouped catalog of the ops VISIBLE to the caller (scope, fence,
localOnly-on-http, publish gates, ceiling — hidden names never leak);
{tools} → read-only descriptors for the visible subset (D5);
{surface} → self-persist within the ceiling, denied on operator lock
(detail 'locked_by=operator') or above the ceiling (detail
'ceiling=<surface>'), ~5/hour/client rate limit (D14.5),
pre-migration → {persisted:false, reason:'migration pending'}.
- D9 meta-op carve-out (BOUND_CLIENT_META_OPS) in opAllowedForBoundClient
so slug-bound clients keep discovery; persist self-enforces its guards.
- Operation.area populated for every non-localOnly op (names
non-contractual, amendment 22); tool-defs CI walker extended.
Integrator fixes (branch verify gate was red at HEAD): withEnv() for the
lane-B token-budget env tests, lane-F writer-lint comment reworded off
the R2 lint token, publish-gates.ts added to the operations-filter-bypass
allowlist with rationale.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(cli): T15 — empty results name their cause on both CLI surfaces
formatResult's empty branch renders the retrieval degradation (stages +
pre-trim count) captured from either path: the local engine via the
emitResponseMeta twin, or the thin-client envelope via _meta.retrieval.
unpackToolResult stays content[0]-only by contract (D8 skew guard, now
pinned) and extractResponseMeta lifts the envelope meta without erroring
on old servers.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(cli): fix generic on unpackToolResult pin (typecheck)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* feat(mcp): T12 expansions — usage reader, advisor starter-fit, usage CLI, TOOL_CATALOG generator
The four T12 expansions over the truthful-surface wave's machinery
(amendments 22-23, 29-30, D12):
- src/core/mcp-usage.ts: the ONE shared reader over mcp_request_log.
Encodes the row-hygiene rules once (JSON-RPC method rows + ENG-8
surface_change audit rows dropped; legacy 'tools/call:<name>' prefix
stripped), windows on created_at (rides idx_mcp_log_time_agent), and
classifies automation-shaped clients behaviorally (>90% context_pack/
delta boundary calls — D12; the hook lane is stdio and never logs, so
there is no name convention to key on).
- E3: advisor collector `mcp-client-fit` — per-client starter fit
(full-surface client whose 30d distinct-op set fits STARTER_OPS gets
the exact `gbrain auth rescope-client <id> --surface starter` fix) +
set-level drift curation (top-used ops missing from STARTER_OPS;
starter members unused 90d). Remote output redacts client identifiers
to aggregate counts (amendment 29); dismiss/snooze rides the nag-state
engine with its own state file; >=10-call alert threshold.
- E4: `gbrain auth clients [--usage] [--days N] [--json]` — per-client
op-call counts, top ops, last-seen, joined with scopes + surface +
surface_set_by from oauth_clients; legacy bearer tokens listed
separately (no per-client surface row to rescope).
- scripts/derive-starter-ops.ts (amendment 23 + D12): proposes the
STARTER_OPS daily slice from production usage — per-client DISTINCT-op
sets ranked by client count, automation clients excluded, provenance
header, BRAIN_TOOL_ALLOWLIST cross-check. Prints only; never edits.
- E6: generated docs/TOOL_CATALOG.md (config-independent, deterministic;
one section per area; per-op scope/starter/gate columns; non-localOnly
only) via src/mcp/tool-catalog.ts + scripts/generate-tool-catalog.ts,
freshness-guarded by scripts/check-tool-catalog-fresh.sh wired into
`bun run verify` (the METRIC_GLOSSARY pattern).
Tests: test/mcp-usage.test.ts (hygiene incl. legacy prefix + exclusions,
windowing, automation classification), test/advisor-mcp-client-fit.test.ts
(local vs remote redaction, exclusions, drift, snooze lifecycle),
test/tool-catalog.test.ts (determinism, coverage, freshness + CI wiring).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(ops): T14 — surface runbook, honest-catalog metric, TODOS filings, docs pass + llms regen
Observability + operator tail of the truthful-surface wave (amendments
33-36, D10, D14.3, ENG-6/7/8/13):
- docs/operations/mcp-surface-runbook.md: the four operator moves with
exact commands + expected outcomes (publish-gate flip, surface rescope
with audit-row verification, strict-params warn→reject flip with the
named evidence criterion + schema-emission note, STARTER_OPS re-derive),
the incident levers (GBRAIN_MCP_FORCE_SURFACE narrow-only clamp,
GBRAIN_SEARCH_SALVAGE=off), the ENG-6 total-embed-outage expectations
(query cache uncacheable by construction; keyword-only degraded
results), the honest-catalog metric SQL, and a first-5-minutes
post-deploy checklist with a ~/.gbrain/smoke-tests.d drop-in snippet.
- Honest-catalog metric (amendment 33): op-level call-time denials the
tools/list filter should have prevented now log
status='denied_after_list' instead of 'error' — the inline scope deny
in serve-http, the publish-gate backstop (detail 'config_key=...'),
and the bound-client fence OP-level deny (new detail 'fence=op',
assign-after per ENG-11). Argument-level slug-fence denials carry no
marker and stay 'error' (D10 carve-out). Classifier
`isListLevelDenialEnvelope` exported from src/mcp/dispatch.ts; pinned
by test/denied-after-list.test.ts through real dispatch envelopes.
- Amendment 23 stopgap: the tools/list mcp_request_log row now records
the listed size as params.tool_count (raw object via executeRawJsonb).
- TODOS.md: eight filings — strict_params reject-flip (P1, named
zero-success_with_warnings/30d criterion + the pinned default=warn
test), mcp_request_log retention/pruning (now carries surface_change
audit + denied_after_list rows), describe_tools (OQ4), page_lint (OQ5),
named client tiers, per-client token budgets, full list-size telemetry,
get_job not_found alignment (ENG-13).
- Docs pass (current-state only): MEMORY_VERBS_v1.md surface modes gain
'starter' + the D2 ceiling semantics; thin-client.md documents the
full-surface posture (bootstrap pin; stdio has no client row);
KEY_FILES.md entries updated (surface.ts, dispatch.ts, tool-defs.ts,
serve-http.ts, advisor cluster) + new entries (validate-params.ts,
publish-gates.ts, tool-catalog.ts, surface-audit.ts, mcp-usage.ts,
MCP_META_CHANNELS.md). llms bundles regenerated (bun run build:llms).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): E5 truthful-catalog invariant — listed means callable, hidden means unknown
The wave's final guard (T13/E5, D10 carve-out, ENG-21 recipe, FOV-4/6c,
amendment 31): for each token class, tools/list then probe every listed
tool and assert no probe returns a LIST-LEVEL denial (publish-gate
config_key=..., bound-fence fence=op, scope insufficient_scope, or an
unknown envelope for an advertised name); invalid_params is acceptable.
Inversely, surface-hidden and localOnly ops return the no-leak
unknown-tool envelope, gate-hidden ops hit the fail-closed config_key
backstop, and fence-hidden ops hit fence=op.
Placement: test/truthful-catalog.e2e-lite.test.ts in the UNIT tree (not
test/e2e/, which runs only under run-e2e.sh on Postgres hosts) — the file
needs no DATABASE_URL, so the invariant runs in every CI unit pass.
Recipe (ENG-21): ONE PGLite engine + ONE real legacy-bearer HTTP server
reused across cells; the OAuth serve-http semantics run in-process through
the exact seams serve-http composes (filterOpsForSurface, hasScope +
agentCallable carve-out, opAllowedForBoundClient, disabledOpsForPublishGates,
dispatchToolCall). mcp.strict_params pinned 'reject' on the DB plane so no
garbage-arg probe can execute a write handler; required params probed with
wrong-typed values; request_tools probed with {surface:'garbage'} (never a
persist); exactly ONE warn-mode case probing a READ op (FOV-6c). Matrix:
scopes {read,write,admin,agent} x surfaces {verbs,starter,full} x gates
{on,off} x bound/unbound — full probe sweep on 3 extreme cells
(admin+full+gates-on, read+starter+gates-off, bound+write+full), list-set
equality + denial-class representative probes on the remaining 48 cells,
the FOV-4 agent-only row (exactly submit_agent/get_agent_job/request_tools),
verbs ⊆ starter ⊆ full monotonicity per token class, the amendment-20
persist→re-list flip (request_tools {surface} persist reflected by the next
per-request resolution, no restart), and a loud <3-minute wall-clock budget.
The full OAuth-server sweep (real HTTP + real tokens) remains the
Postgres-host assertion in test/e2e/serve-http-oauth.test.ts.
Rider fix the guard forced: the legacy bearer transport
(src/mcp/http-transport.ts) listed the four publish-gated ops
unconditionally (tool list built once at startup, no gate filter), so with
gates off — the default — they were listed-but-denied with the config_key
list-level denial: the exact catalog lie this wave exists to end. Its
tools/list now subtracts disabledOpsForPublishGates per request (dual-plane
read, restart-free flip, fail-closed on read failure), matching the OAuth
transport; the in-handler gates stay as the call-time backstop. Verified by
mutation: reverting the fix fails 3 of the new legacy-transport tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore(cli): regenerate flag registry for the wave's new auth flags
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: pre-landing review fixes
Ten review findings, all two-way doors:
1. health-indicators error rate no longer counts success_with_warnings /
surface_change rows as errors (denied_after_list stays counted).
2. visibleOpsForCaller treats the trusted local CLI (remote === false) like
stdio: localOnly + publish-gated ops stay visible to the operator who can
actually call them.
3. request_tools dry-run previews no longer consume the persist rate-limit
budget (denials still exercised; limiter meters actual writes only).
4. normalizeLoggedOperation re-runs the NON_OP_LOG_ROWS hygiene check on
legacy-prefix-stripped names ('tools/call:tools/list' no longer counts
as usage).
5. LLM_CALL_FAILED warnings carry a closed-vocabulary class (timeout |
rate_limited | network | provider_error) instead of raw provider text;
the raw message goes to stderr. MEMORY_VERBS doc + schema updated.
6. Publish-gate + strict-params config reads are issued concurrently
(tools/list RTT depth 3 -> 1).
7. resolveEffectiveSurface skips the default-surface config read when the
clamped ceiling is already 'verbs' (min() cannot go lower).
8. buildQueueDepths / doctor waitingByQueue comments now state the truth:
the wedge index gives no prefix access for a status-only WHERE; these
full-scan today.
9. Verb-count comments updated to the seven frozen verbs + starter tier.
10. ALWAYS_INCLUDED_STARTER_OPS exported from surface.ts and consumed by the
advisor starter-fit collector (which omitted the agent lane, producing a
perpetual bogus unused-starter finding) and derive-starter-ops.
Also extracts requestLogStatusForResult (src/mcp/dispatch.ts) as the one
request-log status decision serve-http persists — behavior identical, unit
pins land in the follow-up test commit. Behavior pins for fixes 2-5 and 10
ride here so every commit stays green (test/request-tools, test/mcp-usage,
test/think-extractive.serial, test/advisor-mcp-client-fit).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test: regression tests for request-log statuses and query invalid_params
Coverage-audit gaps + test hygiene from the pre-landing review:
- requestLogStatusForResult unit pins (all four statuses: success,
success_with_warnings, denied_after_list, error) in
test/denied-after-list.test.ts; row-level twins live in the Postgres-host
e2e (extension filed in TODOS.md).
- query op with neither `query` nor `image` returns the typed invalid_params
envelope, never internal_error (engine stub — the throw precedes any
search).
- writeSurfaceChangeAudit fail-open contract: a throwing engine resolves
false and never throws; the happy path binds the params object raw
(jsonb discipline).
- parseAuthClientsArgs: defaults, --days bounds (incl. >3650 rejection),
--usage/--json flags, unknown-flag rejection.
- E5 truthful-catalog wall-clock budget is enforced only under
GBRAIN_ENFORCE_E5_BUDGET=1 (warn otherwise — machine-load-dependent);
T0 moves from module load into beforeAll.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: file review-deferred TODOs
Six deferrals from the /ship pre-landing review, grouped by component under
a new truthful-surface-wave section: default-surface memoization on the
tools/call hot path (P2), Postgres-host e2e row-level request-log assertions
(P2), surfaceProjectionDegraded marker for drift-shaped brains (P3), partial
completed-jobs index if snapshot polling gets hot (P3), the master-owned
extract-atoms shard flake (P1, with failure signature), and the eight-item
hygiene dedupe batch as one P3 entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: adversarial review fixes — fail-closed surface resolution, usage hygiene, wire-safe warnings
Twelve fixes from the cross-model (Codex + Claude) adversarial ship review:
- resolveEffectiveSurface holds the last successfully read default surface
per process, so a transient config outage can't silently widen a
NULL-surface client to the ceiling; stale never-throws comment rewritten.
- readClientOpUsage counts only success/success_with_warnings rows — denial
and error traffic can no longer "use" its way into starter derivation or
advisor fit findings.
- think/index.ts pushes closed warning codes (QUESTION_EMBED_FAILED /
CALIBRATION_FETCH_FAILED / TRAJECTORY_INJECTION_FAILED) on the wire; raw
exception text goes to stderr only (D6).
- enforceTokenBudget's minKeep failsafe slices the title too, so used <=
budget holds unconditionally; the failsafe now stamps a distinct
budget_truncated stage (additive vocab) while budget_dropped_all is
reserved for genuinely-empty strict returns.
- advisor drift arm excludes localOnly ops from starter recommendations
(mirrors derive-starter-ops).
- legacy bearer transport routes tools/call statuses through
requestLogStatusForResult — denied_after_list / success_with_warnings
now feed the amendment-33 metric on both HTTP transports.
- request_tools rejects {surface, tools} together as invalid_params; a
race-lost persist (0-row UPDATE under a concurrent operator pin) refunds
its rate-limit token (new RateLimiter.refund, capped at limit).
- health-indicators error rate: surface_change is an OPERATION value, not a
status — audit rows now excluded from numerator AND denominator via the
operation column.
- expansion_failed carries reason 'timeout' when the expander timed out.
- resolveStrictParamsMode holds the last-known-good DB mode so a transient
config outage on a reject-mode server can't re-open the warn grace period
(+ reset seam for tests).
- get_agent_job caps error_text at 2000 chars (unbounded worker field).
Regression tests: usage status filter, denied_after_list on the legacy
transport (DB-plane-pinned gate), strict-mode last-known-good, both-params
reject, limiter refund semantics, title-slice used<=budget pin.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: file adversarial-review TODOs
Four review-deferred items from the ship-stage adversarial review: atomic
old-surface capture for the request_tools audit row (P2), persist rate-limit
durability across restarts/processes (P3), cancellation for timed-out
submit-time queue probes (P3), and a schema_version union doc for the
status snapshot JSON consumers (P3).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* chore: bump version and changelog (v0.45.12.0)
Truthful Surface wave — MCP consumer-feedback fixes. Version train:
VERSION + package.json + CHANGELOG + openclaw.plugin.json +
BOOTSTRAP_FOR_AGENTS.md stamp + regenerated bootstrap templates.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: post-ship documentation sync for v0.45.12.0
Catch the drift the pre-landing (a8f502857) and adversarial (28bac59bc)
fix commits introduced after the wave's T14 docs pass:
- KEY_FILES.md: requestLogStatusForResult (both HTTP transports),
ALWAYS_INCLUDED_STARTER_OPS (surface + advisor + derive-starter-ops),
resolveEffectiveSurface / resolveStrictParamsMode last-known-good
fail-closed behavior, RateLimiter.refund, usage success-only status
filter + prefix-strip hygiene re-run, advisor drift-arm localOnly
exclusion, health-indicators error-rate audit-row exclusion.
- mcp-surface-runbook.md: --usage counts successful calls only;
request_tools persist rate-limit/dry-run semantics; strict-params
reject posture survives a transient config outage.
- INSTALL.md, mcp/DEPLOY.md, mcp/CLAUDE_CODE.md,
tutorials/connect-coding-agent.md: the verbs surface is seven verbs
(context_pack + delta), matching the code snippets in the same files;
surface enumerations now include starter.
- llms.txt / llms-full.txt regenerated (build:llms chaser).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: doc-review fixes — honest starter count/provenance, scoped _meta claim, DCR-default runbook move
Four gaps from the cross-model documentation review:
- Starter surface is ~26 ops (STARTER_OPS.size), not ~20 — harmonized
across CHANGELOG, MEMORY_VERBS_v1, KEY_FILES, INSTALL, DEPLOY,
CLAUDE_CODE, connect-coding-agent (the generated TOOL_CATALOG already
said ~26).
- CHANGELOG no longer claims the v1 starter set was usage-derived: it is
the reviewed brain-tool slice + agent lane, re-derivable via
scripts/derive-starter-ops.ts (matches the FOV-6b provenance comment).
- "every MCP response carries _meta.retrieval" scoped to query/search
(the only producers of the retrieval key).
- mcp-surface-runbook gains the mcp.default_surface_dcr operator move
(default for NULL-surface clients, ceiling-bounded, per-request).
- llms bundles regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(ci): add --timeout to the derive-starter-ops printed hint (bun-test guard)
The check-bun-test-timeout guard greps scripts/ for bare `bun test`
invocations and matched the console.log hint this wave's derivation script
prints. CI (GNU grep) enforces the \b word boundary the local BSD grep
silently drops, so the gate only fired on the runner. The hint now models
the convention it exists to teach.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Tutorials
Step-by-step walkthroughs that take you from zero to a working outcome. Concrete commands, real numbers, no abstraction-first jargon. Each tutorial assumes no prior GBrain knowledge.
Shipped
- Set up your personal AI agent + brain from zero — the canonical solo install. Two GitHub repos, a Telegram bot, AlphaClaw on Render, OpenClaw + GBrain + Supabase. End-to-end in about 2 hours; about $100 to $150 a month sustained. The full-stack install I'd run today.
- Set up GBrain as your company brain — federated, multi-user, OAuth-scoped institutional memory for a 10-50 person team. Three sources (shared / customers / internal-only), per-user scope, first synthesized query as a teammate. About 90 minutes end-to-end, about $5 in API calls for the demo, under $100 a month sustained for a 25-person company.
- Auto-improve a skill with
gbrain skillopt— treat aSKILL.mdas the trainable parameter of a frozen agent. Write your first benchmark from scratch (the part everyone gets stuck on), preview the cost, run the optimizer, read accepted vs no_improvement vs aborted, and accept a measurably better skill. About 20 minutes, about $1 in API calls. Reference:../guides/skillopt.md. - Give your coding agent a memory: GBrain + Claude Code / Codex — the two-funnel walkthrough for coding-agent users. Path A: connect Claude Code / Codex to a brain you already run (OpenClaw, Hermes, any
gbrain serve --http). Path B: start from nothing with a 2-second local PGLite brain. Both end with the brain-first protocol you paste intoCLAUDE.md/AGENTS.mdand the four habits (brain-first lookup, ambient capture, briefing-from-your-brain, whoknows) that make it worth it. About 10 minutes.
In progress
These are the next tutorials on the roadmap. Open an issue if one of them is the one you need most; that's how we'll prioritize.
-
Set up GBrain for VC dealflow — the operator's recipe. People pages for founders, companies with typed Facts fence carrying ARR / team-size / runway across dates, meetings auto-ingested, deal pages linking everything. Shows
gbrain whoknows,gbrain find-trajectory, andgbrain founder scorecardon real workflows. -
Migrate your existing vault into GBrain — for Notion / Obsidian / Roam users with a vault that doesn't match GBrain's default layout. Walks through
gbrain schema detect→suggest→review-candidatesso the brain learns your shape instead of forcing you to learn its. -
Index your codebase as a code brain — for developers. Initialize a brain in a code repo, swap to
voyage-code-3for embeddings, usegbrain code-def/gbrain code-refs/gbrain code-callersto navigate the codebase semantically from any MCP-aware editor. -
Run GBrain fully local with Ollama or llama.cpp — for privacy-first deployments. No cloud calls, no API keys, no telemetry. Trades some retrieval quality for full local control. Useful for regulated industries, air-gapped environments, or just paranoia.
-
Set up the dream cycle — the overnight enrichment daemon that makes the brain self-maintaining. Fixes citations, dedupes people pages, surfaces contradictions, generates founder scorecards on the schedule you configure. The piece that turns a static knowledge base into a brain that gets smarter while you sleep.
Want to write one?
Tutorials follow the Diataxis tutorial pattern: learning-oriented, walks a learner from zero to a working result in one session, every step produces a visible change. If you've used GBrain for something interesting and want to write the walkthrough, the existing company-brain.md is the model. Open a PR.
Related documentation
- Reference:
docs/architecture/— system design, topologies, retrieval theory - How-to:
docs/guides/— task-oriented runbooks (sub-agent routing, minion deployment, skill development, brain-first lookup, idea capture, diligence ingestion). Highlight: scaling skills past 300 — the three-tier architecture for agents that have outgrown the always-loaded skill manifest. - Integrations:
docs/integrations/— connecting external data sources (voice, email, calendar, embedding providers) - MCP setup:
docs/mcp/— per-client setup (Claude Desktop, Claude Code, Codex, ChatGPT, Perplexity, Cowork) - Install paths:
docs/INSTALL.md— every install path, end to end - Agent bootstrap:
docs/guides/bootstrap.md— the paste-in path that turns a coding agent into a full agent (identity, per-turn context, schedules, a private repo as its durable body)