Merge remote-tracking branch 'origin/main' into miley/ampr-171-cognitivephaseevent-publish-phase-transitions-on

Miley Chandonnet · Miley Chandonnet · commit 3c778b2afad9 · 2026-05-30T19:56:29.000-05:00
# Conflicts:
#	ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizer.kt
#	ampere-cli/src/jvmMain/kotlin/link/socket/ampere/renderer/EventRenderer.kt
#	ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/utils/SignificanceAwareEventLogger.kt
#	ampere-core/src/commonMain/kotlin/link/socket/ampere/api/service/EventService.kt
#	ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/EventSerializationTest.kt
diff --git a/ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizer.kt b/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.CognitivePhaseEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.FileSystemEvent
@@ -53,6 +54,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,
diff --git a/ampere-cli/src/jvmMain/kotlin/link/socket/ampere/cli/watch/presentation/WatchPresenter.kt b/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)})"
diff --git a/ampere-cli/src/jvmMain/kotlin/link/socket/ampere/renderer/EventRenderer.kt b/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.CognitivePhaseEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
@@ -137,6 +138,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
diff --git a/ampere-cli/src/jvmTest/kotlin/link/socket/ampere/cli/watch/presentation/EventCategorizerTest.kt b/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
@@ -67,6 +68,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(
diff --git a/ampere-cli/src/jvmTest/kotlin/link/socket/ampere/renderer/EventRendererTest.kt b/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
diff --git a/ampere-cli/src/jvmTest/kotlin/link/socket/ampere/util/EventTypeParserTest.kt b/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.MessageEvent
 import link.socket.ampere.agents.domain.event.NotificationEvent
@@ -46,6 +47,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"))
@@ -149,6 +155,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))
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/CognitiveEvent.kt b/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()
+}
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/EventRegistry.kt b/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,
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/MemoryEvent.kt b/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/domain/event/MemoryEvent.kt
@@ -35,6 +35,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.
      *
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/api/AgentEventApi.kt b/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
@@ -198,6 +199,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?,
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/escalation/UncertaintyEscalationEvaluator.kt b/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/escalation/UncertaintyEscalationEvaluator.kt
@@ -0,0 +1,71 @@
+package link.socket.ampere.agents.events.escalation
+
+import kotlinx.datetime.Clock
+import link.socket.ampere.agents.definition.AgentId
+import link.socket.ampere.agents.domain.Urgency
+import link.socket.ampere.agents.domain.cognition.sparks.CognitivePhase
+import link.socket.ampere.agents.domain.event.CognitiveEvent
+import link.socket.ampere.agents.domain.event.EventSource
+import link.socket.ampere.agents.events.api.AgentEventApi
+import link.socket.ampere.agents.events.utils.generateUUID
+
+/**
+ * Evaluates uncertainty against an escalation threshold and publishes the threshold-fired signal.
+ */
+class UncertaintyEscalationEvaluator(
+    private val agentId: AgentId,
+    private val publishEscalationFired: suspend (CognitiveEvent.EscalationFired) -> Unit,
+    private val clock: Clock = Clock.System,
+) {
+
+    constructor(
+        agentEventApi: AgentEventApi,
+        clock: Clock = Clock.System,
+    ) : this(
+        agentId = agentEventApi.agentId,
+        publishEscalationFired = { event -> agentEventApi.publish(event) },
+        clock = clock,
+    )
+
+    /**
+     * @return true when the threshold fired and an [CognitiveEvent.EscalationFired] was published.
+     */
+    suspend fun evaluate(
+        uncertaintyValue: Double,
+        threshold: Double,
+        prompt: String,
+        cognitivePhase: CognitivePhase? = null,
+        urgency: Urgency = Urgency.HIGH,
+    ): Boolean {
+        require(uncertaintyValue in UNCERTAINTY_RANGE) {
+            "uncertaintyValue must be in [0.0, 1.0], was $uncertaintyValue"
+        }
+        require(threshold in UNCERTAINTY_RANGE) {
+            "threshold must be in [0.0, 1.0], was $threshold"
+        }
+
+        if (uncertaintyValue < threshold) {
+            return false
+        }
+
+        publishEscalationFired(
+            CognitiveEvent.EscalationFired(
+                eventId = generateUUID(agentId),
+                timestamp = clock.now(),
+                eventSource = EventSource.Agent(agentId),
+                urgency = urgency,
+                agentId = agentId,
+                uncertaintyValue = uncertaintyValue,
+                threshold = threshold,
+                prompt = prompt,
+                cognitivePhase = cognitivePhase,
+            ),
+        )
+
+        return true
+    }
+
+    private companion object {
+        val UNCERTAINTY_RANGE = 0.0..1.0
+    }
+}
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/utils/SignificanceAwareEventLogger.kt b/ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/events/utils/SignificanceAwareEventLogger.kt
@@ -3,6 +3,7 @@ package link.socket.ampere.agents.events.utils
 import co.touchlab.kermit.Logger
 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.CognitivePhaseEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
@@ -96,6 +97,7 @@ class SignificanceAwareEventLogger(
     private fun categorizeEvent(event: Event): EventSignificance = when (event) {
         // Critical events require immediate human awareness
         is Event.QuestionRaised -> EventSignificance.CRITICAL
+        is CognitiveEvent.EscalationFired -> EventSignificance.CRITICAL
         is TicketEvent.TicketBlocked -> EventSignificance.CRITICAL
         is MessageEvent.EscalationRequested -> EventSignificance.CRITICAL
         is PermissionDeniedEvent -> EventSignificance.CRITICAL
diff --git a/ampere-core/src/commonMain/kotlin/link/socket/ampere/api/service/EventService.kt b/ampere-core/src/commonMain/kotlin/link/socket/ampere/api/service/EventService.kt
@@ -4,6 +4,7 @@ import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterIsInstance
 import kotlinx.datetime.Instant
+import link.socket.ampere.agents.domain.event.CognitiveEvent
 import link.socket.ampere.agents.domain.event.CognitivePhaseEvent
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.FileSystemEvent
@@ -156,6 +157,11 @@ fun EventService.completionEvents(
     filters: EventRelayFilters = EventRelayFilters(),
 ): Flow<ProviderCallCompletedEvent> = observe(filters).filterIsInstance<ProviderCallCompletedEvent>()
 
+@link.socket.ampere.api.AmpereStableApi
+fun EventService.escalationFiredEvents(
+    filters: EventRelayFilters = EventRelayFilters(),
+): Flow<CognitiveEvent.EscalationFired> = observe(filters).filterIsInstance<CognitiveEvent.EscalationFired>()
+
 @link.socket.ampere.api.AmpereStableApi
 enum class EventStreamFilter {
     ALL,
@@ -197,6 +203,7 @@ enum class EventStreamFilter {
             is RoutingEvent,
             is CognitivePhaseEvent,
             is SparkEvent,
+            is CognitiveEvent,
             -> true
             else -> false
         }
diff --git a/ampere-core/src/commonTest/kotlin/link/socket/ampere/agents/events/escalation/UncertaintyEscalationEvaluatorTest.kt b/ampere-core/src/commonTest/kotlin/link/socket/ampere/agents/events/escalation/UncertaintyEscalationEvaluatorTest.kt
diff --git a/ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/EventSerializationTest.kt b/ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/EventSerializationTest.kt
diff --git a/ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/messages/AgentMessageApiTest.kt b/ampere-core/src/jvmTest/kotlin/link/socket/ampere/agents/events/messages/AgentMessageApiTest.kt
diff --git a/docs/ampere/events.md b/docs/ampere/events.md
diff --git a/docs/design/provenance-event.md b/docs/design/provenance-event.md
