@agentproto/adapter-knowledge-gbrain-doc 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,93 @@
+# @agentproto/adapter-knowledge-gbrain-doc
+
+The **document-retrieval** backing for the
+[`@agentproto/knowledge-engine`](../../packages/knowledge-engine)
+`IKnowledgeProvider` contract.
+
+Implements the ingest/query contract over a **gbrain** server's document API —
+`put_page` (ingest) + `search` (query) — reached over its JSON-RPC `/mcp`
+endpoint via pure `fetch` (no vendor SDK). gbrain fuses **lexical (tsvector) +
+semantic** recall, so a query stamps `modeUsed: "hybrid"`.
+
+The document-retrieval sibling of
+[`@agentproto/adapter-knowledge-files`](../knowledge-files) (BM25),
+[`@agentproto/adapter-knowledge-corpus`](../knowledge-corpus) (AIP-10
+composition), and
+[`@agentproto/adapter-knowledge-qdrant`](../knowledge-qdrant) (vector).
+
+> **Distinct from the code-graph gbrain adapter.**
+> [`@agentproto/adapter-code-brain-gbrain`](../code-brain-gbrain) is the
+> **code-graph** gbrain adapter (`ICodeBrainProvider`: define / callers /
+> callees). **This** package is the **knowledge-document** one
+> (`IKnowledgeProvider` over gbrain's document store). Same backend, different
+> contract — they never share a package edge; gbrain is reached only at runtime
+> over HTTP.
+
+> **No studio edge.** Lifted from a studio provider whose only cross-package
+> import was a type-only import of `JsonRpcRequest` / `JsonRpcResponse` from the
+> studio `core/protocol` package. That edge is replaced by two inline JSON-RPC
+> interfaces — no studio dependency survives.
+
+## What's in the box
+
+| Export | Role |
+| --- | --- |
+| `GbrainDocKnowledgeAdapter` | The `IKnowledgeProvider` implementation. Config-driven — consumes a plain `GbrainDocAdapterConfig`; knows nothing about `process.env`. |
+| `GbrainDocAdapterConfigSchema` / `parseGbrainDocAdapterConfig` | The zod config contract (endpoint, bearer token, timeout). |
+| `extractJsonRpcPayload` | Pulls the JSON-RPC envelope out of a gbrain Streamable-HTTP (SSE) response body (exported for testing). |
+| `loadGbrainDocKnowledgeEnv` / `gbrainDocEnvToConfig` | The typed env module — the ONE place `GBRAIN_*` is read. |
+| `createStandaloneGbrainDocAdapter()` | Wires the typed env into a ready-to-use adapter. |
+| provider-kit family (`KNOWLEDGE_GBRAIN_DOC_CATALOG`, `makeKnowledgeGbrainDocResolver`, `resolveKnowledgeBackend`) | Registers the `gbrain-doc` backend under the `@agentproto/adapter-knowledge-*` discovery convention. |
+
+## Environment
+
+| Var | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `GBRAIN_BEARER_TOKEN` | ✅ | — | Machine bearer token accepted by the gbrain `/mcp` endpoint (OAuth 2.1 client_credentials). Shared with the code-graph gbrain adapter's HTTP backend by design. |
+| `GBRAIN_ENDPOINT` | | `http://127.0.0.1:3132` | gbrain HTTP base URL (the `/mcp` endpoint is appended). |
+| `GBRAIN_HTTP_TIMEOUT_MS` | | `45000` | Per-request timeout (ms). |
+
+## Usage
+
+```ts
+import {
+  GbrainDocKnowledgeAdapter,
+  createStandaloneGbrainDocAdapter,
+} from "@agentproto/adapter-knowledge-gbrain-doc"
+
+// From the ambient GBRAIN_* env:
+const kb = createStandaloneGbrainDocAdapter()
+
+// Or construct directly (e.g. a host resolving a per-KB config + vault secret):
+const direct = new GbrainDocKnowledgeAdapter({
+  endpoint: "http://127.0.0.1:3132",
+  bearerToken: process.env.GBRAIN_BEARER_TOKEN!,
+})
+
+await kb.ingest({ kind: "text", uri: "doc://intro", title: "Intro", content: "…" })
+const { hits } = await kb.query({ query: "how do I ship", topK: 5 })
+```
+
+## Scope
+
+Supported: `ingest` (`put_page` a markdown doc), `query` (`search` — stamps
+`modeUsed: "hybrid"`; `minScore` is applied client-side since gbrain `search`
+has no server-side score floor), `listSources` / `getSource` / `deleteSource`
+(via `list_pages` / `get_page` / `delete_page`), `healthCheck` (`GET /health`).
+
+## Testing
+
+Unit tests run against a mocked `globalThis.fetch` returning canned gbrain
+Streamable-HTTP (SSE) frames — **no live gbrain** (CI-safe). They assert the
+`put_page` / `search` request shapes and the result mapping into
+`KnowledgeSource` / `KnowledgeHit`. A guarded live e2e (`put_page` → `search`
+against a running gbrain) runs only when the container is reachable, mirroring
+the code-brain gbrain adapter's guarded e2e.
+
+```sh
+pnpm --filter @agentproto/adapter-knowledge-gbrain-doc test
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+import { KnowledgeCapabilities, IKnowledgeProvider, KnowledgeIngestInput, KnowledgeSource, KnowledgeQuery, KnowledgeQueryResult, ListSourcesFilter } from '@agentproto/knowledge-engine';
+import { AdapterCatalog, AdapterHandle, AdapterResolver } from '@agentproto/provider-kit';
+
+/**
+ * GbrainDocKnowledgeAdapter — the `IKnowledgeProvider` over gbrain's DOCUMENT
+ * API.
+ *
+ * Connects the `@agentproto/knowledge-engine` `IKnowledgeProvider` contract to a
+ * gbrain server's document surface, reached over its JSON-RPC MCP endpoint
+ * (`POST /mcp`, bearer-authenticated) via pure `fetch` — no vendor SDK. The two
+ * load-bearing tools are `put_page` (ingest) and `search` (query); the
+ * lifecycle verbs (`list_pages` / `get_page` / `delete_page`) round out the
+ * contract. Lets a host plug "my own gbrain" as a first-class knowledge engine
+ * alongside the files / corpus / qdrant backends.
+ *
+ * DISTINCT from `@agentproto/adapter-code-brain-gbrain`: that adapter is the
+ * CODE-GRAPH one (`ICodeBrainProvider`: define / callers / callees). THIS one is
+ * the KNOWLEDGE-DOC one (`IKnowledgeProvider` over gbrain's document store).
+ * Same backend, different contract — they never share a package edge; gbrain is
+ * reached only at runtime over HTTP.
+ *
+ * Lifted from the studio integration package
+ * (`packages/integration/knowledge/src/providers/gbrain-knowledge.adapter.ts`).
+ * Changes on the lift:
+ *   1. The contract + data types now come from `@agentproto/knowledge-engine`
+ *      (was the studio `../base-knowledge.provider` / `../../types`).
+ *   2. The ONE cross-package edge — a type-only import of `JsonRpcRequest` /
+ *      `JsonRpcResponse` from the studio `core/protocol` package
+ *      (`gbrain-knowledge.adapter.ts:23`) — is replaced by the two inline
+ *      interfaces below. No studio dependency survives.
+ *   3. The wire shapes are typed against the LIVE gbrain doc API (probed at
+ *      build time), which drifts from the studio original:
+ *        - `put_page` args are `{ slug, content }` (studio sent a `source`
+ *          field; gbrain's real field is the server-stamped `source_uri`).
+ *        - `search` args are `{ query, limit, offset }` (studio sent a
+ *          `min_score` gbrain doesn't accept — `minScore` is applied
+ *          client-side here instead).
+ *        - a `search` hit carries `chunk_text` / `score` / `chunk_index`
+ *          (studio expected `snippet` / `rerank_score`).
+ *      Every response is zod-parsed — nothing untyped reaches a call site.
+ *
+ * Scope of this adapter:
+ *   - `ingest({ kind, uri, title?, content })` — `put_page` a markdown doc
+ *   - `query({ query, topK, minScore })` — `search` (gbrain fuses lexical +
+ *     semantic recall, so `modeUsed` is stamped `"hybrid"`)
+ *   - `listSources()` / `getSource(id)` / `deleteSource(id)` — via
+ *     `list_pages` / `get_page` / `delete_page`
+ *   - `healthCheck()` — `GET /health` returns OK
+ */
+
+declare const GBRAIN_DOC_ENGINE_ID: "gbrain-doc";
+declare const GbrainDocAdapterConfigSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    bearerToken: z.ZodString;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GbrainDocAdapterConfig = z.infer<typeof GbrainDocAdapterConfigSchema>;
+declare function parseGbrainDocAdapterConfig(raw: Readonly<Record<string, unknown>>): GbrainDocAdapterConfig;
+declare const GBRAIN_DOC_CAPABILITIES: KnowledgeCapabilities;
+declare class GbrainDocKnowledgeAdapter implements IKnowledgeProvider {
+    readonly id: "gbrain-doc";
+    readonly capabilities: KnowledgeCapabilities;
+    private readonly endpoint;
+    private readonly bearerToken;
+    private readonly timeoutMs;
+    private readonly label?;
+    private rpcCounter;
+    constructor(config: GbrainDocAdapterConfig);
+    ingest(input: KnowledgeIngestInput): Promise<KnowledgeSource>;
+    query(q: KnowledgeQuery): Promise<KnowledgeQueryResult>;
+    listSources(filter?: ListSourcesFilter): Promise<readonly KnowledgeSource[]>;
+    getSource(id: string): Promise<KnowledgeSource | null>;
+    deleteSource(id: string): Promise<void>;
+    healthCheck(): Promise<boolean>;
+    dispose(): Promise<void>;
+    private authHeaders;
+    private nextRpcId;
+    /** Issue one MCP `tools/call` and return the parsed result envelope. Throws a
+     *  labelled error when gbrain sets `isError` (e.g. page-not-found). */
+    private callTool;
+    private rpcCall;
+    private errPrefix;
+}
+/** Construct a {@link GbrainDocKnowledgeAdapter} from a validated config. */
+declare function gbrainDocKnowledgeAdapter(config: GbrainDocAdapterConfig): GbrainDocKnowledgeAdapter;
+/**
+ * Extract the JSON-RPC envelope from a Streamable-HTTP response body. gbrain
+ * replies with SSE frames (`event: message\ndata: {…}`); the last non-empty
+ * `data:` line carries the JSON-RPC payload. A plain-JSON body (no SSE framing)
+ * is returned whole.
+ */
+declare function extractJsonRpcPayload(body: string): string;
+
+/**
+ * Standalone wiring for {@link GbrainDocKnowledgeAdapter}.
+ *
+ * The adapter class itself is config-driven: it consumes a plain
+ * {@link GbrainDocAdapterConfig} and knows nothing about `process.env`. This
+ * module is the ONE place that binds it to the ambient environment — it reads
+ * the typed `GBRAIN_*` env (via {@link loadGbrainDocKnowledgeEnv}) and
+ * constructs an adapter from it, exactly the role the code-brain adapter's
+ * provider factories play for their backends. Hosts that already hold a config
+ * (e.g. a studio guild host resolving a per-KB `configRef` + vault secrets)
+ * should construct `GbrainDocKnowledgeAdapter` directly and skip this factory.
+ */
+
+/**
+ * Build a {@link GbrainDocKnowledgeAdapter} from the ambient `GBRAIN_*` env.
+ * Throws (via {@link loadGbrainDocKnowledgeEnv}) when `GBRAIN_BEARER_TOKEN` is
+ * absent. Each call returns a fresh adapter — the adapter holds no warm state
+ * (stateless JSON-RPC over HTTP), so sharing an instance is a convenience, not
+ * a requirement.
+ */
+declare function createStandaloneGbrainDocAdapter(): GbrainDocKnowledgeAdapter;
+
+/**
+ * Typed environment module for the gbrain-doc knowledge adapter.
+ *
+ * Every `process.env` read in this package flows through here — no raw
+ * `process.env.X` at a call site (mirrors the code-brain + files + corpus +
+ * qdrant adapters' `env.ts`). The loader parses the ambient env into a typed,
+ * validated config once, so the rest of the adapter is a pure function of its
+ * inputs. This is the ONE place the gbrain-flavoured env names (`GBRAIN_*`)
+ * live, keeping the backend idiom confined to the adapter.
+ *
+ * `GBRAIN_BEARER_TOKEN` is shared with `@agentproto/adapter-code-brain-gbrain`'s
+ * HTTP backend by design — same gbrain server, same machine token — but the two
+ * adapters never share a package edge; the token only ever meets gbrain at
+ * runtime over HTTP.
+ */
+
+/** Config for the standalone gbrain-doc backend — a gbrain HTTP endpoint + a
+ *  machine bearer token. */
+interface GbrainDocKnowledgeEnv {
+    /** gbrain HTTP base URL (`GBRAIN_ENDPOINT`); the `/mcp` JSON-RPC endpoint is
+     *  appended. Default `"http://127.0.0.1:3132"`. */
+    readonly endpoint: string;
+    /** Machine bearer token (`GBRAIN_BEARER_TOKEN`). Required — the `/mcp`
+     *  endpoint is bearer-protected. */
+    readonly bearerToken: string;
+    /** Per-request timeout (ms) (`GBRAIN_HTTP_TIMEOUT_MS`). Default 45_000. */
+    readonly timeoutMs: number;
+}
+/**
+ * Load {@link GbrainDocKnowledgeEnv} from `process.env` with defaults.
+ *
+ * Throws when `GBRAIN_BEARER_TOKEN` is absent — the adapter cannot authenticate
+ * to the `/mcp` endpoint without it, and failing at construction time is
+ * clearer than a 401 on the first call.
+ */
+declare function loadGbrainDocKnowledgeEnv(): GbrainDocKnowledgeEnv;
+/** Project the typed env into a {@link GbrainDocAdapterConfig}. */
+declare function gbrainDocEnvToConfig(env: GbrainDocKnowledgeEnv): GbrainDocAdapterConfig;
+
+/**
+ * Family key used for the knowledge backend creds/ledger store path.
+ *
+ * The gbrain-doc engine is the document-retrieval sibling of the `files`
+ * (BM25), `corpus` (AIP-10 composition), and `qdrant` (vector) backends — same
+ * `knowledge` family, so all four surface through the same provider-kit
+ * discovery convention (`@agentproto/adapter-knowledge-*`).
+ */
+declare const KNOWLEDGE_FAMILY: "knowledge";
+/** The single backend slug this adapter provides. */
+declare const GBRAIN_DOC_SLUG: "gbrain-doc";
+/**
+ * Static catalog of knowledge backends shipped by this adapter. The `gbrain-doc`
+ * slug resolves from THIS package (`@agentproto/adapter-knowledge-gbrain-doc`) —
+ * document retrieval over a gbrain server's `put_page` / `search` API, reached
+ * over its JSON-RPC `/mcp` endpoint via pure `fetch` (no vendor SDK). Needs a
+ * gbrain endpoint + a machine bearer token, so it requires a setup pass.
+ *
+ * DISTINCT from `@agentproto/adapter-code-brain-gbrain` (the code-graph gbrain
+ * adapter) — same backend, different contract, no shared package edge.
+ */
+declare const KNOWLEDGE_GBRAIN_DOC_CATALOG: AdapterCatalog;
+
+/**
+ * provider-kit family wiring for the gbrain-doc knowledge backend.
+ *
+ * The studio home-grown `createEngineRegistry`-based knowledge registry is NOT
+ * ported (it was the guild resolution layer, which stays studio-side per the
+ * Ph4 plan — the studio gbrain `descriptor` recursively resolves per-KB config
+ * + reveals the vault bearer through that registry, and the retired E2B/sandbox
+ * provisioning path stays studio-side too). Instead the gbrain-doc backend
+ * registers as a provider-kit family (`TInfo = KnowledgeGbrainDocInfo`, `THandle
+ * = KnowledgeHandle extends AdapterHandle`), reusing the exact consumer shape
+ * the code-brain + files + corpus + qdrant adapters established — catalog +
+ * resolver + a safe `info()` descriptor that NEVER carries a secret. Discovery
+ * flows through the kit's `@agentproto/adapter-knowledge-*` naming convention.
+ *
+ * gbrain-doc needs a gbrain endpoint + a bearer token, so `requiresSetup` /
+ * `authRequired` are both true and `provider()` (via
+ * {@link createStandaloneGbrainDocAdapter}) throws when `GBRAIN_BEARER_TOKEN` is
+ * absent.
+ */
+
+/** Safe descriptor for a knowledge backend — NEVER carries a secret. */
+interface KnowledgeGbrainDocInfo {
+    readonly slug: string;
+    /** The retrieval engine this backend uses. */
+    readonly engine: "gbrain-doc";
+    readonly capabilities: {
+        /** True — gbrain fuses lexical + semantic document retrieval. */
+        readonly hybridSearch: boolean;
+        /** True — gbrain-doc needs a gbrain endpoint + a machine bearer token. */
+        readonly needsCreds: boolean;
+    };
+}
+/** A resolved knowledge backend handle. */
+interface KnowledgeHandle extends AdapterHandle {
+    /** Safe descriptor — NEVER a secret. */
+    info(): KnowledgeGbrainDocInfo;
+    /**
+     * Build the live {@link IKnowledgeProvider} from the ambient `GBRAIN_*` env.
+     * Throws when `GBRAIN_BEARER_TOKEN` is absent — construction-time failure is
+     * clearer than a 401 on the first query.
+     */
+    provider(): IKnowledgeProvider;
+}
+/**
+ * Resolve a catalog slug to a concrete knowledge handle. Throws for unknown
+ * slugs so the kit's resolver wrapper folds the miss to `null`. `provider()` is
+ * lazy — the `GBRAIN_BEARER_TOKEN` requirement is enforced only when a provider
+ * is actually built, not at resolution time.
+ */
+declare function resolveKnowledgeBackend(slug: string): KnowledgeHandle;
+/**
+ * Build the knowledge resolver: resolves a catalog slug to a handle, returning
+ * `null` when the slug is unknown (via the kit's wrapper).
+ */
+declare function makeKnowledgeGbrainDocResolver(): AdapterResolver<KnowledgeHandle>;
+
+export { GBRAIN_DOC_CAPABILITIES, GBRAIN_DOC_ENGINE_ID, GBRAIN_DOC_SLUG, type GbrainDocAdapterConfig, GbrainDocAdapterConfigSchema, GbrainDocKnowledgeAdapter, type GbrainDocKnowledgeEnv, KNOWLEDGE_FAMILY, KNOWLEDGE_GBRAIN_DOC_CATALOG, type KnowledgeGbrainDocInfo, type KnowledgeHandle, createStandaloneGbrainDocAdapter, extractJsonRpcPayload, gbrainDocEnvToConfig, gbrainDocKnowledgeAdapter, loadGbrainDocKnowledgeEnv, makeKnowledgeGbrainDocResolver, parseGbrainDocAdapterConfig, resolveKnowledgeBackend };

package/dist/index.mjs

@@ -0,0 +1,463 @@
+import { z } from 'zod';
+import { makeAdapterResolver } from '@agentproto/provider-kit';
+
+/**
+ * @agentproto/adapter-knowledge-gbrain-doc v0.1.0
+ * IKnowledgeProvider over a gbrain server's document API (put_page / search)
+ * via pure fetch over its JSON-RPC /mcp endpoint, with a provider-kit family.
+ */
+
+var GBRAIN_DOC_ENGINE_ID = "gbrain-doc";
+var GbrainDocAdapterConfigSchema = z.object({
+  /** Base URL of the gbrain HTTP server (no trailing slash needed). The
+   *  JSON-RPC `/mcp` endpoint is appended. */
+  endpoint: z.string().url(),
+  /** Machine bearer token accepted by the gbrain server (`GBRAIN_BEARER_TOKEN`).
+   *  Required — the `/mcp` endpoint is OAuth 2.1 / bearer-protected. */
+  bearerToken: z.string().min(1),
+  /** Per-request timeout (ms). Default 45_000. */
+  timeoutMs: z.number().int().positive().default(45e3),
+  /** Optional human label for logs. */
+  label: z.string().optional()
+});
+function parseGbrainDocAdapterConfig(raw) {
+  return GbrainDocAdapterConfigSchema.parse(raw);
+}
+var GBRAIN_DOC_CAPABILITIES = Object.freeze({
+  // gbrain `search` fuses lexical (tsvector) + semantic recall, so both the
+  // vector + hybrid flags are honest.
+  vectorSearch: true,
+  hybridSearch: true,
+  // This adapter drives the DOCUMENT surface (put_page / search); it does NOT
+  // reach gbrain's graph traversal (`traverse_graph` / `query`).
+  graphTraversal: false,
+  multiModal: false,
+  streaming: false,
+  citations: true,
+  // gbrain caps a `/mcp` request body at 1 MiB; keep a chunk comfortably inside.
+  maxChunkBytes: 64 * 1024
+});
+var mcpToolResultSchema = z.object({
+  content: z.array(z.object({ type: z.string(), text: z.string().optional() })).optional(),
+  structuredContent: z.unknown().optional(),
+  isError: z.boolean().optional()
+});
+var mcpEnvelopeSchema = z.object({
+  jsonrpc: z.literal("2.0").optional(),
+  id: z.union([z.number(), z.string(), z.null()]).optional(),
+  result: mcpToolResultSchema.optional(),
+  error: z.object({ code: z.number().optional(), message: z.string() }).optional()
+});
+var searchHitSchema = z.object({
+  slug: z.string(),
+  chunk_text: z.string().optional(),
+  chunk_index: z.number().optional(),
+  chunk_id: z.union([z.number(), z.string()]).optional(),
+  score: z.number().optional(),
+  base_score: z.number().optional()
+}).catchall(z.unknown());
+var searchResultSchema = z.union([
+  z.array(searchHitSchema),
+  z.object({ results: z.array(searchHitSchema) })
+]);
+var putPageResultSchema = z.object({
+  slug: z.string().optional(),
+  status: z.string().optional(),
+  chunks: z.number().optional()
+}).catchall(z.unknown());
+var pageSchema = z.object({
+  slug: z.string(),
+  type: z.string().optional(),
+  title: z.string().optional(),
+  compiled_truth: z.string().optional(),
+  source_uri: z.string().nullish(),
+  updated_at: z.string().optional(),
+  created_at: z.string().optional()
+}).catchall(z.unknown());
+var pageListItemSchema = z.object({
+  slug: z.string(),
+  type: z.string().optional(),
+  title: z.string().optional(),
+  updated_at: z.string().optional()
+}).catchall(z.unknown());
+var pageListSchema = z.union([
+  z.array(pageListItemSchema),
+  z.object({ pages: z.array(pageListItemSchema) })
+]);
+var GbrainDocKnowledgeAdapter = class {
+  id = GBRAIN_DOC_ENGINE_ID;
+  capabilities = GBRAIN_DOC_CAPABILITIES;
+  endpoint;
+  bearerToken;
+  timeoutMs;
+  label;
+  rpcCounter = 0;
+  constructor(config) {
+    this.endpoint = config.endpoint.replace(/\/$/, "");
+    this.bearerToken = config.bearerToken;
+    this.timeoutMs = config.timeoutMs;
+    this.label = config.label;
+  }
+  async ingest(input) {
+    const content = normalizeContent(input.content);
+    if (!content.trim()) {
+      throw new Error(
+        `GbrainDocKnowledgeAdapter: ingest payload is empty (uri=${input.uri}); gbrain put_page requires document content.`
+      );
+    }
+    const slug = deriveSlug(input);
+    const result = await this.callTool("put_page", { slug, content });
+    const parsed = putPageResultSchema.parse(parseToolJson(result));
+    return {
+      id: parsed.slug ?? slug,
+      kind: input.kind,
+      uri: input.uri,
+      title: input.title,
+      bytes: byteLength(content),
+      status: "ready",
+      indexedAt: /* @__PURE__ */ new Date(),
+      metadata: {
+        ...input.metadata ?? {},
+        gbrainStatus: parsed.status ?? "created_or_updated",
+        ...parsed.chunks !== void 0 ? { chunks: parsed.chunks } : {}
+      }
+    };
+  }
+  async query(q) {
+    const start = Date.now();
+    if (q.mode === "none") {
+      return { engine: this.id, modeUsed: "none", hits: [], tookMs: 0 };
+    }
+    const args = { query: q.query };
+    if (q.topK !== void 0) args.limit = q.topK;
+    const result = await this.callTool("search", args);
+    const parsed = searchResultSchema.parse(parseToolJson(result));
+    const rows = Array.isArray(parsed) ? parsed : parsed.results;
+    let hits = rows.map((row, i) => searchRowToHit(row, i));
+    if (q.minScore !== void 0) {
+      const floor = q.minScore;
+      hits = hits.filter((h) => h.score >= floor);
+    }
+    return {
+      engine: this.id,
+      // gbrain search fuses lexical + semantic recall — surface the real mode
+      // regardless of the caller's hint.
+      modeUsed: "hybrid",
+      hits,
+      tookMs: Date.now() - start
+    };
+  }
+  async listSources(filter) {
+    const args = {};
+    if (filter?.kind) args.type = kindToGbrainType(filter.kind);
+    const result = await this.callTool("list_pages", args);
+    const parsed = pageListSchema.parse(parseToolJson(result));
+    const rows = Array.isArray(parsed) ? parsed : parsed.pages;
+    let out = rows.map((row) => listItemToSource(row, filter?.kind));
+    if (filter?.status) out = out.filter((s) => s.status === filter.status);
+    return out;
+  }
+  async getSource(id) {
+    try {
+      const result = await this.callTool("get_page", { slug: id });
+      const parsed = pageSchema.parse(parseToolJson(result));
+      return pageToSource(parsed);
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+  async deleteSource(id) {
+    try {
+      await this.callTool("delete_page", { slug: id });
+    } catch (err) {
+      if (isNotFound(err)) return;
+      throw err;
+    }
+  }
+  async healthCheck() {
+    try {
+      const res = await fetch(`${this.endpoint}/health`, {
+        method: "GET",
+        headers: this.authHeaders()
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+  async dispose() {
+  }
+  // ── Internal: MCP / JSON-RPC plumbing ────────────────────────────
+  authHeaders() {
+    return {
+      Authorization: `Bearer ${this.bearerToken}`,
+      "Content-Type": "application/json",
+      // gbrain serves `/mcp` as MCP Streamable HTTP; the client MUST declare it
+      // accepts BOTH JSON and event-stream or the server answers 406.
+      Accept: "application/json, text/event-stream"
+    };
+  }
+  nextRpcId() {
+    this.rpcCounter += 1;
+    return this.rpcCounter;
+  }
+  /** Issue one MCP `tools/call` and return the parsed result envelope. Throws a
+   *  labelled error when gbrain sets `isError` (e.g. page-not-found). */
+  async callTool(name, args) {
+    const envelope = await this.rpcCall("tools/call", { name, arguments: args });
+    if (envelope.error !== void 0) {
+      throw new Error(this.errPrefix(`tool ${name}: ${envelope.error.message}`));
+    }
+    const result = envelope.result;
+    if (result === void 0) {
+      throw new Error(this.errPrefix(`tool ${name} returned no result`));
+    }
+    if (result.isError) {
+      throw new Error(this.errPrefix(`tool ${name}: ${readToolError(result)}`));
+    }
+    return result;
+  }
+  async rpcCall(method, params) {
+    const body = {
+      jsonrpc: "2.0",
+      id: this.nextRpcId(),
+      method,
+      params
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(`${this.endpoint}/mcp`, {
+        method: "POST",
+        headers: this.authHeaders(),
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        throw new Error(
+          this.errPrefix(
+            `${method} \u2192 HTTP ${res.status}${detail ? `: ${detail.slice(0, 300)}` : ""}`
+          )
+        );
+      }
+      const raw = await res.text();
+      return mcpEnvelopeSchema.parse(JSON.parse(extractJsonRpcPayload(raw)));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  errPrefix(msg) {
+    const labelPart = this.label ? ` (${this.label})` : "";
+    return `GbrainDocKnowledgeAdapter${labelPart}: ${msg}`;
+  }
+};
+function gbrainDocKnowledgeAdapter(config) {
+  return new GbrainDocKnowledgeAdapter(config);
+}
+function extractJsonRpcPayload(body) {
+  const dataLines = body.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).trim()).filter((payload) => payload.length > 0);
+  const last = dataLines[dataLines.length - 1];
+  return last ?? body.trim();
+}
+function parseToolJson(result) {
+  if (result.structuredContent !== void 0) return result.structuredContent;
+  const first = result.content?.find((c) => c.text !== void 0 && c.text !== "");
+  if (first?.text === void 0) return null;
+  try {
+    return JSON.parse(first.text);
+  } catch {
+    return first.text;
+  }
+}
+function readToolError(result) {
+  const first = result.content?.find((c) => c.text !== void 0 && c.text !== "");
+  return first?.text ?? "unknown error";
+}
+function isNotFound(err) {
+  return err instanceof Error && /not.?found/i.test(err.message);
+}
+function searchRowToHit(row, index) {
+  const { slug, chunk_text, chunk_index, chunk_id, score, base_score, ...rest } = row;
+  const chunkIndex = chunk_index ?? index;
+  return {
+    sourceId: slug,
+    chunkId: chunk_id !== void 0 ? `${slug}#${chunk_id}` : `${slug}#${chunkIndex}`,
+    text: chunk_text ?? "",
+    score: score ?? base_score ?? 0,
+    // Round-trip every other gbrain field (title, type, page_id, source_id,
+    // evidence, …) so a hit carries full provenance to the LLM.
+    metadata: { chunkIndex, ...rest }
+  };
+}
+function pageToSource(page) {
+  const compiled = page.compiled_truth ?? "";
+  return {
+    id: page.slug,
+    kind: gbrainTypeToKind(page.type),
+    uri: page.source_uri ?? page.slug,
+    title: page.title,
+    bytes: byteLength(compiled),
+    status: "ready",
+    indexedAt: parseDate(page.updated_at ?? page.created_at),
+    metadata: { type: page.type ?? "note" }
+  };
+}
+function listItemToSource(row, hintedKind) {
+  return {
+    id: row.slug,
+    kind: hintedKind ?? gbrainTypeToKind(row.type),
+    uri: row.slug,
+    title: row.title,
+    // list_pages is a slim projection (no body) — bytes are unknown here.
+    bytes: 0,
+    status: "ready",
+    indexedAt: parseDate(row.updated_at),
+    metadata: { type: row.type ?? "note" }
+  };
+}
+function deriveSlug(input) {
+  if (input.title) return slugify(input.title);
+  const [pathPart = ""] = input.uri.split(/[?#]/);
+  const tail = pathPart.split("/").filter(Boolean).pop();
+  if (tail) return slugify(tail);
+  return "note";
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "note";
+}
+function gbrainTypeToKind(t) {
+  if (!t) return "text";
+  if (t === "url" || t === "link") return "url";
+  if (t === "file" || t === "document" || t === "code") return "file";
+  if (t === "connector") return "connector";
+  return "text";
+}
+function kindToGbrainType(kind) {
+  switch (kind) {
+    case "url":
+      return "url";
+    case "file":
+      return "file";
+    case "connector":
+      return "connector";
+    case "text":
+    default:
+      return "note";
+  }
+}
+function normalizeContent(content) {
+  if (content === void 0) return "";
+  if (typeof content === "string") return content;
+  return new TextDecoder().decode(content);
+}
+function byteLength(text) {
+  return new TextEncoder().encode(text).byteLength;
+}
+function parseDate(v) {
+  if (v === void 0) return void 0;
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? void 0 : d;
+}
+
+// src/env.ts
+function parsePositiveInt(value, fallback) {
+  if (value === void 0 || value === "") return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+function nonEmpty(value) {
+  if (value === void 0) return void 0;
+  const trimmed = value.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function loadGbrainDocKnowledgeEnv() {
+  const bearerToken = nonEmpty(process.env.GBRAIN_BEARER_TOKEN);
+  if (bearerToken === void 0) {
+    throw new Error(
+      "GBRAIN_BEARER_TOKEN is required for the gbrain-doc knowledge adapter; mint one via gbrain's admin API (OAuth 2.1 client_credentials) and set it in the environment."
+    );
+  }
+  return {
+    endpoint: nonEmpty(process.env.GBRAIN_ENDPOINT) ?? "http://127.0.0.1:3132",
+    bearerToken,
+    timeoutMs: parsePositiveInt(process.env.GBRAIN_HTTP_TIMEOUT_MS, 45e3)
+  };
+}
+function gbrainDocEnvToConfig(env) {
+  return {
+    endpoint: env.endpoint,
+    bearerToken: env.bearerToken,
+    timeoutMs: env.timeoutMs
+  };
+}
+
+// src/standalone.ts
+function createStandaloneGbrainDocAdapter() {
+  return new GbrainDocKnowledgeAdapter(
+    gbrainDocEnvToConfig(loadGbrainDocKnowledgeEnv())
+  );
+}
+
+// src/catalog.ts
+var KNOWLEDGE_FAMILY = "knowledge";
+var GBRAIN_DOC_SLUG = "gbrain-doc";
+var KNOWLEDGE_GBRAIN_DOC_CATALOG = [
+  {
+    slug: GBRAIN_DOC_SLUG,
+    name: "gbrain (doc)",
+    description: "Document knowledge retrieval over a gbrain server's put_page / search API, reached over its JSON-RPC /mcp endpoint via pure fetch \u2014 no vendor SDK. gbrain fuses lexical (tsvector) + semantic recall. Needs a gbrain endpoint + a machine bearer token. Distinct from the code-graph gbrain adapter.",
+    packageName: "@agentproto/adapter-knowledge-gbrain-doc",
+    hint: "gbrain \xB7 doc"
+  }
+];
+function resolveKnowledgeBackend(slug) {
+  const catalogEntry = KNOWLEDGE_GBRAIN_DOC_CATALOG.find(
+    (entry) => entry.slug === slug
+  );
+  if (catalogEntry === void 0) {
+    throw new Error(`unknown knowledge backend slug: ${slug}`);
+  }
+  switch (slug) {
+    case GBRAIN_DOC_SLUG: {
+      return {
+        slug,
+        name: catalogEntry.name,
+        description: catalogEntry.description,
+        version: "0.1.0",
+        requiresSetup: true,
+        authRequired: true,
+        // Health probe: build from env + hit GET /health. When the env is
+        // absent, construction throws — fold that to "not reachable" rather
+        // than propagating so a listing probe stays total.
+        check: async () => {
+          try {
+            return await createStandaloneGbrainDocAdapter().healthCheck();
+          } catch {
+            return false;
+          }
+        },
+        info() {
+          return {
+            slug,
+            engine: "gbrain-doc",
+            capabilities: { hybridSearch: true, needsCreds: true }
+          };
+        },
+        provider: () => createStandaloneGbrainDocAdapter()
+      };
+    }
+  }
+  throw new Error(`unhandled knowledge backend slug: ${slug}`);
+}
+function makeKnowledgeGbrainDocResolver() {
+  return makeAdapterResolver({
+    load: async (slug) => resolveKnowledgeBackend(slug)
+  });
+}
+
+export { GBRAIN_DOC_CAPABILITIES, GBRAIN_DOC_ENGINE_ID, GBRAIN_DOC_SLUG, GbrainDocAdapterConfigSchema, GbrainDocKnowledgeAdapter, KNOWLEDGE_FAMILY, KNOWLEDGE_GBRAIN_DOC_CATALOG, createStandaloneGbrainDocAdapter, extractJsonRpcPayload, gbrainDocEnvToConfig, gbrainDocKnowledgeAdapter, loadGbrainDocKnowledgeEnv, makeKnowledgeGbrainDocResolver, parseGbrainDocAdapterConfig, resolveKnowledgeBackend };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapter.ts","../src/env.ts","../src/standalone.ts","../src/catalog.ts","../src/handle.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * GbrainDocKnowledgeAdapter — the `IKnowledgeProvider` over gbrain's DOCUMENT\n * API.\n *\n * Connects the `@agentproto/knowledge-engine` `IKnowledgeProvider` contract to a\n * gbrain server's document surface, reached over its JSON-RPC MCP endpoint\n * (`POST /mcp`, bearer-authenticated) via pure `fetch` — no vendor SDK. The two\n * load-bearing tools are `put_page` (ingest) and `search` (query); the\n * lifecycle verbs (`list_pages` / `get_page` / `delete_page`) round out the\n * contract. Lets a host plug \"my own gbrain\" as a first-class knowledge engine\n * alongside the files / corpus / qdrant backends.\n *\n * DISTINCT from `@agentproto/adapter-code-brain-gbrain`: that adapter is the\n * CODE-GRAPH one (`ICodeBrainProvider`: define / callers / callees). THIS one is\n * the KNOWLEDGE-DOC one (`IKnowledgeProvider` over gbrain's document store).\n * Same backend, different contract — they never share a package edge; gbrain is\n * reached only at runtime over HTTP.\n *\n * Lifted from the studio integration package\n * (`packages/integration/knowledge/src/providers/gbrain-knowledge.adapter.ts`).\n * Changes on the lift:\n *   1. The contract + data types now come from `@agentproto/knowledge-engine`\n *      (was the studio `../base-knowledge.provider` / `../../types`).\n *   2. The ONE cross-package edge — a type-only import of `JsonRpcRequest` /\n *      `JsonRpcResponse` from the studio `core/protocol` package\n *      (`gbrain-knowledge.adapter.ts:23`) — is replaced by the two inline\n *      interfaces below. No studio dependency survives.\n *   3. The wire shapes are typed against the LIVE gbrain doc API (probed at\n *      build time), which drifts from the studio original:\n *        - `put_page` args are `{ slug, content }` (studio sent a `source`\n *          field; gbrain's real field is the server-stamped `source_uri`).\n *        - `search` args are `{ query, limit, offset }` (studio sent a\n *          `min_score` gbrain doesn't accept — `minScore` is applied\n *          client-side here instead).\n *        - a `search` hit carries `chunk_text` / `score` / `chunk_index`\n *          (studio expected `snippet` / `rerank_score`).\n *      Every response is zod-parsed — nothing untyped reaches a call site.\n *\n * Scope of this adapter:\n *   - `ingest({ kind, uri, title?, content })` — `put_page` a markdown doc\n *   - `query({ query, topK, minScore })` — `search` (gbrain fuses lexical +\n *     semantic recall, so `modeUsed` is stamped `\"hybrid\"`)\n *   - `listSources()` / `getSource(id)` / `deleteSource(id)` — via\n *     `list_pages` / `get_page` / `delete_page`\n *   - `healthCheck()` — `GET /health` returns OK\n */\n\nimport { z } from \"zod\"\nimport type {\n  IKnowledgeProvider,\n  KnowledgeCapabilities,\n  KnowledgeHit,\n  KnowledgeIngestInput,\n  KnowledgeQuery,\n  KnowledgeQueryResult,\n  KnowledgeSource,\n  KnowledgeSourceKind,\n  ListSourcesFilter,\n} from \"@agentproto/knowledge-engine\"\n\nexport const GBRAIN_DOC_ENGINE_ID = \"gbrain-doc\" as const\n\n// ── Inline JSON-RPC 2.0 wire types ──────────────────────────────────\n//\n// Replaces the studio adapter's ONE cross-package edge: a type-only import of\n// `JsonRpcRequest` / `JsonRpcResponse` from the studio `core/protocol` package.\n// gbrain speaks JSON-RPC 2.0 over `POST /mcp`; these two frames are all we send\n// and receive, so they inline here with zero new dependency. The response is\n// additionally zod-validated on the wire ({@link mcpEnvelopeSchema}) so nothing\n// untyped reaches a call site.\n\n/** A JSON-RPC 2.0 request frame — the body we POST to gbrain's `/mcp`. */\ninterface JsonRpcRequest<TParams = unknown> {\n  readonly jsonrpc: \"2.0\"\n  readonly id: number\n  readonly method: string\n  readonly params?: TParams\n}\n\n/** A JSON-RPC 2.0 response frame — success carries `result`, failure `error`. */\ninterface JsonRpcResponse<TResult = unknown> {\n  readonly jsonrpc?: \"2.0\"\n  readonly id?: number | string | null\n  readonly result?: TResult\n  readonly error?: { readonly code?: number; readonly message: string }\n}\n\n// ── Config ──────────────────────────────────────────────────────────\n\nexport const GbrainDocAdapterConfigSchema = z.object({\n  /** Base URL of the gbrain HTTP server (no trailing slash needed). The\n   *  JSON-RPC `/mcp` endpoint is appended. */\n  endpoint: z.string().url(),\n  /** Machine bearer token accepted by the gbrain server (`GBRAIN_BEARER_TOKEN`).\n   *  Required — the `/mcp` endpoint is OAuth 2.1 / bearer-protected. */\n  bearerToken: z.string().min(1),\n  /** Per-request timeout (ms). Default 45_000. */\n  timeoutMs: z.number().int().positive().default(45_000),\n  /** Optional human label for logs. */\n  label: z.string().optional(),\n})\n\nexport type GbrainDocAdapterConfig = z.infer<typeof GbrainDocAdapterConfigSchema>\n\nexport function parseGbrainDocAdapterConfig(\n  raw: Readonly<Record<string, unknown>>,\n): GbrainDocAdapterConfig {\n  return GbrainDocAdapterConfigSchema.parse(raw)\n}\n\n// ── Capabilities ────────────────────────────────────────────────────\n\nexport const GBRAIN_DOC_CAPABILITIES: KnowledgeCapabilities = Object.freeze({\n  // gbrain `search` fuses lexical (tsvector) + semantic recall, so both the\n  // vector + hybrid flags are honest.\n  vectorSearch: true,\n  hybridSearch: true,\n  // This adapter drives the DOCUMENT surface (put_page / search); it does NOT\n  // reach gbrain's graph traversal (`traverse_graph` / `query`).\n  graphTraversal: false,\n  multiModal: false,\n  streaming: false,\n  citations: true,\n  // gbrain caps a `/mcp` request body at 1 MiB; keep a chunk comfortably inside.\n  maxChunkBytes: 64 * 1024,\n})\n\n// ── Wire shapes (zod-parsed — nothing untyped reaches a call site) ───\n\n/** The MCP `tools/call` result envelope: a text block (+ optional structured\n *  content) and an `isError` flag gbrain sets for e.g. page-not-found. */\nconst mcpToolResultSchema = z.object({\n  content: z\n    .array(z.object({ type: z.string(), text: z.string().optional() }))\n    .optional(),\n  structuredContent: z.unknown().optional(),\n  isError: z.boolean().optional(),\n})\n\ntype McpToolResult = z.infer<typeof mcpToolResultSchema>\n\n/** The JSON-RPC envelope wrapping an MCP `tools/call` result. Mirrors the\n *  inline {@link JsonRpcResponse} interface, validated on the wire. */\nconst mcpEnvelopeSchema = z.object({\n  jsonrpc: z.literal(\"2.0\").optional(),\n  id: z.union([z.number(), z.string(), z.null()]).optional(),\n  result: mcpToolResultSchema.optional(),\n  error: z\n    .object({ code: z.number().optional(), message: z.string() })\n    .optional(),\n})\n\n/** A single `search` hit row (gbrain doc API). Known fields are typed; the rest\n *  (page_id, type, source_id, evidence, …) flow through to `metadata`. */\nconst searchHitSchema = z\n  .object({\n    slug: z.string(),\n    chunk_text: z.string().optional(),\n    chunk_index: z.number().optional(),\n    chunk_id: z.union([z.number(), z.string()]).optional(),\n    score: z.number().optional(),\n    base_score: z.number().optional(),\n  })\n  .catchall(z.unknown())\n\n/** `search` returns a bare array of hits; some builds wrap it as `{ results }`.\n *  Accept both. */\nconst searchResultSchema = z.union([\n  z.array(searchHitSchema),\n  z.object({ results: z.array(searchHitSchema) }),\n])\n\n/** `put_page` result — status + chunk count (+ passthrough backstop fields). */\nconst putPageResultSchema = z\n  .object({\n    slug: z.string().optional(),\n    status: z.string().optional(),\n    chunks: z.number().optional(),\n  })\n  .catchall(z.unknown())\n\n/** A `get_page` document envelope. */\nconst pageSchema = z\n  .object({\n    slug: z.string(),\n    type: z.string().optional(),\n    title: z.string().optional(),\n    compiled_truth: z.string().optional(),\n    source_uri: z.string().nullish(),\n    updated_at: z.string().optional(),\n    created_at: z.string().optional(),\n  })\n  .catchall(z.unknown())\n\n/** A `list_pages` row (slim: no body). */\nconst pageListItemSchema = z\n  .object({\n    slug: z.string(),\n    type: z.string().optional(),\n    title: z.string().optional(),\n    updated_at: z.string().optional(),\n  })\n  .catchall(z.unknown())\n\nconst pageListSchema = z.union([\n  z.array(pageListItemSchema),\n  z.object({ pages: z.array(pageListItemSchema) }),\n])\n\n// ── Adapter ──────────────────────────────────────────────────────────\n\nexport class GbrainDocKnowledgeAdapter implements IKnowledgeProvider {\n  readonly id = GBRAIN_DOC_ENGINE_ID\n  readonly capabilities = GBRAIN_DOC_CAPABILITIES\n\n  private readonly endpoint: string\n  private readonly bearerToken: string\n  private readonly timeoutMs: number\n  private readonly label?: string\n\n  private rpcCounter = 0\n\n  constructor(config: GbrainDocAdapterConfig) {\n    this.endpoint = config.endpoint.replace(/\\/$/, \"\")\n    this.bearerToken = config.bearerToken\n    this.timeoutMs = config.timeoutMs\n    this.label = config.label\n  }\n\n  async ingest(input: KnowledgeIngestInput): Promise<KnowledgeSource> {\n    const content = normalizeContent(input.content)\n    if (!content.trim()) {\n      throw new Error(\n        `GbrainDocKnowledgeAdapter: ingest payload is empty (uri=${input.uri}); gbrain put_page requires document content.`,\n      )\n    }\n    const slug = deriveSlug(input)\n    // gbrain put_page takes { slug, content }. `source_uri` is SERVER-STAMPED\n    // for remote callers (client value ignored), so we don't send it — the\n    // caller's uri round-trips through the returned KnowledgeSource instead.\n    const result = await this.callTool(\"put_page\", { slug, content })\n    const parsed = putPageResultSchema.parse(parseToolJson(result))\n    return {\n      id: parsed.slug ?? slug,\n      kind: input.kind,\n      uri: input.uri,\n      title: input.title,\n      bytes: byteLength(content),\n      status: \"ready\",\n      indexedAt: new Date(),\n      metadata: {\n        ...(input.metadata ?? {}),\n        gbrainStatus: parsed.status ?? \"created_or_updated\",\n        ...(parsed.chunks !== undefined ? { chunks: parsed.chunks } : {}),\n      },\n    }\n  }\n\n  async query(q: KnowledgeQuery): Promise<KnowledgeQueryResult> {\n    const start = Date.now()\n    // `\"none\"` is the cold-start sentinel — skip retrieval entirely.\n    if (q.mode === \"none\") {\n      return { engine: this.id, modeUsed: \"none\", hits: [], tookMs: 0 }\n    }\n\n    const args: Record<string, number | string> = { query: q.query }\n    if (q.topK !== undefined) args.limit = q.topK\n\n    const result = await this.callTool(\"search\", args)\n    const parsed = searchResultSchema.parse(parseToolJson(result))\n    const rows = Array.isArray(parsed) ? parsed : parsed.results\n\n    let hits: KnowledgeHit[] = rows.map((row, i) => searchRowToHit(row, i))\n    // gbrain `search` has no server-side score floor, so honour `minScore`\n    // client-side (the contract lets adapters enforce it either way).\n    if (q.minScore !== undefined) {\n      const floor = q.minScore\n      hits = hits.filter((h) => h.score >= floor)\n    }\n\n    return {\n      engine: this.id,\n      // gbrain search fuses lexical + semantic recall — surface the real mode\n      // regardless of the caller's hint.\n      modeUsed: \"hybrid\",\n      hits,\n      tookMs: Date.now() - start,\n    }\n  }\n\n  async listSources(\n    filter?: ListSourcesFilter,\n  ): Promise<readonly KnowledgeSource[]> {\n    const args: Record<string, string> = {}\n    if (filter?.kind) args.type = kindToGbrainType(filter.kind)\n    const result = await this.callTool(\"list_pages\", args)\n    const parsed = pageListSchema.parse(parseToolJson(result))\n    const rows = Array.isArray(parsed) ? parsed : parsed.pages\n    let out = rows.map((row) => listItemToSource(row, filter?.kind))\n    // `status` isn't a gbrain list dimension — every listed page is live, so a\n    // `status` filter keeps only \"ready\" (all of them) or nothing.\n    if (filter?.status) out = out.filter((s) => s.status === filter.status)\n    return out\n  }\n\n  async getSource(id: string): Promise<KnowledgeSource | null> {\n    try {\n      const result = await this.callTool(\"get_page\", { slug: id })\n      const parsed = pageSchema.parse(parseToolJson(result))\n      return pageToSource(parsed)\n    } catch (err) {\n      // gbrain flags a missing page with isError + a \"page_not_found\" body —\n      // fold that to null; re-throw anything else.\n      if (isNotFound(err)) return null\n      throw err\n    }\n  }\n\n  async deleteSource(id: string): Promise<void> {\n    try {\n      await this.callTool(\"delete_page\", { slug: id })\n    } catch (err) {\n      // Deleting an already-absent page is a no-op, not an error.\n      if (isNotFound(err)) return\n      throw err\n    }\n  }\n\n  async healthCheck(): Promise<boolean> {\n    try {\n      const res = await fetch(`${this.endpoint}/health`, {\n        method: \"GET\",\n        headers: this.authHeaders(),\n      })\n      return res.ok\n    } catch {\n      return false\n    }\n  }\n\n  async dispose(): Promise<void> {\n    // No connections to tear down — gbrain calls are stateless JSON-RPC over\n    // HTTP. Kept on the interface for adapters that hold long-lived clients.\n  }\n\n  // ── Internal: MCP / JSON-RPC plumbing ────────────────────────────\n\n  private authHeaders(): Record<string, string> {\n    return {\n      Authorization: `Bearer ${this.bearerToken}`,\n      \"Content-Type\": \"application/json\",\n      // gbrain serves `/mcp` as MCP Streamable HTTP; the client MUST declare it\n      // accepts BOTH JSON and event-stream or the server answers 406.\n      Accept: \"application/json, text/event-stream\",\n    }\n  }\n\n  private nextRpcId(): number {\n    this.rpcCounter += 1\n    return this.rpcCounter\n  }\n\n  /** Issue one MCP `tools/call` and return the parsed result envelope. Throws a\n   *  labelled error when gbrain sets `isError` (e.g. page-not-found). */\n  private async callTool(\n    name: string,\n    args: Readonly<Record<string, unknown>>,\n  ): Promise<McpToolResult> {\n    const envelope = await this.rpcCall(\"tools/call\", { name, arguments: args })\n    if (envelope.error !== undefined) {\n      throw new Error(this.errPrefix(`tool ${name}: ${envelope.error.message}`))\n    }\n    const result = envelope.result\n    if (result === undefined) {\n      throw new Error(this.errPrefix(`tool ${name} returned no result`))\n    }\n    if (result.isError) {\n      throw new Error(this.errPrefix(`tool ${name}: ${readToolError(result)}`))\n    }\n    return result\n  }\n\n  private async rpcCall(\n    method: string,\n    params: unknown,\n  ): Promise<z.infer<typeof mcpEnvelopeSchema>> {\n    const body: JsonRpcRequest = {\n      jsonrpc: \"2.0\",\n      id: this.nextRpcId(),\n      method,\n      params,\n    }\n    const controller = new AbortController()\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs)\n    try {\n      const res = await fetch(`${this.endpoint}/mcp`, {\n        method: \"POST\",\n        headers: this.authHeaders(),\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      })\n      if (!res.ok) {\n        const detail = await res.text().catch(() => \"\")\n        throw new Error(\n          this.errPrefix(\n            `${method} → HTTP ${res.status}${detail ? `: ${detail.slice(0, 300)}` : \"\"}`,\n          ),\n        )\n      }\n      // gbrain replies as a Streamable-HTTP SSE frame (`data: {…}`) OR plain\n      // JSON — {@link extractJsonRpcPayload} normalises both.\n      const raw = await res.text()\n      return mcpEnvelopeSchema.parse(JSON.parse(extractJsonRpcPayload(raw)))\n    } finally {\n      clearTimeout(timer)\n    }\n  }\n\n  private errPrefix(msg: string): string {\n    const labelPart = this.label ? ` (${this.label})` : \"\"\n    return `GbrainDocKnowledgeAdapter${labelPart}: ${msg}`\n  }\n}\n\n/** Construct a {@link GbrainDocKnowledgeAdapter} from a validated config. */\nexport function gbrainDocKnowledgeAdapter(\n  config: GbrainDocAdapterConfig,\n): GbrainDocKnowledgeAdapter {\n  return new GbrainDocKnowledgeAdapter(config)\n}\n\n// ── Pure helpers (no I/O) — exported where a test drives them ─────────\n\n/**\n * Extract the JSON-RPC envelope from a Streamable-HTTP response body. gbrain\n * replies with SSE frames (`event: message\\ndata: {…}`); the last non-empty\n * `data:` line carries the JSON-RPC payload. A plain-JSON body (no SSE framing)\n * is returned whole.\n */\nexport function extractJsonRpcPayload(body: string): string {\n  const dataLines = body\n    .split(/\\r?\\n/)\n    .filter((line) => line.startsWith(\"data:\"))\n    .map((line) => line.slice(\"data:\".length).trim())\n    .filter((payload) => payload.length > 0)\n  const last = dataLines[dataLines.length - 1]\n  return last ?? body.trim()\n}\n\n/**\n * Pull the JSON payload out of an MCP tool result: prefer `structuredContent`,\n * else the first text block parsed as JSON. Returns the raw text when it isn't\n * JSON. The caller zod-parses the returned value into a concrete shape.\n */\nfunction parseToolJson(result: McpToolResult): unknown {\n  if (result.structuredContent !== undefined) return result.structuredContent\n  const first = result.content?.find((c) => c.text !== undefined && c.text !== \"\")\n  if (first?.text === undefined) return null\n  try {\n    return JSON.parse(first.text)\n  } catch {\n    return first.text\n  }\n}\n\n/** The error text gbrain packs into a `tools/call` result when `isError` is set. */\nfunction readToolError(result: McpToolResult): string {\n  const first = result.content?.find((c) => c.text !== undefined && c.text !== \"\")\n  return first?.text ?? \"unknown error\"\n}\n\nfunction isNotFound(err: unknown): boolean {\n  return err instanceof Error && /not.?found/i.test(err.message)\n}\n\ntype SearchRow = z.infer<typeof searchHitSchema>\n\nfunction searchRowToHit(row: SearchRow, index: number): KnowledgeHit {\n  const { slug, chunk_text, chunk_index, chunk_id, score, base_score, ...rest } =\n    row\n  const chunkIndex = chunk_index ?? index\n  return {\n    sourceId: slug,\n    chunkId:\n      chunk_id !== undefined ? `${slug}#${chunk_id}` : `${slug}#${chunkIndex}`,\n    text: chunk_text ?? \"\",\n    score: score ?? base_score ?? 0,\n    // Round-trip every other gbrain field (title, type, page_id, source_id,\n    // evidence, …) so a hit carries full provenance to the LLM.\n    metadata: { chunkIndex, ...rest },\n  }\n}\n\ntype PageRow = z.infer<typeof pageSchema>\n\nfunction pageToSource(page: PageRow): KnowledgeSource {\n  const compiled = page.compiled_truth ?? \"\"\n  return {\n    id: page.slug,\n    kind: gbrainTypeToKind(page.type),\n    uri: page.source_uri ?? page.slug,\n    title: page.title,\n    bytes: byteLength(compiled),\n    status: \"ready\",\n    indexedAt: parseDate(page.updated_at ?? page.created_at),\n    metadata: { type: page.type ?? \"note\" },\n  }\n}\n\ntype PageListRow = z.infer<typeof pageListItemSchema>\n\nfunction listItemToSource(\n  row: PageListRow,\n  hintedKind?: KnowledgeSourceKind,\n): KnowledgeSource {\n  return {\n    id: row.slug,\n    kind: hintedKind ?? gbrainTypeToKind(row.type),\n    uri: row.slug,\n    title: row.title,\n    // list_pages is a slim projection (no body) — bytes are unknown here.\n    bytes: 0,\n    status: \"ready\",\n    indexedAt: parseDate(row.updated_at),\n    metadata: { type: row.type ?? \"note\" },\n  }\n}\n\nfunction deriveSlug(input: KnowledgeIngestInput): string {\n  if (input.title) return slugify(input.title)\n  const [pathPart = \"\"] = input.uri.split(/[?#]/)\n  const tail = pathPart.split(\"/\").filter(Boolean).pop()\n  if (tail) return slugify(tail)\n  return \"note\"\n}\n\nfunction slugify(s: string): string {\n  return (\n    s\n      .toLowerCase()\n      .replace(/[^a-z0-9]+/g, \"-\")\n      .replace(/^-+|-+$/g, \"\")\n      .slice(0, 80) || \"note\"\n  )\n}\n\nfunction gbrainTypeToKind(t: string | undefined): KnowledgeSourceKind {\n  if (!t) return \"text\"\n  if (t === \"url\" || t === \"link\") return \"url\"\n  if (t === \"file\" || t === \"document\" || t === \"code\") return \"file\"\n  if (t === \"connector\") return \"connector\"\n  return \"text\"\n}\n\nfunction kindToGbrainType(kind: KnowledgeSourceKind): string {\n  switch (kind) {\n    case \"url\":\n      return \"url\"\n    case \"file\":\n      return \"file\"\n    case \"connector\":\n      return \"connector\"\n    case \"text\":\n    default:\n      return \"note\"\n  }\n}\n\nfunction normalizeContent(content: KnowledgeIngestInput[\"content\"]): string {\n  if (content === undefined) return \"\"\n  if (typeof content === \"string\") return content\n  return new TextDecoder().decode(content)\n}\n\n/** UTF-8 byte length without a `node:buffer` edge — runs on edge runtimes too. */\nfunction byteLength(text: string): number {\n  return new TextEncoder().encode(text).byteLength\n}\n\nfunction parseDate(v: string | undefined): Date | undefined {\n  if (v === undefined) return undefined\n  const d = new Date(v)\n  return Number.isNaN(d.getTime()) ? undefined : d\n}\n","/**\n * Typed environment module for the gbrain-doc knowledge adapter.\n *\n * Every `process.env` read in this package flows through here — no raw\n * `process.env.X` at a call site (mirrors the code-brain + files + corpus +\n * qdrant adapters' `env.ts`). The loader parses the ambient env into a typed,\n * validated config once, so the rest of the adapter is a pure function of its\n * inputs. This is the ONE place the gbrain-flavoured env names (`GBRAIN_*`)\n * live, keeping the backend idiom confined to the adapter.\n *\n * `GBRAIN_BEARER_TOKEN` is shared with `@agentproto/adapter-code-brain-gbrain`'s\n * HTTP backend by design — same gbrain server, same machine token — but the two\n * adapters never share a package edge; the token only ever meets gbrain at\n * runtime over HTTP.\n */\n\nimport type { GbrainDocAdapterConfig } from \"./adapter.js\"\n\nfunction parsePositiveInt(value: string | undefined, fallback: number): number {\n  if (value === undefined || value === \"\") return fallback\n  const parsed = Number.parseInt(value, 10)\n  if (Number.isNaN(parsed) || parsed <= 0) return fallback\n  return parsed\n}\n\nfunction nonEmpty(value: string | undefined): string | undefined {\n  if (value === undefined) return undefined\n  const trimmed = value.trim()\n  return trimmed === \"\" ? undefined : trimmed\n}\n\n/** Config for the standalone gbrain-doc backend — a gbrain HTTP endpoint + a\n *  machine bearer token. */\nexport interface GbrainDocKnowledgeEnv {\n  /** gbrain HTTP base URL (`GBRAIN_ENDPOINT`); the `/mcp` JSON-RPC endpoint is\n   *  appended. Default `\"http://127.0.0.1:3132\"`. */\n  readonly endpoint: string\n  /** Machine bearer token (`GBRAIN_BEARER_TOKEN`). Required — the `/mcp`\n   *  endpoint is bearer-protected. */\n  readonly bearerToken: string\n  /** Per-request timeout (ms) (`GBRAIN_HTTP_TIMEOUT_MS`). Default 45_000. */\n  readonly timeoutMs: number\n}\n\n/**\n * Load {@link GbrainDocKnowledgeEnv} from `process.env` with defaults.\n *\n * Throws when `GBRAIN_BEARER_TOKEN` is absent — the adapter cannot authenticate\n * to the `/mcp` endpoint without it, and failing at construction time is\n * clearer than a 401 on the first call.\n */\nexport function loadGbrainDocKnowledgeEnv(): GbrainDocKnowledgeEnv {\n  const bearerToken = nonEmpty(process.env.GBRAIN_BEARER_TOKEN)\n  if (bearerToken === undefined) {\n    throw new Error(\n      \"GBRAIN_BEARER_TOKEN is required for the gbrain-doc knowledge adapter; mint one via gbrain's admin API (OAuth 2.1 client_credentials) and set it in the environment.\",\n    )\n  }\n  return {\n    endpoint: nonEmpty(process.env.GBRAIN_ENDPOINT) ?? \"http://127.0.0.1:3132\",\n    bearerToken,\n    timeoutMs: parsePositiveInt(process.env.GBRAIN_HTTP_TIMEOUT_MS, 45_000),\n  }\n}\n\n/** Project the typed env into a {@link GbrainDocAdapterConfig}. */\nexport function gbrainDocEnvToConfig(\n  env: GbrainDocKnowledgeEnv,\n): GbrainDocAdapterConfig {\n  return {\n    endpoint: env.endpoint,\n    bearerToken: env.bearerToken,\n    timeoutMs: env.timeoutMs,\n  }\n}\n","/**\n * Standalone wiring for {@link GbrainDocKnowledgeAdapter}.\n *\n * The adapter class itself is config-driven: it consumes a plain\n * {@link GbrainDocAdapterConfig} and knows nothing about `process.env`. This\n * module is the ONE place that binds it to the ambient environment — it reads\n * the typed `GBRAIN_*` env (via {@link loadGbrainDocKnowledgeEnv}) and\n * constructs an adapter from it, exactly the role the code-brain adapter's\n * provider factories play for their backends. Hosts that already hold a config\n * (e.g. a studio guild host resolving a per-KB `configRef` + vault secrets)\n * should construct `GbrainDocKnowledgeAdapter` directly and skip this factory.\n */\n\nimport { GbrainDocKnowledgeAdapter } from \"./adapter.js\"\nimport { gbrainDocEnvToConfig, loadGbrainDocKnowledgeEnv } from \"./env.js\"\n\n/**\n * Build a {@link GbrainDocKnowledgeAdapter} from the ambient `GBRAIN_*` env.\n * Throws (via {@link loadGbrainDocKnowledgeEnv}) when `GBRAIN_BEARER_TOKEN` is\n * absent. Each call returns a fresh adapter — the adapter holds no warm state\n * (stateless JSON-RPC over HTTP), so sharing an instance is a convenience, not\n * a requirement.\n */\nexport function createStandaloneGbrainDocAdapter(): GbrainDocKnowledgeAdapter {\n  return new GbrainDocKnowledgeAdapter(\n    gbrainDocEnvToConfig(loadGbrainDocKnowledgeEnv()),\n  )\n}\n","import type { AdapterCatalog } from \"@agentproto/provider-kit\"\n\n/**\n * Family key used for the knowledge backend creds/ledger store path.\n *\n * The gbrain-doc engine is the document-retrieval sibling of the `files`\n * (BM25), `corpus` (AIP-10 composition), and `qdrant` (vector) backends — same\n * `knowledge` family, so all four surface through the same provider-kit\n * discovery convention (`@agentproto/adapter-knowledge-*`).\n */\nexport const KNOWLEDGE_FAMILY = \"knowledge\" as const\n\n/** The single backend slug this adapter provides. */\nexport const GBRAIN_DOC_SLUG = \"gbrain-doc\" as const\n\n/**\n * Static catalog of knowledge backends shipped by this adapter. The `gbrain-doc`\n * slug resolves from THIS package (`@agentproto/adapter-knowledge-gbrain-doc`) —\n * document retrieval over a gbrain server's `put_page` / `search` API, reached\n * over its JSON-RPC `/mcp` endpoint via pure `fetch` (no vendor SDK). Needs a\n * gbrain endpoint + a machine bearer token, so it requires a setup pass.\n *\n * DISTINCT from `@agentproto/adapter-code-brain-gbrain` (the code-graph gbrain\n * adapter) — same backend, different contract, no shared package edge.\n */\nexport const KNOWLEDGE_GBRAIN_DOC_CATALOG: AdapterCatalog = [\n  {\n    slug: GBRAIN_DOC_SLUG,\n    name: \"gbrain (doc)\",\n    description:\n      \"Document knowledge retrieval over a gbrain server's put_page / search \" +\n      \"API, reached over its JSON-RPC /mcp endpoint via pure fetch — no vendor \" +\n      \"SDK. gbrain fuses lexical (tsvector) + semantic recall. Needs a gbrain \" +\n      \"endpoint + a machine bearer token. Distinct from the code-graph gbrain \" +\n      \"adapter.\",\n    packageName: \"@agentproto/adapter-knowledge-gbrain-doc\",\n    hint: \"gbrain · doc\",\n  },\n]\n","/**\n * provider-kit family wiring for the gbrain-doc knowledge backend.\n *\n * The studio home-grown `createEngineRegistry`-based knowledge registry is NOT\n * ported (it was the guild resolution layer, which stays studio-side per the\n * Ph4 plan — the studio gbrain `descriptor` recursively resolves per-KB config\n * + reveals the vault bearer through that registry, and the retired E2B/sandbox\n * provisioning path stays studio-side too). Instead the gbrain-doc backend\n * registers as a provider-kit family (`TInfo = KnowledgeGbrainDocInfo`, `THandle\n * = KnowledgeHandle extends AdapterHandle`), reusing the exact consumer shape\n * the code-brain + files + corpus + qdrant adapters established — catalog +\n * resolver + a safe `info()` descriptor that NEVER carries a secret. Discovery\n * flows through the kit's `@agentproto/adapter-knowledge-*` naming convention.\n *\n * gbrain-doc needs a gbrain endpoint + a bearer token, so `requiresSetup` /\n * `authRequired` are both true and `provider()` (via\n * {@link createStandaloneGbrainDocAdapter}) throws when `GBRAIN_BEARER_TOKEN` is\n * absent.\n */\n\nimport type { IKnowledgeProvider } from \"@agentproto/knowledge-engine\"\nimport {\n  makeAdapterResolver,\n  type AdapterHandle,\n  type AdapterResolver,\n} from \"@agentproto/provider-kit\"\nimport { GBRAIN_DOC_SLUG, KNOWLEDGE_GBRAIN_DOC_CATALOG } from \"./catalog.js\"\nimport { createStandaloneGbrainDocAdapter } from \"./standalone.js\"\n\n/** Safe descriptor for a knowledge backend — NEVER carries a secret. */\nexport interface KnowledgeGbrainDocInfo {\n  readonly slug: string\n  /** The retrieval engine this backend uses. */\n  readonly engine: \"gbrain-doc\"\n  readonly capabilities: {\n    /** True — gbrain fuses lexical + semantic document retrieval. */\n    readonly hybridSearch: boolean\n    /** True — gbrain-doc needs a gbrain endpoint + a machine bearer token. */\n    readonly needsCreds: boolean\n  }\n}\n\n/** A resolved knowledge backend handle. */\nexport interface KnowledgeHandle extends AdapterHandle {\n  /** Safe descriptor — NEVER a secret. */\n  info(): KnowledgeGbrainDocInfo\n  /**\n   * Build the live {@link IKnowledgeProvider} from the ambient `GBRAIN_*` env.\n   * Throws when `GBRAIN_BEARER_TOKEN` is absent — construction-time failure is\n   * clearer than a 401 on the first query.\n   */\n  provider(): IKnowledgeProvider\n}\n\n/**\n * Resolve a catalog slug to a concrete knowledge handle. Throws for unknown\n * slugs so the kit's resolver wrapper folds the miss to `null`. `provider()` is\n * lazy — the `GBRAIN_BEARER_TOKEN` requirement is enforced only when a provider\n * is actually built, not at resolution time.\n */\nexport function resolveKnowledgeBackend(slug: string): KnowledgeHandle {\n  const catalogEntry = KNOWLEDGE_GBRAIN_DOC_CATALOG.find(\n    (entry) => entry.slug === slug,\n  )\n  if (catalogEntry === undefined) {\n    throw new Error(`unknown knowledge backend slug: ${slug}`)\n  }\n\n  switch (slug) {\n    case GBRAIN_DOC_SLUG: {\n      return {\n        slug,\n        name: catalogEntry.name,\n        description: catalogEntry.description,\n        version: \"0.1.0\",\n        requiresSetup: true,\n        authRequired: true,\n        // Health probe: build from env + hit GET /health. When the env is\n        // absent, construction throws — fold that to \"not reachable\" rather\n        // than propagating so a listing probe stays total.\n        check: async () => {\n          try {\n            return await createStandaloneGbrainDocAdapter().healthCheck()\n          } catch {\n            return false\n          }\n        },\n        info() {\n          return {\n            slug,\n            engine: \"gbrain-doc\",\n            capabilities: { hybridSearch: true, needsCreds: true },\n          }\n        },\n        provider: () => createStandaloneGbrainDocAdapter(),\n      }\n    }\n  }\n\n  throw new Error(`unhandled knowledge backend slug: ${slug}`)\n}\n\n/**\n * Build the knowledge resolver: resolves a catalog slug to a handle, returning\n * `null` when the slug is unknown (via the kit's wrapper).\n */\nexport function makeKnowledgeGbrainDocResolver(): AdapterResolver<KnowledgeHandle> {\n  return makeAdapterResolver<KnowledgeHandle>({\n    load: async (slug: string): Promise<KnowledgeHandle> =>\n      resolveKnowledgeBackend(slug),\n  })\n}\n"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@agentproto/adapter-knowledge-gbrain-doc",
+  "version": "0.2.0",
+  "description": "Knowledge adapter: implements @agentproto/knowledge-engine's IKnowledgeProvider over a gbrain server's document API (put_page / search) via pure fetch over its JSON-RPC /mcp endpoint. gbrain fuses lexical (tsvector) + semantic recall. Registers as a provider-kit family. No vendor SDK, no app coupling. Distinct from the code-graph gbrain adapter.",
+  "keywords": [
+    "agentproto",
+    "knowledge-engine",
+    "knowledge",
+    "retrieval",
+    "rag",
+    "gbrain",
+    "document-search",
+    "hybrid-search",
+    "adapter",
+    "provider-kit",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "adapters/knowledge-gbrain-doc"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@agentproto/provider-kit": "0.4.0",
+    "@agentproto/knowledge-engine": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tool": "0.2.1",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}