v0.3.4

What's Changed

🔄 Context Compression Refactoring

核心改进：重构上下文加载机制，使用摘要边界替代固定限制，确保上下文始终从有效的结构点（摘要或首条消息）开始加载。

主要变更

• Session 模型增强：新增 LatestSummaryOffset 字段，追踪最新的摘要边界位置
• 消息仓库优化：ListBySessionBeforeOffset 支持 minOffset 参数，实现精确的范围查询
• ForkSession 改进：使用 LatestSummaryOffset 作为上下文起点，替代原有的 limit 参数，避免从对话中间开始导致的结构问题
• 压缩流程完善：压缩完成后自动持久化摘要偏移量，确保下次加载从正确位置开始
• 消息规范化：为压缩路径添加 normalizeSchemaMessagesForLLM，保证压缩后的消息符合 Anthropic Messages API 规范（系统消息在前、工具调用配对正确等）

解决的问题

• 修复了"第一条非系统消息是 assistant"的 bug
• 确保压缩/分叉后的上下文始终满足 LLM API 的结构要求
• 消除了使用固定 limit 可能导致的上下文不完整问题

📝 配置优化

• 更新 context_tokens_limit、auto_compact_buffer_tokens 等配置的默认值和注释
• 为 max_tokens 配置项添加清晰的注释说明

📊 变更统计

• 27 个文件变更
• 579 行新增
• 183 行删除

Commits

• 40a5749 refactor(agent): use summary boundaries for context loading
• 6985543 docs(config): add clarifying comment for max_tokens

升级说明

此版本包含数据库模型变更（Session 表新增 latest_summary_offset 字段）。升级后：

• 现有会话的 LatestSummaryOffset 默认为 0，表示尚无摘要
• 下次上下文压缩时会自动填充该字段
• 无需手动迁移数据

v0.3.2

Release v0.3.2

This is a major release introducing S3-compatible object storage (OSS3), a complete admin management system, enhanced RTC user management, and comprehensive observability improvements.

🚀 Major Features

OSS3 - S3-Compatible Object Storage

• MinIO Integration: Full MinIO backend implementation with storage quota, rate limiting, and encryption
• S3 Protocol: Complete S3 protocol implementation including SigV4 signature verification (AWS SDK)
• Multipart Upload: Transaction-based multipart upload with compensation logic
• Business Logic: Data access layer, business logic layer, and storage backend interface
• Middleware: Business restriction, CORS, access log, and rate limiting middleware
• Observability: Comprehensive metrics, tracing, and logging for storage operations
• Security: SecretAccessKey encryption at rest, credential cache fixes, and security hardening

Admin Server - Complete Management System

• Authentication: JWT signing/verification, JWKS client, and RFC 8693 Token Exchange
• RBAC System: Role, permission, and user-role management with Casbin integration
• Security: Deny-by-default policy, O(1) lookup, ILIKE injection prevention
• User Management: RTC user management with distributed ban sync and audit logging
• Admin APIs: User list with pagination, session/message queries, device tracking
• Email OTP: Email-based one-time password login for admin authentication
• Dynamic Config: Per-user configuration overrides with ConfigProvider abstraction
• Monitoring Integration: Reverse proxies for Prometheus, Grafana, Jaeger, and Pyroscope

RTC User Management

• Distributed Ban Sync: Real-time ban synchronization across server instances via Redis
• Audit Logging: Comprehensive audit trails for all user management operations
• Ban Cache: Migrate from in-memory to Redis for distributed consistency
• Real-time Check: Real-time ban status verification for user operations

Metrics & Observability

• Database Metrics: Prometheus metrics for GORM queries with error tracking
• WebSocket Metrics: Centrifuge connection and lifecycle metrics
• Queue Metrics: Asynq queue lifecycle and auth failure metrics
• Circuit Breaker: State change metrics for circuit breaker patterns
• Business Events: Session and message business event metrics
• Alerts: Comprehensive Prometheus alert rules for all new metrics
• Dashboards: Grafana dashboard panels for visualization
• Tracing: Standardized span names and improved trace context propagation

Agent Enhancements

• File Attachments: Load file attachments (images/text) from OSS for user messages
• Parallel Loading: Parallel file loading with optimized MultiContent merge
• Performance: Pre-parse ContentData and cache ownerRefID

🔒 Security Enhancements

• JWT Key Management: Automatic JWT key generation and rotation support
• Secret Encryption: Encrypt SecretAccessKey at rest in database
• Trusted Proxy: Add trusted proxy support with audit logging
• Endpoint Protection: Enforce authentication for metrics and debug endpoints in production
• Cookie Security: Add Secure flag and unify error messages
• Redis Atomicity: Fix rate limiter and login protection atomicity issues
• CORS Hardening: Strengthen CORS configuration and HTTP timeouts
• Casbin Security: Deny-by-default policy with O(1) permission lookup
• ILIKE Injection: Prevent SQL injection in ban operations
• Weak Secret Detection: Reject weak JWT secrets in production environment

🐛 Bug Fixes

Critical Fixes

• Concurrent Map Writes: Prevent concurrent map writes in message Extra field
• Transaction Support: Fix transaction support and error handling in OSS3 repos
• SigV4 Verification: Rewrite SigV4 verification using AWS SDK
• Pagination Loop: Fix integration test pagination infinite loop
• Graceful Shutdown: Improve server graceful shutdown and security

Infrastructure

• Metrics Cardinality: Fix cardinality explosion, zero latency, and missing rate limit metrics
• SSE Stream: Fix unbounded buffer memory issue in SSE streams
• Domain Limiter: Add domain limiter cap to prevent memory leaks in webfetch
• Route Conflicts: Resolve gin route wildcard conflicts
• Error Mapping: Correct error mapping for insufficient storage

Configuration

• Redundant Queries: Eliminate redundant queries and improve transaction safety
• Dynamic Config: Resolve 6 P2 issues in dynamic config system
• Permission Bootstrap: Fix server_config permissions missing after bootstrap

Code Quality

• Panic Replacement: Replace panics with error returns and unify logging
• Depguard: Enforce facade pattern consistency and strengthen depguard rules
• Layered Architecture: Enforce layered architecture and eliminate code duplication
• Structured Logging: Normalize log event names and use structured logging

🔧 Refactoring & Improvements

Architecture

• Admin Restructure: Restructure middleware, models, and usecases for better maintainability
• Wire Consolidation: Consolidate asynq Redis configuration
• Handler Decoupling: Decouple handlers from ServiceContext
• Usecase Extraction: Extract AuthUsecase with PKCE support
• Error Codes: Extract error codes to constants

Code Quality

• Comprehensive Improvements: 32+ code quality improvements across review findings
• Redundant Parsing: Eliminate redundant parsing and struct duplication
• Race Detection: Enable race detection and coverage reporting in CI
• Test Coverage: Expand test coverage across multiple modules

Configuration

• Environment Validation: Add environment validation and example configuration
• Config Templates: Sync config templates with recent code changes
• Docker Config: Add token_exchange to config.docker.yaml

Build System

• Admin UI Artifacts: Commit admin UI build artifacts for CI compatibility
• Pre-commit Hook: Update large file detection to allow admin UI artifacts

📊 Statistics

• 161 commits since v0.2.2
• Major features: 6 (OSS3, Admin Server, RTC User Management, Dynamic Config, Metrics, Security)
• Security fixes: 10+
• Bug fixes: 30+
• Refactoring: 15+

⚠️ Breaking Changes

• Model Names: User → AdminUser, Role → AdminRole
• Config Removed: features.permission_system (now always enabled)
• JWT Secret: Weak JWT secrets rejected in production
• Metrics Endpoints: Require authentication in production

📦 Dependencies

• MinIO: Add minio-go/v7 for S3-compatible storage
• AWS SDK: Use AWS SDK for SigV4 signature verification
• Casbin: Integrated for RBAC permission system
• Backoff: Use cenkalti/backoff for quota commit retry

🔒 Security Notes

This release includes extensive security hardening:

• OSS3: SecretAccessKey encryption, credential cache fixes, SigV4 verification
• Admin: JWT key management, trusted proxy support, Casbin deny-by-default
• Infrastructure: Endpoint authentication, cookie security, Redis atomicity
• Network: CORS hardening, ILIKE injection prevention, trusted proxy audit logging

Recommendation: Review and update your configuration files with the new security settings before deploying.

---

Full Changelog: v0.2.2...v0.3.2

v0.3.2-rc.0

Release v0.3.2-rc.0

This release introduces major security and administrative enhancements, including a complete RBAC system, RTC user management, dynamic configuration, and comprehensive monitoring integration.

🚀 Features

RBAC & Permissions

• Role-Based Access Control: Complete RBAC implementation with role, permission, and user-role management
• Casbin Integration: Integrated Casbin RBAC permission system with security hardening
• Security Enhancements: Deny-by-default policy, O(1) lookup optimization, and ILIKE injection prevention
• Self-Service Permissions: Bypass Casbin for self-service profile updates

User Management

• RTC User Management: Add comprehensive RTC user management with distributed ban sync
• Audit Logging: Real-time audit logging for all user management operations
• Ban Status Cache: Migrate ban cache from in-memory to Redis for distributed consistency
• Real-time Ban Check: Implement real-time ban check for user management operations

Dynamic Configuration

• Config System: Add dynamic configuration system with per-user overrides
• ConfigProvider: Add ConfigProvider abstraction and force-overwrite support
• Performance: Eliminate redundant queries and improve transaction safety
• Issue Resolution: Resolve 6 P2 issues in dynamic config system

Admin APIs

• User Management: Add /api/users endpoint with pagination support
• Session & Message: Add session and message query APIs with device tracking
• Email OTP: Add email OTP login for admin authentication

Monitoring & Observability

• Prometheus Integration: Add Prometheus reverse proxy with iframe embedding support
• Grafana Integration: Add Grafana reverse proxy for metrics visualization
• Tracing: Add Jaeger reverse proxy for distributed tracing
• Profiling: Add Pyroscope reverse proxy for continuous profiling

🐛 Bug Fixes

Security

• ILIKE Injection: Prevent ILIKE injection attacks in ban operations
• Casbin Hardening: Harden Casbin middleware with deny-by-default and O(1) lookup
• Cookie Security: Add cookie Secure flag and unify error messages to English
• Redis Atomicity: Fix Redis atomicity and context propagation in rate limiter and login protection
• CORS & Timeouts: Harden CORS configuration and HTTP timeouts in degraded mode

Core Systems

• Ban Watcher: Prevent nested listen calls in reconnection loop
• Route Conflicts: Resolve gin route wildcard conflict between rtc-users routes
• Permission Bootstrap: Fix server_config permissions missing after bootstrap
• Policy Counting: Correct bootstrap policy count comments for accuracy
• Route Mapping: Fix Casbin route mapping and Prometheus alert dimension issues

Infrastructure

• Database Metrics: Exclude ErrRecordNotFound from database error metrics
• Config Queries: Eliminate redundant queries and improve transaction safety
• Depguard: Resolve depguard violations and add AuditLogFilter to model

🔧 Refactoring & Improvements

• Model Naming: Rename User/Role to AdminUser/AdminRole for clarity
• Code Structure: Restructure middleware, models, and usecases for better maintainability
• Config Cleanup: Remove deprecated features.permission_system config
• Error Handling: Improve error handling and context propagation
• Build System: Commit admin UI build artifacts for CI compatibility

📊 Statistics

• 31 commits since v0.3.1-rc.0
• 14 features added
• 12 bug fixes resolved
• 6 refactoring improvements

⚠️ Breaking Changes

• Model names changed: User → AdminUser, Role → AdminRole
• Removed config key: features.permission_system (now always enabled)

🔒 Security Notes

This release includes multiple security hardening measures:

• Casbin middleware now uses deny-by-default policy
• ILIKE injection prevention in ban operations
• Cookie Secure flag enforcement
• Redis rate limiter atomicity improvements
• CORS configuration hardening

---

Full Changelog: v0.3.1-rc.0...v0.3.2-rc.0

v0.3.1-rc.0

Changes

Bug Fixes

• Unified error response format: Return HTTP 200 for all responses (including errors) so frontend response interceptors can properly handle error cases

Details

• Frontend now checks success=false and errorCode to determine error types instead of relying on HTTP status codes
• Login handler now uses Success() wrapper for consistency
• Error() function updated to always return 200 with structured error body

Related

• Required by: rtc-agent/web-components v0.3.1-rc.0

v0.3.0-rc.0

What's Changed

🚀 New Features

S3-Compatible Storage (OSS3)

• Complete S3 protocol implementation with full observability and monitoring
• Multipart upload support for large files (1E-4)
• SigV4 signature verification with AWS SDK integration
• CORS middleware for cross-origin requests
• Business restriction middleware with content-type validation
• Transaction boundary and compensation for atomic operations
• Access log middleware with structured logging
• MinIO backend integration with comprehensive test coverage

File Attachments for Agent

• Load file attachments from OSS in user messages (images and text files)
• Parallel file loading for improved performance with multiple attachments
• MultiContent merge for consecutive user messages with images
• Image preprocessing pipeline: format detection, resizing, quality degradation
• Text file support with UTF-8 validation and truncation for large files
• UserID propagation through context for background worker processing

🔧 Improvements

Code Quality

• Comprehensive code quality improvements across 32+ review findings
• Eliminated redundant parsing and struct duplication
• Improved error handling and transaction support in repositories
• Enhanced SigV4 signature verification with proper credential caching

Testing

• Added comprehensive test coverage for file attachments and message conversion
• MinIO backend integration tests
• S3 protocol layer integration test scaffolding
• Edge case tests for security and error handling

🐛 Bug Fixes

Critical Security

• Resolved critical security issues in OSS3 protocol implementation
• Fixed SigV4 signature verification vulnerabilities
• Corrected error mapping for insufficient storage scenarios

Integration

• Fixed transaction support and error handling in OSS3 repositories
• Resolved review findings from comprehensive S3 protocol audit
• Fixed pagination infinite loop in integration tests
• Corrected user ID handling in integration tests

📝 Documentation

• Added comprehensive testing guide for OSS3
• Enhanced code comments and API documentation

🔄 Breaking Changes

None - this is a backward-compatible release.

New Contributors

This release includes significant contributions from code review findings and comprehensive testing efforts.

Full Changelog: v0.2.2...v0.3.0-rc.0

v0.2.2

What's Changed

🚀 Features

• Web Search Tool: Add web search tool with multi-provider support (Tavily, Bing, DuckDuckGo, SearXNG)
• Web Fetch Tool: Add web fetch tool for page content extraction with LLM-powered summarization

♻️ Refactoring

• Memory System Unification: Unify SessionMemory and UserMemory into a single OKF Memory model
• Memory Tool Renaming: Rename user memory tools to memory (saveUserMemory → saveMemory, etc.) and remove separate session memory concept
• WebFetch/WebSearch Consolidation: Consolidate submodules into main module, extract shared circuit breaker and proxy packages
• WebFetch Extractor: Move LLM extractor to agent layer and add tests
• WebSearch: Inline tool implementation and add thread-safety

⚡ Performance

• Memory Search: Change memory search to word-level OR matching for better recall
• Memory Search SQL: Wrap word conditions in parentheses for correct SQL precedence

🐛 Bug Fixes

• Memory Exporter: Use UTC time for bundle name timestamp for cross-timezone consistency
• Memory Agent: Get user ID directly from session instead of extra DB lookup

📝 Documentation

• Agent Prompts: Clarify script tool purpose and usage

v0.2.1

Release v0.2.1

🚀 Features

• cache-analyzer: Add cache analysis tool with system prompt extraction and enhanced diff reporting
• cache-analyzer, turn-agent: Add cache analysis tool and merge assistant middleware
• observability: Add OpenTelemetry tracing and structured logging across server
• agent: Implement prompt message persistence and static tool registration

🔧 Fixes

• handler/rpc: Set user message streaming status to completed on creation
• eino-agent: Normalize empty/null tool arguments before execution
• protocol: Update generated model comments to match actual behavior
• agent, turn-agent: Resolve message structure mismatch and tool result duplication
• agent: Normalize empty tool arguments to prevent cache invalidation
• agent: Persist tool parse errors to DB for cache consistency
• agent: Read tool output from message table on RTC resume
• rpc: Compact JSON result to preserve key order
• cache-analyzer: Remove duplicate template loading
• agent: Fix prompt injection order and tool_calls merge
• rtc-queue: Prevent distributed lock race with credential-aware ReleaseSession
• rtc-queue, turn-agent: Add trace context to all worker and turn-agent logs
• agent: Reload messages on checkpoint resume and improve sub-agent notification
• loop: Start completed_turns at 0 for accurate counting
• loop: Fix stale history, cross-instance tool loss, and missing tool logs

🔄 Refactoring

• agent: Reorganize prompt system and add edit tool
• agent: Move TodoList from attachment to tool_result persistence
• agent, cache-analyzer: Improve workflow and diff report formatting
• turn-agent: Normalize tool call ordering for cache consistency
• cache-analyzer: Use go:embed for HTML templates
• agent: Return friendly text instead of JSON from createLoop tool
• agent: Rename tools to camelCase and add sendMessageToSubAgent
• loop: Simplify scheduling with idempotent task IDs and fix distributed OnTurnComplete
• agent: Extract toolName helper to eliminate redundant Info() calls

🧪 Testing

• agent: Add comprehensive tests and fix nil tracer panic

🎨 Style

• agent: Fix gofmt alignment in microcompact_extra_test.go

📦 Chores

• reviews: Move review reports to .claude repo

---

Full Changelog: v0.2.0...v0.2.1

v0.2.0 — 稳定性、可观测性与基础设施全面升级

v0.2.0 — 稳定性、可观测性与基础设施全面升级

自 v0.1.1-rc.0 以来,本版本包含 206 次提交(18 项新特性、90 项修复、54 项重构、27 项文档改进、6 项测试增强、1 项性能优化),是 RTC Agent Server 迄今为止内容最丰富的一次发布。

✨ 新特性

会话与生命周期

• OpenSession RPC:新增独立 RPC 接口,改进内存管理与超时处理
• Turn 恢复机制:支持服务器重启后的 stale turn 恢复与 checkpoint 续跑
• 周期性 stale turn 扫描器:基于分布式锁的后台巡检,自动回收卡住的 turn
• 防御性消息归一化器:确保 LLM API 合规,防止异常消息序列导致崩溃

循环任务(Loop)系统

• Loop 命令:支持周期性任务执行
• Asynq 后台任务系统:基于 Redis 的可靠任务调度,支持重试、监控与仪表板

OAuth 认证

• GitHub & Google OAuth2:完整实现两大第三方 OAuth2 提供商接入

内存与记忆

• 统一内存基础设施(pkg/memory):解耦 pkg/memory 与 internal/model
• OKF 导出 API:HTTP 接口导出记忆数据
• 基于 Tool Calling 的记忆抽取:替代原有 embedding 语义搜索

Token 与成本

• Token 用量追踪与预估:集成 tiktoken-go,支持可配置计数
• Token 成本计算:为每次 turn 提供成本核算

可观测性与监控

• 战略缓存断点(Cache Breakpoints):保护稳定内容,提升缓存命中率
• Debug 端点与 goroutine 监控:新增调试接口与 goroutine 泄漏检测
• HTTP 指标中间件:跳过 WebSocket 升级请求的精准度量
• 错误反馈告警与仪表板:Phase 8 监控体系完整落地
• 用户可见错误反馈:turn 失败时向用户插入可读错误消息
• 脚本执行异步记录器:带指标与仪表板的执行追踪

消息与内容

• user_message 内容类型:支持场景化注入
• 批量中断支持:一次操作中断多个 turn

基础设施

• 配置校验、生命周期管理器、限流器与安全加固:一站式基础能力
• 服务器重启恢复与 checkpoint 续跑:生产环境高可用保障

🐛 关键修复

并发与数据一致性 (P0/P1)

• 修复 turn 生命周期、流式传输与错误处理中的 4 个关键 bug
• 修复 split-brain 问题、互斥锁死锁、定时器泄漏
• 修复 RTC-queue 数据竞争、内存泄漏
• 修复 Redis Pub/Sub 竞态导致的 StopTurn 取消信号丢失
• 修复 toolcall_output 数据丢失的拆分事务问题
• 修复 cascade 取消子 agent 时的 goroutine 泄漏
• 修复 DB 操作与已取消 callback 上下文的耦合

上下文与生命周期

• 将 fire-and-forget callback 从已取消的调用方上下文解耦
• 将关键 DB 操作隔离于已取消的 callback 上下文之外
• 修复 context timeout 在 goroutine 内过早取消的问题
• 修复 compact 操作与父 context 生命周期耦合
• 修复 Start 与 Stop 并发执行问题

流式与消息处理

• 修复 thinking-only stream finalization 的 token usage 丢失
• 修复 appendStreamChunk 失败时的 markdown 消息 finalize
• 修复 streaming fallback 中 ContentData 结构破坏
• 修复 streamState 在 markdown 追加失败时的清理
• 修复 UTF-8 安全截断(thinking concat、memory extractor 等多处)

分布式安全

• 修复 sub-agent 通知的 session 加载失败回滚
• 修复 batch resume 中 SRem 返回值误用
• 修复 reactive compact escalation 跨 Process 重启
• 修复 Redis 原子性与错误处理

错误处理与日志

• 消除恢复与清理路径中的 error swallowing
• 修复 sanitizer 规则对 IPv6 与 token 误报
• 修复 panic recovery 堆栈追踪与 sub-agent 通知缺口
• 统一日志字段排序与命名常量替换 magic string

🔧 代码质量

重构

• 500 行合规:拆分所有超限文件(9+ 个超过 500 行的文件)
• 循环复杂度降低:使用 cenkalti/backoff 替代手写指数退避;提取大量 helper 函数
• 重复消除:提取 extractSessionIDFromContext、notifyParentAndCascadeCancel、publishLifecycleFallback 等共享逻辑
• Magic number/ string 替换:优先级常量、typed constants、Redis key prefix 命名化
• 日志规范化:NoopLogger 替代 logIfEnabled 反模式;统一 log fields 排序

类型安全与测试

• 新增 lifecycle Manager 测试(覆盖率 0% → 97.5%)
• 新增 agent、loop、updates 包单元测试
• 修复测试 helper 未使用参数

性能

• 预分配 slice 减少分配开销

📚 文档

• 中文注释英文化:完成 27 次专项文档提交,覆盖 oauth、centrifuge-plus、updates、logger、repo、config、cache、memory、infra、cmd、handler、rtc-queue、eino-agent、turn-agent 等所有内部包
• API 注释完善:澄清 sub_agent resume 状态检查、token usage 语义、stream TTL 默认值等

🙏 致谢

本次发布涉及整个服务端代码库的系统性加固,感谢所有参与代码评审、bug 复现与压测的贡献者。v0.2.0 为后续的 RTC 协议演进与多 agent 协作奠定了坚实的工程基础。

---

Full Changelog: v0.1.1-rc.0...v0.2.0

v0.1.1-rc.0

Release v0.1.1-rc.0 (Release Candidate)

新增功能

• ✨ 添加 pre-push hook，推送前自动运行单元测试
• 🔧 增强 CI workflow，添加 golangci-lint (v2.13.2) 和单元测试步骤
• 🐳 Docker publish workflow 支持 release 触发和智能 tag 逻辑

Docker 镜像

• ghcr.io/rtc-agent/server:v0.1.1-rc.0
• ghcr.io/rtc-agent/server:<commit-sha>

注意：RC 版本不会覆盖 latest tag