AMPR-167 #494: Ampere client-runtime readiness (MemoryStore + UpstreamLlmClient) (#495)

* AMPR-167 #494: Ampere client-runtime readiness

I (Claude) implemented this in collaboration with Miley. It closes out
AMPR-167 in a single commit covering Waves 0-3 plus the follow-up that
wires UpstreamLlmClient through the agent construction chain.

What's new (public injection surface):
- MemoryStore (commonMain) — composition over KnowledgeRepository +
  OutcomeMemoryRepository, the seam Socket implements for on-device
  durable memory.
- UpstreamLlmClient (commonMain) — call-origination seam in AgentLLMService;
  default BundledUpstreamLlmClient is byte-equivalent to pre-seam behavior.
- AgentConfiguration.upstreamLlmClient + AmpereInstance.upstreamLlmClient
  — the load-bearing path that lets a runtime default from fromEnvironment
  reach AgentLLMService.call via SparkBasedAgent -> AgentReasoning.
- Ampere.fromEnvironment(memoryStore, upstreamLlmClient) — additive params;
  existing JVM callers compile unchanged.

What moved:
- 7 Default*Service files from jvmMain to commonMain (zero JVM-isms in
  their bodies — they were misplaced).
- Ampere.fromEnvironment body to commonMain; Ampere.jvm.kt trimmed to just
  the actual fun createInstance for the heavy Ampere.create path.

Tests + CI:
- MemoryStore + UpstreamLlmClient contract tests; plumbing test verifying
  the config field flows through AgentLLMService.call (commonTest).
- fromEnvironment construction + event-bus smoke on JVM (full), iOS sim
  (full), Android Robolectric (construction-only — Robolectric's bundled
  SQLite native runtime lacks FTS5).
- CI matrix: Linux + macOS run JVM + Android tests; macOS also runs
  iosSimulatorArm64Test. Previously :test silently skipped jvmTest in KMP
  modules.
- Deleted 9 dormant ToolRead/Run/WriteCodeFile test stubs (no @test
  annotations on any platform; never ran anything).

Audit doc: docs/ampr-167-fromenvironment-audit.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* AMPR-167 #494: Fix CI — use jvmTest for ampere-cli/ampere-compose

I (Claude) goofed the CI task names in the previous commit. Both
ampere-cli and ampere-compose are KMP modules whose runnable JVM-test
task is :jvmTest, not :test (which doesn't exist in KMP modules). Also
adding :ampere-compose:testDebugUnitTest for parity with ampere-core's
Android coverage.

Verified locally:
- :ampere-cli:jvmTest passes
- :ampere-compose:jvmTest passes
- :ampere-compose:testDebugUnitTest passes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* AMPR-167 #494: Fix McpIntegrationTest runTest+real-dispatcher race

I (Claude) fixed three flaky assertions in McpIntegrationTest that were
masked when CI ran `./gradlew test` (which silently skips `:jvmTest` in
KMP modules) and surfaced once my CI changes started running `jvmTest`
on every PR.

The race: each `runTest` test called `manager.discoverAndRegisterTools()`
then `kotlinx.coroutines.delay(200)` and asserted on events captured
from the event bus. But the event bus runs on `Dispatchers.Default`,
and `delay(...)` inside `runTest` advances virtual time only — the real
dispatcher gets zero wall-clock time, so on loaded CI runners the
asserted events hadn't been delivered yet.

Fix: introduced an `awaitUntil(predicate)` helper that switches to
`Dispatchers.Default` (escaping the virtual scheduler) and polls the
predicate up to 5s with 25ms intervals. Replaced all three fixed-delay
sites with predicate polls — `2 ToolRegistered events emitted`,
`ToolDiscoveryComplete event emitted`, and `tools removed from
registry after disconnect`.

Verified 5/5 clean local runs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* AMPR-167 #494: Bump ProgressIndicatorTest render wait from 60ms to 500ms

I (Claude) fixed another pre-existing flake that my CI changes exposed
once :ampere-cli:jvmTest started running on every PR. The test that
failed on the ubuntu-latest job — \`state indicator can change state\` —
sets the indicator's state to SUCCESS and waits 60ms before asserting
the output contains "[OK]". The indicator renders on a background thread
at BaseProgressIndicator.FRAME_INTERVAL_MS (50ms), so 60ms gave only ~1
frame of headroom and lost the race against JVM warmup / GC / scheduling
on the CI runner.

There are 18 identical Thread.sleep(60) call sites in this file, all
paired with output assertions. Rather than refactor each one to a
condition poll (varying assertion shapes), I extracted a single
RENDER_WAIT_MS constant set to 500ms — 10x the frame interval —
and replaced every site. Adds ~8s to the test run; well worth not
flaking.

Verified :ampere-cli:jvmTest passes locally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wow-miley

.github/workflows/ci.yml

@@ -16,8 +16,10 @@ jobs:
         include:
           - os: ubuntu-latest
             java: '17'
+            ios: false
           - os: macos-latest
             java: '21'
+            ios: true
 
     steps:
       - name: Checkout code
@@ -44,6 +46,11 @@ jobs:
         timeout-minutes: 10
         run: ./gradlew ktlintCheck
 
-      - name: Run tests
-        timeout-minutes: 10
-        run: ./gradlew test
+      - name: Run JVM + Android tests
+        timeout-minutes: 20
+        run: ./gradlew :ampere-core:jvmTest :ampere-core:testDebugUnitTest :ampere-cli:jvmTest :ampere-compose:jvmTest :ampere-compose:testDebugUnitTest
+
+      - name: Run iOS simulator tests
+        if: ${{ matrix.ios }}
+        timeout-minutes: 25
+        run: ./gradlew :ampere-core:iosSimulatorArm64Test

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/repl/ProgressIndicatorTest.kt

@@ -16,6 +16,13 @@ import kotlin.test.assertTrue
 
 class ProgressIndicatorTest {
 
+    // Indicators render every BaseProgressIndicator.FRAME_INTERVAL_MS (50ms).
+    // Each test waits for at least one frame to land in the output buffer
+    // before asserting. The previous 60ms margin raced the render thread on
+    // loaded CI runners (JVM warmup, GC, scheduling); 500ms gives ~10 frames
+    // of headroom while keeping the suite under ~10s overall.
+    private val RENDER_WAIT_MS: Long = 500L
+
     private lateinit var outputStream: ByteArrayOutputStream
     private lateinit var terminal: Terminal
     private lateinit var writer: PrintWriter
@@ -82,7 +89,7 @@ class ProgressIndicatorTest {
             .build() as SpinnerIndicator
 
         indicator.start()
-        Thread.sleep(60) // Wait for at least one frame
+        Thread.sleep(RENDER_WAIT_MS) // Wait for at least one frame
         indicator.stop()
 
         val output = outputStream.toString()
@@ -106,7 +113,7 @@ class ProgressIndicatorTest {
             .build() as SpinnerIndicator
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -184,7 +191,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.update(progress = 0.5f)
-        Thread.sleep(60) // Wait for render
+        Thread.sleep(RENDER_WAIT_MS) // Wait for render
         indicator.stop()
 
         val output = outputStream.toString()
@@ -202,7 +209,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.update(progress = 1.5f) // Should clamp to 1.0
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -219,7 +226,7 @@ class ProgressIndicatorTest {
             .build()
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -238,7 +245,7 @@ class ProgressIndicatorTest {
             .build() as StateIndicator
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -256,7 +263,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.setState(IndicatorState.SUCCESS)
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -303,9 +310,9 @@ class ProgressIndicatorTest {
             .build()
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.update(message = "Updated")
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -320,7 +327,7 @@ class ProgressIndicatorTest {
             .build()
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -336,7 +343,7 @@ class ProgressIndicatorTest {
             .build()
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -348,7 +355,7 @@ class ProgressIndicatorTest {
     fun `SimpleSpinner provides backward compatibility`() {
         val spinner = SimpleSpinner(terminal)
         spinner.start("Loading...")
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         spinner.stop()
 
         val output = outputStream.toString()
@@ -405,7 +412,7 @@ class ProgressIndicatorTest {
 
         indicator.setState(IndicatorState.THINKING)
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -423,7 +430,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.update(progress = 0.5f)
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.complete(success = true)
 
         val output = outputStream.toString()
@@ -445,7 +452,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.update(progress = 0.5f)
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()
@@ -468,7 +475,7 @@ class ProgressIndicatorTest {
 
         indicator.start()
         indicator.update(progress = 0.25f)
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val wideOutput = outputStream.toString()
@@ -479,7 +486,7 @@ class ProgressIndicatorTest {
         terminal.setSize(Size(30, 24))
         indicator.start()
         indicator.update(progress = 0.25f)
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val narrowOutput = outputStream.toString()
@@ -497,7 +504,7 @@ class ProgressIndicatorTest {
             .build()
 
         indicator.start()
-        Thread.sleep(60)
+        Thread.sleep(RENDER_WAIT_MS)
         indicator.stop()
 
         val output = outputStream.toString()

ampere-core/build.gradle.kts

@@ -195,6 +195,15 @@ kotlin {
                 implementation("com.charleskorn.kaml:kaml:0.72.0")
             }
         }
+        val androidUnitTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+                implementation("org.robolectric:robolectric:4.14")
+                implementation("androidx.test:core:1.6.1")
+                implementation("androidx.test.ext:junit:1.2.1")
+                implementation("junit:junit:4.13.2")
+            }
+        }
         val jsMain by getting {
             dependencies {
                 implementation("io.ktor:ktor-client-js:3.2.2")
@@ -250,6 +259,11 @@ android {
     kotlin {
         jvmToolchain(21)
     }
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+        }
+    }
 }
 
 val kotlinConfiguration = tasks.register("kotlinConfiguration") {

ampere-core/src/androidUnitTest/kotlin/link/socket/ampere/agents/execution/tools/ToolReadCodebaseTest.android.kt

@@ -0,0 +1,82 @@
+package link.socket.ampere.api
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import app.cash.sqldelight.db.SqlDriver
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.assertNotNull
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.TestScope
+import kotlinx.coroutines.test.UnconfinedTestDispatcher
+import link.socket.ampere.agents.domain.knowledge.KnowledgeRepository
+import link.socket.ampere.agents.domain.knowledge.KnowledgeRepositoryImpl
+import link.socket.ampere.agents.environment.EnvironmentService
+import link.socket.ampere.data.createAndroidDriver
+import link.socket.ampere.db.Database
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Android construction smoke test for [Ampere.fromEnvironment].
+ *
+ * Runs as a Robolectric unit test so it executes on the CI JVM without
+ * requiring an emulator. Exercises [createAndroidDriver] —
+ * [AndroidSqliteDriver][app.cash.sqldelight.driver.android.AndroidSqliteDriver]
+ * end-to-end — proving that the migrated `fromEnvironment` extension and
+ * its `Default*Service` dependencies compile and execute on Android.
+ */
+@OptIn(ExperimentalCoroutinesApi::class)
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [33])
+class AmpereFromEnvironmentAndroidTest {
+
+    private val scope = TestScope(UnconfinedTestDispatcher())
+
+    private lateinit var driver: SqlDriver
+    private lateinit var database: Database
+    private lateinit var environmentService: EnvironmentService
+    private lateinit var knowledgeRepository: KnowledgeRepository
+
+    @BeforeTest
+    fun setUp() {
+        val context: Context = ApplicationProvider.getApplicationContext()
+        driver = createAndroidDriver(context = context, dbName = "ampere-android-test.db")
+        database = Database(driver)
+        environmentService = EnvironmentService.create(database = database, scope = scope)
+        knowledgeRepository = KnowledgeRepositoryImpl(database)
+    }
+
+    @AfterTest
+    fun tearDown() {
+        driver.close()
+    }
+
+    @Test
+    fun `fromEnvironment constructs on Android with AndroidSqliteDriver`() {
+        // Construction-only smoke: AndroidSqliteDriver is lazily initialized,
+        // so this proves the migrated `fromEnvironment` + `Default*Service`
+        // graph wires up under Android. The full event-bus smoke (pursue ->
+        // observe TaskCreated) lives in the JVM and iOS suites; Robolectric's
+        // bundled SQLite native runtime lacks FTS5, which Ampere's knowledge
+        // schema requires. A proper Android instrumented test (real device /
+        // emulator with full SQLite) is tracked as a follow-up.
+        val instance = Ampere.fromEnvironment(
+            environmentService = environmentService,
+            knowledgeRepository = knowledgeRepository,
+        )
+
+        assertNotNull(instance.agents)
+        assertNotNull(instance.tickets)
+        assertNotNull(instance.threads)
+        assertNotNull(instance.events)
+        assertNotNull(instance.outcomes)
+        assertNotNull(instance.pricing)
+        assertNotNull(instance.knowledge)
+        assertNotNull(instance.status)
+
+        instance.close()
+    }
+}

ampere-core/src/androidUnitTest/kotlin/link/socket/ampere/agents/execution/tools/ToolRunTestsTest.android.kt

@@ -6,6 +6,8 @@ import link.socket.ampere.agents.domain.routing.CognitiveRelay
 import link.socket.ampere.domain.agent.bundled.AgentDefinition
 import link.socket.ampere.domain.ai.configuration.AIConfiguration
 import link.socket.ampere.domain.llm.LlmProvider
+import link.socket.ampere.llm.BundledUpstreamLlmClient
+import link.socket.ampere.llm.UpstreamLlmClient
 
 @Serializable
 data class AgentConfiguration(
@@ -16,4 +18,14 @@ data class AgentConfiguration(
     val llmProvider: LlmProvider? = null,
     @Transient
     val cognitiveRelay: CognitiveRelay? = null,
+    /**
+     * Outbound LLM-call seam. Defaults to [BundledUpstreamLlmClient] (the
+     * pre-seam direct-call behavior). Embedded consumers (e.g. Socket)
+     * override this to route LLM calls through their backend proxy.
+     *
+     * Note: a non-null [llmProvider] still short-circuits before the
+     * upstream client runs.
+     */
+    @Transient
+    val upstreamLlmClient: UpstreamLlmClient = BundledUpstreamLlmClient,
 )