agentx-sdk 0.1.0

package/dist/tools/skill-tool.js

@@ -0,0 +1,149 @@
+/**
+ * SkillTool — allows the LLM to invoke skills as tool calls mid-loop.
+ *
+ * Ported from old_src/tools/SkillTool/SkillTool.ts with adaptations for SDK context.
+ *
+ * Key behaviors from old_src:
+ * - Skill lookup by exact name, alias, and triggerPrefix
+ * - Validates modelInvocable flag (disableModelInvocation equivalent)
+ * - Dynamic prompt resolution via resolveInstructions()
+ * - Registers skill-scoped tools in ToolExecutor when skill activates
+ * - Returns resolved prompt as tagged block for the model
+ * - Tracks invocation for session (survives compaction via invoked set)
+ *
+ * Differences from old_src:
+ * - No permission system (SDK has no interactive UI to ask user)
+ * - No fork mode (SDK uses inline execution only)
+ * - No contextModifier (SDK doesn't support mid-loop model/effort override)
+ * - No remote skill loading (CLI-specific feature)
+ */
+import { z } from 'zod';
+export const SKILL_TOOL_NAME = 'Skill';
+const SkillToolParameters = z.object({
+    skill: z.string().describe('The skill name. E.g., "commit", "review-pr", or "translate"'),
+    args: z.string().optional().describe('Optional arguments for the skill'),
+});
+/**
+ * Build the system prompt section that teaches the model how to use the Skill tool.
+ * Ported from old_src/tools/SkillTool/prompt.ts getPrompt().
+ */
+export function buildSkillToolPrompt(listing) {
+    return [
+        'You have access to a Skill tool that activates specialized behaviors.',
+        '',
+        'How to invoke:',
+        '- Use the Skill tool with the skill name and optional arguments',
+        '- Examples:',
+        '  - `skill: "review"` — invoke the review skill',
+        '  - `skill: "translate", args: "pt Hello world"` — invoke with arguments',
+        '  - `skill: "commit", args: "-m \'Fix bug\'"` — invoke with arguments',
+        '',
+        'Important:',
+        '- When a skill matches the user\'s request, invoke it BEFORE generating other responses',
+        '- Do not mention a skill without actually calling the Skill tool',
+        '- Do not invoke a skill that is already active in the current context',
+        '- If a <skill> tag already appears in the conversation, the skill is ALREADY loaded — follow its instructions directly instead of calling the Skill tool again',
+        '',
+        listing,
+    ].join('\n');
+}
+/**
+ * Find a skill by name, alias, or triggerPrefix.
+ * Normalized: strips leading "/" for compatibility.
+ */
+function findSkill(skillManager, skillName) {
+    const allSkills = skillManager.listAllSkills();
+    // 1. Exact name match
+    const byName = allSkills.find(s => s.name === skillName);
+    if (byName)
+        return byName;
+    // 2. Normalized name (strip leading /)
+    const normalized = skillName.startsWith('/') ? skillName.slice(1) : skillName;
+    const byNormalized = allSkills.find(s => s.name === normalized
+        || s.aliases?.some(a => {
+            const clean = a.startsWith('/') ? a.slice(1) : a;
+            return clean === normalized;
+        }));
+    if (byNormalized)
+        return byNormalized;
+    // 3. triggerPrefix match
+    const withSlash = skillName.startsWith('/') ? skillName : `/${skillName}`;
+    return allSkills.find(s => s.triggerPrefix === withSlash);
+}
+/**
+ * Create the Skill tool that the model can invoke during the react loop.
+ *
+ * @param skillManager — manages skill registry and resolution
+ * @param toolExecutor — used to register skill-scoped tools mid-loop
+ * @param getContext — returns current execution context (threadId, traceId)
+ */
+export function createSkillTool(skillManager, toolExecutor, getContext) {
+    // Track tools registered by skills during this session (for cleanup)
+    const registeredSkillTools = new Set();
+    return {
+        name: SKILL_TOOL_NAME,
+        description: 'Execute a skill by name. Use this when you want to activate a skill\'s specialized behavior. Pass the skill name and optional arguments.',
+        parameters: SkillToolParameters,
+        isConcurrencySafe: false,
+        execute: async (rawArgs) => {
+            const { skill: skillName, args = '' } = rawArgs;
+            const ctx = getContext();
+            // --- Find skill ---
+            const skill = findSkill(skillManager, skillName);
+            if (!skill) {
+                const available = skillManager.listSkills().map(s => s.name).join(', ');
+                return {
+                    content: `Skill "${skillName}" not found. Available skills: ${available || 'none'}`,
+                    isError: true,
+                };
+            }
+            // --- Validate ---
+            if (skill.isEnabled && !skill.isEnabled()) {
+                return {
+                    content: `Skill "${skill.name}" is currently disabled.`,
+                    isError: true,
+                };
+            }
+            if (skill.modelInvocable === false) {
+                return {
+                    content: `Skill "${skill.name}" cannot be invoked by the model. It must be invoked directly by the user.`,
+                    isError: true,
+                };
+            }
+            // --- Resolve instructions ---
+            const resolved = await skillManager.resolveInstructions(skill, args, {
+                threadId: ctx.threadId,
+                traceId: ctx.traceId,
+                skillDir: skill.skillDir,
+            });
+            // --- Register skill-scoped tools ---
+            if (skill.tools?.length) {
+                for (const tool of skill.tools) {
+                    if (!registeredSkillTools.has(tool.name)) {
+                        toolExecutor.register(tool);
+                        registeredSkillTools.add(tool.name);
+                    }
+                }
+            }
+            // --- Track invocation ---
+            skillManager.markInvoked(skill.name);
+            // --- Build result ---
+            const parts = [
+                `<skill name="${skill.name}">`,
+                resolved,
+                '</skill>',
+            ];
+            // Append metadata hints for the model
+            if (skill.tools?.length) {
+                const toolNames = skill.tools.map(t => t.name).join(', ');
+                parts.push('', `This skill provides tools: ${toolNames}. Use them as needed.`);
+            }
+            if (skill.model) {
+                parts.push('', `[Note: This skill recommends model "${skill.model}" but the current model will be used.]`);
+            }
+            parts.push('', `Follow the instructions above from the "${skill.name}" skill.`);
+            return parts.join('\n');
+        },
+    };
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/tools/skill-tool.js.map

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

package/dist/tools/sql/index.d.ts

@@ -0,0 +1,4 @@
+export { createSqlTools } from './sql-tool-factory.js';
+export type { SqlToolFactoryOptions, SqlQueryRunner } from './sql-tool-factory.js';
+export type { SqlQueryDef } from './sql-query-def.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/sql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/sql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/tools/sql/index.js

@@ -0,0 +1,2 @@
+export { createSqlTools } from './sql-tool-factory.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/sql/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/sql/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/tools/sql/sql-query-def.d.ts

@@ -0,0 +1,22 @@
+import type { ZodObject, ZodRawShape } from 'zod';
+/**
+ * Declarative definition of a SQL query exposed as an agent tool.
+ *
+ * Each definition maps to a named, searchable query that the LLM can
+ * discover via `search_queries` and execute via `run_query`.
+ */
+export interface SqlQueryDef {
+    /** Unique identifier — use domain-prefixed snake_case (e.g. sales_revenue_by_month). */
+    name: string;
+    /** Human-readable description — the LLM uses this to decide which query to pick. */
+    description: string;
+    /** Parametrized SQL ($1, $2, …). Parameter order must match the Zod schema key order. */
+    sql: string;
+    /** Zod schema for query parameters. Key order determines $1, $2, … mapping. */
+    parameters: ZodObject<ZodRawShape>;
+    /** Tags for search filtering (e.g. ['sales', 'finance']). */
+    tags?: string[];
+    /** Per-query timeout in milliseconds. Default: 30 000. */
+    timeoutMs?: number;
+}
+//# sourceMappingURL=sql-query-def.d.ts.map

package/dist/tools/sql/sql-query-def.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-query-def.d.ts","sourceRoot":"","sources":["../../../src/tools/sql/sql-query-def.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IAEb,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IAEpB,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IAEZ,+EAA+E;IAC/E,UAAU,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IAEnC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/tools/sql/sql-query-def.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sql-query-def.js.map

package/dist/tools/sql/sql-query-def.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-query-def.js","sourceRoot":"","sources":["../../../src/tools/sql/sql-query-def.ts"],"names":[],"mappings":""}

package/dist/tools/sql/sql-tool-factory.d.ts

@@ -0,0 +1,28 @@
+import type { AgentTool } from '../../contracts/entities/agent-tool.js';
+import type { SqlQueryDef } from './sql-query-def.js';
+/** Minimal interface for a Postgres-compatible query runner (e.g. pg.Pool). */
+export interface SqlQueryRunner {
+    query(sql: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+export interface SqlToolFactoryOptions {
+    /** Connection pool or client that implements `query()`. */
+    pool: SqlQueryRunner;
+    /** Catalog of query definitions. */
+    queries: SqlQueryDef[];
+    /** Max characters for query results before truncation. Default: 8000. */
+    maxResultChars?: number;
+    /** Default per-query timeout in ms. Default: 30 000. */
+    defaultTimeoutMs?: number;
+    /** Prefix for tool names. Default: '' (empty). */
+    toolNamePrefix?: string;
+}
+/**
+ * Creates two meta-tools (`search_queries` + `run_query`) from a catalog of SQL queries.
+ *
+ * This keeps the LLM context small (2 tool definitions instead of N) while still
+ * giving the agent access to all queries via a search→execute workflow.
+ */
+export declare function createSqlTools(options: SqlToolFactoryOptions): AgentTool[];
+//# sourceMappingURL=sql-tool-factory.d.ts.map

package/dist/tools/sql/sql-tool-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-tool-factory.d.ts","sourceRoot":"","sources":["../../../src/tools/sql/sql-tool-factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAiBtD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,IAAI,EAAE,cAAc,CAAC;IAErB,oCAAoC;IACpC,OAAO,EAAE,WAAW,EAAE,CAAC;IAEvB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,EAAE,CAwI1E"}

package/dist/tools/sql/sql-tool-factory.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+/** Unwrap Zod wrappers (nullable, optional, default) to get the base type name. */
+function unwrapZodType(schema) {
+    if (schema instanceof z.ZodNullable || schema instanceof z.ZodOptional) {
+        return unwrapZodType(schema.unwrap());
+    }
+    if (schema instanceof z.ZodDefault) {
+        return unwrapZodType(schema.removeDefault());
+    }
+    if (schema instanceof z.ZodString)
+        return 'string';
+    if (schema instanceof z.ZodNumber)
+        return 'number';
+    if (schema instanceof z.ZodBoolean)
+        return 'boolean';
+    if (schema instanceof z.ZodEnum)
+        return 'enum';
+    return 'unknown';
+}
+/**
+ * Creates two meta-tools (`search_queries` + `run_query`) from a catalog of SQL queries.
+ *
+ * This keeps the LLM context small (2 tool definitions instead of N) while still
+ * giving the agent access to all queries via a search→execute workflow.
+ */
+export function createSqlTools(options) {
+    const { pool, queries, maxResultChars = 8_000, defaultTimeoutMs = 30_000, toolNamePrefix = '', } = options;
+    const queryMap = new Map();
+    for (const q of queries) {
+        queryMap.set(q.name, q);
+    }
+    const searchTool = {
+        name: `${toolNamePrefix}search_queries`,
+        description: 'Search available SQL queries by keyword. Returns matching query names, descriptions, and parameter info. Use this before run_query to find the right query.',
+        parameters: z.object({
+            keyword: z
+                .string()
+                .describe('Search term to match against query names, descriptions, and tags'),
+        }),
+        isConcurrencySafe: true,
+        isReadOnly: true,
+        maxResultChars,
+        async execute(rawArgs) {
+            const { keyword } = rawArgs;
+            const lower = keyword.toLowerCase();
+            const matches = queries.filter((q) => {
+                const haystack = `${q.name} ${q.description} ${(q.tags ?? []).join(' ')}`.toLowerCase();
+                return lower.split(/\s+/).every((term) => haystack.includes(term));
+            });
+            if (matches.length === 0) {
+                return `No queries found matching "${keyword}". Try a broader term.`;
+            }
+            const results = matches.map((q) => {
+                const shape = q.parameters.shape;
+                const params = {};
+                for (const [key, schema] of Object.entries(shape)) {
+                    const s = schema;
+                    params[key] = {
+                        type: unwrapZodType(s),
+                        nullable: s.isNullable(),
+                        description: s.description ?? '',
+                    };
+                }
+                return {
+                    name: q.name,
+                    description: q.description,
+                    parameters: params,
+                    tags: q.tags ?? [],
+                };
+            });
+            return JSON.stringify(results, null, 2);
+        },
+    };
+    // Build inline catalog for run_query description so the LLM knows all queries upfront
+    const catalog = queries.map((q) => {
+        const shape = q.parameters.shape;
+        const paramList = Object.entries(shape)
+            .map(([key, schema]) => {
+            const s = schema;
+            const nullable = s.isNullable() ? ', nullable' : '';
+            return `${key} (${unwrapZodType(s)}${nullable}): ${s.description ?? ''}`;
+        })
+            .join('; ');
+        return `- ${q.name}: ${q.description} Params: { ${paramList} }`;
+    }).join('\n');
+    const runTool = {
+        name: `${toolNamePrefix}run_query`,
+        description: `Execute a SQL query by name. Pass params as key-value pairs. Use null for optional/nullable params you don't need.\n\nAvailable queries:\n${catalog}`,
+        parameters: z.object({
+            query_name: z.string().describe('Name of the query to execute'),
+            params: z
+                .record(z.unknown())
+                .describe('Parameters as key-value pairs. Use null for nullable params you want to skip'),
+        }),
+        isConcurrencySafe: true,
+        isReadOnly: true,
+        maxResultChars,
+        timeoutMs: defaultTimeoutMs,
+        async execute(rawArgs) {
+            const { query_name, params } = rawArgs;
+            const def = queryMap.get(query_name);
+            if (!def) {
+                return {
+                    content: `Query "${query_name}" not found. Use search_queries to find available queries.`,
+                    isError: true,
+                };
+            }
+            // Validate params against the query's Zod schema
+            const parsed = def.parameters.safeParse(params);
+            if (!parsed.success) {
+                const errors = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+                return {
+                    content: `Invalid parameters:\n${errors.join('\n')}`,
+                    isError: true,
+                };
+            }
+            // Map values in schema key order to match $1, $2, ... in SQL
+            const schemaKeys = Object.keys(def.parameters.shape);
+            const data = parsed.data;
+            const values = schemaKeys.map((key) => data[key] ?? null);
+            try {
+                const result = await pool.query(def.sql, values);
+                if (result.rows.length === 0) {
+                    return 'Query returned 0 rows.';
+                }
+                return JSON.stringify(result.rows, null, 2);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return { content: `Query execution failed: ${message}`, isError: true };
+            }
+        },
+    };
+    return [searchTool, runTool];
+}
+//# sourceMappingURL=sql-tool-factory.js.map

package/dist/tools/sql/sql-tool-factory.js.map

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

package/dist/tools/tool-executor.d.ts

@@ -0,0 +1,67 @@
+import type { AgentTool, ToolProgressCallback } from '../contracts/entities/agent-tool.js';
+import type { AgentToolResult } from '../contracts/entities/tool-call.js';
+import type { ToolDefinition } from '../llm/message-types.js';
+export interface ToolCallRequest {
+    name: string;
+    args: unknown;
+}
+export interface ToolHooks {
+    beforeToolCall?: (name: string, args: unknown) => void | Promise<void>;
+    afterToolCall?: (name: string, args: unknown, result: AgentToolResult) => void | Promise<void>;
+    onToolProgress?: (name: string, toolCallId: string, data: Record<string, unknown>) => void;
+}
+export interface ExecuteOptions {
+    signal?: AbortSignal;
+    toolCallId?: string;
+    threadId?: string;
+    onProgress?: ToolProgressCallback;
+}
+/**
+ * Registers tools, validates args via Zod, converts to JSON Schema,
+ * and executes tools with full pipeline:
+ *
+ *   1. Tool lookup
+ *   2. Zod schema validation
+ *   3. Semantic validation (tool.validate)
+ *   4. Before hook
+ *   5. Per-tool timeout wrapping
+ *   6. Retry for transient failures
+ *   7. Execute with progress callback
+ *   8. Result truncation (tool.maxResultChars)
+ *   9. Result mapping (tool.mapResult)
+ *  10. After hook
+ */
+export declare class ToolExecutor {
+    private readonly tools;
+    private readonly hooks;
+    constructor(hooks?: ToolHooks);
+    register(tool: AgentTool): void;
+    unregister(name: string): boolean;
+    listTools(): AgentTool[];
+    getToolDefinitions(): ToolDefinition[];
+    execute(name: string, args: unknown, signalOrOptions?: AbortSignal | ExecuteOptions): Promise<AgentToolResult>;
+    executeParallel(calls: ToolCallRequest[], signal?: AbortSignal): Promise<AgentToolResult[]>;
+    /**
+     * Executes tool calls respecting concurrency safety:
+     * - Consecutive concurrency-safe tools run in parallel
+     * - Non-safe tools run serially (one at a time)
+     * - Results are returned in the original call order
+     */
+    executePartitioned(calls: Array<{
+        id: string;
+        name: string;
+        args: unknown;
+    }>, signal?: AbortSignal): Promise<Array<{
+        id: string;
+        result: AgentToolResult;
+    }>>;
+    /**
+     * Build an AbortSignal combining parent signal + per-tool timeout.
+     */
+    private buildSignal;
+    /**
+     * Execute with retry support using the existing retry utility.
+     */
+    private executeWithRetry;
+}
+//# sourceMappingURL=tool-executor.d.ts.map

package/dist/tools/tool-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.d.ts","sourceRoot":"","sources":["../../src/tools/tool-executor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC5F;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAEtB,KAAK,GAAE,SAAc;IAIjC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,SAAS,IAAI,SAAS,EAAE;IAIxB,kBAAkB,IAAI,cAAc,EAAE;IAWhC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAkF9G,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAIjG;;;;;OAKG;IACG,kBAAkB,CACtB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,EACzD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAqD1D;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;OAEG;YACW,gBAAgB;CAgC/B"}