# v0.32.0 Release Notes

> v0.31.1 -> v0.32.0

## Summary

Session history moves send time and sender out of message text into structured fields, with one-way on-read migration from legacy prefixes. Runtime and store paths follow the new shape end to end. **Do not downgrade after upgrading** — written history is not backward-compatible with older readers.

<details>
<summary>翻譯</summary>

會話歷史將傳送時間與傳送者從訊息本文改為結構化欄位，並在讀取時單向遷移舊式標頭。執行與儲存路徑全面對齊新結構。**升級後請勿降版**——寫入後的歷史與舊版讀取器不相容。

</details>

## ⚠️ Breaking Changes

### History storage shape changed (structured `sendAt` / `sender`)

Message metadata is no longer embedded as text headers in `content`. History now uses a dedicated record shape with structured fields, and SQLite rows gain a `sender` column. On load, legacy text prefixes and blocks are stripped and lifted into fields; new writes only use the structured form.

**Do not downgrade after upgrading.** Once sessions have been opened or written under this release, on-disk history (JSON + SQLite) may lack the old in-content headers. Rolling back to a pre-v0.32.0 binary can lose or misread send time / sender and may fail against the migrated schema.

**Before (conceptual):**

```text
content: "sendAt: 2026-08-12 04:13:01\nsender: alice\n\nhello"
// or legacy Chinese header blocks inside content
```

**After (conceptual):**

```go
type Record struct {
    Role    string `json:"role"`
    Content any    `json:"content"` // body only; no metadata header
    SendAt  int64  `json:"sendAt,omitempty"`
    Sender  string `json:"sender,omitempty"`
}
```

**Migration:**

1. Upgrade fully to v0.32.0+; do not mix old and new binaries against the same history store.
2. No manual rewrite required for normal use: first read normalizes legacy prefixes into `sendAt` / `sender` and strips them from content.
3. **Do not downgrade** after any session has been loaded or saved on v0.32.0+. If you must roll back, restore history files and the SQLite DB from a pre-upgrade backup taken before first open on this version.
4. Call sites that assumed metadata lived only inside `content` text must use the structured fields (or the prefix rebuilt only when building provider messages).
5. Treat the change as one-way for production data; plan backups before upgrade if downgrade must remain an option.

<details>
<summary>翻譯</summary>

### 歷史儲存結構變更（結構化 `sendAt` / `sender`）

訊息 metadata 不再以文字標頭嵌在 `content` 內。歷史改為專用 record，含結構化欄位；SQLite 列新增 `sender`。讀取時會剝除舊式文字標頭／區塊並提升為欄位；新寫入只走結構化形態。

**升級後請勿降版。** 一旦在本版開啟或寫入 session，磁碟上的歷史（JSON + SQLite）可能已沒有舊的 content 內標頭。退回 v0.32.0 之前的二進位可能遺失或誤讀時間／傳送者，並可能與已遷移 schema 不相容。

**遷移：**

1. 完整升級至 v0.32.0+；同一 history store 勿混用新舊二進位。
2. 一般使用無需手動改寫：首次讀取會將舊標頭正規化進 `sendAt` / `sender` 並自 content 剝除。
3. **任何 session 在 v0.32.0+ 載入或儲存後請勿降版。** 若必須回滾，請還原升級前、首次開啟前的 history 與 SQLite 備份。
4. 若程式假設 metadata 只存在於 `content` 文字，需改讀結構化欄位（或僅在組 provider message 時重建 prefix）。
5. 正式環境視此為單向變更；若仍需保留降版選項，升級前先備份。

</details>

## Changes

### BREAKING

- Store sendAt/sender as structured history fields, drop text headers (@pardnchiu) [76c4ffce]

<details>
<summary>翻譯</summary>

- 將 sendAt／sender 改為結構化歷史欄位，移除文字標頭

</details>

### UPDATE

- Wire Discord, Telegram, TUI, and HTTP handlers through the new history record path (@pardnchiu) [76c4ffce]
- Align compaction, summary, and conversation-search with structured metadata (@pardnchiu) [76c4ffce]

<details>
<summary>翻譯</summary>

- 讓 Discord、Telegram、TUI 與 HTTP handler 走新歷史 record 路徑
- 對齊壓縮、摘要與對話搜尋至結構化 metadata

</details>

## Scope

- `internal/session/history/` — BREAKING, ADD, UPDATE (`record.go`, store, compact, replace)
- `internal/agents/exec/` — UPDATE (save, stream, summary, session load)
- `internal/runtime/` — UPDATE (discord, telegram, tui, routes)
- `internal/tools/` — UPDATE (`searchConversationHistory.go`)
- `configs/prompts/system_prompt/` — UPDATE

***

Generated by [SKILL](https://github.com/pardnchiu/skill-version-generate)