server/agui: preserve read-hook policy for persisted track history

[Rememorio]

Background

PR #2349 adds direct persisted track-history reads for session backends. In AG-UI, tracker.GetEvents prefers the optional GetTrackEvents capability and falls back to Service.GetSession only when that capability is absent.

This changes the hook path: the direct reader does not run the backend GetSessionHook chain, while the fallback path does. Hooks that validate or rewrite keys and options, enforce read policy, hydrate state, or audit access can therefore stop applying to AG-UI history depending on the concrete backend or wrapper capability set.

The behavior was identified and acknowledged in the PR review discussion: #2349 (comment)

Desired design

Define a hook-aware contract for persisted track-history reads. Possible approaches include:

• applying the relevant existing session-read policy to direct track reads; or
• introducing a dedicated Track read hook with a clearly documented relationship to GetSessionHook.

The design should avoid double-running hooks and preserve consistent access-control and audit behavior across direct-reader and fallback paths.

Acceptance criteria

• The hook contract for persisted Track reads is documented, including key/options mutation, errors, ordering, and fallback behavior.
• AG-UI direct persisted reads and snapshot fallback enforce equivalent caller-visible read policy.
• Tests cover at least a rejecting hook and a key-rewriting hook on the AG-UI history path.
• Existing backends and wrappers preserve the intended hook capability without changing unrelated defaults.

Related

• {session, server/agui, docs}: add track event history controls #2349
• Review thread: {session, server/agui, docs}: add track event history controls #2349 (comment)

中文

背景

PR #2349 为 Session 后端增加了直接读取持久化 Track 历史的能力。AG-UI 的 tracker.GetEvents 会优先调用可选的 GetTrackEvents，只有服务不具备该能力时才回退到 Service.GetSession。

这会改变 Hook 路径：直接 reader 不会执行后端的 GetSessionHook 链，而 fallback 会执行。用于校验或改写 key/options、执行读取权限策略、注入状态或记录审计日志的 Hook，可能因具体后端或 wrapper 的能力组合不同而在 AG-UI 历史读取中失效。

该行为已在 PR 评审中确认：#2349 (comment)

期望设计

为持久化 Track 历史读取定义 Hook 感知契约。可选方案包括：

• 让直接 Track 读取应用现有 Session 读取策略中相关的部分；或
• 增加专用 Track read Hook，并清楚定义它与 GetSessionHook 的关系。

设计应避免重复执行 Hook，并保证 direct reader 与 fallback 路径具有一致的访问控制和审计行为。

验收条件

• 文档明确持久化 Track 读取的 Hook 契约，包括 key/options 修改、错误、执行顺序和 fallback 行为。
• AG-UI 的直接持久化读取和 snapshot fallback 执行等价的调用方可见读取策略。
• 测试至少覆盖拒绝访问 Hook 和改写 key Hook 的 AG-UI 历史读取场景。
• 现有后端和 wrapper 能保留预期 Hook 能力，且不改变无关默认行为。