indusagi-coding-agent 0.1.22 → 0.1.24

package/dist/core/tools/websearch.d.ts

@@ -1,8 +1,135 @@
 /**
- * Web Search Tool
+ * Web Search Tool - Real-time search using Exa AI API
  *
- * Performs real-time web searches using Exa AI API.
- * Provides up-to-date information for current events and recent data.
+ * @module core/tools/websearch
+ * @description
+ * Implements the web search tool for the agent. Performs real-time web searches with:
+ * - Query-based information retrieval
+ * - Configurable result count
+ * - Search type options (fast, deep, auto)
+ * - Live crawling options
+ * - LLM-optimized context
+ * - Exa AI API integration
+ *
+ * ## Tool Interface
+ *
+ * **Input Parameters:**
+ * - `query` (required): Search query
+ * - `numResults` (optional): Number of results (1-10; default: 8)
+ * - `livecrawl` (optional): Crawling mode (fallback, preferred; default: fallback)
+ * - `type` (optional): Search type (auto, fast, deep; default: auto)
+ * - `contextMaxCharacters` (optional): Max context chars (default: 10000)
+ *
+ * **Output:**
+ * - Search results with snippets
+ * - URLs and relevance info
+ * - LLM-optimized context string
+ * - Error if API fails or disabled
+ *
+ * **Error Behavior:**
+ * - No API key: Tool error "Web search not available (no API key)"
+ * - Network error: Tool error "Search failed: ..."
+ * - API error: Tool error "Search API error: ..."
+ * - Timeout: Tool error "Search request timed out"
+ *
+ * ## Usage in Agent
+ *
+ * The agent uses this tool to:
+ * - Search for current information
+ * - Find recent news and events
+ * - Look up facts and statistics
+ * - Research new topics
+ * - Answer questions about current events
+ *
+ * ## Features
+ *
+ * **Search Types:**
+ * - **auto**: Balanced search (recommended)
+ * - **fast**: Quick results, less comprehensive
+ * - **deep**: Comprehensive search, more thorough
+ *
+ * **Live Crawling:**
+ * - **fallback**: Use cached content, crawl if needed
+ * - **preferred**: Prioritize live crawling for fresh content
+ *
+ * **LLM Optimization:**
+ * - Context formatted for language models
+ * - Configurable max characters
+ * - Snippets and relevance info included
+ * - Structured for easy parsing
+ *
+ * **Result Limiting:**
+ * - Min 1, max 10 results
+ * - Default 8 results
+ * - Configurable per query
+ *
+ * ## Security
+ *
+ * **API Authentication:**
+ * - Requires Exa AI API key
+ * - Key from environment variable or options
+ * - No key = tool not available
+ *
+ * **Query Validation:**
+ * - Non-empty query required
+ * - No injection attacks (sent to API as-is)
+ * - Safe to include user input
+ *
+ * **Rate Limiting:**
+ * - API enforces rate limits
+ * - Errors returned if exceeded
+ * - Exponential backoff recommended
+ *
+ * ## Customization
+ *
+ * **Custom Search Provider:**
+ * ```typescript
+ * const customTool = createWebSearchTool({
+ *   operations: {
+ *     search: async (request, signal) => {
+ *       // Custom search implementation
+ *       return JSON.stringify(results);
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ## Examples
+ *
+ * ### Basic search
+ * ```typescript
+ * // Agent calls: websearch {query: "latest news about AI"}
+ * // Returns: Top 8 news results
+ * ```
+ *
+ * ### Deep search with more results
+ * ```typescript
+ * // Agent calls: websearch {
+ * //   query: "TypeScript generics best practices",
+ * //   numResults: 10,
+ * //   type: "deep"
+ * // }
+ * // Returns: 10 comprehensive results
+ * ```
+ *
+ * ### Fast search with live crawling
+ * ```typescript
+ * // Agent calls: websearch {
+ * //   query: "stock market today",
+ * //   type: "fast",
+ * //   livecrawl: "preferred"
+ * // }
+ * // Returns: Quick results with live data
+ * ```
+ *
+ * ## Attribution
+ *
+ * Based on: indusagi-agent websearch tool
+ * Modifications:
+ * - Added search type options
+ * - Added live crawl configuration
+ * - Added context optimization
+ * - Improved error handling
  */
 import type { AgentTool } from "indusagi/agent";
 declare const webSearchSchema: import("@sinclair/typebox").TObject<{

package/dist/core/tools/websearch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websearch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/websearch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAYhD,QAAA,MAAM,eAAe;;;;;;EA6BnB,CAAC;AAEH,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACpC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7E;AAED,UAAU,gBAAgB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE;YACV,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;YACrC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;YAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACF,CAAC;CACF;AAqED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC,OAAO,eAAe,CAAC,CAoErG;AAED,8BAA8B;AAC9B,eAAO,MAAM,aAAa;;;;;;QAAwB,CAAC"}
+{"version":3,"file":"websearch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/websearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAYhD,QAAA,MAAM,eAAe;;;;;;EA6BnB,CAAC;AAEH,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACpC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7E;AAED,UAAU,gBAAgB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE;YACV,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;YACrC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;YAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACF,CAAC;CACF;AAqED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC,OAAO,eAAe,CAAC,CAoErG;AAED,8BAA8B;AAC9B,eAAO,MAAM,aAAa;;;;;;QAAwB,CAAC"}

package/dist/core/tools/websearch.js

@@ -1,8 +1,135 @@
 /**
- * Web Search Tool
+ * Web Search Tool - Real-time search using Exa AI API
  *
- * Performs real-time web searches using Exa AI API.
- * Provides up-to-date information for current events and recent data.
+ * @module core/tools/websearch
+ * @description
+ * Implements the web search tool for the agent. Performs real-time web searches with:
+ * - Query-based information retrieval
+ * - Configurable result count
+ * - Search type options (fast, deep, auto)
+ * - Live crawling options
+ * - LLM-optimized context
+ * - Exa AI API integration
+ *
+ * ## Tool Interface
+ *
+ * **Input Parameters:**
+ * - `query` (required): Search query
+ * - `numResults` (optional): Number of results (1-10; default: 8)
+ * - `livecrawl` (optional): Crawling mode (fallback, preferred; default: fallback)
+ * - `type` (optional): Search type (auto, fast, deep; default: auto)
+ * - `contextMaxCharacters` (optional): Max context chars (default: 10000)
+ *
+ * **Output:**
+ * - Search results with snippets
+ * - URLs and relevance info
+ * - LLM-optimized context string
+ * - Error if API fails or disabled
+ *
+ * **Error Behavior:**
+ * - No API key: Tool error "Web search not available (no API key)"
+ * - Network error: Tool error "Search failed: ..."
+ * - API error: Tool error "Search API error: ..."
+ * - Timeout: Tool error "Search request timed out"
+ *
+ * ## Usage in Agent
+ *
+ * The agent uses this tool to:
+ * - Search for current information
+ * - Find recent news and events
+ * - Look up facts and statistics
+ * - Research new topics
+ * - Answer questions about current events
+ *
+ * ## Features
+ *
+ * **Search Types:**
+ * - **auto**: Balanced search (recommended)
+ * - **fast**: Quick results, less comprehensive
+ * - **deep**: Comprehensive search, more thorough
+ *
+ * **Live Crawling:**
+ * - **fallback**: Use cached content, crawl if needed
+ * - **preferred**: Prioritize live crawling for fresh content
+ *
+ * **LLM Optimization:**
+ * - Context formatted for language models
+ * - Configurable max characters
+ * - Snippets and relevance info included
+ * - Structured for easy parsing
+ *
+ * **Result Limiting:**
+ * - Min 1, max 10 results
+ * - Default 8 results
+ * - Configurable per query
+ *
+ * ## Security
+ *
+ * **API Authentication:**
+ * - Requires Exa AI API key
+ * - Key from environment variable or options
+ * - No key = tool not available
+ *
+ * **Query Validation:**
+ * - Non-empty query required
+ * - No injection attacks (sent to API as-is)
+ * - Safe to include user input
+ *
+ * **Rate Limiting:**
+ * - API enforces rate limits
+ * - Errors returned if exceeded
+ * - Exponential backoff recommended
+ *
+ * ## Customization
+ *
+ * **Custom Search Provider:**
+ * ```typescript
+ * const customTool = createWebSearchTool({
+ *   operations: {
+ *     search: async (request, signal) => {
+ *       // Custom search implementation
+ *       return JSON.stringify(results);
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ## Examples
+ *
+ * ### Basic search
+ * ```typescript
+ * // Agent calls: websearch {query: "latest news about AI"}
+ * // Returns: Top 8 news results
+ * ```
+ *
+ * ### Deep search with more results
+ * ```typescript
+ * // Agent calls: websearch {
+ * //   query: "TypeScript generics best practices",
+ * //   numResults: 10,
+ * //   type: "deep"
+ * // }
+ * // Returns: 10 comprehensive results
+ * ```
+ *
+ * ### Fast search with live crawling
+ * ```typescript
+ * // Agent calls: websearch {
+ * //   query: "stock market today",
+ * //   type: "fast",
+ * //   livecrawl: "preferred"
+ * // }
+ * // Returns: Quick results with live data
+ * ```
+ *
+ * ## Attribution
+ *
+ * Based on: indusagi-agent websearch tool
+ * Modifications:
+ * - Added search type options
+ * - Added live crawl configuration
+ * - Added context optimization
+ * - Improved error handling
  */
 import { Type } from "@sinclair/typebox";
 const API_CONFIG = {

package/dist/core/tools/websearch.js.map

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

package/dist/core/tools/write.d.ts

@@ -1,24 +1,270 @@
+/**
+ * Write Tool - Create and overwrite files with automatic directory creation
+ *
+ * @module core/tools/write
+ * @description
+ * Implements the write tool for the agent. Creates or overwrites files with:
+ * - Automatic parent directory creation
+ * - Path validation and resolution
+ * - Remote execution support (SSH, containers)
+ * - UTF-8 encoding
+ *
+ * Based on file writing patterns from Anthropic's Claude API.
+ * Refactored for agent file system safety.
+ * - Atomic writes (file written as a whole unit)
+ *
+ * ## Tool Interface
+ *
+ * **Input Parameters:**
+ * - `path` (required): File path (relative or absolute)
+ * - `content` (required): File content as string
+ *
+ * **Output:**
+ * - Success: "File written" message
+ * - Errors: Path invalid, permission denied, disk full, etc.
+ *
+ * **Error Behavior:**
+ * - Invalid path → Tool error "Path outside working directory"
+ * - Permission denied → Tool error "EACCES: permission denied"
+ * - Disk full → Tool error "ENOSPC: no space left on device"
+ * - Other errors → Tool error with message
+ *
+ * ## Usage in Agent
+ *
+ * The agent uses this tool to:
+ * - Create new files (code, config, docs)
+ * - Overwrite existing files
+ * - Write generated content
+ * - Create boilerplate and scaffolding
+ * - Generate test fixtures
+ *
+ * Overwrites existing files completely (no merge).
+ *
+ * ## Features
+ *
+ * **Directory Creation:**
+ * - Automatically creates parent directories
+ * - Recursively creates full path
+ * - No errors if dirs already exist
+ *
+ * **Path Safety:**
+ * - All paths resolved relative to cwd
+ * - No path traversal (no ../../../etc/passwd)
+ * - Validates accessible location
+ *
+ * **Writing:**
+ * - UTF-8 encoding (standard for code)
+ * - Atomic write (no partial files)
+ * - Overwrites completely (not merge)
+ *
+ * **Permissions:**
+ * - Respects system umask
+ * - Files created with standard permissions
+ * - Errors on permission issues
+ *
+ * ## Security
+ *
+ * **Path validation:**
+ * - All paths resolved relative to cwd
+ * - No absolute paths outside cwd
+ * - Directory traversal prevented
+ *
+ * **Write safety:**
+ * - Cannot execute written files
+ * - Files written as text, not executable
+ * - Permission issues caught and reported
+ *
+ * **Disk safety:**
+ * - System handles disk full errors
+ * - Inode limit errors caught
+ * - No intentional DoS vectors
+ *
+ * ## Customization
+ *
+ * **Remote Execution (SSH):**
+ * ```typescript
+ * const sshTool = createWriteTool(cwd, {
+ *   operations: {
+ *     writeFile: (path, content) => sshExec(`cat > ${path} << 'EOF'\n${content}\nEOF`),
+ *     mkdir: (dir) => sshExec(`mkdir -p ${dir}`),
+ *   },
+ * });
+ * ```
+ *
+ * ## Examples
+ *
+ * ### Create new file
+ * ```typescript
+ * // Agent calls: write {path: "hello.txt", content: "Hello, world!"}
+ * // Result: File created with content
+ * ```
+ *
+ * ### Create in subdirectory
+ * ```typescript
+ * // Agent calls: write {path: "src/main.ts", content: "..."}
+ * // Result: src/ and src/main.ts created automatically
+ * ```
+ *
+ * ### Overwrite existing file
+ * ```typescript
+ * // Agent calls: write {path: "existing.js", content: "..."}
+ * // Result: File completely replaced with new content
+ * ```
+ *
+ * ## Attribution
+ *
+ * Based on: indusagi-agent write tool
+ * Modifications:
+ * - Added custom operations interface
+ * - Improved error messages
+ * - Added directory creation details
+ */
 import type { AgentTool } from "indusagi/agent";
+/**
+ * JSON Schema for write tool parameters
+ * @internal
+ */
 declare const writeSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     content: import("@sinclair/typebox").TString;
 }>;
 /**
- * Pluggable operations for the write tool.
- * Override these to delegate file writing to remote systems (e.g., SSH).
+ * Pluggable interface for file writing operations
+ *
+ * Allows custom implementations for:
+ * - Remote file systems (SSH, cloud storage)
+ * - Virtual file systems (in-memory, testing)
+ * - Custom permission models
+ * - Monitoring and auditing
+ *
+ * Implementations must respect working directory boundaries.
  */
 export interface WriteOperations {
-    /** Write content to a file */
+    /**
+     * Write content to a file (overwrite if exists)
+     *
+     * Must handle:
+     * - Creating file if not exists
+     * - Overwriting if exists
+     * - UTF-8 encoding
+     *
+     * @param absolutePath - Full path to file (already validated)
+     * @param content - File content as string
+     * @throws Error on write failures
+     */
     writeFile: (absolutePath: string, content: string) => Promise<void>;
-    /** Create directory (recursively) */
+    /**
+     * Create directory (recursively)
+     *
+     * Must handle:
+     * - Creating directory if not exists
+     * - Creating parent directories
+     * - Not erroring if already exists
+     *
+     * @param dir - Directory path (already validated)
+     * @throws Error on creation failures
+     */
     mkdir: (dir: string) => Promise<void>;
 }
+/**
+ * Configuration options for the write tool
+ */
 export interface WriteToolOptions {
-    /** Custom operations for file writing. Default: local filesystem */
+    /**
+     * Custom operations for file writing
+     *
+     * Default: Local filesystem operations
+     * Custom: SSH, cloud storage, testing mocks
+     *
+     * @example
+     * ```typescript
+     * const tool = createWriteTool(cwd, {
+     *   operations: {
+     *     writeFile: (path, content) => sshExec(`cat > ${path}`, content),
+     *     mkdir: (dir) => sshExec(`mkdir -p ${dir}`),
+     *   },
+     * });
+     * ```
+     */
     operations?: WriteOperations;
 }
+/**
+ * Create a write tool with custom configuration
+ *
+ * Creates an AgentTool that can write files with:
+ * - Automatic parent directory creation
+ * - Path validation and resolution
+ * - Remote execution support
+ * - Proper error handling
+ *
+ * **Tool Behavior:**
+ * - Resolves paths relative to working directory
+ * - Prevents path traversal (no ../../../etc/passwd)
+ * - Creates parent directories automatically
+ * - Overwrites files completely (not merge/append)
+ * - Returns success message
+ *
+ * **Tool Parameters:**
+ * - `path` (required): File to write (relative or absolute)
+ * - `content` (required): File content as string
+ *
+ * **Tool Output:**
+ * - Success: "File written to <path>"
+ * - Errors: Tool error with message
+ *
+ * **Error Handling:**
+ * - Invalid path: Tool error "Path outside working directory"
+ * - Permission denied: Tool error "EACCES: permission denied"
+ * - Disk full: Tool error "ENOSPC: no space left on device"
+ * - Other errors: Tool error with message
+ *
+ * @param cwd - Working directory for relative path resolution
+ *   - All relative paths resolved from this directory
+ *   - Prevents directory traversal attacks
+ *   - Can be overridden per execution
+ *
+ * @param options - Optional configuration
+ *   - operations: Custom file writing backend (default: filesystem)
+ *
+ * @returns AgentTool instance ready to use
+ *
+ * @example
+ * ```typescript
+ * // Basic tool
+ * const tool = createWriteTool(process.cwd());
+ *
+ * // With remote backend (SSH)
+ * const remoteTool = createWriteTool(cwd, {
+ *   operations: sshOperations,
+ * });
+ * ```
+ *
+ * @see WriteToolOptions for detailed configuration
+ * @see WriteOperations for custom backend interface
+ */
 export declare function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema>;
 /** Default write tool using process.cwd() - for backwards compatibility */
+/**
+ * Default write tool instance
+ *
+ * Pre-created write tool using current process working directory.
+ * Supports automatic directory creation and file overwriting.
+ *
+ * Equivalent to:
+ * ```typescript
+ * const writeTool = createWriteTool(process.cwd());
+ * ```
+ *
+ * For custom configuration or remote backends, use createWriteTool() directly.
+ *
+ * @example
+ * ```typescript
+ * import { writeTool } from "./tools/write.js";
+ * const agent = new Agent({ tools: [writeTool] });
+ * ```
+ *
+ * @see createWriteTool for custom configuration
+ */
 export declare const writeTool: AgentTool<import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     content: import("@sinclair/typebox").TString;

package/dist/core/tools/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/core/tools/write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,qCAAqC;IACrC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAOD,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAgFtG;AAED,2EAA2E;AAC3E,eAAO,MAAM,SAAS;;;QAAiC,CAAC"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/core/tools/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwHG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUhD;;;GAGG;AACH,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;;;OAUG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAWD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAgFtG;AAED,2EAA2E;AAC3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS;;;QAAiC,CAAC"}