mirror of
https://github.com/wu736139669/hapi.git
synced 2026-11-17 03:20:40 +00:00
merge: B-M2c Android message window store, pagination fixtures green
This commit is contained in:
@@ -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) }))
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user