AMPR-175 (#504): add milestone memory events

Adds MemoryEvent.MilestoneReached, per-agent milestone tracking, explicit milestone publishing APIs, CLI handling, tests, and docs.

Implemented-by: Codex

Author: codex

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

@@ -85,6 +85,7 @@ object EventCategorizer {
         is ProductEvent.FeatureRequested,
         is ProductEvent.EpicDefined,
         is ProductEvent.PhaseDefined,
+        is MemoryEvent.MilestoneReached,
         is ProviderCallCompletedEvent,
         is TicketEvent.TicketCreated,
         is TicketEvent.TicketStatusChanged,

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

@@ -381,6 +381,9 @@ class WatchPresenter(
                 val tags = event.tags.take(3).joinToString(", ")
                 if (tags.isNotEmpty()) "Stored $type: $tags" else "Stored $type knowledge"
             }
+            is MemoryEvent.MilestoneReached -> {
+                "Milestone ${event.category.name.lowercase()}: ${event.description.take(50)}"
+            }
             is Event.QuestionRaised -> "Question: ${event.questionText.take(50)}"
             is MeetingEvent.MeetingScheduled -> "Meeting: ${event.meeting.invitation.title.take(50)}"
             is MeetingEvent.MeetingStarted -> "Meeting started (${event.meetingId.takeLast(8)})"

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

@@ -8,6 +8,7 @@ import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
 import link.socket.ampere.agents.domain.event.MemoryEvent
 import link.socket.ampere.agents.domain.event.MessageEvent
+import link.socket.ampere.agents.domain.event.MilestoneCategory
 import link.socket.ampere.agents.domain.event.SparkAppliedEvent
 import link.socket.ampere.agents.domain.event.TicketEvent
 import link.socket.ampere.agents.domain.memory.MemoryContext
@@ -173,6 +174,26 @@ class EventCategorizerTest {
         assertEquals(EventSignificance.ROUTINE, significance)
     }
 
+    @Test
+    fun `SIGNIFICANT - MilestoneReached events are significant`() {
+        val event = MemoryEvent.MilestoneReached(
+            eventId = "evt-milestone-1",
+            timestamp = Clock.System.now(),
+            eventSource = EventSource.Agent("agent-test"),
+            urgency = Urgency.MEDIUM,
+            agentId = "agent-test",
+            milestoneId = "milestone-1",
+            description = "First successful code change",
+            knowledgeId = null,
+            taskId = "task-1",
+            runId = "run-1",
+            category = MilestoneCategory.FIRST_SUCCESS,
+        )
+
+        val significance = EventCategorizer.categorize(event)
+        assertEquals(EventSignificance.SIGNIFICANT, significance)
+    }
+
     @Test
     fun `ROUTINE events should not display by default`() {
         val routineEvent = MemoryEvent.KnowledgeRecalled(

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

@@ -6,6 +6,7 @@ import kotlin.test.assertNull
 import kotlin.test.assertTrue
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.MeetingEvent
+import link.socket.ampere.agents.domain.event.MemoryEvent
 import link.socket.ampere.agents.domain.event.MessageEvent
 import link.socket.ampere.agents.domain.event.NotificationEvent
 import link.socket.ampere.agents.domain.event.TicketEvent
@@ -80,6 +81,11 @@ class EventTypeParserTest {
         assertNotNull(EventTypeParser.parse("NotificationToHuman"))
     }
 
+    @Test
+    fun `parse handles milestone event type`() {
+        assertNotNull(EventTypeParser.parse("MilestoneReached"))
+    }
+
     @Test
     fun `parseMultiple returns set of EventClassTypes`() {
         val result = EventTypeParser.parseMultiple(
@@ -139,6 +145,9 @@ class EventTypeParserTest {
         // Should have notification events
         assertTrue(allNames.contains("notificationtoagent"))
         assertTrue(allNames.contains("notificationtohuman"))
+
+        // Should have milestone events
+        assertTrue(allNames.contains("milestonereached"))
     }
 
     @Test
@@ -159,6 +168,9 @@ class EventTypeParserTest {
         // Should have message events
         assertTrue(allTypes.contains(MessageEvent.ThreadCreated.EVENT_TYPE))
 
+        // Should have milestone events
+        assertTrue(allTypes.contains(MemoryEvent.MilestoneReached.EVENT_TYPE))
+
         // Should have notification events
         assertTrue(allTypes.contains(NotificationEvent.ToAgent.EVENT_TYPE))
         assertTrue(allTypes.contains(NotificationEvent.ToHuman.EVENT_TYPE))

ampere-core/src/commonMain/kotlin/link/socket/ampere/agents/definition/ObservableAgent.kt

@@ -8,9 +8,11 @@ import kotlinx.serialization.Serializable
 import link.socket.ampere.agents.domain.cognition.Spark
 import link.socket.ampere.agents.domain.event.CognitiveStateSnapshot
 import link.socket.ampere.agents.domain.event.EventSource
+import link.socket.ampere.agents.domain.event.MilestoneCategory
 import link.socket.ampere.agents.domain.event.SparkAppliedEvent
 import link.socket.ampere.agents.domain.event.SparkRemovedEvent
 import link.socket.ampere.agents.domain.state.AgentState
+import link.socket.ampere.agents.domain.task.TaskId
 import link.socket.ampere.agents.events.api.AgentEventApi
 import link.socket.ampere.agents.events.utils.generateUUID
 
@@ -112,4 +114,25 @@ abstract class ObservableAgent<S : AgentState>(
             }
         }
     }
+
+    /**
+     * Explicitly publish a milestone for externally declared checkpoints.
+     */
+    suspend fun reachMilestone(
+        category: MilestoneCategory,
+        description: String,
+        knowledgeId: String? = null,
+        taskId: TaskId? = null,
+        runId: String? = null,
+        milestoneId: String = generateUUID("milestone", id),
+    ) {
+        eventApi?.reachMilestone(
+            category = category,
+            description = description,
+            knowledgeId = knowledgeId,
+            taskId = taskId,
+            runId = runId,
+            milestoneId = milestoneId,
+        )
+    }
 }

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

@@ -59,6 +59,7 @@ object EventRegistry {
         // MemoryEvent types
         MemoryEvent.KnowledgeStored.EVENT_TYPE,
         MemoryEvent.KnowledgeRecalled.EVENT_TYPE,
+        MemoryEvent.MilestoneReached.EVENT_TYPE,
 
         // ToolEvent types
         ToolEvent.ToolRegistered.EVENT_TYPE,

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

@@ -3,9 +3,11 @@ package link.socket.ampere.agents.domain.event
 import kotlin.math.roundToInt
 import kotlinx.datetime.Instant
 import kotlinx.serialization.Serializable
+import link.socket.ampere.agents.definition.AgentId
 import link.socket.ampere.agents.domain.Urgency
 import link.socket.ampere.agents.domain.knowledge.KnowledgeType
 import link.socket.ampere.agents.domain.memory.MemoryContext
+import link.socket.ampere.agents.domain.task.TaskId
 
 /** Format a double to 2 decimal places (multiplatform compatible). */
 private fun Double.formatPercent(): String {
@@ -174,4 +176,65 @@ sealed interface MemoryEvent : Event {
             const val EVENT_TYPE: EventType = "KnowledgeRecalled"
         }
     }
+
+    /**
+     * Event emitted when an agent reaches a meaningful checkpoint.
+     *
+     * Milestones are low-volume signals for significant agent progress. They are
+     * intentionally separate from [KnowledgeStored] so consumers can subscribe to
+     * milestone semantics without filtering routine memory writes.
+     */
+    @Serializable
+    data class MilestoneReached(
+        override val eventId: EventId,
+        override val timestamp: Instant,
+        override val eventSource: EventSource,
+        val agentId: AgentId,
+        val milestoneId: String,
+        val description: String,
+        val knowledgeId: String?,
+        val taskId: TaskId?,
+        val runId: String?,
+        val category: MilestoneCategory,
+        override val urgency: Urgency = Urgency.MEDIUM,
+    ) : MemoryEvent {
+
+        override val eventType: EventType = EVENT_TYPE
+
+        override fun getSummary(
+            formatUrgency: (Urgency) -> String,
+            formatSource: (EventSource) -> String,
+        ): String = buildString {
+            append("Milestone reached: ")
+            append(category.name.lowercase().replace('_', ' ').replaceFirstChar { it.uppercase() })
+            append(" - ")
+            append(description)
+            taskId?.let { append(" (task=$it)") }
+            knowledgeId?.let { append(" knowledge=$it") }
+            append(" ${formatUrgency(urgency)}")
+            append(" by ${formatSource(eventSource)}")
+        }
+
+        companion object {
+            const val EVENT_TYPE: EventType = "MilestoneReached"
+        }
+    }
+}
+
+/**
+ * Categories for [MemoryEvent.MilestoneReached].
+ *
+ * [FIRST_SUCCESS] and [RECOVERY] are emitted by the built-in milestone tracker.
+ * [EXTERNAL] is emitted through the explicit milestone API for human-in-the-loop
+ * approvals or external orchestration scripts. [KEY_INSIGHT] and [CHECKPOINT]
+ * are available for future implementation when AMPERE promotes insight and
+ * long-running progress signals into explicit milestone publish sites.
+ */
+@Serializable
+enum class MilestoneCategory {
+    FIRST_SUCCESS,
+    KEY_INSIGHT,
+    RECOVERY,
+    CHECKPOINT,
+    EXTERNAL,
 }

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

@@ -85,6 +85,8 @@ sealed interface TaskEvent : Event {
         override val eventSource: EventSource,
         override val timestamp: Instant,
         val summary: String,
+        val taskType: String? = null,
+        val runId: String? = null,
         override val urgency: Urgency = Urgency.MEDIUM,
     ) : TaskEvent {
 
@@ -108,6 +110,7 @@ sealed interface TaskEvent : Event {
         override val eventSource: EventSource,
         override val timestamp: Instant,
         val reason: String,
+        val runId: String? = null,
         override val urgency: Urgency = Urgency.HIGH,
     ) : TaskEvent {
 

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

@@ -252,5 +252,8 @@ private fun Event.runIdOrNull(): String? = when (this) {
     is ToolEvent.ToolExecutionCompleted -> runId
     is MemoryEvent.KnowledgeStored -> runId
     is MemoryEvent.KnowledgeRecalled -> runId
+    is MemoryEvent.MilestoneReached -> runId
+    is link.socket.ampere.agents.domain.event.TaskEvent.TaskCompleted -> runId
+    is link.socket.ampere.agents.domain.event.TaskEvent.TaskFailed -> runId
     else -> null
 }

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

@@ -8,7 +8,9 @@ import link.socket.ampere.agents.domain.Urgency
 import link.socket.ampere.agents.domain.event.Event
 import link.socket.ampere.agents.domain.event.EventSource
 import link.socket.ampere.agents.domain.event.EventType
+import link.socket.ampere.agents.domain.event.MemoryEvent
 import link.socket.ampere.agents.domain.event.MessageEvent
+import link.socket.ampere.agents.domain.event.MilestoneCategory
 import link.socket.ampere.agents.domain.event.PermissionDeniedEvent
 import link.socket.ampere.agents.domain.event.PermissionDeniedReason
 import link.socket.ampere.agents.domain.event.TaskEvent
@@ -56,7 +58,13 @@ class AgentEventApi(
     private val eventRepository: EventRepository,
     private val eventSerialBus: EventSerialBus,
     private val logger: EventLogger = ConsoleEventLogger(),
+    milestoneTrackerState: MilestoneTrackerState = MilestoneTrackerState(),
 ) {
+    private val milestoneTracker = MilestoneTracker(this, milestoneTrackerState)
+
+    init {
+        milestoneTracker.start()
+    }
 
     /** Persist and publish a pre-constructed event. */
     suspend fun publish(event: Event) {
@@ -307,6 +315,8 @@ class AgentEventApi(
     suspend fun publishTaskCompleted(
         taskId: TaskId,
         summary: String,
+        taskType: String? = null,
+        runId: String? = null,
         urgency: Urgency = Urgency.MEDIUM,
     ) {
         val event = TaskEvent.TaskCompleted(
@@ -315,6 +325,8 @@ class AgentEventApi(
             eventSource = EventSource.Agent(agentId),
             timestamp = Clock.System.now(),
             summary = summary,
+            taskType = taskType,
+            runId = runId,
             urgency = urgency,
         )
 
@@ -325,6 +337,7 @@ class AgentEventApi(
     suspend fun publishTaskFailed(
         taskId: TaskId,
         reason: String,
+        runId: String? = null,
         urgency: Urgency = Urgency.HIGH,
     ) {
         val event = TaskEvent.TaskFailed(
@@ -333,6 +346,36 @@ class AgentEventApi(
             eventSource = EventSource.Agent(agentId),
             timestamp = Clock.System.now(),
             reason = reason,
+            runId = runId,
+            urgency = urgency,
+        )
+
+        publish(event)
+    }
+
+    /**
+     * Publish a milestone when an agent or external consumer identifies a significant checkpoint.
+     */
+    suspend fun reachMilestone(
+        category: MilestoneCategory,
+        description: String,
+        knowledgeId: String? = null,
+        taskId: TaskId? = null,
+        runId: String? = null,
+        milestoneId: String = generateUUID("milestone", agentId),
+        urgency: Urgency = Urgency.MEDIUM,
+    ) {
+        val event = MemoryEvent.MilestoneReached(
+            eventId = generateUUID(milestoneId, agentId),
+            timestamp = Clock.System.now(),
+            eventSource = EventSource.Agent(agentId),
+            agentId = agentId,
+            milestoneId = milestoneId,
+            description = description,
+            knowledgeId = knowledgeId,
+            taskId = taskId,
+            runId = runId,
+            category = category,
             urgency = urgency,
         )
 
@@ -441,6 +484,20 @@ class AgentEventApi(
             }
         }
 
+    /** Subscribe to milestone events. */
+    fun onMilestoneReached(
+        filter: EventFilter<MemoryEvent.MilestoneReached> = EventFilter.noFilter(),
+        handler: suspend (MemoryEvent.MilestoneReached, Subscription?) -> Unit,
+    ): Subscription =
+        eventSerialBus.subscribe<MemoryEvent.MilestoneReached, EventSubscription.ByEventClassType>(
+            agentId = agentId,
+            eventType = MemoryEvent.MilestoneReached.EVENT_TYPE,
+        ) { event, subscription ->
+            if (filter.execute(event)) {
+                handler(event, subscription)
+            }
+        }
+
     // ==================== Tool Event Publishing Methods ====================
 
     /** Publish a ToolRegistered event with auto-generated ID and current timestamp. */