AMPR-151 #460: add AgentPause primitive type system (#470)

I added the AgentPause sealed type system in commonMain — AgentPause data
class with PauseUrgency (Routine/Important/Critical) and PauseCorrelationId,
the EscalationChannel sealed hierarchy (Push, Voice, InAppCard, PublicLink),
and AgentPauseResponse (Approved/Rejected/TimedOut). I stubbed the
expect class ChannelAvailability with empty actuals on iOS, Android, JVM,
JS, and Wasm so W1.5 and W2.2 can build against the contract before the
real platform logic lands. I wrote round-trip serialization, ordering, and
exhaustiveness tests, and documented the channel-fallback ordering, the
urgency-to-default-channel mapping, and the relationship to
ConsentRepository in docs/ampere/agent-pause.md.

Closes #460

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

Author: wow-miley

ampere-core/src/androidMain/kotlin/link/socket/ampere/pause/ChannelAvailability.android.kt

@@ -0,0 +1,13 @@
+package link.socket.ampere.pause
+
+import kotlin.reflect.KClass
+
+/**
+ * Android stub. Real implementation in W1.5 will query NotificationManager
+ * channel state, RecognizerIntent voice support, and the Ampere shell's
+ * lifecycle state.
+ */
+actual class ChannelAvailability actual constructor() {
+
+    actual fun available(): List<KClass<out EscalationChannel>> = emptyList()
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/pause/AgentPause.kt

@@ -0,0 +1,68 @@
+package link.socket.ampere.pause
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Correlation identifier used to pair a [AgentPause] request with its
+ * matching [AgentPauseResponse]. Plugins generate one per pause they emit.
+ */
+typealias PauseCorrelationId = String
+
+/**
+ * A typed, serializable description of an agent that has paused execution and
+ * is awaiting human input.
+ *
+ * `AgentPause` is the OS-native escalation primitive. Where [link.socket.ampere
+ * .agents.events.surface.AgentSurface] models a Plugin asking the platform to
+ * render UI, `AgentPause` models the higher-level *intent* of "I am stuck and
+ * need a person." Channel selection (push notification → voice prompt →
+ * in-app card → public link) is handled by the W1.5 channel-selector against
+ * [suggestedChannels]; this type fixes the contract so renderers and per-Arc
+ * override UI can build against it now.
+ *
+ * The contract intentionally lives in commonMain and carries no platform
+ * references so it can be expressed across every Ampere target.
+ */
+@Serializable
+data class AgentPause(
+    /** Stable identifier used to pair this pause with its response. */
+    val correlationId: PauseCorrelationId,
+    /** Human-readable explanation of why the agent paused. */
+    val reason: String,
+    /** How time-sensitive the pause is; drives default channel selection. */
+    val urgency: PauseUrgency,
+    /**
+     * Ordered list of channels to attempt, highest priority first. The
+     * channel selector walks this list and falls through to the next channel
+     * on unavailability or non-response.
+     */
+    val suggestedChannels: List<EscalationChannel>,
+    /** How long to wait before considering the pause [AgentPauseResponse.TimedOut]. */
+    val timeoutMillis: Long,
+    /**
+     * Public URL the user can visit to respond, used as the lowest-priority
+     * fallback when no native channel is available. Optional — pauses that
+     * must not leak to a public surface should leave this null.
+     */
+    val fallbackUrl: String? = null,
+)
+
+/**
+ * Urgency level of an [AgentPause].
+ *
+ * This is intentionally distinct from [link.socket.ampere.agents.domain.Urgency]
+ * (which classifies bus events). Pause urgency drives channel-selection
+ * defaults: [Routine] prefers in-app card, [Important] prefers push
+ * notification, [Critical] prefers voice prompt.
+ */
+@Serializable
+enum class PauseUrgency {
+    /** Non-blocking; in-app card is the default channel. */
+    Routine,
+
+    /** Time-sensitive; push notification is the default channel. */
+    Important,
+
+    /** Blocking; voice prompt is the default channel. */
+    Critical,
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/pause/AgentPauseResponse.kt

@@ -0,0 +1,45 @@
+package link.socket.ampere.pause
+
+import kotlinx.serialization.Serializable
+
+/**
+ * The reply to an [AgentPause].
+ *
+ * Every variant carries the same [correlationId] as the originating
+ * [AgentPause], which is what lets the awaiter pair the response with the
+ * request that emitted it.
+ */
+@Serializable
+sealed interface AgentPauseResponse {
+
+    /** Echo of the originating [AgentPause.correlationId]. */
+    val correlationId: PauseCorrelationId
+
+    /**
+     * The user approved the paused operation. [payload] carries any
+     * additional structured data the responder supplied (e.g., a confirmation
+     * note, a chosen option). It is opaque to the pause primitive — Plugin
+     * code parses it.
+     */
+    @Serializable
+    data class Approved(
+        override val correlationId: PauseCorrelationId,
+        val payload: String? = null,
+    ) : AgentPauseResponse
+
+    /** The user rejected the paused operation. */
+    @Serializable
+    data class Rejected(
+        override val correlationId: PauseCorrelationId,
+        val reason: String? = null,
+    ) : AgentPauseResponse
+
+    /**
+     * No channel produced a response within [AgentPause.timeoutMillis]. The
+     * agent should treat the pause as unanswered.
+     */
+    @Serializable
+    data class TimedOut(
+        override val correlationId: PauseCorrelationId,
+    ) : AgentPauseResponse
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/pause/ChannelAvailability.kt

@@ -0,0 +1,28 @@
+package link.socket.ampere.pause
+
+import kotlin.reflect.KClass
+
+/**
+ * Platform query for which [EscalationChannel] variants are currently
+ * available on this device.
+ *
+ * The W1.5 channel-selector consults [available] before walking
+ * [AgentPause.suggestedChannels] and skips channels whose variant is not in
+ * the returned set. Per-platform implementations inspect runtime state
+ * (notification permissions, voice-input availability, foreground/background)
+ * to populate the result.
+ *
+ * This file ships intentionally empty stubs in W0.3 — the actual platform
+ * logic lands in W1.5. The contract exists now so W1.5 and W2.2 can build
+ * against a stable API.
+ */
+expect class ChannelAvailability() {
+
+    /**
+     * Returns the [EscalationChannel] subclasses that are currently usable.
+     * An empty result means no native channel is available — callers should
+     * fall through to [EscalationChannel.PublicLink] if the originating
+     * [AgentPause.fallbackUrl] is set, or treat the pause as unrouteable.
+     */
+    fun available(): List<KClass<out EscalationChannel>>
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/pause/EscalationChannel.kt

@@ -0,0 +1,73 @@
+package link.socket.ampere.pause
+
+import kotlinx.serialization.Serializable
+
+/**
+ * A channel through which an [AgentPause] can solicit a human response.
+ *
+ * Each variant declares the minimal renderer parameters needed for a platform
+ * implementation to dispatch the channel without reaching back into Ampere.
+ * The channel-selector (W1.5) walks [AgentPause.suggestedChannels] in order;
+ * the per-Arc override UI (W2.2) reorders or filters the list.
+ */
+@Serializable
+sealed interface EscalationChannel {
+
+    /**
+     * Native push notification. The renderer maps [notificationCategory] onto
+     * the platform-specific category/channel id (Android notification channel,
+     * iOS `UNNotificationCategory`).
+     */
+    @Serializable
+    data class Push(
+        val notificationCategory: String,
+        val title: String,
+        val body: String,
+        val deeplink: String? = null,
+    ) : EscalationChannel
+
+    /**
+     * Voice prompt — typically a synthesized read-out followed by a
+     * speech-to-text response window. Used for [PauseUrgency.Critical] pauses
+     * by default.
+     */
+    @Serializable
+    data class Voice(
+        val prompt: String,
+        val expectedResponseSeconds: Int = 15,
+        val voiceProfile: String? = null,
+    ) : EscalationChannel
+
+    /**
+     * In-app card displayed inside the Ampere shell. The renderer resolves
+     * [cardKind] to an in-app surface (e.g., a banner, a modal, an Arc-pinned
+     * card).
+     */
+    @Serializable
+    data class InAppCard(
+        val cardKind: CardKind,
+        val title: String,
+        val body: String,
+        val primaryActionLabel: String = "Approve",
+        val secondaryActionLabel: String = "Reject",
+    ) : EscalationChannel {
+
+        @Serializable
+        enum class CardKind {
+            Banner,
+            Modal,
+            ArcPinned,
+        }
+    }
+
+    /**
+     * Lowest-priority fallback: a public URL the user opens in a browser.
+     * Used when no native channel is available, or when the agent
+     * intentionally wants to reach a non-Ampere recipient.
+     */
+    @Serializable
+    data class PublicLink(
+        val url: String,
+        val displayLabel: String = "Open in browser",
+    ) : EscalationChannel
+}