@rubytech/create-realagent 1.0.707 → 1.0.710

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.707",
+  "version": "1.0.710",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/lib/mcp-spawn-tee/dist/index.d.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * MCP spawn-tee — parent-side stderr capture wrapper (Task 743).
+ *
+ * Claude Code's `--mcp-config` accepts `{command, args, env}` descriptors and
+ * spawns each MCP server itself; the platform never holds a ChildProcess
+ * handle. The in-process `mcp-stderr-tee` patches `process.stderr.write` from
+ * inside the MCP server, but its writes go through `createWriteStream` —
+ * async, buffered. A synchronous module-load throw (e.g. schema-loader's
+ * line-168 width check on memory) calls `process.exit(1)` before the buffer
+ * flushes, so the per-server log file is empty and the platform's
+ * `[mcp-init-error] tail="(no stderr file)"` probe is operationally useless.
+ * That class shipped as the chronic memory-MCP silent-fail loop fixed by
+ * Task 743 (and hit graph in Task 560 — solved there with per-plugin
+ * `appendFileSync` discipline that this wrapper now generalises).
+ *
+ * The wrapper sits between Claude Code and the real MCP server: it spawns
+ * the real entry with `stdio: ['inherit', 'inherit', 'pipe']`, then
+ * synchronously appends every child stderr chunk to
+ * `${LOG_DIR}/mcp-${name}-stderr-<date>.log`. Synchronous writes survive
+ * `process.exit` because the kernel queues the syscall before the call
+ * returns. The chunk is also written to the wrapper's own stderr so
+ * Claude Code's existing stderr consumer is unchanged — the mechanism is
+ * additive, not interceptive.
+ *
+ *   Claude Code CLI
+ *        │ spawns
+ *        ▼
+ *   wrapper (this file) — argv[2] = real entry, env.MCP_SPAWN_TEE_NAME = name
+ *        │ spawns child with stdio:['inherit','inherit','pipe']
+ *        ▼
+ *   child = node <real-entry>
+ *        │
+ *        ├──▶ stdin/stdout: inherited from wrapper (Claude Code pipe)
+ *        └──▶ stderr → wrapper.on('data', chunk =>)
+ *               ├──▶ appendFileSync(${LOG_DIR}/mcp-${name}-stderr-<date>.log)
+ *               └──▶ process.stderr.write(chunk)  → Claude Code consumer
+ *
+ * The wrapper catches:
+ *   - MODULE_NOT_FOUND on the entry script itself (success criterion #3:
+ *     `mv plugins/memory/mcp/dist plugins/memory/mcp/dist-broken && reboot`
+ *     leaves the cause on disk).
+ *   - Synchronous throws during module load before the in-process tee runs.
+ *   - Any stderr a normally-running plugin emits (steady-state telemetry
+ *     remains visible too — the in-process tee handles per-line stream-log
+ *     prefixing; this wrapper handles the raw per-server file).
+ *
+ * SIGTERM/SIGINT propagation: forwarded to the child so a Claude Code
+ * shutdown does not orphan the MCP server. Child exit code is propagated
+ * verbatim so upstream (Claude Code) sees the real outcome.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/mcp-spawn-tee/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG"}

package/payload/platform/lib/mcp-spawn-tee/dist/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — parent-side stderr capture wrapper (Task 743).
+ *
+ * Claude Code's `--mcp-config` accepts `{command, args, env}` descriptors and
+ * spawns each MCP server itself; the platform never holds a ChildProcess
+ * handle. The in-process `mcp-stderr-tee` patches `process.stderr.write` from
+ * inside the MCP server, but its writes go through `createWriteStream` —
+ * async, buffered. A synchronous module-load throw (e.g. schema-loader's
+ * line-168 width check on memory) calls `process.exit(1)` before the buffer
+ * flushes, so the per-server log file is empty and the platform's
+ * `[mcp-init-error] tail="(no stderr file)"` probe is operationally useless.
+ * That class shipped as the chronic memory-MCP silent-fail loop fixed by
+ * Task 743 (and hit graph in Task 560 — solved there with per-plugin
+ * `appendFileSync` discipline that this wrapper now generalises).
+ *
+ * The wrapper sits between Claude Code and the real MCP server: it spawns
+ * the real entry with `stdio: ['inherit', 'inherit', 'pipe']`, then
+ * synchronously appends every child stderr chunk to
+ * `${LOG_DIR}/mcp-${name}-stderr-<date>.log`. Synchronous writes survive
+ * `process.exit` because the kernel queues the syscall before the call
+ * returns. The chunk is also written to the wrapper's own stderr so
+ * Claude Code's existing stderr consumer is unchanged — the mechanism is
+ * additive, not interceptive.
+ *
+ *   Claude Code CLI
+ *        │ spawns
+ *        ▼
+ *   wrapper (this file) — argv[2] = real entry, env.MCP_SPAWN_TEE_NAME = name
+ *        │ spawns child with stdio:['inherit','inherit','pipe']
+ *        ▼
+ *   child = node <real-entry>
+ *        │
+ *        ├──▶ stdin/stdout: inherited from wrapper (Claude Code pipe)
+ *        └──▶ stderr → wrapper.on('data', chunk =>)
+ *               ├──▶ appendFileSync(${LOG_DIR}/mcp-${name}-stderr-<date>.log)
+ *               └──▶ process.stderr.write(chunk)  → Claude Code consumer
+ *
+ * The wrapper catches:
+ *   - MODULE_NOT_FOUND on the entry script itself (success criterion #3:
+ *     `mv plugins/memory/mcp/dist plugins/memory/mcp/dist-broken && reboot`
+ *     leaves the cause on disk).
+ *   - Synchronous throws during module load before the in-process tee runs.
+ *   - Any stderr a normally-running plugin emits (steady-state telemetry
+ *     remains visible too — the in-process tee handles per-line stream-log
+ *     prefixing; this wrapper handles the raw per-server file).
+ *
+ * SIGTERM/SIGINT propagation: forwarded to the child so a Claude Code
+ * shutdown does not orphan the MCP server. Child exit code is propagated
+ * verbatim so upstream (Claude Code) sees the real outcome.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const ENTRY = process.argv[2];
+// Sync-emit: appendFileSync to per-server log + stderr passthrough. Used for
+// wrapper-internal diagnostics (attach line, errors) and for forwarding child
+// stderr chunks. Each destination wrapped independently — an unwritable log
+// must not mask the primary output.
+function syncEmitLine(line) {
+    if (LOG_DIR) {
+        try {
+            (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+            const date = new Date().toISOString().slice(0, 10);
+            (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), line);
+        }
+        catch {
+            /* unwritable destination — preserve primary failure */
+        }
+    }
+    try {
+        process.stderr.write(line);
+    }
+    catch {
+        /* stderr closed — nothing else to do */
+    }
+}
+if (!ENTRY) {
+    syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason="no entry given (argv[2] missing)"\n`);
+    process.exit(2);
+}
+const child = (0, node_child_process_1.spawn)(process.execPath, [ENTRY], {
+    stdio: ["inherit", "inherit", "pipe"],
+    env: process.env,
+});
+syncEmitLine(`[mcp-spawn-tee-attached] server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}\n`);
+child.on("error", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}\n`);
+    process.exit(127);
+});
+if (child.stderr) {
+    child.stderr.on("data", (chunk) => {
+        if (LOG_DIR) {
+            try {
+                const date = new Date().toISOString().slice(0, 10);
+                (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), chunk);
+            }
+            catch {
+                /* unwritable destination — preserve passthrough */
+            }
+        }
+        try {
+            process.stderr.write(chunk);
+        }
+        catch {
+            /* stderr closed — nothing else to do */
+        }
+    });
+}
+// Forward SIGTERM/SIGINT so Claude Code shutdown doesn't orphan the child.
+const forward = (signal) => {
+    if (!child.killed)
+        child.kill(signal);
+};
+process.on("SIGTERM", () => forward("SIGTERM"));
+process.on("SIGINT", () => forward("SIGINT"));
+child.on("exit", (code, signal) => {
+    if (signal) {
+        syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} signal=${signal}\n`);
+        process.exit(128 + (code ?? 0));
+    }
+    if (code !== 0) {
+        syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} code=${code}\n`);
+    }
+    process.exit(code ?? 0);
+});
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/mcp-spawn-tee/dist/index.js.map

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

package/payload/platform/lib/mcp-spawn-tee/src/index.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * MCP spawn-tee — parent-side stderr capture wrapper (Task 743).
+ *
+ * Claude Code's `--mcp-config` accepts `{command, args, env}` descriptors and
+ * spawns each MCP server itself; the platform never holds a ChildProcess
+ * handle. The in-process `mcp-stderr-tee` patches `process.stderr.write` from
+ * inside the MCP server, but its writes go through `createWriteStream` —
+ * async, buffered. A synchronous module-load throw (e.g. schema-loader's
+ * line-168 width check on memory) calls `process.exit(1)` before the buffer
+ * flushes, so the per-server log file is empty and the platform's
+ * `[mcp-init-error] tail="(no stderr file)"` probe is operationally useless.
+ * That class shipped as the chronic memory-MCP silent-fail loop fixed by
+ * Task 743 (and hit graph in Task 560 — solved there with per-plugin
+ * `appendFileSync` discipline that this wrapper now generalises).
+ *
+ * The wrapper sits between Claude Code and the real MCP server: it spawns
+ * the real entry with `stdio: ['inherit', 'inherit', 'pipe']`, then
+ * synchronously appends every child stderr chunk to
+ * `${LOG_DIR}/mcp-${name}-stderr-<date>.log`. Synchronous writes survive
+ * `process.exit` because the kernel queues the syscall before the call
+ * returns. The chunk is also written to the wrapper's own stderr so
+ * Claude Code's existing stderr consumer is unchanged — the mechanism is
+ * additive, not interceptive.
+ *
+ *   Claude Code CLI
+ *        │ spawns
+ *        ▼
+ *   wrapper (this file) — argv[2] = real entry, env.MCP_SPAWN_TEE_NAME = name
+ *        │ spawns child with stdio:['inherit','inherit','pipe']
+ *        ▼
+ *   child = node <real-entry>
+ *        │
+ *        ├──▶ stdin/stdout: inherited from wrapper (Claude Code pipe)
+ *        └──▶ stderr → wrapper.on('data', chunk =>)
+ *               ├──▶ appendFileSync(${LOG_DIR}/mcp-${name}-stderr-<date>.log)
+ *               └──▶ process.stderr.write(chunk)  → Claude Code consumer
+ *
+ * The wrapper catches:
+ *   - MODULE_NOT_FOUND on the entry script itself (success criterion #3:
+ *     `mv plugins/memory/mcp/dist plugins/memory/mcp/dist-broken && reboot`
+ *     leaves the cause on disk).
+ *   - Synchronous throws during module load before the in-process tee runs.
+ *   - Any stderr a normally-running plugin emits (steady-state telemetry
+ *     remains visible too — the in-process tee handles per-line stream-log
+ *     prefixing; this wrapper handles the raw per-server file).
+ *
+ * SIGTERM/SIGINT propagation: forwarded to the child so a Claude Code
+ * shutdown does not orphan the MCP server. Child exit code is propagated
+ * verbatim so upstream (Claude Code) sees the real outcome.
+ */
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const ENTRY = process.argv[2];
+
+// Sync-emit: appendFileSync to per-server log + stderr passthrough. Used for
+// wrapper-internal diagnostics (attach line, errors) and for forwarding child
+// stderr chunks. Each destination wrapped independently — an unwritable log
+// must not mask the primary output.
+function syncEmitLine(line: string): void {
+  if (LOG_DIR) {
+    try {
+      mkdirSync(LOG_DIR, { recursive: true });
+      const date = new Date().toISOString().slice(0, 10);
+      appendFileSync(resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), line);
+    } catch {
+      /* unwritable destination — preserve primary failure */
+    }
+  }
+  try {
+    process.stderr.write(line);
+  } catch {
+    /* stderr closed — nothing else to do */
+  }
+}
+
+if (!ENTRY) {
+  syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason="no entry given (argv[2] missing)"\n`);
+  process.exit(2);
+}
+
+const child = spawn(process.execPath, [ENTRY], {
+  stdio: ["inherit", "inherit", "pipe"],
+  env: process.env,
+});
+
+syncEmitLine(`[mcp-spawn-tee-attached] server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}\n`);
+
+child.on("error", (err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  syncEmitLine(`[mcp-spawn-tee-error] server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}\n`);
+  process.exit(127);
+});
+
+if (child.stderr) {
+  child.stderr.on("data", (chunk: Buffer) => {
+    if (LOG_DIR) {
+      try {
+        const date = new Date().toISOString().slice(0, 10);
+        appendFileSync(resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${date}.log`), chunk);
+      } catch {
+        /* unwritable destination — preserve passthrough */
+      }
+    }
+    try {
+      process.stderr.write(chunk);
+    } catch {
+      /* stderr closed — nothing else to do */
+    }
+  });
+}
+
+// Forward SIGTERM/SIGINT so Claude Code shutdown doesn't orphan the child.
+const forward = (signal: NodeJS.Signals) => {
+  if (!child.killed) child.kill(signal);
+};
+process.on("SIGTERM", () => forward("SIGTERM"));
+process.on("SIGINT", () => forward("SIGINT"));
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} signal=${signal}\n`);
+    process.exit(128 + (code ?? 0));
+  }
+  if (code !== 0) {
+    syncEmitLine(`[mcp-spawn-tee-exit] server=${SERVER_NAME} pid=${child.pid ?? -1} code=${code}\n`);
+  }
+  process.exit(code ?? 0);
+});

package/payload/platform/lib/mcp-spawn-tee/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/lib/oauth-llm/dist/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * OAuth-bearer LLM calls for admin-side classifiers (Task 740).
+ *
+ * Every admin-side classifier (memory-classify, memory-rank, commitment,
+ * adherence, inbound-gateway, query classifier, summarisation, email
+ * screening) uses Claude Code OAuth credentials — never the Anthropic
+ * API key. The API-key path is reserved for the public agent.
+ *
+ * Mechanism: read the access token from ~/.claude/.credentials.json,
+ * refresh it via the standard refresh-token grant if expired, then call
+ * api.anthropic.com with `Authorization: Bearer <token>` and the
+ * `anthropic-beta: oauth-2025-04-20` header. Billed against the operator's
+ * Claude Code subscription, not the API-key key. Refresh uses a
+ * module-level mutex so concurrent classifier calls during expiry don't
+ * race and invalidate each other's tokens (Anthropic rotates both tokens
+ * on refresh).
+ *
+ * Implementation note: this lib uses raw fetch() rather than the
+ * @anthropic-ai/sdk package to keep the lib dependency-free — every
+ * consumer already has its own SDK copy for other purposes, but the
+ * shared lib would create a circular package dependency. The Messages
+ * API surface we use (model + system + one user message + max_tokens)
+ * is small and stable.
+ *
+ * Failure modes are surfaced as a structured `Result` so callers can
+ * pattern-match without parsing error strings. The skill / agent layer
+ * is responsible for translating `fallback` results into operator-visible
+ * blocker messages (loud failure doctrine — Task 540, 740).
+ */
+declare const OAUTH_BETA_HEADER = "oauth-2025-04-20";
+/** Anthropic tool definition — structural-output enforcement via function calling. */
+export interface OauthLlmTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface CallOauthLlmParams {
+    /** Anthropic model id (e.g. claude-haiku-4-5). */
+    model: string;
+    /** System prompt — the classifier instructions. */
+    system: string;
+    /** User message — the input to classify / rank / etc. */
+    userMessage: string;
+    /** Max output tokens. Default 4096. */
+    maxTokens?: number;
+    /** Hard timeout in ms for the model call. Default 60_000. */
+    timeoutMs?: number;
+    /**
+     * Optional tools for structured output. When provided with a forced
+     * `toolChoiceName`, the model returns a `tool_use` block whose `input` is
+     * a structured object matching the tool's `input_schema` — strictly typed
+     * JSON without the parsing brittleness of free-form text output.
+     */
+    tools?: OauthLlmTool[];
+    /** Force the model to call this tool. Required when `tools` is provided. */
+    toolChoiceName?: string;
+}
+/** Result when the call did not declare any tool — only text or fallback. */
+export type CallOauthLlmTextResult = {
+    kind: "ok";
+    text: string;
+} | CallOauthLlmFallback;
+/** Result when the call forced a tool — only the tool input or fallback. */
+export type CallOauthLlmToolResult = {
+    kind: "ok-tool";
+    toolName: string;
+    input: Record<string, unknown>;
+} | CallOauthLlmFallback;
+/** Discriminated union of every possible result. Returned by the no-overload form. */
+export type CallOauthLlmResult = CallOauthLlmTextResult | CallOauthLlmToolResult;
+export interface CallOauthLlmFallback {
+    kind: "fallback";
+    /** Human-readable single-line reason (for operator-visible blocker). */
+    reason: string;
+    /** Stable classifier — callers can pattern-match for retry/abort policy. */
+    cause: "missing-creds" | "dead-token" | "refresh-failed" | "auth-error" | "rate-limit" | "server-error" | "network-error" | "timeout" | "empty-response" | "malformed-response" | "unexpected";
+}
+/**
+ * Call an Anthropic model via OAuth bearer auth.
+ *
+ * Returns:
+ *   { kind: "ok", text }                   — model's text response
+ *   { kind: "ok-tool", toolName, input }   — when `tools` + `toolChoiceName` provided
+ *   { kind: "fallback", reason, cause }    — caller decides whether to abort
+ *
+ * The caller is responsible for translating fallback results into
+ * operator-visible blocker messages — this wrapper never silently
+ * substitutes a degraded response.
+ *
+ * Overloads narrow the return type by call shape: text-only callers (no
+ * `tools`) statically rule out `ok-tool`; tool callers statically rule out
+ * `ok`. Mixed callers get the full union.
+ */
+export declare function callOauthLlm(params: Omit<CallOauthLlmParams, "tools" | "toolChoiceName">): Promise<CallOauthLlmTextResult>;
+export declare function callOauthLlm(params: CallOauthLlmParams & {
+    tools: OauthLlmTool[];
+    toolChoiceName: string;
+}): Promise<CallOauthLlmToolResult>;
+export declare function callOauthLlm(params: CallOauthLlmParams): Promise<CallOauthLlmResult>;
+export { OAUTH_BETA_HEADER };
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/oauth-llm/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAgBH,QAAA,MAAM,iBAAiB,qBAAqB,CAAC;AAe7C,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5B,oBAAoB,CAAC;AAEzB,4EAA4E;AAC5E,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACrE,oBAAoB,CAAC;AAEzB,sFAAsF;AACtF,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAEjF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EACD,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,eAAe,GACf,SAAS,GACT,gBAAgB,GAChB,oBAAoB,GACpB,YAAY,CAAC;CAClB;AAuND;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,GAAG,gBAAgB,CAAC,GAC3D,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACnC,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,GAAG;IAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC7E,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACnC,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAwK/B,OAAO,EAAE,iBAAiB,EAAE,CAAC"}