Merge branch 'main' into lazy-init

Author: nomisRev

.github/workflows/checks.yml

@@ -0,0 +1,84 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will build a Java project with Gradle and cache/restore any dependencies to improve the workflow execution time
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-gradle
+
+name: Checks
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  compilation:
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Configure Git
+        run: |
+          git config --global core.autocrlf input
+      - uses: actions/checkout@v4
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'corretto'
+
+      # Configure Gradle for optimal use in GitHub Actions, including caching of downloaded dependencies.
+      # See: https://github.com/gradle/actions/blob/main/setup-gradle/README.md
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0
+
+      - name: Assemble with Gradle Wrapper
+        run: ./gradlew assemble
+
+      - name: TestClasses with Gradle Wrapper
+        run: ./gradlew jvmTestClasses jsTestClasses
+
+  tests:
+
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+
+    strategy:
+      matrix:
+        os: [ ubuntu-latest, windows-latest ]
+
+    steps:
+      - name: Configure Git
+        run: |
+          git config --global core.autocrlf input
+      - uses: actions/checkout@v4
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'corretto'
+
+      # Configure Gradle for optimal use in GitHub Actions, including caching of downloaded dependencies.
+      # See: https://github.com/gradle/actions/blob/main/setup-gradle/README.md
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0
+
+      - name: JvmTest with Gradle Wrapper
+        env:
+          JB_SPACE_CLIENT_ID: ${{ secrets.JB_SPACE_CLIENT_ID }}
+          JB_SPACE_CLIENT_SECRET: ${{ secrets.JB_SPACE_CLIENT_SECRET }}
+          USER_STGN_JWT_TOKEN: ${{ secrets.USER_STGN_JWT_TOKEN }}
+        run: ./gradlew jvmTest --continue
+
+      - name: Collect reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: reports-${{ matrix.os }}
+          path: |
+            **/build/reports/

.gitignore

@@ -1,4 +1,5 @@
 .gradle
 .idea
 .kotlin
-build
+build
+**/.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This repository contains the Koan Agents framework, a Kotlin multiplatform library for building AI agents. The framework enables creating intelligent agents that interact with tools, handle complex workflows, and maintain context across conversations.
+
+## Building and Testing
+
+### Basic Commands
+
+```bash
+# Build the project
+./gradlew assemble
+
+# Compile test classes
+./gradlew jvmTestClasses jsTestClasses
+
+# Run all JVM tests
+./gradlew jvmTest
+
+# Run all JS tests
+./gradlew jsTest
+
+# Run a specific test class
+./gradlew jvmTest --tests "fully.qualified.TestClassName"
+# Example:
+./gradlew jvmTest --tests "ai.grazie.code.agents.test.SimpleAgentIntegrationTest"
+
+# Run a specific test method
+./gradlew jvmTest --tests "fully.qualified.TestClassName.testMethodName"
+# Example:
+./gradlew jvmTest --tests "ai.grazie.code.agents.test.SimpleAgentIntegrationTest.simpleChatAgent should call default tools"
+```
+
+## Architecture
+
+### Key Modules
+
+1. **agents-core**: Core abstractions and interfaces
+   - AIAgent, AIAgentStrategy, event handling system
+
+2. **agents-core-tools**: Tool infrastructure
+   - Tool, ToolRegistry, ToolDescriptor
+
+3. **agents-local**: Local execution implementation
+   - KotlinAIAgent, execution strategies, session management
+
+4. **agents-local-features**: Extensible agent capabilities
+   - Memory, tracing, and other features 
+
+5. **prompt**: LLM interaction layer
+   - LLM executors, prompt construction, structured data processing
+
+### Core Concepts
+
+- **Agents**: State-machine graphs with nodes that process inputs and produce outputs
+- **Tools**: Encapsulated actions with standardized interfaces
+- **Strategies**: Define agent behavior and execution flow
+- **Features**: Installable extensions that enhance agent capabilities
+- **Event Handling**: System for intercepting and processing agent lifecycle events
+
+### Implementation Pattern
+
+1. Define tools that agents can use
+2. Register tools in the ToolRegistry
+3. Configure agent with strategy
+4. Set up communication (if integrating with external systems)
+
+## Testing
+
+The project has extensive testing support:
+
+- **Mocking LLM responses**:
+  ```kotlin
+  val mockLLMApi = getMockExecutor(toolRegistry, eventHandler) {
+      mockLLMAnswer("Hello!") onRequestContains "Hello"
+      mockLLMToolCall(CreateTool, CreateTool.Args("solve")) onRequestEquals "Solve task"
+  }
+  ```
+
+- **Mocking tool calls**:
+  ```kotlin
+  mockTool(PositiveToneTool) alwaysReturns "The text has a positive tone."
+  ```
+
+- **Testing agent graph structure**:
+  ```kotlin
+  testGraph {
+      assertStagesOrder("first", "second")
+      // ...
+  }
+  ```
+
+For detailed testing guidelines, refer to `agents/TESTING.md`.

agents/README.md

@@ -64,10 +64,6 @@ To start working with IdeFormer in your project, you will need:
 - `ai.jetbrains.code.agents`
     - [agents-core](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/agents-core)
     - [agents-core-tools](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/agents-core-tools)
-    - [agents-tools-registry](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/agents-tools-registry)
-    - [code-agents-ideformer-client](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/code-agents-ideformer-client)
-    - [code-agents-ideformer-daemon](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/code-agents-ideformer-daemon)
-    - [code-agents-ideformer-executable](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.agents/code-agents-ideformer-executable)
 - `ai.jetbrains.code.files`
     - [code-files-jvm](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.files/code-files-jvm)
     - [code-files-model](https://jetbrains.team/p/grazi/packages/maven/grazie-platform-public/ai.jetbrains.code.files/code-files-model)
@@ -466,17 +462,3 @@ and ensuring proper communication with the IdeFormer service.
 This framework is flexible and allows you to customize the tools and the agent's logic for any arbitrary use case.
 Feel free to extend it to suit more complex scenarios, such as multi-stage processes, integrating additional tools,
 or handling different types of events and exceptions.
-
-[^1]:
-    The required version for these dependencies is influenced by the version of `code-engine` you are using.
-    For example, if you are using `1.0.0-beta.26+0.4.16`, then you will need either `0.4.16` or later patches.
-
-[^2]:
-    Defining tool descriptors in code is good for fast experiments, but for production purposes this method is not recommended.
-    Please contribute to `GlobalAgentToolsRegistry.Tools` and then feel free to use the `fromRegistry` method instead.
-    You can read more about contributing [here](https://github.com/JetBrains/koan-agents/tree/main/agents/agents-tools-registry#contributing-tools).
-
-[^3]:
-    Writing prompts in code is good for fast experiments, but for production purposes this method is not recommended.
-    Please contribute to `GlobalAgentToolsRegistry.Prompts` and then feel free to use `fromRegistry` method.
-    You can read more about contributing [here](https://github.com/JetBrains/koan-agents/tree/main/agents/agents-tools-registry#contributing-prompts).

agents/TESTING.md

@@ -452,7 +452,7 @@ fun testMultiStageAgentStructure() = runBlocking {
         mockLLMToolCall(CreateTool, CreateTool.Args("solve")) onRequestEquals "Solve task"
     }
 
-    val basePrompt = prompt(JetBrainsAIModels.OpenAI.GPT4oMini, "test") {}
+    val basePrompt = prompt(OpenAIModels.GPT4o, "test") {}
 
     KotlinAIAgent(
         toolRegistry = toolRegistry,

agents/agents-core-tools/build.gradle.kts

@@ -16,6 +16,12 @@ kotlin {
             }
         }
 
+        jvmMain {
+            dependencies {
+                implementation(kotlin("reflect"))
+            }
+        }
+
         commonTest {
             dependencies {
                 implementation(kotlin("test"))
@@ -26,6 +32,7 @@ kotlin {
         jvmTest {
             dependencies {
                 implementation(kotlin("test-junit5"))
+                implementation(libs.junit.jupiter.params)
             }
         }
     }

agents/agents-core-tools/src/commonMain/kotlin/ai/grazie/code/agents/core/tools/Tool.kt

@@ -1,6 +1,6 @@
 package ai.grazie.code.agents.core.tools
 
-import ai.grazie.code.agents.core.tools.serialization.JsonForTool
+import ai.grazie.code.agents.core.tools.serialization.ToolJson
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
@@ -167,29 +167,29 @@ abstract class Tool<TArgs : Tool.Args, TResult : ToolResult> {
      * @param args The arguments to be encoded.
      * @return A JsonObject representing the encoded arguments.
      */
-    fun encodeArgs(args: TArgs): JsonObject = JsonForTool.encodeToJsonElement(argsSerializer, args).jsonObject
+    fun encodeArgs(args: TArgs): JsonObject = ToolJson.encodeToJsonElement(argsSerializer, args).jsonObject
     /**
      * Encodes the provided arguments into a JSON string representation using the configured serializer.
      *
      * @param args the arguments to be encoded into a JSON string
      * @return the JSON string representation of the provided arguments
      */
-    fun encodeArgsToString(args: TArgs): String = JsonForTool.encodeToString(argsSerializer, args)
+    fun encodeArgsToString(args: TArgs): String = ToolJson.encodeToString(argsSerializer, args)
 
     /**
      * Decodes the provided raw JSON arguments into an instance of the specified arguments type.
      *
      * @param rawArgs the raw JSON object that contains the encoded arguments
      * @return the decoded arguments of type TArgs
      */
-    fun decodeArgs(rawArgs: JsonObject): TArgs = JsonForTool.decodeFromJsonElement(argsSerializer, rawArgs)
+    fun decodeArgs(rawArgs: JsonObject): TArgs = ToolJson.decodeFromJsonElement(argsSerializer, rawArgs)
     /**
      * Decodes a raw string representation of arguments into the corresponding object of type TArgs.
      *
      * @param rawArgs The raw string containing the encoded arguments.
      * @return The decoded arguments as an instance of type TArgs.
      */
-    fun decodeArgsFromString(rawArgs: String): TArgs = JsonForTool.decodeFromString(argsSerializer, rawArgs)
+    fun decodeArgsFromString(rawArgs: String): TArgs = ToolJson.decodeFromString(argsSerializer, rawArgs)
 
 
     /**

agents/agents-core-tools/src/commonMain/kotlin/ai/grazie/code/agents/core/tools/ToolDescriptors.kt

@@ -1,8 +1,6 @@
 package ai.grazie.code.agents.core.tools
 
-import kotlinx.serialization.KSerializer
-import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.builtins.serializer
+
 import kotlin.enums.EnumEntries
 
 /**
@@ -19,8 +17,8 @@ import kotlin.enums.EnumEntries
 data class ToolDescriptor(
     val name: String,
     val description: String,
-    val requiredParameters: List<ToolParameterDescriptor<*>> = emptyList(),
-    val optionalParameters: List<ToolParameterDescriptor<*>> = emptyList(),
+    val requiredParameters: List<ToolParameterDescriptor> = emptyList(),
+    val optionalParameters: List<ToolParameterDescriptor> = emptyList(),
 )
 
 /**
@@ -37,11 +35,8 @@ data class ToolDescriptor(
  * @property type The data type of the tool parameter.
  * @property defaultValue The default value of the tool parameter (nullable).
  */
-data class ToolParameterDescriptor<T>(
-    val name: String,
-    val description: String,
-    val type: ToolParameterType<T>,
-    val defaultValue: T? = null
+data class ToolParameterDescriptor(
+    val name: String, val description: String, val type: ToolParameterType
 )
 
 /**
@@ -52,58 +47,48 @@ data class ToolParameterDescriptor<T>(
  * @param T The type of data that the tool parameter represents.
  * @property name The name associated with the type of tool parameter.
  */
-sealed class ToolParameterType<T>(val name: kotlin.String) {
-    /**
-     * Describes how to serialize default value for a given type
-     */
-    internal abstract val serializer: KSerializer<T>
+sealed class ToolParameterType(val name: kotlin.String) {
 
     /**
      * Represents a string type parameter.
      */
-    data object String : ToolParameterType<kotlin.String>("STRING") {
-        override val serializer = kotlin.String.serializer()
-    }
+    data object String : ToolParameterType("STRING")
 
     /**
      * Represents an integer type parameter.
      */
-    data object Integer : ToolParameterType<Int>("INT") {
-        override val serializer = Int.serializer()
-    }
+    data object Integer : ToolParameterType("INT")
 
     /**
      * Represents a float type parameter.
      */
-    data object Float : ToolParameterType<kotlin.Float>("FLOAT") {
-        override val serializer = kotlin.Float.serializer()
-    }
-
+    data object Float : ToolParameterType("FLOAT")
     /**
      * Represents a boolean type parameter.
      */
-    data object Boolean : ToolParameterType<kotlin.Boolean>("BOOLEAN") {
-        override val serializer = kotlin.Boolean.serializer()
-    }
+    data object Boolean : ToolParameterType("BOOLEAN")
 
     /**
      * Represents an enum type parameter.
      *
      * @param E The specific enumeration type handled by this parameter type.
      * @property entries The entries for the enumeration, allowing the parameter to be one of these values.
      */
-    data class Enum<E : kotlin.Enum<E>>(
-        val entries: EnumEntries<E>,
-        override val serializer: KSerializer<E>
-    ) : ToolParameterType<E>("ENUM")
+    data class Enum(
+        val entries: Array<kotlin.String>,
+    ) : ToolParameterType("ENUM")
 
     /**
      * Represents an array type parameter.
      *
      * @param T The type of each item within the array.
      * @property itemsType The type definition for the items within the array.
      */
-    data class List<T>(val itemsType: ToolParameterType<T>) : ToolParameterType<kotlin.collections.List<T>>("ARRAY") {
-        override val serializer = ListSerializer(itemsType.serializer)
+    data class List(val itemsType: ToolParameterType) : ToolParameterType("ARRAY")
+
+    companion object {
+        fun Enum(entries: EnumEntries<*>): Enum = Enum(entries.map { it.name }.toTypedArray())
+        fun Enum(entries: Array<kotlin.Enum<*>>): Enum = Enum(entries.map { it.name }.toTypedArray())
     }
 }
+