merge: B-M2c Android message window store, pagination fixtures green

This commit is contained in:
weishu
2026-08-17 15:51:34 +08:00
15 changed files with 2880 additions and 2 deletions
@@ -0,0 +1,129 @@
package app.hapi.protocol.window
import app.hapi.protocol.wire.OptionalField
import app.hapi.protocol.wire.isUserMessage
import kotlin.math.abs
/**
* Merge/order semantics for window rows — a faithful port of
* `web/src/lib/messages.ts` (`compareMessages`, `mergeMessages`).
*/
object MessageMerge {
/**
* Position comparator: ascending `at = invokedAt ?? createdAt`, ties by
* `seq`, full ties by ASCII id comparison. The web uses `localeCompare`
* for the final tie-break, but the fixtures keep every position pair
* distinct and the fixtures README pins ASCII comparison for native
* ports (`shared/fixtures/README.md`, pagination determinism notes).
*/
val comparator: Comparator<WindowMessage> = Comparator { a, b ->
val aTime = a.invokedAtOrNull ?: a.createdAt
val bTime = b.invokedAtOrNull ?: b.createdAt
if (aTime != bTime) return@Comparator aTime.compareTo(bTime)
val aSeq = a.seq
val bSeq = b.seq
if (aSeq != null && bSeq != null && aSeq != bSeq) return@Comparator aSeq.compareTo(bSeq)
a.id.compareTo(b.id)
}
/**
* Merge [incoming] into [existing]:
* - by-id upsert (incoming wins; a numeric `invokedAt` already known
* locally is preserved when the incoming copy lacks one);
* - stored rows carrying a `localId` evict the optimistic bubble with the
* same `localId`, inheriting its client `status` (when the server row
* has none) and any locally-known numeric `invokedAt`;
* - fallback: an optimistic row already `sent` is dropped when a server
* user message sits within 10 s of the same position;
* - stable sort by [comparator].
*/
fun mergeMessages(existing: List<WindowMessage>, incoming: List<WindowMessage>): List<WindowMessage> {
if (existing.isEmpty()) {
return incoming.sortedWith(comparator)
}
if (incoming.isEmpty()) {
return existing.sortedWith(comparator)
}
val byId = LinkedHashMap<String, WindowMessage>()
for (message in existing) {
byId[message.id] = message
}
for (message in incoming) {
val current = byId[message.id]
// JS `existing.invokedAt != null && msg.invokedAt == null` — keep a
// locally-known invocation stamp when the incoming copy has none
// (explicit null or absent).
byId[message.id] = if (current != null && current.invokedAtOrNull != null && message.invokedAtOrNull == null) {
message.withInvokedAt(current.invokedAtOrNull!!)
} else {
message
}
}
var merged: List<WindowMessage> = byId.values.toList()
val incomingStoredLocalIds = buildSet {
for (message in incoming) {
val localId = message.localId
if (localId != null && !message.isOptimistic) add(localId)
}
}
if (incomingStoredLocalIds.isNotEmpty()) {
val optimisticStatusByLocalId = HashMap<String, MessageStatus>()
val optimisticInvokedAtByLocalId = HashMap<String, Long?>()
for (message in merged) {
val localId = message.localId ?: continue
if (!message.isOptimistic || localId !in incomingStoredLocalIds) continue
message.status?.let { optimisticStatusByLocalId[localId] = it }
if (message.wire.invokedAt is OptionalField.Present) {
optimisticInvokedAtByLocalId[localId] = message.invokedAtOrNull
}
}
merged = merged.filter { message ->
val localId = message.localId
localId == null || localId !in incomingStoredLocalIds || !message.isOptimistic
}
if (optimisticStatusByLocalId.isNotEmpty() || optimisticInvokedAtByLocalId.isNotEmpty()) {
merged = merged.map { message ->
val localId = message.localId ?: return@map message
var updated = message
val preservedStatus = optimisticStatusByLocalId[localId]
if (preservedStatus != null && message.status == null) {
updated = updated.copy(status = preservedStatus)
}
if (optimisticInvokedAtByLocalId.containsKey(localId) && message.invokedAtOrNull == null) {
val optimisticInvokedAt = optimisticInvokedAtByLocalId[localId]
if (optimisticInvokedAt != null) {
updated = updated.withInvokedAt(optimisticInvokedAt)
}
}
updated
}
}
}
val optimisticMessages = merged.filter { it.isOptimistic }
val nonOptimisticMessages = merged.filter { !it.isOptimistic }
val result = nonOptimisticMessages.toMutableList()
for (optimistic in optimisticMessages) {
if (optimistic.status == MessageStatus.Sent) {
// Compare by the position key (invokedAt ?? createdAt): a late
// ack can attach invokedAt long after createdAt, and matching
// on createdAt alone would render duplicates.
val optimisticTime = optimistic.invokedAtOrNull ?: optimistic.createdAt
val hasServerUserMessage = nonOptimisticMessages.any { message ->
message.wire.isUserMessage
&& abs((message.invokedAtOrNull ?: message.createdAt) - optimisticTime) < 10_000
}
if (hasServerUserMessage) continue
}
result.add(optimistic)
}
return result.sortedWith(comparator)
}
}
@@ -0,0 +1,213 @@
package app.hapi.protocol.window
import app.hapi.protocol.wire.stringOrNull
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonNull
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
/**
* Renderability predicate for window retention — a faithful port of the
* **null-decision tree** of `normalizeDecryptedMessage`
* (`web/src/chat/normalize.ts` + `web/src/chat/normalizeAgent.ts` +
* `shared/src/messages.ts`), used by the web store's
* `shouldRetainWindowMessage`: rows the chat pipeline would hide never enter
* the window (but still advance cursors).
*
* The web returns `null` (⇒ hidden) in exactly two situations:
* 1. agent rows whose content `isSkippableAgentContent` (meta/compact-summary
* Claude output, empty recaps/agy steps, non-chat-visible system rows);
* 2. codex-envelope agent rows (`content.type === 'codex'`) whose payload
* the codex switch of `normalizeAgentRecord` cannot render.
* Everything else — user rows, unknown roles, unparseable envelopes — falls
* back to a raw-stringify bubble and is renderable.
*
* TODO(B-M2a dedup): the full chat-pipeline port owns the complete
* `normalizeAgentRecord`; once it lands, this predicate should be re-expressed
* as `normalize(...) != null` so the two cannot drift.
*/
object MessageRetention {
fun isRenderable(content: JsonElement): Boolean {
val record = unwrapRoleWrappedRecordEnvelope(content) ?: return true
if (record.role != "agent") return true
if (isSkippableAgentContent(record.content)) return false
if (isCodexContent(record.content) && !isRenderableCodexContent(record.content)) return false
return true
}
// ------------------------------------------------------------ envelope --
internal data class RoleWrappedRecord(val role: String, val content: JsonElement)
/** `shared/src/messages.ts` `isRoleWrappedRecord`: object with a string `role` and a `content` key. */
private fun asRoleWrappedRecord(value: JsonElement?): RoleWrappedRecord? {
val obj = value as? JsonObject ?: return null
val role = obj["role"].stringOrNull ?: return null
if (!obj.containsKey("content")) return null
return RoleWrappedRecord(role, obj["content"] ?: JsonNull)
}
/** `shared/src/messages.ts` `unwrapRoleWrappedRecordEnvelope`. */
internal fun unwrapRoleWrappedRecordEnvelope(value: JsonElement?): RoleWrappedRecord? {
asRoleWrappedRecord(value)?.let { return it }
val obj = value as? JsonObject ?: return null
asRoleWrappedRecord(obj["message"])?.let { return it }
(obj["data"] as? JsonObject)?.let { data -> asRoleWrappedRecord(data["message"])?.let { return it } }
(obj["payload"] as? JsonObject)?.let { payload -> asRoleWrappedRecord(payload["message"])?.let { return it } }
return null
}
// ------------------------------------------------- JS-semantics helpers --
/** JS `isObject` (`shared/src/utils.ts`): non-null `typeof 'object'` — arrays included. */
private fun jsIsObject(value: JsonElement?): Boolean =
value is JsonObject || value is JsonArray
/** JS property access: arrays and primitives have no string keys (→ undefined). */
private fun prop(value: JsonElement?, key: String): JsonElement? =
(value as? JsonObject)?.get(key)
/** JS `asString`: the value iff it is a string. */
private fun asString(value: JsonElement?): String? = value.stringOrNull
/** JS `asNumber`: the value iff it is a finite number. */
private fun asNumber(value: JsonElement?): Double? =
(value as? JsonPrimitive)?.takeUnless { it.isString }?.content?.toDoubleOrNull()
?.takeIf { it.isFinite() }
/** JS `Boolean(x)` truthiness over a JSON value. */
private fun jsTruthy(value: JsonElement?): Boolean = when (value) {
null, is JsonNull -> false
is JsonObject, is JsonArray -> true
is JsonPrimitive -> when {
value.isString -> value.content.isNotEmpty()
value.content == "true" -> true
value.content == "false" -> false
else -> value.content.toDoubleOrNull()?.let { it != 0.0 && !it.isNaN() } ?: false
}
}
/** JS `a ?? b` over JSON lookups (absent and `null` fall through). */
private fun coalesce(vararg values: JsonElement?): JsonElement? =
values.firstOrNull { it != null && it !is JsonNull }
// --------------------------------------------------- agent skippability --
private val VISIBLE_CLAUDE_SYSTEM_SUBTYPES = setOf(
"api_error",
"turn_duration",
"microcompact_boundary",
"compact_boundary",
"away_summary",
)
/** `shared/src/messages.ts` `isClaudeChatVisibleMessage`. */
private fun isClaudeChatVisibleMessage(type: JsonElement?, subtype: JsonElement?): Boolean {
val typeString = type.stringOrNull
if (typeString == "rate_limit_event") return false
if (typeString == "tool_progress") return false
if (typeString != "system") return true
return subtype.stringOrNull in VISIBLE_CLAUDE_SYSTEM_SUBTYPES
}
/** `web/src/chat/normalizeAgent.ts` `isSkippableAgentContent`. */
internal fun isSkippableAgentContent(content: JsonElement?): Boolean {
if (prop(content, "type").stringOrNull != "output") return false
val data = prop(content, "data")?.takeIf { jsIsObject(it) } ?: return false
if (jsTruthy(prop(data, "isMeta")) || jsTruthy(prop(data, "isCompactSummary"))) return true
val dataType = prop(data, "type")
val subtype = prop(data, "subtype")
if (
dataType.stringOrNull == "system"
&& subtype.stringOrNull == "away_summary"
&& asString(prop(data, "content"))?.trim().isNullOrEmpty()
) {
return true
}
if (
dataType.stringOrNull == "agy_message"
&& (asString(prop(data, "content")) ?: "").trim().isEmpty()
) {
return true
}
return !isClaudeChatVisibleMessage(dataType, subtype)
}
/** `content.type === AGENT_MESSAGE_PAYLOAD_TYPE` (`'codex'`, `shared/src/modes.ts`). */
internal fun isCodexContent(content: JsonElement?): Boolean =
prop(content, "type").stringOrNull == "codex"
// ------------------------------------------------- codex renderability --
/**
* Whether the codex branch of `normalizeAgentRecord` yields a non-null
* message for this content (`web/src/chat/normalizeAgent.ts:923-1241`).
*/
internal fun isRenderableCodexContent(content: JsonElement?): Boolean {
val data = prop(content, "data")?.takeIf { jsIsObject(it) } ?: return false
val type = prop(data, "type").stringOrNull ?: return false
return when (type) {
"agent-run-start", "agent-run-update", "agent-run-trace" -> true
"generated-image" ->
!asString(coalesce(prop(data, "imageId"), prop(data, "image_id"))).isNullOrEmpty()
"error" -> prop(data, "message").stringOrNull != null
"message" -> prop(data, "message").stringOrNull != null
"reasoning" -> prop(data, "message").stringOrNull != null
"context_compacted" -> true
"compact-summary" -> prop(data, "summary").stringOrNull != null
"token_count" -> hasCodexTokenUsage(data)
"thread_goal_updated" -> hasValidThreadGoal(prop(data, "goal"))
"thread_goal_cleared" -> true
"tool-call" -> prop(data, "callId").stringOrNull != null
"tool-call-result" -> prop(data, "callId").stringOrNull != null
"plan" -> hasPlanEntries(coalesce(prop(data, "entries"), prop(data, "items")) ?: data)
"plan_update" -> hasPlanEntries(
coalesce(prop(data, "plan"), prop(data, "update"), prop(data, "items"), prop(data, "steps")) ?: data
)
else -> false
}
}
/** Null-condition of `normalizeCodexTokenUsage`: `info` object with numeric input+output tokens. */
private fun hasCodexTokenUsage(data: JsonElement): Boolean {
val info = prop(data, "info")?.takeIf { jsIsObject(it) } ?: return false
val usageSource = sequenceOf("last", "lastTokenUsage", "last_token_usage", "total", "totalTokenUsage", "total_token_usage")
.map { prop(info, it) }
.firstOrNull { jsIsObject(it) }
?: info
val input = asNumber(coalesce(prop(usageSource, "inputTokens"), prop(usageSource, "input_tokens")))
val output = asNumber(coalesce(prop(usageSource, "outputTokens"), prop(usageSource, "output_tokens")))
return input != null && output != null
}
/** Null-condition of `normalizeThreadGoal`. */
private fun hasValidThreadGoal(goal: JsonElement?): Boolean {
if (!jsIsObject(goal)) return false
val threadId = asString(coalesce(prop(goal, "threadId"), prop(goal, "thread_id")))
val objective = asString(prop(goal, "objective"))
val status = asString(prop(goal, "status"))
if (threadId.isNullOrEmpty() || objective.isNullOrEmpty() || status.isNullOrEmpty()) return false
return status in setOf("active", "paused", "budgetLimited", "usageLimited", "blocked", "complete")
}
/** Non-empty condition of `normalizePlanEntries`. */
private fun hasPlanEntries(value: JsonElement?): Boolean {
val entries: List<JsonElement> = when {
value is JsonArray -> value
jsIsObject(value) -> sequenceOf("plan", "items", "steps")
.map { prop(value, it) }
.firstOrNull { it is JsonArray }
?.let { (it as JsonArray).toList() }
?: emptyList()
else -> emptyList()
}
return entries.any { entry ->
entry.stringOrNull != null || (
entry is JsonObject && sequenceOf("step", "content", "text", "title", "description")
.any { key -> !asString(prop(entry, key)).isNullOrEmpty() }
)
}
}
}
@@ -0,0 +1,659 @@
package app.hapi.protocol.window
import app.hapi.protocol.wire.MessagesPage
import app.hapi.protocol.wire.hasExplicitNullInvokedAt
import app.hapi.protocol.wire.stringOrNull
import kotlinx.serialization.json.JsonObject
/**
* Pure state transitions of the message window — a function-for-function port
* of `web/src/lib/message-window-store.ts` (with the async orchestration
* stripped out; `:core:data`'s `MessageWindowStore` re-adds it). Every
* function takes the previous [MessageWindowState] and returns the next one;
* nothing here touches clocks, I/O, or coroutines, so the whole surface is
* fixture-comparable.
*/
object MessageWindowLogic {
enum class TrimMode { Append, Prepend }
fun createState(sessionId: String): MessageWindowState = MessageWindowState(sessionId = sessionId)
// -------------------------------------------------------------- helpers --
/** Web `buildState`: swap the messages list, re-derive seq bounds, bump the version on identity change. */
private fun MessageWindowState.withMessages(messages: List<WindowMessage>): MessageWindowState {
if (messages === this.messages) return this
var oldestSeq: Long? = null
var newestSeq: Long? = null
for (message in messages) {
val seq = message.seq ?: continue
oldestSeq = if (oldestSeq == null) seq else minOf(oldestSeq, seq)
newestSeq = if (newestSeq == null) seq else maxOf(newestSeq, seq)
}
return copy(
messages = messages,
oldestSeq = oldestSeq,
newestSeq = newestSeq,
messagesVersion = messagesVersion + 1,
)
}
/** A row's compound position; rows without a server `seq` have none. */
fun messagePosition(message: WindowMessage): MessagePosition? {
val seq = message.seq ?: return null
return MessagePosition(at = message.positionAt, seq = seq)
}
enum class PositionEnd { Oldest, Newest }
fun derivePosition(messages: List<WindowMessage>, end: PositionEnd): MessagePosition? {
var selected: MessagePosition? = null
for (message in messages) {
val candidate = messagePosition(message) ?: continue
val current = selected
if (current == null) {
selected = candidate
continue
}
val comparison = candidate.compareTo(current)
if ((end == PositionEnd.Oldest && comparison < 0) || (end == PositionEnd.Newest && comparison > 0)) {
selected = candidate
}
}
return selected
}
/** Pairwise page cursor (`pagePosition` in the web): both halves or nothing. */
fun pagePosition(at: Long?, seq: Long?): MessagePosition? =
if (at != null && seq != null) MessagePosition(at, seq) else null
private fun maxPosition(a: MessagePosition?, b: MessagePosition?): MessagePosition? = when {
a == null -> b
b == null -> a
a >= b -> a
else -> b
}
// ---------------------------------------------------------------- trims --
private data class Trim(val kept: List<WindowMessage>, val dropped: List<WindowMessage>)
private fun sliceForTrim(items: List<WindowMessage>, limit: Int, mode: TrimMode): Trim {
if (items.size <= limit) return Trim(items, emptyList())
if (limit <= 0) return Trim(emptyList(), items)
return when (mode) {
TrimMode.Prepend -> Trim(items.subList(0, limit).toList(), items.subList(limit, items.size).toList())
TrimMode.Append -> Trim(
items.subList(items.size - limit, items.size).toList(),
items.subList(0, items.size - limit).toList(),
)
}
}
/**
* Codex background-agent trace rows (`agent-run-*`) get their own trim
* bucket so long traces do not evict chat (web `isCodexAgentRunMessage`).
*/
fun isCodexAgentRunMessage(message: WindowMessage): Boolean {
val outer = message.wire.content as? JsonObject ?: return false
if (outer["role"].stringOrNull != "agent") return false
val content = outer["content"] as? JsonObject ?: return false
if (content["type"].stringOrNull != "codex") return false
val data = content["data"] as? JsonObject ?: return false
val type = data["type"].stringOrNull
return type == "agent-run-start" || type == "agent-run-update" || type == "agent-run-trace"
}
/**
* Trim to [regularLimit] while never dropping queued rows: the regular
* budget shrinks by the queued count, `agent-run-*` rows trim against
* their own [AGENT_RUN_WINDOW_SIZE] bucket, and queued rows are re-merged
* afterwards (web `trimPreservingQueued`).
*/
private fun trimPreservingQueued(messages: List<WindowMessage>, regularLimit: Int, mode: TrimMode): Trim {
val queued = messages.filter { it.isQueuedForInvocation }
val queuedIds = queued.mapTo(HashSet()) { it.id }
val nonQueued = messages.filter { it.id !in queuedIds }
val agentRuns = nonQueued.filter { isCodexAgentRunMessage(it) }
val regular = nonQueued.filter { !isCodexAgentRunMessage(it) }
val regularTrim = sliceForTrim(regular, maxOf(0, regularLimit - queued.size), mode)
val agentRunTrim = sliceForTrim(agentRuns, AGENT_RUN_WINDOW_SIZE, mode)
return Trim(
kept = MessageMerge.mergeMessages(regularTrim.kept + agentRunTrim.kept, queued),
dropped = regularTrim.dropped + agentRunTrim.dropped,
)
}
// ------------------------------------------------------------ retention --
/** Web `shouldRetainWindowMessage`: queued, or renderable by the chat pipeline. */
fun shouldRetainWindowMessage(message: WindowMessage): Boolean =
message.isQueuedForInvocation || MessageRetention.isRenderable(message.wire.content)
/**
* How many of [incoming] would add a NEW renderable row (not already
* represented by id or localId) — feeds the `applied` older-load outcome.
*/
fun countNewRenderableMessages(previous: MessageWindowState, incoming: List<WindowMessage>): Int {
val representedIds = previous.messages.mapTo(HashSet()) { it.id }
val representedLocalIds = previous.messages.mapNotNullTo(HashSet()) { it.localId }
var count = 0
for (message in incoming) {
if (!shouldRetainWindowMessage(message)) continue
if (message.id in representedIds) continue
val localId = message.localId
if (localId != null && localId in representedLocalIds) continue
count += 1
representedIds.add(message.id)
if (localId != null) representedLocalIds.add(localId)
}
return count
}
// ---------------------------------------------------------------- merge --
/**
* Merge [incoming] into the window, trim per mode/limit, and repair
* cursors/flags on overflow (web `mergeIntoWindow`): an append-side trim
* flips `hasMore` and recomputes the older cursor from the oldest kept
* row; a prepend-side trim drops tail rows, so the window no longer
* reaches the live bottom — flag `requiresLatestReset` and pull the
* newest cursor back to the newest kept row.
*/
fun mergeIntoWindow(
previous: MessageWindowState,
incoming: List<WindowMessage>,
mode: TrimMode? = null,
regularLimit: Int? = null,
advanceTailRevision: Boolean = false,
): MessageWindowState {
val retainedIncoming = incoming.filter { shouldRetainWindowMessage(it) }
if (retainedIncoming.isEmpty()) {
return previous
}
val effectiveMode = mode
?: if (previous.viewMode == MessageViewMode.History) TrimMode.Prepend else TrimMode.Append
val effectiveLimit = regularLimit
?: if (previous.viewMode == MessageViewMode.History) HISTORY_WINDOW_SIZE else VISIBLE_WINDOW_SIZE
val merged = MessageMerge.mergeMessages(previous.messages, retainedIncoming)
val (kept, dropped) = trimPreservingQueued(merged, effectiveLimit, effectiveMode).let { it.kept to it.dropped }
var next = previous.withMessages(kept)
if (advanceTailRevision) {
next = next.copy(tailRevision = previous.tailRevision + 1)
}
if (dropped.isEmpty()) {
return next
}
if (effectiveMode == TrimMode.Append) {
val oldest = derivePosition(kept, PositionEnd.Oldest)
return next.copy(
hasMore = true,
oldestPosition = oldest ?: next.oldestPosition,
)
}
val newest = derivePosition(kept, PositionEnd.Newest)
return next.copy(
requiresLatestReset = true,
newestPosition = newest,
)
}
// -------------------------------------------------------- latest replace --
/**
* Apply a `latest` page (cold start, activation refresh, or a reset
* response). With [replaceServerRows] the page is authoritative: every
* server row captured in [requestBaseline] (by **reference**) is
* discarded, while optimistic rows and rows that changed since the
* request left (concurrent SSE) survive the swap (web
* `applyLatestResponse`).
*/
fun applyLatestResponse(
previous: MessageWindowState,
responseMessages: List<WindowMessage>,
page: MessagesPage,
replaceServerRows: Boolean,
requestBaseline: Map<String, WindowMessage>,
): MessageWindowState {
val retainedResponseMessages = responseMessages.filter { shouldRetainWindowMessage(it) }
val concurrentServerRows = previous.messages.filter { message ->
!message.isOptimistic && requestBaseline[message.id] !== message
}
val preserved = if (replaceServerRows) {
previous.messages.filter { message ->
message.isOptimistic || requestBaseline[message.id] !== message
}
} else {
previous.messages
}
val authoritative = MessageMerge.mergeMessages(preserved, retainedResponseMessages)
val incoming = MessageMerge.mergeMessages(authoritative, concurrentServerRows)
val (kept, dropped) = trimPreservingQueued(incoming, VISIBLE_WINDOW_SIZE, TrimMode.Append)
.let { it.kept to it.dropped }
val snapshotHead = pagePosition(page.snapshotHeadAt, page.snapshotHeadSeq)
?: derivePosition(responseMessages, PositionEnd.Newest)
val newestKept = derivePosition(kept, PositionEnd.Newest)
val newest = maxPosition(snapshotHead, newestKept)
val responseOldest = pagePosition(page.nextBeforeAt, page.nextBeforeSeq)
val oldest = when {
dropped.isNotEmpty() -> derivePosition(kept, PositionEnd.Oldest)
replaceServerRows -> responseOldest
else -> responseOldest ?: previous.oldestPosition
}
return previous.withMessages(kept).copy(
hasMore = page.hasMore || (!replaceServerRows && previous.hasMore) || dropped.isNotEmpty(),
epoch = page.epoch,
oldestPosition = oldest,
newestPosition = newest,
tailRevision = previous.tailRevision + 1,
requiresLatestReset = false,
isLoadingMore = if (replaceServerRows) false else previous.isLoadingMore,
olderGeneration = if (replaceServerRows) previous.olderGeneration + 1 else previous.olderGeneration,
warning = null,
)
}
// ------------------------------------------------------------ tail sync --
/**
* Web `beginTailSync`: claim a new sync generation. The older generation
* bumps too — an older-page response captured before this point must not
* commit while the tail request is in flight, or a reset can mistake it
* for concurrent SSE.
*/
fun beginTailSync(previous: MessageWindowState): MessageWindowState = previous.copy(
syncGeneration = previous.syncGeneration + 1,
olderGeneration = previous.olderGeneration + 1,
isSyncingTail = true,
isLoadingMore = false,
warning = null,
)
fun finishTailSync(previous: MessageWindowState, generation: Long, warning: String?): MessageWindowState =
if (previous.syncGeneration != generation) {
previous
} else {
previous.copy(isSyncingTail = false, warning = warning)
}
/**
* Loop body of the after-cursor catch-up (web `runTailSync` inner
* updater): merge the page, adopt its epoch, and advance the newest
* cursor to `max(current, nextAfter)` — unless a prepend-side trim just
* flagged a latest reset, in which case the cursor stays pulled back.
*/
fun applyAfterPage(
previous: MessageWindowState,
responseMessages: List<WindowMessage>,
page: MessagesPage,
nextAfter: MessagePosition?,
): MessageWindowState {
val merged = mergeIntoWindow(previous, responseMessages, advanceTailRevision = true)
if (merged.requiresLatestReset) {
return merged.copy(epoch = page.epoch, warning = null)
}
val newest = maxPosition(nextAfter, merged.newestPosition)
return merged.copy(
epoch = page.epoch,
newestPosition = newest,
warning = null,
)
}
// ------------------------------------------------------------ view mode --
/**
* Re-enter tail mode (web `enterTailMode`): trim to the visible window;
* when a history overflow flagged `requiresLatestReset`, drop epoch and
* newest cursor so the next tail sync fetches a fresh latest page.
*/
fun enterTailMode(previous: MessageWindowState): MessageWindowState {
val trim = trimPreservingQueued(previous.messages, VISIBLE_WINDOW_SIZE, TrimMode.Append)
val forceLatest = previous.requiresLatestReset
val oldest = if (trim.dropped.isNotEmpty()) {
derivePosition(trim.kept, PositionEnd.Oldest)
} else {
previous.oldestPosition
}
return previous.withMessages(trim.kept).copy(
hasMore = previous.hasMore || trim.dropped.isNotEmpty(),
viewMode = MessageViewMode.Tail,
epoch = if (forceLatest) null else previous.epoch,
oldestPosition = oldest,
newestPosition = if (forceLatest) null else previous.newestPosition,
)
}
fun setViewMode(previous: MessageWindowState, mode: MessageViewMode): MessageWindowState = when {
previous.viewMode == mode -> previous
mode == MessageViewMode.History -> previous.copy(viewMode = MessageViewMode.History)
else -> enterTailMode(previous)
}
data class Activation(val state: MessageWindowState, val requestedLatest: Boolean)
/**
* Session (re-)activation (web `activateMessageWindow`): trim back to the
* visible window, and when a usable persisted cursor exists, flag
* `preferLatestOnActivation` — another client may have advanced the
* session by many pages, so the next tail sync fetches the current tail
* first and reconciles it through the reset-preservation path.
*/
fun activate(previous: MessageWindowState): Activation {
val trim = trimPreservingQueued(previous.messages, VISIBLE_WINDOW_SIZE, TrimMode.Append)
val forceLatest = previous.requiresLatestReset
val hasUsableCursor = previous.newestPosition != null && previous.epoch != null && !forceLatest
val preferLatestOnActivation = hasUsableCursor && trim.kept.isNotEmpty()
val requestedLatest = preferLatestOnActivation && !previous.preferLatestOnActivation
val invalidateRunningSync = requestedLatest && previous.isSyncingTail
fun MessageWindowState.withActivationUpdates(): MessageWindowState {
if (!preferLatestOnActivation) return this
val flagged = copy(preferLatestOnActivation = true)
return if (invalidateRunningSync) {
flagged.copy(
syncGeneration = flagged.syncGeneration + 1,
olderGeneration = flagged.olderGeneration + 1,
)
} else {
flagged
}
}
if (
previous.viewMode == MessageViewMode.Tail
&& trim.kept.size == previous.messages.size
&& !forceLatest
) {
val state = if (preferLatestOnActivation) previous.withActivationUpdates() else previous
return Activation(state, requestedLatest)
}
val next = enterTailMode(previous)
val state = if (preferLatestOnActivation) next.withActivationUpdates() else next
return Activation(state, requestedLatest)
}
// ---------------------------------------------------------- older pages --
sealed interface OlderPrecheck {
data class Proceed(val before: MessagePosition) : OlderPrecheck
data class Stop(val reason: OlderLoadOutcome.StopReason) : OlderPrecheck
}
fun olderLoadPrecheck(state: MessageWindowState): OlderPrecheck {
val before = state.oldestPosition
if (state.isSyncingTail || state.isLoadingMore) {
return OlderPrecheck.Stop(OlderLoadOutcome.StopReason.Busy)
}
if (!state.hasMore) {
return OlderPrecheck.Stop(OlderLoadOutcome.StopReason.Exhausted)
}
if (before == null) {
return OlderPrecheck.Stop(OlderLoadOutcome.StopReason.Unavailable)
}
return OlderPrecheck.Proceed(before)
}
fun beginOlderLoad(previous: MessageWindowState, generation: Long): MessageWindowState =
previous.copy(olderGeneration = generation, isLoadingMore = true, warning = null)
/**
* An older page answered with a different epoch: every cursor is
* meaningless. Drop epoch + newest cursor and flag the latest reset; the
* caller then runs a tail sync and reports `stopped/epoch-reset`.
*/
fun applyOlderEpochMismatch(previous: MessageWindowState, generation: Long): MessageWindowState =
if (previous.olderGeneration != generation) {
previous
} else {
previous.copy(
isLoadingMore = false,
epoch = null,
newestPosition = null,
requiresLatestReset = true,
)
}
/** The `onBeforeApply` veto path: invalidate this load, keep the window. */
fun rejectOlderApply(previous: MessageWindowState): MessageWindowState = previous.copy(
olderGeneration = previous.olderGeneration + 1,
isLoadingMore = false,
warning = null,
)
fun applyOlderResponse(
previous: MessageWindowState,
responseMessages: List<WindowMessage>,
page: MessagesPage,
historyVersion: Long,
): MessageWindowState {
val merged = mergeIntoWindow(
previous,
responseMessages,
mode = TrimMode.Prepend,
regularLimit = OLDER_LOAD_WINDOW_SIZE,
)
return merged.copy(
hasMore = page.hasMore,
epoch = page.epoch,
oldestPosition = pagePosition(page.nextBeforeAt, page.nextBeforeSeq),
isLoadingMore = false,
historyVersion = historyVersion,
warning = null,
)
}
fun failOlderLoad(previous: MessageWindowState, generation: Long, warning: String): MessageWindowState =
if (previous.olderGeneration != generation) {
previous
} else {
previous.copy(isLoadingMore = false, warning = warning)
}
fun cancelOlderLoad(previous: MessageWindowState): MessageWindowState =
if (!previous.isLoadingMore) {
previous
} else {
previous.copy(
olderGeneration = previous.olderGeneration + 1,
isLoadingMore = false,
warning = null,
)
}
// ------------------------------------------------------------ live rows --
/**
* SSE `message-received` ingest (web `ingestIncomingMessages`): merge,
* then — when an epoch is cached and no reset is pending — advance the
* newest cursor past the incoming rows' positions, **including rows the
* pipeline hides**, so a later tail sync does not refetch them.
*/
fun ingestIncoming(previous: MessageWindowState, incoming: List<WindowMessage>): MessageWindowState {
if (incoming.isEmpty()) return previous
val merged = mergeIntoWindow(previous, incoming, advanceTailRevision = true)
if (merged.epoch == null || merged.requiresLatestReset) {
return merged
}
val incomingNewest = derivePosition(incoming, PositionEnd.Newest)
val currentNewest = merged.newestPosition
val newest = if (incomingNewest != null && (currentNewest == null || incomingNewest > currentNewest)) {
incomingNewest
} else {
currentNewest
}
return merged.copy(newestPosition = newest)
}
/** Optimistic append (web `appendOptimisticMessage`): never advances the newest cursor. */
fun appendOptimistic(previous: MessageWindowState, message: WindowMessage): MessageWindowState =
mergeIntoWindow(
previous,
listOf(message),
mode = if (previous.viewMode == MessageViewMode.History) TrimMode.Prepend else TrimMode.Append,
advanceTailRevision = true,
)
fun updateStatus(previous: MessageWindowState, localId: String, status: MessageStatus): MessageWindowState {
if (localId.isEmpty()) return previous
var changed = false
val messages = previous.messages.map { message ->
if (message.localId != localId || message.status == status) {
message
} else {
changed = true
message.copy(status = status)
}
}
return if (changed) previous.withMessages(messages) else previous
}
/** `message-cancelled` / optimistic DELETE removal: matches localId OR id; idempotent. */
fun removeByLocalIdOrId(previous: MessageWindowState, localId: String): MessageWindowState {
if (localId.isEmpty()) return previous
val messages = previous.messages.filter { it.localId != localId && it.id != localId }
return if (messages.size == previous.messages.size) previous else previous.withMessages(messages)
}
/**
* SSE `messages-consumed` (web `markMessagesConsumed`): stamp `invokedAt`
* and flip status to `sent` on matching rows (skip `failed`), then
* re-sort — the row moves from its enqueue position to its invocation
* position. Never advances the newest cursor.
*/
fun markConsumed(previous: MessageWindowState, localIds: List<String>, invokedAt: Long): MessageWindowState {
if (localIds.isEmpty()) return previous
val idSet = localIds.toSet()
var changed = false
val updated = previous.messages.map { message ->
val localId = message.localId
if (localId == null || localId !in idSet || message.status == MessageStatus.Failed) {
return@map message
}
val needsStatus = message.status != MessageStatus.Sent
val needsInvokedAt = message.wire.hasExplicitNullInvokedAt
if (!needsStatus && !needsInvokedAt) return@map message
changed = true
var next = message
if (needsStatus) next = next.copy(status = MessageStatus.Sent)
if (needsInvokedAt) next = next.withInvokedAt(invokedAt)
next
}
if (!changed) return previous
return previous
.withMessages(MessageMerge.mergeMessages(emptyList(), updated))
.copy(tailRevision = previous.tailRevision + 1)
}
// -------------------------------------------------- queued reconciliation --
/** Web `isQueuedReconcileCandidate`. */
private fun isQueuedReconcileCandidate(message: WindowMessage): Boolean {
if (message.localId == null || !message.isQueuedForInvocation) return false
if (!message.isOptimistic) return true
return message.status == MessageStatus.Queued || message.status == MessageStatus.Sent
}
/** Candidate localIds for the queued-state round trip, in window order. */
fun queuedReconcileCandidateLocalIds(state: MessageWindowState): List<String> {
val localIds = LinkedHashSet<String>()
for (message in state.messages) {
if (isQueuedReconcileCandidate(message)) {
localIds.add(message.localId!!)
}
}
return localIds.toList()
}
/**
* Apply the queued-state verdict (web `reconcileQueuedLocalIds`): drop
* candidates that are in neither the still-queued list nor (post
* `markConsumed`) invoked — they were deleted server-side.
*/
fun reconcileQueuedLocalIds(
previous: MessageWindowState,
candidateLocalIds: List<String>,
queuedLocalIds: List<String>,
): MessageWindowState {
if (candidateLocalIds.isEmpty()) return previous
val candidates = candidateLocalIds.toSet()
val queued = queuedLocalIds.toSet()
val messages = previous.messages.filter { message ->
val localId = message.localId
if (localId == null || localId !in candidates) return@filter true
localId in queued || !isQueuedReconcileCandidate(message)
}
return if (messages.size == previous.messages.size) previous else previous.withMessages(messages)
}
// ---------------------------------------------------------- persistence --
/** Web `shouldPersistState`. */
fun shouldPersist(state: MessageWindowState): Boolean =
state.messages.isNotEmpty()
|| state.hasMore
|| state.epoch != null
|| state.oldestPosition != null
|| state.newestPosition != null
fun toPersisted(state: MessageWindowState): PersistedMessageWindow = PersistedMessageWindow(
messages = state.messages,
hasMore = state.hasMore,
oldestPositionAt = state.oldestPosition?.at,
oldestPositionSeq = state.oldestPosition?.seq,
newestPositionAt = state.newestPosition?.at,
newestPositionSeq = state.newestPosition?.seq,
epoch = state.epoch,
)
/**
* Rebuild a state from a persisted snapshot (web `hydrateState`):
* interrupted `sending` rows restore to `queued`/`sent`, and a snapshot
* with rows but no usable cursor/epoch starts flagged for a latest reset.
*/
fun hydrate(sessionId: String, persisted: PersistedMessageWindow): MessageWindowState {
val restored = persisted.messages.map { message ->
if (message.status != MessageStatus.Sending) {
message
} else {
message.copy(
status = if (message.wire.hasExplicitNullInvokedAt) MessageStatus.Queued else MessageStatus.Sent,
)
}
}
val oldest = pagePosition(persisted.oldestPositionAt, persisted.oldestPositionSeq)
val newest = pagePosition(persisted.newestPositionAt, persisted.newestPositionSeq)
val epoch = persisted.epoch?.takeIf { it >= 0 }
return createState(sessionId)
.withMessages(MessageMerge.mergeMessages(emptyList(), restored))
.copy(
hasMore = persisted.hasMore,
oldestPosition = oldest,
newestPosition = newest,
epoch = epoch,
requiresLatestReset = persisted.messages.isNotEmpty() && (newest == null || epoch == null),
)
}
// ---------------------------------------------------------------- seed --
/**
* Seed a fresh window from another session's (web
* `seedMessageWindowFromSession`) — resume/reopen may hand back a
* different session id; the old rows render instantly while
* `requiresLatestReset` forces a fresh latest page underneath. Cursor
* epoch and newest position are NOT carried over.
*/
fun seededState(source: MessageWindowState, target: MessageWindowState): MessageWindowState =
createState(target.sessionId)
.withMessages(source.messages.toList())
.copy(
hasMore = source.hasMore,
tailRevision = source.tailRevision,
oldestPosition = source.oldestPosition,
requiresLatestReset = true,
syncGeneration = target.syncGeneration + 1,
olderGeneration = target.olderGeneration + 1,
)
}
@@ -0,0 +1,113 @@
package app.hapi.protocol.window
import kotlinx.serialization.Serializable
/**
* State machine model for one session's message window — the faithful port of
* the web reference `web/src/lib/message-window-store.ts` (its
* `InternalState`), per `docs/api/client-contract/pagination.md`. The pure
* transitions over this state live in [MessageWindowLogic]; the async
* orchestration (`:core:data` `MessageWindowStore`) drives them.
*/
/** Windowing constants — normative, from the web reference. */
const val VISIBLE_WINDOW_SIZE: Int = 400
const val HISTORY_WINDOW_SIZE: Int = 600
const val OLDER_LOAD_WINDOW_SIZE: Int = 800
const val AGENT_RUN_WINDOW_SIZE: Int = 800
const val PAGE_SIZE: Int = 200
enum class MessageViewMode(val wire: String) {
/** Following the live bottom; trims from the top. */
Tail("tail"),
/** Scrolled back; trims from the bottom and may force a latest reset. */
History("history"),
}
/**
* Compound paging position `(at, seq)` where `at = invokedAt ?? createdAt` —
* both halves always travel together (`pagination.md` "Position key").
*/
data class MessagePosition(val at: Long, val seq: Long) : Comparable<MessagePosition> {
override fun compareTo(other: MessagePosition): Int =
if (at != other.at) at.compareTo(other.at) else seq.compareTo(other.seq)
}
/** Outcome of one older-page load (`fetchOlderMessages` in the web). */
sealed interface OlderLoadOutcome {
data class Applied(
val historyVersion: Long,
val hasMore: Boolean,
val addedRenderableCount: Int,
) : OlderLoadOutcome
data class Stopped(val reason: StopReason) : OlderLoadOutcome
data class Failed(val error: Throwable) : OlderLoadOutcome
enum class StopReason(val wire: String) {
Unavailable("unavailable"),
Busy("busy"),
Invalidated("invalidated"),
EpochReset("epoch-reset"),
Exhausted("exhausted"),
}
}
/**
* The full window state. Field-for-field port of the web `InternalState`
* (public `MessageWindowState` + internal cursor/generation fields), with the
* two `(at, seq)` half-pairs folded into nullable [MessagePosition]s — the web
* only ever reads/writes them pairwise (`readPosition`).
*/
data class MessageWindowState(
val sessionId: String,
/** Window rows in position order (queued rows re-merged after each trim). */
val messages: List<WindowMessage> = emptyList(),
/** Older history exists (server flag, or rows were trimmed away). */
val hasMore: Boolean = false,
/** min/max `seq` over [messages] — derived, kept for UI parity. */
val oldestSeq: Long? = null,
val newestSeq: Long? = null,
/** Cached server epoch; null until the first page (or after invalidation). */
val epoch: Long? = null,
val isSyncingTail: Boolean = false,
val isLoadingMore: Boolean = false,
val warning: String? = null,
val viewMode: MessageViewMode = MessageViewMode.Tail,
/** Bumped whenever the [messages] list instance changes. */
val messagesVersion: Long = 0,
/** Bumped per applied older page (scroll-anchoring handle). */
val historyVersion: Long = 0,
/** Bumped on tail-side content changes (auto-scroll handle). */
val tailRevision: Long = 0,
/** Next `before` request position (web `oldestPositionAt/Seq`). */
val oldestPosition: MessagePosition? = null,
/** Next `after` request position (web `newestPositionAt/Seq`). */
val newestPosition: MessagePosition? = null,
/** Cursors are unusable — the next tail sync must fetch a fresh latest page. */
val requiresLatestReset: Boolean = false,
/** Re-activation with persisted state: fetch the current tail first. */
val preferLatestOnActivation: Boolean = false,
/** Invalidates in-flight tail syncs (compare-and-ignore). */
val syncGeneration: Long = 0,
/** Invalidates in-flight older-page loads. */
val olderGeneration: Long = 0,
)
/**
* Snapshot shape persisted per session (web `PersistedMessageWindowState`,
* storage key `hapi:message-window:v2:`): messages + cursors + epoch only —
* transient flags and counters never survive a restart.
*/
@Serializable
data class PersistedMessageWindow(
val messages: List<WindowMessage> = emptyList(),
val hasMore: Boolean = false,
val oldestPositionAt: Long? = null,
val oldestPositionSeq: Long? = null,
val newestPositionAt: Long? = null,
val newestPositionSeq: Long? = null,
val epoch: Long? = null,
)
@@ -0,0 +1,160 @@
package app.hapi.protocol.window
import app.hapi.protocol.wire.AttachmentMetadata
import app.hapi.protocol.wire.DecryptedMessage
import app.hapi.protocol.wire.OptionalField
import app.hapi.protocol.wire.hasExplicitNullInvokedAt
import app.hapi.protocol.wire.isUserMessage
import app.hapi.protocol.wire.stringOrNull
import kotlinx.serialization.KSerializer
import kotlinx.serialization.Serializable
import kotlinx.serialization.SerializationException
import kotlinx.serialization.builtins.ListSerializer
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder
import kotlinx.serialization.json.JsonDecoder
import kotlinx.serialization.json.JsonEncoder
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
/**
* Client-side send state of an optimistic user message. The web reference
* extends the wire `DecryptedMessage` with `status?: MessageStatus`
* (`web/src/types/api.ts`); the wire never carries it — servers echo rows
* without a status and the client re-attaches it during merge.
*/
enum class MessageStatus(val wire: String) {
Queued("queued"),
Sending("sending"),
Sent("sent"),
Failed("failed"),
;
companion object {
fun fromWire(value: String?): MessageStatus? = entries.firstOrNull { it.wire == value }
}
}
/**
* One row of the message window: the wire [DecryptedMessage] plus the
* client-side [status]. Mirrors the web's `DecryptedMessage & {status?}`.
*
* Identity matters: `applyLatestResponse`'s request-baseline comparison is by
* **reference** (web `!==`), so transitions must only create new instances for
* rows they actually change — which every function in this package does.
*/
@Serializable(with = WindowMessageSerializer::class)
data class WindowMessage(
val wire: DecryptedMessage,
val status: MessageStatus? = null,
) {
val id: String get() = wire.id
val seq: Long? get() = wire.seq
val localId: String? get() = wire.localId
val createdAt: Long get() = wire.createdAt
/** Position time `invokedAt ?? createdAt` (collapsed tri-state). */
val positionAt: Long get() = wire.positionAt
val invokedAtOrNull: Long? get() = wire.invokedAtOrNull
/** A row is optimistic iff it has a localId and `id === localId`. */
val isOptimistic: Boolean
get() = wire.localId != null && wire.id == wire.localId
/**
* Web `isQueuedForInvocation`: a user message whose `invokedAt` is an
* explicit `null` and whose send did not fail. Only these rows sit in the
* queued bar and survive window trims.
*/
val isQueuedForInvocation: Boolean
get() = wire.isUserMessage && wire.hasExplicitNullInvokedAt && status != MessageStatus.Failed
/** Copy with `invokedAt` stamped to an explicit number. */
fun withInvokedAt(invokedAt: Long): WindowMessage =
copy(wire = wire.copy(invokedAt = OptionalField.Present(invokedAt)))
}
fun DecryptedMessage.asWindowMessage(status: MessageStatus? = null): WindowMessage =
WindowMessage(this, status)
/**
* Serializes as the wire object plus an optional `status` key — the same
* shape the web persists (and the pagination fixtures use for op inputs).
*/
internal object WindowMessageSerializer : KSerializer<WindowMessage> {
override val descriptor: SerialDescriptor =
SerialDescriptor("app.hapi.protocol.window.WindowMessage", JsonObject.serializer().descriptor)
override fun deserialize(decoder: Decoder): WindowMessage {
val input = decoder as? JsonDecoder
?: throw SerializationException("WindowMessage supports JSON only")
val obj = input.decodeJsonElement() as? JsonObject
?: throw SerializationException("WindowMessage must be a JSON object")
return WindowMessage(
wire = input.json.decodeFromJsonElement(DecryptedMessage.serializer(), obj),
status = MessageStatus.fromWire(obj["status"].stringOrNull),
)
}
override fun serialize(encoder: Encoder, value: WindowMessage) {
val output = encoder as? JsonEncoder
?: throw SerializationException("WindowMessage supports JSON only")
val wireObject = output.json.encodeToJsonElement(DecryptedMessage.serializer(), value.wire) as JsonObject
output.encodeJsonElement(buildJsonObject {
wireObject.forEach { (key, element) -> put(key, element) }
value.status?.let { put("status", JsonPrimitive(it.wire)) }
})
}
}
/**
* Builds the optimistic row appended on send, mirroring
* `createOptimisticMessage` in `web/src/hooks/mutations/useSendMessage.ts`
* and the contract's "Optimistic sends" lifecycle: `id = localId`,
* `seq = null`, explicit `invokedAt: null` (so the strict-null queued check
* matches), content `{role:'user', content:{type:'text', text, attachments?},
* meta:{deliveryMode}}`.
*/
fun buildOptimisticMessage(
localId: String,
text: String,
createdAt: Long,
attachments: List<AttachmentMetadata>? = null,
scheduledAt: Long? = null,
deliveryMode: String = "queue",
status: MessageStatus = MessageStatus.Sending,
): WindowMessage {
val content = buildJsonObject {
put("role", "user")
put("content", buildJsonObject {
put("type", "text")
put("text", text)
if (attachments != null) {
put(
"attachments",
app.hapi.protocol.wire.HapiJson.encodeToJsonElement(
ListSerializer(AttachmentMetadata.serializer()),
attachments,
),
)
}
})
put("meta", buildJsonObject { put("deliveryMode", deliveryMode) })
}
return WindowMessage(
wire = DecryptedMessage(
id = localId,
seq = null,
localId = localId,
content = content,
createdAt = createdAt,
invokedAt = OptionalField.Present(null),
scheduledAt = scheduledAt,
),
status = status,
)
}
@@ -0,0 +1,23 @@
package app.hapi.protocol.wire
/**
* Wire-level message predicates shared by the window state machine and (later)
* the chat pipeline. Ported from `web/src/lib/messages.ts`.
*/
/**
* `true` when [DecryptedMessage.content] is a role-wrapped envelope with
* `role: "user"` (web `isUserMessage`). Arrays and primitives have no `role`
* key and are not user messages.
*/
val DecryptedMessage.isUserMessage: Boolean
get() = content.objOrNull?.get("role").stringOrNull == "user"
/**
* `true` when `invokedAt` is an **explicit** wire `null` — the strict-null
* half of the queued predicate (`docs/api/client-contract/pagination.md`
* "Queued semantics"). An absent field (pre-V8 hubs) means already-invoked
* and returns `false`.
*/
val DecryptedMessage.hasExplicitNullInvokedAt: Boolean
get() = invokedAt is OptionalField.Present && invokedAt.value == null
@@ -0,0 +1,121 @@
package app.hapi.protocol.window
import app.hapi.protocol.wire.DecryptedMessage
import app.hapi.protocol.wire.OptionalField
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertTrue
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
/**
* Merge/retention edges the pagination fixtures deliberately avoid: full
* position ties (the fixtures keep every `(at, seq)` pair distinct so the
* web's `localeCompare` never decides an order — natives pin ASCII), the 10s
* no-echo dedup fallback, invokedAt preservation across a stale refetch, and
* the skippable/codex retention predicate.
*/
class MessageMergeTest {
private fun userRow(
id: String,
createdAt: Long,
localId: String? = null,
seq: Long? = null,
invokedAt: OptionalField<Long?> = OptionalField.Present(null),
status: MessageStatus? = null,
): WindowMessage = WindowMessage(
wire = DecryptedMessage(
id = id,
seq = seq,
localId = localId,
createdAt = createdAt,
invokedAt = invokedAt,
content = buildJsonObject {
put("role", "user")
put("content", buildJsonObject {
put("type", "text")
put("text", id)
})
},
),
status = status,
)
@Test
fun `full position ties break by ASCII id comparison`() {
// 'B' (0x42) sorts before 'a' (0x61) in ASCII; locale-aware collation
// (the web's localeCompare) would typically order them the other way.
val rows = listOf(
userRow("row-a", createdAt = 1000),
userRow("row-B", createdAt = 1000),
)
val merged = MessageMerge.mergeMessages(emptyList(), rows)
assertEquals(listOf("row-B", "row-a"), merged.map { it.id })
}
@Test
fun `an optimistic sent row is dropped when a server user row lands within ten seconds`() {
val optimistic = userRow(
"local-1",
createdAt = 10_000,
localId = "local-1",
status = MessageStatus.Sent,
)
// Server row WITHOUT a localId echo, 9 999 ms away by position.
val server = userRow("srv-9", createdAt = 19_999, seq = 9, invokedAt = OptionalField.Absent)
val merged = MessageMerge.mergeMessages(listOf(optimistic), listOf(server))
assertEquals(listOf("srv-9"), merged.map { it.id })
// At exactly 10 000 ms the fallback does not fire.
val far = userRow("srv-far", createdAt = 20_000, seq = 10, invokedAt = OptionalField.Absent)
val kept = MessageMerge.mergeMessages(listOf(optimistic), listOf(far))
assertEquals(listOf("local-1", "srv-far"), kept.map { it.id })
}
@Test
fun `a locally-known invokedAt survives a stale refetch of the same row`() {
val stamped = userRow("srv-1", createdAt = 1000, seq = 1, invokedAt = OptionalField.Present(5000))
val stale = userRow("srv-1", createdAt = 1000, seq = 1, invokedAt = OptionalField.Present(null))
val merged = MessageMerge.mergeMessages(listOf(stamped), listOf(stale))
assertEquals(5000L, merged.single().invokedAtOrNull)
}
@Test
fun `retention hides skippable output and unrenderable codex payloads only`() {
fun agentContent(inner: kotlinx.serialization.json.JsonObject) = buildJsonObject {
put("role", "agent")
put("content", inner)
}
// Meta system output — hidden.
assertTrue(
!MessageRetention.isRenderable(agentContent(buildJsonObject {
put("type", "output")
put("data", buildJsonObject {
put("type", "system")
put("isMeta", true)
})
}))
)
// codex row with no message payload — hidden.
assertTrue(
!MessageRetention.isRenderable(agentContent(buildJsonObject {
put("type", "codex")
put("data", buildJsonObject { put("type", "unknown-kind") })
}))
)
// codex text message — renderable.
assertTrue(
MessageRetention.isRenderable(agentContent(buildJsonObject {
put("type", "codex")
put("data", buildJsonObject {
put("type", "message")
put("message", "hi")
})
}))
)
// Unparseable envelope falls back to a stringify bubble — renderable.
assertTrue(MessageRetention.isRenderable(buildJsonObject { put("whatever", 1) }))
}
}