# 2026-08-14：运行可观测性与工具体验补齐

# 目标

补全单 Agent Core 的运行结果、工具执行和 Token 可观测性，使前端能够区分成功、失败、取消和超时，并在历史恢复后保留关键执行指标。

# 变更文件

• pi-agent-v1/src/main/java/piagent/core/AgentLoop.java
• pi-agent-v1/src/main/java/piagent/core/Protocol.java
• pi-agent-v1/src/main/java/piagent/session/SessionStore.java
• pi-agent-v1/src/main/java/piagent/tools/ToolRegistry.java
• pi-agent-v1/src/main/java/piagent/tools/ToolTimeoutException.java
• pi-agent-v1/src/main/java/piagent/tools/BuiltinTools.java
• pi-agent-v1/src/main/java/piagent/web/WebMain.java
• web/src/main.tsx、web/src/styles.css

# 契约变化

• agent_end 新增 status、turnCount、failureCount、durationMs。
• turnend 新增 durationMs；toolexecution_end 新增 durationMs、outputLines、timedOut。
• 模型调用的第一次运行时异常会发出 model_retry，然后进行一次重试（总计最多两次尝试）。
• 工具超时通过 ToolTimeoutException 转换为带 details.timeout=true 的错误 ToolResult；工具结果的耗时与行数写入 JSONL，历史加载时恢复。

# 前端行为

• 运行卡显示执行中、成功、失败、取消，以及轮数、失败次数和总耗时。
• 工具终端卡显示执行状态、耗时、输出行数，支持复制命令、复制结果、下载结果；长输出按阈值采用虚拟列表并支持搜索与错误行标记。
• Token 支持按轮次展示，并在会话累计接近或达到 TOKEN_BUDGET 时进行颜色提示。

# 验证与边界

• 本次从提交 0c66575 的源码与数据契约核对，尚未补充独立的构建或真实模型端到端证据；后续修改该能力时应执行 Maven、前端生产构建，并以真实模型验证 retry/timeout SSE 顺序。
• 超时的具体时限由各工具执行器负责；ToolRegistry 只负责统一映射为可观测结果。