@biolibs/bionet-agent 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -2
- package/dist/index.d.ts +21 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/lookup.d.ts +44 -0
- package/dist/lookup.d.ts.map +1 -0
- package/dist/lookup.js +191 -0
- package/dist/lookup.js.map +1 -0
- package/dist/serve.d.ts +54 -0
- package/dist/serve.d.ts.map +1 -0
- package/dist/serve.js +175 -0
- package/dist/serve.js.map +1 -0
- package/dist/tools.d.ts +118 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +456 -0
- package/dist/tools.js.map +1 -0
- package/package.json +45 -4
- package/src/index.ts +20 -0
- package/src/lookup.ts +208 -0
- package/src/serve.ts +175 -0
- package/src/tools.ts +499 -0
package/dist/serve.js
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The adviser's tools, served to an agent over the Model Context Protocol.
|
|
3
|
+
*
|
|
4
|
+
* It is the smallest server that speaks the protocol's HTTP transport honestly: an agent posts a
|
|
5
|
+
* request and gets a JSON answer. There are no sessions and nothing is streamed, because nothing
|
|
6
|
+
* here takes long or happens unasked.
|
|
7
|
+
*
|
|
8
|
+
* It is a way into somebody's lab, so it is shut by default in every way it can be:
|
|
9
|
+
*
|
|
10
|
+
* - it listens on this machine only, never on the network;
|
|
11
|
+
* - every request has to carry the token, compared in constant time;
|
|
12
|
+
* - a request that says it comes from a web page is refused, and so is one addressed to any name
|
|
13
|
+
* but this machine's, which is how a page in a browser would otherwise reach a server like this;
|
|
14
|
+
* - and behind it the tools themselves can only read, work things out and propose.
|
|
15
|
+
*/
|
|
16
|
+
import { randomBytes, timingSafeEqual } from "node:crypto";
|
|
17
|
+
import { createServer } from "node:http";
|
|
18
|
+
import { AGENT_INSTRUCTIONS } from "./tools.js";
|
|
19
|
+
/** The versions of the protocol this speaks, newest first. */
|
|
20
|
+
export const PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
|
|
21
|
+
/** The most one request may be, in bytes. A sequence is the largest thing an agent sends. */
|
|
22
|
+
const MOST_BYTES = 2_000_000;
|
|
23
|
+
/** @returns A new token: 32 random bytes, in base64url. Whoever has it can reach the adviser's tools. */
|
|
24
|
+
export const newAgentToken = () => randomBytes(32).toString("base64url");
|
|
25
|
+
const sameText = (a, b) => {
|
|
26
|
+
const [left, right] = [Buffer.from(a), Buffer.from(b)];
|
|
27
|
+
return left.length === right.length && timingSafeEqual(left, right);
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Answer one message of the protocol.
|
|
31
|
+
*
|
|
32
|
+
* @param message - What arrived.
|
|
33
|
+
* @param tools - The tools on offer.
|
|
34
|
+
* @param about - What to call this server and its version.
|
|
35
|
+
* @returns The answer, or `null` if the message was a notification.
|
|
36
|
+
*/
|
|
37
|
+
export async function answerAgent(message, tools, about) {
|
|
38
|
+
const asked = message;
|
|
39
|
+
const id = asked !== null && typeof asked === "object" && (typeof asked.id === "string" || typeof asked.id === "number") ? asked.id : null;
|
|
40
|
+
const fail = (code, says) => ({ jsonrpc: "2.0", id, error: { code, message: says } });
|
|
41
|
+
if (asked === null || typeof asked !== "object" || asked.jsonrpc !== "2.0" || typeof asked.method !== "string")
|
|
42
|
+
return fail(-32600, "That is not a request.");
|
|
43
|
+
// A notification is told, not asked: it has no ID and gets no answer.
|
|
44
|
+
if (asked.id === undefined)
|
|
45
|
+
return null;
|
|
46
|
+
const done = (result) => ({ jsonrpc: "2.0", id, result });
|
|
47
|
+
switch (asked.method) {
|
|
48
|
+
case "initialize": {
|
|
49
|
+
const wanted = asked.params?.["protocolVersion"];
|
|
50
|
+
const version = PROTOCOL_VERSIONS.includes(wanted) ? wanted : PROTOCOL_VERSIONS[0];
|
|
51
|
+
return done({ protocolVersion: version, capabilities: { tools: { listChanged: false } }, serverInfo: { name: about.name, version: about.version }, instructions: AGENT_INSTRUCTIONS });
|
|
52
|
+
}
|
|
53
|
+
case "ping": return done({});
|
|
54
|
+
case "tools/list":
|
|
55
|
+
return done({ tools: tools.map((tool) => ({
|
|
56
|
+
name: tool.name, title: tool.title, description: tool.description, inputSchema: tool.input,
|
|
57
|
+
annotations: { title: tool.title, readOnlyHint: tool.readOnly, destructiveHint: false, idempotentHint: tool.readOnly, openWorldHint: false },
|
|
58
|
+
})) });
|
|
59
|
+
case "tools/call": {
|
|
60
|
+
const tool = tools.find((one) => one.name === asked.params?.["name"]);
|
|
61
|
+
if (tool === undefined)
|
|
62
|
+
return fail(-32602, `There is no tool called ${JSON.stringify(asked.params?.["name"] ?? null)}.`);
|
|
63
|
+
const args = asked.params?.["arguments"];
|
|
64
|
+
if (!(args === undefined || (typeof args === "object" && args !== null && !Array.isArray(args))))
|
|
65
|
+
return fail(-32602, "A tool's arguments are given by name.");
|
|
66
|
+
const given = (args ?? {});
|
|
67
|
+
// Something the tool was not told to expect is refused, not ignored: an agent that sends it
|
|
68
|
+
// meant something by it, and going on without it would do other than it asked.
|
|
69
|
+
const stray = Object.keys(given).find((name) => !(name in tool.input.properties));
|
|
70
|
+
const missing = (tool.input.required ?? []).find((name) => given[name] === undefined);
|
|
71
|
+
try {
|
|
72
|
+
if (stray !== undefined)
|
|
73
|
+
throw new Error(`${tool.name} takes nothing called ${JSON.stringify(stray)}. It takes: ${Object.keys(tool.input.properties).join(", ") || "nothing"}.`);
|
|
74
|
+
if (missing !== undefined)
|
|
75
|
+
throw new Error(`${tool.name} needs ${JSON.stringify(missing)}.`);
|
|
76
|
+
return done({ content: [{ type: "text", text: JSON.stringify(await tool.run(given), null, 1) }] });
|
|
77
|
+
}
|
|
78
|
+
catch (cause) {
|
|
79
|
+
// A tool that could not do what was asked says why to the agent, which can then do something about it.
|
|
80
|
+
return done({ content: [{ type: "text", text: cause instanceof Error ? cause.message : String(cause) }], isError: true });
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
default: return fail(-32601, `This server does not do ${JSON.stringify(asked.method)}.`);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Serve the adviser's tools on this machine.
|
|
88
|
+
*
|
|
89
|
+
* @param options - `tools` are the tools; `token` is what every request has to carry, as a bearer
|
|
90
|
+
* token; `port` is the port to take, or 0 for any that is free; `name` and `version` are what the
|
|
91
|
+
* server calls itself.
|
|
92
|
+
* @returns Where it is listening, and a way to stop it.
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```ts
|
|
96
|
+
* import { agentTools, newAgentToken, serveAgent } from "@biolibs/bionet-agent";
|
|
97
|
+
*
|
|
98
|
+
* const token = newAgentToken();
|
|
99
|
+
* const server = await serveAgent({ tools: agentTools(lab), token });
|
|
100
|
+
* server.url; // http://127.0.0.1:53124/mcp — give this and the token to the agent
|
|
101
|
+
* ```
|
|
102
|
+
*/
|
|
103
|
+
export async function serveAgent(options) {
|
|
104
|
+
if (options.token.length < 32)
|
|
105
|
+
throw new Error("The token is too short to keep anybody out.");
|
|
106
|
+
const about = { name: options.name ?? "bionet-adviser", version: options.version ?? "0.1.0" };
|
|
107
|
+
let port = 0;
|
|
108
|
+
const say = (response, status, body, more = {}) => {
|
|
109
|
+
const text = body === null ? "" : JSON.stringify(body);
|
|
110
|
+
response.writeHead(status, { ...(body === null ? {} : { "content-type": "application/json" }), "cache-control": "no-store", ...more });
|
|
111
|
+
response.end(text);
|
|
112
|
+
};
|
|
113
|
+
const read = (request) => new Promise((resolve) => {
|
|
114
|
+
const chunks = [];
|
|
115
|
+
let size = 0;
|
|
116
|
+
request.on("data", (chunk) => {
|
|
117
|
+
size += chunk.length;
|
|
118
|
+
// Past the limit the rest is let go by without being kept, so that whoever sent it can be
|
|
119
|
+
// told it was too much instead of having the line cut under them.
|
|
120
|
+
if (size <= MOST_BYTES)
|
|
121
|
+
chunks.push(chunk);
|
|
122
|
+
else
|
|
123
|
+
chunks.length = 0;
|
|
124
|
+
});
|
|
125
|
+
request.on("end", () => resolve(size > MOST_BYTES ? null : Buffer.concat(chunks).toString("utf8")));
|
|
126
|
+
request.on("error", () => resolve(null));
|
|
127
|
+
});
|
|
128
|
+
const server = createServer((request, response) => {
|
|
129
|
+
void (async () => {
|
|
130
|
+
// A browser says where a request comes from and which name it was sent to. Nothing that is
|
|
131
|
+
// meant to use this is a web page, and nothing that is meant to use it calls it by another name.
|
|
132
|
+
if (request.headers.origin !== undefined)
|
|
133
|
+
return say(response, 403, { error: "This is not for web pages." });
|
|
134
|
+
const host = request.headers.host ?? "";
|
|
135
|
+
if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`)
|
|
136
|
+
return say(response, 403, { error: "This answers only to this machine's own name." });
|
|
137
|
+
if (new URL(request.url ?? "/", "http://x").pathname !== "/mcp")
|
|
138
|
+
return say(response, 404, { error: "There is nothing here." });
|
|
139
|
+
const given = /^Bearer (.+)$/.exec(request.headers.authorization ?? "")?.[1] ?? "";
|
|
140
|
+
if (!sameText(given, options.token))
|
|
141
|
+
return say(response, 401, { error: "That is not this adviser's token." }, { "www-authenticate": "Bearer" });
|
|
142
|
+
// Nothing is sent unasked, so there is no stream to open and no session to end.
|
|
143
|
+
if (request.method !== "POST")
|
|
144
|
+
return say(response, 405, { error: "Ask by POST." }, { allow: "POST" });
|
|
145
|
+
const body = await read(request);
|
|
146
|
+
if (body === null)
|
|
147
|
+
return say(response, 413, { error: "That is more than one request may be." });
|
|
148
|
+
let message;
|
|
149
|
+
try {
|
|
150
|
+
message = JSON.parse(body);
|
|
151
|
+
}
|
|
152
|
+
catch {
|
|
153
|
+
return say(response, 400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "That is not JSON." } });
|
|
154
|
+
}
|
|
155
|
+
if (Array.isArray(message)) {
|
|
156
|
+
const answers = (await Promise.all(message.map((one) => answerAgent(one, options.tools, about)))).filter((one) => one !== null);
|
|
157
|
+
return answers.length === 0 ? say(response, 202, null) : say(response, 200, answers);
|
|
158
|
+
}
|
|
159
|
+
const answer = await answerAgent(message, options.tools, about);
|
|
160
|
+
return answer === null ? say(response, 202, null) : say(response, 200, answer);
|
|
161
|
+
})().catch(() => { if (!response.headersSent)
|
|
162
|
+
say(response, 500, { error: "Something went wrong here." }); });
|
|
163
|
+
});
|
|
164
|
+
await new Promise((resolve, reject) => {
|
|
165
|
+
server.once("error", reject);
|
|
166
|
+
// This machine only: never every address the machine has.
|
|
167
|
+
server.listen(options.port ?? 0, "127.0.0.1", resolve);
|
|
168
|
+
});
|
|
169
|
+
port = server.address().port;
|
|
170
|
+
return {
|
|
171
|
+
url: `http://127.0.0.1:${port}/mcp`, port,
|
|
172
|
+
close: () => new Promise((resolve) => { server.close(() => resolve()); server.closeAllConnections(); }),
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
//# sourceMappingURL=serve.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}
|
package/dist/tools.d.ts
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What an adviser is given to work with: the lab to read, the lab's own tools to work things out
|
|
3
|
+
* with, and three things it may write.
|
|
4
|
+
*
|
|
5
|
+
* Every tool here is a plain function over a lab, described well enough for something that has
|
|
6
|
+
* never seen this code to use it. Nothing in this file knows how the tools are reached: `serve.ts`
|
|
7
|
+
* hands them over the Model Context Protocol, and a test calls them directly.
|
|
8
|
+
*
|
|
9
|
+
* Two things shape all of it.
|
|
10
|
+
*
|
|
11
|
+
* - **The adviser has no hands.** It can say what would happen and propose that somebody do it. It
|
|
12
|
+
* cannot say that anything was done, used or moved, and there is no tool here that tries: the
|
|
13
|
+
* lab would refuse it anyway, on every device, because of the role its key has.
|
|
14
|
+
* - **It is shown the working, not asked to believe.** What a tool works out comes from the same
|
|
15
|
+
* engines the lab's own windows use, so a proposal the adviser makes is one a person at the bench
|
|
16
|
+
* can set up and see the same numbers for.
|
|
17
|
+
*/
|
|
18
|
+
import type { Lab } from "@biolibs/bionet-client";
|
|
19
|
+
import { type LookupOptions } from "./lookup.js";
|
|
20
|
+
/** A JSON schema for what a tool takes: always an object, with these properties. */
|
|
21
|
+
export interface ToolInput {
|
|
22
|
+
type: "object";
|
|
23
|
+
properties: Record<string, Record<string, unknown>>;
|
|
24
|
+
required?: string[];
|
|
25
|
+
additionalProperties: false;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* What a tool's use would look like in the lab, for a window that wants to show the adviser at work.
|
|
29
|
+
* It is shaped like a stop on the demo's walk, which is already how a bench is told what to show.
|
|
30
|
+
*/
|
|
31
|
+
export type AgentShows = {
|
|
32
|
+
at: "lab";
|
|
33
|
+
focus: {
|
|
34
|
+
place: string | null;
|
|
35
|
+
item?: string;
|
|
36
|
+
};
|
|
37
|
+
} | {
|
|
38
|
+
at: "sequences";
|
|
39
|
+
part: string;
|
|
40
|
+
} | {
|
|
41
|
+
at: "primers";
|
|
42
|
+
part: string;
|
|
43
|
+
from: number;
|
|
44
|
+
to: number;
|
|
45
|
+
} | {
|
|
46
|
+
at: "pcr";
|
|
47
|
+
start: {
|
|
48
|
+
view: "result" | "tube";
|
|
49
|
+
template?: string;
|
|
50
|
+
forward?: string;
|
|
51
|
+
reverse?: string;
|
|
52
|
+
};
|
|
53
|
+
} | {
|
|
54
|
+
at: "digest";
|
|
55
|
+
start: {
|
|
56
|
+
view: "result" | "tube";
|
|
57
|
+
tube: string;
|
|
58
|
+
enzymes: string[];
|
|
59
|
+
};
|
|
60
|
+
} | {
|
|
61
|
+
at: "ligation";
|
|
62
|
+
start: {
|
|
63
|
+
view: "result" | "tube";
|
|
64
|
+
tubes: string[];
|
|
65
|
+
};
|
|
66
|
+
};
|
|
67
|
+
/** One tool an adviser can use. */
|
|
68
|
+
export interface AgentTool {
|
|
69
|
+
/** What it is called over the wire. */
|
|
70
|
+
name: string;
|
|
71
|
+
/** What it is called for a person. */
|
|
72
|
+
title: string;
|
|
73
|
+
/** What it does, when to use it, and what comes back. */
|
|
74
|
+
description: string;
|
|
75
|
+
/** What it takes. */
|
|
76
|
+
input: ToolInput;
|
|
77
|
+
/** Whether it only reads and works things out. The three that write say `false`. */
|
|
78
|
+
readOnly: boolean;
|
|
79
|
+
/** Do it. Throws, with a sentence a person could act on, if it cannot be done. */
|
|
80
|
+
run: (args: Record<string, unknown>) => Promise<unknown>;
|
|
81
|
+
}
|
|
82
|
+
/** One use of a tool, as a host is told of it. */
|
|
83
|
+
export interface AgentCall {
|
|
84
|
+
/** Which tool. */
|
|
85
|
+
tool: string;
|
|
86
|
+
/** What it was given. */
|
|
87
|
+
args: Record<string, unknown>;
|
|
88
|
+
/** Whether it worked. */
|
|
89
|
+
ok: boolean;
|
|
90
|
+
/** What it would look like in the lab, if it has a place there. */
|
|
91
|
+
shows: AgentShows | null;
|
|
92
|
+
}
|
|
93
|
+
/** What is said to an agent before it uses anything: who it is here, and how to treat what it reads. */
|
|
94
|
+
export declare const AGENT_INSTRUCTIONS: string;
|
|
95
|
+
/** The longest stretch of a sequence handed back at once, in bases. A whole genome is not something to read in one go. */
|
|
96
|
+
export declare const MOST_BASES = 20000;
|
|
97
|
+
/**
|
|
98
|
+
* The tools an adviser hosted on a device is given.
|
|
99
|
+
*
|
|
100
|
+
* @param lab - The lab, opened, on a device that hosts an adviser.
|
|
101
|
+
* @param options - `watch` is told of each use, with what it would look like in the lab, so that a
|
|
102
|
+
* window can show the adviser at work; `outside` says whether to offer the tools that look
|
|
103
|
+
* something up at NCBI, and what to tell NCBI about who is asking.
|
|
104
|
+
* @returns The tools, in the order to list them.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```ts
|
|
108
|
+
* import { agentTools } from "@biolibs/bionet-agent";
|
|
109
|
+
*
|
|
110
|
+
* const tools = agentTools(lab);
|
|
111
|
+
* const overview = await tools.find((one) => one.name === "lab_overview")!.run({});
|
|
112
|
+
* ```
|
|
113
|
+
*/
|
|
114
|
+
export declare function agentTools(lab: Lab, options?: {
|
|
115
|
+
watch?: (call: AgentCall) => void;
|
|
116
|
+
outside?: LookupOptions;
|
|
117
|
+
}): AgentTool[];
|
|
118
|
+
//# sourceMappingURL=tools.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,GAAG,EAAW,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAI9D,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,KAAK,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC7D;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACxG;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAAE,GACrF;IAAE,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAE5E,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,oFAAoF;IACpF,QAAQ,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,yBAAyB;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,mEAAmE;IACnE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CAC1B;AAED,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,QAQnB,CAAC;AAgBb,0HAA0H;AAC1H,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAA;CAAO,GAAG,SAAS,EAAE,CA+X9H"}
|