@strands-agents/sdk 1.0.0-rc.5 → 1.1.0

package/dist/src/tools/mcp-tool.d.ts

@@ -22,15 +22,36 @@ export declare class McpTool extends Tool {
     private readonly mcpClient;
     constructor(config: McpToolConfig);
     stream(toolContext: ToolContext): ToolStreamGenerator;
+    /**
+     * Maps a single MCP content item to an SDK ToolResultContent block.
+     *
+     * @param item - MCP content item from tool result
+     * @returns Mapped content block
+     */
+    private _mapMcpContent;
+    /**
+     * Maps an MCP image content item to an ImageBlock.
+     *
+     * @param record - MCP image content with data (base64) and mimeType
+     * @returns ImageBlock or TextBlock fallback if format is unsupported
+     */
+    private _mapMcpImageContent;
+    /**
+     * Maps an MCP embedded resource to an SDK content block.
+     * Text resources become TextBlock, blob resources with image MIME types become ImageBlock.
+     *
+     * @param record - MCP embedded resource content
+     * @returns Mapped content block or undefined if unsupported
+     */
+    private _mapMcpEmbeddedResource;
     /**
      * Type Guard: Checks if value matches the expected MCP SDK result shape.
      * \{ content: unknown[]; isError?: boolean \}
      */
     private _isMcpToolResult;
     /**
-     * Type Guard: Checks if an item is a Text content block.
-     * \{ type: 'text'; text: string \}
+     * Type Guard: Checks if a media format is a supported image format.
      */
-    private _isMcpTextContent;
+    private _isImageFormat;
 }
 //# sourceMappingURL=mcp-tool.d.ts.map

package/dist/src/tools/mcp-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp-tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAA;AAE7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,MAAM,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,IAAI;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;gBAEzB,MAAM,EAAE,aAAa;IAa1B,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;IAkD5D;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAS1B"}
+{"version":3,"file":"mcp-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/mcp-tool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAA;AAI7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAG1C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,UAAU,CAAA;IACvB,MAAM,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,OAAQ,SAAQ,IAAI;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;gBAEzB,MAAM,EAAE,aAAa;IAa1B,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;IAiD5D;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAyBtB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IA6B/B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,cAAc;CAGvB"}

package/dist/src/tools/mcp-tool.js

@@ -1,6 +1,9 @@
-import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { McpError, ErrorCode, UrlElicitationRequiredError } from '@modelcontextprotocol/sdk/types.js';
 import { createErrorResult, Tool } from './tool.js';
 import { JsonBlock, TextBlock, ToolResultBlock } from '../types/messages.js';
+import { ImageBlock, decodeBase64 } from '../types/media.js';
+import { toMediaFormat, IMAGE_FORMATS } from '../mime.js';
+import { logger } from '../logging/logger.js';
 /**
  * A Tool implementation that proxies calls to a remote MCP server.
  *
@@ -33,12 +36,10 @@ export class McpTool extends Tool {
             if (!this._isMcpToolResult(rawResult)) {
                 throw new Error('Invalid tool result from MCP Client: missing content array');
             }
-            const content = rawResult.content.map((item) => {
-                if (this._isMcpTextContent(item)) {
-                    return new TextBlock(item.text);
-                }
-                return new JsonBlock({ json: item });
-            });
+            const content = [];
+            for (const item of rawResult.content) {
+                content.push(this._mapMcpContent(item));
+            }
             if (content.length === 0) {
                 content.push(new TextBlock('Tool execution completed successfully with no output.'));
             }
@@ -49,27 +50,103 @@ export class McpTool extends Tool {
             });
         }
         catch (error) {
-            if (error instanceof McpError && error.code === ErrorCode.UrlElicitationRequired) {
-                try {
-                    const data = error.data;
-                    const elicitations = data?.elicitations;
-                    if (Array.isArray(elicitations)) {
-                        return new ToolResultBlock({
-                            toolUseId,
-                            status: 'error',
-                            content: [
-                                new TextBlock(`MCP Elicitation required: [${String(error)}] with data ${JSON.stringify(elicitations)}`),
-                            ],
-                        });
-                    }
-                }
-                catch {
-                    // Intentionally empty — fall through to createErrorResult below
+            if (error instanceof UrlElicitationRequiredError ||
+                (error instanceof McpError && error.code === ErrorCode.UrlElicitationRequired)) {
+                const elicitations = error instanceof UrlElicitationRequiredError
+                    ? error.elicitations
+                    : error.data?.elicitations;
+                if (Array.isArray(elicitations) && elicitations.length > 0) {
+                    return new ToolResultBlock({
+                        toolUseId,
+                        status: 'error',
+                        content: [
+                            new TextBlock(`MCP Elicitation required: [${String(error)}] with data ${JSON.stringify(elicitations)}`),
+                        ],
+                    });
                 }
             }
             return createErrorResult(error, toolUseId);
         }
     }
+    /**
+     * Maps a single MCP content item to an SDK ToolResultContent block.
+     *
+     * @param item - MCP content item from tool result
+     * @returns Mapped content block
+     */
+    _mapMcpContent(item) {
+        if (!item || typeof item !== 'object') {
+            return new JsonBlock({ json: item });
+        }
+        const record = item;
+        switch (record.type) {
+            case 'text':
+                if (typeof record.text === 'string') {
+                    return new TextBlock(record.text);
+                }
+                return new JsonBlock({ json: item });
+            case 'image':
+                return this._mapMcpImageContent(record);
+            case 'resource':
+                return this._mapMcpEmbeddedResource(record);
+            default:
+                return new JsonBlock({ json: item });
+        }
+    }
+    /**
+     * Maps an MCP image content item to an ImageBlock.
+     *
+     * @param record - MCP image content with data (base64) and mimeType
+     * @returns ImageBlock or TextBlock fallback if format is unsupported
+     */
+    _mapMcpImageContent(record) {
+        const data = record.data;
+        const mimeType = record.mimeType;
+        if (typeof data !== 'string' || typeof mimeType !== 'string') {
+            logger.warn('content_type=<image> | mcp image content missing data or mimeType, falling back to json');
+            return new JsonBlock({ json: record });
+        }
+        const format = toMediaFormat(mimeType);
+        if (!format || !this._isImageFormat(format)) {
+            logger.warn(`mime_type=<${mimeType}> | unsupported mcp image mime type, falling back to json`);
+            return new JsonBlock({ json: record });
+        }
+        return new ImageBlock({
+            format,
+            source: { bytes: decodeBase64(data) },
+        });
+    }
+    /**
+     * Maps an MCP embedded resource to an SDK content block.
+     * Text resources become TextBlock, blob resources with image MIME types become ImageBlock.
+     *
+     * @param record - MCP embedded resource content
+     * @returns Mapped content block or undefined if unsupported
+     */
+    _mapMcpEmbeddedResource(record) {
+        const resource = record.resource;
+        if (!resource || typeof resource !== 'object') {
+            return new JsonBlock({ json: record });
+        }
+        const res = resource;
+        // Text resource
+        if (typeof res.text === 'string') {
+            return new TextBlock(res.text);
+        }
+        // Blob resource
+        if (typeof res.blob === 'string' && typeof res.mimeType === 'string') {
+            const format = toMediaFormat(res.mimeType);
+            if (format && this._isImageFormat(format)) {
+                return new ImageBlock({
+                    format,
+                    source: { bytes: decodeBase64(res.blob) },
+                });
+            }
+            // Non-image blob: fall back to json
+            logger.warn(`mime_type=<${res.mimeType}> | unsupported mcp resource blob mime type, falling back to json`);
+        }
+        return new JsonBlock({ json: record });
+    }
     /**
      * Type Guard: Checks if value matches the expected MCP SDK result shape.
      * \{ content: unknown[]; isError?: boolean \}
@@ -83,15 +160,10 @@ export class McpTool extends Tool {
         return Array.isArray(record.content);
     }
     /**
-     * Type Guard: Checks if an item is a Text content block.
-     * \{ type: 'text'; text: string \}
+     * Type Guard: Checks if a media format is a supported image format.
      */
-    _isMcpTextContent(value) {
-        if (typeof value !== 'object' || value === null) {
-            return false;
-        }
-        const record = value;
-        return record.type === 'text' && typeof record.text === 'string';
+    _isImageFormat(format) {
+        return IMAGE_FORMATS.includes(format);
     }
 }
 //# sourceMappingURL=mcp-tool.js.map

package/dist/src/tools/mcp-tool.js.map

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

package/dist/src/tools/tool.d.ts

@@ -1,12 +1,13 @@
 import type { ToolSpec, ToolUse } from './types.js';
 import { ToolResultBlock } from '../types/messages.js';
-import type { LocalAgent } from '../types/agent.js';
+import type { InvocationState, LocalAgent } from '../types/agent.js';
+import type { Interruptible } from '../interrupt.js';
 export type { ToolSpec } from './types.js';
 /**
  * Context provided to tool implementations during execution.
  * Contains framework-level state and information from the agent invocation.
  */
-export interface ToolContext {
+export interface ToolContext extends Interruptible {
     /**
      * The tool use request that triggered this tool execution.
      * Contains the tool name, toolUseId, and input parameters.
@@ -17,6 +18,16 @@ export interface ToolContext {
      * Provides access to agent state, conversation history, and cancellation state.
      */
     agent: LocalAgent;
+    /**
+     * Per-invocation state shared across hooks and tools for the current
+     * agent invocation. Mutable — read and write freely; changes are visible to
+     * subsequent hooks, tools, and on {@link AgentResult.invocationState}.
+     *
+     * Distinct from `agent.appState`: `invocationState` is ephemeral and accepts
+     * arbitrary values, while `appState` is durable, JSON-serializable, and
+     * deep-copied on read/write.
+     */
+    invocationState: InvocationState;
 }
 /**
  * Data for a tool stream event.
@@ -164,4 +175,12 @@ export interface InvokableTool<TInput, TReturn> extends Tool {
  * @returns A ToolResultBlock with error status, error message content, and original error object
  */
 export declare function createErrorResult(error: unknown, toolUseId: string): ToolResultBlock;
+/**
+ * Returns `true` when `name` satisfies the provider-accepted tool name format:
+ * non-empty, 1–64 characters, and only letters, digits, underscores, or hyphens.
+ *
+ * @param name - The tool name to validate
+ * @returns `true` if the name is valid, `false` otherwise
+ */
+export declare function isValidToolName(name: string): boolean;
 //# sourceMappingURL=tool.d.ts.map

package/dist/src/tools/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/tools/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAa,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAGnD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAA;IAEvB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IACzD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAE1C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;gBAEX,SAAS,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;CAK1C;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,SAAS,CAAC,CAAA;AAE7F;;;;;;;;GAQG;AACH,8BAAsB,IAAI;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;CAC/D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,OAAO,CAAE,SAAQ,IAAI;IAC1D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAUpF"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/tools/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,EAAa,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAA;IAEjB;;;;;;;;OAQG;IACH,eAAe,EAAE,eAAe,CAAA;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,iBAAiB,CAAA;IAEvB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,YAAW,mBAAmB;IACzD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAE1C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;gBAEX,SAAS,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;CAK1C;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,SAAS,CAAC,CAAA;AAE7F;;;;;;;;GAQG;AACH,8BAAsB,IAAI;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB;CAC/D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,EAAE,OAAO,CAAE,SAAQ,IAAI;IAC1D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAUpF;AAKD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/src/tools/tool.js

@@ -65,4 +65,16 @@ export function createErrorResult(error, toolUseId) {
         error: errorObject,
     });
 }
+const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const TOOL_NAME_MAX_LENGTH = 64;
+/**
+ * Returns `true` when `name` satisfies the provider-accepted tool name format:
+ * non-empty, 1–64 characters, and only letters, digits, underscores, or hyphens.
+ *
+ * @param name - The tool name to validate
+ * @returns `true` if the name is valid, `false` otherwise
+ */
+export function isValidToolName(name) {
+    return name.length > 0 && name.length <= TOOL_NAME_MAX_LENGTH && TOOL_NAME_PATTERN.test(name);
+}
 //# sourceMappingURL=tool.js.map

package/dist/src/tools/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/tools/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAsC7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAC1B;;OAEG;IACM,IAAI,GAAG,iBAA0B,CAAA;IAE1C;;;OAGG;IACM,IAAI,CAAU;IAEvB,YAAY,SAA6B;QACvC,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAA;QAC5B,CAAC;IACH,CAAC;CACF;AAQD;;;;;;;;GAQG;AACH,MAAM,OAAgB,IAAI;CAqDzB;AAyBD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,SAAiB;IACjE,0DAA0D;IAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAEzC,OAAO,IAAI,eAAe,CAAC;QACzB,SAAS;QACT,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACzD,KAAK,EAAE,WAAW;KACnB,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/tools/tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAkD7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAC1B;;OAEG;IACM,IAAI,GAAG,iBAA0B,CAAA;IAE1C;;;OAGG;IACM,IAAI,CAAU;IAEvB,YAAY,SAA6B;QACvC,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAA;QAC5B,CAAC;IACH,CAAC;CACF;AAQD;;;;;;;;GAQG;AACH,MAAM,OAAgB,IAAI;CAqDzB;AAyBD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,SAAiB;IACjE,0DAA0D;IAC1D,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IAEzC,OAAO,IAAI,eAAe,CAAC;QACzB,SAAS;QACT,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,UAAU,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACzD,KAAK,EAAE,WAAW;KACnB,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,iBAAiB,GAAG,kBAAkB,CAAA;AAC5C,MAAM,oBAAoB,GAAG,EAAE,CAAA;AAE/B;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,oBAAoB,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC/F,CAAC"}