feat: sync latest ARR implementation

AGENT_INTEGRATION.md

@@ -1,6 +1,8 @@
-# Open Agent API 对接说明
+# ARR1 历史文档 — Open Agent API 对接说明
 
-更新时间：2026-07-27
+> 仅作兼容与迁移审计。ARR2.0 的生产行为以根目录 README 和 ADR-004 为准，不导入、配置或部署此集成。
+
+更新时间：2026-07-29
 
 ## 1. 已完成范围
 
@@ -13,7 +15,7 @@
 - 以 JSONL 输出流事件，便于后续转发到 WebSocket、微信或 CRM；
 - 所有密钥只从环境变量读取。
 
-底层 `agent_integration` 只负责文本 Agent API。Opera XML 远程任务由独立 `arr_processing` 边界建模：ARR 代码先上传私有 OSS，再向 Agent 发送一个不含密钥的 `oss_attachments` 描述对象，由 runtime 的 `fetch_oss_file` 取件；结果只接受经受信 runtime 签名的 path-free 回调。具体处理规则仍只在 `arr-opera-daily-ingest` 确定性 Skill 内。
+底层 `agent_integration` 只负责文本 Agent API。Opera XML 远程任务由独立 `arr_processing` 边界建模：ARR 代码上传源 XML，把 committed 对象设为 `public-read`，再向 Agent 发送含 ARR 生成的无签名 HTTPS URL、但不含密钥的 `oss_attachments` 描述对象，由 runtime 的 `fetch_oss_file` 取件；暂存与输出对象仍为 private。结果只接受经受信 runtime 签名的 path-free 回调。具体处理规则仍只在 `arr-opera-daily-ingest` 确定性 Skill 内。
 
 ## 2. 安装
 
@@ -71,10 +73,21 @@ export DEERFLOW_SESSION_DB="runtime/agent_sessions.sqlite3"
 
 公开事件只包含 `run.started`、`message.delta`、`message.completed`、`run.warning/run.error` 和 `run.end`，不会转发 LangGraph 内部推理、服务器路径、标题中间件或跟踪 metadata。
 
+ARR 生产任务另有受控诊断路径：请求
+`POST /api/open/agent-sessions/{session_id}/messages/stream?include_trace=true`，
+只把外层 `trace` 中的 `run.started`、`task.updated`、`step.updated`、运行终态
+和 `end` 投影为脱敏运维事件。`message.delta`、`message.final`、原始 SSE、Prompt、
+工具参数/结果都不落入任务日志。
+
 调试终端可追加 `--output text`。只有排查协议问题且输出位置受控时才使用 `--output raw-jsonl`；原始流可能包含内部推理和服务器运行信息，不得直接转发给最终用户或写入普通业务日志。
 
 `conversation-id` 和 `external-subject-id` 应使用稳定、不含姓名或证件信息的内部 ID。上游有消息 ID 时务必传 `--message-id`；同一个 ID 会生成同一个幂等键，便于安全重发。
 
+注意：2026-07-29 的真实接口探针确认，`/messages/stream?include_trace=true`
+对完全相同的消息幂等键仍会创建新的 `run_id`，不能把它当作历史回放或服务端
+去重接口。生产代码只 POST 一次并继续消费同一条连接；拿到 `run.started` 后绝不
+为了“补日志”再次提交。
+
 ## 6. 非流式 Run
 
 ```bash
@@ -143,6 +156,7 @@ with SQLiteSessionStore(config.session_db) as store:
             "你好",
             message_id="crm-message-001",
             metadata={"source": "crm"},
+            include_trace=True,
         ):
             print(event.to_dict())
 ```
@@ -151,7 +165,7 @@ with SQLiteSessionStore(config.session_db) as store:
 
 当前 Open API 契约没有附件上传或文件登记接口。远端 Agent 无法访问调用机上的 `/absolute/input.xml`，所以不能把本地路径写进消息后假定 Agent 能读取。
 
-当前已实现 `arr_processing` 的 job/run 关联、有界重试、直接 OSS 输入描述、runtime 结果发布、独立 HMAC 签名、OSS 输出重取、ARR 独立复验和 PostgreSQL 原子落库。输入 message 符合 `arr_opera_daily_program_input.schema.json`：只含 bucket、endpoint、精确 object key、哈希、字节数与任务 ID，不含 OSS AccessKey、XML 正文、签名 URL 或本机路径。`fetch_oss_file` 的平台 credential provider 独立持有读权限。
+当前已实现 `arr_processing` 的 job/run 关联、有界重试、直接 OSS 输入描述、runtime 结果发布、独立 HMAC 签名、OSS 输出重取、ARR 独立复验和 PostgreSQL 原子落库。输入 message 符合 `arr_opera_daily_program_input.schema.json`：含 bucket、public endpoint、精确 object key、ARR 生成的无签名 HTTPS URL、哈希、字节数与任务 ID，不含 OSS AccessKey、XML 正文或本机路径。`fetch_oss_file` 只接收该公网 URL 和文件名，不使用 OSS Provider。
 
 结果不从 `final_content`、`present_files` 或 Agent 本地路径取回。受信 runtime adapter 把产物发布到私有 OSS 交换前缀，然后签名回调 ARR；ARR 从 OSS 重新下载并复验后才入库。回写接口、状态码、ID 对应和部署变量见 `AGENT_WRITEBACK_CONTRACT.md`；实现边界见 `arr_processing/README.md`。