@vinhnt-sdk/core 0.6.1 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # @vinhnt-sdk/core
 
-> Version: 0.1.2-beta.0 | Status: BETA
+> Version: 0.6.1 | Status: STABLE
 
-Core agent engine for vinhnt-sdk — kernel, orchestration, streaming, event bus, and circuit breaker.
+Core agent engine for vinhnt-sdk — kernel, orchestration, streaming, event bus, and workflows.
 
 ## Install
 
@@ -14,63 +14,79 @@ npm install @vinhnt-sdk/core
 pnpm add @vinhnt-sdk/core
 ```
 
+## Features
+
+- **AgentKernel** — Main orchestration engine with configurable steps, retries, and circuit breaker
+- **RunUsage** — Nested usage metrics (tokens, cost, duration, tool calls)
+- **AgentRunHandle** — Lifecycle management with cancel, events streaming, and completion tracking
+- **Agent-as-Tool** — Delegate work to sub-agents via tool interface
+- **Workflow** — Parallel, sequential, and conditional step execution
+- **Guardrails** — Input/output safety tripwires
+- **Guard System** — Monotonic guard decisions for tool execution
+
 ## Quick Start
 
 ```typescript
-import { AgentKernel } from '@vinhnt-sdk/core';
-import type { ModelProvider } from '@vinhnt-sdk/schema';
-
-// Create a simple in-memory store
-class SimpleStore {
-  private events: any[] = [];
-  async append(event: any) { this.events.push(event); }
-  async list(runId: string) { return this.events.filter(e => e.runId === runId); }
-  async getNextSequence() { return 1; }
-  async saveSnapshot() {}
-  async getSnapshot() { return null; }
-  async getSnapshotAfterSequence() { return null; }
-  subscribe() { return () => {}; }
-}
+import { AgentKernel, InMemoryEventBus } from "@vinhnt-sdk/core";
+import { defineTool } from "@vinhnt-sdk/tools";
+import { z } from "zod";
+
+const calculatorTool = defineTool({
+  name: "calculator",
+  description: "Perform arithmetic calculations",
+  risk: "read",
+  input: z.object({
+    expression: z.string(),
+  }),
+  async execute(input) {
+    const parts = input.expression.match(/^(\d+)\s*([+\-*/])\s*(\d+)$/);
+    if (!parts) throw new Error("Invalid expression");
+    const [, a, op, b] = parts;
+    const numA = parseInt(a, 10);
+    const numB = parseInt(b, 10);
+    switch (op) {
+      case "+": return { result: numA + numB };
+      case "-": return { result: numA - numB };
+      case "*": return { result: numA * numB };
+      case "/": return { result: numA / numB };
+      default: throw new Error("Unknown operator");
+    }
+  },
+}).toDefinition();
 
-// Create kernel
 const kernel = new AgentKernel({
   model: yourModelProvider,
-  store: new SimpleStore(),
-  maxSteps: 50,
-});
-
-// Create run handle
-const handle = kernel.createRunHandle("Hello!", {
-  sessionId: "session-123",
-  agentId: "my-agent",
-  userId: "user-1",
+  store: new InMemoryEventBus(),
+  tools: [calculatorTool],
+  maxSteps: 10,
 });
 
-// Listen to events
-handle.onEvent((event) => {
-  console.log(event.type); // "agent.started", "agent.completed", etc.
+const handle = kernel.createRunHandle("Calculate 2 + 2", {
+  sessionId: "session-1",
+  agentId: "calculator-agent",
 });
 
-// Wait for completion
 const result = await handle.completed;
 console.log(result.status); // "succeeded"
+console.log(result.usage);  // RunUsage with nested metrics
 ```
 
 ## API Reference
 
 ### Core Classes
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `AgentKernel` | Class | Main kernel for agent orchestration |
-| `InMemoryEventBus` | Class | Typed pub/sub event bus |
-| `InMemorySessionState` | Class | Session state management |
-| `SessionRunCoordinator` | Class | Run coordination |
-| `InMemoryAgentRegistry` | Class | Agent registry |
-| `InMemoryModelRegistry` | Class | Model registry |
-| `InMemoryApprovalStore` | Class | Approval storage |
-| `WorkspaceManager` | Class | Workspace management |
-| `Tracer` | Class | Execution tracing |
+| Export | Description |
+|--------|-------------|
+| `AgentKernel` | Main kernel for agent orchestration |
+| `KernelError` | Error class for kernel failures |
+| `InMemoryEventBus` | Typed pub/sub event bus |
+| `InMemorySessionState` | Session state management |
+| `SessionRunCoordinator` | Run coordination across sessions |
+| `InMemoryAgentRegistry` | Agent registry for sub-agents |
+| `InMemoryModelRegistry` | Model registry for multi-model routing |
+| `InMemoryApprovalStore` | Approval storage for permissions |
+| `WorkspaceManager` | Workspace file management |
+| `Tracer` | Execution tracing |
 
 ### Kernel Methods
 
@@ -81,13 +97,12 @@ console.log(result.status); // "succeeded"
 | `streamRun(prompt, ctx)` | Stream run events |
 | `reconfigure(config)` | Reconfigure kernel |
 
-### Run Handle
+### AgentRunHandle
 
 ```typescript
 const handle = kernel.createRunHandle(prompt, {
   sessionId: "session-123",
   agentId: "my-agent",
-  userId: "user-1",
 });
 
 // Properties
@@ -97,7 +112,7 @@ handle.isCompleted;  // Is completed
 handle.isCancelled;  // Is cancelled
 
 // Methods
-handle.onEvent(handler);  // Listen to events
+handle.onEvent(handler);  // Subscribe to events
 handle.events();          // Async iterable of events
 handle.cancel();          // Cancel run
 
@@ -105,84 +120,134 @@ handle.cancel();          // Cancel run
 const result = await handle.completed;
 ```
 
-### Event Bus
+### AgentRunResult (Nested Usage Pattern)
 
 ```typescript
-import { InMemoryEventBus } from '@vinhnt-sdk/core';
+interface AgentRunResult {
+  readonly runId: RunId;
+  readonly status: "succeeded" | "failed" | "cancelled";
+  readonly output?: string;
+  readonly error?: string;
+  readonly usage?: RunUsage;
+}
+
+interface RunUsage {
+  readonly totalSteps: number;
+  readonly durationMs?: number;
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly reasoningTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+  readonly totalTokens?: number;
+  readonly cost?: number;
+  readonly toolCallsCount?: number;
+  readonly model?: string;
+  readonly provider?: string;
+  readonly stopReason?: string;
+  readonly raw?: Record<string, unknown>;
+}
+```
 
-const bus = new InMemoryEventBus();
+### Agent-as-Tool
 
-// Subscribe to events
-const unsubscribe = bus.subscribe(eventDef, (event) => {
-  console.log(event.type, event.data);
+```typescript
+import { agentAsTool, createHandoffTool } from "@vinhnt-sdk/core";
+
+const codeReviewTool = agentAsTool({
+  agentId: "code-reviewer",
+  description: "Review code for issues",
+  kernel,
 });
 
-// Publish events
-bus.publish(eventDef, data, { traceId: "123", aggregateId: "run-1" });
+// Use in another agent
+const kernel2 = new AgentKernel({
+  model: provider,
+  store: eventStore,
+  tools: [codeReviewTool],
+});
+```
 
-// Stream events
-for await (const event of bus.stream(eventDef, abortSignal)) {
-  console.log(event);
-}
+### Workflow
 
-// Stream with replay
-for await (const event of bus.streamWithReplay(eventDef, "run-1")) {
-  console.log(event);
-}
+```typescript
+import { parallel, sequential, conditional } from "@vinhnt-sdk/core";
+
+// Sequential execution
+const result = await sequential([
+  { step: step1 },
+  { step: step2 },
+  { step: step3 },
+], context);
+
+// Parallel execution
+const results = await parallel([
+  { step: fetchUsers },
+  { step: fetchOrders },
+  { step: fetchProducts },
+], context);
+
+// Conditional execution
+const result = await conditional([
+  { branch: "if-high-priority", condition: (ctx) => ctx.priority === "high", step: handleHighPriority },
+  { branch: "default", step: handleNormal },
+], context);
 ```
 
-### Circuit Breaker
+### Guardrails
 
 ```typescript
-// Built into kernel
-const kernel = new AgentKernel({
-  model: yourModelProvider,
-  store: yourStore,
-  maxSteps: 50,
-  circuitBreaker: {
-    failureThreshold: 3,
-    successThreshold: 2,
-    resetTimeoutMs: 30_000,
-    maxRetries: 3,
-    retryBackoffMs: 1000,
-    maxRetryBackoffMs: 30_000,
-  },
+import { runGuardrails, maxLengthGuardrail, blocklistGuardrail } from "@vinhnt-sdk/core";
+
+const result = await runGuardrails({
+  input: userInput,
+  guardrails: [
+    maxLengthGuardrail({ maxLength: 10000 }),
+    blocklistGuardrail({ patterns: ["password", "secret"] }),
+  ],
 });
+
+if (result.blocked) {
+  console.log("Input blocked:", result.reason);
+}
 ```
 
 ## Dependencies
 
-- `@vinhnt-sdk/schema` workspace:*
-- `@vinhnt-sdk/security` workspace:*
+- `@vinhnt-sdk/schema` >=0.5.0
+- `@vinhnt-sdk/event` workspace:*
+- `@vinhnt-sdk/llm` workspace:*
+- `@vinhnt-sdk/permission` workspace:*
+- `@vinhnt-sdk/sandbox` workspace:*
+- `@vinhnt-sdk/guard` workspace:*
+- `@vinhnt-sdk/guardrails` workspace:*
+- `@vinhnt-sdk/workflow` workspace:*
+- `@vinhnt-sdk/session` workspace:*
 - `@vinhnt-sdk/knowledge` workspace:*
 - `@vinhnt-sdk/tools` workspace:*
+- `@vinhnt-sdk/step-executor` workspace:*
 - `zod` ^4.4.3
 
-## Peer Dependencies
-
-None
-
 ## Usage Examples
 
 ### Basic Agent Run
 
 ```typescript
-import { AgentKernel } from '@vinhnt-sdk/core';
+import { AgentKernel, InMemoryEventBus } from "@vinhnt-sdk/core";
 
 const kernel = new AgentKernel({
   model: yourModelProvider,
-  store: yourStore,
+  store: new InMemoryEventBus(),
 });
 
-// Simple run
 const handle = kernel.createRunHandle("Write a hello world program", {
   sessionId: "session-1",
   agentId: "coder",
-  userId: "developer",
 });
 
 const result = await handle.completed;
 console.log(result.output);
+console.log(result.usage?.totalTokens);
 ```
 
 ### Streaming Events
@@ -191,10 +256,8 @@ console.log(result.output);
 const handle = kernel.createRunHandle("Tell me a story", {
   sessionId: "session-2",
   agentId: "storyteller",
-  userId: "user-1",
 });
 
-// Stream events
 for await (const event of handle.events()) {
   switch (event.type) {
     case "agent.started":
@@ -218,7 +281,6 @@ for await (const event of handle.events()) {
 ```typescript
 const handle = kernel.createRunHandle("Long running task", ctx);
 
-// Cancel after 5 seconds
 setTimeout(() => handle.cancel(), 5000);
 
 const result = await handle.completed;

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 export { AgentKernel, KernelError } from "./kernel/kernel.js";
 export { canTransitionRun, terminalRunStatuses } from "./kernel/state-machine.js";
 export { RunStateMachine } from "@vinhnt-sdk/step-executor";
-export type { AgentKernelConfig, RunHandle, AgentRunHandle, AgentRunResult } from "./kernel/kernel-types.js";
+export type { AgentKernelConfig, ModelSettings, RunHandle, AgentRunHandle, AgentRunResult, RunUsage } from "./kernel/kernel-types.js";
+export { AgentRunContext } from "./kernel/run-context.js";
+export type { ApprovalRecord } from "./kernel/run-context.js";
 export { createAgent } from "./agent/agent-factory.js";
 export type { CreateAgentParams } from "./agent/agent-factory.js";
 export { agentAsTool, createHandoffTool } from "./kernel/agent-as-tool.js";
 export type { AgentAsToolOptions } from "./kernel/agent-as-tool.js";
+export { createHandoff, isHandoff, HANDOFF_SYMBOL, HandoffTracker } from "./kernel/handoff.js";
+export type { Handoff, HandoffToolOptions, HandoffRecord } from "./kernel/handoff.js";
 export { createUpdatePlanTool, createGetPlanTool } from "./tools/update-plan.js";
 export type { Plan, PlanStep } from "./tools/update-plan.js";
 export { InMemoryEventBus } from "@vinhnt-sdk/event";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -7,10 +7,13 @@
 export { AgentKernel, KernelError } from "./kernel/kernel.js";
 export { canTransitionRun, terminalRunStatuses } from "./kernel/state-machine.js";
 export { RunStateMachine } from "@vinhnt-sdk/step-executor";
+export { AgentRunContext } from "./kernel/run-context.js";
 // === Agent system ===
 export { createAgent } from "./agent/agent-factory.js";
 // === Agent-as-Tool ===
 export { agentAsTool, createHandoffTool } from "./kernel/agent-as-tool.js";
+// === Handoff ===
+export { createHandoff, isHandoff, HANDOFF_SYMBOL, HandoffTracker } from "./kernel/handoff.js";
 // === Plan tracking ===
 export { createUpdatePlanTool, createGetPlanTool } from "./tools/update-plan.js";
 // === Event bus ===

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,kDAAkD;AAClD,EAAE;AACF,6CAA6C;AAC7C,iDAAiD;AAEjD,gCAAgC;AAEhC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,uBAAuB;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,wBAAwB;AAExB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAG3E,wBAAwB;AAExB,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGjF,oBAAoB;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,6BAA6B;AAE7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,yBAAyB;AAEzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,yBAAyB;AAEzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,4BAA4B;AAE5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,oBAAoB;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,uBAAuB;AAEvB,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,kBAAkB;AAElB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,iBAAiB;AAEjB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/C,uBAAuB;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,mBAAmB;AAEnB,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGzE,qBAAqB;AAErB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAYzH,OAAO,EACL,QAAQ,EACR,kBAAkB,EAAE,oBAAoB,EAAE,qBAAqB,EAC/D,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAC3D,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAClD,uBAAuB,EAAE,cAAc,EACvC,qBAAqB,EAAE,eAAe,EAAE,YAAY,EACpD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EACjD,kBAAkB,EAAE,WAAW,GAChC,MAAM,oBAAoB,CAAC;AAI5B,+BAA+B;AAE/B,OAAO,EACL,UAAU,EAAE,gBAAgB,EAAE,2BAA2B,EACzD,YAAY,EAAE,gBAAgB,GAC/B,MAAM,mBAAmB,CAAC;AAM3B,oCAAoC;AAEpC,OAAO,EACL,kBAAkB,EAAE,mBAAmB,EAAE,kBAAkB,EAC3D,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EACzD,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,oBAAoB;AAEpB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAGzE,wDAAwD;AAExD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/kernel/handoff.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Handoff — signal that transfers control to another agent.
+ *
+ * When a tool returns a `Handoff`, the run loop detects it and swaps the
+ * active agent. The new agent takes over the conversation from the next step.
+ *
+ * Follows the OpenAI Agents SDK pattern: handoff is a special tool return
+ * value that the runner intercepts, not a regular tool output.
+ *
+ * @example
+ * ```ts
+ * import { handoff, type Handoff } from '@vinhnt-sdk/core';
+ *
+ * // Define a handoff tool
+ * const transferToBilling = handoff({
+ *   agentId: 'billing-agent',
+ *   toolName: 'transfer_to_billing',
+ *   toolDescription: 'Transfer to billing specialist for payment issues',
+ * });
+ *
+ * // Register on agent
+ * const triageAgent = createAgent({
+ *   id: 'triage',
+ *   tools: [transferToBilling, ...otherTools],
+ * });
+ *
+ * // When LLM calls transfer_to_billing, run loop detects Handoff
+ * // and swaps active agent to billing-agent.
+ * ```
+ */
+import type { AgentId } from "@vinhnt-sdk/schema";
+import { type ToolDefinition } from "@vinhnt-sdk/tools";
+/**
+ * Symbol used to identify handoff results in tool output.
+ * The run loop checks for this symbol to detect agent transfers.
+ */
+export declare const HANDOFF_SYMBOL: unique symbol;
+/**
+ * A handoff result — signals the run loop to transfer control.
+ *
+ * Not a regular tool output. The run loop intercepts this and swaps agents.
+ */
+export interface Handoff {
+    readonly [key: symbol]: true | undefined;
+    readonly __handoff: true;
+    /** Target agent to transfer control to. */
+    readonly targetAgentId: AgentId;
+    /** Reason for the handoff (for logging/tracing). */
+    readonly reason: string;
+    /** Optional summary of conversation so far (passed to target agent). */
+    readonly summary?: string | undefined;
+    /** Optional context data to pass to the target agent. */
+    readonly context?: Record<string, unknown> | undefined;
+}
+/**
+ * Check if a value is a Handoff.
+ */
+export declare function isHandoff(value: unknown): value is Handoff;
+/**
+ * Create a Handoff result.
+ */
+export declare function createHandoff(options: {
+    targetAgentId: AgentId;
+    reason: string;
+    summary?: string | undefined;
+    context?: Record<string, unknown> | undefined;
+}): Handoff;
+export interface HandoffToolOptions {
+    /** Target agent ID to transfer to. */
+    readonly agentId: AgentId;
+    /** Tool name (default: "transfer_to_{agentId}") */
+    readonly toolName?: string;
+    /** Tool description for the LLM. */
+    readonly toolDescription: string;
+    /** Callback before handoff (for logging). */
+    readonly onHandoff?: (reason: string) => void | Promise<void>;
+}
+/**
+ * Create a handoff tool — when LLM calls it, control transfers to target agent.
+ *
+ * Unlike `agentAsTool` (parent keeps control), handoff gives full control
+ * to the target agent. The original agent pauses until the target completes
+ * or transfers back.
+ *
+ * @example
+ * ```ts
+ * const handoffTool = createHandoffTool({
+ *   agentId: 'billing' as AgentId,
+ *   toolDescription: 'Transfer to billing specialist for payment issues',
+ *   onHandoff: (reason) => console.log('Transferring:', reason),
+ * });
+ *
+ * // Register on triage agent
+ * triageAgent.tools.push(handoffTool);
+ *
+ * // When LLM calls transfer_to_billing:
+ * // 1. Run loop executes the tool
+ * // 2. Tool returns Handoff object
+ * // 3. Run loop detects Handoff
+ * // 4. Active agent swaps to billing-agent
+ * // 5. Billing agent continues the conversation
+ * ```
+ */
+export declare function createHandoffTool(options: HandoffToolOptions): ToolDefinition;
+/**
+ * Record of a handoff that occurred during a run.
+ */
+export interface HandoffRecord {
+    /** Timestamp of the handoff. */
+    readonly timestamp: number;
+    /** Agent that initiated the handoff. */
+    readonly fromAgentId: AgentId;
+    /** Agent that received control. */
+    readonly toAgentId: AgentId;
+    /** Reason for the handoff. */
+    readonly reason: string;
+    /** Step number when handoff occurred. */
+    readonly step: number;
+}
+/**
+ * Track handoff history for a run (cycle detection, debugging).
+ */
+export declare class HandoffTracker {
+    private readonly history;
+    private readonly maxDepth;
+    constructor(maxDepth?: number);
+    /** Record a handoff. Returns false if cycle detected or max depth exceeded. */
+    record(record: HandoffRecord): boolean;
+    /** Get the full handoff history. */
+    getHistory(): readonly HandoffRecord[];
+    /** Get the chain of agent IDs in this handoff chain. */
+    getAgentChain(): AgentId[];
+    /** Check if an agent has already been visited (cycle detection). */
+    hasVisited(agentId: AgentId): boolean;
+}
+//# sourceMappingURL=handoff.d.ts.map

package/dist/kernel/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/kernel/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAyC,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAM1D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAC/C,GAAG,OAAO,CASV;AAMD,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,cAAc,CA6B7E;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,MAAW;IAIjC,+EAA+E;IAC/E,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAgBtC,oCAAoC;IACpC,UAAU,IAAI,SAAS,aAAa,EAAE;IAItC,wDAAwD;IACxD,aAAa,IAAI,OAAO,EAAE;IAI1B,oEAAoE;IACpE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;CAGtC"}