SystemConfigReader for Apple platforms using NSUserDefaults (#1231)

# Add multiplatform system configuration and secrets readers with
JVM-specific implementation

Introduce `SystemConfigReader` and `SystemSecretsReader` interfaces to
standardize access to configuration values and secrets across different
platforms. This change utilizes the `expect`/`actual` mechanism to
define common contracts with specific platform implementations.

* Implement fully functional readers for the JVM target: the
configuration reader resolves values from environment variables and
system properties (supports name normalization), while the secrets
reader strictly uses environment variables for security.
* Add stub implementations for Android, Apple, JS, and WasmJS platforms
that currently throw a `NotImplementedError` when accessed.
* Define the common interfaces and factory functions to allow retrieval
of configuration strings and secrets.
* Add `UserDefaultsSystemConfigReader` backed by Apple's NSUserDefaults
for retrieving configuration properties. Update `systemConfigReader` to
use this implementation and introduce comprehensive unit tests to ensure
correctness.

## Motivation and Context
Should be used in Debugger Config and LLM Clients

See also #1228 

## Breaking Changes
No

---

#### Type of the changes
- [x] New feature (non-breaking change which adds functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Tests improvement
- [ ] Refactoring

#### Checklist
- [x] The pull request has a description of the proposed change
- [x] I read the [Contributing
Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md)
before opening the pull request
- [x] The pull request uses **`develop`** as the base branch
- [x] Tests for the changes have been added
- [x] All new and existing tests passed

##### Additional steps for pull requests adding a new feature
- [ ] An issue describing the proposed change exists
- [ ] The pull request includes a link to the issue
- [ ] The change was discussed and approved in the issue
- [ ] Docs have been added / updated

Author: kpavlov

utils/src/androidMain/kotlin/ai/koog/utils/system/SystemConfigReader.android.kt

@@ -0,0 +1,5 @@
+package ai.koog.utils.system
+
+public actual fun systemConfigReader(): SystemConfigReader {
+    throw NotImplementedError("SystemConfigReader is not yet supported on Android platform")
+}

utils/src/androidMain/kotlin/ai/koog/utils/system/SystemSecretsReader.android.kt

@@ -0,0 +1,5 @@
+package ai.koog.utils.system
+
+public actual fun systemSecretsReader(): SystemSecretsReader {
+    throw NotImplementedError("SystemSecretsReader is not yet supported on Android platform")
+}

utils/src/appleMain/kotlin/ai/koog/utils/system/SystemConfigReader.apple.kt

@@ -0,0 +1,3 @@
+package ai.koog.utils.system
+
+public actual fun systemConfigReader(): SystemConfigReader = UserDefaultsSystemConfigReader.shared

utils/src/appleMain/kotlin/ai/koog/utils/system/SystemSecretsReader.apple.kt

@@ -0,0 +1,5 @@
+package ai.koog.utils.system
+
+public actual fun systemSecretsReader(): SystemSecretsReader {
+    throw NotImplementedError("SystemSecretsReader is not yet supported on Apple platforms")
+}

utils/src/appleMain/kotlin/ai/koog/utils/system/UserDefaultsSystemConfigReader.kt

@@ -0,0 +1,44 @@
+package ai.koog.utils.system
+
+import platform.Foundation.NSUserDefaults.Companion.standardUserDefaults
+
+/**
+ * A configuration reader implementation backed by Apple's `NSUserDefaults`.
+ *
+ * This class provides a mechanism to retrieve system configuration properties
+ * stored in the `NSUserDefaults` system on Apple platforms.
+ *
+ * @constructor Initializes an instance of `UserDefaultsSystemConfigReader` with the provided `NSUserDefaults`.
+ * @param userDefaults The `NSUserDefaults` instance used to fetch configuration values.
+ */
+public class UserDefaultsSystemConfigReader(
+    private val userDefaults: platform.Foundation.NSUserDefaults
+) : SystemConfigReader {
+
+    public companion object {
+        /**
+         * A shared instance of [UserDefaultsSystemConfigReader].
+         *
+         * This instance provides centralized access to system configuration properties
+         * stored in Apple's `NSUserDefaults`. It uses the standard `NSUserDefaults` instance
+         * for fetching configuration values.
+         *
+         * The `shared` instance is intended for reuse across the application whenever access
+         * to system configuration properties is required.
+         */
+        public val shared: UserDefaultsSystemConfigReader = UserDefaultsSystemConfigReader(standardUserDefaults())
+    }
+
+    /**
+     * Retrieves the value of a system configuration property by its name.
+     *
+     * This method interacts with Apple's `NSUserDefaults` system to fetch
+     * a configuration value based on the provided key.
+     *
+     * @param name The name of the configuration property to retrieve.
+     * @return The value of the configuration property if it exists, or null if not found.
+     */
+    override fun getConfigVariable(name: String): String? {
+        return userDefaults.stringForKey(name)
+    }
+}

utils/src/appleTest/kotlin/ai/koog/utils/system/UserDefaultsSystemConfigReaderTest.kt

@@ -0,0 +1,27 @@
+package ai.koog.utils.system
+
+import io.kotest.matchers.shouldBe
+import platform.Foundation.NSUserDefaults.Companion.standardUserDefaults
+import kotlin.test.Test
+
+class UserDefaultsSystemConfigReaderTest {
+
+    companion object {
+        init {
+            val defaults = standardUserDefaults()
+            defaults.setObject("ho-ho", forKey = "FOO_PROP")
+        }
+    }
+
+    private val sublect = UserDefaultsSystemConfigReader.shared
+
+    @Test
+    fun testReadValue() {
+        sublect.getConfigVariable("FOO_PROP") shouldBe "ho-ho"
+    }
+
+    @Test
+    fun testReadMissingValue() {
+        sublect.getConfigVariable("BAR_PROP") shouldBe null
+    }
+}

utils/src/commonMain/kotlin/ai/koog/utils/system/SystemConfigReader.kt

@@ -0,0 +1,30 @@
+package ai.koog.utils.system
+
+/**
+ * An interface for reading system configuration properties.
+ *
+ * This interface provides a method to retrieve system configuration values by their names.
+ * Implementations can vary based on the operating system or platform being used.
+ */
+public interface SystemConfigReader {
+
+    /**
+     * Retrieves the value of a system configuration property by its name.
+     *
+     * @param name The name of the system configuration property to retrieve.
+     * @return The value of the configuration property if it exists, or null if not found.
+     */
+    public fun getConfigVariable(name: String): String?
+}
+
+/**
+ * Provides an implementation of the [SystemConfigReader] interface for the current platform.
+ *
+ * This function returns an instance of [SystemConfigReader] that allows access
+ * to system-level configuration properties based on platform-specific implementations.
+ * On unsupported platforms, this function will throw a [NotImplementedError].
+ *
+ * @return An instance of [SystemConfigReader] for accessing system configuration properties.
+ * @throws NotImplementedError if [SystemConfigReader] is not supported on this platform.
+ */
+public expect fun systemConfigReader(): SystemConfigReader

utils/src/commonMain/kotlin/ai/koog/utils/system/SystemSecretsReader.kt

@@ -0,0 +1,46 @@
+package ai.koog.utils.system
+
+/**
+ * An interface for reading secrets.
+ *
+ * This interface provides a method to retrieve secret values by their names.
+ * Implementations can vary based on the operating system or platform being used.
+ */
+public interface SystemSecretsReader {
+
+    /**
+     * Retrieves a secret value from environment variables.
+     *
+     * **SECURITY NOTICE**:
+     * Secrets are returned as Strings because the underlying OS APIs
+     * (environment variables, system properties) return Strings.
+     * The String cannot be cleared from memory.
+     *
+     * **Best practices**:
+     * - Use platform-specific secure storage when possible (Keychain, KeyStore)
+     * - Use short-lived tokens instead of long-lived secrets
+     * - Rotate secrets regularly
+     * - Don't log or print secret values
+     *
+     * For maximum security, consider using:
+     * - Secrets management services (HashiCorp Vault, AWS Secrets Manager)
+     * - Platform secure storage APIs
+     * - Memory-mapped files with OS-level protection
+     *
+     * @param name The secret key
+     * @return The secret value, or null if not found
+     */
+    public fun getSecret(name: String): String?
+}
+
+/**
+ * Provides an implementation of the [SystemSecretsReader] interface for the current platform.
+ *
+ * This function returns an instance of [SystemSecretsReader] that allows access
+ * to secrets based on platform-specific implementations.
+ * On unsupported platforms, this function will throw a [NotImplementedError].
+ *
+ * @return An instance of [SystemSecretsReader] for accessing system configuration properties.
+ * @throws NotImplementedError if [SystemSecretsReader] is not supported on this platform.
+ */
+public expect fun systemSecretsReader(): SystemSecretsReader

utils/src/jsMain/kotlin/ai/koog/utils/system/SystemConfigReader.js.kt

@@ -0,0 +1,5 @@
+package ai.koog.utils.system
+
+public actual fun systemConfigReader(): SystemConfigReader {
+    throw NotImplementedError("SystemConfigReader is not yet supported on JS platform")
+}

utils/src/jsMain/kotlin/ai/koog/utils/system/SystemSecretsReader.js.kt

@@ -0,0 +1,5 @@
+package ai.koog.utils.system
+
+public actual fun systemSecretsReader(): SystemSecretsReader {
+    throw NotImplementedError("SystemSecretsReader is not yet supported on JS platform")
+}