agent/a2aagent: coordinate anonymous-cookie initialization across agent instances

[XnLemon]

Background / 背景

PR #2163 serializes first anonymous-cookie initialization within a single A2AAgent instance and persists the acquired cookie through session state when a SessionService is available.

PR #2163 在单个 A2AAgent 实例内串行化首次 anonymous-cookie 初始化；当 SessionService 可用时，会通过 session state 持久化获取到的 Cookie。

However, this coordination is currently in-process only. Multiple A2AAgent instances, or multiple processes sharing the same SessionService, can still race during first anonymous-cookie initialization for the same logical session and remote cookie scope.

不过，当前协调只在单进程/单实例内生效。多个 A2AAgent 实例，或多个共享同一 SessionService 的进程，在同一个逻辑 session 和远端 Cookie scope 的首次 anonymous-cookie 初始化期间仍然可能发生竞争。

In that case, parallel first anonymous calls may acquire different remote anonymous principals before one persisted cookie wins.

在这种情况下，并发的首次匿名调用可能会在某个持久化 Cookie 最终生效前，分别获取到不同的远端 anonymous principal。

Scope / 范围

Add persistence-backed coordination for first anonymous-cookie initialization across agent instances/processes that share the same SessionService.

为共享同一 SessionService 的多个 agent 实例/进程增加基于持久化存储的首次 anonymous-cookie 初始化协调机制。

Possible directions:

可能方向：

• Add a lease or CAS-style state transition around the anonymous-cookie state key.
• 围绕 anonymous-cookie state key 增加 lease 或 CAS 风格的状态转换。
• Use logical session identity plus remote cookie state key as the coordination key.
• 使用逻辑 session identity 加远端 Cookie state key 作为协调 key。
• Ensure contenders reload persisted cookie state after acquiring or observing the coordination state.
• 确保竞争方在获取或观察协调状态后重新加载已持久化的 Cookie state。
• Define timeout/cleanup behavior for abandoned initialization leases.
• 定义被遗弃初始化 lease 的超时和清理行为。

Acceptance Criteria / 验收标准

• Concurrent first anonymous invocations from separate A2AAgent instances converge on one remote anonymous principal.
• 来自不同 A2AAgent 实例的并发首次匿名调用最终收敛到同一个远端 anonymous principal。
• Coordination works when instances share the same SessionService.
• 当多个实例共享同一个 SessionService 时，协调机制生效。
• Failed or canceled initialization does not leave the session permanently locked.
• 初始化失败或取消不会让 session 永久处于锁定状态。
• The anonymous cookie remains private session state and is not emitted through public event deltas.
• anonymous cookie 仍然保留在私有 session state 中，不会通过公开 event delta 发出。
• Tests cover cross-instance concurrency and cancellation/lease cleanup behavior.
• 测试覆盖跨实例并发以及取消/lease 清理行为。

Related / 关联

Follow-up from PR #2163.

来自 PR #2163 的 follow-up。

[XnLemon]

assign me please

[Rememorio]

Thank you for your contribution

[XnLemon]

目前 follow-up 思路为持久化 lease + Cookie 原子提交，保留现有单实例锁作为 fallback。

1. 核心模型

协调 key：
AppName + UserID + SessionID + anonymousCookieStateKey(remoteURL)
不能使用 *session.Session 指针，因为不同进程拿到的是不同 clone。
新增可选能力，不修改现有 session.Service 主接口：

type StateLeaseCoordinator interface {
    AcquireSessionStateLease(
        ctx context.Context,
        key session.Key,
        stateKey string,
        ttl time.Duration,
    ) (existing []byte, lease StateLease, err error)
}

type StateLease interface {
    Commit(ctx context.Context, state session.StateMap) error
    Abort(ctx context.Context) error
    Renew(ctx context.Context) error
}

语义：

• 已存在 Cookie：直接返回 existing，不创建 lease。
• 不存在 Cookie：只有一个实例获得 lease。
• 其他实例等待；lease 完成后重新读取 Cookie。
• Commit 必须校验 owner token，并持久化 Cookie 后释放 lease。
• Abort 或 TTL 到期后允许其他实例重试。

2. A2A 调用流程

本地 Session state 有 Cookie？
        ├─ 是：直接发送请求
        └─ 否：
             Acquire lease
                ├─ 发现其他实例已提交：重新加载 Cookie，直接发送
                └─ 自己获得 lease：
                     发送首次无 Cookie 请求
                     捕获远端 Set-Cookie
                     Commit Cookie + 释放 lease

Cookie 只有在 Commit 成功后才认为初始化成功。持久化失败时：

• 关闭/丢弃远端响应；
• 当前调用返回错误；
• 不产生成功事件；
• 释放 lease，允许后续调用重试。
  Cookie 仍通过 UpdateSessionState 类似的私有状态写入，不进入 event delta。

这里想着重确认一下后端实现

3.后端实现

建议只给支持持久化协调的 SessionService 增加可选实现：

• In-memory：进程内 mutex，主要用于测试。
• MySQL/PostgreSQL：lease 表或 session 行锁，使用事务和过期时间。
• Redis：SET NX PX + owner token，Lua 脚本校验释放/提交。
• MongoDB：带 expiresAt 和 owner token 的条件更新。
• 自定义 SessionService：未实现该能力时，继续使用当前单实例锁。

同时增加 strict 模式：
WithAnonymousCookieCoordinationRequired()

生产环境开启后，如果 SessionService 不支持跨实例协调，直接返回配置错误，避免用户误以为具备跨进程保证。

4.异常与边界

• 等待 lease 时取消：立即返回 context.Canceled，不残留锁。
• 持有 lease 时取消或远端失败：Abort。
• 进程崩溃：依靠 TTL 自动恢复。
• 远端请求时间可能超过 TTL：启动 Renew，或要求 lease TTL 大于 HTTP timeout。

lease 必须有 fencing token，防止旧实例 lease 过期后继续覆盖新值。

进程在远端已生成 Cookie、但尚未来得及提交时崩溃，仍可能产生一个孤儿 principal。这是当前 A2A 协议无法做到 exactly-once 的边界；若要彻底消除，需要远端支持幂等初始化 key。

我认为该 issue 可以另开一个pr作为 #2163 的 follow-up 而不是在 #2163 内实现
因为其涉及到多后端的锁实现 scope 过大也会给 review 带来困难 我会 base #2163 开新 pr 完成该 issue
如果 #2163 可以在 #2259 完成后合并 我会等待合并后完成该 issue

@Rememorio 请看一下我总结完成的方案 辛苦您了 我会持续跟进该 pr

[Rememorio]

感谢你把 lease、fencing token、异常恢复和各后端实现都整理得这么完整。把这部分作为 #2163 的 follow-up 单独推进，看起来也更方便控制改动和 review 范围。

关于公共接口这里有一个想法，想一起讨论一下。

目前的：

type StateLeaseCoordinator interface {
	AcquireSessionStateLease(...) (...)
}

type StateLease interface {
	Commit(ctx context.Context, state session.StateMap) error
	Abort(ctx context.Context) error
	Renew(ctx context.Context) error
}

会不会稍微偏底层了一些？

Acquire / Commit / Abort / Renew 暴露之后，A2AAgent 需要参与管理 lease TTL、续租、owner token、stale owner、取消和清理等生命周期。不同调用方如果以后复用这个接口，也需要各自正确实现相同的状态机。

另外，lease 是针对单个 stateKey 获取的，但：

Commit(ctx context.Context, state session.StateMap) error

允许提交任意 StateMap，范围可能有些宽泛，也不太容易界定 lease 对哪些 state 具有写入权限。

是否可以考虑把 lease 完整地收在 SessionService 实现内部，对上层只暴露一个高层的“读取或协调初始化单个 session state”能力？例如不修改现有 session.Service 主接口，而是增加一个可选接口：

// StateInitializationService extends Service with coordinated initialization
// of individual session-state values.
type StateInitializationService interface {
	// LoadOrInitializeSessionState returns the existing value for stateKey.
	//
	// If the value does not exist, the service coordinates initialization
	// across callers sharing the same backing store. Only the current owner
	// invokes initialize.
	//
	// A successful return guarantees that value has been persisted.
	// didInitialize reports whether this call produced and committed the value.
	LoadOrInitializeSessionState(
		ctx context.Context,
		key Key,
		stateKey string,
		initialize func(context.Context) ([]byte, error),
	) (
		value []byte,
		didInitialize bool,
		err error,
	)
}

大致可以约定为：

• state 已存在时，直接返回已有值，didInitialize=false；
• state 不存在时，由当前 owner 执行 initialize；
• 其他实例在协调完成后返回已经持久化的值；
• initialize 在数据库事务和全局存储锁之外执行；
• lease 的 acquire、等待、自动续租、fencing 和释放都由后端内部处理；
• callback 返回错误或 context 取消时，不写入 state；
• callback 成功后，后端校验 owner token，再原子完成 state 写入和 lease 释放；
• lease 已经失效的旧 owner 不能继续覆盖新 owner 的值；
• 每次方法调用最多执行一次 callback；
• callback 引起的远端副作用仍然不承诺 exactly-once。

这样 A2AAgent 不需要直接理解 lease，只需要区分“本次完成了初始化”和“其他实例已经完成初始化”。

A2A 侧的流程大致可以是：

var initializedResponse *http.Response

value, didInitialize, err :=
	stateInitializer.LoadOrInitializeSessionState(
		ctx,
		sessionKey,
		anonymousCookieStateKey,
		func(initCtx context.Context) ([]byte, error) {
			resp, cookie, err := sendFirstRequestWithoutCookie(initCtx)
			if err != nil {
				if resp != nil && resp.Body != nil {
					_ = resp.Body.Close()
				}
				return nil, err
			}

			initializedResponse = resp
			return []byte(cookie), nil
		},
	)

if err != nil {
	if initializedResponse != nil && initializedResponse.Body != nil {
		_ = initializedResponse.Body.Close()
	}
	return nil, err
}

anonymousCookieState.Set(value)

if didInitialize {
	// 本次响应只在 Cookie 已经持久化后对外返回。
	return initializedResponse, nil
}

// 其他实例已经完成初始化，本次 invocation 使用最终 Cookie
// 正常发送自己的请求。
return sendRequestWithCookie(ctx, value)

这里 owner 的远端响应仍然会等 Cookie 持久化成功后再返回；如果持久化或 fencing 校验失败，就关闭响应并返回错误。等待方也不会丢失自己的 invocation，而是在得到最终 Cookie 后继续发送自己的请求。

后端内部仍然可以使用你提到的实现：

• In-memory：按 (session.Key, stateKey) 建立共享 gate；
• MySQL/PostgreSQL：独立 lease 表和短事务；
• Redis：TTL + owner token，并通过 Lua 完成条件提交；
• MongoDB：基于 owner token 和过期时间的条件更新。

SQL 这边如果使用 session 行锁并跨越远端 HTTP 请求，事务和连接可能会持有比较久。换成独立 lease 记录是否会更稳妥一些：先用短事务取得 lease，callback 执行期间只保留逻辑 lease，最后再通过短事务校验 token、写 state 并释放 lease。

strict 模式的思路也可以保留。公共命名上，如果希望避免把 Cookie 这一当前实现细节固化在 API 里，是否可以考虑表达成匿名身份协调，例如：

WithRequireAnonymousIdentityCoordination(enabled bool)

默认情况下：

• SessionService 支持 StateInitializationService 时自动使用跨实例协调；
• 不支持时保留当前单 A2AAgent 实例内的 fallback；
• strict 模式开启时，如果首次匿名身份初始化无法获得跨实例协调能力，就在联系远端之前返回错误。

另外可能还需要关注 SessionService wrapper。externalization 这类纯装饰 wrapper 可以条件透传该能力；candidate-selector 这类带 speculative state 语义的 wrapper，可能需要单独确定匿名身份初始化应该进入 attempt state，还是直接进入底层持久化服务。

实现范围上，一开始是否可以先完成：

1. 可选接口和行为契约；
2. In-memory 实现与通用 conformance tests；
3. A2AAgent 接入和两个实例的并发测试；
4. 一个生产后端实现。

其他后端后续分别补齐，可能会比在同一个 PR 里同时实现 MySQL、PostgreSQL、Redis 和 MongoDB 更容易 review，也方便在第一个生产实现中验证接口是否足够稳定。

测试方面可以重点覆盖：

• 两个 A2AAgent、同一个逻辑 session、并发首次调用最终只提交一个 principal；
• waiter 取消；
• owner callback 失败；
• lease 过期后旧 owner 的提交被 fencing 拒绝；
• 持久化失败时关闭远端响应；
• 不同 session 或不同远端 scope 不互相阻塞；
• unsupported SessionService 的 fallback 和 strict 模式；
• SessionService wrapper 的能力透传；
• 允许远端生成 Cookie 后、本地提交前崩溃产生孤儿 principal，但旧 owner 不能覆盖后续成功提交。

整体上，lease、fencing 和原子提交仍然可以作为各后端的实现基础，只是把这些细节隐藏在 SessionService 内部，对 A2AAgent 暴露更高层的 state initialization 能力，公共导出面可能会更小一些，调用方也不容易误用 lease 生命周期。

也想请 @hyprh 一起看看：这种把 lease 隐藏在 SessionService 实现内部、只暴露协调初始化能力的抽象是否合适，以及第一版后端实现范围怎样拆分会更容易维护和 review。