@jini-ai/mcp 0.1.0

package/dist/client/client.js

@@ -0,0 +1,242 @@
+/**
+ * @module @jini-ai/mcp/client/client
+ * Product-neutral runtime primitives for a stdio MCP server: an idle-exit
+ * controller that auto-closes an idle server process, a relative-reference
+ * extractor that walks HTML/CSS/JS text to find sibling files to bundle, and a
+ * textual-MIME classifier. Dependency-free (node stdlib only); imports no
+ * sibling MCP subdirectory.
+ */
+// These are the generic, product-agnostic building blocks that back a stdio
+// MCP server's lifecycle and its "pull an entry file plus everything it
+// references" bundling. They hold no state beyond the idle controller's own
+// timer and never touch the network or filesystem, so they unit-test against
+// plain values.
+// SEC-RB-011: an unvalidated `idleMs` (negative, `NaN`, `Infinity`, or a
+// non-integer) would either schedule an immediately/never-firing timer or
+// hand `setTimeout` a value it silently coerces in surprising ways. Bound it
+// to a sane, documented range instead: reject anything that isn't a finite
+// positive integer (a caller bug, not something to silently paper over), and
+// clamp anything absurdly large down to a one-day ceiling rather than
+// scheduling an effectively-infinite timer.
+const MIN_IDLE_MS = 1;
+const MAX_IDLE_MS = 24 * 60 * 60 * 1000; // 24h
+function normalizeIdleMs(idleMs) {
+    if (typeof idleMs !== 'number' || !Number.isFinite(idleMs) || !Number.isInteger(idleMs) || idleMs < MIN_IDLE_MS) {
+        throw new RangeError(`createMcpIdleExitController: idleMs must be a finite positive integer (>= ${MIN_IDLE_MS}ms), got ${String(idleMs)}`);
+    }
+    return Math.min(idleMs, MAX_IDLE_MS);
+}
+/**
+ * Create an idle-exit controller that calls `onIdle` after `idleMs` of
+ * inactivity. Activity is tracked via `noteActivity()` and `trackRequest()`;
+ * in-flight requests defer the idle timer. Used to auto-close a long-running
+ * stdio MCP server process after a period of no tool calls.
+ * @param options Idle duration in ms (finite positive integer, clamped to a
+ *   24h ceiling — throws `RangeError` otherwise) and the callback to invoke on idle.
+ * @returns An object with `noteActivity`, `trackRequest`, and `dispose` methods.
+ */
+export function createMcpIdleExitController({ idleMs, onIdle, }) {
+    const effectiveIdleMs = normalizeIdleMs(idleMs);
+    let timer = null;
+    let inFlight = 0;
+    let disposed = false;
+    const clear = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    };
+    const schedule = () => {
+        if (disposed)
+            return;
+        clear();
+        timer = setTimeout(() => {
+            // `dispose()` always clears the pending timer and `schedule()` bails when
+            // already disposed, so this callback can only fire while live.
+            timer = null;
+            if (inFlight > 0) {
+                schedule();
+                return;
+            }
+            disposed = true;
+            onIdle();
+        }, effectiveIdleMs);
+    };
+    schedule();
+    return {
+        noteActivity() {
+            schedule();
+        },
+        async trackRequest(fn) {
+            if (disposed) {
+                return fn();
+            }
+            inFlight += 1;
+            // Deliberately does NOT call `schedule()` here (SEC-RB-011): a request
+            // starting while the timer is already running doesn't need to reset
+            // the deadline — the timer, if it fires mid-flight, already re-checks
+            // `inFlight` and reschedules itself (above), and completion below
+            // reschedules once the last in-flight request finishes. Rescheduling
+            // on every concurrent request start instead caused needless
+            // clearTimeout/setTimeout churn under load with no behavioral benefit.
+            try {
+                return await fn();
+            }
+            finally {
+                inFlight -= 1;
+                if (inFlight === 0) {
+                    schedule();
+                }
+            }
+        },
+        dispose() {
+            disposed = true;
+            clear();
+        },
+    };
+}
+// Mimes whose body a stdio MCP server can surface as `text` content.
+const TEXTUAL_MIME_PATTERNS = [
+    /^text\//i,
+    /^application\/json\b/i,
+    /^application\/javascript\b/i,
+    /^application\/typescript\b/i,
+    /^application\/xml\b/i,
+    /^application\/x-(yaml|toml|httpd-php|sh)\b/i,
+    /\+json\b/i,
+    /\+xml\b/i,
+    /^image\/svg\+xml\b/i,
+];
+/**
+ * True when `mime` names a textual content type whose body can be surfaced
+ * as MCP `text` content (text/*, JSON, JS/TS, XML, YAML/TOML/PHP/sh, `+json`
+ * / `+xml` suffixes, and SVG). Returns false for an absent/unknown mime.
+ * @param mime The MIME type string to classify (undefined counts as non-textual).
+ * @returns Whether the content should be treated as text.
+ */
+export function isTextualMime(mime) {
+    if (!mime)
+        return false;
+    return TEXTUAL_MIME_PATTERNS.some((re) => re.test(mime));
+}
+// Patterns common to HTML and CSS (also fine to run on plain markdown).
+const HTML_REF_PATTERNS = [
+    /<script\b[^>]*\bsrc=["']([^"']+)["']/gi,
+    /<link\b[^>]*\bhref=["']([^"']+)["']/gi,
+    /<img\b[^>]*\bsrc=["']([^"']+)["']/gi,
+    /<source\b[^>]*\bsrc=["']([^"']+)["']/gi,
+    /<video\b[^>]*\bsrc=["']([^"']+)["']/gi,
+    /<audio\b[^>]*\bsrc=["']([^"']+)["']/gi,
+    /<iframe\b[^>]*\bsrc=["']([^"']+)["']/gi,
+];
+const CSS_REF_PATTERNS = [
+    /\burl\(\s*["']?([^"')]+)["']?\s*\)/gi,
+    /@import\s+(?:url\()?\s*["']([^"')]+)["']/gi,
+];
+// JS/TS only - running these on prose creates false positives on words
+// like "imported from 'X'".
+const JS_REF_PATTERNS = [
+    /\bimport\s+[^'"]*?['"]([^'"]+)['"]/g,
+    /\bfrom\s+['"]([^'"]+)['"]/g,
+    /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+// `srcset` can list multiple comma-separated candidates.
+const SRCSET_PATTERN = /\bsrcset=["']([^"']+)["']/gi;
+function isJsLike(mime, fromPath) {
+    if (mime && /javascript|typescript/i.test(mime))
+        return true;
+    return /\.(?:m?jsx?|tsx?|cjs)$/i.test(fromPath);
+}
+function isCssLike(mime, fromPath) {
+    if (mime && /^text\/css\b/i.test(mime))
+        return true;
+    return /\.css$/i.test(fromPath);
+}
+function isHtmlLike(mime, fromPath) {
+    if (mime && /^text\/html\b/i.test(mime))
+        return true;
+    return /\.html?$/i.test(fromPath);
+}
+/**
+ * Extract all relative (non-absolute, non-CDN, non-data-URI) file references from
+ * the text content of a file, normalized to root-relative paths.
+ * Runs HTML, CSS, and/or JS pattern sets based on the file's MIME type and extension.
+ * Skips `https?:`, `//`, `data:`, `mailto:`, `tel:`, and `#` prefixes; drops any
+ * reference that would escape the root via `..` traversal.
+ * @param text The textual content of the file.
+ * @param fromPath The root-relative path of the file (used for relative-path resolution).
+ * @param fromMime The MIME type of the file (used to select reference-extraction patterns).
+ * @returns Deduplicated root-relative paths of all referenced files found.
+ */
+export function extractRelativeRefs(text, fromPath, fromMime) {
+    if (!text)
+        return [];
+    const refs = new Set();
+    const runPatterns = [];
+    if (isHtmlLike(fromMime, fromPath)) {
+        runPatterns.push(...HTML_REF_PATTERNS, ...CSS_REF_PATTERNS);
+    }
+    if (isCssLike(fromMime, fromPath)) {
+        runPatterns.push(...CSS_REF_PATTERNS);
+    }
+    if (isJsLike(fromMime, fromPath)) {
+        runPatterns.push(...JS_REF_PATTERNS);
+    }
+    // Fallback for unknown textual files: only the safest pattern,
+    // url() in case it's a CSS-in-something we don't recognize.
+    if (runPatterns.length === 0) {
+        runPatterns.push(...CSS_REF_PATTERNS);
+    }
+    const candidates = [];
+    for (const re of runPatterns) {
+        for (const m of text.matchAll(re)) {
+            // The capture group is required in every pattern, so `m[1]` is always a
+            // matched string here (the `!` only satisfies noUncheckedIndexedAccess).
+            const ref = m[1].trim();
+            if (ref)
+                candidates.push(ref);
+        }
+    }
+    // Pull every candidate URL out of any srcset attributes in HTML.
+    if (isHtmlLike(fromMime, fromPath)) {
+        for (const m of text.matchAll(SRCSET_PATTERN)) {
+            const list = m[1];
+            for (const part of list.split(',')) {
+                const url = part.trim().split(/\s+/)[0];
+                if (url)
+                    candidates.push(url);
+            }
+        }
+    }
+    for (const raw of candidates) {
+        if (/^(?:https?:|\/\/|data:|mailto:|tel:|#)/i.test(raw))
+            continue;
+        const dir = fromPath.includes('/')
+            ? fromPath.slice(0, fromPath.lastIndexOf('/') + 1)
+            : '';
+        const resolved = raw.startsWith('/') ? raw.slice(1) : dir + raw;
+        const stripped = resolved.replace(/[?#].*$/, '');
+        const segs = stripped.split('/').filter(Boolean);
+        const out = [];
+        let escaped = false;
+        for (const s of segs) {
+            if (s === '.')
+                continue;
+            if (s === '..') {
+                if (out.length === 0) {
+                    escaped = true;
+                    break;
+                }
+                out.pop();
+                continue;
+            }
+            out.push(s);
+        }
+        if (escaped || out.length === 0)
+            continue;
+        refs.add(out.join('/'));
+    }
+    return [...refs];
+}
+//# sourceMappingURL=client.js.map

package/dist/client/client.js.map

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

package/dist/client/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module @jini-ai/mcp/client
+ * Product-neutral runtime primitives for a stdio MCP server: the idle-exit
+ * controller, the relative-reference extractor, and the textual-MIME
+ * classifier. Depends on node stdlib only; imports no sibling MCP subdirectory.
+ */
+export * from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,aAAa,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,8 @@
+/**
+ * @module @jini-ai/mcp/client
+ * Product-neutral runtime primitives for a stdio MCP server: the idle-exit
+ * controller, the relative-reference extractor, and the textual-MIME
+ * classifier. Depends on node stdlib only; imports no sibling MCP subdirectory.
+ */
+export * from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,aAAa,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @module @jini-ai/mcp/core/config
+ * Config schema + on-disk store for the external MCP servers the daemon connects
+ * to as a client, plus the per-agent config builders (Claude `.mcp.json`, ACP
+ * `mcpServers`, OpenCode) that hand those servers to a launching agent. Part of
+ * the MCP `core` kernel; depends on no sibling subdirectory.
+ */
+/** Wire-level transport discriminator for how the daemon connects to an external MCP server. */
+export type McpTransport = 'stdio' | 'sse' | 'http';
+/** Authentication mode for remote MCP servers: `'none'` for local/loopback targets, `'oauth'` for remote ones. */
+export type McpAuthMode = 'none' | 'oauth';
+/**
+ * Persisted configuration for a single external MCP server the user has added.
+ * Stored as an element of `McpConfig.servers` in `<dataDir>/mcp-config.json`.
+ */
+export interface McpServerConfig {
+    id: string;
+    label?: string;
+    transport: McpTransport;
+    enabled: boolean;
+    authMode?: McpAuthMode;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/** Top-level on-disk shape of `<dataDir>/mcp-config.json`. */
+export interface McpConfig {
+    servers: McpServerConfig[];
+}
+/**
+ * Infer the appropriate `McpAuthMode` for a given server URL.
+ * Returns `'none'` for loopback targets (localhost, 127.x.x.x, ::1)
+ * and `'oauth'` for everything else, including when `rawUrl` is absent or unparseable.
+ * @param rawUrl The server URL string to inspect, if any.
+ * @returns The inferred `McpAuthMode`.
+ */
+export declare function inferMcpAuthModeForUrl(rawUrl: string | undefined): McpAuthMode;
+/**
+ * Validate a single user-supplied entry. Drops invalid fields so a typo in
+ * one server doesn't tank the whole config. Returns null when the entry is
+ * unsalvageable (no id, or no transport-required fields).
+ */
+export declare function sanitizeMcpServer(raw: unknown): McpServerConfig | null;
+/**
+ * Coerce and de-duplicate a freeform JSON blob into a valid `McpConfig`.
+ * Entries that fail `sanitizeMcpServer` are silently dropped; duplicate ids
+ * are kept first-wins. Returns `{ servers: [] }` for any non-object input.
+ * @param raw The raw parsed JSON to sanitize.
+ * @returns A clean `McpConfig` guaranteed to have only valid, unique server entries.
+ */
+export declare function sanitizeMcpConfig(raw: unknown): McpConfig;
+/**
+ * Read and sanitize the MCP config from `<dataDir>/mcp-config.json`.
+ * Returns `{ servers: [] }` when the file does not exist or contains invalid JSON.
+ * @param dataDir The resolved runtime data directory.
+ * @returns The sanitized `McpConfig`, never rejects on missing-file or corrupt-JSON.
+ */
+export declare function readMcpConfig(dataDir: string): Promise<McpConfig>;
+/**
+ * Sanitize and atomically write the MCP config to `<dataDir>/mcp-config.json`.
+ * Uses a per-`dataDir` promise-chain mutex so concurrent writes serialize
+ * instead of racing. The body is sanitized through `sanitizeMcpConfig` before
+ * being written. This file may carry environment variables and
+ * `Authorization` header values (API keys, bearer tokens — see
+ * `McpServerConfig.env`/`.headers`), so it is written with owner-only
+ * (0600) permissions from the very first byte via `writeSecretFileAtomic`
+ * rather than a post-rename chmod (CR-006 / SEC-RB-002).
+ * @param dataDir The resolved runtime data directory.
+ * @param body The raw config body to sanitize and persist.
+ * @returns The sanitized `McpConfig` that was written to disk.
+ */
+export declare function writeMcpConfig(dataDir: string, body: unknown): Promise<McpConfig>;
+/**
+ * True when `cwd` is a daemon-managed project directory under `projectsDir`
+ * (= safe to write `.mcp.json` into without risk of clobbering a user-owned
+ * file). Git-linked projects whose cwd points at the user's own repo, and
+ * the no-project fallback that resolves to the project root, both return false
+ * — the daemon must NOT write external-MCP config into either of those.
+ *
+ * Both `cwd` and `projectsDir` are realpath-resolved before the containment
+ * check (falling back to lexical `path.resolve` normalization for a path
+ * that doesn't exist on disk yet), and containment is decided with
+ * `@jini-ai/platform`'s separator-aware `pathContains` rather than a raw
+ * string-prefix check — a `..`-containing path or a symlinked descendant
+ * can defeat a plain `startsWith` (CR-006 / SEC-RB-011).
+ */
+export declare function isManagedProjectCwd(cwd: string | null | undefined, projectsDir: string): boolean;
+/**
+ * Project-cwd `.mcp.json` shape that Claude Code auto-loads on spawn (the
+ * same format Claude Desktop and Cursor use). Returns null when the user
+ * has no enabled servers — in that case the caller should NOT write the
+ * file (and should clean up any stale one).
+ *
+ * `tokens` is an optional map of `serverId -> bearer access token`, used
+ * for HTTP/SSE servers that completed the daemon's web OAuth flow. When a
+ * token is present we inject `Authorization: Bearer <token>` into the
+ * server's headers — this is what bypasses the per-spawn `mcp-remote`
+ * dance and lets Claude Code talk directly to the upstream MCP using
+ * pre-authenticated credentials. User-supplied headers always win on
+ * conflict so they can pin a specific token if they really want to.
+ */
+export declare function buildClaudeMcpJson(servers: McpServerConfig[], tokens?: Record<string, string>): unknown | null;
+/**
+ * Convert user-configured external MCP servers into the ACP `mcpServers`
+ * shape that stdio-capable ACP agents accept.
+ * SSE/HTTP servers are dropped — ACP currently models stdio only.
+ */
+export interface AcpMcpServer {
+    type: 'stdio';
+    name: string;
+    command: string;
+    args: string[];
+    env: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+/**
+ * Convert user-configured external MCP servers into the ACP `mcpServers` array.
+ * Only stdio servers are included — SSE/HTTP are dropped because ACP currently
+ * models stdio only. Returns an empty array when no enabled stdio servers exist.
+ * @param servers The full server list from `McpConfig`.
+ * @returns ACP-shaped server entries for all enabled stdio servers.
+ */
+export declare function buildAcpMcpServers(servers: McpServerConfig[]): AcpMcpServer[];
+/**
+ * OpenCode merges its config from multiple sources at boot — global
+ * `~/.config/opencode/opencode.json`, the `OPENCODE_CONFIG` file path, the
+ * project `opencode.json`, and the `OPENCODE_CONFIG_CONTENT` env var (an
+ * inline JSON string). The env-var path is what lets a launcher hand servers
+ * to a single `opencode run` invocation without writing into the user's
+ * global config or leaving a temp file around on crash. We also use the same
+ * payload to grant `external_directory` access to launcher-selected absolute
+ * paths (project cwd, staged skill dirs, etc.) so headless OpenCode runs do
+ * not auto-reject them.
+ *
+ * Returns `null` when nothing would be emitted — the caller must NOT set
+ * `OPENCODE_CONFIG_CONTENT` to `null`/empty in that case, because doing so
+ * would override the user's saved global config with an empty object. A
+ * null return means "leave the env untouched and let OpenCode read the
+ * user's home-dir config as-is."
+ *
+ * The OAuth Bearer merge mirrors `buildClaudeMcpJson` so a remote MCP
+ * server the daemon already authenticated against works the same way for
+ * OpenCode users without forcing them to re-authenticate inside OpenCode.
+ */
+/** Options for `buildOpenCodeMcpConfigContent`. */
+export interface OpenCodeConfigBuildOptions {
+    /** Absolute filesystem paths OpenCode's `external_directory` permission should allow. */
+    allowedDirectories?: string[];
+    /** Additional top-level keys merged into the emitted config object (e.g. `provider`). */
+    extraConfig?: Record<string, unknown>;
+}
+export declare function buildOpenCodeMcpConfigContent(servers: McpServerConfig[], tokens?: Record<string, string>, options?: OpenCodeConfigBuildOptions): string | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH,gGAAgG;AAChG,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AACpD,kHAAkH;AAClH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,YAAY,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AA+DD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAO9E;AAeD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAwCtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAazD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAcvE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,SAAS,CAAC,CASpB;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAClB,OAAO,CAOT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,eAAe,EAAE,EAC1B,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAClC,OAAO,GAAG,IAAI,CAwBhB;AAiCD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,YAAY,EAAE,CAoB7E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,mDAAmD;AACnD,MAAM,WAAW,0BAA0B;IACzC,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,eAAe,EAAE,EAC1B,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACnC,OAAO,GAAE,0BAA+B,GACvC,MAAM,GAAG,IAAI,CAuDf"}