WIP: write cli wrappers

Author: antoniibelyshev

agents/agents-cli/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:20-slim
+
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN npm install -g @openai/codex @anthropic-ai/claude-code && npm cache clean --force
+
+# Set a non-root user (optional but recommended)
+USER node
+
+WORKDIR /workspace

agents/agents-cli/build.gradle.kts

@@ -0,0 +1,41 @@
+import ai.koog.gradle.publish.maven.Publishing.publishToMaven
+
+group = rootProject.group
+version = rootProject.version
+
+plugins {
+    id("ai.kotlin.multiplatform")
+}
+
+kotlin {
+    sourceSets {
+        commonMain {
+            dependencies {
+                api(libs.kotlinx.serialization.json)
+                api(libs.kotlinx.coroutines.core)
+                implementation(libs.oshai.kotlin.logging)
+
+                api(project(":utils"))
+                api(project(":agents:agents-core"))
+            }
+        }
+
+        commonTest {
+            dependencies {
+                implementation(libs.kotest.assertions.core)
+            }
+        }
+
+        jvmTest {
+            dependencies {
+                implementation(kotlin("test-junit5"))
+                implementation(libs.junit.jupiter.params)
+                implementation(libs.kotlinx.coroutines.test)
+            }
+        }
+    }
+
+    explicitApi()
+}
+
+publishToMaven()

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/CliAIAgent.kt

@@ -0,0 +1,155 @@
+package ai.koog.agents.cli
+
+import ai.koog.agents.cli.transport.CliAvailable
+import ai.koog.agents.cli.transport.CliUnavailable
+import ai.koog.agents.core.agent.AIAgent
+import ai.koog.agents.core.agent.AIAgentState
+import ai.koog.agents.core.agent.config.AIAgentConfig
+import ai.koog.agents.core.annotation.InternalAgentsApi
+import ai.koog.agents.core.dsl.builder.AIAgentNodeDelegate
+import io.github.oshai.kotlinlogging.KotlinLogging
+import kotlinx.coroutines.flow.onEach
+import kotlinx.coroutines.flow.toList
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.jsonObject
+import java.util.UUID
+import kotlin.reflect.typeOf
+
+/**
+ * Base helper: runs a process and exposes stdout/stderr as a Flow of AgentEvents.
+ */
+// TODO(): support structured output
+public abstract class CliAIAgent<Result>(
+    private val config: CliAIAgentConfig,
+    private val name: String = config.binary
+) : AIAgent<String, Result?>() {
+
+    protected abstract val commandOptions: List<String>
+
+    /**
+     * Builds the environment variables for the agent process.
+     * For example, most agents may require an API key or other credentials.
+     */
+    protected abstract fun buildEnvironment(): Map<String, String>
+
+    /**
+     * Extracts the result of the agent run.
+     *
+     * This method processes a sequence of generated agent events and returns the agent execution result.
+     *
+     * @param events a list of events of type [AgentEvent], streamed by the agent cli
+     * @return a [Result] object representing the extracted result, or null if no result received
+     */
+    protected abstract fun extractResult(events: List<AgentEvent>): Result?
+
+    override val id: String = UUID.randomUUID().toString()
+
+    // TODO(): implement these overrides properly
+    // note: it might require refactoring the config and the state logic
+
+    override val agentConfig: AIAgentConfig
+        get() = throw UnsupportedOperationException()
+
+    override suspend fun getState(): AIAgentState<Result?> = throw UnsupportedOperationException()
+
+    override suspend fun close() {
+        // No-op by default
+    }
+
+    @OptIn(InternalAgentsApi::class)
+    override suspend fun run(agentInput: String): Result? {
+        connect()
+
+        logger.info { "Starting agent '$name' with binary '$config.binary' in workspace '${config.workspace}'" }
+        val startTime = System.currentTimeMillis()
+
+        val processEvents = config.transport.execute(
+            command = listOf(config.binary) + commandOptions + agentInput,
+            workspace = config.workspace,
+            env = buildEnvironment(),
+            timeout = config.timeout
+        ).onEach {
+            logEvent(it)
+        }.toList()
+
+        val agentEvents = processEvents.filterIsInstance<AgentEvent>()
+
+        val result = extractResult(agentEvents)
+        val durationMs = System.currentTimeMillis() - startTime
+
+        val exitCode = processEvents.filterIsInstance<CliAIAgentEvent.Exit>().firstOrNull()?.exitCode ?: -1
+
+        logger.info { "Agent '$name' finished in ${durationMs}ms with exit code $exitCode" }
+        logger.info { "Agent '$name' result: $result" }
+
+        return result
+    }
+
+    /**
+     * Transforms this agent into a node that can be used in a graph strategy.
+     */
+    public fun asNode(name: String? = null): AIAgentNodeDelegate<String, Result?> =
+        AIAgentNodeDelegate<String, Result?>(
+            name = name,
+            inputType = typeOf<String>(),
+            outputType = typeOf<Any?>(),
+            execute = { input -> run(input) }
+        )
+
+    private fun connect() {
+        when (val availability = config.transport.checkAvailability(config.binary)) {
+            is CliAvailable -> {
+                logger.info { "Connected to agent '$name' (version: ${availability.version ?: "unknown"})" }
+            }
+
+            is CliUnavailable -> {
+                throw CliNotFoundException(
+                    "Agent '$name' CLI '$config.binary' is not available: ${availability.reason}",
+                    availability.cause
+                )
+            }
+        }
+    }
+
+    protected companion object {
+        private val logger = KotlinLogging.logger { }
+
+        private fun logEvent(event: CliAIAgentEvent) {
+            logger.info {
+                when (event) {
+                    is CliAIAgentEvent.Started -> "Agent Started"
+                    is AgentEvent.Stdout -> "[STDOUT] ${event.content}"
+                    is AgentEvent.Stderr -> "[STDERR] ${event.content}"
+                    is CliAIAgentEvent.Exit -> "Agent Exited (code: ${event.exitCode})"
+                    is CliAIAgentEvent.Failed -> "Agent Failed: ${event.message}"
+                }
+            }
+        }
+
+        // json utils
+
+        private val json: Json = Json { ignoreUnknownKeys = true }
+
+        /**
+         * Converts a list of agent events to a list of JSON objects from stdout
+         */
+        public fun toJsonStdoutEvents(events: List<AgentEvent>): List<JsonObject> =
+            events
+                .filterIsInstance<AgentEvent.Stdout>()
+                .mapNotNull {
+                    runCatching {
+                        json.decodeFromString<JsonObject>(it.content).jsonObject
+                    }.getOrNull()
+                }
+
+        /**
+         * Converts a JSON primitive to a string
+         */
+        public val JsonElement.stringVal: String?
+            get() = (this as? JsonPrimitive)?.contentOrNull
+    }
+}

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/CliAIAgentConfig.kt

@@ -0,0 +1,15 @@
+package ai.koog.agents.cli
+
+import ai.koog.agents.cli.transport.CliTransport
+import java.io.File
+import kotlin.time.Duration
+
+/**
+ * Base configuration for agent processes.
+ */
+public abstract class CliAIAgentConfig(
+    public val binary: String,
+    public val transport: CliTransport,
+    public val workspace: File,
+    public val timeout: Duration?
+)

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/CliAIAgentEvent.kt

@@ -0,0 +1,41 @@
+package ai.koog.agents.cli
+
+/**
+ * Represents an event of an agent process.
+ */
+public sealed interface CliAIAgentEvent {
+    /**
+     * An event indicating that the agent process has started.
+     */
+    public object Started : CliAIAgentEvent
+
+    /**
+     * An event indicating that the agent process has exited.
+     */
+    public class Exit(public val exitCode: Int) : CliAIAgentEvent
+
+    /**
+     * An event indicating that the agent process has failed.
+     */
+    public class Failed(public val message: String?) : CliAIAgentEvent
+}
+
+/**
+ * Represents an event of an agent from an agent cli.
+ */
+public sealed interface AgentEvent : CliAIAgentEvent {
+    /**
+     * The content of the event.
+     */
+    public val content: String
+
+    /**
+     * An event streamed from stdout.
+     */
+    public class Stdout(public override val content: String) : AgentEvent
+
+    /**
+     * An event streamed from stderr.
+     */
+    public class Stderr(public override val content: String) : AgentEvent
+}

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/CliAgentException.kt

@@ -0,0 +1,19 @@
+package ai.koog.agents.cli
+
+import kotlin.time.Duration
+
+/**
+ * Base class for cli-agent-related exceptions.
+ */
+public open class CliAgentException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)
+
+/**
+ * Exception indicating that a CLI agent binary was not found.
+ */
+public class CliNotFoundException(message: String, cause: Throwable? = null) : CliAgentException(message, cause)
+
+/**
+ * Exception indicating that a CLI agent run timed out.
+ */
+public class CliAgentTimeoutException(message: String, public val timeout: Duration, cause: Throwable? = null) :
+    CliAgentException(message, cause)

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/claude/ClaudeCodeAgent.kt

@@ -0,0 +1,43 @@
+package ai.koog.agents.cli.claude
+
+import ai.koog.agents.cli.AgentEvent
+import ai.koog.agents.cli.CliAIAgent
+
+/**
+ * Claude Code CLI wrapper.
+ */
+public class ClaudeCodeAgent(
+    public val config: ClaudeCodeConfig = ClaudeCodeConfig(),
+) : CliAIAgent<String>(config) {
+
+    override val commandOptions: List<String> = buildList {
+        add("-p")
+
+        add("--output-format")
+        add("stream-json")
+
+        if (config.verbose) add("--verbose")
+
+        if (config.includePartialMessages) add("--include-partial-messages")
+
+        config.model?.let {
+            add("--model")
+            add(it)
+        }
+    }
+
+    override fun buildEnvironment(): Map<String, String> {
+        return buildMap {
+            config.apiKey?.let { put("ANTHROPIC_API_KEY", it) }
+        }
+    }
+
+    override fun extractResult(events: List<AgentEvent>): String? {
+        val jsonEvents = toJsonStdoutEvents(events)
+
+        val resultJson = jsonEvents.lastOrNull { it["type"]?.stringVal == "result" }
+        val result = resultJson?.let { it["result"]?.stringVal }
+
+        return result
+    }
+}

agents/agents-cli/src/jvmMain/kotlin/ai/koog/agents/cli/claude/ClaudeCodeConfig.kt

@@ -0,0 +1,20 @@
+package ai.koog.agents.cli.claude
+
+import ai.koog.agents.cli.CliAIAgentConfig
+import ai.koog.agents.cli.transport.CliTransport
+import java.io.File
+import kotlin.time.Duration
+
+/**
+ * Claude Code config.
+ */
+public class ClaudeCodeConfig(
+    binary: String = "claude",
+    transport: CliTransport = CliTransport.Default,
+    workspace: File = File("."),
+    timeout: Duration? = null,
+    public val model: String? = null,
+    public val verbose: Boolean = true,
+    public val includePartialMessages: Boolean = false,
+    public val apiKey: String? = null,
+) : CliAIAgentConfig(binary, transport, workspace, timeout)