@braidhq/server 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @braidhq/server
+
+REST + SSE server for Braid. Hono-based, with an OpenAPI 3 spec
+exposed at `GET /openapi.json` for any consumer that wants typed
+access to the graph operations.
+
+## openapi-mcp-gateway Integration
+
+Skills shipped with `@braidhq/core` and `@braidhq/ontology-ddd` invoke
+the server through MCP tools, not curl. The wiring runs the gateway
+as a **per-skill stdio child of claude** — no long-running HTTP
+server, gateway lifecycle tracks the skill run automatically.
+
+```
+┌──────────────────┐   /openapi.json    ┌─────────────────────┐
+│ @braidhq/server  │ ◀───── HTTP ────── │ openapi-mcp-gateway │
+│ (this package)   │ ────── REST  ────▶ │ (uvx, stdio child)  │
+└──────────────────┘                    └─────────────────────┘
+                                                   ▲ stdin/stdout
+                                                   │ MCP
+                                        ┌─────────────────────┐
+                                        │ spawned claude      │
+                                        │ subprocess (skill)  │
+                                        └─────────────────────┘
+```
+
+### 1. Install `uv` (one-time setup)
+
+`openapi-mcp-gateway` is a Python package distributed via PyPI. The
+gateway is launched on demand by claude via `uvx` (UV's "run an
+ephemeral package" command), so the only thing you have to install
+locally is the `uv` runtime itself:
+
+```bash
+# macOS
+brew install uv
+# linux / windows: see https://docs.astral.sh/uv/getting-started/installation/
+```
+
+The Braid server **preflight-checks for `uv` at boot**. If it's not
+found, you'll see:
+
+```
+[braid] `uv` not found on PATH; the built-in braid-core MCP gateway
+        will not be available. Install via `brew install uv` or
+        https://docs.astral.sh/uv/ to enable.
+```
+
+Skills with `requiredMcpServers: ['braid-core']` will then surface
+as not-ready in Studio's sidebar. Other skills keep working.
+
+### 2. That's it
+
+No environment variables to set, no separate gateway process to run.
+When Braid spawns a skill, the skill's mcp-config gets a stdio entry:
+
+```jsonc
+{
+  "braid-core": {
+    "type": "stdio",
+    "command": "uvx",
+    "args": [
+      "openapi-mcp-gateway",
+      "--spec",
+      "http://127.0.0.1:4321/openapi.json",
+      "--transport",
+      "stdio",
+      "--name",
+      "braid-core"
+    ]
+  }
+}
+```
+
+claude spawns the gateway, the gateway pulls the spec from the
+running Braid server, and the REST surface becomes MCP tools for the
+duration of the skill run.
+
+First-time runs take an extra ~1–2 seconds (uvx caches
+`openapi-mcp-gateway` under `~/.cache/uv/`). Subsequent runs hit the
+cache.
+
+### 3. Author skills against the MCP tools
+
+Skill prompts call MCP tools by their `operationId`:
+
+- `braid_search_nodes(workspaceId, q, type?, status?, limit?, offset?)`
+- `braid_get_scope(workspaceId, nodeId, depth)`
+- `braid_get_ontology(workspaceId)`
+- `braid_submit_proposal(workspaceId, operations, generatedBy, rationale)`
+- `braid_submit_clarify(workspaceId, question, candidates)`
+- `braid_mark_clarify_applied(workspaceId, clarifyTicketId, status, userId, proposalId?)`
+- …and the rest, one per operation in `/openapi.json`.
+
+Exact tool names depend on `openapi-mcp-gateway`'s naming convention
+(typically `<server-name>_<operationId>` with snake_case
+normalisation). Inspect the spec or the gateway's `tools/list`
+response to see live names.
+
+### Pinning the uv binary
+
+For reproducibility (e.g. CI environments with multiple Python
+toolchains) you can pin a specific `uvx` binary via the
+`BRAID_UVX_BIN` env var. composeFs preflight-checks the pinned
+binary; if it's not executable, the gateway entry is skipped same as
+when `uv` is missing entirely.
+
+```bash
+export BRAID_UVX_BIN=/opt/homebrew/bin/uvx
+```
+
+### Forward compatibility (hosted Braid)
+
+When Braid grows a hosted product where the server runs remotely:
+
+- If claude runs locally (desktop spawns it): the stdio path above
+  still works. The local gateway just talks HTTPS to the remote
+  `/openapi.json` and REST endpoints, with auth headers passed
+  through workspace-level MCP server config.
+- If claude runs in the cloud (browser Studio): the stdio path runs
+  server-side, gateway loopbacks to the local server.
+
+The `streamable-http` MCP transport stays first-class in the schema
+so workspaces can declare any third-party HTTP MCP server (Redmine /
+Notion / Linear / …) alongside the stdio braid-core. The two
+transports are not mutually exclusive.
+
+## Routes That Are Not in the Spec
+
+- SSE streams (`/workspaces/{ws}/runs/{runId}/events`,
+  `/workspaces/{ws}/events`) — not invocable as one-shot MCP tools.
+- OAuth callbacks (`/oauth/google/callback`) — HTML response.
+- Workspace management (`/workspaces/*`) — admin surface for CLI
+  and Studio, not for skills.
+
+The `GET /openapi.json` test in `test/app.test.ts` pins this list.

package/dist/app.d.ts

@@ -1,7 +1,24 @@
 import type { AppDependencies } from './composition.js';
-import { Hono } from 'hono';
+import { OpenAPIHono } from '@hono/zod-openapi';
 export interface AppOptions {
     readonly corsOrigins?: readonly string[];
+    /**
+     * Base URL the OpenAPI spec advertises in its `servers[]` block. This
+     * is what downstream consumers (openapi-mcp-gateway, Swagger UI, code
+     * generators, …) use to dispatch REST calls. When unset, the spec is
+     * emitted without `servers[]`, which leaves the consumer to guess.
+     * composeFsApp threads its `apiUrl` through here so the gateway can
+     * route REST calls back to this server without an explicit
+     * `--base-url` flag.
+     */
+    readonly apiUrl?: string;
+    /**
+     * When true (or `BRAID_LOCAL_TRUST=true`), the auth middleware lets
+     * every request through and the embedded `userIdMiddleware` falls
+     * back to `local-user`. Set by `composeFs` for the Tauri sidecar;
+     * production remote servers leave it `false`.
+     */
+    readonly localTrust?: boolean;
 }
-export declare function createApp(deps: AppDependencies, options?: AppOptions): Hono;
+export declare function createApp(deps: AppDependencies, options?: AppOptions): OpenAPIHono;
 //# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAkB3B,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,IAAI,CA6D/E"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA8B/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,WAAW,CAwKtF"}

package/dist/app.js

@@ -1,34 +1,108 @@
-import { Hono } from 'hono';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import { authMiddleware } from './middleware/auth.js';
 import { corsMiddleware } from './middleware/cors.js';
 import { errorHandler } from './middleware/error.js';
+import { userIdMiddleware } from './middleware/userId.js';
+import { workspaceAccessMiddleware } from './middleware/workspaceAccess.js';
 import { workspaceIdMiddleware } from './middleware/workspaceId.js';
+import { createAdminRouter } from './routes/admin.js';
+import { createAuthRouter } from './routes/auth.js';
+import { createBatchRouter } from './routes/batch.js';
 import { createClarifyRouter } from './routes/clarify.js';
 import { createDecisionsRouter } from './routes/decisions.js';
 import { createEdgesRouter } from './routes/edges.js';
 import { healthRouter } from './routes/health.js';
+import { createHistoryRouter } from './routes/history.js';
 import { createModelRouter } from './routes/model.js';
 import { createNodesRouter } from './routes/nodes.js';
 import { createOAuthRouter } from './routes/oauth.js';
 import { createOntologyRouter } from './routes/ontology.js';
 import { createProposalsRouter } from './routes/proposals.js';
 import { createRunsRouter } from './routes/runs.js';
+import { createSkillInputOptionsRouter } from './routes/skillInputOptions.js';
 import { createSkillsRouter } from './routes/skills.js';
+import { createSourceLoadersRouter } from './routes/sourceLoaders.js';
+import { createSourceUnitStatesRouter } from './routes/sourceUnitStates.js';
+import { createUsersRouter } from './routes/users.js';
 import { createWorkspaceEventsRouter } from './routes/workspaceEvents.js';
+import { createTransferOwnershipRouter, createWorkspaceMembersRouter } from './routes/workspaceMembers.js';
 import { createWorkspacesRouter } from './routes/workspaces.js';
 export function createApp(deps, options = {}) {
-    const app = new Hono();
+    const app = new OpenAPIHono();
     app.use('*', options.corsOrigins
         ? corsMiddleware({ allowedOrigins: options.corsOrigins })
         : corsMiddleware());
+    // Phase B auth gate. In local-trust mode it short-circuits and lets
+    // the unauthenticated request through; otherwise a Bearer token is
+    // required (Google OAuth-issued session). Public routes — `/auth/*`,
+    // `/health` — are excluded inside the middleware so the login flow
+    // itself isn't gated.
+    if (deps.sessionStore) {
+        const localTrust = options.localTrust ?? deps.localTrust;
+        app.use('*', authMiddleware({
+            sessionStore: deps.sessionStore,
+            localTrust,
+        }));
+    }
+    // Phase A identity. Stamps `c.set('userId', ...)` from `X-Braid-User`
+    // when the auth layer left it empty — i.e. local-trust mode, or any
+    // public route. Bearer-authenticated requests already have a userId
+    // by the time this runs and pass through untouched.
+    app.use('*', userIdMiddleware);
     app.onError(errorHandler);
     app.route('/health', healthRouter);
+    if (deps.sessionStore && deps.accessPolicy && deps.userRegistry) {
+        app.route('/auth', createAuthRouter({
+            clock: deps.clock,
+            sessionStore: deps.sessionStore,
+            accessPolicy: deps.accessPolicy,
+            userRegistry: deps.userRegistry,
+            ...(deps.googleOAuth ? { googleOAuth: deps.googleOAuth } : {}),
+            studioUrl: deps.studioUrl ?? 'http://localhost:5173',
+            localTrust: options.localTrust ?? deps.localTrust,
+        }));
+    }
+    if (deps.userRegistry) {
+        app.route('/users', createUsersRouter({
+            userRegistry: deps.userRegistry,
+            clock: deps.clock,
+        }));
+    }
+    if (deps.userRegistry && deps.accessPolicy && deps.workspaceRegistry) {
+        app.route('/admin', createAdminRouter({
+            userRegistry: deps.userRegistry,
+            accessPolicy: deps.accessPolicy,
+            workspaceRegistry: deps.workspaceRegistry,
+            workspaceService: deps.workspaceService,
+        }));
+    }
     app.route('/workspaces', createWorkspacesRouter({
         workspaceService: deps.workspaceService,
         sourceLoaderRunner: deps.sourceLoaderRunner,
+        workspacesRoot: deps.workspacesRoot,
+        ...(deps.bootstrap ? { bootstrap: deps.bootstrap } : {}),
+        ...(deps.workspaceRegistry ? { workspaceRegistry: deps.workspaceRegistry } : {}),
+        ...(deps.userRegistry ? { userRegistry: deps.userRegistry } : {}),
     }));
     app.route('/workspaces', createWorkspaceEventsRouter({ eventBus: deps.eventBus }));
-    const workspaceScoped = new Hono();
+    // Server-level plugin discovery: lets Studio render its loader dropdown
+    // from the active PluginRegistry rather than hardcoded strings. Not
+    // workspace-scoped because the answer is "what does this server have
+    // installed", which is identical across workspaces.
+    app.route('/source-loaders', createSourceLoadersRouter({ pluginRegistry: deps.pluginRegistry }));
+    const workspaceScoped = new OpenAPIHono();
     workspaceScoped.use('*', workspaceIdMiddleware);
+    // Workspace membership gate. Mounted only when both the workspace
+    // registry and user registry are present (i.e. composeFsApp);
+    // in-memory tests that compose without these stay open so existing
+    // routes keep behaving.
+    if (deps.workspaceRegistry && deps.userRegistry) {
+        workspaceScoped.use('*', workspaceAccessMiddleware({
+            registry: deps.workspaceRegistry,
+            workspaceService: deps.workspaceService,
+            userRegistry: deps.userRegistry,
+        }));
+    }
     workspaceScoped.route('/model', createModelRouter({ modelService: deps.modelService }));
     workspaceScoped.route('/nodes', createNodesRouter({ modelService: deps.modelService }));
     workspaceScoped.route('/edges', createEdgesRouter({ modelService: deps.modelService }));
@@ -37,12 +111,17 @@ export function createApp(deps, options = {}) {
         proposalRepository: deps.proposalRepository,
         modelRepository: deps.modelRepository,
         validationService: deps.validationService,
+        workspaceService: deps.workspaceService,
     }));
     workspaceScoped.route('/clarify', createClarifyRouter({
         hitlService: deps.hitlService,
         clarifyRepository: deps.clarifyRepository,
+        decisionRepository: deps.decisionRepository,
     }));
     workspaceScoped.route('/decisions', createDecisionsRouter({ decisionRepository: deps.decisionRepository }));
+    workspaceScoped.route('/source-unit-states', createSourceUnitStatesRouter({
+        sourceUnitStateService: deps.sourceUnitStateService,
+    }));
     workspaceScoped.route('/ontology', createOntologyRouter({
         workspaceRepository: deps.workspaceRepository,
         pluginRegistry: deps.pluginRegistry,
@@ -59,6 +138,30 @@ export function createApp(deps, options = {}) {
             workspaceRepository: deps.workspaceRepository,
         }));
     }
+    if (deps.historyService) {
+        workspaceScoped.route('/history', createHistoryRouter({ historyService: deps.historyService }));
+    }
+    if (deps.batchService) {
+        workspaceScoped.route('/batch', createBatchRouter({ batchService: deps.batchService }));
+    }
+    workspaceScoped.route('/skill-input-options', createSkillInputOptionsRouter({
+        modelRepository: deps.modelRepository,
+        clarifyRepository: deps.clarifyRepository,
+        workspaceRepository: deps.workspaceRepository,
+        pluginRegistry: deps.pluginRegistry,
+    }));
+    if (deps.workspaceRegistry) {
+        workspaceScoped.route('/members', createWorkspaceMembersRouter({
+            workspaceService: deps.workspaceService,
+            registry: deps.workspaceRegistry,
+            clock: deps.clock,
+        }));
+        workspaceScoped.route('/transfer-ownership', createTransferOwnershipRouter({
+            workspaceService: deps.workspaceService,
+            registry: deps.workspaceRegistry,
+            clock: deps.clock,
+        }));
+    }
     app.route('/workspaces/:workspaceId', workspaceScoped);
     if (deps.secretStore) {
         app.route('/oauth', createOAuthRouter({
@@ -66,6 +169,21 @@ export function createApp(deps, options = {}) {
             ...(deps.googleOAuth ? { google: deps.googleOAuth } : {}),
         }));
     }
+    // OpenAPI 3 spec; consumed by openapi-mcp-gateway to surface REST
+    // operations as MCP tools. SSE routes and the OAuth HTML callback
+    // are intentionally absent — they're mounted via app.route() with
+    // plain Hono sub-routers so they don't register with the OpenAPI
+    // registry. The `servers[]` block lets the gateway resolve the
+    // upstream API base URL without an explicit --base-url flag.
+    app.doc('/openapi.json', {
+        openapi: '3.0.0',
+        info: {
+            title: 'Braid REST API',
+            version: '0.0.1',
+            description: 'REST surface exposed by @braidhq/server. Each operation also becomes an MCP tool via openapi-mcp-gateway.',
+        },
+        ...(options.apiUrl ? { servers: [{ url: options.apiUrl }] } : {}),
+    });
     return app;
 }
 //# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/composeFs.d.ts

@@ -1,5 +1,7 @@
-import type { AgentEffort } from '@braidhq/schema';
+import type { AgentPlugin, OntologyPlugin, SourceLoaderPlugin, StoragePlugin } from '@braidhq/core';
+import type { AgentEffort, StorageKind } from '@braidhq/schema';
 import type { AppDependencies } from './composition.js';
+import { AgentKind } from '@braidhq/schema';
 export interface ComposeFsOptions {
     /** Where to persist registered workspace paths. Default `$BRAID_HOME` or `~/.braid`. */
     readonly braidHome?: string;
@@ -9,12 +11,45 @@ export interface ComposeFsOptions {
     readonly agentModel?: string;
     /** Coding-agent effort tier (default `high`). */
     readonly agentEffort?: AgentEffort;
+    /**
+     * Graph storage backend kind. Resolved against the StoragePlugin
+     * registry; default `kuzu`. Set via `BRAID_STORAGE_KIND` env to swap
+     * (e.g. `neo4j` once `@braidhq/storage-neo4j` is registered).
+     */
+    readonly storageKind?: StorageKind;
+    /** Coding-agent kind to spawn skill subprocesses with. Default `claude-code`. */
+    readonly agentKind?: AgentKind;
+    /**
+     * Extra plugins to register alongside the defaults bundled with this
+     * composition. The defaults bundle is:
+     *   - storage: `kuzuStoragePlugin`
+     *   - ontology: `dddOntology`
+     *   - source-loader: `gitLoader`, `createGithubLoader()`, `createGoogleDriveLoader()`
+     *     (gdrive throws an actionable error at ingest if OAuth env is missing;
+     *     github falls back to anonymous if `${GH_TOKEN}` is unset, subject to
+     *     the 60 req/h public rate limit)
+     *   - agent: `claudeCodeAgentPlugin`
+     *
+     * `composeFsApp` is the opinionated entry that ships with batteries.
+     * Callers who want a different bundle should use `composeApp` directly
+     * with their own pluginRegistry.
+     */
+    readonly extraStoragePlugins?: readonly StoragePlugin[];
+    readonly extraOntologyPlugins?: readonly OntologyPlugin[];
+    readonly extraSourceLoaderPlugins?: readonly SourceLoaderPlugin[];
+    readonly extraAgentPlugins?: readonly AgentPlugin[];
 }
 /**
- * Production composition root: real filesystem persistence for workspaces /
- * proposals / clarify / decisions, built-in skills loaded from `@braidhq/core`,
- * Claude Code subprocess agent. Model storage uses Kuzu (embedded, zero-infra)
- * per workspace at `<workspace>/.braid/model.kuzu`.
+ * Opinionated production composition: real filesystem persistence for
+ * workspaces / proposals / clarify / decisions, built-in skills loaded
+ * from `@braidhq/core`, and a batteries-included plugin bundle (Kuzu
+ * storage / DDD ontology / Git+GDrive source loaders / Claude Code
+ * agent).
+ *
+ * To run with a different plugin set, either:
+ *  1. Pass `extraXxxPlugins` to add alongside defaults + flip `storageKind`
+ *     / `agentKind` to pick a different active one, OR
+ *  2. Call `composeApp` directly with a `pluginRegistry` you built yourself.
  */
-export declare function composeFsApp(options?: ComposeFsOptions): AppDependencies;
+export declare function composeFsApp(options?: ComposeFsOptions): Promise<AppDependencies>;
 //# sourceMappingURL=composeFs.d.ts.map

package/dist/composeFs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composeFs.d.ts","sourceRoot":"","sources":["../src/composeFs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,WAAW,EAAmC,MAAM,iBAAiB,CAAA;AACjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AA+BvD,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA4H5E"}
+{"version":3,"file":"composeFs.d.ts","sourceRoot":"","sources":["../src/composeFs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACnG,OAAO,KAAK,EAAgB,WAAW,EAAE,WAAW,EAAe,MAAM,iBAAiB,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAiBvD,OAAO,EAAW,SAAS,EAAoC,MAAM,iBAAiB,CAAA;AAgCtF,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAE9B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;IACvD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IACzD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACjE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;CACpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyR3F"}