Merge remote-tracking branch 'origin/main' into miley/ampr-175-memoryeventmilestonereached-sibling-event-for-significant

# Conflicts:
#	ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/EventSerializationTest.kt

Author: Miley Chandonnet

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizer.kt

@@ -1,6 +1,7 @@
 package link.socket.ampere.cli.watch.presentation
 
 import link.socket.ampere.agents.domain.event.AgentSurfaceEvent
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.FileSystemEvent
 import link.socket.ampere.agents.domain.event.GitEvent
@@ -52,6 +53,7 @@ object EventCategorizer {
     private fun categorizeInternal(event: Event): EventSignificance = when (event) {
         // Critical events require immediate human awareness
         is Event.QuestionRaised,
+        is CognitiveEvent.EscalationFired,
         is TicketEvent.TicketBlocked,
         is MessageEvent.EscalationRequested,
         is HumanInteractionEvent.InputRequested,

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/WatchPresenter.kt

@@ -10,6 +10,7 @@ import kotlinx.coroutines.flow.catch
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlinx.datetime.Clock
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.CognitiveStateSnapshot
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
@@ -371,6 +372,9 @@ class WatchPresenter(
                 "\"$content\""
             }
             is MessageEvent.EscalationRequested -> "⚠️ Escalation: ${event.reason.take(50)}"
+            is CognitiveEvent.EscalationFired -> {
+                "Uncertainty escalation: ${event.uncertaintyValue} >= ${event.threshold}"
+            }
             is MemoryEvent.KnowledgeRecalled -> {
                 val count = event.resultsFound
                 if (count > 0) "Recalled $count items (relevance: ${String.format("%.0f%%", event.averageRelevance * 100)})"

ampere-cli/src/jvmMain/kotlin/link/socket/ampere/renderer/EventRenderer.kt

@@ -13,6 +13,7 @@ import kotlinx.datetime.TimeZone
 import kotlinx.datetime.toLocalDateTime
 import link.socket.ampere.agents.domain.Urgency
 import link.socket.ampere.agents.domain.event.AgentSurfaceEvent
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
 import link.socket.ampere.agents.domain.event.FileSystemEvent
@@ -134,6 +135,7 @@ class EventRenderer(
             is Event.CodeSubmitted -> "💻" to cyan
             is Event.QuestionRaised -> "❓" to magenta
             is Event.TaskCreated -> "📋" to green
+            is CognitiveEvent.EscalationFired -> "❓" to red
             is TaskEvent -> "📋" to green
             is FileSystemEvent -> "📄" to cyan
             is GitEvent -> "🪾" to cyan

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizerTest.kt

@@ -4,6 +4,7 @@ import kotlinx.datetime.Clock
 import link.socket.ampere.agents.domain.Urgency
 import link.socket.ampere.agents.domain.knowledge.KnowledgeType
 import link.socket.ampere.agents.domain.status.TicketStatus
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
 import link.socket.ampere.agents.domain.event.MemoryEvent
@@ -68,6 +69,24 @@ class EventCategorizerTest {
         assertEquals(EventSignificance.CRITICAL, significance)
     }
 
+    @Test
+    fun `CRITICAL - EscalationFired events are critical`() {
+        val event = CognitiveEvent.EscalationFired(
+            eventId = "evt-escalation-fired",
+            timestamp = Clock.System.now(),
+            eventSource = EventSource.Agent("agent-test"),
+            urgency = Urgency.HIGH,
+            agentId = "agent-test",
+            uncertaintyValue = 0.9,
+            threshold = 0.7,
+            prompt = "Need confidence threshold escalation",
+            cognitivePhase = null,
+        )
+
+        val significance = EventCategorizer.categorize(event)
+        assertEquals(EventSignificance.CRITICAL, significance)
+    }
+
     @Test
     fun `SIGNIFICANT - TaskCreated events are significant`() {
         val event = Event.TaskCreated(

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/renderer/EventRendererTest.kt

@@ -5,6 +5,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 import kotlinx.datetime.TimeZone
 import kotlinx.datetime.toLocalDateTime
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.CognitiveStateSnapshot
 import link.socket.ampere.agents.domain.event.EventSource
@@ -209,6 +210,23 @@ class EventRendererTest {
         success = success,
     )
 
+    private fun escalationFiredEvent(
+        eventId: String = "evt-escalation-fired-1",
+        timestamp: Instant = Clock.System.now(),
+        source: EventSource = EventSource.Agent("agent-test"),
+        urgency: Urgency = Urgency.HIGH,
+    ): CognitiveEvent.EscalationFired = CognitiveEvent.EscalationFired(
+        eventId = eventId,
+        timestamp = timestamp,
+        eventSource = source,
+        urgency = urgency,
+        agentId = "agent-test",
+        uncertaintyValue = 0.9,
+        threshold = 0.7,
+        prompt = "Need human decision",
+        cognitivePhase = null,
+    )
+
     @Test
     fun `render TaskCreated event shows task ID, description, and assignment`() {
         val output = captureTerminalOutput { _, renderer ->
@@ -403,6 +421,12 @@ class EventRendererTest {
             renderer.render(codeEvent())
         }
         assertContains(codeOutput, "💻")
+
+        val escalationOutput = captureTerminalOutput { _, renderer ->
+            renderer.render(escalationFiredEvent())
+        }
+        assertContains(escalationOutput, "❓")
+        assertContains(escalationOutput, "EscalationFired")
     }
 
     @Test

ampere-cli/src/jvmTest/kotlin/link/socket/ampere/util/EventTypeParserTest.kt

@@ -5,6 +5,7 @@ import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
 import link.socket.ampere.agents.domain.event.Event
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.MeetingEvent
 import link.socket.ampere.agents.domain.event.MemoryEvent
 import link.socket.ampere.agents.domain.event.MessageEvent
@@ -47,6 +48,11 @@ class EventTypeParserTest {
         assertNotNull(EventTypeParser.parse("CodeSubmitted"))
     }
 
+    @Test
+    fun `parse handles CognitiveEvent types`() {
+        assertNotNull(EventTypeParser.parse("EscalationFired"))
+    }
+
     @Test
     fun `parse handles all MeetingEvent types`() {
         assertNotNull(EventTypeParser.parse("MeetingScheduled"))
@@ -158,6 +164,7 @@ class EventTypeParserTest {
         assertTrue(allTypes.contains(Event.TaskCreated.EVENT_TYPE))
         assertTrue(allTypes.contains(Event.QuestionRaised.EVENT_TYPE))
         assertTrue(allTypes.contains(Event.CodeSubmitted.EVENT_TYPE))
+        assertTrue(allTypes.contains(CognitiveEvent.EscalationFired.EVENT_TYPE))
 
         // Should have meeting events
         assertTrue(allTypes.contains(MeetingEvent.MeetingScheduled.EVENT_TYPE))

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/CognitiveEvent.kt

@@ -0,0 +1,63 @@
+package link.socket.ampere.agents.domain.event
+
+import kotlinx.datetime.Instant
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import link.socket.ampere.agents.definition.AgentId
+import link.socket.ampere.agents.domain.Urgency
+import link.socket.ampere.agents.domain.cognition.sparks.CognitivePhase
+
+/**
+ * Events emitted by cognitive evaluators outside normal phase transitions.
+ */
+@Serializable
+sealed interface CognitiveEvent : Event {
+
+    val agentId: AgentId
+
+    /**
+     * Emitted when an agent's uncertainty meets or exceeds its configured escalation threshold.
+     */
+    @Serializable
+    @SerialName("CognitiveEvent.EscalationFired")
+    data class EscalationFired(
+        override val eventId: EventId,
+        override val timestamp: Instant,
+        override val eventSource: EventSource,
+        override val urgency: Urgency = Urgency.HIGH,
+        override val agentId: AgentId,
+        val uncertaintyValue: Double,
+        val threshold: Double,
+        val prompt: String,
+        val cognitivePhase: CognitivePhase?,
+    ) : CognitiveEvent {
+
+        override val eventType: EventType = EVENT_TYPE
+
+        override fun getSummary(
+            formatUrgency: (Urgency) -> String,
+            formatSource: (EventSource) -> String,
+        ): String = buildString {
+            append("Escalation fired for $agentId: uncertainty ")
+            append(uncertaintyValue.formatRatio())
+            append(" >= threshold ")
+            append(threshold.formatRatio())
+            cognitivePhase?.let { append(" [${it.name}]") }
+            if (prompt.isNotBlank()) {
+                append(" - ${prompt.take(80)}")
+                if (prompt.length > 80) append("...")
+            }
+            append(" ${formatUrgency(urgency)}")
+            append(" from ${formatSource(eventSource)}")
+        }
+
+        companion object {
+            const val EVENT_TYPE: EventType = "EscalationFired"
+        }
+    }
+}
+
+private fun Double.formatRatio(): String {
+    val rounded = (this * 1000.0).toInt() / 1000.0
+    return rounded.toString()
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/EventRegistry.kt

@@ -30,6 +30,9 @@ object EventRegistry {
         Event.QuestionRaised.EVENT_TYPE,
         Event.CodeSubmitted.EVENT_TYPE,
 
+        // CognitiveEvent types
+        CognitiveEvent.EscalationFired.EVENT_TYPE,
+
         // MeetingEvent types
         MeetingEvent.MeetingScheduled.EVENT_TYPE,
         MeetingEvent.MeetingStarted.EVENT_TYPE,

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/MemoryEvent.kt

@@ -37,6 +37,14 @@ data class RetrievedKnowledgeSummary(
  */
 sealed interface MemoryEvent : Event {
 
+    // TODO(AMPR-176): Add `ProvenanceCommitted` here when the provenance-chain
+    // surface is promoted from design placeholder to implementation. Design
+    // sketch in docs/design/provenance-event.md covers event shape
+    // (entryId / parentHash / contentHash / signer), hash/signature scheme,
+    // publish-site choice, and the relationship to the OpenAI grant's
+    // formal-verification workstream. Do not implement here without first
+    // satisfying one of the promotion criteria in that doc.
+
     /**
      * Event emitted when a Knowledge entry is successfully stored.
      *

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/api/AgentEventApi.kt

@@ -5,6 +5,7 @@ import kotlinx.datetime.Instant
 import link.socket.ampere.agents.config.AgentActionAutonomy
 import link.socket.ampere.agents.definition.AgentId
 import link.socket.ampere.agents.domain.Urgency
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
 import link.socket.ampere.agents.domain.event.EventType
@@ -206,6 +207,20 @@ class AgentEventApi(
             }
         }
 
+    /** Subscribe to threshold-driven cognitive escalation events. */
+    fun onEscalationFired(
+        filter: EventFilter<CognitiveEvent.EscalationFired> = EventFilter.noFilter(),
+        handler: suspend (CognitiveEvent.EscalationFired, Subscription?) -> Unit,
+    ): Subscription =
+        eventSerialBus.subscribe<CognitiveEvent.EscalationFired, EventSubscription.ByEventClassType>(
+            agentId = agentId,
+            eventType = CognitiveEvent.EscalationFired.EVENT_TYPE,
+        ) { event, subscription ->
+            if (filter.execute(event)) {
+                handler(event, subscription)
+            }
+        }
+
     /** Retrieve all events since the provided timestamp, or all if null. */
     suspend fun getRecentEvents(
         since: Instant?,