@zhin.js/agent 1.0.1 → 1.0.3

package/README.md

@@ -7,9 +7,9 @@ Zhin AI Agent 组合层：在 `@zhin.js/core` 的类型与 Provider 之上，提
 ## 功能特性
 
 - 🤖 **agentLoop 统一路径**：ZhinAgent、Subagent、Deferred Worker、AIService 均经 `agentLoop`（legacy `Agent.run` 仅保留在 `@zhin.js/ai` 供单测）
-- 📝 **会话管理**：`SessionManager`、内存/数据库会话、`SessionManager.generateId`
+- 📝 **会话持久化**：`AgentSessionStore` + `ContextRepository` + `ImTranscriptStore`（ADR 0009）
 - 🧠 **ZhinAgent**：与 Zhin 消息流集成的智能体（SOUL/TOOLS/AGENTS、工具收集、执行策略）
-- 🔍 **模型自动发现**：`ModelRegistry` 调用 `listModels()`（OpenAI 兼容 `/v1/models`、Ollama `/api/tags`）；结果写入 `provider.models` 并供 `getModel()` 校验；yaml 显式 `models` 时以配置为准
+- 🔍 **模型自动发现**：`ModelRegistry` 调用 `listModels()`；结果写入 `provider.models` 并供 `getLlmTransportModel()` 校验
 - 🔄 **模型自动降级**：首选模型失败时按 `resolveModelCandidates` 候选链 fallback（文本 / 多模态 / standalone 均走 agentLoop）
 - 🛡️ **6 层 Bash 安全**：`ExecPolicy` 纵深防御（危险黑名单、环境变量剥离、wrapper 剥离、复合命令拆分、只读放行、交互式审批）
 - 📂 **文件访问安全**：`FilePolicy` 路径检查、设备路径拦截、命令读写分类
@@ -27,6 +27,59 @@ Zhin AI Agent 组合层：在 `@zhin.js/core` 的类型与 Provider 之上，提
 - 依赖 **@zhin.js/core**（IM 类型与消息链）与 **@zhin.js/ai**（`agentLoop`、Provider 抽象）
 - **zhin.js 4.x** 主包为 optional peer；运行时通过 `zhin.js/agent` 子路径或本包 import；`bootstrapNode` 在检测到本包时调用 `initAgentModule()`
 
+## 模块化架构（理想蓝图 8 模块）
+
+迁移完成后，`src/` 按职责拆分为 8 个理想模块 + Orchestration + IM 组合层（单包，可选 subpath export）：
+
+```
+packages/im/agent/src/
+  core/          Agent Core — agentLoop 薄适配（ADR 0009）
+  tool/          Tool System — Source/Filter、deferred 解析、运行时
+  session/       Session System — IM/Agent 双 store、passive group、session-io
+  event/         Event System — Agent turn 域事件（不替代 Kernel RunEvent）
+  skill/         Skill System — SkillRegistry 统一出口
+  memory/        Memory System — Port → ContextRepository + compaction
+  subagent/      Subagent System — SubagentSystem + ImResultSink
+  context/       Context System — builder/injector 链、tail limit
+  prompt/        系统提示词、assembly、workspace 模板
+  turn/          Turn pipeline、inbound 队列、auto-continue、metrics
+  config/        ZhinAgent 配置 SSOT、model harness
+  orchestrator/  Orchestration Kernel（ADR 0027 SSOT）
+  collaboration/ IM 入站/出站（阶段 4）
+    inbound-turn-pipeline.ts      enrich → peerPolicy → plan → route → outbound
+    inbound-turn-enrich.ts        媒体/引用/subagent 通知
+    inbound-turn-route.ts         Kernel 委派 / spawn / 本地 execute
+    inbound-turn-outbound-stage.ts  出站 batch + Kernel 投影
+    inbound-turn-endpoint.ts      @ ID / aiAccess
+  zhin-agent/    ZhinAgent 门面类（单文件 index.ts）
+  init/          create-zhin-agent、composeZhinAgentRuntime、configure/dispose 生命周期
+```
+
+**阶段 4 — `collaboration/` 入站编排子模块**
+
+| 文件 | 职责 |
+|------|------|
+| `inbound-turn-pipeline.ts` | enrich → peerPolicy → buildTurnPlan → route → outbound 纯编排 |
+| `inbound-turn-enrich.ts` | 媒体/引用/subagent 通知 enrich |
+| `inbound-turn-route.ts` | Kernel 委派、spawn_task、本地 `executeInboundAgentTurn` |
+| `inbound-turn-outbound-stage.ts` | 出站 batch 解析、IM 发送、Kernel 投影 |
+| `inbound-turn-endpoint.ts` | @ ID / aiAccess 解析 |
+
+**Agent Core**：`AgentCore.runText()` / `runVision()` 为 `AsyncGenerator<TurnEvent>` SSOT；`runTextTurn` 为 collector。组合层经 `composeZhinAgentRuntime` 注入 8 模块 + `createAgentCoreDepsForCompose`。
+
+Port 边界见 [orchestrator/PORTS.md](./src/orchestrator/PORTS.md)。
+
+可选 subpath（`package.json` `exports`）：
+
+```typescript
+import { AgentCore } from '@zhin.js/agent/core'
+import { ToolSystem } from '@zhin.js/agent/tool'
+import { SessionSystem } from '@zhin.js/agent/session'
+// …/event、/skill、/memory、/subagent、/context、/prompt、/turn、/config
+```
+
+词汇与 Port 边界见 [CONTEXT.md](./CONTEXT.md)、[orchestrator/PORTS.md](./src/orchestrator/PORTS.md)。
+
 ## 安装
 
 ```bash
@@ -46,13 +99,12 @@ pnpm add @ai-sdk/openai   # 示例：按厂商安装 provider SDK
 import {
   ZhinAgent,
   AIService,
-  SessionManager,
   registerAIHook,
 } from 'zhin.js/agent'
 
 // 使用 ctx.ai (AIService)
 useContext('ai', async (ai) => {
-  const session = ai.sessions.get(sessionId)
+  const result = await ai.runAgent('你好', { provider: 'ollama' })
   // ...
 })
 ```
@@ -84,17 +136,17 @@ useContext('ai', async (ai) => {
 | 初始化 | `initAgentModule` |
 | Agent | `ServiceAgent`、`CreateServiceAgentOptions`（`AIService.createAgent`）；legacy `Agent` / `createAgent` re-export 自 `@zhin.js/ai` |
 | Model harness | `MODEL_HARNESS_DEFAULTS`, `resolveModelHarness`, `mergeModelHarnessValues` |
-| 服务与会话 | `AIService`, `SessionManager`, `MemorySessionManager`, `DatabaseSessionManager`, `createMemorySessionManager`, `createDatabaseSessionManager` |
-| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / file-policy / tool-runtime / prompt / builtin-tools 等子模块 |
+| 服务与会话 | `AIService`；会话/context 类型见 `@zhin.js/ai`（`ContextRepository`、`AgentSessionStore`、`ImTranscriptStore`） |
+| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / file-policy / `@zhin.js/agent/tool` / prompt / builtin-tools 等 |
 | 安全策略 | `checkExecPolicy`, `applyExecPolicyToTools`, `isDangerousCommand`, `stripEnvVarPrefix`, `stripSafeWrappers`, `splitCompoundCommand`, `extractCommandName`, `ExecPolicyResult`, `checkFileAccess`, `classifyBashCommand`, `isBlockedDevicePath` |
 | 提示词构建 | `buildRichSystemPrompt`, `buildEnhancedPersona`, `buildUserMessageWithHistory`, `buildContextHint` |
-| 上下文与记忆 | `ContextRepository`, `AgentSessionStore`, `ImTranscriptStore`（经 ZhinAgent 注入）；`ContextManager`, `ConversationMemory`, `UserProfileStore` |
+| 上下文与记忆 | `ContextRepository`, `AgentSessionStore`, `ImTranscriptStore`（`@zhin.js/ai`）；`ContextManager`, `ConversationMemory`, `UserProfileStore` |
 | 跟进与定时 | `FollowUpManager`, `PersistentCronEngine`, `createCronTools`, `setCronManager`, `getCronManager` |
 | 压缩与 Bootstrap | `compactSession`, `estimateTokens`, `loadBootstrapFiles`, `loadSoulPersona`, `loadToolsGuide`, `loadAgentsMemory` |
 | Hook | `registerAIHook`, `unregisterAIHook`, `triggerAIHook`, `createAIHookEvent` |
 | IM 内置工具工厂 | `createBuiltinTools`、`BuiltinBaseTool`；具体工具见 `src/builtin/*` |
 | 输出与检测 | `parseOutput`, `renderToPlainText`, `renderToSatori`, `detectTone` |
-| 子代理 | `SubagentManager` |
+| 子代理 | `SubagentSystem` |
 | 编排 | `AgentOrchestrator`、`ToolRegistry`、`SkillRegistry`、`SubAgentRegistry`、`McpRegistry`、`HookRegistry` |
 | MCP 客户端 | `McpClientManager`、`McpClientConnection`、`mcpToolToAgentTool`、`ensureMcpConnections`（见下方「MCP」） |
 | 限流 | `RateLimiter` |
@@ -146,11 +198,31 @@ ai:
 
 ### 1. 主 Agent + 子 Agent（内置）
 
-框架已提供 **SubagentManager**：主 ZhinAgent 通过工具 `spawn_task` 把复杂/耗时任务派给**后台子 Agent** 异步执行，子 Agent 默认仅用受限工具集（文件、Shell、网络搜索等），完成后通过回调把结果发回主会话。
+框架已提供 **SubagentSystem**：主 ZhinAgent 通过工具 `spawn_task` 把复杂/耗时任务派给**后台子 Agent** 异步执行。子 Agent 使用受限工具集；完成后**先交还主 Agent**（写入主会话 + auto-continue 续聊），用户可见回复由主 Agent 整理发出。
+
+- 主对话不阻塞，用户可继续聊天（异步 `spawn_task`）。
+- `spawn_task` 在每轮 `turn-pipeline` 注入（`createSpawnTaskTool`），并默认列入 `deferredTools.alwaysLoadedTools`。
+- **`wait: true`** 时同步等待，结果经 tool result 回到当前主 Agent turn。
+- 监听 `ai.subagent.finish` 可做 log / 监控；需旧式「子任务摘要直推 IM」时设 `ai.agent.subagentDirectImDelivery: true`。
+
+**并发与并行（ADR 0030）**
+
+| 配置 | 默认 | 说明 |
+|------|------|------|
+| `toolExecution` | `tiered` | 同轮 `spawn_task` + 只读工具并行；写/bash 顺序 |
+| `maxParallelSubagents` | `5` | 并行子 agent 硬顶，超限拒绝 |
+| `subagentAutoContinue` | `true` | 异步完成后唤醒主 Agent |
+| `subagentDirectImDelivery` | `false` | 额外直发格式化摘要到 IM |
 
-- 主对话不阻塞，用户可继续聊天。
-- 子 Agent 由 `ZhinAgent.initSubagentManager(createTools)` 在 init 时挂好；`spawn_task` 为主编排序列化常驻工具（见 `orchestratorTools` / `DEFAULT_ORCHESTRATOR_TOOLS`）。
-- 用户说「后台帮我整理这份文档」时，主 Agent 可调用 `spawn_task({ task: '...', label: '...' })`，子任务在后台跑完后再通知用户。
+**类型权限**：`ai.agents.<name>.permission.task`（glob → allow/deny）控制主 Agent 可见的子 agent 预设。
+
+关键路径：
+
+- `src/subagent/` — `SubagentSystem`、`SubagentRuntime`、`onSubagentComplete`
+- `src/builtin/spawn-task-tool.ts` — 工具定义与 `permission.task` 校验
+- `src/turn/persist-subagent-context.ts` / `subagent-auto-continue.ts` — 结果落库与续聊
+- `src/turn/turn-pipeline.ts` — 每轮注入 `spawn_task`
+- `packages/im/ai/src/llm/tiered-tool-buckets.ts` — tiered 并行工具 SSOT
 
 无需额外配置即可使用；若需放宽子 Agent 的工具范围，使用 `ai.agent.subagentTools` 显式追加白名单（不会自动继承主会话全部 skill/tool）。
 
@@ -211,7 +283,7 @@ useContext('ai', async (ai) => {
 
 `AIService` 构造时：
 
-1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `api`，如 `openai-completions`）。
+1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `sdk`，如 `openai` 或 `openai-compatible`）。
 2. `registerLlmApiFromProviders`：**未写 `models` 的 provider** 在 ApiRegistry 注册为空白名单，由后台 `ModelRegistry.discover()` 填充 `provider.models`；**写了 `models`** 则用 yaml 白名单。
 3. `createZhinAgent` 启动时 `loadCache()` 先恢复上次发现结果，再异步刷新 `/v1/models`。
 
@@ -221,12 +293,12 @@ useContext('ai', async (ai) => {
 ai:
   providers:
     openai-main:
-      api: openai-completions
+      sdk: openai-compatible
       baseUrl: ${OPENAI_BASE_URL}
       apiKey: ${OPENAI_API_KEY}
       # models 省略 → 自动 GET /v1/models
     cloudflare-flash:
-      api: cloudflare-workers-ai
+      sdk: openai-compatible
       models: ["@cf/zai-org/glm-4.7-flash"]  # 显式列表
   agents:
     zhin:
@@ -238,7 +310,7 @@ ai:
 
 `AIService` 构造时：
 
-1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `api`，如 `openai-completions`）。
+1. 按 `ai.providers.<别名>` 实例化 Provider（须配置 `sdk`，如 `openai` 或 `openai-compatible`）。
 2. `registerLlmApiFromProviders`：**未写 `models` 的 provider** 在 ApiRegistry 注册为空白名单，由后台 `ModelRegistry.discover()` 填充 `provider.models`；**写了 `models`** 则用 yaml 白名单。
 3. `createZhinAgent` 启动时 `loadCache()` 先恢复上次发现结果，再异步刷新 `/v1/models`。
 
@@ -248,12 +320,12 @@ ai:
 ai:
   providers:
     openai-main:
-      api: openai-completions
+      sdk: openai-compatible
       baseUrl: ${OPENAI_BASE_URL}
       apiKey: ${OPENAI_API_KEY}
       # models 省略 → 自动 GET /v1/models
     cloudflare-flash:
-      api: cloudflare-workers-ai
+      sdk: openai-compatible
       models: ["@cf/zai-org/glm-4.7-flash"]  # 显式列表
   agents:
     zhin:
@@ -267,7 +339,7 @@ ai:
 
 **合并顺序**（约定优先，详见 [ADR 0007](../../docs/adr/0007-ai-agent-model-harness-yaml-overrides.md)）：
 
-1. TypeScript 默认表 `MODEL_HARNESS_DEFAULTS`（[`src/zhin-agent/model-harness.ts`](./src/zhin-agent/model-harness.ts)）
+1. TypeScript 默认表 `MODEL_HARNESS_DEFAULTS`（[`src/config/model-harness.ts`](./src/config/model-harness.ts) + [`model-harness-runtime.ts`](./src/config/model-harness-runtime.ts)）
 2. YAML `ai.agent.modelHarness.providerPatterns`（匹配当前 provider，支持 `*` 通配；按对象键插入顺序叠加）
 3. YAML `ai.agent.modelHarness.models`（`model` 或 `provider:model` 精确键）
 
@@ -287,7 +359,7 @@ ai:
 
 运行时由 `resolveModelHarness(providerName, modelName, config?.modelHarness)` 解析；包入口导出 `MODEL_HARNESS_DEFAULTS`、`resolveModelHarness`、`mergeModelHarnessValues` 与 `ModelHarnessConfig` 类型。未命中任何规则时回退 TS 默认行或空对象；当前仅消费 `maxIterations`，未知 YAML 字段会被忽略。
 
-增补内置默认值：在 `model-harness.ts` 增加 `ModelHarnessRow` 并附测试；YAML 只做覆盖，不替代 TS 约定层。
+增补内置默认值：在 `config/model-harness.ts` 增加 `ModelHarnessRow` 并附测试；YAML 只做覆盖，不替代 TS 约定层。
 
 ## IM 管理命令
 
@@ -307,44 +379,45 @@ zhin-package CLI：`zhin packages`（`basic/cli`）。详见 [ADR 0010](../../do
 
 ```
 src/
-├── index.ts                         # 导出 AgentOrchestrator + 五类 Registry + ZhinAgent + init
+├── index.ts                         # 包根导出：Orchestrator、ZhinAgent、init、builtin…
+│
+├── core/                            # Agent Core — agentLoop 薄适配
+├── tool/                            # Tool System — 运行时工具收集
+├── session/                         # Session System — IM/Agent 双 store、session-io
+├── event/                           # Event System — turn 域事件 + session 事件
+├── skill/                           # Skill System
+├── memory/                          # Memory System
+├── subagent/                        # Subagent System + manager init
+├── context/                         # Context System — builder/injector、tail limit
+├── prompt/                          # 系统提示词、assembly、workspace 模板
+├── turn/                            # Turn pipeline、inbound 队列、auto-continue
+├── config/                          # ZhinAgent 配置 SSOT、model harness
 │
-├── orchestrator/                    # ★ 核心：编排中枢
+├── orchestrator/                    # ★ 编排中枢（Kernel SSOT，ADR 0027）
 │   ├── index.ts                     # AgentOrchestrator class
-│   ├── types.ts                     # ResourceScope, ResourceEntry, Skill, SubAgentDef, AIHook, McpServerEntry
-│   ├── resource-registry.ts         # ResourceRegistry<T> 基类
-│   ├── tool-registry.ts             # ToolRegistry（含 ZhinTool, defineTool, 权限过滤）
-│   ├── skill-registry.ts            # SkillRegistry（含搜索）
-│   ├── subagent-registry.ts         # SubAgentRegistry
-│   ├── mcp-registry.ts              # McpRegistry
-│   └── hook-registry.ts             # HookRegistry
+│   ├── types.ts                     # ResourceScope, Skill, SubAgentDef, AIHook…
+│   ├── resource-registry.ts
+│   ├── tool-registry.ts
+│   ├── skill-registry.ts
+│   ├── subagent-registry.ts
+│   ├── mcp-registry.ts
+│   └── hook-registry.ts
 │
-├── mcp-client/                      # MCP 客户端（Manager / Connection / bridge）
+├── mcp-client/                      # MCP 客户端
 │
 ├── init.ts                          # initAgentModule 入口
-├── init/                            # 挂载子模块（orchestrator、ai、builtin-tools…）
-│
-├── service.ts                       # AIService（保留，对接 Orchestrator）
-│
-├── zhin-agent/                      # 主对话 Agent
-│   ├── index.ts                     # ZhinAgent（改造：从 Orchestrator 获取资源）
-│   ├── config.ts
-│   ├── prompt.ts
-│   ├── tool-runtime.ts              # 运行时工具收集与执行路径规划
-│   └── builtin-tools.ts             # chat_history（im_transcripts）, user_profile, spawn_task
+├── init/                            # create-zhin-agent、compose/configure/dispose 生命周期
 │
-├── discovery/                       # ★ 文件化资源发现
-│   ├── index.ts
-│   ├── utils.ts
-│   ├── tools.ts                     # *.tool.md 发现
-│   ├── skills.ts                    # SKILL.md 发现
-│   └── agents.ts                    # *.agent.md 发现
+├── service.ts                       # AIService
 │
-├── security/                        # ★ 安全策略
-│   ├── file-policy.ts
-│   └── exec-policy.ts
+├── zhin-agent/                      # ZhinAgent 门面类（单文件）
+│   └── index.ts
 │
-├── builtin/                         # IM 内置工具（BuiltinBaseTool + 各 *-tool.ts）
+├── internal/                        # host 契约、asPrivate、turn-context、phase/prompt trace
+├── collaboration/                   # 多 Endpoint 入站/出站
+├── discovery/                       # 文件化资源发现（tools / skills / agents）
+├── security/                        # exec-policy、file-policy
+├── builtin/                         # IM 内置工具
 ├── builtin-tools.ts                 # createBuiltinTools() 聚合
 │
 ├── defaults/                        # ★ 各注册表的默认资源

package/lib/a2a/delegation-message.d.ts

@@ -0,0 +1,14 @@
+import { type SendMessageRequest } from '@a2a-js/sdk';
+export interface DelegationTaskPayload {
+    title: string;
+    description: string;
+    acceptance_criteria?: string;
+    artifacts?: Array<{
+        name?: string;
+        content?: string;
+        mime?: string;
+    }>;
+    role?: string;
+}
+export declare function buildSendMessageRequest(payload: DelegationTaskPayload): SendMessageRequest;
+//# sourceMappingURL=delegation-message.d.ts.map

package/lib/a2a/delegation-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-message.d.ts","sourceRoot":"","sources":["../../src/a2a/delegation-message.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,kBAAkB,EAAQ,MAAM,aAAa,CAAC;AACvE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoBD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,kBAAkB,CA+B1F"}

package/lib/a2a/delegation-message.js

@@ -0,0 +1,53 @@
+/**
+ * Build A2A SendMessageRequest from orchestration task fields.
+ */
+import { randomUUID } from 'node:crypto';
+import { Role } from '@a2a-js/sdk';
+function textPart(text) {
+    return {
+        content: { $case: 'text', value: text },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'text/plain',
+    };
+}
+function dataPart(data) {
+    return {
+        content: { $case: 'data', value: data },
+        metadata: undefined,
+        filename: '',
+        mediaType: 'application/json',
+    };
+}
+export function buildSendMessageRequest(payload) {
+    const parts = [textPart(`# ${payload.title}\n\n${payload.description}`)];
+    if (payload.acceptance_criteria?.trim()) {
+        parts.push(textPart(`## Acceptance Criteria\n${payload.acceptance_criteria}`));
+    }
+    if (payload.artifacts?.length) {
+        parts.push(dataPart({ artifacts: payload.artifacts }));
+    }
+    const metadata = {};
+    if (payload.role?.trim())
+        metadata.skillId = payload.role.trim();
+    return {
+        tenant: '',
+        message: {
+            messageId: randomUUID(),
+            contextId: '',
+            taskId: '',
+            role: Role.ROLE_USER,
+            parts,
+            metadata,
+            extensions: [],
+            referenceTaskIds: [],
+        },
+        configuration: {
+            acceptedOutputModes: ['text/plain'],
+            returnImmediately: true,
+            taskPushNotificationConfig: undefined,
+        },
+        metadata: payload.role ? { skillId: payload.role } : {},
+    };
+}
+//# sourceMappingURL=delegation-message.js.map

package/lib/a2a/delegation-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-message.js","sourceRoot":"","sources":["../../src/a2a/delegation-message.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAsC,IAAI,EAAE,MAAM,aAAa,CAAC;AASvE,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO;QACL,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;QACvC,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,YAAY;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAa;IAC7B,OAAO;QACL,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE;QACvC,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,kBAAkB;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAA8B;IACpE,MAAM,KAAK,GAAW,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,KAAK,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACjF,IAAI,OAAO,CAAC,mBAAmB,EAAE,IAAI,EAAE,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,2BAA2B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,IAAI,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAEjE,OAAO;QACL,MAAM,EAAE,EAAE;QACV,OAAO,EAAE;YACP,SAAS,EAAE,UAAU,EAAE;YACvB,SAAS,EAAE,EAAE;YACb,MAAM,EAAE,EAAE;YACV,IAAI,EAAE,IAAI,CAAC,SAAS;YACpB,KAAK;YACL,QAAQ;YACR,UAAU,EAAE,EAAE;YACd,gBAAgB,EAAE,EAAE;SACrB;QACD,aAAa,EAAE;YACb,mBAAmB,EAAE,CAAC,YAAY,CAAC;YACnC,iBAAiB,EAAE,IAAI;YACvB,0BAA0B,EAAE,SAAS;SACtC;QACD,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;KACxD,CAAC;AACJ,CAAC"}

package/lib/a2a/task-state.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Map A2A TaskState to remote_mesh poll status strings.
+ */
+import { type Task, TaskState } from '@a2a-js/sdk';
+export type RemotePollStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+export declare function mapA2aTaskState(state: TaskState | string | undefined): RemotePollStatus;
+export declare function extractTaskResultText(task: Task): string;
+export declare function isTerminalA2aState(state: TaskState | string | undefined): boolean;
+//# sourceMappingURL=task-state.d.ts.map

package/lib/a2a/task-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-state.d.ts","sourceRoot":"","sources":["../../src/a2a/task-state.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,IAAI,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAC;AACpE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAO5F,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAkBvF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAiBxD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAGjF"}

package/lib/a2a/task-state.js

@@ -0,0 +1,53 @@
+/**
+ * Map A2A TaskState to remote_mesh poll status strings.
+ */
+import { taskStateToJSON } from '@a2a-js/sdk';
+function stateKey(state) {
+    if (state === undefined)
+        return '';
+    return taskStateToJSON(state);
+}
+export function mapA2aTaskState(state) {
+    const key = typeof state === 'string' ? state : stateKey(state);
+    switch (key) {
+        case 'TASK_STATE_COMPLETED':
+            return 'completed';
+        case 'TASK_STATE_FAILED':
+            return 'failed';
+        case 'TASK_STATE_CANCELED':
+            return 'cancelled';
+        case 'TASK_STATE_SUBMITTED':
+            return 'pending';
+        case 'TASK_STATE_WORKING':
+        case 'TASK_STATE_INPUT_REQUIRED':
+        case 'TASK_STATE_AUTH_REQUIRED':
+            return 'running';
+        default:
+            return 'running';
+    }
+}
+export function extractTaskResultText(task) {
+    const statusMsg = task.status?.message;
+    if (statusMsg?.parts?.length) {
+        const text = statusMsg.parts
+            .map((p) => (p.content?.$case === 'text' ? p.content.value : ''))
+            .join('\n')
+            .trim();
+        if (text)
+            return text;
+    }
+    for (const artifact of task.artifacts ?? []) {
+        const text = artifact.parts
+            ?.map((p) => (p.content?.$case === 'text' ? p.content.value : ''))
+            .join('\n')
+            .trim();
+        if (text)
+            return text;
+    }
+    return '';
+}
+export function isTerminalA2aState(state) {
+    const mapped = mapA2aTaskState(state);
+    return mapped === 'completed' || mapped === 'failed' || mapped === 'cancelled';
+}
+//# sourceMappingURL=task-state.js.map

package/lib/a2a/task-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-state.js","sourceRoot":"","sources":["../../src/a2a/task-state.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAwB,eAAe,EAAE,MAAM,aAAa,CAAC;AAGpE,SAAS,QAAQ,CAAC,KAA4B;IAC5C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAqC;IACnE,MAAM,GAAG,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChE,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,sBAAsB;YACzB,OAAO,WAAW,CAAC;QACrB,KAAK,mBAAmB;YACtB,OAAO,QAAQ,CAAC;QAClB,KAAK,qBAAqB;YACxB,OAAO,WAAW,CAAC;QACrB,KAAK,sBAAsB;YACzB,OAAO,SAAS,CAAC;QACnB,KAAK,oBAAoB,CAAC;QAC1B,KAAK,2BAA2B,CAAC;QACjC,KAAK,0BAA0B;YAC7B,OAAO,SAAS,CAAC;QACnB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAU;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;IACvC,IAAI,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK;aACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aAChE,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE,CAAC;QACV,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK;YACzB,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aACjE,IAAI,CAAC,IAAI,CAAC;aACV,IAAI,EAAE,CAAC;QACV,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAqC;IACtE,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACtC,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAC;AACjF,CAAC"}

package/lib/activity-feedback/adapter-integration.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Activity Feedback — endpoint 适配器集成（复用 typing-indicator 底层适配器）
+ */
+import type { Adapter, Endpoint } from '@zhin.js/core';
+import { type TypingIndicator, type TypingIndicatorOptions } from '../typing-indicator/index.js';
+import { PLATFORM_FEATURES, buildTypingSendContent, type PlatformFeatures } from '../typing-indicator/adapter-integration.js';
+import { ActivityFeedbackManager } from './manager.js';
+import type { ActivityFeedbackPhase, ResolvedActivityFeedbackPhaseConfig } from './types.js';
+export { PLATFORM_FEATURES, buildTypingSendContent, type PlatformFeatures };
+type OutboundAdapter = Pick<Adapter, 'sendMessage'>;
+export interface PlatformActivityFeedbackStartOptions {
+    messageId?: string;
+    sessionId: string;
+    userId?: string;
+    groupId?: string;
+    sceneType: 'private' | 'group';
+    phase?: ActivityFeedbackPhase;
+    /** 由 service 插件策略层解析；adapter 不再自行 resolve */
+    phaseConfig: ResolvedActivityFeedbackPhaseConfig;
+}
+/** 平台自管 Activity Feedback IO（如 ICQQ 群临时私聊 parent） */
+export interface PlatformActivityFeedbackManager {
+    start(options: PlatformActivityFeedbackStartOptions): Promise<unknown>;
+    stop(options: {
+        sessionId: string;
+        userId?: string;
+        groupId?: string;
+        phase?: ActivityFeedbackPhase;
+    }): Promise<void>;
+    getActiveIndicator?(phase: ActivityFeedbackPhase, options: TypingIndicatorOptions): TypingIndicator | undefined;
+}
+export type BotActivityFeedbackManager = ActivityFeedbackManager | PlatformActivityFeedbackManager;
+export interface EndpointWithActivityFeedback extends Endpoint {
+    $activityFeedback?: BotActivityFeedbackManager;
+    $addReaction?(messageId: string, emoji: string, hint?: {
+        sceneType?: 'private' | 'group' | 'channel';
+        channelId?: string;
+    }): Promise<string | null>;
+    $removeReaction?(messageId: string, reactionId: string): Promise<void>;
+}
+export declare class AdapterActivityFeedbackManager {
+    private managers;
+    enableForEndpoint(endpoint: EndpointWithActivityFeedback, platform: string, outbound?: OutboundAdapter): ActivityFeedbackManager;
+    getManager(platform: string, endpointId: string): ActivityFeedbackManager | undefined;
+    stopAll(platform: string, endpointId: string): Promise<void>;
+    clearAll(): void;
+}
+export declare function getAdapterActivityFeedbackManager(): AdapterActivityFeedbackManager;
+export declare function initAdapterActivityFeedbackManager(): AdapterActivityFeedbackManager;
+export declare function enableActivityFeedbackForBot(endpoint: EndpointWithActivityFeedback, platform: string, outbound?: OutboundAdapter): ActivityFeedbackManager;
+export declare function isGenericActivityFeedbackManager(manager: BotActivityFeedbackManager): manager is ActivityFeedbackManager;
+//# sourceMappingURL=adapter-integration.d.ts.map

package/lib/activity-feedback/adapter-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-integration.d.ts","sourceRoot":"","sources":["../../src/activity-feedback/adapter-integration.ts"],"names":[],"mappings":"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"}

package/lib/activity-feedback/adapter-integration.js

@@ -0,0 +1,138 @@
+/**
+ * Activity Feedback — endpoint 适配器集成（复用 typing-indicator 底层适配器）
+ */
+import { ReactionTypingIndicatorAdapter, GenericTypingIndicatorAdapter, } from '../typing-indicator/index.js';
+import { PLATFORM_FEATURES, buildTypingSendContent, } from '../typing-indicator/adapter-integration.js';
+import { ActivityFeedbackManager } from './manager.js';
+export { PLATFORM_FEATURES, buildTypingSendContent };
+function resolveSendTarget(options) {
+    if ((options.sceneType === 'group' || options.sceneType === 'channel') && options.groupId) {
+        return { type: 'group', id: options.groupId };
+    }
+    if (options.sceneType === 'private') {
+        if (options.groupId) {
+            return { type: 'private', id: options.groupId };
+        }
+        if (options.userId) {
+            return { type: 'private', id: options.userId };
+        }
+    }
+    const parts = (options.sessionId ?? '').split(':').filter((p) => p.length > 0);
+    if (parts.length >= 3)
+        return { type: 'group', id: parts[1] };
+    if (parts.length >= 2)
+        return { type: 'private', id: parts[parts.length - 1] };
+    return { type: 'private', id: options.sessionId ?? '' };
+}
+function createOutboundSendMessage(endpoint, platform, outbound) {
+    return async (options, content) => {
+        try {
+            const segments = buildTypingSendContent(platform, options, content);
+            if (!segments)
+                return null;
+            const { type, id } = resolveSendTarget(options);
+            const sendOptions = {
+                type,
+                id,
+                context: platform,
+                endpoint: endpoint.$id,
+                content: segments,
+            };
+            if (outbound)
+                return await outbound.sendMessage(sendOptions);
+            console.error(`[${platform}] Activity feedback requires Adapter.sendMessage; endpoint ${endpoint.$id} has no outbound adapter`);
+            return null;
+        }
+        catch (error) {
+            console.error(`[${platform}] Failed to send activity feedback message:`, error);
+            return null;
+        }
+    };
+}
+function registerPlatformAdapters(manager, endpoint, platform, features, outbound) {
+    const sendMessage = createOutboundSendMessage(endpoint, platform, outbound);
+    if (features.supportsReaction && endpoint.$addReaction && endpoint.$removeReaction) {
+        manager.registerAdapter(new ReactionTypingIndicatorAdapter(platform, async (messageId, emoji, options) => {
+            try {
+                return await endpoint.$addReaction(messageId, emoji, {
+                    sceneType: options.sceneType,
+                    channelId: options.groupId,
+                });
+            }
+            catch (error) {
+                console.error(`[${platform}] Failed to add reaction:`, error);
+                return null;
+            }
+        }, async (messageId, reactionId) => {
+            try {
+                await endpoint.$removeReaction(messageId, reactionId);
+            }
+            catch (error) {
+                console.error(`[${platform}] Failed to remove reaction:`, error);
+            }
+        }, sendMessage, async (messageId) => { await endpoint.$recallMessage(messageId); }, async (messageId, content) => {
+            const editBot = endpoint;
+            if (typeof editBot.$editMessage === 'function')
+                await editBot.$editMessage(messageId, content);
+            else if (typeof editBot.$updateMessage === 'function')
+                await editBot.$updateMessage(messageId, content);
+        }));
+        return;
+    }
+    manager.registerAdapter(new GenericTypingIndicatorAdapter(platform, sendMessage, async (messageId) => { await endpoint.$recallMessage(messageId); }, async (messageId, content) => {
+        const editBot = endpoint;
+        if (typeof editBot.$editMessage === 'function')
+            await editBot.$editMessage(messageId, content);
+        else if (typeof editBot.$updateMessage === 'function')
+            await editBot.$updateMessage(messageId, content);
+    }));
+}
+export class AdapterActivityFeedbackManager {
+    managers = new Map();
+    enableForEndpoint(endpoint, platform, outbound) {
+        const botKey = `${platform}:${endpoint.$id}`;
+        if (this.managers.has(botKey)) {
+            return this.managers.get(botKey);
+        }
+        const features = PLATFORM_FEATURES[platform] ?? {
+            platform,
+            supportsReaction: false,
+            supportsEdit: false,
+            supportsDelete: true,
+            supportsTyping: false,
+            defaultType: 'message',
+        };
+        const manager = new ActivityFeedbackManager();
+        registerPlatformAdapters(manager, endpoint, platform, features, outbound);
+        this.managers.set(botKey, manager);
+        endpoint.$activityFeedback = manager;
+        return manager;
+    }
+    getManager(platform, endpointId) {
+        return this.managers.get(`${platform}:${endpointId}`);
+    }
+    async stopAll(platform, endpointId) {
+        await this.managers.get(`${platform}:${endpointId}`)?.stopAll();
+    }
+    clearAll() {
+        this.managers.clear();
+    }
+}
+let globalAdapterManager = null;
+export function getAdapterActivityFeedbackManager() {
+    if (!globalAdapterManager) {
+        globalAdapterManager = new AdapterActivityFeedbackManager();
+    }
+    return globalAdapterManager;
+}
+export function initAdapterActivityFeedbackManager() {
+    globalAdapterManager = new AdapterActivityFeedbackManager();
+    return globalAdapterManager;
+}
+export function enableActivityFeedbackForBot(endpoint, platform, outbound) {
+    return getAdapterActivityFeedbackManager().enableForEndpoint(endpoint, platform, outbound);
+}
+export function isGenericActivityFeedbackManager(manager) {
+    return manager instanceof ActivityFeedbackManager;
+}
+//# sourceMappingURL=adapter-integration.js.map