2 Commits

Author	SHA1	Message	Date
Garry Tan	488e4824e8	v0.34.1.0 fix(mcp): MCP fix wave — source-isolation P0 + PKCE DCR + federated_read + 3 more (#996) ... * fix(mcp): skip stdin EOF handlers when MCP_STDIO=1 OpenClaw's bundle-mcp gateway and similar wrappers pipe the JSON-RPC handshake on stdin then close their stdin half. Pre-fix, both stdin 'end' and 'close' listeners (server.ts:65-66 and serve.ts:204-206) treated this as a permanent disconnect and shut the server down before the first tool call arrived. Guard both sites with `process.env.MCP_STDIO !== '1'`. Signal handlers (SIGTERM/SIGINT/SIGHUP), transport.onclose, and the parent-process watchdog still cover legitimate shutdown paths. The serve.ts site threads the env read through an injectable `mcpStdio?: boolean` on ServeOptions so tests stay isolated (no process.env mutation per scripts/check-test-isolation.sh R1). Tests: 3 new cases in test/serve-stdio-lifecycle.test.ts pin the guard's invariants — mcpStdio=true must NOT trigger shutdown on stdin EOF, signals must still drive shutdown with mcpStdio=true, and mcpStdio=false (default) preserves existing CLI behavior. 25/25 pass. Origin: PR #870. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(oauth): honor token_endpoint_auth_method=none for PKCE public clients RFC 7591 §3.2.1: when a DCR client declares token_endpoint_auth_method="none" (PKCE-only public clients like Claude Code, Cursor), the authorization server MUST NOT issue a client_secret. Pre-fix, registerClient unconditionally minted a secret, and the MCP SDK's clientAuth middleware then rejected valid public-client flows on /token because it expected client.client_secret to match. Three changes to src/core/oauth-provider.ts:registerClient: - Gate clientSecret generation on isPublicClient = (auth_method === 'none'). Public clients store client_secret_hash = NULL. - Omit client_secret from the response payload for public clients. Confidential clients (default client_secret_post and explicit client_secret_basic) keep their existing one-time-reveal shape. - Normalize NULL secret_hash to JS undefined in getClient so SDK middleware (which checks client.client_secret === undefined, not === null) correctly identifies public clients and skips the secret-comparison branch on /token. Schema is already permissive (client_secret_hash TEXT, no NOT NULL on both src/schema.sql and src/core/pglite-schema.ts) — no migration needed. Tests: 5 new cases in test/oauth.test.ts pin: - public client → no client_secret in response (#11 from plan) - default auth_method → secret unchanged (regression guard) - explicit client_secret_post → secret unchanged - getClient NULL→undefined normalization - PKCE full /authorize → /token end-to-end with no secret (#15 from plan) 69/69 oauth.test.ts cases pass. typecheck clean. Origin: PR #909. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(serve-http): --bind HOST, default to loopback (127.0.0.1) Adds `gbrain serve --http --bind <interface>` to control which network interface the HTTP MCP server listens on. Default flipped from `0.0.0.0` (pre-v0.34) to `127.0.0.1` (v0.34.0+). Why the flip: gbrain's primary use case is a personal-knowledge brain on a laptop. The previous default exposed brains on every interface — one accidental `--http` invocation away from publishing the brain to a LAN. Server operators who need remote access pass `--bind 0.0.0.0` (or a specific interface). Codex's outside-voice on the original PR #864 correctly flagged that the additive flag wasn't actually the fix; the default needed to change for the safety claim to hold. If `--public-url` is set but `--bind` is unset, runServeHttp prints a loud stderr WARN at startup recommending `--bind 0.0.0.0`. Declaring a public URL while quietly binding loopback is almost always a misconfiguration; we want the operator to see it on first start, not silently fail remote requests. Startup banner now includes a `Bind:` row so the listening interface is visible alongside Port / Engine / Issuer. Origin: PR #864, extended with D11 (default flip) per /plan-eng-review codex outside-voice review. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(mcp): seal source-isolation leak on read path (P0) Pre-fix, an authenticated OAuth MCP client scoped to source-A could enumerate source-B pages via six read-side ops: search, query (text AND image paths), list_pages, traverse_graph, and find_experts. The v0.31.8 source-scoping pattern shipped through dispatch.ts but the op handlers never threaded ctx.sourceId into their engine calls, and hybridSearch.ts:223's explicit SearchOpts rebuild dropped sourceId even when callers passed it. Sealing the leak: - src/core/operations.ts adds sourceScopeOpts(ctx), the canonical precedence ladder: ctx.auth.allowedSources (federated) wins over ctx.sourceId (scalar) wins over nothing. Threaded into all 5 read-side op handlers + the query-image-path searchVector call (the 6th leak surface codex caught in plan review). - src/core/search/hybrid.ts:223 now threads sourceId + sourceIds fields through the inner SearchOpts rebuild. The explicit pick shape is preserved (HNSW inner-CTE ordering depends on it) but extended. - src/core/types.ts adds sourceIds?: string[] to SearchOpts + PageFilters (D9: federated read needs array-shaped engine filter or fan-out; array wins for hot retrieval). - src/core/operations.ts AuthInfo gains sourceId + allowedSources (D2: identity surface symmetric with the federated_read column #876 will add). - Both engines now apply WHERE source_id = $N (scalar) or = ANY($N::text[]) (array) at the SQL layer for searchKeyword, searchKeywordChunks, searchVector, listPages, traverseGraph, traversePaths. Array form wins when both are set. The searchVector filter pushes into the inner HNSW CTE (codex flagged this placement during plan review). - traverseGraph + traversePaths signatures gain opts.sourceId + opts.sourceIds; engine.ts interface updated. - findExperts (the whoknows op, D3 5th leak surface) accepts sourceId + sourceIds and threads them into its internal hybridSearch call. PR #861 was authored before v0.33 shipped so this op wasn't covered in the original PR. Auth wiring: - GBrainOAuthProvider.verifyAccessToken populates AuthInfo.sourceId from oauth_clients.source_id. JOIN guarded by isUndefinedColumnError so pre-v55 brains degrade to legacy projection rather than refusing every token verification. - GBrainOAuthProvider.registerClientManual gains a sourceId parameter (defaults to 'default'). DCR registerClient also sets source_id='default' on the inserted row. - serve-http.ts:929 cleanup: AuthInfo.sourceId is now a real typed field. The cast + GBRAIN_SOURCE env fallback chain is gone (D13). Legacy bearer tokens default to 'default' source in verifyAccessToken. - http-transport.ts (legacy access_tokens path) threads sourceId='default' through DispatchOpts so v0.22.7 callers stay source-scoped. - auth.ts CLI adds --source flag to gbrain auth register-client. Migration v55 (D10 + D13): - ALTER TABLE oauth_clients ADD COLUMN source_id TEXT (nullable). - Backfill UPDATE source_id = 'default' WHERE source_id IS NULL — preserves v0.33 effective behavior verbatim for legacy clients. - ADD CONSTRAINT FK ... REFERENCES sources(id) ON DELETE SET NULL, wrapped in DO block so re-runs against fresh-install brains (where the FK already lives inline in SCHEMA_SQL) no-op cleanly. - CREATE INDEX idx_oauth_clients_source_id WHERE source_id IS NOT NULL for the verifyAccessToken JOIN. - GBRAIN_ACCEPT_SILENT_WIDEN env-flag wired through the runner via SET LOCAL gbrain.accept_silent_widen — reserved for future migrations that hit the silent-widen footgun codex flagged. This migration doesn't need it (column is brand new; no pre-existing stale values possible by definition). - src/core/pglite-schema.ts + src/schema.sql include the column + FK + index inline for fresh installs. Tests: new test/e2e/source-isolation-pglite.test.ts with 13 regression cases — one per leak surface (search/list_pages/traverse/etc.) plus explicit AuthInfo.sourceId and AuthInfo.allowedSources op-handler threading checks. Full unit suite: 6034 pass / 0 fail. PGLite initSchema time dropped from 2.4s to 850ms after consolidating v55's DO blocks (multiple DO blocks were slow on PGLite; one DO block for the FK install only is fine). Origin: PR #861 + plan-eng-review decisions D2/D3/D4/D9/D10/D13 + F2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(gateway): multimodal embedding for openai-compatible providers Pre-fix, embedMultimodal hardcoded a recipe.id === 'voyage' branch and threw AIConfigError for every other recipe. Multimodal-capable providers fronted by LiteLLM (or any openai-compatible proxy) were unreachable even when the operator had wired up the model. The fix: - src/core/ai/gateway.ts adds embedMultimodalOpenAICompat() that POSTs to the standard /embeddings endpoint with content arrays carrying image_url entries. Routing comes from the existing recipe.implementation switch — Voyage stays on its own /multimodalembeddings path; every other openai-compatible recipe flows through the new helper. - src/core/ai/recipes/litellm-proxy.ts declares supports_multimodal: true so embedMultimodal accepts the recipe. No multimodal_models allow-list: LiteLLM is a passthrough proxy and the user owns model-id selection; provider rejection (400 from upstream) is the right enforcement layer there. Voyage's static allow-list shape stays unchanged (its 12 models share supports_multimodal but only one is multimodal-capable). - D12 runtime dimension validation: the new helper checks the returned vector length against the recipe's declared default_dims (preferred) or the brain's embedding_dimensions config. Mismatch throws AIConfigError with model id + observed + expected so the operator can swap models or rebuild the column. Pre-fix, a wrong-dim response would surface as a cryptic pgvector "vector dimension mismatch" at INSERT time. - Auth resolution routes through the existing defaultResolveAuth helper so optional-auth recipes (LiteLLM proxy with no LITELLM_API_KEY) and required-auth recipes both share one code path. Optional-auth sends "Authorization: Bearer unauthenticated" which servers like Ollama / llama-server ignore but the SDK contract requires. Tests: 11 new cases in test/openai-compat-multimodal.test.ts cover happy-path, multi-input batching, unauthenticated proxy, D12 dim mismatch + default-dim fallback, 401 / 400 / malformed-JSON / non-array error paths, and an explicit Voyage-regression test pinning that the new openai-compat route doesn't accidentally hijack the Voyage path. All 41 multimodal-related tests pass (existing voyage suite + new). typecheck clean. Origin: PR #875 + plan-eng-review D12 (runtime dim validation). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(oauth): federated_read read scope (#876) Pre-fix, OAuth clients had a single source-scope axis (source_id, added in v55). A client could either write+read one source OR be a super-reader across all sources (via NULL source_id). There was no middle ground — WeCare-style L3 dept clients that need to write to dept-x but read dept-x + parent canon + shared canon had no expression. #876 adds federated_read TEXT[] as an orthogonal read-scope axis. source_id is the WRITE authority; federated_read is the READ authority. They default to matching values (read scope == write scope, the pre-v0.34 default) when a client is registered without an explicit federated read list. Migrations v56-v60 (six new migrations on top of v55): - v56: ALTER TABLE ... ADD COLUMN federated_read TEXT[] NOT NULL DEFAULT '{}'. - v57 (F5): explicit CASE backfill so source_id IS NULL → '{}' (not an array containing NULL — codex caught this ambiguity during plan review). - v58: post-backfill validation. Fails loud if any row's source_id isn't in its federated_read array, pointing at a logic bug in v57 if fired. - v59: flip the source_id FK from ON DELETE SET NULL to ON DELETE RESTRICT now that federated_read provides the alternative scope-loss path. Pre-flip, deleting a source could silently widen any oauth_client to super-reader; post-flip, source delete is refused if any client references it (operator must revoke/re-scope first). - v60: GIN index on federated_read for array-containment queries. Auth wiring: - GBrainOAuthProvider.verifyAccessToken JOINs c.federated_read and populates AuthInfo.allowedSources. Pre-v56 / pre-v55 brains degrade via the existing isUndefinedColumnError fallback chain. - registerClientManual gains a federatedRead?: string[] parameter (defaults to [sourceId]). - DCR registerClient sets source_id='default' + federated_read=['default'] on the inserted row. - auth.ts CLI adds --federated-read SRC1,SRC2,... flag. The register-client output now prints "Federated reads:" so operators confirm the scope they set. Engines consume the federated array through the SearchOpts.sourceIds / PageFilters.sourceIds field that #861 added (no engine changes here — the plumbing was D9). sourceScopeOpts in operations.ts already prefers the auth.allowedSources array over scalar ctx.sourceId when set. Test seam: - test/book-mirror.test.ts now spawns the CLI with GBRAIN_HOME pointed at a tempdir so the test isn't sensitive to the developer's local ~/.gbrain/config.json. Pre-fix the test could silently inherit a real Postgres connection and hang past the default 5s test timeout. Fresh GBRAIN_HOME → "No brain configured" → exit 1 in <1s. - test/e2e/source-isolation-pglite.test.ts gains one more regression case: AuthInfo.allowedSources = [] (explicit empty) MUST NOT widen scope to "all sources" — the silent-widen footgun precedence ladder. - test/openai-compat-multimodal.test.ts is part of the wave's commits via the migrate.ts changes that bump the schema chain. typecheck-only fix on a captured-auth type was already in #875's tree. 6045 unit tests pass / 0 fail. typecheck clean. PGLite initSchema runs v55-v60 in ~786ms total (within the test-harness budget for tests using the canonical beforeAll engine pattern). Origin: PR #876 + plan-eng-review F5 (CASE backfill). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.34.0.0: MCP fix wave (#870 #909 #864 #861 #875 #876) VERSION + package.json + CHANGELOG bump for the six-PR MCP fix wave. Schema chain extends from v54 → v60; oauth_clients gains source_id + federated_read columns; auth'd MCP clients now stay inside their scope across all read-side ops; PKCE-only DCR works; --bind defaults to loopback; LiteLLM multimodal embedding ships. Contributed by @Hansen1018 (#870), @ding-modding (#909), @DukeDawg (#864), @toilalesondev (#861 + #876), @yoelgal (#875). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update project documentation for v0.34.0.0 Sync README, CLAUDE.md, SECURITY.md, docs/architecture/topologies.md, and docs/mcp/DEPLOY.md to reflect the v0.34.0.0 MCP fix wave: - README: document --bind HOST default (loopback), --source + --federated-read register-client flags, PKCE public-client gate - SECURITY.md: note loopback-by-default for serve --http, update the trust-proxy contract to point at the new default - CLAUDE.md: annotate operations.ts (sourceScopeOpts helper), oauth-provider.ts (verifyAccessToken JOIN + PKCE public clients), serve-http.ts (--bind flag), gateway.ts (openai-compat multimodal + dim validation), mcp/server.ts (MCP_STDIO guard), auth.ts (--source + --federated-read), migrate.ts (v58-v63 chain), engine.ts (sourceIds field). Add 4 new test-file entries for source-isolation-pglite, openai-compat-multimodal, serve-stdio-lifecycle, oauth.test.ts PKCE cases - docs/architecture/topologies.md: source-scoped register-client example, --bind 0.0.0.0 for thin-client host setup - docs/mcp/DEPLOY.md: --bind explanation in the ngrok section, source-scoped client recipe - llms-full.txt: regenerated per the CLAUDE.md-edit chaser rule Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump v0.34.0.0 → v0.34.1.0 Renumbering the MCP fix wave from v0.34.0.0 to v0.34.1.0 so the release slot lands between master's v0.33.2.1 and the next minor. Touches every release-artifact mention: - VERSION: 0.34.0.0 → 0.34.1.0 - package.json: same - CHANGELOG.md header + "To take advantage" block - CLAUDE.md key-files annotations (8 entries that document this wave) - llms-full.txt (regen from CLAUDE.md) - README.md / SECURITY.md / docs/architecture/topologies.md / docs/mcp/DEPLOY.md - Wave code-comment markers ("// v0.34.0 (#NNN):" → "// v0.34.1 (#NNN):") Test files renamed alongside since they were committed with the wave. Commit subjects on the original 6 PR commits + the v0.34.0.0 bump commit (4f533c72 → 6b47db7e) intentionally NOT rewritten — those are history. `git log` finds the implementation by message subject, not by version tag. 6275 unit tests pass, typecheck clean, migration chain v58-v63 unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-14 20:15:29 -07:00
Garry Tan	8392d434a9	v0.29.2 feat: thin-client mode (gbrain init --mcp-only + gbrain remote ping/doctor + topologies) (#732) ... * feat(config): add remote_mcp field + isThinClient() helper Adds a top-level optional remote_mcp config block to GBrainConfig (issuer_url, mcp_url, oauth_client_id, oauth_client_secret) for thin-client installs that consume a remote `gbrain serve --http` over MCP instead of running a local engine. isThinClient(config) returns true when remote_mcp is set; used by the CLI dispatch guard, doctor branch, and init re-run guard. The engine field stays as today (postgres|pglite); thin-client mode is a separate config field, NOT an engine kind extension (codex outside-voice review flagged the engine='remote' extension as overreach). GBRAIN_REMOTE_CLIENT_SECRET env var overrides the config-file value at load time so the secret can stay out of disk for headless agents. Foundation commit for multi-topology v1; no behavior change yet. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(probe): outbound OAuth + MCP smoke probes Adds three pure async functions over the standard fetch API: - discoverOAuth(issuerUrl): GET /.well-known/oauth-authorization-server - mintClientCredentialsToken(tokenEndpoint, id, secret): POST /token - smokeTestMcp(mcpUrl, accessToken): POST /mcp initialize Discriminated 'ok=true' / 'ok=false + reason' return shapes so callers render error messages consistently. No SDK dependency to keep init's setup-flow scope tight; Lane B's mcp-client.ts will pull in the official @modelcontextprotocol/sdk Client for full session semantics. Used by both 'gbrain init --mcp-only' (Lane A's setup smoke) and runRemoteDoctor (Lane A's thin-client doctor checks). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(init): --mcp-only branch + re-run guard Adds 'gbrain init --mcp-only' for thin-client setup. Required flags (or env vars): --issuer-url OAuth root (e.g. https://host:3001) --mcp-url MCP tool dispatch path (e.g. https://host:3001/mcp) --oauth-client-id, --oauth-client-secret Pre-flight runs three smoke probes (discovery, token round-trip, MCP initialize) BEFORE writing the config — fail-fast on bad URL beats fail-late on bad credentials. On success, writes ~/.gbrain/config.json with remote_mcp set and NO local DB created. Re-run guard (A8): when ~/.gbrain/config.json already has remote_mcp, 'gbrain init' (any flag set) refuses without --force. Catches the scripted-setup-loop friction from the user-reported scenario where re-running setup-gbrain on a thin-client machine kept trying to re-create a local DB. Two URLs in config (issuer + mcp) instead of one because OAuth discovery + /token live at the issuer root while tool dispatch is at /mcp — they compose from a common base in practice but reverse-proxy setups need them explicit (codex review #2). Tests: 15 cases covering happy path, env-var-supplied secret stays out of disk, all four required-flag missing-error paths, three smoke-failure paths, network-unreachable path, and the four re-run guard variants (default/--pglite/--mcp-only without --force / with --force). Uses async Bun.spawn (NOT execFileSync) — sync exec deadlocks against in-process HTTP fixtures because the parent's event loop can't accept connections while sync-blocked on a child. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(doctor): runRemoteDoctor for thin-client mode Replaces every DB-bound check from runDoctor() with a tighter set scoped to 'is the remote MCP we configured actually reachable?'. Five checks: - config_integrity (URL fields well-formed) - oauth_credentials (secret resolvable from env or config file) - oauth_discovery (GET /.well-known/oauth-authorization-server) - oauth_token (POST /token client_credentials) - mcp_smoke (POST /mcp initialize) Output shape matches the local doctor's Check surface so JSON consumers can union the two without conditional logic. schema_version is 2 (matches local doctor). collectRemoteDoctorReport() is the pure data collector; runRemoteDoctor() is the print/exit wrapper. Tests pin the data collector so we don't have to intercept stdout / process.exit. Tests: 12 cases over a tiny in-process HTTP fixture covering happy path, every probe failure mode (404/parse/auth/network/server-error), malformed-URL config integrity, missing-secret short-circuit, and the env-var-overrides-config-file secret resolution. withEnv() helper used for env mutations to satisfy the test-isolation lint. Module is added but not yet wired into the CLI doctor branch; the wiring lands in the next commit (cli dispatch guard + doctor routing). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cli): thin-client dispatch guard + doctor routing Adds a single canonical refusal at the top of handleCliOnly() for the 9 DB-bound commands when ~/.gbrain/config.json has remote_mcp set: sync, embed, extract, migrate, apply-migrations, repair-jsonb, orphans, integrity, serve Single dispatch check (not 9 sprinkled assertLocalEngine calls per codex review #1) — avoids the blast radius of letting commands enter connectEngine before the check fires. Refused commands exit 1 with a canonical error naming the remote mcp_url. doctor branch routes to runRemoteDoctor when isThinClient(config) returns true; falls through to the existing local-doctor flow otherwise. Wires the module added in the previous commit into the user-facing CLI surface. Safe commands (init, auth, --version, --help, etc.) still work in thin-client mode and are NOT in the refused set. Tests: 14 cases — 9 refused commands × 1 each, 2 safe commands, 1 doctor-routing assertion (fingerprints the thin-client output by 'mode:"thin-client"' in JSON), 2 regression tests asserting local config still passes through normally. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(topologies): multi-topology architecture guide + setup skill Phase A.5 New docs/architecture/topologies.md covering three deployment shapes: 1. Single brain (today's default) 2. Cross-machine thin client (consume a remote brain over MCP) 3. Split-engine per-worktree (Conductor users with per-worktree code engines + shared remote artifacts brain) Each topology gets an ASCII diagram, when-it-fits guidance, and concrete setup recipes. Topology 3's alias-level routing footgun (wrong alias = silent wrong-brain writes) is called out explicitly per codex review #6. Topology 3 needs zero gbrain code changes — GBRAIN_HOME already overrides ~/.gbrain and 'gbrain serve --http --port N' already runs on any port. gstack composes these primitives on its side. skills/setup/SKILL.md gets Phase A.5 BEFORE the local-engine phases. Asks the user which topology fits, walks thin-client setup through 'gbrain init --mcp-only', skips Phases B/C/C.5/H entirely for thin clients (host's autopilot handles sync/extract/embed). README.md gets a one-line link to the topology doc from the Architecture section. llms-full.txt regenerated to include the new doc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(e2e): thin-client end-to-end skeleton Spins up 'gbrain serve --http' against real Postgres, registers a client with read,write,admin scope, runs 'gbrain init --mcp-only' from a separate tempdir GBRAIN_HOME, exercises the canonical thin-client flows: - init --mcp-only succeeds against the live host - doctor reports mode: thin-client + all checks green - sync is refused with the canonical thin-client error - re-running init refuses without --force Tier B flows (gbrain remote ping / doctor) will be added alongside their Lane B implementation. Skips when DATABASE_URL unset (matches the e2e gate convention used across the suite). Async Bun.spawn (NOT execFileSync) so the test event loop stays responsive — execFileSync deadlocks against in-process HTTP fixtures because the parent's event loop can't accept connections while sync-blocked on a child process. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(doctor): doctorReportRemote core for thin-client + run_doctor op Adds three new exports to src/commands/doctor.ts that the run_doctor MCP op + gbrain remote doctor CLI both consume: - DoctorReport interface schema_version=2 stable shape - computeDoctorReport(checks) status + health_score math - doctorReportRemote(engine) focused 5-check thin-client surface doctorReportRemote runs: 1. connection (engine reachable + page count via getStats) 2. schema_version (engine.getConfig('version') vs LATEST_VERSION) 3. brain_score (the 5-component composite) 4. sync_failures (file-plane JSONL count from gbrainPath('sync-failures.jsonl')) 5. queue_health (Postgres-only: stalled active jobs > 1h) Engine-agnostic: works on both Postgres and PGLite via engine.executeRaw + engine.getConfig + engine.getHealth — no reliance on db.getConnection() which is Postgres-only. Deliberately a focused subset of the local doctor surface, NOT a full mirror. Generalizing to lint/integrity/orphans is filed as follow-up pending demand. Local doctor (runDoctor) is unchanged; operators on the host machine still get the full check set. schema_version=2 matches the local doctor's --json output schema, so JSON consumers can union the two without conditional logic. Tests: 11 unit cases against PGLite covering the 5-check happy path, schema version reporting (latest), PGLite-specific queue_health informational message, and the score+status math via computeDoctorReport. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(mcp-client): outbound HTTP MCP client over @modelcontextprotocol/sdk New src/core/mcp-client.ts wraps the official SDK's Client + StreamableHTTPClientTransport with OAuth client_credentials minting, in-process token caching with expires_at, and refresh-on-401 retry. Public surface: - callRemoteTool(config, toolName, args) tool call w/ auto-refresh - unpackToolResult(res) parse content[0].text JSON - RemoteMcpError discriminated by `reason` Token cache: module-level Map keyed by mcp_url. CLI processes are short-lived; the cache amortizes when one invocation makes multiple calls (gbrain remote ping submits then polls). Persisting to disk would be a credential-on-disk surface for marginal benefit since /token round-trip is sub-100ms. 401 retry: ONLY for mid-session token rotation (initial good token → stale → 401). If the FIRST mint fails auth, surface immediately as RemoteMcpError(auth) — retry won't help when credentials are wrong from the start. If a fresh-mint-after-401 still 401s, surface as RemoteMcpError(auth_after_refresh) which the CLI renders with a hint pointing the operator at gbrain auth register-client. Used by gbrain remote ping (submit_job + get_job poll) and gbrain remote doctor (run_doctor). Test-only _clearMcpClientTokenCache export for fixture isolation. Tests: 13 unit cases over an in-process HTTP fixture mimicking gbrain serve --http (OAuth discovery + /token + /mcp JSON-RPC handshake). Covers happy path, token cache reuse + force-refresh, args passthrough, config-error paths (no remote_mcp / no secret), token mint 401, network unreachable, tool isError envelope, and unpackToolResult parse failures. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(operations): add run_doctor MCP op (admin scope, HTTP-reachable) New op in src/core/operations.ts wraps doctorReportRemote() and returns the structured DoctorReport JSON over MCP. scope: 'admin' (system-state read; not for routine consumers) localOnly: false (reachable over HTTP) mutating: false (safe to call repeatedly) params: {} (no caller arguments needed) First read-only diagnostic op exposed over HTTP MCP. Used by gbrain remote doctor — the matching client-side renderer lives in src/commands/remote.ts. Precedent: doctor only. Generalizing run_lint / run_integrity / run_orphans to MCP is filed as follow-up work pending demand. Local doctor stays unchanged; this op is the operator-friendly subset for remote callers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(remote): gbrain remote ping + gbrain remote doctor Two thin-client convenience commands that round-trip through the host's HTTP MCP endpoint: - gbrain remote ping submit_job(autopilot-cycle) → poll get_job → exit when terminal. The "I just wrote markdown, tell the host to re-index" affordance. - gbrain remote doctor run_doctor MCP op → render the host's DoctorReport → exit 0/1 based on status. Both require a thin-client install (~/.gbrain/config.json with remote_mcp). Local installs get a clear error pointing at the local equivalents. Polling backoff (ping): 1s × 30s, then 5s × 5min, then 10s. Default cap 15min, configurable via `--timeout`. Without backoff, a 5-min cycle would burn 300 round-trips against the host's rate limiter. Payload uses `data: {phases: [...]}`, NOT `params:` — the submit_job op shape takes `data`. Codex review #8 catch. NO `repo` arg passed to autopilot-cycle — uses the server's configured brain repo. This sidesteps TODO #1144 (sync_brain repo-path validation for caller-controlled paths) entirely. src/cli.ts wires the `remote` subcommand into CLI_ONLY + the dispatch. Help (`gbrain remote --help`) and unknown-subcommand handling included. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(e2e): thin-client Tier B + scope-mismatch regression Extends the existing test/e2e/thin-client.test.ts with three new cases: 1. gbrain remote doctor returns the host's DoctorReport — pins the run_doctor MCP op round-trip. Asserts schema_version=2, all 5 check names present, connection + schema_version ok against a fresh host. 2. gbrain remote ping triggers autopilot-cycle and returns terminal state — pins the submit_job → poll → terminal wire path. Accepts any terminal state (success / failed / dead / cancelled / timeout) because autopilot on an empty no-repo brain may fail-fast in the sync phase. What this test pins is the JSON shape (job_id present, state populated), NOT cycle success on a no-repo fixture. 3. read+write client cannot call run_doctor — codex review #7 regression guard. Registers a separate client with `--scopes "read write"` (no admin), runs `gbrain remote doctor` against it, asserts exit 1 with auth/auth_after_refresh/tool_error reason. Keeps the verification flow honest: the canonical setup MUST require admin scope. `gbrain auth register-client` doesn't have --json, so the test parses the human output for "Client ID:" and "Client Secret:" lines via a helper. Test-level timeout bumped 60s → 120s for the ping wait + auth/init overhead. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.29.2) v0.29.2 ships thin-client mode: gbrain init --mcp-only, gbrain remote ping/doctor, run_doctor MCP op, and the docs/architecture/topologies.md deployment guide. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-07 22:56:22 -07:00