Finch Cross-session Messaging

一个 Finch mini tool，通过在目标 Space 中创建并复用受管 Agent Session，实现跨工作空间任务委派。

工作方式

普通 Session
  → cross_session_message
  → 目标 Space 中由本 mini tool 管理的 Agent Session
  → 执行任务并返回结果

每个“来源 Space + 目标 Space”组合对应一个持久化 Agent 路由。Agent Session：

• 位于目标 Space，使用其目录、项目规则、上下文和工具
• Session 标题显示来源 Space 名称，例如 Cross-session Agent · from finch-cloud
• 委派消息同时显示来源和目标名称，ID 仅作为辅助标识
• 由本 mini tool 创建和管理
• 在后续任务中复用，保留该 Agent 的会话上下文
• 使用 acceptCalls permission mode 执行常规工具调用
• 遇到需要人工处理的权限、问题或表单时，在目标 Space Session 中展示等待卡片

A → B       使用 Session 1
C → B       使用 Session 2
A → B 再次  继续复用 Session 1

能力边界

这是“每个来源→目标组合一个受管 Agent”，不是任意 Session 互通：

• 可以创建、读取和发送消息到本 mini tool 拥有的 Session
• 可以让同一 mini tool 的受管 Agent 继续委派任务
• 不能读取或写入已有普通 Session
• 不能枚举其他 mini tool 拥有的 Session
• 不能向指定普通 Session 主动注入消息

Agent Tool

工具名：cross_session_message

dispatch

创建或复用目标 Space Agent，发送任务并等待结果。

必填参数：

• target_space_id：准确的 Finch Space ID，不应猜测
• task：完整任务、约束、相关上下文和预期输出

可选参数：

• source_space_name：当前来源 Space 名称；Agent 从调用上下文获知后应自动传入
• target_space_name：目标 Space 名称；Agent 解析目标时应自动传入
• request_id：调用方提供的稳定幂等键，重试同一任务时复用
• wait_seconds：同步等待 1–100 秒，默认 90 秒

发送后的消息头示例：

From: finch-cloud (Space aedcde81)
To: token-relay (Space 1057a416)

任务未在等待窗口内结束时，工具返回 session_id 和 turn_id，不会取消目标任务。

result

使用 session_id 和 turn_id 查询超时任务的最终结果、失败状态或等待卡片。

list

列出 mini tool 持久化的来源 Space→目标 Space→Agent Session 路由。

reset

忘记“当前来源 Space→指定目标 Space”的路由，使下一次 dispatch 创建新 Agent Session。旧 Session 不会被删除。

开发

要求 Node.js 20+。

npm install
npm run build
npm test
npx @finchtoys/minitools doctor .

完整检查：

npm run check

安装

从 npm 安装：

npx @finchtoys/minitools add @joehe71/cross-session

本地开发安装：

npx @finchtoys/minitools add .

安装后在 Finch Toolcase 中启用 Cross-session Messaging，并授权 owner-scoped Sessions 权限。

数据与权限

• 仅申请 permissions.sessions
• 不申请文件系统、Shell、网络、Secrets 权限
• Space ID、Agent Session ID 和路由时间保存在 mini tool 私有明文 KV 中
• 不持久化任务正文、Agent 输出或凭据

License

MIT