@kmlckj/aios-agent-server-sdk 0.0.0-stage → 0.0.2

package/EVENTS.md

@@ -0,0 +1,88 @@
+# 执行事件与前端接入
+
+SDK 执行事件沿用桌面端的任务日志契约，保留完整 `payload`。Node 宿主负责鉴权、订阅并向前端转发；SDK 不负责云端 SSE/WebSocket 路由或网页组件。
+
+## 选择观察范围
+
+| 接口 | 用途 | 结束条件 |
+|---|---|---|
+| `run.events({ cursor, signal })` | 观察一轮执行 | 该轮终态已补拉后结束 |
+| `session.events({ cursor, signal })` | 任务页面持续观察，包括下一轮和延迟计量 | 调用方取消观察或发生明确错误 |
+| `session.eventPage({ cursor, signal })` | 获取当前已存事件，用于断线恢复、历史面板 | 返回一页及下页游标 |
+| `run.state()` / `run.wait()` | 查询或等待执行状态及待处理交互 | `waiting` 代表等待处理，不能显示为完成 |
+| `session.history()` / `queryHistory()` | 获取持久消息和引用 | 返回桌面端同源 `LocalTaskMessage`，包含思考、引用、附件、富文本和用量等字段 |
+
+单轮完成后，积分上报等仍可能追加事件。需要完整任务页面时使用会话流；不要在收到一轮 `complete` 后关闭会话订阅。停止观察不取消执行，取消任务调用 `run.cancel()`。
+
+```ts
+// Node 应用宿主：将每个完整事件交给已有的 Web 事件通道。
+const session = await client.openSession(localSessionId);
+const controller = new AbortController();
+for await (const event of session.events({ cursor: savedCursor, signal: controller.signal })) {
+  await forwardToAuthorizedFrontend(event);
+  // 实际业务应在前端确认接收后持久化游标，并以 event.id 去重。
+}
+```
+
+## 字段与标识边界
+
+- `schemaVersion: 1`：SDK 外层契约版本。原生事件版本仍保留在 `payload.schema_version`。
+- `id`：稳定事件 ID；重连、重启后用它去重。
+- `cursor`：处理完本条后保存，可从同一页中间恢复。它绑定会话和观察范围；会话游标不能用作单轮游标，其他会话也不能使用。历史清空/重写使原位置失效时会明确报错。
+- `sequence`：当前观察游标流内的递增位置；不能作为跨会话、跨观察范围的全局序号。`runtimeSequence` 保留引擎原始序号。
+- `sessionId` / `runId`：本地任务及本地运行。会话级事件可以没有 `runId`。
+- `threadId` / `turnId` / `itemId` / `requestId`：原始执行及交互关联标识。
+- `rootThreadId` / `sourceThreadId` / `parentThreadId`：本地子线程的父子关系，来源于实际执行事件。
+- `context`：本轮宿主提供的可信业务元数据，包含平台 session/turn/task/run、actor/owner、项目、空间、场景、trace 等；没有提供时省略。凭证不在此字段中。
+- `runtimeType`：原始事件类型，例如 `tool_call_start`、`usage_update`、`credit_usage_update`、`context_compaction`。
+- `payload`：原始结构化详情，包含工具展示身份、参数、结果、附件名称映射、错误、成员状态等。未知扩展字段不要在转发时丢弃。
+
+本地 `task_list`、`sub_agent`、`team_*` 是执行引擎已有的任务拆分和协作。`payload.team_run_id`、`member_run_id`、`receiver_thread_ids`、`agents_states` 等保持原语义，不能改成平台业务任务 ID。平台关联放 `context.platformTaskId` 等字段。SDK 没有额外建立第二套任务拆分引擎。
+
+## 展示事件
+
+| 事件 | 前端用途 |
+|---|---|
+| `text_delta`、`thinking_delta`、`stage_message` | 回复、思考和阶段说明 |
+| `tool_start`、`command`、`file_change`、`tool_result` | 工具调用、命令和文件操作卡片，依据 item/tool-call 标识配对 |
+| `turn_diff` | 文件变更详情 |
+| `task_list`、`plan_delta`、`plan_response`、`plan_ready` | 本地任务步骤、计划及确认 |
+| `sub_agent` | 原生子任务的委派、状态、等待和结果 |
+| `team_run`、`team_member`、`team_collaboration`、`team_workflow_task`、`team_artifact` | 专家团队执行、成员、协作步骤和产物 |
+| `approval_required`、`approval_response`、`sensitive_protection` | 审批、敏感保护及结果 |
+| `user_input_required`、`user_input_response`、`open_browser` | 补充问询、授权交互与浏览器请求 |
+| `status`、`state`、`queue_changed` | 生命周期、排队及运行状态 |
+| `status` 且 `runtimeType === 'context_compaction'` | 压缩通知，读取 `payload.phase` 和 `payload.trigger` |
+| `status` 且 `runtimeType === 'background_operation'` | 实际异步执行引用，可用 operation ID 查询；不是额外任务完成事件 |
+| `usage` | Token、上下文估算或积分；用 `runtimeType` 区分来源，不把多次累计快照再次相加 |
+| `complete`、`error` | 终态或错误；错误是否终止依据原始 terminal/retryable 语义及 `run.state()` |
+
+压缩 `phase` 为 `started/completed/failed`，`trigger` 为 `manual/threshold/native`。宿主发起的手动或阈值压缩发出真实开始和结果；原生自动压缩只发已收到的通知。只收到完成通知时不会伪造开始通知。Token 数值只在实际可获得时给出，不用 0 表示未知。
+
+工具错误不等于整轮失败，模型可能继续纠正。`awaiting_plan_confirmation`、待审批和待回答也不等于已交付。模型文本自称“验证通过”不能转成系统验证事实；验证范围保留在对应工具结果中。
+
+SDK 应用声明的受控成员继续使用 `team_*` 事件及原成员/线程标识；父任务在成员未收敛时不会发布成功。应用 `run.team({ action: 'wait', ... })` 是观察，不消耗交给模型的成员结果。独立后台 Session 则通过自己的 `events/eventPage` 观察，与父 Session 的事件流分开；来源关系见 `session.configuration().parent`。本地协作关系与业务 `context` 分开传递。
+
+## 复用桌面端工具短句
+
+浏览器可以单独引用无 Node、无运行时启动逻辑的入口：
+
+```ts
+import { toolActivityTitle, type SessionEvent } from '@kmlckj/aios-agent-server-sdk/events';
+
+function describeTool(event: SessionEvent) {
+  return toolActivityTitle(event.payload, 'zh-CN');
+}
+```
+
+该函数与桌面端共用标题规则及脱敏逻辑，如“读取 合同.txt”。未知工具返回 `undefined`，由界面显示真实工具名称或现有通用标题；不能从任意参数的 title/description 推断操作已经成功。SDK 仅提供数据和展示辅助，折叠、卡片、定位及交互布局由前端实现。
+
+## 托管授权通知
+
+注册 `credentials` 回调的客户端通过 `client.auth.managedEvents({ after?, signal? })` 获取 `ManagedAuthorizationEvent`。这是提供者进程内的独立通知流，不混入持久化任务事件，普通观察客户端不能订阅。每条事件含 `cursor/occurredAt/type/scope/reason`，可带原始 `execution`、`expiresAt` 或 `code`；没有 Token、刷新凭证和回调异常文本。
+
+- `authorized`：取证或续期成功，`reason` 为 `initial/expiring/rejected/explicit`。
+- `invalidated`：`expired` 为缓存凭证自然过期，`provider_error` 为取证失败，`revoked/closed` 为整个提供者撤销/关闭。
+- `scope: credential` 只描述一个凭证缓存；`scope: provider` 描述整个提供者。`execution` 缺省表示实例级查询，不代表任意活动任务。
+
+只保留最近 256 条，游标过期返回 `AUTH_EVENT_CURSOR_EXPIRED`，跨提供者或无效游标返回 `AUTH_EVENT_CURSOR_INVALID`。取消观察只终止等待；提供者关闭时发送关闭事件并结束流。远端提前撤销授权通过下一次请求的 401 得知，SDK 不进行额外轮询。